.I key
is provided, all entries will be displayed (unless the database does not
support enumeration).
-.PP
+.P
The
.I database
may be any of those supported by the GNU C Library, listed below:
If no output file is given,
.B iconv
writes to standard output.
-.PP
+.P
If no
.I from-encoding
is given, the default is derived
.TP
.I /usr/lib/gconv/gconv\-modules.cache
Usual system gconv module configuration cache.
-.PP
+.P
Depending on the architecture,
the above files may instead be located at directories with the path prefix
.IR /usr/lib64 .
POSIX.1-2001.
.SH EXAMPLES
Convert text from the ISO 8859-15 character encoding to UTF-8:
-.PP
+.P
.in +4n
.EX
$ \fBiconv \-f ISO\-8859\-15 \-t UTF\-8 < input.txt > output.txt\fP
.EE
.in
-.PP
+.P
The next example converts from UTF-8 to ASCII, transliterating when
possible:
-.PP
+.P
.in +4n
.EX
$ \fBecho abc ß α € àḃç | iconv \-f UTF\-8 \-t ASCII//TRANSLIT\fP
Linux is a flavor of UNIX, and as a first approximation
all user commands under UNIX work precisely the same under
Linux (and FreeBSD and lots of other UNIX-like systems).
-.PP
+.P
Under Linux, there are GUIs (graphical user interfaces), where you
can point and click and drag, and hopefully get work done without
first reading lots of documentation.
.BR dash (1),
.BR ksh (1),
.BR zsh (1).
-.PP
+.P
A session might go like:
-.PP
+.P
.in +4n
.EX
.RB "knuth login: " aeb
$
.EE
.in
-.PP
+.P
Here typing Control-D ended the session.
-.PP
+.P
The
.B $
here was the command prompt\[em]it is the shell's way of indicating
machine name, current directory, time, and so on.
An assignment PS1="What next, master? "
would change the prompt as indicated.
-.PP
+.P
We see that there are commands
.I date
(that gives date and time), and
.I cal
(that gives a calendar).
-.PP
+.P
The command
.I ls
lists the contents of the current directory\[em]it tells you what
.I chown
and
.IR chmod .
-.PP
+.P
The command
.I cat
will show the contents of a file.
.BR stdout (3)),
here
the terminal screen.)
-.PP
+.P
The command
.I cp
(from "copy") will copy a file.
-.PP
+.P
The command
.I mv
(from "move"), on the other hand, only renames it.
-.PP
+.P
The command
.I diff
lists the differences between two files.
Here there was no output because there were no differences.
-.PP
+.P
The command
.I rm
(from "remove") deletes the file, and be careful! it is gone.
No wastepaper basket or anything.
Deleted means lost.
-.PP
+.P
The command
.I grep
(from "g/re/p") finds occurrences of a string in one or more files.
.I tel
when the current directory is
.IR /home/aeb .
-.PP
+.P
The command
.I pwd
prints the current directory.
-.PP
+.P
The command
.I cd
changes the current directory.
-.PP
+.P
Try alternatively
.I cd
and
The command
.I mkdir
makes a new directory.
-.PP
+.P
The command
.I rmdir
removes a directory if it is empty, and complains otherwise.
-.PP
+.P
The command
.I find
(with a rather baroque syntax) will find files with given name
usually
.IR less .
Hit the space bar to get the next page, hit q to quit.
-.PP
+.P
In documentation it is customary to refer to man pages
by giving the name and section number, as in
.BR man (1).
detail.
For newcomers an introductory text with more examples
and explanations is useful.
-.PP
+.P
A lot of GNU/FSF software is provided with info files.
Type "info info"
for an introduction on the use of the program
.IR info .
-.PP
+.P
Special topics are often treated in HOWTOs.
Look in
.I /usr/share/doc/howto/en
shared object specified on the command line.
An example of its use and output
is the following:
-.PP
+.P
.in +4n
.EX
$ \fBldd /bin/ls\fP
libpthread.so.0 => /lib64/libpthread.so.0 (0x00007f87e45fa000)
.EE
.in
-.PP
+.P
In the usual case,
.B ldd
invokes the standard dynamic linker (see
.B ldd
implementation did this for example,
although most distributions provided a modified version that did not.)
-.PP
+.P
Thus, you should
.I never
employ
on an untrusted executable,
since this may result in the execution of arbitrary code.
A safer alternative when dealing with untrusted executables is:
-.PP
+.P
.in +4n
.EX
$ \fBobjdump \-p /path/to/program | grep NEEDED\fP
.EE
.in
-.PP
+.P
Note, however, that this alternative shows only the direct dependencies
of the executable, while
.B ldd
.\" .B \-V
.\" and only has the equivalent
.\" .BR \-\-version .
-.\" .LP
+.\" .P
.\" The libc5 version of this program will use the name of a library given
.\" on the command line as-is when it contains a \[aq]/\[aq]; otherwise it
.\" searches for the library in the standard locations.
.SH BUGS
.B ldd
does not work on a.out shared libraries.
-.PP
+.P
.B ldd
does not work with some extremely old a.out programs which were
built before
.B locale
command displays information about the current locale, or all locales,
on standard output.
-.PP
+.P
When invoked without arguments,
.B locale
displays the current locale settings for each locale category (see
.BR locale (7)).
Values for variables set in the environment are printed without double
quotes, implied values are printed with double quotes.
-.PP
+.P
If either the
.B \-a
or the
Display the available charmaps (character set description files).
To display the current character set for the locale, use
\fBlocale \-c charmap\fR.
-.PP
+.P
The
.B locale
command can also be provided with one or more arguments,
.IP \[bu]
For a locale category,
the values of all keywords in that category are displayed.
-.PP
+.P
When arguments are supplied, the following options are meaningful:
.TP
.B \-\-category\-name
.IR keyword =\[dq] value \[dq]
.EE
.in
-.PP
+.P
The
.B locale
command also knows about the following options:
LC_MEASUREMENT="en_US.UTF\-8"
LC_IDENTIFICATION="en_US.UTF\-8"
LC_ALL=
-.PP
+.P
$ \fBlocale date_fmt\fP
%a %b %e %H:%M:%S %Z %Y
-.PP
+.P
$ \fBlocale \-k date_fmt\fP
date_fmt="%a %b %e %H:%M:%S %Z %Y"
-.PP
+.P
$ \fBlocale \-ck date_fmt\fP
LC_TIME
date_fmt="%a %b %e %H:%M:%S %Z %Y"
-.PP
+.P
$ \fBlocale LC_TELEPHONE\fP
+%c (%a) %l
(%a) %l
11
1
UTF\-8
-.PP
+.P
$ \fBlocale \-k LC_TELEPHONE\fP
tel_int_fmt="+%c (%a) %l"
tel_dom_fmt="(%a) %l"
int_prefix="1"
telephone\-codeset="UTF\-8"
.EE
-.PP
+.P
The following example compiles a custom locale from the
.I ./wrk
directory with the
.B LANG
in the shell profile file so that the custom locale will be used in the
subsequent user sessions:
-.PP
+.P
.EX
$ \fBmkdir \-p $HOME/.locale\fP
$ \fBI18NPATH=./wrk/ localedef \-f UTF\-8 \-i fi_SE $HOME/.locale/fi_SE.UTF\-8\fP
etc.),
and places the output in
.IR outputpath .
-.PP
+.P
The
.I outputpath
argument is interpreted as follows:
it is used by all localized programs when the environment variable
.B LOCPATH
is not set.
-.PP
+.P
In any case,
.B localedef
aborts if the directory in which it tries to write locale files has
not already been created.
-.PP
+.P
If no
.I charmapfile
is given,
Compile the locale files for Finnish in the UTF\-8 character set
and add it to the default locale archive with the name
.BR fi_FI.UTF\-8 :
-.PP
+.P
.in +4n
.EX
localedef \-f UTF\-8 \-i fi_FI fi_FI.UTF\-8
.EE
.in
-.PP
+.P
The next example does the same thing,
but generates files into the
.I fi_FI.UTF\-8
.B LOCPATH
is set to the current directory (note that the last argument must
contain a slash):
-.PP
+.P
.in +4n
.EX
localedef \-f UTF\-8 \-i fi_FI ./fi_FI.UTF\-8
and
.BR munmap (2)
can also be intercepted.
-.PP
+.P
.B memusage
can output the collected data in textual form, or it can use
.BR memusagestat (1)
the difference from the base stack pointer computed.
The maximum of these differences is then the stack peak.
.RE
-.PP
+.P
Immediately following this summary line, a table shows the number calls,
total memory allocated or deallocated,
and number of failed calls for each intercepted function.
.BR realloc (3),
the additional field "free" shows reallocations that
caused a block to be freed (i.e., the reallocated size was 0).
-.PP
+.P
The "realloc/total memory" of the table output by
.B memusage
does not reflect cases where
After compiling the program and running the following commands,
a graph of the memory usage of the program can be found in the file
.IR memusage.png :
-.PP
+.P
.in +4n
.EX
$ \fBmemusage \-\-data=memusage.dat ./a.out\fP
.IR \-\-data )
option of
.BR memusage (1).
-.PP
+.P
The red line in the graph shows the heap usage (allocated memory)
and the green line shows the stack usage.
The x-scale is either the number of memory-handling function calls or
(assuming that
.I binary
was compiled with debugging information).
-.PP
+.P
For more information about the
.BR mtrace (3)
function and
glibc 2.15.
.SH NOTES
The command
-.PP
+.P
.in +4n
.EX
lsof \-p PID
.EE
.in
-.PP
+.P
also shows output that includes the dynamic shared objects
that are linked into a process.
-.PP
+.P
The
.BR gdb (1)
.I "info shared"
using a command such as the following
(to monitor the process with the specified
.IR pid ):
-.PP
+.P
.in +4n
.EX
$ \fBgdb \-ex "set confirm off" \-ex "set height 0" \-ex "info shared" \e\fP
.TQ
.B \-q
Generate a call graph.
-.PP
+.P
If none of the above options is specified,
then the default behavior is to display a flat profile and a call graph.
-.PP
+.P
The following additional command-line options are available:
.TP
.B \-\-help
The example consists of a main program that calls two functions
in a shared object.
First, the code of the main program:
-.PP
+.P
.in +4n
.EX
$ \fBcat prog.c\fP
}
.EE
.in
-.PP
+.P
The functions
.IR x1 ()
and
.IR x2 ()
are defined in the following source file that is used to
construct the shared object:
-.PP
+.P
.in +4n
.EX
$ \fBcat libdemo.c\fP
}
.EE
.in
-.PP
+.P
Now we construct the shared object with the real name
.IR libdemo.so.1.0.1 ,
and the soname
.IR libdemo.so.1 :
-.PP
+.P
.in +4n
.EX
$ \fBcc \-g \-fPIC \-shared \-Wl,\-soname,libdemo.so.1 \e\fP
\fB\-o libdemo.so.1.0.1 libdemo.c\fP
.EE
.in
-.PP
+.P
Then we construct symbolic links for the library soname and
the library linker name:
-.PP
+.P
.in +4n
.EX
$ \fBln \-sf libdemo.so.1.0.1 libdemo.so.1\fP
$ \fBln \-sf libdemo.so.1 libdemo.so\fP
.EE
.in
-.PP
+.P
Next, we compile the main program, linking it against the shared object,
and then list the dynamic dependencies of the program:
-.PP
+.P
.in +4n
.EX
$ \fBcc \-g \-o prog prog.c \-L. \-ldemo\fP
/lib64/ld\-linux\-x86\-64.so.2 (0x00007fd4dc51f000)
.EE
.in
-.PP
+.P
In order to get profiling information for the shared object,
we define the environment variable
.B LD_PROFILE
with the soname of the library:
-.PP
+.P
.in +4n
.EX
$ \fBexport LD_PROFILE=libdemo.so.1\fP
.EE
.in
-.PP
+.P
We then define the environment variable
.B LD_PROFILE_OUTPUT
with the pathname of the directory where profile output should be written,
and create that directory if it does not exist already:
-.PP
+.P
.in +4n
.EX
$ \fBexport LD_PROFILE_OUTPUT=$(pwd)/prof_data\fP
$ \fBmkdir \-p $LD_PROFILE_OUTPUT\fP
.EE
.in
-.PP
+.P
.B LD_PROFILE
causes profiling output to be
.I appended
to the output file if it already exists,
so we ensure that there is no preexisting profiling data:
-.PP
+.P
.in +4n
.EX
$ \fBrm \-f $LD_PROFILE_OUTPUT/$LD_PROFILE.profile\fP
.EE
.in
-.PP
+.P
We then run the program to produce the profiling output,
which is written to a file in the directory specified in
.BR LD_PROFILE_OUTPUT :
-.PP
+.P
.in +4n
.EX
$ \fBLD_LIBRARY_PATH=. ./prog\fP
libdemo.so.1.profile
.EE
.in
-.PP
+.P
We then use the
.B sprof \-p
option to generate a flat profile with counts and ticks:
-.PP
+.P
.in +4n
.EX
$ \fBsprof \-p libdemo.so.1 $LD_PROFILE_OUTPUT/libdemo.so.1.profile\fP
0.00 0.10 0.00 1 0.00 x2
.EE
.in
-.PP
+.P
The
.B sprof \-q
option generates a call graph:
-.PP
+.P
.in +4n
.EX
$ \fBsprof \-q libdemo.so.1 $LD_PROFILE_OUTPUT/libdemo.so.1.profile\fP
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
.EE
.in
-.PP
+.P
Above and below, the "<UNKNOWN>" strings represent identifiers that
are outside of the profiled object (in this example, these are instances of
.IR main() ).
-.PP
+.P
The
.B sprof \-c
option generates a list of call pairs and the number of their occurrences:
-.PP
+.P
.in +4n
.EX
$ \fBsprof \-c libdemo.so.1 $LD_PROFILE_OUTPUT/libdemo.so.1.profile\fP
.I "struct tms"
as returned by
.BR times (2)).
-.PP
+.P
Note: some shells (e.g.,
.BR bash (1))
have a built-in
option or the
.B TIME
environment variable.
-.PP
+.P
The default format string is:
-.PP
+.P
.in +4n
.EX
%Uuser %Ssystem %Eelapsed %PCPU (%Xtext+%Ddata %Mmax)k
%Iinputs+%Ooutputs (%Fmajor+%Rminor)pagefaults %Wswaps
.EE
.in
-.PP
+.P
When the
.I \-p
option is given, the (portable) output format is used:
-.PP
+.P
.in +4n
.EX
real %e
All of those used by
.BR tcsh (1)
are supported.
-.PP
+.P
.B "Time"
.TP
.B %E
.TP
.B %P
Percentage of the CPU that this job got, computed as (%U + %S) / %E.
-.PP
+.P
.B "Memory"
.TP
.B %M
.B %w
Number of waits: times that the program was context-switched voluntarily,
for instance while waiting for an I/O operation to complete.
-.PP
+.P
.B "I/O"
.TP
.B %I
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.
-.PP
+.P
GNU time version 1.7 is not yet localized.
Thus, it does not implement the POSIX requirements.
-.PP
+.P
The environment variable
.B TIME
was badly chosen.
the utility to be used.
Uses like MORE or TIME for options to programs
(instead of program pathnames) tend to lead to difficulties.
-.PP
+.P
It seems unfortunate that
.I \-o
overwrites instead of appends.
(That is, the
.I \-a
option should be the default.)
-.PP
+.P
Mail suggestions and bug reports for GNU
.B time
to
Please include the version of
.BR time ,
which you can get by running
-.PP
+.P
.in +4n
.EX
time \-\-version
.EE
.in
-.PP
+.P
and the operating system
and C compiler you used.
.\" .SH AUTHORS
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.BI "[[noreturn]] void _exit(int " status );
-.PP
+.P
.B #include <stdlib.h>
-.PP
+.P
.BI "[[noreturn]] void _Exit(int " status );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR _Exit ():
.nf
_ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
The process's parent is sent a
.B SIGCHLD
signal.
-.PP
+.P
The value
.I "status & 0xFF"
is returned to the parent process as the process's exit status, and
can be collected by the parent using one of the
.BR wait (2)
family of calls.
-.PP
+.P
The function
.BR _Exit ()
is equivalent to
C11, POSIX.1-2008.
.SH HISTORY
POSIX.1-2001, SVr4, 4.3BSD.
-.PP
+.P
.BR _Exit ()
was introduced by C99.
.SH NOTES
For a discussion on the effects of an exit, the transmission of
exit status, zombie processes, signals sent, and so on, see
.BR exit (3).
-.PP
+.P
The function
.BR _exit ()
is like
and these are the semantics specified by POSIX.1 and implemented
by the C library wrapper function.
On modern systems, this means termination of all threads in the process.
-.PP
+.P
By contrast with the C library wrapper function, the raw Linux
.BR _exit ()
system call terminates only the calling thread, and actions such as
to the parent process are performed only if this is
the last thread in the thread group.
.\" _exit() is used by pthread_exit() to terminate the calling thread
-.PP
+.P
Up to glibc 2.3, the
.BR _exit ()
wrapper function invoked the kernel system call of the same name.
.SH SYNOPSIS
.nf
.B #include <linux/unistd.h>
-.PP
+.P
A _syscall macro
-.PP
+.P
desired system call
.fi
.SH DESCRIPTION
and the function return type.
There are seven macros that make the actual call into the system easier.
They have the form:
-.PP
+.P
.in +4n
.EX
.RI _syscall X ( type , name , type1 , arg1 , type2 , arg2 ,...)
.EE
.in
-.PP
+.P
where
.IP
.I X
.IP
.I argN
is the name of the Nth argument
-.PP
+.P
These macros create a function called
.I name
with the arguments you
produce a prototype.
You may have to
create one, especially for C++ users.
-.PP
+.P
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.
is negative.
For the error codes, see
.BR errno (3).
-.PP
+.P
When defining a system call, the argument types
.I must
be
.SH SYNOPSIS
.nf
.B #include <sys/socket.h>
-.PP
+.P
.BI "int accept(int " sockfd ", struct sockaddr *_Nullable restrict " addr ,
.BI " socklen_t *_Nullable restrict " addrlen );
-.PP
+.P
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <sys/socket.h>
-.PP
+.P
.BI "int accept4(int " sockfd ", struct sockaddr *_Nullable restrict " addr ,
.BI " socklen_t *_Nullable restrict " addrlen ", int " flags );
.fi
The original socket
.I sockfd
is unaffected by this call.
-.PP
+.P
The argument
.I sockfd
is a socket that has been created with
.BR bind (2),
and is listening for connections after a
.BR listen (2).
-.PP
+.P
The argument
.I addr
is a pointer to a
is NULL, nothing is filled in; in this case,
.I addrlen
is not used, and should also be NULL.
-.PP
+.P
The
.I addrlen
argument is a value-result argument:
size (in bytes) of the structure pointed to by
.IR addr ;
on return it will contain the actual size of the peer address.
-.PP
+.P
The returned address is truncated if the buffer provided is too small;
in this case,
.I addrlen
will return a value greater than was supplied to the call.
-.PP
+.P
If no pending
connections are present on the queue, and the socket is not marked as
nonblocking,
.B EAGAIN
or
.BR EWOULDBLOCK .
-.PP
+.P
In order to be notified of incoming connections on a socket, you can use
.BR select (2),
.BR poll (2),
when activity occurs on a socket; see
.BR socket (7)
for details.
-.PP
+.P
If
.I flags
is 0, then
.TP
.B EPROTO
Protocol error.
-.PP
+.P
In addition, network errors for the new socket and as defined
for the protocol may be returned.
Various Linux kernels can
.B O_NONBLOCK
flag set (see
.BR socket (7)).
-.PP
+.P
For certain protocols which require an explicit confirmation,
such as DECnet,
.BR accept ()
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.BI "int access(const char *" pathname ", int " mode );
-.PP
+.P
.BR "#include <fcntl.h>" " /* Definition of " AT_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "int faccessat(int " dirfd ", const char *" pathname ", int " \
mode ", int " flags );
/* But see C library/kernel differences, below */
-.PP
+.P
.BR "#include <fcntl.h>" " /* Definition of " AT_* " constants */"
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.B int syscall(SYS_faccessat2,
.BI " int " dirfd ", const char *" pathname ", int " mode \
", int " flags );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR faccessat ():
.nf
Since glibc 2.10:
If
.I pathname
is a symbolic link, it is dereferenced.
-.PP
+.P
The
.I mode
specifies the accessibility check(s) to be performed,
.BR R_OK ", " W_OK ", and " X_OK
test whether the file exists and grants read, write, and
execute permissions, respectively.
-.PP
+.P
The check is done using the calling process's
.I real
UID and GID, rather than the effective IDs as is done when
permitted capabilities rather than the set of effective
capabilities; and for non-root users, the check uses an empty set
of capabilities.
-.PP
+.P
This allows set-user-ID programs and capability-endowed programs
to easily determine the invoking user's authority.
In other words,
which gives set-user-ID programs the possibility to
prevent malicious users from causing them to read files
which users shouldn't be able to read.
-.PP
+.P
If the calling process is privileged (i.e., its real UID is zero),
then an
.B X_OK
operates in exactly the same way as
.BR access (),
except for the differences described here.
-.PP
+.P
If the pathname given in
.I pathname
is relative, then it is interpreted relative to the directory
the calling process, as is done by
.BR access ()
for a relative pathname).
-.PP
+.P
If
.I pathname
is relative and
is interpreted relative to the current working
directory of the calling process (like
.BR access ()).
-.PP
+.P
If
.I pathname
is absolute, then
.I dirfd
is ignored.
-.PP
+.P
.I flags
is constructed by ORing together zero or more of the following values:
.TP
.I pathname
is a symbolic link, do not dereference it:
instead return information about the link itself.
-.PP
+.P
See
.BR openat (2)
for an explanation of the need for
a safer alternative would be to temporarily switch the process's
effective user ID to the real ID and then call
.BR open (2).)
-.PP
+.P
.BR access ()
always dereferences symbolic links.
If you need to check the permissions on a symbolic link, use
.BR faccessat ()
with the flag
.BR AT_SYMLINK_NOFOLLOW .
-.PP
+.P
These calls return an error if any of the access types in
.I mode
is denied, even if some of the other access types in
.I mode
are permitted.
-.PP
+.P
A file is accessible only if the permissions on each of the
directories in the path prefix of
.I pathname
If any directory is inaccessible, then the
.BR access ()
call fails, regardless of the permissions on the file itself.
-.PP
+.P
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,
Similarly, a DOS file may be reported as executable, but the
.BR execve (2)
call will still fail.
-.PP
+.P
These calls
may not work correctly on NFSv2 filesystems with UID mapping enabled,
because UID mapping is done on the server and hidden from the client,
by making use of the
.BR faccessat2 ()
system call where it is provided by the underlying kernel.
-.PP
+.P
In Linux 2.4 (and earlier) there is some strangeness in the handling of
.B X_OK
tests for superuser.
.\" This behavior appears to have been an implementation accident.
Early Linux 2.6 (up to and including Linux 2.6.3)
also behaved in the same way as Linux 2.4.
-.PP
+.P
Before Linux 2.6.20,
these calls ignored the effect of the
.B MS_NOEXEC
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.BI "int acct(const char *_Nullable " filename );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR acct ():
.nf
Since glibc 2.21:
.SH NOTES
No accounting is produced for programs running when a system crash occurs.
In particular, nonterminating processes are never accounted for.
-.PP
+.P
The structure of the records written to the accounting file is described in
.BR acct (5).
.SH SEE ALSO
.SH SYNOPSIS
.nf
.B #include <keyutils.h>
-.PP
+.P
.BI "key_serial_t add_key(const char *" type ", const char *" description ,
.BI " const void " payload [. plen "], size_t " plen ,
.BI " key_serial_t " keyring ");"
.fi
-.PP
+.P
.IR Note :
There is no glibc wrapper for this system call; see NOTES.
.SH DESCRIPTION
attaches it to the nominated
.IR keyring ,
and returns the key's serial number.
-.PP
+.P
The key may be rejected if the provided data is in the wrong format or
it is invalid in some other way.
-.PP
+.P
If the destination
.I keyring
already contains a key that matches the specified
.\" is consequently unlinked, then keys that it was anchoring
.\" will have their reference count decreased by one (and may
.\" consequently be garbage collected). Is this all correct?
-.PP
+.P
The destination
.I keyring
serial number may be that of a valid keyring for which the caller has
but it does not permit the key to read.
This is suitable for storing payloads
that you do not want to be readable from user space.
-.PP
+.P
This key type vets the
.I description
to ensure that it is qualified by a "service" prefix,
If the key payload is large enough,
then it may be stored encrypted in tmpfs
(which can be swapped out) rather than kernel memory.
-.PP
+.P
For further details on these key types, see
.BR keyrings (7).
.SH RETURN VALUE
specified in its command-line arguments,
and links that key into the session keyring.
The following shell session demonstrates the use of the program:
-.PP
+.P
.in +4n
.EX
$ \fB./a.out user mykey "Some payload"\fP
.BR thread\-keyring (7),
.BR user\-keyring (7),
.BR user\-session\-keyring (7)
-.PP
+.P
The kernel source files
.I Documentation/security/keys/core.rst
and
.SH SYNOPSIS
.nf
.B #include <sys/timex.h>
-.PP
+.P
.BI "int adjtimex(struct timex *" "buf" );
-.PP
+.P
.BI "int clock_adjtime(clockid_t " clk_id, " struct timex *" "buf" );
-.PP
+.P
.BI "int ntp_adjtime(struct timex *" buf );
.fi
.SH DESCRIPTION
structure, updates kernel parameters from (selected) field values,
and returns the same structure updated with the current kernel values.
This structure is declared as follows:
-.PP
+.P
.in +4n
.EX
struct timex {
};
.EE
.in
-.PP
+.P
The
.I modes
field determines which parameters, if any, to set.
.B ADJ_TICK
Set tick value from
.IR buf.tick .
-.PP
+.P
Alternatively,
.I modes
can be specified as either of the following (multibit mask) values,
but did not work correctly
.\" commit 916c7a855174e3b53d182b97a26b2e27a29726a1
until Linux 2.6.28.
-.PP
+.P
Ordinary users are restricted to a value of either 0 or
.B ADJ_OFFSET_SS_READ
for
.IR modes .
Only the superuser may set any parameters.
-.PP
+.P
The
.I buf.status
field is a bit mask that is used to set and/or retrieve status
.\" commit eea83d896e318bda54be2d2770d2c5d6668d11db
.\" Author: Roman Zippel <zippel@linux-m68k.org>
Clock source (0 = A, 1 = B); currently unused.
-.PP
+.P
Attempts to set read-only
.I status
bits are silently ignored.
is a synonym for
.BR TIME_ERROR ,
provided for backward compatibility.
-.PP
+.P
Note that starting with Linux 3.4,
.\" commit 6b43ae8a619d17c4935c3320d2ef9e92bdeed05d changed to asynchronous
.\" operation, so we can no longer rely on the return code.
the call operates asynchronously and the return value usually will
not reflect a state change caused by the call itself.
-.PP
+.P
On failure, these calls return \-1 and set
.I errno
to indicate the error.
.TQ
.BR clock_adjtime ()
Linux.
-.PP
+.P
The preferred API for the NTP daemon is
.BR ntp_adjtime ().
.SH NOTES
This is the case for both input values (in the case of
.IR freq )
and output values.
-.PP
+.P
The leap-second processing triggered by
.B STA_INS
and
.BR time (7),
.BR adjtimex (8),
.BR hwclock (8)
-.PP
+.P
.ad l
.UR http://www.slac.stanford.edu/comp/unix/\:package/\:rtems/\:src/\:ssrlApps/\:ntpNanoclock/\:api.htm
NTP "Kernel Application Program Interface"
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.BI "unsigned int alarm(unsigned int " seconds );
.fi
.SH DESCRIPTION
signal to be delivered to the calling process in
.I seconds
seconds.
-.PP
+.P
If
.I seconds
is zero, any pending alarm is canceled.
-.PP
+.P
In any event any previously set
.BR alarm ()
is canceled.
.BR setitimer (2)
share the same timer; calls to one will interfere with use of the
other.
-.PP
+.P
Alarms created by
.BR alarm ()
are preserved across
.BR execve (2)
and are not inherited by children created via
.BR fork (2).
-.PP
+.P
.BR sleep (3)
may be implemented using
.BR SIGALRM ;
and
.BR sleep (3)
is a bad idea.
-.PP
+.P
Scheduling delays can, as ever, cause the execution of the process to
be delayed by an arbitrary amount of time.
.SH SEE ALSO
.BI "int syscall(SYS_free_hugepages, void *" addr );
.\" asmlinkage int sys_free_hugepages(unsigned long addr);
.fi
-.PP
+.P
.IR Note :
glibc provides no wrappers for these system calls,
necessitating the use of
In Linux 2.4.20, the syscall numbers exist,
but the calls fail with the error
.BR ENOSYS .
-.PP
+.P
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
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.
-.PP
+.P
The
.I key
argument is an identifier.
When positive the pages are shared with other applications using the same
.IR key ,
and inherited by child processes.
-.PP
+.P
The
.I addr
argument of
.BR alloc_hugepages ()
is a hint, that the kernel may or may not follow.
Addresses must be properly aligned.
-.PP
+.P
The
.I len
argument is the length of the required segment.
It must be a multiple of the huge page size.
-.PP
+.P
The
.I prot
argument specifies the memory protection of the segment.
.BR PROT_READ ,
.BR PROT_WRITE ,
.BR PROT_EXEC .
-.PP
+.P
The
.I flag
argument is ignored, unless
using
.BR mmap (2)
to map files in this virtual filesystem.
-.PP
+.P
The maximal number of huge pages can be specified using the
.B hugepages=
boot parameter.
-.\".PP
+.\".P
.\" requires CONFIG_HUGETLB_PAGE (under "Processor type and features")
.\" and CONFIG_HUGETLBFS (under "Filesystems").
.\" mount \-t hugetlbfs hugetlbfs /huge
.BR "#include <asm/prctl.h>" " /* Definition of " ARCH_* " constants */"
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "int syscall(SYS_arch_prctl, int " code ", unsigned long " addr );
.BI "int syscall(SYS_arch_prctl, int " code ", unsigned long *" addr );
.fi
-.PP
+.P
.IR Note :
glibc provides no wrapper for
.BR arch_prctl (),
for the "set" operations, or as an
.IR "unsigned long\ *" ,
for the "get" operations.
-.PP
+.P
Subfunctions for both x86 and x86-64 are:
.TP
.BR ARCH_SET_CPUID " (since Linux 4.12)"
.SH NOTES
.BR arch_prctl ()
is supported only on Linux/x86-64 for 64-bit programs currently.
-.PP
+.P
The 64-bit base changes when a new 32-bit segment selector is loaded.
-.PP
+.P
.B ARCH_SET_GS
is disabled in some kernels.
-.PP
+.P
Context switches for 64-bit segment bases are rather expensive.
As an optimization, if a 32-bit TLS base address is used,
.BR arch_prctl ()
with the
.B MAP_32BIT
flag.
-.PP
+.P
Because of the aforementioned optimization, using
.BR arch_prctl ()
and
.BR set_thread_area (2)
in the same thread is dangerous, as they may overwrite each other's
TLS entries.
-.PP
+.P
.I FS
may be already used by the threading library.
Programs that use
.BR modify_ldt (2),
.BR prctl (2),
.BR set_thread_area (2)
-.PP
+.P
AMD X86-64 Programmer's manual
.SH SYNOPSIS
.nf
.B #include <sys/kdaemon.h>
-.PP
+.P
.BI "[[deprecated]] int bdflush(int " func ", long *" address );
.BI "[[deprecated]] int bdflush(int " func ", long " data );
.fi
is handled by the kernel
.I pdflush
thread.
-.PP
+.P
.BR bdflush ()
starts, flushes, or tunes the buffer-dirty-flush daemon.
Only a privileged process (one with the
.B CAP_SYS_ADMIN
capability) may call
.BR bdflush ().
-.PP
+.P
If
.I func
is negative or 0, and no daemon has been started, then
.BR bdflush ()
enters the daemon code and never returns.
-.PP
+.P
If
.I func
is 1,
some dirty buffers are written to disk.
-.PP
+.P
If
.I func
is 2 or more and is even (low bit is 0), then
and the tuning parameter numbered
.RI "(" "func" "\-2)/2"
is returned to the caller in that address.
-.PP
+.P
If
.I func
is 3 or more and is odd (low bit is 1), then
and the kernel sets tuning parameter numbered
.RI "(" "func" "\-3)/2"
to that value.
-.PP
+.P
The set of parameters, their values, and their valid ranges
are defined in the Linux kernel source file
.IR fs/buffer.c .
.SH SYNOPSIS
.nf
.B #include <sys/socket.h>
-.PP
+.P
.BI "int bind(int " sockfd ", const struct sockaddr *" addr ,
.BI " socklen_t " addrlen );
.fi
specifies the size, in bytes, of the address structure pointed to by
.IR addr .
Traditionally, this operation is called \[lq]assigning a name to a socket\[rq].
-.PP
+.P
It is normally necessary to assign a local address using
.BR bind ()
before a
.B SOCK_STREAM
socket may receive connections (see
.BR accept (2)).
-.PP
+.P
The rules used in name binding vary between address families.
Consult the manual entries in Section 7 for detailed information.
For
.BR AF_NETLINK ,
see
.BR netlink (7).
-.PP
+.P
The actual structure passed for the
.I addr
argument will depend on the address family.
The
.I sockaddr
structure is defined as something like:
-.PP
+.P
.in +4n
.EX
struct sockaddr {
}
.EE
.in
-.PP
+.P
The only purpose of this structure is to cast the structure
pointer passed in
.I addr
The file descriptor
.I sockfd
does not refer to a socket.
-.PP
+.P
The following errors are specific to UNIX domain
.RB ( AF_UNIX )
sockets:
.BR bind ()
with Internet domain sockets can be found in
.BR getaddrinfo (3).
-.PP
+.P
The following example shows how to bind a stream socket in the UNIX
.RB ( AF_UNIX )
domain, and accept connections:
.\" listen.7 refers to this example.
.\" accept.7 refers to this example.
.\" unix.7 refers to this example.
-.PP
+.P
.\" SRC BEGIN (bind.c)
.EX
#include <stdio.h>
.SH SYNOPSIS
.nf
.B #include <linux/bpf.h>
-.PP
+.P
.BI "int bpf(int " cmd ", union bpf_attr *" attr ", unsigned int " size );
.fi
.SH DESCRIPTION
For both cBPF and eBPF programs,
the kernel statically analyzes the programs before loading them,
in order to ensure that they cannot harm the running system.
-.PP
+.P
eBPF extends cBPF in multiple ways, including the ability to call
a fixed set of in-kernel helper functions
.\" See 'enum bpf_func_id' in include/uapi/linux/bpf.h
Data types are generally treated as binary blobs, so a user just specifies
the size of the key and the size of the value at map-creation time.
In other words, a key/value for a given map can have an arbitrary structure.
-.PP
+.P
A user process can create multiple maps (with key/value-pairs being
opaque bytes of data) and access them via file descriptors.
Different eBPF programs can access the same maps in parallel.
It's up to the user process and eBPF program to decide what they store
inside maps.
-.PP
+.P
There's one special map type, called a program array.
This type of map stores file descriptors referring to other eBPF programs.
When a lookup in the map is performed, the program flow is
See
.B BPF_MAP_TYPE_PROG_ARRAY
below for further details.
-.PP
+.P
Generally, eBPF programs are loaded by the user process and automatically
unloaded when the process exits.
In some cases, for example,
depends on how it is further attached to a given kernel subsystem
after it was loaded via
.BR bpf ().
-.PP
+.P
Each eBPF program is a set of instructions that is safe to run until
its completion.
An in-kernel verifier statically determines that the eBPF program
During verification, the kernel increments reference counts for each of
the maps that the eBPF program uses,
so that the attached maps can't be removed until the program is unloaded.
-.PP
+.P
eBPF programs can be attached to different events.
These events can be the arrival of network packets, tracing
events, classification events by network queueing disciplines
may store information about the event in eBPF maps.
Beyond storing data, eBPF programs may call a fixed set of
in-kernel helper functions.
-.PP
+.P
The same eBPF program can be attached to multiple events and different
eBPF programs can access the same map:
-.PP
+.P
.in +4n
.EX
tracing tracing tracing packet packet packet
.I size
argument is the size of the union pointed to by
.IR attr .
-.PP
+.P
The value provided in
.I cmd
is one of the following:
union consists of various anonymous structures that are used by different
.BR bpf ()
commands:
-.PP
+.P
.in +4n
.EX
union bpf_attr {
Maps are a generic data structure for storage of different types of data.
They allow sharing of data between eBPF kernel programs,
and also between kernel and user-space applications.
-.PP
+.P
Each map type has the following attributes:
.IP \[bu] 3
type
key size in bytes
.IP \[bu]
value size in bytes
-.PP
+.P
The following wrapper functions demonstrate how various
.BR bpf ()
commands can be used to access the maps.
command is used to load an eBPF program into the kernel.
The return value for this command is a new file descriptor associated
with this eBPF program.
-.PP
+.P
.in +4n
.EX
char bpf_log_buf[LOG_BUF_SIZE];
}
.EE
.in
-.PP
+.P
.I prog_type
is one of the available program types:
.IP
};
.EE
.in
-.PP
+.P
For further details of eBPF program types, see below.
-.PP
+.P
The remaining fields of
.I bpf_attr
are set as follows:
must be a NULL pointer, and
.I log_size
must be zero.
-.PP
+.P
Applying
.BR close (2)
to the file descriptor returned by
.B BPF_PROG_LOAD
will unload the eBPF program (but see NOTES).
-.PP
+.P
Maps are accessible from eBPF programs and are used to exchange data between
eBPF programs and between eBPF programs and user-space programs.
For example,
.\" Somewhere in this page we need a general introduction to the
.\" bpf_context. For example, how does a BPF program access the
.\" context?
-.PP
+.P
For example, a tracing program does not have the exact same
subset of helper functions as a socket filter program
(though they may have some helpers in common).
Similarly,
the input (context) for a tracing program is a set of register values,
while for a socket filter it is a network packet.
-.PP
+.P
The set of functions available to eBPF programs of a given type may increase
in the future.
-.PP
+.P
The following program types are supported:
.TP
.BR BPF_PROG_TYPE_SOCKET_FILTER " (since Linux 3.19)"
.SS Events
Once a program is loaded, it can be attached to an event.
Various kernel subsystems have different ways to do so.
-.PP
+.P
Since Linux 3.19,
.\" commit 89aa075832b0da4402acebd698d0411dcc82d03e
the following call will attach the program
.IR sockfd ,
which was created by an earlier call to
.BR socket (2):
-.PP
+.P
.in +4n
.EX
setsockopt(sockfd, SOL_SOCKET, SO_ATTACH_BPF,
&prog_fd, sizeof(prog_fd));
.EE
.in
-.PP
+.P
Since Linux 4.1,
.\" commit 2541517c32be2531e0da59dfd7efc1ce844644f5
the following call may be used to attach
.IR event_fd ,
that was created by a previous call to
.BR perf_event_open (2):
-.PP
+.P
.in +4n
.EX
ioctl(event_fd, PERF_EVENT_IOC_SET_BPF, prog_fd);
.TP
All other commands
Zero.
-.PP
+.P
On error, \-1 is returned, and
.I errno
is set to indicate the error.
.IP \[bu]
ktime_get_ns
.PD
-.PP
+.P
Unprivileged access may be blocked by writing the value 1 to the file
.IR /proc/sys/kernel/unprivileged_bpf_disabled .
-.PP
+.P
eBPF objects (maps and programs) can be shared between processes.
For example, after
.BR fork (2),
and similar calls.
An eBPF object is deallocated only after all file descriptors
referring to the object have been closed.
-.PP
+.P
eBPF programs can be written in a restricted C that is compiled (using the
.B clang
compiler) into eBPF bytecode.
files in the kernel source tree.
.\" There are also examples for the tc classifier, in the iproute2
.\" project, in examples/bpf
-.PP
+.P
The kernel contains a just-in-time (JIT) compiler that translates
eBPF bytecode into native machine code for better performance.
Before Linux 4.15,
These opcodes can then be disassembled using the program
.I tools/net/bpf_jit_disasm.c
provided in the kernel source tree.
-.PP
+.P
Since Linux 4.15,
.\" commit 290af86629b25ffd1ed6232c4e9107da031705cb
the kernel may configured with the
is initialized to 1 and is immutable.
(This kernel configuration option was provided as a mitigation for
one of the Spectre attacks against the BPF interpreter.)
-.PP
+.P
The JIT compiler for eBPF is currently
.\" Last reviewed in Linux 4.18-rc by grepping for BPF_ALU64 in arch/
.\" and by checking the documentation for bpf_jit_enable in
}
.EE
.\" SRC END
-.PP
+.P
Some complete working code can be found in the
.I samples/bpf
directory in the kernel source tree.
.BR socket (7),
.BR tc (8),
.BR tc\-bpf (8)
-.PP
+.P
Both classic and extended BPF are explained in the kernel source file
.IR Documentation/networking/filter.txt .
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.BI "int brk(void *" addr );
.BI "void *sbrk(intptr_t " increment );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR brk (),
.BR sbrk ():
.nf
Increasing the program break has the effect of
allocating memory to the process;
decreasing the break deallocates memory.
-.PP
+.P
.BR brk ()
sets the end of the data segment to the value specified by
.IR addr ,
when that value is reasonable, the system has enough memory,
and the process does not exceed its maximum data size (see
.BR setrlimit (2)).
-.PP
+.P
.BR sbrk ()
increments the program's data space by
.I increment
.I errno
is set to
.BR ENOMEM .
-.PP
+.P
On success,
.BR sbrk ()
returns the previous program break.
.BR malloc (3)
memory allocation package is the
portable and comfortable way of allocating memory.
-.PP
+.P
Various systems use various types for the argument of
.BR sbrk ().
Common are \fIint\fP, \fIssize_t\fP, \fIptrdiff_t\fP, \fIintptr_t\fP.
(i.e., checks whether the new break is less than
.IR addr )
to provide the 0 and \-1 return values described above.
-.PP
+.P
On Linux,
.BR sbrk ()
is implemented as a library function that uses the
.SH SYNOPSIS
.nf
.B #include <sys/cachectl.h>
-.PP
+.P
.BI "int cacheflush(void " addr [. nbytes "], int "nbytes ", int "cache );
.fi
-.PP
+.P
.IR Note :
On some architectures,
there is no glibc wrapper for this system call; see NOTES.
with the prototype shown in SYNOPSIS,
for the following architectures:
ARC, CSKY, MIPS, and NIOS2.
-.PP
+.P
On some other architectures,
Linux provides this system call, with different arguments:
.TP
.nf
.BI "int cacheflush(unsigned int " start ", unsigned int " end ", int " cache );
.fi
-.PP
+.P
On the above architectures,
glibc does not provide a wrapper for this system call; call it using
.BR syscall (2).
.BR __builtin___clear_cache (),
which provides a portable interface
across platforms supported by GCC and compatible compilers:
-.PP
+.P
.in +4n
.EX
.BI "void __builtin___clear_cache(void *" begin ", void *" end );
.EE
.in
-.PP
+.P
On platforms that don't require instruction cache flushes,
.BR __builtin___clear_cache ()
has no effect.
-.PP
+.P
.IR Note :
On some GCC-compatible compilers,
the prototype for this built-in function uses
.I nbytes
arguments, making this function fairly expensive.
Therefore, the whole cache is always flushed.
-.PP
+.P
This function always behaves as if
.B BCACHE
has been passed for the
.BR " _LINUX_CAPABILITY_*" " constants */"
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "int syscall(SYS_capget, cap_user_header_t " hdrp ,
.BI " cap_user_data_t " datap );
.BI "int syscall(SYS_capset, cap_user_header_t " hdrp ,
.BI " const cap_user_data_t " datap );
.fi
-.PP
+.P
.IR Note :
glibc provides no wrappers for these system calls,
necessitating the use of
.I cap_user_*_t
types) is subject to extension with each kernel revision,
but old programs will keep working.
-.PP
+.P
The portable interfaces are
.BR cap_set_proc (3)
and
.SS Current details
Now that you have been warned, some current kernel details.
The structures are defined as follows.
-.PP
+.P
.in +4n
.EX
#define _LINUX_CAPABILITY_VERSION_1 0x19980330
} *cap_user_data_t;
.EE
.in
-.PP
+.P
The
.IR effective ,
.IR permitted ,
and
.I struct __user_cap_data_struct
names because the typedefs are only pointers.
-.PP
+.P
Kernels prior to Linux 2.6.25 prefer
32-bit capabilities with version
.BR _LINUX_CAPABILITY_VERSION_1 .
There was, however, an API glitch, and Linux 2.6.26 added
.B _LINUX_CAPABILITY_VERSION_3
to fix the problem.
-.PP
+.P
Note that 64-bit capabilities use
.I datap[0]
and
.IR datap[1] ,
whereas 32-bit capabilities use only
.IR datap[0] .
-.PP
+.P
On kernels that support file capabilities (VFS capabilities support),
these system calls behave slightly differently.
This support was added as an option in Linux 2.6.24,
and became fixed (nonoptional) in Linux 2.6.33.
-.PP
+.P
For
.BR capget ()
calls, one can probe the capabilities of any process by specifying its
process ID with the
.I hdrp\->pid
field value.
-.PP
+.P
For details on the data, see
.BR capabilities (7).
.\"
On error, \-1 is returned, and
.I errno
is set to indicate the error.
-.PP
+.P
The calls fail with the error
.BR EINVAL ,
and set the
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.BI "int chdir(const char *" path );
.BI "int fchdir(int " fd );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR fchdir ():
.nf
_XOPEN_SOURCE >= 500
changes the current working directory of the calling process to the
directory specified in
.IR path .
-.PP
+.P
.BR fchdir ()
is identical to
.BR chdir ();
A component of
.I path
is not a directory.
-.PP
+.P
The general errors for
.BR fchdir ()
are listed below:
.SH NOTES
The current working directory is the starting point for interpreting
relative pathnames (those not starting with \[aq]/\[aq]).
-.PP
+.P
A child process created via
.BR fork (2)
inherits its parent's current working directory.
.SH SYNOPSIS
.nf
.B #include <sys/stat.h>
-.PP
+.P
.BI "int chmod(const char *" pathname ", mode_t " mode );
.BI "int fchmod(int " fd ", mode_t " mode );
-.PP
+.P
.BR "#include <fcntl.h>" " /* Definition of AT_* constants */"
.B #include <sys/stat.h>
-.PP
+.P
.BI "int fchmodat(int " dirfd ", const char *" pathname ", mode_t " \
mode ", int " flags );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.nf
.BR fchmod ():
Since glibc 2.24:
_BSD_SOURCE || _XOPEN_SOURCE >= 500
.\" || (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED)
.fi
-.PP
+.P
.BR fchmodat ():
.nf
Since glibc 2.10:
.BR fchmod ()
changes the mode of the file referred to by the open file descriptor
.IR fd .
-.PP
+.P
The new file mode is specified in
.IR mode ,
which is a bit mask created by ORing together zero or
.TP
.BR S_IXOTH " (00001)"
execute/search by others
-.PP
+.P
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
.B CAP_FOWNER
capability).
-.PP
+.P
If the calling process is not privileged (Linux: does not have the
.B CAP_FSETID
capability), and the group of the file does not match
.B S_ISGID
bit will be turned off,
but this will not cause an error to be returned.
-.PP
+.P
As a security measure, depending on the filesystem,
the set-user-ID and set-group-ID execution bits
may be turned off if a file is written.
For the sticky bit, and for set-user-ID and set-group-ID bits on
directories, see
.BR inode (7).
-.PP
+.P
On NFS filesystems, 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.
system call operates in exactly the same way as
.BR chmod (),
except for the differences described here.
-.PP
+.P
If the pathname given in
.I pathname
is relative, then it is interpreted relative to the directory
the calling process, as is done by
.BR chmod ()
for a relative pathname).
-.PP
+.P
If
.I pathname
is relative and
is interpreted relative to the current working
directory of the calling process (like
.BR chmod ()).
-.PP
+.P
If
.I pathname
is absolute, then
.I dirfd
is ignored.
-.PP
+.P
.I flags
can either be 0, or include the following flag:
.TP
is a symbolic link, do not dereference it:
instead operate on the link itself.
This flag is not currently implemented.
-.PP
+.P
See
.BR openat (2)
for an explanation of the need for
.SH ERRORS
Depending on the filesystem,
errors other than those listed below can be returned.
-.PP
+.P
The more general errors for
.BR chmod ()
are listed below:
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.BI "int chown(const char *" pathname ", uid_t " owner ", gid_t " group );
.BI "int fchown(int " fd ", uid_t " owner ", gid_t " group );
.BI "int lchown(const char *" pathname ", uid_t " owner ", gid_t " group );
-.PP
+.P
.BR "#include <fcntl.h> " "/* Definition of AT_* constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "int fchownat(int " dirfd ", const char *" pathname ,
.BI " uid_t " owner ", gid_t " group ", int " flags );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR fchown (),
.BR lchown ():
.nf
.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
|| /* glibc <= 2.19: */ _BSD_SOURCE
.fi
-.PP
+.P
.BR fchownat ():
.nf
Since glibc 2.10:
is like
.BR chown (),
but does not dereference symbolic links.
-.PP
+.P
Only a privileged process (Linux: one with the
.B CAP_CHOWN
capability) may change the owner of a file.
A privileged process (Linux: with
.BR CAP_CHOWN )
may change the group arbitrarily.
-.PP
+.P
If the
.I owner
or
.I group
is specified as \-1, then that ID is not changed.
-.PP
+.P
When the owner or group of an executable file is
changed by an unprivileged user, the
.B S_ISUID
.B S_ISGID
bit indicates mandatory locking, and is not cleared by a
.BR chown ().
-.PP
+.P
When the owner or group of an executable file is changed (by any user),
all capability sets for the file are cleared.
.\"
system call operates in exactly the same way as
.BR chown (),
except for the differences described here.
-.PP
+.P
If the pathname given in
.I pathname
is relative, then it is interpreted relative to the directory
the calling process, as is done by
.BR chown ()
for a relative pathname).
-.PP
+.P
If
.I pathname
is relative and
is interpreted relative to the current working
directory of the calling process (like
.BR chown ()).
-.PP
+.P
If
.I pathname
is absolute, then
.I dirfd
is ignored.
-.PP
+.P
The
.I flags
argument is a bit mask created by ORing together
.BR fchownat ()
dereferences symbolic links, like
.BR chown ().)
-.PP
+.P
See
.BR openat (2)
for an explanation of the need for
.SH ERRORS
Depending on the filesystem,
errors other than those listed below can be returned.
-.PP
+.P
The more general errors for
.BR chown ()
are listed below.
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.
-.PP
+.P
As at Linux 4.12,
the
.B \-o\ grpid
and
.BR lchown ()
wrapper functions transparently deal with the variations across kernel versions.
-.PP
+.P
Before Linux 2.1.81 (except 2.1.46),
.BR chown ()
did not follow symbolic links.
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.BI "int chroot(const char *" path );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR chroot ():
.nf
Since glibc 2.2.2:
.IR path .
This directory will be used for pathnames beginning with \fI/\fP.
The root directory is inherited by all children of the calling process.
-.PP
+.P
Only a privileged process (Linux: one with the
.B CAP_SYS_CHROOT
capability in its user namespace) may call
.BR chroot ().
-.PP
+.P
This call changes an ingredient in the pathname resolution process
and does nothing else.
In particular, it is not intended to be used
.BR chdir (2)
to the to-be-moved directory, wait for it to be moved out, then open a
path like ../../../etc/passwd.
-.PP
+.P
.\" This is how the "slightly trickier variation" works:
.\" https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-014-2015.txt#L142
A slightly
that usually means that if you want to prevent remote users from accessing
files outside the chroot directory, you must ensure that folders are never
moved out of it.
-.PP
+.P
This call does not change the current working directory,
so that after the call \[aq]\fI.\fP\[aq] can
be outside the tree rooted at \[aq]\fI/\fP\[aq].
In particular, the superuser can escape from a "chroot jail"
by doing:
-.PP
+.P
.in +4n
.EX
mkdir foo; chroot foo; cd ..
.EE
.in
-.PP
+.P
This call does not close open file descriptors, and such file
descriptors may allow access to files outside the chroot tree.
.SH RETURN VALUE
inherits its parent's root directory.
The root directory is left unchanged by
.BR execve (2).
-.PP
+.P
The magic symbolic link,
.IR /proc/ pid /root ,
can be used to discover a process's root directory; see
.BR proc (5)
for details.
-.PP
+.P
FreeBSD has a stronger
.BR jail ()
system call.
Standard C library
.RI ( libc ", " \-lc ),
since glibc 2.17
-.PP
+.P
Before glibc 2.17,
Real-time library
.RI ( librt ", " \-lrt )
.SH SYNOPSIS
.nf
.B #include <time.h>
-.PP
+.P
.BI "int clock_getres(clockid_t " clockid ", struct timespec *_Nullable " res );
-.PP
+.P
.BI "int clock_gettime(clockid_t " clockid ", struct timespec *" tp );
.BI "int clock_settime(clockid_t " clockid ", const struct timespec *" tp );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR clock_getres (),
.BR clock_gettime (),
.BR clock_settime ():
.IR res ,
then it is truncated to a multiple of
.IR res .
-.PP
+.P
The functions
.BR clock_gettime ()
and
.BR clock_settime ()
retrieve and set the time of the specified clock
.IR clockid .
-.PP
+.P
The
.I res
and
arguments are
.BR timespec (3)
structures.
-.PP
+.P
The
.I clockid
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.
-.PP
+.P
All implementations support the system-wide real-time clock,
which is identified by
.BR 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.
-.PP
+.P
More clocks may be implemented.
The interpretation of the
corresponding time values and the effect on timers is unspecified.
-.PP
+.P
Sufficiently recent versions of glibc and the Linux kernel
support the following clocks:
.TP
.BR CLOCK_THREAD_CPUTIME_ID " (since Linux 2.6.12)"
This is a clock that measures CPU time consumed by this thread.
On Linux, this clock is not settable.
-.PP
+.P
Linux also implements dynamic clock instances as described below.
.SS Dynamic clocks
In addition to the hard-coded System-V style clock IDs described above,
POSIX clock operations on certain character devices.
Such devices are
called "dynamic" clocks, and are supported since Linux 2.6.39.
-.PP
+.P
Using the appropriate macros, open file
descriptors may be converted into clock IDs and passed to
.BR clock_gettime (),
.BR clock_adjtime (2).
The following example shows how to convert a file descriptor into a
dynamic clock ID.
-.PP
+.P
.in +4n
.EX
#define CLOCKFD 3
.SH VERSIONS
POSIX.1 specifies the following:
.RS
-.PP
+.P
Setting the value of the
.B CLOCK_REALTIME
clock via
Consequently, these time services shall expire when the requested relative
interval elapses, independently of the new or old value of the clock.
.RE
-.PP
+.P
According to POSIX.1-2001, a process with "appropriate privileges" may set the
.B CLOCK_PROCESS_CPUTIME_ID
and
.SH HISTORY
POSIX.1-2001, SUSv2.
Linux 2.6.
-.PP
+.P
On POSIX systems on which these functions are available, the symbol
.B _POSIX_TIMERS
is defined in \fI<unistd.h>\fP to a value greater than 0.
these clocks may return
.B bogus results
if a process is migrated to another CPU.
-.PP
+.P
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.
to signify this condition.
The two clocks will then be useful only if it
can be ensured that a process stays on a certain CPU.
-.PP
+.P
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.
Kernel).
Typically these offsets are small and therefore the effects may be
negligible in most cases.
-.PP
+.P
Since glibc 2.4,
the wrapper functions for the system calls described in this page avoid
the abovementioned problems by employing the kernel implementation of
.BR clock_getres ()
with various clocks.
This is an example of what we might see when running the program:
-.PP
+.P
.in +4n
.EX
$ \fB./clock_times x\fP
Standard C library
.RI ( libc ", " \-lc ),
since glibc 2.17
-.PP
+.P
Before glibc 2.17,
Real-time library
.RI ( librt ", " \-lrt )
.SH SYNOPSIS
.B #include <time.h>
.nf
-.PP
+.P
.BI "int clock_nanosleep(clockid_t " clockid ", int " flags ,
.BI " const struct timespec *" request ,
.BI " struct timespec *_Nullable " remain );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR clock_nanosleep ():
.nf
_POSIX_C_SOURCE >= 200112L
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.
-.PP
+.P
The time values passed to and returned by this call are specified using
.BR timespec (3)
structures.
-.PP
+.P
The
.I clockid
argument specifies the clock against which the sleep interval
by all threads in the process.
.\" There is some trickery between glibc and the kernel
.\" to deal with the CLOCK_PROCESS_CPUTIME_ID case.
-.PP
+.P
See
.BR clock_getres (2)
for further details on these clocks.
.\" Sleeping against CLOCK_REALTIME_ALARM and CLOCK_BOOTTIME_ALARM
.\" is also possible (tested), with CAP_WAKE_ALARM, but I'm not
.\" sure if this is useful or needs to be documented.
-.PP
+.P
If
.I flags
is 0, then the value specified in
is interpreted as an interval relative to the current
value of the clock specified by
.IR clockid .
-.PP
+.P
If
.I flags
is
then
.BR clock_nanosleep ()
returns immediately without suspending the calling thread.
-.PP
+.P
.BR clock_nanosleep ()
suspends the execution of the calling thread
until either at least the time specified by
has elapsed,
or a signal is delivered that causes a signal handler to be called or
that terminates the process.
-.PP
+.P
If the call is interrupted by a signal handler,
.BR clock_nanosleep ()
fails with the error
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.
-.PP
+.P
Using an absolute timer is useful for preventing
timer drift problems of the type described in
.BR nanosleep (2).
with the
.B TIMER_ABSTIME
flag.
-.PP
+.P
.BR clock_nanosleep ()
is never restarted after being interrupted by a signal handler,
regardless of the use of the
.BR sigaction (2)
.B SA_RESTART
flag.
-.PP
+.P
The
.I remain
argument is unused, and unnecessary, when
(An absolute sleep can be restarted using the same
.I request
argument.)
-.PP
+.P
POSIX.1 specifies that
.BR clock_nanosleep ()
has no effect on signals dispositions or the signal mask.
-.PP
+.P
POSIX.1 specifies that after changing the value of the
.B CLOCK_REALTIME
clock via
if the new clock value falls past the end of the sleep interval, then the
.BR clock_nanosleep ()
call will return immediately.
-.PP
+.P
POSIX.1 specifies that
changing the value of the
.B CLOCK_REALTIME
.SH SYNOPSIS
.nf
/* Prototype for the glibc wrapper function */
-.PP
+.P
.B #define _GNU_SOURCE
.B #include <sched.h>
-.PP
+.P
.BI "int clone(int (*" "fn" ")(void *_Nullable), void *" stack \
", int " flags ,
.BI " void *_Nullable " "arg" ", ..." \
" \fR/*\fP" " pid_t *_Nullable " parent_tid ,
.BI " void *_Nullable " tls ,
.BI " pid_t *_Nullable " child_tid " \fR*/\fP );"
-.PP
+.P
/* For the prototype of the raw clone() system call, see NOTES */
-.PP
+.P
.BR "#include <linux/sched.h>" " /* Definition of " "struct clone_args" " */"
.BR "#include <sched.h>" " /* Definition of " CLONE_* " constants */"
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "long syscall(SYS_clone3, struct clone_args *" cl_args ", size_t " size );
.fi
-.PP
+.P
.IR Note :
glibc provides no wrapper for
.BR clone3 (),
These system calls
create a new ("child") process, in a manner similar to
.BR fork (2).
-.PP
+.P
By contrast with
.BR fork (2),
these system calls provide more precise control over what pieces of execution
These system calls also allow the new child process to be placed
in separate
.BR namespaces (7).
-.PP
+.P
Note that in this manual
page, "calling process" normally corresponds to "parent process".
But see the descriptions of
and
.B CLONE_THREAD
below.
-.PP
+.P
This page describes the following interfaces:
.IP \[bu] 3
The glibc
The newer
.BR clone3 ()
system call.
-.PP
+.P
In the remainder of this page, the terminology "the clone call" is used
when noting details that apply to all of these interfaces.
.\"
.I arg
argument is passed as the argument of the function
.IR fn .
-.PP
+.P
When the
.IR fn ( arg )
function returns, the child process terminates.
The child process may also terminate explicitly by calling
.BR exit (2)
or after receiving a fatal signal.
-.PP
+.P
The
.I stack
argument specifies the location of the stack used by the child process.
.BR clone ()
does not provide a means whereby the caller can inform the kernel of the
size of the stack area.
-.PP
+.P
The remaining arguments to
.BR clone ()
are discussed below.
space for additional flags bits;
cleaner separation in the use of various arguments;
and the ability to specify the size of the child's stack area.
-.PP
+.P
As with
.BR fork (2),
.BR clone3 ()
returns in both the parent and the child.
It returns 0 in the child process and returns the PID of the child
in the parent.
-.PP
+.P
The
.I cl_args
argument of
.BR clone3 ()
is a structure of the following form:
-.PP
+.P
.in +4n
.EX
struct clone_args {
};
.EE
.in
-.PP
+.P
The
.I size
argument that is supplied to
argument permits future extensions to the
.I clone_args
structure.)
-.PP
+.P
The stack for the child process is specified via
.IR cl_args.stack ,
which points to the lowest byte of the stack area,
Otherwise, these two fields can be specified as NULL and 0,
which causes the child to use the same stack area as the parent
(in the child's own virtual address space).
-.PP
+.P
The remaining fields in the
.I cl_args
argument are discussed below.
This structure allows for a superset of the information passed via the
.BR clone ()
arguments.
-.PP
+.P
The following table shows the equivalence between the arguments of
.BR clone ()
and the fields in the
array has to be the desired PID and
.I set_tid_size
needs to be 1.
-.PP
+.P
If the PID of the newly created process should have a certain value in
multiple PID namespaces, then the
.I set_tid
should be set is defined by
.I set_tid_size
which cannot be larger than the number of currently nested PID namespaces.
-.PP
+.P
To create a process with the following PIDs in a PID namespace hierarchy:
.RS 4
.TS
2 7 Innermost PID namespace
.TE
.RE
-.PP
+.P
Set the array to:
-.PP
+.P
.in +4n
.EX
set_tid[0] = 7;
set_tid_size = 3;
.EE
.in
-.PP
+.P
If only the PIDs in the two innermost PID namespaces
need to be specified, set the array to:
-.PP
+.P
.in +4n
.EX
set_tid[0] = 7;
set_tid_size = 2;
.EE
.in
-.PP
+.P
The PID in the PID namespaces outside the two innermost PID namespaces
is selected the same way as any other PID is selected.
-.PP
+.P
The
.I set_tid
feature requires
.\" commit 1caef81da05a84a40dbf02110e967ce6d1135ff6
.B CAP_CHECKPOINT_RESTORE
in all owning user namespaces of the target PID namespaces.
-.PP
+.P
Callers may only choose a PID greater than 1 in a given PID namespace
if an
.B init
referred to as the
.I flags
mask in the remainder of this page.
-.PP
+.P
The
.I flags
mask is specified as a bitwise OR of zero or more of
is used to recursively create children,
do not use the buffer employed for the parent's stack
as the stack of the child.
-.PP
+.P
On i386,
.BR clone ()
should not be called through vsyscall, but directly through
arguments of the
.BR clone ()
wrapper function are omitted.
-.PP
+.P
In contrast to the glibc wrapper, the raw
.BR clone ()
system call accepts NULL as a
.B CLONE_VM
flag,
then no copy-on-write duplication occurs and chaos is likely to result.)
-.PP
+.P
The order of the arguments also differs in the raw system call,
and there are variations in the arguments across architectures,
as detailed in the following paragraphs.
-.PP
+.P
The raw system call interface on x86-64 and some other architectures
(including sh, tile, and alpha) is:
-.PP
+.P
.in +4n
.EX
.BI "long clone(unsigned long " flags ", void *" stack ,
.BI " unsigned long " tls );
.EE
.in
-.PP
+.P
On x86-32, and several other common architectures
(including score, ARM, ARM 64, PA-RISC, arc, Power PC, xtensa,
and MIPS),
.\" CONFIG_CLONE_BACKWARDS
the order of the last two arguments is reversed:
-.PP
+.P
.in +4n
.EX
.BI "long clone(unsigned long " flags ", void *" stack ,
.BI " int *" child_tid );
.EE
.in
-.PP
+.P
On the cris and s390 architectures,
.\" CONFIG_CLONE_BACKWARDS2
the order of the first two arguments is reversed:
-.PP
+.P
.in +4n
.EX
.BI "long clone(void *" stack ", unsigned long " flags ,
.BI " unsigned long " tls );
.EE
.in
-.PP
+.P
On the microblaze architecture,
.\" CONFIG_CLONE_BACKWARDS3
an additional argument is supplied:
-.PP
+.P
.in +4n
.EX
.BI "long clone(unsigned long " flags ", void *" stack ,
For details, see the kernel (and glibc) source.
.SS ia64
On ia64, a different interface is used:
-.PP
+.P
.in +4n
.EX
.BI "int __clone2(int (*" "fn" ")(void *),"
.BI " pid_t *" child_tid " */ );"
.EE
.in
-.PP
+.P
The prototype shown above is for the glibc wrapper function;
for the system call itself,
the prototype can be described as follows (it is identical to the
.BR clone ()
prototype on microblaze):
-.PP
+.P
.in +4n
.EX
.BI "long clone2(unsigned long " flags ", void *" stack_base ,
.BI " unsigned long " tls );
.EE
.in
-.PP
+.P
.BR __clone2 ()
operates in the same way as
.BR clone (),
flag implied the
.B CLONE_PARENT
flag (as in Linux 2.6.0 and later).
-.PP
+.P
In Linux 2.4 and earlier,
.BR clone ()
does not take arguments
One use of these systems calls
is to implement threads: multiple flows of control in a program that
run concurrently in a shared address space.
-.PP
+.P
The
.BR kcmp (2)
system call can be used to test whether two processes share various
resources such as a file descriptor table,
System V semaphore undo operations, or a virtual address space.
-.PP
+.P
Handlers registered using
.BR pthread_atfork (3)
are not executed during a clone call.
argument includes
.BR CLONE_VM .)
To get the truth, it was sometimes necessary to use code such as the following:
-.PP
+.P
.in +4n
.EX
#include <syscall.h>
.\" See also the following bug reports
.\" https://bugzilla.redhat.com/show_bug.cgi?id=417521
.\" http://sourceware.org/bugzilla/show_bug.cgi?id=6910
-.PP
+.P
Because of the stale-cache problem, as well as other problems noted in
.BR getpid (2),
the PID caching feature was removed in glibc 2.25.
differs in the UTS namespaces of the parent and child.
For an example of the use of this program, see
.BR setns (2).
-.PP
+.P
Within the sample program, we allocate the memory that is to
be used for the child's stack using
.BR mmap (2)
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.BI "int close(int " fd );
.fi
.SH DESCRIPTION
.BR fcntl (2)
for discussion of the risks and consequences
as well as for the (probably preferred) open file description locks.
-.PP
+.P
If
.I fd
is the last file descriptor referring to the underlying
.BR fsync (2),
or
.BR close ().
-.PP
+.P
See NOTES for a discussion of why
.BR close ()
should not be retried after an error.
the data is physically stored on the underlying disk, use
.BR fsync (2).
(It will depend on the disk hardware at this point.)
-.PP
+.P
The close-on-exec file descriptor flag can be used to ensure
that a file descriptor is automatically closed upon a successful
.BR execve (2);
.\" call has restarted after ERESTARTSYS, the original system call will
.\" later restart with the reused file descriptor. This is most likely a
.\" serious programming error.
-.PP
+.P
Furthermore, consider the following scenario where two threads are
performing operations on the same file descriptor:
.IP (1) 5
from a stream socket which currently has no available data.
.IP (2)
Another thread closes the file descriptor.
-.PP
+.P
The behavior in this situation varies across systems.
On some systems, when the file descriptor is closed,
the blocking system call returns immediately with an error.
-.PP
+.P
On Linux (and possibly some other systems), the behavior is different:
the blocking I/O system call holds a reference to the underlying
open file description, and this reference keeps the description open
.I silent
loss of data.
This can especially be observed with NFS and with disk quota.
-.PP
+.P
Note, however, that a failure return should be used only for
diagnostic purposes (i.e., a warning to the application that there
may still be I/O pending or there may have been failed I/O)
or remedial purposes
(e.g., writing the file once more or creating a backup).
-.PP
+.P
Retrying the
.BR close ()
after a failure return is the wrong thing to do,
.\" filp_close()
such as flushing data to the filesystem or device,
occur only later in the close operation.
-.PP
+.P
Many other implementations similarly always close the file descriptor
.\" FreeBSD documents this explicitly. From the look of the source code
.\" SVR4, ancient SunOS, later Solaris, and AIX all do this.
but there are plans to mandate this behavior in the next major release
.\" Issue 8
of the standard.
-.PP
+.P
A careful programmer who wants to know about I/O errors may precede
.BR close ()
with a call to
.BR fsync (2).
-.PP
+.P
The
.B EINTR
error is a somewhat special case.
Regarding the
.B EINTR
error, POSIX.1-2008 says:
-.PP
+.P
.RS
If
.BR close ()
.I fildes
is unspecified.
.RE
-.PP
+.P
This permits the behavior that occurs on Linux and
many other implementations, where,
as with other errors that may be reported by
.SH SYNOPSIS
.nf
.B #include <linux/close_range.h>
-.PP
+.P
.BI "int close_range(unsigned int " first ", unsigned int " last ,
.BI " unsigned int " flags );
.fi
to
.I last
(included).
-.PP
+.P
Errors closing a given file descriptor are currently ignored.
-.PP
+.P
.I flags
is a bit mask containing 0 or more of the following:
.TP
.I first
is greater than
.IR last .
-.PP
+.P
The following can occur with
.B CLOSE_RANGE_UNSHARE
(when constructing the new descriptor table):
.SS Closing file descriptors before exec
.\" 60997c3d45d9a67daf01c56d805ae4fec37e0bd8
File descriptors can be closed safely using
-.PP
+.P
.in +4n
.EX
/* we don't want anything past stderr here */
execve(....);
.EE
.in
-.PP
+.P
.B CLOSE_RANGE_UNSHARE
is conceptually equivalent to
-.PP
+.P
.in +4n
.EX
unshare(CLONE_FILES);
close_range(first, last, 0);
.EE
.in
-.PP
+.P
but can be more efficient:
if the unshared range extends past
the current maximum number of file descriptors allocated
to close all file descriptors greater than or equal to 3,
and then once more displays the process's list of open files.
The following example demonstrates the use of the program:
-.PP
+.P
.in +4n
.EX
$ \fBtouch /tmp/a /tmp/b /tmp/c\fP
/proc/self/fd/3 ==> /proc/9005/fd
.EE
.in
-.PP
+.P
Note that the lines showing the pathname
.I /proc/9005/fd
result from the calls to
.SH SYNOPSIS
.nf
.B #include <sys/socket.h>
-.PP
+.P
.BI "int connect(int " sockfd ", const struct sockaddr *" addr ,
.BI " socklen_t " addrlen );
.fi
see
.BR socket (2)
for further details.
-.PP
+.P
If the socket
.I sockfd
is of type
this call attempts to make a connection to the socket that is bound
to the address specified by
.IR addr .
-.PP
+.P
Some protocol sockets (e.g., UNIX domain stream sockets)
may successfully
.BR connect ()
only once.
-.PP
+.P
Some protocol sockets
(e.g., datagram sockets in the UNIX and Internet domains)
may use
.BR connect ()
multiple times to change their association.
-.PP
+.P
Some protocol sockets
(e.g., TCP sockets as well as datagram sockets in the UNIX and
Internet domains)
.B #define _GNU_SOURCE
.B #define _FILE_OFFSET_BITS 64
.B #include <unistd.h>
-.PP
+.P
.BI "ssize_t copy_file_range(int " fd_in ", off_t *_Nullable " off_in ,
.BI " int " fd_out ", off_t *_Nullable " off_out ,
.BI " size_t " len ", unsigned int " flags );
to the target file descriptor
.IR fd_out ,
overwriting any data that exists within the requested range of the target file.
-.PP
+.P
The following semantics apply for
.IR off_in ,
and similar statements apply to
is not changed, but
.I off_in
is adjusted appropriately.
-.PP
+.P
.I fd_in
and
.I fd_out
can refer to the same file.
If they refer to the same file, then the source and target ranges are not
allowed to overlap.
-.PP
+.P
The
.I flags
argument is provided to allow for future extensions
is at or past the end of file, no bytes are copied, and
.BR copy_file_range ()
returns zero.
-.PP
+.P
On error,
.BR copy_file_range ()
returns \-1 and
A major rework of the kernel implementation occurred in Linux 5.3.
Areas of the API that weren't clearly defined were clarified and the API bounds
are much more strictly checked than on earlier kernels.
-.PP
+.P
Since Linux 5.19,
cross-filesystem copies can be achieved
when both filesystems are of the same type,
and that filesystem implements support for it.
See BUGS for behavior prior to Linux 5.19.
-.PP
+.P
Applications should target the behaviour and requirements of Linux 5.19,
that was also backported to earlier stable kernels.
.SH STANDARDS
and
.B SEEK_HOLE
operations to find the locations of data segments.
-.PP
+.P
.BR copy_file_range ()
gives filesystems an opportunity to implement "copy acceleration" techniques,
such as the use of reflinks (i.e., two or more inodes that share
pointers to the same copy-on-write disk blocks)
or server-side-copy (in the case of NFS).
-.PP
+.P
.B _FILE_OFFSET_BITS
should be defined to be 64 in code that uses non-null
.I off_in
.SH SYNOPSIS
.nf
.B #include <linux/module.h>
-.PP
+.P
.BI "[[deprecated]] caddr_t create_module(const char *" name ", size_t " size );
.fi
.SH DESCRIPTION
.IR Note :
This system call is present only before Linux 2.6.
-.PP
+.P
.BR create_module ()
attempts to create a loadable module entry and reserve the kernel memory
that will be needed to hold the module.
.SH HISTORY
Removed in Linux 2.6.
.\" Removed in Linux 2.5.48
-.PP
+.P
This obsolete system call is not supported by glibc.
No declaration is provided in glibc headers, but, through a quirk of history,
glibc versions before glibc 2.23 did export an ABI for this system call.
.BR "#include <fcntl.h>" " /* Definition of " O_* " constants */"
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "int syscall(SYS_delete_module, const char *" name ", unsigned int " flags );
.fi
-.PP
+.P
.IR Note :
glibc provides no wrapper for
.BR delete_module (),
argument is used to modify the behavior of the system call,
as described below.
This system call requires privilege.
-.PP
+.P
Module removal is attempted according to the following rules:
.IP (1) 5
If there are other loaded modules that depend on
The module is unloaded in the usual way.
.RE
.RE
-.PP
+.P
The
.B O_TRUNC
flag has one further effect on the rules described above.
However, if
.B O_TRUNC
was specified, this requirement is bypassed.
-.PP
+.P
Using the
.B O_TRUNC
flag is dangerous!
.BR syscall (2).
.SS Linux 2.4 and earlier
In Linux 2.4 and earlier, the system call took only one argument:
-.PP
+.P
.BI " int delete_module(const char *" name );
-.PP
+.P
If
.I name
is NULL, all unused modules marked auto-clean are removed.
-.PP
+.P
Some further details of differences in the behavior of
.BR delete_module ()
in Linux 2.4 and earlier are
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.BI "int dup(int " oldfd );
.BI "int dup2(int " oldfd ", int " newfd );
-.PP
+.P
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.BR "#include <fcntl.h>" " /* Definition of " O_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "int dup3(int " oldfd ", int " newfd ", int " flags );
.fi
.SH DESCRIPTION
.BR open (2).)
The new file descriptor number is guaranteed to be the lowest-numbered
file descriptor that was unused in the calling process.
-.PP
+.P
After a successful return,
the old and new file descriptors may be used interchangeably.
Since the two file descriptors refer to the same open file description,
.BR lseek (2)
on one of the file descriptors,
the offset is also changed for the other file descriptor.
-.PP
+.P
The two file descriptors do not share file descriptor flags
(the close-on-exec flag).
The close-on-exec flag
.I newfd
is adjusted so that it now refers to the same open file description as
.IR oldfd .
-.PP
+.P
If the file descriptor
.I newfd
was previously open, it is closed before being reused;
the close is performed silently
(i.e., any errors during the close are not reported by
.BR dup2 ()).
-.PP
+.P
The steps of closing and reusing the file descriptor
.I newfd
are performed
Such reuse could happen because the main program is interrupted
by a signal handler that allocates a file descriptor,
or because a parallel thread allocates a file descriptor.
-.PP
+.P
Note the following points:
.IP \[bu] 3
If
.B EINVAL
like
.BR F_DUPFD .
-.PP
+.P
If
.I newfd
was open, any errors that would have been reported at
.BR dup2 (),
because of the race condition described above.
Instead, code something like the following could be used:
-.PP
+.P
.in +4n
.EX
/* Obtain a duplicate of \[aq]newfd\[aq] that can subsequently
.SH SYNOPSIS
.nf
.B #include <sys/epoll.h>
-.PP
+.P
.BI "int epoll_create(int " size );
.BI "int epoll_create1(int " flags );
.fi
Since Linux 2.6.8, the
.I size
argument is ignored, but must be greater than zero; see HISTORY.
-.PP
+.P
.BR epoll_create ()
returns a file descriptor referring to the new epoll instance.
This file descriptor is used for all the subsequent calls to the
.BR epoll_create1 ()
Linux 2.6.27,
glibc 2.9.
-.PP
+.P
In the initial
.BR epoll_create ()
implementation, the
in order to ensure backward compatibility when new
.B epoll
applications are run on older kernels.
-.PP
+.P
Prior to Linux 2.6.29,
.\" commit 9df04e1f25effde823a600e755b51475d438f56b
a
.SH SYNOPSIS
.nf
.B #include <sys/epoll.h>
-.PP
+.P
.BI "int epoll_ctl(int " epfd ", int " op ", int " fd ,
.BI " struct epoll_event *_Nullable " event );
.fi
.I op
be performed for the target file descriptor,
.IR fd .
-.PP
+.P
Valid values for the
.I op
argument are:
The
.I event
argument is ignored and can be NULL (but see BUGS below).
-.PP
+.P
The
.I event
argument describes the object linked to the file descriptor
.I struct epoll_event
is described in
.BR epoll_event (3type).
-.PP
+.P
The
.I data
member of the
structure specifies data that the kernel should save and then return (via
.BR epoll_wait (2))
when this file descriptor becomes ready.
-.PP
+.P
The
.I events
member of the
this event merely indicates that the peer closed its end of the channel.
Subsequent reads from the channel will return 0 (end of file)
only after all outstanding data in the channel has been consumed.
-.PP
+.P
And the available input flags are:
.TP
.B EPOLLET
Applications that need to be portable to kernels before Linux 2.6.9
should specify a non-null pointer in
.IR event .
-.PP
+.P
If
.B EPOLLWAKEUP
is specified in
.SH SYNOPSIS
.nf
.B #include <sys/epoll.h>
-.PP
+.P
.BI "int epoll_wait(int " epfd ", struct epoll_event *" events ,
.BI " int " maxevents ", int " timeout );
.BI "int epoll_pwait(int " epfd ", struct epoll_event *" events ,
The
.I maxevents
argument must be greater than zero.
-.PP
+.P
The
.I timeout
argument specifies the number of milliseconds that
Time is measured against the
.B CLOCK_MONOTONIC
clock.
-.PP
+.P
A call to
.BR epoll_wait ()
will block until either:
the call is interrupted by a signal handler; or
.IP \[bu]
the timeout expires.
-.PP
+.P
Note that the
.I timeout
interval will be rounded up to the system clock granularity,
equal to zero cause
.BR epoll_wait ()
to return immediately, even if no events are available.
-.PP
+.P
The
.I struct epoll_event
is described in
.BR epoll_event (3type).
-.PP
+.P
The
.I data
field of each returned
.BR epoll_ctl (2)
.RB ( EPOLL_CTL_ADD ", " EPOLL_CTL_MOD )
for the corresponding open file descriptor.
-.PP
+.P
The
.I events
field is a bit mask that indicates the events that have occurred for the
.BR epoll_pwait ()
allows an application to safely wait until either a file descriptor
becomes ready or until a signal is caught.
-.PP
+.P
The following
.BR epoll_pwait ()
call:
-.PP
+.P
.in +4n
.EX
ready = epoll_pwait(epfd, &events, maxevents, timeout, &sigmask);
.EE
.in
-.PP
+.P
is equivalent to
.I atomically
executing the following calls:
-.PP
+.P
.in +4n
.EX
sigset_t origmask;
pthread_sigmask(SIG_SETMASK, &origmask, NULL);
.EE
.in
-.PP
+.P
The
.I sigmask
argument may be specified as NULL, in which case
it will cause the
.BR epoll_wait ()
call to unblock.
-.PP
+.P
If more than
.I maxevents
file descriptors are ready when
where a process fails to notice that additional file descriptors
are ready because it focuses on a set of file descriptors that
are already known to be ready.
-.PP
+.P
Note that it is possible to call
.BR epoll_wait ()
on an
.SH SYNOPSIS
.nf
.B #include <sys/eventfd.h>
-.PP
+.P
.BI "int eventfd(unsigned int " initval ", int " flags );
.fi
.SH DESCRIPTION
counter that is maintained by the kernel.
This counter is initialized with the value specified in the argument
.IR initval .
-.PP
+.P
As its return value,
.BR eventfd ()
returns a new file descriptor that can be used to refer to the
eventfd object.
-.PP
+.P
The following values may be bitwise ORed in
.I flags
to change the behavior of
.BR EFD_SEMAPHORE " (since Linux 2.6.30)"
Provide semaphore-like semantics for reads from the new file descriptor.
See below.
-.PP
+.P
Up to Linux 2.6.26, the
.I flags
argument is unused, and must be specified as zero.
-.PP
+.P
The following operations can be performed on the file descriptor returned by
.BR eventfd ():
.TP
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.
-.PP
+.P
A copy of the file descriptor created by
.BR eventfd ()
is inherited by the child produced by
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:
-.PP
+.P
.in +4n
.EX
typedef uint64_t eventfd_t;
int eventfd_write(int fd, eventfd_t value);
.EE
.in
-.PP
+.P
The functions perform the read and write operations on an
eventfd file descriptor,
returning 0 if the correct number of bytes was transferred,
is much lower than that of a pipe,
and only one file descriptor is
required (versus the two required for a pipe).
-.PP
+.P
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)
.\" or eventually syslets/threadlets
to signal to a file descriptor that some operation is complete.
-.PP
+.P
A key point about an eventfd file descriptor is that it can be
monitored just like any other file descriptor using
.BR select (2),
.BR poll (2),
or
.BR epoll (7).)
-.PP
+.P
The current value of an eventfd counter can be viewed
via the entry for the corresponding file descriptor in the process's
.IR /proc/ pid /fdinfo
command-line arguments to the eventfd file descriptor.
When the parent has finished sleeping,
it reads from the eventfd file descriptor.
-.PP
+.P
The following shell session shows a sample run of the program:
-.PP
+.P
.in +4n
.EX
.RB "$" " ./a.out 1 2 4 7 14"
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.BI "int execve(const char *" pathname ", char *const _Nullable " argv [],
.BI " char *const _Nullable " envp []);
.fi
This causes the program that is currently being run by the calling process
to be replaced with a new program, with newly initialized stack, heap,
and (initialized and uninitialized) data segments.
-.PP
+.P
\fIpathname\fP must be either a binary executable, or a script
starting with a line of the form:
-.PP
+.P
.in +4n
.EX
\fB#!\fP\fIinterpreter \fP[optional-arg]
.EE
.in
-.PP
+.P
For details of the latter case, see "Interpreter scripts" below.
-.PP
+.P
.I argv
is an array of pointers to strings passed to the new program
as its command-line arguments.
(Thus, in the new program,
.I argv[argc]
will be NULL.)
-.PP
+.P
.I envp
is an array of pointers to strings, conventionally of the form
.BR key=value ,
The
.I envp
array must be terminated by a NULL pointer.
-.PP
+.P
This manual page describes the Linux system call in detail;
for an overview of the nomenclature and the many, often preferable,
standardised variants of this function provided by libc,
.B PATH
environment variable, see
.BR exec (3).
-.PP
+.P
The argument vector and environment can be accessed by the
new program's main function, when it is defined as:
-.PP
+.P
.in +4n
.EX
int main(int argc, char *argv[], char *envp[])
.EE
.in
-.PP
+.P
Note, however, that the use of a third argument to the main function
is not specified in POSIX.1;
according to POSIX.1,
the environment should be accessed via the external variable
.BR environ (7).
-.PP
+.P
.BR execve ()
does not return on success, and the text, initialized data,
uninitialized data (bss), and stack of the calling process are overwritten
according to the contents of the newly loaded program.
-.PP
+.P
If the current program is being ptraced, a \fBSIGTRAP\fP signal is sent to it
after a successful
.BR execve ().
-.PP
+.P
If the set-user-ID bit is set on the program file referred to by
\fIpathname\fP,
then the effective user ID of the calling process is changed
Similarly, if the set-group-ID bit is set on the program file,
then the effective group ID of the calling
process is set to the group of the program file.
-.PP
+.P
The aforementioned transformations of the effective IDs are
.I not
performed (i.e., the set-user-ID and set-group-ID bits are ignored)
or
.IP \[bu]
the calling process is being ptraced.
-.PP
+.P
The capabilities of the program file (see
.BR capabilities (7))
are also ignored if any of the above are true.
-.PP
+.P
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 mode bits.
-.PP
+.P
The process's real UID and real GID, as well as its supplementary group IDs,
are unchanged by a call to
.BR execve ().
-.PP
+.P
If the executable is an a.out dynamically linked
binary executable containing
shared-library stubs, the Linux dynamic linker
is called at the start of execution to bring
needed shared objects into memory
and link the executable with them.
-.PP
+.P
If the executable is a dynamically linked ELF executable, the
interpreter named in the PT_INTERP segment is used to load the needed
shared objects.
.IP \[bu]
The floating-point environment is reset to the default (see
.BR fenv (3)).
-.PP
+.P
The process attributes in the preceding list are all specified
in POSIX.1.
The following Linux-specific process attributes are also
.B CLONE_FILES
flag of
.BR clone (2).
-.PP
+.P
Note the following further points:
.IP \[bu] 3
All threads other than the calling thread are destroyed during an
.SS Interpreter scripts
An interpreter script is a text file that has execute
permission enabled and whose first line is of the form:
-.PP
+.P
.in +4n
.EX
\fB#!\fP\fIinterpreter \fP[optional-arg]
.EE
.in
-.PP
+.P
The
.I interpreter
must be a valid pathname for an executable file.
-.PP
+.P
If the
.I pathname
argument of
specifies an interpreter script, then
.I interpreter
will be invoked with the following arguments:
-.PP
+.P
.in +4n
.EX
\fIinterpreter\fP [optional-arg] \fIpathname\fP arg...
.EE
.in
-.PP
+.P
where
.I pathname
is the pathname of the file specified as the first argument of
.\" See the P - preserve-argv[0] option.
.\" Documentation/admin-guide/binfmt-misc.rst
.\" https://www.kernel.org/doc/html/latest/admin-guide/binfmt-misc.html
-.PP
+.P
For portable use,
.I optional-arg
should either be absent, or be specified as a single word (i.e., it
should not contain white space); see NOTES below.
-.PP
+.P
Since Linux 2.6.28,
.\" commit bf2a9a39639b8b51377905397a5005f444e9a892
the kernel permits the interpreter of a script to itself be a script.
.I <limits.h>
or available at run time using the call
.IR "sysconf(_SC_ARG_MAX)" ).
-.PP
+.P
Before Linux 2.6.23, the memory used to store the
environment and argument strings was limited to 32 pages
(defined by the kernel constant
.BR MAX_ARG_PAGES ).
On architectures with a 4-kB page size,
this yields a maximum size of 128\ kB.
-.PP
+.P
On Linux 2.6.23 and later, most architectures support a size limit
derived from the soft
.B RLIMIT_STACK
.SH VERSIONS
POSIX does not document the #! behavior, but it exists
(with some variations) on other UNIX systems.
-.PP
+.P
On Linux,
.I argv
and
.\" Bug filed 30 Apr 2007: http://bugzilla.kernel.org/show_bug.cgi?id=8408
.\" Bug rejected (because fix would constitute an ABI change).
.\"
-.PP
+.P
POSIX.1 says that values returned by
.BR sysconf (3)
should be invariant over the lifetime of a process.
Since Linux 5.1,
.\" commit 6eb3c3d0a52dca337e327ae8868ca1f44a712e02
the limit is 255 characters.
-.PP
+.P
The semantics of the
.I optional-arg
argument of an interpreter script vary across implementations.
and white spaces in
.I optional-arg
are used to delimit the arguments.
-.PP
+.P
Linux (like most other modern UNIX systems)
ignores the set-user-ID and set-group-ID bits on scripts.
.SH STANDARDS
.\" conditions EAGAIN, EINTR, ELIBACC, ENOLINK, EMULTIHOP; POSIX does not
.\" document ETXTBSY, EPERM, EFAULT, ELOOP, EIO, ENFILE, EMFILE, EINVAL,
.\" EISDIR or ELIBBAD error conditions.
-.PP
+.P
With UNIX\ V6, the argument list of an
.BR exec ()
call was ended by 0,
.BR execve ()
does is arrange for an existing process (the calling process)
to execute a new program.
-.PP
+.P
Set-user-ID and set-group-ID processes can not be
.BR ptrace (2)d.
-.PP
+.P
The result of mounting a filesystem
.I nosuid
varies across Linux kernel versions:
some will just ignore the set-user-ID and set-group-ID bits and
.BR exec ()
successfully.
-.PP
+.P
In most cases where
.BR execve ()
fails, control returns to the original executable image,
error that can occur (since Linux 3.1) when calling
.BR execve ()
is as follows.
-.PP
+.P
The
.B EAGAIN
error can occur when a
.\" commit 909cc4ae86f3380152a18e2a3c44523893ee11c4
the resource limit was not imposed on processes that
changed their user IDs.)
-.PP
+.P
Since Linux 3.1, the scenario just described no longer causes the
.BR set*uid ()
call to fail,
.BR set*uid ()
+
.BR execve ().
-.PP
+.P
If the resource limit was not still exceeded at the time of the
.BR execve ()
call
.SH EXAMPLES
The following program is designed to be execed by the second program below.
It just echoes its command-line arguments, one per line.
-.PP
+.P
.in +4n
.\" SRC BEGIN (myecho.c)
.EX
.EE
.\" SRC END
.in
-.PP
+.P
This program can be used to exec the program named in its command-line
argument:
-.PP
+.P
.in +4n
.\" SRC BEGIN (execve.c)
.EX
.EE
.\" SRC END
.in
-.PP
+.P
We can use the second program to exec the first as follows:
-.PP
+.P
.in +4n
.EX
.RB "$" " cc myecho.c \-o myecho"
argv[2]: world
.EE
.in
-.PP
+.P
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
.I myecho
program:
-.PP
+.P
.in +4n
.EX
.RB "$" " cat > script"
.RB "$" " chmod +x script"
.EE
.in
-.PP
+.P
We can then use our program to exec the script:
-.PP
+.P
.in +4n
.EX
.RB "$" " ./execve ./script"
.nf
.BR "#include <linux/fcntl.h>" " /* Definition of " AT_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "int execveat(int " dirfd ", const char *" pathname ,
.BI " char *const _Nullable " argv [],
.BI " char *const _Nullable " envp [],
It operates in exactly the same way as
.BR execve (2),
except for the differences described in this manual page.
-.PP
+.P
If the pathname given in
.I pathname
is relative, then it is interpreted relative to the directory
the calling process, as is done by
.BR execve (2)
for a relative pathname).
-.PP
+.P
If
.I pathname
is relative and
is interpreted relative to the current working
directory of the calling process (like
.BR execve (2)).
-.PP
+.P
If
.I pathname
is absolute, then
.I dirfd
is ignored.
-.PP
+.P
If
.I pathname
is an empty string and the
specifies the file to be executed (i.e.,
.I dirfd
refers to an executable file, rather than a directory).
-.PP
+.P
The
.I flags
argument is a bit mask that can include zero or more of the following flags:
to be implemented on systems that do not have the
.I /proc
filesystem mounted.
-.PP
+.P
When asked to execute a script file, the
.I argv[0]
that is passed to the script interpreter is a string of the form
.I P
is the value given in
.IR pathname .
-.PP
+.P
For the same reasons described in
.BR fexecve (3),
the natural idiom when using
.B ENOENT
error described above means that it is not possible to set the
close-on-exec flag on the file descriptor given to a call of the form:
-.PP
+.P
.in +4n
.EX
execveat(fd, "", argv, envp, AT_EMPTY_PATH);
.EE
.in
-.PP
+.P
However, the inability to set the close-on-exec flag means that a file
descriptor referring to the script leaks through to the script itself.
As well as wasting a file descriptor,
.nf
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "[[noreturn]] void syscall(SYS_exit_group, int " status );
.fi
-.PP
+.P
.IR Note :
glibc provides no wrapper for
.BR exit_group (),
.nf
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <fcntl.h>
-.PP
+.P
.BI "int fallocate(int " fd ", int " mode ", off_t " offset \
", off_t " len ");"
.fi
For the portable, POSIX.1-specified method of ensuring that space
is allocated for a file, see
.BR posix_fallocate (3).
-.PP
+.P
.BR fallocate ()
allows the caller to directly manipulate the allocated disk space
for the file referred to by
and continuing for
.I len
bytes.
-.PP
+.P
The
.I mode
argument determines the operation to be performed on the given range.
.BR posix_fallocate (3)
library function,
and is intended as a method of optimally implementing that function.
-.PP
+.P
After a successful call, subsequent writes into the range specified by
.I offset
and
.I len
are guaranteed not to fail because of lack of disk space.
-.PP
+.P
If the
.B FALLOC_FL_KEEP_SIZE
flag is specified in
is greater than the file size.
Preallocating zeroed blocks beyond the end of the file in this manner
is useful for optimizing append workloads.
-.PP
+.P
If the
.B FALLOC_FL_UNSHARE_RANGE
flag is specified in
Typically, this will be done by performing a copy-on-write operation on
all shared data in the file.
This flag may not be supported by all filesystems.
-.PP
+.P
Because allocation is done in block size chunks,
.BR fallocate ()
may allocate a larger range of disk space than was specified.
and whole filesystem blocks are removed from the file.
After a successful call,
subsequent reads from this range will return zeros.
-.PP
+.P
The
.B FALLOC_FL_PUNCH_HOLE
flag must be ORed with
(as reported by
.BR stat (2))
does not change.
-.PP
+.P
Not all filesystems support
.BR FALLOC_FL_PUNCH_HOLE ;
if a filesystem doesn't support the operation, an error is returned.
and the file will be
.I len
bytes smaller.
-.PP
+.P
A filesystem may place limitations on the granularity of the operation,
in order to ensure efficient implementation.
Typically,
fails with the error
.B EINVAL
if this requirement is violated.
-.PP
+.P
If the region specified by
.I offset
plus
instead, use
.BR ftruncate (2)
to truncate a file.
-.PP
+.P
No other flags may be specified in
.I mode
in conjunction with
.BR FALLOC_FL_COLLAPSE_RANGE .
-.PP
+.P
As at Linux 3.15,
.B FALLOC_FL_COLLAPSE_RANGE
is supported by
that span the holes in the file.
After a successful call, subsequent
reads from this range will return zeros.
-.PP
+.P
Zeroing is done within the filesystem preferably by converting the range into
unwritten extents.
This approach means that the specified range will not be physically zeroed
out on the device (except for partial blocks at the either end of the range),
and I/O is (otherwise) required only to update metadata.
-.PP
+.P
If the
.B FALLOC_FL_KEEP_SIZE
flag is additionally specified in
This behavior is the same as when preallocating space with
.B FALLOC_FL_KEEP_SIZE
specified.
-.PP
+.P
Not all filesystems support
.BR FALLOC_FL_ZERO_RANGE ;
if a filesystem doesn't support the operation, an error is returned.
Inserting a hole inside a file increases the file size by
.I len
bytes.
-.PP
+.P
This mode has the same limitations as
.B FALLOC_FL_COLLAPSE_RANGE
regarding the granularity of the operation.
For such operations (i.e., inserting a hole at the end of file),
.BR ftruncate (2)
should be used.
-.PP
+.P
No other flags may be specified in
.I mode
in conjunction with
.BR FALLOC_FL_INSERT_RANGE .
-.PP
+.P
.B FALLOC_FL_INSERT_RANGE
requires filesystem support.
Filesystems that support this operation include
.nf
.BR "#include <fcntl.h>" " /* Definition of " O_* " constants */"
.B #include <sys/fanotify.h>
-.PP
+.P
.BI "int fanotify_init(unsigned int " flags ", unsigned int " event_f_flags );
.fi
.SH DESCRIPTION
For an overview of the fanotify API, see
.BR fanotify (7).
-.PP
+.P
.BR fanotify_init ()
initializes a new fanotify group and returns a file descriptor for the event
queue associated with the group.
-.PP
+.P
The file descriptor is used in calls to
.BR fanotify_mark (2)
to specify the files, directories, mounts, or filesystems for which fanotify
another application is permitted to access a file or directory.
Permission to access filesystem objects is granted by writing to the file
descriptor.
-.PP
+.P
Multiple programs may be using the fanotify interface at the same time to
monitor the same files.
-.PP
+.P
The number of fanotify groups per user is limited.
See
.BR fanotify (7)
for details about this limit.
-.PP
+.P
The
.I flags
argument contains a multi-bit field defining the notification class of the
listening application and further single bit fields specifying the behavior
of the file descriptor.
-.PP
+.P
If multiple listeners for permission events exist,
the notification class is used to establish the sequence
in which the listeners receive the events.
-.PP
+.P
Only one of the following notification classes may be specified in
.IR flags :
.TP
This value only allows the receipt of events notifying that a file has been
accessed.
Permission decisions before the file is accessed are not possible.
-.PP
+.P
Listeners with different notification classes will receive events in the
order
.BR FAN_CLASS_PRE_CONTENT ,
.BR FAN_CLASS_NOTIF .
The order of notification for listeners in the same notification class
is undefined.
-.PP
+.P
The following bits can additionally be set in
.IR flags :
.TP
For more details on information records,
see
.BR fanotify (7).
-.PP
+.P
The
.I event_f_flags
argument
.TP
.B O_RDWR
This value allows read and write access.
-.PP
+.P
Additional bits can be set in
.IR event_f_flags .
The most useful values are:
flag in
.BR open (2)
for reasons why this may be useful.
-.PP
+.P
The following are also allowable:
.BR O_APPEND ,
.BR O_DSYNC ,
.B O_CLOEXEC
is ignored when passed in
.IR event_f_flags .
-.PP
+.P
The following bug was present before Linux 3.14:
.IP \[bu] 3
.\" Fixed by commit 48149e9d3a7e924010a0daab30a6197b7d7b6580
.SH SYNOPSIS
.nf
.B #include <sys/fanotify.h>
-.PP
+.P
.BI "int fanotify_mark(int " fanotify_fd ", unsigned int " flags ,
.BI " uint64_t " mask ", int " dirfd ,
.BI " const char *_Nullable " pathname );
.SH DESCRIPTION
For an overview of the fanotify API, see
.BR fanotify (7).
-.PP
+.P
.BR fanotify_mark ()
adds, removes, or modifies an fanotify mark on a filesystem object.
The caller must have read permission on the filesystem object that
is to be marked.
-.PP
+.P
The
.I fanotify_fd
argument is a file descriptor returned by
.BR fanotify_init (2).
-.PP
+.P
.I flags
is a bit mask describing the modification to perform.
It must include exactly one of the following values:
.BR FAN_MARK_FLUSH .
.I mask
is ignored.
-.PP
+.P
If none of the values above is specified, or more than one is specified,
the call fails with the error
.BR EINVAL .
-.PP
+.P
In addition,
zero or more of the following values may be ORed into
.IR flags :
the listener sets a mark with an ignore mask on the directory.
Evictable inode marks allow using this method for a large number of directories
without the concern of pinning all inodes and exhausting the system's memory.
-.PP
+.P
.I mask
defines which events shall be listened for (or which shall be ignored).
It is a bit mask composed of the following values:
are not generated for children of marked directories.
To monitor complete directory trees it is necessary to mark the relevant
mount or filesystem.
-.PP
+.P
The following composed values are defined:
.TP
.B FAN_CLOSE
.B FAN_MOVE
A file or directory has been moved
.RB ( FAN_MOVED_FROM | FAN_MOVED_TO ).
-.PP
+.P
The filesystem object to be marked is determined by the file descriptor
.I dirfd
and the pathname specified in
.BR uselib (2).
Events of these types will not be raised in the situation where an
interpreter is passed (or reads) a file for interpretation.
-.PP
+.P
Additionally, if a mark has also been placed on the Linux dynamic
linker, a user should also expect to receive an event for it when
an ELF object has been successfully opened using
.BR execve (2)
or
.BR execveat (2).
-.PP
+.P
For example, if the following ELF binary were to be invoked and a
.B FAN_OPEN_EXEC
mark has been placed on /:
-.PP
+.P
.in +4n
.EX
$ /bin/echo foo
.EE
.in
-.PP
+.P
The listening application in this case would receive
.B FAN_OPEN_EXEC
events for both the ELF binary and interpreter, respectively:
-.PP
+.P
.in +4n
.EX
/bin/echo
.SH SYNOPSIS
.nf
.B #include <fcntl.h>
-.PP
+.P
.BI "int fcntl(int " fd ", int " cmd ", ... /* " arg " */ );"
.fi
.SH DESCRIPTION
.IR fd .
The operation is determined by
.IR cmd .
-.PP
+.P
.BR fcntl ()
can take an optional third argument.
Whether or not this argument is required is determined by
or
.I void
is specified if the argument is not required.
-.PP
+.P
Certain of the operations below are supported only since a particular
Linux kernel version.
The preferred method of checking whether the host kernel supports
.BR F_SETFD " (\fIint\fP)"
Set the file descriptor flags to the value specified by
.IR arg .
-.PP
+.P
In multithreaded programs, using
.BR fcntl ()
.B F_SETFD
.BR fork (2),
etc.) refer to the same open file description, and thus
share the same file status flags.
-.PP
+.P
The file status flags and their semantics are described in
.BR open (2).
.TP
as standardized by POSIX.
For a Linux-specific alternative with better semantics,
see the discussion of open file description locks below.
-.PP
+.P
.BR F_SETLK ,
.BR F_SETLKW ,
and
.IR lock ,
is a pointer to a structure that has at least the following fields
(in unspecified order).
-.PP
+.P
.in +4n
.EX
struct flock {
};
.EE
.in
-.PP
+.P
The
.IR 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.
-.PP
+.P
.I l_start
is the starting offset for the lock, and is interpreted
relative to either:
.I l_start
can be a negative number provided the
offset does not lie before the start of the file.
-.PP
+.P
.I l_len
specifies the number of bytes to be locked.
If
location specified by
.IR l_whence " and " l_start
through to the end of file, no matter how large the file grows.
-.PP
+.P
POSIX.1-2001 allows (but does not require)
an implementation to support a negative
.I l_len
up to and including
.IR l_start \-1.
This is supported since Linux 2.4.21 and Linux 2.5.49.
-.PP
+.P
The
.I l_type
field can be used to place a read
is set to \-1.
Note that the returned information
may already be out of date by the time the caller inspects it.
-.PP
+.P
In order to place a read lock,
.I fd
must be open for reading.
.I fd
must be open for writing.
To place both types of lock, open a file read-write.
-.PP
+.P
When placing locks with
.BR F_SETLKW ,
the kernel detects
Circular deadlocks involving more than two processes are also detected.
Note, however, that there are limitations to the kernel's
deadlock-detection algorithm; see BUGS.
-.PP
+.P
As well as being removed by an explicit
.BR F_UNLCK ,
record locks are automatically released when the process terminates.
-.PP
+.P
Record locks are not inherited by a child created via
.BR fork (2),
but are preserved across an
.BR execve (2).
-.PP
+.P
Because of the buffering performed by the
.BR stdio (3)
library, the use of record locking with routines in that package
and
.BR write (2)
instead.
-.PP
+.P
The record locks described above are associated with the process
(unlike the open file description locks described below).
This has some unfortunate consequences:
In other words,
a multithreaded program can't use record locking to ensure
that threads don't simultaneously access the same region of a file.
-.PP
+.P
Open file description locks solve both of these problems.
.SS Open file description locks (non-POSIX)
Open file description locks are advisory byte-range locks whose operation is
to include this lock type in the next revision of POSIX.1.)
For an explanation of open file descriptions, see
.BR open (2).
-.PP
+.P
The principal difference between the two lock types
is that whereas traditional record locks
are associated with a process,
and are only automatically released on the last close
of the open file description,
instead of being released on any close of the file.
-.PP
+.P
Conflicting lock combinations
(i.e., a read lock and a write lock or two write locks)
where one lock is an open file description lock and the other
is a traditional record lock conflict
even when they are acquired by the same process on the same file descriptor.
-.PP
+.P
Open file description locks placed via the same open file description
(i.e., via the same file descriptor,
or via a duplicate of the file descriptor created by
then the existing lock is converted to the new lock type.
(Such conversions may result in splitting, shrinking, or coalescing with
an existing lock as discussed above.)
-.PP
+.P
On the other hand, open file description locks may conflict with
each other when they are acquired via different open file descriptions.
Thus, the threads in a multithreaded program can use
by having each thread perform its own
.BR open (2)
on the file and applying locks via the resulting file descriptor.
-.PP
+.P
As with traditional advisory locks, the third argument to
.BR fcntl (),
.IR lock ,
.I l_pid
field of that structure must be set to zero
when using the commands described below.
-.PP
+.P
The commands for working with open file description locks are analogous
to those used with traditional locks:
.TP
.IR lock ,
as described above for
.BR F_GETLK .
-.PP
+.P
In the current implementation,
.\" commit 57b65325fe34ec4c917bc4e555144b4a94d9e1f7
no deadlock detection is performed for open file description locks.
governed by a configuration option
.RB ( CONFIG_MANDATORY_FILE_LOCKING ).
This feature is no longer supported at all in Linux 5.15 and above.
-.PP
+.P
By default, both traditional (process-associated) and open file description
record locks are advisory.
Advisory locks are not enforced and are useful only between
cooperating processes.
-.PP
+.P
Both lock types can also be mandatory.
Mandatory locks are enforced for all processes.
If a process tries to perform an incompatible access (e.g.,
.B O_NONBLOCK
flag is enabled, then the system call fails with the error
.BR EAGAIN .
-.PP
+.P
To make use of mandatory locks, mandatory locking must be enabled
both on the filesystem that contains the file to be locked,
and on the file itself.
.BR chmod (1)
and
.BR chmod (2)).
-.PP
+.P
Mandatory locking is not specified by POSIX.
Some other systems also support mandatory locking,
although the details of how to enable it vary across systems.
network partition (i.e., loss of network connectivity with the server)
which lasts long enough for the server to assume
that the client is no longer functioning.
-.PP
+.P
When the filesystem determines that a lock has been lost, future
.BR read (2)
or
Since Linux 3.12,
.\" commit ef1820f9be27b6ad158f433ab38002ab8131db4d
this happens at least for NFSv4 (including all minor versions).
-.PP
+.P
Some versions of UNIX send a signal
.RB ( SIGLOST )
in this circumstance.
and this signal is delivered to the entire
process rather than to a specific thread.
.\" See fs/fcntl.c::send_sigio_to_task() (2.4/2.6) sources -- MTK, Apr 05
-.PP
+.P
Using these mechanisms, a program can implement fully asynchronous I/O
without using
.BR select (2)
or
.BR poll (2)
most of the time.
-.PP
+.P
The use of
.B O_ASYNC
is specific to BSD and Linux.
.B F_UNLCK
Remove our lease from the file.
.RE
-.PP
+.P
Leases are associated with an open file description (see
.BR open (2)).
This means that duplicate file descriptors (created by, for example,
.B F_UNLCK
operation on any of these duplicate file descriptors, or when all
such file descriptors have been closed.
-.PP
+.P
Leases may be taken out only on regular files.
An unprivileged process may take out a lease only on a file whose
UID (owner) matches the filesystem UID of the process.
indicating, respectively, a read lease , a write lease, or no lease.
.I arg
is ignored.
-.PP
+.P
When a process (the "lease breaker") performs an
.BR open (2)
or
.I arg
as
.BR F_RDLCK .
-.PP
+.P
If the lease holder fails to downgrade or remove the lease within
the number of seconds specified in
.IR /proc/sys/fs/lease\-break\-time ,
then the kernel forcibly removes or downgrades the lease holder's lease.
-.PP
+.P
Once a lease break has been initiated,
.B F_GETLEASE
returns the target lease type (either
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.
-.PP
+.P
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.
-.PP
+.P
If the lease breaker's blocked
.BR open (2)
or
then the call immediately fails with the error
.BR EWOULDBLOCK ,
but the other steps still occur as described above.
-.PP
+.P
The default signal used to notify the lease holder is
.BR SIGIO ,
but this can be changed using the
.IR arg ,
which is a bit mask specified by ORing together zero or more of
the following bits:
-.PP
+.P
.RS
.PD 0
.TP
For an overview of file sealing, a discussion of its purpose,
and some code examples, see
.BR memfd_create (2).
-.PP
+.P
Currently,
file seals can be applied only to a file descriptor returned by
.BR memfd_create (2)
.BR fcntl ()
operations that operate on seals will return
.BR EINVAL .
-.PP
+.P
Seals are a property of an inode.
Thus, all open file descriptors referring to the same inode share
the same set of seals.
.I errno
is set to
.BR EINVAL .
-.PP
+.P
The following seals are available:
.TP
.B F_SEAL_SEAL
In this context, the term "write lifetime" means
the expected time the data will live on media, before
being overwritten or erased.
-.PP
+.P
An application may use the different hint values specified below to
separate writes into different write classes,
so that multiple users or applications running on a single storage back-end
However, there are no functional semantics implied by these flags,
and different I/O classes can use the write lifetime hints
in arbitrary ways, so long as the hints are used consistently.
-.PP
+.P
The following operations can be applied to the file descriptor,
.IR fd :
.TP
Sets the read/write hint value associated with the open file description
referred to by
.IR fd .
-.PP
+.P
If an open file description has not been assigned a read/write hint,
then it shall use the value assigned to the inode, if any.
-.PP
+.P
The following read/write
hints are valid since Linux 4.13:
.TP
is expected to have a lifetime longer than
data written with
.BR RWH_WRITE_LIFE_LONG .
-.PP
+.P
All the write-specific hints are relative to each other,
and no individual absolute meaning should be attributed to them.
.SH RETURN VALUE
.TP
All other commands
Zero.
-.PP
+.P
On error, \-1 is returned, and
.I errno
is set to indicate the error.
.BR F_SEAL_SEAL .
.SH STANDARDS
POSIX.1-2008.
-.PP
+.P
.BR F_GETOWN_EX ,
.BR F_SETOWN_EX ,
.BR F_SETPIPE_SZ ,
(Define the
.B _GNU_SOURCE
macro to obtain these definitions.)
-.\" .PP
+.\" .P
.\" SVr4 documents additional EIO, ENOLINK and EOVERFLOW error conditions.
-.PP
+.P
.BR F_OFD_SETLK ,
.BR F_OFD_SETLKW ,
and
.B _GNU_SOURCE
to obtain their definitions),
but work is being done to have them included in the next version of POSIX.1.
-.PP
+.P
.B F_ADD_SEALS
and
.B F_GET_SEALS
.\" FIXME . Once glibc adds support, add a note about FTM requirements
.SH HISTORY
SVr4, 4.3BSD, POSIX.1-2001.
-.PP
+.P
Only the operations
.BR F_DUPFD ,
.BR F_GETFD ,
and
.B F_SETLKW
are specified in POSIX.1-2001.
-.PP
+.P
.B F_GETOWN
and
.B F_SETOWN
with the value 500 or greater, or
.B _POSIX_C_SOURCE
with the value 200809L or greater.)
-.PP
+.P
.B F_DUPFD_CLOEXEC
is specified in POSIX.1-2008.
(To get this definition, define
.BR flock (2)
and
.BR fcntl ().
-.PP
+.P
Several systems have more fields in
.I "struct flock"
such as, for example,
may live on a different machine;
on Linux, while present on some architectures (such as MIPS32),
this field is not used.
-.PP
+.P
The original Linux
.BR fcntl ()
system call was not designed to handle large file offsets
This scenario potentially risks data corruption,
since another process might acquire a lock in the intervening period
and perform file I/O.
-.PP
+.P
Since Linux 3.12,
.\" commit ef1820f9be27b6ad158f433ab38002ab8131db4d
if an NFSv4 client loses contact with the server,
.BR capabilities (7),
.BR feature_test_macros (7),
.BR lslocks (8)
-.PP
+.P
.IR locks.txt ,
.IR mandatory\-locking.txt ,
and
.SH SYNOPSIS
.nf
.B #include <sys/file.h>
-.PP
+.P
.BI "int flock(int " fd ", int " operation );
.fi
.SH DESCRIPTION
.B LOCK_UN
Remove an existing lock held by this process.
.RE
-.PP
+.P
A call to
.BR flock ()
may block if an incompatible lock is held by another process.
.B LOCK_NB
(by ORing)
with any of the above operations.
-.PP
+.P
A single file may not simultaneously have both shared and exclusive locks.
-.PP
+.P
Locks created by
.BR flock ()
are associated with an open file description (see
.B LOCK_UN
operation on any of these duplicate file descriptors, or when all
such file descriptors have been closed.
-.PP
+.P
If a process uses
.BR open (2)
(or similar) to obtain more than one file descriptor for the same file,
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 file descriptor.
-.PP
+.P
A process may hold only one type of lock (shared or exclusive)
on a file.
Subsequent
.BR flock ()
calls on an already locked file will convert an existing lock to the new
lock mode.
-.PP
+.P
Locks created by
.BR flock ()
are preserved across an
.BR execve (2).
-.PP
+.P
A shared or exclusive lock can be placed on a file regardless of the
mode in which the file was opened.
.SH RETURN VALUE
.BR flock ()
is not propagated over SMB.
A file with such locks will not appear locked for remote clients.
-.PP
+.P
Since Linux 5.5,
.BR flock ()
locks are emulated with SMB byte-range locks on the entire file.
when done from a separate file descriptor.
This difference originates from the design of locks in the SMB protocol,
which provides mandatory locking semantics.
-.PP
+.P
Remote and mandatory locking semantics may vary with
SMB protocol, mount options and server type.
See
byte-range locking, which does work over NFS,
given a sufficiently recent version of
Linux and a server which supports locking.
-.PP
+.P
Since Linux 2.6.12, NFS clients support
.BR flock ()
locks by emulating them as
interact with one another over NFS.
It also means that in order to place an exclusive lock,
the file must be opened for writing.
-.PP
+.P
Since Linux 2.6.37,
.\" commit 5eebde23223aeb0ad2d9e3be6590ff8bbfab0fc2
the kernel supports a compatibility mode that allows
a process is free to ignore the use of
.BR flock ()
and perform I/O on the file.
-.PP
+.P
.BR flock ()
and
.BR fcntl (2)
the semantics of
.BR flock ()
will be different from those described in this manual page.
-.PP
+.P
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.
.BR open (2),
.BR lockf (3),
.BR lslocks (8)
-.PP
+.P
.I Documentation/filesystems/locks.txt
in the Linux kernel source tree
.RI ( Documentation/locks.txt
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.B pid_t fork(void);
.fi
.SH DESCRIPTION
The calling process is referred to as the
.I parent
process.
-.PP
+.P
The child process and the parent process run in separate memory spaces.
At the time of
.BR fork ()
and unmappings
.RB ( munmap (2))
performed by one of the processes do not affect the other.
-.PP
+.P
The child process is an exact duplicate of the parent
process except for the following points:
.IP \[bu] 3
.BR aio_write (3)),
nor does it inherit any asynchronous I/O contexts from its parent (see
.BR io_setup (2)).
-.PP
+.P
The process attributes in the preceding list are all specified
in POSIX.1.
The parent and child also differ with respect to the following
are not inherited by the child;
the child must turn on any bits that it requires using
.BR ioperm (2).
-.PP
+.P
Note the following further points:
.IP \[bu] 3
The child process is created with a single thread\[em]the
and
.BR wait (2)
for more examples.
-.PP
+.P
.\" SRC BEGIN (fork.c)
.EX
#include <signal.h>
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.BI "int fsync(int " fd );
-.PP
+.P
.BI "int fdatasync(int " fd );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.nf
.BR fsync ():
glibc 2.16 and later:
_BSD_SOURCE || _XOPEN_SOURCE
|| /* Since glibc 2.8: */ _POSIX_C_SOURCE >= 200112L
.fi
-.PP
+.P
.BR fdatasync ():
.nf
_POSIX_C_SOURCE >= 199309L || _XOPEN_SOURCE >= 500
is rebooted.
This includes writing through or flushing a disk cache if present.
The call blocks until the device reports that the transfer has completed.
-.PP
+.P
As well as flushing the file data,
.BR fsync ()
also flushes the metadata information associated with the file (see
.BR inode (7)).
-.PP
+.P
Calling
.BR fsync ()
does not necessarily ensure
For that an explicit
.BR fsync ()
on a file descriptor for the directory is also needed.
-.PP
+.P
.BR fdatasync ()
is similar to
.BR fsync (),
as made by say
.BR ftruncate (2)),
would require a metadata flush.
-.PP
+.P
The aim of
.BR fdatasync ()
is to reduce disk activity for applications that do not
POSIX.1-2008.
.SH HISTORY
POSIX.1-2001, 4.2BSD.
-.PP
+.P
In Linux 2.2 and earlier,
.BR fdatasync ()
is equivalent to
.BR fsync (),
and so has no performance advantage.
-.PP
+.P
The
.BR fsync ()
implementations in older kernels and lesser used filesystems
or
.BR sdparm (8)
to guarantee safe operation.
-.PP
+.P
Under AT&T UNIX System V Release 4
.I fd
needs to be opened for writing.
.RI ( libc ", " \-lc )
.SH SYNOPSIS
.nf
-.PP
+.P
.BR "#include <linux/futex.h>" " /* Definition of " FUTEX_* " constants */"
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "long syscall(SYS_futex, uint32_t *" uaddr ", int " futex_op \
", uint32_t " val ,
.BI " const struct timespec *" timeout , \
" \fR /* or: \fBuint32_t \fIval2\fP */"
.BI " uint32_t *" uaddr2 ", uint32_t " val3 );
.fi
-.PP
+.P
.IR Note :
glibc provides no wrapper for
.BR futex (),
.BR futex ()
operations can be used to wake any processes or threads waiting
for a particular condition.
-.PP
+.P
A futex is a 32-bit value\[em]referred to below as a
.IR "futex word" \[em]whose
address is supplied to the
but these addresses all refer to the same location in physical memory.)
In a multithreaded program, it is sufficient to place the futex word
in a global variable shared by all threads.
-.PP
+.P
When executing a futex operation that requests to block a thread,
the kernel will block only if the futex word has the value that the
calling thread supplied (as one of the arguments of the
.\" the reference in the following sentence
.\" See NOTES for a detailed specification of
.\" the synchronization semantics.
-.PP
+.P
One use of futexes is for implementing locks.
The state of the lock (i.e., acquired or not acquired)
can be represented as an atomically accessed flag in shared memory.
See
.BR futex (7)
for more detail on how to use futexes.
-.PP
+.P
Besides the basic wait and wake-up futex functionality, there are further
futex operations aimed at supporting more complex use cases.
-.PP
+.P
Note that
no explicit initialization or destruction is necessary to use futexes;
the kernel maintains a futex
.I val
is a value whose meaning and purpose depends on
.IR futex_op .
-.PP
+.P
The remaining arguments
.RI ( timeout ,
.IR uaddr2 ,
.IR val3 )
are required only for certain of the futex operations described below.
Where one of these arguments is not required, it is ignored.
-.PP
+.P
For several blocking operations, the
.I timeout
argument is a pointer to a
and in the remainder of this page, this argument is referred to as
.I val2
when interpreted in this fashion.
-.PP
+.P
Where it is required, the
.I uaddr2
argument is a pointer to a second futex word that is employed
by the operation.
-.PP
+.P
The interpretation of the final integer argument,
.IR val3 ,
depends on the operation.
against the
.B CLOCK_MONOTONIC
clock.
-.PP
+.P
The operation specified in
.I futex_op
is one of the following:
the low-priority task from the CPU.
Consequently, the low-priority task makes no progress toward
releasing the lock, and the high-priority task remains blocked.
-.PP
+.P
Priority inheritance is a mechanism for dealing with
the priority-inversion problem.
With this mechanism, when a high-priority task becomes blocked
then both of those tasks
(or more generally, all of the tasks in a lock chain)
have their priorities raised to be the same as the high-priority task.
-.PP
+.P
From a user-space perspective,
what makes a futex PI-aware is a policy agreement (described below)
between user space and the kernel about the value of the futex word,
.\" talk about a PI aware pthread_mutex, than a PI aware futex, since
.\" there is a lot of policy and scaffolding that has to be built up
.\" around it to use it properly (this is what a PI pthread_mutex is).
-.PP
+.P
.\" mtk: The following text is drawn from the Hart/Guniguntala paper
.\" (listed in SEE ALSO), but I have reworded some pieces
.\" significantly.
(Note that is invalid for a PI futex word to have no owner and
.B FUTEX_WAITERS
set.)
-.PP
+.P
With this policy in place,
a user-space application can acquire an unacquired
lock or release a lock using atomic instructions executed in user mode
set the futex word's value to the caller's TID if its previous value was 0.
Releasing a lock requires using compare-and-swap to set the futex word's
value to 0 if the previous value was the expected TID.
-.PP
+.P
If a futex is already acquired (i.e., has a nonzero value),
waiters must employ the
.B FUTEX_LOCK_PI
in this case, the lock owner must employ the
.B FUTEX_UNLOCK_PI
operation to release the lock.
-.PP
+.P
In the cases where callers are forced into the kernel
(i.e., required to perform a
.BR futex ()
priority-inheritance semantics.
After the RT-mutex is acquired, the futex value is updated accordingly,
before the calling thread returns to user space.
-.PP
+.P
It is important to note
.\" tglx (July 2015):
.\" If there are multiple waiters on a pi futex then a wake pi operation
or having waiters but not having the
.B FUTEX_WAITERS
bit set.)
-.PP
+.P
If a futex has an associated RT-mutex in the kernel
(i.e., there are blocked waiters)
and the owner of the futex/RT-mutex dies unexpectedly,
.\" mechanism. In that case the futex value will be set to
.\" FUTEX_OWNER_DIED. The robust futex mechanism is also available for non
.\" PI futexes.
-.PP
+.P
PI futexes are operated on by specifying one of the values listed below in
.IR futex_op .
Note that the PI futex operations must be used as paired operations
(or the error
.B EINVAL
results).
-.PP
+.P
The PI futex operations are as follows:
.\"
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
all operations return \-1 and set
.I errno
to indicate the error.
-.PP
+.P
The return value on success depends on the operation,
as described in the following list:
.TP
Linux.
.SH HISTORY
Linux 2.6.0.
-.PP
+.P
Initial futex support was merged in Linux 2.5.7 but with different
semantics from what was described above.
A four-argument system call with the semantics
messages to the terminal and employ a synchronization protocol
that ensures that they alternate in writing messages.
Upon running this program we see output such as the following:
-.PP
+.P
.in +4n
.EX
$ \fB./futex_demo\fP
.BR pthread_mutexattr_getprotocol (3),
.BR futex (7),
.BR sched (7)
-.PP
+.P
The following kernel source files:
.IP \[bu] 3
.I Documentation/pi\-futex.txt
.I Documentation/locking/rt\-mutex\-design.txt
.IP \[bu]
.I Documentation/robust\-futex\-ABI.txt
-.PP
+.P
Franke, H., Russell, R., and Kirwood, M., 2002.
\fIFuss, Futexes and Furwocks: Fast Userlevel Locking in Linux\fP
(from proceedings of the Ottawa Linux Symposium 2002),
.br
.UR http://kernel.org\:/doc\:/ols\:/2002\:/ols2002\-pages\-479\-495.pdf
.UE
-.PP
+.P
Hart, D., 2009. \fIA futex overview and update\fP,
.UR http://lwn.net/Articles/360699/
.UE
-.PP
+.P
Hart, D.\& and Guniguntala, D., 2009.
\fIRequeue-PI: Making glibc Condvars PI-Aware\fP
(from proceedings of the 2009 Real-Time Linux Workshop),
.UR http://lwn.net/images/conf/rtlws11/papers/proc/p10.pdf
.UE
-.PP
+.P
Drepper, U., 2011. \fIFutexes Are Tricky\fP,
.UR http://www.akkadia.org/drepper/futex.pdf
.UE
-.PP
+.P
Futex example library, futex\-*.tar.bz2 at
.br
.UR https://mirrors.kernel.org\:/pub\:/linux\:/kernel\:/people\:/rusty/
.nf
.BR "#include <fcntl.h>" " /* Definition of " AT_* " constants */"
.B #include <sys/time.h>
-.PP
+.P
.BI "[[deprecated]] int futimesat(int " dirfd ", const char *" pathname ,
.BI " const struct timeval " times [2]);
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR futimesat ():
.nf
_GNU_SOURCE
Use
.BR utimensat (2)
instead.
-.PP
+.P
The
.BR futimesat ()
system call operates in exactly the same way as
.BR utimes (2),
except for the differences described in this manual page.
-.PP
+.P
If the pathname given in
.I pathname
is relative, then it is interpreted relative to the directory
the calling process, as is done by
.BR utimes (2)
for a relative pathname).
-.PP
+.P
If
.I pathname
is relative and
is interpreted relative to the current working
directory of the calling process (like
.BR utimes (2)).
-.PP
+.P
If
.I pathname
is absolute, then
.SH HISTORY
Linux 2.6.16,
glibc 2.4.
-.PP
+.P
It was implemented from a specification that was proposed for POSIX.1,
but that specification was replaced by the one for
.BR utimensat (2).
-.PP
+.P
A similar system call exists on Solaris.
.SH NOTES
.SH SEE ALSO
.SH SYNOPSIS
.nf
.B #include <linux/module.h>
-.PP
+.P
.BI "[[deprecated]] int get_kernel_syms(struct kernel_sym *" table );
.fi
.SH DESCRIPTION
.BR Note :
This system call is present only before Linux 2.6.
-.PP
+.P
If
.I table
is NULL,
.BR get_kernel_syms ()
returns the number of symbols available for query.
Otherwise, it fills in a table of structures:
-.PP
+.P
.in +4n
.EX
struct kernel_sym {
};
.EE
.in
-.PP
+.P
The symbols are interspersed with magic symbols of the form
.BI # module-name
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.
-.PP
+.P
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.
.SH HISTORY
Removed in Linux 2.6.
.\" Removed in Linux 2.5.48
-.PP
+.P
This obsolete system call is not supported by glibc.
No declaration is provided in glibc headers, but, through a quirk of history,
glibc versions before glibc 2.23 did export an ABI for this system call.
.IR table .
If symbols have been added to the kernel since the
program queried for the symbol table size, memory will be corrupted.
-.PP
+.P
The length of exported symbol names is limited to 59 characters.
-.PP
+.P
Because of these limitations, this system call is deprecated in
favor of
.BR query_module (2)
.SH SYNOPSIS
.B "#include <numaif.h>"
.nf
-.PP
+.P
.BI "long get_mempolicy(int *" mode ,
.BI " unsigned long " nodemask [(. maxnode " + ULONG_WIDTH - 1)"
.B " / ULONG_WIDTH],"
retrieves the NUMA policy of the calling thread or of a memory address,
depending on the setting of
.IR flags .
-.PP
+.P
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 thread.
-.PP
+.P
If
.I flags
is specified as 0,
is 0,
.I addr
must be specified as NULL.
-.PP
+.P
If
.I flags
specifies
.B MPOL_F_ADDR
or
.BR MPOL_F_NODE .
-.PP
+.P
If
.I flags
specifies
.BR numa (3)
has been used to establish a policy for the memory range containing
.IR addr .
-.PP
+.P
If the
.I mode
argument is not NULL, then
.I maxnode
is always rounded to a multiple of
.IR "sizeof(unsigned\ long)*8" .
-.PP
+.P
If
.I flags
specifies both
will allocate a page as if the thread had performed a read
(load) access to that address, and return the ID of the node
where that page was allocated.
-.PP
+.P
If
.I flags
specifies
flag for read accesses, and in memory ranges mapped with the
.B MAP_SHARED
flag for all accesses.
-.PP
+.P
Other flag values are reserved.
-.PP
+.P
For an overview of the possible policies see
.BR set_mempolicy (2).
.SH RETURN VALUE
" /* Definition of " "struct robust_list_head" " */"
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "long syscall(SYS_get_robust_list, int " pid ,
.BI " struct robust_list_head **" head_ptr ", size_t *" len_ptr );
.B long syscall(SYS_set_robust_list,
.BI " struct robust_list_head *" head ", size_t " len );
.fi
-.PP
+.P
.IR Note :
glibc provides no wrappers for these system calls,
necessitating the use of
.BR set_robust_list ().
The address of a thread's robust futex list can be obtained using
.BR get_robust_list ().
-.PP
+.P
The purpose of the robust futex list is to ensure that if a thread
accidentally fails to unlock a futex before terminating or calling
.BR execve (2),
.BR futex (2)
.B FUTEX_WAKE
operation on one of the threads waiting on the futex.
-.PP
+.P
The
.BR get_robust_list ()
system call returns the head of the robust futex list of the thread
.I **head_ptr
is stored in
.IR len_ptr .
-.PP
+.P
Permission to employ
.BR get_robust_list ()
is governed by a ptrace access mode
.B PTRACE_MODE_READ_REALCREDS
check; see
.BR ptrace (2).
-.PP
+.P
The
.BR set_robust_list ()
system call requests the kernel to record the head of the list of
.I len
does not equal
.IR "sizeof(struct\ robust_list_head)" .
-.PP
+.P
The
.BR get_robust_list ()
system call can fail with the following errors:
These system calls were added in Linux 2.6.17.
.SH NOTES
These system calls are not needed by normal applications.
-.PP
+.P
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.
-.PP
+.P
In the initial implementation,
a thread waiting on a futex was notified that the owner had died
only if the owner terminated.
.\" commit 8141c7f3e7aee618312fa1c15109e1219de784a7
notification was extended to include the case where the owner performs an
.BR execve (2).
-.PP
+.P
The thread IDs mentioned in the main text are
.I kernel
thread IDs of the kind returned by
.SH SEE ALSO
.BR futex (2),
.BR pthread_mutexattr_setrobust (3)
-.PP
+.P
.I Documentation/robust\-futexes.txt
and
.I Documentation/robust\-futex\-ABI.txt
.nf
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <sched.h>
-.PP
+.P
.BI "int getcpu(unsigned int *_Nullable " cpu ", \
unsigned int *_Nullable " node );
.fi
or
.I node
is NULL nothing is written to the respective pointer.
-.PP
+.P
The information placed in
.I cpu
is guaranteed to be current only at the time of the call:
.\"
.SS C library/kernel differences
The kernel system call has a third argument:
-.PP
+.P
.in +4n
.nf
.BI "int getcpu(unsigned int *" cpu ", unsigned int *" node ,
.BI " struct getcpu_cache *" tcache );
.fi
.in
-.PP
+.P
The
.I tcache
argument is unused since Linux 2.6.24,
and (when invoking the system call directly)
should be specified as NULL,
unless portability to Linux 2.6.23 or earlier is required.
-.PP
+.P
.\" commit 4307d1e5ada595c87f9a4d16db16ba5edb70dcb1
.\" Author: Ingo Molnar <mingo@elte.hu>
.\" Date: Wed Nov 7 18:37:48 2007 +0100
.nf
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "long syscall(SYS_getdents, unsigned int " fd \
", struct linux_dirent *" dirp ,
.BI " unsigned int " count );
-.PP
+.P
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <dirent.h>
-.PP
+.P
.BI "ssize_t getdents64(int " fd ", void " dirp [. count "], size_t " count );
.fi
-.PP
+.P
.IR Note :
glibc provides no wrapper for
.BR getdents (),
necessitating the use of
.BR syscall (2).
-.PP
+.P
.IR Note :
There is no definition of
.I struct linux_dirent
The argument
.I count
specifies the size of that buffer.
-.PP
+.P
The
.I linux_dirent
structure is declared as follows:
-.PP
+.P
.in +4n
.EX
struct linux_dirent {
}
.EE
.in
-.PP
+.P
.I d_ino
is an inode number.
.I d_off
.IR linux_dirent .
.I d_name
is a null-terminated filename.
-.PP
+.P
.I 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
.TP
.B DT_UNKNOWN
The file type is unknown.
-.PP
+.P
The
.I d_type
field is implemented since Linux 2.6.4.
Thus, on kernels up to and including Linux 2.6.3,
attempting to access this field always provides the value 0
.RB ( DT_UNKNOWN ).
-.PP
+.P
Currently,
.\" kernel 2.6.27
.\" The same sentence is in readdir.2
supports an explicit
.I d_type
field.
-.PP
+.P
The
.BR getdents64 ()
system call is like
.BR getdents (),
except that its second argument is a pointer to a buffer containing
structures of the following type:
-.PP
+.P
.in +4n
.EX
struct linux_dirent64 {
or
.I linux_dirent64
structure yourself.
-.PP
+.P
Probably, you want to use
.BR readdir (3)
instead of these system calls.
-.PP
+.P
These calls supersede
.BR readdir (2).
.SH EXAMPLES
.BR getdents ().
The following output shows an example of what we see when running this
program on an ext2 directory:
-.PP
+.P
.in +4n
.EX
.RB "$" " ./a.out /testfs/"
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.BI "int getdomainname(char *" name ", size_t " len );
.BI "int setdomainname(const char *" name ", size_t " len );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR getdomainname (),
.BR setdomainname ():
.nf
host system.
More precisely, they operate on the NIS domain name associated with the calling
process's UTS namespace.
-.PP
+.P
.BR setdomainname ()
sets the domain name to the value given in the character array
.IR name .
(Thus,
.I name
does not require a terminating null byte.)
-.PP
+.P
.BR getdomainname ()
returns the null-terminated domain name in the character array
.IR name ,
.B CAP_SYS_ADMIN
capability in the user namespace associated with its UTS namespace (see
.BR namespaces (7)).
-.PP
+.P
.BR getdomainname ()
can fail with the following errors:
.TP
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.B gid_t getgid(void);
.B gid_t getegid(void);
.fi
.SH DESCRIPTION
.BR getgid ()
returns the real group ID of the calling process.
-.PP
+.P
.BR getegid ()
returns the effective group ID of the calling process.
.SH ERRORS
POSIX.1-2008.
.SH HISTORY
POSIX.1-2001, 4.3BSD.
-.PP
+.P
The original Linux
.BR getgid ()
and
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.BI "int getgroups(int " size ", gid_t " list []);
-.PP
+.P
.B #include <grp.h>
-.PP
+.P
.BI "int setgroups(size_t " size ", const gid_t *_Nullable " list );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR setgroups ():
.nf
Since glibc 2.19:
If the calling process is a member of more than
.I size
supplementary groups, then an error results.
-.PP
+.P
It is unspecified whether the effective group ID of the calling process
is included in the returned list.
(Thus, an application should also call
.BR getegid (2)
and add or remove the resulting value.)
-.PP
+.P
If
.I size
is zero,
.I list
to be used in a further call to
.BR getgroups ().
-.PP
+.P
.BR setgroups ()
sets the supplementary group IDs for the calling process.
Appropriate privileges are required (see the description of the
in the buffer pointed to by
.IR list .
A process can drop all of its supplementary groups with the call:
-.PP
+.P
.in +4n
.EX
setgroups(0, NULL);
On error, \-1 is returned, and
.I errno
is set to indicate the error.
-.PP
+.P
On success,
.BR setgroups ()
returns 0.
.B EFAULT
.I list
has an invalid address.
-.PP
+.P
.BR getgroups ()
can additionally fail with the following error:
.TP
.B EINVAL
.I size
is less than the number of supplementary group IDs, but is not zero.
-.PP
+.P
.BR setgroups ()
can additionally fail with the following errors:
.TP
Since
.BR setgroups ()
requires privilege, it is not covered by POSIX.1.
-.PP
+.P
The original Linux
.BR getgroups ()
system call supported only 16-bit group IDs.
The set of supplementary group IDs
is inherited from the parent process, and preserved across an
.BR execve (2).
-.PP
+.P
The maximum number of supplementary group IDs can be found at run time using
.BR sysconf (3):
-.PP
+.P
.in +4n
.EX
long ngroups_max;
ngroups_max = sysconf(_SC_NGROUPS_MAX);
.EE
.in
-.PP
+.P
The maximum return value of
.BR getgroups ()
cannot be larger than one more than this value.
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.BI "int gethostname(char *" name ", size_t " len );
.BI "int sethostname(const char *" name ", size_t " len );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR gethostname ():
.nf
_XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 200112L
.\" The above is something of a simplification
.\" also before glibc 2.3 there was a bit churn
.fi
-.PP
+.P
.BR sethostname ():
.nf
Since glibc 2.21:
These system calls are used to access or to change the system hostname.
More precisely, they operate on the hostname associated with the calling
process's UTS namespace.
-.PP
+.P
.BR sethostname ()
sets the hostname to the value given in the character array
.IR name .
(Thus,
.I name
does not require a terminating null byte.)
-.PP
+.P
.BR gethostname ()
returns the null-terminated hostname in the character array
.IR name ,
.BR gethostname ()
but not
.BR sethostname ().
-.PP
+.P
Versions of glibc before glibc 2.2
.\" At least glibc 2.0 and glibc 2.1, older versions not checked
handle the case where the length of the
.SH SYNOPSIS
.nf
.B #include <sys/time.h>
-.PP
+.P
.BI "int getitimer(int " which ", struct itimerval *" curr_value );
.BI "int setitimer(int " which ", const struct itimerval *restrict " new_value ,
.BI " struct itimerval *_Nullable restrict " old_value );
When a timer expires, a signal is generated for the calling process,
and the timer is reset to the specified interval
(if the interval is nonzero).
-.PP
+.P
Three types of timers\[em]specified via the
.I which
argument\[em]are provided,
.BR ITIMER_VIRTUAL ,
this timer can be used to profile user and system CPU time
consumed by the process.
-.PP
+.P
A process has only one of each of the three types of timers.
-.PP
+.P
Timer values are defined by the following structures:
-.PP
+.P
.in +4n
.EX
struct itimerval {
.I which
in the buffer pointed to by
.IR curr_value .
-.PP
+.P
The
.I it_value
substructure is populated with the amount of time remaining until
If both fields of
.I it_value
are zero, then this timer is currently disarmed (inactive).
-.PP
+.P
The
.I it_interval
substructure is populated with the timer interval.
the buffer it points to is used to return the previous value of the timer
(i.e., the same information that is returned by
.BR getitimer ()).
-.PP
+.P
If either field in
.I new_value.it_value
is nonzero,
If both fields in
.I new_value.it_value
are zero, then the timer is disarmed.
-.PP
+.P
The
.I new_value.it_interval
field specifies the new interval for the timer;
contains a value outside the range [0, 999999].
.SH VERSIONS
The standards are silent on the meaning of the call:
-.PP
+.P
.in +4n
.EX
setitimer(which, NULL, &old_value);
.EE
.in
-.PP
+.P
Many systems (Solaris, the BSDs, and perhaps others)
treat this as equivalent to:
-.PP
+.P
.in +4n
.EX
getitimer(which, &old_value);
.EE
.in
-.PP
+.P
In Linux, this is treated as being equivalent to a call in which the
.I new_value
fields are zero; that is, the timer is disabled.
If the timer expires while the process is active (always true for
.BR ITIMER_VIRTUAL ),
the signal will be delivered immediately when generated.
-.PP
+.P
A child created via
.BR fork (2)
does not inherit its parent's interval timers.
Interval timers are preserved across an
.BR execve (2).
-.PP
+.P
POSIX.1 leaves the
interaction between
.BR setitimer ()
timer may expire before the signal from a previous expiration
has been delivered.
The second signal in such an event will be lost.
-.PP
+.P
Before Linux 2.6.16, timer values are represented in jiffies.
If a request is made set a timer with a value whose jiffies
representation exceeds
Since Linux 2.6.16,
the kernel uses a different internal representation for times,
and this ceiling is removed.
-.PP
+.P
On certain systems (including i386),
Linux kernels before Linux 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 Linux 2.6.12.
.\" 4 Jul 2005: It looks like this bug may remain in Linux 2.4.x.
.\" http://lkml.org/lkml/2005/7/1/165
-.PP
+.P
POSIX.1-2001 says that
.BR setitimer ()
should fail if a
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.B int getpagesize(void);
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR getpagesize ():
.nf
Since glibc 2.20:
.I sysconf(_SC_PAGESIZE)
instead of
.BR getpagesize ():
-.PP
+.P
.in +4n
.EX
#include <unistd.h>
long sz = sysconf(_SC_PAGESIZE);
.EE
.in
-.PP
+.P
(Most systems allow the synonym
.B _SC_PAGE_SIZE
for
.BR _SC_PAGESIZE .)
-.PP
+.P
Whether
.BR getpagesize ()
is present as a Linux system call depends on the architecture.
.SH SYNOPSIS
.nf
.B #include <sys/socket.h>
-.PP
+.P
.BI "int getpeername(int " sockfd ", struct sockaddr *restrict " addr ,
.BI " socklen_t *restrict " addrlen );
.fi
.IR 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.
-.PP
+.P
The returned address is truncated if the buffer provided is too small;
in this case,
.I addrlen
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.B pid_t getpid(void);
.B pid_t getppid(void);
.fi
returns the process ID (PID) of the calling process.
(This is often used by
routines that generate unique temporary filenames.)
-.PP
+.P
.BR getppid ()
returns the process ID of the parent of the calling process.
This will be either the ID of the process that created this process using
.BR clone (2).)
Furthermore, the complexity of the caching code had been
the source of a few bugs within glibc over the years.
-.PP
+.P
Because of the aforementioned problems,
since glibc 2.25, the PID cache is removed:
.\" commit c579f48edba88380635ab98cb612030e3ed8691e
.BR pid_namespaces (7)),
.BR getppid ()
returns 0.
-.PP
+.P
From a kernel perspective,
the PID (which is shared by all of the threads in a multithreaded process)
is sometimes also known as the thread group ID (TGID).
.SH SYNOPSIS
.nf
.B #include <sys/resource.h>
-.PP
+.P
.BI "int getpriority(int " which ", id_t " who );
.BI "int setpriority(int " which ", id_t " who ", int " prio );
.fi
The process attribute dealt with by these system calls is
the same attribute (also known as the "nice" value) that is dealt with by
.BR nice (2).
-.PP
+.P
The value
.I which
is one of
.I who
denotes (respectively) the calling process, the process group of the
calling process, or the real user ID of the calling process.
-.PP
+.P
The
.I prio
argument is a value in the range \-20 to 19 (but see NOTES below),
are silently clamped to the range.
The default priority is 0;
lower values give a process a higher scheduling priority.
-.PP
+.P
The
.BR getpriority ()
call returns the highest priority (lowest numerical value)
.BR setpriority ()
call sets the priorities of all of the specified processes
to the specified value.
-.PP
+.P
Traditionally, only a privileged process could lower the nice value
(i.e., set a higher priority).
However, since Linux 2.6.12, an unprivileged process can decrease
On error, it returns \-1 and sets
.I errno
to indicate the error.
-.PP
+.P
Since a successful call to
.BR getpriority ()
can legitimately return the value \-1, it is necessary
.I errno
afterward to determine
if \-1 is an error or a legitimate value.
-.PP
+.P
.BR setpriority ()
returns 0 on success.
On failure, it returns \-1 and sets
.SH NOTES
For further details on the nice value, see
.BR sched (7).
-.PP
+.P
.IR Note :
the addition of the "autogroup" feature in Linux 2.6.38 means that
the nice value no longer has its traditional effect in many circumstances.
For details, see
.BR sched (7).
-.PP
+.P
A child created by
.BR fork (2)
inherits its parent's nice value.
The nice value is preserved across
.BR execve (2).
-.PP
+.P
The details on the condition for
.B EPERM
depend on the system.
.BR fork (2),
.BR capabilities (7),
.BR sched (7)
-.PP
+.P
.I Documentation/scheduler/sched\-nice\-design.txt
in the Linux kernel source tree (since Linux 2.6.23)
.SH SYNOPSIS
.nf
.B #include <sys/random.h>
-.PP
+.P
.BI "ssize_t getrandom(void " buf [. buflen "], size_t " buflen ", \
unsigned int " flags );
.fi
random bytes.
These bytes can be used to seed user-space random number generators
or for cryptographic purposes.
-.PP
+.P
By default,
.BR getrandom ()
draws entropy from the
This behavior can be changed via the
.I flags
argument.
-.PP
+.P
If the
.I urandom
source has been initialized,
For example, if the call is interrupted by a signal handler,
it may return a partially filled buffer, or fail with the error
.BR EINTR .
-.PP
+.P
If the
.I urandom
source has not yet been initialized, then
.B GRND_NONBLOCK
is specified in
.IR flags .
-.PP
+.P
The
.I flags
argument is a bit mask that can contain zero or more of the following values
and insufficient entropy was present in the
.I random
source or the system call was interrupted by a signal.
-.PP
+.P
On error, \-1 is returned, and
.I errno
is set to indicate the error.
For an overview and comparison of the various interfaces that
can be used to obtain randomness, see
.BR random (7).
-.PP
+.P
Unlike
.I /dev/random
and
(unless the
.B GRND_NONBLOCK
flag was specified).
-.PP
+.P
The behavior when a call to
.BR getrandom ()
that is blocked while reading from the
will not fail with
.BR EINTR .
Instead, it will return all of the bytes that have been requested.
-.PP
+.P
When reading from the
.I random
source, blocking requests of any size can be interrupted by a signal handler
(the call fails with the error
.BR EINTR ).
-.PP
+.P
Using
.BR getrandom ()
to read small buffers (<=\ 256 bytes) from the
.I urandom
source is the preferred mode of usage.
-.PP
+.P
The special treatment of small values of
.I buflen
was designed for compatibility with
OpenBSD's
.BR getentropy (3),
which is nowadays supported by glibc.
-.PP
+.P
The user of
.BR getrandom ()
.I must
.nf
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <unistd.h>
-.PP
+.P
.BI "int getresuid(uid_t *" ruid ", uid_t *" euid ", uid_t *" suid );
.BI "int getresgid(gid_t *" rgid ", gid_t *" egid ", gid_t *" sgid );
.fi
.SH HISTORY
Linux 2.1.44,
glibc 2.3.2.
-.PP
+.P
The original Linux
.BR getresuid ()
and
.SH SYNOPSIS
.nf
.B #include <sys/resource.h>
-.PP
+.P
.BI "int getrlimit(int " resource ", struct rlimit *" rlim );
.BI "int setrlimit(int " resource ", const struct rlimit *" rlim );
-.PP
+.P
.BI "int prlimit(pid_t " pid ", int " resource ,
.BI " const struct rlimit *_Nullable " new_limit ,
.BI " struct rlimit *_Nullable " old_limit );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR prlimit ():
.nf
_GNU_SOURCE
Each resource has an associated soft and hard limit, as defined by the
.I rlimit
structure:
-.PP
+.P
.in +4n
.EX
struct rlimit {
};
.EE
.in
-.PP
+.P
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:
.B CAP_SYS_RESOURCE
capability in the initial user namespace)
may make arbitrary changes to either limit value.
-.PP
+.P
The value
.B RLIM_INFINITY
denotes no limit on a resource (both in the structure returned by
.BR getrlimit ()
and in the structure passed to
.BR setrlimit ()).
-.PP
+.P
The
.I resource
argument must be one of:
and
.BR getrlimit ().
It can be used to both set and get the resource limits of an arbitrary process.
-.PP
+.P
The
.I resource
argument has the same meaning as for
.BR setrlimit ()
and
.BR getrlimit ().
-.PP
+.P
If the
.I new_limit
argument is not NULL, then the
.I rlimit
structure pointed to by
.IR old_limit .
-.PP
+.P
The
.I pid
argument specifies the ID of the process on which the call is to operate.
.TP
.BR prlimit ()
Linux.
-.PP
+.P
.B RLIMIT_MEMLOCK
and
.B RLIMIT_NPROC
inherits its parent's resource limits.
Resource limits are preserved across
.BR execve (2).
-.PP
+.P
Resource limits are per-process attributes that are shared
by all of the threads in a process.
-.PP
+.P
Lowering the soft limit for a resource below the process's
current consumption of that resource will succeed
(but will prevent the process from further increasing
its consumption of the resource).
-.PP
+.P
One can set the resource limits of the shell using the built-in
.I ulimit
command
.BR csh (1)).
The shell's resource limits are inherited by the processes that
it creates to execute commands.
-.PP
+.P
Since Linux 2.6.24, the resource limits of any process can be inspected via
.IR /proc/ pid /limits ;
see
.BR proc (5).
-.PP
+.P
Ancient systems provided a
.BR vlimit ()
function with a similar purpose to
but instead employ
.BR prlimit (),
for the reasons described in BUGS.
-.PP
+.P
The name of the glibc wrapper function is
.BR prlimit ();
the underlying system call is
.B RLIMIT_CPU
limits were delivered one (CPU) second later than they should have been.
This was fixed in Linux 2.6.8.
-.PP
+.P
In Linux 2.6.x kernels before Linux 2.6.17, a
.B RLIMIT_CPU
limit of 0 is wrongly treated as "no limit" (like
Since Linux 2.6.17, setting a limit of 0 does have an effect,
but is actually treated as a limit of 1 second.
.\" see http://marc.theaimsgroup.com/?l=linux-kernel&m=114008066530167&w=2
-.PP
+.P
A kernel bug means that
.\" See https://lwn.net/Articles/145008/
.B RLIMIT_RTPRIO
does not work in Linux 2.6.12; the problem is fixed in Linux 2.6.13.
-.PP
+.P
In Linux 2.6.12, there was an off-by-one mismatch
between the priority ranges returned by
.BR getpriority (2)
.IR "19\ \-\ rlim_cur" .
This was fixed in Linux 2.6.13.
.\" see http://marc.theaimsgroup.com/?l=linux-kernel&m=112256338703880&w=2
-.PP
+.P
Since Linux 2.6.12,
.\" The relevant patch, sent to LKML, seems to be
.\" http://thread.gmane.org/gmane.linux.kernel/273462
The Linux-specific
.B RLIMIT_RTTIME
limit exhibits the same behavior when the soft limit is encountered.
-.PP
+.P
Kernels before Linux 2.4.22 did not diagnose the error
.B EINVAL
for
was greater than
.IR rlim\->rlim_max .
.\" d3561f78fd379a7110e46c87964ba7aa4120235c
-.PP
+.P
Linux doesn't return an error when an attempt to set
.B RLIMIT_CPU
has failed, for compatibility reasons.
.B off_t
(assuming a program compiled with
.IR _FILE_OFFSET_BITS=64 ).
-.PP
+.P
To work around this kernel limitation,
if a program tried to set a resource limit to a value larger than
can be represented in a 32-bit
wrapper function silently converted the limit value to
.BR RLIM_INFINITY .
In other words, the requested resource limit setting was silently ignored.
-.PP
+.P
Since glibc 2.13,
.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=12201
glibc works around the limitations of the
.SH EXAMPLES
The program below demonstrates the use of
.BR prlimit ().
-.PP
+.P
.\" SRC BEGIN (getrlimit.c)
.EX
#define _GNU_SOURCE
.SH SYNOPSIS
.nf
.B #include <sys/resource.h>
-.PP
+.P
.BI "int getrusage(int " who ", struct rusage *" usage );
.fi
.SH DESCRIPTION
header file)
in order to obtain the definition of this constant from
.IR <sys/resource.h> .
-.PP
+.P
The resource usages are returned in the structure pointed to by
.IR usage ,
which has the following form:
-.PP
+.P
.in +4n
.EX
struct rusage {
};
.EE
.in
-.PP
+.P
Not all fields are completed;
unmaintained fields are set to zero by the kernel.
(The unmaintained fields are provided for compatibility with other systems,
.TE
.SH STANDARDS
POSIX.1-2008.
-.PP
+.P
POSIX.1 specifies
.BR getrusage (),
but specifies only the fields
.I ru_utime
and
.IR ru_stime .
-.PP
+.P
.B RUSAGE_THREAD
is Linux-specific.
.SH HISTORY
POSIX.1-2001, SVr4, 4.3BSD.
-.PP
+.P
Before Linux 2.6.9, if the disposition of
.B SIGCHLD
is set to
This nonconformance is rectified in Linux 2.6.9 and later.
.\" See the description of getrusage() in XSH.
.\" A similar statement was also in SUSv2.
-.PP
+.P
The structure definition shown at the start of this page
was taken from 4.3BSD Reno.
-.PP
+.P
Ancient systems provided a
.BR vtimes ()
function with a similar purpose to
.SH NOTES
Resource usage metrics are preserved across an
.BR execve (2).
-.PP
+.P
See also the description of
.IR /proc/ pid /stat
in
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.BI "pid_t getsid(pid_t" " pid" );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR getsid ():
.nf
_XOPEN_SOURCE >= 500
.SH SYNOPSIS
.nf
.B #include <sys/socket.h>
-.PP
+.P
.BI "int getsockname(int " sockfd ", struct sockaddr *restrict " addr ,
.BI " socklen_t *restrict " addrlen );
.fi
the amount of space (in bytes) pointed to by
.IR addr .
On return it contains the actual size of the socket address.
-.PP
+.P
The returned address is truncated if the buffer provided is too small;
in this case,
.I addrlen
.SH SYNOPSIS
.nf
.B #include <sys/socket.h>
-.PP
+.P
.BI "int getsockopt(int " sockfd ", int " level ", int " optname ,
.BI " void " optval "[restrict *." optlen ],
.BI " socklen_t *restrict " optlen );
Options may exist at multiple
protocol levels; they are always present at the uppermost
socket level.
-.PP
+.P
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,
.BR TCP ;
see
.BR getprotoent (3).
-.PP
+.P
The arguments
.I optval
and
If no option value is to be supplied or returned,
.I optval
may be NULL.
-.PP
+.P
.I Optname
and any specified options are passed uninterpreted to the appropriate
protocol module for interpretation.
Options at
other protocol levels vary in format and name; consult the appropriate
entries in section 4 of the manual.
-.PP
+.P
Most socket-level options utilize an
.I int
argument for
.BR setsockopt (),
the argument should be nonzero to enable a boolean option, or zero if the
option is to be disabled.
-.PP
+.P
For a description of the available socket options see
.BR socket (7)
and the appropriate protocol man pages.
On error, \-1 is returned, and
.I errno
is set to indicate the error.
-.PP
+.P
Netfilter allows the programmer
to define custom socket options with associated handlers; for such
options, the return value on success is the value returned by the handler.
.nf
.B #define _GNU_SOURCE
.B #include <unistd.h>
-.PP
+.P
.B pid_t gettid(void);
.fi
.SH DESCRIPTION
The thread ID returned by this call is not the same thing as a
POSIX thread ID (i.e., the opaque value returned by
.BR pthread_self (3)).
-.PP
+.P
In a new thread group created by a
.BR clone (2)
call that does not specify the
.SH SYNOPSIS
.nf
.B #include <sys/time.h>
-.PP
+.P
.BI "int gettimeofday(struct timeval *restrict " tv ,
.BI " struct timezone *_Nullable restrict " tz );
.BI "int settimeofday(const struct timeval *" tv ,
.BI " const struct timezone *_Nullable " tz );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR settimeofday ():
.nf
Since glibc 2.19:
and
.BR settimeofday ()
can get and set the time as well as a timezone.
-.PP
+.P
The
.I tv
argument is a
.I struct timeval
(as specified in
.IR <sys/time.h> ):
-.PP
+.P
.in +4n
.EX
struct timeval {
};
.EE
.in
-.PP
+.P
and gives the number of seconds and microseconds since the Epoch (see
.BR time (2)).
-.PP
+.P
The
.I tz
argument is a
.IR "struct timezone" :
-.PP
+.P
.in +4n
.EX
struct timezone {
};
.EE
.in
-.PP
+.P
If either
.I tv
or
.I tv
is NULL.)
.\" The following is covered under EPERM below:
-.\" .PP
+.\" .P
.\" Only the superuser may use
.\" .BR settimeofday ().
-.PP
+.P
The use of the
.I timezone
structure is obsolete; the
.I tz
argument should normally be specified as NULL.
(See NOTES below.)
-.PP
+.P
Under Linux, there are some peculiar "warp clock" semantics associated
with the
.BR settimeofday ()
.BR gettimeofday ()
is provided in the
.BR vdso (7).
-.PP
+.P
The kernel accepts NULL for both
.I tv
and
as obsolete, recommending the use of
.BR clock_gettime (2)
instead.
-.PP
+.P
Traditionally, the fields of
.I struct timeval
were of type
.\" Each and every occurrence of this field in the kernel source
.\" (other than the declaration) is a bug.
Thus, the following is purely of historical interest.
-.PP
+.P
On old systems, the field
.I tz_dsttime
contains a symbolic constant (values are given below)
it does not indicate that DST is in force, it just selects an
algorithm.)
The daylight saving time algorithms defined are as follows:
-.PP
+.P
.in +4n
.EX
\fBDST_NONE\fP /* not on DST */
\fBDST_AUSTALT\fP /* Australian style with shift in 1986 */
.EE
.in
-.PP
+.P
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,
(e.g., if the system administrator manually changes the system time).
If you need a monotonically increasing clock, see
.BR clock_gettime (2).
-.PP
+.P
Macros for operating on
.I timeval
structures are described in
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.B uid_t getuid(void);
.B uid_t geteuid(void);
.fi
.SH DESCRIPTION
.BR getuid ()
returns the real user ID of the calling process.
-.PP
+.P
.BR geteuid ()
returns the effective user ID of the calling process.
.SH ERRORS
POSIX.1-2008.
.SH HISTORY
POSIX.1-2001, 4.3BSD.
-.PP
+.P
In UNIX\ V6 the
.BR getuid ()
call returned
.BR getuid ()
and
.BR geteuid ().
-.PP
+.P
The original Linux
.BR getuid ()
and
and
.BR geteuid ()
wrapper functions transparently deal with the variations across kernel versions.
-.PP
+.P
On Alpha, instead of a pair of
.BR getuid ()
and
.B #include <linux/unwind.h>
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "[[deprecated]] long syscall(SYS_getunwind, void " buf [. buf_size ],
.BI " size_t " buf_size );
.fi
.SH DESCRIPTION
.I Note: this system call is obsolete.
-.PP
+.P
The
IA-64-specific
.BR getunwind ()
and returns the size of the unwind data;
this data describes the gate page (kernel code that
is mapped into user space).
-.PP
+.P
The size of the buffer
.I buf
is specified in
is not NULL;
otherwise, no data is copied, and the call succeeds,
returning the size that would be needed to store the unwind data.
-.PP
+.P
The first part of the unwind data contains an unwind table.
The rest contains the associated unwind information, in no particular order.
The unwind table contains entries of the following form:
-.PP
+.P
.in +4n
.EX
u64 start; (64\-bit address of start of function)
u64 info; (BUF\-relative offset to unwind info)
.EE
.in
-.PP
+.P
An entry whose
.I start
value is zero indicates the end of the table.
Linux on IA-64.
.SH HISTORY
Linux 2.4.
-.PP
+.P
This system call has been deprecated.
The modern way to obtain the kernel's unwind data is via the
.BR vdso (7).
.SH SYNOPSIS
.nf
.B #include <sys/xattr.h>
-.PP
+.P
.BI "ssize_t getxattr(const char *" path ", const char *" name ,
.BI " void " value [. size "], size_t " size );
.BI "ssize_t lgetxattr(const char *" path ", const char *" name ,
data).
A complete overview of extended attributes concepts can be found in
.BR xattr (7).
-.PP
+.P
.BR getxattr ()
retrieves the value of the extended attribute identified by
.I name
specifies the size of that buffer.
The return value of the call is the number of bytes placed in
.IR value .
-.PP
+.P
.BR lgetxattr ()
is identical to
.BR getxattr (),
except in the case of a symbolic link, where the link itself is
interrogated, not the file that it refers to.
-.PP
+.P
.BR fgetxattr ()
is identical to
.BR getxattr (),
.BR open (2))
is interrogated in place of
.IR path .
-.PP
+.P
An extended attribute
.I name
is a null-terminated string.
The value of an extended attribute is a chunk of arbitrary textual or
binary data that was assigned using
.BR setxattr (2).
-.PP
+.P
If
.I size
is specified as zero, these calls return the current size of the
of the
.I value
buffer is too small to hold the result.
-.PP
+.P
In addition, the errors documented in
.BR stat (2)
can also occur.
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.B [[deprecated]] int idle(void);
.fi
.SH DESCRIPTION
and enters the main scheduling loop.
.BR idle ()
never returns.
-.PP
+.P
Only process 0 may call
.BR idle ().
Any user process, even a process with superuser permission,
.BR "#include <linux/module.h>" " /* Definition of " MODULE_* " constants */"
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "int syscall(SYS_init_module, void " module_image [. len "], \
unsigned long " len ,
.BI " const char *" param_values );
.BI "int syscall(SYS_finit_module, int " fd ,
.BI " const char *" param_values ", int " flags );
.fi
-.PP
+.P
.IR Note :
glibc provides no wrappers for these system calls,
necessitating the use of
.I init
function.
This system call requires privilege.
-.PP
+.P
The
.I module_image
argument points to a buffer containing the binary image
.I len
specifies the size of that buffer.
The module image should be a valid ELF image, built for the running kernel.
-.PP
+.P
The
.I param_values
argument is a string containing space-delimited specifications of the
The kernel parses this string and initializes the specified
parameters.
Each of the parameter specifications has the form:
-.PP
+.P
.RI " " name [\c
.BI = value\c
.RB [ ,\c
.IR value ...]]
-.PP
+.P
The parameter
.I name
is one of those defined within the module using
.I param_values
argument is as for
.BR init_module ().
-.PP
+.P
The
.I flags
argument modifies the operation of
.TP
.B MODULE_INIT_IGNORE_VERMAGIC
Ignore kernel version magic.
-.PP
+.P
There are some safety checks built into a module to ensure that
it matches the kernel against which it is loaded.
.\" http://www.tldp.org/HOWTO/Module-HOWTO/basekerncompat.html
In this case, the kernel version number within the
"vermagic" string is ignored,
as the symbol version hashes are assumed to be sufficiently reliable.
-.PP
+.P
Using the
.B MODULE_INIT_IGNORE_VERMAGIC
flag indicates that the "vermagic" string is to be ignored, and the
.I /proc/sys/kernel/modules_disabled
in
.BR proc (5)).
-.PP
+.P
The following errors may additionally occur for
.BR init_module ():
.TP
.I module_image
is not an ELF image,
or is an ELF image that is invalid or for a different architecture.
-.PP
+.P
The following errors may additionally occur for
.BR finit_module ():
.TP
The file referred to by
.I fd
is opened for read-write.
-.PP
+.P
In addition to the above errors, if the module's
.I init
function is executed and returns an error, then
.TP
.BR finit_module ()
Linux 3.8.
-.PP
+.P
The
.BR init_module ()
system call is not supported by glibc.
In Linux 2.4 and earlier, the
.BR init_module ()
system call was rather different:
-.PP
+.P
.B " #include <linux/module.h>"
-.PP
+.P
.BI " int init_module(const char *" name ", struct module *" image );
-.PP
+.P
(User-space applications can detect which version of
.BR init_module ()
is available by calling
the latter call fails with the error
.B ENOSYS
on Linux 2.6 and later.)
-.PP
+.P
The older version of the system call
loads the relocated module image pointed to by
.I image
Linux 2.6, the
.BR init_module ()
system call does the relocation).
-.PP
+.P
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:
-.PP
+.P
.in +4n
.EX
struct module {
};
.EE
.in
-.PP
+.P
All of the pointer fields, with the exception of
.I next
and
.I /proc/modules
and in the file trees under the per-module subdirectories under
.IR /sys/module .
-.PP
+.P
See the Linux kernel source file
.I include/linux/module.h
for some useful background information.
.SH SYNOPSIS
.nf
.B #include <sys/inotify.h>
-.PP
+.P
.BI "int inotify_add_watch(int " fd ", const char *" pathname ", uint32_t " mask );
.fi
.SH DESCRIPTION
.BR inotify (7)
for a description of the bits that can be set in
.IR mask .
-.PP
+.P
A successful call to
.BR inotify_add_watch ()
returns a unique watch descriptor for this inotify instance,
If the filesystem object was already being watched
(perhaps via a different link to the same object), then the descriptor
for the existing watch is returned.
-.PP
+.P
The watch descriptor is returned by later
.BR read (2)s
from the inotify file descriptor.
.SH SYNOPSIS
.nf
.B #include <sys/inotify.h>
-.PP
+.P
.B "int inotify_init(void);"
.BI "int inotify_init1(int " flags );
.fi
.SH DESCRIPTION
For an overview of the inotify API, see
.BR inotify (7).
-.PP
+.P
.BR inotify_init ()
initializes a new inotify instance and returns a file descriptor associated
with a new inotify event queue.
-.PP
+.P
If
.I flags
is 0, then
.SH SYNOPSIS
.nf
.B #include <sys/inotify.h>
-.PP
+.P
.BI "int inotify_rm_watch(int " fd ", int " wd );
.\" Before glibc 2.10, the second argument was types as uint32_t.
.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=7040
.I wd
from the inotify instance associated with the file descriptor
.IR fd .
-.PP
+.P
Removing a watch causes an
.B IN_IGNORED
event to be generated for this watch descriptor.
the system call.
Thus, making a system call looks the same as invoking a normal
library function.
-.PP
+.P
In many cases, the C library wrapper function does nothing more than:
.IP \[bu] 3
copying arguments and the unique system call number to the
.I errno
if the system call returns an error number when the kernel returns the
CPU to user mode.
-.PP
+.P
However, in a few cases, a wrapper function may do rather more than this,
for example, performing some preprocessing
of the arguments before trapping to kernel mode,
interface and the raw system call.
Most commonly, the main DESCRIPTION will focus on the C library interface,
and differences for the system call are covered in the NOTES section.
-.PP
+.P
For a list of the Linux system calls, see
.BR syscalls (2).
.SH RETURN VALUE
absolute value into the
.I errno
variable, and returns \-1 as the return value of the wrapper.
-.PP
+.P
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.
-.PP
+.P
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
.SH LIBRARY
Standard C library
.RI ( libc ", " \-lc )
-.PP
+.P
Alternatively, Asynchronous I/O library
.RI ( libaio ", " \-laio );
see VERSIONS.
.BR "#include <linux/aio_abi.h>" " /* Definition of needed types */"
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "int syscall(SYS_io_cancel, aio_context_t " ctx_id ", struct iocb *" iocb ,
.BI " struct io_event *" result );
.fi
.I ctx_id
argument.
See VERSIONS.
-.PP
+.P
The
.BR io_cancel ()
system call
wrapper function provided by
.\" http://git.fedorahosted.org/git/?p=libaio.git
.IR libaio .
-.PP
+.P
Note that the
.I libaio
wrapper function uses a different type
.BR "#include <linux/aio_abi.h>" " /* Definition of " aio_context_t " */"
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "int syscall(SYS_io_destroy, aio_context_t " ctx_id );
.fi
-.PP
+.P
.IR Note :
glibc provides no wrapper for
.BR io_destroy (),
.I ctx_id
argument.
See VERSIONS.
-.PP
+.P
The
.BR io_destroy ()
system call
wrapper function provided by
.\" http://git.fedorahosted.org/git/?p=libaio.git
.IR libaio .
-.PP
+.P
Note that the
.I libaio
wrapper function uses a different type
.SH LIBRARY
Standard C library
.RI ( libc ", " \-lc )
-.PP
+.P
Alternatively, Asynchronous I/O library
.RI ( libaio ", " \-laio );
see VERSIONS.
.BR "#include <linux/aio_abi.h>" " /* Definition of " *io_* " types */"
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "int syscall(SYS_io_getevents, aio_context_t " ctx_id ,
.BI " long " min_nr ", long " nr ", struct io_event *" events ,
.BI " struct timespec *" timeout );
.fi
-.PP
+.P
.IR Note :
glibc provides no wrapper for
.BR io_getevents (),
.I ctx_id
argument.
See VERSIONS.
-.PP
+.P
The
.BR io_getevents ()
system call
attempts to read at least \fImin_nr\fP events and
up to \fInr\fP events from the completion queue of the AIO context
specified by \fIctx_id\fP.
-.PP
+.P
The \fItimeout\fP argument specifies the amount of time to wait for events,
and is specified as a relative timeout in a
.BR timespec (3)
structure.
-.PP
+.P
The specified time will be rounded up to the system clock granularity
and is guaranteed not to expire early.
-.PP
+.P
Specifying
.I timeout
as NULL means block indefinitely until at least
It may also be a nonzero value less than
.IR min_nr ,
if the call was interrupted by a signal handler.
-.PP
+.P
For the failure return, see VERSIONS.
.SH ERRORS
.TP
wrapper function provided by
.\" http://git.fedorahosted.org/git/?p=libaio.git
.IR libaio .
-.PP
+.P
Note that the
.I libaio
wrapper function uses a different type
.SH LIBRARY
Standard C library
.RI ( libc ", " \-lc )
-.PP
+.P
Alternatively, Asynchronous I/O library
.RI ( libaio ", " \-laio );
see VERSIONS.
.SH SYNOPSIS
.nf
.BR "#include <linux/aio_abi.h>" " /* Defines needed types */"
-.PP
+.P
.BI "long io_setup(unsigned int " nr_events ", aio_context_t *" ctx_idp );
.fi
-.PP
+.P
.IR Note :
There is no glibc wrapper for this system call; see VERSIONS.
.SH DESCRIPTION
.I ctx_idp
argument.
See VERSIONS.
-.PP
+.P
The
.BR io_setup ()
system call
wrapper function provided by
.\" http://git.fedorahosted.org/git/?p=libaio.git
.IR libaio .
-.PP
+.P
Note that the
.I libaio
wrapper function uses a different type
.SH LIBRARY
Standard C library
.RI ( libc ", " \-lc )
-.PP
+.P
Alternatively, Asynchronous I/O library
.RI ( libaio ", " \-laio );
see VERSIONS.
.SH SYNOPSIS
.nf
.BR "#include <linux/aio_abi.h>" " /* Defines needed types */"
-.PP
+.P
.BI "int io_submit(aio_context_t " ctx_id ", long " nr \
", struct iocb **" iocbpp );
.fi
-.PP
+.P
.IR Note :
There is no glibc wrapper for this system call; see VERSIONS.
.SH DESCRIPTION
.I ctx_id
argument.
See VERSIONS.
-.PP
+.P
The
.BR io_submit ()
system call
.I iocbpp
argument should be an array of \fInr\fP AIO control blocks,
which will be submitted to context \fIctx_id\fP.
-.PP
+.P
The
.I iocb
(I/O control block) structure defined in
.I linux/aio_abi.h
defines the parameters that control the I/O operation.
-.PP
+.P
.in +4n
.EX
#include <linux/aio_abi.h>
};
.EE
.in
-.PP
+.P
The fields of this structure are as follows:
.TP
.I aio_data
wrapper function provided by
.\" http://git.fedorahosted.org/git/?p=libaio.git
.IR libaio .
-.PP
+.P
Note that the
.I libaio
wrapper function uses a different type
.SH SYNOPSIS
.nf
.B #include <sys/ioctl.h>
-.PP
+.P
.BI "int ioctl(int " fd ", unsigned long " request ", ...);" "\f[R] /* glibc, BSD */\f[]"
.BI "int ioctl(int " fd ", int " request ", ...);" "\f[R] /* musl, other UNIX */\f[]"
.fi
The argument
.I fd
must be an open file descriptor.
-.PP
+.P
The second argument is a device-dependent request code.
The third argument is an untyped pointer to memory.
It's traditionally
(from the days before
.B "void *"
was valid C), and will be so named for this discussion.
-.PP
+.P
An
.BR ioctl ()
.I request
.BI "ioctl(int " fildes ", int " request ", struct sgttyb *" argp );
.fi
.in
-.PP
+.P
.PD
(where
.B struct sgttyb
and is polymorphic by request type (like a
.B void *
would be, if it had been available)).
-.PP
+.P
SysIII documents
.I arg
without a type at all.
-.PP
+.P
4.3BSD has
.PD 0
.in +4n
.BI "ioctl(int " d ", unsigned long " request ", char *" argp );
.fi
.in
-.PP
+.P
.PD
(with
.B char *
similarly in for
.BR "void *" ).
-.PP
+.P
SysVr4 has
.PD 0
.in +4n
.BI "int ioctl(int " fildes ", int " request ", ... /* " arg " */);"
.fi
.in
-.PP
+.P
.PD
.SH NOTES
In order to use this call, one needs an open file descriptor.
Ioctl command values are 32-bit constants.
In principle these constants are completely arbitrary, but people have
tried to build some structure into them.
-.PP
+.P
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.
.B CYGETTIMEOUT
has value 0x00435906, with 0x43 0x59 = \[aq]C\[aq] \[aq]Y\[aq]
indicating the cyclades driver.
-.PP
+.P
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 an 8-bit type (collecting the ioctls in groups
for a common purpose or a common driver), and an 8-bit
serial number.
-.PP
+.P
The macros describing this structure live in
.I <asm/ioctl.h>
and are
.I sizeof(size)
so that size is a
misnomer here: this third argument is a data type.
-.PP
+.P
Note that the size bits are very unreliable: in lots of cases
they are wrong, either because of buggy macros using
.IR sizeof(sizeof(struct)) ,
or because of legacy values.
-.PP
+.P
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.
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.
-.PP
+.P
Before Linux 1.1.54, the LEDs just reflected the state of the corresponding
keyboard flags, and KDGETLED/KDSETLED would also change the keyboard
flags.
See
.BR resizecons (8).
(Since Linux 1.3.3.)
-.PP
+.P
The action of the following ioctls depends on the first byte in the struct
pointed to by
.IR argp ,
situation as of kernel version 1.1.94;
there are many minor and not-so-minor
differences with earlier versions.)
-.PP
+.P
Very often, ioctls 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.
-.PP
+.P
Programs using these ioctls 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.
-.PP
+.P
Use POSIX functions.
.SH SEE ALSO
.BR dumpkeys (1),
.BR mapscrn (8),
.BR resizecons (8),
.BR setfont (8)
-.PP
+.P
.IR /usr/include/linux/kd.h ,
.I /usr/include/linux/vt.h
.BR "#include <linux/msdos_fs.h>" " /* Definition of [" V ] FAT_* " and"
.BR " ATTR_* " constants */"
.B #include <sys/ioctl.h>
-.PP
+.P
.BI "int ioctl(int " fd ", FAT_IOCTL_GET_ATTRIBUTES, uint32_t *" attr );
.BI "int ioctl(int " fd ", FAT_IOCTL_SET_ATTRIBUTES, uint32_t *" attr );
.BI "int ioctl(int " fd ", FAT_IOCTL_GET_VOLUME_ID, uint32_t *" id );
.B FAT_IOCTL_GET_ATTRIBUTES
and written with
.BR FAT_IOCTL_SET_ATTRIBUTES .
-.PP
+.P
The
.I fd
argument contains a file descriptor for a file or directory.
with the
.B O_RDONLY
flag.
-.PP
+.P
The
.I attr
argument contains a pointer to a bit mask.
This bit indicates that this file or directory should be archived.
It is set when a file is created or modified.
It is reset by an archiving system.
-.PP
+.P
The zero value
.B ATTR_NONE
can be used to indicate that no attribute bit is set.
FAT filesystems are identified by a volume ID.
The volume ID can be read with
.BR FAT_IOCTL_GET_VOLUME_ID .
-.PP
+.P
The
.I fd
argument can be a file descriptor for any file or directory of the
with the
.B O_RDONLY
flag.
-.PP
+.P
The
.I id
argument is a pointer to the field that will be filled with the volume ID.
Typically the volume ID is displayed to the user as a group of two
16-bit fields:
-.PP
+.P
.in +4n
.EX
printf("Volume ID %04x\-%04x\en", id >> 16, id & 0xFFFF);
and up to 3 capital letters for the file extension.
If the actual filename does not fit into this scheme, it is stored
as a long filename of up to 255 UTF-16 characters.
-.PP
+.P
The short filenames in a directory can be read with
.BR VFAT_IOCTL_READDIR_SHORT .
.B VFAT_IOCTL_READDIR_BOTH
reads both the short and the long filenames.
-.PP
+.P
The
.I fd
argument must be a file descriptor for a directory.
entries by calling
.BR ioctl (2)
repeatedly.
-.PP
+.P
The
.I entry
argument is a two-element array of the following structures:
-.PP
+.P
.in +4n
.EX
struct __fat_dirent {
};
.EE
.in
-.PP
+.P
The first entry in the array is for the short filename.
The second entry is for the long filename.
-.PP
+.P
The
.I d_ino
and
field holds the offset of the file entry in the directory.
As these values are not available for short filenames, the user code should
simply ignore them.
-.PP
+.P
The field
.I d_reclen
contains the length of the filename in the field
On error, \-1 is returned, and
.I errno
is set to indicate the error.
-.PP
+.P
For
.B VFAT_IOCTL_READDIR_BOTH
and
The file descriptor
.I fd
does not refer to an object in a FAT filesystem.
-.PP
+.P
For further error values, see
.BR ioctl (2).
.SH STANDARDS
The program reads and displays the archive attribute of a file.
After inverting the value of the attribute,
the program reads and displays the attribute again.
-.PP
+.P
The following was recorded when applying the program for the file
.IR /mnt/user/foo :
-.PP
+.P
.in +4n
.EX
# ./toggle_fat_archive_flag /mnt/user/foo
The following program demonstrates the use of
.BR ioctl (2)
to display the volume ID of a FAT filesystem.
-.PP
+.P
The following output was recorded when applying the program for
directory
.IR /mnt/user :
-.PP
+.P
.in +4n
.EX
$ ./display_fat_volume_id /mnt/user
The following program demonstrates the use of
.BR ioctl (2)
to list a directory.
-.PP
+.P
The following was recorded when applying the program to the directory
.IR /mnt/user :
-.PP
+.P
.in +4n
.EX
$ \fB./fat_dir /mnt/user\fP
.nf
.BR "#include <linux/fs.h>" " /* Definition of " FICLONE* " constants */"
.B #include <sys/ioctl.h>
-.PP
+.P
.BI "int ioctl(int " dest_fd ", FICLONERANGE, struct file_clone_range *" arg );
.BI "int ioctl(int " dest_fd ", FICLONE, int " src_fd );
.fi
the filesystem must ensure that the changes remain private to the file being
written.
This behavior is commonly referred to as "copy on write".
-.PP
+.P
This ioctl reflinks up to
.I src_length
bytes from file descriptor
is zero, the ioctl reflinks to the end of the source file.
This information is conveyed in a structure of
the following form:
-.PP
+.P
.in +4n
.EX
struct file_clone_range {
};
.EE
.in
-.PP
+.P
Clones are atomic with regards to concurrent writes, so no locks need to be
taken to obtain a consistent cloned copy.
-.PP
+.P
The
.B FICLONE
ioctl clones entire files.
Linux.
.SH HISTORY
Linux 4.5.
-.PP
+.P
They were previously known as
.B BTRFS_IOC_CLONE
and
.BR "#include <linux/fs.h>" " /* Definition of " FIDEDUPERANGE " and"
.BR " FILE_DEDUPE_* " constants */
.B #include <sys/ioctl.h>
-.PP
+.P
.BI "int ioctl(int " src_fd ", FIDEDUPERANGE, struct file_dedupe_range *" arg );
.fi
.SH DESCRIPTION
region, the filesystem must ensure that the changes remain private to the file
being written.
This behavior is commonly referred to as "copy on write".
-.PP
+.P
This ioctl performs the "compare and share if identical" operation on up to
.I src_length
bytes from file descriptor
at offset
.IR src_offset .
This information is conveyed in a structure of the following form:
-.PP
+.P
.in +4n
.EX
struct file_dedupe_range {
};
.EE
.in
-.PP
+.P
Deduplication is atomic with regards to concurrent writes, so no locks need to
be taken to obtain a consistent deduplicated copy.
-.PP
+.P
The fields
.IR reserved1 " and " reserved2
must be zero.
-.PP
+.P
Destinations for the deduplication operation are conveyed in the array at the
end of the structure.
The number of destinations is given in
.IR dest_count ,
and the destination information is conveyed in the following form:
-.PP
+.P
.in +4n
.EX
struct file_dedupe_range_info {
};
.EE
.in
-.PP
+.P
Each deduplication operation targets
.I src_length
bytes in file descriptor
and the previous contents in
.I dest_fd
are freed.
-.PP
+.P
Upon successful completion of this ioctl, the number of bytes successfully
deduplicated is returned in
.I bytes_deduped
Linux.
.SH HISTORY
Linux 4.5.
-.PP
+.P
It was previously known as
.B BTRFS_IOC_FILE_EXTENT_SAME
and was private to Btrfs.
.nf
.BR "#include <linux/fs.h>" " /* Definition of " *FSLABEL* " constants */"
.B #include <sys/ioctl.h>
-.PP
+.P
.BI "int ioctl(int " fd ", FS_IOC_GETFSLABEL, char " label [FSLABEL_MAX]);
.BI "int ioctl(int " fd ", FS_IOC_SETFSLABEL, char " label [FSLABEL_MAX]);
.fi
Linux.
.SH HISTORY
Linux 4.18.
-.PP
+.P
They were previously known as
.B BTRFS_IOC_GET_FSLABEL
and
.BR "#include <linux/fsmap.h> " "/* Definition of " FS_IOC_GETFSMAP ,
.BR " FM?_OF_*" ", and " *FMR_OWN_* " constants */"
.B #include <sys/ioctl.h>
-.PP
+.P
.BI "int ioctl(int " fd ", FS_IOC_GETFSMAP, struct fsmap_head * " arg );
.fi
.SH DESCRIPTION
operation retrieves physical extent mappings for a filesystem.
This information can be used to discover which files are mapped to a physical
block, examine free space, or find known bad blocks, among other things.
-.PP
+.P
The sole argument to this operation should be a pointer to a single
.IR "struct fsmap_head" ":"
-.PP
+.P
.in +4n
.EX
struct fsmap {
};
.EE
.in
-.PP
+.P
The two
.I fmh_keys
array elements specify the lowest and highest reverse-mapping
The owner and offset fields are part of the key because some filesystems
support sharing physical blocks between multiple files and
therefore may return multiple mappings for a given physical block.
-.PP
+.P
Filesystem mappings are copied into the
.I fmh_recs
array, which immediately follows the header data.
.I fmh_iflags
field is a bit mask passed to the kernel to alter the output.
No flags are currently defined, so the caller must set this value to zero.
-.PP
+.P
The
.I fmh_oflags
field is a bit mask of flags set by the kernel concerning the returned mappings.
field represents a
.I dev_t
structure containing the major and minor numbers of the block device.
-.PP
+.P
The
.I fmh_count
field contains the number of elements in the array being passed to the
will be set to the number of records that would have been returned had
the array been large enough;
no mapping information will be returned.
-.PP
+.P
The
.I fmh_entries
field contains the number of elements in the
.I fmh_recs
array that contain useful information.
-.PP
+.P
The
.I fmh_reserved
fields must be set to zero.
must contain the low key and
.I fsmap_head.fmh_keys[1]
must contain the high key for the request.
-.PP
+.P
For convenience, if
.I fmr_length
is set in the low key, it will be added to
from which major and minor numbers can be extracted.
If the flag is not set, this field contains a value that must be unique
for each unique storage device.
-.PP
+.P
The
.I fmr_physical
field contains the disk address of the extent in bytes.
-.PP
+.P
The
.I fmr_owner
field contains the owner of the extent.
.I fmr_flags
field, in which case the value is determined by the filesystem.
See the section below about owner values for more details.
-.PP
+.P
The
.I fmr_offset
field contains the logical address in the mapping record in bytes.
.BR FMR_OF_SPECIAL_OWNER " or " FMR_OF_EXTENT_MAP
flags are set in
.IR fmr_flags "."
-.PP
+.P
The
.I fmr_length
field contains the length of the extent in bytes.
-.PP
+.P
The
.I fmr_flags
field is a bit mask of extent state flags.
.B FMR_OF_LAST
This is the last record in the data set.
.RE
-.PP
+.P
The
.I fmr_reserved
field will be set to zero.
.B FMR_OWN_METADATA
This extent is filesystem metadata.
.RE
-.PP
+.P
XFS can return the following special owner values:
.RS 0.4i
.TP
This extent has been marked defective either by the filesystem or the
underlying device.
.RE
-.PP
+.P
ext4 can return the following special owner values:
.RS 0.4i
.TP
The filesystem metadata is corrupt and needs repair.
.SH STANDARDS
Linux.
-.PP
+.P
Not all filesystems support it.
.SH HISTORY
Linux 4.12.
These flags can be retrieved and modified using two
.BR ioctl (2)
operations:
-.PP
+.P
.in +4n
.EX
int attr;
referred to by \[aq]fd\[aq] */
.EE
.in
-.PP
+.P
The
.BR lsattr (1)
and
.BR chattr (1)
shell commands provide interfaces to these two operations,
allowing a user to view and modify the inode flags associated with a file.
-.PP
+.P
The following flags are supported
(shown along with the corresponding letter used to indicate the flag by
.BR lsattr (1)
Allow the file to be undeleted if it is deleted.
This feature is not implemented by any filesystem,
since it is possible to implement file-recovery mechanisms outside the kernel.
-.PP
+.P
In most cases,
when any of the above flags is set on a directory,
the flag is inherited by files and subdirectories
or the caller must have the
.B CAP_FOWNER
capability.
-.PP
+.P
The type of the argument given to the
.B FS_IOC_GETFLAGS
and
and
.BR pid_namespaces (7)).
The form of the calls is:
-.PP
+.P
.in +4n
.EX
new_fd = ioctl(fd, request);
.EE
.in
-.PP
+.P
In each case,
.I fd
refers to a
.B NS_GET_PARENT
is synonymous with
.BR NS_GET_USERNS .
-.PP
+.P
The new file descriptor returned by these operations is opened with the
.B O_RDONLY
and
(close-on-exec; see
.BR fcntl (2))
flags.
-.PP
+.P
By applying
.BR fstat (2)
to the returned file descriptor, one obtains a
This inode number can be matched with the inode number of another
.IR /proc/ pid /ns/ { pid , user }
file to determine whether that is the owning/parent namespace.
-.PP
+.P
Either of these
.BR ioctl (2)
operations can fail with the following errors:
.TP
.B ENOTTY
The operation is not supported by this kernel version.
-.PP
+.P
Additionally, the
.B NS_GET_PARENT
operation can fail with the following error:
.B EINVAL
.I fd
refers to a nonhierarchical namespace.
-.PP
+.P
See the EXAMPLES section for an example of the use of these operations.
.\" ============================================================
.\"
operation (available since Linux 4.11) can be used to discover
the type of namespace referred to by the file descriptor
.IR fd :
-.PP
+.P
.in +4n
.EX
nstype = ioctl(fd, NS_GET_NSTYPE);
.EE
.in
-.PP
+.P
.I fd
refers to a
.IR /proc/ pid /ns/*
file.
-.PP
+.P
The return value is one of the
.B CLONE_NEW*
values that can be specified to
the owner user ID of a user namespace (i.e., the effective user ID
of the process that created the user namespace).
The form of the call is:
-.PP
+.P
.in +4n
.EX
uid_t uid;
ioctl(fd, NS_GET_OWNER_UID, &uid);
.EE
.in
-.PP
+.P
.I fd
refers to a
.IR /proc/ pid /ns/user
file.
-.PP
+.P
The owner user ID is returned in the
.I uid_t
pointed to by the third argument.
-.PP
+.P
This operation can fail with the following error:
.TP
.B EINVAL
discovery of namespace relationships.
The following shell sessions show various examples of the use
of this program.
-.PP
+.P
Trying to get the parent of the initial user namespace fails,
since it has no parent:
-.PP
+.P
.in +4n
.EX
$ \fB./ns_show /proc/self/ns/user p\fP
The parent namespace is outside your namespace scope
.EE
.in
-.PP
+.P
Create a process running
.BR sleep (1)
that resides in new user and UTS namespaces,
and show that the new UTS namespace is associated with the new user namespace:
-.PP
+.P
.in +4n
.EX
$ \fBunshare \-Uu sleep 1000 &\fP
user:[4026532448]
.EE
.in
-.PP
+.P
Then show that the parent of the new user namespace in the preceding
example is the initial user namespace:
-.PP
+.P
.in +4n
.EX
$ \fBreadlink /proc/self/ns/user\fP
Device/Inode of parent namespace is: [0,3] / 4026531837
.EE
.in
-.PP
+.P
Start a shell in a new user namespace, and show that from within
this shell, the parent user namespace can't be discovered.
Similarly, the UTS namespace
(which is associated with the initial user namespace)
can't be discovered.
-.PP
+.P
.in +4n
.EX
$ \fBPS1="sh2$ " unshare \-U bash\fP
.BR "#include <linux/fs.h>" " /* Definition of " "struct pm_scan_arg" ,
.BR " struct page_region" ", and " PAGE_IS_* " constants */"
.B #include <sys/ioctl.h>
-.PP
+.P
.BI "int ioctl(int " pagemap_fd ", PAGEMAP_SCAN, struct pm_scan_arg *" arg );
.fi
.SH DESCRIPTION
The information is returned with
.B PAGE_SIZE
granularity.
-.PP
+.P
To start tracking the written state (flag) of a page or range of memory,
the
.B UFFD_FEATURE_WP_ASYNC
.nf
.BR "#include <linux/watch_queue.h>" " /* Definition of " IOC_WATCH_QUEUE_ "* */"
.B #include <sys/ioctl.h>
-.PP
+.P
.BI "int ioctl(int " pipefd "[1], IOC_WATCH_QUEUE_SET_SIZE, int " size );
.BI "int ioctl(int " pipefd "[1], IOC_WATCH_QUEUE_SET_FILTER,"
.BI " struct watch_notification_filter *" filter );
.BR " struct termios2" ", and"
.BR " Bnnn" ", " BOTHER ", " CBAUD ", " CLOCAL ,
.BR " TC*" { FLUSH , ON , OFF "} and other constants */"
-.PP
+.P
.BI "int ioctl(int " fd ", int " cmd ", ...);"
.fi
.SH DESCRIPTION
.I argp
or
.IR arg .
-.PP
+.P
Use of
.BR ioctl ()
makes for nonportable programs.
Use the POSIX interface described in
.BR termios (3)
whenever possible.
-.PP
+.P
Please note that
.B struct termios
from
.IP
Allow the output buffer to drain, discard pending input, and
set the current serial port settings.
-.PP
+.P
The following four ioctls, added in Linux 2.6.20,
.\" commit 64bb6c5e1ddcd47c951740485026ef08975ee2e6
.\" commit 592ee3a5e5e2a981ef2829a0380093006d045661
TCSETSF2 \fBconst struct termios2 *\fPargp
.TE
.RE
-.PP
+.P
The following four ioctls are just like
.BR TCGETS ,
.BR TCSETS ,
.BI "const struct winsize\~*" argp
.IP
Set window size.
-.PP
+.P
The struct used by these ioctls is defined as
-.PP
+.P
.in +4n
.EX
struct winsize {
};
.EE
.in
-.PP
+.P
When the window size changes, a
.B SIGWINCH
signal is sent to the
.BR ptsname (3)
with a pathname where a devpts filesystem
has been mounted in a different mount namespace.)
-.PP
+.P
The BSD ioctls
.BR TIOCSTOP ,
.BR TIOCSTART ,
.BI "const int\~*" argp
.IP
Set the indicated modem bits.
-.PP
+.P
The following bits are used by the above ioctls:
-.PP
+.P
.TS
lb l.
TIOCM_LE DSR (data set ready/line enable)
structure when
.RI * argp
is nonzero, and clear it otherwise.
-.PP
+.P
If the
.B CLOCAL
flag for a line is off, the hardware carrier detect (DCD)
.\"
.\" .SS Serial info
.\" .BR "#include <linux/serial.h>"
-.\" .PP
+.\" .P
.\" .TP
.\" .BI "TIOCGSERIAL struct serial_struct *" argp
.\" Get serial info.
Insufficient permission.
.SH EXAMPLES
Check the condition of DTR on the serial port.
-.PP
+.P
.\" SRC BEGIN (tiocmget.c)
.EX
#include <fcntl.h>
}
.EE
.\" SRC END
-.PP
+.P
Get or set arbitrary baudrate on the serial port.
-.PP
+.P
.\" SRC BEGIN (tcgets.c)
.EX
/* SPDX-License-Identifier: GPL-2.0-or-later */
.nf
.BR "#include <linux/userfaultfd.h>" " /* Definition of " UFFD* " constants */"
.B #include <sys/ioctl.h>
-.PP
+.P
.BI "int ioctl(int " fd ", int " cmd ", ...);"
.fi
.SH DESCRIPTION
operations can be performed on a userfaultfd object (created by a call to
.BR userfaultfd (2))
using calls of the form:
-.PP
+.P
.in +4n
.EX
ioctl(fd, cmd, argp);
.EE
.in
-.PP
+.P
In the above,
.I fd
is a file descriptor referring to a userfaultfd object,
.I argp
is a pointer to a data structure that is specific to
.IR cmd .
-.PP
+.P
The various
.BR ioctl (2)
operations are described below.
.SS UFFDIO_API
(Since Linux 4.3.)
Enable operation of the userfaultfd and perform API handshake.
-.PP
+.P
The
.I argp
argument is a pointer to a
.I uffdio_api
structure, defined as:
-.PP
+.P
.in +4n
.EX
struct uffdio_api {
};
.EE
.in
-.PP
+.P
The
.I api
field denotes the API version requested by the application.
fields to bit masks representing all the available features and the generic
.BR ioctl (2)
operations available.
-.PP
+.P
Since Linux 4.11,
applications should use the
.I features
.I features
field set to zero.
The kernel responds by setting all supported feature bits.
-.PP
+.P
Applications which do not require any specific features
can begin using the userfaultfd immediately.
Applications which do need specific features
.B UFFDIO_API
again with a subset of the reported feature bits set
to enable those features.
-.PP
+.P
Before Linux 4.11, the
.I features
field must be initialized to zero before the call to
.I features
field by the kernel upon return from
.BR ioctl (2).
-.PP
+.P
If the application sets unsupported feature bits,
the kernel will zero out the returned
.I uffdio_api
structure and return
.BR EINVAL .
-.PP
+.P
The following feature bits may be set:
.TP
.BR UFFD_FEATURE_EVENT_FORK " (since Linux 4.11)"
If this feature bit is set,
the write protection faults would be asynchronously resolved
by the kernel.
-.PP
+.P
The returned
.I ioctls
field can contain the following bits:
The
.B UFFDIO_UNREGISTER
operation is supported.
-.PP
+.P
This
.BR ioctl (2)
operation returns 0 on success.
The pages in the range must be \[lq]compatible\[rq].
Please refer to the list of register modes below
for the compatible memory backends for each mode.
-.PP
+.P
The
.I argp
argument is a pointer to a
.I uffdio_register
structure, defined as:
-.PP
+.P
.in +4n
.EX
struct uffdio_range {
};
.EE
.in
-.PP
+.P
The
.I range
field defines a memory range starting at
and continuing for
.I len
bytes that should be handled by the userfaultfd.
-.PP
+.P
The
.I mode
field defines the mode of operation desired for this memory region.
only hugetlbfs ranges are compatible.
Since Linux 5.14,
compatibility with shmem ranges was added.
-.PP
+.P
If the operation is successful, the kernel modifies the
.I ioctls
bit-mask field to indicate which
The
.B UFFDIO_POISON
operation is supported.
-.PP
+.P
This
.BR ioctl (2)
operation returns 0 on success.
The pages in the range must be \[lq]compatible\[rq]
(see the description of
.BR UFFDIO_REGISTER .)
-.PP
+.P
The address range to unregister is specified in the
.I uffdio_range
structure pointed to by
.IR argp .
-.PP
+.P
This
.BR ioctl (2)
operation returns 0 on success.
.I uffdio_copy
structure pointed to by
.IR argp :
-.PP
+.P
.in +4n
.EX
struct uffdio_copy {
};
.EE
.in
-.PP
+.P
The following value may be bitwise ORed in
.I mode
to change the behavior of the
and
.B UFFDIO_REGISTER_MODE_WP
modes are enabled for the registered range.
-.PP
+.P
The
.I copy
field is used by the kernel to return the number of bytes
it is not read by the
.B UFFDIO_COPY
operation.
-.PP
+.P
This
.BR ioctl (2)
operation returns 0 on success.
.SS UFFDIO_ZEROPAGE
(Since Linux 4.3.)
Zero out a memory range registered with userfaultfd.
-.PP
+.P
The requested range is specified by the
.I range
field of the
.I uffdio_zeropage
structure pointed to by
.IR argp :
-.PP
+.P
.in +4n
.EX
struct uffdio_zeropage {
};
.EE
.in
-.PP
+.P
The following value may be bitwise ORed in
.I mode
to change the behavior of the
.TP
.B UFFDIO_ZEROPAGE_MODE_DONTWAKE
Do not wake up the thread that waits for page-fault resolution.
-.PP
+.P
The
.I zeropage
field is used by the kernel to return the number of bytes
it is not read by the
.B UFFDIO_ZEROPAGE
operation.
-.PP
+.P
This
.BR ioctl (2)
operation returns 0 on success.
(Since Linux 4.3.)
Wake up the thread waiting for page-fault resolution on
a specified memory address range.
-.PP
+.P
The
.B UFFDIO_WAKE
operation is used in conjunction with
.B UFFDIO_ZEROPAGE
operations in a batch and then explicitly wake up the faulting thread using
.BR UFFDIO_WAKE .
-.PP
+.P
The
.I argp
argument is a pointer to a
.I uffdio_range
structure (shown above) that specifies the address range.
-.PP
+.P
This
.BR ioctl (2)
operation returns 0 on success.
Write-protect or write-unprotect a userfaultfd-registered memory range
registered with mode
.BR UFFDIO_REGISTER_MODE_WP .
-.PP
+.P
The
.I argp
argument is a pointer to a
.I uffdio_range
structure as shown below:
-.PP
+.P
.in +4n
.EX
struct uffdio_writeprotect {
};
.EE
.in
-.PP
+.P
There are two mode bits that are supported in this structure:
.TP
.B UFFDIO_WRITEPROTECT_MODE_WP
This can be specified only if
.B UFFDIO_WRITEPROTECT_MODE_WP
is not specified.
-.PP
+.P
This
.BR ioctl (2)
operation returns 0 on success.
Resolve a minor page fault
by installing page table entries
for existing pages in the page cache.
-.PP
+.P
The
.I argp
argument is a pointer to a
.I uffdio_continue
structure as shown below:
-.PP
+.P
.in +4n
.EX
struct uffdio_continue {
};
.EE
.in
-.PP
+.P
The following value may be bitwise ORed in
.I mode
to change the behavior of the
.TP
.B UFFDIO_CONTINUE_MODE_DONTWAKE
Do not wake up the thread that waits for page-fault resolution.
-.PP
+.P
The
.I mapped
field is used by the kernel
it is not read by the
.B UFFDIO_CONTINUE
operation.
-.PP
+.P
This
.BR ioctl (2)
operation returns 0 on success.
this works by installing page table entries,
rather than "really" poisoning the underlying physical pages.
This means it only affects this particular address space.
-.PP
+.P
The
.I argp
argument is a pointer to a
.I uffdio_poison
structure as shown below:
-.PP
+.P
.in +4n
.EX
struct uffdio_poison {
};
.EE
.in
-.PP
+.P
The following value may be bitwise ORed in
.I mode
to change the behavior of the
.TP
.B UFFDIO_POISON_MODE_DONTWAKE
Do not wake up the thread that waits for page-fault resolution.
-.PP
+.P
The
.I updated
field is used by the kernel
it is not read by the
.B UFFDIO_POISON
operation.
-.PP
+.P
This
.BR ioctl (2)
operation returns 0 on success.
.BR ioctl (2),
.BR mmap (2),
.BR userfaultfd (2)
-.PP
+.P
.I Documentation/admin\-guide/mm/userfaultfd.rst
in the Linux kernel source tree
.SH SYNOPSIS
.nf
.B #include <sys/io.h>
-.PP
+.P
.BI "int ioperm(unsigned long " from ", unsigned long " num ", int " turn_on );
.fi
.SH DESCRIPTION
.I turn_on
is nonzero, the calling thread must be privileged
.RB ( CAP_SYS_RAWIO ).
-.PP
+.P
Before Linux 2.6.8,
only the first 0x3ff I/O ports could be specified in this manner.
For more ports, the
.I level
argument of 3).
Since Linux 2.6.8, 65,536 I/O ports can be specified.
-.PP
+.P
Permissions are inherited by the child created by
.BR fork (2)
(but see NOTES).
.BR execve (2);
this is useful for giving port access permissions to unprivileged
programs.
-.PP
+.P
This call is mostly for the i386 architecture.
On many other architectures it does not exist or will always
return an error.
.SH SYNOPSIS
.nf
.B #include <sys/io.h>
-.PP
+.P
.BI "[[deprecated]] int iopl(int " level );
.fi
.SH DESCRIPTION
changes the I/O privilege level of the calling thread,
as specified by the two least significant bits in
.IR level .
-.PP
+.P
The I/O privilege level for a normal thread is 0.
Permissions are inherited from parents to children.
-.PP
+.P
This call is deprecated, is significantly slower than
.BR ioperm (2),
and is only provided for older X servers which require
allowed the thread to disable interrupts while running
at a higher I/O privilege level.
This will probably crash the system, and is not recommended.
-.PP
+.P
Prior to Linux 3.7,
on some architectures (such as i386), permissions
.I were
.BR "#include <linux/ioprio.h> " "/* Definition of " IOPRIO_* " constants */"
.BR "#include <sys/syscall.h> " "/* Definition of " SYS_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "int syscall(SYS_ioprio_get, int " which ", int " who );
.BI "int syscall(SYS_ioprio_set, int " which ", int " who ", int " ioprio );
.fi
-.PP
+.P
.IR Note :
glibc provides no wrappers for these system calls,
necessitating the use of
.BR ioprio_set ()
system calls get and set the I/O scheduling class and
priority of one or more threads.
-.PP
+.P
The
.I which
and
have a matching real UID.
.\" FIXME . Need to document the behavior when 'who" is specified as 0
.\" See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=652443
-.PP
+.P
If
.I which
is specified as
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).
-.PP
+.P
The
.I ioprio
argument given to
value), this macro returns its priority
.RI ( data )
component.
-.PP
+.P
See the NOTES section for more
information on scheduling classes and priorities,
as well as the meaning of specifying
.I ioprio
as 0.
-.PP
+.P
I/O priorities are supported for reads and for synchronous
.RB ( O_DIRECT ,
.BR O_SYNC )
On error, \-1 is returned, and
.I errno
is set to indicate the error.
-.PP
+.P
On success,
.BR ioprio_set ()
returns 0.
.BR gettid (2)
or
.BR clone (2).
-.PP
+.P
These system calls have an effect only 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.
-.PP
+.P
If no I/O scheduler has been set for a thread,
then by default the I/O priority will follow the CPU nice value
.RB ( setpriority (2)).
I/O schedulers are selected on a per-device basis via the special
file
.IR /sys/block/ device /queue/scheduler .
-.PP
+.P
One can view the current I/O scheduler via the
.I /sys
filesystem.
For example, the following command
displays a list of all schedulers currently loaded in the kernel:
-.PP
+.P
.in +4n
.EX
.RB "$" " cat /sys/block/sda/queue/scheduler"
noop anticipatory deadline [cfq]
.EE
.in
-.PP
+.P
The scheduler surrounded by brackets is the one actually
in use for the device
.RI ( sda
.I sda
device to
.IR cfq :
-.PP
+.P
.in +4n
.EX
.RB "$" " su"
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.
-.PP
+.P
Refer to the kernel source file
.I Documentation/block/ioprio.txt
for more information on the CFQ I/O Scheduler and an example program.
to set a very low priority
.RB ( IOPRIO_CLASS_IDLE ),
but since Linux 2.6.25, this is no longer required.
-.PP
+.P
A call to
.BR ioprio_set ()
must follow both rules, or the call will fail with the error
.BR open (2),
.BR capabilities (7),
.BR cgroups (7)
-.PP
+.P
.I Documentation/block/ioprio.txt
in the Linux kernel source tree
.BR "#include <linux/ipc.h>" " /* Definition of needed constants */"
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "int syscall(SYS_ipc, unsigned int " call ", int " first ,
.BI " unsigned long " second ", unsigned long " third \
", void *" ptr ,
.BI " long " fifth );
.fi
-.PP
+.P
.IR Note :
glibc provides no wrapper for
.BR ipc (),
.I call
determines which IPC function to invoke;
the other arguments are passed through to the appropriate call.
-.PP
+.P
User-space programs should call the appropriate functions by their usual names.
Only standard library implementors and kernel hackers need to know about
.BR ipc ().
.BR "#include <linux/kcmp.h>" " /* Definition of " KCMP_* " constants */"
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "int syscall(SYS_kcmp, pid_t " pid1 ", pid_t " pid2 ", int " type ,
.BI " unsigned long " idx1 ", unsigned long " idx2 );
.fi
-.PP
+.P
.IR Note :
glibc provides no wrapper for
.BR kcmp (),
.I pid2
share a kernel resource such as virtual memory, file descriptors,
and so on.
-.PP
+.P
Permission to employ
.BR kcmp ()
is governed by ptrace access mode
.IR pid2 ;
see
.BR ptrace (2).
-.PP
+.P
The
.I type
argument specifies which resource is to be compared in the two processes.
.I idx2
is a pointer to a structure where the target file is described.
This structure has the form:
-.PP
+.P
.in +4n
.EX
struct kcmp_epoll_slot {
};
.EE
.in
-.PP
+.P
Within this structure,
.I efd
is an epoll file descriptor returned from
Several different targets may be registered with
the same file descriptor number and setting a specific
offset helps to investigate each of them.
-.PP
+.P
Note the
.BR kcmp ()
is not protected against false positives which may occur if
is simply the result of arithmetic comparison
of kernel pointers (when the kernel compares resources, it uses their
memory addresses).
-.PP
+.P
The easiest way to explain is to consider an example.
Suppose that
.I v1
.IR v2 ,
but ordering information is unavailable.
.RE
-.PP
+.P
On error, \-1 is returned, and
.I errno
is set to indicate the error.
-.PP
+.P
.BR kcmp ()
was designed to return values suitable for sorting.
This is particularly handy if one needs to compare
Linux.
.SH HISTORY
Linux 3.5.
-.PP
+.P
Before Linux 5.12,
this system call is available only if the kernel is configured with
.BR CONFIG_CHECKPOINT_RESTORE ,
The program tests different cases for the file descriptor pairs,
as described in the program output.
An example run of the program is as follows:
-.PP
+.P
.in +4n
.EX
$ \fB./a.out\fP
.BR "#include <linux/kexec.h>" " /* Definition of " KEXEC_* " constants */"
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "long syscall(SYS_kexec_load, unsigned long " entry ,
.BI " unsigned long " nr_segments \
", struct kexec_segment *" segments ,
.BI " unsigned long " cmdline_len ", const char *" cmdline ,
.BI " unsigned long " flags );
.fi
-.PP
+.P
.IR Note :
glibc provides no wrappers for these system calls,
necessitating the use of
.BR kexec_load ()
system call loads a new kernel that can be executed later by
.BR reboot (2).
-.PP
+.P
The
.I flags
argument is a bit mask that controls the operation of the call.
and is effective only if
.I nr_segments
is greater than 0.
-.PP
+.P
The high-order bits (corresponding to the mask 0xffff0000) of
.I flags
contain the architecture of the to-be-executed kernel.
and
.BR KEXEC_ARCH_MIPS_LE .
The architecture must be executable on the CPU of the system.
-.PP
+.P
The
.I entry
argument is the physical entry address in the kernel image.
argument is an array of
.I kexec_segment
structures which define the kernel layout:
-.PP
+.P
.in +4n
.EX
struct kexec_segment {
};
.EE
.in
-.PP
+.P
The kernel image defined by
.I segments
is copied from the calling process into
is less than
.IR memsz ,
then the excess bytes in the kernel buffer are zeroed out.
-.PP
+.P
In case of a normal kexec (i.e., the
.B KEXEC_ON_CRASH
flag is not set), the segment data is loaded in any available memory
command is executed with the
.I \-e
option).
-.PP
+.P
In case of kexec on panic (i.e., the
.B KEXEC_ON_CRASH
flag is set), the segment data is
loaded to reserved memory at the time of the call, and, after a crash,
the kexec mechanism simply passes control to that kernel.
-.PP
+.P
The
.BR kexec_load ()
system call is available only if the kernel was configured with
.I cmdline_len
argument specifies size of the buffer.
The last byte in the buffer must be a null byte (\[aq]\e0\[aq]).
-.PP
+.P
The
.I flags
argument is a bit mask which modifies the behavior of the call.
If this flag is set, the value passed in
.I initrd_fd
is ignored.
-.PP
+.P
The
.BR kexec_file_load ()
.\" See also http://lwn.net/Articles/603116/
.BR reboot (2),
.BR syscall (2),
.BR kexec (8)
-.PP
+.P
The kernel source files
.I Documentation/kdump/kdump.txt
and
.SH LIBRARY
Standard C library
.RI ( libc ", " \-lc )
-.PP
+.P
Alternatively, Linux Key Management Utilities
.RI ( libkeyutils ", " \-lkeyutils );
see VERSIONS.
.BR "#include <linux/keyctl.h>" " /* Definition of " KEY* " constants */"
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "long syscall(SYS_keyctl, int " operation ", unsigned long " arg2 ,
.BI " unsigned long " arg3 ", unsigned long " arg4 ,
.BI " unsigned long " arg5 );
.fi
-.PP
+.P
.IR Note :
glibc provides no wrapper for
.BR keyctl (),
.SH DESCRIPTION
.BR keyctl ()
allows user-space programs to perform key manipulation.
-.PP
+.P
The operation performed by
.BR keyctl ()
is determined by the value of the
.I keyutils
package) into individual functions (noted below)
to permit the compiler to check types.
-.PP
+.P
The permitted values for
.I operation
are:
.TP
All other operations
Zero.
-.PP
+.P
On error, \-1 is returned, and
.I errno
is set to indicate the error.
package.
For informational purposes,
the program records various information in a log file.
-.PP
+.P
As described in
.BR request_key (2),
the
The example program fetches and logs these arguments.
The program assumes authority to instantiate the requested key,
and then instantiates that key.
-.PP
+.P
The following shell session demonstrates the use of this program.
In the session,
we compile the program and then use it to temporarily replace the standard
we use the example program shown in
.BR request_key (2)
to request a key.
-.PP
+.P
.in +4n
.EX
$ \fBcc \-o key_instantiate key_instantiate.c \-lkeyutils\fP
$ \fBsudo mv /sbin/request\-key.backup /sbin/request\-key\fP
.EE
.in
-.PP
+.P
Looking at the log file created by this program,
we can see the command-line arguments supplied to our example program:
-.PP
+.P
.in +4n
.EX
$ \fBcat /tmp/key_instantiate.log\fP
Auth key description: .request_key_auth;1000;1000;0b010000;20d035bf
.EE
.in
-.PP
+.P
The last few lines of the above output show that the example program
was able to fetch:
.IP \[bu] 3
where we can see that the name of the authorization key matches
the ID of the key that is to be instantiated
.RI ( 20d035bf ).
-.PP
+.P
The example program in
.BR request_key (2)
specified the destination keyring as
.I mykey
and ID
.IR 20d035bf .
-.PP
+.P
.in +4n
.EX
$ \fBcat /proc/keys | egrep \[aq]mykey|256e6a6\[aq]\fP
.BR user_namespaces (7),
.BR user\-session\-keyring (7),
.BR request\-key (8)
-.PP
+.P
The kernel source files under
.I Documentation/security/keys/
(or, before Linux 4.13, in the file
.SH SYNOPSIS
.nf
.B #include <signal.h>
-.PP
+.P
.BI "int kill(pid_t " pid ", int " sig );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR kill ():
.nf
_POSIX_C_SOURCE
.BR kill ()
system call
can be used to send any signal to any process group or process.
-.PP
+.P
If \fIpid\fP is positive, then signal \fIsig\fP is sent to the
process with the ID specified by \fIpid\fP.
-.PP
+.P
If \fIpid\fP equals 0, then \fIsig\fP is sent to every process in the
process group of the calling process.
-.PP
+.P
If \fIpid\fP equals \-1, then \fIsig\fP is sent to every process
for which the calling process has permission to send signals,
except for process 1 (\fIinit\fP), but see below.
-.PP
+.P
If \fIpid\fP is less than \-1, then \fIsig\fP is sent to every process
in the process group whose ID is \fI\-pid\fP.
-.PP
+.P
If \fIsig\fP is 0, then no signal is sent,
but existence and permission checks are still performed;
this can be used to check for the existence of a process ID or
process group ID that the caller is permitted to signal.
-.PP
+.P
For a process to have permission to send a signal,
it must either be privileged (under Linux: have the
.B CAP_KILL
has explicitly installed signal handlers.
This is done to assure the
system is not brought down accidentally.
-.PP
+.P
POSIX.1 requires that \fIkill(\-1,sig)\fP send \fIsig\fP
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
\fIkill(\-1,sig)\fP does not signal the calling process.
-.PP
+.P
POSIX.1 requires that if a process sends a signal to itself,
and the sending thread does not have the signal blocked,
and no other thread
.nf
.BR "#include <linux/landlock.h>" " /* Definition of " LANDLOCK_* " constants */"
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
-.PP
+.P
.BI "int syscall(SYS_landlock_add_rule, int " ruleset_fd ,
.BI " enum landlock_rule_type " rule_type ,
.BI " const void *" rule_attr ", uint32_t " flags );
See
.BR landlock (7)
for a global overview.
-.PP
+.P
.I ruleset_fd
is a Landlock ruleset file descriptor obtained with
.BR landlock_create_ruleset (2).
-.PP
+.P
.I rule_type
identifies the structure type pointed to by
.IR rule_attr .
flag,
which identifies the parent directory of the file hierarchy or
just a file.
-.PP
+.P
.I flags
must be 0.
.SH RETURN VALUE
.nf
.BR "#include <linux/landlock.h>" " /* Definition of " LANDLOCK_* " constants */"
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
-.PP
+.P
.B int syscall(SYS_landlock_create_ruleset,
.BI " const struct landlock_ruleset_attr *" attr ,
.BI " size_t " size " , uint32_t " flags );
See
.BR landlock (7)
for a global overview.
-.PP
+.P
.I attr
specifies the properties of the new ruleset.
It points to the following structure:
.BR landlock (7)).
This enables simply restricting ambient rights
(e.g., global filesystem access) and is needed for compatibility reasons.
-.PP
+.P
.I size
must be specified as
.I sizeof(struct landlock_ruleset_attr)
for compatibility reasons.
-.PP
+.P
.I flags
must be 0 if
.I attr
.nf
.BR "#include <linux/landlock.h>" " /* Definition of " LANDLOCK_* " constants */"
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
-.PP
+.P
.BI "int syscall(SYS_landlock_restrict_self, int " ruleset_fd ,
.BI " uint32_t " flags );
.SH DESCRIPTION
See
.BR landlock (7)
for a global overview.
-.PP
+.P
A thread can be restricted with multiple rulesets that are then
composed together to form the thread's Landlock domain.
This can be seen as a stack of rulesets but
Instead, developers are encouraged to build a tailored ruleset thanks to
multiple calls to
.BR landlock_add_rule (2).
-.PP
+.P
In order to enforce a ruleset, either the caller must have the
.B CAP_SYS_ADMIN
capability in its user namespace, or the thread must already have the
.EX
prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0);
.EE
-.PP
+.P
.I ruleset_fd
is a Landlock ruleset file descriptor obtained with
.BR landlock_create_ruleset (2)
and fully populated with a set of calls to
.BR landlock_add_rule (2).
-.PP
+.P
.I flags
must be 0.
.SH RETURN VALUE
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.BI "int link(const char *" oldpath ", const char *" newpath );
-.PP
+.P
.BR "#include <fcntl.h> " "/* Definition of " AT_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "int linkat(int " olddirfd ", const char *" oldpath ,
.BI " int " newdirfd ", const char *" newpath ", int " flags );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR linkat ():
.nf
Since glibc 2.10:
.SH DESCRIPTION
.BR link ()
creates a new link (also known as a hard link) to an existing file.
-.PP
+.P
If
.I newpath
exists, it will
.I not
be overwritten.
-.PP
+.P
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
system call operates in exactly the same way as
.BR link (),
except for the differences described here.
-.PP
+.P
If the pathname given in
.I oldpath
is relative, then it is interpreted relative to the directory
the calling process, as is done by
.BR link ()
for a relative pathname).
-.PP
+.P
If
.I oldpath
is relative and
is interpreted relative to the current working
directory of the calling process (like
.BR link ()).
-.PP
+.P
If
.I oldpath
is absolute, then
.I olddirfd
is ignored.
-.PP
+.P
The interpretation of
.I newpath
is as for
except that a relative pathname is interpreted relative
to the directory referred to by the file descriptor
.IR newdirfd .
-.PP
+.P
The following values can be bitwise ORed in
.IR flags :
.TP
newname, AT_SYMLINK_FOLLOW);
.EE
.in
-.PP
+.P
Before Linux 2.6.18, the
.I flags
argument was unused, and had to be specified as 0.
-.PP
+.P
See
.BR openat (2)
for an explanation of the need for
.BR link ()
does not work across different mounts,
even if the same filesystem is mounted on both.)
-.PP
+.P
The following additional errors can occur for
.BR linkat ():
.TP
.SH SYNOPSIS
.nf
.B #include <sys/socket.h>
-.PP
+.P
.BI "int listen(int " sockfd ", int " backlog );
.fi
.SH DESCRIPTION
as a passive socket, that is, as a socket that will
be used to accept incoming connection requests using
.BR accept (2).
-.PP
+.P
The
.I sockfd
argument is a file descriptor that refers to a socket of type
.B SOCK_STREAM
or
.BR SOCK_SEQPACKET .
-.PP
+.P
The
.I backlog
argument defines the maximum length
Connections are accepted with
.BR accept (2).
.RE
-.PP
+.P
The behavior of the
.I backlog
argument on TCP sockets changed with Linux 2.2.
See
.BR tcp (7)
for more information.
-.PP
+.P
If the
.I backlog
argument is greater than the value in
.SH SYNOPSIS
.nf
.B #include <sys/xattr.h>
-.PP
+.P
.BI "ssize_t listxattr(const char *" path ", char *_Nullable " list \
", size_t " size );
.BI "ssize_t llistxattr(const char *" path ", char *_Nullable " list \
data).
A complete overview of extended attributes concepts can be found in
.BR xattr (7).
-.PP
+.P
.BR listxattr ()
retrieves the list
of extended attribute names associated with the given
The length of the attribute name
.I list
is returned.
-.PP
+.P
.BR llistxattr ()
is identical to
.BR 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.
-.PP
+.P
.BR flistxattr ()
is identical to
.BR listxattr (),
.BR open (2))
is interrogated in place of
.IR path .
-.PP
+.P
A single extended attribute
.I name
is a null-terminated string.
The name includes a namespace prefix; there may be several, disjoint
namespaces associated with an individual inode.
-.PP
+.P
If
.I size
is specified as zero, these calls return the current size of the
of names is returned as an unordered array of null-terminated character strings
(attribute names are separated by null bytes (\[aq]\e0\[aq])),
like this:
-.PP
+.P
.in +4n
.EX
user.name1\e0system.name1\e0user.name2\e0
.EE
.in
-.PP
+.P
Filesystems that implement POSIX ACLs using
extended attributes might return a
.I list
like this:
-.PP
+.P
.in +4n
.EX
system.posix_acl_access\e0system.posix_acl_default\e0
of the
.I list
buffer is too small to hold the result.
-.PP
+.P
In addition, the errors documented in
.BR stat (2)
can also occur.
.BR getxattr (2).
For the file whose pathname is provided as a command-line argument,
it lists all extended file attributes and their values.
-.PP
+.P
To keep the code simple, the program assumes that attribute keys and
values are constant during the execution of the program.
A production program should expect and handle changes during
Calls to
.BR getxattr (2)
could be handled similarly.
-.PP
+.P
The following output was recorded by first creating a file, setting
some extended file attributes,
and then listing the attributes with the example program.
.nf
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "int syscall(SYS__llseek, unsigned int " fd ", unsigned long " offset_high ,
.BI " unsigned long " offset_low ", loff_t *" result ,
.BI " unsigned int " whence );
.fi
-.PP
+.P
.IR Note :
glibc provides no wrapper for
.BR _llseek (),
.BR llseek (3)
library function, see
.BR lseek64 (3).
-.PP
+.P
The
.BR _llseek ()
system call repositions the offset of the open file description associated
to the value
.IP
(offset_high << 32) | offset_low
-.PP
+.P
This new offset is a byte offset
relative to the beginning of the file, the current file offset,
or the end of the file, depending on whether
or
.BR SEEK_END ,
respectively.
-.PP
+.P
The new file offset is returned in the argument
.IR result .
The type
.I loff_t
is a 64-bit signed type.
-.PP
+.P
This system call exists on various 32-bit platforms to support
seeking to large file offsets.
.SH RETURN VALUE
.nf
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "int syscall(SYS_lookup_dcookie, uint64_t " cookie ", char *" buffer ,
.BI " size_t " len );
.fi
-.PP
+.P
.IR Note :
glibc provides no wrapper for
.BR lookup_dcookie (),
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.
-.PP
+.P
For
.BR lookup_dcookie ()
to return successfully,
Linux.
.SH HISTORY
Linux 2.5.43.
-.PP
+.P
The
.B ENAMETOOLONG
error was added in Linux 2.5.70.
.BR oprofile (1)
profiler.
It relies on a kernel driver to register cookies for directory entries.
-.PP
+.P
The path returned may be suffixed by the string " (deleted)" if the directory
entry has been removed.
.SH SEE ALSO
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.BI "off_t lseek(int " fd ", off_t " offset ", int " whence );
.fi
.SH DESCRIPTION
The file offset is set to the size of the file plus
.I offset
bytes.
-.PP
+.P
.BR lseek ()
allows the file offset to be set beyond the end
of the file (but this does not change the size of the file).
.IR 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).
-.PP
+.P
In both of the above cases,
.BR lseek ()
fails if
.I offset
points past the end of the file.
-.PP
+.P
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.
-.PP
+.P
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 filesystem is not obliged to report holes,
.\" https://lkml.org/lkml/2011/4/22/79
.\" http://lwn.net/Articles/440255/
.\" http://blogs.oracle.com/bonwick/entry/seek_hole_and_seek_data
-.PP
+.P
The
.B _GNU_SOURCE
feature test macro must be defined in order to obtain the definitions of
.B SEEK_HOLE
from
.IR <unistd.h> .
-.PP
+.P
The
.B SEEK_HOLE
and
POSIX.1-2008.
.SH HISTORY
POSIX.1-2001, SVr4, 4.3BSD.
-.PP
+.P
.B SEEK_DATA
and
.B SEEK_HOLE
.BR open (2)
for a discussion of the relationship between file descriptors,
open file descriptions, and files.
-.PP
+.P
If the
.B O_APPEND
file status flag is set on the open file description,
.I always
moves the file offset to the end of the file, regardless of the use of
.BR lseek ().
-.PP
+.P
Some devices are incapable of seeking and POSIX does not specify which
devices must support
.BR lseek ().
.SH SYNOPSIS
.nf
.B #include <sys/mman.h>
-.PP
+.P
.BI "int madvise(void " addr [. length "], size_t " length ", int " advice );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR madvise ():
.nf
Since glibc 2.19:
is rounded up to a multiple of page size.
In most cases,
the goal of such advice is to improve system or application performance.
-.PP
+.P
Initially, the system call supported a set of "conventional"
.I advice
values, which are also available on several other implementations.
.BR posix_madvise (3)
function, and the values have the same meanings, with the exception of
.BR MADV_DONTNEED .
-.PP
+.P
The advice is indicated in the
.I advice
argument, which is one of the following:
above under
.IR "Conventional advice flags" ,
albeit with some variation in semantics.
-.PP
+.P
POSIX.1-2001 describes
.BR posix_madvise (3)
with constants
ignores them and applies the call to the rest (but returns
.B ENOMEM
from the system call, as it should).
-.PP
+.P
.I madvise(0,\ 0,\ advice)
will return zero iff
.I advice
None.
.SH HISTORY
First appeared in 4.4BSD.
-.PP
+.P
Since Linux 3.18,
.\" commit d3ac21cacc24790eb45d735769f35753f5b56ceb
support for this system call is optional,
.SH SYNOPSIS
.nf
.B "#include <numaif.h>"
-.PP
+.P
.BI "long mbind(void " addr [. len "], unsigned long " len ", int " mode ,
.BI " const unsigned long " nodemask [(. maxnode " + ULONG_WIDTH - 1)"
.B " / ULONG_WIDTH],"
.I len
bytes.
The memory policy defines from which node memory is allocated.
-.PP
+.P
If the memory range specified by the
.IR addr " and " len
arguments includes an "anonymous" region of memory\[em]that is
memory policy of the thread that causes the page to be allocated.
This may not be the thread that called
.BR mbind ().
-.PP
+.P
The specified policy will be ignored for any
.B MAP_SHARED
mappings in the specified memory range.
of the thread that caused the page to be allocated.
Again, this may not be the thread that called
.BR mbind ().
-.PP
+.P
If the specified memory range includes a shared memory region
created using the
.BR shmget (2)
only if the page allocation is caused by the process that calls
.BR mbind ()
for that region.
-.PP
+.P
By default,
.BR mbind ()
has an effect only for new allocations; if the pages inside
and
.B MPOL_MF_MOVE_ALL
flags described below.
-.PP
+.P
The
.I mode
argument must specify one of
via the
.I nodemask
argument.
-.PP
+.P
The
.I mode
argument may also include an optional
.I nodemask
specifies node IDs that are relative to the set of
node IDs allowed by the thread's current cpuset.
-.PP
+.P
.I nodemask
points to a bit mask of nodes containing up to
.I maxnode
.B MPOL_F_STATIC_NODES
mode flag is specified),
and contains memory.
-.PP
+.P
The
.I mode
argument must include one of the following values:
reverts to the memory policy of the thread (which may be set via
.BR set_mempolicy (2));
that policy may be something other than "local allocation".
-.PP
+.P
If
.B MPOL_MF_STRICT
is passed in
.\" --Lee Schermerhorn
.\" In Linux 2.6.16 or later the kernel will also try to move pages
.\" to the requested node with this flag.
-.PP
+.P
If
.B MPOL_MF_MOVE
is specified in
policy was specified,
pages already residing on the specified nodes
will not be moved such that they are interleaved.
-.PP
+.P
If
.B MPOL_MF_MOVE_ALL
is passed in
Linux.
.SH HISTORY
Linux 2.6.7.
-.PP
+.P
Support for huge page policy was added with Linux 2.6.16.
For interleave policy to be effective on huge page mappings the
policied memory needs to be tens of megabytes or larger.
-.PP
+.P
Before Linux 5.7.
.\" commit dcf1763546d76c372f3136c8d6b2b6e77f140cf0
.B MPOL_MF_STRICT
was ignored on huge page mappings.
-.PP
+.P
.B MPOL_MF_MOVE
and
.B MPOL_MF_MOVE_ALL
.SH NOTES
For information on library support, see
.BR numa (7).
-.PP
+.P
NUMA policy is not supported on a memory-mapped file range
that was mapped with the
.B MAP_SHARED
flag.
-.PP
+.P
The
.B MPOL_DEFAULT
mode can have different effects for
.RI ( libc ", " \-lc )
.SH SYNOPSIS
.nf
-.PP
+.P
.BR "#include <linux/membarrier.h>" \
" /* Definition of " MEMBARRIER_* " constants */"
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "int syscall(SYS_membarrier, int " cmd ", unsigned int " flags \
", int " cpu_id );
.fi
-.PP
+.P
.IR Note :
glibc provides no wrapper for
.BR membarrier (),
.I not
as simple as replacing memory barriers with this
system call, but requires understanding of the details below.
-.PP
+.P
Use of memory barriers needs to be done taking into account that a
memory barrier always needs to be either matched with its memory barrier
counterparts, or that the architecture's memory model doesn't require the
matching barriers.
-.PP
+.P
There are cases where one side of the matching barriers (which we will
refer to as "fast side") is executed much more often than the other
(which we will refer to as "slow side").
The key idea is to replace, for these matching
barriers, the fast-side memory barriers by simple compiler barriers,
for example:
-.PP
+.P
.in +4n
.EX
asm volatile ("" : : : "memory")
.EE
.in
-.PP
+.P
and replace the slow-side memory barriers by calls to
.BR membarrier ().
-.PP
+.P
This will add overhead to the slow side, and remove overhead from the
fast side, thus resulting in an overall performance increase as long as
the slow side is infrequent enough that the overhead of the
.BR membarrier ()
calls does not outweigh the performance gain on the fast side.
-.PP
+.P
The
.I cmd
argument is one of the following:
This is an alias for
.B MEMBARRIER_CMD_GLOBAL
that exists for header backward compatibility.
-.PP
+.P
The
.I flags
argument must be specified as 0 unless the command is
.I flags
can be either 0 or
.BR MEMBARRIER_CMD_FLAG_CPU .
-.PP
+.P
The
.I cpu_id
argument is ignored unless
.BR MEMBARRIER_CMD_FLAG_CPU ,
in which case it must specify the CPU targeted by this membarrier
command.
-.PP
+.P
All memory accesses performed in program order from each targeted thread
are guaranteed to be ordered with respect to
.BR membarrier ().
-.PP
+.P
If we use the semantic
.I barrier()
to represent a compiler barrier forcing memory
and
.IR smp_mb() .
The pair ordering is detailed as (O: ordered, X: not ordered):
-.PP
+.P
.RS
.TS
l c c c.
and
.I errno
is set to indicate the error.
-.PP
+.P
For a given command, with
.I flags
set to 0, this system call is
Linux.
.SH HISTORY
Linux 4.3.
-.PP
+.P
Before Linux 5.10, the prototype was:
-.PP
+.P
.in +4n
.EX
.BI "int membarrier(int " cmd ", int " flags );
For instance, a load fence can order
loads prior to and following that fence with respect to stores ordered
by store fences.
-.PP
+.P
Program order is the order in which instructions are ordered in the
program assembly code.
-.PP
+.P
Examples where
.BR membarrier ()
can be useful include implementations
very frequently, and where "slow_path()" is executed infrequently, the
following code (x86) can be transformed using
.BR membarrier ():
-.PP
+.P
.in +4n
.\" SRC BEGIN (membarrier.c)
.EX
.EE
.\" SRC END
.in
-.PP
+.P
The code above transformed to use
.BR membarrier ()
becomes:
-.PP
+.P
.in +4n
.EX
#define _GNU_SOURCE
.nf
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <sys/mman.h>
-.PP
+.P
.BI "int memfd_create(const char *" name ", unsigned int " flags ");"
.fi
.SH DESCRIPTION
with the
.B MAP_ANONYMOUS
flag.
-.PP
+.P
The initial size of the file is set to 0.
Following the call, the file size should be set using
.BR ftruncate (2).
(Alternatively, the file may be populated by calls to
.BR write (2)
or similar.)
-.PP
+.P
The name supplied in
.I name
is used as a filename and will be displayed
and serves only for debugging purposes.
Names do not affect the behavior of the file descriptor,
and as such multiple files can have the same name without any side effects.
-.PP
+.P
The following values may be bitwise ORed in
.I flags
to change the behavior of
For details on encoding huge page sizes not included in the header file,
see the discussion of the similarly named constants in
.BR mmap (2).
-.PP
+.P
Unused bits in
.I flags
must be 0.
-.PP
+.P
As its return value,
.BR memfd_create ()
returns a new file descriptor that can be used to refer to the file.
and
.B O_LARGEFILE
is set for the file descriptor.
-.PP
+.P
With respect to
.BR fork (2)
and
is to create files and associated file descriptors that are
used with the file-sealing APIs provided by
.BR fcntl (2).
-.PP
+.P
The
.BR memfd_create ()
system call also has uses without file sealing
(Dealing with this possibility necessitates the use of a handler for the
.B SIGBUS
signal.)
-.PP
+.P
Dealing with untrusted peers imposes extra complexity on
code that employs shared memory.
Memory sealing enables that extra complexity to be eliminated,
by allowing a process to operate secure in the knowledge that
its peer can't modify the shared memory in an undesired fashion.
-.PP
+.P
An example of the usage of the sealing mechanism is as follows:
.IP (1) 5
The first process creates a
Below are shown two example programs that demonstrate the use of
.BR memfd_create ()
and the file sealing API.
-.PP
+.P
The first program,
.IR t_memfd_create.c ,
creates a
the second argument is the size to be set for the file,
and the optional third argument is a string of characters that specify
seals to be set on the file.
-.PP
+.P
The second program,
.IR t_get_seals.c ,
can be used to open an existing file that was created via
.BR memfd_create ()
and inspect the set of seals that have been applied to that file.
-.PP
+.P
The following shell session demonstrates the use of these programs.
First we create a
.BR tmpfs (5)
file and set some seals on it:
-.PP
+.P
.in +4n
.EX
$ \fB./t_memfd_create my_memfd_file 4096 sw &\fP
PID: 11775; fd: 3; /proc/11775/fd/3
.EE
.in
-.PP
+.P
At this point, the
.I t_memfd_create
program continues to run in the background.
symbolic link, and use our
.I t_get_seals
program to view the seals that have been placed on the file:
-.PP
+.P
.in +4n
.EX
$ \fBreadlink /proc/11775/fd/3\fP
.RI ( libc ", " \-lc )
.SH SYNOPSIS
.nf
-.PP
+.P
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "int syscall(SYS_memfd_secret, unsigned int " flags );
.fi
-.PP
+.P
.IR Note :
glibc provides no wrapper for
.BR memfd_secret (),
The initial size of the file is set to 0.
Following the call, the file size should be set using
.BR ftruncate (2).
-.PP
+.P
The memory areas backing the file created with
.BR memfd_secret (2)
are visible only to the processes that have access to the file descriptor.
(Thus, the pages in the region can't be accessed by the kernel itself,
so that, for example, pointers to the region can't be passed to
system calls.)
-.PP
+.P
The following values may be bitwise ORed in
.I flags
to control the behavior of
.B O_CLOEXEC
flag in
.BR open (2)
-.PP
+.P
As its return value,
.BR memfd_secret ()
returns a new file descriptor that refers to an anonymous file.
and
.B O_LARGEFILE
is set for the file descriptor.
-.PP
+.P
With respect to
.BR fork (2)
and
The file descriptor is preserved across
.BR execve (2),
unless the close-on-exec flag has been set.
-.PP
+.P
The memory region is locked into memory in the same way as with
.BR mlock (2),
so that it will never be written into swap,
.BR memfd_secret ()
in any circumstances, but nevertheless,
it is much harder to exfiltrate data from these regions.
-.PP
+.P
.BR memfd_secret ()
provides the following protections:
.IP \[bu] 3
or spawn a new privileged user-space process to perform
secrets exfiltration using
.BR ptrace (2).
-.PP
+.P
The way
.BR memfd_secret ()
allocates and locks the memory may impact overall system performance,
therefore the system call is disabled by default and only available
if the system administrator turned it on using
"secretmem.enable=y" kernel parameter.
-.PP
+.P
To prevent potential data leaks of memory regions backed by
.BR memfd_secret ()
from a hybernation image,
.SH SYNOPSIS
.nf
.B #include <numaif.h>
-.PP
+.P
.BI "long migrate_pages(int " pid ", unsigned long " maxnode,
.BI " const unsigned long *" old_nodes,
.BI " const unsigned long *" new_nodes );
.I old_nodes
during the migration to
.IR new_nodes .
-.PP
+.P
The
.I old_nodes
and
.BR mbind (2),
but different from
.BR select (2)).
-.PP
+.P
The
.I pid
argument is the ID of the process whose pages are to be moved.
is 0, then
.BR migrate_pages ()
moves pages of the calling process.
-.PP
+.P
Pages shared with another process will be moved only if the initiating
process has the
.B CAP_SYS_NICE
.SH NOTES
For information on library support, see
.BR numa (7).
-.PP
+.P
Use
.BR get_mempolicy (2)
with the
the calling process's cpuset.
Note that this information is subject to change at any
time by manual or automatic reconfiguration of the cpuset.
-.PP
+.P
Use of
.BR migrate_pages ()
may result in pages whose location
That is, memory policy does not constrain the destination
nodes used by
.BR migrate_pages ().
-.PP
+.P
The
.I <numaif.h>
header is not included with glibc, but requires installing
.BR numa (7),
.BR migratepages (8),
.BR numastat (8)
-.PP
+.P
.I Documentation/vm/page_migration.rst
in the Linux kernel source tree
.SH SYNOPSIS
.nf
.B #include <sys/mman.h>
-.PP
+.P
.BI "int mincore(void " addr [. length "], size_t " length ", unsigned char *" vec );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR mincore ():
.nf
Since glibc 2.19:
and continuing for
.I length
bytes.
-.PP
+.P
The
.I addr
argument must be a multiple of the system page size.
.RB ( PAGE_SIZE )
using
.IR sysconf(_SC_PAGESIZE) .
-.PP
+.P
The
.I vec
argument must point to an array containing at least
.SH HISTORY
Linux 2.3.99pre1,
glibc 2.2.
-.PP
+.P
First appeared in 4.4BSD.
-.PP
+.P
NetBSD, FreeBSD, OpenBSD, Solaris 8,
AIX 5.1, SunOS 4.1.
.SH BUGS
.nf
.B #include <sys/stat.h>
.\" .B #include <unistd.h>
-.PP
+.P
.BI "int mkdir(const char *" pathname ", mode_t " mode );
-.PP
+.P
.BR "#include <fcntl.h> " "/* Definition of AT_* constants */"
.B #include <sys/stat.h>
-.PP
+.P
.BI "int mkdirat(int " dirfd ", const char *" pathname ", mode_t " mode );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR mkdirat ():
.nf
Since glibc 2.10:
.BR mkdir ()
attempts to create a directory named
.IR pathname .
-.PP
+.P
The argument
.I mode
specifies the mode for the new directory (see
.I mode
bits are honored for the created directory depends on the operating system.
For Linux, see NOTES below.
-.PP
+.P
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
.IR "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.
-.PP
+.P
If the parent directory has the set-group-ID bit set, then so will the
newly created directory.
.\"
system call operates in exactly the same way as
.BR mkdir (),
except for the differences described here.
-.PP
+.P
If the pathname given in
.I pathname
is relative, then it is interpreted relative to the directory
the calling process, as is done by
.BR mkdir ()
for a relative pathname).
-.PP
+.P
If
.I pathname
is relative and
is interpreted relative to the current working
directory of the calling process (like
.BR mkdir ()).
-.PP
+.P
If
.I pathname
is absolute, then
.I dirfd
is ignored.
-.PP
+.P
See
.BR openat (2)
for an explanation of the need for
.SH SYNOPSIS
.nf
.B #include <sys/stat.h>
-.PP
+.P
.BI "int mknod(const char *" pathname ", mode_t " mode ", dev_t " dev );
-.PP
+.P
.BR "#include <fcntl.h> " "/* Definition of AT_* constants */"
.B #include <sys/stat.h>
-.PP
+.P
.BI "int mknodat(int " dirfd ", const char *" pathname ", mode_t " mode \
", dev_t " dev );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR mknod ():
.nf
_XOPEN_SOURCE >= 500
.I mode
and
.IR dev .
-.PP
+.P
The
.I mode
argument specifies both the file mode to use and the type of node
It should be a combination (using bitwise OR) of one of the file types
listed below and zero or more of the file mode bits listed in
.BR inode (7).
-.PP
+.P
The file mode is modified by the process's
.I umask
in the usual way: in the absence of a default ACL, the permissions of the
created node are
.RI ( mode " & \[ti]" umask ).
-.PP
+.P
The file type must be one of
.BR S_IFREG ,
.BR S_IFCHR ,
respectively.
(Zero file type is equivalent to type
.BR S_IFREG .)
-.PP
+.P
If the file type is
.B S_IFCHR
or
may be useful to build the value for
.IR dev );
otherwise it is ignored.
-.PP
+.P
If
.I pathname
already exists, or is a symbolic link, this call fails with an
.B EEXIST
error.
-.PP
+.P
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
system call operates in exactly the same way as
.BR mknod (),
except for the differences described here.
-.PP
+.P
If the pathname given in
.I pathname
is relative, then it is interpreted relative to the directory
the calling process, as is done by
.BR mknod ()
for a relative pathname).
-.PP
+.P
If
.I pathname
is relative and
is interpreted relative to the current working
directory of the calling process (like
.BR mknod ()).
-.PP
+.P
If
.I pathname
is absolute, then
.I dirfd
is ignored.
-.PP
+.P
See
.BR openat (2)
for an explanation of the need for
for this purpose; one should use
.BR mkfifo (3),
a function especially defined for this purpose.
-.PP
+.P
Under Linux,
.BR mknod ()
cannot be used to create directories.
.SH SYNOPSIS
.nf
.B #include <sys/mman.h>
-.PP
+.P
.BI "int mlock(const void " addr [. len "], size_t " len );
.BI "int mlock2(const void " addr [. len "], size_t " len ", \
unsigned int " flags );
.BI "int munlock(const void " addr [. len "], size_t " len );
-.PP
+.P
.BI "int mlockall(int " flags );
.B int munlockall(void);
.fi
lock part or all of the calling process's virtual address
space into RAM, preventing that memory from being paged to the
swap area.
-.PP
+.P
.BR munlock ()
and
.BR munlockall ()
unlocking part or all of the calling process's virtual address space,
so that pages in the specified virtual address range
can be swapped out again if required by the kernel memory manager.
-.PP
+.P
Memory locking and unlocking are performed in units of whole pages.
.SS mlock(), mlock2(), and munlock()
.BR mlock ()
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.
-.PP
+.P
.BR mlock2 ()
.\" commit a8ca5d0ecbdde5cc3d7accacbd69968b0c98764e
.\" commit de60f5f10c58d4f34b68622442c0e04180367f3f
returns successfully will depend on the value in the
.I flags
argument.
-.PP
+.P
The
.I flags
argument can be either 0 or the following constant:
Lock pages that are currently resident and mark the entire range so
that the remaining nonresident pages are locked when they are populated
by a page fault.
-.PP
+.P
If
.I flags
is 0,
.BR mlock2 ()
behaves exactly the same as
.BR mlock ().
-.PP
+.P
.BR munlock ()
unlocks pages in the address range starting at
.I addr
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.
-.PP
+.P
The
.I flags
argument is constructed as the bitwise OR of one or more of the
or
.B MCL_FUTURE
or both.
-.PP
+.P
If
.B MCL_FUTURE
has been specified, then a later system call (e.g.,
the kernel will deny stack expansion and deliver a
.B SIGSEGV
signal to the process.
-.PP
+.P
.BR munlockall ()
unlocks all pages mapped into the address space of the
calling process.
allows an implementation to require that
.I addr
is page aligned, so portable applications should ensure this.
-.PP
+.P
The
.I VmLck
field of the Linux-specific
.TP
.BR mlock2 ()
Linux.
-.PP
+.P
On POSIX systems on which
.BR mlock ()
and
.B PAGESIZE
(if defined) in \fI<limits.h>\fP or by calling
.IR sysconf(_SC_PAGESIZE) .
-.PP
+.P
On POSIX systems on which
.BR mlockall ()
and
(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.)
-.PP
+.P
Real-time processes that are using
.BR mlockall ()
to prevent delays on page faults should reserve enough
locked into RAM.
The dummy writes ensure that not even copy-on-write
page faults can occur in the critical section.
-.PP
+.P
Memory locks are not inherited by a child created via
.BR fork (2)
and are automatically removed (unlocked) during an
.BR fork (2)
and are cleared during an
.BR execve (2).
-.PP
+.P
Note that
.BR fork (2)
will prepare the address space for a copy-on-write operation.
.BR mlock ()
operation\[em]not even from a thread which runs at a low priority within
a process which also has a thread running at elevated priority.
-.PP
+.P
The memory lock on an address range is automatically removed
if the address range is unmapped via
.BR munmap (2).
-.PP
+.P
Memory locks do not stack, that is, pages which have been locked several times
by calls to
.BR mlock (),
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.
-.PP
+.P
If a call to
.BR mlockall ()
which uses the
changes made by the
.B MCL_FUTURE
call will be lost.
-.PP
+.P
The
.BR mlock2 ()
.B MLOCK_ONFAULT
in order to lock memory and the
.B RLIMIT_MEMLOCK
soft resource limit defines a limit on how much memory the process may lock.
-.PP
+.P
Since Linux 2.6.9, no limits are placed on the amount of memory
that a privileged process can lock and the
.B RLIMIT_MEMLOCK
This bug was fixed
.\" commit 0cf2f6f6dc605e587d2c1120f295934c77e810e8
in Linux 4.9.
-.PP
+.P
In Linux 2.4 series of kernels up to and including Linux 2.4.17,
a bug caused the
.BR mlockall ()
flag to be inherited across a
.BR fork (2).
This was rectified in Linux 2.4.18.
-.PP
+.P
Since Linux 2.6.9, if a privileged process calls
.I mlockall(MCL_FUTURE)
and later drops privileges (loses the
.SH SYNOPSIS
.nf
.B #include <sys/mman.h>
-.PP
+.P
.BI "void *mmap(void " addr [. length "], size_t " length \
", int " prot ", int " flags ,
.BI " int " fd ", off_t " offset );
.BI "int munmap(void " addr [. length "], size_t " length );
.fi
-.PP
+.P
See NOTES for information on feature test macro requirements.
.SH DESCRIPTION
.BR mmap ()
The
.I length
argument specifies the length of the mapping (which must be greater than 0).
-.PP
+.P
If
.I addr
is NULL,
.\" Before Linux 2.6.24, the address was rounded up to the next page
.\" boundary; since Linux 2.6.24, it is rounded down!
The address of the new mapping is returned as the result of the call.
-.PP
+.P
The contents of a file mapping (as opposed to an anonymous mapping; see
.B MAP_ANONYMOUS
below), are initialized using
.I offset
must be a multiple of the page size as returned by
.IR sysconf(_SC_PAGE_SIZE) .
-.PP
+.P
After the
.BR mmap ()
call has returned, the file descriptor,
.IR fd ,
can be closed immediately without invalidating the mapping.
-.PP
+.P
The
.I prot
argument describes the desired memory protection of the mapping
It is unspecified whether changes made to the file after the
.BR mmap ()
call are visible in the mapped region.
-.PP
+.P
Both
.B MAP_SHARED
and
are described in POSIX.1-2001 and POSIX.1-2008.
.B MAP_SHARED_VALIDATE
is a Linux extension.
-.PP
+.P
In addition, zero or more of the following values can be ORed in
.IR flags :
.TP
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).
-.PP
+.P
Of the above flags, only
.B MAP_FIXED
is specified in POSIX.1-2001 and POSIX.1-2008.
when the process is terminated.
On the other hand, closing the file
descriptor does not unmap the region.
-.PP
+.P
The address
.I addr
must be a multiple of the page size (but
is returned, and
.I errno
is set to indicate the error.
-.PP
+.P
On success,
.BR munmap ()
returns 0.
was set but the object specified by
.I fd
is open for writing.
-.PP
+.P
Use of a mapped region can result in these signals:
.TP
.B SIGSEGV
Portable programs should always set
.B PROT_EXEC
if they intend to execute code in the new mapping.
-.PP
+.P
The portable way to create a mapping is to specify
.I addr
as 0 (NULL), and omit
flag is specified, and
.I addr
is 0 (NULL), then the mapped address will be 0 (NULL).
-.PP
+.P
Certain
.I flags
constants are defined only if suitable feature test macros are defined
POSIX.1-2001, SVr4, 4.4BSD.
.\" SVr4 documents additional error codes ENXIO and ENODEV.
.\" SUSv2 documents additional error codes EMFILE and EOVERFLOW.
-.PP
+.P
On POSIX systems on which
.BR mmap (),
.BR msync (2),
is preserved across
.BR fork (2),
with the same attributes.
-.PP
+.P
A file is mapped in multiples of the page size.
For a file that is not
a multiple of the page size,
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.
-.PP
+.P
An application can determine which pages of a mapping are
currently resident in the buffer/page cache using
.BR mincore (2).
.B MAP_FIXED
is hazardous because it forcibly removes preexisting mappings,
making it easy for a multithreaded process to corrupt its own address space.
-.PP
+.P
For example, suppose that thread A looks through
.IR /proc/ pid /maps
in order to locate an unused address range that it can map using
and the PAM libraries
.UR http://www.linux-pam.org
.UE .
-.PP
+.P
Since Linux 4.17, a multithreaded program can use the
.B MAP_FIXED_NOREPLACE
flag to avoid the hazard described above
.BR mmap ()
and the corresponding unmapping; the first reference to a mapped
page will update the field if it has not been already.
-.PP
+.P
The
.I st_ctime
and
.BR munmap ()
differ somewhat from the requirements for mappings
that use the native system page size.
-.PP
+.P
For
.BR mmap (),
.I offset
The system automatically aligns
.I length
to be a multiple of the underlying huge page size.
-.PP
+.P
For
.BR munmap (),
.IR addr ,
.BR MAP_NORESERVE .
By default, any process can be killed
at any moment when the system runs out of memory.
-.PP
+.P
Before Linux 2.6.7, the
.B MAP_POPULATE
flag has effect only if
.I prot
is specified as
.BR PROT_NONE .
-.PP
+.P
SUSv3 specifies that
.BR mmap ()
should fail if
fails with the error
.B EINVAL
for this case.
-.PP
+.P
POSIX specifies that the system shall always
zero fill any partial page at the end
of the object and that system will never write any modification of the
.BR userfaultfd (2),
.BR shm_open (3),
.BR shm_overview (7)
-.PP
+.P
The descriptions of the following files in
.BR proc (5):
.IR /proc/ pid /maps ,
.IR /proc/ pid /map_files ,
and
.IR /proc/ pid /smaps .
-.PP
+.P
B.O. Gallmeister, POSIX.4, O'Reilly, pp. 128\[en]129 and 389\[en]391.
.\"
.\" Repeat after me: private read-only mappings are 100% equivalent to
.BR "#include <sys/mman.h>" " /* Definition of " MAP_* " and " PROT_* " constants */"
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "void *syscall(SYS_mmap2, unsigned long " addr ", unsigned long " length ,
.BI " unsigned long " prot ", unsigned long " flags ,
.BI " unsigned long " fd ", unsigned long " pgoffset );
This is probably not the system call that you are interested in; instead, see
.BR mmap (2),
which describes the glibc wrapper function that invokes this system call.
-.PP
+.P
The
.BR mmap2 ()
system call provides the same interface as
(Various platforms where the page size is not 4096 bytes.)
.I "offset\ *\ 4096"
is not a multiple of the system page size.
-.PP
+.P
.BR mmap2 ()
can also return any of the errors described in
.BR mmap (2).
wrapper function invokes this system call rather than the
.BR mmap (2)
system call.
-.PP
+.P
This system call does not exist on x86-64.
-.PP
+.P
On ia64, the unit for
.I offset
is actually the system page size, rather than 4096 bytes.
.BR "#include <asm/ldt.h>" " /* Definition of " "struct user_desc" " */"
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "int syscall(SYS_modify_ldt, int " func ", void " ptr [. bytecount ],
.BI " unsigned long " bytecount );
.fi
-.PP
+.P
.IR Note :
glibc provides no wrapper for
.BR modify_ldt (),
Linux allows processes to configure a per-process (actually per-mm) LDT.
For more information about the LDT, see the Intel Software Developer's
Manual or the AMD Architecture Programming Manual.
-.PP
+.P
When
.I func
is 0,
On success,
.BR modify_ldt ()
will return the number of bytes read.
-.PP
+.P
When
.I func
is 1 or 0x11,
and
.I bytecount
must equal the size of this structure.
-.PP
+.P
The
.I user_desc
structure is defined in \fI<asm/ldt.h>\fP as:
-.PP
+.P
.in +4n
.EX
struct user_desc {
};
.EE
.in
-.PP
+.P
In Linux 2.4 and earlier, this structure was named
.IR modify_ldt_ldt_s .
-.PP
+.P
The
.I contents
field is the segment type (data, expand-down data, non-conforming code, or
The other fields match their descriptions in the CPU manual, although
.BR modify_ldt ()
cannot set the hardware-defined "accessed" bit described in the CPU manual.
-.PP
+.P
A
.I user_desc
is considered "empty" if
and
.I limit
to 0.
-.PP
+.P
A conforming code segment (i.e., one with
.IR contents==3 )
will be rejected if
is 1 or if
.I seg_not_present
is 0.
-.PP
+.P
When
.I func
is 2,
.BR arch_prctl (2)
instead, except on extremely old kernels that do not support those system
calls.
-.PP
+.P
The normal use for
.BR modify_ldt ()
is to run legacy 16-bit or segmented 32-bit code.
Not all kernels allow 16-bit segments to be installed, however.
-.PP
+.P
Even on 64-bit kernels,
.BR modify_ldt ()
cannot be used to create a long mode (i.e., 64-bit) code segment.
.SH SYNOPSIS
.nf
.B "#include <sys/mount.h>"
-.PP
+.P
.BI "int mount(const char *" source ", const char *" target ,
.BI " const char *" filesystemtype ", unsigned long " mountflags ,
.BI " const void *_Nullable " data );
or a dummy string) to the location (a directory or file)
specified by the pathname in
.IR target .
-.PP
+.P
Appropriate privilege (Linux: the
.B CAP_SYS_ADMIN
capability) is required to mount filesystems.
-.PP
+.P
Values for the
.I filesystemtype
argument supported by the kernel are listed in
"tmpfs", "cgroup", "proc", "mqueue", "nfs", "cifs", "iso9660").
Further types may become available when the appropriate modules
are loaded.
-.PP
+.P
The
.I data
argument is interpreted by the different filesystems.
.BR mount (8)
for details of the options available for each filesystem type.
This argument may be specified as NULL, if there are no options.
-.PP
+.P
A call to
.BR mount ()
performs one of a number of general types of operation,
Create a new mount:
.I mountflags
includes none of the above flags.
-.PP
+.P
Each of these operations is detailed later in this page.
Further flags may be specified in
.I mountflags
and
.BR realpath (3)
all still work properly.
-.PP
+.P
From Linux 2.4 onward, some of the above flags are
settable on a per-mount basis,
while others apply to the superblock of the mounted filesystem,
meaning that all mounts of the same filesystem share those flags.
(Previously, all of the flags were per-superblock.)
-.PP
+.P
The per-mount-point flags are as follows:
.IP \[bu] 3
Since Linux 2.4:
.IP \[bu]
Additionally, since Linux 2.6.20:
.BR MS_RELATIME .
-.PP
+.P
The following flags are per-superblock:
.BR MS_DIRSYNC ,
.BR MS_LAZYTIME ,
via a remount operation (see below).
Such changes will be visible via all mounts associated
with the filesystem.
-.PP
+.P
Since Linux 2.6.16,
.B MS_RDONLY
can be set or cleared on a per-mount-point basis as well as on
should be the same value specified in the initial
.BR mount ()
call.
-.PP
+.P
The
.I source
and
.I filesystemtype
arguments are ignored.
-.PP
+.P
The
.I mountflags
and
arguments should match the values used in the original
.BR mount ()
call, except for those parameters that are being deliberately changed.
-.PP
+.P
The following
.I mountflags
can be changed:
Note that changes to per-superblock flags are visible via
all mounts of the associated filesystem
(because the per-superblock flags are shared by all mounts).
-.PP
+.P
Since Linux 3.17,
.\" commit ffbc6f0ead47fa5a1dc9642b0331cb75c20a640e
if none of
then the remount operation preserves the existing values of these flags
(rather than defaulting to
.BR MS_RELATIME ).
-.PP
+.P
Since Linux 2.6.26, the
.B MS_REMOUNT
flag can be used with
Specifying
.I mountflags
as:
-.PP
+.P
.in +4n
.EX
MS_REMOUNT | MS_BIND | MS_RDONLY
.EE
.in
-.PP
+.P
will make access through this mountpoint read-only, without affecting
other mounts.
.\"
Bind mounts may cross filesystem boundaries and span
.BR chroot (2)
jails.
-.PP
+.P
The
.I filesystemtype
and
.I data
arguments are ignored.
-.PP
+.P
The remaining bits (other than
.BR MS_REC ,
described below) in the
the underlying mount.)
However, see the discussion of remounting above,
for a method of making an existing bind mount read-only.
-.PP
+.P
By default, when a directory is bind mounted,
only that directory is mounted;
if there are any submounts under the directory tree,
(all available since Linux 2.6.15),
then the propagation type of an existing mount is changed.
If more than one of these flags is specified, an error results.
-.PP
+.P
The only other flags that can be specified while changing
the propagation type are
.B MS_REC
(described below) and
.B MS_SILENT
(which is ignored).
-.PP
+.P
The
.IR source ,
.IR filesystemtype ,
and
.I data
arguments are ignored.
-.PP
+.P
The meanings of the propagation type flags are as follows:
.TP
.B MS_SHARED
any unbindable mounts within the subtree are automatically pruned
(i.e., not replicated)
when replicating that subtree to produce the target subtree.
-.PP
+.P
By default, changing the propagation type affects only the
.I target
mount.
then the propagation type of all mounts under
.I target
is also changed.
-.PP
+.P
For further details regarding mount propagation types
(including the default propagation type assigned to new mounts), see
.BR mount_namespaces (7).
.I target
specifies the new location to which that mount is to be relocated.
The move is atomic: at no point is the subtree unmounted.
-.PP
+.P
The remaining bits in the
.I mountflags
argument are ignored, as are the
specifies the source for the new mount, and
.I target
specifies the directory at which to create the mount point.
-.PP
+.P
The
.I filesystemtype
and
and
.B MS_UNBINDABLE
were added to glibc headers in glibc 2.12.
-.PP
+.P
Since Linux 2.4 a single filesystem can be mounted at
multiple mount points, and multiple mounts can be stacked
on the same mount point.
.\" Multiple mounts on same mount point: since Linux 2.3.99pre7.
-.PP
+.P
The
.I mountflags
argument may have the magic number 0xC0ED (\fBMS_MGC_VAL\fP)
.B MS_MGC_VAL
was required before Linux 2.4,
but since Linux 2.4 is no longer required and is ignored if specified.
-.PP
+.P
The original
.B MS_SYNC
flag was renamed
when a different
.B MS_SYNC
was added to \fI<mman.h>\fP.
-.PP
+.P
Before Linux 2.4 an attempt to execute a set-user-ID or set-group-ID program
on a filesystem mounted with
.B MS_NOSUID
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.)
-.PP
+.P
A child process created by
.BR fork (2)
shares its parent's mount namespace;
the mount namespace is preserved across an
.BR execve (2).
-.PP
+.P
A process can obtain a private mount namespace if:
it was created using the
.BR clone (2)
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.
-.PP
+.P
For further details on mount namespaces, see
.BR mount_namespaces (7).
.\"
Each mount has a parent mount.
The overall parental relationship of all mounts defines
the single directory hierarchy seen by the processes within a mount namespace.
-.PP
+.P
The parent of a new mount is defined when the mount is created.
In the usual case,
the parent of a new mount is the mount of the filesystem
In the case where a new mount is stacked on top of an existing mount,
the parent of the new mount is the previous mount that was stacked
at that location.
-.PP
+.P
The parental relationship between mounts can be discovered via the
.IR /proc/ pid /mountinfo
file (see below).
.BR "#include <linux/mount.h>" " /* Definition of " MOUNT_ATTR_* " constants */"
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "int syscall(SYS_mount_setattr, int " dirfd ", const char *" pathname ,
.BI " unsigned int " flags ", struct mount_attr *" attr \
", size_t " size );
.fi
-.PP
+.P
.IR Note :
glibc provides no wrapper for
.BR mount_setattr (),
for an explanation of why the
.I dirfd
argument is useful.)
-.PP
+.P
The
.BR mount_setattr ()
system call uses an extensible structure
See the "Extensibility" subsection under
.B NOTES
for more details.
-.PP
+.P
The
.I size
argument should usually be specified as
.I struct mount_attr
is
.BR MOUNT_ATTR_SIZE_VER0 .
-.PP
+.P
The
.I flags
argument can be used to alter the pathname resolution behavior.
.TP
.B AT_NO_AUTOMOUNT
Don't trigger automounts.
-.PP
+.P
The
.I attr
argument of
.BR mount_setattr ()
is a structure of the following form:
-.PP
+.P
.in +4n
.EX
struct mount_attr {
};
.EE
.in
-.PP
+.P
The
.I attr_set
and
and flags set in
.I attr_clr
remove a property from a mount or mount tree.
-.PP
+.P
When changing mount properties,
the kernel will first clear the flags specified
in the
.I attr_set
field.
For example, these settings:
-.PP
+.P
.in +4n
.EX
struct mount_attr attr = {
};
.EE
.in
-.PP
+.P
are equivalent to the following steps:
-.PP
+.P
.in +4n
.EX
unsigned int current_mnt_flags = mnt\->mnt_flags;
mnt\->mnt_flags = current_mnt_flags;
.EE
.in
-.PP
+.P
As a result of this change, the mount or mount tree (a) is read-only;
(b) blocks the execution of set-user-ID and set-group-ID programs;
(c) allows execution of programs; and (d) allows access to devices.
-.PP
+.P
Multiple changes with the same set of flags requested
in
.I attr_clr
and
.I attr_set
are guaranteed to be idempotent after the changes have been applied.
-.PP
+.P
The following mount attributes can be specified in the
.I attr_set
or
.IR attr_clr .
.IP
For further details, see the subsection "ID-mapped mounts" under NOTES.
-.PP
+.P
The
.I propagation
field is used to specify the propagation type of the mount or mount tree.
.TP
.B MS_UNBINDABLE
Turn all mounts into unbindable mounts.
-.PP
+.P
For further details on the above propagation types, see
.BR mount_namespaces (7).
.SH RETURN VALUE
All other users and locations where the filesystem is exposed are unaffected.
It is a temporary change because
the ownership changes are tied to the lifetime of the mount.
-.PP
+.P
Whenever callers interact with the filesystem through an ID-mapped mount,
the ID mapping of the mount will be applied to
user and group IDs associated with filesystem objects.
or
.B ACL_GROUP
entries.
-.PP
+.P
The following conditions must be met in order to create an ID-mapped mount:
.IP \[bu] 3
The caller must have the
the mount must not have been attached to the filesystem hierarchy
with a system call such as
.BR move_mount (2).)
-.PP
+.P
ID mappings can be created for user IDs, group IDs, and project IDs.
An ID mapping is essentially a mapping of a range of user or group IDs into
another or the same range of user or group IDs.
user ID 1001 in its ancestor user namespace.
Since the map range is 1,
only user ID 1000 is mapped.
-.PP
+.P
It is possible to specify up to 340 ID mappings for each ID mapping type.
If any user IDs or group IDs are not mapped,
all files owned by that unmapped user or group ID will appear as
being owned by the overflow user ID or overflow group ID respectively.
-.PP
+.P
Further details on setting up ID mappings can be found in
.BR user_namespaces (7).
-.PP
+.P
In the common case, the user namespace passed in
.I userns_fd
(together with
.BR systemd-homed.service (8)).
It is also perfectly fine to create a dedicated user namespace
for the sake of ID mapping a mount.
-.PP
+.P
ID-mapped mounts can be useful in the following
and a variety of other scenarios:
.IP \[bu] 3
.BR clone3 (2)
and
.BR openat2 (2).
-.PP
+.P
Let
.I usize
be the size of the structure as specified by the user-space application,
is set to
.BR E2BIG .
This provides forwards-compatibility.
-.PP
+.P
Because the definition of
.I struct mount_attr
may change in the future
to ensure that recompiling the program with new headers will not result in
spurious errors at run time.
The simplest way is to use a designated initializer:
-.PP
+.P
.in +4n
.EX
struct mount_attr attr = {
};
.EE
.in
-.PP
+.P
Alternatively, the structure can be zero-filled using
.BR memset (3)
or similar functions:
-.PP
+.P
.in +4n
.EX
struct mount_attr attr;
attr.attr_clr = MOUNT_ATTR_NODEV;
.EE
.in
-.PP
+.P
A user-space application that wishes to determine which extensions the running
kernel supports can do so by conducting a binary search on
.I size
.SH SYNOPSIS
.nf
.B #include <numaif.h>
-.PP
+.P
.BI "long move_pages(int " pid ", unsigned long " count ", \
void *" pages [. count ],
.BI " const int " nodes [. count "], int " status [. count "], \
The
.I flags
indicate constraints on the pages to be moved.
-.PP
+.P
.I pid
is the ID of the process in which pages are to be moved.
If
is 0, then
.BR move_pages ()
moves pages of the calling process.
-.PP
+.P
To move pages in another process requires the following privileges:
.IP \[bu] 3
Up to and including Linux 4.12:
.B PTRACE_MODE_READ_REALCREDS
check with respect to the target process; see
.BR ptrace (2).
-.PP
+.P
.I count
is the number of pages to move.
It defines the size of the three arrays
.IR nodes ,
and
.IR status .
-.PP
+.P
.I pages
is an array of pointers to the pages that should be moved.
These are pointers that should be aligned to page boundaries.
.\" not aligned to page boundaries
Addresses are specified as seen by the process specified by
.IR pid .
-.PP
+.P
.I nodes
is an array of integers that specify the desired location for each page.
Each element in the array is a node number.
array.
Obtaining the status of each page may be necessary to determine
pages that need to be moved.
-.PP
+.P
.I status
is an array of integers that return the status of each page.
The array contains valid values only if
Preinitialization of the array to a value
which cannot represent a real numa node or valid error of status array
could help to identify pages that have been migrated.
-.PP
+.P
.I flags
specify what types of pages to move.
.B MPOL_MF_MOVE
.SH NOTES
For information on library support, see
.BR numa (7).
-.PP
+.P
Use
.BR get_mempolicy (2)
with the
the current cpuset.
Note that this information is subject to change at any
time by manual or automatic reconfiguration of the cpuset.
-.PP
+.P
Use of this function may result in pages whose location
(node) violates the memory policy established for the
specified addresses (See
That is, memory policy does not constrain the destination
nodes used by
.BR move_pages ().
-.PP
+.P
The
.I <numaif.h>
header is not included with glibc, but requires installing
.SH SYNOPSIS
.nf
.B #include <sys/mman.h>
-.PP
+.P
.BI "int mprotect(void " addr [. len "], size_t " len ", int " prot );
-.PP
+.P
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <sys/mman.h>
-.PP
+.P
.BI "int pkey_mprotect(void " addr [. len "], size_t " len ", int " prot ", int " pkey ");"
.fi
.SH DESCRIPTION
interval [\fIaddr\fP,\ \fIaddr\fP+\fIlen\fP\-1].
.I addr
must be aligned to a page boundary.
-.PP
+.P
If the calling process tries to access memory in a manner
that violates the protections, then the kernel generates a
.B SIGSEGV
signal for the process.
-.PP
+.P
.I prot
is a combination of the following access flags:
.B PROT_NONE
the PowerPC architecture
(version 2.06 of the architecture specification adds the SAO CPU feature,
and it is available on POWER 7 or PowerPC A2, for example).
-.PP
+.P
Additionally (since Linux 2.6.0),
.I prot
can have one of the following flags set:
(which should be a stack segment or a segment mapped with the
.B MAP_GROWSDOWN
flag set).
-.PP
+.P
Like
.BR mprotect (),
.BR pkey_mprotect ()
is unspecified if it is applied to a region of memory that
was not obtained via
.BR mmap (2).
-.PP
+.P
On Linux, it is always permissible to call
.BR 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.
-.PP
+.P
Whether
.B PROT_EXEC
has any effect different from
.B PROT_READ
will implicitly add
.BR PROT_EXEC .
-.PP
+.P
On some hardware architectures (e.g., i386),
.B PROT_WRITE
implies
.BR PROT_READ .
-.PP
+.P
POSIX.1 says that an implementation may permit access
other than that specified in
.IR prot ,
has been set, and must not allow any access if
.B PROT_NONE
has been set.
-.PP
+.P
Applications should be careful when mixing use of
.BR mprotect ()
and
.B PROT_EXEC
a pkey may be allocated and set on the memory implicitly
by the kernel, but only when the pkey was 0 previously.
-.PP
+.P
On systems that do not support protection keys in hardware,
.BR pkey_mprotect ()
may still be used, but
The program 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.
-.PP
+.P
An example of what we might see when running the program is the
following:
-.PP
+.P
.in +4n
.EX
.RB "$" " ./a.out"
.BR "#include <mqueue.h>" " /* Definition of " "struct mq_attr" " */"
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "int syscall(SYS_mq_getsetattr, mqd_t " mqdes ,
.BI " const struct mq_attr *" newattr ", struct mq_attr *" oldattr );
.fi
.SH DESCRIPTION
Do not use this system call.
-.PP
+.P
This is the low-level system call used to implement
.BR mq_getattr (3)
and
.nf
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <sys/mman.h>
-.PP
+.P
.BI "void *mremap(void " old_address [. old_size "], size_t " old_size ,
.BI " size_t " new_size ", int " flags ", ... /* void *" new_address " */);"
.fi
expands (or shrinks) an existing memory mapping, potentially
moving it at the same time (controlled by the \fIflags\fP argument and
the available virtual address space).
-.PP
+.P
\fIold_address\fP is the old address of the virtual memory block that you
want to expand (or shrink).
Note that \fIold_address\fP has to be page
may be provided; see the description of
.B MREMAP_FIXED
below.
-.PP
+.P
If the value of \fIold_size\fP is zero, and \fIold_address\fP refers to
a shareable mapping (see
.BR mmap (2)
If a new mapping is requested via this method, then the
.B MREMAP_MAYMOVE
flag must also be specified.
-.PP
+.P
The \fIflags\fP bit-mask argument may be 0, or include the following flags:
.TP
.B MREMAP_MAYMOVE
mapped.
See NOTES for some possible applications of
.BR MREMAP_DONTUNMAP .
-.PP
+.P
If the memory segment specified by
.I old_address
and
.\" 4.2BSD had a (never actually implemented)
.\" .BR mremap (2)
.\" call with completely different semantics.
-.\" .PP
+.\" .P
Prior to glibc 2.4, glibc did not expose the definition of
.BR MREMAP_FIXED ,
and the prototype for
mapping between virtual addresses and memory pages.
This can be used to implement a very efficient
.BR realloc (3).
-.PP
+.P
In Linux, memory is divided into pages.
A process has (one or)
several linear virtual memory segments.
writing to a read-only segment).
Accessing virtual memory outside of the
segments will also cause a segmentation violation.
-.PP
+.P
If
.BR mremap ()
is used to move or expand an area locked with
.BR sbrk (2),
.BR malloc (3),
.BR realloc (3)
-.PP
+.P
Your favorite text book on operating systems
for more information on paged memory
(e.g., \fIModern Operating Systems\fP by Andrew S.\& Tanenbaum,
.SH SYNOPSIS
.nf
.B #include <sys/msg.h>
-.PP
+.P
.BI "int msgctl(int " msqid ", int " cmd ", struct msqid_ds *" buf );
.fi
.SH DESCRIPTION
.I cmd
on the System\ V message queue with identifier
.IR msqid .
-.PP
+.P
The
.I msqid_ds
data structure is defined in \fI<sys/msg.h>\fP as follows:
-.PP
+.P
.in +4n
.EX
struct msqid_ds {
};
.EE
.in
-.PP
+.P
The fields of the
.I msqid_ds
structure are as follows:
ID of the process that performed the last
.BR msgrcv (2)
system call.
-.PP
+.P
The
.I ipc_perm
structure is defined as follows
(the highlighted fields are settable using
.BR IPC_SET ):
-.PP
+.P
.in +4n
.EX
struct ipc_perm {
};
.EE
.in
-.PP
+.P
The least significant 9 bits of the
.I mode
field of the
0004 Read by others
0002 Write by others
.TE
-.PP
+.P
Bits 0100, 0010, and 0001 (the execute bits) are unused by the system.
-.PP
+.P
Valid values for
.I cmd
are:
.B MSG_STAT_ANY
operation returns the identifier of the queue whose index was given in
.IR msqid .
-.PP
+.P
On failure, \-1 is returned and
.I errno
is set to indicate the error.
.SH HISTORY
POSIX.1-2001, SVr4.
.\" SVID does not document the EIDRM error condition.
-.PP
+.P
Various fields in the \fIstruct msqid_ds\fP were
typed as
.I short
.SH SYNOPSIS
.nf
.B #include <sys/msg.h>
-.PP
+.P
.BI "int msgget(key_t " key ", int " msgflg );
.fi
.SH DESCRIPTION
does not have the value
.BR IPC_PRIVATE ),
or to create a new set.
-.PP
+.P
A new message queue is created if
.I key
has the value
.B IPC_CREAT
is specified in
.IR msgflg .
-.PP
+.P
If
.I msgflg
specifies both
.B O_CREAT | O_EXCL
for
.BR open (2).)
-.PP
+.P
Upon creation, the least significant bits of the argument
.I msgflg
define the permissions of the message queue.
argument of
.BR open (2).
(The execute permissions are not used.)
-.PP
+.P
If a new message queue is created,
then its associated data structure
.I msqid_ds
.I msg_qbytes
is set to the system limit
.BR MSGMNB .
-.PP
+.P
If the message queue already exists the permissions are
verified, and a check is made to see if it is marked for
destruction.
the system call ignores everything but the least significant 9 bits of
.I msgflg
and creates a new message queue (on success).
-.PP
+.P
The following is a system limit on message queue resources affecting a
.BR msgget ()
call:
.SH SYNOPSIS
.nf
.B #include <sys/msg.h>
-.PP
+.P
.BI "int msgsnd(int " msqid ", const void " msgp [. msgsz "], size_t " msgsz ,
.BI " int " msgflg );
-.PP
+.P
.BI "ssize_t msgrcv(int " msqid ", void " msgp [. msgsz "], size_t " msgsz \
", long " msgtyp ,
.BI " int " msgflg );
and receive messages from, a System\ V 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.
-.PP
+.P
The
.I msgp
argument is a pointer to a caller-defined structure
of the following general form:
-.PP
+.P
.in +4n
.EX
struct msgbuf {
};
.EE
.in
-.PP
+.P
The
.I mtext
field is an array (or other structure) whose size is specified by
to the message queue whose identifier is specified
by
.IR msqid .
-.PP
+.P
If sufficient space is available in the queue,
.BR msgsnd ()
succeeds immediately.
messages being placed on the queue.
Although such messages contain no data,
they nevertheless consume (locked) kernel memory.
-.PP
+.P
If insufficient space is available in the queue, then the default
behavior of
.BR msgsnd ()
.IR msgflg ,
then the call instead fails with the error
.BR EAGAIN .
-.PP
+.P
A blocked
.BR msgsnd ()
call may also fail if:
signal handler, regardless of the setting of the
.B SA_RESTART
flag when establishing a signal handler.)
-.PP
+.P
Upon successful completion the message queue data structure is updated
as follows:
.IP \[bu] 3
and places it in the buffer
pointed to by
.IR msgp .
-.PP
+.P
The argument
.I msgsz
specifies the maximum size in bytes for the member
.I errno
set to
.BR E2BIG .
-.PP
+.P
Unless
.B MSG_COPY
is specified in
equal to the absolute value of
.I msgtyp
will be read.
-.PP
+.P
The
.I msgflg
argument is a bit mask constructed by ORing together zero or more
To truncate the message text if longer than
.I msgsz
bytes.
-.PP
+.P
If no message of the requested type is available and
.B IPC_NOWAIT
isn't specified in
signal handler, regardless of the setting of the
.B SA_RESTART
flag when establishing a signal handler.)
-.PP
+.P
Upon successful completion the message queue data structure is updated
as follows:
.IP
The system does not have enough memory to make a copy of the
message pointed to by
.IR msgp .
-.PP
+.P
.BR msgrcv ()
can fail with the following errors:
.TP
.BR CONFIG_CHECKPOINT_RESTORE .
.SH STANDARDS
POSIX.1-2008.
-.PP
+.P
The
.B MSG_EXCEPT
and
feature test macro.
.SH HISTORY
POSIX.1-2001, SVr4.
-.PP
+.P
The
.I msgp
argument is declared as \fIstruct msgbuf\ *\fP in
.BR msgctl (2)
.B IPC_SET
operation.
-.PP
+.P
The implementation has no intrinsic system-wide limits on the
number of message headers
.RB ( MSGTQL )
This bug is fixed
.\" commit 4f87dac386cc43d5525da7a939d4b4e7edbea22c
in Linux 3.14.
-.PP
+.P
Specifying both
.B MSG_COPY
and
.BR msgsnd ()
and
.BR msgrcv ().
-.PP
+.P
The example program is first run with the \fB\-s\fP option to send a
message and then run again with the \fB\-r\fP option to receive a
message.
-.PP
+.P
The following shell session shows a sample run of the program:
-.PP
+.P
.in +4n
.EX
.RB "$" " ./a.out \-s"
sent: a message at Wed Mar 4 16:25:45 2015
-.PP
+.P
.RB "$" " ./a.out \-r"
message received: a message at Wed Mar 4 16:25:45 2015
.EE
.SH SYNOPSIS
.nf
.B #include <sys/mman.h>
-.PP
+.P
.BI "int msync(void " addr [. length "], size_t " length ", int " flags );
.fi
.SH DESCRIPTION
and having length
.I length
is updated.
-.PP
+.P
The
.I flags
argument should specify exactly one of
POSIX.1-2008.
.SH HISTORY
POSIX.1-2001.
-.PP
+.P
This call was introduced in Linux 1.3.21, and then used
.B EFAULT
instead of
.BR ENOMEM .
In Linux 2.4.19, this was changed to the POSIX value
.BR ENOMEM .
-.PP
+.P
On POSIX systems on which
.BR msync ()
is available, both
.\" glibc defines them to 1.
.SH SEE ALSO
.BR mmap (2)
-.PP
+.P
B.O. Gallmeister, POSIX.4, O'Reilly, pp. 128\[en]129 and 389\[en]391.
.SH SYNOPSIS
.nf
.B #include <time.h>
-.PP
+.P
.BI "int nanosleep(const struct timespec *" req ,
.BI " struct timespec *_Nullable " rem );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR nanosleep ():
.nf
_POSIX_C_SOURCE >= 199309L
has elapsed, or the delivery of a signal
that triggers the invocation of a handler in the calling thread or
that terminates the process.
-.PP
+.P
If the call is interrupted by a signal handler,
.BR nanosleep ()
returns \-1, sets
can then be used to call
.BR nanosleep ()
again and complete the specified pause (but see NOTES).
-.PP
+.P
The
.BR timespec (3)
structure
is used to specify intervals of time with nanosecond precision.
-.PP
+.P
The value of the nanoseconds field must be in the range [0, 999999999].
-.PP
+.P
Compared to
.BR sleep (3)
and
should not affect
.BR nanosleep ():
.RS
-.PP
+.P
Setting the value of the
.B CLOCK_REALTIME
clock via
POSIX.1-2008.
.SH HISTORY
POSIX.1-2001.
-.PP
+.P
In order to support applications requiring much more precise pauses
(e.g., in order to control some time-critical hardware),
.BR nanosleep ()
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.
-.PP
+.P
The fact that
.BR nanosleep ()
sleeps for a relative interval can be problematic if the call
with the
.B TIMER_ABSTIME
flag to sleep to an absolute deadline.
-.PP
+.P
In Linux 2.4, if
.BR nanosleep ()
is stopped by a signal (e.g.,
.SH SYNOPSIS
.nf
.B #include <linux/nfsd/syscall.h>
-.PP
+.P
.BI "long nfsservctl(int " cmd ", struct nfsctl_arg *" argp ,
.BI " union nfsctl_res *" resp );
.fi
.I nfsd
filesystem; see
.BR nfsd (7).
-.PP
+.P
.in +4n
.EX
/*
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.BI "int nice(int " inc );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR nice ():
.nf
_XOPEN_SOURCE
.I inc
to the nice value for the calling thread.
(A higher nice value means a lower priority.)
-.PP
+.P
The range of the nice value is +19 (low priority) to \-20 (high priority).
Attempts to set a nice value outside the range are clamped to the range.
-.PP
+.P
Traditionally, only a privileged process could lower the nice value
(i.e., set a higher priority).
However, since Linux 2.6.12, an unprivileged process can decrease
On error, \-1 is returned, and
.I errno
is set to indicate the error.
-.PP
+.P
A successful call can legitimately return \-1.
To detect an error, set
.I errno
Likewise, the
.BR nice ()
wrapper function provided in glibc 2.2.3 and earlier returns 0 on success.
-.PP
+.P
Since glibc 2.2.4, the
.BR nice ()
wrapper function provided by glibc provides conformance to POSIX.1 by calling
.SH NOTES
For further details on the nice value, see
.BR sched (7).
-.PP
+.P
.IR Note :
the addition of the "autogroup" feature in Linux 2.6.38 means that
the nice value no longer has its traditional effect in many circumstances.
.SH SYNOPSIS
.nf
.B #include <fcntl.h>
-.PP
+.P
.BI "int open(const char *" pathname ", int " flags ", ..."
.BI " \fR/*\fP mode_t " mode " \fR*/\fP );"
-.PP
+.P
.BI "int creat(const char *" pathname ", mode_t " mode );
-.PP
+.P
.BI "int openat(int " dirfd ", const char *" pathname ", int " flags ", ..."
.BI " \fR/*\fP mode_t " mode " \fR*/\fP );"
-.PP
+.P
/* Documented separately, in \fBopenat2\fP(2): */
.BI "int openat2(int " dirfd ", const char *" pathname ,
.BI " const struct open_how *" how ", size_t " size );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR openat ():
.nf
Since glibc 2.10:
.IR flags )
be created by
.BR open ().
-.PP
+.P
The return value of
.BR open ()
is a file descriptor, a small, nonnegative integer that is an index
etc.) to refer to the open file.
The file descriptor returned by a successful call will be
the lowest-numbered file descriptor not currently open for the process.
-.PP
+.P
By default, the new file descriptor is set to remain open across an
.BR execve (2)
(i.e., the
flag, described below, can be used to change this default.
The file offset is set to the beginning of the file (see
.BR lseek (2)).
-.PP
+.P
A call to
.BR open ()
creates a new
.I pathname
is subsequently removed or modified to refer to a different file.
For further details on open file descriptions, see NOTES.
-.PP
+.P
The argument
.I flags
must include one of the following
.BR O_RDONLY ", " O_WRONLY ", or " O_RDWR .
These request opening the file read-only, write-only, or read/write,
respectively.
-.PP
+.P
In addition, zero or more file creation flags and file status flags
can be
bitwise ORed
modified; see
.BR fcntl (2)
for details.
-.PP
+.P
The full list of file creation flags and file status flags is as follows:
.TP
.B O_APPEND
system call operates in exactly the same way as
.BR open (),
except for the differences described here.
-.PP
+.P
The
.I dirfd
argument is used in conjunction with the
or using the
.B O_PATH
flag.
-.PP
+.P
If the pathname given in
.I pathname
is relative, and
it must at least support the use of
.B O_SYNC
for regular files.
-.PP
+.P
Linux implements
.B O_SYNC
and
is defined in the Linux header file
.I <asm/fcntl.h>
on HP PA-RISC, but it is not used.)
-.PP
+.P
.B O_SYNC
provides synchronized I/O
.I file
Data integrity completion can reduce the number of disk operations
that are required for applications that don't need the guarantees
of file integrity completion.
-.PP
+.P
To understand the difference between the two types of completion,
consider two pieces of file metadata:
the file last modification timestamp
(whereas
.B O_SYNC
would also always flush the last modification timestamp metadata).
-.PP
+.P
Before Linux 2.6.33, Linux implemented only the
.B O_SYNC
flag for
.B O_SYNC
was actually implemented as the equivalent of
.BR O_DSYNC ).
-.PP
+.P
Since Linux 2.6.33, proper
.B O_SYNC
support is provided.
.TQ
.BR openat ()
POSIX.1-2008.
-.PP
+.P
.BR openat2 (2)
Linux.
-.PP
+.P
The
.BR O_DIRECT ,
.BR O_NOATIME ,
One must define
.B _GNU_SOURCE
to obtain their definitions.
-.PP
+.P
The
.BR O_CLOEXEC ,
.BR O_DIRECTORY ,
this may be used to open a device in order to get a file descriptor
for use with
.BR ioctl (2).
-.PP
+.P
Note that
.BR open ()
can open device special files, but
cannot create them; use
.BR mknod (2)
instead.
-.PP
+.P
If the file is newly created, its
.IR st_atime ,
.IR st_ctime ,
and
.I st_mtime
fields are set to the current time.
-.PP
+.P
The files in the
.IR /proc/ pid /fd
directory show the open file descriptors of the process with the PID
See
.BR proc (5)
for further details of both of these directories.
-.PP
+.P
The Linux header file
.B <asm/fcntl.h>
doesn't define
a "file handle", an "open file table entry",
or\[em]in kernel-developer parlance\[em]a
.IR "struct file" .
-.PP
+.P
When a file descriptor is duplicated (using
.BR dup (2)
or similar),
.BR fork (2)
inherits duplicates of its parent's file descriptors,
and those duplicates refer to the same open file descriptions.
-.PP
+.P
Each
.BR open ()
of a file creates a new open file description;
thus, there may be multiple open file descriptions
corresponding to a file inode.
-.PP
+.P
On Linux, one can use the
.BR kcmp (2)
.B KCMP_FILE
There are many infelicities in the protocol underlying NFS, affecting
amongst others
.BR O_SYNC " and " O_NDELAY .
-.PP
+.P
On NFS filesystems with UID mapping enabled,
.BR open ()
may
.B "O_RDONLY | O_WRONLY"
is a logical error, and certainly does not have the same meaning as
.BR O_RDWR .
-.PP
+.P
Linux reserves the special, nonstandard access mode 3 (binary 11) in
.I flags
to mean:
Here, the explanation is in terms of the
.BR openat ()
call, but the rationale is analogous for the other interfaces.
-.PP
+.P
First,
.BR openat ()
allows an application to avoid race conditions that could
the open file descriptor prevents the underlying filesystem from
being dismounted,
just as when a process has a current working directory on a filesystem.
-.PP
+.P
Second,
.BR openat ()
allows the implementation of a per-thread "current working
on the use of
.IR /proc/self/fd/ dirfd,
but less efficiently.)
-.PP
+.P
The
.I dirfd
argument for these APIs can be obtained by using
.BR dirfd (3)
to a directory stream created using
.BR opendir (3).
-.PP
+.P
When these APIs are given a
.I dirfd
argument of
they can either fail with
.B EINVAL
or fall back to buffered I/O.
-.PP
+.P
Since Linux 6.1,
.B O_DIRECT
support and alignment restrictions for a file can be queried using
varies by filesystem;
see
.BR statx (2).
-.PP
+.P
Some filesystems provide their own interfaces for querying
.B O_DIRECT
alignment restrictions,
.BR xfsctl (3).
.B STATX_DIOALIGN
should be used instead when it is available.
-.PP
+.P
If none of the above is available,
then direct I/O support and alignment restrictions
can only be assumed from known characteristics of the filesystem,
.BR ioctl (2)
.B BLKSSZGET
operation or from the shell using the command:
-.PP
+.P
.in +4n
.EX
blockdev \-\-getss
.EE
.in
-.PP
+.P
.B O_DIRECT
I/Os should never be run concurrently with the
.BR fork (2)
ensuring that it will not be available
to the child after
.BR fork (2).
-.PP
+.P
The
.B O_DIRECT
flag was introduced in SGI IRIX, where it has alignment
call to query appropriate alignments, and sizes.
FreeBSD 4.x introduced
a flag of the same name, but without alignment restrictions.
-.PP
+.P
.B O_DIRECT
support was added in Linux 2.4.10.
Older Linux kernels simply ignore this flag.
fails with the error
.B EINVAL
if it is used.
-.PP
+.P
Applications should avoid mixing
.B O_DIRECT
and normal I/O to the same file,
Likewise, applications should avoid mixing
.BR mmap (2)
of files with direct I/O to the same files.
-.PP
+.P
The behavior of
.B O_DIRECT
with NFS will differ from local filesystems.
The Linux NFS client places no alignment restrictions on
.B O_DIRECT
I/O.
-.PP
+.P
In summary,
.B O_DIRECT
is a potentially powerful tool that should be used with caution.
to enable this flag.
.\" FIXME . Check bugzilla report on open(O_ASYNC)
.\" See http://bugzilla.kernel.org/show_bug.cgi?id=5993
-.PP
+.P
One must check for two different error codes,
.B EISDIR
and
when trying to determine whether the kernel supports
.B O_TMPFILE
functionality.
-.PP
+.P
When both
.B O_CREAT
and
.nf
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <fcntl.h>
-.PP
+.P
.BI "int name_to_handle_at(int " dirfd ", const char *" pathname ,
.BI " struct file_handle *" handle ,
.BI " int *" mount_id ", int " flags );
The file handle is returned via the argument
.IR handle ,
which is a pointer to a structure of the following form:
-.PP
+.P
.in +4n
.EX
struct file_handle {
};
.EE
.in
-.PP
+.P
It is the caller's responsibility to allocate the structure
with a size large enough to hold the handle returned in
.IR f_handle .
.I handle_bytes
field is updated to contain the number of bytes actually written to
.IR f_handle .
-.PP
+.P
The caller can discover the required size for the
.I file_handle
structure by making a call in which
error is returned without
.I handle_bytes
being increased.
-.PP
+.P
Other than the use of the
.I handle_bytes
field, the caller should treat the
with an information record containing a
.I file_handle
to identify the filesystem object.
-.PP
+.P
The
.I flags
argument is a bit mask constructed by ORing together zero or more of
and
.BR AT_SYMLINK_FOLLOW ,
described below.
-.PP
+.P
When
.I flags
contain the
with the returned
.I file_handle
may fail.
-.PP
+.P
Together, the
.I pathname
and
.BR AT_FDCWD ,
meaning the current working directory,
and a handle is returned for the file to which it refers.
-.PP
+.P
The
.I mount_id
argument returns an identifier for the filesystem
is returned both for a successful call and for a call that results
in the error
.BR EOVERFLOW .
-.PP
+.P
By default,
.BR name_to_handle_at ()
does not dereference
.I pathname
is dereferenced if it is a symbolic link
(so that the call returns a handle for the file referred to by the link).
-.PP
+.P
.BR name_to_handle_at ()
does not trigger a mount when the final component of the pathname is an
automount point.
.IR handle ,
a file handle returned by a previous call to
.BR name_to_handle_at ().
-.PP
+.P
The
.I mount_fd
argument is a file descriptor for any object (file, directory, etc.)
The special value
.B AT_FDCWD
can be specified, meaning the current working directory of the caller.
-.PP
+.P
The
.I flags
argument
flag, and the symbolic link is not dereferenced; the
.B O_NOFOLLOW
flag, if specified, is ignored.
-.PP
+.P
The caller must have the
.B CAP_DAC_READ_SEARCH
capability to invoke
and
.BR open_by_handle_at ()
returns a file descriptor (a nonnegative integer).
-.PP
+.P
In the event of an error, both system calls return \-1 and set
.I errno
to indicate the error.
can fail for the same errors as
.BR openat (2).
In addition, they can fail with the errors noted below.
-.PP
+.P
.BR name_to_handle_at ()
can fail with the following errors:
.TP
is updated to indicate the required size for the handle.
.\"
.\"
-.PP
+.P
.BR open_by_handle_at ()
can fail with the following errors:
.TP
.BR name_to_handle_at ()
and later used in a different process that calls
.BR open_by_handle_at ().
-.PP
+.P
Some filesystem don't support the translation of pathnames to
file handles, for example,
.IR /proc ,
Some filesystems support the translation of pathnames to
file handles, but do not support using those file handles in
.BR open_by_handle_at ().
-.PP
+.P
A file handle may become invalid ("stale") if a file is deleted,
or for other filesystem-specific reasons.
Invalid handles are notified by an
.B ESTALE
error from
.BR open_by_handle_at ().
-.PP
+.P
These system calls are designed for use by user-space file servers.
For example, a user-space NFS server might generate a file handle
and pass it to an NFS client.
.\" "Open by handle" - Jonathan Corbet, 2010-02-23
This sort of functionality allows a user-space file server to operate in
a stateless fashion with respect to the files it serves.
-.PP
+.P
If
.I pathname
refers to a symbolic link and
.I mountinfo
record that corresponds to the mount ID
to derive a persistent identifier.
-.PP
+.P
For example, one can use the device name in the fifth field of the
.I mountinfo
record to search for the corresponding device UUID via the symbolic links in
to obtain the file handle and mount ID
for the file specified in its command-line argument;
the handle and mount ID are written to standard output.
-.PP
+.P
The second program
.RI ( t_open_by_handle_at.c )
reads a mount ID and file handle from standard input.
read from standard input,
and the mount directory specified in that record is opened.
(These programs do not deal with the fact that mount IDs are not persistent.)
-.PP
+.P
The following shell session demonstrates the use of these two programs:
-.PP
+.P
.in +4n
.EX
$ \fBecho \[aq]Can you please think about it?\[aq] > cecilia.txt\fP
$ \fBrm cecilia.txt\fP
.EE
.in
-.PP
+.P
Now we delete and (quickly) re-create the file so that
it has the same content and (by chance) the same inode.
Nevertheless,
.\" counter that gets incremented in this case.
recognizes that the original file referred to by the file handle
no longer exists.
-.PP
+.P
.in +4n
.EX
$ \fBstat \-\-printf="%i\en" cecilia.txt\fP # Display inode number
.BR blkid (8),
.BR findfs (8),
.BR mount (8)
-.PP
+.P
The
.I libblkid
and
.BR "#include <linux/openat2.h>" " /* Definition of " RESOLVE_* " constants */"
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "long syscall(SYS_openat2, int " dirfd ", const char *" pathname ,
.BI " struct open_how *" how ", size_t " size );
.fi
-.PP
+.P
.IR Note :
glibc provides no wrapper for
.BR openat2 (),
system call is an extension of
.BR openat (2)
and provides a superset of its functionality.
-.PP
+.P
The
.BR openat2 ()
system call opens the file specified by
is specified in
.IR how.flags )
be created.
-.PP
+.P
As with
.BR openat (2),
if
.I pathname
is resolved relative to
.IR dirfd ).
-.PP
+.P
Rather than taking a single
.I flags
argument, an extensible structure (\fIhow\fP) is passed to allow for
structure,
described in
.BR open_how (2type).
-.PP
+.P
Any future extensions to
.BR openat2 ()
will be implemented as new fields appended to the
(See the "Extensibility" section of the
.B NOTES
for more detail on why this is necessary.)
-.PP
+.P
The fields of the
.I open_how
structure are as follows:
.SH HISTORY
Linux 5.6.
.\" commit fddb5d430ad9fa91b49b1d34d0202ffe2fa0e179
-.PP
+.P
The semantics of
.B RESOLVE_BENEATH
were modeled after FreeBSD's
.BR perf_event_open (2),
and
.BR clone3 (2).
-.PP
+.P
If we let
.I usize
be the size of the structure as specified by the user-space application, and
is set to
.BR E2BIG .
This provides forwards-compatibility.
-.PP
+.P
Because the definition of
.I struct open_how
may change in the future (with new fields being added when system headers are
spurious errors at run time.
The simplest way is to use a designated
initializer:
-.PP
+.P
.in +4n
.EX
struct open_how how = { .flags = O_RDWR,
.resolve = RESOLVE_IN_ROOT };
.EE
.in
-.PP
+.P
or explicitly using
.BR memset (3)
or similar:
-.PP
+.P
.in +4n
.EX
struct open_how how;
how.resolve = RESOLVE_IN_ROOT;
.EE
.in
-.PP
+.P
A user-space application that wishes to determine which extensions
the running kernel supports can do so by conducting a binary search on
.I size
.SH SYNOPSIS
.nf
.B #include <sys/io.h>
-.PP
+.P
.BI "unsigned char inb(unsigned short " port );
.BI "unsigned char inb_p(unsigned short " port );
.BI "unsigned short inw(unsigned short " port );
.BI "unsigned short inw_p(unsigned short " port );
.BI "unsigned int inl(unsigned short " port );
.BI "unsigned int inl_p(unsigned short " port );
-.PP
+.P
.BI "void outb(unsigned char " value ", unsigned short " port );
.BI "void outb_p(unsigned char " value ", unsigned short " port );
.BI "void outw(unsigned short " value ", unsigned short " port );
.BI "void outw_p(unsigned short " value ", unsigned short " port );
.BI "void outl(unsigned int " value ", unsigned short " port );
.BI "void outl_p(unsigned int " value ", unsigned short " port );
-.PP
+.P
.BI "void insb(unsigned short " port ", void " addr [. count ],
.BI " unsigned long " count );
.BI "void insw(unsigned short " port ", void " addr [. count ],
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.
-.PP
+.P
They are primarily designed for internal kernel use,
but can be used from user space.
.\" , given the following information
.\" in addition to that given in
.\" .BR outb (9).
-.PP
+.P
You must compile with \fB\-O\fP or \fB\-O2\fP or similar.
The functions
are defined as inline macros, and will not be substituted in without
optimization enabled, causing unresolved references at link time.
-.PP
+.P
You use
.BR ioperm (2)
or alternatively
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.B int pause(void);
.fi
.SH DESCRIPTION
.SH SYNOPSIS
.nf
.B #include <pci.h>
-.PP
+.P
.BI "int pciconfig_read(unsigned long " bus ", unsigned long " dfn ,
.BI " unsigned long " off ", unsigned long " len ,
.BI " unsigned char *" buf );
.BR "#include <linux/hw_breakpoint.h>" " /* Definition of " HW_* " constants */"
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "int syscall(SYS_perf_event_open, struct perf_event_attr *" attr ,
.BI " pid_t " pid ", int " cpu ", int " group_fd \
", unsigned long " flags );
.fi
-.PP
+.P
.IR Note :
glibc provides no wrapper for
.BR perf_event_open (),
.BR perf_event_open ()
returns a file descriptor, for use in subsequent system calls
.RB ( read "(2), " mmap "(2), " prctl "(2), " fcntl "(2), etc.)."
-.PP
+.P
A call to
.BR perf_event_open ()
creates a file descriptor that allows measuring performance
Each file descriptor corresponds to one
event that is measured; these can be grouped together
to measure multiple events simultaneously.
-.PP
+.P
Events can be enabled and disabled in two ways: via
.BR ioctl (2)
and via
.BR prctl (2).
When an event is disabled it does not count or generate overflows but does
continue to exist and maintain its count value.
-.PP
+.P
Events come in two flavors: counting and sampled.
A
.I counting
.TP
.BR "pid == \-1" " and " "cpu == \-1"
This setting is invalid and will return an error.
-.PP
+.P
When
.I pid
is greater than zero, permission to perform this system call
.B PTRACE_MODE_READ_REALCREDS
check on older Linux versions; see
.BR ptrace (2).
-.PP
+.P
The
.I group_fd
argument allows event groups to be created.
\[em]added, divided (to get ratios), and so on\[em]
with each other,
since they have counted events for the same set of executed instructions.
-.PP
+.P
The
.I flags
argument is formed by ORing together zero or more of the following values:
parameter.
cgroup monitoring is available only
for system-wide events and may therefore require extra permissions.
-.PP
+.P
The
.I perf_event_attr
structure provides detailed configuration information
for the event being created.
-.PP
+.P
.in +4n
.EX
struct perf_event_attr {
};
.EE
.in
-.PP
+.P
The fields of the
.I perf_event_attr
structure are described in more detail below:
In other words, if the next task is in the same cgroup,
it won't count the switch.
.RE
-.PP
+.P
.RS
If
.I type
.I tracing/events/*/*/id
if ftrace is enabled in the kernel.
.RE
-.PP
+.P
.RS
If
.I type
.I config
value, use the following equation:
.RS 4
-.PP
+.P
.in +4n
.EX
config = (perf_hw_cache_id) |
(perf_hw_cache_op_result_id << 16);
.EE
.in
-.PP
+.P
where
.I perf_hw_cache_id
is one of:
.\" commit 89d6c0b5bdbb1927775584dcf532d98b3efe1477
for measuring local memory accesses
.RE
-.PP
+.P
and
.I perf_hw_cache_op_id
is one of:
.B PERF_COUNT_HW_CACHE_OP_PREFETCH
for prefetch accesses
.RE
-.PP
+.P
and
.I perf_hw_cache_op_result_id
is one of:
to measure misses
.RE
.RE
-.PP
+.P
If
.I type
is
architectural manuals to the raw hex value
.BR perf_event_open ()
expects in this field.
-.PP
+.P
If
.I type
is
.I config
set to zero.
Its parameters are set in other places.
-.PP
+.P
If
.I type
is
It has the following format and
the meaning of each field is
dependent on the hardware implementation.
-.PP
+.P
.in +4n
.EX
union perf_sample_weight {
.TP
.B HW_BREAKPOINT_X
Count when we execute code at the memory location.
-.PP
+.P
The values can be combined via a bitwise or, but the
combination of
.B HW_BREAKPOINT_R
.TP
.B PERF_SAMPLE_BRANCH_PLM_ALL
A convenience value that is the three preceding values ORed together.
-.PP
+.P
In addition to the privilege value, at least one or more of the
following bits must be set.
.TP
field in the
.I attr
structure at open time.
-.PP
+.P
If you attempt to read into a buffer that is not big enough to hold the
data, the error
.B ENOSPC
results.
-.PP
+.P
Here is the layout of the data returned by a read:
.IP \[bu] 3
If
};
.EE
.in
-.PP
+.P
The values read are as follows:
.TP
.I nr
are logged into a ring-buffer.
This ring-buffer is created and accessed through
.BR mmap (2).
-.PP
+.P
The mmap size should be 1+2\[ha]n pages, where the first page is a
metadata page
.RI ( "struct perf_event_mmap_page" )
that contains various
bits of information such as where the ring-buffer head is.
-.PP
+.P
Before Linux 2.6.39, there is a bug that means you must allocate an mmap
ring buffer when sampling even if you do not plan to access it.
-.PP
+.P
The structure of the first metadata mmap page is as follows:
-.PP
+.P
.in +4n
.EX
struct perf_event_mmap_page {
}
.EE
.in
-.PP
+.P
The following list describes the fields in the
.I perf_event_mmap_page
structure in more detail:
.I data_head
and
.IR data_tail .
-.PP
+.P
The following 2^n ring-buffer pages have the layout described below.
-.PP
+.P
If
.I perf_event_attr.sample_id_all
is set, then all event types will
This allows a newer perf.data
file to be supported by older perf tools, with the new optional
fields being ignored.
-.PP
+.P
The mmap values start with a header:
-.PP
+.P
.in +4n
.EX
struct perf_event_header {
};
.EE
.in
-.PP
+.P
Below, we describe the
.I perf_event_header
fields in more detail.
.\" commit 39447b386c846bbf1c56f6403c5282837486200f
Sample happened in guest user code.
.RE
-.PP
+.P
.RS
Since the following three statuses are generated by
different record types, they alias to the same bit:
context switch is away from the current process
(instead of into the current process).
.RE
-.PP
+.P
.RS
In addition, the following bits can be set:
.TP
.\" commit 71ef3c6b9d4665ee7afbbe4c208a98917dcfc32f
This reports the number of cycles elapsed since the
previous branch stack update.
-.PP
+.P
The entries are from most to least recent, so the first entry
has the most recent branch.
-.PP
+.P
Support for
.IR mispred ,
.IR predicted ,
.I cycles
is optional; if not supported, those
values will be 0.
-.PP
+.P
The type of branches recorded is specified by the
.I branch_sample_type
field.
.B F_SETSIG
operations in
.BR fcntl (2).
-.PP
+.P
Overflows are generated only by sampling events
.RI ( sample_period
must have a nonzero value).
-.PP
+.P
There are two ways to generate overflow notifications.
-.PP
+.P
The first is to set a
.I wakeup_events
or
In this case,
.B POLL_IN
is indicated.
-.PP
+.P
The other way is by use of the
.B PERF_EVENT_IOC_REFRESH
ioctl.
.B POLL_HUP
is indicated and
the underlying event is disabled.
-.PP
+.P
Refreshing an event group leader refreshes all siblings and
refreshing with a parameter of 0 currently enables infinite
refreshes;
these behaviors are unsupported and should not be relied on.
.\" See https://lkml.org/lkml/2011/5/24/337
-.PP
+.P
Starting with Linux 3.18,
.\" commit 179033b3e064d2cd3f5f9945e76b0a0f0fbf4883
.B POLL_HUP
Note that using
.I rdpmc
is not necessarily faster than other methods for reading event values.
-.PP
+.P
Support for this can be detected with the
.I cap_usr_rdpmc
field in the mmap page; documentation on how
to calculate event values can be found in that section.
-.PP
+.P
Originally, when rdpmc support was enabled, any process (not just ones
with an active perf event) could use the rdpmc instruction to access
the counters.
.BR mlock (2).
The default is 516 (kB).
.RE
-.PP
+.P
Files in
.I /sys/bus/event_source/devices/
-.PP
+.P
.RS 4
Since Linux 2.6.34, the kernel supports having multiple PMUs
available for monitoring.
support is enabled is checking
for the existence of the file
.IR /proc/sys/kernel/perf_event_paranoid .
-.PP
+.P
.B CAP_PERFMON
capability (since Linux 5.8) provides secure approach to
performance monitoring and observability operations in a system
is needed to properly get overflow signals in threads.
This was introduced in Linux 2.6.32.
.\" commit ba0a6c9f6fceed11c6a99e8326f0477fe383e6b5
-.PP
+.P
Prior to Linux 2.6.33 (at least for x86),
.\" commit b690081d4d3f6a23541493f1682835c3cd5c54a1
the kernel did not check
.BR perf_event_open (),
start, then read before you know for sure you
can get valid measurements.
-.PP
+.P
Prior to Linux 2.6.34,
.\" FIXME . cannot find a kernel commit for this one
event constraints were not enforced by the kernel.
In that case, some events would silently return "0" if the kernel
scheduled them in an improper counter slot.
-.PP
+.P
Prior to Linux 2.6.34, there was a bug when multiplexing where the
wrong results could be returned.
.\" commit 45e16a6834b6af098702e5ea6c9a40de42ff77d8
-.PP
+.P
Kernels from Linux 2.6.35 to Linux 2.6.39 can quickly crash the kernel if
"inherit" is enabled and many threads are started.
.\" commit 38b435b16c36b0d863efcf3f07b34a6fac9873fd
-.PP
+.P
Prior to Linux 2.6.35,
.\" commit 050735b08ca8a016bbace4445fa025b88fee770b
.B PERF_FORMAT_GROUP
did not work with attached processes.
-.PP
+.P
There is a bug in the kernel code between
Linux 2.6.36 and Linux 3.0 that ignores the
"watermark" field and acts as if a wakeup_event
was chosen if the union has a
nonzero value in it.
.\" commit 4ec8363dfc1451f8c8f86825731fe712798ada02
-.PP
+.P
From Linux 2.6.31 to Linux 3.4, the
.B PERF_IOC_FLAG_GROUP
ioctl argument was broken and would repeatedly operate
on the event specified rather than iterating across
all sibling events in a group.
.\" commit 724b6daa13e100067c30cfc4d1ad06629609dc4e
-.PP
+.P
From Linux 3.4 to Linux 3.11, the mmap
.\" commit fa7315871046b9a4c48627905691dbde57e51033
.I cap_usr_rdpmc
and
.I cap_user_time
fields instead.
-.PP
+.P
Always double-check your results!
Various generalized events have had wrong values.
For example, retired branches measured
The following is a short example that measures the total
instruction count of a call to
.BR printf (3).
-.PP
+.P
.\" SRC BEGIN (perf_event_open.c)
.EX
#include <linux/perf_event.h>
.BR open (2),
.BR prctl (2),
.BR read (2)
-.PP
+.P
.I Documentation/admin\-guide/perf\-security.rst
in the kernel source tree
.nf
.B #include <syscall.h>
.B #include <perfmon.h>
-.PP
+.P
.BI "long perfmonctl(int " fd ", int " cmd ", void " arg [. narg "], int " narg ");"
.fi
-.PP
+.P
.IR Note :
There is no glibc wrapper for this system call; see HISTORY.
.SH DESCRIPTION
The PMU consists of PMD (performance monitoring data) registers and
PMC (performance monitoring control) registers,
which gather hardware statistics.
-.PP
+.P
.BR perfmonctl ()
applies the operation
.I cmd
The
.I fd
argument specifies the perfmon context to operate on.
-.PP
+.P
Supported values for
.I cmd
are:
Added in Linux 2.4;
.\" commit ecf5b72d5f66af843f189dfe9ce31598c3e48ad7
removed in Linux 5.10.
-.PP
+.P
This system call was broken for many years,
and ultimately removed in Linux 5.10.
-.PP
+.P
glibc does not provide a wrapper for this system call;
on kernels where it exists, call it using
.BR syscall (2).
.SH SEE ALSO
.BR gprof (1)
-.PP
+.P
The perfmon2 interface specification
.SH SYNOPSIS
.nf
.B #include <sys/personality.h>
-.PP
+.P
.BI "int personality(unsigned long " persona );
.fi
.SH DESCRIPTION
The execution domain system allows
Linux to provide limited support for binaries compiled under other
UNIX-like operating systems.
-.PP
+.P
If
.I persona
is not
.I persona
as 0xffffffff provides a way of retrieving
the current persona without changing it.
-.PP
+.P
A list of the available execution domains can be found in
.IR <sys/personality.h> .
The execution domain is a 32-bit value in which the top three
.TP
.BR WHOLE_SECONDS " (since Linux 1.2.0)"
No effect.
-.PP
+.P
The available execution domains are:
.TP
.BR PER_BSD " (since Linux 1.2.0)"
.nf
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "int syscall(SYS_pidfd_getfd, int " pidfd ", int " targetfd ,
.BI " unsigned int " flags );
.fi
-.PP
+.P
.IR Note :
glibc provides no wrapper for
.BR pidfd_getfd (),
.IR targetfd ,
in the process referred to by the PID file descriptor
.IR pidfd .
-.PP
+.P
The duplicate file descriptor refers to the same open file description (see
.BR open (2))
as the original file descriptor in the process referred to by
(for example, assigning an address to a socket object using
.BR bind (2))
can equally be performed via the duplicate file descriptor.
-.PP
+.P
The close-on-exec flag
.RB ( FD_CLOEXEC ;
see
.BR fcntl (2))
is set on the file descriptor returned by
.BR pidfd_getfd ().
-.PP
+.P
The
.I flags
argument is reserved for future use.
Currently, it must be specified as 0.
-.PP
+.P
Permission to duplicate another process's file descriptor
is governed by a ptrace access mode
.B PTRACE_MODE_ATTACH_REALCREDS
.SH NOTES
For a description of PID file descriptors, see
.BR pidfd_open (2).
-.PP
+.P
The effect of
.BR pidfd_getfd ()
is similar to the use of
.nf
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "int syscall(SYS_pidfd_open, pid_t " pid ", unsigned int " flags );
.fi
-.PP
+.P
.IR Note :
glibc provides no wrapper for
.BR pidfd_open (),
.IR pid .
The file descriptor is returned as the function result;
the close-on-exec flag is set on the file descriptor.
-.PP
+.P
The
.I flags
argument either has the value 0, or contains the following flag:
The following code sequence can be used to obtain a file descriptor
for the child of
.BR fork (2):
-.PP
+.P
.in +4n
.EX
pid = fork();
}
.EE
.in
-.PP
+.P
Even if the child has already terminated by the time of the
.BR pidfd_open ()
call, its PID will not have been recycled and the returned
(e.g., either by an asynchronously executed signal handler or by
.BR wait (2)
or similar in another thread).
-.PP
+.P
If any of these conditions does not hold,
then the child process (along with a PID file descriptor that refers to it)
should instead be created using
.BR process_madvise (2)
in order to provide advice on the memory usage patterns of the process
referred to by the file descriptor.
-.PP
+.P
The
.BR pidfd_open ()
system call is the preferred way of obtaining a PID file descriptor
.BR "#include <signal.h>" " /* Definition of " SI_* " constants */"
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "int syscall(SYS_pidfd_send_signal, int " pidfd ", int " sig ,
.BI " siginfo_t *_Nullable " info ", unsigned int " flags );
.fi
-.PP
+.P
.IR Note :
glibc provides no wrapper for
.BR pidfd_send_signal (),
a PID file descriptor that refers to a process.
.\" See the very detailed commit message for kernel commit
.\" 3eb39f47934f9d5a3027fe00d906a45fe3a15fad
-.PP
+.P
If the
.I info
argument points to a
.I siginfo_t
buffer, that buffer should be populated as described in
.BR rt_sigqueueinfo (2).
-.PP
+.P
If the
.I info
argument is a NULL pointer,
buffer whose fields match the values that are
implicitly supplied when a signal is sent using
.BR kill (2):
-.PP
+.P
.PD 0
.IP \[bu] 3
.I si_signo
.I si_uid
is set to the caller's real user ID.
.PD
-.PP
+.P
The calling process must either be in the same PID namespace as the
process referred to by
.IR pidfd ,
or be in an ancestor of that namespace.
-.PP
+.P
The
.I flags
argument is reserved for future use;
that specifies the
.B CLONE_PIDFD
flag.
-.PP
+.P
The
.BR pidfd_send_signal ()
system call allows the avoidance of race conditions that occur
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.BI "int pipe(int " pipefd [2]);
-.PP
+.P
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.BR "#include <fcntl.h>" " /* Definition of " O_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "int pipe2(int " pipefd "[2], int " flags );
-.PP
+.P
/* On Alpha, IA-64, MIPS, SuperH, and SPARC/SPARC64, pipe() has the
following prototype; see VERSIONS */
-.PP
+.P
.B #include <unistd.h>
-.PP
+.P
.B struct fd_pair {
.B " long fd[2];"
.B "};"
until it is read from the read end of the pipe.
For further details, see
.BR pipe (7).
-.PP
+.P
If
.I flags
is 0, then
is set to indicate the error, and
.I pipefd
is left unchanged.
-.PP
+.P
On Linux (and other systems),
.BR pipe ()
does not modify
.nf
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "int syscall(SYS_pivot_root, const char *" new_root \
", const char *" put_old );
.fi
-.PP
+.P
.IR Note :
glibc provides no wrapper for
.BR pivot_root (),
The calling process must have the
.B CAP_SYS_ADMIN
capability in the user namespace that owns the caller's mount namespace.
-.PP
+.P
.BR pivot_root ()
changes the root directory and the current working directory
of each process or thread in the same mount namespace to
(unless it is on the old root directory),
and thus it should be followed by a
\fBchdir("/")\fP call.
-.PP
+.P
The following restrictions apply:
.IP \[bu] 3
.I new_root
.SH NOTES
A command-line interface for this system call is provided by
.BR pivot_root (8).
-.PP
+.P
.BR pivot_root ()
allows the caller to switch to a new root filesystem while at the same time
placing the old root mount at a location under
or current working directory on the old root directory to the
new root frees the old root directory of users,
allowing the old root mount to be unmounted more easily.)
-.PP
+.P
One use of
.BR pivot_root ()
is during system startup, when the
the root directory of all relevant processes and threads.
A modern use is to set up a root filesystem during
the creation of a container.
-.PP
+.P
The fact that
.BR pivot_root ()
modifies process root and current working directories in the
root mount busy with their root and current working directories,
even if they never access
the filesystem in any way.
-.PP
+.P
The rootfs (initial ramfs) cannot be
.BR pivot_root ()ed.
The recommended method of changing the root filesystem in this case is
may be the same directory.
In particular, the following sequence allows a pivot-root operation
without needing to create and remove a temporary directory:
-.PP
+.P
.in +4n
.EX
chdir(new_root);
umount2(".", MNT_DETACH);
.EE
.in
-.PP
+.P
This sequence succeeds because the
.BR pivot_root ()
call stacks the old root mount point
.SS Historical notes
For many years, this manual page carried the following text:
.RS
-.PP
+.P
.BR 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 and current working directory to \fInew_root\fP before invoking
.BR pivot_root ().
.RE
-.PP
+.P
This text, written before the system call implementation was
even finalized in the kernel, was probably intended to warn users
at that time that the implementation might change before final release.
first command-line argument, the child created by
.BR clone (2)
then executes the program named in the remaining command-line arguments.
-.PP
+.P
We demonstrate the program by creating a directory that will serve as
the new root filesystem and placing a copy of the (statically linked)
.BR busybox (1)
executable in that directory.
-.PP
+.P
.in +4n
.EX
$ \fBmkdir /tmp/rootfs\fP
.in
.SS Program source
\&
-.PP
+.P
.\" SRC BEGIN (pivot_root.c)
.EX
/* pivot_root_demo.c */
.nf
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <sys/mman.h>
-.PP
+.P
.BI "int pkey_alloc(unsigned int " flags ", unsigned int " access_rights ");"
.BI "int pkey_free(int " pkey ");"
.fi
.BR pkey_alloc ()
allocates a protection key (pkey) and allows it to be passed to
.BR pkey_mprotect (2).
-.PP
+.P
The
.BR pkey_alloc ()
.I flags
is reserved for future use and currently must always be specified as 0.
-.PP
+.P
The
.BR pkey_alloc ()
.I access_rights
.TP
.B PKEY_DISABLE_WRITE
Disable write access to memory covered by the returned protection key.
-.PP
+.P
.BR pkey_free ()
frees a protection key and makes it available for later
allocations.
After a protection key has been freed, it may no longer be used
in any protection-key-related operations.
-.PP
+.P
An application should not call
.BR pkey_free ()
on any protection key which has been assigned to an address
and will simply fail with the error
.B ENOSPC
if the operating system has no pkey support.
-.PP
+.P
The kernel guarantees that the contents of the hardware rights
register (PKRU) will be preserved only for allocated protection
keys.
.SH SYNOPSIS
.nf
.B #include <poll.h>
-.PP
+.P
.BI "int poll(struct pollfd *" fds ", nfds_t " nfds ", int " timeout );
-.PP
+.P
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <poll.h>
-.PP
+.P
.BI "int ppoll(struct pollfd *" fds ", nfds_t " nfds ,
.BI " const struct timespec *_Nullable " tmo_p ,
.BI " const sigset_t *_Nullable " sigmask );
.BR epoll (7)
API performs a similar task, but offers features beyond those found in
.BR poll ().
-.PP
+.P
The set of file descriptors to be monitored is specified in the
.I fds
argument, which is an array of structures of the following form:
-.PP
+.P
.in +4n
.EX
struct pollfd {
};
.EE
.in
-.PP
+.P
The caller should specify the number of items in the
.I fds
array in
.IR nfds .
-.PP
+.P
The field
.I fd
contains a file descriptor for an open file.
call: simply set the
.I fd
field to its bitwise complement.)
-.PP
+.P
The field
.I events
is an input parameter, a bit mask specifying the events the application
and
.B POLLNVAL
(see below).
-.PP
+.P
The field
.I revents
is an output parameter, filled by the kernel with the events that
field, and will be set in the
.I revents
field whenever the corresponding condition is true.)
-.PP
+.P
If none of the events requested (and no error) has occurred for any
of the file descriptors, then
.BR poll ()
blocks until one of the events occurs.
-.PP
+.P
The
.I timeout
argument specifies the number of milliseconds that
the call is interrupted by a signal handler; or
.IP \[bu]
the timeout expires.
-.PP
+.P
Being "ready" means that the requested operation will not block; thus,
.BR poll ()ing
regular files,
and other files with no reasonable polling semantic
.I always
returns instantly as ready to read and write.
-.PP
+.P
Note that the
.I timeout
interval will be rounded up to the system clock granularity,
of zero causes
.BR poll ()
to return immediately, even if no file descriptors are ready.
-.PP
+.P
The bits that may be set/returned in
.I events
and
.IR revents ;
ignored in
.IR events ).
-.PP
+.P
When compiling with
.B _XOPEN_SOURCE
defined, one also has the following,
.TP
.B POLLWRBAND
Priority data may be written.
-.PP
+.P
Linux also knows about, but does not use
.BR POLLMSG .
.SS ppoll()
.BR ppoll ()
allows an application to safely wait until either a file descriptor
becomes ready or until a signal is caught.
-.PP
+.P
Other than the difference in the precision of the
.I timeout
argument, the following
.BR ppoll ()
call:
-.PP
+.P
.in +4n
.EX
ready = ppoll(&fds, nfds, tmo_p, &sigmask);
.EE
.in
-.PP
+.P
is nearly equivalent to
.I atomically
executing the following calls:
-.PP
+.P
.in +4n
.EX
sigset_t origmask;
pthread_sigmask(SIG_SETMASK, &origmask, NULL);
.EE
.in
-.PP
+.P
The above code segment is described as
.I nearly
equivalent because whereas a negative
.I *tmo_p
results in an error from
.BR ppoll ().
-.PP
+.P
See the description of
.BR pselect (2)
for an explanation of why
.BR ppoll ()
is necessary.
-.PP
+.P
If the
.I sigmask
argument is specified as NULL, then
only in the precision of the
.I timeout
argument).
-.PP
+.P
The
.I tmo_p
argument specifies an upper limit on the amount of time that
This argument is a pointer to a
.BR timespec (3)
structure.
-.PP
+.P
If
.I tmo_p
is specified as NULL, then
fields have been set to a nonzero value (indicating an event or an error).
A return value of zero indicates that the system call timed out
before any file descriptors became ready.
-.PP
+.P
On error, \-1 is returned, and
.I errno
is set to indicate the error.
.B EAGAIN
and loop, just as with
.BR EINTR .
-.PP
+.P
Some implementations define the nonstandard constant
.B INFTIM
with the value \-1 for use as a
function does not modify its
.I tmo_p
argument.
-.PP
+.P
The raw
.BR ppoll ()
system call has a fifth argument,
is not affected by the
.B O_NONBLOCK
flag.
-.PP
+.P
For a discussion of what may happen if a file descriptor being monitored by
.BR poll ()
is closed in another thread, see
but some other event occurred (presumably
.BR POLLHUP ),
closes the file descriptor.
-.PP
+.P
Suppose we run the program in one terminal, asking it to open a FIFO:
-.PP
+.P
.in +4n
.EX
$ \fBmkfifo myfifo\fP
$ \fB./poll_input myfifo\fP
.EE
.in
-.PP
+.P
In a second terminal window, we then open the FIFO for writing,
write some data to it, and close the FIFO:
-.PP
+.P
.in +4n
.EX
$ \fBecho aaaaabbbbbccccc > myfifo\fP
.EE
.in
-.PP
+.P
In the terminal where we are running the program, we would then see:
-.PP
+.P
.in +4n
.EX
Opened "myfifo" on fd 3
All file descriptors closed; bye
.EE
.in
-.PP
+.P
In the above output, we see that
.BR poll ()
returned three times:
.SH SYNOPSIS
.nf
.B #include <fcntl.h>
-.PP
+.P
.BI "int posix_fadvise(int " fd ", off_t " offset ", off_t " len \
", int " advice ");"
.fi
-.PP
+.P
.ad l
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR posix_fadvise ():
.nf
_POSIX_C_SOURCE >= 200112L
to announce an intention to access
file data in a specific pattern in the future, thus allowing the kernel
to perform appropriate optimizations.
-.PP
+.P
The \fIadvice\fP applies to a (not necessarily existent) region starting
at \fIoffset\fP and extending for \fIlen\fP bytes (or until the end of
the file if \fIlen\fP is 0) within the file referred to by \fIfd\fP.
The \fIadvice\fP is not binding;
it merely constitutes an expectation on behalf of
the application.
-.PP
+.P
Permissible values for \fIadvice\fP include:
.TP
.B POSIX_FADV_NORMAL
system call that orders the arguments suitably,
but is otherwise exactly the same as
.BR posix_fadvise ().
-.PP
+.P
For example, since Linux 2.6.14, ARM has the following system call:
-.PP
+.P
.in +4n
.EX
.BI "long arm_fadvise64_64(int " fd ", int " advice ,
.BI " loff_t " offset ", loff_t " len );
.EE
.in
-.PP
+.P
These architecture-specific details are generally
hidden from applications by the glibc
.BR posix_fadvise ()
POSIX.1-2008.
.SH HISTORY
POSIX.1-2001.
-.PP
+.P
Kernel support first appeared in Linux 2.5.60;
the underlying system call is called
.BR fadvise64 ().
Library support has been provided since glibc 2.2,
via the wrapper function
.BR posix_fadvise ().
-.PP
+.P
Since Linux 3.18,
.\" commit d3ac21cacc24790eb45d735769f35753f5b56ceb
support for the underlying system call is optional,
depending on the setting of the
.B CONFIG_ADVISE_SYSCALLS
configuration option.
-.PP
+.P
The type of the
.I len
argument was changed from
.I /proc/sys/vm/drop_caches
interface described in
.BR proc (5).
-.PP
+.P
One can obtain a snapshot of which pages of a file are resident
in the buffer cache by opening a file, mapping it with
.BR mmap (2),
.SH SYNOPSIS
.nf
.B #include <sys/prctl.h>
-.PP
+.P
.BI "int prctl(int " option ", ..."
.BI " \fR/*\fP unsigned long " arg2 ", unsigned long " arg3 ,
.BI " unsigned long " arg4 ", unsigned long " arg5 " \fR*/\fP );"
.BR prctl ()
manipulates various aspects of the behavior
of the calling thread or process.
-.PP
+.P
Note that careless use of some
.BR prctl ()
operations can confuse the user-space run-time environment,
so these operations should be used with care.
-.PP
+.P
.BR prctl ()
is called with a first argument describing what to do
(with values defined in \fI<linux/prctl.h>\fP), and further
The requirements for the address are the same as for the
.B PR_SET_MM_START_BRK
option.
-.PP
+.P
The following options are available since Linux 3.5.
.\" commit fe8c7f5cbf91124987106faa3bdf0c8b955c4cf7
.TP
deemed specious,
and the restriction was removed in Linux 4.10 because some
user-space applications needed to perform this operation more than once.
-.PP
+.P
The following options are available since Linux 3.18.
.\" commit f606b77f1a9e362451aca8f81d8f36a3a112139e
.TP
system call (also introduced in Linux 2.1.44
as irix_prctl on the MIPS architecture),
with prototype
-.PP
+.P
.in +4n
.EX
.BI "ptrdiff_t prctl(int " option ", int " arg2 ", int " arg3 );
.EE
.in
-.PP
+.P
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,
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.BI "ssize_t pread(int " fd ", void " buf [. count "], size_t " count ,
.BI " off_t " offset );
.BI "ssize_t pwrite(int " fd ", const void " buf [. count "], size_t " count ,
.BI " off_t " offset );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR pread (),
.BR pwrite ():
.nf
(from the start of the file) into the buffer starting at
.IR buf .
The file offset is not changed.
-.PP
+.P
.BR pwrite ()
writes up to
.I count
at offset
.IR offset .
The file offset is not changed.
-.PP
+.P
The file referenced by
.I fd
must be capable of seeking.
and
.BR pwrite ()
returns the number of bytes written.
-.PP
+.P
Note that it is not an error for a successful call to transfer fewer bytes
than requested (see
.BR read (2)
and
.BR write (2)).
-.PP
+.P
On error, \-1 is returned and
.I errno
is set to indicate the error.
POSIX.1-2008.
.SH HISTORY
POSIX.1-2001.
-.PP
+.P
Added in Linux 2.1.60;
the entries in the i386 system call table were added in Linux 2.1.69.
C library support (including emulation using
and
.BR pwrite ()
wrapper functions transparently deal with the change.
-.PP
+.P
On some 32-bit architectures,
the calling signature for these system calls differ,
for the reasons described in
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.BR "#include <sys/uio.h>" " /* Definition of " "struct iovec" " type */"
.B #include <unistd.h>
-.PP
+.P
.BI "ssize_t syscall(SYS_process_madvise, int " pidfd ,
.BI " const struct iovec *" iovec ", size_t " vlen \
", int " advice ,
.BI " unsigned int " flags ");"
.fi
-.PP
+.P
.IR Note :
glibc provides no wrapper for
.BR process_madvise (),
and
.IR vlen .
The goal of such advice is to improve system or application performance.
-.PP
+.P
The
.I pidfd
argument is a PID file descriptor (see
.BR pidfd_open (2))
that specifies the process to which the advice is to be applied.
-.PP
+.P
The pointer
.I iovec
points to an array of
.I iovec
structures, described in
.BR iovec (3type).
-.PP
+.P
.I vlen
specifies the number of elements in the array of
.I iovec
.I <limits.h>
or accessible via the call
.IR sysconf(_SC_IOV_MAX) ).
-.PP
+.P
The
.I advice
argument is one of the following values:
.B MADV_WILLNEED
See
.BR madvise (2).
-.PP
+.P
The
.I flags
argument is reserved for future use; currently, this argument must be
specified as 0.
-.PP
+.P
The
.I vlen
and
.I iovec
is invalid,
then an error will be returned immediately and no advice will be applied.
-.PP
+.P
The advice might be applied to only a part of
.I iovec
if one of its elements points to an invalid memory region in the
remote process.
No further elements will be processed beyond that point.
(See the discussion regarding partial advice in RETURN VALUE.)
-.PP
+.P
.\" commit 96cfe2c0fd23ea7c2368d14f769d287e7ae1082e
Starting in Linux 5.12,
permission to apply advice to another process is governed by
elements were already processed.
The caller should check the return value to determine whether a partial
advice occurred.
-.PP
+.P
On error, \-1 is returned and
.I errno
is set to indicate the error.
.TP
.B ESRCH
The target process does not exist (i.e., it has terminated and been waited on).
-.PP
+.P
See
.BR madvise (2)
for
.SH HISTORY
Linux 5.10.
.\" commit ecb8ac8b1f146915aa6b96449b66dd48984caacc
-.PP
+.P
Support for this system call is optional,
depending on the setting of the
.B CONFIG_ADVISE_SYSCALLS
configuration option.
-.PP
+.P
When this system call first appeared in Linux 5.10,
permission to apply advice to another process was entirely governed by
ptrace access mode
.SH SYNOPSIS
.nf
.B #include <sys/uio.h>
-.PP
+.P
.BI "ssize_t process_vm_readv(pid_t " pid ,
.BI " const struct iovec *" local_iov ,
.BI " unsigned long " liovcnt ,
.BI " unsigned long " riovcnt ,
.BI " unsigned long " flags ");"
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR process_vm_readv (),
.BR process_vm_writev ():
.nf
("the remote process").
The data moves directly between the address spaces of the two processes,
without passing through kernel space.
-.PP
+.P
The
.BR process_vm_readv ()
system call transfers data from the remote process to the local process.
.I liovcnt
specifies the number of elements in
.IR local_iov .
-.PP
+.P
The
.BR process_vm_writev ()
system call is the converse of
.I remote_iov
have the same meaning as for
.BR process_vm_readv ().
-.PP
+.P
The
.I local_iov
and
.I iovec
structures, described in
.BR iovec (3type).
-.PP
+.P
Buffers are processed in array order.
This means that
.BR process_vm_readv ()
is completely read before proceeding to
.IR remote_iov[1] ,
and so on.
-.PP
+.P
Similarly,
.BR process_vm_writev ()
writes out the entire contents of
.I remote_iov[0]
before proceeding to
.IR remote_iov[1] .
-.PP
+.P
The lengths of
.I remote_iov[i].iov_len
and
do not have to be the same.
Thus, it is possible to split a single local buffer
into multiple remote buffers, or vice versa.
-.PP
+.P
The
.I flags
argument is currently unused and must be set to 0.
-.PP
+.P
The values specified in the
.I liovcnt
and
.IR sysconf(_SC_IOV_MAX) ).
.\" In time, glibc might provide a wrapper that works around this limit,
.\" as is done for readv()/writev()
-.PP
+.P
The count arguments and
.I local_iov
are checked before doing any transfers.
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.
-.PP
+.P
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)
entry.
The first read entry goes up to the page boundary,
while the second starts on the next page boundary.)
-.PP
+.P
Permission to read from or write to another process
is governed by a ptrace access mode
.B PTRACE_MODE_ATTACH_REALCREDS
element.)
The caller should check the return value to determine whether
a partial read/write occurred.
-.PP
+.P
On error, \-1 is returned and
.I errno
is set to indicate the error.
and
.BR process_vm_writev ()
are not guaranteed to be atomic in any way.
-.PP
+.P
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
.I buf1
and the second 10 bytes into
.IR buf2 .
-.PP
+.P
.\" SRC BEGIN (process_vm_readv.c)
.EX
#define _GNU_SOURCE
.SH SYNOPSIS
.nf
.B #include <sys/ptrace.h>
-.PP
+.P
.BI "long ptrace(enum __ptrace_request " request ", pid_t " pid ,
.BI " void *" addr ", void *" data );
.fi
and examine and change the tracee's memory and registers.
It is primarily used to implement breakpoint debugging and system
call tracing.
-.PP
+.P
A tracee first needs to be attached to the tracer.
Attachment and subsequent commands are per thread:
in a multithreaded process,
never "a (possibly multithreaded) process".
Ptrace commands are always sent to
a specific tracee using a call of the form
-.PP
+.P
.in +4n
.EX
ptrace(PTRACE_foo, pid, ...)
.EE
.in
-.PP
+.P
where
.I pid
is the thread ID of the corresponding Linux thread.
-.PP
+.P
(Note that in this page, a "multithreaded process"
means a thread group consisting of threads created using the
.BR clone (2)
.B CLONE_THREAD
flag.)
-.PP
+.P
A process can initiate a trace by calling
.BR fork (2)
and having the resulting child do a
.B PTRACE_ATTACH
or
.BR PTRACE_SEIZE .
-.PP
+.P
While being traced, the tracee will stop each time a signal is delivered,
even if the signal is being ignored.
(An exception is
The tracer then causes the tracee to continue,
optionally ignoring the delivered signal
(or even delivering a different signal instead).
-.PP
+.P
If the
.B PTRACE_O_TRACEEXEC
option is not in effect, all successful calls to
signal,
giving the parent a chance to gain control before the new program
begins execution.
-.PP
+.P
When the tracer is finished tracing, it can cause the tracee to continue
executing in a normal, untraced mode via
.BR PTRACE_DETACH .
-.PP
+.P
The value of
.I request
determines the action to be performed:
.RB ( __SI_CHLD ,
.BR __SI_FAULT ,
etc.) that are not otherwise exposed to user space.
-.PP
+.P
.in +4n
.EX
struct ptrace_peeksiginfo_args {
Tracees report their death to their tracer(s).
Notification of this event is delivered via
.BR waitpid (2).
-.PP
+.P
Note that the killing signal will first cause signal-delivery-stop
(on one tracee only),
and only after it is injected by the tracer
.I all
tracees within a multithreaded process.
(The term "signal-delivery-stop" is explained below.)
-.PP
+.P
.B SIGKILL
does not generate signal-delivery-stop and
therefore the tracer can't suppress it.
.B SIGKILL
always kills the process (all its threads),
even if some threads of the process are ptraced.
-.PP
+.P
When the tracee calls
.BR _exit (2),
it reports its death to its tracer.
Other threads are not affected.
-.PP
+.P
When any thread executes
.BR exit_group (2),
every tracee in its thread group reports its death to its tracer.
-.PP
+.P
If the
.B PTRACE_O_TRACEEXIT
option is on,
and when threads are torn down on
.BR execve (2)
in a multithreaded process.
-.PP
+.P
The tracer cannot assume that the ptrace-stopped tracee exists.
There are many scenarios when the tracee may die while stopped (such as
.BR SIGKILL ).
may return 0 instead.
In other words, the tracee may be "not yet fully dead",
but already refusing ptrace requests.
-.PP
+.P
The tracer can't assume that the tracee
.I always
ends its life by reporting
it will not respond to signals until
.B SIGCONT
is received.
-.PP
+.P
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.
-.PP
+.P
In this manual page, any stopped state in which the tracee is ready
to accept ptrace commands from the tracer is called
.IR ptrace-stop .
.IR "PTRACE_EVENT stops" ,
and so on.
These stopped states are described in detail below.
-.PP
+.P
When the running tracee enters ptrace-stop, it notifies its tracer using
.BR waitpid (2)
(or one of the other "wait" system calls).
Most of this manual page assumes that the tracer waits with:
-.PP
+.P
.in +4n
.EX
pid = waitpid(pid_or_minus_1, &status, __WALL);
.EE
.in
-.PP
+.P
Ptrace-stopped tracees are reported as returns with
.I pid
greater than 0 and
.\" rules different if user wants to use waitid? Will waitid require
.\" WEXITED?
.\"
-.PP
+.P
The
.B __WALL
flag does not include the
and
.B WEXITED
flags, but implies their functionality.
-.PP
+.P
Setting the
.B WCONTINUED
flag when calling
.BR waitpid (2)
is not recommended: the "continued" state is per-process and
consuming it can confuse the real parent of the tracee.
-.PP
+.P
Use of the
.B WNOHANG
flag may cause
to return 0 ("no wait results available yet")
even if the tracer knows there should be a notification.
Example:
-.PP
+.P
.in +4n
.EX
errno = 0;
.\" FIXME .
.\" waitid usage? WNOWAIT?
.\" describe how wait notifications queue (or not queue)
-.PP
+.P
The following kinds of ptrace-stops exist: signal-delivery-stops,
group-stops,
.B PTRACE_EVENT
with the usual exception that
.B SIGSTOP
can't be blocked.
-.PP
+.P
Signal-delivery-stop is observed by the tracer as
.BR waitpid (2)
returning with
.SS Signal injection and suppression
After signal-delivery-stop is observed by the tracer,
the tracer should restart the tracee with the call
-.PP
+.P
.in +4n
.EX
ptrace(PTRACE_restart, pid, 0, sig)
.EE
.in
-.PP
+.P
where
.B PTRACE_restart
is one of the restarting ptrace requests.
This operation is called
.I "signal injection"
in this manual page, to distinguish it from signal-delivery-stop.
-.PP
+.P
The
.I sig
value may be different from the
.I WSTOPSIG(status)
value: the tracer can cause a different signal to be injected.
-.PP
+.P
Note that a suppressed signal still causes system calls to return
prematurely.
In this case, system calls will be restarted: the tracer will
however, kernel bugs exist which cause some system calls to fail with
.B EINTR
even though no observable signal is injected to the tracee.
-.PP
+.P
Restarting ptrace commands issued in ptrace-stops other than
signal-delivery-stop are not guaranteed to inject a signal, even if
.I sig
Ptrace users should not try to "create a new signal" this way: use
.BR tgkill (2)
instead.
-.PP
+.P
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
-.PP
+.P
.in +4n
.EX
ptrace(PTRACE_restart, pid, 0, stopsig)
.EE
.in
-.PP
+.P
with the intention of injecting
.IR stopsig ,
but
.I stopsig
gets ignored and the tracee continues to run.
-.PP
+.P
The
.B SIGCONT
signal has a side effect of waking up (all threads of)
In other words,
.B SIGCONT
may be not the first signal observed by the tracee after it was sent.
-.PP
+.P
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.
-.PP
+.P
In Linux 2.4 and earlier, the
.B SIGSTOP
signal can't be injected.
.\" /* The debugger continued. Ignore SIGSTOP. */
.\" if (signr == SIGSTOP)
.\" continue;
-.PP
+.P
.B PTRACE_GETSIGINFO
can be used to retrieve a
.I siginfo_t
tracees within the multithreaded process.
As usual, every tracee reports its group-stop separately
to the corresponding tracer.
-.PP
+.P
Group-stop is observed by the tracer as
.BR waitpid (2)
returning with
.IR WSTOPSIG(status) .
The same result is returned by some other classes of ptrace-stops,
therefore the recommended practice is to perform the call
-.PP
+.P
.in +4n
.EX
ptrace(PTRACE_GETSIGINFO, pid, 0, &siginfo)
.EE
.in
-.PP
+.P
The call can be avoided if the signal is not
.BR SIGSTOP ,
.BR SIGTSTP ,
("no such process") if a
.B SIGKILL
killed the tracee.)
-.PP
+.P
If tracee was attached using
.BR PTRACE_SEIZE ,
group-stop is indicated by
without requiring an extra
.B PTRACE_GETSIGINFO
call.
-.PP
+.P
As of Linux 2.6.38,
after the tracer sees the tracee ptrace-stop and until it
restarts or kills it, the tracee will not run,
death) to the tracer, even if the tracer enters into another
.BR waitpid (2)
call.
-.PP
+.P
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,
this would cause the
.B SIGCONT
signals to have no effect on the tracee.
-.PP
+.P
Since Linux 3.4, there is a method to overcome this problem: instead of
.BR PTRACE_CONT ,
a
options, the tracee will enter ptrace-stops called
.B PTRACE_EVENT
stops.
-.PP
+.P
.B PTRACE_EVENT
stops are observed by the tracer as
.BR waitpid (2)
the value
.I status>>8
will be
-.PP
+.P
.in +4n
.EX
((PTRACE_EVENT_foo<<8) | SIGTRAP).
.EE
.in
-.PP
+.P
The following events exist:
.TP
.B PTRACE_EVENT_VFORK
.B CLONE_VFORK
flag,
but after the child unblocked this tracee by exiting or execing.
-.PP
+.P
For all four stops described above,
the stop occurs in the parent (i.e., the tracee),
not in the newly created thread.
.BR PTRACE_GETEVENTMSG .
The semantics of this stop are described in
detail in a separate section below.
-.PP
+.P
.B PTRACE_GETSIGINFO
on
.B PTRACE_EVENT
.B PTRACE_SYSEMU
apply equally to
.BR PTRACE_SYSEMU_SINGLESTEP .
-.PP
+.P
However, even if the tracee was continued using
.BR PTRACE_SYSCALL ,
it is not guaranteed that the next stop will be a syscall-exit-stop.
happened in another thread,
and that thread is not traced by the same tracer;
this situation is discussed later).
-.PP
+.P
Syscall-enter-stop and syscall-exit-stop are observed by the tracer as
.BR waitpid (2)
returning with
.I WSTOPSIG(status)
will give the value
.IR "(SIGTRAP\ |\ 0x80)" .
-.PP
+.P
Syscall-stops can be distinguished from signal-delivery-stop with
.B SIGTRAP
by querying
.TP
.IR si_code " == SIGTRAP or " si_code " == (SIGTRAP|0x80)"
This is a syscall-stop.
-.PP
+.P
However, syscall-stops happen very often (twice per system call),
and performing
.B PTRACE_GETSIGINFO
for every syscall-stop may be somewhat expensive.
-.PP
+.P
Some architectures allow the cases to be distinguished
by examining registers.
For example, on x86,
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.
-.PP
+.P
Using the
.B 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.
-.PP
+.P
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
without preceding syscall-entry-stops.
If seccomp is in use, care needs
to be taken not to misinterpret such stops as syscall-entry-stops.
-.PP
+.P
If after syscall-enter-stop,
the tracer uses a restarting command other than
.BR PTRACE_SYSCALL ,
syscall-exit-stop is not generated.
-.PP
+.P
.B PTRACE_GETSIGINFO
on syscall-stops returns
.B SIGTRAP
This documents the behavior
from their introduction until Linux 4.7 (inclusive).
The behavior in later kernel versions is documented in the next section.
-.PP
+.P
A
.B PTRACE_EVENT_SECCOMP
stop occurs whenever a
Notably, seccomp still runs even if the tracee was restarted using
.B PTRACE_SYSEMU
and this system call is unconditionally skipped.
-.PP
+.P
Restarts from this stop will behave as if the stop had occurred right
before the system call in question.
In particular, both
.B PTRACE_EVENT_SECCOMP
will be reported) if the system call is skipped due to
.BR PTRACE_SYSEMU .
-.PP
+.P
Functionally, a
.B PTRACE_EVENT_SECCOMP
stop functions comparably
are visible to the to-be-executed system call as well).
Note that there may be,
but need not have been a preceding syscall-entry-stop.
-.PP
+.P
After a
.B PTRACE_EVENT_SECCOMP
stop, seccomp will be rerun, with a
.BR PTRACE_KILL )
require the tracee to be in a ptrace-stop, otherwise they fail with
.BR ESRCH .
-.PP
+.P
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:
-.PP
+.P
.in +4n
.EX
ptrace(PTRACE_PEEKTEXT/PEEKDATA/PEEKUSER, pid, addr, 0);
ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags);
.EE
.in
-.PP
+.P
Note that some errors are not reported.
For example, setting signal information
.RI ( siginfo )
.B PTRACE_GETEVENTMSG
may succeed and return some random value if current ptrace-stop
is not documented as returning a meaningful event message.
-.PP
+.P
The call
-.PP
+.P
.in +4n
.EX
ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags);
.EE
.in
-.PP
+.P
affects one tracee.
The tracee's current flags are replaced.
Flags are inherited by new tracees created and "auto-attached" via active
or
.B PTRACE_O_TRACECLONE
options.
-.PP
+.P
Another group of commands makes the ptrace-stopped tracee run.
They have the form:
-.PP
+.P
.in +4n
.EX
ptrace(cmd, pid, 0, sig);
.EE
.in
-.PP
+.P
where
.I cmd
is
.IR sig .)
.SS Attaching and detaching
A thread can be attached to the tracer using the call
-.PP
+.P
.in +4n
.EX
ptrace(PTRACE_ATTACH, pid, 0, 0);
.EE
.in
-.PP
+.P
or
-.PP
+.P
.in +4n
.EX
ptrace(PTRACE_SEIZE, pid, 0, PTRACE_O_flags);
.EE
.in
-.PP
+.P
.B PTRACE_ATTACH
sends
.B SIGSTOP
may be lost.
.\"
.\" FIXME Describe how to attach to a thread which is already group-stopped.
-.PP
+.P
Since attaching sends
.B SIGSTOP
and the tracer usually suppresses it, this may cause a stray
.B EINTR
return from the currently executing system call in the tracee,
as described in the "Signal injection and suppression" section.
-.PP
+.P
Since Linux 3.4,
.B PTRACE_SEIZE
can be used instead of
use
.B PTRACE_INTERRUPT
command.
-.PP
+.P
The request
-.PP
+.P
.in +4n
.EX
ptrace(PTRACE_TRACEME, 0, 0, 0);
.EE
.in
-.PP
+.P
turns the calling thread into a tracee.
The thread continues to run (doesn't enter ptrace-stop).
A common practice is to follow the
.B PTRACE_TRACEME
with
-.PP
+.P
.in +4n
.EX
raise(SIGSTOP);
.EE
.in
-.PP
+.P
and allow the parent (which is our tracer now) to observe our
signal-delivery-stop.
-.PP
+.P
If the
.BR PTRACE_O_TRACEFORK ,
.BR PTRACE_O_TRACEVFORK ,
.B SIGSTOP
is delivered to the children, causing them to enter
signal-delivery-stop after they exit the system call which created them.
-.PP
+.P
Detaching of the tracee is performed by:
-.PP
+.P
.in +4n
.EX
ptrace(PTRACE_DETACH, pid, 0, sig);
.EE
.in
-.PP
+.P
.B PTRACE_DETACH
is a restarting operation;
therefore it requires the tracee to be in ptrace-stop.
Otherwise, the
.I sig
parameter may be silently ignored.
-.PP
+.P
If the tracee is running when the tracer wants to detach it,
the usual solution is to send
.B SIGSTOP
.BR SIGSTOP .
.\" FIXME Describe how to detach from a group-stopped tracee so that it
.\" doesn't run, but continues to wait for SIGCONT.
-.PP
+.P
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,
.BR execve (2)
it will appear as if it has become a tracee of
the tracer of the execing tracee.
-.PP
+.P
All of the above effects are the artifacts of
the thread ID change in the tracee.
-.PP
+.P
The
.B PTRACE_O_TRACEEXEC
option is the recommended tool for dealing with this situation.
.B SIGTRAP
generation on
.BR execve (2).
-.PP
+.P
When the tracer receives
.B 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.
-.PP
+.P
On receiving the
.B PTRACE_EVENT_EXEC
stop notification,
data structures describing the threads of this process,
and retain only one data structure\[em]one which
describes the single still running tracee, with
-.PP
+.P
.in +4n
.EX
thread ID == thread group ID == process ID.
.EE
.in
-.PP
+.P
Example: two threads call
.BR execve (2)
at the same time:
-.PP
+.P
.nf
*** we get syscall-enter-stop in thread 1: **
PID1 execve("/bin/foo", "foo" <unfinished ...>
*** we get syscall-exit-stop for PID0: **
PID0 <... execve resumed> ) = 0
.fi
-.PP
+.P
If the
.B PTRACE_O_TRACEEXEC
option is
.RI ( SI_USER ).
This signal may be blocked by signal mask,
and thus may be delivered (much) later.
-.PP
+.P
Usually, the tracer (for example,
.BR strace (1))
would not want to show this extra post-execve
several kinds of
.BR waitpid (2)
notifications when the child process is traced by some other process.
-.PP
+.P
Many of these bugs have been fixed, but as of Linux 2.6.38 several still
exist; see BUGS below.
-.PP
+.P
As of Linux 2.6.38, the following is believed to work correctly:
.IP \[bu] 3
exit/death by signal is reported first to the tracer, then,
.B PTRACE_GET_SYSCALL_INFO
request returns the number of bytes available to be written by the kernel,
and other requests return zero.
-.PP
+.P
On error, all requests return \-1, and
.I errno
is set to indicate the error.
None.
.SH HISTORY
SVr4, 4.3BSD.
-.PP
+.P
Before Linux 2.6.26,
.\" See commit 00cd5c37afd5f431ac186dd131705048c0a11fdb
.BR init (1),
.I 0L
or
.IR "(void\ *)\ 0".
-.PP
+.P
A tracees parent continues to be the tracer even if that tracer calls
.BR execve (2).
-.PP
+.P
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
.IR "struct user" .
.\" See http://lkml.org/lkml/2008/5/8/375
-.PP
+.P
The size of a "word" is determined by the operating-system variant
(e.g., for 32-bit Linux it is 32 bits).
-.PP
+.P
This page documents the way the
.BR ptrace ()
call works currently in Linux.
and the results of checks performed by any enabled Linux Security Module
(LSM)\[em]for example, SELinux, Yama, or Smack\[em]and by the commoncap LSM
(which is always invoked).
-.PP
+.P
Prior to Linux 2.6.27, all access checks were of a single type.
Since Linux 2.6.27,
.\" commit 006ebb40d3d65338bd74abb03b945f8d60e362bd
.\" about proper handling of /proc/pid/fd. Arguably that one might belong
.\" back in the _ATTACH camp.
.\"
-.PP
+.P
Since Linux 4.5,
.\" commit caaee6234d05a58c5b4d05e7bf766131b810a657
the above access mode checks are combined (ORed) with
.B PTRACE_MODE_REALCREDS
Use the caller's real UID and GID or permitted capabilities for LSM checks.
This was effectively the default before Linux 4.5.
-.PP
+.P
Because combining one of the credential modifiers with one of
the aforementioned access modes is typical,
some macros are defined in the kernel sources for the combinations:
.B PTRACE_MODE_ATTACH_REALCREDS
Defined as
.BR "PTRACE_MODE_ATTACH | PTRACE_MODE_REALCREDS" .
-.PP
+.P
One further modifier can be ORed with the access mode:
.TP
.BR PTRACE_MODE_NOAUDIT " (since Linux 3.3)"
there is no reason to generate a security audit record.
This modifier suppresses the generation of
such an audit record for the particular access check.
-.PP
+.P
Note that all of the
.B PTRACE_MODE_*
constants described in this subsection are kernel-internal,
.IR /proc ).
These names are used in other manual pages to provide a simple
shorthand for labeling the different kernel checks.
-.PP
+.P
The algorithm employed for ptrace access mode checking determines whether
the calling process is allowed to perform the corresponding action
on the target process.
(e.g., a GPG agent or an SSH session) owned by the user in order
to gain additional credentials that may exist in memory
and thus expand the scope of the attack.
-.PP
+.P
More precisely, the Yama LSM limits two types of operations:
.IP \[bu] 3
Any operation that performs a ptrace access mode
.IP \[bu]
.BR ptrace ()
.BR PTRACE_TRACEME .
-.PP
+.P
A process that has the
.B CAP_SYS_PTRACE
capability can update the
.BR PTRACE_TRACEME .
.IP
Once this value has been written to the file, it cannot be changed.
-.PP
+.P
With respect to values 1 and 2,
note that creating a new user namespace effectively removes the
protection offered by Yama.
to
.BR PTRACE_OLDSETOPTIONS ,
if that is defined.
-.PP
+.P
Group-stop notifications are sent to the tracer, but not to real parent.
Last confirmed on 2.6.38.6.
-.PP
+.P
If a thread group leader is traced and exits by calling
.BR _exit (2),
.\" Note from Denys Vlasenko:
the thread group leader instead of restarting it in this case.
Last confirmed on 2.6.38.6.
.\" FIXME . need to test/verify this scenario
-.PP
+.P
A
.B SIGKILL
signal may still cause a
.B SIGKILL
is meant to always immediately kill tasks even under ptrace.
Last confirmed on Linux 3.13.
-.PP
+.P
Some system calls return with
.B EINTR
if a signal was sent to a tracee, but delivery was suppressed by the tracer.
file descriptor.
The usual symptom of this bug is that when you attach to
a quiescent process with the command
-.PP
+.P
.in +4n
.EX
strace \-p <process\-ID>
.EE
.in
-.PP
+.P
then, instead of the usual
and expected one-line output such as
-.PP
+.P
.in +4n
.EX
restart_syscall(<... resuming interrupted call ...>_
.EE
.in
-.PP
+.P
or
-.PP
+.P
.in +4n
.EX
select(6, [5], NULL, [5], NULL_
.EE
.in
-.PP
+.P
('_' denotes the cursor position), you observe more than one line.
For example:
-.PP
+.P
.in +4n
.EX
clock_gettime(CLOCK_MONOTONIC, {15370, 690928118}) = 0
epoll_wait(4,_
.EE
.in
-.PP
+.P
What is not visible here is that the process was blocked in
.BR epoll_wait (2)
before
errors may behave in an unintended way upon an
.BR strace (1)
attach.)
-.PP
+.P
Contrary to the normal rules, the glibc wrapper for
.BR ptrace ()
can set
.SH SYNOPSIS
.nf
.B #include <linux/module.h>
-.PP
+.P
.BI "[[deprecated]] int query_module(const char *" name ", int " which ,
.BI " void " buf [. bufsize "], \
size_t " bufsize ,
.SH DESCRIPTION
.IR Note :
This system call is present only before Linux 2.6.
-.PP
+.P
.BR query_module ()
requests information from the kernel about loadable modules.
The returned information is placed in the buffer pointed to by
to identify a currently loaded module, some allow
.I name
to be NULL, indicating the kernel proper.
-.PP
+.P
The following values can be specified for
.IR which :
.TP
.SH VERSIONS
Removed in Linux 2.6.
.\" Removed in Linux 2.5.48
-.PP
+.P
Some of the information that was formerly available via
.BR query_module ()
can be obtained from
.IR /proc/kallsyms ,
and the files under the directory
.IR /sys/module .
-.PP
+.P
The
.BR query_module ()
system call is not supported by glibc.
.BR "#include <xfs/xqm.h>" " /* Definition of " Q_X* " and " XFS_QUOTA_* \
" constants"
.RB " (or " <linux/dqblk_xfs.h> "; see NOTES) */"
-.PP
+.P
.BI "int quotactl(int " cmd ", const char *_Nullable " special ", int " id ,
.BI " caddr_t " addr );
.fi
Moreover, the user can't exceed the soft limit for more than grace period
duration (one week by default) at a time;
after this, the soft limit counts as a hard limit.
-.PP
+.P
The
.BR quotactl ()
call manipulates disk quotas.
The
.I subcmd
value is described below.
-.PP
+.P
The
.I special
argument is a pointer to a null-terminated string containing the pathname
of the (mounted) block special device for the filesystem being manipulated.
-.PP
+.P
The
.I addr
argument is the address of an optional, command-specific, data structure
The interpretation of
.I addr
is given with each operation below.
-.PP
+.P
The
.I subcmd
value is one of the following operations:
Files in
.I /proc/sys/fs/quota/
carry the information instead.
-.PP
+.P
For XFS filesystems making use of the XFS Quota Manager (XQM),
the above operations are bypassed and the following operations are used:
.TP
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.BI "ssize_t read(int " fd ", void " buf [. count "], size_t " count );
.fi
.SH DESCRIPTION
.I fd
into the buffer starting at
.IR buf .
-.PP
+.P
On files that support seeking,
the read operation commences at the file offset,
and the file offset is incremented by the number of bytes read.
no bytes are read, and
.BR read ()
returns zero.
-.PP
+.P
If
.I count
is zero,
with a
.I count
of 0 returns zero and has no other effects.
-.PP
+.P
According to POSIX.1, if
.I count
is greater than
.BR read ()
was interrupted by a signal.
See also NOTES.
-.PP
+.P
On error, \-1 is returned, and
.I errno
is set to indicate the error.
.B EISDIR
.I fd
refers to a directory.
-.PP
+.P
Other errors may occur, depending on the object connected to
.IR fd .
.SH STANDARDS
returning the number of bytes actually transferred.
.\" commit e28cc71572da38a5a12c1cfe4d7032017adccf69
(This is true on both 32-bit and 64-bit systems.)
-.PP
+.P
On NFS filesystems, reading small amounts of data will update the
timestamp only the first time, subsequent calls may not do so.
This is caused
.SH BUGS
According to POSIX.1-2008/SUSv4 Section XSI 2.9.7
("Thread Interactions with Regular File Operations"):
-.PP
+.P
.RS 4
All of the following functions shall be atomic with respect to
each other in the effects specified in POSIX.1-2008 when they
operate on regular files or symbolic links: ...
.RE
-.PP
+.P
Among the APIs subsequently listed are
.BR read ()
and
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #define _FILE_OFFSET_BITS 64
.B #include <fcntl.h>
-.PP
+.P
.BI "ssize_t readahead(int " fd ", off_t " offset ", size_t " count );
.fi
.SH DESCRIPTION
be satisfied from the cache, and not block on disk I/O
(assuming the readahead was initiated early enough and that other activity
on the system did not in the meantime flush pages from the cache).
-.PP
+.P
The
.I fd
argument is a file descriptor identifying the file which is
.nf
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "int syscall(SYS_readdir, unsigned int " fd ,
.BI " struct old_linux_dirent *" dirp ", unsigned int " count );
.fi
-.PP
+.P
.IR Note :
There is no definition of
.BR "struct old_linux_dirent" ;
This page documents the bare kernel system call interface,
which is superseded by
.BR getdents (2).
-.PP
+.P
.BR readdir ()
reads one
.I old_linux_dirent
is ignored; at most one
.I old_linux_dirent
structure is read.
-.PP
+.P
The
.I old_linux_dirent
structure is declared (privately in Linux kernel file
.BR fs/readdir.c )
as follows:
-.PP
+.P
.in +4n
.EX
struct old_linux_dirent {
}
.EE
.in
-.PP
+.P
.I d_ino
is an inode number.
.I d_offset
However, probably you should use
.BR readdir (3)
instead.
-.PP
+.P
This system call does not exist on x86-64.
.SH STANDARDS
Linux.
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.BI "ssize_t readlink(const char *restrict " pathname ", char *restrict " buf ,
.BI " size_t " bufsiz );
-.PP
+.P
.BR "#include <fcntl.h> " "/* Definition of " AT_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "ssize_t readlinkat(int " dirfd ", const char *restrict " pathname ,
.BI " char *restrict " buf ", size_t " bufsiz );
-.PP
+.P
.fi
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR readlink ():
.nf
_XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 200112L
.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
|| /* glibc <= 2.19: */ _BSD_SOURCE
.fi
-.PP
+.P
.BR readlinkat ():
.nf
Since glibc 2.10:
system call operates in exactly the same way as
.BR readlink (),
except for the differences described here.
-.PP
+.P
If the pathname given in
.I pathname
is relative, then it is interpreted relative to the directory
the calling process, as is done by
.BR readlink ()
for a relative pathname).
-.PP
+.P
If
.I pathname
is relative and
is interpreted relative to the current working
directory of the calling process (like
.BR readlink ()).
-.PP
+.P
If
.I pathname
is absolute, then
.I dirfd
is ignored.
-.PP
+.P
Since Linux 2.6.39,
.\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d
.I pathname
and
.B O_NOFOLLOW
flags).
-.PP
+.P
See
.BR openat (2)
for an explanation of the need for
POSIX.1-2008.
Linux 2.6.16,
glibc 2.4.
-.PP
+.P
Up to and including glibc 2.4, the return type of
.BR readlink ()
was declared as
in cases where
.BR lstat (2)
reports a size of zero.
-.PP
+.P
.\" SRC BEGIN (readlink.c)
.EX
#include <limits.h>
.SH SYNOPSIS
.nf
.B #include <sys/uio.h>
-.PP
+.P
.BI "ssize_t readv(int " fd ", const struct iovec *" iov ", int " iovcnt );
.BI "ssize_t writev(int " fd ", const struct iovec *" iov ", int " iovcnt );
-.PP
+.P
.BI "ssize_t preadv(int " fd ", const struct iovec *" iov ", int " iovcnt ,
.BI " off_t " offset );
.BI "ssize_t pwritev(int " fd ", const struct iovec *" iov ", int " iovcnt ,
.BI " off_t " offset );
-.PP
+.P
.BI "ssize_t preadv2(int " fd ", const struct iovec *" iov ", int " iovcnt ,
.BI " off_t " offset ", int " flags );
.BI "ssize_t pwritev2(int " fd ", const struct iovec *" iov ", int " iovcnt ,
.BI " off_t " offset ", int " flags );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR preadv (),
.BR pwritev ():
.nf
into the buffers described by
.I iov
("scatter input").
-.PP
+.P
The
.BR writev ()
system call writes
to the file associated with the file descriptor
.I fd
("gather output").
-.PP
+.P
The pointer
.I iov
points to an array of
structures,
described in
.BR iovec (3type).
-.PP
+.P
The
.BR readv ()
system call works just like
.BR read (2)
except that multiple buffers are filled.
-.PP
+.P
The
.BR writev ()
system call works just like
.BR write (2)
except that multiple buffers are written out.
-.PP
+.P
Buffers are processed in array order.
This means that
.BR readv ()
before proceeding to
.IR iov[1] ,
and so on.
-.PP
+.P
The data transfers performed by
.BR readv ()
and
.IR offset ,
which specifies the file offset at which the input operation
is to be performed.
-.PP
+.P
The
.BR pwritev ()
system call combines the functionality of
.IR offset ,
which specifies the file offset at which the output operation
is to be performed.
-.PP
+.P
The file offset is not changed by these system calls.
The file referred to by
.I fd
calls, but add a fifth argument,
.IR flags ,
which modifies the behavior on a per-call basis.
-.PP
+.P
Unlike
.BR preadv ()
and
if the
.I offset
argument is \-1, then the current file offset is used and updated.
-.PP
+.P
The
.I flags
argument contains a bitwise OR of zero or more of the following flags:
and
.BR pwritev2 ()
return the number of bytes written.
-.PP
+.P
Note that it is not an error for a successful call to transfer fewer bytes
than requested (see
.BR read (2)
and
.BR write (2)).
-.PP
+.P
On error, \-1 is returned, and \fIerrno\fP is set to indicate the error.
.SH ERRORS
The errors are as given for
The final argument,
.IR offset ,
is unpacked by the wrapper functions into two arguments in the system calls:
-.PP
+.P
.BI " unsigned long " pos_l ", unsigned long " pos
-.PP
+.P
These arguments contain, respectively, the low order and high order 32 bits of
.IR offset .
.SH STANDARDS
.\" and \fIint\fP as the return type.
.\" The readv/writev system calls were buggy before Linux 1.3.40.
.\" (Says release.libc.)
-.PP
+.P
.BR preadv (),
.BR pwritev ():
Linux 2.6.30,
glibc 2.10.
-.PP
+.P
.BR preadv2 (),
.BR pwritev2 ():
Linux 4.6,
.BR writev ()
performed the analogous task using a temporary buffer and a call to
.BR write (2).
-.PP
+.P
The need for this extra effort in the glibc wrapper functions
went away with Linux 2.2 and later.
However, glibc continued to provide this behavior until glibc 2.10.
.SH EXAMPLES
The following code sample demonstrates the use of
.BR writev ():
-.PP
+.P
.in +4n
.EX
char *str0 = "hello ";
.nf
.RB "/* Since Linux 2.1.30 there are symbolic names " LINUX_REBOOT_*
for the constants and a fourth argument to the call: */
-.PP
+.P
.BR "#include <linux/reboot.h> " \
"/* Definition of " LINUX_REBOOT_* " constants */"
.BR "#include <sys/syscall.h> " "/* Definition of " SYS_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "int syscall(SYS_reboot, int " magic ", int " magic2 ", int " cmd ", void *" arg );
-.PP
+.P
/* Under glibc and most alternative libc's (including uclibc, dietlibc,
musl and a few others), some of the constants involved have gotten
.RB " symbolic names " RB_* ", and the library call is a 1-argument"
wrapper around the system call: */
-.PP
+.P
.BR "#include <sys/reboot.h> " "/* Definition of " RB_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "int reboot(int " cmd );
.fi
.SH DESCRIPTION
(abbreviated CAD, since the default is Ctrl-Alt-Delete;
it can be changed using
.BR loadkeys (1)).
-.PP
+.P
This system call fails (with the error
.BR EINVAL )
unless
are permitted as values for
.IR magic2 .
(The hexadecimal values of these constants are meaningful.)
-.PP
+.P
The
.I cmd
argument can have the following values:
The system is suspended (hibernated) to disk.
This option is available only if the kernel was configured with
.BR CONFIG_HIBERNATION .
-.PP
+.P
Only the superuser may call
.BR reboot ().
-.PP
+.P
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
the "init" process of the PID namespace is immediately terminated,
with the effects described in
.BR pid_namespaces (7).
-.PP
+.P
The values that can be supplied in
.I cmd
when calling
in the parent process reports that the child was killed with a
.B SIGINT
signal.
-.PP
+.P
For the other
.I cmd
values,
.SH SYNOPSIS
.nf
.B #include <sys/socket.h>
-.PP
+.P
.BI "ssize_t recv(int " sockfd ", void " buf [. len "], size_t " len ,
.BI " int " flags );
.BI "ssize_t recvfrom(int " sockfd ", void " buf "[restrict ." len "], size_t " len ,
to receive data on both connectionless and connection-oriented sockets.
This page first describes common features of all three system calls,
and then describes the differences between the calls.
-.PP
+.P
The only difference between
.BR recv ()
and
.BR read (2)
(but see NOTES).
Also, the following call
-.PP
+.P
.in +4n
.EX
recv(sockfd, buf, len, flags);
.EE
.in
-.PP
+.P
is equivalent to
-.PP
+.P
.in +4n
.EX
recvfrom(sockfd, buf, len, flags, NULL, NULL);
.EE
.in
-.PP
+.P
All three calls 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.
-.PP
+.P
If no messages are available at the socket, the receive calls wait for a
message to arrive, unless the socket is nonblocking (see
.BR fcntl (2)),
.BR 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.
-.PP
+.P
An application can use
.BR select (2),
.BR poll (2),
.IR buf .
The caller must specify the size of the buffer in
.IR len .
-.PP
+.P
If
.I src_addr
is not NULL,
in this case,
.I addrlen
will return a value greater than was supplied to the call.
-.PP
+.P
If the caller is not interested in the source address,
.I src_addr
and
socket (see
.BR connect (2)).
It is equivalent to the call:
-.PP
+.P
.in +4n
.EX
recvfrom(fd, buf, len, flags, NULL, 0);
structure to minimize the number of directly supplied arguments.
This structure is defined as follows in
.IR <sys/socket.h> :
-.PP
+.P
.in +4n
.EX
struct msghdr {
};
.EE
.in
-.PP
+.P
The
.I msg_name
field points to a caller-allocated buffer that is used to
If the application does not need to know the source address,
.I msg_name
can be specified as NULL.
-.PP
+.P
The fields
.I msg_iov
and
.I msg_iovlen
describe scatter-gather locations, as discussed in
.BR readv (2).
-.PP
+.P
The field
.IR msg_control ,
which has length
.IR msg_control ;
upon return from a successful call it will contain the length
of the control message sequence.
-.PP
+.P
The messages are of the form:
-.PP
+.P
.in +4n
.EX
struct cmsghdr {
};
.EE
.in
-.PP
+.P
Ancillary data should be accessed only by the macros defined in
.BR cmsg (3).
-.PP
+.P
As an example, Linux uses this ancillary data mechanism to pass extended
errors, IP options, or file descriptors over UNIX domain sockets.
For further information on the use of ancillary data in various
.BR unix (7)
and
.BR ip (7).
-.PP
+.P
The
.I msg_flags
field in the
In the event of an error,
.I errno
is set to indicate the error.
-.PP
+.P
When a stream socket peer has performed an orderly shutdown,
the return value will be 0 (the traditional "end-of-file" return).
-.PP
+.P
Datagram sockets in various domains (e.g., the UNIX and Internet domains)
permit zero-length datagrams.
When such a datagram is received, the return value is 0.
-.PP
+.P
The value 0 may also be returned if the requested number of bytes
to receive from a stream socket was 0.
.SH ERRORS
.SH HISTORY
POSIX.1-2001,
4.4BSD (first appeared in 4.2BSD).
-.PP
+.P
POSIX.1 describes only the
.BR MSG_OOB ,
.BR MSG_PEEK ,
has no effect (the datagram remains pending), while
.BR recv ()
consumes the pending datagram.
-.PP
+.P
See
.BR recvmmsg (2)
for information about a Linux-specific system call
.nf
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <sys/socket.h>
-.PP
+.P
.BI "int recvmmsg(int " sockfd ", struct mmsghdr *" msgvec \
", unsigned int " vlen ","
.BI " int " flags ", struct timespec *" timeout ");"
A further extension over
.BR recvmsg (2)
is support for a timeout on the receive operation.
-.PP
+.P
The
.I sockfd
argument is the file descriptor of the socket to receive data from.
-.PP
+.P
The
.I msgvec
argument is a pointer to an array of
structures.
The size of this array is specified in
.IR vlen .
-.PP
+.P
The
.I mmsghdr
structure is defined in
.I <sys/socket.h>
as:
-.PP
+.P
.in +4n
.EX
struct mmsghdr {
};
.EE
.in
-.PP
+.P
The
.I msg_hdr
field is a
This field has the same value as the return value of a single
.BR recvmsg (2)
on the header.
-.PP
+.P
The
.I flags
argument contains flags ORed together.
Turns on
.B MSG_DONTWAIT
after the first message has been received.
-.PP
+.P
The
.I timeout
argument points to a
If
.I timeout
is NULL, then the operation blocks indefinitely.
-.PP
+.P
A blocking
.BR recvmmsg ()
call blocks until
(up to the limit specified by
.IR vlen )
and returns immediately.
-.PP
+.P
On return from
.BR recvmmsg (),
successive elements of
.B EINVAL
.I timeout
is invalid.
-.PP
+.P
See also BUGS.
.SH STANDARDS
Linux.
.I vlen\-1
datagrams are received before the timeout expires,
but then no further datagrams are received, the call will block forever.
-.PP
+.P
If an error occurs after at least one message has been received,
the call succeeds, and returns the number of messages received.
The error code is expected to be returned on a subsequent call to
them in multiple buffers.
The call returns if all buffers are filled or if the
timeout specified has expired.
-.PP
+.P
The following snippet periodically generates UDP datagrams
containing a random number:
-.PP
+.P
.in +4n
.EX
.RB "$" " while true; do echo $RANDOM > /dev/udp/127.0.0.1/1234;"
.B " sleep 0.25; done"
.EE
.in
-.PP
+.P
These datagrams are read by the example application, which
can give the following output:
-.PP
+.P
.in +4n
.EX
.RB "$" " ./a.out"
.nf
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <sys/mman.h>
-.PP
+.P
.BI "[[deprecated]] int remap_file_pages(void " addr [. size "], size_t " size ,
.BI " int " prot ", size_t " pgoff ", \
int " flags );
and it is believed to be little used or perhaps even completely unused.
While it had some use cases in database applications on 32-bit systems,
those use cases don't exist on 64-bit systems.
-.PP
+.P
The
.BR remap_file_pages ()
system call is used to create a nonlinear mapping, that is, a mapping
.BR mmap (2)
is that the former approach does not require the kernel to create
additional VMA (Virtual Memory Area) data structures.
-.PP
+.P
To create a nonlinear mapping we perform the following steps:
.TP 3
1.
and the pages of the file.
It is possible to map the same page of a file
into multiple locations within the mapped region.
-.PP
+.P
The
.I pgoff
and
is a file offset in units of the system page size;
.I size
is the length of the region in bytes.
-.PP
+.P
The
.I addr
argument serves two purposes.
and
.I size
will be placed.
-.PP
+.P
The values specified in
.I addr
and
.\" This rounding is weird, and not consistent with the treatment of
.\" the analogous arguments for munmap()/mprotect() and for mlock().
.\" MTK, 14 Sep 2005
-.PP
+.P
The
.I prot
argument must be specified as 0.
-.PP
+.P
The
.I flags
argument has the same meaning as for
.SH SYNOPSIS
.nf
.B #include <sys/xattr.h>
-.PP
+.P
.BI "int removexattr(const char *" path ", const char *" name );
.BI "int lremovexattr(const char *" path ", const char *" name );
.BI "int fremovexattr(int " fd ", const char *" name );
data).
A complete overview of extended attributes concepts can be found in
.BR xattr (7).
-.PP
+.P
.BR removexattr ()
removes the extended attribute identified by
.I name
and associated with the given
.I path
in the filesystem.
-.PP
+.P
.BR lremovexattr ()
is identical to
.BR 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.
-.PP
+.P
.BR fremovexattr ()
is identical to
.BR removexattr (),
.BR open (2))
in place of
.IR path .
-.PP
+.P
An extended attribute name is a null-terminated string.
The
.I name
.TP
.B ENOTSUP
Extended attributes are not supported by the filesystem, or are disabled.
-.PP
+.P
In addition, the errors documented in
.BR stat (2)
can also occur.
.SH SYNOPSIS
.nf
.B #include <stdio.h>
-.PP
+.P
.BI "int rename(const char *" oldpath ", const char *" newpath );
-.PP
+.P
.BR "#include <fcntl.h> " "/* Definition of " AT_* " constants */"
.B #include <stdio.h>
-.PP
+.P
.BI "int renameat(int " olddirfd ", const char *" oldpath ,
.BI " int " newdirfd ", const char *" newpath );
.BI "int renameat2(int " olddirfd ", const char *" oldpath ,
.BI " int " newdirfd ", const char *" newpath \
", unsigned int " flags );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.nf
.BR renameat ():
Since glibc 2.10:
_POSIX_C_SOURCE >= 200809L
Before glibc 2.10:
_ATFILE_SOURCE
-.PP
+.P
.BR renameat2 ():
_GNU_SOURCE
.fi
Open file descriptors for
.I oldpath
are also unaffected.
-.PP
+.P
Various restrictions determine whether or not the rename operation succeeds:
see ERRORS below.
-.PP
+.P
If
.I newpath
already exists, it will be atomically replaced, so that there is
and
.I newpath
refer to the file being renamed.
-.PP
+.P
If
.I oldpath
and
are existing hard links referring to the same file, then
.BR rename ()
does nothing, and returns a success status.
-.PP
+.P
If
.I newpath
exists but the operation fails for some reason,
guarantees to leave an instance of
.I newpath
in place.
-.PP
+.P
.I oldpath
can specify a directory.
In this case,
.I newpath
must either not exist, or it must specify an empty directory.
-.PP
+.P
If
.I oldpath
refers to a symbolic link, the link is renamed; if
system call operates in exactly the same way as
.BR rename (),
except for the differences described here.
-.PP
+.P
If the pathname given in
.I oldpath
is relative, then it is interpreted relative to the directory
the calling process, as is done by
.BR rename ()
for a relative pathname).
-.PP
+.P
If
.I oldpath
is relative and
is interpreted relative to the current working
directory of the calling process (like
.BR rename ()).
-.PP
+.P
If
.I oldpath
is absolute, then
.I olddirfd
is ignored.
-.PP
+.P
The interpretation of
.I newpath
is as for
except that a relative pathname is interpreted relative
to the directory referred to by the file descriptor
.IR newdirfd .
-.PP
+.P
See
.BR openat (2)
for an explanation of the need for
.I flags
argument is equivalent to
.BR renameat ().
-.PP
+.P
The
.I flags
argument is a bit mask consisting of zero or more of the following flags:
.BR rename ()
does not work across different mount points,
even if the same filesystem is mounted on both.)
-.PP
+.P
The following additional errors can occur for
.BR renameat ()
and
.I newpath
and
.I newdirfd
-.PP
+.P
The following additional errors can occur for
.BR renameat2 ():
.TP
.SH SYNOPSIS
.nf
.B #include <keyutils.h>
-.PP
+.P
.BI "key_serial_t request_key(const char *" type ", const char *" description ,
.BI " const char *_Nullable " callout_info ,
.BI " key_serial_t " dest_keyring );
attaches it to the keyring whose ID is specified in
.I dest_keyring
and returns the key's serial number.
-.PP
+.P
.BR request_key ()
first recursively searches for a matching key in all of the keyrings
attached to the calling process.
The keyrings are searched in the order: thread-specific keyring,
process-specific keyring, and then session keyring.
-.PP
+.P
If
.BR request_key ()
is called from a program invoked by
.\" David Howells: we can then have an arbitrarily long sequence
.\" of "recursive" request-key upcalls. There is no limit, other
.\" than number of PIDs, etc.
-.PP
+.P
The search of the keyring tree is breadth-first:
the keys in each keyring searched are checked for a match before any child
keyrings are recursed into.
permission be found, and only keyrings for which the caller has
.I search
permission may be searched.
-.PP
+.P
If the key is not found and
.I callout
is NULL, then the call fails with the error
.BR ENOKEY .
-.PP
+.P
If the key is not found and
.I callout
is not NULL, then the kernel attempts to invoke a user-space
program to instantiate the key.
The details are given below.
-.PP
+.P
The
.I dest_keyring
serial number may be that of a valid keyring for which the caller has
.B KEY_SPEC_USER_SESSION_KEYRING
This specifies the caller's UID-session keyring (see
.BR user\-session\-keyring (7)).
-.PP
+.P
When the
.I dest_keyring
is specified as 0
and no key construction has been performed,
then no additional linking is done.
-.PP
+.P
Otherwise, if
.I dest_keyring
is 0 and a new key is constructed, the new key will be linked
.\"
.\" will all create a keyring under some circumstances. Whereas the rest,
.\" such as KEYCTL_GET_SECURITY, KEYCTL_READ and KEYCTL_REVOKE, won't.
-.PP
+.P
If the
.BR keyctl (2)
.B KEYCTL_SET_REQKEY_KEYRING
.BR request_key ()
call completes, and the requesting program can continue execution.
.RE
-.PP
+.P
If these steps are unsuccessful, then an
.B ENOKEY
error will be returned to the caller of
(that require expensive
.BR request\-key (8)
upcalls) for a key that can't (at the moment) be positively instantiated.
-.PP
+.P
Once the key has been instantiated, the authorization key
.RB ( KEY_SPEC_REQKEY_AUTH_KEY )
is revoked, and the destination keyring
is no longer accessible from the
.BR request\-key (8)
program.
-.PP
+.P
If a key is created, then\[em]regardless of whether it is a valid key or
a negatively instantiated key\[em]it will displace any other key with
the same type and description from the keyring specified in
Linux.
.SH HISTORY
Linux 2.6.10.
-.PP
+.P
The ability to instantiate keys upon request was added
.\" commit 3e30148c3d524a9c1c63ca28261bc24c457eb07a
in Linux 2.6.13.
arguments for the system call are taken from the values
supplied in the command-line arguments.
The call specifies the session keyring as the target keyring.
-.PP
+.P
In order to demonstrate this program,
we first create a suitable entry in the file
.IR /etc/request\-key.conf .
-.PP
+.P
.in +4n
.EX
$ sudo sh
# \fBexit\fP
.EE
.in
-.PP
+.P
This entry specifies that when a new "user" key with the prefix
"mtk:" must be instantiated, that task should be performed via the
.BR keyctl (1)
for details of these
.I %
specifiers.
-.PP
+.P
Then we run the program and check the contents of
.I /proc/keys
to verify that the requested key has been instantiated:
-.PP
+.P
.in +4n
.EX
$ \fB./t_request_key user mtk:key1 "Payload data"\fP
2dddaf50 I\-\-Q\-\-\- 1 perm 3f010000 1000 1000 user mtk:key1: 12
.EE
.in
-.PP
+.P
For another example of the use of this program, see
.BR keyctl (2).
.SS Program source
.BR user\-keyring (7),
.BR user\-session\-keyring (7),
.BR request\-key (8)
-.PP
+.P
The kernel source files
.I Documentation/security/keys/core.rst
and
.nf
.B long restart_syscall(void);
.fi
-.PP
+.P
.IR Note :
There is no glibc wrapper for this system call; see NOTES.
.SH DESCRIPTION
.B SIGCONT
signal.
This system call is designed only for internal use by the kernel.
-.PP
+.P
.BR restart_syscall ()
is used for restarting only those system calls that,
when restarted, should adjust their time-related parameters\[em]namely
There is no glibc wrapper for this system call,
because it is intended for use only by the kernel and
should never be called by applications.
-.PP
+.P
The kernel uses
.BR restart_syscall ()
to ensure that when a system call is restarted
.BR select (2),
and
.BR pselect (2).
-.PP
+.P
From user space, the operation of
.BR restart_syscall ()
is largely invisible:
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.BI "int rmdir(const char *" pathname );
.fi
.SH DESCRIPTION
.BR "#include <linux/signal.h>" " /* Definition of " SI_* " constants */"
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "int syscall(SYS_rt_sigqueueinfo, pid_t " tgid ,
.BI " int " sig ", siginfo_t *" info );
.BI "int syscall(SYS_rt_tgsigqueueinfo, pid_t " tgid ", pid_t " tid ,
.BI " int " sig ", siginfo_t *" info );
.fi
-.PP
+.P
.IR Note :
There are no glibc wrappers for these system calls; see NOTES.
.SH DESCRIPTION
.BR sigaction (2)
.B SA_SIGINFO
flag.
-.PP
+.P
These system calls are not intended for direct application use;
they are provided to allow the implementation of
.BR sigqueue (3)
and
.BR pthread_sigqueue (3).
-.PP
+.P
The
.BR rt_sigqueueinfo ()
system call sends the signal
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).
-.PP
+.P
The
.I info
argument specifies the data to accompany the signal.
.RI ( "union sigval" )
argument of
.BR sigqueue (3).
-.PP
+.P
Internally, the kernel sets the
.I si_signo
field to the value specified in
.IR sig ,
so that the receiver of the signal can also obtain
the signal number via that field.
-.PP
+.P
The
.BR rt_tgsigqueueinfo ()
system call is like
No thread group matching
.I tgid
was found.
-.PP
+.P
.BR rt_tgsigqueinfo ():
No thread matching
.I tgid
there are no glibc wrapper functions; use
.BR syscall (2)
in the unlikely case that you want to call them directly.
-.PP
+.P
As with
.BR kill (2),
the null signal (0) can be used to check if the specified process
.BR "#include <sys/syscall.h> " \
"/* Definition of " SYS_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "int syscall(SYS_s390_guarded_storage, int " command ,
.BI " struct gs_cb *" gs_cb );
.fi
-.PP
+.P
.IR Note :
glibc provides no wrapper for
.BR s390_guarded_storage (),
.BR s390_guarded_storage ()
system call enables the use of the Guarded Storage Facility
(a z/Architecture-specific feature) for user-space processes.
-.PP
+.P
.\" The description is based on
.\" http://www-05.ibm.com/de/linux-on-z-ws-us/agenda/pdfs/8_-_Linux_Whats_New_-_Stefan_Raspl.pdf
.\" and "z/Architecture Principles of Operation" obtained from
or "Load Logical and Shift Guarded" (LLGFSG) instructions will cause
a range check on the loaded value and invoke a (previously set up)
user-space handler if one of the guarded regions is affected.
-.PP
+.P
The
.\" The command description is copied from v4.12-rc1~139^2~56^2 commit message
.I command
without a refresh of the stored control block with
.B GS_SET_BC_CB
will not have any effect.
-.PP
+.P
The
.I gs_cb
argument specifies the address of a guarded storage control block structure
On success, the return value of
.BR s390_guarded_storage ()
is 0.
-.PP
+.P
On error, \-1 is returned, and
.I errno
is set to indicate the error.
Guarded Storage Event Parameter List structure layouts
is available in "z/Architecture Principles of Operations"
beginning from the twelfth edition.
-.PP
+.P
The
.I gs_cb
structure has a field
structure type definition in the
.I asm/guarded_storage.h
header.
-.\" .PP
+.\" .P
.\" For the example of using the guarded storage facility, see
.\" .UR https://developer.ibm.com/javasdk/2017/09/25/concurrent-scavenge-using-guarded-storage-facility-works/
.\" the article with the description of its usage in the Java Garbage Collection
.nf
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "int syscall(SYS_s390_pci_mmio_write, unsigned long " mmio_addr ,
.BI " const void " user_buffer [. length "], \
size_t " length );
.BI "int syscall(SYS_s390_pci_mmio_read, unsigned long " mmio_addr ,
.BI " void " user_buffer [. length "], size_t " length );
.fi
-.PP
+.P
.IR Note :
glibc provides no wrappers for these system calls,
necessitating the use of
.I mmio_addr
to the user-space buffer
.IR user_buffer .
-.PP
+.P
These system calls must be used instead of the simple assignment
or data-transfer operations that are used to access the PCI MMIO
memory areas mapped to user space on the Linux System z platform.
.BR "#include <asm/runtime_instr.h>" " /* Definition of " S390_* " constants */"
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "int syscall(SYS_s390_runtime_instr, int " command ", int " signum );
.fi
-.PP
+.P
.IR Note :
glibc provides no wrapper for
.BR s390_runtime_instr (),
.BR s390_runtime_instr ()
system call starts or stops CPU run-time instrumentation for the
calling thread.
-.PP
+.P
The
.I command
argument controls whether run-time instrumentation is started
1) or stopped
.RB ( S390_RUNTIME_INSTR_STOP ,
2) for the calling thread.
-.PP
+.P
The
.I signum
argument specifies the number of a real-time signal.
header file is available
.\" commit df2f815a7df7edb5335a3bdeee6a8f9f6f9c35c4
since Linux 4.16.
-.PP
+.P
Starting with Linux 4.4,
support for signalling was removed, as was the check whether
.I signum
.BR "#include <asm/sthyi.h>" " /* Definition of " STHYI_* " constants */"
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "int syscall(SYS_s390_sthyi, unsigned long " function_code ,
.BI " void *" resp_buffer ", uint64_t *" return_code ,
.BI " unsigned long " flags );
.fi
-.PP
+.P
.IR Note :
glibc provides no wrapper for
.BR s390_sthyi (),
virtualization levels.
This includes CPU type and capacity, as well as the machine model and
other metrics.
-.PP
+.P
The
.I function_code
argument indicates which function to perform.
.B STHYI_FC_CP_IFL_CAP
Return CP (Central Processor) and IFL (Integrated Facility for Linux)
capacity information.
-.PP
+.P
The
.I resp_buffer
argument specifies the address of a response buffer.
If the system call returns 0,
the response buffer will be filled with CPU capacity information.
Otherwise, the response buffer's content is unchanged.
-.PP
+.P
The
.I return_code
argument stores the return code of the STHYI instruction,
.TP
4
Unsupported function code.
-.PP
+.P
For further details about
.IR return_code ,
.IR function_code ,
and
.IR resp_buffer ,
see the reference given in NOTES.
-.PP
+.P
The
.I flags
argument is provided to allow for future extensions and currently
.I *resp_buffer
is unchanged.
The return values 1 and 2 are reserved.
-.PP
+.P
On error, \-1 is returned, and
.I errno
is set to indicate the error.
.UR https://www.ibm.com\:/support\:/knowledgecenter\:/SSB27U_6.3.0\:/com.ibm.zvm.v630.hcpb4\:/hcpb4sth.htm
the documentation page
.UE .
-.PP
+.P
When the system call interface is used, the response buffer doesn't
have to fulfill alignment requirements described in the STHYI
instruction definition.
-.PP
+.P
The kernel caches the response (for up to one second, as of Linux 4.16).
Subsequent system call invocations may return the cached response.
.SH SEE ALSO
.SH SYNOPSIS
.nf
.B #include <sched.h>
-.PP
+.P
.BI "int sched_get_priority_max(int " policy );
.BI "int sched_get_priority_min(int " policy );
.fi
.BR SCHED_DEADLINE .
Further details about these policies can be found in
.BR sched (7).
-.PP
+.P
Processes with numerically higher priority values are scheduled before
processes with numerically lower priority values.
Thus, the value
will be greater than the
value returned by
.BR sched_get_priority_min ().
-.PP
+.P
Linux allows the static priority range 1 to 99 for the
.B SCHED_FIFO
and
policies, and the priority 0 for the remaining policies.
Scheduling priority ranges for the various policies
are not alterable.
-.PP
+.P
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
.B SCHED_FIFO
and
.BR SCHED_RR .
-.PP
+.P
POSIX systems on which
.BR sched_get_priority_max ()
and
.SH SYNOPSIS
.nf
.B #include <sched.h>
-.PP
+.P
.BI "int sched_rr_get_interval(pid_t " pid ", struct timespec *" tp );
.fi
.SH DESCRIPTION
The specified process should be running under the
.B SCHED_RR
scheduling policy.
-.PP
+.P
If
.I pid
is zero, the time quantum for the calling process is written into
.nf
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <sched.h>
-.PP
+.P
.BI "int sched_setaffinity(pid_t " pid ", size_t " cpusetsize ,
.BI " const cpu_set_t *" mask );
.BI "int sched_getaffinity(pid_t " pid ", size_t " cpusetsize ,
the performance cost caused by the cache invalidation that occurs
when a thread ceases to execute on one CPU and then
recommences execution on a different CPU.
-.PP
+.P
A CPU affinity mask is represented by the
.I cpu_set_t
structure, a "CPU set", pointed to by
.IR mask .
A set of macros for manipulating CPU sets is described in
.BR CPU_SET (3).
-.PP
+.P
.BR sched_setaffinity ()
sets the CPU affinity mask of the thread whose ID is
.I pid
.IR mask .
Normally this argument would be specified as
.IR "sizeof(cpu_set_t)" .
-.PP
+.P
If the thread specified by
.I pid
is not currently running on one of the CPUs specified in
.IR mask ,
then that thread is migrated to one of the CPUs specified in
.IR mask .
-.PP
+.P
.BR sched_getaffinity ()
writes the affinity mask of the thread whose ID is
.I pid
.SH HISTORY
Linux 2.5.8,
glibc 2.3.
-.PP
+.P
Initially, the glibc interfaces included a
.I cpusetsize
argument, typed as
is being used.
These restrictions on the actual set of CPUs on which the thread
will run are silently imposed by the kernel.
-.PP
+.P
There are various ways of determining the number of CPUs
available on the system, including: inspecting the contents of
.IR /proc/cpuinfo ;
.B _SC_NPROCESSORS_ONLN
parameters; and inspecting the list of CPU directories under
.IR /sys/devices/system/cpu/ .
-.PP
+.P
.BR sched (7)
has a description of the Linux scheduling scheme.
-.PP
+.P
The affinity mask is 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
.BR pthread_setaffinity_np (3)
instead of
.BR sched_setaffinity ().)
-.PP
+.P
The
.I isolcpus
boot option can be used to isolate one or more CPUs at boot time,
is the preferred mechanism of isolating CPUs
(versus the alternative of manually setting the CPU affinity
of all processes on the system).
-.PP
+.P
A child created via
.BR fork (2)
inherits its parent's CPU affinity mask.
.IR "unsigned long\ *" ,
reflecting the fact that the underlying implementation of CPU
sets is a simple bit mask.
-.PP
+.P
On success, the raw
.BR sched_getaffinity ()
system call returns the number of bytes placed copied into the
.\" and https://sourceware.org/ml/libc-alpha/2013-07/msg00288.html
If the kernel CPU affinity mask is larger than 1024,
then calls of the form:
-.PP
+.P
.in +4n
.EX
sched_getaffinity(pid, sizeof(cpu_set_t), &mask);
.EE
.in
-.PP
+.P
fail with the error
.BR EINVAL ,
the error produced by the underlying system call for the case where the
is smaller than the size of the affinity mask used by the kernel.
(Depending on the system CPU topology, the kernel affinity mask can
be substantially larger than the number of active CPUs in the system.)
-.PP
+.P
When working on systems with large kernel CPU affinity masks,
one must dynamically allocate the
.I mask
.BR sched_getaffinity ()
calls with increasing mask sizes (until the call does not fail with the error
.BR EINVAL ).
-.PP
+.P
Be aware that
.BR CPU_ALLOC (3)
may allocate a slightly larger CPU set than requested
the CPU number for the parent,
the CPU number for the child,
and the number of loop iterations that both processes should perform.
-.PP
+.P
As the sample runs below demonstrate, the amount of real and CPU time
consumed when running the program will depend on intra-core caching effects
and whether the processes are using the same CPU.
-.PP
+.P
We first employ
.BR lscpu (1)
to determine that this (x86)
system has two cores, each with two CPUs:
-.PP
+.P
.in +4n
.EX
$ \fBlscpu | egrep \-i \[aq]core.*:|socket\[aq]\fP
Socket(s): 1
.EE
.in
-.PP
+.P
We then time the operation of the example program for three cases:
both processes running on the same CPU;
both processes running on different CPUs on the same core;
and both processes running on different CPUs on different cores.
-.PP
+.P
.in +4n
.EX
$ \fBtime \-p ./a.out 0 0 100000000\fP
.BR "#include <sched.h>" " /* Definition of " SCHED_* " constants */"
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "int syscall(SYS_sched_setattr, pid_t " pid ", struct sched_attr *" attr ,
.BI " unsigned int " flags );
.BI "int syscall(SYS_sched_getattr, pid_t " pid ", struct sched_attr *" attr ,
.BI " unsigned int " size ", unsigned int " flags );
.fi
.\" FIXME . Add feature test macro requirements
-.PP
+.P
.IR Note :
glibc provides no wrappers for these system calls,
necessitating the use of
.I pid
equals zero,
the scheduling policy and attributes of the calling thread will be set.
-.PP
+.P
Currently, Linux supports the following "normal"
(i.e., non-real-time) scheduling policies as values that may be specified in
.IR policy :
for running
.I very
low priority background jobs.
-.PP
+.P
Various "real-time" policies are also supported,
for special time-critical applications that need precise control over
the way in which runnable threads are selected for execution.
.TP
.B SCHED_RR
a round-robin policy.
-.PP
+.P
Linux also provides the following policy:
.TP 14
.B SCHED_DEADLINE
a deadline scheduling policy; see
.BR sched (7)
for details.
-.PP
+.P
The
.I attr
argument is a pointer to a structure that defines
the new scheduling policy and attributes for the specified thread.
This structure has the following form:
-.PP
+.P
.in +4n
.EX
struct sched_attr {
};
.EE
.in
-.PP
+.P
The fields of the
.I sched_attr
structure are as follows:
.I sched_period
This field specifies the "Period" parameter for deadline scheduling.
The value is expressed in nanoseconds.
-.PP
+.P
The
.I flags
argument is provided to allow for future extensions to the interface;
equals zero,
the scheduling policy and attributes of the calling thread
will be retrieved.
-.PP
+.P
The
.I size
argument should be set to the size of the
.I sched_attr
structure, or the call fails with the error
.BR EINVAL .
-.PP
+.P
The retrieved scheduling attributes are placed in the fields of the
.I sched_attr
structure pointed to by
to the size of its
.I sched_attr
structure.
-.PP
+.P
If the caller-provided
.I attr
buffer is larger than the kernel's
As with
.BR sched_setattr (),
these semantics allow for future extensibility of the interface.
-.PP
+.P
The
.I flags
argument is provided to allow for future extensions to the interface;
The thread whose ID is
.I pid
could not be found.
-.PP
+.P
In addition,
.BR sched_getattr ()
can fail for the following reasons:
is invalid; that is, it is smaller than the initial version of the
.I sched_attr
structure (48 bytes) or larger than the system page size.
-.PP
+.P
In addition,
.BR sched_setattr ()
can fail for the following reasons:
.SH NOTES
glibc does not provide wrappers for these system calls; call them using
.BR syscall (2).
-.PP
+.P
.BR sched_setattr ()
provides a superset of the functionality of
.BR sched_setscheduler (2),
instead of
.B E2BIG
for the case described in ERRORS.
-.PP
+.P
Up to Linux 5.3,
.BR sched_getattr ()
failed with the error
.SH SYNOPSIS
.nf
.B #include <sched.h>
-.PP
+.P
.BI "int sched_setparam(pid_t " pid ", const struct sched_param *" param );
.BI "int sched_getparam(pid_t " pid ", struct sched_param *" param );
-.PP
+.P
\fBstruct sched_param {
...
int \fIsched_priority\fB;
See
.BR sched (7)
for a description of the scheduling policies supported under Linux.
-.PP
+.P
.BR sched_getparam ()
retrieves the scheduling parameters for the
thread identified by \fIpid\fP.
If \fIpid\fP is zero, then the parameters
of the calling thread are retrieved.
-.PP
+.P
.BR sched_setparam ()
checks the validity of \fIparam\fP for the scheduling policy of the
thread.
.BR sched_get_priority_min (2)
and
.BR sched_get_priority_max (2).
-.PP
+.P
For a discussion of the privileges and resource limits related to
scheduling priority and policy, see
.BR sched (7).
-.PP
+.P
POSIX systems on which
.BR sched_setparam ()
and
.SH SYNOPSIS
.nf
.B #include <sched.h>
-.PP
+.P
.BI "int sched_setscheduler(pid_t " pid ", int " policy ,
.BI " const struct sched_param *" param );
.BI "int sched_getscheduler(pid_t " pid );
thread whose ID is specified in \fIpid\fP.
If \fIpid\fP equals zero, the
scheduling policy and parameters of the calling thread will be set.
-.PP
+.P
The scheduling parameters are specified in the
.I param
argument, which is a pointer to a structure of the following form:
-.PP
+.P
.in +4n
.EX
struct sched_param {
};
.EE
.in
-.PP
+.P
In the current implementation, the structure contains only one field,
.IR sched_priority .
The interpretation of
.I param
depends on the selected policy.
-.PP
+.P
Currently, Linux supports the following "normal"
(i.e., non-real-time) scheduling policies as values that may be specified in
.IR policy :
for running
.I very
low priority background jobs.
-.PP
+.P
For each of the above policies,
.I param\->sched_priority
must be 0.
-.PP
+.P
Various "real-time" policies are also supported,
for special time-critical applications that need precise control over
the way in which runnable threads are selected for execution.
.TP
.B SCHED_RR
a round-robin policy.
-.PP
+.P
For each of the above policies,
.I param\->sched_priority
specifies a scheduling priority for the thread.
with the specified
.IR policy .
On Linux, these system calls return, respectively, 1 and 99.
-.PP
+.P
Since Linux 2.6.32, the
.B SCHED_RESET_ON_FORK
flag can be ORed in
See
.BR sched (7)
for details.
-.PP
+.P
.BR sched_getscheduler ()
returns the current scheduling policy of the thread
identified by \fIpid\fP.
For example, the Solaris 7 manual page says that
the real or effective user ID of the caller must
match the real user ID or the save set-user-ID of the target.
-.PP
+.P
The scheduling policy and parameters are in fact per-thread
attributes on Linux.
The value returned from a call to
system calls.)
.SH STANDARDS
POSIX.1-2008 (but see BUGS below).
-.PP
+.P
.B SCHED_BATCH
and
.B SCHED_IDLE
.BR SCHED_DEADLINE ,
which is settable only via
.BR sched_setattr (2).
-.PP
+.P
POSIX systems on which
.BR sched_setscheduler ()
and
.SH SYNOPSIS
.nf
.B #include <sched.h>
-.PP
+.P
.B int sched_yield(void);
.fi
.SH DESCRIPTION
.SH HISTORY
POSIX.1-2001 (but optional).
POSIX.1-2008.
-.PP
+.P
Before POSIX.1-2008,
systems on which
.BR sched_yield ()
with nondeterministic scheduling policies such as
.B SCHED_OTHER
is unspecified and very likely means your application design is broken.
-.PP
+.P
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
.BR sched_yield ().
-.PP
+.P
Avoid calling
.BR sched_yield ()
unnecessarily or inappropriately
.\" need <sys/ptrace.h>
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "int syscall(SYS_seccomp, unsigned int " operation ", unsigned int " flags ,
.BI " void *" args );
.fi
-.PP
+.P
.IR Note :
glibc provides no wrapper for
.BR seccomp (),
.BR seccomp ()
system call operates on the Secure Computing (seccomp) state of the
calling process.
-.PP
+.P
Currently, Linux supports the following
.I operation
values:
.BR SECCOMP_SET_MODE_FILTER ,
.I args
points to a filter program:
-.PP
+.P
.in +4n
.EX
struct sock_fprog {
};
.EE
.in
-.PP
+.P
Each program must contain one or more BPF instructions:
-.PP
+.P
.in +4n
.EX
struct sock_filter { /* Filter block */
};
.EE
.in
-.PP
+.P
When executing the instructions, the BPF program operates on the
system call information made available (i.e., use the
.B BPF_ABS
.\" that would need to use ptrace to catch the call and directly
.\" modify the registers before continuing with the call.
buffer of the following form:
-.PP
+.P
.in +4n
.EX
struct seccomp_data {
};
.EE
.in
-.PP
+.P
Because numbering of system calls varies between architectures and
some architectures (e.g., x86-64) allow user-space code to use
the calling conventions of multiple architectures
it is usually necessary to verify the value of the
.I arch
field.
-.PP
+.P
It is strongly recommended to use an allow-list approach whenever
possible because such an approach is more robust and simple.
A deny-list will have to be updated whenever a potentially
See also
.I Caveats
below.
-.PP
+.P
The
.I arch
field is not unique for all calling conventions.
.\" will have a value that is not all-ones, and this will trigger
.\" an extra instruction in system_call to mask off the extra bit,
.\" so that the syscall table indexing still works.
-.PP
+.P
This means that a policy must either deny all syscalls with
.B __X32_SYSCALL_BIT
or it must recognize syscalls with and without
.B __X32_SYSCALL_BIT
set can be bypassed by a malicious program that sets
.BR __X32_SYSCALL_BIT .
-.PP
+.P
Additionally, kernels prior to Linux 5.4 incorrectly permitted
.I nr
in the ranges 512-547 as well as the corresponding non-x32 syscalls ORed
such system calls will fail with the error
.BR ENOSYS ,
without doing anything.
-.PP
+.P
The
.I instruction_pointer
field provides the address of the machine-language instruction that
and
.BR mprotect (2)
system calls to prevent the program from subverting such checks.)
-.PP
+.P
When checking values from
.IR args ,
keep in mind that arguments are often
.IR int ,
the more-significant half of the argument register is ignored by
the system call, but visible in the seccomp data.
-.PP
+.P
A seccomp filter returns a 32-bit value consisting of two parts:
the most significant 16 bits
(corresponding to the mask defined by the constant
the least significant 16-bits (defined by the constant
.BR SECCOMP_RET_DATA )
are "data" to be associated with this return value.
-.PP
+.P
If multiple filters exist, they are \fIall\fP executed,
in reverse order of their addition to the filter tree\[em]that is,
the most recently installed filter is executed first.
The return value for the evaluation of a given system call is the first-seen
action value of highest precedence (along with its accompanying data)
returned by execution of all of the filters.
-.PP
+.P
In decreasing order of precedence,
the action values that may be returned by a seccomp filter are:
.TP
.TP
.B SECCOMP_RET_ALLOW
This value results in the system call being executed.
-.PP
+.P
If an action value other than one of the above is specified,
then the filter action is treated as either
.B SECCOMP_RET_KILL_PROCESS
you may prefer to employ the
.I libseccomp
library, which provides a front-end for generating seccomp filters.
-.PP
+.P
The
.I Seccomp
field of the
.IR /proc/ pid /status
file provides a method of viewing the seccomp mode of a process; see
.BR proc (5).
-.PP
+.P
.BR seccomp ()
provides a superset of the functionality provided by the
.BR prctl (2)
.B PR_SET_SECCOMP
operation (which does not support
.IR flags ).
-.PP
+.P
Since Linux 4.4, the
.BR ptrace (2)
.B PTRACE_SECCOMP_GET_FILTER
.BR openat (2)
on all architectures.
.RE
-.PP
+.P
The consequence of the above points is that it may be necessary
to filter for a system call other than might be expected.
Various manual pages in Section 2 provide helpful details
about the differences between wrapper functions and
the underlying system calls in subsections entitled
.IR "C library/kernel differences" .
-.PP
+.P
Furthermore, note that the application of seccomp filters
even risks causing bugs in an application,
when the filters cause unexpected failures for legitimate operations
the BPF filter causes the system call to fail, with
.I errno
being set to the specified error number.
-.PP
+.P
The remaining command-line arguments specify
the pathname and additional arguments of a program
that the example program should attempt to execute using
.BR execve (2)
system call).
Some example runs of the program are shown below.
-.PP
+.P
First, we display the architecture that we are running on (x86-64)
and then construct a shell function that looks up system call
numbers on this architecture:
-.PP
+.P
.in +4n
.EX
$ \fBuname \-m\fP
}\fP
.EE
.in
-.PP
+.P
When the BPF filter rejects a system call (case [2] above),
it causes the system call to fail with the error number
specified on the command line.
In the experiments shown here, we'll use error number 99:
-.PP
+.P
.in +4n
.EX
$ \fBerrno 99\fP
EADDRNOTAVAIL 99 Cannot assign requested address
.EE
.in
-.PP
+.P
In the following example, we attempt to run the command
.BR whoami (1),
but the BPF filter rejects the
.BR execve (2)
system call, so that the command is not even executed:
-.PP
+.P
.in +4n
.EX
$ \fBsyscall_nr execve\fP
execv: Cannot assign requested address
.EE
.in
-.PP
+.P
In the next example, the BPF filter rejects the
.BR write (2)
system call, so that, although it is successfully started, the
.BR whoami (1)
command is not able to write output:
-.PP
+.P
.in +4n
.EX
$ \fBsyscall_nr write\fP
$ \fB./a.out 1 0xC000003E 99 /bin/whoami\fP
.EE
.in
-.PP
+.P
In the final example,
the BPF filter rejects a system call that is not used by the
.BR whoami (1)
command, so it is able to successfully execute and produce output:
-.PP
+.P
.in +4n
.EX
$ \fBsyscall_nr preadv\fP
.BR proc (5),
.BR signal (7),
.BR socket (7)
-.PP
+.P
Various pages from the
.I libseccomp
library, including:
.BR seccomp_load (3),
and
.BR seccomp_rule_add (3).
-.PP
+.P
The kernel source files
.I Documentation/networking/filter.txt
and
(or
.I Documentation/prctl/seccomp_filter.txt
before Linux 4.13).
-.PP
+.P
McCanne, S.\& and Jacobson, V.\& (1992)
.IR "The BSD Packet Filter: A New Architecture for User-level Packet Capture" ,
Proceedings of the USENIX Winter 1993 Conference
.B #include <linux/seccomp.h>
.B #include <linux/filter.h>
.B #include <linux/audit.h>
-.PP
+.P
.BI "int seccomp(unsigned int " operation ", unsigned int " flags \
", void *" args );
-.PP
+.P
.B #include <sys/ioctl.h>
-.PP
+.P
.BI "int ioctl(int " fd ", SECCOMP_IOCTL_NOTIF_RECV,"
.BI " struct seccomp_notif *" req );
.BI "int ioctl(int " fd ", SECCOMP_IOCTL_NOTIF_SEND,"
Note that this mechanism is explicitly
.B not
intended as a method implementing security policy; see NOTES.
-.PP
+.P
In the discussion that follows,
the thread(s) on which the seccomp filter is installed is (are)
referred to as the
and the process that is notified by the user-space notification
mechanism is referred to as the
.IR supervisor .
-.PP
+.P
A suitably privileged supervisor can use the user-space notification
mechanism to perform actions on behalf of the target.
The advantage of the user-space notification mechanism is that
(A seccomp filter is limited in the information it can obtain and
the actions that it can perform because it
is running on a virtual machine inside the kernel.)
-.PP
+.P
An overview of the steps performed by the target and the supervisor
is as follows:
.\"-------------------------------------
returning the information that was provided by the supervisor
in the notification response.
.\"-------------------------------------
-.PP
+.P
As a variation on the last two steps,
the supervisor can send a response that tells the kernel that it
should execute the target thread's system call; see the discussion of
argument is a pointer to a structure of the following form
which contains information about the event.
This structure must be zeroed out before the call.
-.PP
+.P
.in +4n
.EX
struct seccomp_notif {
};
.EE
.in
-.PP
+.P
The fields in this structure are as follows:
.TP
.I id
See
.BR seccomp (2)
for details of this structure.
-.PP
+.P
On success, this operation returns 0; on failure, \-1 is returned, and
.I errno
is set to indicate the cause of the error.
operation is still valid
(i.e., that the target still exists and its system call
is still blocked waiting for a response).
-.PP
+.P
The third
.BR ioctl (2)
argument is a pointer to the cookie
returned by the
.B SECCOMP_IOCTL_NOTIF_RECV
operation.
-.PP
+.P
This operation is necessary to avoid race conditions that can occur when the
.I pid
returned by the
file for the TID obtained in step 1, with the intention of (say)
inspecting the memory location(s) that containing the argument(s) of
the system call that triggered the notification in step 1.
-.PP
+.P
In the above scenario, the risk is that the supervisor may try
to access the memory of a process other than the target.
This race can be avoided by following the call to
.\" PID, or something like that. (Actually, it is associated
.\" with the "struct pid", which is not reused, instead of the
.\" numeric PID.
-.PP
+.P
See NOTES for a discussion of other cases where
.B SECCOMP_IOCTL_NOTIF_ID_VALID
checks must be performed.
-.PP
+.P
On success (i.e., the notification ID is still valid),
this operation returns 0.
On failure (i.e., the notification ID is no longer valid),
The third
.BR ioctl (2)
argument of this structure is a pointer to a structure of the following form:
-.PP
+.P
.in +4n
.EX
struct seccomp_notif_resp {
};
.EE
.in
-.PP
+.P
The fields of this structure are as follows:
.TP
.I id
Tell the kernel to execute the target's system call.
.\" commit fb3c5386b382d4097476ce9647260fc89b34afdb
.RE
-.PP
+.P
Two kinds of response are possible:
.IP \[bu] 3
A response to the kernel telling it to execute the
.\" verify that val and err are both 0 when CONTINUE is specified (as you
.\" pointed out correctly above).
.RE
-.PP
+.P
On success, this operation returns 0; on failure, \-1 is returned, and
.I errno
is set to indicate the cause of the error.
this operation is semantically equivalent to duplicating
a file descriptor from the supervisor's file descriptor table
into the target's file descriptor table.
-.PP
+.P
The
.B SECCOMP_IOCTL_NOTIF_ADDFD
operation permits the supervisor to emulate a target system call (such as
a file descriptor that refers to the same open file description in the target.
(For an explanation of open file descriptions, see
.BR open (2).)
-.PP
+.P
Once this operation has been performed,
the supervisor can close its copy of the file descriptor.
-.PP
+.P
In the target,
the received file descriptor is subject to the same
Linux Security Module (LSM) checks as are applied to a file descriptor
and
.IR netprioidx )
of the target.
-.PP
+.P
The third
.BR ioctl (2)
argument is a pointer to a structure of the following form:
-.PP
+.P
.in +4n
.EX
struct seccomp_notif_addfd {
};
.EE
.in
-.PP
+.P
The fields in this structure are as follows:
.TP
.I id
.B O_CLOEXEC
Set the close-on-exec flag on the received file descriptor.
.RE
-.PP
+.P
On success, this
.BR ioctl (2)
call returns the number of the file descriptor that was allocated
that is supplied in the response that is subsequently sent with the
.B SECCOMP_IOCTL_NOTIF_SEND
operation.
-.PP
+.P
On error, \-1 is returned and
.I errno
is set to indicate the cause of the error.
-.PP
+.P
This operation can fail with the following errors:
.TP
.B EBADF
The blocked system call in the target
has been interrupted by a signal handler
or the target has terminated.
-.PP
+.P
Here is some sample code (with error handling omitted) that uses the
.B SECCOMP_ADDFD_FLAG_SETFD
operation (here, to emulate a call to
.BR openat (2)):
-.PP
+.P
.EX
.in +4n
int fd, removeFd;
The target's system call should either be handled by the supervisor or
allowed to continue normally in the kernel (where standard security
policies will be applied).
-.PP
+.P
.BR "Note well" :
this mechanism must not be used to make security policy decisions
about the system call,
which would be inherently race-prone for reasons described next.
-.PP
+.P
The
.B SECCOMP_USER_NOTIF_FLAG_CONTINUE
flag must be used with caution.
since an attacker could exploit the interval of time where the target is
blocked waiting on the "continue" response to do things such as
rewriting the system call arguments.
-.PP
+.P
Note furthermore that a user-space notifier can be bypassed if
the existing filters allow the use of
.BR seccomp (2)
.B SECCOMP_RET_USER_NOTIF
(see
.BR seccomp (2)).
-.PP
+.P
It should thus be absolutely clear that the
seccomp user-space notification mechanism
.B can not
.BR ioctl (2)
operation is also necessary in other situations,
as explained in the following paragraphs.
-.PP
+.P
Consider the following scenario, where the supervisor
tries to read the pathname argument of a target's blocked
.BR mount (2)
The supervisor now calls
.BR mount (2)
with some arbitrary bytes obtained in the previous step.
-.PP
+.P
The conclusion from the above scenario is this:
since the target's blocked system call may be interrupted by a signal handler,
the supervisor must be written to expect that the
time;
in such an event, any information that the supervisor obtained from
the target's memory must be considered invalid.
-.PP
+.P
To prevent such scenarios,
every read from the target's memory must be separated from use of
the bytes so obtained by a
check.
In the above example, the check would be placed between the two final steps.
An example of such a check is shown in EXAMPLES.
-.PP
+.P
Following on from the above, it should be clear that
a write by the supervisor into the target's memory can
.B never
.BR accept (2))
that the supervisor should handle.
The supervisor might then in turn execute the same blocking system call.
-.PP
+.P
In this scenario,
it is important to note that if the target's system call is now
interrupted by a signal, the supervisor is
perhaps closed its listening socket) might expect to be able to reuse in a
.BR bind (2)
call.
-.PP
+.P
Therefore, when the supervisor wishes to emulate a blocking system call,
it must do so in such a way that it gets informed if the target's
system call is interrupted by a signal handler.
.BR accept (2)
call has been interrupted) and the listening file descriptor
(so as to know when a connection is available).
-.PP
+.P
If the target's system call is interrupted,
the supervisor must take care to release resources (e.g., file descriptors)
that it acquired on behalf of the target.
operation will fail with the
.B ENOENT
error.
-.PP
+.P
In this scenario, the kernel will restart the target's system call.
Consequently, the supervisor will receive another user-space notification.
Thus, depending on how many times the blocked system call
is interrupted by a signal handler,
the supervisor may receive multiple notifications for
the same instance of a system call in the target.
-.PP
+.P
One oddity is that system call restarting as described in this scenario
will occur even for the blocking system calls listed in
.BR signal (7)
.\" calls because it's impossible for the kernel to restart the call
.\" with the right timeout value. I wonder what happens when those
.\" system calls are restarted in the scenario we're discussing.)
-.PP
+.P
Furthermore, if the supervisor response is a file descriptor
added with
.BR SECCOMP_IOCTL_NOTIF_ADDFD ,
once for each of the supplied command-line arguments,
and reports the result returned by the call.
After processing all arguments, the child process terminates.
-.PP
+.P
The parent process acts as the supervisor, listening for the notifications
that are generated when the target process calls
.BR mkdir (2).
("Operation not supported").
Additionally, if the specified pathname is exactly "/bye",
then the supervisor terminates.
-.PP
+.P
This program can be used to demonstrate various aspects of the
behavior of the seccomp user-space notification mechanism.
To help aid such demonstrations,
the program logs various messages to show the operation
of the target process (lines prefixed "T:") and the supervisor
(indented lines prefixed "S:").
-.PP
+.P
In the following example, the target attempts to create the directory
.IR /tmp/x .
Upon receiving the notification, the supervisor creates the directory on the
and spoofs a success return to be received by the target process's
.BR mkdir (2)
call.
-.PP
+.P
.in +4n
.EX
$ \fB./seccomp_unotify /tmp/x\fP
S: target has terminated; bye
.EE
.in
-.PP
+.P
In the above output, note that the spoofed return value seen by the target
process is 6 (the length of the pathname
.IR /tmp/x ),
whereas a normal
.BR mkdir (2)
call returns 0 on success.
-.PP
+.P
In the next example, the target attempts to create a directory using the
relative pathname
.IR ./sub .
and the kernel then (successfully) executes the target process's
.BR mkdir (2)
call.
-.PP
+.P
.in +4n
.EX
$ \fB./seccomp_unotify ./sub\fP
S: target has terminated; bye
.EE
.in
-.PP
+.P
If the target process attempts to create a directory with
a pathname that doesn't start with "." and doesn't begin with the prefix
"/tmp/", then the supervisor spoofs an error return
for the target's
.BR mkdir (2)
call (which is not executed):
-.PP
+.P
.in +4n
.EX
$ \fB./seccomp_unotify /xxx\fP
S: target has terminated; bye
.EE
.in
-.PP
+.P
In the next example,
the target process attempts to create a directory with the pathname
.BR /tmp/nosuchdir/b .
that it received back to the target process's
.BR mkdir (2)
call.
-.PP
+.P
.in +4n
.EX
$ \fB./seccomp_unotify /tmp/nosuchdir/b\fP
S: target has terminated; bye
.EE
.in
-.PP
+.P
If the supervisor receives a notification and sees that the
argument of the target's
.BR mkdir (2)
.B ENOSYS
("Function not implemented").
This is demonstrated by the following example:
-.PP
+.P
.in +4n
.EX
$ \fB./seccomp_unotify /bye /tmp/y\fP
.BR pidfd_getfd (2),
.BR pidfd_open (2),
.BR seccomp (2)
-.PP
+.P
A further example program can be found in the kernel source file
.IR samples/seccomp/user-trap.c .
.SH SYNOPSIS
.nf
.B #include <sys/select.h>
-.PP
+.P
.BR typedef " /* ... */ " fd_set;
-.PP
+.P
.BI "int select(int " nfds ", fd_set *_Nullable restrict " readfds ,
.BI " fd_set *_Nullable restrict " writefds ,
.BI " fd_set *_Nullable restrict " exceptfds ,
.BI " struct timeval *_Nullable restrict " timeout );
-.PP
+.P
.BI "void FD_CLR(int " fd ", fd_set *" set );
.BI "int FD_ISSET(int " fd ", fd_set *" set );
.BI "void FD_SET(int " fd ", fd_set *" set );
.BI "void FD_ZERO(fd_set *" set );
-.PP
+.P
.BI "int pselect(int " nfds ", fd_set *_Nullable restrict " readfds ,
.BI " fd_set *_Nullable restrict " writefds ,
.BI " fd_set *_Nullable restrict " exceptfds ,
.BI " const struct timespec *_Nullable restrict " timeout ,
.BI " const sigset_t *_Nullable restrict " sigmask );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR pselect ():
.nf
_POSIX_C_SOURCE >= 200112L
or
.BR epoll (7),
which do not suffer this limitation.
-.PP
+.P
.BR select ()
allows a program to monitor multiple file descriptors,
waiting until one or more of the file descriptors become "ready"
.I fd_set
arguments may be specified as NULL if no file descriptors are
to be watched for the corresponding class of events.
-.PP
+.P
.BR "Note well" :
Upon return, each of the file descriptor sets is modified in place
to indicate which file descriptors are currently "ready".
Thus, if using
.BR select ()
within a loop, the sets \fImust be reinitialized\fP before each call.
-.PP
+.P
The contents of a file descriptor set can be manipulated
using the following macros:
.TP
.BR pselect ()
system call allows an application to safely wait until either
a file descriptor becomes ready or until a signal is caught.
-.PP
+.P
The operation of
.BR select ()
and
.BR pselect ()
called with NULL
.IR sigmask .
-.PP
+.P
.I sigmask
is a pointer to a signal mask (see
.BR sigprocmask (2));
the signal mask is not modified during the
.BR pselect ()
call.)
-.PP
+.P
Other than the difference in the precision of the
.I timeout
argument, the following
.BR pselect ()
call:
-.PP
+.P
.in +4n
.EX
ready = pselect(nfds, &readfds, &writefds, &exceptfds,
timeout, &sigmask);
.EE
.in
-.PP
+.P
is equivalent to
.I atomically
executing the following calls:
-.PP
+.P
.in +4n
.EX
sigset_t origmask;
pthread_sigmask(SIG_SETMASK, &origmask, NULL);
.EE
.in
-.PP
+.P
The reason that
.BR pselect ()
is needed is that if one wants to wait for either a signal
argument for
.BR select ()
is a structure of the following type:
-.PP
+.P
.in +4n
.EX
struct timeval {
};
.EE
.in
-.PP
+.P
The corresponding argument for
.BR pselect ()
is a
.BR timespec (3)
structure.
-.PP
+.P
On Linux,
.BR select ()
modifies
to be undefined after
.BR select ()
returns.
-.\" .PP - it is rumored that:
+.\" .P - it is rumored that:
.\" On BSD, when a timeout occurs, the file descriptor bits are not changed.
.\" - it is certainly true that:
.\" Linux follows SUSv2 and sets the bit masks to zero upon a timeout.
.IR exceptfds ).
The return value may be zero if the timeout expired before any
file descriptors became ready.
-.PP
+.P
On error, \-1 is returned, and
.I errno
is set to indicate the error;
.I fd_set
type:
.IR <sys/time.h> .
-.PP
+.P
An
.I fd_set
is a fixed size buffer.
Moreover, POSIX requires
.I fd
to be a valid file descriptor.
-.PP
+.P
The operation of
.BR select ()
and
.BR poll (2)
and
.BR epoll (7):
-.PP
+.P
.in +4n
.EX
#define POLLIN_SET (EPOLLRDNORM | EPOLLRDBAND | EPOLLIN |
.I fd_set
type is fixed in size.
See also BUGS.
-.PP
+.P
The
.BR pselect ()
interface described in this page is implemented by glibc.
.BR pselect6 ().
This system call has somewhat different behavior from the glibc
wrapper function.
-.PP
+.P
The Linux
.BR pselect6 ()
system call modifies its
.I timeout
argument;
this is the behavior required by POSIX.1-2001.
-.PP
+.P
The final argument of the
.BR pselect6 ()
system call is not a
.I "sigset_t\ *"
pointer, but is instead a structure of the form:
-.PP
+.P
.in +4n
.EX
struct {
};
.EE
.in
-.PP
+.P
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
that did not take a
.I sigmask
argument.
-.PP
+.P
From glibc 2.1 to glibc 2.2.1,
one must define
.B _GNU_SOURCE
or
.BR epoll (7)
instead.
-.PP
+.P
The implementation of the
.I fd_set
arguments as value-result arguments is a design error that is avoided in
.BR poll (2)
and
.BR epoll (7).
-.PP
+.P
According to POSIX,
.BR select ()
should check all specified file descriptors in the three file descriptor sets,
According to POSIX, any such file descriptor that is specified in one
of the sets should result in the error
.BR EBADF .
-.PP
+.P
Starting with glibc 2.1, glibc provided an emulation of
.BR pselect ()
that was implemented using
Modern versions of glibc use the (race-free)
.BR pselect ()
system call on kernels where it is provided.
-.PP
+.P
On Linux,
.BR select ()
may report a socket file descriptor as "ready for reading", while
.B O_NONBLOCK
on sockets that should not block.
.\" Maybe the kernel should have returned EIO in such a situation?
-.PP
+.P
On Linux,
.BR select ()
also modifies
.BR timespec (3),
.BR epoll (7),
.BR time (7)
-.PP
+.P
For a tutorial with discussion and examples, see
.BR select_tut (2).
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 file descriptors.
-.PP
+.P
This page provides background and tutorial information
on the use of these system calls.
For details of the arguments and semantics of
in the main loop of the program, otherwise
.BR select ()
would block indefinitely.
-.PP
+.P
Now, somewhere
in the main loop will be a conditional to check the global flag.
So we must ask:
.B SIGCHLD
by using an empty signal mask.
Our program would look like:
-.PP
+.P
.EX
static volatile sig_atomic_t got_SIGCHLD = 0;
\&
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.
-.PP
+.P
The
.BR poll (2)
system call has the same functionality as
file descriptor sets.
It is nowadays widely available, but historically was less portable than
.BR select ().
-.PP
+.P
The Linux-specific
.BR epoll (7)
API provides an interface that is more efficient than
.BR select ().
The listing below is a TCP forwarding program that forwards
from one TCP port to another.
-.PP
+.P
.\" SRC BEGIN (select.c)
.EX
#include <arpa/inet.h>
}
.EE
.\" SRC END
-.PP
+.P
The above program properly forwards most kinds of TCP connections
including OOB signal data transmitted by \fBtelnet\fP servers.
It handles the tricky problem of having data flow in both directions
.BR fcntl (2).
This also has its problems because you end up using
inefficient timeouts.
-.PP
+.P
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\[em]one for each connection.
.SH SYNOPSIS
.nf
.B #include <sys/sem.h>
-.PP
+.P
.BI "int semctl(int " semid ", int " semnum ", int " cmd ", ...);"
.fi
.SH DESCRIPTION
.IR semnum -th
semaphore of that set.
(The semaphores in a set are numbered starting at 0.)
-.PP
+.P
This function has three or four arguments, depending on
.IR cmd .
When there are four, the fourth has the type
.IR "union semun" .
The \fIcalling program\fP must define this union as follows:
-.PP
+.P
.in +4n
.EX
union semun {
};
.EE
.in
-.PP
+.P
The
.I semid_ds
data structure is defined in \fI<sys/sem.h>\fP as follows:
-.PP
+.P
.in +4n
.EX
struct semid_ds {
};
.EE
.in
-.PP
+.P
The fields of the
.I semid_ds
structure are as follows:
.B 0
to
.IR sem_nsems\-1 .
-.PP
+.P
The
.I ipc_perm
structure is defined as follows
(the highlighted fields are settable using
.BR IPC_SET ):
-.PP
+.P
.in +4n
.EX
struct ipc_perm {
};
.EE
.in
-.PP
+.P
The least significant 9 bits of the
.I mode
field of the
0004 Read by others
0002 Write by others
.TE
-.PP
+.P
In effect, "write" means "alter" for a semaphore set.
Bits 0100, 0010, and 0001 (the execute bits) are unused by the system.
-.PP
+.P
Valid values for
.I cmd
are:
.B SEM_STAT_ANY
as for
.BR SEM_STAT .
-.PP
+.P
All other
.I cmd
values return 0 on success.
-.PP
+.P
On failure,
.BR semctl ()
returns \-1 and sets
call, with the implication that no other interface affects the
.I sempid
value.
-.PP
+.P
While some implementations conform to the behavior specified in POSIX.1,
others do not.
(The fault here probably lies with POSIX.1 inasmuch as it likely failed
.B SEM_UNDO
flag (see
.BR semop (2)).
-.PP
+.P
Linux also updates
.I sempid
for
.SH HISTORY
POSIX.1-2001, SVr4.
.\" SVr4 documents more error conditions EINVAL and EOVERFLOW.
-.PP
+.P
Various fields in a \fIstruct semid_ds\fP were typed as
.I short
under Linux 2.2
.B IPC_64
flag in
.IR cmd .)
-.PP
+.P
In some earlier versions of glibc, the
.I semun
union was defined in \fI<sys/sem.h>\fP, but POSIX.1 requires
In the future these may modified or moved to a
.I /proc
filesystem interface.
-.PP
+.P
The following system limit on semaphore sets affects a
.BR semctl ()
call:
Maximum value for
.BR semval :
implementation dependent (32767).
-.PP
+.P
For greater portability, it is best to always call
.BR semctl ()
with four arguments.
.nf
.B #include <sys/sem.h>
.fi
-.PP
+.P
.BI "int semget(key_t " key ,
.BI "int " nsems ,
.BI "int " semflg );
does not have the value
.BR IPC_PRIVATE ),
or to create a new set.
-.PP
+.P
A new set of
.I nsems
semaphores is created if
.B IPC_CREAT
is specified in
.IR semflg .
-.PP
+.P
If
.I semflg
specifies both
.B O_CREAT | O_EXCL
for
.BR open (2).)
-.PP
+.P
Upon creation, the least significant 9 bits of the argument
.I semflg
define the permissions (for owner, group, and others)
(though the execute permissions are
not meaningful for semaphores, and write permissions mean permission
to alter semaphore values).
-.PP
+.P
When creating a new semaphore set,
.BR semget ()
initializes the set's associated data structure,
.IP \[bu]
.I sem_ctime
is set to the current time.
-.PP
+.P
The argument
.I nsems
can be 0
must be greater than 0
and less than or equal to the maximum number of semaphores per semaphore set
.RB ( SEMMSL ).
-.PP
+.P
If the semaphore set already exists, the permissions are
verified.
.\" and a check is made to see if it is marked for destruction.
.\" In truth, every one of the many implementations that I've tested sets
.\" the values to zero, but I suppose there is/was some obscure
.\" implementation out there that does not.
-.PP
+.P
Initialization can be done using
.BR semctl (2)
.B SETVAL
flags for the call to
.BR semget ().
The usage of this program is demonstrated below.
-.PP
+.P
We first create two files that will be used to generate keys using
.BR ftok (3),
create two semaphore sets using those files, and then list the sets using
.BR ipcs (1):
-.PP
+.P
.in +4n
.EX
$ \fBtouch mykey mykey2\fP
0x70041368 10 mtk 600 2
.EE
.in
-.PP
+.P
Next, we demonstrate that when
.BR semctl (2)
is given the same
(as generated by the same arguments to
.BR ftok (3)),
it returns the ID of the already existing semaphore set:
-.PP
+.P
.in +4n
.EX
$ \fB./t_semget \-c mykey p 1\fP
ID = 9
.EE
.in
-.PP
+.P
Finally, we demonstrate the kind of collision that can occur when
.BR ftok (3)
is given different
.I pathname
arguments that have the same inode number:
-.PP
+.P
.in +4n
.EX
$ \fBln mykey link\fP
.SH SYNOPSIS
.nf
.B #include <sys/sem.h>
-.PP
+.P
.BI "int semop(int " semid ", struct sembuf *" sops ", size_t " nsops );
.BI "int semtimedop(int " semid ", struct sembuf *" sops ", size_t " nsops ,
.BI " const struct timespec *_Nullable " timeout );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR semtimedop ():
.nf
_GNU_SOURCE
.SH DESCRIPTION
Each semaphore in a System\ V semaphore set
has the following associated values:
-.PP
+.P
.in +4n
.EX
unsigned short semval; /* semaphore value */
modified the semaphore value */
.EE
.in
-.PP
+.P
.BR semop ()
performs operations on selected semaphores in the set indicated by
.IR semid .
The elements of this structure are of type
.IR "struct sembuf" ,
containing the following members:
-.PP
+.P
.in +4n
.EX
unsigned short sem_num; /* semaphore number */
short sem_flg; /* operation flags */
.EE
.in
-.PP
+.P
Flags recognized in
.I sem_flg
are
If an operation specifies
.BR SEM_UNDO ,
it will be automatically undone when the process terminates.
-.PP
+.P
The set of operations contained in
.I sops
is performed in
flag in the individual
.I sem_flg
fields, as noted below.
-.PP
+.P
Each operation is performed on the
.IR 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
.IR sem_op .
-.PP
+.P
If
.I sem_op
is a positive integer, the operation adds this value to
value for this semaphore.
This operation can always proceed\[em]it never forces a thread to wait.
The calling process must have alter permission on the semaphore set.
-.PP
+.P
If
.I sem_op
is zero, the process must have read permission on the semaphore
.I errno
set to
.BR EINTR .
-.PP
+.P
If
.I sem_op
is less than zero, the process must have alter permission on the
.I errno
set to
.BR EINTR .
-.PP
+.P
On successful completion, the
.I sempid
value for each semaphore specified in the array pointed to by
.BR semtimedop ()
behaves exactly like
.BR semop ().
-.PP
+.P
Note that if
.BR semtimedop ()
is interrupted by a signal, causing the call to fail with the error
but they are inherited across an
.BR execve (2)
system call.
-.PP
+.P
.BR semop ()
is never automatically restarted after being interrupted by a signal handler,
regardless of the setting of the
.B SA_RESTART
flag when establishing a signal handler.
-.PP
+.P
A semaphore adjustment
.RI ( semadj )
value is a per-process, per-semaphore integer that is the negated sum
list; see
.BR clone (2)
for details.
-.PP
+.P
The \fIsemval\fP, \fIsempid\fP, \fIsemzcnt\fP, and \fIsemnct\fP values
for a semaphore can all be retrieved using appropriate
.BR semctl (2)
Maximum allowable value for
.IR semval :
implementation dependent (32767).
-.PP
+.P
The implementation has no intrinsic limits for
the adjust on exit maximum value
.RB ( SEMAEM ),
Linux adopts a third approach: decreasing the semaphore value
as far as possible (i.e., to zero) and allowing process
termination to proceed immediately.
-.PP
+.P
In Linux 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.
.BR semop ()
to atomically wait for the value of semaphore 0 to become zero,
and then increment the semaphore value by one.
-.PP
+.P
.in +4n
.EX
struct sembuf sops[2];
}
.EE
.in
-.PP
+.P
A further example of the use of
.BR semop ()
can be found in
.SH SYNOPSIS
.nf
.B #include <sys/socket.h>
-.PP
+.P
.BI "ssize_t send(int " sockfd ", const void " buf [. len "], size_t " len \
", int " flags );
.BI "ssize_t sendto(int " sockfd ", const void " buf [. len "], size_t " len \
and
.BR sendmsg ()
are used to transmit a message to another socket.
-.PP
+.P
The
.BR send ()
call may be used only when the socket is in a
is equivalent to
.BR write (2).
Also, the following call
-.PP
+.P
.in +4n
.EX
send(sockfd, buf, len, flags);
.EE
.in
-.PP
+.P
is equivalent to
-.PP
+.P
.in +4n
.EX
sendto(sockfd, buf, len, flags, NULL, 0);
.EE
.in
-.PP
+.P
The argument
.I sockfd
is the file descriptor of the sending socket.
-.PP
+.P
If
.BR sendto ()
is used on a connection-mode
with
.I msg.msg_namelen
specifying its size.
-.PP
+.P
For
.BR send ()
and
The
.BR sendmsg ()
call also allows sending ancillary data (also known as control information).
-.PP
+.P
If the message is too long to pass atomically through the
underlying protocol, the error
.B EMSGSIZE
is returned, and the message is not transmitted.
-.PP
+.P
No indication of failure to deliver is implicit in a
.BR send ().
Locally detected errors are indicated by a return value of \-1.
-.PP
+.P
When the message does not fit into the send buffer of the socket,
.BR send ()
normally blocks, unless the socket has been placed in nonblocking I/O
structure employed by
.BR sendmsg ()
is as follows:
-.PP
+.P
.in +4n
.EX
struct msghdr {
};
.EE
.in
-.PP
+.P
The
.I msg_name
field is used on an unconnected socket to specify the target
field should be set to the size of the address.
For a connected socket, these fields should be specified as NULL and 0,
respectively.
-.PP
+.P
The
.I msg_iov
and
.I msg_iovlen
fields specify scatter-gather locations, as for
.BR writev (2).
-.PP
+.P
You may send control information (ancillary data) using the
.I msg_control
and
.BR unix (7)
and
.BR ip (7).
-.PP
+.P
The
.I msg_flags
field is ignored.
.\" as (at least with GCC) is int.
.SH STANDARDS
POSIX.1-2008.
-.PP
+.P
.B MSG_CONFIRM
is a Linux extension.
.SH HISTORY
4.4BSD, SVr4, POSIX.1-2001.
(first appeared in 4.2BSD).
-.PP
+.P
POSIX.1-2001 describes only the
.B MSG_OOB
and
.SH SYNOPSIS
.nf
.B #include <sys/sendfile.h>
-.PP
+.P
.BI "ssize_t sendfile(int" " out_fd" ", int" " in_fd" ", \
off_t *_Nullable " offset ,
.BI " size_t" " count" );
and
.BR write (2),
which would require transferring data to and from user space.
-.PP
+.P
.I in_fd
should be a file descriptor opened for reading and
.I out_fd
should be a descriptor opened for writing.
-.PP
+.P
If
.I offset
is not NULL, then it points
otherwise the file offset is adjusted to reflect
the number of bytes read from
.IR in_fd .
-.PP
+.P
If
.I offset
is NULL, then data will be read from
.I in_fd
starting at the file offset,
and the file offset will be updated by the call.
-.PP
+.P
.I count
is the number of bytes to copy between the file descriptors.
-.PP
+.P
The
.I in_fd
argument must correspond to a file which supports
.BR mmap (2)-like
operations
(i.e., it cannot be a socket).
-.PP
+.P
Before Linux 2.6.33,
.I out_fd
must refer to a socket.
may write fewer bytes than requested;
the caller should be prepared to retry the call if there were unsent bytes.
See also NOTES.
-.PP
+.P
On error, \-1 is returned, and
.I errno
is set to indicate the error.
.SH HISTORY
Linux 2.2,
glibc 2.1.
-.PP
+.P
In Linux 2.4 and earlier,
.I out_fd
could also refer to a regular file;
this possibility went away in the Linux 2.6.x kernel series,
but was restored in Linux 2.6.33.
-.PP
+.P
The original Linux
.BR sendfile ()
system call was not designed to handle large file offsets.
returning the number of bytes actually transferred.
.\" commit e28cc71572da38a5a12c1cfe4d7032017adccf69
(This is true on both 32-bit and 64-bit systems.)
-.PP
+.P
If you plan to use
.BR sendfile ()
for sending files to a TCP socket, but need
option, described in
.BR tcp (7),
to minimize the number of packets and to tune performance.
-.PP
+.P
Applications may wish to fall back to
.BR read (2)
and
.B EINVAL
or
.BR ENOSYS .
-.PP
+.P
If
.I out_fd
refers to a socket or pipe with zero-copy support, callers must ensure the
remain unmodified until the reader on the other end of
.I out_fd
has consumed the transferred data.
-.PP
+.P
The Linux-specific
.BR splice (2)
call supports transferring data between arbitrary file descriptors
.nf
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <sys/socket.h>
-.PP
+.P
.BI "int sendmmsg(int " sockfd ", struct mmsghdr *" msgvec \
", unsigned int " vlen ","
.BI " int " flags ");"
using a single system call.
(This has performance benefits for some applications.)
.\" See commit 228e548e602061b08ee8e8966f567c12aa079682
-.PP
+.P
The
.I sockfd
argument is the file descriptor of the socket
on which data is to be transmitted.
-.PP
+.P
The
.I msgvec
argument is a pointer to an array of
structures.
The size of this array is specified in
.IR vlen .
-.PP
+.P
The
.I mmsghdr
structure is defined in
.I <sys/socket.h>
as:
-.PP
+.P
.in +4n
.EX
struct mmsghdr {
};
.EE
.in
-.PP
+.P
The
.I msg_hdr
field is a
(i.e., the same as the return value from a single
.BR sendmsg (2)
call).
-.PP
+.P
The
.I flags
argument contains flags ORed together.
The flags are the same as for
.BR sendmsg (2).
-.PP
+.P
A blocking
.BR sendmmsg ()
call blocks until
(up to the limit specified by
.IR vlen )
and returns immediately.
-.PP
+.P
On return from
.BR sendmmsg (),
the
the caller can retry with a further
.BR sendmmsg ()
call to send the remaining messages.
-.PP
+.P
On error, \-1 is returned, and
.I errno
is set to indicate the error.
.I three
in two distinct UDP datagrams using one system call.
The contents of the first datagram originates from a pair of buffers.
-.PP
+.P
.\" SRC BEGIN (sendmmsg.c)
.EX
#define _GNU_SOURCE
.SH SYNOPSIS
.nf
.B "#include <numaif.h>"
-.PP
+.P
.BI "long set_mempolicy(int " mode ", const unsigned long *" nodemask ,
.BI " unsigned long " maxnode );
.fi
and
.I maxnode
arguments.
-.PP
+.P
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 thread.
-.PP
+.P
This system call defines the default policy for the thread.
The thread policy governs allocation of pages in the process's
address space outside of memory ranges
for the thread.
For anonymous memory this is when the page is first
touched by the thread.
-.PP
+.P
The
.I mode
argument must specify one of
via the
.I nodemask
argument.
-.PP
+.P
The
.I mode
argument may also include an optional
when the process moves to a different cpuset context,
nor when the set of nodes allowed by the process's
current cpuset context changes.
-.PP
+.P
.I nodemask
points to a bit mask of node IDs that contains up to
.I maxnode
the
.I nodemask
argument is ignored.
-.PP
+.P
Where a
.I nodemask
is required, it must contain at least one node that is on-line,
This effectively overrides the specified policy until the process's
cpuset context includes one or more of the nodes specified by
.IR nodemask .
-.PP
+.P
The
.I mode
argument must include one of the following values:
the kernel will try to allocate memory from other nodes.
The kernel will allocate memory from the "local node" whenever
it becomes allowed by the process's current cpuset context.
-.PP
+.P
The thread memory policy is preserved across an
.BR execve (2),
and is inherited by child threads created using
When such a page is paged back in, it will use the policy of
the thread or memory range that is in effect at the time the
page is allocated.
-.PP
+.P
For information on library support, see
.BR numa (7).
.SH SEE ALSO
.nf
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.B #if defined __i386__ || defined __x86_64__
.BR "# include <asm/ldt.h>" " /* Definition of " "struct user_desc" " */"
-.PP
+.P
.BI "int syscall(SYS_get_thread_area, struct user_desc *" u_info );
.BI "int syscall(SYS_set_thread_area, struct user_desc *" u_info );
-.PP
+.P
.B #elif defined __m68k__
-.PP
+.P
.B "int syscall(SYS_get_thread_area);"
.BI "int syscall(SYS_set_thread_area, unsigned long " tp );
-.PP
+.P
.B #elif defined __mips__ || defined __csky__
-.PP
+.P
.BI "int syscall(SYS_set_thread_area, unsigned long " addr );
-.PP
+.P
.B #endif
.fi
-.PP
+.P
.IR Note :
glibc provides no wrappers for these system calls,
necessitating the use of
is available on m68k, MIPS, C-SKY, and x86 (both 32-bit and 64-bit variants);
.BR get_thread_area ()
is available on m68k and x86.
-.PP
+.P
On m68k, MIPS and C-SKY,
.BR set_thread_area ()
allows storing an arbitrary pointer (provided in the
.BR get_thread_area ()
(see also NOTES
for information regarding obtaining the thread pointer on MIPS).
-.PP
+.P
On x86, Linux dedicates three global descriptor table (GDT) entries for
thread-local storage.
For more information about the GDT, see the
Intel Software Developer's Manual or the AMD Architecture Programming Manual.
-.PP
+.P
Both of these system calls take an argument that is a pointer
to a structure of the following type:
-.PP
+.P
.in +4n
.EX
struct user_desc {
};
.EE
.in
-.PP
+.P
.BR get_thread_area ()
reads the GDT entry indicated by
.I u_info\->entry_number
and fills in the rest of the fields in
.IR u_info .
-.PP
+.P
.BR set_thread_area ()
sets a TLS entry in the GDT.
-.PP
+.P
The TLS array entry set by
.BR set_thread_area ()
corresponds to the value of
writes the TLS descriptor pointed to by
.I u_info
into the thread's TLS array.
-.PP
+.P
When
.BR set_thread_area ()
is passed an
finds a free TLS entry, the value of
.I u_info\->entry_number
is set upon return to show which entry was changed.
-.PP
+.P
A
.I user_desc
is considered "empty" if
.BR set_thread_area (),
the corresponding TLS entry will be cleared.
See BUGS for additional details.
-.PP
+.P
Since Linux 3.19,
.BR set_thread_area ()
cannot be used to write non-present segments, 16-bit segments, or code
return 0 on success, and \-1 on failure, with
.I errno
set to indicate the error.
-.PP
+.P
On C-SKY, MIPS and m68k,
.BR set_thread_area ()
always returns 0.
Linux 2.5.32.
.SH NOTES
These system calls are generally intended for use only by threading libraries.
-.PP
+.P
.BR arch_prctl (2)
can interfere with
.BR set_thread_area ()
This is not normally a problem, as
.BR arch_prctl (2)
is normally used only by 64-bit programs.
-.PP
+.P
On MIPS, the current value of the thread area pointer can be obtained
using the instruction:
-.PP
+.P
.in +4n
.EX
rdhwr dest, $29
.EE
.in
-.PP
+.P
This instruction traps and is handled by kernel.
.SH BUGS
On 64-bit kernels before Linux 3.19,
.I entry_number
will also be interpreted as a request to clear a TLS entry, but this
behaved differently on older kernels.
-.PP
+.P
Prior to Linux 3.19, the DS and ES segment registers must not reference
TLS entries.
.SH SEE ALSO
.nf
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "pid_t syscall(SYS_set_tid_address, int *" tidptr );
.fi
-.PP
+.P
.IR Note :
glibc provides no wrapper for
.BR set_tid_address (),
is set to the value passed in the
.I ctid
argument of that system call.
-.PP
+.P
The system call
.BR set_tid_address ()
sets the
.I clear_child_tid
value for the calling thread to
.IR tidptr .
-.PP
+.P
When a thread whose
.I clear_child_tid
is not NULL terminates, then,
then 0 is written at the address specified in
.I clear_child_tid
and the kernel performs the following operation:
-.PP
+.P
.in +4n
.EX
futex(clear_child_tid, FUTEX_WAKE, 1, NULL, NULL, 0);
.EE
.in
-.PP
+.P
The effect of this operation is to wake a single thread that
is performing a futex wait on the memory location.
Errors from the futex wake operation are ignored.
Linux.
.SH HISTORY
Linux 2.5.48.
-.PP
+.P
Details as given here are valid since Linux 2.5.49.
.SH SEE ALSO
.BR clone (2),
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.BI "int seteuid(uid_t " euid );
.BI "int setegid(gid_t " egid );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR seteuid (),
.BR setegid ():
.nf
sets the effective user ID of the calling process.
Unprivileged processes may only set the effective user ID to the
real user ID, the effective user ID or the saved set-user-ID.
-.PP
+.P
Precisely the same holds for
.BR setegid ()
with "group" instead of "user".
On error, \-1 is returned, and
.I errno
is set to indicate the error.
-.PP
+.P
.IR Note :
there are cases where
.BR seteuid ()
possible since Linux 1.1.37 (1.1.38).
On an arbitrary system one should check
.BR _POSIX_SAVED_IDS .
-.PP
+.P
Under glibc 2.0,
.BI seteuid( euid )
is equivalent to
to
.BI setresgid(\-1, " egid" ", \-1)"
occurred in glibc 2.2 or 2.3 (depending on the hardware architecture).
-.PP
+.P
According to POSIX.1,
.BR seteuid ()
.RB ( setegid ())
.SH SYNOPSIS
.nf
.B #include <sys/fsuid.h>
-.PP
+.P
.BI "[[deprecated]] int setfsgid(gid_t " fsgid );
.fi
.SH DESCRIPTION
while the effective group ID is used for some other kinds
of permissions checks (see
.BR credentials (7)).
-.PP
+.P
Normally, the value of the process's filesystem group ID
is the same as the value of its effective group ID.
This is so, because whenever a process's effective group ID is changed,
.BR setfsgid ()
to change its filesystem group ID to the value given in
.IR fsgid .
-.PP
+.P
.BR setfsgid ()
will succeed only if the caller is the superuser or if
.I fsgid
and
.BR setfsgid ()
is nowadays unneeded.
-.PP
+.P
The original Linux
.BR setfsgid ()
system call supported only 16-bit group IDs.
.SH SYNOPSIS
.nf
.B #include <sys/fsuid.h>
-.PP
+.P
.BI "[[deprecated]] int setfsuid(uid_t " fsuid );
.fi
.SH DESCRIPTION
while the effective user ID is used for various other kinds
of permissions checks (see
.BR credentials (7)).
-.PP
+.P
Normally, the value of the process's filesystem user ID
is the same as the value of its effective user ID.
This is so, because whenever a process's effective user ID is changed,
.BR setfsuid ()
to change its filesystem user ID to the value given in
.IR fsuid .
-.PP
+.P
Explicit calls to
.BR setfsuid ()
and
A change in the normal user IDs for a program such as the NFS server
is (was) a security hole that can expose it to unwanted signals.
(However, this issue is historical; see below.)
-.PP
+.P
.BR setfsuid ()
will succeed only if the caller is the superuser or if
.I fsuid
Linux 1.2.
.\" Linux 1.1.44
.\" and in libc since libc 4.7.6.
-.PP
+.P
At the time when this system call was introduced, one process
could send a signal to another process with the same effective user ID.
This meant that if a privileged process changed its effective user ID
is nowadays unneeded and should be avoided in new applications
(likewise for
.BR setfsgid (2)).
-.PP
+.P
The original Linux
.BR setfsuid ()
system call supported only 16-bit user IDs.
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.BI "int setgid(gid_t " gid );
.fi
.SH DESCRIPTION
.B CAP_SETGID
capability in its user namespace),
the real GID and saved set-group-ID are also set.
-.PP
+.P
Under Linux,
.BR setgid ()
is implemented like the POSIX version with the
POSIX.1-2008.
.SH HISTORY
POSIX.1-2001, SVr4.
-.PP
+.P
The original Linux
.BR setgid ()
system call supported only 16-bit group IDs.
.nf
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <sched.h>
-.PP
+.P
.BI "int setns(int " fd ", int " nstype );
.fi
.SH DESCRIPTION
.IP \[bu]
a PID file descriptor (see
.BR pidfd_open (2)).
-.PP
+.P
The
.I nstype
argument is interpreted differently in each case.
In this usage, each call to
.BR setns ()
changes just one of the caller's namespace memberships.
-.PP
+.P
The
.I nstype
argument specifies which type of namespace
.BR CLONE_NEWUTS " (since Linux 3.0)"
.I fd
must refer to a UTS namespace.
-.PP
+.P
Specifying
.I nstype
as 0 suffices if the caller knows (or does not care)
atomically moves the calling thread into one or more of the same namespaces
as the thread referred to by
.IR fd .
-.PP
+.P
The
.I nstype
argument is a bit mask specified by ORing together
that is specified in
.IR nstype ;
the caller's memberships in the remaining namespaces are left unchanged.
-.PP
+.P
For example, the following code would move the caller into the
same user, network, and UTS namespaces as PID 1234,
but would leave the caller's other namespace memberships unchanged:
-.PP
+.P
.in +4n
.EX
int fd = pidfd_open(1234, 0);
.IR /proc/ pid /ns/
magic links, see
.BR namespaces (7).
-.PP
+.P
Not all of the attributes that can be shared when
a new thread is created using
.BR clone (2)
The program opens the namespace file, joins that namespace using
.BR setns (),
and executes the specified command inside that namespace.
-.PP
+.P
The following shell session demonstrates the use of this program
(compiled as a binary named
.IR ns_exec )
.BR clone (2)
man page (complied as a binary named
.IR newuts ).
-.PP
+.P
We begin by executing the example program in
.BR clone (2)
in the background.
The child changes the hostname in its namespace,
and then both processes display the hostnames in their UTS namespaces,
so that we can see that they are different.
-.PP
+.P
.in +4n
.EX
$ \fBsu\fP # Need privilege for namespace operations
antero
.EE
.in
-.PP
+.P
We then run the program shown below,
using it to execute a shell.
Inside that shell, we verify that the hostname is the one
set by the child created by the first program:
-.PP
+.P
.in +4n
.EX
# \fB./ns_exec /proc/3550/ns/uts /bin/bash\fP
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.BI "int setpgid(pid_t " pid ", pid_t " pgid );
.BI "pid_t getpgid(pid_t " pid );
-.PP
+.P
.BR "pid_t getpgrp(void);" " /* POSIX.1 version */"
.BI "[[deprecated]] pid_t getpgrp(pid_t " pid ");\fR /* BSD version */"
-.PP
+.P
.BR "int setpgrp(void);" " /* System V version */"
.BI "[[deprecated]] int setpgrp(pid_t " pid ", pid_t " pgid ");\fR /* BSD version */"
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR getpgid ():
.nf
_XOPEN_SOURCE >= 500
.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
|| /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
.fi
-.PP
+.P
.BR setpgrp "() (POSIX.1):"
.nf
_XOPEN_SOURCE >= 500
|| /* Since glibc 2.19: */ _DEFAULT_SOURCE
|| /* glibc <= 2.19: */ _SVID_SOURCE
.fi
-.PP
+.P
.BR setpgrp "() (BSD),"
.BR getpgrp "() (BSD):"
.nf
for retrieving the calling process's PGID; and
.BR setpgid (),
for setting a process's PGID.
-.PP
+.P
.BR setpgid ()
sets the PGID of the process specified by
.I pid
In this case,
the \fIpgid\fP specifies an existing process group to be joined and the
session ID of that group must match the session ID of the joining process.
-.PP
+.P
The POSIX.1 version of
.BR getpgrp (),
which takes no arguments,
returns the PGID of the calling process.
-.PP
+.P
.BR getpgid ()
returns the PGID of the process specified by
.IR pid .
necessary, and the POSIX.1
.BR getpgrp ()
is preferred for that task.)
-.PP
+.P
The System\ V-style
.BR setpgrp (),
which takes no arguments, is equivalent to
.IR "setpgid(0,\ 0)" .
-.PP
+.P
The BSD-specific
.BR setpgrp ()
call, which takes arguments
and
.IR pgid ,
is a wrapper function that calls
-.PP
+.P
.in +4n
.EX
setpgid(pid, pgid)
.EE
.in
-.PP
+.P
.\" The true BSD setpgrp() system call differs in allowing the PGID
.\" to be set to arbitrary values, rather than being restricted to
.\" PGIDs in the same session.
calls should be replaced with the
.BR setpgid ()
call shown above.
-.PP
+.P
The BSD-specific
.BR getpgrp ()
call, which takes a single
.I pid
argument, is a wrapper function that calls
-.PP
+.P
.in +4n
.EX
getpgid(pid)
.EE
.in
-.PP
+.P
Since glibc 2.19, the BSD-specific
.BR getpgrp ()
function is no longer exposed by
On error, \-1 is returned, and
.I errno
is set to indicate the error.
-.PP
+.P
The POSIX.1
.BR getpgrp ()
always returns the PGID of the caller.
-.PP
+.P
.BR getpgid (),
and the BSD-specific
.BR getpgrp ()
inherits its parent's process group ID.
The PGID is preserved across an
.BR execve (2).
-.PP
+.P
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.
(See
.BR credentials (7).)
-.PP
+.P
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
.BR tcsetpgrp (3)
functions are used to get/set the foreground
process group of the controlling terminal.
-.PP
+.P
The
.BR setpgid ()
and
calls are used by programs such as
.BR bash (1)
to create process groups in order to implement shell job control.
-.PP
+.P
If the termination of a process causes a process group to become orphaned,
and if any member of the newly orphaned process group is stopped, then a
.B SIGHUP
.nf
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <unistd.h>
-.PP
+.P
.BI "int setresuid(uid_t " ruid ", uid_t " euid ", uid_t " suid );
.BI "int setresgid(gid_t " rgid ", gid_t " egid ", gid_t " sgid );
.fi
.BR setresuid ()
sets the real user ID, the effective user ID, and the
saved set-user-ID of the calling process.
-.PP
+.P
An unprivileged process may change its 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.
-.PP
+.P
A privileged process (on Linux, one having the \fBCAP_SETUID\fP capability)
may set its real UID, effective UID, and
saved set-user-ID to arbitrary values.
-.PP
+.P
If one of the arguments equals \-1, the corresponding value is not changed.
-.PP
+.P
Regardless of what changes are made to the real UID, effective UID,
and saved set-user-ID, the filesystem UID is always set to the same
value as the (possibly new) effective UID.
-.PP
+.P
Completely analogously,
.BR setresgid ()
sets the real GID, effective GID, and saved set-group-ID
On error, \-1 is returned, and
.I errno
is set to indicate the error.
-.PP
+.P
.IR Note :
there are cases where
.BR setresuid ()
Linux 2.1.44,
glibc 2.3.2.
HP-UX, FreeBSD.
-.PP
+.P
The original Linux
.BR setresuid ()
and
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.BI "int setreuid(uid_t " ruid ", uid_t " euid );
.BI "int setregid(gid_t " rgid ", gid_t " egid );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR setreuid (),
.BR setregid ():
.nf
.SH DESCRIPTION
.BR setreuid ()
sets real and effective user IDs of the calling process.
-.PP
+.P
Supplying a value of \-1 for either the real or effective user ID forces
the system to leave that ID unchanged.
-.PP
+.P
Unprivileged processes may only set the effective user ID to the real user ID,
the effective user ID, or the saved set-user-ID.
-.PP
+.P
Unprivileged users may only set the real user ID to
the real user ID or the effective user ID.
-.PP
+.P
If the real user ID is set (i.e.,
.I ruid
is not \-1) 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.
-.PP
+.P
Completely analogously,
.BR setregid ()
sets real and effective group ID's of the calling process,
On error, \-1 is returned, and
.I errno
is set to indicate the error.
-.PP
+.P
.IR Note :
there are cases where
.BR setreuid ()
the real group ID or the saved set-group-ID.
The precise details of what ID changes are permitted vary
across implementations.
-.PP
+.P
POSIX.1 makes no specification about the effect of these calls
on the saved set-user-ID and saved set-group-ID.
.SH STANDARDS
POSIX.1-2008.
.SH HISTORY
POSIX.1-2001, 4.3BSD (first appeared in 4.2BSD).
-.PP
+.P
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).
-.PP
+.P
The original Linux
.BR setreuid ()
and
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.B pid_t setsid(void);
.fi
.SH DESCRIPTION
The calling process also becomes
the process group leader of a new process group in the session
(i.e., its process group ID is made the same as its process ID).
-.PP
+.P
The calling process will be the only process in
the new process group and in the new session.
-.PP
+.P
Initially, the new session has no controlling terminal.
For details of how a session acquires a controlling terminal, see
.BR credentials (7).
inherits its parent's session ID.
The session ID is preserved across an
.BR execve (2).
-.PP
+.P
A process group leader is a process whose process group ID equals its PID.
Disallowing a process group leader from calling
.BR setsid ()
.BR _exit (2),
while the child (which by definition can't be a process group leader) calls
.BR setsid ().
-.PP
+.P
If a session has a controlling terminal, and the
.B CLOCAL
flag for that terminal is not set,
and a terminal hangup occurs, then the session leader is sent a
.B SIGHUP
signal.
-.PP
+.P
If a process that is a session leader terminates, then a
.B SIGHUP
signal is sent to each process in the foreground
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.BI "int setuid(uid_t " uid );
.fi
.SH DESCRIPTION
.B CAP_SETUID
capability in its user namespace),
the real UID and saved set-user-ID are also set.
-.PP
+.P
Under Linux,
.BR setuid ()
is implemented like the POSIX version with the
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.
-.PP
+.P
If the user is root or the program is set-user-ID-root, special care must be
taken:
.BR setuid ()
.IR uid .
After this has occurred, it is impossible for the program to regain root
privileges.
-.PP
+.P
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
On error, \-1 is returned, and
.I errno
is set to indicate the error.
-.PP
+.P
.IR Note :
there are cases where
.BR setuid ()
POSIX.1-2008.
.SH HISTORY
POSIX.1-2001, SVr4.
-.PP
+.P
Not quite compatible with the 4.4BSD call, which
sets all of the real, saved, and effective user IDs.
.\" SVr4 documents an additional EINVAL error condition.
-.PP
+.P
The original Linux
.BR setuid ()
system call supported only 16-bit user IDs.
call also sets the filesystem user ID of the calling process.
See
.BR setfsuid (2).
-.PP
+.P
If
.I uid
is different from the old effective UID, the process will
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.B [[deprecated]] int setup(void);
.fi
.SH DESCRIPTION
.IR linux/init/main.c .
It calls initialization functions for devices and filesystems
configured into the kernel and then mounts the root filesystem.
-.PP
+.P
No user process may call
.BR setup ().
Any user process, even a process with superuser permission,
Linux.
.SH VERSIONS
Removed in Linux 2.1.121.
-.PP
+.P
The calling sequence varied: at some times
.BR setup ()
has had a single argument
.SH SYNOPSIS
.nf
.B #include <sys/xattr.h>
-.PP
+.P
.BI "int setxattr(const char *" path ", const char *" name ,
.BI " const void " value [. size "], size_t " size ", int " flags );
.BI "int lsetxattr(const char *" path ", const char *" name ,
data).
A complete overview of extended attributes concepts can be found in
.BR xattr (7).
-.PP
+.P
.BR setxattr ()
sets the
.I value
argument specifies the size (in bytes) of
.IR value ;
a zero-length value is permitted.
-.PP
+.P
.BR lsetxattr ()
is identical to
.BR 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.
-.PP
+.P
.BR fsetxattr ()
is identical to
.BR setxattr (),
.BR open (2))
in place of
.IR path .
-.PP
+.P
An extended attribute name is a null-terminated string.
The
.I name
.I value
of an extended attribute is a chunk of arbitrary textual or
binary data of specified length.
-.PP
+.P
By default
(i.e.,
.I flags
The file is marked immutable or append-only.
(See
.BR ioctl_iflags (2).)
-.PP
+.P
In addition, the errors documented in
.BR stat (2)
can also occur.
.nf
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.B [[deprecated]] long syscall(SYS_sgetmask, void);
.BI "[[deprecated]] long syscall(SYS_ssetmask, long " newmask );
.fi
use
.BR sigprocmask (2)
instead.
-.PP
+.P
.BR sgetmask ()
returns the signal mask of the calling process.
-.PP
+.P
.BR ssetmask ()
sets the signal mask of the calling process to the value given in
.IR newmask .
The previous signal mask is returned.
-.PP
+.P
The signal masks dealt with by these two system calls
are plain bit masks (unlike the
.I sigset_t
.SH NOTES
These system calls are unaware of signal numbers greater than 31
(i.e., real-time signals).
-.PP
+.P
These system calls do not exist on x86-64.
-.PP
+.P
It is not possible to block
.B SIGSTOP
or
.SH SYNOPSIS
.nf
.B #include <sys/shm.h>
-.PP
+.P
.BI "int shmctl(int " shmid ", int " cmd ", struct shmid_ds *" buf );
.fi
.SH DESCRIPTION
.I cmd
on the System\ V shared memory segment whose identifier is given in
.IR shmid .
-.PP
+.P
The
.I buf
argument is a pointer to a \fIshmid_ds\fP structure,
defined in \fI<sys/shm.h>\fP as follows:
-.PP
+.P
.in +4n
.EX
struct shmid_ds {
};
.EE
.in
-.PP
+.P
The fields of the
.I shmid_ds
structure are as follows:
.TP
.I shm_nattch
Number of processes that have this segment attached.
-.PP
+.P
The
.I ipc_perm
structure is defined as follows
(the highlighted fields are settable using
.BR IPC_SET ):
-.PP
+.P
.in +4n
.EX
struct ipc_perm {
};
.EE
.in
-.PP
+.P
The least significant 9 bits of the
.I mode
field of the
0004 Read by others
0002 Write by others
.TE
-.PP
+.P
Bits 0100, 0010, and 0001 (the execute bits) are unused by the system.
(It is not necessary to have execute permission on a segment
in order to perform a
call with the
.B SHM_EXEC
flag.)
-.PP
+.P
Valid values for
.I cmd
are:
meaning that any user can employ this operation (just as any user may read
.I /proc/sysvipc/shm
to obtain the same information).
-.PP
+.P
The caller can prevent or allow swapping of a shared
memory segment with the following \fIcmd\fP values:
.TP
.TP
.BR SHM_UNLOCK " (Linux-specific)"
Unlock the segment, allowing it to be swapped out.
-.PP
+.P
Before Linux 2.6.10, only a privileged process
could employ
.B SHM_LOCK
whose index was given in
.IR shmid .
Other operations return 0 on success.
-.PP
+.P
On error, \-1 is returned, and
.I errno
is set to indicate the error.
.\" SVr4 documents additional error conditions EINVAL,
.\" ENOENT, ENOSPC, ENOMEM, EEXIST. Neither SVr4 nor SVID documents
.\" an EIDRM error condition.
-.PP
+.P
Various fields in a \fIstruct shmid_ds\fP were typed as
.I short
under Linux 2.2
.SH SYNOPSIS
.nf
.B #include <sys/shm.h>
-.PP
+.P
.BI "int shmget(key_t " key ", size_t " size ", int " shmflg );
.fi
.SH DESCRIPTION
does not have the value
.BR IPC_PRIVATE ),
or to create a new set.
-.PP
+.P
A new shared memory segment, with size equal to the value of
.I size
rounded up to a multiple of
.B IPC_CREAT
is specified in
.IR shmflg .
-.PP
+.P
If
.I shmflg
specifies both
.B O_CREAT | O_EXCL
for
.BR open (2).)
-.PP
+.P
The value
.I shmflg
is composed of:
.BR proc (5).
.\" As at 2.6.17-rc2, this flag has no effect if SHM_HUGETLB was also
.\" specified.
-.PP
+.P
In addition to the above flags, the least significant 9 bits of
.I shmflg
specify the permissions granted to the owner, group, and others.
argument of
.BR open (2).
Presently, execute permissions are not used by the system.
-.PP
+.P
When a new shared memory segment is created,
its contents are initialized to zero values, and
its associated data structure,
.IP \[bu]
.I shm_ctime
is set to the current time.
-.PP
+.P
If the shared memory segment already exists, the permissions are
verified, and a check is made to see if it is marked for destruction.
.SH RETURN VALUE
.BR proc (5).
.SH STANDARDS
POSIX.1-2008.
-.PP
+.P
.B SHM_HUGETLB
and
.B SHM_NORESERVE
.\" Kernels between Linux 2.4.x and Linux 2.6.8 had an off-by-one error
.\" that meant that we could create one more segment than SHMMNI -- MTK
.\" This /proc file is not available in Linux 2.2 and earlier -- MTK
-.PP
+.P
The implementation has no specific limits for the per-process maximum
number of shared memory segments
.RB ( SHMSEG ).
.SH SYNOPSIS
.nf
.B #include <sys/shm.h>
-.PP
+.P
.BI "void *shmat(int " shmid ", const void *_Nullable " shmaddr ", \
int " shmflg );
.BI "int shmdt(const void *" shmaddr );
Otherwise,
.I shmaddr
must be a page-aligned address at which the attach occurs.
-.PP
+.P
In addition to
.BR SHM_RND ,
the following flags may be specified in the
In this case,
.I shmaddr
must not be NULL.
-.PP
+.P
The
.BR 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.
-.PP
+.P
A successful
.BR shmat ()
call updates the members of the
equal to the value returned by the attaching
.BR shmat ()
call.
-.PP
+.P
On a successful
.BR shmdt ()
call, the system updates the members of the
is returned, and
.I errno
is set to indicate the error.
-.PP
+.P
On success,
.BR shmdt ()
returns 0; on error \-1 is returned, and
.TP
.B ENOMEM
Could not allocate memory for the descriptor or for the page tables.
-.PP
+.P
.BR shmdt ()
can fail with one of the following errors:
.TP
.SH HISTORY
POSIX.1-2001, SVr4.
.\" SVr4 documents an additional error condition EMFILE.
-.PP
+.P
In SVID 3 (or perhaps earlier),
the type of the \fIshmaddr\fP argument was changed from
.I "char\ *"
After a
.BR fork (2),
the child inherits the attached shared memory segments.
-.PP
+.P
After an
.BR execve (2),
all attached shared memory segments are detached from the process.
-.PP
+.P
Upon
.BR _exit (2),
all attached shared memory segments are detached from the process.
-.PP
+.P
Using
.BR shmat ()
with
Therefore, any pointers maintained within the shared memory must be
made relative (typically to the starting address of the segment),
rather than absolute.
-.PP
+.P
On Linux, it is possible to attach a shared memory segment even if it
is already marked to be deleted.
However, POSIX.1 does not specify this behavior and
many other implementations do not support it.
-.PP
+.P
The following system parameter affects
.BR shmat ():
.TP
(On many Linux architectures,
.B SHMLBA
is the same as the system page size.)
-.PP
+.P
The implementation places no intrinsic per-process limit on the
number of shared memory segments
.RB ( SHMSEG ).
The two programs shown below exchange a string using a shared memory segment.
Further details about the programs are given below.
First, we show a shell session demonstrating their use.
-.PP
+.P
In one terminal window, we run the "reader" program,
which creates a System V shared memory segment and a System V semaphore set.
The program prints out the IDs of the created objects,
and then waits for the semaphore to change value.
-.PP
+.P
.in +4n
.EX
$ \fB./svshm_string_read\fP
shmid = 1114194; semid = 15
.EE
.in
-.PP
+.P
In another terminal window, we run the "writer" program.
The "writer" program takes three command-line arguments:
the IDs of the shared memory segment and semaphore set created
by the "reader", and a string.
It attaches the existing shared memory segment,
copies the string to the shared memory, and modifies the semaphore value.
-.PP
+.P
.in +4n
.EX
$ \fB./svshm_string_write 1114194 15 \[aq]Hello, world\[aq]\fP
.EE
.in
-.PP
+.P
Returning to the terminal where the "reader" is running,
we see that the program has ceased waiting on the semaphore
and has printed the string that was copied into the
shared memory segment by the writer:
-.PP
+.P
.in +4n
.EX
Hello, world
.\"
.SS Program source: svshm_string.h
The following header file is included by the "reader" and "writer" programs:
-.PP
+.P
.in +4n
.\" SRC BEGIN (svshm_string.h)
.EX
Finally, the program waits for the semaphore value to become 0,
and afterwards prints the string that has been copied into the
shared memory segment by the "writer".
-.PP
+.P
.in +4n
.\" SRC BEGIN (svshm_string_read.c)
.EX
It attaches the shared memory segment into its address space,
and then decrements the semaphore value to 0 in order to inform the
"reader" that it can now examine the contents of the shared memory.
-.PP
+.P
.in +4n
.\" SRC BEGIN (svshm_string_write.c)
.EX
.SH SYNOPSIS
.nf
.B #include <sys/socket.h>
-.PP
+.P
.BI "int shutdown(int " sockfd ", int " how );
.fi
.SH DESCRIPTION
.SH SYNOPSIS
.nf
.B #include <signal.h>
-.PP
+.P
.BI "int sigaction(int " signum ,
.BI " const struct sigaction *_Nullable restrict " act ,
.BI " struct sigaction *_Nullable restrict " oldact );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR sigaction ():
.nf
_POSIX_C_SOURCE
.fi
-.PP
+.P
.IR siginfo_t :
.nf
_POSIX_C_SOURCE >= 199309L
(See
.BR signal (7)
for an overview of signals.)
-.PP
+.P
.I signum
specifies the signal and can be any valid signal except
.B SIGKILL
and
.BR SIGSTOP .
-.PP
+.P
If
.I act
is non-NULL, the new action for signal
.I oldact
is non-NULL, the previous action is saved in
.IR oldact .
-.PP
+.P
The
.I sigaction
structure is defined as something like:
-.PP
+.P
.in +4n
.EX
struct sigaction {
};
.EE
.in
-.PP
+.P
On some architectures a union is involved: do not assign to both
.I sa_handler
and
.IR sa_sigaction .
-.PP
+.P
The
.I sa_restorer
field is not intended for application use.
field.)
Some further details of the purpose of this field can be found in
.BR sigreturn (2).
-.PP
+.P
.I sa_handler
specifies the action to be associated with
.I signum
.IP \[bu]
A pointer to a signal handling function.
This function receives the signal number as its only argument.
-.PP
+.P
If
.B SA_SIGINFO
is specified in
specifies the signal-handling function for
.IR signum .
This function receives three arguments, as described below.
-.PP
+.P
.I sa_mask
specifies a mask of signals which should be blocked
(i.e., added to the signal mask of the thread in which
will be blocked, unless the
.B SA_NODEFER
flag is used.
-.PP
+.P
.I 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:
.I act.sa_sigaction
field.
This handler takes three arguments, as follows:
-.PP
+.P
.in +4n
.EX
void
}
.EE
.in
-.PP
+.P
These three arguments are as follows
.TP
.I sig
and
.BR signal (7).
Commonly, the handler function doesn't make any use of the third argument.
-.PP
+.P
The
.I siginfo_t
data type is a structure with the following fields:
-.PP
+.P
.in +4n
.EX
siginfo_t {
}
.EE
.in
-.PP
+.P
.IR si_signo ", " si_errno " and " si_code
are defined for all signals.
.RI ( si_errno
will contain
.B SIGTRAP
and have the ptrace event in the high byte:
-.PP
+.P
.in +4n
.EX
(SIGTRAP | PTRACE_EVENT_foo << 8).
.EE
.in
-.PP
+.P
For a
.RB non- ptrace (2)
event, the values that can appear in
.IP \[bu]
.B _POSIX_C_SOURCE
with the value 200809L or greater.
-.PP
+.P
For the
.B TRAP_*
constants, the symbol definitions are provided only in the first two cases.
Before glibc 2.20, no feature test macros were required to obtain these symbols.
-.PP
+.P
For a regular signal, the following list shows the values which can be
placed in
.I si_code
.\" It appears to have been an idea that was tried during 2.5.6
.\" through to Linux 2.5.24 and then was backed out.
.RE
-.PP
+.P
The following values can be placed in
.I si_code
for a
.B ILL_BADSTK
Internal stack error.
.RE
-.PP
+.P
The following values can be placed in
.I si_code
for a
.B FPE_FLTSUB
Subscript out of range.
.RE
-.PP
+.P
The following values can be placed in
.I si_code
for a
The protection key which applied to this access is available via
.IR si_pkey .
.RE
-.PP
+.P
The following values can be placed in
.I si_code
for a
.BR BUS_MCEERR_AO " (since Linux 2.6.32)"
Hardware memory error detected in process but not consumed; action optional.
.RE
-.PP
+.P
The following values can be placed in
.I si_code
for a
.BR TRAP_HWBKPT " (since Linux 2.4, IA64 only)"
Hardware breakpoint/watchpoint.
.RE
-.PP
+.P
The following values can be placed in
.I si_code
for a
.BR CLD_CONTINUED " (since Linux 2.6.9)"
Stopped child has continued.
.RE
-.PP
+.P
The following values can be placed in
.I si_code
for a
.B POLL_HUP
Device disconnected.
.RE
-.PP
+.P
The following value can be placed in
.I si_code
for a
.BR sigaction ()
call would typically leave those bits set in
.IR oldact\->sa_flags .
-.PP
+.P
This means that support for new flags cannot be detected
simply by testing for a flag in
.IR sa_flags ,
.B SA_UNSUPPORTED
has been cleared before relying on the contents of
.IR sa_flags .
-.PP
+.P
Since the behavior of the signal handler cannot be guaranteed
unless the check passes,
it is wise to either block the affected signal
for example if the signal is synchronous, to issue the second
.BR sigaction ()
in the signal handler itself.
-.PP
+.P
In kernels that do not support a specific flag,
the kernel's behavior is as if the flag was not set,
even if the flag was set in
.IR act\->sa_flags .
-.PP
+.P
The flags
.BR SA_NOCLDSTOP ,
.BR SA_NOCLDWAIT ,
However, in general, programs may assume that these flags are supported,
since they have all been supported since Linux 2.6,
which was released in the year 2003.
-.PP
+.P
See EXAMPLES below for a demonstration of the use of
.BR SA_UNSUPPORTED .
.SH RETURN VALUE
See
.BR nptl (7)
for details.
-.PP
+.P
On architectures where the signal trampoline resides in the C library,
the glibc wrapper function for
.BR sigaction ()
field.
See
.BR sigreturn (2).
-.PP
+.P
The original Linux system call was named
.BR sigaction ().
However, with the addition of real-time signals in Linux 2.2,
.SH HISTORY
POSIX.1-2001, SVr4.
.\" SVr4 does not document the EINTR condition.
-.PP
+.P
POSIX.1-1990 disallowed setting the action for
.B SIGCHLD
to
signal and perform a
.BR wait (2)
or similar.
-.PP
+.P
POSIX.1-1990 specified only
.BR SA_NOCLDSTOP .
POSIX.1-2001 added
.I sa_flags
may be less portable in applications intended for older
UNIX implementations.
-.PP
+.P
The
.B SA_RESETHAND
flag is compatible with the SVr4 flag of the same name.
-.PP
+.P
The
.B SA_NODEFER
flag is compatible with the SVr4 flag of the same name under kernels
.BR execve (2),
the dispositions of handled signals are reset to the default;
the dispositions of ignored signals are left unchanged.
-.PP
+.P
According to POSIX, the behavior of a process is undefined after it
ignores a
.BR SIGFPE ,
(Also dividing the most negative integer by \-1 may generate
.BR SIGFPE .)
Ignoring this signal might lead to an endless loop.
-.PP
+.P
.BR 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.
-.PP
+.P
It is not possible to block
.BR SIGKILL " or " SIGSTOP
(by specifying them in
.IR sa_mask ).
Attempts to do so are silently ignored.
-.PP
+.P
See
.BR sigsetops (3)
for details on manipulating signal sets.
-.PP
+.P
See
.BR signal\-safety (7)
for a list of the async-signal-safe functions that can be
for all of the fields of the
.I siginfo_t
that are relevant for that signal.
-.PP
+.P
Up to and including Linux 2.6.13, specifying
.B SA_NODEFER
in
is determined to be supported, and
.B EXIT_FAILURE
otherwise.
-.PP
+.P
.\" SRC BEGIN (sigaction.c)
.EX
#include <signal.h>
.SH SYNOPSIS
.nf
.B #include <signal.h>
-.PP
+.P
.BI "int sigaltstack(const stack_t *_Nullable restrict " ss ,
.BI " stack_t *_Nullable restrict " old_ss );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR sigaltstack ():
.nf
_XOPEN_SOURCE >= 500
execution of a signal handler if the establishment of that handler (see
.BR sigaction (2))
requested it.
-.PP
+.P
The normal sequence of events for using an alternate signal stack
is the following:
.TP 3
inform the system that the signal handler should be executed
on the alternate signal stack by
specifying the \fBSA_ONSTACK\fP flag.
-.PP
+.P
The \fIss\fP argument is used to specify a new
alternate signal stack, while the \fIold_ss\fP 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.
-.PP
+.P
The
.I stack_t
type used to type the arguments of this function is defined as follows:
-.PP
+.P
.in +4n
.EX
typedef struct {
} stack_t;
.EE
.in
-.PP
+.P
To establish a new alternate signal stack,
the fields of this structure are set as follows:
.TP
to cover the usual size requirements for an alternate signal stack,
and the constant \fBMINSIGSTKSZ\fP defines the minimum
size required to execute a signal handler.
-.PP
+.P
To disable an existing stack, specify \fIss.ss_flags\fP
as \fBSS_DISABLE\fP.
In this case, the kernel ignores any other flags in
.I ss.ss_flags
and the remaining fields
in \fIss\fP.
-.PP
+.P
If \fIold_ss\fP is not NULL, then it is used to return information about
the alternate signal stack which was in effect prior to the
call to
.B SS_AUTODISARM
The alternate signal stack has been marked to be autodisarmed
as described above.
-.PP
+.P
By specifying
.I ss
as NULL, and
.TE
.SH STANDARDS
POSIX.1-2008.
-.PP
+.P
.B SS_AUTODISARM
is a Linux extension.
.SH HISTORY
.B SIGSEGV
cannot be invoked on the standard stack; if we wish to handle it,
we must use an alternate signal stack.
-.PP
+.P
Establishing an alternate signal stack is useful if a thread
expects that it may exhaust its standard stack.
This may occur, for example, because the stack grows so large
the thread a \fBSIGSEGV\fP signal.
In these circumstances the only way to catch this signal is
on an alternate signal stack.
-.PP
+.P
On most hardware architectures supported by Linux, stacks grow
downward.
.BR sigaltstack ()
automatically takes account
of the direction of stack growth.
-.PP
+.P
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
automatically extend the alternate signal stack.
Exceeding the allocated size of the alternate signal stack will
lead to unpredictable results.
-.PP
+.P
A successful call to
.BR execve (2)
removes any existing alternate
.BR CLONE_VFORK ,
in which case any alternate signal stack that was established in the parent
is disabled in the child process.
-.PP
+.P
.BR sigaltstack ()
supersedes the older
.BR sigstack ()
for the
.B SIGSEGV
signal:
-.PP
+.P
.in +4n
.EX
stack_t ss;
.SH SYNOPSIS
.nf
.B #include <signal.h>
-.PP
+.P
.B typedef void (*sighandler_t)(int);
-.PP
+.P
.BI "sighandler_t signal(int " signum ", sighandler_t " handler );
.fi
.SH DESCRIPTION
.BR sigaction (2)
instead.
See \fIPortability\fP below.
-.PP
+.P
.BR signal ()
sets the disposition of the signal
.I signum
.BR SIG_IGN ,
.BR SIG_DFL ,
or the address of a programmer-defined function (a "signal handler").
-.PP
+.P
If the signal
.I signum
is delivered to the process, then one of the following happens:
.IR signum .
If invocation of the handler caused the signal to be blocked,
then the signal is unblocked upon return from the handler.
-.PP
+.P
The signals
.B SIGKILL
and
Without use of such a type, the declaration of
.BR signal ()
is the somewhat harder to read:
-.PP
+.P
.in +4n
.EX
.BI "void ( *" signal "(int " signum ", void (*" handler ")(int)) ) (int);"
to establish a signal handler vary across systems
(and POSIX.1 explicitly permits this variation);
.B do not use it for this purpose.
-.PP
+.P
POSIX.1 solved the portability mess by specifying
.BR sigaction (2),
which provides explicit control of the semantics when a
C11, POSIX.1-2008.
.SH HISTORY
C89, POSIX.1-2001.
-.PP
+.P
In the original UNIX systems, when a handler that was established using
.BR signal ()
was invoked by the delivery of a signal,
This is equivalent to calling
.BR sigaction (2)
with the following flags:
-.PP
+.P
.in +4n
.EX
sa.sa_flags = SA_RESETHAND | SA_NODEFER;
.EE
.in
-.PP
+.P
System\ V also provides these semantics for
.BR 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.
-.PP
+.P
BSD improved on this situation, but unfortunately also
changed the semantics of the existing
.BR signal ()
The BSD semantics are equivalent to calling
.BR sigaction (2)
with the following flags:
-.PP
+.P
.in +4n
.EX
sa.sa_flags = SA_RESTART;
.EE
.in
-.PP
+.P
The situation on Linux is as follows:
.IP \[bu] 3
The kernel's
The effects of
.BR signal ()
in a multithreaded process are unspecified.
-.PP
+.P
According to POSIX, the behavior of a process is undefined after it
ignores a
.BR SIGFPE ,
(Also dividing the most negative integer by \-1 may generate
.BR SIGFPE .)
Ignoring this signal might lead to an endless loop.
-.PP
+.P
See
.BR sigaction (2)
for details on what happens when the disposition
.B SIGCHLD
is set to
.BR SIG_IGN .
-.PP
+.P
See
.BR signal\-safety (7)
for a list of the async-signal-safe functions that can be
.SH SYNOPSIS
.nf
.B #include <sys/signalfd.h>
-.PP
+.P
.BI "int signalfd(int " fd ", const sigset_t *" mask ", int " flags );
.fi
.SH DESCRIPTION
.BR poll (2),
and
.BR epoll (7).
-.PP
+.P
The
.I mask
argument specifies the set of signals that the caller
signals via a signalfd file descriptor;
these signals are silently ignored if specified in
.IR mask .
-.PP
+.P
If the
.I fd
argument is \-1,
then it must specify a valid existing signalfd file descriptor, and
.I mask
is used to replace the signal set associated with that file descriptor.
-.PP
+.P
Starting with Linux 2.6.27, the following values may be bitwise ORed in
.I flags
to change the behavior of
flag in
.BR open (2)
for reasons why this may be useful.
-.PP
+.P
Up to Linux 2.6.26, the
.I flags
argument is unused, and must be specified as zero.
-.PP
+.P
.BR signalfd ()
returns a file descriptor that supports the following operations:
.TP
structure(s) returned by
.BR read (2)s
from a signalfd file descriptor is as follows:
-.PP
+.P
.in +4n
.EX
struct signalfd_siginfo {
};
.EE
.in
-.PP
+.P
Each of the fields in this structure
is analogous to the similarly named field in the
.I siginfo_t
.BR signalfd ()
wrapper function does not include this argument,
since it provides the required value for the underlying system call.
-.PP
+.P
There are two underlying Linux system calls:
.BR signalfd ()
and the more recent
.I mask
of more than one of the file descriptors, then occurrences
of that signal can be read (once) from any one of the file descriptors.
-.PP
+.P
Attempts to include
.B SIGKILL
and
in
.I mask
are silently ignored.
-.PP
+.P
The signal mask employed by a signalfd file descriptor can be viewed
via the entry for the corresponding file descriptor in the process's
.IR /proc/ pid /fdinfo
.B SIGFPE
signal that results from an arithmetic error.
Such signals can be caught only via signal handler.
-.PP
+.P
As described above,
in normal usage one blocks the signals that will be accepted via
.BR signalfd ().
.B SIGQUIT
signal.
The following shell session demonstrates the use of the program:
-.PP
+.P
.in +4n
.EX
.RB "$" " ./signalfd_demo"
.SH SYNOPSIS
.nf
.B #include <signal.h>
-.PP
+.P
.BI "int sigpending(sigset_t *" set );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR sigpending ():
.nf
_POSIX_C_SOURCE
See
.BR sigsetops (3)
for details on manipulating signal sets.
-.PP
+.P
If a signal is both blocked and has a disposition of "ignored", it is
.I not
added to the mask of pending signals when generated.
-.PP
+.P
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
.BR signal (7).
-.PP
+.P
A child created via
.BR fork (2)
initially has an empty pending signal set;
.RI ( libc ", " \-lc )
.SH SYNOPSIS
.B #include <signal.h>
-.PP
+.P
.nf
/* Prototype for the glibc wrapper function */
.BI "int sigprocmask(int " how ", const sigset_t *_Nullable restrict " set ,
.BI " sigset_t *_Nullable restrict " oldset );
-.PP
+.P
.BR "#include <signal.h>" " /* Definition of " SIG_* " constants */"
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
-.PP
+.P
/* Prototype for the underlying system call */
.BI "int syscall(SYS_rt_sigprocmask, int " how ,
.BI " const kernel_sigset_t *_Nullable " set ,
.BI " kernel_sigset_t *_Nullable " oldset ,
.BI " size_t " sigsetsize );
-.PP
+.P
/* Prototype for the legacy system call */
.BI "[[deprecated]] int syscall(SYS_sigprocmask, int " how ,
.BI " const old_kernel_sigset_t *_Nullable " set ,
.BI " old_kernel_sigset_t *_Nullable " oldset );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR sigprocmask ():
.nf
_POSIX_C_SOURCE
(see also
.BR signal (7)
for more details).
-.PP
+.P
The behavior of the call is dependent on the value of
.IR how ,
as follows.
.B SIG_SETMASK
The set of blocked signals is set to the argument
.IR set .
-.PP
+.P
If
.I oldset
is non-NULL, the previous value of the signal mask is stored in
.IR oldset .
-.PP
+.P
If
.I set
is NULL, then the signal mask is unchanged (i.e.,
but the current value of the signal mask is nevertheless returned in
.I oldset
(if it is not NULL).
-.PP
+.P
A set of functions for modifying and inspecting variables of type
.I sigset_t
("signal sets") is described in
.BR sigsetops (3).
-.PP
+.P
The use of
.BR sigprocmask ()
is unspecified in a multithreaded process; see
(it is nevertheless named
.I sigset_t
in the kernel sources).
-.PP
+.P
The glibc wrapper function for
.BR sigprocmask ()
silently ignores attempts to block the two real-time signals that
See
.BR nptl (7)
for details.
-.PP
+.P
The original Linux system call was named
.BR sigprocmask ().
However, with the addition of real-time signals in Linux 2.2,
.IR sizeof(kernel_sigset_t) ).
.\" sizeof(kernel_sigset_t) == _NSIG / 8,
.\" which equals to 8 on most architectures, but e.g. on MIPS it's 16.
-.PP
+.P
The glibc
.BR sigprocmask ()
wrapper function hides these details from us, transparently calling
It is not possible to block
.BR SIGKILL " or " SIGSTOP .
Attempts to do so are silently ignored.
-.PP
+.P
Each of the threads in a process has its own signal mask.
-.PP
+.P
A child created via
.BR fork (2)
inherits a copy of its parent's signal mask;
the signal mask is preserved across
.BR execve (2).
-.PP
+.P
If
.BR SIGBUS ,
.BR SIGFPE ,
.BR sigqueue (3),
or
.BR raise (3).
-.PP
+.P
See
.BR sigsetops (3)
for details on manipulating signal sets.
-.PP
+.P
Note that it is permissible (although not very useful) to specify both
.I set
and
saves various pieces of process context
(processor status word, registers, signal mask, and signal stack settings).
.\" See arch/x86/kernel/signal.c::__setup_frame() [in Linux 3.17 source code]
-.PP
+.P
The kernel also arranges that, during the transition back to user mode,
the signal handler is called, and that, upon return from the handler,
control passes to a piece of user-space code commonly called
the "signal trampoline".
The signal trampoline code in turn calls
.BR sigreturn ().
-.PP
+.P
This
.BR sigreturn ()
call undoes everything that was
takes no arguments, since all of the information that it requires
is available in the stack frame that was previously created by the
kernel on the user-space stack.)
-.PP
+.P
Once upon a time, UNIX systems placed the signal trampoline code
onto the user stack.
Nowadays, pages of the user stack are protected so as to
flag in the
.I sa_flags
field.
-.PP
+.P
The saved process context information is placed in a
.I ucontext_t
structure (see
with the
.B SA_SIGINFO
flag.
-.PP
+.P
On some other UNIX systems,
the operation of the signal trampoline differs a little.
In particular, on some systems, upon transitioning back to user mode,
.SH SYNOPSIS
.nf
.B #include <signal.h>
-.PP
+.P
.BI "int sigsuspend(const sigset_t *" mask );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR sigsuspend ():
.nf
_POSIX_C_SOURCE
.I mask
and then suspends the thread until delivery of a signal whose
action is to invoke a signal handler or to terminate a process.
-.PP
+.P
If the signal terminates the process, then
.BR sigsuspend ()
does not return.
returns after the signal handler returns,
and the signal mask is restored to the state before the call to
.BR sigsuspend ().
-.PP
+.P
It is not possible to block
.B SIGKILL
or
(in the
.I oldset
argument).
-.PP
+.P
See
.BR sigsetops (3)
for details on manipulating signal sets.
.SH SYNOPSIS
.nf
.B #include <signal.h>
-.PP
+.P
.BI "int sigwaitinfo(const sigset_t *restrict " set ,
.BI " siginfo_t *_Nullable restrict " info );
.BI "int sigtimedwait(const sigset_t *restrict " set ,
.BI " siginfo_t *_Nullable restrict " info ,
.BI " const struct timespec *restrict " timeout );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR sigwaitinfo (),
.BR sigtimedwait ():
.nf
is already pending for the calling thread,
.BR sigwaitinfo ()
will return immediately.)
-.PP
+.P
.BR sigwaitinfo ()
removes the signal from the set of pending
signals and returns the signal number as its function result.
(see
.BR sigaction (2))
containing information about the signal.
-.PP
+.P
If multiple signals in
.I set
are pending for the caller, the signal that is retrieved by
is determined according to the usual ordering rules; see
.BR signal (7)
for further details.
-.PP
+.P
.BR sigtimedwait ()
operates in exactly the same way as
.BR sigwaitinfo ()
This argument is a
.BR timespec (3)
structure.
-.PP
+.P
If both fields of this structure are specified as 0, a poll is performed:
.BR sigtimedwait ()
returns immediately, either with information about a signal that
.BR sigwaitinfo ()
is a library function implemented on top of
.BR sigtimedwait ().
-.PP
+.P
The glibc wrapper functions for
.BR sigwaitinfo ()
and
See
.BR nptl (7)
for details.
-.PP
+.P
The original Linux system call was named
.BR sigtimedwait ().
However, with the addition of real-time signals in Linux 2.2,
.BR sigwaitinfo ()
or
.BR sigtimedwait ()).
-.PP
+.P
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
.BR signal (7)).
-.PP
+.P
Attempts to wait for
.B SIGKILL
and
.B SIGSTOP
are silently ignored.
-.PP
+.P
If multiple threads of a process are blocked
waiting for the same signal(s) in
.BR sigwaitinfo ()
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.
-.PP
+.P
.BR sigwaitinfo ()
or
.BR sigtimedwait (),
.B SIGFPE
signal that results from an arithmetic error.
Such signals can be caught only via signal handler.
-.PP
+.P
POSIX leaves the meaning of a NULL value for the
.I timeout
argument of
.SH SYNOPSIS
.nf
.B #include <sys/socket.h>
-.PP
+.P
.BI "int socket(int " domain ", int " type ", int " protocol );
.fi
.SH DESCRIPTION
that refers to that endpoint.
The file descriptor returned by a successful call will be
the lowest-numbered file descriptor not currently open for the process.
-.PP
+.P
The
.I domain
argument specifies a communication domain; this selects the protocol
XDP (express data path) interface
T}
.TE
-.PP
+.P
Further details of the above address families,
as well as information on several other address families, can be found in
.BR address_families (7).
-.PP
+.P
The socket has the indicated
.IR type ,
which specifies the communication semantics.
Obsolete and should not be used in new programs;
see
.BR packet (7).
-.PP
+.P
Some socket types may not be implemented by all protocol families.
-.PP
+.P
Since Linux 2.6.27, the
.I type
argument serves a second purpose:
flag in
.BR open (2)
for reasons why this may be useful.
-.PP
+.P
The
.I protocol
specifies a particular protocol to be used with the socket.
See
.BR getprotoent (3)
on how to map protocol name strings to protocol numbers.
-.PP
+.P
Sockets of type
.B SOCK_STREAM
are full-duplex byte streams.
.BR send (2)
and received as described in
.BR recv (2).
-.PP
+.P
The communications protocols which implement a
.B SOCK_STREAM
ensure that data is not lost or duplicated.
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.
-.PP
+.P
.B SOCK_DGRAM
and
.B SOCK_RAW
Datagrams are generally received with
.BR recvfrom (2),
which returns the next datagram along with the address of its sender.
-.PP
+.P
.B SOCK_PACKET
is an obsolete socket type to receive raw packets directly from the
device driver.
Use
.BR packet (7)
instead.
-.PP
+.P
An
.BR fcntl (2)
.B F_SETOWN
or
.B SIOCSPGRP
argument.
-.PP
+.P
When the network signals an error condition to the protocol module (e.g.,
using an 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
.B IP_RECVERR
in
.BR ip (7).
-.PP
+.P
The operation of sockets is controlled by socket level
.IR options .
These options are defined in
.B EPROTONOSUPPORT
The protocol type or the specified protocol is not
supported within this domain.
-.PP
+.P
Other errors may be generated by the underlying protocol modules.
.SH STANDARDS
POSIX.1-2008.
-.PP
+.P
.B SOCK_NONBLOCK
and
.B SOCK_CLOEXEC
are Linux-specific.
.SH HISTORY
POSIX.1-2001, 4.4BSD.
-.PP
+.P
.BR 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).
-.PP
+.P
The manifest constants used under 4.x BSD for protocol families
are
.BR PF_UNIX ,
.BR tcp (7),
.BR udp (7),
.BR unix (7)
-.PP
+.P
\[lq]An Introductory 4.3BSD Interprocess Communication Tutorial\[rq]
and
\[lq]BSD Interprocess Communication Tutorial\[rq],
.BR "#include <linux/net.h>" " /* Definition of " SYS_* " constants */"
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_socketcall " */"
.B #include <unistd.h>
-.PP
+.P
.BI "int syscall(SYS_socketcall, int " call ", unsigned long *" args );
.fi
-.PP
+.P
.IR Note :
glibc provides no wrapper for
.BR socketcall (),
.I args
points to a block containing the actual arguments,
which are passed through to the appropriate call.
-.PP
+.P
User programs should call the appropriate functions by their usual names.
Only standard library implementors and kernel hackers need to know about
.BR socketcall ().
-.PP
+.P
.TS
tab(:);
l l.
and so on really are implemented as separate system calls.
.SH STANDARDS
Linux.
-.PP
+.P
On x86-32,
.BR socketcall ()
was historically the only entry point for the sockets API.
.SH SYNOPSIS
.nf
.B #include <sys/socket.h>
-.PP
+.P
.BI "int socketpair(int " domain ", int " type ", int " protocol \
", int " sv [2]);
.fi
.IR protocol .
For further details of these arguments, see
.BR socket (2).
-.PP
+.P
The file descriptors used in referencing the new sockets are returned in
.I sv[0]
and
is set to indicate the error, and
.I sv
is left unchanged
-.PP
+.P
On Linux (and other systems),
.BR socketpair ()
does not modify
POSIX.1-2008.
.SH HISTORY
POSIX.1-2001, 4.4BSD.
-.PP
+.P
.BR socketpair ()
first appeared in 4.2BSD.
It is generally portable to/from
non-BSD systems supporting clones of the BSD socket layer (including
System\ V variants).
-.PP
+.P
Since Linux 2.6.27,
.BR socketpair ()
supports the
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #define _FILE_OFFSET_BITS 64
.B #include <fcntl.h>
-.PP
+.P
.BI "ssize_t splice(int " fd_in ", off_t *_Nullable " off_in ,
.BI " int " fd_out ", off_t *_Nullable " off_out ,
.BI " size_t " len ", unsigned int " flags );
to the file descriptor
.IR fd_out ,
where one of the file descriptors must refer to a pipe.
-.PP
+.P
The following semantics apply for
.I fd_in
and
in this case, the file offset of
.I fd_in
is not changed.
-.PP
+.P
Analogous statements apply for
.I fd_out
and
.IR off_out .
-.PP
+.P
The
.I flags
argument is a bit mask that is composed by ORing together
.BR splice ()
returns the number of bytes
spliced to or from the pipe.
-.PP
+.P
A return value of 0 means end of input.
If
.I fd_in
refers to a pipe, then this 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.
-.PP
+.P
On error,
.BR splice ()
returns \-1 and
.SH HISTORY
Linux 2.6.17,
glibc 2.5.
-.PP
+.P
In Linux 2.6.30 and earlier,
exactly one of
.I fd_in
.TP
.BR vmsplice (2)
"copies" data from user space into the buffer.
-.PP
+.P
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 data and choose to forward it to two or more different
.\" users - for things like logging etc.).
.\"
-.PP
+.P
.B _FILE_OFFSET_BITS
should be defined to be 64 in code that uses non-null
.I off_in
.BR "#include <sys/spu.h>" " /* Definition of " SPU_* " constants */"
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "int syscall(SYS_spu_create, const char *" pathname \
", unsigned int " flags ,
.BI " mode_t " mode ", int " neighbor_fd );
.fi
-.PP
+.P
.IR Note :
glibc provides no wrapper for
.BR spu_create (),
.I pathname
and it is populated with the files described in
.BR spufs (7).
-.PP
+.P
When a context is created,
the returned file descriptor can only be passed to
.BR spu_run (2),
this usually occurs when the file descriptor returned by
.BR spu_create ()
is closed.
-.PP
+.P
The
.I mode
argument (minus any bits set in the process's
for a full list of the possible
.I mode
values.
-.PP
+.P
The
.I neighbor_fd
is used only when the
.B SPU_CREATE_AFFINITY_SPU
flag is specified; see below.
-.PP
+.P
The
.I flags
argument can be zero or any bitwise OR-ed
Linux on PowerPC.
.SH HISTORY
Linux 2.6.16.
-.PP
+.P
Prior to the addition of the
.B SPU_CREATE_AFFINITY_SPU
flag in Linux 2.6.23, the
.BR "#include <sys/spu.h>" " /* Definition of " SPU_* " constants */"
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "int syscall(SYS_spu_run, int " fd ", uint32_t *" npc \
", uint32_t *" event );
.fi
-.PP
+.P
.IR Note :
glibc provides no wrapper for
.BR spu_run (),
When the context gets scheduled to a physical SPU,
it starts execution at the instruction pointer passed in
.IR npc .
-.PP
+.P
Execution of SPU code happens synchronously, meaning that
.BR spu_run ()
blocks while the SPU is still running.
main CPU or other SPUs, a new thread of execution must be created
first (e.g., using
.BR pthread_create (3)).
-.PP
+.P
When
.BR spu_run ()
returns, the current value of the SPU program counter is written to
can use the same
.I npc
pointer.
-.PP
+.P
The
.I event
argument provides a buffer for an extended status code.
flag, then this buffer is populated by the Linux kernel before
.BR spu_run ()
returns.
-.PP
+.P
The status code may be one (or more) of the following constants:
.TP
.B SPE_EVENT_DMA_ALIGNMENT
.TP
.B SPE_EVENT_SPE_ERROR
An illegal instruction was executed.
-.PP
+.P
NULL
is a valid value for the
.I event
On failure, it returns \-1 and sets
.I errno
is set to indicate the error.
-.PP
+.P
The
.I spu_status
register value is a bit mask of status codes and
.B stop-and-signal
instruction.
These bits are valid only if the 0x02 bit is set.
-.PP
+.P
If
.BR spu_run ()
has not returned an error, one or more bits among the lower eight
program with the
.BR spu_run ()
system call.
-.PP
+.P
.\" SRC BEGIN (spu_run.c)
.EX
#include <err.h>
.SH SYNOPSIS
.nf
.B #include <sys/stat.h>
-.PP
+.P
.BI "int stat(const char *restrict " pathname ,
.BI " struct stat *restrict " statbuf );
.BI "int fstat(int " fd ", struct stat *" statbuf );
.BI "int lstat(const char *restrict " pathname ,
.BI " struct stat *restrict " statbuf );
-.PP
+.P
.BR "#include <fcntl.h> " "/* Definition of " AT_* " constants */"
.B #include <sys/stat.h>
-.PP
+.P
.BI "int fstatat(int " dirfd ", const char *restrict " pathname ,
.BI " struct stat *restrict " statbuf ", int " flags );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR lstat ():
.nf
/* Since glibc 2.20 */ _DEFAULT_SOURCE
|| /* Since glibc 2.10: */ _POSIX_C_SOURCE >= 200112L
|| /* glibc 2.19 and earlier */ _BSD_SOURCE
.fi
-.PP
+.P
.BR fstatat ():
.nf
Since glibc 2.10:
(search) permission is required on all of the directories in
.I pathname
that lead to the file.
-.PP
+.P
.BR stat ()
and
.BR fstatat ()
the differences for
.BR fstatat ()
are described below.
-.PP
+.P
.BR lstat ()
is identical to
.BR stat (),
.I pathname
is a symbolic link, then it returns information about the link itself,
not the file that the link refers to.
-.PP
+.P
.BR fstat ()
is identical to
.BR stat (),
.I stat
structure (see
.BR stat (3type)).
-.PP
+.P
.\" Background: inode attributes are modified with i_mutex held, but
.\" read by stat() without taking the mutex.
.IR Note :
.BR lstat (),
and
.BR fstat ().
-.PP
+.P
If the pathname given in
.I pathname
is relative, then it is interpreted relative to the directory
and
.BR lstat ()
for a relative pathname).
-.PP
+.P
If
.I pathname
is relative and
.BR stat ()
and
.BR lstat ()).
-.PP
+.P
If
.I pathname
is absolute, then
.I dirfd
is ignored.
-.PP
+.P
.I flags
can either be 0, or include one or more of the following flags ORed:
.TP
.BR fstatat ()
dereferences symbolic links, like
.BR stat ().)
-.PP
+.P
See
.BR openat (2)
for an explanation of the need for
POSIX.1-2008.
Linux 2.6.16,
glibc 2.4.
-.PP
+.P
According to POSIX.1-2001,
.BR lstat ()
on a symbolic link need return valid information only in the
.BR lstat ()
to return valid information in all fields except the mode bits in
.IR st_mode .
-.PP
+.P
Use of the
.I st_blocks
and
.BR fstat ()
and
.BR lstat ().
-.PP
+.P
The kernel-internal versions of the
.I stat
structure dealt with by the different versions are, respectively:
(Various padding bytes were eventually consumed in Linux 2.6,
with the advent of 32-bit device IDs and nanosecond components
for the timestamp fields.)
-.PP
+.P
The glibc
.BR stat ()
wrapper function hides these details from applications,
.\" interface, rather than the libc-kernel interface.
.\"
.\" (Note that the details depend on gcc being used as c compiler.)
-.PP
+.P
On modern 64-bit systems, life is simpler: there is a single
.BR stat ()
system call and the kernel deals with a
.I stat
structure that contains fields of a sufficient size.
-.PP
+.P
The underlying system call employed by the glibc
.BR fstatat ()
wrapper function is actually called
and displays selected fields in the returned
.I stat
structure.
-.PP
+.P
.\" SRC BEGIN (stat.c)
.EX
#include <stdint.h>
.SH SYNOPSIS
.nf
.BR "#include <sys/vfs.h> " "/* or <sys/statfs.h> */"
-.PP
+.P
.BI "int statfs(const char *" path ", struct statfs *" buf );
.BI "int fstatfs(int " fd ", struct statfs *" buf );
.fi
-.PP
+.P
Unless you need the
.I f_type
field, you should use the standard
is a pointer to a
.I statfs
structure defined approximately as follows:
-.PP
+.P
.in +4n
.EX
struct statfs {
};
.EE
.in
-.PP
+.P
The following filesystem types may appear in
.IR f_type :
-.PP
+.P
.in +4n
.EX
ADFS_SUPER_MAGIC 0xadf5
_XIAFS_SUPER_MAGIC 0x012fd16d /* Linux 2.0 and earlier */
.EE
.in
-.PP
+.P
Most of these MAGIC constants are defined in
.IR /usr/include/linux/magic.h ,
and some are hardcoded in kernel sources.
-.PP
+.P
The
.I f_flags
field is a bit mask indicating mount options for the filesystem.
.\" dab741e0e02bd3c4f5e2e97be74b39df2523fc6e
Symbolic links are not followed when resolving paths; see
.BR mount (2).
-.PP
+.P
Nobody knows what
.I f_fsid
is supposed to contain (but see below).
-.PP
+.P
Fields that are undefined for a particular filesystem are set to 0.
-.PP
+.P
.BR fstatfs ()
returns the same information about an open file referenced by descriptor
.IR fd .
.IR "struct { int val[2]; }" .
The same holds for FreeBSD, except that it uses the include file
.IR <sys/mount.h> .
-.PP
+.P
The general idea is that
.I f_fsid
contains some random stuff such that the pair
field to the superuser only (and zero it for unprivileged users),
because this field is used in the filehandle of the filesystem
when NFS-exported, and giving it out is a security concern.
-.PP
+.P
Under some operating systems, the
.I fsid
can be used as the second argument to the
.BR statfs ()
was inspired by the 4.4BSD one
(but they do not use the same structure).
-.PP
+.P
The original Linux
.BR statfs ()
and
and
.BR fstatfs ()
wrapper functions transparently deal with the kernel differences.
-.PP
+.P
LSB has deprecated the library calls
.BR statfs ()
and
Using
.I "unsigned\ int"
for such variables suffices on most systems.
-.PP
+.P
Some systems have only \fI<sys/vfs.h>\fP, other systems also have
\fI<sys/statfs.h>\fP, where the former includes the latter.
So it seems
.BR "#define _GNU_SOURCE " "/* See feature_test_macros(7) */"
.BR "#include <fcntl.h> " "/* Definition of " AT_* " constants */"
.B #include <sys/stat.h>
-.PP
+.P
.BI "int statx(int " dirfd ", const char *restrict " pathname ", int " flags ,
.BI " unsigned int " mask ", struct statx *restrict " statxbuf );
.fi
pointed to by
.IR statxbuf .
The returned buffer is a structure of the following type:
-.PP
+.P
.in +4n
.EX
struct statx {
};
.EE
.in
-.PP
+.P
The file timestamps are structures of the following type:
-.PP
+.P
.in +4n
.EX
struct statx_timestamp {
};
.EE
.in
-.PP
+.P
(Note that reserved space and padding is omitted.)
.SS
Invoking \fBstatx\fR():
execute (search) permission is required on all of the directories in
.I pathname
that lead to the file.
-.PP
+.P
.BR statx ()
uses
.IR pathname ,
(see below),
then the target file is the one referred to by the file descriptor
.IR dirfd .
-.PP
+.P
.I flags
can be used to influence a pathname-based lookup.
A value for
is a symbolic link, do not dereference it:
instead return information about the link itself, like
.BR lstat (2).
-.PP
+.P
.I flags
can also be used to control what sort of synchronization the kernel will do
when querying a file on a remote filesystem.
This may mean that the information returned is approximate, but,
on a network filesystem, it may not involve a round trip to the server - even
if no lease is held.
-.PP
+.P
The
.I mask
argument to
is used to tell the kernel which fields the caller is interested in.
.I mask
is an ORed combination of the following constants:
-.PP
+.P
.in +4n
.TS
lB l.
(since Linux 6.1; support varies by filesystem)
.TE
.in
-.PP
+.P
Note that, in general, the kernel does
.I not
reject values in
.I mask
argument and bits are set in it to indicate
which fields have been filled in.
-.PP
+.P
It should be noted that the kernel may return fields that weren't
requested and may fail to return fields that were requested,
depending on what the backing filesystem supports.
.I stx_mask
will not be equal
.IR mask .
-.PP
+.P
If a filesystem does not support a field or if it has
an unrepresentable value (for instance, a file with an exotic type),
then the mask bit corresponding to that field will be cleared in
even if the user asked for it and a dummy value will be filled in for
compatibility purposes if one is available (e.g., a dummy UID and GID may be
specified to mount under some circumstances).
-.PP
+.P
A filesystem may also fill in fields that the caller didn't ask for if it has
values for them available and the information is available at no extra cost.
If this happens, the corresponding bits will be set in
.IR stx_mask .
-.PP
+.P
.\" Background: inode attributes are modified with i_mutex held, but
.\" read by stat() without taking the mutex.
.IR Note :
.I stx_uid
together with the new
.IR stx_mode .
-.PP
+.P
Apart from
.I stx_mask
(which is described above), the fields in the
This will only be nonzero if
.I stx_dio_mem_align
is nonzero, and vice versa.
-.PP
+.P
For further information on the above fields, see
.BR inode (7).
.\"
.I stx_attributes_mask
correspond bit-by-bit to
.IR stx_attributes .
-.PP
+.P
The flags are as follows:
.TP
.B STATX_ATTR_COMPRESSED
.SH SYNOPSIS
.nf
.B #include <time.h>
-.PP
+.P
.BI "[[deprecated]] int stime(const time_t *" t );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR stime ():
.nf
Since glibc 2.19:
use
.BR clock_settime (2)
instead.
-.PP
+.P
.BR stime ()
sets the system's idea of the time and date.
The time, pointed
None.
.SH HISTORY
SVr4.
-.PP
+.P
Starting with glibc 2.31,
this function is no longer available to newly linked applications
and is no longer declared in
.nf
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "int syscall(SYS_subpage_prot, unsigned long " addr ", unsigned long " len ,
.BI " uint32_t *" map );
.fi
-.PP
+.P
.IR Note :
glibc provides no wrapper for
.BR subpage_prot (),
system call provides the facility to control the access
permissions on individual 4\ kB subpages on systems configured with
a page size of 64\ kB.
-.PP
+.P
The protection map is applied to the memory pages in the region starting at
.I addr
and continuing for
.I len
bytes.
Both of these arguments must be aligned to a 64-kB boundary.
-.PP
+.P
The protection map is specified in the buffer pointed to by
.IR map .
The map has 2 bits per 4\ kB subpage;
Linux.
.SH HISTORY
Linux 2.6.25 (PowerPC).
-.PP
+.P
The system call is provided only if the kernel is configured with
.BR CONFIG_PPC_64K_PAGES .
.SH NOTES
.SH SEE ALSO
.BR mprotect (2),
.BR syscall (2)
-.PP
+.P
.I Documentation/admin\-guide/mm/hugetlbpage.rst
in the Linux kernel source tree
.SH SYNOPSIS
.nf
.B #include <sys/swap.h>
-.PP
+.P
.BI "int swapon(const char *" path ", int " swapflags );
.BI "int swapoff(const char *" path );
.fi
.BR swapoff ()
stops swapping to the file or block device specified by
.IR path .
-.PP
+.P
If the
.B SWAP_FLAG_PREFER
flag is specified in the
The priority is encoded within
.I swapflags
as:
-.PP
+.P
.in +4n
.EX
.I "(prio << SWAP_FLAG_PRIO_SHIFT) & SWAP_FLAG_PRIO_MASK"
.EE
.in
-.PP
+.P
If the
.B SWAP_FLAG_DISCARD
flag is specified in the
(This may improve performance on some Solid State Devices,
but often it does not.)
See also NOTES.
-.PP
+.P
These functions may be used only by a privileged process (one having the
.B CAP_SYS_ADMIN
capability).
The default priority is low.
Within the low-priority areas,
newer areas are even lower priority than older areas.
-.PP
+.P
All priorities set with
.I swapflags
are high-priority, higher than default.
They may have any nonnegative value chosen by the caller.
Higher numbers mean higher priority.
-.PP
+.P
Swap pages are allocated from areas in priority order,
highest priority first.
For areas with different priorities,
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.
-.PP
+.P
As of Linux 1.3.6, the kernel usually follows these rules,
but there are exceptions.
.SH RETURN VALUE
.SH NOTES
The partition or path must be prepared with
.BR mkswap (8).
-.PP
+.P
There is an upper limit on the number of swap files that may be used,
defined by the kernel constant
.BR MAX_SWAPFILES .
if the kernel is built with the
.B CONFIG_DEVICE_PRIVATE
option.
-.PP
+.P
Discard of swap pages was introduced in Linux 2.6.29,
then made conditional
on the
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.BI "int symlink(const char *" target ", const char *" linkpath );
-.PP
+.P
.BR "#include <fcntl.h> " "/* Definition of " AT_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "int symlinkat(const char *" target ", int " newdirfd \
", const char *" linkpath );
-.PP
+.P
.fi
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR symlink ():
.nf
_XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 200112L
.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
|| /* glibc <= 2.19: */ _BSD_SOURCE
.fi
-.PP
+.P
.BR symlinkat ():
.nf
Since glibc 2.10:
.I linkpath
which contains the string
.IR target .
-.PP
+.P
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.
-.PP
+.P
Symbolic links may contain
.I ..
path components, which (if used at the start of the link) refer to the
parent directories of that in which the link resides.
-.PP
+.P
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.
-.PP
+.P
The permissions of a symbolic link are irrelevant; the ownership is
ignored when following the link
(except when the
the sticky bit
.RB ( S_ISVTX )
set.
-.PP
+.P
If
.I linkpath
exists, it will
system call operates in exactly the same way as
.BR symlink (),
except for the differences described here.
-.PP
+.P
If the pathname given in
.I linkpath
is relative, then it is interpreted relative to the directory
the calling process, as is done by
.BR symlink ()
for a relative pathname).
-.PP
+.P
If
.I linkpath
is relative and
is interpreted relative to the current working
directory of the calling process (like
.BR symlink ()).
-.PP
+.P
If
.I linkpath
is absolute, then
.I newdirfd
is ignored.
-.PP
+.P
See
.BR openat (2)
for an explanation of the need for
No checking of
.I target
is done.
-.PP
+.P
Deleting the name referred to by a symbolic link will actually delete the
file (unless it also has other hard links).
If this behavior is not desired, use
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.B void sync(void);
-.PP
+.P
.BI "int syncfs(int " fd );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR sync ():
.nf
_XOPEN_SOURCE >= 500
|| /* Since glibc 2.19: */ _DEFAULT_SOURCE
|| /* glibc <= 2.19: */ _BSD_SOURCE
.fi
-.PP
+.P
.BR syncfs ():
.nf
_GNU_SOURCE
.BR sync ()
causes all pending modifications to filesystem metadata and cached file
data to be written to the underlying filesystems.
-.PP
+.P
.BR syncfs ()
is like
.BR sync (),
.SH ERRORS
.BR sync ()
is always successful.
-.PP
+.P
.BR syncfs ()
can fail for at least the following reasons:
.TP
.BR syncfs ()
Linux 2.6.39,
glibc 2.14.
-.PP
+.P
Since glibc 2.2.2, the Linux prototype for
.BR sync ()
is as listed above,
it was "int sync(void)", and
.BR sync ()
always returned 0.
-.PP
+.P
In mainline kernel versions prior to Linux 5.8,
.BR syncfs ()
will fail only when passed a bad file descriptor
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #define _FILE_OFFSET_BITS 64
.B #include <fcntl.h>
-.PP
+.P
.BI "int sync_file_range(int " fd ", off_t " offset ", off_t " nbytes ,
.BI " unsigned int " flags );
.fi
file descriptor
.I fd
with disk.
-.PP
+.P
.I offset
is the starting byte of the file range to be synchronized.
.I nbytes
is rounded down to a page boundary;
.I (offset+nbytes\-1)
is rounded up to a page boundary.
-.PP
+.P
The
.I flags
bit-mask argument can include any of the following values:
.B SYNC_FILE_RANGE_WAIT_AFTER
Wait upon write-out of all pages in the range
after performing any write.
-.PP
+.P
Specifying
.I flags
as 0 is permitted, as a no-op.
I/O errors or
.B ENOSPC
conditions and will return these to the caller.
-.PP
+.P
Useful combinations of the
.I flags
bits are:
for details.)
Therefore, these architectures define a different
system call that orders the arguments suitably:
-.PP
+.P
.in +4n
.EX
.BI "int sync_file_range2(int " fd ", unsigned int " flags ,
.BI " off_t " offset ", off_t " nbytes );
.EE
.in
-.PP
+.P
The behavior of this system call is otherwise exactly the same as
.BR sync_file_range ().
.SH STANDARDS
.nf
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "long syscall(long " number ", ...);"
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR syscall ():
.nf
Since glibc 2.19:
.BR syscall ()
is useful, for example,
when invoking a system call that has no wrapper function in the C library.
-.PP
+.P
.BR syscall ()
saves CPU registers before making the system call,
restores the registers upon return from the system call,
and stores any error returned by the system call in
.BR errno (3).
-.PP
+.P
Symbolic constants for system call numbers can be found in the header file
.IR <sys/syscall.h> .
.SH RETURN VALUE
.TP
.B ENOSYS
The requested system call number is not implemented.
-.PP
+.P
Other errors are specific to the invoked system call.
.SH NOTES
.BR syscall ()
to make a system call,
the caller might need to handle architecture-dependent details;
this requirement is most commonly encountered on certain 32-bit architectures.
-.PP
+.P
For example, on the ARM architecture Embedded ABI (EABI), a
64-bit value (e.g.,
.IR "long long" )
.BR readahead (2)
system call would be invoked as follows on the ARM architecture with the EABI
in little endian mode:
-.PP
+.P
.in +4n
.EX
syscall(SYS_readahead, fd, 0,
count);
.EE
.in
-.PP
+.P
Since the offset argument is 64 bits, and the first argument
.RI ( fd )
is passed in
(the second argument of 0).
Care also must be taken so that the split follows endian conventions
(according to the C ABI for the platform).
-.PP
+.P
Similar issues can occur on MIPS with the O32 ABI,
on PowerPC and parisc with the 32-bit ABI, and on Xtensa.
.\" Mike Frysinger: this issue ends up forcing MIPS
.\" O32 to take 7 arguments to syscall()
-.PP
+.P
.\" See arch/parisc/kernel/sys_parisc.c.
Note that while the parisc C ABI also uses aligned register pairs,
it uses a shim layer to hide the issue from user space.
-.PP
+.P
The affected system calls are
.BR fadvise64_64 (2),
.BR ftruncate64 (2),
.BR sync_file_range (2),
and
.BR truncate64 (2).
-.PP
+.P
.\" You need to look up the syscalls directly in the kernel source to see if
.\" they should be in this list. For example, look at fs/read_write.c and
.\" the function signatures that do:
Every architecture has its own way of invoking and passing arguments to the
kernel.
The details for various architectures are listed in the two tables below.
-.PP
+.P
The first table lists the instruction used to transition to kernel mode
(which might not be the fastest or best way to transition to the kernel,
so you might have to refer to
x32 syscall rax rax rdx - 5
xtensa syscall a2 a2 - -
.TE
-.PP
+.P
Notes:
.IP \[bu] 3
On a few architectures,
.in
.ft P
\}
-.PP
+.P
The second table shows the registers used to pass the system call arguments.
.if t \{\
.ft CW
x32 rdi rsi rdx r10 r8 r9 -
xtensa a6 a3 a4 a5 a8 a9 -
.TE
-.PP
+.P
Notes:
.IP \[bu] 3
The mips/o32 system call convention passes
.in
.ft P
\}
-.PP
+.P
Note that these tables don't cover the entire calling convention\[em]some
architectures may indiscriminately clobber other registers not listed here.
.SH EXAMPLES
For example, glibc contains a function
.BR chdir ()
which invokes the underlying "chdir" system call.
-.PP
+.P
Often the glibc wrapper function is quite thin, doing little work
other than copying arguments to the right registers
before invoking the system call,
(to make it positive), copies it to
.IR errno ,
and returns \-1 to the caller of the wrapper.
-.PP
+.P
Sometimes, however, the wrapper function does some extra work
before invoking the system call.
For example, nowadays there are (for reasons described below) two
into a Linux 2.4.x release after Linux 2.4.15.
When this is so, the version where the system call appeared
in both of the major kernel series is listed.
-.PP
+.P
The list of system calls that are available as at Linux 5.14
(or in a few cases only on older kernels) is as follows:
.\"
.\" 5a0015d62668e64c8b6e02e360fbbea121bfd5e6
\fBxtensa\fP(2) 2.6.13 Xtensa only
.TE
-.PP
+.P
On many platforms, including x86-32, socket calls are all multiplexed
(via glibc wrapper functions) through
.BR socketcall (2)
and similarly System\ V IPC calls are multiplexed through
.BR ipc (2).
-.PP
+.P
Although slots are reserved for them in the system call table,
the following system calls are not implemented in the standard kernel:
.BR afs_syscall (2), \" __NR_afs_syscall is 53 on Linux 2.6.22/i386
.BR putpmsg (2)
calls are for kernels patched to support STREAMS,
and may never be in the standard kernel.
-.PP
+.P
There was briefly
.BR set_zone_reclaim (2),
added in Linux 2.6.13, and removed in Linux 2.6.16;
such as sparc, sparc64, and alpha,
there are many additional system calls; mips64 also contains a full
set of 32-bit system calls.
-.PP
+.P
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
.IR __NR_mmap2 .
s390x is the only 64-bit architecture that has
.IR old_mmap ().
-.\" .PP
+.\" .P
.\" Two system call numbers,
.\" .IR __NR__llseek
.\" and
.nf
.B #include <unistd.h>
.B #include <linux/sysctl.h>
-.PP
+.P
.BI "[[deprecated]] int _sysctl(struct __sysctl_args *" args );
.fi
.SH DESCRIPTION
.B This system call no longer exists on current kernels!
See NOTES.
-.PP
+.P
The
.BR _sysctl ()
call reads and/or writes kernel parameters.
For example, the hostname,
or the maximum number of open files.
The argument has the form
-.PP
+.P
.in +4n
.EX
struct __sysctl_args {
};
.EE
.in
-.PP
+.P
This call does a search in a tree structure, possibly resembling
a directory tree under
.IR /proc/sys ,
.SH HISTORY
Linux 1.3.57.
Removed in Linux 5.5, glibc 2.32.
-.PP
+.P
It originated in
4.4BSD.
Only Linux has the
Use the
.I /proc/sys
interface instead.
-.PP
+.P
Note that on older kernels where this system call still exists,
it is available only if the kernel was configured with the
.B CONFIG_SYSCTL_SYSCALL
.SH BUGS
The object names vary between kernel versions,
making this system call worthless for applications.
-.PP
+.P
Not all available objects are properly documented.
-.PP
+.P
It is not yet possible to change operating system by writing to
.IR /proc/sys/kernel/ostype .
.SH EXAMPLES
.IR /sys ,
see
.BR sysfs (5).
-.PP
+.P
The (obsolete)
.BR sysfs ()
system call returns information about the filesystem types
.B 3
Return the total number of filesystem types currently present in the
kernel.
-.PP
+.P
The numbering of the filesystem type indexes begins with zero.
.SH RETURN VALUE
On success,
None.
.SH HISTORY
SVr4.
-.PP
+.P
This System-V derived system call is obsolete; don't use it.
On systems with
.IR /proc ,
.SH SYNOPSIS
.nf
.B #include <sys/sysinfo.h>
-.PP
+.P
.BI "int sysinfo(struct sysinfo *" info );
.fi
.SH DESCRIPTION
.BR sysinfo ()
returns certain statistics on memory and swap usage,
as well as the load average.
-.PP
+.P
Until Linux 2.3.16,
.BR sysinfo ()
returned information in the following structure:
-.PP
+.P
.in +4n
.EX
struct sysinfo {
};
.EE
.in
-.PP
+.P
In the above structure, the sizes of the memory and swap fields
are given in bytes.
-.PP
+.P
Since Linux 2.3.23 (i386) and Linux 2.3.48
(all architectures) the structure is:
-.PP
+.P
.in +4n
.EX
struct sysinfo {
};
.EE
.in
-.PP
+.P
In the above structure,
sizes of the memory and swap fields are given as multiples of
.I mem_unit
.BR "#include <sys/klog.h>" " /* Definition of " SYSLOG_* " constants */"
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "int syscall(SYS_syslog, int " type ", char *" bufp ", int " len );
-.PP
+.P
/* The glibc interface */
.B #include <sys/klog.h>
-.PP
+.P
.BI "int klogctl(int " type ", char *" bufp ", int " len );
.fi
.SH DESCRIPTION
see
.BR syslog (3)
for details.
-.PP
+.P
This page describes the kernel
.BR syslog ()
system call, which is used to control the kernel
and
.I len
arguments are ignored.
-.PP
+.P
All commands except 3 and 10 require privilege.
In Linux kernels before Linux 2.6.37,
command types 3 and 10 are allowed to unprivileged processes;
KERN_INFO 6 Informational
KERN_DEBUG 7 Debug-level messages
.TE
-.PP
+.P
The kernel
.I printk()
routine will print a message on the
.BR syslog ()
returns the total size of the kernel log buffer.
For other values of \fItype\fP, 0 is returned on success.
-.PP
+.P
In case of error, \-1 is returned,
and \fIerrno\fP is set to indicate the error.
.SH ERRORS
.nf
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <fcntl.h>
-.PP
+.P
.BI "ssize_t tee(int " fd_in ", int " fd_out ", size_t " len \
", unsigned int " flags );
.fi
.IR fd_in ;
therefore, that data can be copied by a subsequent
.BR splice (2).
-.PP
+.P
.I flags
is a bit mask that is composed by ORing together
zero or more of the following values:
and it would not make sense to block, because there are no
writers connected to the write end of the pipe referred to by
.IR fd_in .
-.PP
+.P
On error,
.BR tee ()
returns \-1 and
.BR tee ()
system call.
Here is an example of its use:
-.PP
+.P
.in +4n
.EX
$ \fBdate | ./a.out out.log | cat\fP
.SH SYNOPSIS
.nf
.B #include <time.h>
-.PP
+.P
.BI "time_t time(time_t *_Nullable " tloc );
.fi
.SH DESCRIPTION
.BR time ()
returns the time as the number of seconds since the
Epoch, 1970-01-01 00:00:00 +0000 (UTC).
-.PP
+.P
If
.I tloc
is non-NULL,
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.
-.PP
+.P
On Linux, a call to
.BR time ()
with
the Epoch, so the C library wrapper function never sets
.I errno
as a result of this call.
-.PP
+.P
The
.I tloc
argument is obsolescent and should always be NULL in new code.
.nf
.BR "#include <signal.h>" " /* Definition of " SIGEV_* " constants */"
.B #include <time.h>
-.PP
+.P
.BI "int timer_create(clockid_t " clockid ,
.BI " struct sigevent *_Nullable restrict " sevp ,
.BI " timer_t *restrict " timerid );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR timer_create ():
.nf
_POSIX_C_SOURCE >= 199309L
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.
-.PP
+.P
The
.I clockid
argument specifies the clock that the new timer uses to measure time.
.TP
.BR CLOCK_TAI " (since Linux 3.10)"
A system-wide clock derived from wall-clock time but ignoring leap seconds.
-.PP
+.P
See
.BR clock_getres (2)
for some further details on the above clocks.
-.PP
+.P
As well as the above values,
.I clockid
can be specified as the
.BR clock_getcpuclockid (3)
or
.BR pthread_getcpuclockid (3).
-.PP
+.P
The
.I sevp
argument points to a
should be notified when the timer expires.
For the definition and general details of this structure, see
.BR sigevent (3type).
-.PP
+.P
The
.I sevp.sigev_notify
field can have the following values:
or
.BR gettid (2).
This flag is intended only for use by threading libraries.
-.PP
+.P
Specifying
.I sevp
as NULL is equivalent to specifying a pointer to a
.SH HISTORY
Linux 2.6.
POSIX.1-2001.
-.PP
+.P
Prior to Linux 2.6,
glibc provided an incomplete user-space implementation
.RB ( CLOCK_REALTIME
.SH NOTES
A program may create multiple interval timers using
.BR timer_create ().
-.PP
+.P
Timers are not inherited by the child of a
.BR fork (2),
and are disarmed and deleted during an
.BR execve (2).
-.PP
+.P
The kernel preallocates a "queued real-time signal"
for each timer created using
.BR timer_create ().
.B RLIMIT_SIGPENDING
resource limit (see
.BR setrlimit (2)).
-.PP
+.P
The timers created by
.BR timer_create ()
are commonly known as "POSIX (interval) timers".
.TP
.BR timer_delete (2)
Disarm and delete a timer.
-.PP
+.P
Since Linux 3.10, the
.IR /proc/ pid /timers
file can be used to list the POSIX timers for the process with PID
See
.BR proc (5)
for further information.
-.PP
+.P
Since Linux 4.10,
.\" baa73d9e478ff32d62f3f9422822b59dd9a95a21
support for POSIX timers is a configurable option that is enabled by default.
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.
-.PP
+.P
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.
-.PP
+.P
.in +4n
.EX
$ \fB./a.out 1 100\fP
.SH SYNOPSIS
.nf
.B #include <time.h>
-.PP
+.P
.BI "int timer_delete(timer_t " timerid );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR timer_delete ():
.nf
_POSIX_C_SOURCE >= 199309L
.SH SYNOPSIS
.nf
.B #include <time.h>
-.PP
+.P
.BI "int timer_getoverrun(timer_t " timerid );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR timer_getoverrun ():
.nf
_POSIX_C_SOURCE >= 199309L
.RB ( SIGEV_SIGNAL ),
and via threads
.RB ( SIGEV_THREAD ).
-.PP
+.P
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
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.
-.PP
+.P
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
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.
-.PP
+.P
POSIX.1 discusses timer overruns only in the context of
timer notifications using signals.
.\" FIXME . Austin bug filed, 11 Feb 09
.SH SYNOPSIS
.nf
.B #include <time.h>
-.PP
+.P
.BI "int timer_gettime(timer_t " timerid ", struct itimerspec *" curr_value );
.BI "int timer_settime(timer_t " timerid ", int " flags ,
.BI " const struct itimerspec *restrict " new_value ,
.BI " struct itimerspec *_Nullable restrict " old_value );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR timer_settime (),
.BR timer_gettime ():
.nf
.I itimerspec
structure is described in
.BR itimerspec (3type).
-.PP
+.P
Each of the substructures of the
.I itimerspec
structure is a
These time values are measured according to the clock
that was specified when the timer was created by
.BR timer_create (2).
-.PP
+.P
If
.I new_value\->it_value
specifies a nonzero value (i.e., either subfield is nonzero), then
specifies a zero value
(i.e., both subfields are zero),
then the timer is disarmed.
-.PP
+.P
The
.I new_value\->it_interval
field specifies the period of the timer, in seconds and nanoseconds.
specifies a zero value,
then the timer expires just once, at the time specified by
.IR it_value .
-.PP
+.P
By default, the initial expiration time specified in
.I new_value\->it_value
is interpreted relative to the current time on the timer's
.BR timer_getoverrun (2))
will be set correctly.
.\" By experiment: the overrun count is set correctly, for CLOCK_REALTIME.
-.PP
+.P
If the value of the
.B CLOCK_REALTIME
clock is adjusted while an absolute timer based on that clock is armed,
clock have no effect on relative timers based on that clock.
.\" Similar remarks might apply with respect to process and thread CPU time
.\" clocks, but these clocks are not currently (2.6.28) settable on Linux.
-.PP
+.P
If
.I old_value
is not NULL, then it points to a buffer
and the amount of time until the timer
would previously have next expired (in
.IR old_value\->it_value ).
-.PP
+.P
.BR timer_gettime ()
returns the time until next expiration, and the interval,
for the timer specified by
.I timerid
is invalid.
.\" FIXME . eventually: invalid value in flags
-.PP
+.P
.BR timer_settime ()
may fail with the following errors:
.TP
.SH SYNOPSIS
.nf
.B #include <sys/timerfd.h>
-.PP
+.P
.BI "int timerfd_create(int " clockid ", int " flags );
-.PP
+.P
.BI "int timerfd_settime(int " fd ", int " flags ,
.BI " const struct itimerspec *" new_value ,
.BI " struct itimerspec *_Nullable " old_value );
.BR poll (2),
and
.BR epoll (7).
-.PP
+.P
The use of these three system calls is analogous to the use of
.BR timer_create (2),
.BR timer_settime (2),
The caller must have the
.B CAP_WAKE_ALARM
capability in order to set a timer against this clock.
-.PP
+.P
See
.BR clock_getres (2)
for some further details on the above clocks.
-.PP
+.P
The current value of each of these clocks can be retrieved using
.BR clock_gettime (2).
-.PP
+.P
Starting with Linux 2.6.27, the following values may be bitwise ORed in
.I flags
to change the behavior of
flag in
.BR open (2)
for reasons why this may be useful.
-.PP
+.P
In Linux versions up to and including 2.6.26,
.I flags
must be specified as zero.
arms (starts) or disarms (stops)
the timer referred to by the file descriptor
.IR fd .
-.PP
+.P
The
.I new_value
argument specifies the initial expiration and interval for the timer.
.I itimerspec
structure used for this argument is described in
.BR itimerspec (3type).
-.PP
+.P
.I new_value.it_value
specifies the initial expiration of the timer,
in seconds and nanoseconds.
Setting both fields of
.I new_value.it_value
to zero disarms the timer.
-.PP
+.P
Setting one or both fields of
.I new_value.it_interval
to nonzero values specifies the period, in seconds and nanoseconds,
.I new_value.it_interval
are zero, the timer expires just once, at the time specified by
.IR new_value.it_value .
-.PP
+.P
By default,
the initial expiration time specified in
.I new_value
An absolute timeout can be selected via the
.I flags
argument.
-.PP
+.P
The
.I flags
argument is a bit mask that can include the following values:
.BR read (2)
from the file descriptor will fail with the error
.BR ECANCELED .
-.PP
+.P
If the
.I old_value
argument is not NULL, then the
structure that contains the current setting of the timer
referred to by the file descriptor
.IR fd .
-.PP
+.P
The
.I it_value
field returns the amount of time
This field always contains a relative value, regardless of whether the
.B TFD_TIMER_ABSTIME
flag was specified when setting the timer.
-.PP
+.P
The
.I it_interval
field returns the interval of the timer.
On error, \-1 is returned and
.I errno
is set to indicate the error.
-.PP
+.P
.BR timerfd_settime ()
and
.BR timerfd_gettime ()
but the caller did not have the
.B CAP_WAKE_ALARM
capability.
-.PP
+.P
.BR timerfd_settime ()
and
.BR timerfd_gettime ()
.B EINVAL
.I fd
is not a valid timerfd file descriptor.
-.PP
+.P
.BR timerfd_settime ()
can also fail with the following errors:
.TP
to rearm the timer (without first doing a
.BR read (2)
on the file descriptor).
-.PP
+.P
In this case the following occurs:
.IP \[bu] 3
The
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.
-.PP
+.P
The following shell session demonstrates the use of the program:
-.PP
+.P
.in +4n
.EX
.RB "$" " a.out 3 1 100"
.SH SYNOPSIS
.nf
.B #include <sys/times.h>
-.PP
+.P
.BI "clock_t times(struct tms *" buf );
.fi
.SH DESCRIPTION
.I struct tms
is as defined in
.IR <sys/times.h> :
-.PP
+.P
.in +4n
.EX
struct tms {
};
.EE
.in
-.PP
+.P
The
.I tms_utime
field contains the CPU time spent executing instructions
.I tms_stime
field contains the CPU time spent executing inside the kernel
while performing tasks on behalf of the calling process.
-.PP
+.P
The
.I tms_cutime
field contains the sum of the
and
.I tms_cstime
values for all waited-for terminated children.
-.PP
+.P
Times for terminated children (and their descendants)
are added in at the moment
.BR wait (2)
In particular,
times of grandchildren
that the children did not wait for are never seen.
-.PP
+.P
All times reported are in clock ticks.
.SH RETURN VALUE
.BR times ()
POSIX.1-2001,
SVr4,
4.3BSD.
-.PP
+.P
In POSIX.1-1996 the symbol \fBCLK_TCK\fP (defined in
.IR <time.h> )
is mentioned as obsolescent.
It is obsolete now.
-.PP
+.P
Before Linux 2.6.9,
if the disposition of
.B SIGCHLD
.\" See the description of times() in XSH, which says:
.\" The times of a terminated child process are included... when wait()
.\" or waitpid() returns the process ID of this terminated child.
-.PP
+.P
On Linux,
the \[lq]arbitrary point in the past\[rq]
from which the return value of
use
.BR clock_gettime (2)
instead.
-.\" .PP
+.\" .P
.\" On older systems the number of clock ticks per second is given
.\" by the variable HZ.
-.PP
+.P
SVr1-3 returns
.I long
and the struct members are of type
yet.
.SH NOTES
The number of clock ticks per second can be obtained using:
-.PP
+.P
.in +4n
.EX
sysconf(_SC_CLK_TCK);
.EE
.in
-.PP
+.P
Note that
.BR clock (3)
also returns a value of type
.BR "#include <signal.h>" " /* Definition of " SIG* " constants */"
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "[[deprecated]] int syscall(SYS_tkill, pid_t " tid ", int " sig );
-.PP
+.P
.B #include <signal.h>
-.PP
+.P
.BI "int tgkill(pid_t " tgid ", pid_t " tid ", int " sig );
.fi
-.PP
+.P
.IR Note :
glibc provides no wrapper for
.BR tkill (),
can be used to send a signal only to a process (i.e., thread group)
as a whole, and the signal will be delivered to an arbitrary
thread within that process.)
-.PP
+.P
.BR tkill ()
is an obsolete predecessor to
.BR tgkill ().
.\" measurable, one could exhaust all but 1-2 available pid values,
.\" possibly by lowering the max pid parameter in /proc, forcing
.\" the same tid to be reused rapidly.
-.PP
+.P
These are the raw system call interfaces, meant for internal
thread library use.
.SH RETURN VALUE
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.BI "int truncate(const char *" path ", off_t " length );
.BI "int ftruncate(int " fd ", off_t " length );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR truncate ():
.nf
_XOPEN_SOURCE >= 500
|| /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
|| /* glibc <= 2.19: */ _BSD_SOURCE
.fi
-.PP
+.P
.BR ftruncate ():
.nf
_XOPEN_SOURCE >= 500
to be truncated to a size of precisely
.I length
bytes.
-.PP
+.P
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 (\[aq]\e0\[aq]).
-.PP
+.P
The file offset is not changed.
-.PP
+.P
If the size changed, then the st_ctime and st_mtime fields
(respectively, time of last status change and
time of last modification; see
.BR inode (7))
for the file are updated,
and the set-user-ID and set-group-ID mode bits may be cleared.
-.PP
+.P
With
.BR ftruncate (),
the file must be open for writing; with
.TP
.B ETXTBSY
The file is an executable file that is being executed.
-.PP
+.P
For
.BR ftruncate ()
the same errors apply, but instead of things that can be wrong with
to be used to extend a file beyond its current length:
a notable example on Linux is VFAT.
.\" At the very least: OSF/1, Solaris 7, and FreeBSD conform, mtk, Jan 2002
-.PP
+.P
On some 32-bit architectures,
the calling signature for these system calls differ,
for the reasons described in
.\" POSIX.1-2001 also has
.\" .BR truncate (),
.\" as an XSI extension.
-.\" .LP
+.\" .P
.\" SVr4 documents additional
.\" .BR truncate ()
.\" error conditions EMFILE, EMULTIHP, ENFILE, ENOLINK. SVr4 documents for
.\" .BR ftruncate ()
.\" an additional EAGAIN error condition.
-.PP
+.P
The original Linux
.BR truncate ()
and
.SH SYNOPSIS
.nf
.B #include <sys/stat.h>
-.PP
+.P
.BI "mode_t umask(mode_t " mask );
.fi
.SH DESCRIPTION
& 0777 (i.e., only the file permission bits of
.I mask
are used), and returns the previous value of the mask.
-.PP
+.P
The umask is used by
.BR open (2),
.BR mkdir (2),
.BR open (2)
and
.BR mkdir (2).
-.PP
+.P
Alternatively, if the parent directory has a default ACL (see
.BR acl (5)),
the umask is ignored, the default ACL is inherited,
.I mode
argument are turned off.
For example, the following default ACL is equivalent to a umask of 022:
-.PP
+.P
.in +4n
.EX
u::rwx,g::r-x,o::r-x
.EE
.in
-.PP
+.P
Combining the effect of this default ACL with a
.I mode
argument of 0666 (rw-rw-rw-), the resulting file permissions would be 0644
(rw-r--r--).
-.PP
+.P
The constants that should be used to specify
.I mask
are described in
.BR inode (7).
-.PP
+.P
The typical default value for the process umask is
.BR S_IWGRP " | " S_IWOTH
(octal 022).
argument to
.BR open (2)
is specified as:
-.PP
+.P
.in +4n
.EX
.BR S_IRUSR " | " S_IWUSR " | " S_IRGRP " | " S_IWGRP " | " S_IROTH " | " S_IWOTH
.EE
.in
-.PP
+.P
(octal 0666) when creating a new file, the permissions on the
resulting file will be:
-.PP
+.P
.in +4n
.EX
.BR S_IRUSR " | " S_IWUSR " | " S_IRGRP " | " S_IROTH
.EE
.in
-.PP
+.P
(because 0666 & \[ti]022 = 0644; i.e. rw\-r\-\-r\-\-).
.SH RETURN VALUE
This system call always succeeds and the previous value of the mask
inherits its parent's umask.
The umask is left unchanged by
.BR execve (2).
-.PP
+.P
It is impossible to use
.BR umask ()
to fetch a process's umask without at the same time changing it.
would then be needed to restore the umask.
The nonatomicity of these two steps provides the potential
for races in multithreaded programs.
-.PP
+.P
Since Linux 4.7, the umask of any process can be viewed via the
.I Umask
field of
Inspecting this field in
.I /proc/self/status
allows a process to retrieve its umask without at the same time changing it.
-.PP
+.P
The umask setting also affects the permissions assigned to POSIX IPC objects
.RB ( mq_open (3),
.BR sem_open (3),
.SH SYNOPSIS
.nf
.B "#include <sys/mount.h>"
-.PP
+.P
.BI "int umount(const char *" target );
.BI "int umount2(const char *" target ", int " flags );
.fi
.\" Note: the kernel naming differs from the glibc naming
.\" umount2 is the glibc name for what the kernel now calls umount
.\" and umount is the glibc name for oldumount
-.PP
+.P
Appropriate privilege (Linux: the
.B CAP_SYS_ADMIN
capability) is required to unmount filesystems.
-.PP
+.P
Linux 2.1.116 added the
.BR umount2 ()
system call, which, like
.B MNT_EXPIRE
.\" http://sourceware.org/bugzilla/show_bug.cgi?id=10092
are available since glibc 2.11.
-.PP
+.P
The original
.BR umount ()
function was called as \fIumount(device)\fP and would return
.BR umount ()
of any peer in a set of shared mounts will cause all of its
peers to be unmounted and all of their slaves to be unmounted as well.
-.PP
+.P
This propagation of unmount activity can be particularly surprising
on systems where every mount is shared by default.
On such systems,
onto a subdirectory and then later unmounting that subdirectory with
.B MNT_DETACH
will cause every mount in the mount namespace to be lazily unmounted.
-.PP
+.P
To ensure
.BR umount ()
does not propagate in this fashion,
.SH SYNOPSIS
.nf
.B #include <sys/utsname.h>
-.PP
+.P
.BI "int uname(struct utsname *" buf );
.fi
.SH DESCRIPTION
.I utsname
struct is defined in
.IR <sys/utsname.h> :
-.PP
+.P
.in +4n
.EX
struct utsname {
};
.EE
.in
-.PP
+.P
The length of the arrays in a
.I struct utsname
is unspecified (see NOTES);
The
.I domainname
member (the NIS or YP domain name) is a GNU extension.
-.PP
+.P
The length of the fields in the struct varies.
Some operating systems
or libraries use a hardcoded 9 or 33 or 65 or 257.
.I domainname
field is set via
.BR setdomainname (2).
-.PP
+.P
Part of the utsname information is also accessible via
.IR /proc/sys/kernel/ { ostype ,
.IR hostname ,
and
.BR ulimit (3)
are implemented as library functions.
-.PP
+.P
Some system calls, like
.BR alloc_hugepages (2),
.BR free_hugepages (2),
and
.BR vm86 (2)
exist only on certain architectures.
-.PP
+.P
Some system calls, like
.BR ipc (2),
.BR create_module (2),
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.BI "int unlink(const char *" pathname );
-.PP
+.P
.BR "#include <fcntl.h> " "/* Definition of " AT_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "int unlinkat(int " dirfd ", const char *" pathname ", int " flags );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR unlinkat ():
.nf
Since glibc 2.10:
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.
-.PP
+.P
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.
-.PP
+.P
If the name referred to a symbolic link, the link is removed.
-.PP
+.P
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.
.B AT_REMOVEDIR
flag)
except for the differences described here.
-.PP
+.P
If the pathname given in
.I pathname
is relative, then it is interpreted relative to the directory
and
.BR rmdir (2)
for a relative pathname).
-.PP
+.P
If the pathname given in
.I pathname
is relative and
.BR unlink ()
and
.BR rmdir (2)).
-.PP
+.P
If the pathname given in
.I pathname
is absolute, then
.I dirfd
is ignored.
-.PP
+.P
.I flags
is a bit mask that can either be specified as 0, or by ORing
together flag values that control the operation of
.BR rmdir (2)
on
.IR pathname .
-.PP
+.P
See
.BR openat (2)
for an explanation of the need for
.B EROFS
.I pathname
refers to a file on a read-only filesystem.
-.PP
+.P
The same errors that occur for
.BR unlink ()
and
.nf
.B #define _GNU_SOURCE
.B #include <sched.h>
-.PP
+.P
.BI "int unshare(int " flags );
.fi
.SH DESCRIPTION
while other parts, such as virtual memory, may be
shared by explicit request when creating a process or thread using
.BR clone (2).
-.PP
+.P
The main use of
.BR unshare ()
is to allow a process to control its
shared execution context without creating a new process.
-.PP
+.P
The
.I flags
argument is a bit mask that specifies which parts of
.BR semop (2).
.\" CLONE_NEWNS If CLONE_SIGHAND is set and signals are also being shared
.\" (i.e., current->signal->count > 1), force CLONE_THREAD.
-.PP
+.P
In addition,
.BR CLONE_THREAD ,
.BR CLONE_SIGHAND ,
If the process is multithreaded, then
the use of these flags results in an error.
.\" See kernel/fork.c::check_unshare_flags()
-.PP
+.P
If
.I flags
is specified as zero, then
.\"be incrementally added to unshare without affecting legacy
.\"applications using unshare.
.\"
-.PP
+.P
Creating all kinds of namespace, except user namespaces, requires the
.B CAP_SYS_ADMIN
capability.
running a shell in a new mount namespace,
and verifying that the original shell and the
new shell are in separate mount namespaces:
-.PP
+.P
.in +4n
.EX
$ \fBreadlink /proc/$$/ns/mnt\fP
mnt:[4026532325]
.EE
.in
-.PP
+.P
The differing output of the two
.BR readlink (1)
commands shows that the two shells are in different mount namespaces.
.BR setns (2),
.BR vfork (2),
.BR namespaces (7)
-.PP
+.P
.I Documentation/userspace\-api/unshare.rst
in the Linux kernel source tree
.\" commit f504d47be5e8fa7ecf2bf660b18b42e6960c0eb2
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.BI "[[deprecated]] int uselib(const char *" library );
.fi
.SH DESCRIPTION
it was sufficient to manually declare the interface in your code;
alternatively, you could invoke the system call using
.BR syscall (2).
-.PP
+.P
In ancient libc versions (before glibc 2.0),
.BR uselib ()
was used to load
the shared libraries with names found in an array of names
in the binary.
-.\" .PP
+.\" .P
.\" .\" libc 4.3.1f - changelog 1993-03-02
.\" Since libc 4.3.2, startup code tries to prefix these names
.\" with "/usr/lib", "/lib" and "" before giving up.
.\" .BR LD_LIBRARY_PATH ,
.\" and if not found there,
.\" prefixes "/usr/lib", "/lib" and "/" are tried.
-.\" .PP
+.\" .P
.\" 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.
-.\" .PP
+.\" .P
.\" glibc2 does not use this call.
-.PP
+.P
Since Linux 3.15,
.\" commit 69369a7003735d0d8ef22097e27a55a8bad9557a
this system call is available only when the kernel is configured with the
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.BR "#include <linux/userfaultfd.h>" " /* Definition of " UFFD_* " constants */"
.B #include <unistd.h>
-.PP
+.P
.BI "int syscall(SYS_userfaultfd, int " flags );
.fi
-.PP
+.P
.IR Note :
glibc provides no wrapper for
.BR userfaultfd (),
and returns a file descriptor that refers to the new object.
The new userfaultfd object is configured using
.BR ioctl (2).
-.PP
+.P
Once the userfaultfd object is configured, the application can use
.BR read (2)
to receive userfaultfd notifications.
.I flags
used for the creation of the userfaultfd or subsequent calls to
.BR fcntl (2).
-.PP
+.P
The following values may be bitwise ORed in
.I flags
to change the behavior of
on the registered range with this userfaultfd, a
.B SIGBUS
signal will be delivered.
-.PP
+.P
When the last file descriptor referring to a userfaultfd object is closed,
all memory ranges that were registered with the object are unregistered
and unread events are flushed.
.\"
-.PP
+.P
Userfaultfd supports three modes of registration:
.TP
.BR UFFDIO_REGISTER_MODE_MISSING " (since Linux 4.10)"
until user-space write-unprotects the page using an
.B UFFDIO_WRITEPROTECT
ioctl.
-.PP
+.P
Multiple modes can be enabled at the same time for the same memory range.
-.PP
+.P
Since Linux 4.14, a userfaultfd page-fault notification can selectively embed
faulting thread ID information into the notification.
One needs to enable this feature explicitly using the
.BR ioctl_userfaultfd (2).
When servicing the page fault events,
the fault-handling thread can trigger a wake-up for the sleeping thread.
-.PP
+.P
It is possible for the faulting threads and the fault-handling threads
to run in the context of different processes.
In this case, these threads may belong to different programs,
the process that monitors userfaultfd and handles page faults
needs to be aware of the changes in the virtual memory layout
of the faulting process to avoid memory corruption.
-.PP
+.P
Since Linux 4.11,
userfaultfd can also notify the fault-handling threads about changes
in the virtual memory layout of the faulting process.
The userfaultfd manager should carefully synchronize calls to
.B UFFDIO_COPY
with the processing of events.
-.PP
+.P
The current asynchronous model of the event delivery is optimal for
single threaded non-cooperative userfaultfd manager implementations.
.\" Regarding the preceding sentence, Mike Rapoport says:
.\" problematic for multi-threaded monitor. I even suspect that it would be
.\" impossible to ensure synchronization between page faults and non-page
.\" fault events in multi-threaded monitor.
-.\" .PP
+.\" .P
.\" FIXME elaborate about non-cooperating mode, describe its limitations
.\" for kernels before Linux 4.11, features added in Linux 4.11
.\" and limitations remaining in Linux 4.11
.\" Maybe it's worth adding a dedicated sub-section...
.\"
-.PP
+.P
Since Linux 5.7, userfaultfd is able to do
synchronous page dirty tracking using the new write-protect register mode.
One should check against the feature bit
operations described below (or those operations fail with the
.B EINVAL
error).
-.PP
+.P
After a successful
.B UFFDIO_API
operation,
.BR UFFDIO_CONTINUE )
.BR ioctl (2)
operations to resolve the page fault.
-.PP
+.P
Since Linux 4.14, if the application sets the
.B UFFD_FEATURE_SIGBUS
feature bit using the
For example, this feature can be useful for applications that
want to prevent the kernel from automatically allocating pages and filling
holes in sparse files when the hole is accessed through a memory mapping.
-.PP
+.P
The
.B UFFD_FEATURE_SIGBUS
feature is implicitly inherited through
.BR fork (2)
if used in combination with
.BR UFFD_FEATURE_FORK .
-.PP
+.P
Details of the various
.BR ioctl (2)
operations can be found in
.BR ioctl_userfaultfd (2).
-.PP
+.P
Since Linux 4.11, events other than page-fault may enabled during
.B UFFDIO_API
operation.
-.PP
+.P
Up to Linux 4.11,
userfaultfd can be used only with anonymous private memory mappings.
Since Linux 4.11,
ioctl against the feature bit
.B UFFD_FEATURE_PAGEFAULT_FLAG_WP
before using this feature.
-.PP
+.P
Since Linux 5.19,
the write-protection mode was also supported on
shmem and hugetlbfs memory types.
It can be detected with the feature bit
.BR UFFD_FEATURE_WP_HUGETLBFS_SHMEM .
-.PP
+.P
To register with userfaultfd write-protect mode, the user needs to initiate the
.B UFFDIO_REGISTER
ioctl with mode
receive any notification when a missing page is written.
Instead, user-space will receive a write-protect page-fault notification
only when an existing but write-protected page got written.
-.PP
+.P
After the
.B UFFDIO_REGISTER
ioctl completed with
.I uffdio_writeprotect.mode
should be set to
.BR UFFDIO_WRITEPROTECT_MODE_WP .
-.PP
+.P
When a write-protect event happens,
user-space will receive a page-fault notification whose
.I uffd_msg.pagefault.flags
bit set along with the
.B UFFD_PAGEFAULT_FLAG_WP
bit.
-.PP
+.P
To resolve a write-protection page fault, the user should initiate another
.B UFFDIO_WRITEPROTECT
ioctl, whose
or
.B UFFD_FEATURE_MINOR_SHMEM
since Linux 5.14.
-.PP
+.P
To register with userfaultfd minor fault mode,
the user needs to initiate the
.B UFFDIO_REGISTER
ioctl with mode
.B UFFD_REGISTER_MODE_MINOR
set.
-.PP
+.P
When a minor fault occurs,
user-space will receive a page-fault notification
whose
will have the
.B UFFD_PAGEFAULT_FLAG_MINOR
flag set.
-.PP
+.P
To resolve a minor page fault,
the handler should decide whether or not
the existing page contents need to be modified first.
which installs the page table entries and
(by default)
wakes up the faulting thread(s).
-.PP
+.P
Minor fault mode supports only hugetlbfs-backed (since Linux 5.13)
and shmem-backed (since Linux 5.14) memory.
.\"
.I uffd_msg
structures, each of which describes a page-fault event
or an event required for the non-cooperative userfaultfd usage:
-.PP
+.P
.in +4n
.EX
struct uffd_msg {
} __packed;
.EE
.in
-.PP
+.P
If multiple events are available and the supplied buffer is large enough,
.BR read (2)
returns as many events as will fit in the supplied buffer.
.BR read (2)
fails with the error
.BR EINVAL .
-.PP
+.P
The fields set in the
.I uffd_msg
structure are as follows:
.TP
.B UFFD_PAGEFAULT_FLAG_WRITE
If this flag is set, then the fault was a write fault.
-.PP
+.P
If neither
.B UFFD_PAGEFAULT_FLAG_WP
nor
The end address of the memory range that was freed using
.BR madvise (2)
or unmapped
-.PP
+.P
A
.BR read (2)
on a userfaultfd file descriptor can fail with the following errors:
.B UFFDIO_API
.BR ioctl (2)
operation
-.PP
+.P
If the
.B O_NONBLOCK
flag is enabled in the associated open file description,
Linux.
.SH HISTORY
Linux 4.3.
-.PP
+.P
Support for hugetlbfs and shared memory areas and
non-page-fault events was added in Linux 4.11
.SH NOTES
page-fault handler for the process, for the pages in a demand-page zero
region created using
.BR mmap (2).
-.PP
+.P
The program takes one command-line argument,
which is the number of pages that will be created in a mapping
whose page faults will be handled via userfaultfd.
operation.
The program then creates a second thread that will perform the
task of handling page faults.
-.PP
+.P
The main thread then walks through the pages of the mapping fetching
bytes from successive pages.
Because the pages have not yet been accessed,
the first access of a byte in each page will trigger a page-fault event
on the userfaultfd file descriptor.
-.PP
+.P
Each of the page-fault events is handled by the second thread,
which sits in a loop processing input from the userfaultfd file descriptor.
In each loop iteration, the second thread first calls
.B UFFDIO_COPY
.BR ioctl (2)
operation.
-.PP
+.P
The following is an example of what we see when running the program:
-.PP
+.P
.in +4n
.EX
$ \fB./userfaultfd_demo 3\fP
.BR ioctl_userfaultfd (2),
.BR madvise (2),
.BR mmap (2)
-.PP
+.P
.I Documentation/admin\-guide/mm/userfaultfd.rst
in the Linux kernel source tree
.B #include <sys/types.h>
.BR "#include <unistd.h>" " /* libc[45] */"
.BR "#include <ustat.h>" " /* glibc2 */"
-.PP
+.P
.BI "[[deprecated]] int ustat(dev_t " dev ", struct ustat *" ubuf );
.fi
.SH DESCRIPTION
.I ustat
structure that contains the following
members:
-.PP
+.P
.in +4n
.EX
daddr_t f_tfree; /* Total free blocks */
char f_fpack[6]; /* Filsys pack name */
.EE
.in
-.PP
+.P
The last two fields,
.I f_fname
and
Removed in glibc 2.28.
.\" SVr4 documents additional error conditions ENOLINK, ECOMM, and EINTR
.\" but has no ENOSYS condition.
-.PP
+.P
.BR ustat ()
is deprecated and has been provided only for compatibility.
All new programs should use
.SH SYNOPSIS
.nf
.B #include <utime.h>
-.PP
+.P
.BI "int utime(const char *" filename ,
.BI " const struct utimbuf *_Nullable " times );
-.PP
+.P
.B #include <sys/time.h>
-.PP
+.P
.BI "int utimes(const char *" filename ,
.BI " const struct timeval " times "[_Nullable 2]);"
.fi
.B Note:
modern applications may prefer to use the interfaces described in
.BR utimensat (2).
-.PP
+.P
The
.BR utime ()
system call
respectively.
The status change time (ctime) will be set to the current time, even if the
other time stamps don't actually change.
-.PP
+.P
If
.I times
is NULL, then the access and modification times of the file are set
to the current time.
-.PP
+.P
Changing timestamps is permitted when: either
the process has appropriate privileges,
or the effective user ID equals the user ID
of the file, or
.I times
is NULL and the process has write permission for the file.
-.PP
+.P
The
.I utimbuf
structure is:
-.PP
+.P
.in +4n
.EX
struct utimbuf {
};
.EE
.in
-.PP
+.P
The
.BR utime ()
system call
allows specification of timestamps with a resolution of 1 second.
-.PP
+.P
The
.BR utimes ()
system call
The
.I timeval
structure is:
-.PP
+.P
.in +4n
.EX
struct timeval {
};
.EE
.in
-.PP
+.P
.I times[0]
specifies the new access time, and
.I times[1]
.nf
.BR "#include <fcntl.h>" " /* Definition of " AT_* " constants */"
.B #include <sys/stat.h>
-.PP
+.P
.BI "int utimensat(int " dirfd ", const char *" pathname ,
.BI " const struct timespec " times "[_Nullable 2], int " flags );
.BI "int futimens(int " fd ", const struct timespec " times "[_Nullable 2]);"
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR utimensat ():
.nf
Since glibc 2.10:
Before glibc 2.10:
_ATFILE_SOURCE
.fi
-.PP
+.P
.BR futimens ():
.nf
Since glibc 2.10:
.BR utimes (2),
which permit only second and microsecond precision, respectively,
when setting file timestamps.
-.PP
+.P
With
.BR utimensat ()
the file is specified via the pathname given in
the file whose timestamps are to be updated is specified via
an open file descriptor,
.IR fd .
-.PP
+.P
For both calls, the new file timestamps are specified in the array
.IR times :
.I times[0]
This information is conveyed in a
.BR timespec (3)
structure.
-.PP
+.P
Updated file timestamps are set to the greatest value
supported by the filesystem that is not greater than the specified time.
-.PP
+.P
If the
.I tv_nsec
field of one of the
.I tv_sec
.\" 2.6.22 was broken: it is not ignored
field is ignored.
-.PP
+.P
If
.I times
is NULL, then both timestamps are set to the current time.
.\"
-.PP
+.P
The status change time (ctime) will be set to the current time, even if the
other time stamps don't actually change.
.SS Permissions requirements
the caller's effective user ID must match the owner of the file; or
.IP \[bu]
the caller must have appropriate privileges.
-.PP
+.P
To make any change other than setting both timestamps to the
current time (i.e.,
.I times
field is
.BR UTIME_OMIT ),
either condition 2 or 3 above must apply.
-.PP
+.P
If both
.I tv_nsec
fields are specified as
See
.BR openat (2)
for an explanation of why this can be useful.
-.PP
+.P
If
.I pathname
is relative and
is interpreted relative to the current working
directory of the calling process (like
.BR utimes (2)).
-.PP
+.P
If
.I pathname
is absolute, then
.I dirfd
is ignored.
-.PP
+.P
The
.I flags
field is a bit mask that may be 0, or include the following constant,
Using this feature, the call
.I "futimens(fd,\ times)"
is implemented as:
-.PP
+.P
.in +4n
.EX
utimensat(fd, NULL, times, 0);
.EE
.in
-.PP
+.P
Note, however, that the glibc wrapper for
.BR utimensat ()
disallows passing NULL as the value for
.BR utimensat ()
obsoletes
.BR futimesat (2).
-.PP
+.P
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.
and
.BR utimes (2)
on Linux.)
-.PP
+.P
If both
.I tv_nsec
fields are specified as
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.B pid_t vfork(void);
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR vfork ():
.nf
Since glibc 2.12:
creates a child process of the calling process.
For details and return value and errors, see
.BR fork (2).
-.PP
+.P
.BR vfork ()
is a special case of
.BR clone (2).
It may be useful in performance-sensitive applications
where a child is created which then immediately issues an
.BR execve (2).
-.PP
+.P
.BR vfork ()
differs from
.BR fork (2)
.BR stdio (3)
buffers), but may call
.BR _exit (2).
-.PP
+.P
As with
.BR fork (2),
the child process created by
.BR vfork ()
call differs only in the treatment of the virtual address space,
as described above.
-.PP
+.P
Signals sent to the parent
arrive after the child releases the parent's memory
(i.e., after the child terminates
.BR execve (2),
and cannot rely on any specific behavior with respect to shared memory.
.\" In AIXv3.1 vfork is equivalent to fork.
-.PP
+.P
Some consider the semantics of
.BR vfork ()
to be an architectural blemish, and the 4.2BSD man page stated:
(See
.BR pthreads (7)
for a description of Linux threading libraries.)
-.PP
+.P
A call to
.BR vfork ()
is equivalent to calling
with
.I flags
specified as:
-.PP
+.P
.in +4n
.EX
CLONE_VM | CLONE_VFORK | SIGCHLD
4.3BSD; POSIX.1-2001 (but marked OBSOLETE).
POSIX.1-2008 removes the specification of
.BR vfork ().
-.PP
+.P
The
.BR vfork ()
system call appeared in 3.0BSD.
from the perspective of the parent process
(e.g., memory changes would be visible in the parent,
but changes to the state of open file descriptors would not be visible).
-.PP
+.P
When
.BR vfork ()
is called in a multithreaded process,
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.B int vhangup(void);
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR vhangup ():
.nf
Since glibc 2.21:
.SH SYNOPSIS
.nf
.B #include <sys/vm86.h>
-.PP
+.P
.BI "int vm86old(struct vm86_struct *" info );
.BI "int vm86(unsigned long " fn ", struct vm86plus_struct *" v86 );
.fi
.I struct vm86_struct
was changed
in 1.1.8 and 1.1.9.
-.PP
+.P
These calls cause the process to enter VM86 mode (virtual-8086 in Intel
literature), and are used by
.BR dosemu .
-.PP
+.P
VM86 mode is an emulation of real mode within a protected mode task.
.SH RETURN VALUE
On success, zero is returned.
.nf
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <fcntl.h>
-.PP
+.P
.BI "ssize_t vmsplice(int " fd ", const struct iovec *" iov ,
.BI " size_t " nr_segs ", unsigned int " flags );
.fi
The file descriptor
.I fd
must refer to a pipe.
-.PP
+.P
The pointer
.I iov
points to an array of
.I iovec
structures as described in
.BR iovec (3type).
-.PP
+.P
The
.I flags
argument is a bit mask that is composed by ORing together
Currently,
.\" UIO_MAXIOV in kernel source
this limit is 1024.
-.PP
+.P
.\" commit 6a14b90bb6bc7cd83e2a444bf457a2ea645cbfe7
.BR vmsplice ()
really supports true splicing only from user memory to a pipe.
.SH SYNOPSIS
.nf
.B #include <sys/wait.h>
-.PP
+.P
.BI "pid_t wait(int *_Nullable " "wstatus" );
.BI "pid_t waitpid(pid_t " pid ", int *_Nullable " wstatus ", int " options );
-.PP
+.P
.BI "int waitid(idtype_t " idtype ", id_t " id \
", siginfo_t *" infop ", int " options );
/* This is the glibc and POSIX interface; see
NOTES for information on the raw system call. */
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR waitid ():
.nf
Since glibc 2.26:
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).
-.PP
+.P
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
The call
.I wait(&wstatus)
is equivalent to:
-.PP
+.P
.in +4n
.EX
waitpid(\-1, &wstatus, 0);
.EE
.in
-.PP
+.P
The
.BR waitpid ()
system call suspends execution of the calling thread until a
via the
.I options
argument, as described below.
-.PP
+.P
The value of
.I pid
can be:
meaning wait for the child whose process ID is equal to the
value of
.IR pid .
-.PP
+.P
The value of
.I options
is an OR of zero or more of the following constants:
.BR WCONTINUED " (since Linux 2.6.10)"
also return if a stopped child has been resumed by delivery of
.BR SIGCONT .
-.PP
+.P
(For Linux-only options, see below.)
-.PP
+.P
If
.I wstatus
is not NULL,
.BR waitid ()
system call (available since Linux 2.6.9) provides more precise
control over which child state changes to wait for.
-.PP
+.P
The
.I idtype
and
Wait for any child;
.I id
is ignored.
-.PP
+.P
The child state changes to wait for are specified by ORing
one or more of the following flags in
.IR options :
Wait for (previously stopped) children that have been
resumed by delivery of
.BR SIGCONT .
-.PP
+.P
The following flags may additionally be ORed in
.IR options :
.TP
.B WNOWAIT
Leave the child in a waitable state; a later wait call
can be used to again retrieve the child status information.
-.PP
+.P
Upon successful return,
.BR waitid ()
fills in the following fields of the
.B CLD_CONTINUED
(child continued by
.BR SIGCONT ).
-.PP
+.P
If
.B WNOHANG
was specified in
.I si_pid
field before the call and check for a nonzero value in this field
after the call returns.
-.PP
+.P
POSIX.1-2008 Technical Corrigendum 1 (2013) adds the requirement that when
.B WNOHANG
is specified in
.BR wait ():
on success, returns the process ID of the terminated child;
on failure, \-1 is returned.
-.PP
+.P
.BR waitpid ():
on success, returns the process ID of the child whose state has changed;
if
.I pid
exist, but have not yet changed state, then 0 is returned.
On failure, \-1 is returned.
-.PP
+.P
.BR waitid ():
returns 0 on success or
if
.\" returns the PID of the child. Either this is a bug, or it is intended
.\" behavior that needs to be documented. See my Jan 2009 LKML mail
.\" "waitid() return value strangeness when infop is NULL".
-.PP
+.P
On failure, each of these calls sets
.I errno
to indicate the error.
.BR wait ()
is actually a library function that (in glibc) is implemented as a call to
.BR wait4 (2).
-.PP
+.P
On some architectures, there is no
.BR waitpid ()
system call;
instead, this interface is implemented via a C library
wrapper function that calls
.BR wait4 (2).
-.PP
+.P
The raw
.BR waitid ()
system call takes a fifth argument, of type
operation);
.BR init (1)
automatically performs a wait to remove the zombies.
-.PP
+.P
POSIX.1-2001 specifies that if the disposition of
.B SIGCHLD
is set to
is "ignore", explicitly setting the disposition to
.B SIG_IGN
results in different treatment of zombie process children.)
-.PP
+.P
Linux 2.6 conforms to the POSIX requirements.
However, Linux 2.4 (and earlier) does not:
if a
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.
-.PP
+.P
The following Linux-specific
.I options
are for use with children created using
Do not wait for children of other threads in
the same thread group.
This was the default before Linux 2.4.
-.PP
+.P
Since Linux 4.7,
.\" commit bf959931ddb88c4e4366e96dd22e68fa0db9527c
.\" prevents cases where an unreapable zombie is created if
The parent process executes a loop that monitors the child using
.BR waitpid (),
and uses the W*() macros described above to analyze the wait status value.
-.PP
+.P
The following shell session demonstrates the use of the program:
-.PP
+.P
.in +4n
.EX
.RB "$" " ./a.out &"
.SH SYNOPSIS
.nf
.B #include <sys/wait.h>
-.PP
+.P
.BI "pid_t wait3(int *_Nullable " "wstatus" ", int " options ,
.BI " struct rusage *_Nullable " rusage );
.BI "pid_t wait4(pid_t " pid ", int *_Nullable " wstatus ", int " options ,
.BI " struct rusage *_Nullable " rusage );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR wait3 ():
.nf
Since glibc 2.26:
_BSD_SOURCE || _XOPEN_SOURCE >= 500
.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
.fi
-.PP
+.P
.BR wait4 ():
.nf
Since glibc 2.19:
or
.BR waitid (2)
is preferable.
-.PP
+.P
The
.BR wait3 ()
and
but additionally return resource usage information about the
child in the structure pointed to by
.IR rusage .
-.PP
+.P
Other than the use of the
.I rusage
argument, the following
.BR wait3 ()
call:
-.PP
+.P
.in +4n
.EX
wait3(wstatus, options, rusage);
.EE
.in
-.PP
+.P
is equivalent to:
-.PP
+.P
.in +4n
.EX
waitpid(\-1, wstatus, options);
.EE
.in
-.PP
+.P
Similarly, the following
.BR wait4 ()
call:
-.PP
+.P
.in +4n
.EX
wait4(pid, wstatus, options, rusage);
.EE
.in
-.PP
+.P
is equivalent to:
-.PP
+.P
.in +4n
.EX
waitpid(pid, wstatus, options);
.EE
.in
-.PP
+.P
In other words,
.BR wait3 ()
waits of any child, while
See
.BR wait (2)
for further details.
-.PP
+.P
If
.I rusage
is not NULL, the
None.
.SH HISTORY
4.3BSD.
-.PP
+.P
SUSv1 included a specification of
.BR wait3 ();
SUSv2 included
.BR wait3 (),
but marked it LEGACY;
SUSv3 removed it.
-.PP
+.P
Including
.I <sys/time.h>
is not required these days, but increases portability.
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.BI "ssize_t write(int " fd ", const void " buf [. count "], size_t " count );
.fi
.SH DESCRIPTION
.I buf
to the file referred to by the file descriptor
.IR fd .
-.PP
+.P
The number of bytes written may be less than
.I count
if, for example,
bytes.
(See also
.BR pipe (7).)
-.PP
+.P
For a seekable file (i.e., one to which
.BR lseek (2)
may be applied, for example, a regular file)
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.
-.PP
+.P
POSIX requires that a
.BR read (2)
that can be proved to occur after a
.BR write ()
has returned will return the new data.
Note that not all filesystems are POSIX conforming.
-.PP
+.P
According to POSIX.1, if
.I count
is greater than
On success, the number of bytes written is returned.
On error, \-1 is returned, and \fIerrno\fP is set
to indicate the error.
-.PP
+.P
Note that a successful
.BR write ()
may transfer fewer than
call to transfer the remaining bytes.
The subsequent call will either transfer further bytes or
may result in an error (e.g., if the disk is now full).
-.PP
+.P
If \fIcount\fP is zero and
.I fd
refers to a regular file, then
signal.
(Thus, the write return value is seen only if the program
catches, blocks or ignores this signal.)
-.PP
+.P
Other errors may occur, depending on the object connected to
.IR fd .
.SH STANDARDS
SVr4, 4.3BSD, POSIX.1-2001.
.\" SVr4 documents additional error
.\" conditions EDEADLK, ENOLCK, ENOLNK, ENOSR, ENXIO, or ERANGE.
-.PP
+.P
Under SVr4 a write may be interrupted and return
.B EINTR
at any point,
The only way to be sure is to call
.BR fsync (2)
after you are done writing all your data.
-.PP
+.P
If a
.BR write ()
is interrupted by a signal handler before any bytes are written,
.BR EINTR ;
if it is interrupted after at least one byte has been written,
the call succeeds, and returns the number of bytes written.
-.PP
+.P
On Linux,
.BR write ()
(and similar system calls) will transfer at most
returning the number of bytes actually transferred.
.\" commit e28cc71572da38a5a12c1cfe4d7032017adccf69
(This is true on both 32-bit and 64-bit systems.)
-.PP
+.P
An error return value while performing
.BR write ()
using direct I/O does not mean the
.SH BUGS
According to POSIX.1-2008/SUSv4 Section XSI 2.9.7
("Thread Interactions with Regular File Operations"):
-.PP
+.P
.RS 4
All of the following functions shall be atomic with respect to
each other in the effects specified in POSIX.1-2008 when they
operate on regular files or symbolic links: ...
.RE
-.PP
+.P
Among the APIs subsequently listed are
.BR write ()
and
.SH SYNOPSIS
.EX
.B #include <linux/openat2.h>
-.PP
+.P
.B struct open_how {
.BR " u64 flags;" " /* " O_ "* flags */"
.BR " u64 mode;" " /* Mode for " O_ { CREAT , TMPFILE "} */"
.EE
.SH DESCRIPTION
Specifies how a pathname should be opened.
-.PP
+.P
The fields are as follows:
.TP
.I flags
.nf
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <sched.h>
-.PP
+.P
.BI "void CPU_ZERO(cpu_set_t *" set );
-.PP
+.P
.BI "void CPU_SET(int " cpu ", cpu_set_t *" set );
.BI "void CPU_CLR(int " cpu ", cpu_set_t *" set );
.BI "int CPU_ISSET(int " cpu ", cpu_set_t *" set );
-.PP
+.P
.BI "int CPU_COUNT(cpu_set_t *" set );
-.PP
+.P
.BI "void CPU_AND(cpu_set_t *" destset ,
.BI " cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 );
.BI "void CPU_OR(cpu_set_t *" destset ,
.BI " cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 );
.BI "void CPU_XOR(cpu_set_t *" destset ,
.BI " cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 );
-.PP
+.P
.BI "int CPU_EQUAL(cpu_set_t *" set1 ", cpu_set_t *" set2 );
-.PP
+.P
.BI "cpu_set_t *CPU_ALLOC(int " num_cpus );
.BI "void CPU_FREE(cpu_set_t *" set );
.BI "size_t CPU_ALLOC_SIZE(int " num_cpus );
-.PP
+.P
.BI "void CPU_ZERO_S(size_t " setsize ", cpu_set_t *" set );
-.PP
+.P
.BI "void CPU_SET_S(int " cpu ", size_t " setsize ", cpu_set_t *" set );
.BI "void CPU_CLR_S(int " cpu ", size_t " setsize ", cpu_set_t *" set );
.BI "int CPU_ISSET_S(int " cpu ", size_t " setsize ", cpu_set_t *" set );
-.PP
+.P
.BI "int CPU_COUNT_S(size_t " setsize ", cpu_set_t *" set );
-.PP
+.P
.BI "void CPU_AND_S(size_t " setsize ", cpu_set_t *" destset ,
.BI " cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 );
.BI "void CPU_OR_S(size_t " setsize ", cpu_set_t *" destset ,
.BI " cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 );
.BI "void CPU_XOR_S(size_t " setsize ", cpu_set_t *" destset ,
.BI " cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 );
-.PP
+.P
.BI "int CPU_EQUAL_S(size_t " setsize ", cpu_set_t *" set1 \
", cpu_set_t *" set2 );
.fi
CPU sets are used by
.BR sched_setaffinity (2)
and similar interfaces.
-.PP
+.P
The
.I cpu_set_t
data type is implemented as a bit mask.
However, the data structure should be treated as opaque:
all manipulation of CPU sets should be done via the macros
described in this page.
-.PP
+.P
The following macros are provided to operate on the CPU set
.IR set :
.TP
.BR CPU_COUNT ()
Return the number of CPUs in
.IR set .
-.PP
+.P
Where a
.I cpu
argument is specified, it should not produce side effects,
since the above macros may evaluate the argument more than once.
-.PP
+.P
The first CPU on the system corresponds to a
.I cpu
value of 0, the next CPU corresponds to a
(currently 1024) specifies a value one greater than the maximum CPU
number that can be stored in
.IR cpu_set_t .
-.PP
+.P
The following macros perform logical operations on CPU sets:
.TP
.BR CPU_AND ()
defined by the standard
.I cpu_set_t
data type), glibc nowadays provides a set of macros to support this.
-.PP
+.P
The following macros are used to allocate and deallocate CPU sets:
.TP
.BR CPU_ALLOC ()
.BR CPU_FREE ()
Free a CPU set previously allocated by
.BR CPU_ALLOC ().
-.PP
+.P
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,
is in
.IR set ;
otherwise, it returns 0.
-.PP
+.P
.BR CPU_COUNT ()
and
.BR CPU_COUNT_S ()
return the number of CPUs in
.IR set .
-.PP
+.P
.BR CPU_EQUAL ()
and
.BR CPU_EQUAL_S ()
return nonzero if the two CPU sets are equal; otherwise they return 0.
-.PP
+.P
.BR CPU_ALLOC ()
returns a pointer on success, or NULL on failure.
(Errors are as for
.BR malloc (3).)
-.PP
+.P
.BR CPU_ALLOC_SIZE ()
returns the number of bytes required to store a
CPU set of the specified cardinality.
-.PP
+.P
The other functions do not return a value.
.SH STANDARDS
Linux.
and
.BR CPU_ISSET ()
macros were added in glibc 2.3.3.
-.PP
+.P
.BR CPU_COUNT ()
first appeared in glibc 2.6.
-.PP
+.P
.BR CPU_AND (),
.BR CPU_OR (),
.BR CPU_XOR (),
.SH NOTES
To duplicate a CPU set, use
.BR memcpy (3).
-.PP
+.P
Since CPU sets are bit masks 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
.IR "sizeof(unsigned long)" .
An application should consider the contents of these extra bits
to be undefined.
-.PP
+.P
Notwithstanding the similarity in the names,
note that the constant
.B CPU_SETSIZE
argument of the
.BR CPU_*_S ()
macros is a size in bytes.
-.PP
+.P
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,
.SH EXAMPLES
The following program demonstrates the use of some of the macros
used for dynamically allocated CPU sets.
-.PP
+.P
.\" SRC BEGIN (CPU_SET.c)
.EX
#define _GNU_SOURCE
.nf
.BR "#define _ISOC99_SOURCE" " /* See feature_test_macros(7) */"
.B #include <math.h>
-.PP
+.P
.B INFINITY
-.PP
+.P
.B NAN
-.PP
+.P
.B HUGE_VAL
.B HUGE_VALF
.B HUGE_VALL
expands to a
.I float
constant representing positive infinity.
-.PP
+.P
The macro
.B NAN
expands to a
.I signaling
NaN.
See IEC 60559:1989.
-.PP
+.P
The macros
.BR HUGE_VAL ,
.BR HUGE_VALF ,
C11.
.SH HISTORY
C99.
-.PP
+.P
On a glibc system, the macro
.B HUGE_VAL
is always available.
.SH SYNOPSIS
.nf
.B #include <sys/param.h>
-.PP
+.P
.BI MAX( a ", " b );
.BI MIN( a ", " b );
.fi
or
.BR fmin (3),
which can handle NaN.
-.PP
+.P
The arguments may be evaluated more than once, or not at all.
-.PP
+.P
Some UNIX systems might provide these macros in a different header,
or not at all.
.SH BUGS
or
.B default:
if no type is compatible.
-.PP
+.P
.I expression
is not evaluated.
-.PP
+.P
This is especially useful for writing type-generic macros,
that will behave differently depending on the type of the argument.
.SH STANDARDS
.SH SYNOPSIS
.nf
.B #include <sys/platform/ppc.h>
-.PP
+.P
.B uint64_t __ppc_get_timebase(void);
.B uint64_t __ppc_get_timebase_freq(void);
.fi
value, while
.BR __ppc_get_timebase_freq ()
returns the frequency in which the Time Base Register is updated.
-.PP
+.P
The Time Base Register is a 64-bit register provided by Power Architecture
processors.
It stores a monotonically incremented value that is updated at a
.BR __ppc_get_timebase ()
returns a 64-bit unsigned integer that represents the current value of the
Time Base Register.
-.PP
+.P
.BR __ppc_get_timebase_freq ()
returns a 64-bit unsigned integer that represents the frequency at
which the Time Base Register is updated.
.SH SYNOPSIS
.nf
.B #include <sys/platform/ppc.h>
-.PP
+.P
.B void __ppc_set_ppr_med(void);
.B void __ppc_set_ppr_very_low(void);
.B void __ppc_set_ppr_low(void);
These functions provide access to the
.I Program Priority Register
(PPR) on the Power architecture.
-.PP
+.P
The PPR is a 64-bit register that controls the program's priority.
By adjusting the PPR value the programmer may improve system
throughput by causing system resources to be used more
.BR __ppc_set_ppr_med_low ()
sets the Program Priority Register value to
.IR "medium low" .
-.PP
+.P
The privileged state
.I medium high
may also be set during certain time intervals by problem-state (unprivileged)
.BR __ppc_set_ppr_med_high ()
sets the Program Priority to
.IR "medium high" .
-.PP
+.P
If the program priority is medium high when the time interval expires or if an
attempt is made to set the priority to medium high when it is not allowed, the
priority is set to medium.
.BR "#ifdef _ARCH_PWR8" .
.SH SEE ALSO
.BR __ppc_yield (3)
-.PP
+.P
.I Power ISA, Book\~II - Section\ 3.1 (Program Priority Registers)
.SH SYNOPSIS
.nf
.B #include <sys/platform/ppc.h>
-.PP
+.P
.B void __ppc_yield(void);
.B void __ppc_mdoio(void);
.B void __ppc_mdoom(void);
processors on the Power architecture.
They can be used, for example, if a program waiting on a lock intends
to divert the shared resources to be used by other processors.
-.PP
+.P
.BR __ppc_yield ()
provides a hint that performance will probably be improved if shared
resources dedicated to the executing processor are released for use by
other processors.
-.PP
+.P
.BR __ppc_mdoio ()
provides a hint that performance will probably be improved if shared
resources dedicated to the executing processor are released until all
outstanding storage accesses to caching-inhibited storage have been
completed.
-.PP
+.P
.BR __ppc_mdoom ()
provides a hint that performance will probably be improved if shared
resources dedicated to the executing processor are released until all
glibc 2.18.
.SH SEE ALSO
.BR __ppc_set_ppr_med (3)
-.PP
+.P
.I Power ISA, Book\~II - Section\~3.2 ("or" architecture)
.SH SYNOPSIS
.nf
.B #include <i386/fpu_control.h>
-.PP
+.P
.BI "[[deprecated]] void __setfpucw(unsigned short " control_word );
.fi
.SH DESCRIPTION
.BR fesetexceptflag (3),
and
.BR fetestexcept (3).
-.PP
+.P
If direct access to the FPU control word is still needed, the
.B _FPU_GETCW
and
can be used.
.SH EXAMPLES
.B __setfpucw(0x1372)
-.PP
+.P
Set FPU control word on the i386 architecture to
.RS
.PD 0
.RE
.SH SEE ALSO
.BR feclearexcept (3)
-.PP
+.P
.I <fpu_control.h>
.SH SYNOPSIS
.nf
.B #include <stdlib.h>
-.PP
+.P
.BI "long a64l(const char *" str64 );
.BI "char *l64a(long " value );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR a64l (),
.BR l64a ():
.nf
and
.BR a64l ()
sign-extends its 32-bit result.
-.PP
+.P
The 64 digits in the base-64 system are:
-.PP
+.P
.RS
.nf
\&\[aq].\[aq] represents a 0
a-z represent 38-63
.fi
.RE
-.PP
+.P
So 123 = 59*64\[ha]0 + 1*64\[ha]1 = "v/".
.SH ATTRIBUTES
For an explanation of the terms used in this section, see
.BR l64a ()
may be a pointer to a static buffer, possibly overwritten
by later calls.
-.PP
+.P
The behavior of
.BR l64a ()
is undefined when
If
.I value
is zero, it returns an empty string.
-.PP
+.P
These functions are broken before glibc 2.2.5
(puts most significant digit first).
-.PP
+.P
This is not the encoding used by
.BR uuencode (1).
.SH SEE ALSO
.SH SYNOPSIS
.nf
.B #include <stdlib.h>
-.PP
+.P
.B [[noreturn]] void abort(void);
.fi
.SH DESCRIPTION
signal is caught and the signal handler does not return
(see
.BR longjmp (3)).
-.PP
+.P
If the
.B SIGABRT
signal is ignored, or caught by a handler that returns, the
It does this by restoring the default disposition for
.B SIGABRT
and then raising the signal for a second time.
-.PP
+.P
As with other cases of abnormal termination the functions registered with
.BR atexit (3)
and
C11, POSIX.1-2008.
.SH HISTORY
SVr4, POSIX.1-2001, 4.3BSD, C89.
-.PP
+.P
Up until glibc 2.26,
if the
.BR abort ()
.SH SYNOPSIS
.nf
.B #include <stdlib.h>
-.PP
+.P
.BI "int abs(int " j );
.BI "long labs(long " j );
.BI "long long llabs(long long " j );
-.PP
+.P
.B #include <inttypes.h>
-.PP
+.P
.BI "intmax_t imaxabs(intmax_t " j );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR llabs ():
.nf
_ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
.\" POSIX.1 (1996 edition) requires only the
.\" .BR abs ()
.\" function.
-.PP
+.P
C89 only
includes the
.BR abs ()
.SH NOTES
Trying to take the absolute value of the most negative integer
is not defined.
-.PP
+.P
The
.BR llabs ()
function is included since glibc 2.0.
The
.BR imaxabs ()
function is included since glibc 2.1.1.
-.PP
+.P
For
.BR llabs ()
to be declared, it may be necessary to define
\fB_ISOC99_SOURCE\fP or \fB_ISOC9X_SOURCE\fP (depending on the
version of glibc) before including any standard headers.
-.PP
+.P
By default,
GCC handles
.BR abs (),
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "double acos(double " x );
.BI "float acosf(float " x );
.BI "long double acosl(long double " x );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR acosf (),
.BR acosl ():
.nf
On success, these functions return the arc cosine of
.I x
in radians; the return value is in the range [0,\ pi].
-.PP
+.P
If
.I x
is a NaN, a NaN is returned.
-.PP
+.P
If
.I x
is +1,
+0 is returned.
-.PP
+.P
If
.I x
is positive infinity or negative infinity,
a domain error occurs,
and a NaN is returned.
-.PP
+.P
If
.I x
is outside the range [\-1,\ 1],
.BR math_error (7)
for information on how to determine whether an error has occurred
when calling these functions.
-.PP
+.P
The following errors can occur:
.TP
Domain error: \fIx\fP is outside the range [\-1,\ 1]
C11, POSIX.1-2008.
.SH HISTORY
C99, POSIX.1-2001.
-.PP
+.P
The variant returning
.I double
also conforms to
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "double acosh(double " x );
.BI "float acoshf(float " x );
.BI "long double acoshl(long double " x );
-.PP
+.P
.fi
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR acosh ():
.nf
_ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
|| /* Since glibc 2.19: */ _DEFAULT_SOURCE
|| /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
.fi
-.PP
+.P
.BR acoshf (),
.BR acoshl ():
.nf
.SH RETURN VALUE
On success, these functions return the inverse hyperbolic cosine of
.IR x .
-.PP
+.P
If
.I x
is a NaN, a NaN is returned.
-.PP
+.P
If
.I x
is +1, +0 is returned.
-.PP
+.P
If
.I x
is positive infinity, positive infinity is returned.
-.PP
+.P
If
.I x
is less than 1,
.BR math_error (7)
for information on how to determine whether an error has occurred
when calling these functions.
-.PP
+.P
The following errors can occur:
.TP
Domain error: \fIx\fP is less than 1
C11, POSIX.1-2008.
.SH HISTORY
C99, POSIX.1-2001.
-.PP
+.P
The variant returning
.I double
also conforms to
.RI ( libc ", " \-lc )
.SH SYNOPSIS
.nf
-.PP
+.P
.B #include <fmtmsg.h>
-.PP
+.P
.BI "int addseverity(int " severity ", const char *" s );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR addseverity ():
.nf
Since glibc 2.19:
.SH SYNOPSIS
.nf
.B #include <sys/time.h>
-.PP
+.P
.BI "int adjtime(const struct timeval *" delta ", struct timeval *" olddelta );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR adjtime ():
.nf
Since glibc 2.19:
in the structure pointed to by
.IR delta .
This structure has the following form:
-.PP
+.P
.in +4n
.EX
struct timeval {
};
.EE
.in
-.PP
+.P
If the adjustment in
.I delta
is positive, then the system clock is speeded up by some
If the adjustment in
.I delta
is negative, then the clock is slowed down in a similar fashion.
-.PP
+.P
If a clock adjustment from an earlier
.BR adjtime ()
call is already in progress
.I 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.
-.PP
+.P
If
.I olddelta
is not NULL, then the buffer that it points to is used to return
applications (e.g.,
.BR make (1))
by abrupt positive or negative jumps in the system time.
-.PP
+.P
.BR 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
.SH SYNOPSIS
.nf
.B "#include <aio.h>"
-.PP
+.P
.BI "int aio_cancel(int " fd ", struct aiocb *" aiocbp );
.fi
.SH DESCRIPTION
for a description of the
.I aiocb
structure.)
-.PP
+.P
Normal asynchronous notification occurs for canceled requests (see
.BR aio (7)
and
is set to
.BR ECANCELED .
The control block of requests that cannot be canceled is not changed.
-.PP
+.P
If the request could not be canceled,
then it will terminate in the usual way after performing the I/O operation.
(In this case,
.BR aio_error (3)
will return the status
.BR EINPROGRESSS .)
-.PP
+.P
If
.I aiocbp
is not NULL, and
.I fd
differs from the file descriptor with which the asynchronous operation
was initiated, unspecified results occur.
-.PP
+.P
Which operations are cancelable is implementation-defined.
.\" FreeBSD: not those on raw disk devices.
.SH RETURN VALUE
.SH SYNOPSIS
.nf
.B "#include <aio.h>"
-.PP
+.P
.BI "int aio_error(const struct aiocb *" aiocbp );
.fi
.SH DESCRIPTION
.SH SYNOPSIS
.nf
.B "#include <aio.h>"
-.PP
+.P
.BI "int aio_fsync(int " op ", struct aiocb *" aiocbp );
.fi
.SH DESCRIPTION
for a description of the
.I aiocb
structure.)
-.PP
+.P
More precisely, if
.I op
is
.BR O_DSYNC ,
this call is the asynchronous analog of
.BR fdatasync (2).
-.PP
+.P
Note that this is a request only; it does not wait for I/O completion.
-.PP
+.P
Apart from
.IR aio_fildes ,
the only field in the structure pointed to by
.nf
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B "#include <aio.h>"
-.PP
+.P
.BI "void aio_init(const struct aioinit *" init );
.fi
.SH DESCRIPTION
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.
-.PP
+.P
The tuning information is provided in the buffer pointed to by the argument
.IR init .
This buffer is a structure of the following form:
-.PP
+.P
.in +4n
.EX
struct aioinit {
};
.EE
.in
-.PP
+.P
The following fields are used in the
.I aioinit
structure:
.SH SYNOPSIS
.nf
.B "#include <aio.h>"
-.PP
+.P
.BI "int aio_read(struct aiocb *" aiocbp );
.fi
.SH DESCRIPTION
This function is the asynchronous analog of
.BR read (2).
The arguments of the call
-.PP
+.P
.in +4n
.EX
read(fd, buf, count)
.EE
.in
-.PP
+.P
correspond (in order) to the fields
.IR aio_fildes ,
.IR aio_buf ,
for a description of the
.I aiocb
structure.)
-.PP
+.P
The data is read starting at the absolute position
.IR aiocbp\->aio_offset ,
regardless of the file offset.
After the call,
the value of the file offset is unspecified.
-.PP
+.P
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.
appropriately; see
.BR sigevent (3type)
for details.
-.PP
+.P
If
.B _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
.IR aiocbp\->aio_reqprio .
-.PP
+.P
The field
.I aiocbp\->aio_lio_opcode
is ignored.
-.PP
+.P
No data is read from a regular file beyond its maximum offset.
.SH RETURN VALUE
On success, 0 is returned.
.\" or the control block of the operation
must not be accessed during the operation or undefined results may occur.
The memory areas involved must remain valid.
-.PP
+.P
Simultaneous I/O operations specifying the same
.I aiocb
structure produce undefined results.
.SH SYNOPSIS
.nf
.B "#include <aio.h>"
-.PP
+.P
.BI "ssize_t aio_return(struct aiocb *" aiocbp );
.fi
.SH DESCRIPTION
for a description of the
.I aiocb
structure.)
-.PP
+.P
This function should be called only once for any given request, after
.BR aio_error (3)
returns something other than
.BR fdatasync (2),
call.
On error, \-1 is returned, and \fIerrno\fP is set to indicate the error.
-.PP
+.P
If the asynchronous I/O operation has not yet completed,
the return value and effect of
.BR aio_return ()
.RI ( librt ", " \-lrt )
.SH SYNOPSIS
.nf
-.PP
+.P
.B "#include <aio.h>"
-.PP
+.P
.BI "int aio_suspend(const struct aiocb *const " aiocb_list "[], int " nitems ,
.BI " const struct timespec *restrict " timeout );
.fi
.I timespec
structure, see
.BR nanosleep (2).)
-.PP
+.P
The
.I nitems
argument specifies the number of items in
for a description of the
.I aiocb
structure.)
-.PP
+.P
If
.B CLOCK_MONOTONIC
is supported, this clock is used to measure
.SH HISTORY
glibc 2.1.
POSIX.1-2001.
-.PP
+.P
POSIX doesn't specify the parameters to be
.IR restrict ;
that is specific to glibc.
One can achieve polling by using a non-NULL
.I timeout
that specifies a zero time interval.
-.PP
+.P
If one or more of the asynchronous I/O operations specified in
.I aiocb_list
has already completed at the time of the call to
.BR aio_suspend (),
then the call returns immediately.
-.PP
+.P
To determine which I/O operations have completed
after a successful return from
.BR aio_suspend (),
.SH SYNOPSIS
.nf
.B "#include <aio.h>"
-.PP
+.P
.BI "int aio_write(struct aiocb *" aiocbp );
.fi
.SH DESCRIPTION
This function is the asynchronous analog of
.BR write (2).
The arguments of the call
-.PP
+.P
.in +4n
.EX
write(fd, buf, count)
.EE
.in
-.PP
+.P
correspond (in order) to the fields
.IR aio_fildes ,
.IR aio_buf ,
for a description of the
.I aiocb
structure.)
-.PP
+.P
If
.B O_APPEND
is not set, the data is written starting at the
.BR aio_write ()
calls are made.
After the call, the value of the file offset is unspecified.
-.PP
+.P
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.
appropriately; see
.BR sigevent (3type)
for details.
-.PP
+.P
If
.B _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
.IR aiocbp\->aio_reqprio .
-.PP
+.P
The field
.I aiocbp\->aio_lio_opcode
is ignored.
-.PP
+.P
No data is written to a regular file beyond its maximum offset.
.SH RETURN VALUE
On success, 0 is returned.
.\" or the control block of the operation
must not be accessed during the operation or undefined results may occur.
The memory areas involved must remain valid.
-.PP
+.P
Simultaneous I/O operations specifying the same
.I aiocb
structure produce undefined results.
.SH SYNOPSIS
.nf
.B #include <alloca.h>
-.PP
+.P
.BI "void *alloca(size_t " size );
.fi
.SH DESCRIPTION
or
.BR siglongjmp (3).
Otherwise, its use is discouraged.
-.PP
+.P
Because the space allocated by
.BR alloca ()
is allocated within the stack frame,
.BR longjmp (3)
or
.BR siglongjmp (3).
-.PP
+.P
The space allocated by
.BR alloca ()
is
.I not
automatically deallocated if the pointer that refers to it
simply goes out of scope.
-.PP
+.P
Do not attempt to
.BR free (3)
space allocated by
.BR alloca ()!
-.PP
+.P
By necessity,
.BR alloca ()
is a compiler built-in, also known as
in which case
.I <alloca.h>
is required, lest a symbol dependency be emitted.
-.PP
+.P
The fact that
.BR alloca ()
is a built-in means it is impossible to take its address
or to change its behavior by linking with a different library.
-.PP
+.P
Variable length arrays (VLAs) are part of the C99 standard,
optional since C11, and can be used for a similar purpose.
However, they do not port to standard C++, and, being variables,
(However, the program is likely to receive a
.B SIGSEGV
signal if it attempts to access unavailable space.)
-.PP
+.P
On many systems
.BR alloca ()
cannot be used inside the list of arguments of a function call, because
.SH SYNOPSIS
.nf
.B #include <stdlib.h>
-.PP
+.P
.B uint32_t arc4random(void);
.BI "uint32_t arc4random_uniform(uint32_t " upper_bound );
.BI "void arc4random_buf(void " buf [. n "], size_t " n );
.fi
.SH DESCRIPTION
These functions give cryptographically-secure pseudorandom numbers.
-.PP
+.P
.BR arc4random ()
returns a uniformly-distributed value.
-.PP
+.P
.BR arc4random_uniform ()
returns a uniformly-distributed value less than
.I upper_bound
(see BUGS).
-.PP
+.P
.BR arc4random_buf ()
fills the memory pointed to by
.IR buf ,
with
.I n
bytes of pseudorandom data.
-.PP
+.P
The
.BR rand (3)
and
.SH RETURN VALUE
.BR arc4random ()
returns a pseudorandom number.
-.PP
+.P
.BR arc4random_uniform ()
returns a pseudorandom number less than
.I upper_bound
.SH SYNOPSIS
.nf
.B "#include <argz.h>"
-.PP
+.P
.BI "error_t argz_add(char **restrict " argz ", size_t *restrict " argz_len ,
.BI " const char *restrict " str );
-.PP
+.P
.BI "error_t argz_add_sep(char **restrict " argz \
", size_t *restrict " argz_len ,
.BI " const char *restrict " str ", int " delim );
-.PP
+.P
.BI "error_t argz_append(char **restrict " argz ", size_t *restrict " argz_len ,
.BI " const char *restrict " buf ", size_t " buf_len );
-.PP
+.P
.BI "size_t argz_count(const char *" argz ", size_t " argz_len );
-.PP
+.P
.BI "error_t argz_create(char *const " argv "[], char **restrict " argz ,
.BI " size_t *restrict " argz_len );
-.PP
+.P
.BI "error_t argz_create_sep(const char *restrict " str ", int " sep ,
.BI " char **restrict " argz ", size_t *restrict " argz_len );
-.PP
+.P
.BI "void argz_delete(char **restrict " argz ", size_t *restrict " argz_len ,
.BI " char *restrict " entry );
-.PP
+.P
.BI "void argz_extract(const char *restrict " argz ", size_t " argz_len ,
.BI " char **restrict " argv );
-.PP
+.P
.BI "error_t argz_insert(char **restrict " argz ", size_t *restrict " argz_len ,
.BI " char *restrict " before ", const char *restrict " entry );
-.PP
+.P
.BI "char *argz_next(const char *restrict " argz ", size_t " argz_len ,
.BI " const char *restrict " entry );
-.PP
+.P
.BI "error_t argz_replace(char **restrict " argz \
", size_t *restrict " argz_len ,
.BI " const char *restrict " str ", const char *restrict " with ,
.BI " unsigned int *restrict " replace_count );
-.PP
+.P
.BI "void argz_stringify(char *" argz ", size_t " len ", int " sep );
.fi
.SH DESCRIPTION
These functions are glibc-specific.
-.PP
+.P
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 (\[aq]\e0\[aq]).
If the length is nonzero, the last byte of the buffer must be a null byte.
-.PP
+.P
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.
so that
.BR free (3)
can be used to dispose of them again.
-.PP
+.P
.BR argz_add ()
adds the string
.I str
.I *argz
and
.IR *argz_len .
-.PP
+.P
.BR argz_add_sep ()
is similar, but splits the string
.I str
.IR delim .
For example, one might use this on a UNIX search path with
delimiter \[aq]:\[aq].
-.PP
+.P
.BR argz_append ()
appends the argz vector
.RI ( buf ,\ buf_len )
.I *argz_len
will be increased by
.IR buf_len .)
-.PP
+.P
.BR argz_count ()
counts the number of strings, that is,
the number of null bytes (\[aq]\e0\[aq]), in
.RI ( argz ,\ argz_len ).
-.PP
+.P
.BR argz_create ()
converts a UNIX-style argument vector
.IR argv ,
.IR "(char\ *)\ 0" ,
into an argz vector
.RI ( *argz ,\ *argz_len ).
-.PP
+.P
.BR argz_create_sep ()
converts the null-terminated string
.I str
.RI ( *argz ,\ *argz_len )
by breaking it up at every occurrence of the separator
.IR sep .
-.PP
+.P
.BR argz_delete ()
removes the substring pointed to by
.I entry
.I *argz
and
.IR *argz_len .
-.PP
+.P
.BR argz_extract ()
is the opposite of
.BR argz_create ().
must have room for
.IR argz_count ( argz ", " argz_len ") + 1"
pointers.
-.PP
+.P
.BR argz_insert ()
is the opposite of
.BR argz_delete ().
is NULL, then
.I entry
will inserted at the end.
-.PP
+.P
.BR argz_next ()
is a function to step through the argz vector.
If
Otherwise, the entry
following is returned.
It returns NULL if there is no following entry.
-.PP
+.P
.BR argz_replace ()
replaces each occurrence of
.I str
is non-NULL,
.I *replace_count
will be incremented by the number of replacements.
-.PP
+.P
.BR argz_stringify ()
is the opposite of
.BR argz_create_sep ().
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "double asin(double " x );
.BI "float asinf(float " x );
.BI "long double asinl(long double " x );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR asinf (),
.BR asinl ():
.nf
On success, these functions return the principal value of the arc sine of
.I x
in radians; the return value is in the range [\-pi/2,\ pi/2].
-.PP
+.P
If
.I x
is a NaN, a NaN is returned.
-.PP
+.P
If
.I x
is +0 (\-0),
+0 (\-0) is returned.
-.PP
+.P
If
.I x
is outside the range [\-1,\ 1],
.BR math_error (7)
for information on how to determine whether an error has occurred
when calling these functions.
-.PP
+.P
The following errors can occur:
.TP
Domain error: \fIx\fP is outside the range [\-1,\ 1]
C11, POSIX.1-2008.
.SH HISTORY
C99, POSIX.1-2001.
-.PP
+.P
The variant returning
.I double
also conforms to
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "double asinh(double " x );
.BI "float asinhf(float " x );
.BI "long double asinhl(long double " x );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR asinh ():
.nf
_ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
|| /* Since glibc 2.19: */ _DEFAULT_SOURCE
|| /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
.fi
-.PP
+.P
.BR asinhf (),
.BR asinhl ():
.nf
.SH RETURN VALUE
On success, these functions return the inverse hyperbolic sine of
.IR x .
-.PP
+.P
If
.I x
is a NaN, a NaN is returned.
-.PP
+.P
If
.I x
is +0 (\-0), +0 (\-0) is returned.
-.PP
+.P
If
.I x
is positive infinity (negative infinity),
C11, POSIX.1-2008.
.SH HISTORY
C99, POSIX.1-2001.
-.PP
+.P
The variant returning
.I double
also conforms to
.nf
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <stdio.h>
-.PP
+.P
.BI "int asprintf(char **restrict " strp ", const char *restrict " fmt ", ...);"
.BI "int vasprintf(char **restrict " strp ", const char *restrict " fmt ,
.BI " va_list " ap );
.SH SYNOPSIS
.nf
.B #include <assert.h>
-.PP
+.P
.BI "void assert(scalar " expression );
.fi
.SH DESCRIPTION
This macro can help programmers find bugs in their programs,
or handle exceptional cases
via a crash that will produce limited debugging output.
-.PP
+.P
If
.I expression
is false (i.e., compares equal to zero),
.BR assert ()
call, the source code line number of the call, and the text of the argument;
something like:
-.PP
+.P
.in +4n
.EX
prog: some_file.c:16: some_func: Assertion \`val == 0\[aq] failed.
.EE
.in
-.PP
+.P
If the macro
.B NDEBUG
is defined at the moment
C11, POSIX.1-2008.
.SH HISTORY
C89, C99, POSIX.1-2001.
-.PP
+.P
In C89,
.I expression
is required to be of type
.nf
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <assert.h>
-.PP
+.P
.BI "void assert_perror(int " errnum );
.fi
.SH DESCRIPTION
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "double atan(double " x );
.BI "float atanf(float " x );
.BI "long double atanl(long double " x );
-.PP
+.P
.fi
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR atanf (),
.BR atanl ():
.nf
On success, these functions return the principal value of the arc tangent of
.I x
in radians; the return value is in the range [\-pi/2,\ pi/2].
-.PP
+.P
If
.I x
is a NaN, a NaN is returned.
-.PP
+.P
If
.I x
is +0 (\-0),
+0 (\-0) is returned.
-.PP
+.P
If
.I x
is positive infinity (negative infinity), +pi/2 (\-pi/2) is returned.
C11, POSIX.1-2008.
.SH HISTORY
C99, POSIX.1-2001.
-.PP
+.P
The variant returning
.I double
also conforms to
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "double atan2(double " y ", double " x );
.BI "float atan2f(float " y ", float " x );
.BI "long double atan2l(long double " y ", long double " x );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR atan2f (),
.BR atan2l ():
.nf
On success, these functions return the principal value of the arc tangent of
.I y/x
in radians; the return value is in the range [\-pi,\ pi].
-.PP
+.P
If
.I y
is +0 (\-0) and
.I x
is less than 0, +pi (\-pi) is returned.
-.PP
+.P
If
.I y
is +0 (\-0) and
.I x
is greater than 0, +0 (\-0) is returned.
-.PP
+.P
If
.I y
is less than 0 and
.I x
is +0 or \-0, \-pi/2 is returned.
-.PP
+.P
If
.I y
is greater than 0 and
.I x
is +0 or \-0, pi/2 is returned.
-.PP
+.P
.\" POSIX.1 says:
.\" If
.\" .I x
or
.I y
is NaN, a NaN is returned.
-.PP
+.P
.\" POSIX.1 says:
.\" If the result underflows, a range error may occur and
.\" .I y/x
is +0 (\-0) and
.I x
is \-0, +pi (\-pi) is returned.
-.PP
+.P
If
.I y
is +0 (\-0) and
.I x
is +0, +0 (\-0) is returned.
-.PP
+.P
If
.I y
is a finite value greater (less) than 0, and
.I x
is negative infinity, +pi (\-pi) is returned.
-.PP
+.P
If
.I y
is a finite value greater (less) than 0, and
.I x
is positive infinity, +0 (\-0) is returned.
-.PP
+.P
If
.I y
is positive infinity (negative infinity), and
.I x
is finite,
pi/2 (\-pi/2) is returned.
-.PP
+.P
If
.I y
is positive infinity (negative infinity) and
.I x
is negative infinity, +3*pi/4 (\-3*pi/4) is returned.
-.PP
+.P
If
.I y
is positive infinity (negative infinity) and
C11, POSIX.1-2008.
.SH HISTORY
C99, POSIX.1-2001.
-.PP
+.P
The variant returning
.I double
also conforms to
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "double atanh(double " x );
.BI "float atanhf(float " x );
.BI "long double atanhl(long double " x );
-.PP
+.P
.fi
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR atanh ():
.nf
_ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
|| /* Since glibc 2.19: */ _DEFAULT_SOURCE
|| /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
.fi
-.PP
+.P
.BR atanhf (),
.BR atanhl ():
.nf
.SH RETURN VALUE
On success, these functions return the inverse hyperbolic tangent of
.IR x .
-.PP
+.P
If
.I x
is a NaN, a NaN is returned.
-.PP
+.P
If
.I x
is +0 (\-0), +0 (\-0) is returned.
-.PP
+.P
If
.I x
is +1 or \-1,
or
.BR HUGE_VALL ,
respectively, with the mathematically correct sign.
-.PP
+.P
If the absolute value of
.I x
is greater than 1,
.BR math_error (7)
for information on how to determine whether an error has occurred
when calling these functions.
-.PP
+.P
The following errors can occur:
.TP
Domain error: \fIx\fP less than \-1 or greater than +1
C11, POSIX.1-2008.
.SH HISTORY
C99, POSIX.1-2001.
-.PP
+.P
The variant returning
.I double
also conforms to
.SH SYNOPSIS
.nf
.B #include <stdlib.h>
-.PP
+.P
.BI "int atexit(void (*" function )(void));
.fi
.SH DESCRIPTION
.IR main ().
Functions so registered are called in
the reverse order of their registration; no arguments are passed.
-.PP
+.P
The same function may be registered multiple times:
it is called once for each registration.
-.PP
+.P
POSIX.1 requires that an implementation allow at least
.\" POSIX.1-2001, POSIX.1-2008
.B ATEXIT_MAX
(32) such functions to be registered.
The actual limit supported by an implementation can be obtained using
.BR sysconf (3).
-.PP
+.P
When a child process is created via
.BR fork (2),
it inherits copies of its parent's registrations.
.BR on_exit (3))
are not called if a process terminates abnormally because
of the delivery of a signal.
-.PP
+.P
If one of the registered functions calls
.BR _exit (2),
then any remaining functions are not invoked,
and the other process termination steps performed by
.BR exit (3)
are not performed.
-.PP
+.P
The
.BR atexit ()
and
at normal process termination,
the registered functions are invoked in reverse order
of their registration by these two functions.
-.PP
+.P
According to POSIX.1, the result is undefined if
.BR longjmp (3)
is used to terminate execution of one of the functions registered using
.SH SYNOPSIS
.nf
.B #include <stdlib.h>
-.PP
+.P
.BI "double atof(const char *" nptr );
.fi
.SH DESCRIPTION
pointed to by \fInptr\fP to
.IR double .
The behavior is the same as
-.PP
+.P
.in +4n
.EX
strtod(nptr, NULL);
.EE
.in
-.PP
+.P
except that
.BR atof ()
does not detect errors.
.SH SYNOPSIS
.nf
.B #include <stdlib.h>
-.PP
+.P
.BI "int atoi(const char *" nptr );
.BI "long atol(const char *" nptr );
.BI "long long atoll(const char *" nptr );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR atoll ():
.nf
_ISOC99_SOURCE
pointed to by \fInptr\fP to
.IR int .
The behavior is the same as
-.PP
+.P
.in +4n
.EX
strtol(nptr, NULL, 10);
.EE
.in
-.PP
+.P
except that
.BR atoi ()
does not detect errors.
-.PP
+.P
The
.BR atol ()
and
C11, POSIX.1-2008.
.SH HISTORY
C99, POSIX.1-2001, SVr4, 4.3BSD.
-.PP
+.P
C89 and
POSIX.1-1996 include the functions
.BR atoi ()
.SH SYNOPSIS
.nf
.B #include <execinfo.h>
-.PP
+.P
.BI "int backtrace(void *" buffer [. size "], int " size );
-.PP
+.P
.BI "char **backtrace_symbols(void *const " buffer [. size "], int " size );
.BI "void backtrace_symbols_fd(void *const " buffer [. size "], int " size ", \
int " fd );
and
.I size
are large enough.
-.PP
+.P
Given the set of addresses returned by
.BR backtrace ()
in
and must be freed by the caller.
(The strings pointed to by the array of pointers
need not and should not be freed.)
-.PP
+.P
.BR backtrace_symbols_fd ()
takes the same
.I buffer
.IR size ,
then it may have been truncated, in which case the addresses of the
oldest stack frames are not returned.
-.PP
+.P
On success,
.BR backtrace_symbols ()
returns a pointer to the array
(in signal handlers, for example), you need to make sure
.I libgcc
is loaded beforehand.
-.PP
+.P
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
.BR backtrace_symbols ().
The following shell session shows what we might see when running the
program:
-.PP
+.P
.in +4n
.EX
.RB "$" " cc \-rdynamic prog.c \-o prog"
.SH SYNOPSIS
.nf
.B #include <libgen.h>
-.PP
+.P
.BI "char *dirname(char *" path );
.BI "char *basename(char *" path );
.fi
Warning: there are two different functions
.BR basename ();
see below.
-.PP
+.P
The functions
.BR dirname ()
and
.BR basename ()
returns the component following the final \[aq]/\[aq].
Trailing \[aq]/\[aq] characters are not counted as part of the pathname.
-.PP
+.P
If
.I path
does not contain a slash,
and
.BR basename ()
return the string ".".
-.PP
+.P
Concatenating the string returned by
.BR dirname (),
a "/", and the string returned by
.BR basename ()
yields a complete pathname.
-.PP
+.P
Both
.BR dirname ()
and
.IR path ,
so it may be desirable to pass a copy when calling one of
these functions.
-.PP
+.P
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
.I path
should not be modified or freed until the pointer returned by
the function is no longer required.
-.PP
+.P
The following list of examples (taken from SUSv2)
shows the strings returned by
.BR dirname ()
.BR basename ()
- the POSIX version described above, and the GNU version, which one gets
after
-.PP
+.P
.in +4n
.EX
.BR " #define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B " #include <string.h>"
.EE
.in
-.PP
+.P
The GNU version never modifies its argument, and returns the
empty string when
.I path
has a trailing slash, and in particular also when it is "/".
There is no GNU version of
.BR dirname ().
-.PP
+.P
With glibc, one gets the POSIX version of
.BR basename ()
when
.I path
argument, and segfault when called with a static string
such as "/usr/".
-.PP
+.P
Before glibc 2.2.1, the glibc version of
.BR dirname ()
did not correctly handle pathnames with trailing \[aq]/\[aq] characters,
.SH SYNOPSIS
.nf
.B #include <strings.h>
-.PP
+.P
.BI "[[deprecated]] int bcmp(const void " s1 [. n "], const void " s2 [. n "], \
size_t " n );
.fi
.SH SYNOPSIS
.nf
.B #include <strings.h>
-.PP
+.P
.BI "[[deprecated]] void bcopy(const void " src [. n "], void " dest [. n "], \
size_t " n );
.fi
None.
.SH HISTORY
4.3BSD.
-.PP
+.P
Marked as LEGACY in POSIX.1-2001: use
.BR memcpy (3)
or
.nf
.B #include <sys/types.h>
.B #include <netinet/in.h>
-.PP
+.P
.BI "int bindresvport(int " sockfd ", struct sockaddr_in *" sin );
.fi
.SH DESCRIPTION
to a privileged anonymous IP port,
that is, a port number arbitrarily selected from the range 512 to 1023.
.\" glibc actually starts searching with a port # in the range 600 to 1023
-.PP
+.P
If the
.BR bind (2)
performed by
is not NULL, then
.I sin\->sin_port
returns the port number actually allocated.
-.PP
+.P
.I sin
can be NULL, in which case
.I sin\->sin_family
glibc\ <\ 2.17: MT-Unsafe
T}
.TE
-.PP
+.P
The
.BR bindresvport ()
function uses a static variable that was not protected by a lock
.SH SYNOPSIS
.nf
.B #include <signal.h>
-.PP
+.P
.B typedef void (*sighandler_t)(int);
-.PP
+.P
.BI "sighandler_t bsd_signal(int " signum ", sighandler_t " handler );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR bsd_signal ():
.nf
Since glibc 2.26:
.BR bsd_signal ()
function takes the same arguments, and performs the same task, as
.BR signal (2).
-.PP
+.P
The difference between the two is that
.BR bsd_signal ()
is guaranteed to provide reliable signal semantics, that is:
should be avoided; use
.BR sigaction (2)
instead.
-.PP
+.P
On modern Linux systems,
.BR bsd_signal ()
and
provided unreliable signal semantics; see
.BR signal (2)
for details.
-.PP
+.P
The use of
.I sighandler_t
is a GNU extension;
.SH SYNOPSIS
.nf
.B #include <stdlib.h>
-.PP
+.P
.BI "void *bsearch(const void " key [. size "], \
const void " base [. size " * ." nmemb ],
.BI " size_t " nmemb ", size_t " size ,
The size of each member
of the array is specified by
.IR size .
-.PP
+.P
The contents of the array should be in ascending sorted order according
to the comparison function referenced by
.IR compar .
.BR qsort (3),
then retrieves desired elements using
.BR bsearch ().
-.PP
+.P
.\" SRC BEGIN (bsearch.c)
.EX
#include <stdio.h>
.SH SYNOPSIS
.nf
.B #include <string.h>
-.PP
+.P
.BI "int bcmp(const void " s1 [. n "], const void " s2 [. n "], size_t " n );
-.PP
+.P
.BI "void bcopy(const void " src [. n "], void " dest [. n "], size_t " n );
-.PP
+.P
.BI "void bzero(void " s [. n "], size_t " n );
-.PP
+.P
.BI "void *memccpy(void " dest [. n "], const void " src [. n "], int " c ", \
size_t " n );
-.PP
+.P
.BI "void *memchr(const void " s [. n "], int " c ", size_t " n );
-.PP
+.P
.BI "int memcmp(const void " s1 [. n "], const void " s2 [. n "], size_t " n );
-.PP
+.P
.BI "void *memcpy(void " dest [. n "], const void " src [. n "], size_t " n );
-.PP
+.P
.BI "void *memfrob(void " s [. n "], size_t " n );
-.PP
+.P
.BI "void *memmem(const void " haystack [. haystacklen "], size_t " haystacklen ,
.BI " const void " needle [. needlelen "], size_t " needlelen );
-.PP
+.P
.BI "void *memmove(void " dest [. n "], const void " src [. n "], size_t " n );
-.PP
+.P
.BI "void *memset(void " s [. n "], int " c ", size_t " n );
.fi
.SH DESCRIPTION
.SH SYNOPSIS
.nf
.B #include <byteswap.h>
-.PP
+.P
.BI "uint16_t bswap_16(uint16_t " x );
.BI "uint32_t bswap_32(uint32_t " x );
.BI "uint64_t bswap_64(uint64_t " x );
The program below swaps the bytes of the 8-byte integer supplied as
its command-line argument.
The following shell session demonstrates the use of the program:
-.PP
+.P
.in +4n
.EX
$ \fB./a.out 0x0123456789abcdef\fP
.SH SYNOPSIS
.nf
.B #include <wchar.h>
-.PP
+.P
.BI "wint_t btowc(int " c );
.fi
.SH DESCRIPTION
.B LC_CTYPE
category of the
current locale.
-.PP
+.P
This function should never be used.
It does not work for encodings which have
state, and unnecessarily treats single bytes differently from multibyte
Probably, you are looking for the APIs provided by the
.I libdb
library instead.
-.PP
+.P
The routine
.BR dbopen (3)
is the library interface to database files.
The general description of the database access methods is in
.BR dbopen (3),
this manual page describes only the btree-specific information.
-.PP
+.P
The btree data structure is a sorted, balanced tree structure storing
associated key/data pairs.
-.PP
+.P
The btree access-method-specific data structure provided to
.BR dbopen (3)
is defined in the
.I <db.h>
include file as follows:
-.PP
+.P
.in +4n
.EX
typedef struct {
} BTREEINFO;
.EE
.in
-.PP
+.P
The elements of this structure are as follows:
.TP
.I flags
If
.I lorder
is 0 (no order is specified), the current host order is used.
-.PP
+.P
If the file already exists (and the
.B O_TRUNC
flag is not specified), the
.I psize
are ignored
in favor of the values used when the tree was created.
-.PP
+.P
Forward sequential scans of a tree are from the least key to the greatest.
-.PP
+.P
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.
-.PP
+.P
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.
.BR hash (3),
.BR mpool (3),
.BR recno (3)
-.PP
+.P
.IR "The Ubiquitous B-tree" ,
Douglas Comer, ACM Comput. Surv. 11, 2 (June 1979), 121-138.
-.PP
+.P
.IR "Prefix B-trees" ,
Bayer and Unterauer, ACM Transactions on Database Systems, Vol. 2, 1
(March 1977), 11-26.
-.PP
+.P
.IR "The Art of Computer Programming Vol. 3: Sorting and Searching" ,
D.E. Knuth, 1968, pp 471-480.
.SH SYNOPSIS
.nf
.B #include <arpa/inet.h>
-.PP
+.P
.BI "uint32_t htonl(uint32_t " hostlong );
.BI "uint16_t htons(uint16_t " hostshort );
-.PP
+.P
.BI "uint32_t ntohl(uint32_t " netlong );
.BI "uint16_t ntohs(uint16_t " netshort );
.fi
function converts the unsigned integer
.I hostlong
from host byte order to network byte order.
-.PP
+.P
The
.BR htons ()
function converts the unsigned short integer
.I hostshort
from host byte order to network byte order.
-.PP
+.P
The
.BR ntohl ()
function converts the unsigned integer
.I netlong
from network byte order to host byte order.
-.PP
+.P
The
.BR ntohs ()
function converts the unsigned short integer
.I netshort
from network byte order to host byte order.
-.PP
+.P
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.
.SH SYNOPSIS
.nf
.B #include <strings.h>
-.PP
+.P
.BI "void bzero(void " s [. n "], size_t " n );
-.PP
+.P
.B #include <string.h>
-.PP
+.P
.BI "void explicit_bzero(void " s [. n "], size_t " n );
.fi
.SH DESCRIPTION
bytes of the memory starting at the location pointed to by
.IR s ,
by writing zeros (bytes containing \[aq]\e0\[aq]) to that area.
-.PP
+.P
The
.BR explicit_bzero ()
function performs the same task as
Calls to
.BR explicit_bzero ()
are never optimized away by the compiler.
-.PP
+.P
The
.BR explicit_bzero ()
function does not solve all problems associated with erasing sensitive data:
call creates a brief time window where the sensitive data is more
vulnerable than it would otherwise have been
if no attempt had been made to erase the data.
-.PP
+.P
Note that declaring the sensitive variable with the
.B volatile
qualifier does
it may force a variable that would otherwise have been optimized
into a register to instead be maintained in (more vulnerable)
RAM for its entire lifetime.
-.PP
+.P
Notwithstanding the above details, for security-conscious applications, using
.BR explicit_bzero ()
is generally preferable to not using it.
.SH SYNOPSIS
.nf
.B #include <complex.h>
-.PP
+.P
.BI "double cabs(double complex " z );
.BI "float cabsf(float complex " z );
.BI "long double cabsl(long double complex " z );
.SH SYNOPSIS
.nf
.B #include <complex.h>
-.PP
+.P
.BI "double complex cacos(double complex " z );
.BI "float complex cacosf(float complex " z );
.BI "long double complex cacosl(long double complex " z );
The real part of
.I y
is chosen in the interval [0,pi].
-.PP
+.P
One has:
-.PP
+.P
.nf
cacos(z) = \-i * clog(z + i * csqrt(1 \- z * z))
.fi
.SH SYNOPSIS
.nf
.B #include <complex.h>
-.PP
+.P
.BI "double complex cacosh(double complex " z );
.BI "float complex cacoshf(float complex " z );
.BI "long double complex cacoshl(long double complex " z );
The real part of
.I y
is chosen nonnegative.
-.PP
+.P
One has:
-.PP
+.P
.nf
cacosh(z) = 2 * clog(csqrt((z + 1) / 2) + csqrt((z \- 1) / 2))
.fi
.nf
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <stdlib.h>
-.PP
+.P
.BI "char *canonicalize_file_name(const char *" path ");"
.fi
.SH DESCRIPTION
Consecutive slash
.RI ( / )
characters are replaced by a single slash.
-.PP
+.P
The returned string is dynamically allocated by
.BR canonicalize_file_name ()
and the caller should deallocate it with
.BR free (3)
when it is no longer required.
-.PP
+.P
The call
.I canonicalize_file_name(path)
is equivalent to the call:
-.PP
+.P
.in +4n
.EX
realpath(path, NULL);
.SH SYNOPSIS
.nf
.B #include <complex.h>
-.PP
+.P
.BI "double carg(double complex " z ");"
.BI "float cargf(float complex " z ");"
.BI "long double cargl(long double complex " z ");"
These functions calculate the complex argument (also called phase angle) of
.IR z ,
with a branch cut along the negative real axis.
-.PP
+.P
A complex number can be described by two real coordinates.
One may use rectangular coordinates and gets
-.PP
+.P
.in +4n
.EX
z = x + I * y
.EE
.in
-.PP
+.P
where
.I x\~=\~creal(z)
and
.IR y\~=\~cimag(z) .
-.PP
+.P
Or one may use polar coordinates and gets
-.PP
+.P
.in +4n
.EX
z = r * cexp(I * a)
.EE
.in
-.PP
+.P
where
.I r\~=\~cabs(z)
is the "radius", the "modulus", the absolute value of
.I a\~=\~carg(z)
is the "phase angle", the argument of
.IR z .
-.PP
+.P
One has:
-.PP
+.P
.in +4n
.EX
tan(carg(z)) = cimag(z) / creal(z)
.SH SYNOPSIS
.nf
.B #include <complex.h>
-.PP
+.P
.BI "double complex casin(double complex " z );
.BI "float complex casinf(float complex " z );
.BI "long double complex casinl(long double complex " z );
The real part of
.I y
is chosen in the interval [\-pi/2,pi/2].
-.PP
+.P
One has:
-.PP
+.P
.nf
casin(z) = \-i clog(iz + csqrt(1 \- z * z))
.fi
.SH SYNOPSIS
.nf
.B #include <complex.h>
-.PP
+.P
.BI "double complex casinh(double complex " z );
.BI "float complex casinhf(float complex " z );
.BI "long double complex casinhl(long double complex " z );
The imaginary part of
.I y
is chosen in the interval [\-pi/2,pi/2].
-.PP
+.P
One has:
-.PP
+.P
.in +4n
.EX
casinh(z) = clog(z + csqrt(z * z + 1))
.SH SYNOPSIS
.nf
.B #include <complex.h>
-.PP
+.P
.BI "double complex catan(double complex " z );
.BI "float complex catanf(float complex " z );
.BI "long double complex catanl(long double complex " z );
.IR z .
If \fIy\~=\~catan(z)\fP, then \fIz\~=\~ctan(y)\fP.
The real part of y is chosen in the interval [\-pi/2,pi/2].
-.PP
+.P
One has:
-.PP
+.P
.in +4n
.EX
catan(z) = (clog(1 + i * z) \- clog(1 \- i * z)) / (2 * i)
.SH SYNOPSIS
.nf
.B #include <complex.h>
-.PP
+.P
.BI "double complex catanh(double complex " z );
.BI "float complex catanhf(float complex " z );
.BI "long double complex catanhl(long double complex " z );
The imaginary part of
.I y
is chosen in the interval [\-pi/2,pi/2].
-.PP
+.P
One has:
-.PP
+.P
.in +4n
.EX
catanh(z) = 0.5 * (clog(1 + z) \- clog(1 \- z))
.SH SYNOPSIS
.nf
.B #include <nl_types.h>
-.PP
+.P
.BI "char *catgets(nl_catd " catalog ", int " set_number \
", int " message_number ,
.BI " const char *" message );
POSIX.1-2008.
.SH HISTORY
POSIX.1-2001.
-.PP
+.P
The
.BR catgets ()
function is available only in libc.so.4.4.4c and above.
-.PP
+.P
The Jan 1987 X/Open Portability Guide specifies a more subtle
error return:
.I message
.SH SYNOPSIS
.nf
.B #include <nl_types.h>
-.PP
+.P
.BI "nl_catd catopen(const char *" name ", int " flag );
.BI "int catclose(nl_catd " catalog );
.fi
then the
.B FD_CLOEXEC
flag will be set.
-.PP
+.P
The argument
.I name
specifies the name of the message catalog to be opened.
.B LC_MESSAGES
part of the locale may invalidate
open catalog descriptors.
-.PP
+.P
The
.I flag
argument to
Otherwise, it will use the
.B LANG
environment variable.
-.PP
+.P
The function
.BR catclose ()
closes the message catalog identified by
possible values for the
.BR open (2)
call.
-.PP
+.P
The function
.BR catclose ()
returns 0 on success, or \-1 on failure.
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "double cbrt(double " x );
.BI "float cbrtf(float " x );
.BI "long double cbrtl(long double " x );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR cbrt ():
.nf
_ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
|| /* Since glibc 2.19: */ _DEFAULT_SOURCE
|| /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
.fi
-.PP
+.P
.BR cbrtf (),
.BR cbrtl ():
.nf
.SH RETURN VALUE
These functions return the cube root of
.IR x .
-.PP
+.P
If
.I x
is +0, \-0, positive infinity, negative infinity, or NaN,
.SH SYNOPSIS
.nf
.B #include <complex.h>
-.PP
+.P
.BI "double complex ccos(double complex " z );
.BI "float complex ccosf(float complex " z );
.BI "long double complex ccosl(long double complex " z );
.SH DESCRIPTION
These functions calculate the complex cosine of
.IR z .
-.PP
+.P
The complex cosine function is defined as:
-.PP
+.P
.in +4n
.EX
ccos(z) = (exp(i * z) + exp(\-i * z)) / 2
.SH SYNOPSIS
.nf
.B #include <complex.h>
-.PP
+.P
.BI "double complex ccosh(double complex " z );
.BI "float complex ccoshf(float complex " z );
.BI "long double complex ccoshl(long double complex " z );
.SH DESCRIPTION
These functions calculate the complex hyperbolic cosine of
.IR z .
-.PP
+.P
The complex hyperbolic cosine function is defined as:
-.PP
+.P
.in +4n
.EX
ccosh(z) = (exp(z)+exp(\-z))/2
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "double ceil(double " x );
.BI "float ceilf(float " x );
.BI "long double ceill(long double " x );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR ceilf (),
.BR ceill ():
.nf
.SH DESCRIPTION
These functions return the smallest integral value that is not less than
.IR x .
-.PP
+.P
For example,
.I ceil(0.5)
is 1.0, and
.SH RETURN VALUE
These functions return the ceiling of
.IR x .
-.PP
+.P
If
.I x
is integral, +0, \-0, NaN, or infinite,
C11, POSIX.1-2008.
.SH HISTORY
C99, POSIX.1-2001.
-.PP
+.P
The variant returning
.I double
also conforms to
and the number of mantissa bits
including the implicit bit
is 24 (respectively, 53).)
-.PP
+.P
The integral value returned by these functions may be too large
to store in an integer type
.RI ( int ,
.SH SYNOPSIS
.nf
.B #include <complex.h>
-.PP
+.P
.BI "double complex cexp(double complex " z );
.BI "float complex cexpf(float complex " z );
.BI "long double complex cexpl(long double complex " z );
These functions calculate e (2.71828..., the base of natural logarithms)
raised to the power of
.IR z .
-.PP
+.P
One has:
-.PP
+.P
.in +4n
.EX
cexp(I * z) = ccos(z) + I * csin(z)
.SH SYNOPSIS
.nf
.B #include <complex.h>
-.PP
+.P
.BI "double complex cexp2(double complex " z );
.BI "float complex cexp2f(float complex " z );
.BI "long double complex cexp2l(long double complex " z );
.IR z .
.SH STANDARDS
These function names are reserved for future use in C99.
-.PP
+.P
As at glibc 2.31, these functions are not provided in glibc.
.\" But reserved in NAMESPACE.
.SH SEE ALSO
.RI ( libc ", " \-lc )
.SH SYNOPSIS
.nf
-.PP
+.P
.B "#include <stdlib.h>"
-.PP
+.P
/* In SunOS 4 */
.BI "int cfree(void *" ptr );
-.PP
+.P
/* In glibc or FreeBSD libcompat */
.BI "void cfree(void *" ptr );
-.PP
+.P
/* In SCO OpenServer */
.BI "void cfree(char " ptr [. size " * ." num "], unsigned int " num ", \
unsigned int " size );
-.PP
+.P
/* In Solaris watchmalloc.so.1 */
.BI "void cfree(void " ptr [. elsize " * ." nelem "], size_t " nelem ", \
size_t " elsize );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR cfree ():
.nf
Since glibc 2.19:
is a synonym for
.BR free (3),
"added for compatibility with SunOS".
-.PP
+.P
Other systems have other functions with this name.
The declaration is sometimes in
.I <stdlib.h>
.BR cfree (),
apparently as an analog to
.BR calloc (3).
-.PP
+.P
If you need it while porting something, add
-.PP
+.P
.in +4n
.EX
#define cfree(p, n, s) free((p))
.EE
.in
-.PP
+.P
to your file.
-.PP
+.P
A frequently asked question is "Can I use
.BR free (3)
to free memory allocated with
.BR cfree ()?"
Answer: use
.BR free (3).
-.PP
+.P
An SCO manual writes: "The cfree routine is provided for compliance
to the iBCSe2 standard and simply calls free.
The num and size
.SH SYNOPSIS
.nf
.B #include <complex.h>
-.PP
+.P
.BI "double cimag(double complex " z );
.BI "float cimagf(float complex " z );
.BI "long double cimagl(long double complex " z );
.SH DESCRIPTION
These functions return the imaginary part of the complex number
.IR z .
-.PP
+.P
One has:
-.PP
+.P
.in +4n
.EX
z = creal(z) + I * cimag(z)
.SH SYNOPSIS
.nf
.B #include <sys/queue.h>
-.PP
+.P
.B CIRCLEQ_ENTRY(TYPE);
-.PP
+.P
.B CIRCLEQ_HEAD(HEADNAME, TYPE);
.BI "CIRCLEQ_HEAD CIRCLEQ_HEAD_INITIALIZER(CIRCLEQ_HEAD " head );
.BI "void CIRCLEQ_INIT(CIRCLEQ_HEAD *" head );
-.PP
+.P
.BI "int CIRCLEQ_EMPTY(CIRCLEQ_HEAD *" head );
-.PP
+.P
.BI "void CIRCLEQ_INSERT_HEAD(CIRCLEQ_HEAD *" head ,
.BI " struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME );
.BI "void CIRCLEQ_INSERT_TAIL(CIRCLEQ_HEAD *" head ,
.BI " struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME );
.BI "void CIRCLEQ_INSERT_AFTER(CIRCLEQ_HEAD *" head ", struct TYPE *" listelm ,
.BI " struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME );
-.PP
+.P
.BI "struct TYPE *CIRCLEQ_FIRST(CIRCLEQ_HEAD *" head );
.BI "struct TYPE *CIRCLEQ_LAST(CIRCLEQ_HEAD *" head );
.BI "struct TYPE *CIRCLEQ_PREV(struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME );
.BI " struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME );
.BI "struct TYPE *CIRCLEQ_LOOP_NEXT(CIRCLEQ_HEAD *" head ,
.BI " struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME );
-.PP
+.P
.BI "CIRCLEQ_FOREACH(struct TYPE *" var ", CIRCLEQ_HEAD *" head ,
.BI " CIRCLEQ_ENTRY " NAME );
.BI "CIRCLEQ_FOREACH_REVERSE(struct TYPE *" var ", CIRCLEQ_HEAD *" head ,
.BI " CIRCLEQ_ENTRY " NAME );
-.PP
+.P
.BI "void CIRCLEQ_REMOVE(CIRCLEQ_HEAD *" head ", struct TYPE *" elm ,
.BI " CIRCLEQ_ENTRY " NAME );
.fi
.SH DESCRIPTION
These macros define and operate on doubly linked circular queues.
-.PP
+.P
In the macro definitions,
.I TYPE
is the name of a user-defined structure,
A
.I CIRCLEQ_HEAD
structure is declared as follows:
-.PP
+.P
.in +4
.EX
CIRCLEQ_HEAD(HEADNAME, TYPE) head;
.EE
.in
-.PP
+.P
where
.I struct HEADNAME
is the structure to be defined, and
.I struct TYPE
is the type of the elements to be linked into the queue.
A pointer to the head of the queue can later be declared as:
-.PP
+.P
.in +4
.EX
struct HEADNAME *headp;
.EE
.in
-.PP
+.P
(The names
.I head
and
.I headp
are user selectable.)
-.PP
+.P
.BR CIRCLEQ_ENTRY ()
declares a structure that connects the elements in the queue.
-.PP
+.P
.BR CIRCLEQ_HEAD_INITIALIZER ()
evaluates to an initializer for the queue
.IR head .
-.PP
+.P
.BR CIRCLEQ_INIT ()
initializes the queue referenced by
.IR head .
-.PP
+.P
.BR CIRCLEQ_EMPTY ()
evaluates to true if there are no items on the queue.
.SS Insertion
inserts the new element
.I elm
at the head of the queue.
-.PP
+.P
.BR CIRCLEQ_INSERT_TAIL ()
inserts the new element
.I elm
at the end of the queue.
-.PP
+.P
.BR CIRCLEQ_INSERT_BEFORE ()
inserts the new element
.I elm
before the element
.IR listelm .
-.PP
+.P
.BR CIRCLEQ_INSERT_AFTER ()
inserts the new element
.I elm
.SS Traversal
.BR CIRCLEQ_FIRST ()
returns the first item on the queue.
-.PP
+.P
.BR CIRCLEQ_LAST ()
returns the last item on the queue.
-.PP
+.P
.BR CIRCLEQ_PREV ()
returns the previous item on the queue, or
.I &head
if this item is the first one.
-.PP
+.P
.BR CIRCLEQ_NEXT ()
returns the next item on the queue, or
.I &head
if this item is the last one.
-.PP
+.P
.BR CIRCLEQ_LOOP_PREV ()
returns the previous item on the queue.
If
.I elm
is the first element on the queue, the last element is returned.
-.PP
+.P
.BR CIRCLEQ_LOOP_NEXT ()
returns the next item on the queue.
If
.I elm
is the last element on the queue, the first element is returned.
-.PP
+.P
.BR CIRCLEQ_FOREACH ()
traverses the queue referenced by
.I head
is set to
.I &head
if the loop completes normally, or if there were no elements.
-.PP
+.P
.BR CIRCLEQ_FOREACH_REVERSE ()
traverses the queue referenced by
.I head
.BR CIRCLEQ_EMPTY ()
returns nonzero if the queue is empty,
and zero if the queue contains at least one entry.
-.PP
+.P
.BR CIRCLEQ_FIRST (),
.BR CIRCLEQ_LAST (),
.BR CIRCLEQ_LOOP_PREV (),
return a pointer to the first, last, previous, or next
.I TYPE
structure, respectively.
-.PP
+.P
.BR CIRCLEQ_PREV (),
and
.BR CIRCLEQ_NEXT ()
except that if the argument is the first or last element, respectively,
they return
.IR &head .
-.PP
+.P
.BR CIRCLEQ_HEAD_INITIALIZER ()
returns an initializer that can be assigned to the queue
.IR head .
.SH SYNOPSIS
.nf
.B #include <stdlib.h>
-.PP
+.P
.B "int clearenv(void);"
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR clearenv ():
.nf
/* glibc >= 2.19: */ _DEFAULT_SOURCE
.TP
.BR clearenv ()
glibc 2.0.
-.PP
+.P
Various UNIX variants (DG/UX, HP-UX, QNX, ...).
POSIX.9 (bindings for FORTRAN77).
POSIX.1-1996 did not accept
On systems where
.BR clearenv ()
is unavailable, the assignment
-.PP
+.P
.in +4n
.EX
environ = NULL;
.EE
.in
-.PP
+.P
will probably do.
-.PP
+.P
The
.BR clearenv ()
function may be useful in security-conscious applications that want to
.BR exec (3).
The application would do this by first clearing the environment
and then adding select environment variables.
-.PP
+.P
Note that the main effect of
.BR clearenv ()
is to adjust the value of the pointer
.BR environ (7);
this function does not erase the contents of the buffers
containing the environment definitions.
-.PP
+.P
The DG/UX and Tru64 man pages write: If
.I environ
has been modified by anything other than the
functions, then
.BR clearenv ()
will return an error and the process environment will remain unchanged.
-.\" .LP
+.\" .P
.\" HP-UX has a ENOMEM error return.
.SH SEE ALSO
.BR getenv (3),
.SH SYNOPSIS
.nf
.B #include <time.h>
-.PP
+.P
.B clock_t clock(void);
.fi
.SH DESCRIPTION
.B CLOCKS_PER_SEC
equals 1000000 independent
of the actual resolution.
-.PP
+.P
On several other implementations,
the value returned by
.BR clock ()
C11, POSIX.1-2008.
.SH HISTORY
POSIX.1-2001, C89.
-.PP
+.P
In glibc 2.17 and earlier,
.BR clock ()
was implemented on top of
subtract the value returned from a call to
.BR clock ()
at the start of the program to get maximum portability.
-.PP
+.P
Note that the time can wrap around.
On a 32-bit system where
.B CLOCKS_PER_SEC
Standard C library
.RI ( libc ", " \-lc ),
since glibc 2.17
-.PP
+.P
Before glibc 2.17,
Real-time library
.RI ( librt ", " \-lrt )
.SH SYNOPSIS
.B #include <time.h>
.nf
-.PP
+.P
.BI "int clock_getcpuclockid(pid_t " pid ", clockid_t *" clockid );
.fi
-.PP
+.P
.ad l
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR clock_getcpuclockid ():
.nf
_POSIX_C_SOURCE >= 200112L
.BR clock_gettime (2)
to obtain the time on that clock.
An example run is the following:
-.PP
+.P
.in +4n
.EX
.RB "$" " ./a.out 1" " # Show CPU clock of init process"
.SH SYNOPSIS
.nf
.B #include <complex.h>
-.PP
+.P
.BI "double complex clog(double complex " z );
.BI "float complex clogf(float complex " z );
.BI "long double complex clogl(long double complex " z );
These functions calculate the complex natural logarithm of
.IR z ,
with a branch cut along the negative real axis.
-.PP
+.P
The logarithm
.BR clog ()
is the inverse function of the exponential
The imaginary part of
.I y
is chosen in the interval [\-pi,pi].
-.PP
+.P
One has:
-.PP
+.P
.in +4n
.EX
clog(z) = log(cabs(z)) + I * carg(z)
.EE
.in
-.PP
+.P
Note that
.I z
close to zero will cause an overflow.
.nf
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <complex.h>
-.PP
+.P
.BI "double complex clog10(double complex " z );
.BI "float complex clog10f(float complex " z );
.BI "long double complex clog10l(long double complex " z );
The call
.I clog10(z)
is equivalent to:
-.PP
+.P
.in +4n
.EX
clog(z)/log(10)
.EE
.in
-.PP
+.P
or equally:
-.PP
+.P
.in +4n
.EX
log10(cabs(c)) + I * carg(c) / log(10)
.EE
.in
-.PP
+.P
The other functions perform the same task for
.I float
and
.IR "long double" .
-.PP
+.P
Note that
.I z
close to zero will cause an overflow.
GNU.
.SH HISTORY
glibc 2.1.
-.PP
+.P
The identifiers are reserved for future use in C99 and C11.
.SH SEE ALSO
.BR cabs (3),
.SH SYNOPSIS
.nf
.B #include <complex.h>
-.PP
+.P
.BI "double complex clog2(double complex " z );
.BI "float complex clog2f(float complex " z );
.BI "long double complex clog2l(long double complex " z );
.I clog2(z)
is equivalent to
.IR clog(z)/log(2) .
-.PP
+.P
The other functions perform the same task for
.I float
and
.IR "long double" .
-.PP
+.P
Note that
.I z
close to zero will cause an overflow.
None.
.SH HISTORY
These function names are reserved for future use in C99.
-.PP
+.P
Not yet in glibc, as at glibc 2.19.
.\" But reserved in NAMESPACE.
.SH SEE ALSO
.nf
.B #include <sys/types.h>
.B #include <dirent.h>
-.PP
+.P
.BI "int closedir(DIR *" dirp );
.fi
.SH DESCRIPTION
.SH SYNOPSIS
.nf
.B #include <sys/socket.h>
-.PP
+.P
.BI "struct cmsghdr *CMSG_FIRSTHDR(struct msghdr *" msgh );
.BI "struct cmsghdr *CMSG_NXTHDR(struct msghdr *" msgh ,
.BR " struct cmsghdr *" cmsg );
and received by calling
.BR recvmsg (2).
See their manual pages for more information.
-.PP
+.P
Ancillary data is a sequence of
.I cmsghdr
structures with appended data.
.IR /proc/sys/net/core/optmem_max ;
see
.BR socket (7).
-.PP
+.P
The
.I cmsghdr
structure is defined as follows:
-.PP
+.P
.in +4n
.EX
struct cmsghdr {
};
.EE
.in
-.PP
+.P
The sequence of
.I cmsghdr
structures should never be accessed directly.
It takes the data length as an argument.
This is a constant
expression.
-.PP
+.P
To create ancillary data, first initialize the
.I msg_controllen
member of the
.SH VERSIONS
For portability, ancillary data should be accessed using only the macros
described here.
-.PP
+.P
In Linux,
.BR CMSG_LEN (),
.BR CMSG_DATA (),
.SH HISTORY
This ancillary data model conforms to the POSIX.1g draft, 4.4BSD-Lite,
the IPv6 advanced API described in RFC\ 2292 and SUSv2.
-.PP
+.P
.BR CMSG_SPACE ()
and
.BR CMSG_LEN ()
This code looks for the
.B IP_TTL
option in a received ancillary buffer:
-.PP
+.P
.in +4n
.EX
struct msghdr msgh;
}
.EE
.in
-.PP
+.P
The code below passes an array of file descriptors over a
UNIX domain socket using
.BR SCM_RIGHTS :
-.PP
+.P
.in +4n
.EX
struct msghdr msg = { 0 };
memcpy(CMSG_DATA(cmsg), myfds, sizeof(myfds));
.EE
.in
-.PP
+.P
For a complete code example that shows passing of file descriptors
over a UNIX domain socket, see
.BR seccomp_unotify (2).
.SH SEE ALSO
.BR recvmsg (2),
.BR sendmsg (2)
-.PP
+.P
RFC\ 2292
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.BI "size_t confstr(int " "name" ", char " buf [. size "], size_t " size );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR confstr ():
.nf
_POSIX_C_SOURCE >= 2 || _XOPEN_SOURCE
.SH DESCRIPTION
.BR confstr ()
gets the value of configuration-dependent string variables.
-.PP
+.P
The
.I name
argument is the system variable to be queried.
.B PATH
variable which indicates where all the POSIX.2 standard utilities can
be found.
-.PP
+.P
If
.I buf
is not NULL and
.BR confstr ()
against
.IR size .
-.PP
+.P
If
.I size
is zero and
which means that the value in
.I buf
is truncated.
-.PP
+.P
If
.I name
is a valid configuration variable,
.SH EXAMPLES
The following code fragment determines the path where to find
the POSIX.2 system utilities:
-.PP
+.P
.in +4n
.EX
char *pathbuf;
.SH SYNOPSIS
.nf
.B #include <complex.h>
-.PP
+.P
.BI "double complex conj(double complex " z );
.BI "float complex conjf(float complex " z );
.BI "long double complex conjl(long double complex " z );
These functions return the complex conjugate value of
.IR z .
That is the value obtained by changing the sign of the imaginary part.
-.PP
+.P
One has:
-.PP
+.P
.in +4n
.EX
cabs(z) = csqrt(z * conj(z))
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "double copysign(double " x ", double " y );
.BI "float copysignf(float " x ", float " y );
.BI "long double copysignl(long double " x ", long double " y );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR copysign (),
.BR copysignf (),
.BR copysignl ():
.IR x ,
but whose sign bit matches that of
.IR y .
-.PP
+.P
For example,
.I "copysign(42.0,\ \-1.0)"
and
.I x
and whose sign is taken from
.IR y .
-.PP
+.P
If
.I x
is a NaN,
these functions may treat a negative zero as positive.
.SH STANDARDS
C11, POSIX.1-2008.
-.PP
+.P
This function is defined in IEC 559 (and the appendix with
recommended functions in IEEE 754/IEEE 854).
.SH HISTORY
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "double cos(double " x );
.BI "float cosf(float " x );
.BI "long double cosl(long double " x );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR cosf (),
.BR cosl ():
.nf
.SH RETURN VALUE
On success, these functions return the cosine of
.IR x .
-.PP
+.P
If
.I x
is a NaN, a NaN is returned.
-.PP
+.P
If
.I x
is positive infinity or negative infinity,
.BR math_error (7)
for information on how to determine whether an error has occurred
when calling these functions.
-.PP
+.P
The following errors can occur:
.TP
Domain error: \fIx\fP is an infinity
C11, POSIX.1-2008.
.SH HISTORY
C89, POSIX.1-2001.
-.PP
+.P
The variant returning
.I double
also conforms to
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "double cosh(double " x );
.BI "float coshf(float " x );
.BI "long double coshl(long double " x );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR coshf (),
.BR coshl ():
.nf
These functions return the hyperbolic cosine of
.IR x ,
which is defined mathematically as:
-.PP
+.P
.in +4n
.EX
cosh(x) = (exp(x) + exp(\-x)) / 2
.SH RETURN VALUE
On success, these functions return the hyperbolic cosine of
.IR x .
-.PP
+.P
If
.I x
is a NaN, a NaN is returned.
-.PP
+.P
If
.I x
is +0 or \-0, 1 is returned.
-.PP
+.P
If
.I x
is positive infinity or negative infinity,
positive infinity is returned.
-.PP
+.P
If the result overflows,
a range error occurs,
and the functions return
.BR math_error (7)
for information on how to determine whether an error has occurred
when calling these functions.
-.PP
+.P
The following errors can occur:
.TP
Range error: result overflow
C11, POSIX.1-2008.
.SH HISTORY
C99, POSIX.1-2001.
-.PP
+.P
The variant returning
.I double
also conforms to
.SH SYNOPSIS
.nf
.B #include <complex.h>
-.PP
+.P
.BI "double complex cpow(double complex " x ", double complex " z );
.BI "float complex cpowf(float complex " x ", float complex " z );
.BI "long double complex cpowl(long double complex " x ,
.SH SYNOPSIS
.nf
.B #include <complex.h>
-.PP
+.P
.BI "double complex cproj(double complex " z ");"
.BI "float complex cprojf(float complex " z ");"
.BI "long double complex cprojl(long double complex " z ");"
.SH HISTORY
glibc 2.1.
C99, POSIX.1-2001.
-.PP
+.P
In glibc 2.11 and earlier, the implementation does something different
(a
.I stereographic
.SH SYNOPSIS
.nf
.B #include <complex.h>
-.PP
+.P
.BI "double creal(double complex " z );
.BI "float crealf(float complex " z );
.BI "long double creall(long double complex " z );
.SH DESCRIPTION
These functions return the real part of the complex number
.IR z .
-.PP
+.P
One has:
-.PP
+.P
.nf
z = creal(z) + I * cimag(z)
.fi
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.BI "char *crypt(const char *" key ", const char *" salt );
-.PP
+.P
.B #include <crypt.h>
-.PP
+.P
.BI "char *crypt_r(const char *" key ", const char *" salt ,
.BI " struct crypt_data *restrict " data );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR crypt ():
.nf
Since glibc 2.28:
glibc 2.27 and earlier:
_XOPEN_SOURCE
.fi
-.PP
+.P
.BR crypt_r ():
.nf
_GNU_SOURCE
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.
-.PP
+.P
.I key
is a user's typed password.
-.PP
+.P
.I salt
is a two-character string chosen from the set
[\fBa\-zA\-Z0\-9./\fP].
This string is used to
perturb the algorithm in one of 4096 different ways.
-.PP
+.P
By taking the lowest 7 bits of each of the first eight characters of the
.IR key ,
a 56-bit key is obtained.
characters (the first two characters represent the salt itself).
The return value points to static data whose content is
overwritten by each call.
-.PP
+.P
Warning: the key space consists of
.if t 2\s-2\u56\s0\d
.if n 2**56
.BR passwd (1)
program that checks for crackable passwords during the selection process is
recommended.
-.PP
+.P
The DES algorithm itself has a few quirks which make the use of the
.BR crypt ()
interface a very poor choice for anything other than password
.BR crypt ()
interface for a cryptography project, don't do it: get a good book on
encryption and one of the widely available DES libraries.
-.PP
+.P
.BR crypt_r ()
is a reentrant version of
.BR crypt ().
.BR crypt ()
function was not implemented, probably because of U.S.A. export restrictions.
.\" This level of detail is not necessary in this man page. . .
-.\" .PP
+.\" .P
.\" When encrypting a plain text P using DES with the key K results in the
.\" encrypted text C, then the complementary plain text P' being encrypted
.\" using the complementary key K' will result in the complementary encrypted
.\" text C'.
-.\" .PP
+.\" .P
.\" Weak keys are keys which stay invariant under the DES key transformation.
.\" The four known weak keys 0101010101010101, fefefefefefefefe,
.\" 1f1f1f1f0e0e0e0e and e0e0e0e0f1f1f1f1 must be avoided.
-.\" .PP
+.\" .P
.\" There are six known half weak key pairs, which keys lead to the same
.\" encrypted data. Keys which are part of such key clusters should be
.\" avoided.
.\" Sorry, I could not find out what they are.
.\""
-.\" .PP
+.\" .P
.\" Heavily redundant data causes trouble with DES encryption, when used in the
.\" .I codebook
.\" mode that
.\" .BR crypt ()
.\" interface should be used only for its intended purpose of password
.\" verification, and should not be used as part of a data encryption tool.
-.\" .PP
+.\" .P
.\" The first and last three output bits of the fourth S-box can be
.\" represented as function of their input bits. Empiric studies have
.\" shown that S-boxes partially compute the same output for similar input.
.\" It is suspected that this may contain a back door which could allow the
.\" NSA to decrypt DES encrypted data.
-.\" .PP
+.\" .P
.\" Making encrypted data computed using crypt() publicly available has
.\" to be considered insecure for the given reasons.
.TP
.SS Features in glibc
The glibc version of this function supports additional
hashing algorithms.
-.PP
+.P
If
.I salt
is a character string starting with the characters "$\fIid\fP$"
followed by a string optionally terminated by "$",
then the result has the form:
.RS
-.PP
+.P
$\fIid\fP$\fIsalt\fP$\fIhashed\fP
.RE
-.PP
+.P
.I id
identifies the hashing method used instead of DES and this
then determines how the rest of the password string is interpreted.
6 SHA-512 (since glibc 2.7)
.TE
.RE
-.PP
+.P
Thus, $5$\fIsalt\fP$\fIhashed\fP and $6$\fIsalt\fP$\fIhashed\fP
contain the password hashed with, respectively, functions
based on SHA-256 and SHA-512.
-.PP
+.P
"\fIsalt\fP" stands for the up to 16 characters
following "$\fIid\fP$" in the salt.
The "\fIhashed\fP"
SHA-512 86 characters
.TE
.RE
-.PP
+.P
The characters in "\fIsalt\fP" and "\fIhashed\fP" are drawn from the set
[\fBa\-zA\-Z0\-9./\fP].
In the MD5 and SHA implementations the entire
.I key
is significant (instead of only the first
8 bytes in DES).
-.PP
+.P
Since glibc 2.7,
.\" glibc commit 9425cb9eea6a62fc21d99aafe8a60f752b934b05
the SHA-256 and SHA-512 implementations support a user-supplied number of
followed by "rounds=\fIxxx\fP$", where \fIxxx\fP is an integer, then the
result has the form
.RS
-.PP
+.P
$\fIid\fP$\fIrounds=yyy\fP$\fIsalt\fP$\fIhashed\fP
.RE
-.PP
+.P
where \fIyyy\fP is the number of hashing rounds actually used.
The number of rounds actually used is 1000 if
.I xxx
.SH SYNOPSIS
.nf
.B #include <complex.h>
-.PP
+.P
.BI "double complex csin(double complex " z );
.BI "float complex csinf(float complex " z );
.BI "long double complex csinl(long double complex " z );
.SH DESCRIPTION
These functions calculate the complex sine of
.IR z .
-.PP
+.P
The complex sine function is defined as:
-.PP
+.P
.in +4n
.EX
csin(z) = (exp(i * z) \- exp(\-i * z)) / (2 * i)
.SH SYNOPSIS
.nf
.B #include <complex.h>
-.PP
+.P
.BI "double complex csinh(double complex " z );
.BI "float complex csinhf(float complex " z );
.BI "long double complex csinhl(long double complex " z );
.SH DESCRIPTION
These functions calculate the complex hyperbolic sine of
.IR z .
-.PP
+.P
The complex hyperbolic sine function is defined as:
-.PP
+.P
.in +4n
.EX
csinh(z) = (exp(z)\-exp(\-z))/2
.SH SYNOPSIS
.nf
.B #include <complex.h>
-.PP
+.P
.BI "double complex csqrt(double complex " z );
.BI "float complex csqrtf(float complex " z );
.BI "long double complex csqrtl(long double complex " z );
.SH SYNOPSIS
.nf
.B #include <complex.h>
-.PP
+.P
.BI "double complex ctan(double complex " z );
.BI "float complex ctanf(float complex " z );
.BI "long double complex ctanl(long double complex " z );
.SH DESCRIPTION
These functions calculate the complex tangent of
.IR z .
-.PP
+.P
The complex tangent function is defined as:
-.PP
+.P
.in +4n
.EX
ctan(z) = csin(z) / ccos(z)
.SH SYNOPSIS
.nf
.B #include <complex.h>
-.PP
+.P
.BI "double complex ctanh(double complex " z );
.BI "float complex ctanhf(float complex " z );
.BI "long double complex ctanhl(long double complex " z );
.SH DESCRIPTION
These functions calculate the complex hyperbolic tangent of
.IR z .
-.PP
+.P
The complex hyperbolic tangent function is defined
mathematically as:
-.PP
+.P
.in +4n
.EX
ctanh(z) = csinh(z) / ccosh(z)
.B #include <stdio.h>
.\" POSIX also requires this function to be declared in <unistd.h>,
.\" and glibc does so if suitable feature test macros are defined.
-.PP
+.P
.BI "char *ctermid(char *" "s" );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR ctermid ():
.nf
_POSIX_C_SOURCE
The returned pathname may not uniquely identify the controlling
terminal; it may, for example, be
.IR /dev/tty .
-.PP
+.P
It is not assured that the program can open the terminal.
.\" in glibc 2.3.x, x >= 4, the glibc headers threw an error
.\" if ctermid() was given an argument; fixed in glibc 2.4.
.SH SYNOPSIS
.nf
.B #include <time.h>
-.PP
+.P
.BI "char *asctime(const struct tm *" tm );
.BI "char *asctime_r(const struct tm *restrict " tm ,
.BI " char " buf "[restrict 26]);"
-.PP
+.P
.BI "char *ctime(const time_t *" timep );
.BI "char *ctime_r(const time_t *restrict " timep ,
.BI " char " buf "[restrict 26]);"
-.PP
+.P
.BI "struct tm *gmtime(const time_t *" timep );
.BI "struct tm *gmtime_r(const time_t *restrict " timep ,
.BI " struct tm *restrict " result );
-.PP
+.P
.BI "struct tm *localtime(const time_t *" timep );
.BI "struct tm *localtime_r(const time_t *restrict " timep ,
.BI " struct tm *restrict " result );
-.PP
+.P
.BI "time_t mktime(struct tm *" tm );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR asctime_r (),
.BR ctime_r (),
.BR gmtime_r (),
an argument of data type \fItime_t\fP, 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).
-.PP
+.P
The
.BR asctime ()
and
functions both take an argument
representing broken-down time, which is a representation
separated into year, month, day, and so on.
-.PP
+.P
Broken-down time is stored in the structure
.IR tm ,
described in
.BR tm (3type).
-.PP
+.P
The call
.BI ctime( t )
is equivalent to
.BI asctime(localtime( t )) \fR.
It converts the calendar time \fIt\fP into a
null-terminated string of the form
-.PP
+.P
.in +4n
.EX
"Wed Jun 30 21:49:08 1993\en"
.EE
.in
-.PP
+.P
The abbreviations for the days of the week are "Sun", "Mon", "Tue", "Wed",
"Thu", "Fri", and "Sat".
The abbreviations for the months are "Jan",
which should have room for at least 26 bytes.
It need not
set \fItzname\fP, \fItimezone\fP, and \fIdaylight\fP.
-.PP
+.P
The
.BR gmtime ()
function converts the calendar time \fItimep\fP to
.BR gmtime_r ()
function does the same, but stores the data in a
user-supplied struct.
-.PP
+.P
The
.BR localtime ()
function converts the calendar time \fItimep\fP to
function does the same, but stores the data in a
user-supplied struct.
It need not set \fItzname\fP, \fItimezone\fP, and \fIdaylight\fP.
-.PP
+.P
The
.BR asctime ()
function converts the broken-down time value
.BR asctime_r ()
function does the same, but stores the string in
a user-supplied buffer which should have room for at least 26 bytes.
-.PP
+.P
The
.BR mktime ()
function converts a broken-down time structure, expressed
.BR mktime ()
should (use timezone information and system databases to)
attempt to determine whether DST is in effect at the specified time.
-.PP
+.P
The
.BR mktime ()
function modifies the fields of the
.BR mktime ()
also sets the external variable \fItzname\fP with
information about the current timezone.
-.PP
+.P
If the specified broken-down
time cannot be represented as calendar time (seconds since the Epoch),
.BR mktime ()
.BR localtime ()
return a pointer to a
.IR "struct\ tm" .
-.PP
+.P
On success,
.BR gmtime_r ()
and
.BR localtime_r ()
return the address of the structure pointed to by
.IR result .
-.PP
+.P
On success,
.BR asctime ()
and
.BR ctime ()
return a pointer to a string.
-.PP
+.P
On success,
.BR asctime_r ()
and
.BR ctime_r ()
return a pointer to the string pointed to by
.IR buf .
-.PP
+.P
On success,
.BR mktime ()
returns the calendar time (seconds since the Epoch),
expressed as a value of type
.IR time_t .
-.PP
+.P
On error,
.BR mktime ()
returns the value
to be
.IR restrict ;
that is specific to glibc.
-.PP
+.P
In many implementations, including glibc, a 0 in
.I tm_mday
is interpreted as meaning the last day of the preceding month.
-.PP
+.P
According to POSIX.1-2001,
.BR localtime ()
is required to behave as though
and
.BR localtime_r (),
are specified by SUSv2.
-.PP
+.P
POSIX.1-2001 says:
"The
.BR asctime (),
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.BI "int daemon(int " nochdir ", int " noclose );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR daemon ():
.nf
Since glibc 2.21:
.BR daemon ()
function is for programs wishing to detach themselves from the
controlling terminal and run in the background as system daemons.
-.PP
+.P
If
.I nochdir
is zero,
changes the process's current working directory
to the root directory ("/");
otherwise, the current working directory is left unchanged.
-.PP
+.P
If
.I noclose
is zero,
.TE
.SH VERSIONS
A similar function appears on the BSDs.
-.PP
+.P
The glibc implementation can also return \-1 when
.I /dev/null
exists but is not a character device with the expected
.B #include <limits.h>
.B #include <db.h>
.B #include <fcntl.h>
-.PP
+.P
.BI "DB *dbopen(const char *" file ", int " flags ", int " mode \
", DBTYPE " type ,
.BI " const void *" openinfo );
Probably, you are looking for the APIs provided by the
.I libdb
library instead.
-.PP
+.P
.BR dbopen ()
is the library interface to database files.
The supported file formats are btree, hashed, and UNIX file oriented.
.BR hash (3),
and
.BR recno (3).
-.PP
+.P
.BR dbopen ()
opens
.I file
the
.I file
argument to NULL.
-.PP
+.P
The
.I flags
and
.\"DB_TXN
.\"Support transactions in the database.
.\"The DB_LOCK and DB_SHMEM flags must be set as well.
-.PP
+.P
The
.I type
argument is of type
.BR DB_HASH ,
or
.BR DB_RECNO .
-.PP
+.P
The
.I openinfo
argument is a pointer to an access-method-specific structure described
.I openinfo
is NULL, each access method will use defaults appropriate for the system
and the access method.
-.PP
+.P
.BR dbopen ()
returns a pointer to a
.I DB
.I <db.h>
include file, and contains at
least the following fields:
-.PP
+.P
.in +4n
.EX
typedef struct {
} DB;
.EE
.in
-.PP
+.P
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
.SS 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:
-.PP
+.P
.in +4n
.EX
typedef struct {
} DBT;
.EE
.in
-.PP
+.P
The elements of the
.I DBT
structure are defined as follows:
.TP
.I size
The length of the byte string.
-.PP
+.P
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.
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.
-.PP
+.P
The
.I close
routines may fail and set
.BR free (3),
or
.BR fsync (2).
-.PP
+.P
The
.IR del ,
.IR get ,
.BR free (3),
or
.BR malloc (3).
-.PP
+.P
The
.I fd
routines will fail and set
to
.B ENOENT
for in memory databases.
-.PP
+.P
The
.I sync
routines may fail and set
.I 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.
-.PP
+.P
The file descriptor interface is a kludge and will be deleted in a
future version of the interface.
-.PP
+.P
None of the access methods provide any form of concurrent access,
locking, or transactions.
.SH SEE ALSO
.BR hash (3),
.BR mpool (3),
.BR recno (3)
-.PP
+.P
.IR "LIBTP: Portable, Modular Transactions for UNIX" ,
Margo Seltzer, Michael Olson, USENIX proceedings, Winter 1992.
.\" Sun version
.\" .B #include <des_crypt.h>
.B #include <rpc/des_crypt.h>
-.PP
+.P
.BI "[[deprecated]] int ecb_crypt(char *" key ", char " data [. datalen ],
.BI " unsigned int " datalen ", \
unsigned int " mode );
.BI " unsigned int " datalen ", \
unsigned int " mode ,
.BI " char *" ivec );
-.PP
+.P
.BI "[[deprecated]] void des_setparity(char *" key );
-.PP
+.P
.BI "[[deprecated]] int DES_FAILED(int " status );
.fi
.SH DESCRIPTION
substitutions of blocks.
Also, regularities in the clear text will
not appear in the cipher text.
-.PP
+.P
Here is how to use these routines.
The first argument,
.IR key ,
.TP
.B DESERR_BADPARAM
Bad argument to routine.
-.PP
+.P
Given a result status
.IR stat ,
the macro
4.3BSD.
glibc 2.1.
Removed in glibc 2.28.
-.PP
+.P
Because they employ the DES block cipher,
which is no longer considered secure,
these functions were removed.
.SH SYNOPSIS
.nf
.B #include <time.h>
-.PP
+.P
.BI "double difftime(time_t " time1 ", time_t " time0 );
.fi
.SH DESCRIPTION
.I time_t
is an arithmetic type, and one could just
define
-.PP
+.P
.in +4n
.EX
#define my_difftime(t1,t0) (double)(t1 \- t0)
.EE
.in
-.PP
+.P
when the possible overflow in the subtraction is not a concern.
.SH SEE ALSO
.BR date (1),
.nf
.B #include <sys/types.h>
.B #include <dirent.h>
-.PP
+.P
.BI "int dirfd(DIR *" dirp );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR dirfd ():
.nf
/* Since glibc 2.10: */ _POSIX_C_SOURCE >= 200809L
.BR dirfd ()
returns the file descriptor associated with the directory stream
.IR dirp .
-.PP
+.P
This file descriptor is the one used internally by the directory stream.
As a result, it is useful only for functions which do not depend on
or alter the file position, such as
.SH SYNOPSIS
.nf
.B #include <stdlib.h>
-.PP
+.P
.BI "div_t div(int " numerator ", int " denominator );
.BI "ldiv_t ldiv(long " numerator ", long " denominator );
.BI "lldiv_t lldiv(long long " numerator ", long long " denominator );
-.PP
+.P
.B #include <inttypes.h>
-.PP
+.P
.BI "imaxdiv_t imaxdiv(intmax_t " numerator ", intmax_t " denominator );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR lldiv ():
.nf
_ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
two integer members (in unspecified order) named \fIquot\fP and \fIrem\fP.
The quotient is rounded toward zero.
The result satisfies \fIquot\fP*\fIdenominator\fP+\fIrem\fP = \fInumerator\fP.
-.PP
+.P
The
.BR ldiv (),
.BR lldiv (),
C11, POSIX.1-2008.
.SH HISTORY
POSIX.1-2001, C89, C99, SVr4, 4.3BSD.
-.PP
+.P
.BR lldiv ()
and
.BR imaxdiv ()
were added in C99.
.SH EXAMPLES
After
-.PP
+.P
.in +4n
.EX
div_t q = div(\-5, 3);
.EE
.in
-.PP
+.P
the values \fIq.quot\fP and \fIq.rem\fP are \-1 and \-2, respectively.
.SH SEE ALSO
.BR abs (3),
.nf
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <link.h>
-.PP
+.P
.B int dl_iterate_phdr(
.BI " int (*" callback ")(struct dl_phdr_info *" info ,
.BI " size_t " size ", void *" data ),
function allows an application to inquire at run time to find
out which shared objects it has loaded,
and the order in which they were loaded.
-.PP
+.P
The
.BR dl_iterate_phdr ()
function walks through the list of an
until either all shared objects have been processed or
.I callback
returns a nonzero value.
-.PP
+.P
Each call to
.I callback
receives three arguments:
.IR data )
in the call to
.BR dl_iterate_phdr ().
-.PP
+.P
The
.I info
argument is a structure of the following type:
-.PP
+.P
.in +4n
.EX
struct dl_phdr_info {
};
.EE
.in
-.PP
+.P
(The
.IR ElfW ()
macro definition turns its argument into the name of an ELF data
Further information on these types can be found in the
.IR <elf.h> " and " <link.h>
header files.)
-.PP
+.P
The
.I dlpi_addr
field indicates the base address of the shared object
.I dlpi_name
field is a null-terminated string giving the pathname
from which the shared object was loaded.
-.PP
+.P
To understand the meaning of the
.I dlpi_phdr
and
The
.I dlpi_phnum
field indicates the size of this array.
-.PP
+.P
These program headers are structures of the following form:
-.PP
+.P
.in +4n
.EX
typedef struct {
} Elf32_Phdr;
.EE
.in
-.PP
+.P
Note that we can calculate the location of a particular program header,
.IR x ,
in virtual memory using the formula:
-.PP
+.P
.in +4n
.EX
addr == info\->dlpi_addr + info\->dlpi_phdr[x].p_vaddr;
.EE
.in
-.PP
+.P
Possible values for
.I p_type
include the following (see
.I <elf.h>
for further details):
-.PP
+.P
.in +4n
.EX
#define PT_LOAD 1 /* Loadable program segment */
and
.I dlpi_phnum
in addition to other implementation-specific fields.
-.PP
+.P
Future versions of the C library may add further fields to the
.I dl_phdr_info
structure; in that event, the
For each shared object, the program lists some information
(virtual address, size, flags, and type)
for each of the objects ELF segments.
-.PP
+.P
The following shell session demonstrates the output
produced by the program on an x86-64 system.
The first shared object for which output is displayed
(where the name is an empty string)
is the main program.
-.PP
+.P
.in +4n
.EX
$ \fB./a.out\fP
.BR dlopen (3),
.BR elf (5),
.BR ld.so (8)
-.PP
+.P
.IR "Executable and Linking Format Specification" ,
available at various locations online.
.nf
.B #define _GNU_SOURCE
.B #include <dlfcn.h>
-.PP
+.P
.BI "int dladdr(const void *" addr ", Dl_info *" info );
.BI "int dladdr1(const void *" addr ", Dl_info *" info ", void **" extra_info ,
.BI " int " flags );
This information is returned in a
.I Dl_info
structure:
-.PP
+.P
.in +4n
.EX
typedef struct {
} Dl_info;
.EE
.in
-.PP
+.P
If no symbol matching
.I addr
could be found, then
and
.I dli_saddr
are set to NULL.
-.PP
+.P
The function
.BR dladdr1 ()
is like
and
.I info\->dli_saddr
fields are set to NULL.
-.PP
+.P
If the address specified in
.I addr
could not be matched to a shared object, then these functions return 0.
.TP
.BR dladdr1 ()
glibc 2.3.3.
-.PP
+.P
Solaris.
.SH BUGS
Sometimes, the function pointers you pass to
.BR dladdr (),
even if the function used as an argument should come from
a dynamically linked library.
-.PP
+.P
The problem is that the function pointer will still be resolved
at compile time, but merely point to the
.I plt
.SH SYNOPSIS
.nf
.B #include <dlfcn.h>
-.PP
+.P
.B "char *dlerror(void);"
.fi
.SH DESCRIPTION
The returned string does
.I not
include a trailing newline.
-.PP
+.P
.BR dlerror ()
returns NULL if no errors have occurred since initialization or since
it was last called.
.SH HISTORY
glibc 2.0.
POSIX.1-2001.
-.PP
+.P
SunOS.
.SH NOTES
The message returned by
overwritten by subsequent
.BR dlerror ()
calls.
-.\" .LP
+.\" .P
.\" The string returned by
.\" .BR dlerror ()
.\" should not be modified.
.B #define _GNU_SOURCE
.B #include <link.h>
.B #include <dlfcn.h>
-.PP
+.P
.BR "int dlinfo(void *restrict " handle ", int " request \
", void *restrict " info );
.fi
argument is a pointer to a buffer used to store information
returned by the call; the type of this argument depends on
.IR request .
-.PP
+.P
The following values are supported for
.I request
(with the corresponding type for
.B RTLD_DI_SERINFO
requests to obtain the library search path list for the library.
Here is an example of what we might see when running the program:
-.PP
+.P
.in +4n
.EX
$ \fB./a.out /lib64/libm.so.6\fP
.SH SYNOPSIS
.nf
.B #include <dlfcn.h>
-.PP
+.P
.BI "void *dlopen(const char *" filename ", int " flags );
.BI "int dlclose(void *" handle );
-.PP
+.P
.B #define _GNU_SOURCE
.br
.B #include <dlfcn.h>
-.PP
+.P
.BI "void *dlmopen(Lmid_t " lmid ", const char *" filename ", int " flags );
.fi
.SH DESCRIPTION
.BR dlinfo (3),
and
.BR dlclose ().
-.PP
+.P
If
.I filename
.\" FIXME On Solaris, when handle is NULL, we seem to get back
and
.I /usr/lib
are searched (in that order).
-.PP
+.P
If the object specified by
.I filename
has dependencies on other shared objects,
using the same rules.
(This process may occur recursively,
if those objects in turn have dependencies, and so on.)
-.PP
+.P
One of the following two values must be included in
.IR flags :
.TP
.BR dlopen ()
returns.
If this cannot be done, an error is returned.
-.PP
+.P
Zero or more of the following values may also be ORed in
.IR flags :
.TP
This means that a self-contained object will use
its own symbols in preference to global symbols with the same name
contained in objects that have already been loaded.
-.PP
+.P
If
.I filename
is NULL, then the returned handle is for the main program.
.BR dlopen ()
with the flag
.BR RTLD_GLOBAL .
-.PP
+.P
Symbol references in the shared object are resolved using (in order):
symbols in the link map of objects loaded for the main program and its
dependencies;
flag;
and definitions in the shared object itself
(and any dependencies that were loaded for that object).
-.PP
+.P
Any global symbols in the executable that were placed into
its dynamic symbol table by
.BR ld (1)
or because
.BR ld (1)
noted a dependency on a symbol in another object during static linking.
-.PP
+.P
If the same shared object is opened again with
.BR dlopen (),
the same object handle is returned.
has succeeded on it.
Constructors (see below) are called only when the object is actually loaded
into memory (i.e., when the reference count increases to 1).
-.PP
+.P
A subsequent
.BR dlopen ()
call that loads the same shared object with
.B RTLD_GLOBAL
in a subsequent
.BR dlopen ().
-.PP
+.P
If
.BR dlopen ()
fails for any reason, it returns NULL.
.I flags
arguments, as well as the return value, are the same,
except for the differences noted below.
-.PP
+.P
The
.BR dlmopen ()
function differs from
The
.I Lmid_t
type is an opaque handle that refers to a namespace.
-.PP
+.P
The
.I lmid
argument is either the ID of an existing namespace
The object must have been correctly linked
to reference all of the other shared objects that it requires,
since the new namespace is initially empty.
-.PP
+.P
If
.I filename
is NULL, then the only permitted value for
decrements the reference count on the
dynamically loaded shared object referred to by
.IR handle .
-.PP
+.P
If the object's reference count drops to zero
and no symbols in this object are required by other objects,
then the object is unloaded
because this object was opened with the
.B RTLD_GLOBAL
flag and one of its symbols satisfied a relocation in another object.)
-.PP
+.P
All shared objects that were automatically loaded when
.BR dlopen ()
was invoked on the object referred to by
.I handle
are recursively closed in the same manner.
-.PP
+.P
A successful return from
.BR dlclose ()
does not guarantee that the symbols associated with
(file could not be found, was not readable, had the wrong format,
or caused errors during loading),
these functions return NULL.
-.PP
+.P
On success,
.BR dlclose ()
returns 0; on error, it returns a nonzero value.
-.PP
+.P
Errors from these functions can be diagnosed using
.BR dlerror (3).
.SH ATTRIBUTES
and symbol references are likewise resolved according to the usual rules,
but such resolution is confined to the definitions provided by the
objects that have been (explicitly and implicitly) loaded into the namespace.
-.PP
+.P
The
.BR dlmopen ()
function permits object-load isolation\[em]the ability
This can be achieved by using a separate namespace and the
.B RTLD_GLOBAL
flag.
-.PP
+.P
The
.BR dlmopen ()
function also can be used to provide better isolation than the
.B RTLD_LOCAL
is insufficient to isolate a loaded shared object except in the (uncommon)
case where one has explicit control over all shared object dependencies.
-.PP
+.P
Possible uses of
.BR dlmopen ()
are plugins where the author of the plugin-loading framework
.BR dlmopen (),
this can be achieved by loading the same shared object file into
different namespaces.
-.PP
+.P
The glibc implementation supports a maximum of
.\" DL_NNS
16 namespaces.
info pages (under "Function attributes")
.\" info gcc "C Extensions" "Function attributes"
for further information.
-.PP
+.P
An older method of (partially) achieving the same result is via the use of
two special symbols recognized by the linker:
.B _init
.BR gcc (1)
.I \-nostartfiles
command-line option.
-.PP
+.P
Use of
.B _init
and
.\" .\" void _init(void) __attribute__((constructor));
.\" .\" void _fini(void) __attribute__((destructor));
.\"
-.PP
+.P
Since glibc 2.2.3,
.BR atexit (3)
can be used to register an exit handler that is automatically
.BR cos (3)
function, and prints the cosine of 2.0.
The following is an example of building and running the program:
-.PP
+.P
.in +4n
.EX
$ \fBcc dlopen_demo.c \-ldl\fP
.BR rtld\-audit (7),
.BR ld.so (8),
.BR ldconfig (8)
-.PP
+.P
gcc info pages, ld info pages
.SH SYNOPSIS
.nf
.B #include <dlfcn.h>
-.PP
+.P
.BI "void *dlsym(void *restrict " handle ", const char *restrict " symbol );
-.PP
+.P
.B #define _GNU_SOURCE
.B #include <dlfcn.h>
-.PP
+.P
.BI "void *dlvsym(void *restrict " handle ", const char *restrict " symbol ,
.BI " const char *restrict " version );
.fi
(The search performed by
.BR dlsym ()
is breadth first through the dependency tree of these shared objects.)
-.PP
+.P
In unusual cases (see NOTES) the value of the symbol could actually be NULL.
Therefore, a NULL return from
.BR dlsym ()
.BR dlerror (3)
again, saving its return value into a variable, and check whether
this saved value is not NULL.
-.PP
+.P
There are two special pseudo-handles that may be specified in
.IR handle :
.TP
can find and invoke the "real" function provided in another shared object
(or for that matter, the "next" definition of the function in cases
where there are multiple layers of preloading).
-.PP
+.P
The
.B _GNU_SOURCE
feature test macro must be defined in order to obtain the
.B RTLD_NEXT
from
.IR <dlfcn.h> .
-.PP
+.P
The function
.BR dlvsym ()
does the same as
.SH SYNOPSIS
.nf
.B #include <stdlib.h>
-.PP
+.P
.B double drand48(void);
.BI "double erand48(unsigned short " xsubi [3]);
-.PP
+.P
.B long lrand48(void);
.BI "long nrand48(unsigned short " xsubi [3]);
-.PP
+.P
.B long mrand48(void);
.BI "long jrand48(unsigned short " xsubi [3]);
-.PP
+.P
.BI "void srand48(long " seedval );
.BI "unsigned short *seed48(unsigned short " seed16v [3]);
.BI "void lcong48(unsigned short " param [7]);
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
All functions shown above:
.\" .BR drand48 (),
.\" .BR erand48 (),
.SH DESCRIPTION
These functions generate pseudo-random numbers using the linear congruential
algorithm and 48-bit integer arithmetic.
-.PP
+.P
The
.BR drand48 ()
and
functions return nonnegative
double-precision floating-point values uniformly distributed over the interval
[0.0,\ 1.0).
-.PP
+.P
The
.BR lrand48 ()
and
.BR nrand48 ()
functions return nonnegative
long integers uniformly distributed over the interval [0,\ 2\[ha]31).
-.PP
+.P
The
.BR mrand48 ()
and
.BR jrand48 ()
functions return signed long
integers uniformly distributed over the interval [\-2\[ha]31,\ 2\[ha]31).
-.PP
+.P
The
.BR srand48 (),
.BR seed48 (),
.BR jrand48 ()
do not require
an initialization function to be called first.
-.PP
+.P
All the functions work by generating a sequence of 48-bit integers,
.IR Xi ,
according to the linear congruential formula:
-.PP
+.P
.in +4n
.EX
.B Xn+1 = (aXn + c) mod m, where n >= 0
.EE
.in
-.PP
+.P
The parameter
.I m
= 2\[ha]48, hence 48-bit integer arithmetic is performed.
and
.I c
are given by:
-.PP
+.P
.in +4n
.EX
.B a = 0x5DEECE66D
.B c = 0xB
.EE
.in
-.PP
+.P
The value returned by any of the functions
.BR drand48 (),
.BR erand48 (),
.I Xi
and transformed
into the returned value.
-.PP
+.P
The functions
.BR drand48 (),
.BR lrand48 (),
.I Xi
into the array before calling the function for the first
time.
-.PP
+.P
The initializer function
.BR srand48 ()
sets the high order 32-bits of
.IR seedval .
The low order 16-bits are set
to the arbitrary value 0x330E.
-.PP
+.P
The initializer function
.BR seed48 ()
sets the value of
is copied into an internal buffer and a
pointer to this buffer is returned by
.BR seed48 ().
-.PP
+.P
The initialization function
.BR lcong48 ()
allows the user to specify
MT-Unsafe race:drand48
T}
.TE
-.PP
+.P
The above
functions record global state information for the random number generator,
so they are not thread-safe.
.SH SYNOPSIS
.nf
.B #include <stdlib.h>
-.PP
+.P
.BI "int drand48_r(struct drand48_data *restrict " buffer ,
.BI " double *restrict " result );
.BI "int erand48_r(unsigned short " xsubi [3] ","
.BI " struct drand48_data *restrict "buffer ,
.BI " double *restrict " result ");"
-.PP
+.P
.BI "int lrand48_r(struct drand48_data *restrict " buffer ,
.BI " long *restrict " result );
.BI "int nrand48_r(unsigned short " xsubi[3] ","
.BI " struct drand48_data *restrict "buffer ,
.BI " long *restrict " result ");"
-.PP
+.P
.BI "int mrand48_r(struct drand48_data *restrict " buffer ,
.BI " long *restrict " result ");"
.BI "int jrand48_r(unsigned short " xsubi[3] ","
.BI " struct drand48_data *restrict " buffer ,
.BI " long *restrict " result ");"
-.PP
+.P
.BI "int srand48_r(long int " seedval ", struct drand48_data *" buffer ");"
.BI "int seed48_r(unsigned short " seed16v[3] ", struct drand48_data *" buffer );
.BI "int lcong48_r(unsigned short " param[7] ", struct drand48_data *" buffer );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
All functions shown above:
.\" .BR drand48_r (),
.\" .BR erand48_r (),
Instead of modifying the global random generator state, they use
the supplied data
.IR buffer .
-.PP
+.P
Before the first use, this struct must be initialized, for example,
by filling it with zeros, or by calling one of the functions
.BR srand48_r (),
.SH SYNOPSIS
.nf
.B #include <locale.h>
-.PP
+.P
.BI "locale_t duplocale(locale_t " locobj );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR duplocale ():
.nf
Since glibc 2.10:
.BR duplocale ()
function creates a duplicate of the locale object referred to by
.IR locobj .
-.PP
+.P
If
.I locobj
is
.B LC_GLOBAL_LOCALE
value is converted into a usable locale object.
See EXAMPLES, below.
-.PP
+.P
Each locale object created by
.BR duplocale ()
should be deallocated using
a string of characters that is converted to uppercase and
displayed on standard output.
An example of its use is the following:
-.PP
+.P
.in +4n
.EX
$ \fB./a.out abc\fP
.SH SYNOPSIS
.nf
.B "#include <time.h>"
-.PP
+.P
.BI "int dysize(int " year );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR dysize ():
.nf
Since glibc 2.19:
.SH DESCRIPTION
The function returns 365 for a normal year and 366 for a leap year.
The calculation for leap year is based on:
-.PP
+.P
.in +4n
.EX
(year) %4 == 0 && ((year) %100 != 0 || (year) %400 == 0)
.EE
.in
-.PP
+.P
The formula is defined in the macro
.I __isleap(year)
also found in
None.
.SH HISTORY
SunOS 4.x.
-.PP
+.P
This is a compatibility function only.
Don't use it in new programs.
.\" The SCO version of this function had a year-2000 problem.
.SH SYNOPSIS
.nf
.B #include <stdlib.h>
-.PP
+.P
.BI "[[deprecated]] char *ecvt(double " number ", int " ndigits ,
.BI " int *restrict " decpt ", int *restrict " sign );
.BI "[[deprecated]] char *fcvt(double " number ", int " ndigits ,
.BI " int *restrict " decpt ", int *restrict " sign );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR ecvt (),
.BR fcvt ():
.nf
If
.I number
is zero, it is unspecified whether \fI*decpt\fP is 0 or 1.
-.PP
+.P
The
.BR fcvt ()
function is identical to
.SH SYNOPSIS
.nf
.B #include <stdlib.h>
-.PP
+.P
.BI "[[deprecated]] int ecvt_r(double " number ", int " ndigits ,
.BI " int *restrict " decpt ", int *restrict " sign ,
.BI " char *restrict " buf ", size_t " len );
.BI "[[deprecated]] int fcvt_r(double " number ", int " ndigits ,
.BI " int *restrict " decpt ", int *restrict " sign ,
.BI " char *restrict " buf ", size_t " len );
-.PP
+.P
.BI "[[deprecated]] int qecvt_r(long double " number ", int " ndigits ,
.BI " int *restrict " decpt ", int *restrict " sign ,
.BI " char *restrict " buf ", size_t " len );
.BI " int *restrict " decpt ", int *restrict " sign ,
.BI " char *restrict " buf ", size_t " len );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR ecvt_r (),
.BR fcvt_r (),
.BR qecvt_r (),
.nf
.BR "#define _XOPEN_SOURCE" " /* See feature_test_macros(7) */"
.B #include <unistd.h>
-.PP
+.P
.BI "[[deprecated]] void encrypt(char " block "[64], int " edflag );
-.PP
+.P
.BR "#define _XOPEN_SOURCE" " /* See feature_test_macros(7) */"
.B #include <stdlib.h>
-.PP
+.P
.BI "[[deprecated]] void setkey(const char *" key );
-.PP
+.P
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <crypt.h>
-.PP
+.P
.BI "[[deprecated]] void setkey_r(const char *" key ", struct crypt_data *" data );
.BI "[[deprecated]] void encrypt_r(char *" block ", int " edflag ,
.BI " struct crypt_data *" data );
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.
-.PP
+.P
The
.BR encrypt ()
function modifies the passed buffer, encoding if
.I block
is a bit vector representation of the actual value that is encoded.
The result is returned in that same vector.
-.PP
+.P
These two functions are not reentrant, that is, the key data is
kept in static storage.
The functions
are the reentrant versions.
They use the following
structure to hold the key data:
-.PP
+.P
.in +4n
.EX
struct crypt_data {
};
.EE
.in
-.PP
+.P
Before calling
.BR setkey_r ()
set
None.
.SH HISTORY
Removed in glibc 2.28.
-.PP
+.P
Because they employ the DES block cipher,
which is no longer considered secure,
these functions were removed from glibc.
.SH NOTES
The program must explicitly declare these symbols;
they are not defined in any header file.
-.PP
+.P
On some systems the names of these symbols are preceded by underscores,
thus:
.IR _etext ,
and
.IR _end .
These symbols are also defined for programs compiled on Linux.
-.PP
+.P
At the start of program execution,
the program break will be somewhere near
.I &end
with an argument of zero to find the current value of the program break.
.SH EXAMPLES
When run, the program below produces output such as the following:
-.PP
+.P
.in +4n
.EX
.RB "$" " ./a.out"
.SH SYNOPSIS
.nf
.B #include <endian.h>
-.PP
+.P
.BI "uint16_t htobe16(uint16_t " host_16bits );
.BI "uint16_t htole16(uint16_t " host_16bits );
.BI "uint16_t be16toh(uint16_t " big_endian_16bits );
.BI "uint16_t le16toh(uint16_t " little_endian_16bits );
-.PP
+.P
.BI "uint32_t htobe32(uint32_t " host_32bits );
.BI "uint32_t htole32(uint32_t " host_32bits );
.BI "uint32_t be32toh(uint32_t " big_endian_32bits );
.BI "uint32_t le32toh(uint32_t " little_endian_32bits );
-.PP
+.P
.BI "uint64_t htobe64(uint64_t " host_64bits );
.BI "uint64_t htole64(uint64_t " host_64bits );
.BI "uint64_t be64toh(uint64_t " big_endian_64bits );
.BI "uint64_t le64toh(uint64_t " little_endian_64bits );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
.ad l
-.PP
+.P
.BR htobe16 (),
.BR htole16 (),
.BR be16toh (),
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.
-.PP
+.P
The number,
.IR nn ,
in the name of each function indicates the size of
integer handled by the function, either 16, 32, or 64 bits.
-.PP
+.P
The functions with names of the form "htobe\fInn\fP" convert
from host byte order to big-endian order.
-.PP
+.P
The functions with names of the form "htole\fInn\fP" convert
from host byte order to little-endian order.
-.PP
+.P
The functions with names of the form "be\fInn\fPtoh" convert
from big-endian order to host byte order.
-.PP
+.P
The functions with names of the form "le\fInn\fPtoh" convert
from little-endian order to host byte order.
.SH VERSIONS
None.
.SH HISTORY
glibc 2.9.
-.PP
+.P
These functions are similar to the older
.BR byteorder (3)
family of functions.
.BR be32toh ()
is identical to
.BR ntohl ().
-.PP
+.P
The advantage of the
.BR byteorder (3)
functions is that they are standard functions available
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:
-.PP
+.P
.in +4n
.EX
$ \fB./a.out\fP
.SH SYNOPSIS
.nf
.B #include <envz.h>
-.PP
+.P
.BI "error_t envz_add(char **restrict " envz ", size_t *restrict " envz_len ,
.BI " const char *restrict " name \
", const char *restrict " value );
-.PP
+.P
.BI "char *envz_entry(const char *restrict " envz ", size_t " envz_len ,
.BI " const char *restrict " name );
-.PP
+.P
.BI "char *envz_get(const char *restrict " envz ", size_t " envz_len ,
.BI " const char *restrict " name );
-.PP
+.P
.BI "error_t envz_merge(char **restrict " envz ", size_t *restrict " envz_len ,
.BI " const char *restrict " envz2 ", size_t " envz2_len ,
.BI " int " override );
-.PP
+.P
.BI "void envz_remove(char **restrict " envz ", size_t *restrict " envz_len ,
.BI " const char *restrict " name );
-.PP
+.P
.BI "void envz_strip(char **restrict " envz ", size_t *restrict " envz_len );
.fi
.SH DESCRIPTION
These functions are glibc-specific.
-.PP
+.P
An argz vector is a pointer to a character buffer together with a length,
see
.BR argz_add (3).
to be the value.
If there is no \[aq]=\[aq], the value is taken to be NULL.
(While the value in case of a trailing \[aq]=\[aq] is the empty string "".)
-.PP
+.P
These functions are for handling envz vectors.
-.PP
+.P
.BR envz_add ()
adds the string
.RI \&" name = value \&"
If an entry with the same
.I name
existed, it is removed.
-.PP
+.P
.BR envz_entry ()
looks for
.I name
in the envz vector
.RI ( envz ,\ envz_len )
and returns the entry if found, or NULL if not.
-.PP
+.P
.BR envz_get ()
looks for
.I name
an entry for
.I name
without \[aq]=\[aq] sign.)
-.PP
+.P
.BR envz_merge ()
adds each entry in
.I envz2
will supersede those with the same name in
.IR *envz ,
otherwise not.
-.PP
+.P
.BR envz_remove ()
removes the entry for
.I name
from
.RI ( *envz ,\ *envz_len )
if there was one.
-.PP
+.P
.BR envz_strip ()
removes all entries with value NULL.
.SH RETURN VALUE
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "double erf(double " x );
.BI "float erff(float " x );
.BI "long double erfl(long double " x );
-.PP
+.P
.fi
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR erf ():
.nf
_ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L || _XOPEN_SOURCE
|| /* Since glibc 2.19: */ _DEFAULT_SOURCE
|| /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
.fi
-.PP
+.P
.BR erff (),
.BR erfl ():
.nf
These functions return the error function of
.IR x ,
defined as
-.PP
+.P
.in +4n
.EX
erf(x) = 2/sqrt(pi) * integral from 0 to x of exp(\-t*t) dt
On success, these functions return the value of the error function of
.IR x ,
a value in the range [\-1,\ 1].
-.PP
+.P
If
.I x
is a NaN, a NaN is returned.
-.PP
+.P
If
.I x
is +0 (\-0), +0 (\-0) is returned.
-.PP
+.P
If
.I x
is positive infinity (negative infinity),
+1 (\-1) is returned.
-.PP
+.P
If
.I x
is subnormal,
.BR math_error (7)
for information on how to determine whether an error has occurred
when calling these functions.
-.PP
+.P
The following errors can occur:
.TP
Range error: result underflow (\fIx\fP is subnormal)
An underflow floating-point exception
.RB ( FE_UNDERFLOW )
is raised.
-.PP
+.P
These functions do not set
.IR errno .
.\" It is intentional that these functions do not set errno for this case
C11, POSIX.1-2008.
.SH HISTORY
C99, POSIX.1-2001.
-.PP
+.P
The variant returning
.I double
also conforms to
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "double erfc(double " x );
.BI "float erfcf(float " x );
.BI "long double erfcl(long double " x );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR erfc ():
.nf
_ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L || _XOPEN_SOURCE
|| /* Since glibc 2.19: */ _DEFAULT_SOURCE
|| /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
.fi
-.PP
+.P
.BR erfcf (),
.BR erfcl ():
.nf
On success, these functions return the complementary error function of
.IR x ,
a value in the range [0,2].
-.PP
+.P
If
.I x
is a NaN, a NaN is returned.
-.PP
+.P
If
.I x
is +0 or \-0, 1 is returned.
-.PP
+.P
If
.I x
is positive infinity,
+0 is returned.
-.PP
+.P
If
.I x
is negative infinity,
+2 is returned.
-.PP
+.P
If the function result underflows and produces an unrepresentable value,
the return value is 0.0.
-.PP
+.P
If the function result underflows but produces a representable
(i.e., subnormal) value,
.\" e.g., erfc(27) on x86-32
.BR math_error (7)
for information on how to determine whether an error has occurred
when calling these functions.
-.PP
+.P
The following errors can occur:
.TP
Range error: result underflow (result is subnormal)
An underflow floating-point exception
.RB ( FE_UNDERFLOW )
is raised.
-.PP
+.P
These functions do not set
.IR errno .
.\" It is intentional that these functions do not set errno for this case
C11, POSIX.1-2008.
.SH HISTORY
C99, POSIX.1-2001.
-.PP
+.P
The variant returning
.I double
also conforms to
.SH SYNOPSIS
.nf
.B #include <err.h>
-.PP
+.P
.BI "[[noreturn]] void err(int " eval ", const char *" fmt ", ...);"
.BI "[[noreturn]] void errx(int " eval ", const char *" fmt ", ...);"
-.PP
+.P
.BI "void warn(const char *" fmt ", ...);"
.BI "void warnx(const char *" fmt ", ...);"
-.PP
+.P
.B #include <stdarg.h>
-.PP
+.P
.BI "[[noreturn]] void verr(int " eval ", const char *" fmt ", va_list " args );
.BI "[[noreturn]] void verrx(int " eval ", const char *" fmt ", va_list " args );
-.PP
+.P
.BI "void vwarn(const char *" fmt ", va_list " args );
.BI "void vwarnx(const char *" fmt ", va_list " args );
.fi
.BR printf (3)-like
formatted error message is output.
The output is terminated by a newline character.
-.PP
+.P
The
.BR err (),
.BR verr (),
.I fmt
argument is
NULL.
-.PP
+.P
The
.BR errx ()
and
.BR warnx ()
functions do not append an error message.
-.PP
+.P
The
.BR err (),
.BR verr (),
Display the current
.I errno
information string and exit:
-.PP
+.P
.in +4n
.EX
p = malloc(size);
err(EXIT_FAILURE, "%s", file_name);
.EE
.in
-.PP
+.P
Display an error message and exit:
-.PP
+.P
.in +4n
.EX
if (tm.tm_hour < START_TIME)
start_time_string);
.EE
.in
-.PP
+.P
Warn of an error:
-.PP
+.P
.in +4n
.EX
fd = open(raw_device, O_RDONLY, 0);
.SH SYNOPSIS
.nf
.B #include <errno.h>
-.\".PP
+.\".P
.\".BI "extern int " errno ;
.fi
.SH DESCRIPTION
The value of
.I errno
is never set to zero by any system call or library function.
-.PP
+.P
For some system calls and library functions (e.g.,
.BR getpriority (2)),
\-1 is a valid return on success.
may have occurred, checking to see if
.I errno
has a nonzero value.
-.PP
+.P
.I errno
is defined by the ISO C standard to be a modifiable lvalue
of type
header file defines symbolic names for each
of the possible error numbers that may appear in
.IR errno .
-.PP
+.P
All the error names specified by POSIX.1
must have distinct values, with the exception of
.B EAGAIN
.BR EWOULDBLOCK ,
which may be the same.
On Linux, these two have the same value on all architectures.
-.PP
+.P
The error numbers that correspond to each symbolic name
vary across UNIX systems,
and even across different architectures on Linux.
.BR strerror (3)
functions can be used to convert these names to
corresponding textual error messages.
-.PP
+.P
On any particular Linux system,
one can obtain a list of all symbolic error names and
the corresponding error numbers using the
command (part of the
.I moreutils
package):
-.PP
+.P
.in +4n
.EX
$ \fBerrno \-l\fP
\&...
.EE
.in
-.PP
+.P
The
.BR errno (1)
command can also be used to look up individual error numbers and names,
and to search for errors using strings from the error description,
as in the following examples:
-.PP
+.P
.in +4n
.EX
$ \fBerrno 2\fP
EACCES 13 Permission denied
.EE
.in
-.\".PP
+.\".P
.\" POSIX.1 (2001 edition) lists the following symbolic error names. Of
.\" these, \fBEDOM\fP and \fBERANGE\fP are in the ISO C standard. ISO C
.\" Amendment 1 defines the additional error number \fBEILSEQ\fP for
.TP
.I C99
The name is defined by C99.
-.PP
+.P
Below is a list of the symbolic error names that are defined on Linux:
.TP 16
.B E2BIG
Exchange full.
.SH NOTES
A common mistake is to do
-.PP
+.P
.in +4n
.EX
if (somecall() == \-1) {
}
.EE
.in
-.PP
+.P
where
.I errno
no longer needs to have the value it had upon return from
If the value of
.I errno
should be preserved across a library call, it must be saved:
-.PP
+.P
.in +4n
.EX
if (somecall() == \-1) {
}
.EE
.in
-.PP
+.P
Note that the POSIX threads APIs do
.I not
set
These error numbers have the same meanings as the error numbers returned in
.I errno
by other APIs.
-.PP
+.P
On some ancient systems,
.I <errno.h>
was not present or did not declare
.SH SYNOPSIS
.nf
.B #include <error.h>
-.PP
+.P
.BI "void error(int " status ", int " errnum ", const char *" format ", ...);"
.BI "void error_at_line(int " status ", int " errnum ", const char *" filename ,
.BI " unsigned int " linenum ", const char *" format ", ...);"
-.PP
+.P
.BI "extern unsigned int " error_message_count ;
.BI "extern int " error_one_per_line ;
-.PP
+.P
.BI "extern void (*" error_print_progname ")(void);"
.fi
.SH DESCRIPTION
.I format
in the argument list.
The output is terminated by a newline character.
-.PP
+.P
The program name printed by
.BR error ()
is the value of the global variable
.IR argv[0] .
The value of this variable can be modified to change the output of
.BR error ().
-.PP
+.P
If \fIstatus\fP has a nonzero value, then
.BR error ()
calls
.BR exit (3)
to terminate the program using the given value as the exit status;
otherwise it returns after printing the error message.
-.PP
+.P
The
.BR error_at_line ()
function is exactly the same as
.BR error_at_line (),
but other values can also be used.
For example, these arguments could refer to a location in an input file.
-.PP
+.P
If the global variable \fIerror_one_per_line\fP is set nonzero,
a sequence of
.BR error_at_line ()
calls with the
same value of \fIfilename\fP and \fIlinenum\fP will result in only
one message (the first) being output.
-.PP
+.P
The global variable \fIerror_message_count\fP counts the number of
messages that have been output by
.BR error ()
and
.BR error_at_line ().
-.PP
+.P
If the global variable \fIerror_print_progname\fP
is assigned the address of a function
(i.e., is not NULL), then that function is called
MT-Unsafe\ race: error_at_line/\:error_one_per_line locale
T}
.TE
-.PP
+.P
The internal
.I error_one_per_line
variable is accessed (without any form of synchronization, but since it's an
.SH SYNOPSIS
.nf
.B #include <netinet/ether.h>
-.PP
+.P
.BI "char *ether_ntoa(const struct ether_addr *" addr );
.BI "struct ether_addr *ether_aton(const char *" asc );
-.PP
+.P
.BI "int ether_ntohost(char *" hostname ", const struct ether_addr *" addr );
.BI "int ether_hostton(const char *" hostname ", struct ether_addr *" addr );
-.PP
+.P
.BI "int ether_line(const char *" line ", struct ether_addr *" addr ,
.BI " char *" hostname );
-.PP
+.P
/* GNU extensions */
.BI "char *ether_ntoa_r(const struct ether_addr *" addr ", char *" buf );
-.PP
+.P
.BI "struct ether_addr *ether_aton_r(const char *" asc ,
.BI " struct ether_addr *" addr );
.fi
overwrite.
.BR ether_aton ()
returns NULL if the address is invalid.
-.PP
+.P
The
.BR ether_ntoa ()
function converts the Ethernet host address
hex-digits-and-colons notation, omitting leading zeros.
The string is returned in a statically allocated buffer,
which subsequent calls will overwrite.
-.PP
+.P
The
.BR ether_ntohost ()
function maps an Ethernet address to the
corresponding hostname in
.I /etc/ethers
and returns nonzero if it cannot be found.
-.PP
+.P
The
.BR ether_hostton ()
function maps a hostname to the
corresponding Ethernet address in
.I /etc/ethers
and returns nonzero if it cannot be found.
-.PP
+.P
The
.BR ether_line ()
function parses a line in
.I hostname
must be sufficiently long, for example, have the same length as
.IR line .
-.PP
+.P
The functions
.BR ether_ntoa_r ()
and
and
.BR ether_aton ()
respectively, and do not use static buffers.
-.PP
+.P
The structure
.I ether_addr
is defined in
.I <net/ethernet.h>
as:
-.PP
+.P
.in +4n
.EX
struct ether_addr {
.nf
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <unistd.h>
-.PP
+.P
.BI "int euidaccess(const char *" pathname ", int " mode );
.BI "int eaccess(const char *" pathname ", int " mode );
.fi
performs checks using the real user and group identifiers of the process,
.BR euidaccess ()
uses the effective identifiers.
-.PP
+.P
.I mode
is a mask consisting of one or more of
.BR R_OK ", " W_OK ", " X_OK ", and " F_OK ,
with the same meanings as for
.BR access (2).
-.PP
+.P
.BR eaccess ()
is a synonym for
.BR euidaccess (),
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.
-.PP
+.P
This function always dereferences symbolic links.
If you need to check the permissions on a symbolic link, use
.BR faccessat (2)
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.B extern char **environ;
-.PP
+.P
.BI "int execl(const char *" pathname ", const char *" arg ", ..."
.B " /*, (char *) NULL */);"
.BI "int execlp(const char *" file ", const char *" arg ", ..."
.BI "int execvpe(const char *" file ", char *const " argv \
"[], char *const " envp "[]);"
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR execvpe ():
.nf
_GNU_SOURCE
(See the manual page for
.BR execve (2)
for further details about the replacement of the current process image.)
-.PP
+.P
The initial argument for these functions is the name of a file that is
to be executed.
-.PP
+.P
The functions can be grouped based on the letters following the "exec" prefix.
.\"
.SS l - execl(), execlp(), execle()
be terminated by a null pointer,
and, since these are variadic functions, this pointer must be cast
.IR "(char\ *) NULL" .
-.PP
+.P
By contrast with the 'l' functions, the 'v' functions (below) specify the
command-line arguments of the executed program as a vector.
.\"
argument is an array of pointers to null-terminated strings and
.I must
be terminated by a null pointer.
-.PP
+.P
All other
.BR exec ()
functions (which do not include 'e' in the suffix)
(which typically returns the value "/bin:/usr/bin")
and possibly also the current working directory;
see NOTES for further details.
-.PP
+.P
.BR execvpe ()
searches for the program using the value of
.B PATH
from the caller's environment, not from the
.I envp
argument.
-.PP
+.P
If the specified filename includes a slash character, then
.B PATH
is ignored, and the file at the specified pathname is executed.
-.PP
+.P
In addition, certain errors are treated specially.
-.PP
+.P
If permission is denied for a file (the attempted
.BR execve (2)
failed with the error
.I errno
set to
.BR EACCES .
-.PP
+.P
If the header of a file isn't recognized (the attempted
.BR execve (2)
failed with the error
.RI ( /bin/sh )
with the path of the file as its first argument.
(If this attempt fails, no further searching is done.)
-.PP
+.P
All other
.BR exec ()
functions (which do not include 'p' in the suffix)
from the default search path.
This accidental behavior change is considered mildly beneficial,
and won't be reverted.
-.PP
+.P
The behavior of
.BR execlp ()
and
is encountered.
Linux treats it as a hard
error and returns immediately.
-.PP
+.P
Traditionally, the functions
.BR execlp ()
and
.SH SYNOPSIS
.nf
.B #include <stdlib.h>
-.PP
+.P
.BI "[[noreturn]] void exit(int " status );
.fi
.SH DESCRIPTION
.I status
(i.e., \fIstatus & 0xFF\fP) is returned to the parent (see
.BR wait (2)).
-.PP
+.P
All functions registered with
.BR atexit (3)
and
or
.BR on_exit (3),
then it is called as many times as it was registered.
-.PP
+.P
All open
.BR stdio (3)
streams are flushed and closed.
Files created by
.BR tmpfile (3)
are removed.
-.PP
+.P
The C standard specifies two constants,
\fBEXIT_SUCCESS\fP and \fBEXIT_FAILURE\fP,
that may be passed to
.BR exit ()
T} Thread safety MT-Unsafe race:exit
.TE
-.PP
+.P
The
.BR exit ()
function uses a global variable that is not protected,
.BR atexit (3)
and
.BR on_exit (3).
-.PP
+.P
The use of
.B EXIT_SUCCESS
and
(to non-UNIX environments) than the use of 0 and some nonzero value
like 1 or \-1.
In particular, VMS uses a different convention.
-.PP
+.P
BSD has attempted to standardize exit codes
(which some C libraries such as the GNU C library have also adopted);
see the file
.IR <sysexits.h> .
-.PP
+.P
After
.BR exit (),
the exit status must be transmitted to the
.BR waitpid (2)
(or similar) to learn the termination status of the child;
at that point the zombie process slot is released.
-.PP
+.P
If the implementation supports the
.B SIGCHLD
signal, this signal
signal, and the terminal is disassociated
from this session, allowing it to be acquired by a new controlling
process.
-.PP
+.P
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
See
.BR setpgid (2)
for an explanation of orphaned process groups.
-.PP
+.P
Except in the above cases,
where the signalled processes may be children of the terminating process,
termination of a process does
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "double exp(double " x );
.BI "float expf(float " x );
.BI "long double expl(long double " x );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR expf (),
.BR expl ():
.nf
.SH RETURN VALUE
On success, these functions return the exponential value of
.IR x .
-.PP
+.P
If
.I x
is a NaN,
a NaN is returned.
-.PP
+.P
If
.I x
is positive infinity,
positive infinity is returned.
-.PP
+.P
If
.I x
is negative infinity,
+0 is returned.
-.PP
+.P
If the result underflows,
a range error occurs,
and zero is returned.
-.PP
+.P
If the result overflows,
a range error occurs,
and the functions return
.BR math_error (7)
for information on how to determine whether an error has occurred
when calling these functions.
-.PP
+.P
The following errors can occur:
.TP
Range error, overflow
C11, POSIX.1-2008.
.SH HISTORY
C99, POSIX.1-2001.
-.PP
+.P
The variant returning
.I double
also conforms to
.nf
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <math.h>
-.PP
+.P
.BI "double exp10(double " x );
.BI "float exp10f(float " x );
.BI "long double exp10l(long double " x );
.SH RETURN VALUE
On success, these functions return the base-10 exponential value of
.IR x .
-.PP
+.P
For various special cases, including the handling of infinity and NaN,
as well as overflows and underflows, see
.BR exp (3).
.BR math_error (7)
for information on how to determine whether an error has occurred
when calling these functions.
-.PP
+.P
For a discussion of the errors that can occur for these functions, see
.BR exp (3).
.SH ATTRIBUTES
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "double exp2(double " x );
.BI "float exp2f(float " x );
.BI "long double exp2l(long double " x );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR exp2 (),
.BR exp2f (),
.BR exp2l ():
.SH RETURN VALUE
On success, these functions return the base-2 exponential value of
.IR x .
-.PP
+.P
For various special cases, including the handling of infinity and NaN,
as well as overflows and underflows, see
.BR exp (3).
.BR math_error (7)
for information on how to determine whether an error has occurred
when calling these functions.
-.PP
+.P
For a discussion of the errors that can occur for these functions, see
.BR exp (3).
.SH ATTRIBUTES
.SH HISTORY
glibc 2.1.
C99, POSIX.1-2001.
-.PP
+.P
The variant returning
.I double
also conforms to
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "double expm1(double " x );
.BI "float expm1f(float " x );
.BI "long double expm1l(long double " x );
-.PP
+.P
.fi
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR expm1 ():
.nf
_ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
|| /* Since glibc 2.19: */ _DEFAULT_SOURCE
|| /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
.fi
-.PP
+.P
.BR expm1f (),
.BR expm1l ():
.nf
.fi
.SH DESCRIPTION
These functions return a value equivalent to
-.PP
+.P
.nf
exp(x) \- 1
.fi
-.PP
+.P
The result is computed in a way that is accurate even if the value of
.I x
is near
.SH RETURN VALUE
On success, these functions return
.IR "exp(x)\ \-\ 1" .
-.PP
+.P
If
.I x
is a NaN,
a NaN is returned.
-.PP
+.P
If
.I x
is +0 (\-0),
+0 (\-0) is returned.
-.PP
+.P
If
.I x
is positive infinity, positive infinity is returned.
-.PP
+.P
If
.I x
is negative infinity, \-1 is returned.
-.PP
+.P
If the result overflows, a range error occurs,
and the functions return
.RB \- HUGE_VAL ,
.BR math_error (7)
for information on how to determine whether an error has occurred
when calling these functions.
-.PP
+.P
The following errors can occur:
.TP
Range error, overflow
for some large negative
.I x
values (where the function result approaches \-1).
-.PP
+.P
Before approximately glibc 2.11,
.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6814
.\" e.g., expm1(1e5) through expm1(1.00199970127e5),
for some large positive
.I x
values.
-.PP
+.P
Before glibc 2.11,
.\" It looks like the fix was in glibc 2.11, or possibly glibc 2.12.
.\" I have no test system for glibc 2.11, but glibc 2.12 passes.
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "double fabs(double " x );
.BI "float fabsf(float " x );
.BI "long double fabsl(long double " x );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR fabsf (),
.BR fabsl ():
.nf
.SH RETURN VALUE
These functions return the absolute value of
.IR x .
-.PP
+.P
If
.I x
is a NaN, a NaN is returned.
-.PP
+.P
If
.I x
is \-0, +0 is returned.
-.PP
+.P
If
.I x
is negative infinity or positive infinity, positive infinity is returned.
C11, POSIX.1-2008.
.SH HISTORY
C99, POSIX.1-2001.
-.PP
+.P
The variant returning
.I double
also conforms to
.SH SYNOPSIS
.nf
.B #include <stdio.h>
-.PP
+.P
.BI "int fclose(FILE *" stream );
.fi
.SH DESCRIPTION
.\" low-level file operations on the same stream. If you do get this error,
.\" you must have closed the stream's low-level file descriptor using
.\" something like close(fileno(stream)).
-.PP
+.P
The
.BR fclose ()
function may also fail and set
.nf
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <stdio.h>
-.PP
+.P
.B int fcloseall(void);
.fi
.SH DESCRIPTION
(as for
.BR fflush (3));
buffered input is discarded.
-.PP
+.P
The standard streams,
.IR stdin ,
.IR stdout ,
.BR fcloseall ()
T} Thread safety MT-Unsafe race:streams
.TE
-.PP
+.P
The
.BR fcloseall ()
function does not lock the streams, so it is not thread-safe.
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "double fdim(double " x ", double " y );
.BI "float fdimf(float " x ", float " y );
.BI "long double fdiml(long double " x ", long double " y );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR fdimf (),
.BR fdiml ():
.nf
between their arguments.
.SH RETURN VALUE
On success, these functions return the positive difference.
-.PP
+.P
If
.I x
or
.I y
is a NaN, a NaN is returned.
-.PP
+.P
If the result overflows,
a range error occurs,
and the functions return
.BR math_error (7)
for information on how to determine whether an error has occurred
when calling these functions.
-.PP
+.P
The following errors can occur:
.TP
Range error: result overflow
.SH SYNOPSIS
.nf
.B #include <fenv.h>
-.PP
+.P
.BI "int feclearexcept(int " excepts );
.BI "int fegetexceptflag(fexcept_t *" flagp ", int " excepts );
.BI "int feraiseexcept(int " excepts );
.BI "int fesetexceptflag(const fexcept_t *" flagp ", int " excepts );
.BI "int fetestexcept(int " excepts );
-.PP
+.P
.B "int fegetround(void);"
.BI "int fesetround(int " rounding_mode );
-.PP
+.P
.BI "int fegetenv(fenv_t *" envp );
.BI "int feholdexcept(fenv_t *" envp );
.BI "int fesetenv(const fenv_t *" envp );
.I divide-by-zero
exception occurs when an operation on finite numbers
produces infinity as exact answer.
-.PP
+.P
The
.I 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.
-.PP
+.P
The
.I 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).
-.PP
+.P
The
.I inexact
exception occurs when the rounded result of an operation
or
.I underflow
occurs.
-.PP
+.P
The
.I invalid
exception occurs when there is no well-defined result
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).
-.PP
+.P
Each of the macros
.BR FE_DIVBYZERO ,
.BR FE_INEXACT ,
The macro
.B FE_ALL_EXCEPT
is the bitwise OR of all bits corresponding to supported exceptions.
-.PP
+.P
The
.BR feclearexcept ()
function clears the supported exceptions represented by the bits
in its argument.
-.PP
+.P
The
.BR fegetexceptflag ()
function stores a representation of the state of the exception flags
.I excepts
in the opaque object
.IR *flagp .
-.PP
+.P
The
.BR feraiseexcept ()
function raises the supported exceptions represented by the bits in
.IR excepts .
-.PP
+.P
The
.BR fesetexceptflag ()
function sets the complete status for the exceptions represented by
.BR fegetexceptflag ()
with a last argument that contained all bits in
.IR excepts .
-.PP
+.P
The
.BR fetestexcept ()
function returns a word in which the bits are set that were
round up (toward positive infinity),
round down (toward negative infinity), and
round toward zero.
-.PP
+.P
Each of the macros
.BR FE_TONEAREST ,
.BR FE_UPWARD ,
.B FE_TOWARDZERO
is defined when the implementation supports getting and setting
the corresponding rounding direction.
-.PP
+.P
The
.BR fegetround ()
function returns the macro corresponding to the current
rounding mode.
-.PP
+.P
The
.BR fesetround ()
function sets the rounding mode as specified by its argument
and returns zero when it was successful.
-.PP
+.P
C99 and POSIX.1-2008 specify an identifier,
.BR FLT_ROUNDS ,
defined in
.TP
.B 3
Rounding is toward negative infinity.
-.PP
+.P
Other values represent machine-dependent, nonstandard rounding modes.
-.PP
+.P
The value of
.B FLT_ROUNDS
should reflect the current rounding mode as set by
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.
-.PP
+.P
The
.BR fegetenv ()
function saves the current floating-point environment in the object
.IR *envp .
-.PP
+.P
The
.BR 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.
-.PP
+.P
The
.BR fesetenv ()
function restores the floating-point environment from
or equal to
.BR FE_DFL_ENV .
This call does not raise exceptions.
-.PP
+.P
The
.BR feupdateenv ()
function installs the floating-point environment represented by
to set individual floating-point traps, and
.BR fegetexcept ()
to query the state.
-.PP
+.P
.nf
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B "#include <fenv.h>"
-.PP
+.P
.BI "int feenableexcept(int " excepts );
.BI "int fedisableexcept(int " excepts );
.B "int fegetexcept(void);"
.fi
-.PP
+.P
The
.BR feenableexcept ()
and
.SH SYNOPSIS
.nf
.B #include <stdio.h>
-.PP
+.P
.BI "void clearerr(FILE *" stream );
.BI "int feof(FILE *" stream );
.BI "int ferror(FILE *" stream );
.BR clearerr ()
clears the end-of-file and error indicators for the stream pointed to by
.IR stream .
-.PP
+.P
The function
.BR feof ()
tests the end-of-file indicator for the stream pointed to by
returning nonzero if it is set.
The end-of-file indicator can be cleared only by the function
.BR clearerr ().
-.PP
+.P
The function
.BR ferror ()
tests the error indicator for the stream pointed to by
The error indicator can be reset only by the
.BR clearerr ()
function.
-.PP
+.P
For nonlocking counterparts, see
.BR unlocked_stdio (3).
.SH RETURN VALUE
function returns nonzero if the end-of-file indicator is set for
.IR stream ;
otherwise, it returns zero.
-.PP
+.P
The
.BR ferror ()
function returns nonzero if the error indicator is set for
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.BI "int fexecve(int " fd ", char *const " argv "[], char *const " envp []);
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR fexecve ():
.nf
Since glibc 2.10:
POSIX.1-2008.
.SH HISTORY
glibc 2.3.2.
-.PP
+.P
On Linux with glibc versions 2.26 and earlier,
.BR fexecve ()
is implemented using the
.BR fexecve ();
for that, the solution is to ensure that the permissions on the file
prevent it from being modified by malicious users.
-.PP
+.P
The natural idiom when using
.BR fexecve ()
is to set the close-on-exec flag on
.SH SYNOPSIS
.nf
.B #include <stdio.h>
-.PP
+.P
.BI "int fflush(FILE *_Nullable " stream );
.fi
.SH DESCRIPTION
forces a write of all user-space buffered data for the given output or update
.I stream
via the stream's underlying write function.
-.PP
+.P
For input streams associated with seekable files
(e.g., disk files, but not pipes or terminals),
.BR fflush ()
discards any buffered data that has been fetched from the underlying file,
but has not been consumed by the application.
-.PP
+.P
The open status of the stream is unaffected.
-.PP
+.P
If the
.I stream
argument is NULL,
open output streams.
.\" mtk: POSIX specifies that only output streams are flushed for this case.
.\" Also verified for glibc by experiment.
-.PP
+.P
For a nonlocking counterpart, see
.BR unlocked_stdio (3).
.SH RETURN VALUE
.B EBADF
.I stream
is not an open stream, or is not open for writing.
-.PP
+.P
The function
.BR fflush ()
may also fail and set
C11, POSIX.1-2008.
.SH HISTORY
C89, POSIX.1-2001, POSIX.1-2008.
-.PP
+.P
POSIX.1-2001 did not specify the behavior for flushing of input streams,
but the behavior is specified in POSIX.1-2008.
.SH NOTES
.SH SYNOPSIS
.nf
.B #include <strings.h>
-.PP
+.P
.BI "int ffs(int " i );
-.PP
+.P
.B #include <string.h>
-.PP
+.P
.BI "int ffsl(long " i );
.BI "int ffsll(long long " i );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR ffs ():
.nf
Since glibc 2.12:
Before glibc 2.12:
none
.fi
-.PP
+.P
.BR ffsl (),
.BR ffsll ():
.nf
.SH SYNOPSIS
.nf
.B #include <stdio.h>
-.PP
+.P
.BI "int fgetc(FILE *" stream );
.BI "int getc(FILE *" stream );
.B "int getchar(void);"
-.PP
+.P
.BI "char *fgets(char " s "[restrict ." size "], int " size ", \
FILE *restrict " stream );
-.PP
+.P
.BI "int ungetc(int " c ", FILE *" stream );
.fi
.SH DESCRIPTION
or
.B EOF
on end of file or error.
-.PP
+.P
.BR getc ()
is equivalent to
.BR fgetc ()
except that it may be implemented as a macro which evaluates
.I stream
more than once.
-.PP
+.P
.BR getchar ()
is equivalent to
.BI "getc(" stdin ) \fR.
-.PP
+.P
.BR fgets ()
reads in at most one less than
.I size
If a newline is read, it is stored into the buffer.
A terminating null byte (\[aq]\e0\[aq])
is stored after the last character in the buffer.
-.PP
+.P
.BR ungetc ()
pushes
.I c
where it is available for subsequent read operations.
Pushed-back characters
will be returned in reverse order; only one pushback is guaranteed.
-.PP
+.P
Calls to the functions described here can be mixed with each other and with
calls to other input functions from the
.I stdio
library for the same input stream.
-.PP
+.P
For nonlocking counterparts, see
.BR unlocked_stdio (3).
.SH RETURN VALUE
or
.B EOF
on end of file or error.
-.PP
+.P
.BR fgets ()
returns
.I s
on success, and NULL
on error or when end of file occurs while no characters have been read.
-.PP
+.P
.BR ungetc ()
returns
.I c
.B #include <stdio.h>
.B #include <sys/types.h>
.B #include <grp.h>
-.PP
+.P
.BI "struct group *fgetgrent(FILE *" stream );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR fgetgrent ():
.nf
Since glibc 2.19:
.I /etc/group
(see
.BR group (5)).
-.PP
+.P
The \fIgroup\fP structure is defined in \fI<grp.h>\fP as follows:
-.PP
+.P
.in +4n
.EX
struct group {
.B #include <stdio.h>
.B #include <sys/types.h>
.B #include <pwd.h>
-.PP
+.P
.BI "struct passwd *fgetpwent(FILE *" stream );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR fgetpwent ():
.nf
Since glibc 2.19:
.I /etc/passwd
(see
.BR passwd (5)).
-.PP
+.P
The \fIpasswd\fP structure is defined in \fI<pwd.h>\fP as follows:
-.PP
+.P
.in +4n
.EX
struct passwd {
.nf
.B #include <stdio.h>
.B #include <wchar.h>
-.PP
+.P
.BI "wint_t fgetwc(FILE *" stream );
.BI "wint_t getwc(FILE *" stream );
.fi
If a wide-character conversion error occurs, it sets
\fIerrno\fP to \fBEILSEQ\fP and returns
.BR WEOF .
-.PP
+.P
The
.BR getwc ()
function or macro functions identically to
It may be implemented as a macro, and may evaluate its argument
more than once.
There is no reason ever to use it.
-.PP
+.P
For nonlocking counterparts, see
.BR unlocked_stdio (3).
.SH RETURN VALUE
.B LC_CTYPE
category of the
current locale.
-.PP
+.P
In the absence of additional information passed to the
.BR fopen (3)
call, it is
.SH SYNOPSIS
.nf
.B #include <wchar.h>
-.PP
+.P
.BI "wchar_t *fgetws(wchar_t " ws "[restrict ." n "], int " n \
", FILE *restrict " stream );
.fi
It stops reading wide characters after it has encountered and
stored a newline wide character.
It also stops when end of stream is reached.
-.PP
+.P
The programmer must ensure that there is room for at least \fIn\fP wide
characters at \fIws\fP.
-.PP
+.P
For a nonlocking counterpart, see
.BR unlocked_stdio (3).
.SH RETURN VALUE
.B LC_CTYPE
category of the
current locale.
-.PP
+.P
In the absence of additional information passed to the
.BR fopen (3)
call, it is
.BR fgetws ()
will actually read a multibyte string
from the stream and then convert it to a wide-character string.
-.PP
+.P
This function is unreliable,
because it does not permit to deal properly with
null wide characters that may be present in the input.
.SH SYNOPSIS
.nf
.B #include <stdio.h>
-.PP
+.P
.BI "int fileno(FILE *" stream );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR fileno ():
.nf
_POSIX_C_SOURCE
Duplicate the file descriptor with
.BR dup (2)
before passing it to code that might close it.
-.PP
+.P
For the nonlocking counterpart, see
.BR unlocked_stdio (3).
.SH RETURN VALUE
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "int finite(double " x );
.BI "int finitef(float " x );
.BI "int finitel(long double " x );
-.PP
+.P
.BI "int isinf(double " x );
.BI "int isinff(float " x );
.BI "int isinfl(long double " x );
-.PP
+.P
.BI "int isnan(double " x );
.BI "int isnanf(float " x );
.BI "int isnanl(long double " x );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR finite (),
.BR finitef (),
.BR finitel ():
.nf
/* glibc >= 2.19: */ _DEFAULT_SOURCE
|| /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
-.PP
+.P
.BR isinf ():
_XOPEN_SOURCE >= 600 || _ISOC99_SOURCE
|| /* glibc >= 2.19: */ _DEFAULT_SOURCE
|| /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
.fi
-.PP
+.P
.BR isinff (),
.BR isinfl ():
.nf
/* glibc >= 2.19: */ _DEFAULT_SOURCE
|| /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
.fi
-.PP
+.P
.BR isnan ():
.nf
_XOPEN_SOURCE || _ISOC99_SOURCE
|| /* glibc >= 2.19: */ _DEFAULT_SOURCE
|| /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
.fi
-.PP
+.P
.BR isnanf (),
.BR isnanl ():
.nf
.I x
is neither infinite
nor a "not-a-number" (NaN) value, and 0 otherwise.
-.PP
+.P
The
.BR isnan (),
.BR isnanf (),
.I x
is a NaN value,
and 0 otherwise.
-.PP
+.P
The
.BR isinf (),
.BR isinff (),
.SH SYNOPSIS
.nf
.B #include <stdio.h>
-.PP
+.P
.BI "void flockfile(FILE *" filehandle );
.BI "int ftrylockfile(FILE *" filehandle );
.BI "void funlockfile(FILE *" filehandle );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
All functions shown above:
.nf
/* Since glibc 2.24: */ _POSIX_C_SOURCE >= 199309L
object
is no longer locked by a different thread, then lock it, do the
requested I/O, and unlock the object again.
-.PP
+.P
(Note: this locking has nothing to do with the file locking done
by functions like
.BR flock (2)
and
.BR lockf (3).)
-.PP
+.P
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
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.
-.PP
+.P
To this end, a thread can explicitly lock the
.I FILE
object,
.BR getc (3)
and
.BR putc (3).
-.PP
+.P
The
.BR flockfile ()
function waits for
.IR *filehandle ,
and increments
the lockcount.
-.PP
+.P
The
.BR funlockfile ()
function decrements the lock count.
-.PP
+.P
The
.BR ftrylockfile ()
function is a nonblocking version
POSIX.1-2008.
.SH HISTORY
POSIX.1-2001.
-.PP
+.P
These functions are available when
.B _POSIX_THREAD_SAFE_FUNCTIONS
is defined.
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "double floor(double " x );
.BI "float floorf(float " x );
.BI "long double floorl(long double " x );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR floorf (),
.BR floorl ():
.nf
.SH DESCRIPTION
These functions return the largest integral value that is not greater than
.IR x .
-.PP
+.P
For example,
.I floor(0.5)
is 0.0, and
.SH RETURN VALUE
These functions return the floor of
.IR x .
-.PP
+.P
If
.I x
is integral, +0, \-0, NaN, or an infinity,
C11, POSIX.1-2008.
.SH HISTORY
C99, POSIX.1-2001.
-.PP
+.P
The variant returning
.I double
also conforms to
SVr4, 4.3BSD, C89.
-.PP
+.P
SUSv2 and POSIX.1-2001 contain text about overflow (which might set
.I errno
to
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "double fma(double " x ", double " y ", double " z );
.BI "float fmaf(float " x ", float " y ", float " z );
.BI "long double fmal(long double " x ", long double " y ", long double " z );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR fma (),
.BR fmaf (),
.BR fmal ():
These functions return the value of
.IR x " * " y " + " z ,
rounded as one ternary operation.
-.PP
+.P
If
.I x
or
.I y
is a NaN, a NaN is returned.
-.PP
+.P
If
.I x
times
is an infinity with the opposite sign,
a domain error occurs,
and a NaN is returned.
-.PP
+.P
.\" POSIX.1-2008 allows some possible differences for the following two
.\" domain error cases, but on Linux they are treated the same (AFAICS).
.\" Nevertheless, we'll mirror POSIX.1 and describe the two cases
a NaN is returned.
.\" POSIX.1 says that a NaN or an implementation-defined value shall
.\" be returned for this case.
-.PP
+.P
If one of
.I x
or
.\" POSIX.1 makes the domain error optional for this case.
a domain error occurs, and
a NaN is returned.
-.PP
+.P
If
.I x
times
.I z
is a NaN,
a NaN is returned.
-.PP
+.P
If the result overflows,
a range error occurs, and
an infinity with the correct sign is returned.
-.PP
+.P
If the result underflows,
a range error occurs, and
a signed 0 is returned.
.BR math_error (7)
for information on how to determine whether an error has occurred
when calling these functions.
-.PP
+.P
The following errors can occur:
.TP
Domain error: \fIx\fP * \fIy\fP + \fIz\fP, \
An underflow floating-point exception
.RB ( FE_UNDERFLOW )
is raised.
-.PP
+.P
These functions do not set
.IR errno .
.\" FIXME . Is it intentional that these functions do not set errno?
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "double fmax(double " x ", double " y );
.BI "float fmaxf(float " x ", float " y );
.BI "long double fmaxl(long double " x ", long double " y );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR fmax (),
.BR fmaxf (),
.BR fmaxl ():
.I x
and
.IR y .
-.PP
+.P
If one argument is a NaN, the other argument is returned.
-.PP
+.P
If both arguments are NaN, a NaN is returned.
.SH ERRORS
No errors occur.
.SH SYNOPSIS
.nf
.B #include <stdio.h>
-.PP
+.P
.BI "FILE *fmemopen(void " buf [. size "], size_t " size ", \
const char *" mode );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR fmemopen ():
.nf
Since glibc 2.10:
The stream allows I/O to be performed on the string or memory buffer
pointed to by
.IR buf .
-.PP
+.P
The
.I mode
argument specifies the semantics of I/O on the stream,
.I a+
Append; open the stream for reading and writing,
with the initial buffer position set to the first null byte.
-.PP
+.P
The stream maintains the notion of a current position,
the location where the next I/O operation will be performed.
The current position is implicitly updated by I/O operations.
In append mode, if no null byte is found within the buffer,
then the initial position is
.IR size+1 .
-.PP
+.P
If
.I buf
is specified as NULL, then
Note that the caller has no way to obtain a pointer to the
temporary buffer allocated by this call (but see
.BR open_memstream (3)).
-.PP
+.P
If
.I buf
is not NULL, then it should point to a buffer of at least
.I size
bytes allocated by the caller.
-.PP
+.P
When a stream that has been opened for writing is flushed
.RB ( fflush (3))
or closed
.I size
counts that byte)
to allow for this.
-.PP
+.P
In a stream opened for reading,
null bytes (\[aq]\e0\[aq]) in the buffer do not cause read
operations to return an end-of-file indication.
only when the current buffer position advances
.I size
bytes past the start of the buffer.
-.PP
+.P
Write operations take place either at the current position
(for modes other than append), or at the current size of the stream
(for append modes).
-.PP
+.P
Attempts to write more than
.I size
bytes to the buffer result in an error.
buffer is flushed.
Disabling buffering with the following call
may be useful to detect errors at the time of an output operation:
-.PP
+.P
.in +4n
.EX
setbuf(stream, NULL);
.SH HISTORY
glibc 1.0.x.
POSIX.1-2008.
-.PP
+.P
POSIX.1-2008 specifies that \[aq]b\[aq] in
.I mode
shall be ignored.
.\" http://austingroupbugs.net/view.php?id=396
adjusts the standard to allow implementation-specific treatment for this case,
thus permitting the glibc treatment of \[aq]b\[aq].
-.PP
+.P
With glibc 2.22, binary mode (see below) was removed,
many longstanding bugs in the implementation of
.BR fmemopen ()
is relative to the end of the buffer (i.e., the value specified by the
.I size
argument), rather than the current string length.
-.PP
+.P
An API bug afflicted the implementation of binary mode:
to specify binary mode, the \[aq]b\[aq] must be the
.I second
.I mode
by
.BR fopen (3).
-.PP
+.P
Binary mode was removed in glibc 2.22; a \[aq]b\[aq] specified in
.I mode
has no effect.
It would be more consistent if this case successfully created
a stream that then returned end-of-file on the first attempt at reading;
since glibc 2.22, the glibc implementation provides that behavior.
-.PP
+.P
Before glibc 2.22,
specifying append mode ("a" or "a+") for
.BR fmemopen ()
the end of the stream)
does not force subsequent writes to append at the end of the stream.
This bug is fixed in glibc 2.22.
-.PP
+.P
Before glibc 2.22, if the
.I mode
argument to
.BR fmemopen ()
sets the buffer position to \-1.
This bug is fixed in glibc 2.22.
-.PP
+.P
Before glibc 2.22,
.\" https://sourceware.org/bugzilla/show_bug.cgi?id=14292
when a call to
.I subtracted
from the end-of-stream position, instead of being added.
This bug is fixed in glibc 2.22.
-.PP
+.P
The glibc 2.9 addition of "binary" mode for
.BR fmemopen ()
.\" http://sourceware.org/bugzilla/show_bug.cgi?id=6544
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:
-.PP
+.P
.in +4n
.EX
.RB "$" " ./a.out \[aq]1 23 43\[aq]"
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "double fmin(double " x ", double " y );
.BI "float fminf(float " x ", float " y );
.BI "long double fminl(long double " x ", long double " y );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR fmin (),
.BR fminf (),
.BR fminl ():
.I x
and
.IR y .
-.PP
+.P
If one argument is a NaN, the other argument is returned.
-.PP
+.P
If both arguments are NaN, a NaN is returned.
.SH ERRORS
No errors occur.
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "double fmod(double " x ", double " y );
.BI "float fmodf(float " x ", float " y );
.BI "long double fmodl(long double " x ", long double " y );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR fmodf (),
.BR fmodl ():
.nf
/
.IR y ,
rounded toward zero to an integer.
-.PP
+.P
To obtain the modulus, more specifically, the Least Positive Residue,
you will need to adjust the result from fmod like so:
-.PP
+.P
.in +4n
.nf
z = fmod(x, y);
z += y;
.fi
.in
-.PP
+.P
An alternate way to express this is with
.IR "fmod(fmod(x, y) + y, y)" ,
but the second
.I x
and a magnitude less than the magnitude of
.IR y .
-.PP
+.P
If
.I x
or
.I y
is a NaN, a NaN is returned.
-.PP
+.P
If
.I x
is an infinity,
a domain error occurs, and
a NaN is returned.
-.PP
+.P
If
.I y
is zero,
a domain error occurs, and
a NaN is returned.
-.PP
+.P
If
.I x
is +0 (\-0), and
.BR math_error (7)
for information on how to determine whether an error has occurred
when calling these functions.
-.PP
+.P
The following errors can occur:
.TP
Domain error: \fIx\fP is an infinity
C11, POSIX.1-2008.
.SH HISTORY
C99, POSIX.1-2001.
-.PP
+.P
The variant returning
.I double
also conforms to
The call
.I fmod(372, 360)
returns 348.
-.PP
+.P
The call
.I fmod(-372, 360)
returns -12.
-.PP
+.P
The call
.I fmod(-372, -360)
also returns -12.
.SH SYNOPSIS
.nf
.B #include <fmtmsg.h>
-.PP
+.P
.BI "int fmtmsg(long " classification ", const char *" label ,
.BI " int " severity ", const char *" text ,
.BI " const char *" action ", const char *" tag );
the format depends on the
.B MSGVERB
environment variable.
-.PP
+.P
The
.I 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.
-.PP
+.P
The
.I text
argument describes the condition of the error.
-.PP
+.P
The
.I action
argument describes possible steps to recover from the error.
If it is printed, it is prefixed by "TO FIX: ".
-.PP
+.P
The
.I tag
argument is a reference to the online documentation where more
The
.I classification
argument is the sum of values describing 4 types of information.
-.PP
+.P
The first value defines the output channel.
.TP 12n
.B MM_PRINT
.TP
.B "MM_PRINT | MM_CONSOLE"
Output to both.
-.PP
+.P
The second value is the source of the error:
.TP 12n
.B MM_HARD
.TP
.B MM_SOFT
A software error occurred.
-.PP
+.P
The third value encodes the detector of the problem:
.TP 12n
.B MM_APPL
.TP
.B MM_OPSYS
It is detected by the operating system.
-.PP
+.P
The fourth value shows the severity of the incident:
.TP 12n
.B MM_RECOVER
.TP
.B MM_INFO
This value is printed as INFO.
-.PP
+.P
The numeric values are between 0 and 4.
Using
.BR addseverity (3)
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".
-.PP
+.P
The environment variable
.B SEV_LEVEL
can be used to introduce new severity levels.
If the user puts
.B SEV_LEVEL
with a format like
-.PP
+.P
.RS
SEV_LEVEL=[description[:description[:...]]]
.RE
-.PP
+.P
in the environment of the process before the first call to
.BR fmtmsg (),
where each description is of the form
-.PP
+.P
.RS
severity-keyword,level,printstring
.RE
-.PP
+.P
then
.BR fmtmsg ()
will also accept the indicated values for the level (in addition to
the standard levels 0\[en]4), and use the indicated printstring when
such a level occurs.
-.PP
+.P
The severity-keyword part is not used by
.BR fmtmsg ()
but it has to be present.
glibc\ <\ 2.16: MT-Unsafe
T}
.TE
-.PP
+.P
Before glibc 2.16, the
.BR fmtmsg ()
function uses a static variable that is not protected,
so it is not thread-safe.
-.PP
+.P
Since glibc 2.16,
.\" Modified in commit 7724defcf8873116fe4efab256596861eef21a94
the
.TP
.B SEV_LEVEL
System V.
-.PP
+.P
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.
}
.EE
.\" SRC END
-.PP
+.P
The output should be:
-.PP
+.P
.in +4n
.EX
util\-linux:mount: ERROR: unknown mount option
TO FIX: See mount(8). util\-linux:mount:017
.EE
.in
-.PP
+.P
and after
-.PP
+.P
.in +4n
.EX
MSGVERB=text:action; export MSGVERB
.EE
.in
-.PP
+.P
the output becomes:
-.PP
+.P
.in +4n
.EX
unknown mount option
.SH SYNOPSIS
.nf
.B #include <fnmatch.h>
-.PP
+.P
.BI "int fnmatch(const char *" "pattern" ", const char *" string ", int " flags );
.fi
.SH DESCRIPTION
.I pattern
argument, which is a shell wildcard pattern (see
.BR glob (7)).
-.PP
+.P
The
.I flags
argument modifies the behavior; it is the bitwise OR of zero or more
.SH SYNOPSIS
.nf
.B #include <stdio.h>
-.PP
+.P
.BI "FILE *fopen(const char *restrict " pathname \
", const char *restrict " mode );
.BI "FILE *fdopen(int " fd ", const char *" mode );
", const char *restrict " mode ,
.BI " FILE *restrict " stream );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR fdopen ():
.nf
_POSIX_C_SOURCE
function opens the file whose name is the string pointed to by
.I pathname
and associates a stream with it.
-.PP
+.P
The argument
.I mode
points to a string beginning with one of the following sequences
For glibc, the initial file position for reading is at
the beginning of the file, but for Android/BSD/MacOS, the
initial file position for reading is at the end of the file.
-.PP
+.P
The
.I mode
string can also include the letter \[aq]b\[aq] either as a last character or as
and adding the \[aq]b\[aq] 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.)
-.PP
+.P
See NOTES below for details of glibc extensions for
.IR mode .
-.PP
+.P
Any created file will have the mode
.BR S_IRUSR " | " S_IWUSR " | " S_IRGRP " | " S_IWGRP " | " S_IROTH " | " S_IWOTH
(0666), as modified by the process's umask value (see
.BR umask (2)).
-.PP
+.P
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.
This operation may be an apparent no-op
(as in \fIfseek(..., 0L, SEEK_CUR)\fP
called for its synchronizing side effect).
-.PP
+.P
Opening a file in append mode (\fBa\fP as the first character of
.IR mode )
causes all subsequent write operations to this stream to occur
at end-of-file, as if preceded by the call:
-.PP
+.P
.in +4n
.EX
fseek(stream, 0, SEEK_END);
.EE
.in
-.PP
+.P
The file descriptor associated with the stream is opened as if by a call to
.BR open (2)
with the following flags:
argument is used just as in the
.BR fopen ()
function.
-.PP
+.P
If the
.I pathname
argument is a null pointer,
.BR freopen ()
reopens the pathname that is associated with the stream.
The specification for this behavior was added in the C99 standard, which says:
-.PP
+.P
.RS
In this case,
the file descriptor associated with the stream need not be closed
It is implementation-defined which changes of mode are permitted (if any),
and under what circumstances.
.RE
-.PP
+.P
The primary use of the
.BR freopen ()
function is to change the file associated with a standard text stream
or
.BR freopen ()
was invalid.
-.PP
+.P
The
.BR fopen (),
.BR fdopen (),
.I errno
for any of the errors specified for the routine
.BR malloc (3).
-.PP
+.P
The
.BR fopen ()
function may also fail and set
.I errno
for any of the errors specified for the routine
.BR open (2).
-.PP
+.P
The
.BR fdopen ()
function may also fail and set
.I errno
for any of the errors specified for the routine
.BR fcntl (2).
-.PP
+.P
The
.BR freopen ()
function may also fail and set
.BR EEXIST .
This flag is ignored for
.BR fdopen ().
-.PP
+.P
In addition to the above characters,
.BR fopen ()
and
support the following syntax
in
.IR mode :
-.PP
+.P
.BI " ,ccs=" string
-.PP
+.P
The given
.I string
is taken as the name of a coded character set and
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #define _FILE_OFFSET_BITS 64
.B #include <stdio.h>
-.PP
+.P
.BI "FILE *fopencookie(void *restrict " cookie ", const char *restrict " mode ,
.BI " cookie_io_functions_t " io_funcs );
.fi
.BR fmemopen (3),
which provides a stream interface to data that is stored in a
buffer in memory.
-.PP
+.P
In order to create a custom stream the programmer must:
.IP \[bu] 3
Implement four "hook" functions that are used internally by the
.BR fopencookie ()
to open a new stream and associate the cookie and hook functions
with that stream.
-.PP
+.P
The
.BR fopencookie ()
function serves a purpose similar to
it opens a new stream and returns a pointer to a
.I FILE
object that is used to operate on that stream.
-.PP
+.P
The
.I 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.
-.PP
+.P
The
.I mode
argument serves the same purpose as for
See
.BR fopen (3)
for details.
-.PP
+.P
The
.I 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
-.PP
+.P
.in +4n
.EX
typedef struct {
} cookie_io_functions_t;
.EE
.in
-.PP
+.P
The four fields are as follows:
.TP
.I cookie_read_function_t *read
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:
-.PP
+.P
.in +4n
.EX
.RB "$" " ./a.out \[aq]hello world\[aq]"
Reached end of file
.EE
.in
-.PP
+.P
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;
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.BI "long fpathconf(int " fd ", int " name );
.BI "long pathconf(const char *" path ", int " name );
.fi
.I name
for the open file descriptor
.IR fd .
-.PP
+.P
.BR pathconf ()
gets a value for configuration option
.I name
for the filename
.IR path .
-.PP
+.P
The corresponding macros defined in
.I <unistd.h>
are minimum values; if an application wants to take advantage of values
or
.BR pathconf ()
can be made, which may yield more liberal results.
-.PP
+.P
Setting
.I name
equal to one of the following constants returns the following
equal to
.B _PC_NAME_MAX
may exist in the given directory.
-.PP
+.P
Some returned values may be huge; they are not suitable for allocating
memory.
.SH SEE ALSO
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "int fpclassify(" x );
.BI "int isfinite(" x );
.BI "int isnormal(" x );
.BI "int isnan(" x );
.BI "int isinf(" x );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.\" I haven't fully grokked the source to determine the FTM requirements;
.\" in part, the following has been tested by experiment.
.BR fpclassify (),
.nf
_ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
.fi
-.PP
+.P
.BR isnan ():
.nf
_ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
|| /* Since glibc 2.19: */ _DEFAULT_SOURCE
|| /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
.fi
-.PP
+.P
.BR isinf ():
.nf
_ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
.B FP_NORMAL
if nothing of the above is correct then it must be a
normal floating-point number.
-.PP
+.P
The other macros provide a short answer to some standard questions.
.TP 14
.BI isfinite( x )
C11, POSIX.1-2008.
.SH HISTORY
POSIX.1-2001, C99.
-.PP
+.P
In glibc 2.01 and earlier,
.BR isinf ()
returns a nonzero value (actually: 1) if
.nf
/* unsupported */
.B #include <stdio.h>
-.PP
+.P
.BI "int fpurge(FILE *" stream );
-.PP
+.P
/* supported */
.B #include <stdio.h>
.B #include <stdio_ext.h>
-.PP
+.P
.BI "void __fpurge(FILE *" stream );
.fi
.SH DESCRIPTION
.BR ungetc (3).
See also
.BR fflush (3).
-.PP
+.P
The function
.BR __fpurge ()
does precisely the same, but without returning a value.
.nf
.B #include <stdio.h>
.B #include <wchar.h>
-.PP
+.P
.BI "wint_t fputwc(wchar_t " wc ", FILE *" stream );
.BI "wint_t putwc(wchar_t " wc ", FILE *" stream );
.fi
it sets \fIerrno\fP to \fBEILSEQ\fP and returns
.BR WEOF .
Otherwise, it returns \fIwc\fP.
-.PP
+.P
The
.BR putwc ()
function or macro functions identically to
It may be implemented as a macro, and may evaluate its argument
more than once.
There is no reason ever to use it.
-.PP
+.P
For nonlocking counterparts, see
.BR unlocked_stdio (3).
.SH RETURN VALUE
.B LC_CTYPE
category of the
current locale.
-.PP
+.P
In the absence of additional information passed to the
.BR fopen (3)
call, it is
.SH SYNOPSIS
.nf
.B #include <wchar.h>
-.PP
+.P
.BI "int fputws(const wchar_t *restrict " ws ", FILE *restrict " stream );
.fi
.SH DESCRIPTION
It writes the wide-character string starting at \fIws\fP,
up to but not including the terminating null wide character (L\[aq]\e0\[aq]),
to \fIstream\fP.
-.PP
+.P
For a nonlocking counterpart, see
.BR unlocked_stdio (3).
.SH RETURN VALUE
.B LC_CTYPE
category of the
current locale.
-.PP
+.P
In the absence of additional information passed to the
.BR fopen (3)
call, it is
.SH SYNOPSIS
.nf
.B #include <stdio.h>
-.PP
+.P
.BI "size_t fread(void " ptr "[restrict ." size " * ." nmemb ],
.BI " size_t " size ", size_t " nmemb ,
.BI " FILE *restrict " stream );
.IR stream ,
storing them at the location given by
.IR ptr .
-.PP
+.P
The function
.BR fwrite ()
writes
.IR stream ,
obtaining them from the location given by
.IR ptr .
-.PP
+.P
For nonlocking counterparts, see
.BR unlocked_stdio (3).
.SH RETURN VALUE
is 1.
If an error occurs, or the end of the file is reached,
the return value is a short item count (or zero).
-.PP
+.P
The file position indicator for the stream is advanced by the number
of bytes successfully read or written.
-.PP
+.P
.BR fread ()
does not distinguish between end-of-file and error, and callers must use
.BR feof (3)
.BR fread ()
by parsing /bin/sh ELF executable in binary mode and printing its
magic and class:
-.PP
+.P
.in +4n
.EX
$ \fB./a.out\fP
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "double frexp(double " x ", int *" exp );
.BI "float frexpf(float " x ", int *" exp );
.BI "long double frexpl(long double " x ", int *" exp );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR frexpf (),
.BR frexpl ():
.nf
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).
-.PP
+.P
If
.I x
is zero, then the normalized fraction is
zero and zero is stored in
.IR exp .
-.PP
+.P
If
.I x
is a NaN,
a NaN is returned, and the value of
.I *exp
is unspecified.
-.PP
+.P
If
.I x
is positive infinity (negative infinity),
C11, POSIX.1-2008.
.SH HISTORY
C99, POSIX.1-2001.
-.PP
+.P
The variant returning
.I double
also conforms to
SVr4, 4.3BSD, C89.
.SH EXAMPLES
The program below produces results such as the following:
-.PP
+.P
.in +4n
.EX
.RB "$" " ./a.out 2560"
.SH SYNOPSIS
.nf
.B #include <stdio.h>
-.PP
+.P
.BI "int fseek(FILE *" stream ", long " offset ", int " whence );
.BI "long ftell(FILE *" stream );
-.PP
+.P
.BI "void rewind(FILE *" stream );
-.PP
+.P
.BI "int fgetpos(FILE *restrict " stream ", fpos_t *restrict " pos );
.BI "int fsetpos(FILE *" stream ", const fpos_t *" pos );
.fi
any effects of the
.BR ungetc (3)
function on the same stream.
-.PP
+.P
The
.BR ftell ()
function obtains the current value of the file position indicator for the
stream pointed to by
.IR stream .
-.PP
+.P
The
.BR rewind ()
function sets the file position indicator for the stream pointed to by
.I stream
to the beginning of the file.
It is equivalent to:
-.PP
+.P
.RS
(void) fseek(stream, 0L, SEEK_SET)
.RE
-.PP
+.P
except that the error indicator for the stream is also cleared (see
.BR clearerr (3)).
-.PP
+.P
The
.BR fgetpos ()
and
.I fpos_t
object may be a complex object and these routines may be the only way to
portably reposition a text stream.
-.PP
+.P
If the stream refers to a regular file
and the resulting stream offset is beyond the size of the file,
subsequent writes will extend the file with a hole, up to the offset,
The file descriptor underlying
.I stream
is not seekable (e.g., it refers to a pipe, FIFO, or socket).
-.PP
+.P
The functions
.BR fgetpos (),
.BR fseek (),
.SH SYNOPSIS
.nf
.B #include <stdio.h>
-.PP
+.P
.BI "int fseeko(FILE *" stream ", off_t " offset ", int " whence );
.BI "off_t ftello(FILE *" stream );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR fseeko (),
.BR ftello ():
.nf
.I off_t
instead of
.IR long .
-.PP
+.P
On some architectures, both
.I off_t
and
.SH SYNOPSIS
.nf
.B "#include <sys/timeb.h>"
-.PP
+.P
.BI "int ftime(struct timeb *" tp );
.fi
.SH DESCRIPTION
Use
.BR clock_gettime (2)
instead.
-.PP
+.P
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
.IR tp ,
which is declared as follows:
-.PP
+.P
.in +4n
.EX
struct timeb {
};
.EE
.in
-.PP
+.P
Here \fItime\fP is the number of seconds since the Epoch,
and \fImillitm\fP is the number of milliseconds since \fItime\fP
seconds since the Epoch.
The \fIdstflag\fP field
is a flag that, if nonzero, indicates that Daylight Saving time
applies locally during the appropriate part of the year.
-.PP
+.P
POSIX.1-2001 says that the contents of the \fItimezone\fP and \fIdstflag\fP
fields are unspecified; avoid relying on them.
.SH RETURN VALUE
Removed in glibc 2.33.
4.2BSD, POSIX.1-2001.
Removed in POSIX.1-2008.
-.PP
+.P
This function is obsolete.
Don't use it.
If the time in seconds
.nf
.B #include <sys/ipc.h>
.fi
-.PP
+.P
.BI "key_t ftok(const char *" pathname ", int " proj_id );
.SH DESCRIPTION
The
.BR semget (2),
or
.BR shmget (2).
-.PP
+.P
The resulting value is the same for all pathnames that
name the same file, when the same value of
.I proj_id
POSIX.1-2001.
.SH NOTES
On some ancient systems, the prototype was:
-.PP
+.P
.in +4n
.EX
.BI "key_t ftok(char *" pathname ", char " proj_id );
.EE
.in
-.PP
+.P
Today,
.I proj_id
is an
that is why the behavior is said to be undefined when
.I proj_id
is zero.
-.PP
+.P
Of course, no guarantee can be given that the resulting
.I key_t
is unique.
.B #include <sys/types.h>
.B #include <sys/stat.h>
.B #include <fts.h>
-.PP
+.P
.BI "FTS *fts_open(char *const *" path_argv ", int " options ,
.BI " int (*_Nullable " compar ")(const FTSENT **, const FTSENT **));"
-.PP
+.P
.BI "FTSENT *fts_read(FTS *" ftsp );
-.PP
+.P
.BI "FTSENT *fts_children(FTS *" ftsp ", int " instr );
-.PP
+.P
.BI "int fts_set(FTS *" ftsp ", FTSENT *" f ", int " instr );
-.PP
+.P
.BI "int fts_close(FTS *" ftsp );
.fi
.SH DESCRIPTION
.BR 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.
-.PP
+.P
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).
or physically (visiting the symbolic links themselves),
order the walk of the hierarchy or
prune and/or revisit portions of the hierarchy.
-.PP
+.P
Two structures (and associated types) are defined in the include file
.IR <fts.h> .
The first type is
In this manual page, "file" and
"FTSENT structure"
are generally interchangeable.
-.PP
+.P
The
.I FTSENT
structure contains fields describing a file.
The structure contains at least the following fields
(there are additional fields that
should be considered private to the implementation):
-.PP
+.P
.in +4n
.EX
typedef struct _ftsent {
} FTSENT;
.EE
.in
-.PP
+.P
These fields are defined as follows:
.\" .Bl -tag -width "fts_namelen"
.TP
.RB [ l ] stat (2)
information for the file.
.\" .El
-.PP
+.P
A single buffer is used for all of the paths of all of the files in the
file hierarchy.
Therefore, the
or more paths which make up a logical file hierarchy to be traversed.
The array must be terminated by a
null pointer.
-.PP
+.P
There are
a number of options, at least one of which (either
.B FTS_LOGICAL
fts from descending into directories that have a different device number
than the file from which the descent began.
.\" .El
-.PP
+.P
The argument
.BR compar ()
specifies a user-defined function which may be used to order the traversal
(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.)
-.PP
+.P
If all the members of the hierarchy have been returned,
.BR fts_read ()
returns NULL and sets
.I errno
may or may not have been set (see
.IR fts_info ).
-.PP
+.P
The
.I FTSENT
structures returned by
Repeated calls to
.BR fts_children ()
will re-create this linked list.
-.PP
+.P
As a special case, if
.BR fts_read ()
has not yet been called for a hierarchy,
and sets
.I errno
to indicate the error.
-.PP
+.P
The
.I FTSENT
structures returned by
or
.BR fts_read ()
on the same file hierarchy stream.
-.PP
+.P
The
.I instr
argument is either zero or the following value:
.BR fts_set ()
function
returns 0 on success, and \-1 if an error occurs.
-.PP
+.P
The
.I instr
argument is either 0 (meaning "do nothing") or one of the following values:
.BR open (2)
and
.BR malloc (3).
-.PP
+.P
In addition,
.BR fts_open ()
may fail and set
Any element of
.I path_argv
was an empty string.
-.PP
+.P
The function
.BR fts_close ()
may fail and set
.BR chdir (2)
and
.BR close (2).
-.PP
+.P
The functions
.BR fts_read ()
and
.BR readdir (3),
and
.RB [ l ] stat (2).
-.PP
+.P
In addition,
.BR fts_children (),
.BR fts_open (),
.SH SYNOPSIS
.nf
.B #include <ftw.h>
-.PP
+.P
.BI "int nftw(const char *" dirpath ,
.BI " int (*" fn ")(const char *" fpath ", const struct stat *" sb ,
.BI " int " typeflag ", struct FTW *" ftwbuf ),
.BI " int " nopenfd ", int " flags );
-.PP
+.P
.B [[deprecated]]
.BI "int ftw(const char *" dirpath ,
.BI " int (*" fn ")(const char *" fpath ", const struct stat *" sb ,
.BI " int " typeflag ),
.BI " int " nopenfd );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR nftw ():
.nf
_XOPEN_SOURCE >= 500
and calls \fIfn\fP() once for each entry in the tree.
By default, directories are handled before the files and
subdirectories they contain (preorder traversal).
-.PP
+.P
To avoid using up all of the calling process's file descriptors,
\fInopenfd\fP specifies the maximum number of directories that
.BR nftw ()
.BR nftw ()
uses at most
one file descriptor for each level in the directory tree.
-.PP
+.P
For each entry found in the tree,
.BR nftw ()
calls
.BR stat (2)
for
.IR fpath .
-.PP
+.P
The
.I typeflag
argument passed to
.BR lstat (2)
on the "dangling" symbolic link.
(But see BUGS.)
-.PP
+.P
The fourth argument
.RI ( ftwbuf )
that
supplies when calling
\fIfn\fP()
is a pointer to a structure of type \fIFTW\fP:
-.PP
+.P
.in +4n
.EX
struct FTW {
};
.EE
.in
-.PP
+.P
.I base
is the offset of the filename (i.e., basename component)
in the pathname given in
in the directory tree, relative to the root of the tree
.RI ( dirpath ,
which has depth 0).
-.PP
+.P
To stop the tree walk, \fIfn\fP() returns a nonzero value; this
value will become the return value of
.BR nftw ().
or until it encounters an error (such as a
.BR malloc (3)
failure), in which case it will return \-1.
-.PP
+.P
Because
.BR nftw ()
uses dynamic data structures, the only safe way to
\fIDon't\fP use
.BR longjmp (3)
unless the program is going to terminate.
-.PP
+.P
The \fIflags\fP argument of
.BR nftw ()
is formed by ORing zero or more of the
.BR nftw ()
to return immediately with the return value
\fBFTW_STOP\fP.
-.PP
+.P
Other return values could be associated with new actions in the future;
\fIfn\fP() should not return values other than those listed above.
-.PP
+.P
The feature test macro
.B _GNU_SOURCE
must be defined
.BR FTW_SL .
.SH RETURN VALUE
These functions return 0 on success, and \-1 if an error occurs.
-.PP
+.P
If \fIfn\fP() returns nonzero,
then the tree walk is terminated and the value returned by \fIfn\fP()
is returned as the result of
.BR ftw ()
or
.BR nftw ().
-.PP
+.P
If
.BR nftw ()
is called with the \fBFTW_ACTIONRETVAL\fP flag,
.SH SYNOPSIS
.nf
.B #include <sys/time.h>
-.PP
+.P
.BI "int futimes(int " fd ", const struct timeval " tv [2]);
.BI "int lutimes(const char *" filename ", const struct timeval " tv [2]);
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR futimes (),
.BR lutimes ():
.nf
is specified via a file descriptor,
.IR fd ,
rather than via a pathname.
-.PP
+.P
.BR lutimes ()
changes the access and modification times of a file in the same way as
.BR utimes (2),
The
.I /proc
filesystem could not be accessed.
-.PP
+.P
The following additional error may occur for
.BR lutimes ():
.TP
.SH SYNOPSIS
.nf
.B #include <wchar.h>
-.PP
+.P
.BI "int fwide(FILE *" stream ", int " mode );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR fwide ():
.nf
_XOPEN_SOURCE >= 500 || _ISOC99_SOURCE
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).
-.PP
+.P
Once a stream has an orientation, it cannot be changed and persists until
the stream is closed.
-.PP
+.P
When \fImode\fP is nonzero, the
.BR fwide ()
function first attempts to set
and
.B %ls
directives.
-.PP
+.P
Char oriented output to a wide-character oriented stream can be performed
through the
.BR fwprintf (3)
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "[[deprecated]] double gamma(double " x ");"
.BI "[[deprecated]] float gammaf(float " x ");"
.BI "[[deprecated]] long double gammal(long double " x ");"
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR gamma ():
.nf
_XOPEN_SOURCE
|| /* Since glibc 2.19: */ _DEFAULT_SOURCE
|| /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
.fi
-.PP
+.P
.BR gammaf (),
.BR gammal ():
.nf
or the
.BR lgamma (3)
functions, as appropriate.
-.PP
+.P
For the definition of the Gamma function, see
.BR tgamma (3).
.SS *BSD version
None.
.SH HISTORY
SVID 2.
-.PP
+.P
Because of historical variations in behavior across systems,
this function is not specified in any recent standard.
-.PP
+.P
4.2BSD had a
.BR gamma ()
that computed
In 4.3BSD the name was changed to
.BR lgamma (3),
and the man page promises
-.PP
+.P
.in +4n
"At some time in the future the name gamma will be rehabilitated
and used for the Gamma function"
.in
-.PP
+.P
This did indeed happen in 4.4BSD, where
.BR gamma ()
computes the Gamma function (with no effect on
.SH SYNOPSIS
.nf
.B #include <stdlib.h>
-.PP
+.P
.BI "char *gcvt(double " number ", int " ndigit ", char *" buf );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR gcvt ():
.nf
Since glibc 2.17
.SH SYNOPSIS
.nf
.B #include <sys/sysinfo.h>
-.PP
+.P
.B int get_nprocs(void);
.B int get_nprocs_conf(void);
.fi
The function
.BR get_nprocs_conf ()
returns the number of processors configured by the operating system.
-.PP
+.P
The function
.BR get_nprocs ()
returns the number of processors currently available in the system.
since they open and parse files in the
.I /sys
filesystem each time they are called.
-.PP
+.P
The following
.BR sysconf (3)
calls make use of the functions documented on this page
to return the same information.
-.PP
+.P
.in +4n
.EX
np = sysconf(_SC_NPROCESSORS_CONF); /* processors configured */
and
.BR get_nprocs_conf ()
can be used.
-.PP
+.P
.\" SRC BEGIN (get_nprocs_conf.c)
.EX
#include <stdio.h>
.SH SYNOPSIS
.nf
.B "#include <sys/sysinfo.h>"
-.PP
+.P
.B long get_phys_pages(void);
.B long get_avphys_pages(void);
.fi
The function
.BR get_phys_pages ()
returns the total number of physical pages of memory available on the system.
-.PP
+.P
The function
.BR get_avphys_pages ()
returns the number of currently available physical pages of memory on the
.BR sysconf (3)
calls provide a portable means of obtaining the same information as the
functions described on this page.
-.PP
+.P
.in +4n
.EX
total_pages = sysconf(_SC_PHYS_PAGES); /* total pages */
and
.BR get_avphys_pages ()
can be used.
-.PP
+.P
.\" SRC BEGIN (get_phys_pages.c)
.EX
#include <stdio.h>
.B #include <sys/types.h>
.B #include <sys/socket.h>
.B #include <netdb.h>
-.PP
+.P
.BI "int getaddrinfo(const char *restrict " node ,
.BI " const char *restrict " service ,
.BI " const struct addrinfo *restrict " hints ,
.BI " struct addrinfo **restrict " res );
-.PP
+.P
.BI "void freeaddrinfo(struct addrinfo *" res );
-.PP
+.P
.BI "const char *gai_strerror(int " errcode );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR getaddrinfo (),
.BR freeaddrinfo (),
.BR gai_strerror ():
functions into a single interface, but unlike the latter functions,
.BR getaddrinfo ()
is reentrant and allows programs to eliminate IPv4-versus-IPv6 dependencies.
-.PP
+.P
The
.I addrinfo
structure used by
.BR getaddrinfo ()
contains the following fields:
-.PP
+.P
.in +4n
.EX
struct addrinfo {
};
.EE
.in
-.PP
+.P
The
.I hints
argument points to an
.I ai_flags
This field specifies additional options, described below.
Multiple flags are specified by bitwise OR-ing them together.
-.PP
+.P
All the other fields in the structure pointed to by
.I hints
must contain either 0 or a null pointer, as appropriate.
-.PP
+.P
Specifying
.I hints
as NULL is equivalent to setting
The
.B AI_NUMERICHOST
flag suppresses any potentially lengthy network host address lookups.
-.PP
+.P
If the
.B AI_PASSIVE
flag is specified in
is not NULL, then the
.B AI_PASSIVE
flag is ignored.
-.PP
+.P
If the
.B AI_PASSIVE
flag is not set in
for IPv6 address);
this is used by applications that intend to communicate
with peers running on the same host.
-.PP
+.P
.I service
sets the port in each returned address structure.
If this argument is a service name (see
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.
-.PP
+.P
Either
.I node
or
.IR service ,
but not both, may be NULL.
-.PP
+.P
The
.BR getaddrinfo ()
function allocates and initializes a linked list of
The items in the linked list are linked by the
.I ai_next
field.
-.PP
+.P
There are several reasons why
the linked list may have more than one
.I addrinfo
system by editing
.I /etc/gai.conf
(available since glibc 2.5).
-.PP
+.P
If
.I hints.ai_flags
includes the
.\" structure was set pointing to the canonical name; that was
.\" more than POSIX.1-2001 specified, or other implementations provided.
.\" MTK, Aug 05
-.PP
+.P
The remaining fields of each returned
.I addrinfo
structure are initialized as follows:
is placed in the
.I ai_addrlen
field.
-.PP
+.P
If
.I hints.ai_flags
includes the
.BR connect (2)
or
.BR bind (2).
-.PP
+.P
If
.I hints.ai_flags
specifies the
is ignored if
.B AI_V4MAPPED
is not also specified.
-.PP
+.P
The
.BR freeaddrinfo ()
function frees the memory that was allocated
Other system error;
.I errno
is set to indicate the error.
-.PP
+.P
The
.BR gai_strerror ()
function translates these error codes to a human readable string,
.nf
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <netdb.h>
-.PP
+.P
.BI "int getaddrinfo_a(int " mode ", struct gaicb *" list [restrict],
.BI " int " nitems ", struct sigevent *restrict " sevp );
.BI "int gai_suspend(const struct gaicb *const " list "[], int " nitems ,
.BI " const struct timespec *" timeout );
-.PP
+.P
.BI "int gai_error(struct gaicb *" req );
.BI "int gai_cancel(struct gaicb *" req );
.fi
.BR getaddrinfo (3),
but allows multiple name look-ups to be performed asynchronously,
with optional notification on completion of look-up operations.
-.PP
+.P
The
.I mode
argument has one of the following values:
See the discussion of the
.I sevp
argument below.
-.PP
+.P
The array
.I list
specifies the look-up requests to process.
Each request is described by a
.I gaicb
structure, defined as follows:
-.PP
+.P
.in +4n
.EX
struct gaicb {
};
.EE
.in
-.PP
+.P
The elements of this structure correspond to the arguments of
.BR getaddrinfo (3).
Thus,
.I addrinfo
structure referenced by the last two elements is described in
.BR getaddrinfo (3).
-.PP
+.P
When
.I mode
is specified as
See
.BR sigevent (3type)
for details.
-.PP
+.P
For
.B SIGEV_SIGNAL
and
.I sevp\->sigev_value.sival_ptr
to
.IR list .
-.PP
+.P
The
.BR gai_suspend ()
function suspends execution of the calling thread,
.I timeout
is NULL, then the call blocks indefinitely
(until one of the events above occurs).
-.PP
+.P
No explicit indication of which request was completed is given;
you must determine which request(s) have completed by iterating with
.BR gai_error ()
over the list of requests.
-.PP
+.P
The
.BR gai_error ()
function returns the status of the request
if the request was not completed yet,
0 if it was handled successfully,
or an error code if the request could not be resolved.
-.PP
+.P
The
.BR gai_cancel ()
function cancels the request
.B EAI_SYSTEM
.I mode
is invalid.
-.PP
+.P
The
.BR gai_suspend ()
function returns 0 if at least one of the listed requests has been completed.
A signal has interrupted the function.
Note that this interruption might have been
caused by signal notification of some completed look-up request.
-.PP
+.P
The
.BR gai_error ()
function can return
or the error code
.B EAI_CANCELED
if the request has been canceled explicitly before it could be finished.
-.PP
+.P
The
.BR gai_cancel ()
function can return one of these values:
.TP
.B EAI_ALLDONE
The request has already completed.
-.PP
+.P
The
.BR gai_strerror (3)
function translates these error codes to a human readable string,
GNU.
.SH HISTORY
glibc 2.2.3.
-.PP
+.P
The interface of
.BR getaddrinfo_a ()
was modeled after the
giving a speed-up compared to resolving the hostnames sequentially using
.BR getaddrinfo (3).
The program might be used like this:
-.PP
+.P
.in +4n
.EX
$ \fB./a.out mirrors.kernel.org enoent.linuxfoundation.org gnu.org\fP
gnu.org: 209.51.188.116
.EE
.in
-.PP
+.P
Here is the program source code
-.PP
+.P
.\" SRC BEGIN (sync.c)
.EX
#define _GNU_SOURCE
.BR getaddrinfo_a ()
front-end.
The notification facility is not demonstrated.
-.PP
+.P
An example session might look like this:
-.PP
+.P
.in +4n
.EX
$ \fB./a.out\fP
[02] gnu.org: 209.51.188.116
.EE
.in
-.PP
+.P
The program source is as follows:
-.PP
+.P
.\" SRC BEGIN (async.c)
.EX
#define _GNU_SOURCE
.SH SYNOPSIS
.nf
.B #include <sys/auxv.h>
-.PP
+.P
.BI "unsigned long getauxval(unsigned long " type );
.fi
.SH DESCRIPTION
a mechanism that the kernel's ELF binary loader
uses to pass certain information to
user space when a program is executed.
-.PP
+.P
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.
.IR type ,
.BR getauxval ()
returns the corresponding value.
-.PP
+.P
The value returned for each
.I type
is given in the following list.
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.
-.PP
+.P
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
.B LD_SHOW_AUXV
environment variable when running a program:
-.PP
+.P
.in +4n
.EX
$ LD_SHOW_AUXV=1 sleep 1
.EE
.in
-.PP
+.P
The auxiliary vector of any process can (subject to file permissions)
be obtained via
.IR /proc/ pid /auxv ;
.SH SYNOPSIS
.nf
.B #include <ucontext.h>
-.PP
+.P
.BI "int getcontext(ucontext_t *" ucp );
.BI "int setcontext(const ucontext_t *" ucp );
.fi
.BR swapcontext (3)
that allow user-level context switching between multiple
threads of control within a process.
-.PP
+.P
The
.I mcontext_t
type is machine-dependent and opaque.
.I ucontext_t
type is a structure that has at least
the following fields:
-.PP
+.P
.in +4n
.EX
typedef struct ucontext_t {
} ucontext_t;
.EE
.in
-.PP
+.P
with
.I sigset_t
and
is the
machine-specific representation of the saved context,
that includes the calling thread's machine registers.
-.PP
+.P
The function
.BR getcontext ()
initializes the structure
pointed to by
.I ucp
to the currently active context.
-.PP
+.P
The function
.BR setcontext ()
restores the user context
.B SA_SIGINFO
flag in
.BR sigaction (2)).
-.PP
+.P
If the context was obtained by a call of
.BR getcontext (),
program execution continues as if this call just returned.
-.PP
+.P
If the context was obtained by a call of
.BR makecontext (3),
program execution continues by a call to the function
first argument of that call to
.BR makecontext (3).
When this member is NULL, the thread exits.
-.PP
+.P
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
None.
.SH HISTORY
SUSv2, POSIX.1-2001.
-.PP
+.P
POSIX.1-2008 removes these functions,
citing portability issues, and
recommending that applications be rewritten to use POSIX threads instead.
call.
The user has to invent their own bookkeeping device, and a register
variable won't do since registers are restored.
-.PP
+.P
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
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.BI "char *getcwd(char " buf [. size "], size_t " size );
.B "char *get_current_dir_name(void);"
-.PP
+.P
.BI "[[deprecated]] char *getwd(char " buf [PATH_MAX]);
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR get_current_dir_name ():
.nf
_GNU_SOURCE
.fi
-.PP
+.P
.BR getwd ():
.nf
Since glibc 2.12:
The pathname is returned as the function result and via the argument
.IR buf ,
if present.
-.PP
+.P
The
.BR getcwd ()
function copies an absolute pathname of the current working directory
.IR buf ,
which is of length
.IR size .
-.PP
+.P
If the length of the absolute pathname of the current working directory,
including the terminating null byte, exceeds
.I size
.BR ERANGE ;
an application should check for this error, and allocate a larger
buffer if necessary.
-.PP
+.P
As an extension to the POSIX.1-2001 standard, glibc's
.BR getcwd ()
allocates the buffer dynamically using
The caller should
.BR free (3)
the returned buffer.
-.PP
+.P
.BR get_current_dir_name ()
will
.BR malloc (3)
The caller should
.BR free (3)
the returned buffer.
-.PP
+.P
.BR getwd ()
does not
.BR malloc (3)
.BR getwd ()
this is the same value as
.IR buf .
-.PP
+.P
On failure, these functions return NULL, and
.I errno
is set to indicate the error.
unspecified if
.I buf
is NULL.
-.PP
+.P
POSIX.1-2001
does not define any errors for
.BR getwd ().
.BR ENAMETOOLONG .
In this case, the library functions fall back to
a (slower) alternative implementation that returns the full pathname.
-.PP
+.P
Following a change in Linux 2.6.36,
.\" commit 8df9d1a4142311c084ffeeacb67cd34d190eff74
the pathname returned by the
Use
.BR getcwd ()
instead.
-.PP
+.P
Under Linux, these functions make use of the
.BR getcwd ()
system call (available since Linux 2.1.92).
.SH SYNOPSIS
.nf
.B "#include <time.h>"
-.PP
+.P
.BI "struct tm *getdate(const char *" string );
-.PP
+.P
.B "extern int getdate_err;"
-.PP
+.P
.BI "int getdate_r(const char *restrict " string ", struct tm *restrict " res );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR getdate ():
.nf
_XOPEN_SOURCE >= 500
.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
.fi
-.PP
+.P
.BR getdate_r ():
.nf
_GNU_SOURCE
structure is allocated in static storage,
and consequently it will be overwritten by further calls to
.BR getdate ().
-.PP
+.P
In contrast to
.BR strptime (3),
(which has a
.BR DATEMSK .
The first line in the file that matches the given input string
is used for the conversion.
-.PP
+.P
The matching is done case insensitively.
Superfluous whitespace, either in the pattern or in the string to
be converted, is ignored.
-.PP
+.P
The conversion specifications that a pattern can contain are those given for
.BR strptime (3).
One more conversion specification is specified in POSIX.1-2001:
.\" Looking at the glibc 2.21 source code, where the implementation uses
.\" strptime(), suggests that it might be supported.
This is not implemented in glibc.
-.PP
+.P
When
.B %Z
is given, the structure containing the broken-down time
Otherwise, the structure is initialized to the broken-down time
corresponding to the current local time (as by a call to
.BR localtime (3)).
-.PP
+.P
When only the day of the week is given,
the day is taken to be the first such day
on or after today.
-.PP
+.P
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.
-.PP
+.P
When no hour, minute, and second are given, the current
hour, minute, and second are taken.
-.PP
+.P
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.
-.PP
+.P
.BR getdate_r ()
is a GNU extension that provides a reentrant version of
.BR getdate ().
Changes to
.I errno
are unspecified.
-.PP
+.P
On success
.BR getdate_r ()
returns 0;
.I tm
structure.
The following shell session demonstrates the operation of the program:
-.PP
+.P
.in +4n
.EX
.RB "$" " TFILE=$PWD/tfile"
.SH SYNOPSIS
.nf
.B #include <dirent.h>
-.PP
+.P
.BI "ssize_t getdirentries(int " fd ", char " buf "[restrict ." nbytes "], \
size_t " nbytes ,
.BI " off_t *restrict " basep );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR getdirentries ():
.nf
Since glibc 2.19:
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.B int getdtablesize(void);
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR getdtablesize ():
.nf
Since glibc 2.20:
.\" The libc4 and libc5 versions return
.\" .B OPEN_MAX
.\" (set to 256 since Linux 0.98.4).
-.PP
+.P
Portable applications should employ
.I sysconf(_SC_OPEN_MAX)
instead of this call.
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.BI "int getentropy(void " buffer [. length "], size_t " length );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR getentropy ():
.nf
_DEFAULT_SOURCE
The maximum permitted value for the
.I length
argument is 256.
-.PP
+.P
A successful call to
.BR getentropy ()
always provides the requested number of bytes of entropy.
.BR getentropy ()
function is implemented using
.BR getrandom (2).
-.PP
+.P
Whereas the glibc wrapper makes
.BR getrandom (2)
a cancelation point,
.BR getentropy ()
is not a cancelation point.
-.PP
+.P
.BR getentropy ()
is also declared in
.BR <sys/random.h> .
(No feature test macro need be defined to obtain the declaration from
that header file.)
-.PP
+.P
A call to
.BR getentropy ()
may block if the system has just booted and the kernel has
.SH SYNOPSIS
.nf
.B #include <stdlib.h>
-.PP
+.P
.BI "char *getenv(const char *" name );
.BI "char *secure_getenv(const char *" name );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR secure_getenv ():
.nf
_GNU_SOURCE
and returns a pointer to the corresponding
.I value
string.
-.PP
+.P
The GNU-specific
.BR secure_getenv ()
function is just like
the effective capability bit was set on the executable file; or
.IP \[bu]
the process has a nonempty permitted capability set.
-.PP
+.P
Secure execution may also be required if triggered
by some Linux security modules.
-.PP
+.P
The
.BR secure_getenv ()
function is intended for use in general-purpose libraries
glibc 2.17.
.SH NOTES
The strings in the environment list are of the form \fIname=value\fP.
-.PP
+.P
As typically implemented,
.BR 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.
-.PP
+.P
The implementation of
.BR getenv ()
is not required to be reentrant.
.BR setenv (3),
or
.BR unsetenv (3).
-.PP
+.P
The "secure execution" mode of
.BR secure_getenv ()
is controlled by the
.SH SYNOPSIS
.nf
.B #include <fstab.h>
-.PP
+.P
.B "int setfsent(void);"
.B "struct fstab *getfsent(void);"
.B "void endfsent(void);"
-.PP
+.P
.BI "struct fstab *getfsfile(const char *" mount_point );
.BI "struct fstab *getfsspec(const char *" special_file );
.fi
The
.I struct fstab
is defined by:
-.PP
+.P
.in +4n
.EX
struct fstab {
};
.EE
.in
-.PP
+.P
Here the field
.I 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).
-.PP
+.P
The function
.BR setfsent ()
opens the file when required and positions it at the first line.
-.PP
+.P
The function
.BR getfsent ()
parses the next line from the file.
(After opening it when required.)
-.PP
+.P
The function
.BR endfsent ()
closes the file when required.
-.PP
+.P
The function
.BR getfsspec ()
searches the file from the start and returns the first entry found
field matches the
.I special_file
argument.
-.PP
+.P
The function
.BR getfsfile ()
searches the file from the start and returns the first entry found
function appeared in 4.0BSD; the other four functions appeared in 4.3BSD.
.SH NOTES
These functions are not thread-safe.
-.PP
+.P
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,
.nf
.B #include <sys/types.h>
.B #include <grp.h>
-.PP
+.P
.B struct group *getgrent(void);
-.PP
+.P
.B void setgrent(void);
.B void endgrent(void);
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR setgrent ():
.nf
_XOPEN_SOURCE >= 500
|| /* glibc >= 2.19: */ _DEFAULT_SOURCE
|| /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
.fi
-.PP
+.P
.BR getgrent (),
.BR endgrent ():
.nf
.BR getgrent ()
is called,
it returns the first entry; thereafter, it returns successive entries.
-.PP
+.P
The
.BR setgrent ()
function rewinds to the beginning
of the group database, to allow repeated scans.
-.PP
+.P
The
.BR endgrent ()
function is used to close the group database
after all processing has been performed.
-.PP
+.P
The \fIgroup\fP structure is defined in \fI<grp.h>\fP as follows:
-.PP
+.P
.in +4n
.EX
struct group {
};
.EE
.in
-.PP
+.P
For more information about the fields of this structure, see
.BR group (5).
.SH RETURN VALUE
.I group
structure,
or NULL if there are no more entries or an error occurs.
-.PP
+.P
Upon error,
.I errno
may be set.
If one wants to check
.I errno
after the call, it should be set to zero before the call.
-.PP
+.P
The return value may point to a static area, and may be overwritten
by subsequent calls to
.BR getgrent (),
MT-Unsafe race:grent locale
T}
.TE
-.PP
+.P
In the above table,
.I grent
in
.SH SYNOPSIS
.nf
.B #include <grp.h>
-.PP
+.P
.BI "int getgrent_r(struct group *restrict " gbuf ,
.BI " char " buf "[restrict ." buflen "], size_t " buflen ,
.BI " struct group **restrict " gbufp );
.BI " char " buf "[restrict ." buflen "], size_t " buflen ,
.BI " struct group **restrict " gbufp );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR getgrent_r ():
.nf
_GNU_SOURCE
.fi
.\" FIXME . The FTM requirements seem inconsistent here. File a glibc bug?
-.PP
+.P
.BR fgetgrent_r ():
.nf
Since glibc 2.19:
.BR setgrent (3).
The latter reads the next group entry from
.IR stream .
-.PP
+.P
The \fIgroup\fP structure is defined in
.I <grp.h>
as follows:
-.PP
+.P
.in +4n
.EX
struct group {
};
.EE
.in
-.PP
+.P
For more information about the fields of this structure, see
.BR group (5).
-.PP
+.P
The nonreentrant functions return a pointer to static storage,
where this static storage contains further pointers to group
name, password, and members.
MT-Safe
T}
.TE
-.PP
+.P
In the above table,
.I grent
in
then data races could occur.
.SH VERSIONS
Other systems use the prototype
-.PP
+.P
.in +4n
.EX
struct group *getgrent_r(struct group *grp, char *buf,
int buflen);
.EE
.in
-.PP
+.P
or, better,
-.PP
+.P
.in +4n
.EX
int getgrent_r(struct group *grp, char *buf, int buflen,
.nf
.B #include <sys/types.h>
.B #include <grp.h>
-.PP
+.P
.BI "struct group *getgrnam(const char *" name );
.BI "struct group *getgrgid(gid_t " gid );
-.PP
+.P
.BI "int getgrnam_r(const char *restrict " name \
", struct group *restrict " grp ,
.BI " char " buf "[restrict ." buflen "], size_t " buflen ,
.BI " char " buf "[restrict ." buflen "], size_t " buflen ,
.BI " struct group **restrict " result );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR getgrnam_r (),
.BR getgrgid_r ():
.nf
NIS, and LDAP)
that matches the group name
.IR name .
-.PP
+.P
The
.BR 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
.IR gid .
-.PP
+.P
The \fIgroup\fP structure is defined in \fI<grp.h>\fP as follows:
-.PP
+.P
.in +4n
.EX
struct group {
};
.EE
.in
-.PP
+.P
For more information about the fields of this structure, see
.BR group (5).
-.PP
+.P
The
.BR getgrnam_r ()
and
A pointer to the result (in case of success) or NULL (in case no entry
was found or an error occurred) is stored in
.IR *result .
-.PP
+.P
The call
-.PP
+.P
.in +4n
.EX
sysconf(_SC_GETGR_R_SIZE_MAX)
.EE
.in
-.PP
+.P
returns either \-1, without changing
.IR errno ,
or an initial suggested size for
If one wants to check
.I errno
after the call, it should be set to zero before the call.
-.PP
+.P
The return value may point to a static area, and may be overwritten
by subsequent calls to
.BR getgrent (3),
.BR getgrnam ().
(Do not pass the returned pointer to
.BR free (3).)
-.PP
+.P
On success,
.BR getgrnam_r ()
and
.SH SYNOPSIS
.nf
.B #include <grp.h>
-.PP
+.P
.BI "int getgrouplist(const char *" user ", gid_t " group ,
.BI " gid_t *" groups ", int *" ngroups );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR getgrouplist ():
.nf
Since glibc 2.19:
.I *ngroups
of these groups are returned in the array
.IR groups .
-.PP
+.P
If it was not among the groups defined for
.I user
in the group database, then
typically this argument is specified as the group ID from
the password record for
.IR user .
-.PP
+.P
The
.I ngroups
argument is a value-result argument:
then the value
.I *ngroups
is returned.
-.PP
+.P
If the user is a member of more than
.I *ngroups
groups, then
value to be supplied to
.BR getgrouplist ().
The following shell session shows examples of the use of this program:
-.PP
+.P
.in +4n
.EX
.RB "$" " ./a.out cecilia 0"
.SH SYNOPSIS
.nf
.B #include <netdb.h>
-.PP
+.P
.BI "void sethostent(int " stayopen );
.B void endhostent(void);
-.PP
+.P
.B [[deprecated]] extern int h_errno;
-.PP
+.P
.BI "[[deprecated]] struct hostent *gethostbyname(const char *" name );
.BI "[[deprecated]] struct hostent *gethostbyaddr(const void " addr [. len ],
.BI " socklen_t " len ", int " type );
-.PP
+.P
.BI "[[deprecated]] void herror(const char *" s );
.BI "[[deprecated]] const char *hstrerror(int " err );
-.PP
+.P
/* System V/POSIX extension */
.B struct hostent *gethostent(void);
-.PP
+.P
/* GNU extensions */
.B [[deprecated]]
.BI "struct hostent *gethostbyname2(const char *" name ", int " af );
-.PP
+.P
.BI "int gethostent_r(struct hostent *restrict " ret ,
.BI " char " buf "[restrict ." buflen "], size_t " buflen ,
.BI " struct hostent **restrict " result ,
.BI " int *restrict " h_errnop );
-.PP
+.P
.B [[deprecated]]
.BI "int gethostbyaddr_r(const void " addr "[restrict ." len "], socklen_t " len ,
.BI " int " type ,
.BI " struct hostent **restrict " result ,
.BI " int *restrict " h_errnop );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR gethostbyname2 (),
.BR gethostent_r (),
.BR gethostbyaddr_r (),
glibc up to and including 2.19:
_BSD_SOURCE || _SVID_SOURCE
.fi
-.PP
+.P
.BR herror (),
.BR hstrerror ():
.nf
Before glibc 2.8:
none
.fi
-.PP
+.P
.BR h_errno :
.nf
Since glibc 2.19
and
.BR gai_strerror (3)
instead.
-.PP
+.P
The
.BR sethostent ()
function specifies, if \fIstayopen\fP 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.
-.PP
+.P
The
.BR endhostent ()
function ends the use of a TCP connection for name
server queries.
-.PP
+.P
The
.BR gethostbyname ()
function returns a structure of type
for the file format).
The current domain and its parents are searched unless \fIname\fP
ends in a dot.
-.PP
+.P
The
.BR gethostbyaddr ()
function returns a structure of type \fIhostent\fP
.BR inet_addr (3))
for address type
.BR AF_INET .
-.PP
+.P
The (obsolete)
.BR herror ()
function prints the error message associated
with the current value of \fIh_errno\fP on \fIstderr\fP.
-.PP
+.P
The (obsolete)
.BR hstrerror ()
function takes an error number
(typically \fIh_errno\fP) and returns the corresponding message string.
-.PP
+.P
The domain name queries carried out by
.BR gethostbyname ()
and
The
.BR nsswitch.conf (5)
file is the modern way of controlling the order of host lookups.
-.PP
+.P
In glibc 2.4 and earlier, the
.I order
keyword was used to control the order of host lookups as defined in
.I /etc/host.conf
.RB ( host.conf (5)).
-.PP
+.P
The \fIhostent\fP structure is defined in \fI<netdb.h>\fP as follows:
-.PP
+.P
.in +4n
.EX
struct hostent {
#define h_addr h_addr_list[0] /* for backward compatibility */
.EE
.in
-.PP
+.P
The members of the \fIhostent\fP structure are:
.TP
.I h_name
.BR gethostbyname2_r ()
T} Thread safety MT-Safe env locale
.TE
-.PP
+.P
In the above table,
.I hostent
in
Copying the
.I struct hostent
does not suffice, since it contains pointers; a deep copy is required.
-.PP
+.P
In the original BSD implementation the
.I len
argument
which is OK.)
See also
.BR accept (2).
-.PP
+.P
The BSD prototype for
.BR gethostbyaddr ()
uses
that works like
.BR gethostbyname (),
but permits to specify the address family to which the address must belong.
-.PP
+.P
glibc2 also has reentrant versions
.BR gethostent_r (),
.BR gethostbyaddr_r (),
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.B long gethostid(void);
.BI "int sethostid(long " hostid );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR gethostid ():
.nf
Since glibc 2.20:
_BSD_SOURCE || _XOPEN_SOURCE >= 500
.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
.fi
-.PP
+.P
.BR sethostid ():
.nf
Since glibc 2.21:
machine, as returned by
.BR gethostbyname (3),
and thus usually never needs to be set.
-.PP
+.P
The
.BR sethostid ()
call is restricted to the superuser.
.BR gethostid ()
returns the 32-bit identifier for the current host as set by
.BR sethostid ().
-.PP
+.P
On success,
.BR sethostid ()
returns 0; on error, \-1 is returned, and
.I /var/adm/hostid
was used.)
.\" libc5 used /etc/hostid; libc4 didn't have these functions
-.PP
+.P
In the glibc implementation, if
.BR gethostid ()
cannot open the file containing the host ID,
.nf
.B #include <sys/types.h>
.B #include <ifaddrs.h>
-.PP
+.P
.BI "int getifaddrs(struct ifaddrs **" "ifap" );
.BI "void freeifaddrs(struct ifaddrs *" "ifa" );
.fi
The list consists of
.I ifaddrs
structures, defined as follows:
-.PP
+.P
.in +4n
.EX
struct ifaddrs {
};
.EE
.in
-.PP
+.P
The
.I ifa_next
field contains a pointer to the next structure on the list,
or NULL if this is the last item of the list.
-.PP
+.P
The
.I ifa_name
points to the null-terminated interface name.
.\" The constant
.\" .B IF NAMESIZE
.\" indicates the maximum length of this field.
-.PP
+.P
The
.I ifa_flags
field contains the interface flags, as returned by the
operation (see
.BR netdevice (7)
for a list of these flags).
-.PP
+.P
The
.I ifa_addr
field points to a structure containing the interface address.
subfield should be consulted to determine the format of the
address structure.)
This field may contain a null pointer.
-.PP
+.P
The
.I ifa_netmask
field points to a structure containing the netmask associated with
.IR ifa_addr ,
if applicable for the address family.
This field may contain a null pointer.
-.PP
+.P
Depending on whether the bit
.B IFF_BROADCAST
or
(if applicable for the address family) or
.I ifa_dstaddr
will contain the destination address of the point-to-point interface.
-.PP
+.P
The
.I 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.
-.PP
+.P
The data returned by
.BR getifaddrs ()
is dynamically allocated and should be freed using
.\" appears to be confused and obsolete on this point.
.\" i.e., commonly it still says one of them will be NULL, even if
.\" the ifa_ifu union is already present
-.PP
+.P
.BR getifaddrs ()
first appeared in glibc 2.3, but before glibc 2.3.3,
the implementation supported only IPv4 addresses;
and
.BR getnameinfo (3).
Here is what we see when running this program on one system:
-.PP
+.P
.in +4n
.EX
$ \fB./a.out\fP
.B #include <sys/types.h>
.B #include <sys/socket.h>
.B #include <netdb.h>
-.PP
+.P
.BI "[[deprecated]] struct hostent *getipnodebyname(const char *" name ", int " af ,
.BI " int " flags ", int *" error_num );
.BI "[[deprecated]] struct hostent *getipnodebyaddr(const void " addr [. len ],
and
.BR getnameinfo (3)
instead.
-.PP
+.P
The
.BR getipnodebyname ()
and
functions return the names and addresses of a network host.
These functions return a pointer to the
following structure:
-.PP
+.P
.in +4n
.EX
struct hostent {
};
.EE
.in
-.PP
+.P
These functions replace the
.BR gethostbyname (3)
and
and
.BR getipnodebyaddr ()
functions can access multiple network address families.
-.PP
+.P
Unlike the
.B gethostby
functions,
.I name
argument points to a hexadecimal IPv6 address or a name
of an IPv6 network host.
-.PP
+.P
The
.I flags
argument specifies additional options.
.B TRY_AGAIN
The domain name server returned a temporary failure response.
You might have better luck next time.
-.PP
+.P
A successful query returns a pointer to a
.I hostent
structure that contains the following fields:
.SH HISTORY
.\" Not in POSIX.1-2001.
RFC\ 2553.
-.PP
+.P
Present in glibc 2.1.91-95, but removed again.
Several UNIX-like systems support them, but all
call them deprecated.
.SH SYNOPSIS
.nf
.B #include <stdio.h>
-.PP
+.P
.BI "ssize_t getline(char **restrict " lineptr ", size_t *restrict " n ,
.BI " FILE *restrict " stream );
.BI "ssize_t getdelim(char **restrict " lineptr ", size_t *restrict " n ,
.BI " int " delim ", FILE *restrict " stream );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR getline (),
.BR getdelim ():
.nf
.IR *lineptr .
The buffer is null-terminated and includes the newline character, if
one was found.
-.PP
+.P
If
.I *lineptr
is set to NULL before the call, then
even if
.BR getline ()
failed.
-.PP
+.P
Alternatively, before calling
.BR getline (),
.I *lineptr
and
.I *n
as necessary.
-.PP
+.P
In either case, on a successful call,
.I *lineptr
and
.I *n
will be updated to reflect the buffer address and allocated size respectively.
-.PP
+.P
.BR getdelim ()
works like
.BR getline (),
but not including the terminating null byte (\[aq]\e0\[aq]).
This value can be used
to handle embedded null bytes in the line read.
-.PP
+.P
Both functions return \-1 on failure to read a line (including end-of-file
condition).
In the event of a failure,
.I errno
is set to indicate the error.
-.PP
+.P
If
.I *lineptr
was set to NULL before the call, then the buffer should be freed by the
.SH SYNOPSIS
.nf
.B #include <stdlib.h>
-.PP
+.P
.BI "int getloadavg(double " loadavg[] ", int " nelem );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR getloadavg ():
.nf
Since glibc 2.19:
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.B "char *getlogin(void);"
.BI "int getlogin_r(char " buf [. bufsize "], size_t " bufsize );
-.PP
+.P
.B #include <stdio.h>
-.PP
+.P
.BI "char *cuserid(char *" string );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR getlogin_r ():
.nf
.\" Deprecated: _REENTRANT ||
_POSIX_C_SOURCE >= 199506L
.fi
-.PP
+.P
.BR cuserid ():
.nf
Since glibc 2.24:
statically allocated and might be overwritten on subsequent calls to
this function or to
.BR cuserid ().
-.PP
+.P
.BR getlogin_r ()
returns this same username in the array
.I buf
of size
.IR bufsize .
-.PP
+.P
.BR cuserid ()
returns a pointer to a string containing a username
associated with the effective user ID of the process.
string is statically allocated and might be overwritten on subsequent
calls to this function or to
.BR getlogin ().
-.PP
+.P
The macro \fBL_cuserid\fP is an integer constant that indicates how
long an array you might need to store a username.
\fBL_cuserid\fP is declared in \fI<stdio.h>\fP.
-.PP
+.P
These functions let your program identify positively the user who is
running
.RB ( cuserid ())
or the user who logged in this session
.RB ( getlogin ()).
(These can differ when set-user-ID programs are involved.)
-.PP
+.P
For most purposes, it is more useful to use the environment variable
\fBLOGNAME\fP to find out who the user is.
This is more flexible
The length of the username, including the terminating null byte (\[aq]\e0\[aq]),
is larger than
.IR bufsize .
-.PP
+.P
Linux/glibc also has:
.TP
.B ENOENT
MT-Unsafe race:cuserid/!string locale
T}
.TE
-.PP
+.P
In the above table,
.I utent
in
Avoid
.BR getlogin ()
for security-related purposes.
-.PP
+.P
Note that glibc does not follow the POSIX specification and uses
.I stdin
instead of
all return the login name also when
.I stdin
is redirected.)
-.PP
+.P
Nobody knows precisely what
.BR cuserid ()
does; avoid it in portable programs.
.nf
.B #include <stdio.h>
.B #include <mntent.h>
-.PP
+.P
.BI "FILE *setmntent(const char *" filename ", const char *" type );
-.PP
+.P
.BI "struct mntent *getmntent(FILE *" stream );
-.PP
+.P
.BI "int addmntent(FILE *restrict " stream ,
.BI " const struct mntent *restrict " mnt );
-.PP
+.P
.BI "int endmntent(FILE *" streamp );
-.PP
+.P
.BI "char *hasmntopt(const struct mntent *" mnt ", const char *" opt );
-.PP
+.P
/* GNU extension */
.B #include <mntent.h>
-.PP
+.P
.BI "struct mntent *getmntent_r(FILE *restrict " streamp ,
.BI " struct mntent *restrict " mntbuf ,
.BI " char " buf "[restrict ." buflen "], int " buflen );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR getmntent_r ():
.nf
Since glibc 2.19:
.I /etc/fstab
and the mounted filesystem description file
.IR /etc/mtab .
-.PP
+.P
The
.BR setmntent ()
function opens the filesystem description file
.BR endmntent ()
rather than
.BR fclose (3).
-.PP
+.P
The
.BR getmntent ()
function reads the next line of the filesystem
points to a static area of memory which is overwritten by subsequent
calls to
.BR getmntent ().
-.PP
+.P
The
.BR addmntent ()
function adds the
to
the end of the open
.IR stream .
-.PP
+.P
The
.BR endmntent ()
function closes the
.I stream
associated with the filesystem description file.
-.PP
+.P
The
.BR hasmntopt ()
function scans the
and
.BR mount (8)
for valid mount options.
-.PP
+.P
The reentrant
.BR getmntent_r ()
function is similar to
.I buf
of size
.IR buflen .
-.PP
+.P
The
.I mntent
structure is defined in
.I <mntent.h>
as follows:
-.PP
+.P
.in +4n
.EX
struct mntent {
};
.EE
.in
-.PP
+.P
Since fields in the mtab and fstab files are separated by whitespace,
octal escapes are used to represent the characters space (\e040),
tab (\e011), newline (\e012), and backslash (\e\e) in those files
a pointer to the
.I mntent
structure or NULL on failure.
-.PP
+.P
The
.BR addmntent ()
function returns 0 on success and 1 on failure.
-.PP
+.P
The
.BR endmntent ()
function always returns 1.
-.PP
+.P
The
.BR hasmntopt ()
function returns the address of the substring if
was introduced in HP-UX 10, but it returns an
.IR int .
The prototype shown above is glibc-only.
-.PP
+.P
System V also has a
.BR getmntent ()
function but the calling sequence
.nf
.B #include <sys/socket.h>
.B #include <netdb.h>
-.PP
+.P
.BI "int getnameinfo(const struct sockaddr *restrict " addr \
", socklen_t " addrlen ,
.BI " char " host "[_Nullable restrict ." hostlen ],
.BI " socklen_t " servlen ,
.BI " int " flags );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR getnameinfo ():
.nf
Since glibc 2.22:
.BR getnameinfo ()
is reentrant and allows programs to eliminate
IPv4-versus-IPv6 dependencies.
-.PP
+.P
The
.I addr
argument is a pointer to a generic socket address structure
.BR getnameinfo ()
places null-terminated strings containing the host and
service names respectively.
-.PP
+.P
The caller can specify that no hostname (or no service name)
is required by providing a NULL
.I host
argument.
However, at least one of hostname or service name
must be requested.
-.PP
+.P
The
.I flags
argument modifies the behavior of
A system error occurred.
The error code can be found in
.IR errno .
-.PP
+.P
The
.BR gai_strerror (3)
function translates these error codes to a human readable string,
.SH HISTORY
glibc 2.1.
POSIX.1-2001.
-.PP
+.P
Before glibc 2.2, the
.I hostlen
and
for the supplied buffers,
.I <netdb.h>
defines the constants
-.PP
+.P
.in +4n
.EX
#define NI_MAXHOST 1025
#define NI_MAXSERV 32
.EE
.in
-.PP
+.P
Since glibc 2.8,
these definitions are exposed only if suitable
feature test macros are defined, namely:
.B _BSD_SOURCE
or
.BR _SVID_SOURCE .
-.PP
+.P
The former is the constant
.B MAXDNAME
in recent versions of BIND's
for a given socket address.
Note that there is no hardcoded reference to
a particular address family.
-.PP
+.P
.in +4n
.EX
struct sockaddr *addr; /* input */
printf("host=%s, serv=%s\en", hbuf, sbuf);
.EE
.in
-.PP
+.P
The following version checks if the socket address has a
reverse address mapping.
-.PP
+.P
.in +4n
.EX
struct sockaddr *addr; /* input */
printf("host=%s\en", hbuf);
.EE
.in
-.PP
+.P
An example program using
.BR getnameinfo ()
can be found in
.BR services (5),
.BR hostname (7),
.BR named (8)
-.PP
+.P
R.\& Gilligan, S.\& Thomson, J.\& Bound and W.\& Stevens,
.IR "Basic Socket Interface Extensions for IPv6" ,
RFC\ 2553, March 1999.
-.PP
+.P
Tatsuya Jinmei and Atsushi Onoe,
.IR "An Extension of Format for IPv6 Scoped Addresses" ,
internet draft, work in progress
.UR ftp://ftp.ietf.org\:/internet\-drafts\:/draft\-ietf\-ipngwg\-scopedaddr\-format\-02.txt
.UE .
-.PP
+.P
Craig Metz,
.IR "Protocol Independence Using the Sockets API" ,
Proceedings of the freenix track:
.SH SYNOPSIS
.nf
.B #include <netdb.h>
-.PP
+.P
.B struct netent *getnetent(void);
-.PP
+.P
.BI "struct netent *getnetbyname(const char *" name );
.BI "struct netent *getnetbyaddr(uint32_t " net ", int " type );
-.PP
+.P
.BI "void setnetent(int " stayopen );
.B void endnetent(void);
.fi
structure containing
the broken-out fields from the entry.
A connection is opened to the database if necessary.
-.PP
+.P
The
.BR getnetbyname ()
function returns a
for the entry from the database
that matches the network
.IR name .
-.PP
+.P
The
.BR getnetbyaddr ()
function returns a
The
.I net
argument must be in host byte order.
-.PP
+.P
The
.BR setnetent ()
function opens a connection to the database,
will not be closed between calls to one of the
.BR getnet* ()
functions.
-.PP
+.P
The
.BR endnetent ()
function closes the connection to the database.
-.PP
+.P
The
.I netent
structure is defined in
.I <netdb.h>
as follows:
-.PP
+.P
.in +4n
.EX
struct netent {
}
.EE
.in
-.PP
+.P
The members of the
.I netent
structure are:
locale
T}
.TE
-.PP
+.P
In the above table,
.I netent
in
POSIX.1-2008.
.SH HISTORY
POSIX.1-2001, 4.3BSD.
-.PP
+.P
Before glibc 2.2, the
.I net
argument of
.SH SYNOPSIS
.nf
.B #include <netdb.h>
-.PP
+.P
.BI "int getnetent_r(struct netent *restrict " result_buf ,
.BI " char " buf "[restrict ." buflen "], size_t " buflen ,
.BI " struct netent **restrict " result ,
.BI " char " buf "[restrict ." buflen "], size_t " buflen ,
.BI " struct netent **restrict " result ,
.BI " int *restrict " h_errnop );
-.PP
+.P
.fi
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR getnetent_r (),
.BR getnetbyname_r (),
.BR getnetbyaddr_r ():
and in the function calling signature and return value.
This manual page describes just the differences from
the nonreentrant functions.
-.PP
+.P
Instead of returning a pointer to a statically allocated
.I netent
structure as the function result,
these functions copy the structure into the location pointed to by
.IR result_buf .
-.PP
+.P
The
.I buf
array is used to store the string fields pointed to by the returned
(A buffer of length 1024 bytes should be sufficient for most applications.)
.\" I can find no information on the required/recommended buffer size;
.\" the nonreentrant functions use a 1024 byte buffer -- mtk.
-.PP
+.P
If the function call successfully obtains a network record, then
.I *result
is set pointing to
otherwise,
.I *result
is set to NULL.
-.PP
+.P
The buffer pointed to by
.I h_errnop
is used to return the value that would be stored in the global variable
.SH RETURN VALUE
On success, these functions return 0.
On error, they return one of the positive error numbers listed in ERRORS.
-.PP
+.P
On error, record not found
.RB ( getnetbyname_r (),
.BR getnetbyaddr_r ()),
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.BI "int getopt(int " argc ", char *" argv [],
.BI " const char *" optstring );
-.PP
+.P
.BI "extern char *" optarg ;
.BI "extern int " optind ", " opterr ", " optopt ;
-.PP
+.P
.B #include <getopt.h>
-.PP
+.P
.BI "int getopt_long(int " argc ", char *" argv [],
.BI " const char *" optstring ,
.BI " const struct option *" longopts ", int *" longindex );
.BI " const char *" optstring ,
.BI " const struct option *" longopts ", int *" longindex );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR getopt ():
.nf
_POSIX_C_SOURCE >= 2 || _XOPEN_SOURCE
.fi
-.PP
+.P
.BR getopt_long (),
.BR getopt_long_only ():
.nf
.BR getopt ()
is called repeatedly, it returns successively each of the option characters
from each of the option elements.
-.PP
+.P
The variable
.I optind
is the index of the next element to be processed in
The caller can reset it to 1 to restart scanning of the same
.IR argv ,
or when scanning a new argument vector.
-.PP
+.P
If
.BR getopt ()
finds another option character, it returns that
can
resume the scan with the following option character or
\fIargv\fP-element.
-.PP
+.P
If there are no more option characters,
.BR getopt ()
returns \-1.
Then \fIoptind\fP is the index in \fIargv\fP of the first
\fIargv\fP-element that is not an option.
-.PP
+.P
.I optstring
is a string containing the legitimate option characters.
A legitimate option character is any visible one byte
option is reserved by POSIX.2 for implementation extensions.)
This behavior is a GNU extension, not available with libraries before
glibc 2.
-.PP
+.P
By default,
.BR getopt ()
permutes the contents of \fIargv\fP as it
and that care about the ordering of the two.)
The special argument "\-\-" forces an end of option-scanning regardless
of the scanning mode.
-.PP
+.P
While processing the option list,
.BR getopt ()
can detect two kinds of errors:
.B \-\-arg=param
or
.BR "\-\-arg param" .
-.PP
+.P
.I longopts
is a pointer to the first element of an array of
.I struct option
declared in
.I <getopt.h>
as
-.PP
+.P
.in +4n
.EX
struct option {
};
.EE
.in
-.PP
+.P
The meanings of the different fields are:
.TP
.I name
\fIval\fP
is the value to return, or to load into the variable pointed
to by \fIflag\fP.
-.PP
+.P
The last element of the array has to be filled with zeros.
-.PP
+.P
If \fIlongindex\fP is not NULL, it
points to a variable which is set to the index of the long option relative to
.IR longopts .
-.PP
+.P
.BR getopt_long_only ()
is like
.BR getopt_long (),
.IR optstring :
if it is \[aq]:\[aq], then \[aq]:\[aq] is returned;
otherwise \[aq]?\[aq] is returned.
-.PP
+.P
.BR getopt_long ()
and
.BR getopt_long_only ()
.TP
.BR getopt ()
POSIX.1-2001, and POSIX.2.
-.PP
+.P
On some older implementations,
.BR getopt ()
was declared in
.B POSIXLY_CORRECT
and checks for GNU extensions in
.IR optstring .)
-.PP
+.P
Command-line arguments are parsed in strict order
meaning that an option requiring an argument will consume the next argument,
regardless of whether that argument is the correctly specified option argument
with no associated value; and
.IR "\-t val" ,
which expects an associated value.
-.PP
+.P
.\" SRC BEGIN (getopt.c)
.EX
#include <stdio.h>
The following example program illustrates the use of
.BR getopt_long ()
with most of its features.
-.PP
+.P
.\" SRC BEGIN (getopt_long.c)
.EX
#include <getopt.h>
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.BI "[[deprecated]] char *getpass(const char *" prompt );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR getpass ():
.nf
Since glibc 2.2.2:
.I ECHO
flag in
.BR termios (3).
-.PP
+.P
The
.BR getpass ()
function opens
.BR readpassphrase (3bsd),
provided by
.IR libbsd .
-.PP
+.P
In the GNU C library implementation, if
.I /dev/tty
cannot be opened, the prompt is written to
.IR stdin .
There is no limit on the length of the password.
Line editing is not disabled.
-.PP
+.P
According to SUSv2, the value of
.B PASS_MAX
must be defined in
.SH SYNOPSIS
.nf
.B #include <netdb.h>
-.PP
+.P
.B struct protoent *getprotoent(void);
-.PP
+.P
.BI "struct protoent *getprotobyname(const char *" name );
.BI "struct protoent *getprotobynumber(int " proto );
-.PP
+.P
.BI "void setprotoent(int " stayopen );
.B void endprotoent(void);
.fi
structure
containing the broken-out fields from the entry.
A connection is opened to the database if necessary.
-.PP
+.P
The
.BR getprotobyname ()
function returns a
that matches the protocol name
.IR name .
A connection is opened to the database if necessary.
-.PP
+.P
The
.BR getprotobynumber ()
function returns a
that matches the protocol number
.IR number .
A connection is opened to the database if necessary.
-.PP
+.P
The
.BR setprotoent ()
function opens a connection to the database,
will not be closed between calls to one of the
.BR getproto* ()
functions.
-.PP
+.P
The
.BR endprotoent ()
function closes the connection to the database.
-.PP
+.P
The
.I protoent
structure is defined in
.I <netdb.h>
as follows:
-.PP
+.P
.in +4n
.EX
struct protoent {
}
.EE
.in
-.PP
+.P
The members of the
.I protoent
structure are:
locale
T}
.TE
-.PP
+.P
In the above table,
.I protoent
in
.SH SYNOPSIS
.nf
.B #include <netdb.h>
-.PP
+.P
.BI "int getprotoent_r(struct protoent *restrict " result_buf ,
.BI " char " buf "[restrict ." buflen "], size_t " buflen ,
.BI " struct protoent **restrict " result );
.BI " struct protoent *restrict " result_buf ,
.BI " char " buf "[restrict ." buflen "], size_t " buflen ,
.BI " struct protoent **restrict " result );
-.PP
+.P
.fi
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR getprotoent_r (),
.BR getprotobyname_r (),
.BR getprotobynumber_r ():
and in the function calling signature and return value.
This manual page describes just the differences from
the nonreentrant functions.
-.PP
+.P
Instead of returning a pointer to a statically allocated
.I protoent
structure as the function result,
these functions copy the structure into the location pointed to by
.IR result_buf .
-.PP
+.P
The
.I buf
array is used to store the string fields pointed to by the returned
.\" I can find no information on the required/recommended buffer size;
.\" the nonreentrant functions use a 1024 byte buffer.
.\" The 1024 byte value is also what the Solaris man page suggests. -- mtk
-.PP
+.P
If the function call successfully obtains a protocol record, then
.I *result
is set pointing to
.SH RETURN VALUE
On success, these functions return 0.
On error, they return one of the positive error numbers listed in ERRORS.
-.PP
+.P
On error, record not found
.RB ( getprotobyname_r (),
.BR getprotobynumber_r ()),
.BR ERANGE ,
the program retries with larger buffer sizes.
The following shell session shows a couple of sample runs:
-.PP
+.P
.in +4n
.EX
.RB "$" " ./a.out tcp 1"
.nf
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <stdlib.h>
-.PP
+.P
.B "int getpt(void);"
.fi
.SH DESCRIPTION
opens a new pseudoterminal device and returns a file descriptor
that refers to that device.
It is equivalent to opening the pseudoterminal multiplexor device
-.PP
+.P
.in +4n
.EX
open("/dev/ptmx", O_RDWR);
.EE
.in
-.PP
+.P
on Linux systems, though the pseudoterminal multiplexor device is located
elsewhere on some systems that use the GNU C library.
.SH RETURN VALUE
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <sys/types.h>
.B #include <pwd.h>
-.PP
+.P
.BI "[[deprecated]] int getpw(uid_t " uid ", char *" buf );
.fi
.SH DESCRIPTION
function reconstructs the password line entry for
the given user ID \fIuid\fP in the buffer \fIbuf\fP.
The returned buffer contains a line of format
-.PP
+.P
.in +4n
.EX
.B name:passwd:uid:gid:gecos:dir:shell
.EE
.in
-.PP
+.P
The \fIpasswd\fP structure is defined in \fI<pwd.h>\fP as follows:
-.PP
+.P
.in +4n
.EX
struct passwd {
};
.EE
.in
-.PP
+.P
For more information about the fields of this structure, see
.BR passwd (5).
.SH RETURN VALUE
function returns 0 on success; on error, it returns \-1, and
.I errno
is set to indicate the error.
-.PP
+.P
If
.I uid
is not found in the password database,
.nf
.B #include <sys/types.h>
.B #include <pwd.h>
-.PP
+.P
.B struct passwd *getpwent(void);
.B void setpwent(void);
.B void endpwent(void);
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR getpwent (),
.BR setpwent (),
.BR endpwent ():
.BR getpwent ()
is called, it returns the first entry; thereafter, it returns successive
entries.
-.PP
+.P
The
.BR setpwent ()
function rewinds to the beginning
of the password database.
-.PP
+.P
The
.BR endpwent ()
function is used to close the password database
after all processing has been performed.
-.PP
+.P
The \fIpasswd\fP structure is defined in \fI<pwd.h>\fP as follows:
-.PP
+.P
.in +4n
.EX
struct passwd {
};
.EE
.in
-.PP
+.P
For more information about the fields of this structure, see
.BR passwd (5).
.SH RETURN VALUE
If one wants to check
.I errno
after the call, it should be set to zero before the call.
-.PP
+.P
The return value may point to a static area, and may be overwritten
by subsequent calls to
.BR getpwent (),
MT-Unsafe race:pwent locale
T}
.TE
-.PP
+.P
In the above table,
.I pwent
in
.SH SYNOPSIS
.nf
.B #include <pwd.h>
-.PP
+.P
.BI "int getpwent_r(struct passwd *restrict " pwbuf ,
.BI " char " buf "[restrict ." buflen "], size_t " buflen ,
.BI " struct passwd **restrict " pwbufp );
.BI " char " buf "[restrict ." buflen "], size_t " buflen ,
.BI " struct passwd **restrict " pwbufp );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR getpwent_r (),
.nf
Since glibc 2.19:
glibc 2.19 and earlier:
_BSD_SOURCE || _SVID_SOURCE
.fi
-.PP
+.P
.BR fgetpwent_r ():
.nf
Since glibc 2.19:
.BR setpwent (3).
The latter reads the next passwd entry from
.IR stream .
-.PP
+.P
The \fIpasswd\fP structure is defined in
.I <pwd.h>
as follows:
-.PP
+.P
.in +4n
.EX
struct passwd {
};
.EE
.in
-.PP
+.P
For more information about the fields of this structure, see
.BR passwd (5).
-.PP
+.P
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.
.BR fgetpwent_r ()
T} Thread safety MT-Safe
.TE
-.PP
+.P
In the above table,
.I pwent
in
then data races could occur.
.SH VERSIONS
Other systems use the prototype
-.PP
+.P
.in +4n
.EX
struct passwd *
getpwent_r(struct passwd *pwd, char *buf, int buflen);
.EE
.in
-.PP
+.P
or, better,
-.PP
+.P
.in +4n
.EX
int
.nf
.B #include <sys/types.h>
.B #include <pwd.h>
-.PP
+.P
.BI "struct passwd *getpwnam(const char *" name );
.BI "struct passwd *getpwuid(uid_t " uid );
-.PP
+.P
.BI "int getpwnam_r(const char *restrict " name ", \
struct passwd *restrict " pwd ,
.BI " char " buf "[restrict ." buflen "], size_t " buflen ,
.BI " char " buf "[restrict ." buflen "], size_t " buflen ,
.BI " struct passwd **restrict " result );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR getpwnam_r (),
.BR getpwuid_r ():
.nf
NIS, and LDAP)
that matches the username
.IR name .
-.PP
+.P
The
.BR 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
.IR uid .
-.PP
+.P
The \fIpasswd\fP structure is defined in \fI<pwd.h>\fP as follows:
-.PP
+.P
.in +4n
.EX
struct passwd {
};
.EE
.in
-.PP
+.P
See
.BR passwd (5)
for more information about these fields.
-.PP
+.P
The
.BR getpwnam_r ()
and
A pointer to the result (in case of success) or NULL (in case no entry
was found or an error occurred) is stored in
.IR *result .
-.PP
+.P
The call
-.PP
+.P
.in +4n
.EX
sysconf(_SC_GETPW_R_SIZE_MAX)
.EE
.in
-.PP
+.P
returns either \-1, without changing
.IR errno ,
or an initial suggested size for
If one wants to check
.I errno
after the call, it should be set to zero before the call.
-.PP
+.P
The return value may point to a static area, and may be overwritten
by subsequent calls to
.BR getpwent (3),
.BR getpwuid ().
(Do not pass the returned pointer to
.BR free (3).)
-.PP
+.P
On success,
.BR getpwnam_r ()
and
.\" FreeBSD 4.8, OpenBSD 3.2, NetBSD 1.6 - give EPERM
.\" SunOS 5.8 - gives EBADF
.\" Tru64 5.1b, HP-UX-11i, SunOS 5.7 - give 0
-.PP
+.P
The
.I pw_dir
field contains the name of the initial working directory of the user.
.BR getpwnam_r ()
to find the full username and user ID for the username
supplied as a command-line argument.
-.PP
+.P
.\" SRC BEGIN (getpwnam.c)
.EX
#include <errno.h>
.SH SYNOPSIS
.nf
.B #include <netdb.h>
-.PP
+.P
.B struct rpcent *getrpcent(void);
-.PP
+.P
.BI "struct rpcent *getrpcbyname(const char *" name );
.BI "struct rpcent *getrpcbynumber(int " number );
-.PP
+.P
.BI "void setrpcent(int " stayopen );
.B void endrpcent(void);
.fi
functions 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.
-.PP
+.P
.in +4n
.EX
struct rpcent {
};
.EE
.in
-.PP
+.P
The members of this structure are:
.TP
.I r_name
.TP
.I r_number
The RPC program number for this service.
-.PP
+.P
The
.BR getrpcent ()
function reads the next entry from the database.
A connection is opened to the database if necessary.
-.PP
+.P
The
.BR setrpcent ()
function opens a connection to the database,
will not be closed between calls to one of the
.BR getrpc* ()
functions.
-.PP
+.P
The
.BR endrpcent ()
function closes the connection to the database.
-.PP
+.P
The
.BR getrpcbyname ()
and
.SH SYNOPSIS
.nf
.B #include <netdb.h>
-.PP
+.P
.BI "int getrpcent_r(struct rpcent *" result_buf ", char " buf [. buflen ],
.BI " size_t " buflen ", struct rpcent **" result );
.BI "int getrpcbyname_r(const char *" name ,
.BI "int getrpcbynumber_r(int " number ,
.BI " struct rpcent *" result_buf ", char " buf [. buflen ],
.BI " size_t " buflen ", struct rpcent **" result );
-.PP
+.P
.fi
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR getrpcent_r (),
.BR getrpcbyname_r (),
.BR getrpcbynumber_r ():
and in the function calling signature and return value.
This manual page describes just the differences from
the nonreentrant functions.
-.PP
+.P
Instead of returning a pointer to a statically allocated
.I rpcent
structure as the function result,
these functions copy the structure into the location pointed to by
.IR result_buf .
-.PP
+.P
The
.I buf
array is used to store the string fields pointed to by the returned
(A buffer of length 1024 bytes should be sufficient for most applications.)
.\" I can find no information on the required/recommended buffer size;
.\" the nonreentrant functions use a 1024 byte buffer -- mtk.
-.PP
+.P
If the function call successfully obtains an RPC record, then
.I *result
is set pointing to
.SH RETURN VALUE
On success, these functions return 0.
On error, they return one of the positive error numbers listed in ERRORS.
-.PP
+.P
On error, record not found
.RB ( getrpcbyname_r (),
.BR getrpcbynumber_r ()),
.SH SYNOPSIS
.nf
.B "#include <rpc/rpc.h>"
-.PP
+.P
.BI "int getrpcport(const char *" host ", unsigned long " prognum ,
.BI " unsigned long " versnum ", unsigned int " proto );
.fi
.SH SYNOPSIS
.nf
.B #include <stdio.h>
-.PP
+.P
.BI "[[deprecated]] char *gets(char *" "s" );
.fi
.SH DESCRIPTION
.IR "Never use this function" .
-.PP
+.P
.BR gets ()
reads a line from
.I stdin
POSIX.1-2008.
.SH HISTORY
C89, POSIX.1-2001.
-.PP
+.P
LSB deprecates
.BR gets ().
POSIX.1-2008 marks
Use
.BR fgets ()
instead.
-.PP
+.P
For more information, see CWE-242 (aka "Use of Inherently Dangerous
Function") at
http://cwe.mitre.org/data/definitions/242.html
.SH SYNOPSIS
.nf
.B #include <netdb.h>
-.PP
+.P
.B struct servent *getservent(void);
-.PP
+.P
.BI "struct servent *getservbyname(const char *" name ", const char *" proto );
.BI "struct servent *getservbyport(int " port ", const char *" proto );
-.PP
+.P
.BI "void setservent(int " stayopen );
.B void endservent(void);
.fi
structure containing
the broken-out fields from the entry.
A connection is opened to the database if necessary.
-.PP
+.P
The
.BR getservbyname ()
function returns a
.I proto
is NULL, any protocol will be matched.
A connection is opened to the database if necessary.
-.PP
+.P
The
.BR getservbyport ()
function returns a
.I proto
is NULL, any protocol will be matched.
A connection is opened to the database if necessary.
-.PP
+.P
The
.BR setservent ()
function opens a connection to the database,
will not be closed between calls to one of the
.BR getserv* ()
functions.
-.PP
+.P
The
.BR endservent ()
function closes the connection to the database.
-.PP
+.P
The
.I servent
structure is defined in
.I <netdb.h>
as follows:
-.PP
+.P
.in +4n
.EX
struct servent {
}
.EE
.in
-.PP
+.P
The members of the
.I servent
structure are:
locale
T}
.TE
-.PP
+.P
In the above table,
.I servent
in
.SH SYNOPSIS
.nf
.B #include <netdb.h>
-.PP
+.P
.BI "int getservent_r(struct servent *restrict " result_buf ,
.BI " char " buf "[restrict ." buflen "], size_t " buflen ,
.BI " struct servent **restrict " result );
.BI " struct servent *restrict " result_buf ,
.BI " char " buf "[restrict ." buflen "], size_t " buflen ,
.BI " struct servent **restrict " result );
-.PP
+.P
.fi
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR getservent_r (),
.BR getservbyname_r (),
.BR getservbyport_r ():
and in the function calling signature and return value.
This manual page describes just the differences from
the nonreentrant functions.
-.PP
+.P
Instead of returning a pointer to a statically allocated
.I servent
structure as the function result,
these functions copy the structure into the location pointed to by
.IR result_buf .
-.PP
+.P
The
.I buf
array is used to store the string fields pointed to by the returned
(A buffer of length 1024 bytes should be sufficient for most applications.)
.\" I can find no information on the required/recommended buffer size;
.\" the nonreentrant functions use a 1024 byte buffer -- mtk.
-.PP
+.P
If the function call successfully obtains a service record, then
.I *result
is set pointing to
.SH RETURN VALUE
On success, these functions return 0.
On error, they return one of the positive error numbers listed in errors.
-.PP
+.P
On error, record not found
.RB ( getservbyname_r (),
.BR getservbyport_r ()),
.BR ERANGE ,
the program retries with larger buffer sizes.
The following shell session shows a couple of sample runs:
-.PP
+.P
.in +4n
.EX
.RB "$" " ./a.out 7 tcp 1"
.nf
/* General shadow password file API */
.B #include <shadow.h>
-.PP
+.P
.BI "struct spwd *getspnam(const char *" name );
.B struct spwd *getspent(void);
-.PP
+.P
.B void setspent(void);
.B void endspent(void);
-.PP
+.P
.BI "struct spwd *fgetspent(FILE *" stream );
.BI "struct spwd *sgetspent(const char *" s );
-.PP
+.P
.BI "int putspent(const struct spwd *" p ", FILE *" stream );
-.PP
+.P
.B int lckpwdf(void);
.B int ulckpwdf(void);
-.PP
+.P
/* GNU extension */
.B #include <shadow.h>
-.PP
+.P
.BI "int getspent_r(struct spwd *" spbuf ,
.BI " char " buf [. buflen "], size_t " buflen ", \
struct spwd **" spbufp );
.BI "int getspnam_r(const char *" name ", struct spwd *" spbuf ,
.BI " char " buf [. buflen "], size_t " buflen ", \
struct spwd **" spbufp );
-.PP
+.P
.BI "int fgetspent_r(FILE *" stream ", struct spwd *" spbuf ,
.BI " char " buf [. buflen "], size_t " buflen ", \
struct spwd **" spbufp );
.BI " char " buf [. buflen "], size_t " buflen ", \
struct spwd **" spbufp );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR getspent_r (),
.BR getspnam_r (),
.BR fgetspent_r (),
.IR /etc/shadow ,
NIS, and LDAP),
readable only by root.
-.PP
+.P
The functions described below resemble those for
the traditional password database
(e.g., see
.\" (pluggable authentication modules), and the file
.\" .I /etc/nsswitch.conf
.\" now describes the sources to be used.
-.PP
+.P
The
.BR 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
.IR name .
-.PP
+.P
The
.BR getspent ()
function returns a pointer to the next entry in the shadow password
so that resources can be deallocated.
.\" some systems require a call of setspent() before the first getspent()
.\" glibc does not
-.PP
+.P
The
.BR fgetspent ()
function is similar to
.BR getspent ()
but uses the supplied stream instead of the one implicitly opened by
.BR setspent ().
-.PP
+.P
The
.BR sgetspent ()
function parses the supplied string
.I s
into a struct
.IR spwd .
-.PP
+.P
The
.BR putspent ()
function writes the contents of the supplied struct
.IR stream .
String entries with value NULL and numerical entries with value \-1
are written as an empty string.
-.PP
+.P
The
.BR lckpwdf ()
function is intended to protect against multiple simultaneous accesses
Only programs that use
.BR lckpwdf ()
will notice the lock.
-.PP
+.P
These were the functions that formed the original shadow API.
They are widely available.
.\" Also in libc5
A pointer to the result (in case of success) or NULL (in case no entry
was found or an error occurred) is stored in
.IR *spbufp .
-.PP
+.P
The functions
.BR getspent_r (),
.BR fgetspent_r (),
and
.BR sgetspent_r ()
are similarly analogous to their nonreentrant counterparts.
-.PP
+.P
Some non-glibc systems also have functions with these names,
often with different prototypes.
.\" SUN doesn't have sgetspent_r()
.SS Structure
The shadow password structure is defined in \fI<shadow.h>\fP as follows:
-.PP
+.P
.in +4n
.EX
struct spwd {
success and \-1 for failure, with
.I errno
set to indicate the error.
-.PP
+.P
For the nonreentrant functions, the return value may point to static area,
and may be overwritten by subsequent calls to these functions.
-.PP
+.P
The reentrant functions return zero on success.
In case of error, an error number is returned.
.SH ERRORS
.TP
.I /etc/.pwd.lock
lock file
-.PP
+.P
The include file
.I <paths.h>
defines the constant
MT-Safe
T}
.TE
-.PP
+.P
In the above table,
.I getspent
in
.SH SYNOPSIS
.nf
.B #include <stdlib.h>
-.PP
+.P
.BI "int getsubopt(char **restrict " optionp ", char *const *restrict " tokens ,
.BI " char **restrict " valuep );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR getsubopt ():
.nf
_XOPEN_SOURCE >= 500
The following is an example of the kind of string
that might be passed in
.IR optionp :
-.PP
+.P
.in +4n
.EX
.B ro,name=xyz
.EE
.in
-.PP
+.P
The
.I tokens
argument is a pointer to a NULL-terminated array of pointers to the tokens that
.IR optionp .
The tokens should be distinct, null-terminated strings containing at
least one character, with no embedded equal signs or commas.
-.PP
+.P
Each call to
.BR getsubopt ()
returns information about the next unprocessed suboption in
is overwritten with a null byte, so
.I *valuep
is precisely the "value string" for that suboption.
-.PP
+.P
If the suboption is recognized, but no value string was found,
.I *valuep
is set to NULL.
-.PP
+.P
When
.BR getsubopt ()
returns,
is the entire
.IB name [= value ]
string.
-.PP
+.P
Since
.I *optionp
is changed, the first suboption before the call to
that string must be writable; it cannot be a string constant.
.SH EXAMPLES
The following program expects suboptions following a "\-o" option.
-.PP
+.P
.\" SRC BEGIN (getsubopt.c)
.EX
#define _XOPEN_SOURCE 500
.SH SYNOPSIS
.nf
.B "#include <ttyent.h>"
-.PP
+.P
.B "struct ttyent *getttyent(void);"
.BI "struct ttyent *getttynam(const char *" name );
-.PP
+.P
.B "int setttyent(void);"
.B "int endttyent(void);"
.fi
.B _PATH_TTYS
(e.g.,
.IR /etc/ttys ).
-.PP
+.P
The function
.BR setttyent ()
opens the file or rewinds it if already open.
-.PP
+.P
The function
.BR endttyent ()
closes the file.
-.PP
+.P
The function
.BR getttynam ()
searches for a given terminal name in the file.
It returns a pointer to a
.I ttyent
structure (description below).
-.PP
+.P
The function
.BR getttyent ()
opens the file
The
.I ttyent
structure has the form:
-.PP
+.P
.in +4n
.EX
struct ttyent {
};
.EE
.in
-.PP
+.P
.I ty_status
can be:
-.PP
+.P
.in +4n
.EX
#define TTY_ON 0x01 /* enable logins (start ty_getty program) */
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.B char *getusershell(void);
.B void setusershell(void);
.B void endusershell(void);
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR getusershell (),
.BR setusershell (),
.BR endusershell ():
and
.I /bin/csh
were listed in the file.
-.PP
+.P
The
.BR setusershell ()
function rewinds
.IR /etc/shells .
-.PP
+.P
The
.BR endusershell ()
function closes
.SH SYNOPSIS
.nf
.B #include <utmp.h>
-.PP
+.P
.B struct utmp *getutent(void);
.BI "struct utmp *getutid(const struct utmp *" ut );
.BI "struct utmp *getutline(const struct utmp *" ut );
-.PP
+.P
.BI "struct utmp *pututline(const struct utmp *" ut );
-.PP
+.P
.B void setutent(void);
.B void endutent(void);
-.PP
+.P
.BI "int utmpname(const char *" file );
.fi
.SH DESCRIPTION
New applications should use the POSIX.1-specified "utmpx" versions of
these functions; see STANDARDS.
-.PP
+.P
.BR utmpname ()
sets the name of the utmp-format file for the other utmp
functions to access.
is not used to set the filename
before the other functions are used, they assume \fB_PATH_UTMP\fP, as
defined in \fI<paths.h>\fP.
-.PP
+.P
.BR 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.
-.PP
+.P
.BR endutent ()
closes the utmp file.
It should be called when the user
code is done accessing the file with the other functions.
-.PP
+.P
.BR 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
.BR utmp (5).
-.PP
+.P
.BR getutid ()
searches forward from the current file position in the utmp
file based upon \fIut\fP.
first entry whose
.I ut_id
field matches \fIut\->ut_id\fP.
-.PP
+.P
.BR getutline ()
searches forward from the current file position in the utmp file.
It scans entries whose
.I ut_line
field
matches \fIut\->ut_line\fP.
-.PP
+.P
.BR pututline ()
writes the
.I utmp
and NULL on failure (which includes the "record not found" case).
This \fIstruct utmp\fP is allocated in static storage, and may be
overwritten by subsequent calls.
-.PP
+.P
On success
.BR pututline ()
returns
.IR ut ;
on failure, it returns NULL.
-.PP
+.P
.BR utmpname ()
returns 0 if the new name was successfully stored, or \-1 on failure.
-.PP
+.P
On failure, these functions
.I errno
set to indicate the error.
.TP
.B ESRCH
Record not found.
-.PP
+.P
.BR setutent (),
.BR pututline (),
and the
.BR utmpname ()
T} Thread safety MT-Unsafe race:utent
.TE
-.PP
+.P
In the above table,
.I utent
in
None.
.SH HISTORY
XPG2, SVr4.
-.PP
+.P
In XPG2 and SVID 2 the function
.BR pututline ()
is documented to return void, and that is what it does on many systems
.BR _pututline ()
with the prototype given above for
.BR pututline ().
-.PP
+.P
All these functions are obsolete now on non-Linux systems.
POSIX.1-2001 and POSIX.1-2008, following SUSv1,
does not have any of these functions, but instead uses
-.PP
+.P
.RS 4
.EX
.B #include <utmpx.h>
-.PP
+.P
.B struct utmpx *getutxent(void);
.B struct utmpx *getutxid(const struct utmpx *);
.B struct utmpx *getutxline(const struct utmpx *);
.B void endutxent(void);
.EE
.RE
-.PP
+.P
These functions are provided by glibc,
and perform the same task as their equivalents without the "x", but use
.IR "struct utmpx" ,
For completeness, glibc also provides
.BR utmpxname (),
although this function is not specified by POSIX.1.
-.PP
+.P
On some other systems,
the \fIutmpx\fP structure is a superset of the \fIutmp\fP structure,
with additional fields, and larger versions of the existing fields,
.I /var/*/utmpx
and
.IR /var/*/wtmpx .
-.PP
+.P
Linux glibc on the other hand does not use a parallel \fIutmpx\fP file
since its \fIutmp\fP structure is already large enough.
The "x" functions listed above are just aliases for
.SS glibc notes
The above functions are not thread-safe.
glibc adds reentrant versions
-.PP
+.P
.nf
.B #include <utmp.h>
-.PP
+.P
.BI "int getutent_r(struct utmp *" ubuf ", struct utmp **" ubufp );
.BI "int getutid_r(struct utmp *" ut ,
.BI " struct utmp *" ubuf ", struct utmp **" ubufp );
.BI "int getutline_r(struct utmp *" ut ,
.BI " struct utmp *" ubuf ", struct utmp **" ubufp );
.fi
-.PP
+.P
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
-.PP
+.P
.BR getutent_r (),
.BR getutid_r (),
.BR getutline_r ():
|| /* Since glibc 2.19: */ _DEFAULT_SOURCE
|| /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE
.fi
-.PP
+.P
These functions are GNU extensions, analogs of the functions of the
same name without the _r suffix.
The
.BR getpwuid (3)
and
.BR ttyname (3).
-.PP
+.P
.\" SRC BEGIN (getutent.c)
.EX
#include <pwd.h>
.nf
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <utmpx.h>
-.PP
+.P
.BI "void getutmp(const struct utmpx *" ux ", struct utmp *" u );
.BI "void getutmpx(const struct utmp *" u ", struct utmpx *" ux );
.fi
.SH SYNOPSIS
.nf
.B #include <stdio.h>
-.PP
+.P
.BI "int getw(FILE *" stream );
.BI "int putw(int " w ", FILE *" stream );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR getw (),
.BR putw ():
.nf
We recommend you use
.BR fread (3)
instead.
-.PP
+.P
.BR putw ()
writes the word \fIw\fP (that is,
an \fIint\fP) to \fIstream\fP.
.SH SYNOPSIS
.nf
.B #include <wchar.h>
-.PP
+.P
.B "wint_t getwchar(void);"
.fi
.SH DESCRIPTION
.B EILSEQ
and returns
.BR WEOF .
-.PP
+.P
For a nonlocking counterpart, see
.BR unlocked_stdio (3).
.SH RETURN VALUE
.B LC_CTYPE
category of the
current locale.
-.PP
+.P
It is reasonable to expect that
.BR getwchar ()
will actually
.SH SYNOPSIS
.nf
.B #include <glob.h>
-.PP
+.P
.BI "int glob(const char *restrict " pattern ", int " flags ,
.BI " int (*" errfunc ")(const char *" epath ", int " eerrno ),
.BI " glob_t *restrict " pglob );
No tilde expansion or parameter substitution is done; if you want
these, use
.BR wordexp (3).
-.PP
+.P
The
.BR globfree ()
function frees the dynamically allocated storage from an earlier call
to
.BR glob ().
-.PP
+.P
The results of a
.BR glob ()
call are stored in the structure pointed to by
.IR <glob.h> )
and includes the following elements defined by POSIX.2 (more may be
present as an extension):
-.PP
+.P
.in +4n
.EX
typedef struct {
} glob_t;
.EE
.in
-.PP
+.P
Results are stored in dynamically allocated storage.
-.PP
+.P
The argument
.I flags
is made up of the bitwise OR of zero or more the following symbolic
Normally, a backslash can be used to quote the following character,
providing a mechanism to turn off the special meaning
metacharacters.
-.PP
+.P
.I flags
may also include any of the following, which are GNU
extensions and not defined by POSIX.2:
are directories.
(The purpose of this flag is merely to optimize performance when
the caller is interested only in directories.)
-.PP
+.P
If
.I errfunc
is not NULL,
.BR glob ()
will terminate after the call to
.IR errfunc .
-.PP
+.P
Upon successful return,
.I pglob\->gl_pathc
contains the number of matched pathnames and
.I pglob\->gl_pathv
contains a pointer to the list of pointers to matched pathnames.
The list of pointers is terminated by a null pointer.
-.PP
+.P
It is possible to call
.BR glob ()
several times.
flag has to be set in
.I flags
on the second and later invocations.
-.PP
+.P
As a GNU extension,
.I pglob\->gl_flags
is set to the flags specified,
.BR globfree ()
T} Thread safety MT-Safe
.TE
-.PP
+.P
In the above table,
.I utent
in
.IR errno .
.SH EXAMPLES
One example of use is the following code, which simulates typing
-.PP
+.P
.in +4n
.EX
ls \-l *.c ../*.c
.EE
.in
-.PP
+.P
in the shell:
-.PP
+.P
.in +4n
.EX
glob_t globbuf;
.SH SYNOPSIS
.nf
.B #include <gnu/libc\-version.h>
-.PP
+.P
.B const char *gnu_get_libc_version(void);
.B const char *gnu_get_libc_release(void);
.fi
The function
.BR gnu_get_libc_version ()
returns a string that identifies the glibc version available on the system.
-.PP
+.P
The function
.BR gnu_get_libc_release ()
returns a string indicates the release status of the glibc version
glibc 2.1.
.SH EXAMPLES
When run, the program below will produce output such as the following:
-.PP
+.P
.in +4n
.EX
.RB "$" " ./a.out"
.SH SYNOPSIS
.nf
.B #include <stdlib.h>
-.PP
+.P
.BI "int grantpt(int " fd ");"
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR grantpt ():
.nf
Since glibc 2.24:
The group ID is set to an unspecified value (e.g.,
.IR tty ).
The mode of the slave is set to 0620 (crw\-\-w\-\-\-\-).
-.PP
+.P
The behavior of
.BR grantpt ()
is unspecified if a signal handler is installed to catch
.SH HISTORY
glibc 2.1.
POSIX.1-2001.
-.PP
+.P
This is part of the UNIX 98 pseudoterminal support, see
.BR pts (4).
-.PP
+.P
Historical systems implemented this function via a set-user-ID helper binary
called "pt_chown".
glibc on Linux before glibc 2.33 could do so as well,
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.BI "int group_member(gid_t " gid );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR group_member ():
.nf
_GNU_SOURCE
.SH SYNOPSIS
.nf
.B #include <signal.h>
-.PP
+.P
.B typedef void (*sighandler_t)(int);
-.PP
+.P
.BI "[[deprecated]] int gsignal(int " signum );
-.PP
+.P
.BI "[[deprecated]] sighandler_t ssignal(int " signum ", sighandler_t " action );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR gsignal (),
.BR ssignal ():
.nf
and
.BR signal (2),
respectively.
-.PP
+.P
Elsewhere, on System V-like systems, these functions implement
software signaling, entirely independent of the classical
.BR signal (2)
Probably, you are looking for the APIs provided by the
.I libdb
library instead.
-.PP
+.P
The routine
.BR dbopen (3)
is the library interface to database files.
The general description of the database access methods is in
.BR dbopen (3),
this manual page describes only the hash-specific information.
-.PP
+.P
The hash data structure is an extensible, dynamic hashing scheme.
-.PP
+.P
The access-method-specific data structure provided to
.BR dbopen (3)
is defined in the
.I <db.h>
include file as follows:
-.PP
+.P
.in +4n
.EX
typedef struct {
} HASHINFO;
.EE
.in
-.PP
+.P
The elements of this structure are as follows:
.TP 10
.I bsize
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.
-.PP
+.P
If the file already exists (and the
.B O_TRUNC
flag is not specified), the
.I nelem
are
ignored and the values specified when the tree was created are used.
-.PP
+.P
If a hash function is specified,
.I hash_open
attempts to determine if the hash function specified is the same as
the one with which the database was created, and fails if it is not.
-.PP
+.P
Backward-compatible interfaces to the routines described in
.BR dbm (3),
and
.BR dbopen (3),
.BR mpool (3),
.BR recno (3)
-.PP
+.P
.IR "Dynamic Hash Tables" ,
Per-Ake Larson, Communications of the ACM, April 1988.
-.PP
+.P
.IR "A New Hash Package for UNIX" ,
Margo Seltzer, USENIX Proceedings, Winter 1991.
.SH SYNOPSIS
.nf
.B #include <search.h>
-.PP
+.P
.BI "int hcreate(size_t " nel );
.B "void hdestroy(void);"
-.PP
+.P
.BI "ENTRY *hsearch(ENTRY " item ", ACTION " action );
-.PP
+.P
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <search.h>
-.PP
+.P
.BI "int hcreate_r(size_t " nel ", struct hsearch_data *" htab );
.BI "void hdestroy_r(struct hsearch_data *" htab );
-.PP
+.P
.BI "int hsearch_r(ENTRY " item ", ACTION " action ", ENTRY **" retval ,
.BI " struct hsearch_data *" htab );
.fi
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.
-.PP
+.P
The three functions
.BR hcreate_r (),
.BR hsearch_r (),
The programmer should treat this structure as opaque
(i.e., do not attempt to directly access or modify
the fields in this structure).
-.PP
+.P
First a hash table must be created using
.BR hcreate ().
The argument \fInel\fP specifies the maximum number of entries
The implementation may adjust this value upward to improve the
performance of the resulting hash table.
.\" e.g., in glibc it is raised to the next higher prime number
-.PP
+.P
The
.BR hcreate_r ()
function performs the same task as
.I htab
must be zeroed before the first call to
.BR hcreate_r ().
-.PP
+.P
The function
.BR hdestroy ()
frees the memory occupied by the hash table that was created by
.IR *htab ,
which was previously created using
.BR hcreate_r ().
-.PP
+.P
The
.BR hsearch ()
function searches the hash table for an
item with the same key as \fIitem\fP (where "the same" is determined using
.BR strcmp (3)),
and if successful returns a pointer to it.
-.PP
+.P
The argument \fIitem\fP is of type \fIENTRY\fP, which is defined in
\fI<search.h>\fP as follows:
-.PP
+.P
.in +4n
.EX
typedef struct entry {
} ENTRY;
.EE
.in
-.PP
+.P
The field \fIkey\fP points to a null-terminated string which is the
search key.
The field \fIdata\fP points to data that is associated with that key.
-.PP
+.P
The argument \fIaction\fP determines what
.BR hsearch ()
does after an unsuccessful search.
then
.I data
is ignored.)
-.PP
+.P
The
.BR hsearch_r ()
function is like
They return 0 on error, with
.I errno
set to indicate the error.
-.PP
+.P
On success,
.BR hsearch ()
returns a pointer to an entry in the hash table.
.B EINVAL
.I htab
is NULL.
-.PP
+.P
.BR hsearch ()
and
.BR hsearch_r ()
and
.I key
was not found in the table.
-.PP
+.P
POSIX.1 specifies only the
.\" PROX.1-2001, POSIX.1-2008
.B ENOMEM
.I nel
should be at least 25% larger than the maximum number of elements
that the caller expects to store in the table.
-.PP
+.P
The
.BR hdestroy ()
and
In libc and glibc (before glibc 2.3), the
implementation violates the specification,
updating the \fIdata\fP for the given \fIkey\fP in this case.
-.PP
+.P
Individual hash table entries can be added, but not deleted.
.SH EXAMPLES
The following program inserts 24 items into a hash table, then prints
some of them.
-.PP
+.P
.\" SRC BEGIN (hsearch.c)
.EX
#include <search.h>
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "double hypot(double " x ", double " y );
.BI "float hypotf(float " x ", float " y );
.BI "long double hypotl(long double " x ", long double " y );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR hypot ():
.nf
_ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
|| /* Since glibc 2.19: */ _DEFAULT_SOURCE
|| /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
.fi
-.PP
+.P
.BR hypotf (),
.BR hypotl ():
.nf
or the distance of the point
.RI ( x , y )
from the origin.
-.PP
+.P
The calculation is performed without undue overflow or underflow
during the intermediate steps of the calculation.
.\" e.g., hypot(DBL_MIN, DBL_MIN) does the right thing, as does, say
.I x
and
.IR y .
-.PP
+.P
If
.I x
or
.I y
is an infinity,
positive infinity is returned.
-.PP
+.P
If
.I x
or
is a NaN,
and the other argument is not an infinity,
a NaN is returned.
-.PP
+.P
If the result overflows,
a range error occurs,
and the functions return
or
.BR HUGE_VALL ,
respectively.
-.PP
+.P
If both arguments are subnormal, and the result is subnormal,
.\" Actually, could the result not be subnormal if both arguments
.\" are subnormal? I think not -- mtk, Jul 2008
.BR math_error (7)
for information on how to determine whether an error has occurred
when calling these functions.
-.PP
+.P
The following errors can occur:
.TP
Range error: result overflow
C11, POSIX.1-2008.
.SH HISTORY
C99, POSIX.1-2001.
-.PP
+.P
The variant returning
.I double
also conforms to
.SH SYNOPSIS
.nf
.B #include <iconv.h>
-.PP
+.P
.BI "size_t iconv(iconv_t " cd ,
.BI " char **restrict " inbuf ", size_t *restrict " inbytesleft ,
.BI " char **restrict " outbuf ", size_t *restrict " outbytesleft );
the first byte available in the output buffer;
.I outbytesleft
indicates the number of bytes available in the output buffer.
-.PP
+.P
The main case is when \fIinbuf\fP is not NULL and \fI*inbuf\fP is not NULL.
In this case, the
.BR iconv ()
starting at \fI*inbuf\fP to a multibyte sequence starting at \fI*outbuf\fP.
At most \fI*inbytesleft\fP bytes, starting at \fI*inbuf\fP, will be read.
At most \fI*outbytesleft\fP bytes, starting at \fI*outbuf\fP, will be written.
-.PP
+.P
The
.BR iconv ()
function converts one multibyte character at a time, and for
The output buffer has no more room for the next converted character.
In this case, it sets \fIerrno\fP to \fBE2BIG\fP and returns
.IR (size_t)\ \-1 .
-.PP
+.P
A different case is when \fIinbuf\fP is NULL or \fI*inbuf\fP is NULL, but
\fIoutbuf\fP is not NULL and \fI*outbuf\fP is not NULL.
In this case, the
Otherwise, it increments
\fI*outbuf\fP and decrements \fI*outbytesleft\fP by the number of bytes
written.
-.PP
+.P
A third case is when \fIinbuf\fP is NULL or \fI*inbuf\fP is NULL, and
\fIoutbuf\fP is NULL or \fI*outbuf\fP is NULL.
In this case, the
.BR iconv ()
T} Thread safety MT-Safe race:cd
.TE
-.PP
+.P
The
.BR iconv ()
function is MT-Safe, as long as callers arrange for
.BR iconv (),
the last should be one with \fIinbuf\fP or \fI*inbuf\fP equal to NULL,
in order to flush out any partially converted input.
-.PP
+.P
Although
.I inbuf
and
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.
-.PP
+.P
The caller of
.BR iconv ()
must ensure that the pointers passed to the function are suitable
.SH SYNOPSIS
.nf
.B #include <iconv.h>
-.PP
+.P
.BI "int iconv_close(iconv_t " cd );
.fi
.SH DESCRIPTION
.SH SYNOPSIS
.nf
.B #include <iconv.h>
-.PP
+.P
.BI "iconv_t iconv_open(const char *" tocode ", const char *" fromcode );
.fi
.SH DESCRIPTION
to
character encoding
.IR tocode .
-.PP
+.P
The values permitted for
.I fromcode
and
.IR tocode ,
characters that
cannot be represented in the target character set will be silently discarded.
-.PP
+.P
The resulting conversion descriptor can be used with
.BR iconv (3)
any number of times.
It remains valid until deallocated using
.BR iconv_close (3).
-.PP
+.P
A conversion descriptor contains a conversion state.
After creation using
.BR iconv_open (),
.SH SYNOPSIS
.nf
.B #include <net/if.h>
-.PP
+.P
.BI "struct if_nameindex *if_nameindex(" void );
.BI "void if_freenameindex(struct if_nameindex *" "ptr" );
.fi
The
.I if_nameindex
structure contains at least the following entries:
-.PP
+.P
.in +4n
.EX
unsigned int if_index; /* Index of interface (1, 2, ...) */
char *if_name; /* Null\-terminated name ("eth0", etc.) */
.EE
.in
-.PP
+.P
The
.I if_index
field contains the interface index.
set to zero and
.I if_name
set to NULL.
-.PP
+.P
The data structure returned by
.BR if_nameindex ()
is dynamically allocated and should be freed using
.TP
.B ENOBUFS
Insufficient resources available.
-.PP
+.P
.BR if_nameindex ()
may also fail for any of the errors specified for
.BR socket (2),
glibc 2.1.
POSIX.1-2001.
BSDi.
-.PP
+.P
Before glibc 2.3.4,
the implementation supported only interfaces with IPv4 addresses.
Support of interfaces that don't have IPv4 addresses is available only
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:
-.PP
+.P
.in +4n
.EX
$ \fB./a.out\fI
.SH SYNOPSIS
.nf
.B #include <net/if.h>
-.PP
+.P
.BI "unsigned int if_nametoindex(const char *" "ifname" );
.BI "char *if_indextoname(unsigned int ifindex, char *" ifname );
.fi
function returns the index of the network interface
corresponding to the name
.IR ifname .
-.PP
+.P
The
.BR if_indextoname ()
function returns the name of the network interface
on error, 0 is returned and
.I errno
is set to indicate the error.
-.PP
+.P
On success,
.BR if_indextoname ()
returns
.TP
.B ENODEV
No interface found with given name.
-.PP
+.P
.BR if_indextoname ()
may fail and set
.I errno
.TP
.B ENXIO
No interface found for the index.
-.PP
+.P
.BR if_nametoindex ()
and
.BR if_indextoname ()
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "int ilogb(double " x );
.BI "int ilogbf(float " x );
.BI "int ilogbl(long double " x );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR ilogb ():
.nf
_ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
|| /* Since glibc 2.19: */ _DEFAULT_SOURCE
|| /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
.fi
-.PP
+.P
.BR ilogbf (),
.BR ilogbl ():
.nf
On success, these functions return the exponent of
.IR x ,
as a signed integer.
-.PP
+.P
If
.I x
is zero, then a domain error occurs, and the functions return
.\" case, but for ilogb() it says domain error.
.BR FP_ILOGB0 .
.\" glibc: The numeric value is either `INT_MIN' or `-INT_MAX'.
-.PP
+.P
If
.I x
is a NaN, then a domain error occurs, and the functions return
.BR FP_ILOGBNAN .
.\" glibc: The numeric value is either `INT_MIN' or `INT_MAX'.
.\" On i386, FP_ILOGB0 and FP_ILOGBNAN have the same value.
-.PP
+.P
If
.I x
is negative infinity or positive infinity, then
.BR math_error (7)
for information on how to determine whether an error has occurred
when calling these functions.
-.PP
+.P
The following errors can occur:
.TP
Domain error: \fIx\fP is 0 or a NaN
.SH SYNOPSIS
.nf
.B #include <strings.h>
-.PP
+.P
.BI "[[deprecated]] char *index(const char *" s ", int " c );
.BI "[[deprecated]] char *rindex(const char *" s ", int " c );
.fi
.BR index ()
is identical to
.BR strchr (3).
-.PP
+.P
.BR rindex ()
is identical to
.BR strrchr (3).
-.PP
+.P
Use
.BR strchr (3)
and
.B #include <sys/socket.h>
.B #include <netinet/in.h>
.B #include <arpa/inet.h>
-.PP
+.P
.BI "int inet_aton(const char *" cp ", struct in_addr *" inp );
-.PP
+.P
.BI "in_addr_t inet_addr(const char *" cp );
.BI "in_addr_t inet_network(const char *" cp );
-.PP
+.P
.BI "[[deprecated]] char *inet_ntoa(struct in_addr " in );
-.PP
+.P
.BI "[[deprecated]] struct in_addr inet_makeaddr(in_addr_t " net ,
.BI " in_addr_t " host );
-.PP
+.P
.BI "[[deprecated]] in_addr_t inet_lnaof(struct in_addr " in );
.BI "[[deprecated]] in_addr_t inet_netof(struct in_addr " in );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR inet_aton (),
.BR inet_ntoa ():
.nf
.I a
is interpreted as a 32-bit value that is stored directly
into the binary address without any byte rearrangement.
-.PP
+.P
In all of the above forms,
components of the dotted address can be specified in decimal,
octal (with a leading
.I IPv4 dotted-decimal notation
(or sometimes:
.IR "IPv4 dotted-quad notation" ).
-.PP
+.P
.BR inet_aton ()
returns 1 if the supplied string was successfully interpreted,
or 0 if the string is invalid
is
.I not
set on error).
-.PP
+.P
The
.BR inet_addr ()
function converts the Internet host address
or
.BR getaddrinfo (3),
which provide a cleaner way to indicate error return.
-.PP
+.P
The
.BR inet_network ()
function converts
Internet network address.
On success, the converted address is returned.
If the input is invalid, \-1 is returned.
-.PP
+.P
The
.BR inet_ntoa ()
function converts the Internet host address
dotted-decimal notation.
The string is returned in a statically
allocated buffer, which subsequent calls will overwrite.
-.PP
+.P
The
.BR inet_lnaof ()
function returns the local network address part
of the Internet address \fIin\fP.
The returned value is in host byte order.
-.PP
+.P
The
.BR inet_netof ()
function returns the network number part of
the Internet address \fIin\fP.
The returned value is in host byte order.
-.PP
+.P
The
.BR inet_makeaddr ()
function is the converse of
created by combining the network number \fInet\fP
with the local address \fIhost\fP, both in
host byte order.
-.PP
+.P
The structure \fIin_addr\fP as used in
.BR inet_ntoa (),
.BR inet_makeaddr (),
is defined in
.I <netinet/in.h>
as:
-.PP
+.P
.in +4n
.EX
typedef uint32_t in_addr_t;
.TQ
.BR inet_ntoa ()
POSIX.1-2001, 4.3BSD.
-.PP
+.P
.BR inet_lnaof (),
.BR inet_netof (),
and
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.
-.PP
+.P
Classful network addresses are now obsolete,
having been superseded by Classless Inter-Domain Routing (CIDR),
which divides addresses into network and host components at
.BR inet_ntoa ()
is shown below.
Here are some example runs:
-.PP
+.P
.in +4n
.EX
.RB "$" " ./a.out 226.000.000.037" " # Last byte is in octal"
.SH SYNOPSIS
.nf
.B #include <arpa/inet.h>
-.PP
+.P
.BI "int inet_net_pton(int " af ", const char *" pres ,
.BI " void " netp [. nsize "], size_t " nsize );
.BI "char *inet_net_ntop(int " af ,
.BI " int " bits ,
.BI " char " pres [. psize "], size_t " psize );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR inet_net_pton (),
.BR inet_net_ntop ():
.nf
.SH DESCRIPTION
These functions convert network numbers between
presentation (i.e., printable) format and network (i.e., binary) format.
-.PP
+.P
For both functions,
.I af
specifies the address family for the conversion;
.I nsize
argument specifies the number of bytes available in
.IR netp .
-.PP
+.P
On success,
.BR inet_net_pton ()
returns the number of bits in the network number field
.IR netp .
For a discussion of the input presentation format and the return value,
see NOTES.
-.PP
+.P
.IR Note :
the buffer pointed to by
.I netp
.I bits
argument specifies the number of bits in the network number in
.IR *netp .
-.PP
+.P
The null-terminated presentation-format string
is placed in the buffer pointed to by
.IR pres .
On error, it returns \-1, and
.I errno
is set to indicate the error.
-.PP
+.P
On success,
.BR inet_net_ntop ()
returns
The network number may be specified either
as a hexadecimal value
or in dotted-decimal notation.
-.PP
+.P
Hexadecimal values are indicated by an initial "0x" or "0X".
The hexadecimal digits populate the nibbles (half octets) of the
network number from left to right in network byte order.
.\" If the hexadecimal string is short, the remaining nibbles are zeroed.
-.PP
+.P
In dotted-decimal notation, up to four octets are specified,
as decimal numbers separated by dots.
Thus, any of the following forms are accepted:
-.PP
+.P
.in +4n
.EX
a.b.c.d
a
.EE
.in
-.PP
+.P
Each part is a number in the range 0 to 255 that
populates one byte of the resulting network number,
going from left to right, in network-byte (big endian) order.
.\" Reading other man pages, some other implementations treat
.\" 'c' in a.b.c as a 16-bit number that populates right-most two bytes
.\" 'b' in a.b as a 24-bit number that populates right-most three bytes
-.PP
+.P
For either hexadecimal or dotted-decimal format,
the network number can optionally be followed by a slash
and a number in the range 0 to 32,
Otherwise,
.I bits
is 8.
-.PP
+.P
If the resulting
.I bits
value from the above steps is greater than or equal to 8,
.BR inet_net_ntop ()
to convert the binary form back to presentation format,
and displays the resulting string.
-.PP
+.P
In order to demonstrate that
.BR inet_net_pton ()
may not write to all bytes of its
.BR inet_net_pton ()
allowing the user to see which bytes have not been touched by
.BR inet_net_pton ().
-.PP
+.P
An example run, showing that
.BR inet_net_pton ()
infers the number of bits in the network number:
-.PP
+.P
.in +4n
.EX
$ \fB./a.out 193.168\fP
Raw address: c1a80000
.EE
.in
-.PP
+.P
Demonstrate that
.BR inet_net_pton ()
does not zero out unused bytes in its result buffer:
-.PP
+.P
.in +4n
.EX
$ \fB./a.out 193.168 0xffffffff\fP
Raw address: c1a800ff
.EE
.in
-.PP
+.P
Demonstrate that
.BR inet_net_pton ()
will widen the inferred size of the network number,
if the supplied number of bytes in the presentation
string exceeds the inferred value:
-.PP
+.P
.in +4n
.EX
$ \fB./a.out 193.168.1.128\fP
Raw address: c1a80180
.EE
.in
-.PP
+.P
Explicitly specifying the size of the network number overrides any
inference about its size
(but any extra bytes that are explicitly specified will still be used by
.BR inet_net_pton ():
to populate the result buffer):
-.PP
+.P
.in +4n
.EX
$ \fB./a.out 193.168.1.128/24\fP
.SH SYNOPSIS
.nf
.B #include <arpa/inet.h>
-.PP
+.P
.BI "const char *inet_ntop(int " af ", const void *restrict " src ,
.BI " char " dst "[restrict ." size "], socklen_t " size );
.fi
The caller specifies the number of bytes available in this buffer in
the argument
.IR size .
-.PP
+.P
.BR inet_ntop ()
extends the
.BR inet_ntoa (3)
POSIX.1-2008.
.SH HISTORY
POSIX.1-2001.
-.PP
+.P
Note that RFC\ 2553 defines a prototype where the last argument
.I size
is of type
.SH SYNOPSIS
.nf
.B #include <arpa/inet.h>
-.PP
+.P
.BI "int inet_pton(int " af ", const char *restrict " src \
", void *restrict " dst );
.fi
.BR AF_INET6 .
.I dst
is written in network byte order.
-.PP
+.P
The following address families are currently supported:
.TP
.B AF_INET
and
.BR inet_ntop (3).
Here are some example runs:
-.PP
+.P
.in +4n
.EX
.RB "$" " ./a.out i6 0:0:0:0:0:0:0:0"
.nf
.B #include <sys/types.h>
.B #include <grp.h>
-.PP
+.P
.BI "int initgroups(const char *" user ", gid_t " group );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR initgroups ():
.nf
Since glibc 2.19:
.I group
is
also added to the list.
-.PP
+.P
The
.I user
argument must be non-NULL.
.SH SYNOPSIS
.nf
.B #include <search.h>
-.PP
+.P
.BI "void insque(void *" elem ", void *" prev );
.BI "void remque(void *" elem );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR insque (),
.BR remque ():
.nf
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.
-.PP
+.P
The
.BR insque ()
function inserts the element pointed to by \fIelem\fP
immediately after the element pointed to by \fIprev\fP.
-.PP
+.P
If the list is linear, then the call
.I "insque(elem, NULL)"
can be used to insert the initial list element,
and the call sets the forward and backward pointers of
.I elem
to NULL.
-.PP
+.P
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,
argument of the
.BR insque ()
call should also point to the element.
-.PP
+.P
The
.BR remque ()
function removes the element pointed to by \fIelem\fP from the
.\" e.g., SunOS, Linux libc4 and libc5
the arguments of these functions were of type \fIstruct qelem *\fP,
defined as:
-.PP
+.P
.in +4n
.EX
struct qelem {
};
.EE
.in
-.PP
+.P
This is still what you will get if
.B _GNU_SOURCE
is defined before
including \fI<search.h>\fP.
-.PP
+.P
The location of the prototypes for these functions differs among several
versions of UNIX.
The above is the POSIX version.
The program below demonstrates the use of
.BR insque ().
Here is an example run of the program:
-.PP
+.P
.in +4n
.EX
.RB "$ " "./a.out \-c a b c"
(system call wrappers)
described in Section 2,
which implement system calls.
-.PP
+.P
Many of the functions described in the section are part of the
Standard C Library
.RI ( libc ).
.IR \-lrt ,
respectively,
for the aforementioned libraries).
-.PP
+.P
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
3head
.IP \[bu]
3type
-.PP
+.P
This difficult history frequently makes it a poor example to follow
in design,
implementation,
and presentation.
-.PP
+.P
Ideally,
a library for the C language
is designed such that each header file
.SH SYNOPSIS
.nf
.B #include <ctype.h>
-.PP
+.P
.BI "int isalnum(int " c );
.BI "int isalpha(int " c );
.BI "int iscntrl(int " c );
.BI "int isspace(int " c );
.BI "int isupper(int " c );
.BI "int isxdigit(int " c );
-.PP
+.P
.BI "int isascii(int " c );
.BI "int isblank(int " c );
-.PP
+.P
.BI "int isalnum_l(int " c ", locale_t " locale );
.BI "int isalpha_l(int " c ", locale_t " locale );
.BI "int isblank_l(int " c ", locale_t " locale );
.BI "int isspace_l(int " c ", locale_t " locale );
.BI "int isupper_l(int " c ", locale_t " locale );
.BI "int isxdigit_l(int " c ", locale_t " locale );
-.PP
+.P
.BI "int isascii_l(int " c ", locale_t " locale );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
.ad l
-.PP
+.P
.BR isascii ():
.nf
_XOPEN_SOURCE
|| /* glibc >= 2.19: */ _DEFAULT_SOURCE
|| /* glibc <= 2.19: */ _SVID_SOURCE
.fi
-.PP
+.P
.BR isblank ():
.nf
_ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
.fi
-.PP
+.P
.BR \%salnum_l (),
.BR \%salpha_l (),
.BR \%sblank_l (),
Before glibc 2.10:
_GNU_SOURCE
.fi
-.PP
+.P
.BR isascii_l ():
.nf
Since glibc 2.10:
falls into a certain character class according to the specified locale.
The functions without the
"_l" suffix perform the check based on the current locale.
-.PP
+.P
The functions with the "_l" suffix perform the check
based on the locale specified by the locale object
.IR locale .
(see
.BR duplocale (3))
or is not a valid locale object handle.
-.PP
+.P
The list below explains the operation of the functions without
the "_l" suffix;
the functions with the "_l" suffix differ only in using the locale object
it must be cast to
.IR "unsigned char" ,
as in the following example:
-.PP
+.P
.in +4n
.EX
char c;
res = toupper((unsigned char) c);
.EE
.in
-.PP
+.P
This is necessary because
.I char
may be the equivalent of
.IR int ,
yielding a value that is outside the range of
.IR "unsigned char" .
-.PP
+.P
The details of what characters belong to which class depend on the
locale.
For example,
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.BI "int isatty(int " fd );
.fi
.SH DESCRIPTION
.nf
.B #include <sys/stat.h>
.B #include <sys/socket.h>
-.PP
+.P
.BI "int isfdtype(int " fd ", int " fdtype );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR isfdtype ():
.nf
Since glibc 2.20:
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "int isgreater(" x ", " y );
.BI "int isgreaterequal(" x ", " y );
.BI "int isless(" x ", " y );
.BI "int islessgreater(" x ", " y );
.BI "int isunordered(" x ", " y );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.nf
All functions described here:
_ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
fail if one of the operands is NaN.
This will cause an exception.
To avoid this, C99 defines the macros listed below.
-.PP
+.P
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
.BR isunordered ()
return the result of the relational comparison;
these macros return 0 if either argument is a NaN.
-.PP
+.P
.BR isunordered ()
returns 1 if
.I x
.SH SYNOPSIS
.nf
.B #include <wctype.h>
-.PP
+.P
.BI "int iswalnum(wint_t " wc );
.fi
.SH DESCRIPTION
.I wc
is a wide character
belonging to the wide-character class "alnum".
-.PP
+.P
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".
-.PP
+.P
Being a subclass of the wide-character class "print",
the wide-character class
"alnum" is disjoint from the wide-character class "cntrl".
-.PP
+.P
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".
-.PP
+.P
The wide-character class "alnum" is disjoint from the wide-character class
"punct".
-.PP
+.P
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".
-.PP
+.P
The wide-character class "alnum"
always contains at least the letters
\[aq]A\[aq] to \[aq]Z\[aq],
.SH SYNOPSIS
.nf
.B #include <wctype.h>
-.PP
+.P
.BI "int iswalpha(wint_t " wc );
.fi
.SH DESCRIPTION
.I wc
is a wide character
belonging to the wide-character class "alpha".
-.PP
+.P
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".
-.PP
+.P
Being a subclass of the wide-character class "print",
the wide-character class
"alpha" is disjoint from the wide-character class "cntrl".
-.PP
+.P
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".
-.PP
+.P
Being a subclass of the wide-character class "alnum",
the wide-character class "alpha" is disjoint from the
wide-character class "punct".
-.PP
+.P
The wide-character class "alpha" is disjoint from the wide-character class
"digit".
-.PP
+.P
The wide-character class "alpha" contains the wide-character classes "upper"
and "lower".
-.PP
+.P
The wide-character class "alpha" always contains at least the
letters \[aq]A\[aq] to \[aq]Z\[aq] and \[aq]a\[aq] to \[aq]z\[aq].
.SH RETURN VALUE
.SH SYNOPSIS
.nf
.B #include <wctype.h>
-.PP
+.P
.BI "int iswblank(wint_t " wc );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR iswblank ():
.nf
_ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
function.
It tests whether \fIwc\fP is a wide character
belonging to the wide-character class "blank".
-.PP
+.P
The wide-character class "blank" is a subclass of the wide-character class
"space".
-.PP
+.P
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".
-.PP
+.P
The wide-character class "blank" always contains
at least the space character
and the control character \[aq]\et\[aq].
.SH SYNOPSIS
.nf
.B #include <wctype.h>
-.PP
+.P
.BI "int iswcntrl(wint_t " wc );
.fi
.SH DESCRIPTION
.I wc
is a wide character
belonging to the wide-character class "cntrl".
-.PP
+.P
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".
-.PP
+.P
For an unsigned char
.IR c ,
.I iscntrl(c)
.SH SYNOPSIS
.nf
.B #include <wctype.h>
-.PP
+.P
.BI "int iswctype(wint_t " wc ", wctype_t " desc );
.fi
.SH DESCRIPTION
is
.BR WEOF ,
zero is returned.
-.PP
+.P
.I desc
must be a character property descriptor
returned by the
.SH SYNOPSIS
.nf
.B #include <wctype.h>
-.PP
+.P
.BI "int iswdigit(wint_t " wc );
.fi
.SH DESCRIPTION
.I wc
is a wide character
belonging to the wide-character class "digit".
-.PP
+.P
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".
-.PP
+.P
Being a subclass of the wide character
class "print", the wide-character class
"digit" is disjoint from the wide-character class "cntrl".
-.PP
+.P
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".
-.PP
+.P
Being a subclass of the wide-character
class "alnum", the wide-character class
"digit" is disjoint from the wide-character class "punct".
-.PP
+.P
The wide-character class "digit" is
disjoint from the wide-character class
"alpha" and therefore also disjoint from its subclasses "lower", "upper".
-.PP
+.P
The wide-character class "digit" always
contains exactly the digits \[aq]0\[aq] to \[aq]9\[aq].
.SH RETURN VALUE
.SH SYNOPSIS
.nf
.B #include <wctype.h>
-.PP
+.P
.BI "int iswgraph(wint_t " wc );
.fi
.SH DESCRIPTION
.I wc
is a wide character
belonging to the wide-character class "graph".
-.PP
+.P
The wide-character class "graph" is a subclass of the wide-character class
"print".
-.PP
+.P
Being a subclass of the wide-character class "print",
the wide-character class
"graph" is disjoint from the wide-character class "cntrl".
-.PP
+.P
The wide-character class "graph" is disjoint from the wide-character class
"space" and therefore also disjoint from its subclass "blank".
.\" Note: UNIX98 (susv2/xbd/locale.html) says that "graph" and "space" may
.\" have characters in common, except U+0020. But C99 (ISO/IEC 9899:1999
.\" section 7.25.2.1.10) says that "space" and "graph" are disjoint.
-.PP
+.P
The wide-character class "graph" contains all the wide characters from the
wide-character class "print" except the space character.
It therefore contains
.SH SYNOPSIS
.nf
.B #include <wctype.h>
-.PP
+.P
.BI "int iswlower(wint_t " wc );
.fi
.SH DESCRIPTION
.I wc
is a wide character
belonging to the wide-character class "lower".
-.PP
+.P
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".
-.PP
+.P
Being a subclass of the wide-character class "print",
the wide-character class
"lower" is disjoint from the wide-character class "cntrl".
-.PP
+.P
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".
-.PP
+.P
Being a subclass of the wide-character class "alnum",
the wide-character class
"lower" is disjoint from the wide-character class "punct".
-.PP
+.P
Being a subclass of the wide-character class "alpha",
the wide-character class
"lower" is disjoint from the wide-character class "digit".
-.PP
+.P
The wide-character class "lower" contains at least
those characters
.I wc
.I towlower(wc)
and different from
.IR towupper(wc) .
-.PP
+.P
The wide-character class "lower" always contains
at least the letters \[aq]a\[aq] to \[aq]z\[aq].
.SH RETURN VALUE
.B LC_CTYPE
category of the
current locale.
-.PP
+.P
This function is not very appropriate for dealing with Unicode characters,
because Unicode knows about three cases: upper, lower, and title case.
.SH SEE ALSO
.SH SYNOPSIS
.nf
.B #include <wctype.h>
-.PP
+.P
.BI "int iswprint(wint_t " wc );
.fi
.SH DESCRIPTION
.I wc
is a wide character
belonging to the wide-character class "print".
-.PP
+.P
The wide-character class "print" is disjoint from the wide-character class
"cntrl".
-.PP
+.P
The wide-character class "print" contains the wide-character class "graph".
.SH RETURN VALUE
The
.SH SYNOPSIS
.nf
.B #include <wctype.h>
-.PP
+.P
.BI "int iswpunct(wint_t " wc );
.fi
.SH DESCRIPTION
.I wc
is a wide character
belonging to the wide-character class "punct".
-.PP
+.P
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".
-.PP
+.P
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".
-.PP
+.P
Being a subclass of the wide-character class "print",
the wide-character class
"punct" is disjoint from the wide-character class "cntrl".
-.PP
+.P
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
.B LC_CTYPE
category of the
current locale.
-.PP
+.P
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.
.SH SYNOPSIS
.nf
.B #include <wctype.h>
-.PP
+.P
.BI "int iswspace(wint_t " wc );
.fi
.SH DESCRIPTION
.I wc
is a wide character
belonging to the wide-character class "space".
-.PP
+.P
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".
.\" Note: UNIX98 (susv2/xbd/locale.html) says that "space" and "graph" may
.\" have characters in common, except U+0020. But C99 (ISO/IEC 9899:1999
.\" section 7.25.2.1.10) says that "space" and "graph" are disjoint.
-.PP
+.P
The wide-character class "space" contains the wide-character class "blank".
-.PP
+.P
The wide-character class "space"
always contains at least the space character
and the control characters
.SH SYNOPSIS
.nf
.B #include <wctype.h>
-.PP
+.P
.BI "int iswupper(wint_t " wc );
.fi
.SH DESCRIPTION
.I wc
is a wide character
belonging to the wide-character class "upper".
-.PP
+.P
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".
-.PP
+.P
Being a subclass of the wide-character class "print", the wide-character class
"upper" is disjoint from the wide-character class "cntrl".
-.PP
+.P
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".
-.PP
+.P
Being a subclass of the wide-character class "alnum", the wide-character class
"upper" is disjoint from the wide-character class "punct".
-.PP
+.P
Being a subclass of the wide-character class "alpha", the wide-character class
"upper" is disjoint from the wide-character class "digit".
-.PP
+.P
The wide-character class "upper" contains at least those characters
.I wc
which are equal to
.I towupper(wc)
and different from
.IR towlower(wc) .
-.PP
+.P
The wide-character class "upper" always contains at least the
letters \[aq]A\[aq] to \[aq]Z\[aq].
.SH RETURN VALUE
.B LC_CTYPE
category of the
current locale.
-.PP
+.P
This function is not very appropriate for dealing with Unicode characters,
because Unicode knows about three cases: upper, lower, and title case.
.SH SEE ALSO
.SH SYNOPSIS
.nf
.B #include <wctype.h>
-.PP
+.P
.BI "int iswxdigit(wint_t " wc );
.fi
.SH DESCRIPTION
.I wc
is a wide character
belonging to the wide-character class "xdigit".
-.PP
+.P
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".
-.PP
+.P
Being a subclass of the wide-character class "print", the wide-character class
"xdigit" is disjoint from the wide-character class "cntrl".
-.PP
+.P
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".
-.PP
+.P
Being a subclass of the wide-character class "alnum", the wide-character class
"xdigit" is disjoint from the wide-character class "punct".
-.PP
+.P
The wide-character class "xdigit" always contains at least the
letters \[aq]A\[aq] to \[aq]F\[aq], \[aq]a\[aq] to \[aq]f\[aq]
and the digits \[aq]0\[aq] to \[aq]9\[aq].
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "double j0(double " x );
.BI "double j1(double " x );
.BI "double jn(int " n ", double " x );
-.PP
+.P
.BI "float j0f(float " x );
.BI "float j1f(float " x );
.BI "float jnf(int " n ", float " x );
-.PP
+.P
.BI "long double j0l(long double " x );
.BI "long double j1l(long double " x );
.BI "long double jnl(int " n ", long double " x );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR j0 (),
.BR j1 (),
.BR jn ():
|| /* Since glibc 2.19: */ _DEFAULT_SOURCE
|| /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE
.fi
-.PP
+.P
.BR j0f (),
.BR j0l (),
.BR j1f (),
.I x
of the first kind of order
.IR n .
-.PP
+.P
The
.BR j0f (),
.BR j1f (),
On success, these functions return the appropriate
Bessel value of the first kind for
.IR x .
-.PP
+.P
If
.I x
is a NaN, a NaN is returned.
-.PP
+.P
If
.I x
is too large in magnitude,
.BR math_error (7)
for information on how to determine whether an error has occurred
when calling these functions.
-.PP
+.P
The following errors can occur:
.TP
Range error: result underflow, or \fIx\fP is too large in magnitude
.I errno
is set to
.BR ERANGE .
-.PP
+.P
These functions do not raise exceptions for
.BR fetestexcept (3).
.\" e.g., j0(1.5e16)
.SH SYNOPSIS
.nf
.B #include <rpc/rpc.h>
-.PP
+.P
.BI "int key_decryptsession(char *" remotename ", des_block *" deskey );
.BI "int key_encryptsession(char *" remotename ", des_block *" deskey );
-.PP
+.P
.BI "int key_gendes(des_block *" deskey );
-.PP
+.P
.BI "int key_setsecret(char *" key );
.B int key_secretkey_is_set(void);
.fi
mechanism (AUTH_DES).
There should be no need for user programs to
use this functions.
-.PP
+.P
The function
.BR 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.
-.PP
+.P
The function
.BR key_encryptsession ()
is the inverse of
.BR 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.
-.PP
+.P
The function
.BR key_gendes ()
is used to ask the keyserver for a secure conversation key.
-.PP
+.P
The function
.BR key_setsecret ()
is used to set the key for the effective UID of the calling process.
-.PP
+.P
The function
.BR key_secretkey_is_set ()
can be used to determine whether a key has been
One is asymmetric using a public and secret key.
The other is symmetric, the
64-bit DES.
-.PP
+.P
These routines were part of the Linux/Doors-project, abandoned by now.
.SH SEE ALSO
.BR crypt (3)
.SH SYNOPSIS
.nf
.B #include <signal.h>
-.PP
+.P
.BI "int killpg(int " pgrp ", int " sig );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR killpg ():
.nf
_XOPEN_SOURCE >= 500
See
.BR signal (7)
for a list of signals.
-.PP
+.P
If
.I pgrp
is 0,
(POSIX says: if
.I pgrp
is less than or equal to 1, the behavior is undefined.)
-.PP
+.P
For the permissions required to send a signal to another process, see
.BR kill (2).
.SH RETURN VALUE
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "double ldexp(double " x ", int " exp );
.BI "float ldexpf(float " x ", int " exp );
.BI "long double ldexpl(long double " x ", int " exp );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR ldexpf (),
.BR ldexpl ():
.nf
.SH RETURN VALUE
On success, these functions return
.IR "x * (2\[ha]exp)" .
-.PP
+.P
If
.I exp
is zero, then
.I x
is returned.
-.PP
+.P
If
.I x
is a NaN,
a NaN is returned.
-.PP
+.P
If
.I x
is positive infinity (negative infinity),
positive infinity (negative infinity) is returned.
-.PP
+.P
If the result underflows,
a range error occurs,
and zero is returned.
-.PP
+.P
If the result overflows,
a range error occurs,
and the functions return
.BR math_error (7)
for information on how to determine whether an error has occurred
when calling these functions.
-.PP
+.P
The following errors can occur:
.TP
Range error, overflow
C11, POSIX.1-2008.
.SH HISTORY
C99, POSIX.1-2001.
-.PP
+.P
The variant returning
.I double
also conforms to
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "double lgamma(double " x );
.BI "float lgammaf(float " x );
.BI "long double lgammal(long double " x );
-.PP
+.P
.BI "double lgamma_r(double " x ", int *" signp );
.BI "float lgammaf_r(float " x ", int *" signp );
.BI "long double lgammal_r(long double " x ", int *" signp );
-.PP
+.P
.BI "extern int " signgam ;
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.nf
.BR lgamma ():
_ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L || _XOPEN_SOURCE
|| /* Since glibc 2.19: */ _DEFAULT_SOURCE
|| /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
.fi
-.PP
+.P
.BR lgammaf (),
.BR lgammal ():
.nf
|| /* Since glibc 2.19: */ _DEFAULT_SOURCE
|| /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
.fi
-.PP
+.P
.BR lgamma_r (),
.BR lgammaf_r (),
.BR lgammal_r ():
/* Since glibc 2.19: */ _DEFAULT_SOURCE
|| /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
.fi
-.PP
+.P
.IR signgam :
.nf
_XOPEN_SOURCE
.SH DESCRIPTION
For the definition of the Gamma function, see
.BR tgamma (3).
-.PP
+.P
The
.BR lgamma (),
.BR lgammaf (),
.IR <math.h> .
It is 1 when the Gamma function is positive or zero, \-1
when it is negative.
-.PP
+.P
Since using a constant location
.I signgam
is not thread-safe, the functions
.IR signp .
.SH RETURN VALUE
On success, these functions return the natural logarithm of Gamma(x).
-.PP
+.P
If
.I x
is a NaN, a NaN is returned.
-.PP
+.P
If
.I x
is 1 or 2, +0 is returned.
-.PP
+.P
If
.I x
is positive infinity or negative infinity,
positive infinity is returned.
-.PP
+.P
If
.I x
is a nonpositive integer,
or
.RB + HUGE_VALL ,
respectively.
-.PP
+.P
If the result overflows,
a range error occurs,
.\" e.g., lgamma(DBL_MAX)
.BR math_error (7)
for information on how to determine whether an error has occurred
when calling these functions.
-.PP
+.P
The following errors can occur:
.TP
Pole error: \fIx\fP is a nonpositive integer
.SH SYNOPSIS
.nf
.B "#include <aio.h>"
-.PP
+.P
.BI "int lio_listio(int " mode ,
.BI " struct aiocb *restrict const " aiocb_list [restrict],
.BI " int " nitems ", struct sigevent *restrict " sevp );
.BR lio_listio ()
function initiates the list of I/O operations described by the array
.IR aiocb_list .
-.PP
+.P
The
.I mode
operation has one of the following values:
If
.I sevp
is NULL, no asynchronous notification occurs.
-.PP
+.P
The
.I aiocb_list
argument is an array of pointers to
Null pointers in
.I aiocb_list
are ignored.
-.PP
+.P
In each control block in
.IR aiocb_list ,
the
.TP
.B LIO_NOP
Ignore this control block.
-.PP
+.P
The remaining fields in each control block have the same meanings as for
.BR aio_read (3)
and
Otherwise, \-1 is returned, and
.I errno
is set to indicate the error.
-.PP
+.P
If
.I mode
is
Otherwise, \-1 is returned, and
.I errno
is set to indicate the error.
-.PP
+.P
The return status from
.BR lio_listio ()
provides information only about the call itself,
.\" e.g., ioa_reqprio or aio_lio_opcode was invalid
The application can check the status of each operation using
.BR aio_return (3).
-.PP
+.P
If
.BR lio_listio ()
fails with the error
.\" or the control block of the operation
must not be accessed during the operations or undefined results may occur.
The memory areas involved must remain valid.
-.PP
+.P
Simultaneous I/O operations specifying the same
.I aiocb
structure produce undefined results.
.SH SYNOPSIS
.nf
.B #include <sys/queue.h>
-.PP
+.P
.B LIST_ENTRY(TYPE);
-.PP
+.P
.B LIST_HEAD(HEADNAME, TYPE);
.BI "LIST_HEAD LIST_HEAD_INITIALIZER(LIST_HEAD " head );
.BI "void LIST_INIT(LIST_HEAD *" head );
-.PP
+.P
.BI "int LIST_EMPTY(LIST_HEAD *" head );
-.PP
+.P
.BI "void LIST_INSERT_HEAD(LIST_HEAD *" head ,
.BI " struct TYPE *" elm ", LIST_ENTRY " NAME );
.BI "void LIST_INSERT_BEFORE(struct TYPE *" listelm ,
.BI " struct TYPE *" elm ", LIST_ENTRY " NAME );
.BI "void LIST_INSERT_AFTER(struct TYPE *" listelm ,
.BI " struct TYPE *" elm ", LIST_ENTRY " NAME );
-.PP
+.P
.BI "struct TYPE *LIST_FIRST(LIST_HEAD *" head );
.\" .BI "struct TYPE *LIST_PREV(struct TYPE *" elm ", LIST_HEAD *" head ,
.\" .BI " struct TYPE, LIST_ENTRY " NAME );
.BI "struct TYPE *LIST_NEXT(struct TYPE *" elm ", LIST_ENTRY " NAME );
-.PP
+.P
.BI "LIST_FOREACH(struct TYPE *" var ", LIST_HEAD *" head ", LIST_ENTRY " NAME );
.\" .BI "LIST_FOREACH_FROM(struct TYPE *" var ", LIST_HEAD *" head ", LIST_ENTRY " NAME );
-.\" .PP
+.\" .P
.\" .BI "LIST_FOREACH_SAFE(struct TYPE *" var ", LIST_HEAD *" head ,
.\" .BI " LIST_ENTRY " NAME ", struct TYPE *" temp_var );
.\" .BI "LIST_FOREACH_FROM_SAFE(struct TYPE *" var ", LIST_HEAD *" head ,
.\" .BI " LIST_ENTRY " NAME ", struct TYPE *" temp_var );
-.PP
+.P
.BI "void LIST_REMOVE(struct TYPE *" elm ", LIST_ENTRY " NAME );
-.\" .PP
+.\" .P
.\" .BI "void LIST_SWAP(LIST_HEAD *" head1 ", LIST_HEAD *" head2 ,
.\" .BI " struct TYPE, LIST_ENTRY " NAME );
.fi
.SH DESCRIPTION
These macros define and operate on doubly linked lists.
-.PP
+.P
In the macro definitions,
.I TYPE
is the name of a user-defined structure,
A
.I LIST_HEAD
structure is declared as follows:
-.PP
+.P
.in +4
.EX
LIST_HEAD(HEADNAME, TYPE) head;
.EE
.in
-.PP
+.P
where
.I struct HEADNAME
is the structure to be defined, and
.I struct 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:
-.PP
+.P
.in +4
.EX
struct HEADNAME *headp;
.EE
.in
-.PP
+.P
(The names
.I head
and
.I headp
are user selectable.)
-.PP
+.P
.BR LIST_ENTRY ()
declares a structure that connects the elements in the list.
-.PP
+.P
.BR LIST_HEAD_INITIALIZER ()
evaluates to an initializer for the list
.IR head .
-.PP
+.P
.BR LIST_INIT ()
initializes the list referenced by
.IR head .
-.PP
+.P
.BR LIST_EMPTY ()
evaluates to true if there are no elements in the list.
.SS Insertion
inserts the new element
.I elm
at the head of the list.
-.PP
+.P
.BR LIST_INSERT_BEFORE ()
inserts the new element
.I elm
before the element
.IR listelm .
-.PP
+.P
.BR LIST_INSERT_AFTER ()
inserts the new element
.I elm
.SS Traversal
.BR LIST_FIRST ()
returns the first element in the list, or NULL if the list is empty.
-.\" .PP
+.\" .P
.\" .BR LIST_PREV ()
.\" returns the previous element in the list, or NULL if this is the first.
.\" List
.\" .I head
.\" must contain element
.\" .IR elm .
-.PP
+.P
.BR LIST_NEXT ()
returns the next element in the list, or NULL if this is the last.
-.PP
+.P
.BR LIST_FOREACH ()
traverses the list referenced by
.I head
in the forward direction,
assigning each element in turn to
.IR var .
-.\" .PP
+.\" .P
.\" .BR LIST_FOREACH_FROM ()
.\" behaves identically to
.\" .BR LIST_FOREACH ()
.\" .I var
.\" instead of the first element in the LIST referenced by
.\" .IR head .
-.\" .PP
+.\" .P
.\" .BR LIST_FOREACH_SAFE ()
.\" traverses the list referenced by
.\" .I head
.\" .I var
.\" as well as free it from within the loop safely without interfering with the
.\" traversal.
-.\" .PP
+.\" .P
.\" .BR LIST_FOREACH_FROM_SAFE ()
.\" behaves identically to
.\" .BR LIST_FOREACH_SAFE ()
.BR LIST_EMPTY ()
returns nonzero if the list is empty,
and zero if the list contains at least one entry.
-.PP
+.P
.BR LIST_FIRST (),
and
.BR LIST_NEXT ()
return a pointer to the first or next
.I TYPE
structure, respectively.
-.PP
+.P
.BR LIST_HEAD_INITIALIZER ()
returns an initializer that can be assigned to the list
.IR head .
.SH SYNOPSIS
.nf
.B #include <locale.h>
-.PP
+.P
.B struct lconv *localeconv(void);
.fi
.SH DESCRIPTION
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.BI "int lockf(int " fd ", int " cmd ", off_t " len );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR lockf ():
.nf
_XOPEN_SOURCE >= 500
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.
-.PP
+.P
On Linux,
.BR lockf ()
is just an interface on top of
locks unspecified.
A portable application should probably avoid mixing calls
to these interfaces.
-.PP
+.P
Valid operations are given below:
.TP
.B F_LOCK
.SH SEE ALSO
.BR fcntl (2),
.BR flock (2)
-.PP
+.P
.I locks.txt
and
.I mandatory\-locking.txt
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "double log(double " x );
.BI "float logf(float " x );
.BI "long double logl(long double " x );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR logf (),
.BR logl ():
.nf
.SH RETURN VALUE
On success, these functions return the natural logarithm of
.IR x .
-.PP
+.P
If
.I x
is a NaN,
a NaN is returned.
-.PP
+.P
If
.I x
is 1, the result is +0.
-.PP
+.P
If
.I x
is positive infinity,
positive infinity is returned.
-.PP
+.P
If
.I x
is zero,
or
.RB \- HUGE_VALL ,
respectively.
-.PP
+.P
If
.I x
is negative (including negative infinity), then
.BR math_error (7)
for information on how to determine whether an error has occurred
when calling these functions.
-.PP
+.P
The following errors can occur:
.TP
Domain error: \fIx\fP is negative
C11, POSIX.1-2008.
.SH HISTORY
C99, POSIX.1-2001.
-.PP
+.P
The variant returning
.I double
also conforms to
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "double log10(double " x );
.BI "float log10f(float " x );
.BI "long double log10l(long double " x );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR log10f (),
.BR log10l ():
.nf
.SH RETURN VALUE
On success, these functions return the base 10 logarithm of
.IR x .
-.PP
+.P
For special cases, including where
.I x
is 0, 1, negative, infinity, or NaN, see
.BR math_error (7)
for information on how to determine whether an error has occurred
when calling these functions.
-.PP
+.P
For a discussion of the errors that can occur for these functions, see
.BR log (3).
.SH ATTRIBUTES
C11, POSIX.1-2008.
.SH HISTORY
C99, POSIX.1-2001.
-.PP
+.P
The variant returning
.I double
also conforms to
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "double log1p(double " x );
.BI "float log1pf(float " x );
.BI "long double log1pl(long double " x );
-.PP
+.P
.fi
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.nf
.BR log1p ():
_ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
|| /* Since glibc 2.19: */ _DEFAULT_SOURCE
|| /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
.fi
-.PP
+.P
.BR log1pf (),
.BR log1pl ():
.nf
.fi
.SH DESCRIPTION
These functions return a value equivalent to
-.PP
+.P
.nf
log (1 + \fIx\fP)
.fi
-.PP
+.P
The result is computed in a way
that is accurate even if the value of
.I x
.SH RETURN VALUE
On success, these functions return the natural logarithm of
.IR "(1\ +\ x)" .
-.PP
+.P
If
.I x
is a NaN,
a NaN is returned.
-.PP
+.P
If
.I x
is positive infinity, positive infinity is returned.
-.PP
+.P
If
.I x
is \-1, a pole error occurs,
or
.RB \- HUGE_VALL ,
respectively.
-.PP
+.P
If
.I x
is less than \-1 (including negative infinity),
.BR math_error (7)
for information on how to determine whether an error has occurred
when calling these functions.
-.PP
+.P
The following errors can occur:
.TP
Domain error: \fIx\fP is less than \-1
to
.B EDOM
when a domain error occurred.
-.PP
+.P
Before glibc 2.22, the glibc implementation did not set
.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6792
.I errno
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "double log2(double " x );
.BI "float log2f(float " x );
.BI "long double log2l(long double " x );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR log2 (),
.BR log2f (),
.BR log2l ():
.SH RETURN VALUE
On success, these functions return the base 2 logarithm of
.IR x .
-.PP
+.P
For special cases, including where
.I x
is 0, 1, negative, infinity, or NaN, see
.BR math_error (7)
for information on how to determine whether an error has occurred
when calling these functions.
-.PP
+.P
For a discussion of the errors that can occur for these functions, see
.BR log (3).
.SH ATTRIBUTES
.SH HISTORY
glibc 2.1.
C99, POSIX.1-2001.
-.PP
+.P
The variant returning
.I double
also conforms to
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "double logb(double " x );
.BI "float logbf(float " x );
.BI "long double logbl(long double " x );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR logb ():
.nf
_ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
|| /* Since glibc 2.19: */ _DEFAULT_SOURCE
|| /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
.fi
-.PP
+.P
.BR logbf (),
.BR logbl ():
.nf
is equal to
.BI floor(log2( x ))\fR,
except that it is probably faster.
-.PP
+.P
If
.I x
is subnormal,
.SH RETURN VALUE
On success, these functions return the exponent of
.IR x .
-.PP
+.P
If
.I x
is a NaN,
a NaN is returned.
-.PP
+.P
If
.I x
is zero, then a pole error occurs, and the functions return
or
.RB \- HUGE_VALL ,
respectively.
-.PP
+.P
If
.I x
is negative infinity or positive infinity, then
.BR math_error (7)
for information on how to determine whether an error has occurred
when calling these functions.
-.PP
+.P
The following errors can occur:
.TP
Pole error: \fIx\fP is 0
A divide-by-zero floating-point exception
.RB ( FE_DIVBYZERO )
is raised.
-.PP
+.P
These functions do not set
.IR errno .
.\" FIXME . Is it intentional that these functions do not set errno?
.SH SYNOPSIS
.nf
.B #include <utmp.h>
-.PP
+.P
.BI "void login(const struct utmp *" ut );
.BI "int logout(const char *" ut_line );
.fi
The wtmp file records all logins and logouts.
See
.BR utmp (5).
-.PP
+.P
The function
.BR login ()
takes the supplied
.IR "struct utmp" ,
.IR ut ,
and writes it to both the utmp and the wtmp file.
-.PP
+.P
The function
.BR logout ()
clears the entry in the utmp file again.
if no terminal 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.
-.PP
+.P
The
.BR logout ()
function searches the utmp file for an entry matching the
sig:ALRM timer
T}
.TE
-.PP
+.P
In the above table,
.I utent
in
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "long lrint(double " x );
.BI "long lrintf(float " x );
.BI "long lrintl(long double " x );
-.PP
+.P
.BI "long long llrint(double " x );
.BI "long long llrintf(float " x );
.BI "long long llrintl(long double " x );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
All functions shown above:
.nf
_ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
These functions round their argument to the nearest integer value,
using the current rounding direction (see
.BR fesetround (3)).
-.PP
+.P
Note that unlike the
.BR rint (3)
family of functions,
that of their arguments.
.SH RETURN VALUE
These functions return the rounded integer value.
-.PP
+.P
If
.I x
is a NaN or an infinity,
.BR math_error (7)
for information on how to determine whether an error has occurred
when calling these functions.
-.PP
+.P
The following errors can occur:
.TP
Domain error: \fIx\fP is a NaN or infinite, or the rounded value is too large
An invalid floating-point exception
.RB ( FE_INVALID )
is raised.
-.PP
+.P
These functions do not set
.IR errno .
.\" FIXME . Is it intentional that these functions do not set errno?
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "long lround(double " x );
.BI "long lroundf(float " x );
.BI "long lroundl(long double " x );
-.PP
+.P
.BI "long long llround(double " x );
.BI "long long llroundf(float " x );
.BI "long long llroundl(long double " x );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
All functions shown above:
.nf
_ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
rounding halfway cases away from zero,
regardless of the current rounding direction (see
.BR fenv (3)).
-.PP
+.P
Note that unlike the
.BR round (3)
and
that of their arguments.
.SH RETURN VALUE
These functions return the rounded integer value.
-.PP
+.P
If
.I x
is a NaN or an infinity,
.BR math_error (7)
for information on how to determine whether an error has occurred
when calling these functions.
-.PP
+.P
The following errors can occur:
.TP
Domain error: \fIx\fP is a NaN or infinite, or the rounded value is too large
An invalid floating-point exception
.RB ( FE_INVALID )
is raised.
-.PP
+.P
These functions do not set
.IR errno .
.\" FIXME . Is it intentional that these functions do not set errno?
.SH SYNOPSIS
.nf
.B #include <search.h>
-.PP
+.P
.BI "void *lfind(const void " key [. size "], \
const void " base [. size " * ." nmemb ],
.BI " size_t *" nmemb ", size_t " size ,
.I key
object matches the array member, and
nonzero otherwise.
-.PP
+.P
If
.BR lsearch ()
does not find a matching element, then the
.BR "#define _LARGEFILE64_SOURCE" " /* See feature_test_macros(7) */"
.B #include <sys/types.h>
.B #include <unistd.h>
-.PP
+.P
.BI "off64_t lseek64(int " fd ", off64_t " offset ", int " whence );
.fi
.SH DESCRIPTION
or
.BR SEEK_END ,
respectively.
-.PP
+.P
For more details, return value, and errors, see
.BR lseek (2).
-.PP
+.P
Four interfaces are available:
.BR lseek (),
.BR lseek64 (),
.\"
.SS lseek()
Prototype:
-.PP
+.P
.in +4n
.EX
.BI "off_t lseek(int " fd ", off_t " offset ", int " whence );
.EE
.in
-.PP
+.P
The C library's
.BR lseek ()
wrapper function uses the type
.IR off_t .
This is a 32-bit signed type on 32-bit architectures, unless one
compiles with
-.PP
+.P
.in +4n
.EX
#define _FILE_OFFSET_BITS 64
.EE
.in
-.PP
+.P
in which case it is a 64-bit signed type.
.SS lseek64()
Prototype:
-.PP
+.P
.in +4n
.EX
.BI "off64_t lseek64(int " fd ", off64_t " offset ", int " whence );
.EE
.in
-.PP
+.P
The
.BR lseek64 ()
library function uses a 64-bit type even when
Its prototype (and the type
.IR off64_t )
is available only when one compiles with
-.PP
+.P
.in +4n
.EX
#define _LARGEFILE64_SOURCE
.EE
.in
-.PP
+.P
The function
.BR lseek64 ()
.\" in glibc 2.0.94, not in glibc 2.0.6
.\"
.SS llseek()
Prototype:
-.PP
+.P
.in +4n
.EX
.BI "loff_t llseek(int " fd ", loff_t " offset ", int " whence );
.EE
.in
-.PP
+.P
The type
.I loff_t
is a 64-bit signed type.
When users complained about data loss caused by a miscompilation of
.BR e2fsck (8),
glibc 2.1.3 added the link-time warning
-.PP
+.P
.in +4n
"the \`llseek\' function may be dangerous; use \`lseek64\' instead."
.in
-.PP
+.P
This makes this function unusable if one desires a warning-free
compilation.
-.PP
+.P
Since glibc 2.28,
.\" glibc commit 5c5c0dd747070db624c8e2c43691cec854f114ef
this function symbol is no longer available to newly linked applications.
this is the system call that is used (by the C library wrapper functions)
to implement all of the above functions.
The prototype is:
-.PP
+.P
.in +4n
.EX
.BI "int _llseek(int " fd ", off_t " offset_hi ", off_t " offset_lo ,
.BI " loff_t *" result ", int " whence );
.EE
.in
-.PP
+.P
For more details, see
.BR llseek (2).
-.PP
+.P
64-bit systems don't need an
.BR _llseek ()
system call.
.SH SYNOPSIS
.nf
.B #include <ucontext.h>
-.PP
+.P
.BI "void makecontext(ucontext_t *" ucp ", void (*" func ")(), int " argc \
", ...);"
.BI "int swapcontext(ucontext_t *restrict " oucp ,
.BR swapcontext ()
that allow user-level context switching
between multiple threads of control within a process.
-.PP
+.P
The
.BR makecontext ()
function modifies the context pointed to
for this context and assign its address to \fIucp\->uc_stack\fP,
and define a successor context and
assign its address to \fIucp\->uc_link\fP.
-.PP
+.P
When this context is later activated (using
.BR setcontext (3)
or
.IR argc .
When this function returns, the successor context is activated.
If the successor context pointer is NULL, the thread exits.
-.PP
+.P
The
.BR swapcontext ()
function saves the current context in
the stack.
Thus, it is not necessary for the user program to
worry about this direction.
-.PP
+.P
On architectures where
.I int
and pointer types are the same size
and
.BR swapcontext ().
Running the program produces the following output:
-.PP
+.P
.in +4n
.EX
.RB "$" " ./a.out"
.SH SYNOPSIS
.nf
.B #include <sys/sysmacros.h>
-.PP
+.P
.BI "dev_t makedev(unsigned int " maj ", unsigned int " min );
-.PP
+.P
.BI "unsigned int major(dev_t " dev );
.BI "unsigned int minor(dev_t " dev );
.fi
and a minor ID, identifying a specific instance of a device in that class.
A device ID is represented using the type
.IR dev_t .
-.PP
+.P
Given major and minor device IDs,
.BR makedev ()
combines these to produce a device ID, returned as the function result.
This device ID can be given to
.BR mknod (2),
for example.
-.PP
+.P
The
.BR major ()
and
BSD, HP-UX, Solaris, AIX, Irix.
.\" The header location is inconsistent:
.\" Could be sys/mkdev.h, sys/sysmacros.h, or sys/types.h.
-.PP
+.P
These interfaces are defined as macros.
Since glibc 2.3.3,
they have been aliases for three GNU-specific functions:
and
.BR gnu_dev_minor ().
The latter names are exported, but the traditional names are more portable.
-.PP
+.P
Depending on the version,
glibc also exposes definitions for these macros from
.I <sys/types.h>
.SH SYNOPSIS
.nf
.B #include <malloc.h>
-.PP
+.P
.B struct mallinfo mallinfo(void);
.B struct mallinfo2 mallinfo2(void);
.fi
However, the older function,
.BR mallinfo (),
is deprecated since the type used for the fields is too small (see BUGS).
-.PP
+.P
Note that not all allocations are visible to these functions;
see BUGS and consider using
.BR malloc_info (3)
instead.
-.PP
+.P
The
.I mallinfo2
structure returned by
.BR mallinfo2 ()
is defined as follows:
-.PP
+.P
.in +4n
.EX
struct mallinfo2 {
};
.EE
.in
-.PP
+.P
The
.I mallinfo
structure returned by the deprecated
.BR mallinfo ()
function is exactly the same, except that the fields are typed as
.IR int .
-.PP
+.P
The structure fields contain the following information:
.TP 10
.I arena
MT-Unsafe init const:mallopt
T}
.TE
-.PP
+.P
.BR mallinfo ()/
.BR mallinfo2 ()
would access some global internal objects.
and
.BR malloc_info (3)
for alternatives that include information about other arenas.
-.PP
+.P
The fields of the
.I mallinfo
structure that is returned by the older
to retrieve memory allocation statistics before and after
allocating and freeing some blocks of memory.
The statistics are displayed on standard output.
-.PP
+.P
The first two command-line arguments specify the number and size of
blocks to be allocated with
.BR malloc (3).
-.PP
+.P
The remaining three arguments specify which of the allocated blocks
should be freed with
.BR free (3).
(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.
-.PP
+.P
In the following example run of the program,
1000 allocations of 100 bytes are performed,
and then every second allocated block is freed:
-.PP
+.P
.in +4n
.EX
$ \fB./a.out 1000 100 2\fP
.SH SYNOPSIS
.nf
.B #include <stdlib.h>
-.PP
+.P
.BI "void *malloc(size_t " size );
.BI "void free(void *_Nullable " ptr );
.BI "void *calloc(size_t " nmemb ", size_t " size );
.BI "void *realloc(void *_Nullable " ptr ", size_t " size );
.BI "void *reallocarray(void *_Nullable " ptr ", size_t " nmemb ", size_t " size );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR reallocarray ():
.nf
Since glibc 2.29:
.BR calloc ()
returns a unique pointer value that can later be successfully passed to
.BR free ().
-.PP
+.P
If the multiplication of
.I nmemb
and
an integer overflow would not be detected in the following call to
.BR malloc (),
with the result that an incorrectly sized block of memory would be allocated:
-.PP
+.P
.in +4n
.EX
malloc(nmemb * size);
If the new size is larger than the old size, the added memory will
.I not
be initialized.
-.PP
+.P
If
.I ptr
is NULL, then the call is equivalent to
.IR malloc(size) ,
for all values of
.IR size .
-.PP
+.P
If
.I size
is equal to zero,
is not NULL, then the call is equivalent to
.I free(ptr)
(but see "Nonportable behavior" for portability issues).
-.PP
+.P
Unless
.I ptr
is NULL, it must have been returned by an earlier call to
.I size
bytes.
It is equivalent to the call
-.PP
+.P
.in +4n
.EX
realloc(ptr, nmemb * size);
.EE
.in
-.PP
+.P
However, unlike that
.BR realloc ()
call,
.B PTRDIFF_MAX
bytes is considered an error, as an object that large
could cause later pointer subtraction to overflow.
-.PP
+.P
The
.BR free ()
function returns no value, and preserves
.IR errno .
-.PP
+.P
The
.BR realloc ()
and
.BR reallocarray ()
glibc 2.26.
OpenBSD 5.6, FreeBSD 11.0.
-.PP
+.P
.BR malloc ()
and related functions rejected sizes greater than
.B PTRDIFF_MAX
starting in glibc 2.30.
-.PP
+.P
.BR free ()
preserved
.I errno
.BR proc (5),
and the Linux kernel source file
.IR Documentation/vm/overcommit\-accounting.rst .
-.PP
+.P
Normally,
.BR malloc ()
allocates memory from the heap, and adjusts the size of the heap
resource limit;
since Linux 4.7, this limit is also enforced for allocations performed using
.BR mmap (2).
-.PP
+.P
To avoid corruption in multithreaded applications,
mutexes are used internally to protect the memory-management
data structures employed by these functions.
or
.BR mmap (2)),
and managed with its own mutexes.
-.PP
+.P
If your program uses a private memory allocator,
it should do so by replacing
.BR malloc (),
.IR errno .
Private memory allocators may also need to replace other glibc functions;
see "Replacing malloc" in the glibc manual for details.
-.PP
+.P
Crashes in memory allocators
are almost always related to heap corruption, such as overflowing
an allocated chunk or freeing the same pointer twice.
-.PP
+.P
The
.BR malloc ()
implementation is tunable via environment variables; see
and portable POSIX programs should tolerate such behavior.
See
.BR realloc (3p).
-.PP
+.P
POSIX requires memory allocators
to set
.I errno
upon failure.
However, the C standard does not require this, and applications
portable to non-POSIX platforms should not assume this.
-.PP
+.P
Portable programs should not use private memory allocators,
as POSIX and the C standard do not allow replacement of
.BR malloc (),
.BR mcheck (3),
.BR mtrace (3),
.BR posix_memalign (3)
-.PP
+.P
For details of the GNU C library implementation, see
.UR https://sourceware.org/glibc/wiki/MallocInternals
.UE .
.SH SYNOPSIS
.nf
.B #include <malloc.h>
-.PP
+.P
.B void *malloc_get_state(void);
.BI "int malloc_set_state(void *" state );
.fi
.SH DESCRIPTION
.IR Note :
these function are removed in glibc 2.25.
-.PP
+.P
The
.BR malloc_get_state ()
function records the current state of all
(It is the caller's responsibility to
.BR free (3)
this memory.)
-.PP
+.P
The
.BR malloc_set_state ()
function restores the state of all
On error (for example, memory could not be allocated for the data structure),
.BR malloc_get_state ()
returns NULL.
-.PP
+.P
On success,
.BR malloc_set_state ()
returns 0.
implementation as part of a shared library,
and the heap contents are saved/restored via some other method.
This technique is used by GNU Emacs to implement its "dumping" function.
-.PP
+.P
Hook function pointers are never saved or restored by these
functions, with two exceptions:
if malloc checking (see
.SH SYNOPSIS
.nf
.B "#include <malloc.h>"
-.PP
+.P
.BI "void *(*volatile __malloc_hook)(size_t " size ", const void *" caller );
-.PP
+.P
.BI "void *(*volatile __realloc_hook)(void *" ptr ", size_t " size ,
.BI " const void *" caller );
-.PP
+.P
.BI "void *(*volatile __memalign_hook)(size_t " alignment ", size_t " size ,
.BI " const void *" caller );
-.PP
+.P
.BI "void (*volatile __free_hook)(void *" ptr ", const void *" caller );
-.PP
+.P
.B "void (*__malloc_initialize_hook)(void);"
-.PP
+.P
.B "void (*volatile __after_morecore_hook)(void);"
.fi
.SH DESCRIPTION
You can use these hooks
to help you debug programs that use dynamic memory allocation,
for example.
-.PP
+.P
The variable
.B __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:
-.PP
+.P
.in +4n
.EX
void (*__malloc_initialize_hook)(void) = my_init_hook;
.EE
.in
-.PP
+.P
Now the function
.IR my_init_hook ()
can do the initialization of all hooks.
-.PP
+.P
The four functions pointed to by
.BR __malloc_hook ,
.BR __realloc_hook ,
that gives the address of the caller of
.BR malloc (3),
etc.
-.PP
+.P
The variable
.B __after_morecore_hook
points at a function that is called each time after
.BR calloc ().
.SH EXAMPLES
Here is a short example of how to use these variables.
-.PP
+.P
.EX
#include <stdio.h>
#include <malloc.h>
.SH SYNOPSIS
.nf
.B #include <malloc.h>
-.PP
+.P
.BI "int malloc_info(int " options ", FILE *" stream );
.fi
.SH DESCRIPTION
.IR stream .
The exported string includes information about all arenas (see
.BR malloc (3)).
-.PP
+.P
As currently implemented,
.I options
must be zero.
because the information may change over time
(according to changes in the underlying implementation).
The output XML string includes a version field.
-.PP
+.P
The
.BR open_memstream (3)
function can be used to send the output of
.BR malloc_info ()
directly into a buffer in memory, rather than to a file.
-.PP
+.P
The
.BR malloc_info ()
function is designed to address deficiencies in
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.
-.PP
+.P
The program calls
.BR 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.
-.PP
+.P
In the following example,
the command-line arguments specify the creation of one additional thread,
and both the main thread and the additional thread
After the blocks of memory have been allocated,
.BR malloc_info ()
shows the state of two allocation arenas.
-.PP
+.P
.in +4n
.EX
.RB "$ " "getconf GNU_LIBC_VERSION"
.SH SYNOPSIS
.nf
.B #include <malloc.h>
-.PP
+.P
.B void malloc_stats(void);
.fi
.SH DESCRIPTION
.SH SYNOPSIS
.nf
.B #include <malloc.h>
-.PP
+.P
.BI "int malloc_trim(size_t " pad );
.fi
.SH DESCRIPTION
or
.BR madvise (2)
with suitable arguments).
-.PP
+.P
The
.I pad
argument specifies the amount of free space to leave untrimmed
honors the
.I pad
argument; thread heaps do not.
-.PP
+.P
Since glibc 2.8 this function frees memory in all arenas and in all
chunks with whole free pages.
.\" See commit 68631c8eb92ff38d9da1ae34f6aa048539b199cc
.\" (dated 2007-12-16) which adds iteration over all
.\" arenas and frees all pages in chunks which are free.
-.PP
+.P
Before glibc 2.8 this function only freed memory at the
top of the heap in the main arena.
.SH SEE ALSO
.SH SYNOPSIS
.nf
.B #include <malloc.h>
-.PP
+.P
.BI "size_t malloc_usable_size(void *_Nullable " ptr );
.fi
.SH DESCRIPTION
.SH SYNOPSIS
.nf
.B #include <malloc.h>
-.PP
+.P
.BI "int mallopt(int " param ", int " value );
.fi
.SH DESCRIPTION
argument specifies the parameter to be modified, and
.I value
specifies the new value for that parameter.
-.PP
+.P
The following values can be specified for
.IR param :
.TP
settings take precedence.)
For security reasons,
these variables are ignored in set-user-ID and set-group-ID programs.
-.PP
+.P
The environment variables are as follows
(note the trailing underscore at the end of the name of some variables):
.TP
Specifying an invalid value for
.I param
does not generate an error.
-.PP
+.P
A calculation error within the glibc implementation means that
a call of the form:
.\" FIXME . This looks buggy:
.\" malloc requests are rounded up:
.\" (req) + SIZE_SZ + MALLOC_ALIGN_MASK) & ~MALLOC_ALIGN_MASK
.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=12129
-.PP
+.P
.in +4n
.EX
mallopt(M_MXFAST, n)
.EE
.in
-.PP
+.P
does not result in fastbins being employed for all allocations of size up to
.IR n .
To ensure desired results,
.I k
is an integer.
.\" Bins are multiples of 2 * sizeof(size_t) + sizeof(size_t)
-.PP
+.P
If
.BR mallopt ()
is used to set
parameter.
The program then allocates a block of memory,
and frees it twice (an error).
-.PP
+.P
The following shell session shows what happens when we run this program
under glibc, with the default value for
.BR M_CHECK_ACTION :
-.PP
+.P
.in +4n
.EX
$ \fB./a.out\fP
Aborted (core dumped)
.EE
.in
-.PP
+.P
The following runs show the results when employing other values for
.BR M_CHECK_ACTION :
-.PP
+.P
.in +4n
.EX
$ \fB./a.out 1\fP # Diagnose error and continue
main(): returned from second free() call
.EE
.in
-.PP
+.P
The next run shows how to set the same parameter using the
.B MALLOC_CHECK_
environment variable:
-.PP
+.P
.in +4n
.EX
$ \fBMALLOC_CHECK_=1 ./a.out\fP
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "[[deprecated]] int matherr(struct exception *" exc );
-.PP
+.P
.B [[deprecated]] extern _LIB_VERSION_TYPE _LIB_VERSION;
.fi
.SH DESCRIPTION
This page documents the
.BR matherr ()
mechanism as an aid for maintaining and porting older applications.
-.PP
+.P
The System V Interface Definition (SVID) specifies that various
math functions should invoke a function called
.BR matherr ()
.BR matherr ()
returns, the system then returns to the math function,
which in turn returns to the caller.
-.PP
+.P
To employ
.BR matherr (),
the programmer must define the
.B _SVID_
to the external variable
.BR _LIB_VERSION .
-.PP
+.P
The system provides a default version of
.BR matherr ().
This version does nothing, and returns zero
The function is invoked with one argument, a pointer to an
.I exception
structure, defined as follows:
-.PP
+.P
.in +4n
.EX
struct exception {
}
.EE
.in
-.PP
+.P
The
.I type
field has one of the following values:
Partial loss of significance.
This value is unused on glibc
(and many other systems).
-.PP
+.P
The
.I arg1
and
fields are the arguments supplied to the function
.RI ( arg2
is undefined for functions that take only one argument).
-.PP
+.P
The
.I retval
field specifies the return value that the math
The programmer-defined
.BR matherr ()
can modify this field to change the return value of the math function.
-.PP
+.P
If the
.BR matherr ()
function returns zero, then the system sets
.I errno
as described above, and may print an error message on standard error
(see below).
-.PP
+.P
If the
.BR matherr ()
function returns a nonzero value, then the system does not set
.BR matherr ().
The "Result" column is the default return value assigned to
.IR exc\->retval .
-.PP
+.P
The "Msg?" and "errno" columns describe the default behavior if
.BR matherr ()
returns zero.
If the "Msg?" columns contains "y",
then the system prints an error message on standard error.
-.PP
+.P
The table uses the following notations and abbreviations:
-.PP
+.P
.RS
.TS
l l.
then it specifies an alternative return value that
.BR matherr ()
should assign as the return value of the math function.
-.PP
+.P
The following example run, where
.BR log (3)
is given an argument of 0.0, does not use
.BR matherr ():
-.PP
+.P
.in +4n
.EX
.RB "$" " ./a.out 0.0"
x=\-inf
.EE
.in
-.PP
+.P
In the following run,
.BR matherr ()
is called, and returns 0:
-.PP
+.P
.in +4n
.EX
.RB "$" " ./a.out 0.0 0"
x=\-340282346638528859811704183484516925440.000000
.EE
.in
-.PP
+.P
The message "log: SING error" was printed by the C library.
-.PP
+.P
In the following run,
.BR matherr ()
is called, and returns a nonzero value:
-.PP
+.P
.in +4n
.EX
.RB "$" " ./a.out 0.0 1"
x=\-340282346638528859811704183484516925440.000000
.EE
.in
-.PP
+.P
In this case, the C library did not print a message, and
.I errno
was not set.
-.PP
+.P
In the following run,
.BR matherr ()
is called, changes the return value of the math function,
and returns a nonzero value:
-.PP
+.P
.in +4n
.EX
.RB "$" " ./a.out 0.0 1 12345.0"
.SH SYNOPSIS
.nf
.B #include <stdlib.h>
-.PP
+.P
.BI "int mblen(const char " s [. n "], size_t " n );
.fi
.SH DESCRIPTION
character, it returns the number of bytes that were consumed from
.IR s .
If the multibyte character is the null wide character, it returns 0.
-.PP
+.P
If the
.I n
bytes starting at
is greater than or equal to
.IR MB_CUR_MAX ,
if the multibyte string contains redundant shift sequences.
-.PP
+.P
If the multibyte string starting at
.I s
contains an invalid multibyte
sequence before the next complete character,
.BR mblen ()
also returns \-1.
-.PP
+.P
If
.I s
is NULL, the
.SH SYNOPSIS
.nf
.B #include <wchar.h>
-.PP
+.P
.BI "size_t mbrlen(const char " s "[restrict ." n "], size_t " n ,
.BI " mbstate_t *restrict " ps );
.fi
shift state
.I *ps
to the initial state and returns 0.
-.PP
+.P
If the
.I n
bytes starting at
.IR MB_CUR_MAX ,
if the multibyte string contains redundant shift
sequences.
-.PP
+.P
If the multibyte string starting at
.I s
contains an invalid multibyte
the effects on
.I *ps
are undefined.
-.PP
+.P
If
.I ps
is NULL, a static anonymous state known only to the
.SH SYNOPSIS
.nf
.B #include <wchar.h>
-.PP
+.P
.BI "size_t mbrtowc(wchar_t *restrict " pwc ", const char " s "[restrict ." n ],
.BI " size_t " n ", mbstate_t *restrict " ps );
.fi
state
.I *ps
to the initial state and returns 0.
-.PP
+.P
If the
.I n
bytes starting at
.IR MB_CUR_MAX ,
if the multibyte string contains redundant shift
sequences.
-.PP
+.P
If the multibyte string starting at
.I s
contains an invalid multibyte
the effects on
.I *ps
are undefined.
-.PP
+.P
A different case is when
.I s
is not NULL but
.BR mbrtowc ()
function behaves as above, except that it does not
store the converted wide character in memory.
-.PP
+.P
A third case is when
.I s
is NULL.
puts
.I *ps
in the initial state and returns 0.
-.PP
+.P
In all of the above cases, if
.I ps
is NULL, a static anonymous
.I a
can be initialized to the initial state
by zeroing it, for example using
-.PP
+.P
.in +4n
.EX
memset(&a, 0, sizeof(a));
.SH SYNOPSIS
.nf
.B #include <wchar.h>
-.PP
+.P
.BI "int mbsinit(const mbstate_t *" ps );
.fi
.SH DESCRIPTION
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.
-.PP
+.P
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
.IR mbstate_t ,
and they both have the same
representation for an initial state.
-.PP
+.P
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
.BR mbrtowc (3)
do
produce non-initial states when interrupted in the middle of a character.
-.PP
+.P
One possible way to create an
.I mbstate_t
in initial state is to set it to zero:
-.PP
+.P
.in +4n
.EX
mbstate_t state;
memset(&state, 0, sizeof(state));
.EE
.in
-.PP
+.P
On Linux, the following works as well, but might generate compiler warnings:
-.PP
+.P
.in +4n
.EX
mbstate_t state = { 0 };
.EE
.in
-.PP
+.P
The function
.BR mbsinit ()
tests whether
.SH SYNOPSIS
.nf
.B #include <wchar.h>
-.PP
+.P
.BI "size_t mbsnrtowcs(wchar_t " dest "[restrict ." len "], const char **restrict " src ,
.BI " size_t " nms ", size_t " len \
", mbstate_t *restrict " ps );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR mbsnrtowcs ():
.nf
Since glibc 2.10:
is limited to at most
.I nms
bytes.
-.PP
+.P
If
.I dest
is not NULL, the
.IR dest ,
excluding the terminating null wide character,
is returned.
-.PP
+.P
According to POSIX.1,
if the input buffer ends with an incomplete character,
it is unspecified whether conversion stops at the end of
the previous character (if any), or at the end of the input buffer.
The glibc implementation adopts the former behavior.
-.PP
+.P
If
.I dest
is NULL,
above, except that the converted wide characters
are not written out to memory,
and that no destination length limit exists.
-.PP
+.P
In both of the above cases, if
.I ps
is NULL, a static anonymous
state known only to the
.BR mbsnrtowcs ()
function is used instead.
-.PP
+.P
The programmer must ensure that there is room for at least
.I len
wide
.B LC_CTYPE
category of the
current locale.
-.PP
+.P
Passing NULL as
.I ps
is not multithread safe.
.SH SYNOPSIS
.nf
.B #include <wchar.h>
-.PP
+.P
.BI "size_t mbsrtowcs(wchar_t " dest "[restrict ." len "], const char **restrict " src ,
.BI " size_t " len ", mbstate_t *restrict " ps );
.fi
characters written to
.IR dest ,
excluding the terminating null wide character, is returned.
-.PP
+.P
If
.I dest
is NULL,
and the conversion proceeds as above,
except that the converted wide characters are not written out to memory,
and that no length limit exists.
-.PP
+.P
In both of the above cases,
if
.I ps
state known only to the
.BR mbsrtowcs ()
function is used instead.
-.PP
+.P
The programmer must ensure that there is room for at least
.I len
wide
.B LC_CTYPE
category of the
current locale.
-.PP
+.P
Passing NULL as
.I ps
is not multithread safe.
.SH SYNOPSIS
.nf
.B #include <stdlib.h>
-.PP
+.P
.BI "size_t mbstowcs(wchar_t " dest "[restrict ." n "], \
const char *restrict " src ,
.BI " size_t " n );
In this case, the number of wide characters written to
.IR dest ,
excluding the terminating null wide character, is returned.
-.PP
+.P
The programmer must ensure that there is room for at least
.I n
wide
characters at
.IR dest .
-.PP
+.P
If
.I dest
is NULL,
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.
-.PP
+.P
In order to avoid the case 2 above, the programmer should make sure
.I n
is
.BR mbstowcs (),
as well as some of the wide character classification functions.
An example run is the following:
-.PP
+.P
.in +4n
.EX
$ ./t_mbstowcs de_DE.UTF\-8 Grüße!
.SH SYNOPSIS
.nf
.B #include <stdlib.h>
-.PP
+.P
.BI "int mbtowc(wchar_t *restrict " pwc ", const char " s "[restrict ." n "], \
size_t " n );
.fi
of bytes that were consumed from
.IR s ,
otherwise it returns 0.
-.PP
+.P
If the
.I n
bytes starting at
>=
.IR MB_CUR_MAX ,
if the multibyte string contains redundant shift sequences.
-.PP
+.P
A different case is when
.I s
is not NULL but
.BR mbtowc ()
function behaves as above, except that it does not
store the converted wide character in memory.
-.PP
+.P
A third case is when
.I s
is NULL.
.I s
points to a null byte,
or \-1 upon failure.
-.PP
+.P
If
.I s
is NULL, the
.SH SYNOPSIS
.nf
.B #include <mcheck.h>
-.PP
+.P
.BI "int mcheck(void (*" abortfunc ")(enum mcheck_status " mstatus ));
.BI "int mcheck_pedantic(void (*" abortfunc ")(enum mcheck_status " mstatus ));
.B void mcheck_check_all(void);
-.PP
+.P
.BI "enum mcheck_status mprobe(void *" ptr );
.fi
.SH DESCRIPTION
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.
-.PP
+.P
To be effective, the
.BR mcheck ()
function must be called before the first call to
.BR mcheck ()
(with a NULL argument)
before the first call to a memory-allocation function.
-.PP
+.P
The
.BR mcheck_pedantic ()
function is similar to
but performs checks on all allocated blocks whenever
one of the memory-allocation functions is called.
This can be very slow!
-.PP
+.P
The
.BR mcheck_check_all ()
function causes an immediate check on all allocated blocks.
This call is effective only if
.BR mcheck ()
is called beforehand.
-.PP
+.P
If the system detects an inconsistency in the heap,
the caller-supplied function pointed to by
.I abortfunc
.I stderr
and calls
.BR abort (3).
-.PP
+.P
The
.BR mprobe ()
function performs a consistency check on
.BR mprobe ()
returns
.BR MCHECK_DISABLED ).
-.PP
+.P
The following list describes the values returned by
.BR mprobe ()
or passed as the
with a NULL argument and then frees the same block of memory twice.
The following shell session demonstrates what happens
when running the program:
-.PP
+.P
.in +4n
.EX
.RB "$" " ./a.out"
.SH SYNOPSIS
.nf
.B #include <string.h>
-.PP
+.P
.BI "void *memccpy(void " dest "[restrict ." n "], const void " src "[restrict ." n ],
.BI " int " c ", size_t " n );
.fi
character
.I c
is found.
-.PP
+.P
If the memory areas overlap, the results are undefined.
.SH RETURN VALUE
The
.SH SYNOPSIS
.nf
.B #include <string.h>
-.PP
+.P
.BI "void *memchr(const void " s [. n "], int " c ", size_t " n );
.BI "void *memrchr(const void " s [. n "], int " c ", size_t " n );
-.PP
+.P
.BI "[[deprecated]] void *rawmemchr(const void *" s ", int " c );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR memrchr (),
.BR rawmemchr ():
.nf
.I s
are interpreted as
.IR "unsigned char" .
-.PP
+.P
The
.BR memrchr ()
function is like the
bytes pointed to by
.I s
instead of forward from the beginning.
-.PP
+.P
The
.BR rawmemchr ()
function is similar to
functions return a pointer
to the matching byte or NULL if the character does not occur in
the given memory area.
-.PP
+.P
The
.BR rawmemchr ()
function returns a pointer to the matching byte.
.SH SYNOPSIS
.nf
.B #include <string.h>
-.PP
+.P
.BI "int memcmp(const void " s1 [. n "], const void " s2 [. n "], size_t " n );
.fi
.SH DESCRIPTION
greater than zero if the first \fIn\fP bytes of \fIs1\fP is found,
respectively, to be less than, to match, or be greater than the first
\fIn\fP bytes of \fIs2\fP.
-.PP
+.P
For a nonzero return value, the sign is determined by the sign of
the difference between the first pair of bytes (interpreted as
.IR "unsigned char" )
.I s1
and
.IR s2 .
-.PP
+.P
If
.I n
is zero, the return value is zero.
.SH SYNOPSIS
.nf
.B #include <string.h>
-.PP
+.P
.BI "void *memcpy(void " dest "[restrict ." n "], const void " src "[restrict ." n ],
.BI " size_t " n );
.fi
.I src
to
.IR dest .
-.PP
+.P
This change revealed breakages in a number of applications that performed
copying with overlapping areas.
.\" Adobe Flash player was the highest profile example:
.nf
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <string.h>
-.PP
+.P
.BI "void *memfrob(void " s [. n "], size_t " n );
.fi
.SH DESCRIPTION
.BR memfrob ()
on the
obfuscated memory area.
-.PP
+.P
Note that this function is not a proper encryption routine as the XOR
constant is fixed, and is suitable only for hiding strings.
.SH RETURN VALUE
.nf
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <string.h>
-.PP
+.P
.BI "void *memmem(const void " haystack [. haystacklen "], size_t " haystacklen ,
.BI " const void " needle [. needlelen "], size_t " needlelen );
.fi
.SH SYNOPSIS
.nf
.B #include <string.h>
-.PP
+.P
.BI "void *memmove(void " dest [. n "], const void " src [. n "], size_t " n );
.fi
.SH DESCRIPTION
.nf
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <string.h>
-.PP
+.P
.BI "void *mempcpy(void " dest "[restrict ." n "], const void " src "[restrict ." n ],
.BI " size_t " n );
-.PP
+.P
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <wchar.h>
-.PP
+.P
.BI "wchar_t *wmempcpy(wchar_t " dest "[restrict ." n ],
.BI " const wchar_t " src "[restrict ." n ],
.BI " size_t " n );
But instead of returning the value of
.I dest
it returns a pointer to the byte following the last written byte.
-.PP
+.P
This function is useful in situations where a number of objects
shall be copied to consecutive memory positions.
-.PP
+.P
The
.BR wmempcpy ()
function is identical but takes
.SH SYNOPSIS
.nf
.B #include <string.h>
-.PP
+.P
.BI "void *memset(void " s [. n "], int " c ", size_t " n );
.fi
.SH DESCRIPTION
.SH SYNOPSIS
.nf
.B #include <stdlib.h>
-.PP
+.P
.BI "char *mkdtemp(char *" template );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR mkdtemp ():
.nf
/* Since glibc 2.19: */ _DEFAULT_SOURCE
.B EINVAL
The last six characters of \fItemplate\fP were not XXXXXX.
Now \fItemplate\fP is unchanged.
-.PP
+.P
Also see
.BR mkdir (2)
for other possible values for \fIerrno\fP.
.nf
.B #include <sys/types.h>
.B #include <sys/stat.h>
-.PP
+.P
.BI "int mkfifo(const char *" pathname ", mode_t " mode );
-.PP
+.P
.BR "#include <fcntl.h> " "/* Definition of AT_* constants */"
.B #include <sys/stat.h>
-.PP
+.P
.BI "int mkfifoat(int " dirfd ", const char *" pathname ", mode_t " mode );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR mkfifoat ():
.nf
Since glibc 2.10:
It is modified by the
process's \fBumask\fP in the usual way: the permissions of the created
file are \fB(\fP\fImode\fP\fB & \[ti]umask)\fP.
-.PP
+.P
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 filesystem by
calling
.BR mkfifo ().
-.PP
+.P
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
function operates in exactly the same way as
.BR mkfifo (),
except for the differences described here.
-.PP
+.P
If the pathname given in
.I pathname
is relative, then it is interpreted relative to the directory
the calling process, as is done by
.BR mkfifo ()
for a relative pathname).
-.PP
+.P
If
.I pathname
is relative and
is interpreted relative to the current working
directory of the calling process (like
.BR mkfifo ()).
-.PP
+.P
If
.I pathname
is absolute, then
.I dirfd
is ignored.
-.PP
+.P
See
.BR openat (2)
for an explanation of the need for
.SH SYNOPSIS
.nf
.B #include <stdlib.h>
-.PP
+.P
.BI "int mkstemp(char *" template );
.BI "int mkostemp(char *" template ", int " flags );
.BI "int mkstemps(char *" template ", int " suffixlen );
.BI "int mkostemps(char *" template ", int " suffixlen ", int " flags );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR mkstemp ():
.nf
_XOPEN_SOURCE >= 500
|| /* glibc >= 2.12: */ _POSIX_C_SOURCE >= 200809L
|| /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE
.fi
-.PP
+.P
.BR mkostemp ():
.nf
_GNU_SOURCE
.fi
-.PP
+.P
.BR mkstemps ():
.nf
/* glibc >= 2.19: */ _DEFAULT_SOURCE
|| /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE
.fi
-.PP
+.P
.BR mkostemps ():
.nf
_GNU_SOURCE
.IR template ,
creates and opens the file,
and returns an open file descriptor for the file.
-.PP
+.P
The last six characters of
.I template
must be "XXXXXX" and these are replaced with a string that makes the
Since it will be modified,
.I template
must not be a string constant, but should be declared as a character array.
-.PP
+.P
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.
.BR open (2)
.B O_EXCL
flag, guaranteeing that the caller is the process that creates the file.
-.PP
+.P
The
.BR mkostemp ()
function is like
is unnecessary, and produces errors on some
.\" Reportedly, FreeBSD
systems.
-.PP
+.P
The
.BR mkstemps ()
function is like
.IR "prefixXXXXXXsuffix" ,
and the string XXXXXX is modified as for
.BR mkstemp ().
-.PP
+.P
The
.BR mkostemps ()
function is to
characters long, or the last 6 characters before the suffix in
.I template
were not XXXXXX.
-.PP
+.P
These functions may also fail with any of the errors described for
.BR open (2).
.SH ATTRIBUTES
.TP
.BR mkostemps ()
glibc 2.11.
-.PP
+.P
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.
-.PP
+.P
More generally, the POSIX specification of
.BR mkstemp ()
does not say anything
.SH SYNOPSIS
.nf
.B #include <stdlib.h>
-.PP
+.P
.BI "char *mktemp(char *" template );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR mktemp ():
.nf
Since glibc 2.12:
.SH DESCRIPTION
.IR "Never use this function" ;
see BUGS.
-.PP
+.P
The
.BR mktemp ()
function generates a unique temporary filename
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "double modf(double " x ", double *" iptr );
.BI "float modff(float " x ", float *" iptr );
.BI "long double modfl(long double " x ", long double *" iptr );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR modff (),
.BR modfl ():
.nf
.SH RETURN VALUE
These functions return the fractional part of
.IR x .
-.PP
+.P
If
.I x
is a NaN, a NaN is returned, and
.I *iptr
is set to a NaN.
-.PP
+.P
If
.I x
is positive infinity (negative infinity), +0 (\-0) is returned, and
C11, POSIX.1-2008.
.SH HISTORY
C99, POSIX.1-2001.
-.PP
+.P
The variant returning
.I double
also conforms to
.nf
.B #include <db.h>
.B #include <mpool.h>
-.PP
+.P
.BI "MPOOL *mpool_open(DBT *" key ", int " fd ", pgno_t " pagesize \
", pgno_t " maxcache );
-.PP
+.P
.BI "void mpool_filter(MPOOL *" mp ", void (*pgin)(void *, pgno_t, void *),"
.BI " void (*" pgout ")(void *, pgno_t, void *),"
.BI " void *" pgcookie );
-.PP
+.P
.BI "void *mpool_new(MPOOL *" mp ", pgno_t *" pgnoaddr );
.BI "void *mpool_get(MPOOL *" mp ", pgno_t " pgno ", unsigned int " flags );
.BI "int mpool_put(MPOOL *" mp ", void *" pgaddr ", unsigned int " flags );
-.PP
+.P
.BI "int mpool_sync(MPOOL *" mp );
.BI "int mpool_close(MPOOL *" mp );
.fi
Probably, you are looking for the APIs provided by the
.I libdb
library instead.
-.PP
+.P
.I Mpool
is the library interface intended to provide page oriented buffer management
of files.
The buffers may be shared between processes.
-.PP
+.P
The function
.BR mpool_open ()
initializes a memory pool.
is non-NULL and matches a file already being mapped, the
.I fd
argument is ignored.
-.PP
+.P
The
.I pagesize
argument is the size, in bytes, of the pages into which the file is broken up.
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.
-.PP
+.P
The
.BR mpool_filter ()
function is intended to make transparent input and output processing of the
Both functions are called with the
.I pgcookie
pointer, the page number and a pointer to the page to being read or written.
-.PP
+.P
The function
.BR mpool_new ()
takes an
Otherwise, NULL is returned and
.I errno
is set.
-.PP
+.P
The function
.BR mpool_get ()
takes an
The
.I flags
argument is not currently used.
-.PP
+.P
The function
.BR mpool_put ()
unpins the page referenced by
.TP
.B MPOOL_DIRTY
The page has been modified and needs to be written to the backing file.
-.PP
+.P
.BR mpool_put ()
returns 0 on success and \-1 if an error occurs.
-.PP
+.P
The function
.BR mpool_sync ()
writes all modified pages associated with the
backing file.
.BR mpool_sync ()
returns 0 on success and \-1 if an error occurs.
-.PP
+.P
The
.BR mpool_close ()
function free's up any allocated memory associated with the memory pool
.I errno
for any of the errors specified for the library routine
.BR malloc (3).
-.PP
+.P
The
.BR mpool_get ()
function may fail and set
.TP 15
.B EINVAL
The requested record doesn't exist.
-.PP
+.P
The
.BR mpool_new ()
and
.BR write (2),
and
.BR malloc (3).
-.PP
+.P
The
.BR mpool_sync ()
function may fail and set
.I errno
for any of the errors specified for the library routine
.BR write (2).
-.PP
+.P
The
.BR mpool_close ()
function may fail and set
.SH SYNOPSIS
.nf
.B #include <mqueue.h>
-.PP
+.P
.BI "int mq_close(mqd_t " mqdes );
.fi
.SH DESCRIPTION
.BR mq_close ()
closes the message queue descriptor
.IR mqdes .
-.PP
+.P
If the calling process has attached a notification request (see
.BR mq_notify (3))
to this message queue via
.SH SYNOPSIS
.nf
.B #include <mqueue.h>
-.PP
+.P
.BI "int mq_getattr(mqd_t " mqdes ", struct mq_attr *" attr );
.BI "int mq_setattr(mqd_t " mqdes ", const struct mq_attr *restrict " newattr ,
.BI " struct mq_attr *restrict " oldattr );
respectively retrieve and modify attributes of the message queue
referred to by the message queue descriptor
.IR mqdes .
-.PP
+.P
.BR mq_getattr ()
returns an
.I mq_attr
structure in the buffer pointed by
.IR attr .
This structure is defined as:
-.PP
+.P
.in +4n
.EX
struct mq_attr {
};
.EE
.in
-.PP
+.P
The
.I mq_flags
field contains flags associated with the open message queue description.
.BR mq_open (3).
The only flag that can appear in this field is
.BR O_NONBLOCK .
-.PP
+.P
The
.I mq_maxmsg
and
.I /proc
files that place ceilings on the values for these fields are described in
.BR mq_overview (7).
-.PP
+.P
The
.I mq_curmsgs
field returns the number of messages currently held in the queue.
-.PP
+.P
.BR mq_setattr ()
sets message queue attributes using information supplied in the
.I mq_attr
.I attr
argument is NULL.
Here is an example run of the program:
-.PP
+.P
.in +4n
.EX
$ \fB./a.out /testq\fP
Maximum message size: 8192
.EE
.in
-.PP
+.P
Since Linux 3.5, the following
.I /proc
files (described in
.BR mq_overview (7))
can be used to control the defaults:
-.PP
+.P
.in +4n
.EX
$ \fBuname \-sr\fP
.nf
.B #include <mqueue.h>
.BR "#include <signal.h> " "/* Definition of SIGEV_* constants */"
-.PP
+.P
.BI "int mq_notify(mqd_t " mqdes ", const struct sigevent *" sevp );
.fi
.SH DESCRIPTION
an asynchronous notification when a new message arrives on
the empty message queue referred to by the message queue descriptor
.IR mqdes .
-.PP
+.P
The
.I sevp
argument is a pointer to a
structure.
For the definition and general details of this structure, see
.BR sigevent (3type).
-.PP
+.P
If
.I sevp
is a non-null pointer, then
See
.BR sigevent (3type)
for details.
-.PP
+.P
Only one process can be registered to receive notification
from a message queue.
-.PP
+.P
If
.I 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.
-.PP
+.P
Message notification occurs only when a new message arrives and
the queue was previously empty.
If the queue was not empty at the time
.BR mq_notify ()
was called, then a notification will occur only after
the queue is emptied and a new message arrives.
-.PP
+.P
If another process or thread is waiting to read a message
from an empty queue using
.BR mq_receive (3),
the message is delivered to the process or thread calling
.BR mq_receive (3),
and the message notification registration remains in effect.
-.PP
+.P
Notification occurs once: after a notification is delivered,
the notification registration is removed,
and another process can register for message notification.
.TP
.B ENOMEM
Insufficient memory.
-.PP
+.P
POSIX.1-2008 says that an implementation
.I may
generate an
.BR "#include <fcntl.h>" " /* For O_* constants */"
.BR "#include <sys/stat.h>" " /* For mode constants */"
.B #include <mqueue.h>
-.PP
+.P
.BI "mqd_t mq_open(const char *" name ", int " oflag );
.BI "mqd_t mq_open(const char *" name ", int " oflag ", mode_t " mode ,
.BI " struct mq_attr *" attr );
.IR name ,
see
.BR mq_overview (7).
-.PP
+.P
The
.I oflag
argument specifies flags that control the operation of the call.
.TP
.B O_RDWR
Open the queue to both send and receive messages.
-.PP
+.P
Zero or more of the following flags can additionally be
.IR OR ed
in
.BR mq_send (3)
would normally block, these functions instead fail with the error
.BR EAGAIN .
-.PP
+.P
If
.B O_CREAT
is specified in
(Symbolic definitions for the permissions bits can be obtained by including
.IR <sys/stat.h> .)
The permissions settings are masked against the process umask.
-.PP
+.P
The fields of the
.I struct mq_attr
pointed to
specify the maximum number of messages and
the maximum size of messages that the queue will allow.
This structure is defined as follows:
-.PP
+.P
.in +4n
.EX
struct mq_attr {
};
.EE
.in
-.PP
+.P
Only the
.I mq_maxmsg
and
fields are employed when calling
.BR mq_open ();
the values in the remaining fields are ignored.
-.PP
+.P
If
.I attr
is NULL, then the queue is created with implementation-defined
.SH SYNOPSIS
.nf
.B #include <mqueue.h>
-.PP
+.P
.BI "ssize_t mq_receive(mqd_t " mqdes ", char " msg_ptr [. msg_len ],
.BI " size_t " msg_len ", unsigned int *" msg_prio );
-.PP
+.P
.B #include <time.h>
.B #include <mqueue.h>
-.PP
+.P
.BI "ssize_t mq_timedreceive(mqd_t " mqdes ", \
char *restrict " msg_ptr [. msg_len ],
.BI " size_t " msg_len ", unsigned int *restrict " msg_prio ,
.BI " const struct timespec *restrict " abs_timeout );
.fi
-.PP
+.P
.ad l
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR mq_timedreceive ():
.nf
_POSIX_C_SOURCE >= 200112L
.I msg_prio
is not NULL, then the buffer to which it points is used
to return the priority associated with the received message.
-.PP
+.P
If the queue is empty, then, by default,
.BR mq_receive ()
blocks until a message becomes available,
flag is enabled for the message queue description,
then the call instead fails immediately with the error
.BR EAGAIN .
-.PP
+.P
.BR mq_timedreceive ()
behaves just like
.BR mq_receive (),
specified in a
.BR timespec (3)
structure.
-.PP
+.P
If no message is available,
and the timeout has already expired by the time of the call,
.BR mq_timedreceive ()
.SH SYNOPSIS
.nf
.B #include <mqueue.h>
-.PP
+.P
.BI "int mq_send(mqd_t " mqdes ", const char " msg_ptr [. msg_len ],
.BI " size_t " msg_len ", unsigned int " msg_prio );
-.PP
+.P
.B #include <time.h>
.B #include <mqueue.h>
-.PP
+.P
.BI "int mq_timedsend(mqd_t " mqdes ", const char " msg_ptr [. msg_len ],
.BI " size_t " msg_len ", unsigned int " msg_prio ,
.BI " const struct timespec *" abs_timeout );
.fi
-.PP
+.P
.ad l
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR mq_timedsend ():
.nf
_POSIX_C_SOURCE >= 200112L
.I mq_msgsize
attribute.
Zero-length messages are allowed.
-.PP
+.P
The
.I msg_prio
argument is a nonnegative integer that specifies the priority
See
.BR mq_overview (7)
for details on the range for the message priority.
-.PP
+.P
If the message queue is already full
(i.e., the number of messages on the queue equals the queue's
.I mq_maxmsg
flag is enabled for the message queue description,
then the call instead fails immediately with the error
.BR EAGAIN .
-.PP
+.P
.BR mq_timedsend ()
behaves just like
.BR mq_send (),
specified in a
.BR timespec (3)
structure.
-.PP
+.P
If the message queue is full,
and the timeout has already expired by the time of the call,
.BR mq_timedsend ()
.SH SYNOPSIS
.nf
.B #include <mqueue.h>
-.PP
+.P
.BI "int mq_unlink(const char *" name );
.fi
.SH DESCRIPTION
.SH SYNOPSIS
.nf
.B "#include <mcheck.h>"
-.PP
+.P
.B "void mtrace(void);"
.B "void muntrace(void);"
.fi
and deallocation.
The tracing information can be used to discover memory leaks and
attempts to free nonallocated memory in a program.
-.PP
+.P
The
.BR muntrace ()
function disables the hook functions installed by
.BR mtrace (),
.BR muntrace ()
does nothing.
-.PP
+.P
When
.BR mtrace ()
is called, it checks the value of the environment variable
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.
-.PP
+.P
If
.B MALLOC_TRACE
is not set,
is called once at the start of execution of a program, and
.BR muntrace ()
is never called.
-.PP
+.P
The tracing output produced after a call to
.BR mtrace ()
is textual, but not designed to be human readable.
For best results,
the traced program should be compiled with debugging enabled,
so that line-number information is recorded in the executable.
-.PP
+.P
The tracing performed by
.BR mtrace ()
incurs a performance penalty (if
.BR mtrace (1)
command in a program that has memory leaks at two different locations.
The demonstration uses the following program:
-.PP
+.P
.in +4n
.RB "$ " "cat t_mtrace.c"
.\" [[memory leak]] SRC BEGIN (t_mtrace.c)
.EE
.\" SRC END
.in
-.PP
+.P
When we run the program as follows, we see that
.BR mtrace ()
diagnosed memory leaks at two different locations in the program:
-.PP
+.P
.in +4n
.EX
.RB "$ " "cc \-g t_mtrace.c \-o t_mtrace"
0x084c9448 0x100 at /home/cecilia/t_mtrace.c:16
.EE
.in
-.PP
+.P
The first two messages about unfreed memory correspond to the two
.BR malloc (3)
calls inside the
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "double nan(const char *" tagp );
.BI "float nanf(const char *" tagp );
.BI "long double nanl(const char *" tagp );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR nan (),
.BR nanf (),
.BR nanl ():
of a quiet NaN.
If the implementation does not support
quiet NaNs, these functions return zero.
-.PP
+.P
The call
.I nan("char\-sequence")
is equivalent to:
-.PP
+.P
.in +4n
.EX
strtod("NAN(char\-sequence)", NULL);
.EE
.in
-.PP
+.P
Similarly, calls to
.BR nanf ()
and
.BR strtof (3)
and
.BR strtold (3).
-.PP
+.P
The argument
.I tagp
is used in an unspecified manner.
.TE
.SH STANDARDS
C11, POSIX.1-2008.
-.PP
+.P
See also IEC 559 and the appendix with
recommended functions in IEEE 754/IEEE 854.
.SH HISTORY
.nf
.B #include <asm/types.h>
.B #include <linux/netlink.h>
-.PP
+.P
.BI "int NLMSG_ALIGN(size_t " len );
.BI "int NLMSG_LENGTH(size_t " len );
.BI "int NLMSG_SPACE(size_t " len );
.SH SYNOPSIS
.nf
.B #include <locale.h>
-.PP
+.P
.BI "locale_t newlocale(int " category_mask ", const char *" locale ,
.BI " locale_t " base );
.BI "void freelocale(locale_t " locobj );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR newlocale (),
.BR freelocale ():
.nf
If the call fails, the contents of
.I base
remain valid and unchanged.
-.PP
+.P
If
.I base
is the special locale object
.I (locale_t)\ 0
and is not a valid locale object handle,
the behavior is undefined.
-.PP
+.P
The
.I category_mask
argument is a bit mask that specifies the locale categories
Alternatively, the mask can be specified as
.BR LC_ALL_MASK ,
which is equivalent to ORing all of the preceding constants.
-.PP
+.P
For each category specified in
.IR category_mask ,
the locale data from
data for all categories not specified in
.I category_mask
is taken from the default ("POSIX") locale.
-.PP
+.P
The following preset values of
.I locale
are defined for all categories that can be specified in
is
.B LC_GLOBAL_LOCALE
or is not valid locale object handle, the results are undefined.
-.PP
+.P
Once a locale object has been freed,
the program should make no further use of it.
.SH RETURN VALUE
if it is present, it is used to set the
.B LC_TIME
category of the locale object.
-.PP
+.P
Having created and initialized the locale object,
the program then applies it using
.BR uselocale (3),
The format and language of the output will be affected by the
.B LC_TIME
setting.
-.PP
+.P
The following shell sessions show some example runs of this program.
-.PP
+.P
Set the
.B LC_NUMERIC
category to
.I fr_FR
(French):
-.PP
+.P
.in +4n
.EX
$ \fB./a.out fr_FR\fP
Fri Mar 7 00:25:08 2014
.EE
.in
-.PP
+.P
Set the
.B LC_NUMERIC
category to
category to
.I it_IT
(Italian):
-.PP
+.P
.in +4n
.EX
$ \fB./a.out fr_FR it_IT\fP
ven 07 mar 2014 00:26:01 CET
.EE
.in
-.PP
+.P
Specify the
.B LC_TIME
setting as an empty string,
(which, here, specify
.IR mi_NZ ,
New Zealand Māori):
-.PP
+.P
.in +4n
.EX
$ LC_ALL=mi_NZ ./a.out fr_FR ""
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "double nextafter(double " x ", double " y );
.BI "float nextafterf(float " x ", float " y );
.BI "long double nextafterl(long double " x ", long double " y );
-.PP
+.P
.BI "double nexttoward(double " x ", long double " y );
.BI "float nexttowardf(float " x ", long double " y );
.BI "long double nexttowardl(long double " x ", long double " y );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR nextafter ():
.nf
_ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
|| /* Since glibc 2.19: */ _DEFAULT_SOURCE
|| /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
.fi
-.PP
+.P
.BR nextafterf (),
.BR nextafterl ():
.nf
|| /* Since glibc 2.19: */ _DEFAULT_SOURCE
|| /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
.fi
-.PP
+.P
.BR nexttoward (),
.BR nexttowardf (),
.BR nexttowardl ():
.IR x ,
these functions will return the largest representable number less than
.IR x .
-.PP
+.P
If
.I x
equals
.IR y ,
the functions return
.IR y .
-.PP
+.P
The
.BR nexttoward (),
.BR nexttowardf (),
.I x
in the direction of
.IR y .
-.PP
+.P
If
.I x
equals
(cast to the same type as
.IR x )
is returned.
-.PP
+.P
If
.I x
or
.I y
is a NaN,
a NaN is returned.
-.PP
+.P
If
.I x
is finite,
or
.BR HUGE_VALL ,
respectively, with the correct mathematical sign.
-.PP
+.P
If
.I x
is not equal to
.BR math_error (7)
for information on how to determine whether an error has occurred
when calling these functions.
-.PP
+.P
The following errors can occur:
.TP
Range error: result overflow
.TE
.SH STANDARDS
C11, POSIX.1-2008.
-.PP
+.P
This function is defined in IEC 559 (and the appendix with
recommended functions in IEEE 754/IEEE 854).
.SH HISTORY
floating-point
.RB ( FE_UNDERFLOW )
exception when an underflow occurs.
-.PP
+.P
Before glibc 2.23
.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6799
these functions did not set
.nf
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <math.h>
-.PP
+.P
.BI "double nextup(double " x );
.BI "float nextupf(float " x );
.BI "long double nextupl(long double " x );
-.PP
+.P
.BI "double nextdown(double " x );
.BI "float nextdownf(float " x );
.BI "long double nextdownl(long double " x );
.BR nextupl ()
functions return the next representable floating-point number greater than
.IR x .
-.PP
+.P
If
.I x
is the smallest representable negative number in the corresponding type,
.I x
is 0, the returned value is the smallest representable positive number
of the corresponding type.
-.PP
+.P
If
.I x
is positive infinity, the returned value is positive infinity.
is negative infinity,
the returned value is the largest representable finite negative number
of the corresponding type.
-.PP
+.P
If
.I x
is Nan,
the returned value is NaN.
-.PP
+.P
The value returned by
.I nextdown(x)
is
.SH SYNOPSIS
.nf
.B #include <langinfo.h>
-.PP
+.P
.BI "char *nl_langinfo(nl_item " item );
.BI "char *nl_langinfo_l(nl_item " item ", locale_t " locale );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR nl_langinfo_l ():
.nf
Since glibc 2.24:
.BR newlocale (3).
Individual and additional elements of the locale categories can
be queried.
-.PP
+.P
Examples for the locale elements that can be specified in \fIitem\fP
using the constants defined in \fI<langinfo.h>\fP are:
.TP
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.
-.PP
+.P
The above list covers just some examples of items that can be requested.
For a more detailed list, consult
.IR "The GNU C Library Reference Manual" .
is the value corresponding to
.I item
in the specified locale.
-.PP
+.P
If no locale has been selected by
.BR setlocale (3)
for the appropriate category,
specifies a locale where
.I langinfo
data is not defined.
-.PP
+.P
If \fIitem\fP is not valid, a pointer to an empty string is returned.
-.PP
+.P
The pointer returned by these functions may point to static data that
may be overwritten, or the pointer itself may be invalidated,
by a subsequent call to
.BR freelocale (3)
or
.BR newlocale (3).
-.PP
+.P
POSIX specifies that the application may not modify
the string returned by these functions.
.SH ATTRIBUTES
The following program sets the character type and the numeric locale
according to the environment and queries the terminal character set and
the radix character.
-.PP
+.P
.\" SRC BEGIN (nl_langinfo.c)
.EX
#include <langinfo.h>
.BR setlocale (3),
.BR charsets (7),
.BR locale (7)
-.PP
+.P
The GNU C Library Reference Manual
.SH SYNOPSIS
.nf
.B #include <sys/timex.h>
-.PP
+.P
.BI "int ntp_gettime(struct ntptimeval *" ntv );
.BI "int ntp_gettimex(struct ntptimeval *" ntv );
.fi
Both of these APIs return information to the caller via the
.I ntv
argument, a structure of the following type:
-.PP
+.P
.in +4n
.EX
struct ntptimeval {
};
.EE
.in
-.PP
+.P
The fields of this structure are as follows:
.TP
.I time
.TP
.I tai
TAI (Atomic International Time) offset.
-.PP
+.P
.BR ntp_gettime ()
returns an
.I ntptimeval
and
.I esterror
fields are filled in.
-.PP
+.P
.BR ntp_gettimex ()
performs the same task as
.BR ntp_gettime (),
.BR adjtimex (2),
.BR ntp_adjtime (3),
.BR time (7)
-.PP
+.P
.ad l
.UR http://www.slac.stanford.edu/comp/unix/\:package/\:rtems/\:src/\:ssrlApps/\:ntpNanoclock/\:api.htm
NTP "Kernel Application Program Interface"
.SH SYNOPSIS
.nf
.B #include <stddef.h>
-.PP
+.P
.BI "size_t offsetof(" type ", " member );
.fi
.SH DESCRIPTION
.I member
from the start of the structure
.IR type .
-.PP
+.P
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.
-.PP
+.P
A compiler error will result if
.I member
is not aligned to a byte boundary
On a Linux/i386 system, when compiled using the default
.BR gcc (1)
options, the program below produces the following output:
-.PP
+.P
.in +4n
.EX
.RB "$" " ./a.out"
.SH SYNOPSIS
.nf
.B #include <stdlib.h>
-.PP
+.P
.BI "int on_exit(void (*" function ")(int, void *), void *" arg );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR on_exit ():
.nf
Since glibc 2.19:
.I arg
argument from
.BR on_exit ().
-.PP
+.P
The same function may be registered multiple times:
it is called once for each registration.
-.PP
+.P
When a child process is created via
.BR fork (2),
it inherits copies of its parent's registrations.
.SH SYNOPSIS
.nf
.B #include <stdio.h>
-.PP
+.P
.BI "FILE *open_memstream(char **" ptr ", size_t *" sizeloc );
-.PP
+.P
.B #include <wchar.h>
-.PP
+.P
.BI "FILE *open_wmemstream(wchar_t **" ptr ", size_t *" sizeloc );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR open_memstream (),
.BR open_wmemstream ():
.nf
After closing the stream, the caller should
.BR free (3)
this buffer.
-.PP
+.P
The locations pointed to by
.I ptr
and
performs no further output on the stream.
If further output is performed, then the stream
must again be flushed before trying to access these values.
-.PP
+.P
A null byte is maintained at the end of the buffer.
This byte is
.I not
included in the size value stored at
.IR sizeloc .
-.PP
+.P
The stream maintains the notion of a current position,
which is initially zero (the start of the buffer).
Each write operation implicitly adjusts the buffer position.
Moving the buffer position past the end
of the data already written fills the intervening space with
null characters.
-.PP
+.P
The
.BR open_wmemstream ()
is similar to
.nf
.B #include <sys/types.h>
.B #include <dirent.h>
-.PP
+.P
.BI "DIR *opendir(const char *" name );
.BI "DIR *fdopendir(int " fd );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR fdopendir ():
.nf
Since glibc 2.10:
function opens a directory stream corresponding to the
directory \fIname\fP, and returns a pointer to the directory stream.
The stream is positioned at the first entry in the directory.
-.PP
+.P
The
.BR fdopendir ()
function
.SH NOTES
Filename entries can be read from a directory stream using
.BR readdir (3).
-.PP
+.P
The underlying file descriptor of the directory stream can be obtained using
.BR dirfd (3).
-.PP
+.P
The
.BR opendir ()
function sets the close-on-exec flag for the file descriptor underlying the
.SH SYNOPSIS
.nf
.B #include <pty.h>
-.PP
+.P
.BI "int openpty(int *" amaster ", int *" aslave ", char *" name ,
.BI " const struct termios *" termp ,
.BI " const struct winsize *" winp );
.BI "pid_t forkpty(int *" amaster ", char *" name ,
.BI " const struct termios *" termp ,
.BI " const struct winsize *" winp );
-.PP
+.P
.B #include <utmp.h>
-.PP
+.P
.BI "int login_tty(int " fd );
.fi
.SH DESCRIPTION
.I winp
is not NULL, the window size of the slave will be set to the values in
.IR winp .
-.PP
+.P
The
.BR login_tty ()
function prepares for a login on the terminal
to be the standard input, output, and error streams of the current
process, and closing
.IR fd .
-.PP
+.P
The
.BR forkpty ()
function combines
.TP
.B ENOENT
There are no available terminals.
-.PP
+.P
.BR login_tty ()
fails if
.BR ioctl (2)
fails to set
.I fd
to the controlling terminal of the calling process.
-.PP
+.P
.BR forkpty ()
fails if either
.BR openpty ()
and
.BR forkpty ()
in glibc 2.8.
-.PP
+.P
Before glibc 2.0.92,
.BR openpty ()
returns file descriptors for a BSD pseudoterminal pair;
.SH SYNOPSIS
.nf
.B #include <stdio.h>
-.PP
+.P
.BI "void perror(const char *" s );
-.PP
+.P
.B #include <errno.h>
-.PP
+.P
.BI "int " errno "; \fR/* Not really declared this way; see errno(3) */"
-.PP
+.P
.BI "[[deprecated]] const char *const " sys_errlist [];
.BI "[[deprecated]] int " sys_nerr ;
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.IR sys_errlist ,
.IR sys_nerr :
.nf
.BR perror ()
function produces a message on standard error describing the last
error encountered during a call to a system or library function.
-.PP
+.P
First (if
.I s
is not NULL and
Then an error message corresponding to the current value of
.I errno
and a new-line.
-.PP
+.P
To be of most use, the argument string should include the name
of the function that incurred the error.
-.PP
+.P
The global error list
.IR sys_errlist "[],"
which can be indexed by
is nowadays deprecated; use
.BR strerror (3)
instead.
-.PP
+.P
When a system call fails, it usually returns \-1 and sets the
variable
.I errno
.SH SYNOPSIS
.nf
.B #include <stdio.h>
-.PP
+.P
.BI "FILE *popen(const char *" command ", const char *" type );
.BI "int pclose(FILE *" stream );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR popen (),
.BR pclose ():
.nf
.I type
argument may specify only reading or writing, not both; the resulting
stream is correspondingly read-only or write-only.
-.PP
+.P
The
.I command
argument is a pointer to a null-terminated string containing a shell
using the
.B \-c
flag; interpretation, if any, is performed by the shell.
-.PP
+.P
The
.I type
argument is a pointer to a null-terminated string which must contain
flag in
.BR open (2)
for reasons why this may be useful.
-.PP
+.P
The return value from
.BR popen ()
is a normal standard I/O stream in all respects save that it must be closed
the stream reads the command's standard output, and the command's
standard input is the same as that of the process that called
.BR popen ().
-.PP
+.P
Note that output
.BR popen ()
streams are block buffered by default.
-.PP
+.P
The
.BR pclose ()
function waits for the associated process to terminate and returns the exit
.BR pipe (2)
calls fail, or if the function cannot allocate memory,
NULL is returned.
-.PP
+.P
.BR pclose ():
on success, returns the exit status of the command; if
.\" These conditions actually give undefined results, so I commented
.BR wait4 (2)
returns an error, or some other error is detected,
\-1 is returned.
-.PP
+.P
On failure, both functions set
.I errno
to indicate the error.
.I errno
is set to
.BR EINVAL .
-.PP
+.P
If
.BR pclose ()
cannot obtain the child status,
.BR fflush (3)
before
.BR popen ().
-.PP
+.P
Failure to execute the shell is indistinguishable from the shell's failure
to execute the command, or an immediate exit of the command.
The only hint is an exit status of 127.
.SH SYNOPSIS
.nf
.B #include <fcntl.h>
-.PP
+.P
.BI "int posix_fallocate(int " fd ", off_t " offset ", off_t " len );
.fi
-.PP
+.P
.ad l
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR posix_fallocate ():
.nf
_POSIX_C_SOURCE >= 200112L
.BR posix_fallocate (),
subsequent writes to bytes in the specified range are
guaranteed not to fail because of lack of disk space.
-.PP
+.P
If the size of the file is less than
.IR offset + len ,
then the file is increased to this size;
.SH HISTORY
glibc 2.1.94.
POSIX.1-2001
-.PP
+.P
POSIX.1-2008 says that an implementation
.I shall
give the
.B O_WRONLY
flags, the function fails with the error
.BR EBADF .
-.PP
+.P
In general, the emulation is not MT-safe.
On Linux, applications may use
.BR fallocate (2)
.SH SYNOPSIS
.nf
.B #include <sys/mman.h>
-.PP
+.P
.BI "int posix_madvise(void " addr [. len "], size_t " len ", int " advice );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR posix_madvise ():
.nf
_POSIX_C_SOURCE >= 200112L
of memory accesses (or to ignore the advice altogether), but calling
.BR posix_madvise ()
shall not affect the semantics of access to memory in the specified range.
-.PP
+.P
The
.I advice
argument is one of the following:
On Linux, specifying
.I len
as 0 is permitted (as a successful no-op).
-.PP
+.P
In glibc, this function is implemented using
.BR madvise (2).
However, since glibc 2.6,
.SH SYNOPSIS
.nf
.B #include <stdlib.h>
-.PP
+.P
.BI "int posix_memalign(void **" memptr ", size_t " alignment ", size_t " size );
.BI "void *aligned_alloc(size_t " alignment ", size_t " size );
.BI "[[deprecated]] void *valloc(size_t " size );
-.PP
+.P
.B #include <malloc.h>
-.PP
+.P
.BI "[[deprecated]] void *memalign(size_t " alignment ", size_t " size );
.BI "[[deprecated]] void *pvalloc(size_t " size );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR posix_memalign ():
.nf
_POSIX_C_SOURCE >= 200112L
.fi
-.PP
+.P
.BR aligned_alloc ():
.nf
_ISOC11_SOURCE
.fi
-.PP
+.P
.BR valloc ():
.nf
Since glibc 2.12:
is either NULL
.\" glibc does this:
or a unique pointer value.
-.PP
+.P
The obsolete function
.BR memalign ()
allocates
which must be a power of two.
.\" The behavior of memalign() for size==0 is as for posix_memalign()
.\" but no standards govern this.
-.PP
+.P
The function
.BR aligned_alloc ()
is the same as
except for the added restriction that
.I alignment
must be a power of two.
-.PP
+.P
The obsolete function
.BR valloc ()
allocates
The memory address will be a multiple of the page size.
It is equivalent to
.IR "memalign(sysconf(_SC_PAGESIZE),size)" .
-.PP
+.P
The obsolete function
.BR pvalloc ()
is similar to
.BR valloc (),
but rounds the size of the allocation up to
the next multiple of the system page size.
-.PP
+.P
For all of these functions, the memory is not zeroed.
.SH RETURN VALUE
.BR aligned_alloc (),
return a pointer to the allocated memory on success.
On error, NULL is returned, and \fIerrno\fP is set
to indicate the error.
-.PP
+.P
.BR posix_memalign ()
returns zero on success, or one of the error values listed in the
next section on failure.
Everybody agrees that
.BR posix_memalign ()
is declared in \fI<stdlib.h>\fP.
-.PP
+.P
On some systems
.BR memalign ()
is declared in \fI<stdlib.h>\fP instead of \fI<malloc.h>\fP.
-.PP
+.P
According to SUSv2,
.BR valloc ()
is declared in \fI<stdlib.h>\fP.
Now one can use
.BR posix_memalign ()
to satisfy this requirement.
-.PP
+.P
.BR posix_memalign ()
verifies that
.I alignment
may not check that the
.I alignment
argument is correct.
-.PP
+.P
POSIX requires that memory obtained from
.BR posix_memalign ()
can be freed using
allows memory obtained from any of these functions to be
reclaimed with
.BR free (3).
-.PP
+.P
The glibc
.BR malloc (3)
always returns 8-byte aligned memory addresses, so these functions are
.nf
.B #include <stdlib.h>
.B #include <fcntl.h>
-.PP
+.P
.BI "int posix_openpt(int " flags ");"
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR posix_openpt ():
.nf
_XOPEN_SOURCE >= 600
.BR posix_openpt ()
function opens an unused pseudoterminal master device, returning a
file descriptor that can be used to refer to that device.
-.PP
+.P
The
.I flags
argument is a bit mask that ORs together zero or more of
.SH HISTORY
glibc 2.2.1.
POSIX.1-2001.
-.PP
+.P
It is part of the UNIX 98 pseudoterminal support (see
.BR pts (4)).
.SH NOTES
Some older UNIX implementations that support System V
(aka UNIX 98) pseudoterminals don't have this function, but it
can be easily implemented by opening the pseudoterminal multiplexor device:
-.PP
+.P
.in +4n
.EX
int
}
.EE
.in
-.PP
+.P
Calling
.BR posix_openpt ()
creates a pathname for the corresponding pseudoterminal slave device.
.SH SYNOPSIS
.nf
.B #include <spawn.h>
-.PP
+.P
.BI "int posix_spawn(pid_t *restrict " pid ", const char *restrict " path ,
.BI " const posix_spawn_file_actions_t *restrict " file_actions ,
.BI " const posix_spawnattr_t *restrict " attrp ,
.BR fork (2)
system call.
These machines are generally small, embedded systems lacking MMU support.
-.PP
+.P
The
.BR posix_spawn ()
and
system calls.
In fact, they provide only a subset of the functionality
that can be achieved by using the system calls.
-.PP
+.P
The only difference between
.BR posix_spawn ()
and
with the understanding that
.BR posix_spawnp ()
differs only on the point just described.
-.PP
+.P
The remaining arguments to these two functions are as follows:
.TP
.I pid
specify the argument list and environment for the program
that is executed in the child process, as for
.BR execve (2).
-.PP
+.P
Below, the functions are described in terms of a three-step process: the
.BR fork ()
step, the
or possibly
.BR vfork (2)
(see below).
-.PP
+.P
The PID of the new child process is placed in
.IR *pid .
The
.BR posix_spawn ()
function then returns control to the parent process.
-.PP
+.P
Subsequently, the parent can use one of the system calls described in
.BR wait (2)
to check the status of the child process.
If the child fails in any of the housekeeping steps described below,
or fails to execute the desired file,
it exits with a status of 127.
-.PP
+.P
Before glibc 2.24, the child process is created using
.BR vfork (2)
instead of
.BR POSIX_SPAWN_SETPGROUP ,
or
.BR POSIX_SPAWN_RESETIDS .
-.PP
+.P
In other words,
.BR vfork (2)
is used if the caller requests it,
File descriptors with the
.B FD_CLOEXEC
flag set are closed.
-.PP
+.P
All process attributes in the child,
other than those affected by attributes specified in the
object pointed to by
.BR fork (2)
and it executed the program with
.BR execve (2).
-.PP
+.P
The process attributes actions are defined by the attributes object
pointed to by
.IR attrp .
controls the general actions that occur,
and other attributes in the object specify values
to be used during those actions.
-.PP
+.P
The effects of the flags that may be specified in
.I spawn-flags
are as follows:
of the object pointed to by
.I attrp
(but see BUGS).
-.PP
+.P
If the
.B POSIX_SPAWN_SETSCHEDPARAM
and
.\" http://austingroupbugs.net/view.php?id=1044
.\" and has been implemented since glibc 2.26
.\" commit daeb1fa2e1b33323e719015f5f546988bd4cc73b
-.PP
+.P
If
.I attrp
is NULL, then the default behaviors described above for each flag apply.
.\" .I attrp
.\" when you are done with it;
.\" however, on Linux systems this operation is a no-op.
-.PP
+.P
The
.I file_actions
argument specifies a sequence of file operations
.B FD_CLOEXEC
flag has been set.
File locks remain in place.
-.PP
+.P
If
.I file_actions
is not NULL, then it contains an ordered set of requests to
.\" closed by the earlier operations
.\" added to
.\" .I file_actions .
-.PP
+.P
If any of the housekeeping actions fails
(due to bogus values being passed or other reasons why signal handling,
process scheduling, process group ID functions,
Once the child has successfully forked and performed
all requested pre-exec steps,
the child runs the requested executable.
-.PP
+.P
The child process takes its environment from the
.I envp
argument, which is interpreted as if it had been passed to
.I *pid
are unspecified,
and these functions return an error number as described below.
-.PP
+.P
Even when these functions return a success status,
the child process may still fail for a plethora of reasons related to its
pre-\fBexec\fR() initialization.
.BR vfork (2),
or
.BR clone (2).
-.PP
+.P
In addition, these functions fail if:
.TP
.B ENOSYS
(In other words,
although these objects may be implemented as structures containing fields,
portable programs must avoid dependence on such implementation details.)
-.PP
+.P
According to POSIX, it is unspecified whether fork handlers established with
.BR pthread_atfork (3)
are called when
On older implementations,
fork handlers are called only if the child is created using
.BR fork (2).
-.PP
+.P
There is no "posix_fspawn" function (i.e., a function that is to
.BR posix_spawn ()
as
to create file actions and attributes objects.
The remaining command-line arguments are used as the executable name
and command-line arguments of the program that is executed in the child.
-.PP
+.P
In the first run, the
.BR date (1)
command is executed in the child, and the
.BR posix_spawn ()
call employs no file actions or attributes objects.
-.PP
+.P
.in +4n
.EX
$ \fB./a.out date\fP
Child status: exited, status=0
.EE
.in
-.PP
+.P
In the next run, the
.I \-c
command-line option is used to create a file actions object that closes
Consequently,
.BR date (1)
fails when trying to perform output and exits with a status of 1.
-.PP
+.P
.in +4n
.EX
$ \fB./a.out \-c date\fP
Child status: exited, status=1
.EE
.in
-.PP
+.P
In the next run, the
.I \-s
command-line option is used to create an attributes object that
is necessary
.RB ( SIGKILL
can't be blocked).
-.PP
+.P
.in +4n
.EX
$ \fB./a.out \-s sleep 60 &\fP
[1] 7637
$ PID of child: 7638
-.PP
+.P
$ \fBkill 7638\fP
$ \fBkill \-KILL 7638\fP
$ Child status: killed by signal 9
[1]+ Done ./a.out \-s sleep 60
.EE
.in
-.PP
+.P
When we try to execute a nonexistent command in the child, the
.BR exec (3)
fails and the child exits with a status of 127.
-.PP
+.P
.in +4n
.EX
$ \fB./a.out xxxxx
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "double pow(double " x ", double " y );
.BI "float powf(float " x ", float " y );
.BI "long double powl(long double " x ", long double " y );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR powf (),
.BR powl ():
.nf
.I x
to the power of
.IR y .
-.PP
+.P
If the result overflows,
a range error occurs,
.\" The range error is generated at least as far back as glibc 2.4
or
.BR HUGE_VALL ,
respectively, with the mathematically correct sign.
-.PP
+.P
If result underflows, and is not representable,
a range error occurs,
and 0.0 with the appropriate sign is returned.
.\" POSIX.1 does not specify the sign of the zero,
.\" but https://www.sourceware.org/bugzilla/show_bug.cgi?id=2678
.\" points out that the zero has the wrong sign in some cases.
-.PP
+.P
.\" pow(\(+-0, <0 [[odd]]) = HUGE_VAL*
If
.I x
is returned,
with the same sign as
.IR x .
-.PP
+.P
.\" pow(\(+-0, <0 [[!odd]]) = HUGE_VAL*
If
.I x
or
.RB + HUGE_VALL ,
is returned.
-.PP
+.P
.\" pow(\(+-0, >0 [[odd]]) = \(+-0
If
.I x
.I y
is an odd integer greater than 0,
the result is +0 (\-0).
-.PP
+.P
.\" pow(\(+-0, >0 [[!odd]]) = +0
If
.I x
.I y
greater than 0 and not an odd integer,
the result is +0.
-.PP
+.P
.\" pow(-1, \(+-INFINITY) = 1.0
If
.I x
.I y
is positive infinity or negative infinity,
the result is 1.0.
-.PP
+.P
.\" pow(+1, y) = 1.0
If
.I x
is +1, the result is 1.0 (even if
.I y
is a NaN).
-.PP
+.P
.\" pow(x, \(+-0) = 1.0
If
.I y
is 0, the result is 1.0 (even if
.I x
is a NaN).
-.PP
+.P
.\" pow(<0, y) = NaN
If
.I x
is a finite noninteger, a domain error occurs,
.\" The domain error is generated at least as far back as glibc 2.4
and a NaN is returned.
-.PP
+.P
.\" pow(|x|<1, -INFINITY) = INFINITY
If the absolute value of
.I x
.I y
is negative infinity,
the result is positive infinity.
-.PP
+.P
.\" pow(|x|>1, -INFINITY) = +0
If the absolute value of
.I x
.I y
is negative infinity,
the result is +0.
-.PP
+.P
.\" pow(|x|<1, INFINITY) = +0
If the absolute value of
.I x
.I y
is positive infinity,
the result is +0.
-.PP
+.P
.\" pow(|x|>1, INFINITY) = INFINITY
If the absolute value of
.I x
.I y
is positive infinity,
the result is positive infinity.
-.PP
+.P
.\" pow(-INFINITY, <0 [[odd]]) = -0
If
.I x
.I y
is an odd integer less than 0,
the result is \-0.
-.PP
+.P
.\" pow(-INFINITY, <0 [[!odd]]) = +0
If
.I x
.I y
less than 0 and not an odd integer,
the result is +0.
-.PP
+.P
.\" pow(-INFINITY, >0 [[odd]]) = -INFINITY
If
.I x
.I y
is an odd integer greater than 0,
the result is negative infinity.
-.PP
+.P
.\" pow(-INFINITY, >0 [[!odd]]) = INFINITY
If
.I x
.I y
greater than 0 and not an odd integer,
the result is positive infinity.
-.PP
+.P
.\" pow(INFINITY, <0) = +0
If
.I x
.I y
less than 0,
the result is +0.
-.PP
+.P
.\" pow(INFINITY, >0) = INFINITY
If
.I x
.I y
greater than 0,
the result is positive infinity.
-.PP
+.P
.\" pow(NaN, y) or pow(x, NaN) = NaN
Except as specified above, if
.I x
.BR math_error (7)
for information on how to determine whether an error has occurred
when calling these functions.
-.PP
+.P
The following errors can occur:
.TP
Domain error: \fIx\fP is negative, and \fIy\fP is a finite noninteger
C11, POSIX.1-2008.
.SH HISTORY
C99, POSIX.1-2001.
-.PP
+.P
The variant returning
.I double
also conforms to
This problem was fixed
.\" commit c3d466cba1692708a19c6ff829d0386c83a0c6e5
in glibc 2.28.
-.PP
+.P
A number of bugs
.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=3866
in the glibc implementation of
.BR pow ()
were fixed in glibc 2.16.
-.PP
+.P
In glibc 2.9 and earlier,
.\"
.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6776
.\" or possibly 2.9, I haven't found the source code change
.\" and I don't have a 2.9 system to test
glibc does the right thing.
-.PP
+.P
In glibc 2.3.2 and earlier,
.\" Actually, glibc 2.3.2 is the earliest test result I have; so yet
.\" to confirm if this error occurs only in glibc 2.3.2.
.nf
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <math.h>
-.PP
+.P
.BI "double pow10(double " x );
.BI "float pow10f(float " x );
.BI "long double pow10l(long double " x );
.SH DESCRIPTION
These functions return the value of 10 raised to the power
.IR x .
-.PP
+.P
.BR "Note well" :
These functions perform exactly the same task as the functions described in
.BR exp10 (3),
.SH SYNOPSIS
.nf
.B #include <sys/param.h>
-.PP
+.P
.BI "int powerof2(" x );
.fi
.SH DESCRIPTION
.I x
is a power of 2,
and false otherwise.
-.PP
+.P
.B 0
is considered a power of 2.
This can make sense considering wrapping of unsigned integers,
BSD.
.SH CAVEATS
The arguments may be evaluated more than once.
-.PP
+.P
Because this macro is implemented using bitwise operations,
some negative values can invoke undefined behavior.
For example,
.SH SYNOPSIS
.nf
.B #include <stdio.h>
-.PP
+.P
.BI "int printf(const char *restrict " format ", ...);"
.BI "int fprintf(FILE *restrict " stream ,
.BI " const char *restrict " format ", ...);"
.BI " const char *restrict " format ", ...);"
.BI "int snprintf(char " str "[restrict ." size "], size_t " size ,
.BI " const char *restrict " format ", ...);"
-.PP
+.P
.BI "int vprintf(const char *restrict " format ", va_list " ap );
.BI "int vfprintf(FILE *restrict " stream ,
.BI " const char *restrict " format ", va_list " ap );
.BI "int vsnprintf(char " str "[restrict ." size "], size_t " size ,
.BI " const char *restrict " format ", va_list " ap );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR snprintf (),
.BR vsnprintf ():
.nf
_XOPEN_SOURCE >= 500 || _ISOC99_SOURCE
|| /* glibc <= 2.19: */ _BSD_SOURCE
.fi
-.PP
+.P
.BR dprintf (),
.BR vdprintf ():
.nf
.BR vsnprintf ()
write to the character string
.IR str .
-.PP
+.P
The function
.BR dprintf ()
is the same as
instead of to a
.BR stdio (3)
stream.
-.PP
+.P
The functions
.BR snprintf ()
and
.I size
bytes (including the terminating null byte (\[aq]\e0\[aq])) to
.IR str .
-.PP
+.P
The functions
.BR vprintf (),
.BR vfprintf (),
is undefined after the call.
See
.BR stdarg (3).
-.PP
+.P
All of these functions write the output under the control of a
.I format
string that specifies how subsequent arguments (or arguments accessed via
the variable-length argument facilities of
.BR stdarg (3))
are converted for output.
-.PP
+.P
C99 and POSIX.1-2001 specify that the results are undefined if a call to
.BR sprintf (),
.BR snprintf (),
.I precision
and an optional
.IR "length modifier" .
-.PP
+.P
The overall syntax of a conversion specification is:
-.PP
+.P
.in +4n
.nf
%[$][flags][width][.precision][length modifier]conversion
.fi
.in
-.PP
+.P
The arguments must correspond properly (after type promotion) with the
conversion specifier.
By default, the arguments are used in the order
the position in the argument list of the desired argument, indexed starting
from 1.
Thus,
-.PP
+.P
.in +4n
.EX
printf("%*d", width, num);
.EE
.in
-.PP
+.P
and
-.PP
+.P
.in +4n
.EX
printf("%2$*1$d", width, num);
.EE
.in
-.PP
+.P
are equivalent.
The second style allows repeated references to the
same argument.
gaps in the numbers of arguments specified using \[aq]$\[aq]; for example, if
arguments 1 and 3 are specified, argument 2 must also be specified
somewhere in the format string.
-.PP
+.P
For some numeric conversions a radix character ("decimal point") or
thousands' grouping character is used.
The actual character used
The POSIX locale
uses \[aq].\[aq] as radix character, and does not have a grouping character.
Thus,
-.PP
+.P
.in +4n
.EX
printf("%\[aq].2f", 1234567.89);
.EE
.in
-.PP
+.P
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.
.SS Flag characters
A
.B +
overrides a space if both are used.
-.PP
+.P
The five flag characters above are defined in the C99 standard.
The Single UNIX Specification specifies one further flag character.
.TP
Therefore, without a prior call to
.BR setlocale (3),
no thousands' grouping characters will be printed.
-.PP
+.P
glibc 2.2 adds one further flag character.
.TP
.B I
conversion corresponds to a pointer to a
.I ptrdiff_t
argument.
-.PP
+.P
SUSv3 specifies all of the above,
except for those modifiers explicitly noted as being nonstandard extensions.
SUSv2 specified only the length modifiers
.BR Lf ,
.BR Lg ,
.BR LG ).
-.PP
+.P
As a nonstandard extension, the GNU implementations treats
.B ll
and
.SH RETURN VALUE
Upon successful return, these functions return the number of characters
printed (excluding the null byte used to end output to strings).
-.PP
+.P
The functions
.BR snprintf ()
and
.I size
or more means that the output was truncated.
(See also below under CAVEATS.)
-.PP
+.P
If an output error is encountered, a negative value is returned.
.SH ATTRIBUTES
For an explanation of the terms used in this section, see
.TQ
.BR vdprintf ()
GNU, POSIX.1-2008.
-.PP
+.P
.\" Linux libc4 knows about the five C standard flags.
.\" It knows about the length modifiers \fBh\fP, \fBl\fP, \fBL\fP,
.\" and the conversions
.\" support for \fB%D\fP disappeared.)
.\" No locale-dependent radix character,
.\" no thousands' separator, no NaN or infinity, no "%m$" and "*m$".
-.\" .PP
+.\" .P
.\" Linux libc5 knows about the five C standard flags and the \[aq] flag,
.\" locale, "%m$" and "*m$".
.\" It knows about the length modifiers \fBh\fP, \fBl\fP, \fBL\fP,
.\" .BR m ,
.\" which outputs
.\" .IR strerror(errno) .
-.\" .PP
+.\" .P
.\" glibc 2.0 adds conversion characters \fBC\fP and \fBS\fP.
-.\" .PP
+.\" .P
glibc 2.1 adds length modifiers \fBhh\fP, \fBj\fP, \fBt\fP, and \fBz\fP
and conversion characters \fBa\fP and \fBA\fP.
-.PP
+.P
glibc 2.2 adds the conversion character \fBF\fP with C99 semantics,
and the flag character \fBI\fP.
-.PP
+.P
glibc 2.35 gives a meaning to the alternate form
.RB ( # )
of the
.IR %#m .
.SH CAVEATS
Some programs imprudently rely on code such as the following
-.PP
+.P
.in +4n
.EX
sprintf(buf, "%s some further text", buf);
.EE
.in
-.PP
+.P
to append text to
.IR buf .
However, the standards explicitly note that the results are undefined
used, and the compiler options employed, calls such as the above will
.B not
produce the expected results.
-.PP
+.P
The glibc implementation of the functions
.BR snprintf ()
and
.BR asprintf (3)
and
.BR vasprintf (3)).
-.\" .PP
+.\" .P
.\" Linux libc4.[45] does not have a
.\" .BR snprintf (),
.\" but provides a libbsd that contains an
.\" Thus, the use of
.\" .BR snprintf ()
.\" with early libc4 leads to serious security problems.
-.PP
+.P
Code such as
.BI printf( foo );
often indicates a bug, since
comes from untrusted user input, it may contain \fB%n\fP, causing the
.BR printf ()
call to write to memory and creating a security hole.
-.\" .PP
+.\" .P
.\" Some floating-point conversions under early libc4
.\" caused memory leaks.
.SH EXAMPLES
To print
.I Pi
to five decimal places:
-.PP
+.P
.in +4n
.EX
#include <math.h>
fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0));
.EE
.in
-.PP
+.P
To print a date and time in the form "Sunday, July 3, 10:02",
where
.I weekday
and
.I month
are pointers to strings:
-.PP
+.P
.in +4n
.EX
#include <stdio.h>
weekday, month, day, hour, min);
.EE
.in
-.PP
+.P
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:
-.PP
+.P
.in +4n
.EX
#include <stdio.h>
weekday, month, day, hour, min);
.EE
.in
-.PP
+.P
where
.I format
depends on locale, and may permute the arguments.
With the value:
-.PP
+.P
.in +4n
.EX
"%1$s, %3$d. %2$s, %4$d:%5$.2d\en"
.EE
.in
-.PP
+.P
one might obtain "Sonntag, 3. Juli, 10:02".
-.PP
+.P
To allocate a sufficiently large string and print into it
(code correct for both glibc 2.0 and glibc 2.1):
-.PP
+.P
.EX
#include <stdio.h>
#include <stdlib.h>
return p;
}
.EE
-.PP
+.P
If truncation occurs in glibc versions prior to glibc 2.0.6,
this is treated as an error instead of being handled gracefully.
.SH SEE ALSO
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.BI "int profil(unsigned short *" buf ", size_t " bufsiz ,
.BI " size_t " offset ", unsigned int " scale );
-.PP
+.P
.fi
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR profil ():
.nf
Since glibc 2.21:
.B ITIMER_PROF
interval timers (see
.BR setitimer (2)).
-.PP
+.P
True kernel profiling provides more accurate results.
.\" Libc 4.4 contained a kernel patch providing a system call profil.
.SH SEE ALSO
.nf
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <errno.h>
-.PP
+.P
.BI "extern char *" program_invocation_name ;
.BI "extern char *" program_invocation_short_name ;
.fi
with the difference that the scope of
.I program_invocation_name
is global.
-.PP
+.P
.I 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
.IR program_invocation_name ,
with all text up to and including the final slash (/), if any, removed.
-.PP
+.P
These variables are automatically initialized by the glibc run-time
startup code.
.SH VERSIONS
.SH SYNOPSIS
.nf
.B #include <signal.h>
-.PP
+.P
.BI "void psignal(int " sig ", const char *" s );
.BI "void psiginfo(const siginfo_t *" pinfo ", const char *" s );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR psignal ():
.nf
Since glibc 2.19:
glibc 2.19 and earlier:
_BSD_SOURCE || _SVID_SOURCE
.fi
-.PP
+.P
.BR psiginfo ():
.nf
_POSIX_C_SOURCE >= 200809L
If the string \fIs\fP is NULL or empty, the colon and space are omitted.
If \fIsig\fP is invalid,
the message displayed will indicate an unknown signal.
-.PP
+.P
The
.BR psiginfo ()
function is like
.SH SYNOPSIS
.nf
.B #include <pthread.h>
-.PP
+.P
.BI "int pthread_atfork(void (*" prepare ")(void), void (*" parent ")(void),"
.BI " void (*" child ")(void));"
.fi
is called by any thread in a process.
The handlers are executed in the context of the thread that calls
.BR fork (2).
-.PP
+.P
Three kinds of handler can be registered:
.IP \[bu] 3
.I prepare
specifies a handler that is executed in the child process after
.BR fork (2)
processing completes.
-.PP
+.P
Any of the three arguments may be NULL if no handler is needed
in the corresponding phase of
.BR fork (2)
could ensure that mutexes and other process and thread state would be
restored to a consistent state.
In practice, this task is generally too difficult to be practicable.
-.PP
+.P
After a
.BR fork (2)
in a multithreaded process returns in the child,
until such time as it calls
.BR execve (2)
to execute a new program.
-.PP
+.P
POSIX.1 specifies that
.BR pthread_atfork ()
shall not fail with the error
.SH SYNOPSIS
.nf
.B #include <pthread.h>
-.PP
+.P
.BI "int pthread_attr_init(pthread_attr_t *" attr );
.BI "int pthread_attr_destroy(pthread_attr_t *" attr );
.fi
and then the object can be used in one or more
.BR pthread_create (3)
calls that create threads.
-.PP
+.P
Calling
.BR pthread_attr_init ()
on a thread attributes object that has already been initialized
results in undefined behavior.
-.PP
+.P
When a thread attributes object is no longer required,
it should be destroyed using the
.BR pthread_attr_destroy ()
function.
Destroying a thread attributes object has no effect
on threads that were created using that object.
-.PP
+.P
Once a thread attributes object has been destroyed,
it can be reinitialized using
.BR pthread_attr_init ().
.BR pthread_getattr_np (3)
function (a nonstandard GNU extension) to retrieve the thread's
attributes, and then displays those attributes.
-.PP
+.P
If the program is run with no command-line argument,
then it passes NULL as the
.I attr
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:
-.PP
+.P
.in +4n
.EX
.\" Results from glibc 2.8, SUSE 11.0; Oct 2008
Stack size = 0x201000 bytes
.EE
.in
-.PP
+.P
When we supply a stack size as a command-line argument,
the program initializes a thread attributes object,
sets various attributes in that object,
.BR pthread_create (3).
Running the program on Linux/x86-32 with the NPTL threading implementation,
we see the following:
-.PP
+.P
.in +4n
.EX
.\" Results from glibc 2.8, SUSE 11.0; Oct 2008
.nf
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <pthread.h>
-.PP
+.P
.BI "int pthread_attr_setaffinity_np(pthread_attr_t *" attr ,
.BI " size_t " cpusetsize ", const cpu_set_t *" cpuset );
.BI "int pthread_attr_getaffinity_np(const pthread_attr_t *" attr ,
This attribute determines the CPU affinity mask
of a thread created using the thread attributes object
.IR attr .
-.PP
+.P
The
.BR pthread_attr_getaffinity_np ()
function
.I attr
in the buffer pointed to by
.IR cpuset .
-.PP
+.P
The argument
.I cpusetsize
is the length (in bytes) of the buffer pointed to by
.IR cpuset .
Typically, this argument would be specified as
.IR sizeof(cpu_set_t) .
-.PP
+.P
For more details on CPU affinity masks, see
.BR sched_setaffinity (2).
For a description of a set of macros
.SH SYNOPSIS
.nf
.B #include <pthread.h>
-.PP
+.P
.BI "int pthread_attr_setdetachstate(pthread_attr_t *" attr \
", int " detachstate );
.BI "int pthread_attr_getdetachstate(const pthread_attr_t *" attr ,
the thread attributes object
.I attr
will be created in a joinable or a detached state.
-.PP
+.P
The following values may be specified in
.IR detachstate :
.TP
Threads that are created using
.I attr
will be created in a joinable state.
-.PP
+.P
The default setting of the detach state attribute in a newly initialized
thread attributes object is
.BR PTHREAD_CREATE_JOINABLE .
-.PP
+.P
The
.BR pthread_attr_getdetachstate ()
returns the detach state attribute of the thread attributes object
See
.BR pthread_create (3)
for more details on detached and joinable threads.
-.PP
+.P
A thread that is created in a joinable state should
eventually either be joined using
.BR pthread_join (3)
.BR pthread_detach (3);
see
.BR pthread_create (3).
-.PP
+.P
It is an error to specify the thread ID of
a thread that was created in a detached state
in a later call to
.SH SYNOPSIS
.nf
.B #include <pthread.h>
-.PP
+.P
.BI "int pthread_attr_setguardsize(pthread_attr_t *" attr \
", size_t " guardsize );
.BI "int pthread_attr_getguardsize(const pthread_attr_t *restrict " attr ,
.I attr
to the value specified in
.IR guardsize .
-.PP
+.P
If
.I guardsize
is greater than 0,
.I guardsize
bytes at the end of the thread's stack to act as the guard area
for the stack (but see BUGS).
-.PP
+.P
If
.I guardsize
is 0, then new threads created with
.I attr
will not have a guard area.
-.PP
+.P
The default guard size is the same as the system page size.
-.PP
+.P
If the stack address attribute has been set in
.I attr
(using
.BR mprotect (2)
to manually define a guard area at the end of the stack
that it has allocated).
-.PP
+.P
The
.BR pthread_attr_getguardsize ()
function returns the guard size attribute of the
.BR pthread_attr_getguardsize ()
returns the guard size that was set by
.BR pthread_attr_setguardsize ().)
-.PP
+.P
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.
-.PP
+.P
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.
.BR pthread_create (3)
if the guard size value is too large,
leaving no space for the actual stack.)
-.PP
+.P
The obsolete LinuxThreads implementation did the right thing,
allocating extra space at the end of the stack for the guard area.
.\" glibc includes the guardsize within the allocated stack size,
.SH SYNOPSIS
.nf
.B #include <pthread.h>
-.PP
+.P
.BI "int pthread_attr_setinheritsched(pthread_attr_t *" attr ,
.BI " int " inheritsched );
.BI "int pthread_attr_getinheritsched(const pthread_attr_t *restrict " attr ,
will inherit its scheduling attributes from the calling thread
or whether it will take them from
.IR attr .
-.PP
+.P
The following scheduling attributes are affected by the
inherit-scheduler attribute:
scheduling policy
.RB ( pthread_attr_setschedparam (3)),
and contention scope
.RB ( pthread_attr_setscope (3)).
-.PP
+.P
The following values may be specified in
.IR inheritsched :
.TP
take their scheduling attributes from the values specified
by the attributes object.
.\" FIXME Document the defaults for scheduler settings
-.PP
+.P
The default setting of the inherit-scheduler attribute in
a newly initialized thread attributes object is
.BR PTHREAD_INHERIT_SCHED .
-.PP
+.P
The
.BR pthread_attr_getinheritsched ()
returns the inherit-scheduler attribute of the thread attributes object
.B EINVAL
Invalid value in
.IR inheritsched .
-.PP
+.P
POSIX.1 also documents an optional
.B ENOTSUP
error ("attempt was made to set the attribute to an unsupported value") for
.SH SYNOPSIS
.nf
.B #include <pthread.h>
-.PP
+.P
.BI "int pthread_attr_setschedparam(pthread_attr_t *restrict " attr ,
.BI " const struct sched_param *restrict " param );
.BI "int pthread_attr_getschedparam(const pthread_attr_t *restrict " attr ,
These attributes determine the scheduling parameters of
a thread created using the thread attributes object
.IR attr .
-.PP
+.P
The
.BR pthread_attr_getschedparam ()
returns the scheduling parameter attributes of the thread attributes object
.I attr
in the buffer pointed to by
.IR param .
-.PP
+.P
Scheduling parameters are maintained in the following structure:
-.PP
+.P
.in +4n
.EX
struct sched_param {
};
.EE
.in
-.PP
+.P
As can be seen, only one scheduling parameter is supported.
For details of the permitted ranges for scheduling priorities
in each scheduling policy, see
.BR sched (7).
-.PP
+.P
In order for the parameter setting made by
.BR pthread_attr_setschedparam ()
to have effect when calling
.I param
does not make sense for the current scheduling policy of
.IR attr .
-.PP
+.P
POSIX.1 also documents an
.B ENOTSUP
error for
.SH SYNOPSIS
.nf
.B #include <pthread.h>
-.PP
+.P
.BI "int pthread_attr_setschedpolicy(pthread_attr_t *" attr ", int " policy );
.BI "int pthread_attr_getschedpolicy(const pthread_attr_t *restrict " attr ,
.BI " int *restrict " policy );
This attribute determines the scheduling policy of
a thread created using the thread attributes object
.IR attr .
-.PP
+.P
The supported values for
.I policy
are
.\" FIXME . pthread_setschedparam() places no restriction on the policy,
.\" but pthread_attr_setschedpolicy() restricts policy to RR/FIFO/OTHER
.\" http://sourceware.org/bugzilla/show_bug.cgi?id=7013
-.PP
+.P
The
.BR pthread_attr_getschedpolicy ()
returns the scheduling policy attribute of the thread attributes object
.I attr
in the buffer pointed to by
.IR policy .
-.PP
+.P
In order for the policy setting made by
.BR pthread_attr_setschedpolicy ()
to have effect when calling
.B EINVAL
Invalid value in
.IR policy .
-.PP
+.P
POSIX.1 also documents an optional
.B ENOTSUP
error ("attempt was made to set the attribute to an unsupported value") for
.SH SYNOPSIS
.nf
.B #include <pthread.h>
-.PP
+.P
.BI "int pthread_attr_setscope(pthread_attr_t *" attr ", int " scope );
.BI "int pthread_attr_getscope(const pthread_attr_t *restrict " attr ,
.BI " int *restrict " scope );
were created with the
.B PTHREAD_SCOPE_SYSTEM
contention scope.
-.PP
+.P
POSIX.1 requires that an implementation support at least one of these
contention scopes.
Linux supports
.BR PTHREAD_SCOPE_SYSTEM ,
but not
.BR PTHREAD_SCOPE_PROCESS .
-.PP
+.P
On systems that support multiple contention scopes, then,
in order for the parameter setting made by
.BR pthread_attr_setscope ()
.I attr
to
.BR PTHREAD_EXPLICIT_SCHED .
-.PP
+.P
The
.BR pthread_attr_getscope ()
function returns the contention scope attribute of the
This is the case on Linux for the obsolete LinuxThreads implementation
and the modern NPTL implementation,
which are both 1:1 threading implementations.
-.PP
+.P
POSIX.1 specifies that the default contention scope is
implementation-defined.
.SH SEE ALSO
.nf
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <pthread.h>
-.PP
+.P
.BI "int pthread_attr_setsigmask_np(pthread_attr_t *" attr ,
.BI " const sigset_t *" sigmask );
.BI "int pthread_attr_getsigmask_np(const pthread_attr_t *" attr ,
is specified as NULL, then any existing signal mask attribute in
.I attr
is unset.
-.PP
+.P
The
.BR pthread_attr_getsigmask_np ()
function returns the signal mask attribute of the thread attributes object
The
.BR pthread_attr_setsigmask_np ()
function returns 0 on success, or a nonzero error number on failure.
-.PP
+.P
the
.BR pthread_attr_getsigmask_np ()
function returns either 0 or
.B PTHREAD_ATTR_NO_SIGMASK_NP
indicates that the signal mask attribute is not set in
.IR attr .
-.PP
+.P
On error, these functions return a positive error number.
.SH ERRORS
.TP
If this attribute is not set, then a thread created using
.I attr
will inherit a copy of the creating thread's signal mask.
-.PP
+.P
For more details on signal masks, see
.BR sigprocmask (2).
For a description of a set of macros
that can be used to manipulate and inspect signal sets, see
.BR sigsetops (3).
-.PP
+.P
In the absence of
.BR pthread_attr_setsigmask_np ()
it is possible to create a thread with a desired signal mask as follows:
.BR pthread_sigmask (3).
.IP \[bu]
The creating thread restores its signal mask to the original value.
-.PP
+.P
Following the above steps,
there is no possibility for the new thread to receive a signal
before it has adjusted its signal mask to the desired value.
.SH SYNOPSIS
.nf
.B #include <pthread.h>
-.PP
+.P
.BI "int pthread_attr_setstack(pthread_attr_t *" attr ,
.BI " void " stackaddr [. stacksize ],
.BI " size_t " stacksize );
.BI " void **restrict " stackaddr ,
.BI " size_t *restrict " stacksize );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR pthread_attr_getstack (),
.BR pthread_attr_setstack ():
.nf
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
.IR attr .
-.PP
+.P
.I stackaddr
should point to the lowest addressable byte of a buffer of
.I stacksize
bytes that was allocated by the caller.
The pages of the allocated buffer should be both readable and writable.
-.PP
+.P
The
.BR pthread_attr_getstack ()
function returns the stack address and stack size attributes of the
or
.I stackaddr\~+\~stacksize
is not suitably aligned.
-.PP
+.P
POSIX.1 also documents an
.B EACCES
error if the stack area described by
(Use
.BR pthread_attr_setstacksize (3)
if an application simply requires a stack size other than the default.)
-.PP
+.P
When an application employs
.BR pthread_attr_setstack (),
it takes over the responsibility of allocating the stack.
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.
-.PP
+.P
The address specified in
.I stackaddr
should be suitably aligned:
Probably,
.I stacksize
should also be a multiple of the system page size.
-.PP
+.P
If
.I attr
is used to create multiple threads, then the caller must change the
.SH SYNOPSIS
.nf
.B #include <pthread.h>
-.PP
+.P
.B [[deprecated]]
.BI "int pthread_attr_setstackaddr(pthread_attr_t *" attr \
", void *" stackaddr );
and
.BR pthread_attr_getstack (3)
instead.
-.PP
+.P
The
.BR pthread_attr_setstackaddr ()
function sets the stack address attribute of the
This attribute specifies the location of the stack that should
be used by a thread that is created using the thread attributes object
.IR attr .
-.PP
+.P
.I stackaddr
should point to a buffer of at least
.B PTHREAD_STACK_MIN
bytes that was allocated by the caller.
The pages of the allocated buffer should be both readable and writable.
-.PP
+.P
The
.BR pthread_attr_getstackaddr ()
function returns the stack address attribute of the
.SH SYNOPSIS
.nf
.B #include <pthread.h>
-.PP
+.P
.BI "int pthread_attr_setstacksize(pthread_attr_t *" attr \
", size_t " stacksize );
.BI "int pthread_attr_getstacksize(const pthread_attr_t *restrict " attr ,
.I attr
to the value specified in
.IR stacksize .
-.PP
+.P
The stack size attribute determines the minimum size (in bytes) that
will be allocated for threads created using the thread attributes object
.IR attr .
-.PP
+.P
The
.BR pthread_attr_getstacksize ()
function returns the stack size attribute of the
The stack size is less than
.B PTHREAD_STACK_MIN
(16384) bytes.
-.PP
+.P
On some systems,
.\" e.g., MacOS
.BR pthread_attr_setstacksize ()
.SH NOTES
For details on the default stack size of new threads, see
.BR pthread_create (3).
-.PP
+.P
A thread's stack size is fixed at the time of thread creation.
Only the main thread can dynamically grow its stack.
-.PP
+.P
The
.BR pthread_attr_setstack (3)
function allows an application to set both the size and location
.SH SYNOPSIS
.nf
.B #include <pthread.h>
-.PP
+.P
.BI "int pthread_cancel(pthread_t " thread );
.fi
.SH DESCRIPTION
.I state
and
.IR type .
-.PP
+.P
A thread's cancelability state, determined by
.BR pthread_setcancelstate (3),
can be
enables cancelation.
If a thread has enabled cancelation,
then its cancelability type determines when cancelation occurs.
-.PP
+.P
A thread's cancelation type, determined by
.BR pthread_setcanceltype (3),
may be either
.IR "cancelation point" .
A list of functions that are or may be cancelation points is provided in
.BR pthreads (7).
-.PP
+.P
When a cancelation requested is acted on, the following steps occur for
.I thread
(in this order):
The thread is terminated.
(See
.BR pthread_exit (3).)
-.PP
+.P
The above steps happen asynchronously with respect to the
.BR pthread_cancel ()
call;
.BR pthread_cancel ()
merely informs the caller whether the cancelation request
was successfully queued.
-.PP
+.P
After a canceled thread has terminated,
a join with that thread using
.BR pthread_join (3)
that its exit status was
.BR PTHREAD_CANCELED .
The following shell session shows what happens when we run the program:
-.PP
+.P
.in +4n
.EX
$ ./a.out
.SH SYNOPSIS
.nf
.B #include <pthread.h>
-.PP
+.P
.BI "void pthread_cleanup_push(void (*" routine ")(void *), void *" arg );
.BI "void pthread_cleanup_pop(int " execute );
.fi
described below);
it might, for example, unlock a mutex so that
it becomes available to other threads in the process.
-.PP
+.P
The
.BR pthread_cleanup_push ()
function pushes
is later invoked, it will be given
.I arg
as its argument.
-.PP
+.P
The
.BR pthread_cleanup_pop ()
function removes the routine at the top of the stack of clean-up handlers,
and optionally executes it if
.I execute
is nonzero.
-.PP
+.P
A cancelation clean-up handler is popped from the stack
and executed in the following circumstances:
.IP \[bu] 3
with a nonzero
.I execute
argument, the top-most clean-up handler is popped and executed.
-.PP
+.P
POSIX.1 permits
.BR pthread_cleanup_push ()
and
and at the same lexical nesting level.
(In other words, a clean-up handler is established only
during the execution of a specified section of code.)
-.PP
+.P
Calling
.BR longjmp (3)
.RB ( siglongjmp (3))
containing \[aq]\fB{\fP\[aq] and \[aq]\fB}\fP\[aq], respectively.
This means that variables declared within the scope of
paired calls to these functions will be visible within only that scope.
-.PP
+.P
POSIX.1
.\" The text was actually added in the 2004 TC2
says that the effect of using
or sets a global variable that causes the other thread
to exit its loop and terminate normally (by doing a
.IR return ).
-.PP
+.P
In the following shell session,
the main thread sends a cancelation request to the other thread:
-.PP
+.P
.in +4n
.EX
$ \fB./a.out\fP
Thread was canceled; cnt = 0
.EE
.in
-.PP
+.P
From the above, we see that the thread was canceled,
and that the cancelation clean-up handler was called
and it reset the value of the global variable
.I cnt
to 0.
-.PP
+.P
In the next run, the main program sets a
global variable that causes other thread to terminate normally:
-.PP
+.P
.in +4n
.EX
$ \fB./a.out x\fP
Thread terminated normally; cnt = 2
.EE
.in
-.PP
+.P
From the above, we see that the clean-up handler was not executed (because
.I cleanup_pop_arg
was 0), and therefore the value of
.I cnt
was not reset.
-.PP
+.P
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
.IR cleanup_pop_arg :
-.PP
+.P
.in +4n
.EX
$ \fB./a.out x 1\fP
Thread terminated normally; cnt = 0
.EE
.in
-.PP
+.P
In the above, we see that although the thread was not canceled,
the clean-up handler was executed, because the argument given to
.BR pthread_cleanup_pop ()
.SH SYNOPSIS
.nf
.B #include <pthread.h>
-.PP
+.P
.BI "void pthread_cleanup_push_defer_np(void (*" routine ")(void *), void *" arg );
.BI "void pthread_cleanup_pop_restore_np(int " execute );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR pthread_cleanup_push_defer_np (),
.BR pthread_cleanup_pop_defer_np ():
.nf
and
.BR pthread_cleanup_pop (3),
except for the differences noted on this page.
-.PP
+.P
Like
.BR pthread_cleanup_push (3),
.BR pthread_cleanup_push_defer_np ()
this ensures that cancelation clean-up will occur
even if the thread's cancelability type was "asynchronous"
before the call.
-.PP
+.P
Like
.BR pthread_cleanup_pop (3),
.BR pthread_cleanup_pop_restore_np ()
In addition, it restores the thread's cancelability
type to its value at the time of the matching
.BR pthread_cleanup_push_defer_np ().
-.PP
+.P
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
.BR pthread_cleanup_push (3).
-.PP
+.P
This sequence of calls:
-.PP
+.P
.in +4n
.EX
pthread_cleanup_push_defer_np(routine, arg);
pthread_cleanup_pop_restore_np(execute);
.EE
.in
-.PP
+.P
is equivalent to (but shorter and more efficient than):
-.PP
+.P
.\" As far as I can see, LinuxThreads reverses the two substeps
.\" in the push and pop below.
.in +4n
.
.SH SYNOPSIS
.B #include <pthread.h>
-.PP
+.P
.BI "pthread_cond_t " cond " = PTHREAD_COND_INITIALIZER;"
-.PP
+.P
.BI "int pthread_cond_init(pthread_cond_t *" cond ", pthread_condattr_t *" cond_attr ");"
.BI "int pthread_cond_signal(pthread_cond_t *" cond ");"
.BI "int pthread_cond_broadcast(pthread_cond_t *" cond ");"
signal the condition (when the predicate becomes true),
and wait for the condition,
suspending the thread execution until another thread signals the condition.
-.PP
+.P
A condition variable must always be associated with a mutex,
to avoid the race condition where
a thread prepares to wait on a condition variable
and another thread signals the condition
just before the first thread actually waits on it.
-.PP
+.P
\fBpthread_cond_init\fP initializes the condition variable \fIcond\fP,
using the condition attributes specified in \fIcond_attr\fP,
or default attributes if \fIcond_attr\fP is \fBNULL\fP.
The LinuxThreads implementation supports no attributes for conditions,
hence the \fIcond_attr\fP parameter is actually ignored.
-.PP
+.P
Variables of type \fBpthread_cond_t\fP can also be initialized statically,
using the constant \fBPTHREAD_COND_INITIALIZER\fP.
-.PP
+.P
\fBpthread_cond_signal\fP restarts one of the threads that
are waiting on the condition variable \fIcond\fP.
If no threads are waiting on \fIcond\fP,
If several threads are waiting on \fIcond\fP,
exactly one is restarted,
but it is not specified which.
-.PP
+.P
\fBpthread_cond_broadcast\fP restarts all the threads that
are waiting on the condition variable \fIcond\fP.
Nothing happens if no threads are waiting on \fIcond\fP.
-.PP
+.P
\fBpthread_cond_wait\fP atomically unlocks the \fImutex\fP
(as per \fBpthread_unlock_mutex\fP)
and waits for the condition variable \fIcond\fP to be signaled.
Before returning to the calling thread,
\fBpthread_cond_wait\fP re-acquires \fImutex\fP
(as per \fBpthread_lock_mutex\fP).
-.PP
+.P
Unlocking the mutex and suspending on the condition variable is done atomically.
Thus,
if all threads always acquire the mutex before signaling the condition,
this guarantees that the condition cannot be signaled (and thus ignored)
between the time a thread locks the mutex
and the time it waits on the condition variable.
-.PP
+.P
\fBpthread_cond_timedwait\fP atomically unlocks \fImutex\fP
and waits on \fIcond\fP,
as \fBpthread_cond_wait\fP does,
with the same origin as \fBtime\fP(2) and \fBgettimeofday\fP(2):
an \fIabstime\fP of 0
corresponds to 00:00:00 GMT, January 1, 1970.
-.PP
+.P
\fBpthread_cond_destroy\fP destroys a condition variable,
freeing the resources it might hold.
No threads must be waiting on the condition variable
\fBpthread_cond_broadcast\fP,
and \fBpthread_cond_wait\fP
never return an error code.
-.PP
+.P
The \fBpthread_cond_timedwait\fP function returns
the following error codes on error:
.RS
\fBEINTR\fP
\fBpthread_cond_timedwait\fP was interrupted by a signal.
.RE
-.PP
+.P
The \fBpthread_cond_destroy\fP function returns
the following error code on error:
.RS
and a condition variable \fIcond\fP
that is to be signaled
whenever \fIx\fP becomes greater than \fIy\fP.
-.PP
+.P
.RS
.ft 3
.nf
pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER;
pthread_cond_t cond = PTHREAD_COND_INITIALIZER;
.ft
-.LP
+.P
.RE
.fi
-.PP
+.P
Waiting until \fIx\fP is greater than \fIy\fP is performed as follows:
-.PP
+.P
.RS
.ft 3
.nf
/* operate on x and y */
pthread_mutex_unlock(&mut);
.ft
-.LP
+.P
.RE
.fi
-.PP
+.P
Modifications on \fIx\fP and \fIy\fP
that may cause \fIx\fP to become greater than \fIy\fP
should signal the condition if needed:
-.PP
+.P
.RS
.ft 3
.nf
if (x > y) pthread_cond_broadcast(&cond);
pthread_mutex_unlock(&mut);
.ft
-.LP
+.P
.RE
.fi
-.PP
+.P
If it can be proved that at most one waiting thread needs to be waken up
(for instance,
if there are only two threads communicating through \fIx\fP and \fIy\fP),
a slightly more efficient alternative to \fBpthread_cond_broadcast\fP.
In doubt,
use \fBpthread_cond_broadcast\fP.
-.PP
+.P
To wait for \fIx\fP to become greater than \fIy\fP
with a timeout of 5 seconds,
do:
-.PP
+.P
.RS
.ft 3
.nf
}
pthread_mutex_unlock(&mut);
.ft
-.LP
+.P
.RE
.fi
.
.SH SYNOPSIS
.B #include <pthread.h>
-.PP
+.P
.BI "int pthread_condattr_init(pthread_condattr_t *" attr ");"
.BI "int pthread_condattr_destroy(pthread_condattr_t *" attr ");"
.
Passing \fBNULL\fP is equivalent to
passing a condition attribute object
with all attributes set to their default values.
-.PP
+.P
The LinuxThreads implementation supports no attributes for conditions.
The functions on condition attributes are
included only for compliance with the POSIX standard.
-.PP
+.P
\fBpthread_condattr_init\fP
initializes the condition attribute object \fIattr\fP
and fills it with default values for the attributes.
.SH SYNOPSIS
.nf
.B #include <pthread.h>
-.PP
+.P
.BI "int pthread_create(pthread_t *restrict " thread ,
.BI " const pthread_attr_t *restrict " attr ,
.BI " void *(*" start_routine ")(void *),"
.I arg
is passed as the sole argument of
.IR start_routine ().
-.PP
+.P
The new thread terminates in one of the following ways:
.IP \[bu] 3
It calls
or the main thread performs a return from
.IR main ().
This causes the termination of all threads in the process.
-.PP
+.P
The
.I attr
argument points to a
.I attr
is NULL,
then the thread is created with default attributes.
-.PP
+.P
Before returning, a successful call to
.BR pthread_create ()
stores the ID of the new thread in the buffer pointed to by
.IR thread ;
this identifier is used to refer to the thread
in subsequent calls to other pthreads functions.
-.PP
+.P
The new thread inherits a copy of the creating thread's signal mask
.RB ( pthread_sigmask (3)).
The set of pending signals for the new thread is empty
The new thread does not inherit the creating thread's
alternate signal stack
.RB ( sigaltstack (2)).
-.PP
+.P
The new thread inherits the calling thread's floating-point environment
.RB ( fenv (3)).
-.PP
+.P
The initial value of the new thread's CPU-time clock is 0
(see
.BR pthread_getcpuclockid (3)).
.BR pthread_create (),
it is indeterminate which thread\[em]the caller or the new thread\[em]will
next execute.
-.PP
+.P
A thread may either be
.I joinable
or
.I attr
was set to create the thread in a detached state (using
.BR pthread_attr_setdetachstate (3)).
-.PP
+.P
Under the NPTL threading implementation, if the
.B RLIMIT_STACK
soft resource limit
The program below demonstrates the use of
.BR pthread_create (),
as well as a number of other functions in the pthreads API.
-.PP
+.P
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:
-.PP
+.P
.in +4n
.EX
.RB "$" " ulimit \-s"
Joined with thread 3; returned value was SERVUS
.EE
.in
-.PP
+.P
In the next run, the program explicitly sets a stack size of 1\ MB (using
.BR pthread_attr_setstacksize (3))
for the created threads:
-.PP
+.P
.in +4n
.EX
.RB "$" " ./a.out \-s 0x100000 hola salut servus"
.SH SYNOPSIS
.nf
.B #include <pthread.h>
-.PP
+.P
.BI "int pthread_detach(pthread_t " thread );
.fi
.SH DESCRIPTION
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.
-.PP
+.P
Attempting to detach an already detached thread results
in unspecified behavior.
.SH RETURN VALUE
Once a thread has been detached, it can't be joined with
.BR pthread_join (3)
or be made joinable again.
-.PP
+.P
A new thread can be created in a detached state using
.BR pthread_attr_setdetachstate (3)
to set the detached attribute of the
.I attr
argument of
.BR pthread_create (3).
-.PP
+.P
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
.BR exit (3)
(or equivalently, if the main thread returns).
-.PP
+.P
Either
.BR pthread_join (3)
or
actions has not been done will be freed when the process terminates.)
.SH EXAMPLES
The following statement detaches the calling thread:
-.PP
+.P
.in +4n
.EX
pthread_detach(pthread_self());
.SH SYNOPSIS
.nf
.B #include <pthread.h>
-.PP
+.P
.BI "int pthread_equal(pthread_t " t1 ", pthread_t " t2 );
.fi
.SH DESCRIPTION
.SH SYNOPSIS
.nf
.B #include <pthread.h>
-.PP
+.P
.BI "[[noreturn]] void pthread_exit(void *" retval );
.fi
.SH DESCRIPTION
that (if the thread is joinable)
is available to another thread in the same process that calls
.BR pthread_join (3).
-.PP
+.P
Any clean-up handlers established by
.BR pthread_cleanup_push (3)
that have not yet been popped,
after the clean-up handlers have been executed,
the corresponding destructor functions are called,
in an unspecified order.
-.PP
+.P
When a thread terminates,
process-shared resources (e.g., mutexes, condition variables,
semaphores, and file descriptors) are not released,
and functions registered using
.BR atexit (3)
are not called.
-.PP
+.P
After the last thread in a process terminates,
the process terminates as by calling
.BR exit (3)
than the main thread results in an implicit call to
.BR pthread_exit (),
using the function's return value as the thread's exit status.
-.PP
+.P
To allow other threads to continue execution,
the main thread should terminate by calling
.BR pthread_exit ()
rather than
.BR exit (3).
-.PP
+.P
The value pointed to by
.I retval
should not be located on the calling thread's stack,
.nf
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <pthread.h>
-.PP
+.P
.BI "int pthread_getattr_default_np(pthread_attr_t *" attr );
.BI "int pthread_setattr_default_np(const pthread_attr_t *" attr );
.fi
Setting the
.I stack size
attribute to zero means leave the default stack size unchanged.
-.PP
+.P
The
.BR pthread_getattr_default_np ()
function initializes the thread attributes object referred to by
to fetch the default thread-creation attributes and then displays
various settings from the returned thread attributes object.
When running the program, we see the following output:
-.PP
+.P
.in +4n
.EX
$ \fB./a.out\fP
.nf
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <pthread.h>
-.PP
+.P
.BI "int pthread_getattr_np(pthread_t " thread ", pthread_attr_t *" attr );
.fi
.SH DESCRIPTION
.I attr
so that it contains actual attribute values describing the running thread
.IR thread .
-.PP
+.P
The returned attribute values may differ from
the corresponding attribute values passed in the
.I attr
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.
-.PP
+.P
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.
-.PP
+.P
When the thread attributes object returned by
.BR pthread_getattr_np ()
is no longer required, it should be destroyed using
.B ENOMEM
.\" Can happen (but unlikely) while trying to allocate memory for cpuset
Insufficient memory.
-.PP
+.P
In addition, if
.I thread
refers to the main thread, then
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.
-.PP
+.P
In the first run, on an x86-32 system,
a thread is created using default attributes:
-.PP
+.P
.in +4n
.EX
.RB "$" " ulimit \-s" " # No stack limit ==> default stack size is 2 MB"
Stack size = 0x201000 (2101248) bytes
.EE
.in
-.PP
+.P
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):
-.PP
+.P
.in +4n
.EX
.RB "$" " ./a.out \-g 4097"
.\" Stack size = 0x8000 (32768) bytes
.\".fi
.\".in
-.PP
+.P
In the last run, the program manually allocates a stack for the thread.
In this case, the guard size attribute is ignored.
-.PP
+.P
.in +4n
.EX
.RB "$" " ./a.out \-g 4096 \-s 0x8000 \-a"
.nf
.B #include <pthread.h>
.B #include <time.h>
-.PP
+.P
.BI "int pthread_getcpuclockid(pthread_t " thread ", clockid_t *" clockid );
.fi
.SH DESCRIPTION
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:
-.PP
+.P
.in +4n
.EX
$ \fB./a.out\fP
.SH SYNOPSIS
.nf
.B #include <pthread.h>
-.PP
+.P
.BI "int pthread_join(pthread_t " thread ", void **" retval );
.fi
.SH DESCRIPTION
The thread specified by
.I thread
must be joinable.
-.PP
+.P
If
.I retval
is not NULL, then
.B PTHREAD_CANCELED
is placed in the location pointed to by
.IR retval .
-.PP
+.P
If multiple threads simultaneously try to join with the same thread,
the results are undefined.
If the thread calling
The caller may then choose to do any clean-up that is required
after termination of the thread (e.g., freeing memory or other
resources that were allocated to the target thread).
-.PP
+.P
Joining with a thread that has previously been joined results in
undefined behavior.
-.PP
+.P
Failure to join with a thread that is joinable
(i.e., one that is not detached),
produces a "zombie thread".
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).
-.PP
+.P
There is no pthreads analog of
.IR "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.
-.PP
+.P
All of the threads in a process are peers:
any thread can join with any other thread in the process.
.SH EXAMPLES
.
.SH SYNOPSIS
.B #include <pthread.h>
-.PP
+.P
.BI "int pthread_key_create(pthread_key_t *" key ", void (*" destr_function ") (void *));"
.BI "int pthread_key_delete(pthread_key_t " key ");"
.BI "int pthread_setspecific(pthread_key_t " key ", const void *" pointer ");"
Since threads share one memory space,
this cannot be achieved with regular variables.
Thread-specific data is the POSIX threads answer to this need.
-.PP
+.P
Each thread possesses a private memory block,
the thread-specific data area,
or TSD area for short.
TSD keys are common to all threads,
but the value associated with a given TSD key
can be different in each thread.
-.PP
+.P
For concreteness,
the TSD areas can be viewed as arrays of \fBvoid *\fP pointers,
TSD keys as integer indices into these arrays,
and the value of a TSD key
as the value of the corresponding array element in the calling thread.
-.PP
+.P
When a thread is created,
its TSD area initially associates \fBNULL\fP with all keys.
-.PP
+.P
\fBpthread_key_create\fP allocates a new TSD key.
The key is stored in the location pointed to by \fIkey\fP.
There is a limit of \fBPTHREAD_KEYS_MAX\fP
on the number of keys allocated at a given time.
The value initially associated with the returned key
is \fBNULL\fP in all currently executing threads.
-.PP
+.P
The \fIdestr_function\fP argument,
if not \fBNULL\fP,
specifies a destructor function associated with the key.
The \fIdestr_function\fP is not called if that value is \fBNULL\fP.
The order in which destructor functions are called at thread termination time
is unspecified.
-.PP
+.P
Before the destructor function is called,
the \fBNULL\fP value is associated with the key in the current thread.
A destructor function might,
after \fBPTHREAD_DESTRUCTOR_ITERATIONS\fP iterations,
even if some non-\fBNULL\fP values with associated descriptors remain.
Other implementations may loop indefinitely.
-.PP
+.P
\fBpthread_key_delete\fP deallocates a TSD key.
It does not check
whether non-\fBNULL\fP values are associated with that key
in the currently executing threads,
nor call the destructor function associated with the key.
-.PP
+.P
\fBpthread_setspecific\fP changes the value
associated with \fIkey\fP in the calling thread,
storing the given \fIpointer\fP instead.
-.PP
+.P
\fBpthread_getspecific\fP returns the value
currently associated with \fIkey\fP in the calling thread.
.
If successful,
\fBpthread_key_create\fP stores the newly allocated key
in the location pointed to by its \fIkey\fP argument.
-.PP
+.P
\fBpthread_getspecific\fP returns
the value associated with \fIkey\fP on success,
and \fBNULL\fP on error.
\fBEAGAIN\fP
\fBPTHREAD_KEYS_MAX\fP keys are already allocated.
.RE
-.PP
+.P
\fBpthread_key_delete\fP and \fBpthread_setspecific\fP return
the following error code on error:
.RS
\fBEINVAL\fP
\fIkey\fP is not a valid, allocated TSD key.
.RE
-.PP
+.P
\fBpthread_getspecific\fP returns \fBNULL\fP if \fIkey\fP is not a valid,
allocated TSD key.
.
The following code fragment
allocates a thread-specific array of 100 characters,
with automatic reclaimation at thread exit:
-.PP
+.P
.RS
.ft 3
.nf
free(buf);
}
.ft
-.LP
+.P
.RE
.fi
.SH SYNOPSIS
.nf
.B #include <signal.h>
-.PP
+.P
.BI "int pthread_kill(pthread_t " thread ", int " sig );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR pthread_kill ():
.nf
_POSIX_C_SOURCE >= 199506L || _XOPEN_SOURCE >= 500
a thread in the same process as the caller.
The signal is asynchronously directed to
.IR thread .
-.PP
+.P
If
.I sig
is 0, then no signal is sent, but error checking is still performed.
See
.BR nptl (7)
for details.
-.PP
+.P
POSIX.1-2008 recommends that if an implementation detects the use
of a thread ID after the end of its lifetime,
.BR pthread_kill ()
.SH SYNOPSIS
.nf
.B #include <pthread.h>
-.PP
+.P
.B void pthread_kill_other_threads_np(void);
.fi
.SH DESCRIPTION
.SH SYNOPSIS
.nf
.B #include <pthread.h>
-.PP
+.P
.BI "int pthread_mutex_consistent(pthread_mutex_t *" mutex ");"
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR pthread_mutex_consistent ():
.nf
_POSIX_C_SOURCE >= 200809L
.SH HISTORY
glibc 2.12.
POSIX.1-2008.
-.PP
+.P
Before the addition of
.BR pthread_mutex_consistent ()
to POSIX,
glibc defined the following equivalent nonstandard function if
.B _GNU_SOURCE
was defined:
-.PP
+.P
.nf
.B [[deprecated]]
.BI "int pthread_mutex_consistent_np(const pthread_mutex_t *" mutex );
.fi
-.PP
+.P
This GNU-specific API, which first appeared in glibc 2.4,
is nowadays obsolete and should not be used in new programs;
since glibc 2.34 it has been marked as deprecated.
.
.SH SYNOPSIS
.B #include <pthread.h>
-.PP
+.P
.BI "pthread_mutex_t " fastmutex " = PTHREAD_MUTEX_INITIALIZER;"
.BI "pthread_mutex_t " recmutex " = PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP;"
.BI "pthread_mutex_t " errchkmutex " = PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP;"
-.PP
+.P
.BI "int pthread_mutex_init(pthread_mutex_t *" mutex ", const pthread_mutexattr_t *" mutexattr ");"
.BI "int pthread_mutex_lock(pthread_mutex_t *" mutex ");"
.BI "int pthread_mutex_trylock(pthread_mutex_t *" mutex ");"
and is useful for
protecting shared data structures from concurrent modifications,
and implementing critical sections and monitors.
-.PP
+.P
A mutex has two possible states:
unlocked (not owned by any thread),
and locked (owned by one thread).
A thread attempting to lock a mutex
that is already locked by another thread
is suspended until the owning thread unlocks the mutex first.
-.PP
+.P
\fBpthread_mutex_init\fP initializes the mutex object pointed to by \fImutex\fP
according to the mutex attributes specified in \fImutexattr\fP.
If \fImutexattr\fP is \fBNULL\fP,
default attributes are used instead.
-.PP
+.P
The LinuxThreads implementation supports only one mutex attributes,
the \fImutex kind\fP,
which is either ``fast'',
whether it can be locked again by a thread that already owns it.
The default kind is ``fast''.
See \fBpthread_mutexattr_init\fP(3) for more information on mutex attributes.
-.PP
+.P
Variables of type \fBpthread_mutex_t\fP can also be initialized statically,
using the constants
\fBPTHREAD_MUTEX_INITIALIZER\fP
(for recursive mutexes),
and \fBPTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP\fP
(for error checking mutexes).
-.PP
+.P
\fBpthread_mutex_lock\fP locks the given mutex.
If the mutex is currently unlocked,
it becomes locked and owned by the calling thread,
If the mutex is already locked by another thread,
\fBpthread_mutex_lock\fP suspends the calling thread
until the mutex is unlocked.
-.PP
+.P
If the mutex is already locked by the calling thread,
the behavior of \fBpthread_mutex_lock\fP depends on the kind of the mutex.
If the mutex is of the ``fast'' kind,
recording the number of times the calling thread has locked the mutex.
An equal number of \fBpthread_mutex_unlock\fP operations
must be performed before the mutex returns to the unlocked state.
-.PP
+.P
\fBpthread_mutex_trylock\fP behaves identically to \fBpthread_mutex_lock\fP,
except that it does not block the calling thread
if the mutex is already locked by another thread
Instead,
\fBpthread_mutex_trylock\fP returns immediately
with the error code \fBEBUSY\fP.
-.PP
+.P
\fBpthread_mutex_unlock\fP unlocks the given mutex.
The mutex is assumed to be locked and owned by the calling thread
on entrance to \fBpthread_mutex_unlock\fP.
(number of \fBpthread_mutex_lock\fP operations
performed on it by the calling thread),
and only when this count reaches zero is the mutex actually unlocked.
-.PP
+.P
On ``error checking'' and ``recursive'' mutexes,
\fBpthread_mutex_unlock\fP actually checks at run-time
that the mutex is locked on entrance,
thus allowing a locked mutex to be
unlocked by a thread other than its owner.
This is non-portable behavior and must not be relied upon.
-.PP
+.P
\fBpthread_mutex_destroy\fP destroys a mutex object,
freeing the resources it might hold.
The mutex must be unlocked on entrance.
The mutex is already locked by the calling thread
(``error checking'' mutexes only).
.RE
-.PP
+.P
The \fBpthread_mutex_trylock\fP function returns
the following error codes on error:
.RS
\fBEINVAL\fP
The mutex has not been properly initialized.
.RE
-.PP
+.P
The \fBpthread_mutex_unlock\fP function returns
the following error code on error:
.RS
The calling thread does not own the mutex
(``error checking'' mutexes only).
.RE
-.PP
+.P
The \fBpthread_mutex_destroy\fP function returns
the following error code on error:
.RS
.
.SH EXAMPLE
A shared global variable \fIx\fP can be protected by a mutex as follows:
-.PP
+.P
.RS
.ft 3
.nf
int x;
pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER;
.ft
-.LP
+.P
.RE
.fi
-.PP
+.P
All accesses and modifications to \fIx\fP
should be bracketed by calls to
\fBpthread_mutex_lock\fP and \fBpthread_mutex_unlock\fP
as follows:
-.PP
+.P
.RS
.ft 3
.nf
/* operate on x */
pthread_mutex_unlock(&mut);
.ft
-.LP
+.P
.RE
.fi
.SH SYNOPSIS
.nf
.B #include <pthread.h>
-.PP
+.P
.B int pthread_mutexattr_getpshared(
.BI " const pthread_mutexattr_t *restrict " attr ,
.BI " int *restrict " pshared );
in a mutex attributes object.
This attribute must be appropriately set to ensure correct,
efficient operation of a mutex created using this attributes object.
-.PP
+.P
The process-shared attribute can have one of the following values:
.TP
.B PTHREAD_PROCESS_PRIVATE
Mutexes created with this attributes object can be shared between
any threads that have access to the memory containing the object,
including threads in different processes.
-.PP
+.P
.BR pthread_mutexattr_getpshared ()
places the value of the process-shared attribute of
the mutex attributes object referred to by
.I attr
in the location pointed to by
.IR pshared .
-.PP
+.P
.BR pthread_mutexattr_setpshared ()
sets the value of the process-shared attribute of
the mutex attributes object referred to by
.I attr
to the value specified in
.BR pshared .
-.PP
+.P
If
.I attr
does not refer to an initialized mutex attributes object,
.SH SYNOPSIS
.nf
.B #include <pthread.h>
-.PP
+.P
.BI "int pthread_mutexattr_init(pthread_mutexattr_t *" attr ");"
.BI "int pthread_mutexattr_destroy(pthread_mutexattr_t *" attr ");"
.fi
function initializes the mutex attributes object pointed to by
.I attr
with default values for all attributes defined by the implementation.
-.PP
+.P
The results of initializing an already initialized mutex attributes
object are undefined.
-.PP
+.P
The
.BR pthread_mutexattr_destroy ()
function destroys a mutex attribute object (making it uninitialized).
Once a mutex attributes object has been destroyed, it can be reinitialized with
.BR pthread_mutexattr_init ().
-.PP
+.P
The results of destroying an uninitialized mutex attributes
object are undefined.
.SH RETURN VALUE
.
.SH SYNOPSIS
.B #include <pthread.h>
-.PP
+.P
.BI "int pthread_mutexattr_setkind_np(pthread_mutexattr_t *" attr ", int " kind ");"
.BI "int pthread_mutexattr_getkind_np(const pthread_mutexattr_t *" attr ", int *" kind ");"
.
.
.SH "RETURN VALUE"
\fBpthread_mutexattr_getkind_np\fP always returns 0.
-.PP
+.P
\fBpthread_mutexattr_setkind_np\fP
returns 0 on success and a non-zero error code on error.
.
.SH SYNOPSIS
.nf
.B #include <pthread.h>
-.PP
+.P
.BI "int pthread_mutexattr_getrobust(const pthread_mutexattr_t *" attr ,
.BI " int *" robustness ");"
.BI "int pthread_mutexattr_setrobust(pthread_mutexattr_t *" attr ,
.BI " int " robustness ");"
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR pthread_mutexattr_getrobust (),
.BR pthread_mutexattr_setrobust ():
.nf
.I attr
to the value specified in
.IR *robustness .
-.PP
+.P
The robustness attribute specifies the behavior of the mutex when
the owning thread dies without unlocking the mutex.
The following values are valid for
.BR pthread_mutex_lock (3)
operations on this mutex will still return
.BR EOWNERDEAD .
-.PP
+.P
Note that the
.I attr
argument of
.SH RETURN VALUE
On success, these functions return 0.
On error, they return a positive error number.
-.PP
+.P
In the glibc implementation,
.BR pthread_mutexattr_getrobust ()
always return zero.
.SH HISTORY
glibc 2.12.
POSIX.1-2008.
-.PP
+.P
Before the addition of
.BR pthread_mutexattr_getrobust ()
and
glibc defined the following equivalent nonstandard functions if
.B _GNU_SOURCE
was defined:
-.PP
+.P
.nf
.B [[deprecated]]
.BI "int pthread_mutexattr_getrobust_np(const pthread_mutexattr_t *" attr ,
.BI "int pthread_mutexattr_setrobust_np(const pthread_mutexattr_t *" attr ,
.BI " int " robustness ");"
.fi
-.PP
+.P
Correspondingly, the constants
.B PTHREAD_MUTEX_STALLED_NP
and
.B PTHREAD_MUTEX_ROBUST_NP
were also defined.
-.PP
+.P
These GNU-specific APIs, which first appeared in glibc 2.4,
are nowadays obsolete and should not be used in new programs;
since glibc 2.34 these APIs are marked as deprecated.
successfully and gets the error
.BR EOWNERDEAD ,
after which it makes the mutex consistent.
-.PP
+.P
The following shell session shows what we see when running this program:
-.PP
+.P
.in +4n
.EX
$ \fB./a.out\fP
.
.SH SYNOPSIS
.B #include <pthread.h>
-.PP
+.P
.BI "pthread_once_t " once_control " = PTHREAD_ONCE_INIT;"
-.PP
+.P
.BI "int pthread_once(pthread_once_t *" once_control ", void (*" init_routine ") (void));"
.
.
to ensure that a piece of initialization code is executed at most once.
The \fIonce_control\fP argument points to a static or extern variable
statically initialized to \fBPTHREAD_ONCE_INIT\fP.
-.PP
+.P
The first time \fBpthread_once\fP is called
with a given \fIonce_control\fP argument,
it calls \fIinit_routine\fP with no argument
.SH SYNOPSIS
.nf
.B #include <pthread.h>
-.PP
+.P
.BI "int pthread_rwlockattr_setkind_np(pthread_rwlockattr_t *" attr ,
.BI " int " pref );
.B int pthread_rwlockattr_getkind_np(
.BI " const pthread_rwlockattr_t *restrict " attr ,
.BI " int *restrict " pref );
-.PP
+.P
.fi
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR pthread_rwlockattr_setkind_np (),
.BR pthread_rwlockattr_getkind_np ():
.nf
Setting the lock kind to this
avoids writer starvation as long as any read locking is not done in a
recursive fashion.
-.PP
+.P
The
.BR pthread_rwlockattr_getkind_np ()
function returns the value of the lock kind attribute of the
.SH SYNOPSIS
.nf
.B #include <pthread.h>
-.PP
+.P
.B pthread_t pthread_self(void);
.fi
.SH DESCRIPTION
use
.BR pthread_equal (3)
instead.
-.PP
+.P
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.
-.PP
+.P
Thread IDs are guaranteed to be unique only within a process.
A thread ID may be reused after a terminated thread has been joined,
or a detached thread has terminated.
-.PP
+.P
The thread ID returned by
.BR pthread_self ()
is not the same thing as the kernel thread ID returned by a call to
.nf
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <pthread.h>
-.PP
+.P
.BI "int pthread_setaffinity_np(pthread_t " thread ", size_t " cpusetsize ,
.BI " const cpu_set_t *" cpuset );
.BI "int pthread_getaffinity_np(pthread_t " thread ", size_t " cpusetsize ,
and the thread is not currently running on one of the CPUs in
.IR cpuset ,
then it is migrated to one of those CPUs.
-.PP
+.P
The
.BR pthread_getaffinity_np ()
function returns the CPU affinity mask of the thread
.I thread
in the buffer pointed to by
.IR cpuset .
-.PP
+.P
For more details on CPU affinity masks, see
.BR sched_setaffinity (2).
For a description of a set of macros
that can be used to manipulate and inspect CPU sets, see
.BR CPU_SET (3).
-.PP
+.P
The argument
.I cpusetsize
is the length (in bytes) of the buffer pointed to by
hence the suffix "_np" (nonportable) in the names.
.SH HISTORY
glibc 2.3.4.
-.PP
+.P
In glibc 2.3.3 only,
versions of these functions were provided that did not have a
.I cpusetsize
is being used.
These restrictions on the actual set of CPUs on which the thread
will run are silently imposed by the kernel.
-.PP
+.P
These functions are implemented on top of the
.BR sched_setaffinity (2)
and
.BR sched_getaffinity (2)
system calls.
-.PP
+.P
A new thread created by
.BR pthread_create (3)
inherits a copy of its creator's CPU affinity mask.
and then calls
.BR pthread_getaffinity_np ()
to check the resulting CPU affinity mask of the thread.
-.PP
+.P
.\" SRC BEGIN (pthread_setaffinity_np.c)
.EX
#define _GNU_SOURCE
.SH SYNOPSIS
.nf
.B #include <pthread.h>
-.PP
+.P
.BI "int pthread_setcancelstate(int " state ", int *" oldstate );
.BI "int pthread_setcanceltype(int " type ", int *" oldtype );
.fi
The thread is not cancelable.
If a cancelation request is received,
it is blocked until cancelability is enabled.
-.PP
+.P
The
.BR pthread_setcanceltype ()
sets the cancelability type of the calling thread to the value
(Typically,
it will be canceled immediately upon receiving a cancelation request,
but the system doesn't guarantee this.)
-.PP
+.P
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.
.B EINVAL
Invalid value for
.IR state .
-.PP
+.P
The
.BR pthread_setcanceltype ()
can fail with the following error:
.SH NOTES
For details of what happens when a thread is canceled, see
.BR \%pthread_cancel (3).
-.PP
+.P
Briefly disabling cancelability is useful
if a thread performs some critical action
that must not be interrupted by a cancelation request.
family of functions) may be left in an inconsistent state
if cancelation occurs in the middle of the function call.
Consequently, clean-up handlers cease to be useful.
-.PP
+.P
Functions that can be safely asynchronously canceled are called
.IR "async-cancel-safe functions" .
POSIX.1-2001 and POSIX.1-2008 require only that
be async-cancel-safe.
In general, other library functions
can't be safely called from an asynchronously cancelable thread.
-.PP
+.P
One of the few circumstances in which asynchronous cancelability is useful
is for cancelation of a thread that is in a pure compute-bound loop.
.SS Portability notes
.SH SYNOPSIS
.nf
.B #include <pthread.h>
-.PP
+.P
.BI "int pthread_setconcurrency(int " new_level );
.BI "int pthread_getconcurrency(" void );
.fi
POSIX.1 does not specify the level of concurrency that
should be provided as a result of calling
.BR pthread_setconcurrency ().
-.PP
+.P
Specifying
.I new_level
as 0 instructs the implementation to manage the concurrency level
as it deems appropriate.
-.PP
+.P
.BR pthread_getconcurrency ()
returns the current value of the concurrency level for this process.
.SH RETURN VALUE
.BR pthread_setconcurrency ()
returns 0;
on error, it returns a nonzero error number.
-.PP
+.P
.BR pthread_getconcurrency ()
always succeeds, returning the concurrency level set by a previous call to
.BR pthread_setconcurrency (),
.B EINVAL
.I new_level
is negative.
-.PP
+.P
POSIX.1 also documents an
.B EAGAIN
error ("the value specified by
POSIX.1-2001.
.SH NOTES
The default concurrency level is 0.
-.PP
+.P
Concurrency levels are meaningful only 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.
-.PP
+.P
Both LinuxThreads and NPTL are 1:1 threading implementations,
so setting the concurrency level has no meaning.
In other words,
.nf
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <pthread.h>
-.PP
+.P
.BI "int pthread_setname_np(pthread_t " thread ", const char *" name );
.BI "int pthread_getname_np(pthread_t " thread ", char " name [. size "], \
size_t " size );
argument specifies the thread whose name is to be changed;
.I name
specifies the new name.
-.PP
+.P
The
.BR pthread_getname_np ()
function can be used to retrieve the name of the thread.
The length of the string specified pointed to by
.I name
exceeds the allowed limit.
-.PP
+.P
The
.BR pthread_getname_np ()
function can fail with the following error:
and
.I size
is too small to hold the thread name.
-.PP
+.P
If either of these functions fails to open
.IR /proc/self/task/ tid /comm ,
then the call may fail with one of the errors described in
.BR pthread_setname_np ()
and
.BR pthread_getname_np ().
-.PP
+.P
The following shell session shows a sample run of the program:
-.PP
+.P
.in +4n
.EX
.RB "$" " ./a.out"
.SH SYNOPSIS
.nf
.B #include <pthread.h>
-.PP
+.P
.BI "int pthread_setschedparam(pthread_t " thread ", int " policy ,
.BI " const struct sched_param *" param );
.BI "int pthread_getschedparam(pthread_t " thread ", int *restrict " policy ,
.BR pthread_setschedparam ()
function sets the scheduling policy and parameters of the thread
.IR thread .
-.PP
+.P
.I policy
specifies the new scheduling policy for
.IR thread .
.\" FIXME . pthread_setschedparam() places no restriction on the policy,
.\" but pthread_attr_setschedpolicy() restricts policy to RR/FIFO/OTHER
.\" http://sourceware.org/bugzilla/show_bug.cgi?id=7013
-.PP
+.P
The structure pointed to by
.I param
specifies the new scheduling parameters for
.IR thread .
Scheduling parameters are maintained in the following structure:
-.PP
+.P
.in +4n
.EX
struct sched_param {
};
.EE
.in
-.PP
+.P
As can be seen, only one scheduling parameter is supported.
For details of the permitted ranges for scheduling priorities
in each scheduling policy, see
.BR sched (7).
-.PP
+.P
The
.BR pthread_getschedparam ()
function returns the scheduling policy and parameters of the thread
No thread with the ID
.I thread
could be found.
-.PP
+.P
.BR pthread_setschedparam ()
may additionally fail with the following errors:
.TP
.B EPERM
The caller does not have appropriate privileges
to set the specified scheduling policy and parameters.
-.PP
+.P
POSIX.1 also documents an
.B ENOTSUP
("attempt was made to set the policy or scheduling parameters
.BR pthread_getschedparam (),
as well as the use of a number of other scheduling-related
pthreads functions.
-.PP
+.P
In the following run, the main thread sets its scheduling policy to
.B SCHED_FIFO
with a priority of 10,
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.
-.PP
+.P
.in +4n
.EX
$ \fBsu\fP # Need privilege to set real\-time scheduling policies
policy=SCHED_RR, priority=20
.EE
.in
-.PP
+.P
In the above output, one can see that the scheduling policy and priority
were taken from the values specified in the thread attributes object.
-.PP
+.P
The next run is the same as the previous,
except that the inherit scheduler attribute is set to
.BR 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.
-.PP
+.P
.in +4n
.EX
# \fB./a.out \-mf10 \-ar20 \-i i\fP
policy=SCHED_FIFO, priority=10
.EE
.in
-.PP
+.P
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.
-.PP
+.P
Note that if we had omitted the
.I \-i\~i
option, the output would have been the same, since
.SH SYNOPSIS
.nf
.B #include <pthread.h>
-.PP
+.P
.BI "int pthread_setschedprio(pthread_t " thread ", int " prio );
.fi
.SH DESCRIPTION
No thread with the ID
.I thread
could be found.
-.PP
+.P
POSIX.1 also documents an
.B ENOTSUP
("attempt was made to set the priority
.SH SYNOPSIS
.nf
.B #include <signal.h>
-.PP
+.P
.BI "int pthread_sigmask(int " how ", const sigset_t *" set \
", sigset_t *" oldset );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR pthread_sigmask ():
.nf
_POSIX_C_SOURCE >= 199506L || _XOPEN_SOURCE >= 500
with the difference that its use in multithreaded programs
is explicitly specified by POSIX.1.
Other differences are noted in this page.
-.PP
+.P
For a description of the arguments and operation of this function, see
.BR sigprocmask (2).
.SH RETURN VALUE
POSIX.1-2001.
.SH NOTES
A new thread inherits a copy of its creator's signal mask.
-.PP
+.P
The glibc
.BR pthread_sigmask ()
function silently ignores attempts to block the two real-time signals that
and then creates a dedicated thread to fetch those signals via
.BR sigwait (3).
The following shell session demonstrates its use:
-.PP
+.P
.in +4n
.EX
.RB "$" " ./a.out &"
.nf
.B #include <signal.h>
.B #include <pthread.h>
-.PP
+.P
.BI "int pthread_sigqueue(pthread_t " thread ", int " sig ,
.BI " const union sigval " value );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR pthread_sigqueue ():
.nf
_GNU_SOURCE
but, rather than sending a signal to a process,
it sends a signal to a thread in the same process as the
calling thread.
-.PP
+.P
The
.I thread
argument is the ID of a thread in the same process as the caller.
.SH SYNOPSIS
.nf
.B #include <pthread.h>
-.PP
+.P
.BI "int pthread_spin_init(pthread_spinlock_t *" lock ", int " pshared ");"
.BI "int pthread_spin_destroy(pthread_spinlock_t *" lock ");"
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR pthread_spin_init (),
.BR pthread_spin_destroy ():
.nf
Spin locks are primarily useful in conjunction with real-time
scheduling policies.
See NOTES.
-.PP
+.P
The
.BR pthread_spin_init ()
function allocates any resources required for the use of
has access to the memory containing the lock
(i.e., the lock may be in a shared memory object that is
shared among multiple processes).
-.PP
+.P
Calling
.BR pthread_spin_init ()
on a spin lock that has already been initialized results
in undefined behavior.
-.PP
+.P
The
.BR pthread_spin_destroy ()
function destroys a previously initialized spin lock,
Destroying a spin lock that has not been previously been initialized
or destroying a spin lock while another thread holds the lock
results in undefined behavior.
-.PP
+.P
Once a spin lock has been destroyed,
performing any operation on the lock other than
once more initializing it with
.BR pthread_spin_init ()
results in undefined behavior.
-.PP
+.P
The result of performing operations such as
.BR pthread_spin_lock (3),
.BR pthread_spin_unlock (3),
.SH HISTORY
glibc 2.2.
POSIX.1-2001.
-.PP
+.P
Support for process-shared spin locks is a POSIX option.
The option is supported in the glibc implementation.
.SH NOTES
is scheduled off the CPU while it holds a spin lock,
then other threads will waste time spinning on the lock
until the lock holder is once more rescheduled and releases the lock.
-.PP
+.P
If threads create a deadlock situation while employing spin locks,
those threads will spin forever consuming CPU time.
-.PP
+.P
User-space spin locks are
.I not
applicable as a general locking solution.
.SH SYNOPSIS
.nf
.B #include <pthread.h>
-.PP
+.P
.BI "int pthread_spin_lock(pthread_spinlock_t *" lock );
.BI "int pthread_spin_trylock(pthread_spinlock_t *" lock );
.BI "int pthread_spin_unlock(pthread_spinlock_t *" lock );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR pthread_spin_lock (),
.BR pthread_spin_trylock ():
.nf
If the spin lock is currently locked by another thread,
the calling thread spins, testing the lock until it becomes available,
at which point the calling thread acquires the lock.
-.PP
+.P
Calling
.BR pthread_spin_lock ()
on a lock that is already held by the caller
or a lock that has not been initialized with
.BR pthread_spin_init (3)
results in undefined behavior.
-.PP
+.P
The
.BR pthread_spin_trylock ()
function is like
is currently locked,
then, instead of spinning, the call returns immediately with the error
.BR EBUSY .
-.PP
+.P
The
.BR pthread_spin_unlock ()
function unlocks the spin lock referred to
.IR lock .
If any threads are spinning on the lock,
one of those threads will then acquire the lock.
-.PP
+.P
Calling
.BR pthread_spin_unlock ()
on a lock that is not held by the caller results in undefined behavior.
.B EDEADLOCK
.\" Not detected in glibc
The system detected a deadlock condition.
-.PP
+.P
.BR pthread_spin_trylock ()
fails with the following errors:
.TP
.SH CAVEATS
Applying any of the functions described on this page to
an uninitialized spin lock results in undefined behavior.
-.PP
+.P
Carefully read NOTES in
.BR pthread_spin_init (3).
.SH SEE ALSO
.SH SYNOPSIS
.nf
.B #include <pthread.h>
-.PP
+.P
.B void pthread_testcancel(void);
.fi
.SH DESCRIPTION
creates a cancelation point within the calling thread,
so that a thread that is otherwise executing code that contains
no cancelation points will respond to a cancelation request.
-.PP
+.P
If cancelability is disabled (using
.BR pthread_setcancelstate (3)),
or no cancelation request is pending,
.nf
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <pthread.h>
-.PP
+.P
.BI "int pthread_tryjoin_np(pthread_t " thread ", void **" retval );
.BI "int pthread_timedjoin_np(pthread_t " thread ", void **" retval ,
.BI " const struct timespec *" abstime );
These functions operate in the same way as
.BR pthread_join (3),
except for the differences described on this page.
-.PP
+.P
The
.BR pthread_tryjoin_np ()
function performs a nonblocking join with the thread
has not yet terminated, then instead of blocking, as is done by
.BR pthread_join (3),
the call returns an error.
-.PP
+.P
The
.BR pthread_timedjoin_np ()
function performs a join-with-timeout.
.B EBUSY
.I thread
had not yet terminated at the time of the call.
-.PP
+.P
.BR pthread_timedjoin_np ()
can in addition fail with the following errors:
.TP
The call timed out before
.I thread
terminated.
-.PP
+.P
.BR pthread_timedjoin_np ()
never returns the error
.BR EINTR .
clock.
.SH EXAMPLES
The following code waits to join for up to 5 seconds:
-.PP
+.P
.in +4n
.EX
struct timespec ts;
.nf
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <pthread.h>
-.PP
+.P
.B [[deprecated]] int pthread_yield(void);
.fi
.SH DESCRIPTION
.BR Note :
This function is deprecated; see below.
-.PP
+.P
.BR pthread_yield ()
causes the calling thread to relinquish the CPU.
The thread is placed at the end of the run queue for its static
.SH SYNOPSIS
.nf
.B #include <stdlib.h>
-.PP
+.P
.BI "char *ptsname(int " fd );
.BI "int ptsname_r(int " fd ", char " buf [. buflen "], size_t " buflen );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR ptsname ():
.nf
Since glibc 2.24:
glibc 2.23 and earlier:
_XOPEN_SOURCE
.fi
-.PP
+.P
.BR ptsname_r ():
.nf
_GNU_SOURCE
function returns the name of the slave pseudoterminal device
corresponding to the master referred to by the file descriptor
.IR fd .
-.PP
+.P
The
.BR ptsname_r ()
function is the reentrant equivalent of
overwritten by subsequent calls.
This pointer must not be freed.
On failure, NULL is returned.
-.PP
+.P
On success,
.BR ptsname_r ()
returns 0.
.TP
.BR ptsname ():
POSIX.1-2008.
-.PP
+.P
.BR ptsname_r ()
is a Linux extension, that is proposed for inclusion
.\" FIXME . for later review when Issue 8 is one day released
.BR ptsname ():
POSIX.1-2001.
glibc 2.1.
-.PP
+.P
.BR ptsname ()
is part of the UNIX 98 pseudoterminal support (see
.BR pts (4)).
.SH SYNOPSIS
.nf
.B #include <stdlib.h>
-.PP
+.P
.BI "int putenv(char *" string );
.\" Not: const char *
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR putenv ():
.nf
_XOPEN_SOURCE
POSIX.1-2008.
.SH HISTORY
POSIX.1-2001, SVr2, 4.3BSD-Reno.
-.PP
+.P
The
.BR putenv ()
function is not required to be reentrant, and the
one in glibc 2.0 is not, but the glibc 2.1 version is.
-.\" .LP
+.\" .P
.\" Description for libc4, libc5, glibc:
.\" If the argument \fIstring\fP is of the form \fIname\fP,
.\" and does not contain an \[aq]=\[aq] character, then the variable \fIname\fP
.\" then it will be freed.
.\" In no case will the old storage associated
.\" to the environment variable itself be freed.
-.PP
+.P
Since glibc 2.1.2, the glibc implementation conforms to SUSv2:
the pointer \fIstring\fP given to
.BR putenv ()
a copy of the string is used.
On the one hand this causes a memory leak, and on the other hand
it violates SUSv2.
-.PP
+.P
The 4.3BSD-Reno version, like glibc 2.0, uses a copy;
this is fixed in all modern BSDs.
-.PP
+.P
SUSv2 removes the \fIconst\fP from the prototype, and so does glibc 2.1.3.
-.PP
+.P
The GNU C library implementation provides a nonstandard extension.
If
.I string
does not include an equal sign:
-.PP
+.P
.in +4n
.EX
putenv("NAME");
.EE
.in
-.PP
+.P
then the named variable is removed from the caller's environment.
.SH SEE ALSO
.BR clearenv (3),
.nf
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <grp.h>
-.PP
+.P
.BI "int putgrent(const struct group *restrict " grp \
", FILE *restrict " stream );
.fi
into the
.IR stream .
The list of group members must be NULL-terminated or NULL-initialized.
-.PP
+.P
The
.I struct group
is defined as follows:
-.PP
+.P
.in +4n
.EX
struct group {
.B #include <stdio.h>
.B #include <sys/types.h>
.B #include <pwd.h>
-.PP
+.P
.BI "int putpwent(const struct passwd *restrict " p \
", FILE *restrict " stream );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR putpwent ():
.nf
Since glibc 2.19:
.BR putpwent ()
function writes a password entry from the
structure \fIp\fP in the file associated with \fIstream\fP.
-.PP
+.P
The \fIpasswd\fP structure is defined in \fI<pwd.h>\fP as follows:
-.PP
+.P
.in +4n
.EX
struct passwd {
.SH SYNOPSIS
.nf
.B #include <stdio.h>
-.PP
+.P
.BI "int fputc(int " c ", FILE *" stream );
.BI "int putc(int " c ", FILE *" stream );
.BI "int putchar(int " c );
-.PP
+.P
.BI "int fputs(const char *restrict " s ", FILE *restrict " stream );
.BI "int puts(const char *" s );
.fi
.IR "unsigned char" ,
to
.IR stream .
-.PP
+.P
.BR putc ()
is equivalent to
.BR fputc ()
except that it may be implemented as a macro which evaluates
.I stream
more than once.
-.PP
+.P
.BI "putchar(" c )
is equivalent to
.BI "putc(" c ", " stdout ) \fR.
-.PP
+.P
.BR fputs ()
writes the string
.I s
to
.IR stream ,
without its terminating null byte (\[aq]\e0\[aq]).
-.PP
+.P
.BR puts ()
writes the string
.I s
and a trailing newline
to
.IR stdout .
-.PP
+.P
Calls to the functions described here can be mixed with each other and with
calls to other output functions from the
.I stdio
library for the same output stream.
-.PP
+.P
For nonlocking counterparts, see
.BR unlocked_stdio (3).
.SH RETURN VALUE
or
.B EOF
on error.
-.PP
+.P
.BR puts ()
and
.BR fputs ()
.SH SYNOPSIS
.nf
.B #include <wchar.h>
-.PP
+.P
.BI "wint_t putwchar(wchar_t " wc );
.fi
.SH DESCRIPTION
.BR WEOF .
Otherwise, it returns
.IR wc .
-.PP
+.P
For a nonlocking counterpart, see
.BR unlocked_stdio (3).
.SH RETURN VALUE
.B LC_CTYPE
category of the
current locale.
-.PP
+.P
It is reasonable to expect that
.BR putwchar ()
will actually write
.SH SYNOPSIS
.nf
.B #include <stdlib.h>
-.PP
+.P
.BI "[[deprecated]] char *qecvt(long double " number ", int " ndigits ,
.BI " int *restrict " decpt ", int *restrict " sign );
.BI "[[deprecated]] char *qfcvt(long double " number ", int " ndigits ,
.BI " int *restrict " decpt ", int *restrict " sign );
.BI "[[deprecated]] char *qgcvt(long double " number ", int " ndigit ", char *" buf );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR qecvt (),
.BR qfcvt (),
.BR qgcvt ():
.SH HISTORY
SVr4, SunOS, GNU.
.\" Not supported by libc4 and libc5.
-.PP
+.P
These functions are obsolete.
Instead,
.BR snprintf (3)
.SH SYNOPSIS
.nf
.B #include <stdlib.h>
-.PP
+.P
.BI "void qsort(void " base [. size " * ." nmemb "], size_t " nmemb ", \
size_t " size ,
.BI " int (*" compar ")(const void [." size "], \
const void [." size "], void *),"
.BI " void *" arg ");"
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR qsort_r ():
.nf
_GNU_SOURCE
size \fIsize\fP.
The \fIbase\fP argument points to the start of the
array.
-.PP
+.P
The contents of the array are sorted in ascending order according to a
comparison function pointed to by \fIcompar\fP, which is called with two
arguments that point to the objects being compared.
-.PP
+.P
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.
-.PP
+.P
The
.BR qsort_r ()
function is identical to
.SH EXAMPLES
For one example of use, see the example under
.BR bsearch (3).
-.PP
+.P
Another example is the following program,
which sorts the strings given in its command-line arguments:
-.PP
+.P
.\" SRC BEGIN (qsort.c)
.EX
#include <stdio.h>
.SH SYNOPSIS
.nf
.B #include <signal.h>
-.PP
+.P
.BI "int raise(int " sig );
.fi
.SH DESCRIPTION
.BR raise ()
function sends a signal to the calling process or thread.
In a single-threaded program it is equivalent to
-.PP
+.P
.in +4n
.EX
kill(getpid(), sig);
.EE
.in
-.PP
+.P
In a multithreaded program it is equivalent to
-.PP
+.P
.in +4n
.EX
pthread_kill(pthread_self(), sig);
.EE
.in
-.PP
+.P
If the signal causes a handler to be called,
.BR raise ()
will return only after the signal handler has returned.
C11, POSIX.1-2008.
.SH HISTORY
POSIX.1-2001, C89.
-.PP
+.P
Since glibc 2.3.3,
.BR raise ()
is implemented by calling
.SH SYNOPSIS
.nf
.B #include <stdlib.h>
-.PP
+.P
.B int rand(void);
.BI "void srand(unsigned int " seed );
-.PP
+.P
.BI "[[deprecated]] int rand_r(unsigned int *" seedp );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR rand_r ():
.nf
Since glibc 2.24:
function returns a pseudo-random integer in the range 0 to
.B RAND_MAX
inclusive (i.e., the mathematical range [0,\ \fBRAND_MAX\fR]).
-.PP
+.P
The
.BR srand ()
function sets its argument as the seed for a new
These sequences are repeatable by calling
.BR srand ()
with the same seed value.
-.PP
+.P
If no seed value is provided, the
.BR rand ()
function is automatically seeded with a value of 1.
-.PP
+.P
The function
.BR rand ()
is not reentrant, since it
application, this state must be made explicit;
this can be done using the reentrant function
.BR rand_r ().
-.PP
+.P
Like
.BR rand (),
.BR rand_r ()
.IR seedp ,
and that value is not modified between calls,
then the same pseudo-random sequence will result.
-.PP
+.P
The value pointed to by the
.I seedp
argument of
and
.BR srand (),
possibly useful when one needs the same sequence on two different machines.
-.PP
+.P
.in +4n
.EX
static unsigned long next = 1;
}
.EE
.in
-.PP
+.P
The following program can be used to display the
pseudo-random sequence produced by
.BR rand ()
When the seed is
.IR \-1 ,
the program uses a random seed.
-.PP
+.P
.in +4n
.\" SRC BEGIN (rand.c)
.EX
.SH SYNOPSIS
.nf
.B #include <stdlib.h>
-.PP
+.P
.B long random(void);
.BI "void srandom(unsigned int " seed );
-.PP
+.P
.BI "char *initstate(unsigned int " seed ", char " state [. n "], size_t " n );
.BI "char *setstate(char *" state );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR random (),
.BR srandom (),
.BR initstate (),
the range from 0 to 2\[ha]31\ \-\ 1.
The period of this random number generator is very large, approximately
.IR "16\ *\ ((2\[ha]31)\ \-\ 1)" .
-.PP
+.P
The
.BR srandom ()
function sets its argument as the seed for a new
.BR random ()
function
is automatically seeded with a value of 1.
-.PP
+.P
The
.BR initstate ()
function allows a state array \fIstate\fP to
\fIseed\fP is the seed for the
initialization, which specifies a starting point for the random number
sequence, and provides for restarting at the same point.
-.PP
+.P
The
.BR setstate ()
function changes the state array used by the
The
.BR srandom ()
function returns no value.
-.PP
+.P
The
.BR initstate ()
function returns a pointer to the previous state array.
On failure, it returns NULL, and
.I errno
is set to indicate the error.
-.PP
+.P
On success,
.BR setstate ()
returns a pointer to the previous state array.
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).
-.PP
+.P
For a more theoretical discussion which also covers many practical issues
in depth, see Chapter 3 (Random Numbers) in Donald E.\& Knuth's
.IR "The Art of Computer Programming" ,
.SH SYNOPSIS
.nf
.B #include <stdlib.h>
-.PP
+.P
.BI "int random_r(struct random_data *restrict " buf ,
.BI " int32_t *restrict " result );
.BI "int srandom_r(unsigned int " seed ", struct random_data *" buf );
-.PP
+.P
.BI "int initstate_r(unsigned int " seed ", \
char " statebuf "[restrict ." statelen ],
.BI " size_t " statelen ", struct random_data *restrict " buf );
.BI "int setstate_r(char *restrict " statebuf ,
.BI " struct random_data *restrict " buf );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR random_r (),
.BR srandom_r (),
.BR initstate_r (),
.BR random (3).
They are suitable for use in multithreaded programs where each thread
needs to obtain an independent, reproducible sequence of random numbers.
-.PP
+.P
The
.BR random_r ()
function is like
.BR initstate_r ().
The generated random number is returned in the argument
.IR result .
-.PP
+.P
The
.BR srandom_r ()
function is like
which must have been previously initialized by
.BR initstate_r (),
instead of the seed associated with the global state variable.
-.PP
+.P
The
.BR initstate_r ()
function is like
or allocated on the heap using
.BR malloc (3)
or similar.)
-.PP
+.P
The
.BR setstate_r ()
function is like
.SH SYNOPSIS
.nf
.BR "#include <netdb.h> " "/* Or <unistd.h> on some systems */"
-.PP
+.P
.BI "int rcmd(char **restrict " ahost ", unsigned short " inport ,
.BI " const char *restrict " locuser ,
.BI " const char *restrict " remuser ,
.BI " const char *restrict " cmd ", int *restrict " fd2p );
-.PP
+.P
.BI "int rresvport(int *" port );
-.PP
+.P
.BI "int iruserok(uint32_t " raddr ", int " superuser ,
.BI " const char *" ruser ", const char *" luser );
.BI "int ruserok(const char *" rhost ", int " superuser ,
.BI " const char *" ruser ", const char *" luser );
-.PP
+.P
.BI "int rcmd_af(char **restrict " ahost ", unsigned short " inport ,
.BI " const char *restrict " locuser ,
.BI " const char *restrict " remuser ,
.BI " const char *restrict " cmd ", int *restrict " fd2p ,
.BI " sa_family_t " af );
-.PP
+.P
.BI "int rresvport_af(int *" port ", sa_family_t " af );
-.PP
+.P
.BI "int iruserok_af(const void *restrict " raddr ", int " superuser ,
.BI " const char *restrict " ruser ", const char *restrict " luser ,
.BI " sa_family_t " af );
.BI " const char *" ruser ", const char *" luser ,
.BI " sa_family_t " af );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
.ad l
-.PP
+.P
.BR rcmd (),
.BR rcmd_af (),
.BR rresvport (),
and a connection is established to a server
residing at the well-known Internet port
.IR inport .
-.PP
+.P
If the connection succeeds,
a socket in the Internet domain of type
.B SOCK_STREAM
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.
-.PP
+.P
The protocol is described in detail in
.BR rshd (8).
.SS rresvport()
.I .rhosts
in the local user's home directory is checked to see if the request for
service is allowed.
-.PP
+.P
If this file does not exist, is not a regular file, is owned by anyone
other than the user or the superuser, is writable by anyone other
than the owner, or is hardlinked anywhere, the check automatically fails.
If the local domain (as obtained from
.BR gethostname (2))
is the same as the remote domain, only the machine name need be specified.
-.PP
+.P
If the IP address of the remote host is known,
.BR iruserok ()
should be used in preference to
function
returns a valid socket descriptor on success.
It returns \-1 on error and prints a diagnostic message on the standard error.
-.PP
+.P
The
.BR rresvport ()
function
The error code
.B EAGAIN
is overloaded to mean: "All network ports in use".
-.PP
+.P
For information on the return from
.BR ruserok ()
and
.TQ
.BR ruserok_af ()
glibc 2.2.
-.PP
+.P
Solaris, 4.2BSD.
The "_af" variants are more recent additions,
and are not present on as wide a range of systems.
.B #define _REGEX_RE_COMP
.B #include <sys/types.h>
.B #include <regex.h>
-.PP
+.P
.BI "[[deprecated]] char *re_comp(const char *" regex );
.BI "[[deprecated]] int re_exec(const char *" string );
.fi
is NULL,
no operation is performed and the pattern buffer's contents are not
altered.
-.PP
+.P
.BR re_exec ()
is used to assess whether the null-terminated string pointed to by
.I string
returns NULL on successful compilation of
.I regex
otherwise it returns a pointer to an appropriate error message.
-.PP
+.P
.BR re_exec ()
returns 1 for a successful match, zero for failure.
.SH ATTRIBUTES
None.
.SH HISTORY
4.3BSD.
-.PP
+.P
These functions are obsolete; the functions documented in
.BR regcomp (3)
should be used instead.
.SH SYNOPSIS
.nf
.B #include <dirent.h>
-.PP
+.P
.BI "struct dirent *readdir(DIR *" dirp );
.fi
.SH DESCRIPTION
to by \fIdirp\fP.
It returns NULL on reaching the end of the directory stream or if
an error occurred.
-.PP
+.P
In the glibc implementation, the
.I dirent
structure is defined as follows:
-.PP
+.P
.in +4n
.EX
struct dirent {
};
.EE
.in
-.PP
+.P
The only fields in the
.I dirent
structure that are mandated by POSIX.1 are
.IR d_ino .
The other fields are unstandardized, and not present on all systems;
see NOTES below for some further details.
-.PP
+.P
The fields of the
.I dirent
structure are as follows:
.I d_name
This field contains the null terminated filename.
.IR "See NOTES" .
-.PP
+.P
The data returned by
.BR readdir ()
may be overwritten by subsequent calls to
(This structure may be statically allocated; do not attempt to
.BR free (3)
it.)
-.PP
+.P
If the end of the directory stream is reached, NULL is returned and
.I errno
is not changed.
.BR readdir ()
T} Thread safety MT-Unsafe race:dirstream
.TE
-.PP
+.P
In the current POSIX.1 specification (POSIX.1-2008),
.BR readdir ()
is not required to be thread-safe.
and shows the
.I d_name
field with a fixed size.
-.PP
+.P
.IR Warning :
applications should avoid any dependence on the size of the
.I d_name
a character array of unspecified size, with at most
.B NAME_MAX
characters preceding the terminating null byte (\[aq]\e0\[aq]).
-.PP
+.P
POSIX.1 explicitly notes that this field should not be used as an lvalue.
The standard also notes that the use of
.I sizeof(d_name)
to capture the size of the record including the size of
.I d_name
is also incorrect.
-.PP
+.P
Note that while the call
-.PP
+.P
.in +4n
.EX
fpathconf(fd, _PC_NAME_MAX)
.EE
.in
-.PP
+.P
returns the value 255 for most filesystems,
on some filesystems (e.g., CIFS, Windows SMB servers),
the null-terminated filename that is (correctly) returned in
.SH NOTES
A directory stream is opened using
.BR opendir (3).
-.PP
+.P
The order in which filenames are read by successive calls to
.BR readdir ()
depends on the filesystem implementation;
.SH SYNOPSIS
.nf
.B #include <dirent.h>
-.PP
+.P
.BI "[[deprecated]] int readdir_r(DIR *restrict " dirp ,
.BI " struct dirent *restrict " entry ,
.BI " struct dirent **restrict " result );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR readdir_r ():
.nf
_POSIX_C_SOURCE
This function is deprecated; use
.BR readdir (3)
instead.
-.PP
+.P
The
.BR readdir_r ()
function was invented as a reentrant version of
.I dirent
structure, see
.BR readdir (3).
-.PP
+.P
A pointer to the returned buffer is placed in
.IR *result ;
if the end of the directory stream was encountered,
then NULL is instead returned in
.IR *result .
-.PP
+.P
It is recommended that applications use
.BR readdir (3)
instead of
.nf
.B #include <limits.h>
.B #include <stdlib.h>
-.PP
+.P
.BI "char *realpath(const char *restrict " path ,
.BI " char *restrict " resolved_path );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR realpath ():
.nf
_XOPEN_SOURCE >= 500
or
.I "/../"
components.
-.PP
+.P
If
.I resolved_path
is specified as NULL, then
.BR realpath ()
returns a pointer to the
.IR resolved_path .
-.PP
+.P
Otherwise, it returns NULL, the contents
of the array
.I resolved_path
POSIX.1-2008.
.SH HISTORY
4.4BSD, POSIX.1-2001, Solaris.
-.PP
+.P
POSIX.1-2001 says that the behavior if
.I resolved_path
is NULL is implementation-defined.
POSIX.1-2008 specifies the behavior described in this page.
-.PP
+.P
In 4.4BSD and Solaris, the limit on the pathname length is
.B MAXPATHLEN
(found in \fI<sys/param.h>\fP).
.BR pathconf (3)
function.
A typical source fragment would be
-.PP
+.P
.in +4n
.EX
#ifdef PATH_MAX
#endif
.EE
.in
-.PP
+.P
(But see the BUGS section.)
-.\".PP
+.\".P
.\" 2012-05-05, According to Casper Dik, the statement about
.\" Solaris was not true at least as far back as 1997, and
.\" may never have been true.
.I "resolved_path\ ==\ NULL"
feature, not standardized in POSIX.1-2001,
but standardized in POSIX.1-2008, allows this design problem to be avoided.
-.\" .LP
+.\" .P
.\" The libc4 and libc5 implementation contained a buffer overflow
.\" (fixed in libc-5.4.13).
.\" Thus, set-user-ID programs like
Probably, you are looking for the APIs provided by the
.I libdb
library instead.
-.PP
+.P
The routine
.BR dbopen (3)
is the library interface to database files.
The general description of the database access methods is in
.BR dbopen (3),
this manual page describes only the recno-specific information.
-.PP
+.P
The record number data structure is either variable or fixed-length
records stored in a flat-file format, accessed by the logical record
number.
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.
-.PP
+.P
The recno access-method-specific data structure provided to
.BR dbopen (3)
is defined in the
.I <db.h>
include file as follows:
-.PP
+.P
.in +4n
.EX
typedef struct {
} RECNOINFO;
.EE
.in
-.PP
+.P
The elements of this structure are defined as follows:
.TP
.I flags
as if specified as the filename for a
.BR dbopen (3)
of a btree file.
-.PP
+.P
The data part of the key/data pair used by the
.I recno
access method
The
.I size
field of the key should be the size of that type.
-.PP
+.P
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.
-.PP
+.P
In the interface specified by
.BR dbopen (3),
using the
.BR dbopen (3),
.BR hash (3),
.BR mpool (3)
-.PP
+.P
.IR "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.
.SH SYNOPSIS
.nf
.B #include <regex.h>
-.PP
+.P
.BI "int regcomp(regex_t *restrict " preg ", const char *restrict " regex ,
.BI " int " cflags );
.BI "int regexec(const regex_t *restrict " preg \
.BI " size_t " nmatch ", \
regmatch_t " pmatch "[_Nullable restrict ." nmatch ],
.BI " int " eflags );
-.PP
+.P
.BI "size_t regerror(int " errcode ", const regex_t *_Nullable restrict " preg ,
.BI " char " errbuf "[_Nullable restrict ." errbuf_size ],
.BI " size_t " errbuf_size );
.BI "void regfree(regex_t *" preg );
-.PP
+.P
.B typedef struct {
.B " size_t re_nsub;"
.B } regex_t;
-.PP
+.P
.B typedef struct {
.B " regoff_t rm_so;"
.B " regoff_t rm_eo;"
.B } regmatch_t;
-.PP
+.P
.BR typedef " /* ... */ " regoff_t;
.fi
.SH DESCRIPTION
for subsequent
.BR regexec ()
searches.
-.PP
+.P
On success, the pattern buffer at
.I *preg
is initialized.
is a null-terminated string.
The locale must be the same when running
.BR regexec ().
-.PP
+.P
After
.BR regcomp ()
succeeds,
to
.BR regexec ()
is sufficient to capture all matches.
-.PP
+.P
.I cflags
is the
bitwise OR
.I pmatch
are filled with
.BR \-1 s.
-.PP
+.P
Each returned valid
.RB (non- \-1 )
match corresponds to the range
.RI [ "string + rm_so" , " string + rm_eo" ).
-.PP
+.P
.I regoff_t
is a signed integer type
capable of storing the largest value that can be stored in either an
and
.BR regexec ()
into error message strings.
-.PP
+.P
If
.I preg
isn't a null pointer,
.I errcode
must be the latest error returned from an operation on
.IR preg .
-.PP
+.P
If
.I errbuf_size
isn't 0, up to
.SH RETURN VALUE
.BR regcomp ()
returns zero for a successful compilation or an error code for failure.
-.PP
+.P
.BR regexec ()
returns zero for a successful match or
.B REG_NOMATCH
for failure.
-.PP
+.P
.BR regerror ()
returns the size of the buffer required to hold the string.
.SH ERRORS
POSIX.1-2008.
.SH HISTORY
POSIX.1-2001.
-.PP
+.P
Prior to POSIX.1-2008,
.I regoff_t
was required to be
.B REG_NOSUB
wasn't specified, but all known implementations initialize it regardless.
.\" glibc, musl, 4.4BSD, illumos
-.PP
+.P
Both
.I regex_t
and
.SH SEE ALSO
.BR grep (1),
.BR regex (7)
-.PP
+.P
The glibc manual section,
.I "Regular Expressions"
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "double remainder(double " x ", double " y );
.BI "float remainderf(float " x ", float " y );
.BI "long double remainderl(long double " x ", long double " y );
-.PP
+.P
/* Obsolete synonyms */
.BI "[[deprecated]] double drem(double " x ", double " y );
.BI "[[deprecated]] float dremf(float " x ", float " y );
.BI "[[deprecated]] long double dreml(long double " x ", long double " y );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR remainder ():
.nf
_ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
|| /* Since glibc 2.19: */ _DEFAULT_SOURCE
|| /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
.fi
-.PP
+.P
.BR remainderf (),
.BR remainderl ():
.nf
|| /* Since glibc 2.19: */ _DEFAULT_SOURCE
|| /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
.fi
-.PP
+.P
.BR drem (),
.BR dremf (),
.BR dreml ():
is 0.5,
.I n
is chosen to be even.
-.PP
+.P
These functions are unaffected by the current rounding mode (see
.BR fenv (3)).
-.PP
+.P
The
.BR drem ()
function does precisely the same thing.
\fIx\fP\-\fIn\fP*\fIy\fP.
If the return value is 0, it has the sign of
.IR x .
-.PP
+.P
If
.I x
or
.I y
is a NaN, a NaN is returned.
-.PP
+.P
If
.I x
is an infinity,
is not a NaN,
a domain error occurs, and
a NaN is returned.
-.PP
+.P
If
.I y
is zero,
.BR math_error (7)
for information on how to determine whether an error has occurred
when calling these functions.
-.PP
+.P
The following errors can occur:
.TP
Domain error: \fIx\fP is an infinity and \fIy\fP is not a NaN
Before glibc 2.15,
.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6779
the call
-.PP
+.P
.in +4n
.EX
remainder(nan(""), 0);
.EE
.in
-.PP
+.P
returned a NaN, as expected, but wrongly caused a domain error.
Since glibc 2.15, a silent NaN (i.e., no domain error) is returned.
-.PP
+.P
Before glibc 2.15,
.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6783
.I errno
.SH SYNOPSIS
.nf
.B #include <stdio.h>
-.PP
+.P
.BI "int remove(const char *" pathname );
.fi
.SH DESCRIPTION
for files, and
.BR rmdir (2)
for directories.
-.PP
+.P
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.
-.PP
+.P
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.
-.PP
+.P
If the name referred to a symbolic link, the link is removed.
-.PP
+.P
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.
.SH RETURN VALUE
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "double remquo(double " x ", double " y ", int *" quo );
.BI "float remquof(float " x ", float " y ", int *" quo );
.BI "long double remquol(long double " x ", long double " y ", int *" quo );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR remquo (),
.BR remquof (),
.BR remquol ():
.I quo
pointer.
The remainder is returned as the function result.
-.PP
+.P
The value of the remainder is the same as that computed by the
.BR remainder (3)
function.
-.PP
+.P
The value stored via the
.I quo
pointer has the sign of
.I x\~/\~y
and agrees with the quotient in at least the low order 3 bits.
-.PP
+.P
For example, \fIremquo(29.0,\ 3.0)\fP returns \-1.0 and might store 2.
Note that the actual quotient might not fit in an integer.
.\" A possible application of this function might be the computation
On success, these functions return the same value as
the analogous functions described in
.BR remainder (3).
-.PP
+.P
If
.I x
or
.I y
is a NaN, a NaN is returned.
-.PP
+.P
If
.I x
is an infinity,
is not a NaN,
a domain error occurs, and
a NaN is returned.
-.PP
+.P
If
.I y
is zero,
.BR math_error (7)
for information on how to determine whether an error has occurred
when calling these functions.
-.PP
+.P
The following errors can occur:
.TP
Domain error: \fIx\fP is an infinity or \fIy\fP is 0, \
An invalid floating-point exception
.RB ( FE_INVALID )
is raised.
-.PP
+.P
These functions do not set
.IR errno .
.\" FIXME . Is it intentional that these functions do not set errno?
.B #include <netinet/in.h>
.B #include <arpa/nameser.h>
.B #include <resolv.h>
-.PP
+.P
.B struct __res_state;
.B typedef struct __res_state *res_state;
-.PP
+.P
.BI "int res_ninit(res_state " statep );
-.PP
+.P
.BI "void res_nclose(res_state " statep );
-.PP
+.P
.BI "int res_nquery(res_state " statep ,
.BI " const char *" dname ", int " class ", int " type ,
.BI " unsigned char " answer [. anslen "], int " anslen );
-.PP
+.P
.BI "int res_nsearch(res_state " statep ,
.BI " const char *" dname ", int " class ", int " type ,
.BI " unsigned char " answer [. anslen "], int " anslen );
-.PP
+.P
.BI "int res_nquerydomain(res_state " statep ,
.BI " const char *" name ", const char *" domain ,
.BI " int " class ", int " type ", unsigned char " answer [. anslen ],
.BI " int " anslen );
-.PP
+.P
.BI "int res_nmkquery(res_state " statep ,
.BI " int " op ", const char *" dname ", int " class ,
.BI " int " type ", const unsigned char " data [. datalen "], \
int " datalen ,
.BI " const unsigned char *" newrr ,
.BI " unsigned char " buf [. buflen "], int " buflen );
-.PP
+.P
.BI "int res_nsend(res_state " statep ,
.BI " const unsigned char " msg [. msglen "], int " msglen ,
.BI " unsigned char " answer [. anslen "], int " anslen );
-.PP
+.P
.BI "int dn_comp(const char *" exp_dn ", unsigned char " comp_dn [. length ],
.BI " int " length ", unsigned char **" dnptrs ,
.BI " unsigned char **" lastdnptr );
-.PP
+.P
.BI "int dn_expand(const unsigned char *" msg ,
.BI " const unsigned char *" eomorig ,
.BI " const unsigned char *" comp_dn ", char " exp_dn [. length ],
.BI " int " length );
-.PP
+.P
.B [[deprecated]] extern struct __res_state _res;
-.PP
+.P
.B [[deprecated]] int res_init(void);
-.PP
+.P
.B [[deprecated]]
.BI "int res_query(const char *" dname ", int " class ", int " type ,
.BI " unsigned char " answer [. anslen "], int " anslen );
-.PP
+.P
.B [[deprecated]]
.BI "int res_search(const char *" dname ", int " class ", int " type ,
.BI " unsigned char " answer [. anslen "], int " anslen );
-.PP
+.P
.B [[deprecated]]
.BI "int res_querydomain(const char *" name ", const char *" domain ,
.BI " int " class ", int " type ", unsigned char " answer [. anslen ],
.BI " int " anslen );
-.PP
+.P
.B [[deprecated]]
.BI "int res_mkquery(int " op ", const char *" dname ", int " class ,
.BI " int " type ", const unsigned char " data [. datalen "], \
int " datalen ,
.BI " const unsigned char *" newrr ,
.BI " unsigned char " buf [. buflen "], int " buflen );
-.PP
+.P
.B [[deprecated]]
.BI "int res_send(const unsigned char " msg [. msglen "], int " msglen ,
.BI " unsigned char " answer [. anslen "], int " anslen );
.B Note:
This page is incomplete (various resolver functions provided by glibc
are not described) and likely out of date.
-.PP
+.P
The functions described below make queries to and interpret
the responses from Internet domain name servers.
-.PP
+.P
The API consists of a set of more modern, reentrant functions
and an older set of nonreentrant functions that have been superseded.
The traditional resolver interfaces such as
and so on, which take a
.I res_state
as their first argument, so you can use a per-thread resolver state.
-.PP
+.P
The
.BR res_ninit ()
and
.BR res_ninit ()
and subsequent calls to
.BR res_nquery ().
-.PP
+.P
The
.BR res_nquery ()
and
\fIclass\fP.
The reply is left in the buffer \fIanswer\fP of length
\fIanslen\fP supplied by the caller.
-.PP
+.P
The
.BR res_nsearch ()
and
.B RES_DNSRCH
(see description of
\fI_res\fP options below).
-.PP
+.P
The
.BR res_nquerydomain ()
and
functions make a query using
.BR res_nquery ()/ res_query ()
on the concatenation of \fIname\fP and \fIdomain\fP.
-.PP
+.P
The following functions are lower-level routines used by
.BR res_nquery ()/ res_query ().
-.PP
+.P
The
.BR res_nmkquery ()
and
.TP
.B NS_NOTIFY_OP
Notify secondary of SOA (Start of Authority) change.
-.PP
+.P
\fInewrr\fP is currently unused.
-.PP
+.P
The
.BR res_nsend ()
and
They will call
.BR res_ninit ()/ res_init ()
if it has not already been called.
-.PP
+.P
The
.BR dn_comp ()
function compresses the domain name \fIexp_dn\fP
If \fIdnptr\fP is NULL, domain names are not compressed.
If \fIlastdnptr\fP is NULL, the list
of labels is not updated.
-.PP
+.P
The
.BR dn_expand ()
function expands the compressed domain name
The compressed name is contained
in a query or reply message, and \fImsg\fP points to the beginning of
the message.
-.PP
+.P
The resolver routines use configuration and state information
contained in a
.I __res_state
.BR res_init ()
functions return 0 on success, or \-1 if an error
occurs.
-.PP
+.P
The
.BR res_nquery (),
.BR res_query (),
.BR res_send ()
functions return the length
of the response, or \-1 if an error occurs.
-.PP
+.P
The
.BR dn_comp ()
and
.BR dn_expand ()
functions return the length
of the compressed name, or \-1 if an error occurs.
-.PP
+.P
In the case of an error return from
.BR res_nquery (),
.BR res_query (),
.BR resolver (5),
.BR hostname (7),
.BR named (8)
-.PP
+.P
The GNU C library source file
.IR resolv/README .
.nf
.B #include <sys/types.h>
.B #include <dirent.h>
-.PP
+.P
.BI "void rewinddir(DIR *" dirp );
.fi
.SH DESCRIPTION
.SH SYNOPSIS
.nf
.B #include <netdb.h>
-.PP
+.P
.B [[deprecated]]
.BI "int rexec(char **restrict " ahost ", int " inport ,
.BI " const char *restrict " user ", const char *restrict " passwd ,
.BI " const char *restrict " cmd ", int *restrict " fd2p );
-.PP
+.P
.B [[deprecated]]
.BI "int rexec_af(char **restrict " ahost ", int " inport ,
.BI " const char *restrict " user ", const char *restrict " passwd ,
.BI " const char *restrict " cmd ", int *restrict " fd2p ,
.BI " sa_family_t " af );
.fi
-.PP
+.P
.BR rexec (),
.BR rexec_af ():
.nf
.SH DESCRIPTION
This interface is obsoleted by
.BR rcmd (3).
-.PP
+.P
The
.BR rexec ()
function
file in user's
home directory are searched for appropriate information.
If all this fails, the user is prompted for the information.
-.PP
+.P
The port
.I inport
specifies which well-known DARPA Internet port to use for
will return a pointer to a structure that contains the necessary port.
The protocol for connection is described in detail in
.BR rexecd (8).
-.PP
+.P
If the connection succeeds,
a socket in the Internet domain of type
.B SOCK_STREAM
The
.BR rexec ()
function sends the unencrypted password across the network.
-.PP
+.P
The underlying service is considered a big security hole and therefore
not enabled on many sites; see
.BR rexecd (8)
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "double nearbyint(double " x );
.BI "float nearbyintf(float " x );
.BI "long double nearbyintl(long double " x );
-.PP
+.P
.BI "double rint(double " x );
.BI "float rintf(float " x );
.BI "long double rintl(long double " x );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR nearbyint (),
.BR nearbyintf (),
.BR nearbyintl ():
.nf
_POSIX_C_SOURCE >= 200112L || _ISOC99_SOURCE
.fi
-.PP
+.P
.BR rint ():
.nf
_ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
|| /* Since glibc 2.19: */ _DEFAULT_SOURCE
|| /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
.fi
-.PP
+.P
.BR rintf (),
.BR rintl ():
.nf
When the current rounding direction is to nearest, these
functions round halfway cases to the even integer in accordance with
IEEE-754.
-.PP
+.P
The
.BR rint (),
.BR rintf (),
when the result differs in value from the argument.
.SH RETURN VALUE
These functions return the rounded integer value.
-.PP
+.P
If
.I x
is integral, +0, \-0, NaN, or infinite,
and the number of mantissa bits
including the implicit bit
is 24 (respectively, 53).)
-.PP
+.P
If you want to store the rounded value in an integer type,
you probably want to use one of the functions described in
.BR lrint (3)
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "double round(double " x );
.BI "float roundf(float " x );
.BI "long double roundl(long double " x );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR round (),
.BR roundf (),
.BR roundl ():
.BR fenv (3)),
instead of to the nearest even integer like
.BR rint (3).
-.PP
+.P
For example,
.I round(0.5)
is 1.0, and
is \-1.0.
.SH RETURN VALUE
These functions return the rounded integer value.
-.PP
+.P
If
.I x
is integral, +0, \-0, NaN, or infinite,
and the number of mantissa bits
including the implicit bit
is 24 (respectively, 53).)
-.PP
+.P
If you want to store the rounded value in an integer type,
you probably want to use one of the functions described in
.BR lround (3)
.SH SYNOPSIS
.nf
.B #include <sys/param.h>
-.PP
+.P
.BI roundup( x ", " step );
.fi
.SH DESCRIPTION
.I step
that is not less than
.IR x .
-.PP
+.P
It is typically used for
rounding up a pointer to align it or
increasing a buffer to be allocated.
-.PP
+.P
This API is not designed to be generic,
and doesn't work in some cases
that are not important for the typical use cases described above.
None.
.SH CAVEATS
The arguments may be evaluated more than once.
-.PP
+.P
.I x
should be nonnegative,
and
.I step
should be positive.
-.PP
+.P
If
.I x + step
would overflow or wrap around,
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.
-.\" .LP
+.\" .P
.\" We don't have an rpc_secure.3 page at the moment -- MTK, 19 Sep 05
.\" Routines that are used for Secure RPC (DES authentication) are described in
.\" .BR rpc_secure (3).
.\" Secure RPC can be used only if DES encryption is available.
-.PP
+.P
To take use of these routines, include the header file
.IR "<rpc/rpc.h>" .
-.PP
+.P
The prototypes below make use of the following types:
-.PP
+.P
.RS 4
.EX
.BI "typedef int " bool_t ;
-.PP
+.P
.BI "typedef bool_t (*" xdrproc_t ")(XDR *, void *, ...);"
-.PP
+.P
.BI "typedef bool_t (*" resultproc_t ")(caddr_t " resp ,
.BI " struct sockaddr_in *" raddr );
.EE
.RE
-.PP
+.P
See the header files for the declarations of the
.IR AUTH ,
.IR CLIENT ,
and
.I XDR
types.
-.PP
+.P
.nf
.BI "void auth_destroy(AUTH *" auth );
.fi
.I auth
is undefined after calling
.BR auth_destroy ().
-.PP
+.P
.nf
.B AUTH *authnone_create(void);
.fi
authentication handle that passes nonusable authentication
information with each remote procedure call.
This is the default authentication used by RPC.
-.PP
+.P
.nf
.BI "AUTH *authunix_create(char *" host ", uid_t " uid ", gid_t " gid ,
.BI " int " len ", gid_t " aup_gids [. len ]);
.I aup_gids
refer to a counted array of groups to which the user belongs.
It is easy to impersonate a user.
-.PP
+.P
.nf
.B AUTH *authunix_create_default(void);
.fi
Calls
.BR authunix_create ()
with the appropriate parameters.
-.PP
+.P
.nf
.BI "int callrpc(char *" host ", unsigned long " prognum ,
.BI " unsigned long " versnum ", unsigned long " procnum ,
.BR clntudp_create ()
for restrictions.
You do not have control of timeouts or authentication using this routine.
-.PP
+.P
.nf
.BI "enum clnt_stat clnt_broadcast(unsigned long " prognum ,
.BI " unsigned long " versnum ", unsigned long " procnum ,
Warning: broadcast sockets are limited in size to the
maximum transfer unit of the data link.
For ethernet, this value is 1500 bytes.
-.PP
+.P
.nf
.BI "enum clnt_stat clnt_call(CLIENT *" clnt ", unsigned long " procnum ,
.BI " xdrproc_t " inproc ", char *" in ,
is used to decode the procedure's results;
.I tout
is the time allowed for results to come back.
-.PP
+.P
.nf
.BI "clnt_destroy(CLIENT *" clnt );
.fi
.BR clnt_destroy ().
If the RPC library opened the associated socket, it will close it also.
Otherwise, the socket remains open.
-.PP
+.P
.nf
.BI "CLIENT *clnt_create(const char *" host ", unsigned long " prog ,
.BI " unsigned long " vers ", const char *" proto );
Since UDP-based RPC messages can hold only up to 8 Kbytes of encoded data,
this transport cannot be used for procedures that take
large arguments or return huge results.
-.PP
+.P
.nf
.BI "bool_t clnt_control(CLIENT *" cl ", int " req ", char *" info );
.fi
The retry timeout is the time that "UDP RPC"
waits for the server to reply before
retransmitting the request.
-.PP
+.P
.nf
.BI "clnt_freeres(CLIENT * " clnt ", xdrproc_t " outproc ", char *" out );
.fi
is the XDR routine describing the results.
This routine returns one if the results were successfully freed,
and zero otherwise.
-.PP
+.P
.nf
.BI "void clnt_geterr(CLIENT *" clnt ", struct rpc_err *" errp );
.fi
A macro that copies the error structure out of the client
handle to the structure at address
.IR errp .
-.PP
+.P
.nf
.BI "void clnt_pcreateerror(const char *" s );
.fi
or
.BR clntudp_create ()
call fails.
-.PP
+.P
.nf
.BI "void clnt_perrno(enum clnt_stat " stat );
.fi
.IR stat .
Used after
.BR callrpc ().
-.PP
+.P
.nf
.BI "clnt_perror(CLIENT *" clnt ", const char *" s );
.fi
and a colon.
Used after
.BR clnt_call ().
-.PP
+.P
.nf
.BI "char *clnt_spcreateerror(const char *" s );
.fi
except that it returns a string instead of printing to the standard error.
.IP
Bugs: returns pointer to static data that is overwritten on each call.
-.PP
+.P
.nf
.BI "char *clnt_sperrno(enum clnt_stat " stat );
.fi
.BR clnt_sperrno ()
returns pointer to static data, but the
result will not get overwritten on each call.
-.PP
+.P
.nf
.BI "char *clnt_sperror(CLIENT *" rpch ", const char *" s );
.fi
it returns a string instead of printing to standard error.
.IP
Bugs: returns pointer to static data that is overwritten on each call.
-.PP
+.P
.nf
.BI "CLIENT *clntraw_create(unsigned long " prognum \
", unsigned long " versnum );
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.
-.PP
+.P
.nf
.BI "CLIENT *clnttcp_create(struct sockaddr_in *" addr ,
.BI " unsigned long " prognum ", unsigned long " versnum ,
.IR recvsz ;
values of zero choose suitable defaults.
This routine returns NULL if it fails.
-.PP
+.P
.nf
.BI "CLIENT *clntudp_create(struct sockaddr_in *" addr ,
.BI " unsigned long " prognum ", unsigned long " versnum ,
Warning: since UDP-based RPC messages can hold only up to 8 Kbytes
of encoded data, this transport cannot be used for procedures
that take large arguments or return huge results.
-.PP
+.P
.nf
.BI "CLIENT *clntudp_bufcreate(struct sockaddr_in *" addr ,
.BI " unsigned long " prognum ", unsigned long " versnum ,
.IP
This allows the user to specify the maximum packet
size for sending and receiving UDP-based RPC messages.
-.PP
+.P
.nf
.BI "void get_myaddress(struct sockaddr_in *" addr );
.fi
.IR /etc/hosts .
The port number is always set to
.BR htons(PMAPPORT) .
-.PP
+.P
.nf
.BI "struct pmaplist *pmap_getmaps(struct sockaddr_in *" addr );
.fi
The command
.I rpcinfo\~\-p
uses this routine.
-.PP
+.P
.nf
.BI "unsigned short pmap_getport(struct sockaddr_in *" addr ,
.BI " unsigned long " prognum ", unsigned long " versnum ,
In the latter case, the global variable
.I rpc_createerr
contains the RPC status.
-.PP
+.P
.nf
.BI "enum clnt_stat pmap_rmtcall(struct sockaddr_in *" addr ,
.BI " unsigned long " prognum ", unsigned long " versnum ,
This procedure should be used for a \[lq]ping\[rq] and nothing else.
See also
.BR clnt_broadcast ().
-.PP
+.P
.nf
.BI "bool_t pmap_set(unsigned long " prognum ", unsigned long " versnum ,
.BI " int " protocol ", unsigned short " port );
This routine returns one if it succeeds, zero otherwise.
Automatically done by
.BR svc_register ().
-.PP
+.P
.nf
.BI "bool_t pmap_unset(unsigned long " prognum ", unsigned long " versnum );
.fi
.B portmap
service.
This routine returns one if it succeeds, zero otherwise.
-.PP
+.P
.nf
.BI "int registerrpc(unsigned long " prognum ", unsigned long " versnum ,
.BI " unsigned long " procnum ", char *(*" procname ")(char *),"
are accessed using the UDP/IP transport; see
.BR svcudp_create ()
for restrictions.
-.PP
+.P
.nf
.BI "struct rpc_createerr " rpc_createerr ;
.fi
Use the routine
.BR clnt_pcreateerror ()
to print the reason why.
-.PP
+.P
.nf
.BI "void svc_destroy(SVCXPRT *" xprt );
.fi
Use of
.I xprt
is undefined after calling this routine.
-.PP
+.P
.nf
.BI "fd_set " svc_fdset ;
.fi
yet it may change after calls to
.BR svc_getreqset ()
or any creation routines.
-.PP
+.P
.nf
.BI "int " svc_fds ;
.fi
but limited to 32 file descriptors.
This interface is obsoleted by
.BR svc_fdset .
-.PP
+.P
.nf
.BI "svc_freeargs(SVCXPRT *" xprt ", xdrproc_t " inproc ", char *" in );
.fi
.BR svc_getargs ().
This routine returns 1 if the results were successfully freed,
and zero otherwise.
-.PP
+.P
.nf
.BI "svc_getargs(SVCXPRT *" xprt ", xdrproc_t " inproc ", char *" in );
.fi
.I inproc
is the XDR routine used to decode the arguments.
This routine returns one if decoding succeeds, and zero otherwise.
-.PP
+.P
.nf
.BI "struct sockaddr_in *svc_getcaller(SVCXPRT *" xprt );
.fi
The approved way of getting the network address of the caller
of a procedure associated with the RPC service transport handle,
.IR xprt .
-.PP
+.P
.nf
.BI "void svc_getreqset(fd_set *" rdfds );
.fi
The routine returns when all sockets associated with the value of
.I rdfds
have been serviced.
-.PP
+.P
.nf
.BI "void svc_getreq(int " rdfds );
.fi
but limited to 32 file descriptors.
This interface is obsoleted by
.BR svc_getreqset ().
-.PP
+.P
.nf
.BI "bool_t svc_register(SVCXPRT *" xprt ", unsigned long " prognum ,
.BI " unsigned long " versnum ,
The
.BR svc_register ()
routine returns one if it succeeds, and zero otherwise.
-.PP
+.P
.nf
.B "void svc_run(void);"
.fi
This procedure is usually waiting for a
.BR select (2)
system call to return.
-.PP
+.P
.nf
.BI "bool_t svc_sendreply(SVCXPRT *" xprt ", xdrproc_t " outproc \
", char *" out );
.I out
is the address of the results.
This routine returns one if it succeeds, zero otherwise.
-.PP
+.P
.nf
.BI "void svc_unregister(unsigned long " prognum ", unsigned long " versnum );
.fi
to dispatch routines, and of the triple
.RI [ prognum , versnum , * ]
to port number.
-.PP
+.P
.nf
.BI "void svcerr_auth(SVCXPRT *" xprt ", enum auth_stat " why );
.fi
.IP
Called by a service dispatch routine that refuses to perform
a remote procedure call due to an authentication error.
-.PP
+.P
.nf
.BI "void svcerr_decode(SVCXPRT *" xprt );
.fi
decode its parameters.
See also
.BR svc_getargs ().
-.PP
+.P
.nf
.BI "void svcerr_noproc(SVCXPRT *" xprt );
.fi
.IP
Called by a service dispatch routine that does not implement
the procedure number that the caller requests.
-.PP
+.P
.nf
.BI "void svcerr_noprog(SVCXPRT *" xprt );
.fi
.IP
Called when the desired program is not registered with the RPC package.
Service implementors usually do not need this routine.
-.PP
+.P
.nf
.BI "void svcerr_progvers(SVCXPRT *" xprt ", unsigned long " low_vers ,
.BI " unsigned long " high_vers );
Called when the desired version of a program is not registered
with the RPC package.
Service implementors usually do not need this routine.
-.PP
+.P
.nf
.BI "void svcerr_systemerr(SVCXPRT *" xprt );
.fi
error not covered by any particular protocol.
For example, if a service can no longer allocate storage,
it may call this routine.
-.PP
+.P
.nf
.BI "void svcerr_weakauth(SVCXPRT *" xprt );
.fi
a remote procedure call due to insufficient authentication parameters.
The routine calls
.BR "svcerr_auth(xprt, AUTH_TOOWEAK)" .
-.PP
+.P
.nf
.BI "SVCXPRT *svcfd_create(int " fd ", unsigned int " sendsize ,
.BI " unsigned int " recvsize );
.I recvsize
indicate sizes for the send and receive buffers.
If they are zero, a reasonable default is chosen.
-.PP
+.P
.nf
.B SVCXPRT *svcraw_create(void);
.fi
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.
-.PP
+.P
.nf
.BI "SVCXPRT *svctcp_create(int " sock ", unsigned int " send_buf_size ,
.BI " unsigned int " recv_buf_size );
Since TCP-based RPC uses buffered I/O,
users may specify the size of buffers; values of zero
choose suitable defaults.
-.PP
+.P
.nf
.BI "SVCXPRT *svcudp_bufcreate(int " sock ", unsigned int " sendsize ,
.BI " unsigned int " recosize );
.IP
This allows the user to specify the maximum packet size for sending and
receiving UDP-based RPC messages.
-.PP
+.P
.nf
.BI "SVCXPRT *svcudp_create(int " sock );
.fi
.I svcudp_bufcreate(sock,SZ,SZ)
for some default size
.IR SZ .
-.PP
+.P
.nf
.BI "bool_t xdr_accepted_reply(XDR *" xdrs ", struct accepted_reply *" ar );
.fi
Used for encoding RPC reply messages.
This routine is useful for users who wish to generate
RPC-style messages without using the RPC package.
-.PP
+.P
.nf
.BI "bool_t xdr_authunix_parms(XDR *" xdrs ", struct authunix_parms *" aupp );
.fi
This routine is useful for users
who wish to generate these credentials without using the RPC
authentication package.
-.PP
+.P
.nf
.BI "void xdr_callhdr(XDR *" xdrs ", struct rpc_msg *" chdr );
.fi
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.
-.PP
+.P
.nf
.BI "bool_t xdr_callmsg(XDR *" xdrs ", struct rpc_msg *" cmsg );
.fi
Used for describing RPC call messages.
This routine is useful for users who wish to generate RPC-style
messages without using the RPC package.
-.PP
+.P
.nf
.BI "bool_t xdr_opaque_auth(XDR *" xdrs ", struct opaque_auth *" ap );
.fi
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.
-.PP
+.P
.nf
.BI "bool_t xdr_pmap(XDR *" xdrs ", struct pmap *" regs );
.fi
these parameters without using the
.B pmap
interface.
-.PP
+.P
.nf
.BI "bool_t xdr_pmaplist(XDR *" xdrs ", struct pmaplist **" rp );
.fi
these parameters without using the
.B pmap
interface.
-.PP
+.P
.nf
.BI "bool_t xdr_rejected_reply(XDR *" xdrs ", struct rejected_reply *" rr );
.fi
Used for describing RPC reply messages.
This routine is useful for users who wish to generate
RPC-style messages without using the RPC package.
-.PP
+.P
.nf
.BI "bool_t xdr_replymsg(XDR *" xdrs ", struct rpc_msg *" rmsg );
.fi
Used for describing RPC reply messages.
This routine is useful for users who wish to generate
RPC style messages without using the RPC package.
-.PP
+.P
.nf
.BI "void xprt_register(SVCXPRT *" xprt );
.fi
This routine modifies the global variable
.IR svc_fds .
Service implementors usually do not need this routine.
-.PP
+.P
.nf
.BI "void xprt_unregister(SVCXPRT *" xprt );
.fi
.\" We don't have an rpc_secure.3 page in the set at the moment -- MTK, 19 Sep 05
.\" .BR rpc_secure (3),
.BR xdr (3)
-.PP
+.P
The following manuals:
.RS
Remote Procedure Calls: Protocol Specification
rpcgen Programming Guide
.br
.RE
-.PP
+.P
.IR "RPC: Remote Procedure Call Protocol Specification" ,
RFC\ 1050, Sun Microsystems, Inc.,
USC-ISI.
.SH SYNOPSIS
.nf
.B #include <stdlib.h>
-.PP
+.P
.BI "int rpmatch(const char *" response );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR rpmatch ():
.nf
Since glibc 2.19:
.BR rpmatch ()
handles a user response to yes or no questions, with
support for internationalization.
-.PP
+.P
.I response
should be a null-terminated string containing a
user-supplied response, perhaps obtained with
.BR fgets (3)
or
.BR getline (3).
-.PP
+.P
The user's language preference is taken into account per the
environment variables
.BR LANG ,
if the program has called
.BR setlocale (3)
to effect their changes.
-.PP
+.P
Regardless of the locale, responses matching
.B \[ha][Yy]
are always accepted as affirmative, and those matching
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.
-.PP
+.P
.BR rpmatch ()
can fail for any of the reasons that
.BR regcomp (3)
The following program displays the results when
.BR rpmatch ()
is applied to the string given in the program's command-line argument.
-.PP
+.P
.\" SRC BEGIN (rpmatch.c)
.EX
#define _DEFAULT_SOURCE
.SH SYNOPSIS
.nf
.B "#include <rpc/auth_des.h>"
-.PP
+.P
.BI "int rtime(struct sockaddr_in *" addrp ", struct rpc_timeval *" timep ,
.BI " struct rpc_timeval *" timeout );
.fi
.SH DESCRIPTION
This function uses the Time Server Protocol as described in
RFC\ 868 to obtain the time from a remote machine.
-.PP
+.P
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).
-.PP
+.P
When
.I timeout
is non-NULL, the udp/time socket (port 37) is used.
.TE
.SH NOTES
Only IPv4 is supported.
-.PP
+.P
Some
.I in.timed
versions support only TCP.
Try the example program with
.I use_tcp
set to 1.
-.\" .PP
+.\" .P
.\" Libc5 uses the prototype
-.\" .PP
+.\" .P
.\" .nf
.\" int rtime(struct sockaddr_in *, struct timeval *, struct timeval *);
.\" .fi
-.\" .PP
+.\" .P
.\" and requires
.\" .I <sys/time.h>
.\" instead of
that the time entry within
.I /etc/inetd.conf
is not commented out.
-.PP
+.P
The program connects to a computer called "linux".
Using "localhost" does not work.
The result is the localtime of the computer "linux".
-.PP
+.P
.\" SRC BEGIN (rtime.c)
.EX
#include <errno.h>
.B #include <linux/netlink.h>
.B #include <linux/rtnetlink.h>
.B #include <sys/socket.h>
-.PP
+.P
.BI "rtnetlink_socket = socket(AF_NETLINK, int " socket_type \
", NETLINK_ROUTE);"
-.PP
+.P
.BI "int RTA_OK(struct rtattr *" rta ", int " rtabuflen );
-.PP
+.P
.BI "void *RTA_DATA(struct rtattr *" rta );
.BI "unsigned int RTA_PAYLOAD(struct rtattr *" rta );
-.PP
+.P
.BI "struct rtattr *RTA_NEXT(struct rtattr *" rta \
", unsigned int " rtabuflen );
-.PP
+.P
.BI "unsigned int RTA_LENGTH(unsigned int " length );
.BI "unsigned int RTA_SPACE(unsigned int "length );
.fi
.BR netlink (7)
message header and appended attributes.
The attributes should be manipulated only using the macros provided here.
-.PP
+.P
.BI RTA_OK( rta ", " attrlen )
returns true if
.I rta
message, even if
.I attrlen
is nonzero.
-.PP
+.P
.BI RTA_DATA( rta )
returns a pointer to the start of this attribute's data.
-.PP
+.P
.BI RTA_PAYLOAD( rta )
returns the length of this attribute's data.
-.PP
+.P
.BI RTA_NEXT( rta ", " attrlen )
gets the next attribute after
.IR rta .
You should use
.B RTA_OK
to check the validity of the returned pointer.
-.PP
+.P
.BI RTA_LENGTH( len )
returns the length which is required for
.I len
bytes of data plus the header.
-.PP
+.P
.BI RTA_SPACE( len )
returns the amount of space which will be needed in a message with
.I len
.SH EXAMPLES
.\" FIXME . ? would be better to use libnetlink in the EXAMPLE code here
Creating a rtnetlink message to set the MTU of a device:
-.PP
+.P
.in +4n
.EX
#include <linux/rtnetlink.h>
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "[[deprecated]] double scalb(double " x ", double " exp );
.BI "[[deprecated]] float scalbf(float " x ", float " exp );
.BI "[[deprecated]] long double scalbl(long double " x ", long double " exp );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR scalb ():
.nf
_XOPEN_SOURCE >= 500
|| /* Since glibc 2.19: */ _DEFAULT_SOURCE
|| /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
.fi
-.PP
+.P
.BR scalbf (),
.BR scalbl ():
.nf
to the power of
.IR exp ,
that is:
-.PP
+.P
.nf
x * FLT_RADIX ** exp
.fi
-.PP
+.P
The definition of
.B FLT_RADIX
can be obtained by including
.B FLT_RADIX
**
.IR exp .
-.PP
+.P
If
.I x
or
.I exp
is a NaN, a NaN is returned.
-.PP
+.P
If
.I x
is positive infinity (negative infinity),
.I exp
is not negative infinity,
positive infinity (negative infinity) is returned.
-.PP
+.P
If
.I x
is +0 (\-0), and
.I exp
is not positive infinity, +0 (\-0) is returned.
-.PP
+.P
If
.I x
is zero, and
is positive infinity,
a domain error occurs, and
a NaN is returned.
-.PP
+.P
If
.I x
is an infinity,
is negative infinity,
a domain error occurs, and
a NaN is returned.
-.PP
+.P
If the result overflows,
a range error occurs,
and the functions return
.BR HUGE_VALL ,
respectively, with a sign the same as
.IR x .
-.PP
+.P
If the result underflows,
a range error occurs,
and the functions return zero, with a sign the same as
.BR math_error (7)
for information on how to determine whether an error has occurred
when calling these functions.
-.PP
+.P
The following errors can occur:
.TP
Domain error: \fIx\fP is 0, and \fIexp\fP is positive infinity, \
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "double scalbln(double " x ", long " exp );
.BI "float scalblnf(float " x ", long " exp );
.BI "long double scalblnl(long double " x ", long " exp );
-.PP
+.P
.BI "double scalbn(double " x ", int " exp );
.BI "float scalbnf(float " x ", int " exp );
.BI "long double scalbnl(long double " x ", int " exp );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR scalbln (),
.BR scalblnf (),
.BR scalblnl ():
_ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
|| /* Since glibc 2.19: */ _DEFAULT_SOURCE
.fi
-.PP
+.P
.BR scalbn (),
.BR scalbnf (),
.BR scalbnl ():
to the power of
.IR exp ,
that is:
-.PP
+.P
.nf
x * FLT_RADIX ** exp
.fi
-.PP
+.P
The definition of
.B FLT_RADIX
can be obtained by including
.B FLT_RADIX
**
.IR exp .
-.PP
+.P
If
.I x
is a NaN, a NaN is returned.
-.PP
+.P
If
.I x
is positive infinity (negative infinity),
positive infinity (negative infinity) is returned.
-.PP
+.P
If
.I x
is +0 (\-0), +0 (\-0) is returned.
-.PP
+.P
If the result overflows,
a range error occurs,
and the functions return
.BR HUGE_VALL ,
respectively, with a sign the same as
.IR x .
-.PP
+.P
If the result underflows,
a range error occurs,
and the functions return zero, with a sign the same as
.BR math_error (7)
for information on how to determine whether an error has occurred
when calling these functions.
-.PP
+.P
The following errors can occur:
.TP
Range error, overflow
.SH SYNOPSIS
.nf
.B #include <dirent.h>
-.PP
+.P
.BI "int scandir(const char *restrict " dirp ,
.BI " struct dirent ***restrict " namelist ,
.BI " int (*" filter ")(const struct dirent *),"
.BI " int (*" compar ")(const struct dirent **,"
.B " const struct dirent **));"
-.PP
+.P
.BI "int alphasort(const struct dirent **" a ", const struct dirent **" b );
.BI "int versionsort(const struct dirent **" a ", const struct dirent **" b );
-.PP
+.P
.BR "#include <fcntl.h>" " /* Definition of AT_* constants */"
.B #include <dirent.h>
-.PP
+.P
.BI "int scandirat(int " dirfd ", const char *restrict " dirp ,
.BI " struct dirent ***restrict " namelist ,
.BI " int (*" filter ")(const struct dirent *),"
.BI " int (*" compar ")(const struct dirent **,"
.B " const struct dirent **));"
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR scandir (),
.BR alphasort ():
.nf
/* Since glibc 2.10: */ _POSIX_C_SOURCE >= 200809L
|| /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
.fi
-.PP
+.P
.BR versionsort ():
.nf
_GNU_SOURCE
.fi
-.PP
+.P
.BR scandirat ():
.nf
_GNU_SOURCE
which is allocated via
.BR malloc (3).
If \fIfilter\fP is NULL, all entries are selected.
-.PP
+.P
The
.BR alphasort ()
and
function operates in exactly the same way as
.BR scandir (),
except for the differences described here.
-.PP
+.P
If the pathname given in
.I dirp
is relative, then it is interpreted relative to the directory
the calling process, as is done by
.BR scandir ()
for a relative pathname).
-.PP
+.P
If
.I dirp
is relative and
is interpreted relative to the current working
directory of the calling process (like
.BR scandir ()).
-.PP
+.P
If
.I dirp
is absolute, then
.I dirfd
is ignored.
-.PP
+.P
See
.BR openat (2)
for an explanation of the need for
On error, \-1 is returned, with
.I errno
set to indicate the error.
-.PP
+.P
The
.BR alphasort ()
and
.TP
.BR scandirat ()
glibc 2.15.
-.\" .LP
+.\" .P
.\" The functions
.\" .BR scandir ()
.\" and
.BR strcoll (3);
earlier it used
.BR strcmp (3).
-.PP
+.P
Before glibc 2.10, the two arguments of
.BR alphasort ()
and
.SH SYNOPSIS
.nf
.B #include <stdio.h>
-.PP
+.P
.BI "int scanf(const char *restrict " format ", ...);"
.BI "int fscanf(FILE *restrict " stream ,
.BI " const char *restrict " format ", ...);"
-.PP
+.P
.B #include <stdarg.h>
-.PP
+.P
.BI "int vscanf(const char *restrict " format ", va_list " ap );
.BI "int vfscanf(FILE *restrict " stream ,
.BI " const char *restrict " format ", va_list " ap );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR vscanf (),
.BR vfscanf ():
.nf
.BR sscanf (3)
or more specialized functions such as
.BR strtol (3).
-.PP
+.P
The
.BR scanf ()
function reads input from the standard input stream
.BR fscanf ()
reads input from the stream pointer
.IR stream .
-.PP
+.P
The
.BR vfscanf ()
function is analogous to
successfully matched and assigned;
this can be fewer than provided for,
or even zero, in the event of an early matching failure.
-.PP
+.P
The value
.B EOF
is returned if the end of input is reached before either the first
.SH SYNOPSIS
.nf
.B #include <sched.h>
-.PP
+.P
.B int sched_getcpu(void);
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR sched_getcpu ():
.nf
Since glibc 2.14:
glibc 2.6.
.SH NOTES
The call
-.PP
+.P
.in +4n
.EX
cpu = sched_getcpu();
.EE
.in
-.PP
+.P
is equivalent to the following
.BR getcpu (2)
call:
-.PP
+.P
.in +4n
.EX
int c, s;
.SH SYNOPSIS
.nf
.B #include <dirent.h>
-.PP
+.P
.BI "void seekdir(DIR *" dirp ", long " loc );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR seekdir ():
.nf
_XOPEN_SOURCE
.SH SYNOPSIS
.nf
.B #include <semaphore.h>
-.PP
+.P
.BI "int sem_close(sem_t *" sem );
.fi
.SH DESCRIPTION
.SH SYNOPSIS
.nf
.B #include <semaphore.h>
-.PP
+.P
.BI "int sem_destroy(sem_t *" sem );
.fi
.SH DESCRIPTION
.BR sem_destroy ()
destroys the unnamed semaphore at the address pointed to by
.IR sem .
-.PP
+.P
Only a semaphore that has been initialized by
.BR sem_init (3)
should be destroyed using
.BR sem_destroy ().
-.PP
+.P
Destroying a semaphore that other processes or threads are
currently blocked on (in
.BR sem_wait (3))
produces undefined behavior.
-.PP
+.P
Using a semaphore that has been destroyed produces undefined results,
until the semaphore has been reinitialized using
.BR sem_init (3).
.SH SYNOPSIS
.nf
.B #include <semaphore.h>
-.PP
+.P
.BI "int sem_getvalue(sem_t *restrict " sem ", int *restrict " sval );
.fi
.SH DESCRIPTION
.I sem
into the integer pointed to by
.IR sval .
-.PP
+.P
If one or more processes or threads are blocked
waiting to lock the semaphore with
.BR sem_wait (3),
.SH SYNOPSIS
.nf
.B #include <semaphore.h>
-.PP
+.P
.BI "int sem_init(sem_t *" sem ", int " pshared ", unsigned int " value );
.fi
.SH DESCRIPTION
The
.I value
argument specifies the initial value for the semaphore.
-.PP
+.P
The
.I pshared
argument indicates whether this semaphore is to be shared
between the threads of a process, or between processes.
-.PP
+.P
If
.I pshared
has the value 0,
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).
-.PP
+.P
If
.I pshared
is nonzero, then the semaphore is shared between processes,
.BR sem_post (3),
.BR sem_wait (3),
and so on.
-.PP
+.P
Initializing a semaphore that has already been initialized
results in undefined behavior.
.SH RETURN VALUE
POSIX.1-2008.
.SH HISTORY
POSIX.1-2001.
-.PP
+.P
Bizarrely, POSIX.1-2001 does not specify the value that should
be returned by a successful call to
.BR sem_init ().
.BR "#include <fcntl.h>" " /* For O_* constants */"
.BR "#include <sys/stat.h>" " /* For mode constants */"
.B #include <semaphore.h>
-.PP
+.P
.BI "sem_t *sem_open(const char *" name ", int " oflag );
.BI "sem_t *sem_open(const char *" name ", int " oflag ,
.BI " mode_t " mode ", unsigned int " value );
.IR name ,
see
.BR sem_overview (7).
-.PP
+.P
The
.I oflag
argument specifies flags that control the operation of the call.
then an error is returned if a semaphore with the given
.I name
already exists.
-.PP
+.P
If
.B O_CREAT
is specified in
.SH SYNOPSIS
.nf
.B #include <semaphore.h>
-.PP
+.P
.BI "int sem_post(sem_t *" sem );
.fi
.SH DESCRIPTION
.SH SYNOPSIS
.nf
.B #include <semaphore.h>
-.PP
+.P
.BI "int sem_unlink(const char *" name );
.fi
.SH DESCRIPTION
.SH SYNOPSIS
.nf
.B #include <semaphore.h>
-.PP
+.P
.BI "int sem_wait(sem_t *" sem );
.BI "int sem_trywait(sem_t *" sem );
.BI "int sem_timedwait(sem_t *restrict " sem ,
.BI " const struct timespec *restrict " abs_timeout );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR sem_timedwait ():
.nf
_POSIX_C_SOURCE >= 200112L
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.
-.PP
+.P
.BR sem_trywait ()
is the same as
.BR sem_wait (),
set to
.BR EAGAIN )
instead of blocking.
-.PP
+.P
.BR sem_timedwait ()
is the same as
.BR sem_wait (),
.BR timespec (3)
structure that specifies an absolute timeout
in seconds and nanoseconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC).
-.PP
+.P
If the timeout has already expired by the time of the call,
and the semaphore could not be locked immediately,
then
.RI ( errno
set to
.BR ETIMEDOUT ).
-.PP
+.P
If the operation can be performed immediately, then
.BR sem_timedwait ()
never fails with a timeout error, regardless of the value of
of the timeout, in seconds, for
.BR sem_timedwait ().
The following shows what happens on two different runs of the program:
-.PP
+.P
.in +4n
.EX
.RB "$" " ./a.out 2 3"
.SH SYNOPSIS
.nf
.B #include <aliases.h>
-.PP
+.P
.B "void setaliasent(void);"
.B "void endaliasent(void);"
-.PP
+.P
.B "struct aliasent *getaliasent(void);"
.BI "int getaliasent_r(struct aliasent *restrict " result ,
.BI " char " buffer "[restrict ." buflen "], \
size_t " buflen ,
.BI " struct aliasent **restrict " res );
-.PP
+.P
.BI "struct aliasent *getaliasbyname(const char *" name );
.BI "int getaliasbyname_r(const char *restrict " name ,
.BI " struct aliasent *restrict " result ,
(To find out which databases are supported, try
.IR "getent \-\-help" .)
Six functions are provided to access the aliases database.
-.PP
+.P
The
.BR 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.
-.PP
+.P
The
.BR setaliasent ()
function rewinds the file pointer to the beginning of the
aliases database.
-.PP
+.P
The
.BR endaliasent ()
function closes the aliases database.
-.PP
+.P
.BR 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.
-.PP
+.P
The function
.BR getaliasbyname ()
takes the name argument and searches the aliases database.
The entry is returned as a pointer to a
.IR "struct aliasent" .
-.PP
+.P
.BR 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.
-.PP
+.P
The
.I "struct aliasent"
is defined in
.IR <aliases.h> :
-.PP
+.P
.in +4n
.EX
struct aliasent {
GNU.
.SH HISTORY
The NeXT system has similar routines:
-.PP
+.P
.in +4n
.EX
#include <aliasdb.h>
The following example compiles with
.IR "gcc example.c \-o example" .
It will dump all names in the alias database.
-.PP
+.P
.\" SRC BEGIN (setaliasent.c)
.EX
#include <aliases.h>
.SH SYNOPSIS
.nf
.B #include <stdio.h>
-.PP
+.P
.BI "int setvbuf(FILE *restrict " stream ", char " buf "[restrict ." size ],
.BI " int " mode ", size_t " size );
-.PP
+.P
.BI "void setbuf(FILE *restrict " stream ", char *restrict " buf );
.BI "void setbuffer(FILE *restrict " stream ", char " buf "[restrict ." size ],
.BI " size_t " size );
.BI "void setlinebuf(FILE *" stream );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR setbuffer (),
.BR setlinebuf ():
.nf
may be used to force the block out early.
(See
.BR fclose (3).)
-.PP
+.P
Normally all files are block buffered.
If a stream refers to a terminal (as
.I stdout
The standard error stream
.I stderr
is always unbuffered by default.
-.PP
+.P
The
.BR setvbuf ()
function may be used on any open stream to change its buffer.
.B _IOFBF
fully buffered
.RE
-.PP
+.P
Except for unbuffered files, the
.I buf
argument should point to a buffer at least
.BR setvbuf ()
function may be used only after opening a stream and before any other
operations have been performed on it.
-.PP
+.P
The other three calls are, in effect, simply aliases for calls to
.BR setvbuf ().
The
.BR setbuf ()
function is exactly equivalent to the call
-.PP
+.P
.in +4n
setvbuf(stream, buf, buf ? _IOFBF : _IONBF, BUFSIZ);
.in
-.PP
+.P
The
.BR setbuffer ()
function is the same, except that the size of the buffer is up to the
The
.BR setlinebuf ()
function is exactly equivalent to the call:
-.PP
+.P
.in +4n
setvbuf(stream, NULL, _IOLBF, 0);
.in
It may set
.I errno
on failure.
-.PP
+.P
The other functions do not return a value.
.SH ATTRIBUTES
For an explanation of the terms used in this section, see
.\" On 4.2BSD and 4.3BSD systems,
.\" .BR setbuf ()
.\" always uses a suboptimal buffer size and should be avoided.
-.\".PP
+.\".P
You must make sure that the space that
.I buf
points to still exists by the time
.I stream
is closed, which also happens at program termination.
For example, the following is invalid:
-.PP
+.P
.\" [[invalid]] SRC BEGIN (setbuf.c)
.EX
#include <stdio.h>
.SH SYNOPSIS
.nf
.B #include <stdlib.h>
-.PP
+.P
.BI "int setenv(const char *" name ", const char *" value ", int " overwrite );
.BI "int unsetenv(const char *" name );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR setenv (),
.BR unsetenv ():
.nf
.I value
(by contrast with
.BR putenv (3)).
-.PP
+.P
The
.BR unsetenv ()
function deletes the variable
POSIX.1-2008.
.SH HISTORY
POSIX.1-2001, 4.3BSD.
-.PP
+.P
Prior to glibc 2.2.2,
.BR unsetenv ()
was prototyped
.SH SYNOPSIS
.nf
.B #include <setjmp.h>
-.PP
+.P
.BI "int setjmp(jmp_buf " env );
.BI "int sigsetjmp(sigjmp_buf " env ", int " savesigs );
-.PP
+.P
.BI "[[noreturn]] void longjmp(jmp_buf " env ", int " val );
.BI "[[noreturn]] void siglongjmp(sigjmp_buf " env ", int " val );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR setjmp ():
see NOTES.
-.PP
+.P
.BR sigsetjmp ():
.nf
_POSIX_C_SOURCE
will later be transferred, and
.BR longjmp ()
performs the transfer of execution.
-.PP
+.P
The
.BR setjmp ()
function saves various information about the calling environment
In this case,
.BR setjmp ()
returns 0.
-.PP
+.P
The
.BR longjmp ()
function uses the information saved in
may be restored to their state at the time of the
.BR setjmp ()
call.
-.PP
+.P
Following a successful
.BR longjmp (),
execution continues as if
.BR siglongjmp ()
also perform nonlocal gotos, but provide predictable handling of
the process signal mask.
-.PP
+.P
If, and only if, the
.I savesigs
argument provided to
the nonzero value specified in
.I val
is returned.
-.PP
+.P
The
.BR longjmp ()
or
.TQ
.BR siglongjmp ()
POSIX.1-2001.
-.PP
+.P
POSIX does not specify whether
.BR setjmp ()
will save the signal mask
.IP \[bu]
they are not declared as
.IR volatile .
-.PP
+.P
Analogous remarks apply for
.BR siglongjmp ().
.\"
call should employ a unique
.I jmp_buf
variable.)
-.PP
+.P
Adding further difficulty, the
.BR setjmp ()
and
.BR longjmp ()
calls may not even be in the same source code module.
-.PP
+.P
In summary, nonlocal gotos can make programs harder to understand
and maintain, and an alternative should be used if possible.
.\"
.BR longjmp ()
is called, the behavior is undefined.
Some kind of subtle or unsubtle chaos is sure to result.
-.PP
+.P
If, in a multithreaded program, a
.BR longjmp ()
call employs an
.\" (i.e., from a handler that was invoked in response to a signal that was
.\" generated while another signal was already in the process of being
.\" handled), the behavior is undefined.
-.PP
+.P
POSIX.1-2008 Technical Corrigendum 2 adds
.\" http://austingroupbugs.net/view.php?id=516#c1195
.BR longjmp ()
.SH SYNOPSIS
.nf
.B #include <locale.h>
-.PP
+.P
.BI "char *setlocale(int " category ", const char *" locale );
.fi
.SH DESCRIPTION
The
.BR setlocale ()
function is used to set or query the program's current locale.
-.PP
+.P
If
.I locale
is not NULL,
Formatting of date and time values
T}
.TE
-.PP
+.P
The categories marked with an asterisk in the above table
are GNU extensions.
For further information on these locale categories, see
.BR locale (7).
-.PP
+.P
The argument
.I locale
is a pointer to a character string containing the
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
.BR setlocale ().
-.PP
+.P
If
.I locale
is an empty string,
is unchanged, and
.BR setlocale ()
returns NULL.
-.PP
+.P
The locale
.B """C"""
or
.B """POSIX"""
is a portable locale;
it exists on all conforming systems.
-.PP
+.P
A locale name is typically of the form
.IR language "[_" territory "][." codeset "][@" modifier "],"
where
.BR "UTF\-8" .
For a list of all supported locales, try "locale \-a" (see
.BR locale (1)).
-.PP
+.P
If
.I locale
is NULL, the current locale is only queried, not modified.
-.PP
+.P
On startup of the main program, the portable
.B """C"""
locale is selected as default.
A program may be made portable to all locales by calling:
-.PP
+.P
.in +4n
.EX
setlocale(LC_ALL, "");
.EE
.in
-.PP
+.P
after program initialization, and then:
.IP \[bu] 3
using the values returned from a
.SH SYNOPSIS
.nf
.B #include <syslog.h>
-.PP
+.P
.BI "int setlogmask(int " mask );
.fi
.SH DESCRIPTION
bit set in
.IR mask .
The initial mask is such that logging is enabled for all priorities.
-.PP
+.P
The
.BR 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.
-.PP
+.P
The eight priorities are
.BR LOG_EMERG ,
.BR LOG_ALERT ,
.SH HISTORY
POSIX.1-2001.
.\" Note that the description in POSIX.1-2001 is flawed.
-.PP
+.P
.BR LOG_UPTO ()
will be included in the next release of the POSIX specification (Issue 8).
.\" FIXME . https://www.austingroupbugs.net/view.php?id=1033
.SH SYNOPSIS
.nf
.B #include <netdb.h>
-.PP
+.P
.BI "int setnetgrent(const char *" netgroup );
.B "void endnetgrent(void);"
-.PP
+.P
.BI "int getnetgrent(char **restrict " host ,
.BI " char **restrict " user ", char **restrict " domain );
.BI "int getnetgrent_r(char **restrict " host ,
.BI " char **restrict " user ", char **restrict " domain ,
.BI " char " buf "[restrict ." buflen "], size_t " buflen );
-.PP
+.P
.BI "int innetgr(const char *" netgroup ", const char *" host ,
.BI " const char *" user ", const char *" domain );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR \%setnetgrent (),
.BR \%endnetgrent (),
.BR \%getnetgrent (),
The file
.I /etc/nsswitch.conf
defines what database is searched.
-.PP
+.P
The
.BR setnetgrent ()
call defines the netgroup that will be searched by subsequent
that stores the strings in the supplied buffer.
To free all allocated buffers use
.BR endnetgrent ().
-.PP
+.P
In most cases you want to check only if the triplet
.RI ( hostname ", " username ", " domainname )
is a member of a netgroup.
race:netgrentbuf locale
T}
.TE
-.PP
+.P
In the above table,
.I netgrent
in
.B #include <sys/mman.h>
.BR "#include <sys/stat.h>" " /* For mode constants */"
.BR "#include <fcntl.h>" " /* For O_* constants */"
-.PP
+.P
.BI "int shm_open(const char *" name ", int " oflag ", mode_t " mode );
.BI "int shm_unlink(const char *" name );
.fi
function performs the converse operation,
removing an object previously created by
.BR shm_open ().
-.PP
+.P
The operation of
.BR shm_open ()
is analogous to that of
.\" case the subdirectory must exist under /dev/shm, and allow the
.\" required permissions if a user wants to create a shared memory
.\" object in that subdirectory.
-.PP
+.P
.I oflag
is a bit mask created by ORing together exactly one of
.B O_RDONLY
.TP
.B O_TRUNC
If the shared memory object already exists, truncate it to zero bytes.
-.PP
+.P
Definitions of these flag values can be obtained by including
.IR <fcntl.h> .
-.PP
+.P
On successful completion
.BR shm_open ()
returns a new file descriptor referring to the shared memory object.
flag (see
.BR fcntl (2))
is set for the file descriptor.
-.PP
+.P
The file descriptor is normally used in subsequent calls
to
.BR ftruncate (2)
After a call to
.BR mmap (2)
the file descriptor may be closed without affecting the memory mapping.
-.PP
+.P
The operation
of
.BR shm_unlink ()
unspecified.
On Linux, this will successfully truncate an existing
shared memory object\[em]this may not be so on other UNIX systems.
-.PP
+.P
The POSIX shared memory object implementation on Linux makes use
of a dedicated
.BR tmpfs (5)
.SH HISTORY
glibc 2.2.
POSIX.1-2001.
-.PP
+.P
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".
Once the data has been modified, the "send" program then prints
the contents of the modified shared memory.
An example execution of the two programs is the following:
-.PP
+.P
.in +4n
.EX
$ \fB./pshm_ucase_bounce /myshm &\fP
HELLO
.EE
.in
-.PP
+.P
Further detail about these programs is provided below.
.\"
.SS Program source: pshm_ucase.h
The following header file is included by both programs below.
Its primary purpose is to define a structure that will be imposed
on the memory object that is shared between the two programs.
-.PP
+.P
.in +4n
.\" SRC BEGIN (pshm_ucase.h)
.EX
structure defined in the header file.
It then maps the object into the process's address space,
and initializes two POSIX semaphores inside the object to 0.
-.PP
+.P
After the "send" program has posted the first of the semaphores,
the "bounce" program upper cases the data that has been placed
in the memory by the "send" program and then posts the second semaphore
to tell the "send" program that it may now access the shared memory.
-.PP
+.P
.in +4n
.\" SRC BEGIN (pshm_ucase_bounce.c)
.EX
The "send" program takes two command-line arguments:
the pathname of a shared memory object previously created by the "bounce"
program and a string that is to be copied into that object.
-.PP
+.P
The program opens the shared memory object
and maps the object into its address space.
It then copies the data specified in its second argument
After the "bounce" program posts the second semaphore,
the "send" program prints the contents of the shared memory
on standard output.
-.PP
+.P
.in +4n
.\" SRC BEGIN (pshm_ucase_send.c)
.EX
.SH SYNOPSIS
.nf
.B #include <signal.h>
-.PP
+.P
.BI "[[deprecated]] int siginterrupt(int " sig ", int " flag );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR siginterrupt ():
.nf
_XOPEN_SOURCE >= 500
argument is false (0), then system calls will be restarted if interrupted
by the specified signal \fIsig\fP.
This is the default behavior in Linux.
-.PP
+.P
If the \fIflag\fP argument is true (1) and no data has been transferred,
then a system call interrupted by the signal \fIsig\fP will return \-1
and \fIerrno\fP will be set to
.BR EINTR .
-.PP
+.P
If the \fIflag\fP 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.
.SH SYNOPSIS
.nf
.B "#include <math.h>"
-.PP
+.P
.BI "int signbit(" x ");"
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR signbit ():
.nf
_ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
It returns a nonzero value if the value of
.I x
has its sign bit set.
-.PP
+.P
This is not the same as
.IR "x < 0.0" ,
because IEEE 754 floating point allows zero to be signed.
is false, but
.I signbit(\-0.0)
will return a nonzero value.
-.PP
+.P
NaNs and infinities have a sign bit.
.SH RETURN VALUE
The
C11, POSIX.1-2008.
.SH HISTORY
POSIX.1-2001, C99.
-.PP
+.P
This function is defined in IEC 559 (and the appendix with
recommended functions in IEEE 754/IEEE 854).
.SH SEE ALSO
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "double significand(double " x );
.BI "float significandf(float " x );
.BI "long double significandl(long double " x );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR significand (),
.BR significandf (),
.BR significandl ():
.I x
scaled to the range [1,2).
They are equivalent to
-.PP
+.P
.in +4n
.EX
scalb(x, (double) \-ilogb(x))
.EE
.in
-.PP
+.P
This function exists mainly for use in certain standardized tests
for IEEE 754 conformance.
.SH ATTRIBUTES
.SH SYNOPSIS
.nf
.B #include <signal.h>
-.PP
+.P
.BI "[[deprecated]] int sigpause(int " sigmask "); /* BSD (but see NOTES) */"
-.PP
+.P
.BI "[[deprecated]] int sigpause(int " sig "); /* POSIX.1 / SysV / UNIX 95 */"
.fi
.SH DESCRIPTION
Use
.BR sigsuspend (2)
instead.
-.PP
+.P
The function
.BR sigpause ()
is designed to wait for some signal.
.SH VERSIONS
On Linux, this routine is a system call only on the Sparc (sparc64)
architecture.
-.PP
+.P
.\" Libc4 and libc5 know only about the BSD version.
.\"
glibc uses the BSD version if the
.\" || (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED)
.IP \[bu]
glibc 2.25 and earlier: _XOPEN_SOURCE
-.PP
+.P
Since glibc 2.19, only the System V version is exposed by
.IR <signal.h> ;
applications that formerly used the BSD
.SH HISTORY
POSIX.1-2001.
Obsoleted in POSIX.1-2008.
-.PP
+.P
The classical BSD version of this function appeared in 4.2BSD.
It sets the process's signal mask to
.IR sigmask .
.SH SYNOPSIS
.nf
.B #include <signal.h>
-.PP
+.P
.BI "int sigqueue(pid_t " pid ", int " sig ", const union sigval " value );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR sigqueue ():
.nf
_POSIX_C_SOURCE >= 199309L
.BR kill (2),
the null signal (0) can be used to check if a process with a given
PID exists.
-.PP
+.P
The
.I 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:
-.PP
+.P
.in +4n
.EX
union sigval {
};
.EE
.in
-.PP
+.P
If the receiving process has installed a handler for this signal using the
.B SA_SIGINFO
flag to
wrapper, this argument,
.IR uinfo ,
is initialized as follows:
-.PP
+.P
.in +4n
.EX
uinfo.si_signo = sig; /* Argument supplied to sigqueue() */
.SH SYNOPSIS
.nf
.B #include <signal.h>
-.PP
+.P
.B typedef void (*sighandler_t)(int);
-.PP
+.P
.BI "[[deprecated]] sighandler_t sigset(int " sig ", sighandler_t " disp );
-.PP
+.P
.BI "[[deprecated]] int sighold(int " sig );
.BI "[[deprecated]] int sigrelse(int " sig );
.BI "[[deprecated]] int sigignore(int " sig );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR sigset (),
.BR sighold (),
.BR sigrelse (),
.RB ( sigaction (2),
.BR sigprocmask (2),
etc.)
-.PP
+.P
The
.BR sigset ()
function modifies the disposition of the signal
to the process's signal mask, but leave the disposition of
.I sig
unchanged.
-.PP
+.P
If
.I disp
specifies the address of a signal handler, then
.I sig
is added to the process's signal mask during execution of the handler.
-.PP
+.P
If
.I disp
was specified as a value other than
then
.I sig
is removed from the process's signal mask.
-.PP
+.P
The dispositions for
.B SIGKILL
and
.B SIGSTOP
cannot be changed.
-.PP
+.P
The
.BR sighold ()
function adds
.I sig
to the calling process's signal mask.
-.PP
+.P
The
.BR sigrelse ()
function removes
.I sig
from the calling process's signal mask.
-.PP
+.P
The
.BR sigignore ()
function sets the disposition of
.I errno
set to indicate the error.
(But see BUGS below.)
-.PP
+.P
The
.BR sighold (),
.BR sigrelse (),
.BR sigaction (2)
and
.BR sigprocmask (2).
-.PP
+.P
For
.BR sighold ()
and
.BR sigrelse ()
see the ERRORS under
.BR sigprocmask (2).
-.PP
+.P
For
.BR sigignore (),
see the errors under
with
.I sa_mask
equal to 0).
-.PP
+.P
On System V, the
.BR signal ()
function provides unreliable semantics (as when calling
See
.BR signal (2)
for further details.
-.PP
+.P
In order to wait for a signal,
BSD and System V both provided a function named
.BR sigpause (3),
.I disp
was specified as a value other than
.BR SIG_HOLD .
-.PP
+.P
Before glibc 2.5,
.BR sigset ()
does not correctly return the previous disposition of the signal
.SH SYNOPSIS
.nf
.B #include <signal.h>
-.PP
+.P
.BI "int sigemptyset(sigset_t *" set );
.BI "int sigfillset(sigset_t *" set );
-.PP
+.P
.BI "int sigaddset(sigset_t *" set ", int " signum );
.BI "int sigdelset(sigset_t *" set ", int " signum );
-.PP
+.P
.BI "int sigismember(const sigset_t *" set ", int " signum );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR sigemptyset (),
.BR sigfillset (),
.BR sigaddset (),
.fi
.SH DESCRIPTION
These functions allow the manipulation of POSIX signal sets.
-.PP
+.P
.BR sigemptyset ()
initializes the signal set given by
.I set
to empty, with all signals excluded from the set.
-.PP
+.P
.BR sigfillset ()
initializes
.I set
to full, including all signals.
-.PP
+.P
.BR sigaddset ()
and
.BR sigdelset ()
.I signum
from
.IR set .
-.PP
+.P
.BR sigismember ()
tests whether
.I signum
is a member of
.IR set .
-.PP
+.P
Objects of type
.I sigset_t
must be initialized by a call to either
and
.BR sigdelset ()
return 0 on success and \-1 on error.
-.PP
+.P
.BR sigismember ()
returns 1 if
.I signum
0 if
.I signum
is not a member, and \-1 on error.
-.PP
+.P
On error, these functions set
.I errno
to indicate the error.
feature test macro is defined, then \fI<signal.h>\fP
exposes three other functions for manipulating signal
sets:
-.PP
+.P
.nf
.BI "int sigisemptyset(const sigset_t *" set );
.BI "int sigorset(sigset_t *" dest ", const sigset_t *" left ,
.BI "int sigandset(sigset_t *" dest ", const sigset_t *" left ,
.BI " const sigset_t *" right );
.fi
-.PP
+.P
.BR sigisemptyset ()
returns 1 if
.I set
contains no signals, and 0 otherwise.
-.PP
+.P
.BR sigorset ()
places the union of the sets
.I left
in
.IR dest .
Both functions return 0 on success, and \-1 on failure.
-.PP
+.P
These functions are nonstandard (a few other systems provide similar
functions) and their use should be avoided in portable applications.
.SH STANDARDS
.SH SYNOPSIS
.nf
.B #include <signal.h>
-.PP
+.P
.BI "[[deprecated]] int sigvec(int " sig ", const struct sigvec *" vec ,
.BI " struct sigvec *" ovec );
-.PP
+.P
.BI "[[deprecated]] int sigmask(int " signum );
-.PP
+.P
.BI "[[deprecated]] int sigblock(int " mask );
.BI "[[deprecated]] int sigsetmask(int " mask );
.B [[deprecated]] int siggetmask(void);
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
All functions shown above:
.nf
Since glibc 2.19:
.RB ( sigaction (2),
.BR sigprocmask (2),
etc.).
-.PP
+.P
The
.BR sigvec ()
function sets and/or gets the disposition of the signal
.IR vec ,
and a non-null pointer for
.IR ovec .
-.PP
+.P
The dispositions for
.B SIGKILL
and
.B SIGSTOP
cannot be changed.
-.PP
+.P
The
.I sigvec
structure has the following form:
-.PP
+.P
.in +4n
.EX
struct sigvec {
};
.EE
.in
-.PP
+.P
The
.I sv_handler
field specifies the disposition of the signal, and is either:
meaning the default disposition applies for the signal; or
.BR SIG_IGN ,
meaning that the signal is ignored.
-.PP
+.P
If
.I sv_handler
specifies the address of a signal handler, then
or
.B SIGSTOP
are silently ignored.
-.PP
+.P
If
.I sv_handler
specifies the address of a signal handler, then the
.BR sigstack ()
function; the POSIX replacement is
.BR sigaltstack (2)).
-.PP
+.P
The
.BR sigmask ()
macro constructs and returns a "signal mask" for
field given to
.BR sigvec ()
using code such as the following:
-.PP
+.P
.in +4n
.EX
vec.sv_mask = sigmask(SIGQUIT) | sigmask(SIGABRT);
handler execution */
.EE
.in
-.PP
+.P
The
.BR sigblock ()
function adds the signals in
or
.B SIGSTOP
are silently ignored.
-.PP
+.P
The
.BR sigsetmask ()
function sets the process's signal mask to the value given in
(like POSIX
.IR sigprocmask(SIG_SETMASK) ),
and returns the process's previous signal mask.
-.PP
+.P
The
.BR siggetmask ()
function returns the process's current signal mask.
function returns 0 on success; on error, it returns \-1 and sets
.I errno
to indicate the error.
-.PP
+.P
The
.BR sigblock ()
and
.BR sigsetmask ()
functions return the previous signal mask.
-.PP
+.P
The
.BR sigmask ()
macro returns the signal mask for
See
.BR signal (2)
for further details.
-.PP
+.P
In order to wait for a signal,
BSD and System V both provided a function named
.BR sigpause (3),
.SH SYNOPSIS
.nf
.B #include <signal.h>
-.PP
+.P
.BI "int sigwait(const sigset_t *restrict " set ", int *restrict " sig );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR sigwait ():
.nf
Since glibc 2.26:
(removes it from the pending list of signals),
and returns the signal number in
.IR sig .
-.PP
+.P
The operation of
.BR sigwait ()
is the same as
.BR sigwait ()
is implemented using
.BR sigtimedwait (2).
-.PP
+.P
The glibc implementation of
.BR sigwait ()
silently ignores attempts to wait for the two real-time signals that
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "double sin(double " x );
.BI "float sinf(float " x );
.BI "long double sinl(long double " x );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR sinf (),
.BR sinl ():
.nf
.SH RETURN VALUE
On success, these functions return the sine of
.IR x .
-.PP
+.P
If
.I x
is a NaN, a NaN is returned.
-.PP
+.P
If
.I x
is positive infinity or negative infinity,
.BR math_error (7)
for information on how to determine whether an error has occurred
when calling these functions.
-.PP
+.P
The following errors can occur:
.TP
Domain error: \fIx\fP is an infinity
C11, POSIX.1-2008.
.SH HISTORY
C99, POSIX.1-2001.
-.PP
+.P
The variant returning
.I double
also conforms to
.nf
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <math.h>
-.PP
+.P
.BI "void sincos(double " x ", double *" sin ", double *" cos );
.BI "void sincosf(float " x ", float *" sin ", float *" cos );
.BI "void sincosl(long double " x ", long double *" sin ", long double *" cos );
.BR sin (3)
and
.BR cos (3).
-.PP
+.P
If
.I x
is a NaN,
.I *sin
and
.IR *cos .
-.PP
+.P
If
.I x
is positive infinity or negative infinity,
.BR math_error (7)
for information on how to determine whether an error has occurred
when calling these functions.
-.PP
+.P
The following errors can occur:
.TP
Domain error: \fIx\fP is an infinity
it may be necessary to disable
.BR gcc (1)
built-in optimizations, using flags such as:
-.PP
+.P
.in +4n
.EX
cc \-O \-lm \-fno\-builtin prog.c
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "double sinh(double " x );
.BI "float sinhf(float " x );
.BI "long double sinhl(long double " x );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR sinhf (),
.BR sinhl ():
.nf
.IR x ,
which
is defined mathematically as:
-.PP
+.P
.nf
sinh(x) = (exp(x) \- exp(\-x)) / 2
.fi
.SH RETURN VALUE
On success, these functions return the hyperbolic sine of
.IR x .
-.PP
+.P
If
.I x
is a NaN, a NaN is returned.
-.PP
+.P
If
.I x
is +0 (\-0), +0 (\-0) is returned.
-.PP
+.P
If
.I x
is positive infinity (negative infinity),
positive infinity (negative infinity) is returned.
-.PP
+.P
If the result overflows,
a range error occurs,
and the functions return
.BR math_error (7)
for information on how to determine whether an error has occurred
when calling these functions.
-.PP
+.P
The following errors can occur:
.TP
Range error: result overflow
C11, POSIX.1-2008.
.SH HISTORY
C99, POSIX.1-2001.
-.PP
+.P
The variant returning
.I double
also conforms to
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.BI "unsigned int sleep(unsigned int " "seconds" );
.fi
.SH DESCRIPTION
See the
.BR nanosleep (2)
man page for a discussion of the clock used.
-.PP
+.P
On some systems,
.BR sleep ()
may be implemented using
.SH SYNOPSIS
.nf
.B #include <sys/queue.h>
-.PP
+.P
.B SLIST_ENTRY(TYPE);
-.PP
+.P
.B SLIST_HEAD(HEADNAME, TYPE);
.BI "SLIST_HEAD SLIST_HEAD_INITIALIZER(SLIST_HEAD " head );
.BI "void SLIST_INIT(SLIST_HEAD *" head );
-.PP
+.P
.BI "int SLIST_EMPTY(SLIST_HEAD *" head );
-.PP
+.P
.BI "void SLIST_INSERT_HEAD(SLIST_HEAD *" head ,
.BI " struct TYPE *" elm ", SLIST_ENTRY " NAME );
.BI "void SLIST_INSERT_AFTER(struct TYPE *" listelm ,
.BI " struct TYPE *" elm ", SLIST_ENTRY " NAME );
-.PP
+.P
.BI "struct TYPE *SLIST_FIRST(SLIST_HEAD *" head );
.BI "struct TYPE *SLIST_NEXT(struct TYPE *" elm ", SLIST_ENTRY " NAME );
-.PP
+.P
.BI "SLIST_FOREACH(struct TYPE *" var ", SLIST_HEAD *" head ", SLIST_ENTRY " NAME );
.\" .BI "SLIST_FOREACH_FROM(struct TYPE *" var ", SLIST_HEAD *" head ,
.\" .BI " SLIST_ENTRY " NAME );
-.\" .PP
+.\" .P
.\" .BI "SLIST_FOREACH_SAFE(struct TYPE *" var ", SLIST_HEAD *" head ,
.\" .BI " SLIST_ENTRY " NAME ", struct TYPE *" temp_var );
.\" .BI "SLIST_FOREACH_FROM_SAFE(struct TYPE *" var ", SLIST_HEAD *" head ,
.\" .BI " SLIST_ENTRY " NAME ", struct TYPE *" temp_var );
-.PP
+.P
.BI "void SLIST_REMOVE(SLIST_HEAD *" head ", struct TYPE *" elm ,
.BI " SLIST_ENTRY " NAME );
.BI "void SLIST_REMOVE_HEAD(SLIST_HEAD *" head ,
.BI " SLIST_ENTRY " NAME );
.\" .BI "void SLIST_REMOVE_AFTER(struct TYPE *" elm ,
.\" .BI " SLIST_ENTRY " NAME );
-.\" .PP
+.\" .P
.\" .BI "void SLIST_SWAP(SLIST_HEAD *" head1 ", SLIST_HEAD *" head2 ,
.\" .BI " SLIST_ENTRY " NAME );
.fi
.SH DESCRIPTION
These macros define and operate on doubly linked lists.
-.PP
+.P
In the macro definitions,
.I TYPE
is the name of a user-defined structure,
An
.I SLIST_HEAD
structure is declared as follows:
-.PP
+.P
.in +4
.EX
SLIST_HEAD(HEADNAME, TYPE) head;
.EE
.in
-.PP
+.P
where
.I struct HEADNAME
is the structure to be defined, and
.I struct 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:
-.PP
+.P
.in +4
.EX
struct HEADNAME *headp;
.EE
.in
-.PP
+.P
(The names
.I head
and
.I headp
are user selectable.)
-.PP
+.P
.BR SLIST_ENTRY ()
declares a structure that connects the elements in
the list.
-.PP
+.P
.BR SLIST_HEAD_INITIALIZER ()
evaluates to an initializer for the list
.IR head .
-.PP
+.P
.BR SLIST_INIT ()
initializes the list referenced by
.IR head .
-.PP
+.P
.BR SLIST_EMPTY ()
evaluates to true if there are no elements in the list.
.SS Insertion
inserts the new element
.I elm
at the head of the list.
-.PP
+.P
.BR SLIST_INSERT_AFTER ()
inserts the new element
.I elm
.SS Traversal
.BR SLIST_FIRST ()
returns the first element in the list, or NULL if the list is empty.
-.PP
+.P
.BR SLIST_NEXT ()
returns the next element in the list.
-.PP
+.P
.BR SLIST_FOREACH ()
traverses the list referenced by
.I head
in the forward direction,
assigning each element in turn to
.IR var .
-.\" .PP
+.\" .P
.\" .BR SLIST_FOREACH_FROM ()
.\" behaves identically to
.\" .BR SLIST_FOREACH ()
.\" .I var
.\" as well as free it from within the loop safely without interfering with the
.\" traversal.
-.\" .PP
+.\" .P
.\" .BR SLIST_FOREACH_FROM_SAFE ()
.\" behaves identically to
.\" .BR SLIST_FOREACH_SAFE ()
removes the element
.I elm
from the list.
-.PP
+.P
.BR SLIST_REMOVE_HEAD ()
removes the element
.I elm
elements being removed from the head of the list
should explicitly use this macro instead of the generic
.BR SLIST_REMOVE ().
-.\" .PP
+.\" .P
.\" .BR SLIST_REMOVE_AFTER ()
.\" removes the element after
.\" .I elm
.BR SLIST_EMPTY ()
returns nonzero if the list is empty,
and zero if the list contains at least one entry.
-.PP
+.P
.BR SLIST_FIRST (),
and
.BR SLIST_NEXT ()
return a pointer to the first or next
.I TYPE
structure, respectively.
-.PP
+.P
.BR SLIST_HEAD_INITIALIZER ()
returns an initializer that can be assigned to the list
.IR head .
.SH SYNOPSIS
.nf
.B #include <sys/socket.h>
-.PP
+.P
.BI "int sockatmark(int " sockfd );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR sockatmark ():
.nf
_POSIX_C_SOURCE >= 200112L
.B MSG_OOB
flag of
.BR recv (2).
-.PP
+.P
Out-of-band data is supported only on some stream socket protocols.
-.PP
+.P
.BR sockatmark ()
can safely be called from a handler for the
.B SIGURG
signal.
-.PP
+.P
.BR sockatmark ()
is implemented using the
.B SIOCATMARK
.B SIGURG
signal to read (and discard) all data up to the mark,
and then read the byte of data at the mark:
-.PP
+.P
.EX
char buf[BUF_LEN];
char oobdata;
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "double sqrt(double " x );
.BI "float sqrtf(float " x );
.BI "long double sqrtl(long double " x );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR sqrtf (),
.BR sqrtl ():
.nf
.SH RETURN VALUE
On success, these functions return the square root of
.IR x .
-.PP
+.P
If
.I x
is a NaN, a NaN is returned.
-.PP
+.P
If
.I x
is +0 (\-0), +0 (\-0) is returned.
-.PP
+.P
If
.I x
is positive infinity, positive infinity is returned.
-.PP
+.P
If
.I x
is less than \-0,
.BR math_error (7)
for information on how to determine whether an error has occurred
when calling these functions.
-.PP
+.P
The following errors can occur:
.TP
Domain error: \fIx\fP less than \-0
C11, POSIX.1-2008.
.SH HISTORY
C99, POSIX.1-2001.
-.PP
+.P
The variant returning
.I double
also conforms to
.SH SYNOPSIS
.nf
.B #include <stdio.h>
-.PP
+.P
.BI "int sscanf(const char *restrict " str ,
.BI " const char *restrict " format ", ...);"
-.PP
+.P
.B #include <stdarg.h>
-.PP
+.P
.BI "int vsscanf(const char *restrict " str ,
.BI " const char *restrict " format ", va_list " ap );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR vsscanf ():
.nf
_ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
.I pointer
argument must be of a type that is appropriate for the value returned
by the corresponding conversion specification.
-.PP
+.P
If the number of conversion specifications in
.I format
exceeds the number of
arguments exceeds the number of conversion specifications, then the excess
.I pointer
arguments are evaluated, but are otherwise ignored.
-.PP
+.P
.BR sscanf ()
These functions
read their input from the string pointed to by
.IR str .
-.PP
+.P
The
.BR vsscanf ()
function is analogous to
.BR vsprintf (3).
-.PP
+.P
The
.I format
string consists of a sequence of
meaning that input characters were unavailable, or
.IR "matching failure" ,
meaning that the input was inappropriate (see below).
-.PP
+.P
A directive is one of the following:
.TP
\[bu]
If the next item of input does not match the conversion specification,
the conversion fails\[em]this is a
.IR "matching failure" .
-.PP
+.P
Each
.I conversion specification
in
A
.I "conversion specifier"
that specifies the type of input conversion to be performed.
-.PP
+.P
The conversion specifications in
.I format
are of two forms, either beginning with \[aq]%\[aq] or beginning with
but the next pointer is a pointer to a
.IR size_t .
This modifier was introduced in C99.
-.PP
+.P
The following
.I "conversion specifiers"
are available:
successfully matched and assigned;
this can be fewer than provided for,
or even zero, in the event of an early matching failure.
-.PP
+.P
The value
.B EOF
is returned if the end of input is reached before either the first
C11, POSIX.1-2008.
.SH HISTORY
C89, POSIX.1-2001.
-.PP
+.P
The
.B q
specifier is the 4.4BSD notation for
or the usage of
.B L
in integer conversions is the GNU notation.
-.PP
+.P
The Linux version of these functions is based on the
.I GNU
.I libio
allocate a buffer for a string,
with a pointer to that buffer being returned in
.IR *buf :
-.PP
+.P
.in +4n
.EX
char *buf;
sscanf(str, "%as", &buf);
.EE
.in
-.PP
+.P
The use of the letter
.B a
for this purpose was problematic, since
POSIX.1-2008 instead specifies the
.B m
modifier for assignment allocation (as documented in DESCRIPTION, above).
-.PP
+.P
Note that the
.B a
modifier is not available if the program is compiled with
is also specified), in which case the
.B a
is interpreted as a specifier for floating-point numbers (see above).
-.PP
+.P
Support for the
.B m
modifier was added to glibc 2.7,
and new programs should use that modifier instead of
.BR a .
-.PP
+.P
As well as being standardized by POSIX, the
.B m
modifier has the following further advantages over
modifiers.
The latter may be considered to be a bug, as it changes the
behavior of modifiers defined in C99.
-.PP
+.P
Some combinations of the type modifiers and conversion
specifiers defined by C99 do not make sense
(e.g.,
\fBd\fP, \fBi\fP, \fBo\fP, \fBu\fP, \fBx\fP, and \fBX\fP
conversions or
.BR ll .
-.PP
+.P
The usage of
.B q
is not the same as on 4.4BSD,
The caller must
.BR free (3)
the returned string, as in the following example:
-.PP
+.P
.in +4n
.EX
char *p;
}
.EE
.in
-.PP
+.P
As shown in the above example, it is necessary to call
.BR free (3)
only if the
.SH SYNOPSIS
.nf
.B #include <sys/queue.h>
-.PP
+.P
.B STAILQ_ENTRY(TYPE);
-.PP
+.P
.B STAILQ_HEAD(HEADNAME, TYPE);
.BI "STAILQ_HEAD STAILQ_HEAD_INITIALIZER(STAILQ_HEAD " head );
.BI "void STAILQ_INIT(STAILQ_HEAD *" head );
-.PP
+.P
.BI "int STAILQ_EMPTY(STAILQ_HEAD *" head );
-.PP
+.P
.BI "void STAILQ_INSERT_HEAD(STAILQ_HEAD *" head ,
.BI " struct TYPE *" elm ", STAILQ_ENTRY " NAME );
.BI "void STAILQ_INSERT_TAIL(STAILQ_HEAD *" head ,
.BI " struct TYPE *" elm ", STAILQ_ENTRY " NAME );
.BI "void STAILQ_INSERT_AFTER(STAILQ_HEAD *" head ", struct TYPE *" listelm ,
.BI " struct TYPE *" elm ", STAILQ_ENTRY " NAME );
-.PP
+.P
.BI "struct TYPE *STAILQ_FIRST(STAILQ_HEAD *" head );
.\" .BI "struct TYPE *STAILQ_LAST(STAILQ_HEAD *" head ", struct TYPE *" elm ,
.\" .BI " STAILQ_ENTRY " NAME );
.BI "struct TYPE *STAILQ_NEXT(struct TYPE *" elm ", STAILQ_ENTRY " NAME );
-.PP
+.P
.BI "STAILQ_FOREACH(struct TYPE *" var ", STAILQ_HEAD *" head ", STAILQ_ENTRY " NAME );
.\" .BI "STAILQ_FOREACH_FROM(struct TYPE *" var ", STAILQ_HEAD *" head ,
.\" .BI " STAILQ_ENTRY " NAME );
-.\" .PP
+.\" .P
.\" .BI "STAILQ_FOREACH_SAFE(struct TYPE *" var ", STAILQ_HEAD *" head ,
.\" .BI " STAILQ_ENTRY " NAME ", struct TYPE *" temp_var );
.\" .BI "STAILQ_FOREACH_FROM_SAFE(struct TYPE *" var ", STAILQ_HEAD *" head ,
.\" .BI " STAILQ_ENTRY " NAME ", struct TYPE *" temp_var );
-.PP
+.P
.BI "void STAILQ_REMOVE(STAILQ_HEAD *" head ", struct TYPE *" elm ", TYPE,"
.BI " STAILQ_ENTRY " NAME );
.BI "void STAILQ_REMOVE_HEAD(STAILQ_HEAD *" head ,
.BI " STAILQ_ENTRY " NAME );
.\" .BI "void STAILQ_REMOVE_AFTER(STAILQ_HEAD *" head ", struct TYPE *" elm ,
.\" .BI " STAILQ_ENTRY " NAME );
-.PP
+.P
.BI "void STAILQ_CONCAT(STAILQ_HEAD *" head1 ", STAILQ_HEAD *" head2 );
.\" .BI "void STAILQ_SWAP(STAILQ_HEAD *" head1 ", STAILQ_HEAD *" head2 ,
.\" .BI " STAILQ_ENTRY " NAME );
Identical macros prefixed with SIMPLEQ instead of STAILQ exist; see NOTES.
.SH DESCRIPTION
These macros define and operate on singly linked tail queues.
-.PP
+.P
In the macro definitions,
.I TYPE
is the name of a user-defined structure,
A
.I STAILQ_HEAD
structure is declared as follows:
-.PP
+.P
.in +4
.EX
STAILQ_HEAD(HEADNAME, TYPE) head;
.EE
.in
-.PP
+.P
where
.I struct HEADNAME
is the structure to be defined, and
.I struct 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:
-.PP
+.P
.in +4
.EX
struct HEADNAME *headp;
.EE
.in
-.PP
+.P
(The names
.I head
and
.I headp
are user selectable.)
-.PP
+.P
.BR STAILQ_ENTRY ()
declares a structure that connects the elements in the tail queue.
-.PP
+.P
.BR STAILQ_HEAD_INITIALIZER ()
evaluates to an initializer for the tail queue
.IR head .
-.PP
+.P
.BR STAILQ_INIT ()
initializes the tail queue referenced by
.IR head .
-.PP
+.P
.BR STAILQ_EMPTY ()
evaluates to true if there are no items on the tail queue.
.SS Insertion
inserts the new element
.I elm
at the head of the tail queue.
-.PP
+.P
.BR STAILQ_INSERT_TAIL ()
inserts the new element
.I elm
at the end of the tail queue.
-.PP
+.P
.BR STAILQ_INSERT_AFTER ()
inserts the new element
.I elm
.SS Traversal
.BR STAILQ_FIRST ()
returns the first item on the tail queue or NULL if the tail queue is empty.
-.\" .PP
+.\" .P
.\" .BR STAILQ_LAST ()
.\" returns the last item on the tail queue.
.\" If the tail queue is empty the return value is NULL .
-.PP
+.P
.BR STAILQ_NEXT ()
returns the next item on the tail queue, or NULL this item is the last.
-.PP
+.P
.BR STAILQ_FOREACH ()
traverses the tail queue referenced by
.I head
in the forward direction,
assigning each element in turn to
.IR var .
-.\" .PP
+.\" .P
.\" .BR STAILQ_FOREACH_FROM ()
.\" behaves identically to
.\" .BR STAILQ_FOREACH ()
.\" .I var
.\" instead of the first element in the STAILQ referenced by
.\" .IR head .
-.\" .PP
+.\" .P
.\" .BR STAILQ_FOREACH_SAFE ()
.\" traverses the tail queue referenced by
.\" .I head
.\" .I var
.\" as well as free it from within the loop safely without interfering with the
.\" traversal.
-.\" .PP
+.\" .P
.\" .BR STAILQ_FOREACH_FROM_SAFE ()
.\" behaves identically to
.\" .BR STAILQ_FOREACH_SAFE ()
removes the element
.I elm
from the tail queue.
-.PP
+.P
.BR STAILQ_REMOVE_HEAD ()
removes the element at the head of the tail queue.
For optimum efficiency,
use this macro explicitly rather than the generic
.BR STAILQ_REMOVE ()
macro.
-.\" .PP
+.\" .P
.\" .BR STAILQ_REMOVE_AFTER ()
.\" removes the element after
.\" .I elm
onto the end of the one headed by
.I head1
removing all entries from the former.
-.\" .PP
+.\" .P
.\" .BR STAILQ_SWAP ()
.\" swaps the contents of
.\" .I head1
.BR STAILQ_EMPTY ()
returns nonzero if the queue is empty,
and zero if the queue contains at least one entry.
-.PP
+.P
.BR STAILQ_FIRST (),
and
.BR STAILQ_NEXT ()
return a pointer to the first or next
.I TYPE
structure, respectively.
-.PP
+.P
.BR STAILQ_HEAD_INITIALIZER ()
returns an initializer that can be assigned to the queue
.IR head .
.SH SYNOPSIS
.nf
.B #include <assert.h>
-.PP
+.P
.BI "void static_assert(scalar " constant-expression ", const char *" msg );
-.PP
+.P
/* Since C23: */
.BI "void static_assert(scalar " constant-expression );
.fi
but it works at compile time,
generating a compilation error (with an optional message)
when the input is false (i.e., compares equal to zero).
-.PP
+.P
If the input is nonzero,
no code is emitted.
-.PP
+.P
.I msg
must be a string literal.
Since C23, this argument is optional.
-.PP
+.P
There's a keyword,
.BR \%_Static_assert (),
that behaves identically,
can be written in terms of
.BR \%static_assert ().
The following program uses the macro to get the size of an array safely.
-.PP
+.P
.in +4n
.\" SRC BEGIN (must_be.c)
.EX
.SH SYNOPSIS
.nf
.B #include <sys/statvfs.h>
-.PP
+.P
.BI "int statvfs(const char *restrict " path \
", struct statvfs *restrict " buf );
.BI "int fstatvfs(int " fd ", struct statvfs *" buf );
is a pointer to a
.I statvfs
structure defined approximately as follows:
-.PP
+.P
.in +4n
.EX
struct statvfs {
};
.EE
.in
-.PP
+.P
Here the types
.I fsblkcnt_t
and
.IR <sys/types.h> .
Both used to be
.IR "unsigned long" .
-.PP
+.P
The field
.I f_flag
is a bit mask indicating various options that were employed
.B O_SYNC
in
.BR open (2)).
-.PP
+.P
It is unspecified whether all members of the returned struct
have meaningful values on all filesystems.
-.PP
+.P
.BR fstatvfs ()
returns the same information about an open file referenced by descriptor
.IR fd .
and
.BR fstatfs (2)
to support this library call.
-.PP
+.P
The glibc implementations of
-.PP
+.P
.in +4n
.EX
pathconf(path, _PC_REC_XFER_ALIGN);
pathconf(path, _PC_REC_MIN_XFER_SIZE);
.EE
.in
-.PP
+.P
respectively use the
.IR f_frsize ,
.IR f_frsize ,
.BR statvfs ()
with the argument
.IR path .
-.PP
+.P
Under Linux,
.I f_favail
is always the same as
POSIX.1-2008.
.SH HISTORY
POSIX.1-2001.
-.PP
+.P
Before glibc 2.13,
.\" glibc commit 3cdaa6adb113a088fdfb87aa6d7747557eccc58d
.BR statvfs ()
.SH SYNOPSIS
.nf
.B #include <stdarg.h>
-.PP
+.P
.BI "void va_start(va_list " ap ", " last );
.IB type " va_arg(va_list " ap ", " type );
.BI "void va_end(va_list " ap );
.I va_list
and defines three macros for stepping through a list of arguments whose
number and types are not known to the called function.
-.PP
+.P
The called function must declare an object of type
.I va_list
which is used by the macros
and
.BR va_end (),
and must be called first.
-.PP
+.P
The argument
.I 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.
-.PP
+.P
Because the address of this argument may be used in the
.BR va_start ()
macro, it should not be declared as a register variable,
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
.IR type .
-.PP
+.P
The first use of the
.BR va_arg ()
macro after that of the
macro returns the argument after
.IR last .
Successive invocations return the values of the remaining arguments.
-.PP
+.P
If there is no next argument, or if
.I type
is not compatible with the type of the actual next argument (as promoted
according to the default argument promotions), random errors will occur.
-.PP
+.P
If
.I ap
is passed to a function that uses
.BR va_arg ()
invocations that was used to reach the current state of
.IR src .
-.PP
+.P
.\" Proposal from clive@demon.net, 1997-02-28
An obvious implementation would have a
.I 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
-.PP
+.P
.in +4n
.EX
va_list aq = ap;
.EE
.in
-.PP
+.P
Unfortunately, there are also systems that make it an
array of pointers (of length 1), and there one needs
-.PP
+.P
.in +4n
.EX
va_list aq;
*aq = *ap;
.EE
.in
-.PP
+.P
Finally, on systems where arguments are passed in registers,
it may be necessary for
.BR va_start ()
To accommodate this situation, C99 adds a macro
.BR va_copy (),
so that the above assignment can be replaced by
-.PP
+.P
.in +4n
.EX
va_list aq;
va_end(aq);
.EE
.in
-.PP
+.P
Each invocation of
.BR va_copy ()
must be matched by a corresponding invocation of
.I foo
takes a string of format characters and prints out the argument associated
with each format character based on the type.
-.PP
+.P
.EX
#include <stdio.h>
#include <stdarg.h>
.SH SYNOPSIS
.nf
.B #include <stdio.h>
-.PP
+.P
.BI "extern FILE *" stdin ;
.BI "extern FILE *" stdout ;
.BI "extern FILE *" stderr ;
the parent process chose to set up.
(See also the "Redirection" section of
.BR sh (1).)
-.PP
+.P
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".
.IR stdout ,
and
.IR stderr .
-.PP
+.P
Each of these symbols is a
.BR stdio (3)
macro of type pointer to
.BR fprintf (3)
or
.BR fread (3).
-.PP
+.P
Since
.IR FILE s
are a buffering wrapper around UNIX file descriptors, the
.BR read (2)
and
.BR lseek (2).
-.PP
+.P
On program startup, the integer file descriptors
associated with the streams
.IR stdin ,
.BR freopen (3)
to one of these streams can change the file descriptor number
associated with the stream.)
-.PP
+.P
Note that mixing use of
.IR FILE s
and raw file descriptors can produce
.BR exec (3),
the child inherits all open file descriptors, but all old streams
have become inaccessible.
-.PP
+.P
Since the symbols
.IR stdin ,
.IR stdout ,
and by normal program termination.
.SH STANDARDS
C11, POSIX.1-2008.
-.PP
+.P
The standards also stipulate that these three
streams shall be open at program startup.
.SH HISTORY
.SH SYNOPSIS
.nf
.B #include <stdio.h>
-.PP
+.P
.BI "FILE *" stdin ;
.BI "FILE *" stdout ;
.BI "FILE *" stderr ;
physical I/O characteristics are concealed.
The functions and macros are
listed below; more information is available from the individual man pages.
-.PP
+.P
A stream is associated with an external file (which may be a physical
device) by
.I opening
successive calls to the
.BR fputc (3)
function.
-.PP
+.P
A file is disassociated from a stream by
.I closing
the file.
The value of a pointer to a
.I FILE
object is indeterminate after a file is closed (garbage).
-.PP
+.P
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).
such as
.BR abort (3)
do not bother about closing files properly.
-.PP
+.P
At program startup, three text streams are predefined and need not be
opened explicitly:
.I standard input
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 refer to an interactive device.
-.PP
+.P
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.
.BR fflush (3)
the standard output before going off and computing so that the output will
appear.
-.PP
+.P
The
.I stdio
library is a part of the library
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.
-.PP
+.P
The following are defined as macros; these names may not be reused without
first removing their current definitions with
.BR #undef :
.nf
.B #include <stdio.h>
.B #include <stdio_ext.h>
-.PP
+.P
.BI "size_t __fbufsize(FILE *" stream );
.BI "size_t __fpending(FILE *" stream );
.BI "int __flbf(FILE *" stream );
internals of the
.I FILE
structure, and glibc also implemented these.
-.PP
+.P
The
.BR __fbufsize ()
function returns the size of the buffer currently used
by the given stream.
-.PP
+.P
The
.BR __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.
-.PP
+.P
The
.BR __flbf ()
function returns a nonzero value if the stream is line-buffered,
and zero otherwise.
-.PP
+.P
The
.BR __freadable ()
function returns a nonzero value if the stream allows reading,
and zero otherwise.
-.PP
+.P
The
.BR __fwritable ()
function returns a nonzero value if the stream allows writing,
and zero otherwise.
-.PP
+.P
The
.BR __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.
-.PP
+.P
The
.BR __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.
-.PP
+.P
The
.BR __fsetlocking ()
function can be used to select the desired type of locking on the stream.
.B FSETLOCKING_QUERY
Don't change the type of locking.
(Only return it.)
-.PP
+.P
The
.BR _flushlbf ()
function flushes all line-buffered streams.
(Presumably so that
output to a terminal is forced out, say before reading keyboard input.)
-.PP
+.P
The
.BR __fpurge ()
function discards the contents of the stream's buffer.
.SH SYNOPSIS
.nf
.B #include <string.h>
-.PP
+.P
.BI "char *strncpy(char " dst "[restrict ." sz "], \
const char *restrict " src ,
.BI " size_t " sz );
const char *restrict " src ,
.BI " size_t " sz );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR stpncpy ():
.nf
Since glibc 2.10:
isn't large enough to hold the copy,
the resulting character sequence is truncated.
For the difference between the two functions, see RETURN VALUE.
-.PP
+.P
An implementation of these functions might be:
-.PP
+.P
.in +4n
.EX
char *
These functions produce a null-padded character sequence,
not a string (see
.BR string_copying (7)).
-.PP
+.P
It's impossible to distinguish truncation by the result of the call,
from a character sequence that just fits the destination buffer;
truncation should be detected by
comparing the length of the input string
with the size of the destination buffer.
-.PP
+.P
If you're going to use this function in chained calls,
it would be useful to develop a similar function that accepts
a pointer to the end (one after the last element) of the destination buffer
.SH SYNOPSIS
.nf
.B #include <strings.h>
-.PP
+.P
.BI "int strcasecmp(const char *" s1 ", const char *" s2 );
.BI "int strncasecmp(const char " s1 [. n "], const char " s2 [. n "], \
size_t " n );
is found,
respectively, to be less than, to match, or be greater than
.IR s2 .
-.PP
+.P
The
.BR strncasecmp ()
function is similar, except that it compares
POSIX.1-2008.
.SH HISTORY
4.4BSD, POSIX.1-2001.
-.PP
+.P
The
.BR strcasecmp ()
and
(or, in glibc 2.19 and earlier,
.BR _BSD_SOURCE )
feature test macro is defined.
-.PP
+.P
The POSIX.1-2008 standard says of these functions:
-.PP
+.P
.RS
When the
.B LC_CTYPE
.SH SYNOPSIS
.nf
.B #include <string.h>
-.PP
+.P
.BI "char *strchr(const char *" s ", int " c );
.BI "char *strrchr(const char *" s ", int " c );
-.PP
+.P
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <string.h>
-.PP
+.P
.BI "char *strchrnul(const char *" s ", int " c );
.fi
.SH DESCRIPTION
.I c
in the string
.IR s .
-.PP
+.P
The
.BR strrchr ()
function returns a pointer to the last occurrence
.I c
in the string
.IR s .
-.PP
+.P
The
.BR strchrnul ()
function is like
at the end of
.IR s ,
rather than NULL.
-.PP
+.P
Here "character" means "byte"; these functions do not work with
wide or multibyte characters.
.SH RETURN VALUE
.I c
is specified as \[aq]\e0\[aq],
these functions return a pointer to the terminator.
-.PP
+.P
The
.BR strchrnul ()
function returns a pointer to the matched character,
.SH SYNOPSIS
.nf
.B #include <string.h>
-.PP
+.P
.BI "int strcmp(const char *" s1 ", const char *" s2 );
.BI "int strncmp(const char " s1 [. n "], const char " s2 [. n "], size_t " n );
.fi
The locale is not taken into account (for a locale-aware comparison, see
.BR strcoll (3)).
The comparison is done using unsigned characters.
-.PP
+.P
.BR strcmp ()
returns an integer indicating the result of the comparison, as follows:
.IP \[bu] 3
.I s1
is greater than
.IR s2 .
-.PP
+.P
The
.BR strncmp ()
function is similar, except it compares
.SH VERSIONS
POSIX.1 specifies only that:
.RS
-.PP
+.P
The sign of a nonzero return value shall be determined by the sign
of the difference between the values of the first pair of bytes
(both interpreted as type
.IR "unsigned char" )
that differ in the strings being compared.
.RE
-.PP
+.P
In glibc, as in most other implementations,
the return value is the arithmetic result of subtracting
the last compared byte in
(when given three arguments).
First, some examples using
.BR strcmp ():
-.PP
+.P
.in +4n
.EX
$ \fB./string_comp ABC ABC\fP
<str1> is greater than <str2> (64)
.EE
.in
-.PP
+.P
The last example uses
.BR bash (1)-specific
syntax to produce a string containing an 8-bit ASCII code;
the result demonstrates that the string comparison uses unsigned
characters.
-.PP
+.P
And then some examples using
.BR strncmp ():
-.PP
+.P
.in +4n
.EX
$ \fB./string_comp ABC AB 3\fP
.SH SYNOPSIS
.nf
.B #include <string.h>
-.PP
+.P
.BI "int strcoll(const char *" s1 ", const char *" s2 );
.fi
.SH DESCRIPTION
.SH SYNOPSIS
.nf
.B #include <string.h>
-.PP
+.P
.BI "char *stpcpy(char *restrict " dst ", const char *restrict " src );
.BI "char *strcpy(char *restrict " dst ", const char *restrict " src );
.BI "char *strcat(char *restrict " dst ", const char *restrict " src );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR stpcpy ():
.nf
Since glibc 2.10:
The programmer is responsible for allocating a destination buffer large enough,
that is,
.IR "strlen(dst) + strlen(src) + 1" .
-.PP
+.P
An implementation of these functions might be:
-.PP
+.P
.in +4n
.EX
char *
and
.I dst
may not overlap.
-.PP
+.P
If the destination buffer is not large enough,
the behavior is undefined.
See
.B _FORTIFY_SOURCE
in
.BR feature_test_macros (7).
-.PP
+.P
.BR strcat ()
can be very inefficient.
Read about
.SH SYNOPSIS
.nf
.B #include <string.h>
-.PP
+.P
.BI "char *strdup(const char *" s );
-.PP
+.P
.BI "char *strndup(const char " s [. n "], size_t " n );
.BI "char *strdupa(const char *" s );
.BI "char *strndupa(const char " s [. n "], size_t " n );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR strdup ():
.nf
_XOPEN_SOURCE >= 500
|| /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
|| /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
.fi
-.PP
+.P
.BR strndup ():
.nf
Since glibc 2.10:
Before glibc 2.10:
_GNU_SOURCE
.fi
-.PP
+.P
.BR strdupa (),
.BR strndupa ():
.nf
.BR malloc (3),
and can be freed with
.BR free (3).
-.PP
+.P
The
.BR strndup ()
function is similar, but copies at most
only
.I n
bytes are copied, and a terminating null byte (\[aq]\e0\[aq]) is added.
-.PP
+.P
.BR strdupa ()
and
.BR strndupa ()
.SH SYNOPSIS
.nf
.B #include <string.h>
-.PP
+.P
.BI "char *strerror(int " errnum );
.BI "const char *strerrorname_np(int " errnum );
.BI "const char *strerrordesc_np(int " errnum );
-.PP
+.P
.BI "int strerror_r(int " errnum ", char " buf [. buflen "], size_t " buflen );
/* XSI-compliant */
-.PP
+.P
.BI "char *strerror_r(int " errnum ", char " buf [. buflen "], size_t " buflen );
/* GNU-specific */
-.PP
+.P
.BI "char *strerror_l(int " errnum ", locale_t " locale );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR strerrorname_np (),
.BR strerrordesc_np ():
.nf
_GNU_SOURCE
.fi
-.PP
+.P
.BR strerror_r ():
.nf
The XSI-compliant version is provided if:
No other library function, including
.BR perror (3),
will modify this string.
-.PP
+.P
Like
.BR strerror (),
the
.IR errnum ,
with the difference that the returned string is not translated
according to the current locale.
-.PP
+.P
The
.BR strerrorname_np ()
function returns a pointer to a string containing the name of the error
200112L, so that the XSI-compliant version of
.BR strerror_r ()
is provided by default.
-.PP
+.P
The XSI-compliant
.BR strerror_r ()
is preferred for portable applications.
.I buf
of length
.IR buflen .
-.PP
+.P
The GNU-specific
.BR strerror_r ()
returns a pointer to a string containing the error message.
functions return
the appropriate error description string,
or an "Unknown error nnn" message if the error number is unknown.
-.PP
+.P
On success,
.BR strerrorname_np ()
and
If
.I errnum
is an invalid error number, these functions return NULL.
-.PP
+.P
The XSI-compliant
.BR strerror_r ()
function returns 0 on success.
or \-1 is returned and
.I errno
is set to indicate the error (before glibc 2.13).
-.PP
+.P
POSIX.1-2001 and POSIX.1-2008 require that a successful call to
.BR strerror ()
or
.BR strerror_l ()
T} Thread safety MT-Safe
.TE
-.PP
+.P
Before glibc 2.32,
.BR strerror ()
is not MT-Safe.
.TQ
.BR strerrordesc_np ()
GNU.
-.PP
+.P
POSIX.1-2001 permits
.BR strerror ()
to set
.SH SYNOPSIS
.nf
.B #include <monetary.h>
-.PP
+.P
.BI "ssize_t strfmon(char " s "[restrict ." max "], size_t " max ,
.BI " const char *restrict " format ", ...);"
.BI "ssize_t strfmon_l(char " s "[restrict ." max "], size_t " max ", \
.I s
of size
.IR max .
-.PP
+.P
The
.BR strfmon_l ()
function performs the same task,
(see
.BR duplocale (3))
or is not a valid locale object handle.
-.PP
+.P
Ordinary characters in
.I format
are copied to
.B \-
Left justify all fields.
The default is right justification.
-.PP
+.P
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).
-.PP
+.P
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.
-.PP
+.P
Next, there may be a right precision of the form "." followed by
a decimal digit string.
The amount being formatted is rounded to
.BR LC_MONETARY ,
and may differ from that specified by
.BR LC_NUMERIC .)
-.PP
+.P
Finally, the conversion specification must be ended with a
conversion character.
The three conversion characters are
POSIX.1-2001.
.SH EXAMPLES
The call
-.PP
+.P
.in +4n
.EX
strfmon(buf, sizeof(buf), "[%\[ha]=*#6n] [%=*#6i]",
1234.567, 1234.567);
.EE
.in
-.PP
+.P
outputs
-.PP
+.P
.in +4n
.EX
[€ **1234,57] [EUR **1 234,57]
.EE
.in
-.PP
+.P
in the
.I nl_NL
locale.
and
.I en_GB
locales yield
-.PP
+.P
.in +4n
.EX
[ **1234,57 €] [ **1.234,57 EUR]
.SH SYNOPSIS
.nf
.B #include <stdlib.h>
-.PP
+.P
.BI "int strfromd(char " str "[restrict ." n "], size_t " n ,
.BI " const char *restrict " format ", double " fp ");"
.BI "int strfromf(char " str "[restrict ." n "], size_t " n ,
.BI "int strfroml(char " str "[restrict ." n "], size_t " n ,
.BI " const char *restrict " format ", long double " fp ");"
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR strfromd (),
.BR strfromf (),
.BR strfroml ():
.I n
characters are stored into
.IR str .
-.PP
+.P
The terminating null byte ('\e0') is written if and only if
.I n
is sufficiently large, otherwise the written string is truncated at
.I n
characters.
-.PP
+.P
The
.BR strfromd (),
.BR strfromf (),
and
.BR strfroml ()
functions are equivalent to
-.PP
+.P
.in +4n
.EX
snprintf(str, n, format, fp);
.EE
.in
-.PP
+.P
except for the
.I format
string.
.BR g ,
or
.BR G .
-.PP
+.P
The conversion specifier is applied based on the floating-point type
indicated by the function suffix.
Therefore, unlike
See
.BR snprintf (3)
for a detailed description of these conversion specifiers.
-.PP
+.P
The implementation conforms to the C99 standard on conversion of NaN and
infinity values:
-.PP
+.P
.RS
If
.I fp
.BR E ,
.BR G )
is the conversion specifier, the conversion is to "NAN" or "\-NAN".
-.PP
+.P
Likewise if
.I fp
is infinity, it is converted to [\-]inf or [\-]INF.
.RE
-.PP
+.P
A malformed
.I format
string results in undefined behavior.
and the
.B POSIX Safety Concepts
section in GNU C Library manual.
-.PP
+.P
.TS
allbox;
lbx lb lb
\^ Async-signal safety AS-Unsafe heap
\^ Async-cancel safety AC-Unsafe mem
.TE
-.PP
+.P
Note: these attributes are preliminary.
.SH STANDARDS
ISO/IEC TS 18661-1.
.SH EXAMPLES
To convert the value 12.1 as a float type to a string using decimal
notation, resulting in "12.100000":
-.PP
+.P
.in +4n
.EX
#define __STDC_WANT_IEC_60559_BFP_EXT__
strfromf(s, ssize, "%f", 12.1);
.EE
.in
-.PP
+.P
To convert the value 12.3456 as a float type to a string using
decimal notation with two digits of precision, resulting in "12.35":
-.PP
+.P
.in +4n
.EX
#define __STDC_WANT_IEC_60559_BFP_EXT__
strfromf(s, ssize, "%.2f", 12.3456);
.EE
.in
-.PP
+.P
To convert the value 12.345e19 as a double type to a string using
scientific notation with zero digits of precision, resulting in "1E+20":
-.PP
+.P
.in +4n
.EX
#define __STDC_WANT_IEC_60559_BFP_EXT__
.nf
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <string.h>
-.PP
+.P
.BI "char *strfry(char *" string );
.fi
.SH DESCRIPTION
.SH SYNOPSIS
.nf
.B #include <time.h>
-.PP
+.P
.BI "size_t strftime(char " s "[restrict ." max "], size_t " max ,
.BI " const char *restrict " format ,
.BI " const struct tm *restrict " tm );
-.PP
+.P
.BI "size_t strftime_l(char " s "[restrict ." max "], size_t " max ,
.BI " const char *restrict " format ,
.BI " const struct tm *restrict " tm ,
.BR ctime (3).
.\" FIXME . POSIX says: Local timezone information is used as though
.\" strftime() called tzset(). But this doesn't appear to be the case
-.PP
+.P
The format specification is a null-terminated string and may contain
special character sequences called
.IR "conversion specifications",
.IR "conversion specifier character".
All other character sequences are
.IR "ordinary character sequences".
-.PP
+.P
The characters of ordinary character sequences (including the null byte)
are copied verbatim from
.I format
.TP
.B %%
A literal \[aq]%\[aq] character.
-.PP
+.P
Some conversion specifications can be modified by preceding the
conversion specifier character by the
.B E
One example of such alternative forms is the Japanese era calendar scheme in the
.B ja_JP
glibc locale.
-.PP
+.P
.BR strftime_l ()
is equivalent to
.BR strftime (),
.\" would return
.\" .I max
.\" if the array was too small.)
-.PP
+.P
Note that the return value 0 does not necessarily indicate an error.
For example, in many locales
.B %p
.TP
.BR strftime_l ()
POSIX.1-2008.
-.PP
+.P
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),
The
.B %F
conversion is in C99 and POSIX.1-2001.
-.PP
+.P
In SUSv2, the
.B %S
specifier allowed a range of 00 to 61,
or
.B O
modifiers, if present.)
-.PP
+.P
The following flag characters are permitted:
.TP
.B _
(This flag works only with certain conversion specifier characters,
and of these, it is only really useful with
.BR %Z .)
-.PP
+.P
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.
.I errno
settings for
.BR strftime ().
-.PP
+.P
Some buggy versions of
.BR gcc (1)
complain about the use of
problem.
A relatively clean one is to add an
intermediate function
-.PP
+.P
.in +4n
.EX
size_t
}
.EE
.in
-.PP
+.P
Nowadays,
.BR gcc (1)
provides the
.SH EXAMPLES
.B RFC\~2822-compliant date format
(with an English locale for %a and %b)
-.PP
+.P
.in +4n
.EX
"%a,\ %d\ %b\ %Y\ %T\ %z"
.EE
.in
-.PP
+.P
.B RFC\~822-compliant date format
(with an English locale for %a and %b)
-.PP
+.P
.in +4n
.EX
"%a,\ %d\ %b\ %y\ %T\ %z"
.SS Example program
The program below can be used to experiment with
.BR strftime ().
-.PP
+.P
Some examples of the result string produced by the glibc implementation of
.BR strftime ()
are as follows:
-.PP
+.P
.in +4n
.EX
.RB "$" " ./a.out \[aq]%m\[aq]"
.SH SYNOPSIS
.nf
.B #include <string.h>
-.PP
+.P
.BI "size_t strlen(const char *" s );
.fi
.SH DESCRIPTION
.SH SYNOPSIS
.nf
.B #include <string.h>
-.PP
+.P
.BI "char *strncat(char *restrict " dst ", const char " src "[restrict ." sz ],
.BI " size_t " sz );
.fi
The programmer is responsible for allocating a destination buffer large enough,
that is,
.IR "strlen(dst) + strnlen(src, sz) + 1" .
-.PP
+.P
An implementation of this function might be:
-.PP
+.P
.in +4n
.EX
char *
The name of this function is confusing.
This function has no relation to
.BR strncpy (3).
-.PP
+.P
If the destination buffer is not large enough,
the behavior is undefined.
See
.SH SYNOPSIS
.nf
.B #include <string.h>
-.PP
+.P
.BI "size_t strnlen(const char " s [. maxlen "], size_t " maxlen );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR strnlen ():
.nf
Since glibc 2.10:
.SH SYNOPSIS
.nf
.B #include <string.h>
-.PP
+.P
.BI "char *strpbrk(const char *" s ", const char *" accept );
.fi
.SH DESCRIPTION
.nf
.BR "#define _XOPEN_SOURCE" " /* See feature_test_macros(7) */"
.B #include <time.h>
-.PP
+.P
.BI "char *strptime(const char *restrict " s ", const char *restrict " format ,
.BI " struct tm *restrict " tm );
.fi
.IR tm ,
using the format specified by
.IR format .
-.PP
+.P
The broken-down time structure
.I tm
is described in
.BR tm (3type).
-.PP
+.P
The
.I format
argument
whitespace characters in the input string.
There should be white\%space or other alphanumeric characters
between any two field descriptors.
-.PP
+.P
The
.BR strptime ()
function processes the input string from left
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.
-.PP
+.P
The supported input field descriptors are listed below.
In case a text string (such as the name of a day of the week or a month name)
is to be matched, the comparison is case insensitive.
.TP
.B %Y
The year, including century (for example, 1991).
-.PP
+.P
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.
-.PP
+.P
The E modifier specifies that the input string may contain
alternative locale-dependent versions of the date and time representation:
.TP
.TP
.B %EY
The full alternative year representation.
-.PP
+.P
The O modifier specifies that the numerical input may be in an
alternative locale-dependent format:
.TP
and
.I tm_yday
field if any of the year, month, or day elements changed.
-.\" .PP
+.\" .P
.\" 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
.\" or
.\" .B _GNU_SOURCE
.\" are defined.
-.\" .PP
+.\" .P
.\" Before libc 5.4.13 whitespace
.\" (and the \[aq]n\[aq] and \[aq]t\[aq] specifications) was not handled,
.\" no \[aq]E\[aq] and \[aq]O\[aq] locale modifier characters were accepted,
.\" and the \[aq]C\[aq] specification was a synonym for the \[aq]c\[aq] specification.
-.PP
+.P
The \[aq]y\[aq] (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
.TP
.B %Z
The timezone name.
-.PP
+.P
Similarly, because of GNU extensions to
.BR strftime (3),
.B %k
.B %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.
-.PP
+.P
The glibc implementation does not require whitespace between
two field descriptors.
.SH EXAMPLES
.BR strptime ()
and
.BR strftime (3).
-.PP
+.P
.\" SRC BEGIN (strptime.c)
.EX
#define _XOPEN_SOURCE
.SH SYNOPSIS
.nf
.B #include <string.h>
-.PP
+.P
.BI "char *strsep(char **restrict " stringp ", const char *restrict " delim );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR strsep ():
.nf
Since glibc 2.19:
None.
.SH HISTORY
4.4BSD.
-.PP
+.P
The
.BR strsep ()
function was introduced as a replacement for
The program below is a port of the one found in
.BR strtok (3),
which, however, doesn't discard multiple delimiters or empty tokens:
-.PP
+.P
.in +4n
.EX
.RB "$" " ./a.out \[aq]a/bbb///cc;xxx:yyy:\[aq] \[aq]:;\[aq] \[aq]/\[aq]"
.SH SYNOPSIS
.nf
.B #include <string.h>
-.PP
+.P
.BI "char *strsignal(int " sig );
.BI "const char *sigdescr_np(int " sig );
.BI "const char *sigabbrev_np(int " sig );
-.PP
+.P
.BI "[[deprecated]] extern const char *const " sys_siglist [];
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR sigabbrev_np (),
.BR sigdescr_np ():
.nf
_GNU_SOURCE
.fi
-.PP
+.P
.BR strsignal ():
.nf
From glibc 2.10 to glibc 2.31:
Before glibc 2.10:
_GNU_SOURCE
.fi
-.PP
+.P
.IR sys_siglist :
.nf
Since glibc 2.19:
is localized according to the
.B LC_MESSAGES
category in the current locale.
-.PP
+.P
The
.BR sigdescr_np ()
function returns a string describing the signal
Unlike
.BR strsignal ()
this string is not influenced by the current locale.
-.PP
+.P
The
.BR sigabbrev_np ()
function returns the abbreviated name of the signal,
For example, given the value
.BR SIGINT ,
it returns the string "INT".
-.PP
+.P
The (deprecated) array
.I sys_siglist
holds the signal description strings
string, or an unknown signal message if the signal number is invalid.
On some systems (but not on Linux), NULL may instead be
returned for an invalid signal number.
-.PP
+.P
The
.BR sigdescr_np ()
and
.SH SYNOPSIS
.nf
.B #include <string.h>
-.PP
+.P
.BI "size_t strspn(const char *" s ", const char *" accept );
.BI "size_t strcspn(const char *" s ", const char *" reject );
.fi
.I s
which consists entirely of bytes in
.IR accept .
-.PP
+.P
The
.BR strcspn ()
function calculates the length of the initial
which consist only of bytes
from
.IR accept .
-.PP
+.P
The
.BR strcspn ()
function returns the number of bytes in
.SH SYNOPSIS
.nf
.B #include <string.h>
-.PP
+.P
.BI "char *strstr(const char *" haystack ", const char *" needle );
-.PP
+.P
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <string.h>
-.PP
+.P
.BI "char *strcasestr(const char *" haystack ", const char *" needle );
.fi
.SH DESCRIPTION
in the string
.IR haystack .
The terminating null bytes (\[aq]\e0\[aq]) are not compared.
-.PP
+.P
The
.BR strcasestr ()
function is like
.SH RETURN VALUE
These functions return a pointer to the beginning of the
located substring, or NULL if the substring is not found.
-.PP
+.P
If
.I needle
is the empty string,
.SH SYNOPSIS
.nf
.B #include <stdlib.h>
-.PP
+.P
.BI "double strtod(const char *restrict " nptr ", char **restrict " endptr );
.BI "float strtof(const char *restrict " nptr ", char **restrict " endptr );
.BI "long double strtold(const char *restrict " nptr \
", char **restrict " endptr );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR strtof (),
.BR strtold ():
.nf
and
.I long double
representation, respectively.
-.PP
+.P
The expected form of the (initial portion of the) string is
optional leading white space as recognized by
.BR isspace (3),
an optional plus (\[aq]+\[aq]) or minus sign (\[aq]\-\[aq]) and then either
(i) a decimal number, or (ii) a hexadecimal number,
or (iii) an infinity, or (iv) a NAN (not-a-number).
-.PP
+.P
A
.I "decimal number"
consists of a nonempty sequence of decimal digits
A decimal exponent consists of an \[aq]E\[aq] or \[aq]e\[aq], followed by an
optional plus or minus sign, followed by a nonempty sequence of
decimal digits, and indicates multiplication by a power of 10.
-.PP
+.P
A
.I "hexadecimal number"
consists of a "0x" or "0X" followed by a nonempty sequence of
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.
-.PP
+.P
An
.I infinity
is either "INF" or "INFINITY", disregarding case.
-.PP
+.P
A
.I NAN
is "NAN" (disregarding case) optionally followed by a string,
way the type of NAN (see NOTES).
.SH RETURN VALUE
These functions return the converted value, if any.
-.PP
+.P
If
.I endptr
is not NULL,
a pointer to the character after the last character used in the conversion
is stored in the location referenced by
.IR endptr .
-.PP
+.P
If no conversion is performed, zero is returned and (unless
.I endptr
is null) the value of
.I nptr
is stored in the location referenced by
.IR endptr .
-.PP
+.P
If the correct value would cause overflow, plus or minus
.BR HUGE_VAL ,
.BR HUGE_VALF ,
.B ERANGE
is stored in
.IR errno .
-.PP
+.P
If the correct value would cause underflow,
a value with magnitude no larger than
.BR DBL_MIN ,
.SH SYNOPSIS
.nf
.B #include <inttypes.h>
-.PP
+.P
.BI "intmax_t strtoimax(const char *restrict " nptr ", char **restrict " endptr ,
.BI " int " base );
.BI "uintmax_t strtoumax(const char *restrict " nptr ", char **restrict " endptr ,
.SH SYNOPSIS
.nf
.B #include <string.h>
-.PP
+.P
.BI "char *strtok(char *restrict " str ", const char *restrict " delim );
.BI "char *strtok_r(char *restrict " str ", const char *restrict " delim ,
.BI " char **restrict " saveptr );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR strtok_r ():
.nf
_POSIX_C_SOURCE
In each subsequent call that should parse the same string,
.I str
must be NULL.
-.PP
+.P
The
.I delim
argument specifies a set of bytes that
.I delim
in successive
calls that parse the same string.
-.PP
+.P
Each call to
.BR strtok ()
returns a pointer to a
If no more tokens are found,
.BR strtok ()
returns NULL.
-.PP
+.P
A sequence of calls to
.BR strtok ()
that operate on the same string maintains a pointer
will thus cause
.BR strtok ()
to return NULL on the first call.)
-.PP
+.P
The end of each token is found by scanning forward until either
the next delimiter byte is found or until the
terminating null byte (\[aq]\e0\[aq]) is encountered.
In this case,
.BR strtok ()
returns a pointer to the start of the found token.
-.PP
+.P
From the above description,
it follows that a sequence of two or more contiguous delimiter bytes in
the parsed string is considered to be a single delimiter, and that
that specify the delimiter string "\fI;,\fP"
would return the strings "\fIaaa\fP" and "\fIbbb\fP",
and then a null pointer.
-.PP
+.P
The
.BR strtok_r ()
function is a reentrant version of
.BR strtok_r ()
in order to maintain context between successive calls that parse the
same string.
-.PP
+.P
On the first call to
.BR strtok_r (),
.I str
.I saveptr
(and the buffer that it points to)
should be unchanged since the previous call.
-.PP
+.P
Different strings may be parsed concurrently using sequences of calls to
.BR strtok_r ()
that specify different
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.
-.PP
+.P
An example of the output produced by this program is the following:
-.PP
+.P
.in +4n
.EX
.RB "$" " ./a.out \[aq]a/bbb///cc;xxx:yyy:\[aq] \[aq]:;\[aq] \[aq]/\[aq]"
}
.EE
.\" SRC END
-.PP
+.P
Another example program using
.BR strtok ()
can be found in
.SH SYNOPSIS
.nf
.B #include <stdlib.h>
-.PP
+.P
.BI "long strtol(const char *restrict " nptr ,
.BI " char **restrict " endptr ", int " base );
.BI "long long strtoll(const char *restrict " nptr ,
.BI " char **restrict " endptr ", int " base );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR strtoll ():
.nf
_ISOC99_SOURCE
to a long integer value according to the given
.IR base ,
which must be between 2 and 36 inclusive, or be the special value 0.
-.PP
+.P
The string may begin with an arbitrary amount of white space (as
determined by
.BR isspace (3))
.I base
is taken as 10 (decimal) unless the next character
is \[aq]0\[aq], in which case it is taken as 8 (octal).
-.PP
+.P
The remainder of the string is converted to a
.I long
value
(In bases above 10, the letter \[aq]A\[aq] in
either uppercase or lowercase represents 10, \[aq]B\[aq] represents 11, and so
forth, with \[aq]Z\[aq] representing 35.)
-.PP
+.P
If
.I endptr
is not NULL,
is not \[aq]\e0\[aq] but
.I **endptr
is \[aq]\e0\[aq] on return, the entire string is valid.
-.PP
+.P
The
.BR strtoll ()
function works just like the
.TP
.B ERANGE
The resulting value was out of range.
-.PP
+.P
The implementation may also set
.I errno
to
and then determine if an error occurred by checking whether
.I errno
has a nonzero value after the call.
-.PP
+.P
According to POSIX.1,
in locales other than "C" and "POSIX",
these functions may accept other,
implementation-defined numeric strings.
-.PP
+.P
BSD also has
-.PP
+.P
.in +4n
.EX
.BI "quad_t strtoq(const char *" nptr ", char **" endptr ", int " base );
.EE
.in
-.PP
+.P
with completely analogous definition.
Depending on the wordsize of the current architecture, this
may be equivalent to
has a simpler interface than
.BR strtol ().)
Some examples of the results produced by this program are the following:
-.PP
+.P
.in +4n
.EX
.RB "$" " ./a.out 123"
.SH SYNOPSIS
.nf
.B #include <stdlib.h>
-.PP
+.P
.BI "unsigned long strtoul(const char *restrict " nptr ,
.BI " char **restrict " endptr ", int " base );
.BI "unsigned long long strtoull(const char *restrict " nptr ,
.BI " char **restrict " endptr ", int " base );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR strtoull ():
.nf
_ISOC99_SOURCE
.IR base ,
which must be between 2 and 36 inclusive, or be
the special value 0.
-.PP
+.P
The string may begin with an arbitrary amount of white space (as
determined by
.BR isspace (3))
.I base
is taken as 10 (decimal) unless the next character
is \[aq]0\[aq], in which case it is taken as 8 (octal).
-.PP
+.P
The remainder of the string is converted to an
.I "unsigned long"
value in the obvious manner,
(In bases above 10, the letter \[aq]A\[aq] in
either uppercase or lowercase represents 10, \[aq]B\[aq] represents 11, and so
forth, with \[aq]Z\[aq] representing 35.)
-.PP
+.P
If
.I endptr
is not NULL,
is not \[aq]\e0\[aq] but
.I **endptr
is \[aq]\e0\[aq] on return, the entire string is valid.
-.PP
+.P
The
.BR strtoull ()
function works just like the
.TP
.B ERANGE
The resulting value was out of range.
-.PP
+.P
The implementation may also set
.I errno
to
and then determine if an error occurred by checking whether
.I errno
has a nonzero value after the call.
-.PP
+.P
In locales other than the "C" locale, other strings may be accepted.
(For example, the thousands separator of the current locale may be
supported.)
-.PP
+.P
BSD also has
-.PP
+.P
.in +4n
.EX
.BI "u_quad_t strtouq(const char *" nptr ", char **" endptr ", int " base );
.EE
.in
-.PP
+.P
with completely analogous definition.
Depending on the wordsize of the current architecture, this
may be equivalent to
.BR strtoull ()
or to
.BR strtoul ().
-.PP
+.P
Negative values are considered valid input and are
silently converted to the equivalent
.I "unsigned long"
.nf
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <string.h>
-.PP
+.P
.BI "int strverscmp(const char *" s1 ", const char *" s2 );
.fi
.SH DESCRIPTION
.BR versionsort (3),
which again uses
.BR strverscmp ().
-.PP
+.P
Thus, the task of
.BR strverscmp ()
is to compare two strings and find the "right" order, while
.BR LC_COLLATE ,
so is meant mostly for situations
where the strings are expected to be in ASCII.
-.PP
+.P
What this function does is the following.
If both strings are equal, return 0.
Otherwise, find the position
.BR strverscmp ()
to compare the two strings given as its command-line arguments.
An example of its use is the following:
-.PP
+.P
.in +4n
.EX
$ \fB./a.out jan1 jan10\fP
.SH SYNOPSIS
.nf
.B #include <string.h>
-.PP
+.P
.BI "size_t strxfrm(char " dest "[restrict ." n "], \
const char " src "[restrict ." n ],
.BI " size_t " n );
.nf
.BR "#define _XOPEN_SOURCE" " /* See feature_test_macros(7) */"
.B #include <unistd.h>
-.PP
+.P
.BI "void swab(const void " from "[restrict ." n "], void " to "[restrict ." n ],
.BI " ssize_t " n );
.fi
adjacent even and odd bytes.
This function is used to exchange data
between machines that have different low/high byte ordering.
-.PP
+.P
This function does nothing when
.I n
is negative.
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.BI "long sysconf(int " "name" );
.fi
.SH DESCRIPTION
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.
-.PP
+.P
At compile time this is done by including
.I <unistd.h>
and/or
.I <limits.h>
and testing the value of certain macros.
-.PP
+.P
At run time, one can ask for numerical values using the present function
.BR sysconf ().
One can ask for numerical values that may depend
.BR pathconf (3).
One can ask for string values using
.BR confstr (3).
-.PP
+.P
The values obtained from these functions are system configuration constants.
They do not change during the lifetime of a process.
.\" except that sysconf(_SC_OPEN_MAX) may change answer after a call
.\" to setrlimit( ) which changes the RLIMIT_NOFILE soft limit
-.PP
+.P
For options, typically, there is a constant
.B _POSIX_FOO
that may be defined in
.BR _SC_FOO .
For a list of options, see
.BR posixoptions (7).
-.PP
+.P
For variables or limits, typically, there is a constant
.BR _FOO ,
maybe defined in
.BR sysconf ()
argument used to inquire about its value,
and a short description.
-.PP
+.P
First, the POSIX.1 compatible values.
.\" [for the moment: only the things that are unconditionally present]
.\" .TP
.BR POSIX2_SW_DEV " - " _SC_2_SW_DEV
indicates whether the POSIX.2 software development utilities option is
supported.
-.PP
+.P
These values also exist, but may not be standard.
.TP
.BR "" " - " _SC_PHYS_PAGES
because it is not specified how much of the argument space for
.BR exec (3)
is consumed by the user's environment variables.
-.PP
+.P
Some returned values may be huge; they are not suitable for allocating
memory.
.SH SEE ALSO
.SH SYNOPSIS
.nf
.B #include <syslog.h>
-.PP
+.P
.BI "void openlog(const char *" ident ", int " option ", int " facility );
.BI "void syslog(int " priority ", const char *" format ", ...);"
.B "void closelog(void);"
-.PP
+.P
.BI "void vsyslog(int " priority ", const char *" format ", va_list " ap );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR vsyslog ():
.nf
Since glibc 2.19:
.SS openlog()
.BR openlog ()
opens a connection to the system logger for a program.
-.PP
+.P
The string pointed to by
.I ident
is prepended to every message, and is typically set to the program name.
(POSIX.1-2008 does not specify the behavior when
.I ident
is NULL.)
-.PP
+.P
The
.I option
argument specifies flags which control the operation of
and
.I facility
are described below.
-.PP
+.P
The use of
.BR openlog ()
is optional; it will automatically be called by
.BR syslog ()
generates a log message, which will be distributed by
.BR syslogd (8).
-.PP
+.P
The
.I priority
argument is formed by ORing together a
call, a default of
.B LOG_USER
is employed.
-.PP
+.P
The remaining arguments are a
.IR format ,
as in
the error message string
.IR strerror ( errno ).
The format string need not include a terminating newline character.
-.PP
+.P
The function
.BR vsyslog ()
performs the same task as
.TP
.B LOG_DEBUG
debug-level message
-.PP
+.P
The function
.BR setlogmask (3)
can be used to restrict logging to specified levels only.
.\" .I <varargs.h>
.\" mechanism, which is not compatible with
.\" .IR <stdarg.h> .
-.PP
+.P
POSIX.1-2001 specifies only the
.B LOG_USER
and
the other
.I facility
values appear on most UNIX systems.
-.PP
+.P
The
.B LOG_PERROR
value for
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.
-.PP
+.P
Never pass a string with user-supplied data as a format,
use the following instead:
-.PP
+.P
.in +4n
.EX
syslog(priority, "%s", string);
.SH SYNOPSIS
.nf
.B #include <stdlib.h>
-.PP
+.P
.BI "int system(const char *" "command" );
.fi
.SH DESCRIPTION
using
.BR execl (3)
as follows:
-.PP
+.P
.in +4n
.EX
execl("/bin/sh", "sh", "\-c", command, (char *) NULL);
.EE
.in
-.PP
+.P
.BR system ()
returns after the command has been completed.
-.PP
+.P
During execution of the command,
.B SIGCHLD
will be blocked, and
(These signals will be handled according to their defaults inside
the child process that executes
.IR command .)
-.PP
+.P
If
.I command
is NULL, then
.IR command .
(The termination status of a shell is the termination status of
the last command it executes.)
-.PP
+.P
In the last two cases,
the return value is a "wait status" that can be examined using
the macros described in
.BR WIFEXITED (),
.BR WEXITSTATUS (),
and so on).
-.PP
+.P
.BR system ()
does not affect the wait status of any other children.
.SH ERRORS
is inefficiency:
additional system calls are required to create the process that
runs the shell and to execute the shell.
-.PP
+.P
If the
.B _XOPEN_SOURCE
feature test macro is defined
.RB ( WEXITSTATUS (),
etc.) are made available when including
.IR <stdlib.h> .
-.PP
+.P
As mentioned,
.BR system ()
ignores
from a loop uninterruptible, unless they take care themselves
to check the exit status of the child.
For example:
-.PP
+.P
.in +4n
.EX
while (something) {
}
.EE
.in
-.PP
+.P
According to POSIX.1, it is unspecified whether handlers registered using
.BR pthread_atfork (3)
are called during the execution of
.BR system ().
In the glibc implementation, such handlers are not called.
-.PP
+.P
Before glibc 2.1.3, the check for the availability of
.I /bin/sh
was not actually performed if
the calling program has previously called
.BR chroot (2)
(which is not specified by POSIX.1-2001).
-.PP
+.P
It is possible for the shell command to terminate with a status of 127,
which yields a
.BR system ()
(which also use the
.B PATH
environment variable to search for an executable).
-.PP
+.P
.BR system ()
will not, in fact, work properly from programs with set-user-ID or
set-group-ID privileges on systems on which
.BR dash (1),
which does not do this when invoked as
.BR sh .)
-.PP
+.P
Any user input that is employed as part of
.I command
should be
.BR sh (1).)
To work around this problem,
prepend the command with a space as in the following call:
-.PP
+.P
.in +4n
.EX
system(" \-unfortunate\-command\-name");
.nf
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <signal.h>
-.PP
+.P
.B typedef void (*sighandler_t)(int);
-.PP
+.P
.BI "sighandler_t sysv_signal(int " signum ", sighandler_t " handler );
.fi
.SH DESCRIPTION
.BR sysv_signal ()
function takes the same arguments, and performs the same task, as
.BR signal (2).
-.PP
+.P
However
.BR sysv_signal ()
provides the System V unreliable signal semantics, that is:
should be avoided; use
.BR sigaction (2)
instead.
-.PP
+.P
On older Linux systems,
.BR sysv_signal ()
and
provides reliable signal semantics; see
.BR signal (2)
for details.
-.PP
+.P
The use of
.I sighandler_t
is a GNU extension;
.SH SYNOPSIS
.nf
.B #include <sys/queue.h>
-.PP
+.P
.B TAILQ_ENTRY(TYPE);
-.PP
+.P
.B TAILQ_HEAD(HEADNAME, TYPE);
.BI "TAILQ_HEAD TAILQ_HEAD_INITIALIZER(TAILQ_HEAD " head );
.BI "void TAILQ_INIT(TAILQ_HEAD *" head );
-.PP
+.P
.BI "int TAILQ_EMPTY(TAILQ_HEAD *" head );
-.PP
+.P
.BI "void TAILQ_INSERT_HEAD(TAILQ_HEAD *" head ,
.BI " struct TYPE *" elm ", TAILQ_ENTRY " NAME );
.BI "void TAILQ_INSERT_TAIL(TAILQ_HEAD *" head ,
.BI " struct TYPE *" elm ", TAILQ_ENTRY " NAME );
.BI "void TAILQ_INSERT_AFTER(TAILQ_HEAD *" head ", struct TYPE *" listelm ,
.BI " struct TYPE *" elm ", TAILQ_ENTRY " NAME );
-.PP
+.P
.BI "struct TYPE *TAILQ_FIRST(TAILQ_HEAD *" head );
.BI "struct TYPE *TAILQ_LAST(TAILQ_HEAD *" head ", HEADNAME);"
.BI "struct TYPE *TAILQ_PREV(struct TYPE *" elm ", HEADNAME, TAILQ_ENTRY " NAME );
.BI "struct TYPE *TAILQ_NEXT(struct TYPE *" elm ", TAILQ_ENTRY " NAME );
-.PP
+.P
.BI "TAILQ_FOREACH(struct TYPE *" var ", TAILQ_HEAD *" head ,
.BI " TAILQ_ENTRY " NAME );
.\" .BI "TAILQ_FOREACH_FROM(struct TYPE *" var ", TAILQ_HEAD *" head ,
.BI " TAILQ_ENTRY " NAME );
.\" .BI "TAILQ_FOREACH_REVERSE_FROM(struct TYPE *" var ", TAILQ_HEAD *" head ", HEADNAME,"
.\" .BI " TAILQ_ENTRY " NAME );
-.\" .PP
+.\" .P
.\" .BI "TAILQ_FOREACH_SAFE(struct TYPE *" var ", TAILQ_HEAD *" head ,
.\" .BI " TAILQ_ENTRY " NAME ,
.\" .BI " struct TYPE *" temp_var );
.\" .BI "TAILQ_FOREACH_REVERSE_FROM_SAFE(struct TYPE *" var ", TAILQ_HEAD *" head ,
.\" .BI " HEADNAME, TAILQ_ENTRY " NAME ,
.\" .BI " struct TYPE *" temp_var );
-.PP
+.P
.BI "void TAILQ_REMOVE(TAILQ_HEAD *" head ", struct TYPE *" elm ,
.BI " TAILQ_ENTRY " NAME );
-.PP
+.P
.BI "void TAILQ_CONCAT(TAILQ_HEAD *" head1 ", TAILQ_HEAD *" head2 ,
.BI " TAILQ_ENTRY " NAME );
.\" .BI "void TAILQ_SWAP(TAILQ_HEAD *" head1 ", TAILQ_HEAD *" head2 ", TYPE,"
.fi
.SH DESCRIPTION
These macros define and operate on doubly linked tail queues.
-.PP
+.P
In the macro definitions,
.I TYPE
is the name of a user defined structure,
A
.I TAILQ_HEAD
structure is declared as follows:
-.PP
+.P
.in +4
.EX
TAILQ_HEAD(HEADNAME, TYPE) head;
.EE
.in
-.PP
+.P
where
.I struct HEADNAME
is the structure to be defined, and
.I struct TYPE
is the type of the elements to be linked into the queue.
A pointer to the head of the queue can later be declared as:
-.PP
+.P
.in +4
.EX
struct HEADNAME *headp;
.EE
.in
-.PP
+.P
(The names
.I head
and
.I headp
are user selectable.)
-.PP
+.P
.BR TAILQ_ENTRY ()
declares a structure that connects the elements in the queue.
-.PP
+.P
.BR TAILQ_HEAD_INITIALIZER ()
evaluates to an initializer for the queue
.IR head .
-.PP
+.P
.BR TAILQ_INIT ()
initializes the queue referenced by
-.PP
+.P
.BR TAILQ_EMPTY ()
evaluates to true if there are no items on the queue.
.IR head .
inserts the new element
.I elm
at the head of the queue.
-.PP
+.P
.BR TAILQ_INSERT_TAIL ()
inserts the new element
.I elm
at the end of the queue.
-.PP
+.P
.BR TAILQ_INSERT_BEFORE ()
inserts the new element
.I elm
before the element
.IR listelm .
-.PP
+.P
.BR TAILQ_INSERT_AFTER ()
inserts the new element
.I elm
.SS Traversal
.BR TAILQ_FIRST ()
returns the first item on the queue, or NULL if the queue is empty.
-.PP
+.P
.BR TAILQ_LAST ()
returns the last item on the queue.
If the queue is empty the return value is NULL.
-.PP
+.P
.BR TAILQ_PREV ()
returns the previous item on the queue, or NULL if this item is the first.
-.PP
+.P
.BR TAILQ_NEXT ()
returns the next item on the queue, or NULL if this item is the last.
-.PP
+.P
.BR TAILQ_FOREACH ()
traverses the queue referenced by
.I head
.I var
is set to NULL if the loop completes normally,
or if there were no elements.
-.\" .PP
+.\" .P
.\" .BR TAILQ_FOREACH_FROM ()
.\" behaves identically to
.\" .BR TAILQ_FOREACH ()
.\" .I var
.\" instead of the first element in the TAILQ referenced by
.\" .IR head .
-.PP
+.P
.BR TAILQ_FOREACH_REVERSE ()
traverses the queue referenced by
.I head
in the reverse direction,
assigning each element in turn to
.IR var .
-.\" .PP
+.\" .P
.\" .BR TAILQ_FOREACH_REVERSE_FROM ()
.\" behaves identically to
.\" .BR TAILQ_FOREACH_REVERSE ()
.\" .I var
.\" instead of the last element in the TAILQ referenced by
.\" .IR head .
-.\" .PP
+.\" .P
.\" .BR TAILQ_FOREACH_SAFE ()
.\" and
.\" .BR TAILQ_FOREACH_REVERSE_SAFE ()
.\" .I var
.\" as well as free it from within the loop safely without interfering with the
.\" traversal.
-.\" .PP
+.\" .P
.\" .BR TAILQ_FOREACH_FROM_SAFE ()
.\" behaves identically to
.\" .BR TAILQ_FOREACH_SAFE ()
.\" .I var
.\" instead of the first element in the TAILQ referenced by
.\" .IR head .
-.\" .PP
+.\" .P
.\" .BR TAILQ_FOREACH_REVERSE_FROM_SAFE ()
.\" behaves identically to
.\" .BR TAILQ_FOREACH_REVERSE_SAFE ()
.\" .I head1
.\" and
.\" .IR head2 .
-.\" .PP
+.\" .P
.BR TAILQ_CONCAT ()
concatenates the queue headed by
.I head2
.BR TAILQ_EMPTY ()
returns nonzero if the queue is empty,
and zero if the queue contains at least one entry.
-.PP
+.P
.BR TAILQ_FIRST (),
.BR TAILQ_LAST (),
.BR TAILQ_PREV (),
return a pointer to the first, last, previous, or next
.I TYPE
structure, respectively.
-.PP
+.P
.BR TAILQ_HEAD_INITIALIZER ()
returns an initializer that can be assigned to the queue
.IR head .
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "double tan(double " x );
.BI "float tanf(float " x );
.BI "long double tanl(long double " x );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR tanf (),
.BR tanl ():
.nf
.SH RETURN VALUE
On success, these functions return the tangent of
.IR x .
-.PP
+.P
If
.I x
is a NaN, a NaN is returned.
-.PP
+.P
If
.I x
is positive infinity or negative infinity,
a domain error occurs,
and a NaN is returned.
-.PP
+.P
If the correct result would overflow,
a range error occurs,
and the functions return
.BR math_error (7)
for information on how to determine whether an error has occurred
when calling these functions.
-.PP
+.P
The following errors can occur:
.TP
Domain error: \fIx\fP is an infinity
C11, POSIX.1-2008.
.SH HISTORY
C99, POSIX.1-2001.
-.PP
+.P
The variant returning
.I double
also conforms to
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "double tanh(double " x );
.BI "float tanhf(float " x );
.BI "long double tanhl(long double " x );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR tanhf (),
.BR tanhl ():
.nf
.IR x ,
which
is defined mathematically as:
-.PP
+.P
.nf
tanh(x) = sinh(x) / cosh(x)
.fi
.SH RETURN VALUE
On success, these functions return the hyperbolic tangent of
.IR x .
-.PP
+.P
If
.I x
is a NaN, a NaN is returned.
-.PP
+.P
If
.I x
is +0 (\-0), +0 (\-0) is returned.
-.PP
+.P
If
.I x
is positive infinity (negative infinity),
C11, POSIX.1-2008.
.SH HISTORY
C99, POSIX.1-2001.
-.PP
+.P
The variant returning
.I double
also conforms to
.SH SYNOPSIS
.nf
.B "#include <unistd.h>"
-.PP
+.P
.BI "pid_t tcgetpgrp(int " fd );
.BI "int tcsetpgrp(int " fd ", pid_t " pgrp );
.fi
.IR fd ,
which must be the controlling terminal of the calling process.
.\" The process itself may be a background process.
-.PP
+.P
The function
.BR tcsetpgrp ()
makes the process group with process group ID
.I pgrp
must be a (nonempty) process group belonging to
the same session as the calling process.
-.PP
+.P
If
.BR tcsetpgrp ()
is called by a member of a background process group in its session,
\-1 is returned, and
.I errno
is set to indicate the error.
-.PP
+.P
When successful,
.BR tcsetpgrp ()
returns 0.
POSIX.1-2008.
.SH HISTORY
POSIX.1-2001.
-.PP
+.P
The ioctls appeared in 4.2BSD.
The functions are POSIX inventions.
.SH SEE ALSO
.nf
.BR "#define _XOPEN_SOURCE 500" " /* See feature_test_macros(7) */"
.B "#include <termios.h>"
-.PP
+.P
.BI "pid_t tcgetsid(int " fd );
.fi
.SH DESCRIPTION
.SH HISTORY
glibc 2.1.
POSIX.1-2001.
-.PP
+.P
This function is implemented via the
.B TIOCGSID
.BR ioctl (2),
.SH SYNOPSIS
.nf
.B #include <dirent.h>
-.PP
+.P
.BI "long telldir(DIR *" dirp );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR telldir ():
.nf
_XOPEN_SOURCE
POSIX.1-2008.
.SH HISTORY
POSIX.1-2001, 4.3BSD.
-.PP
+.P
Up to glibc 2.1.1, the return type of
.BR telldir ()
was
POSIX.1-2001 specifies
.IR long ,
and this is the type used since glibc 2.1.2.
-.PP
+.P
In early filesystems, the value returned by
.BR telldir ()
was a simple file offset within a directory.
.SH SYNOPSIS
.nf
.B #include <stdio.h>
-.PP
+.P
.BI "char *tempnam(const char *" dir ", const char *" pfx );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR tempnam ():
.nf
Since glibc 2.19:
or
.BR tmpfile (3)
instead.
-.PP
+.P
The
.BR tempnam ()
function returns a pointer to a string that is a valid filename,
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).
-.PP
+.P
Attempts to find an appropriate directory go through the following
steps:
.TP 3
.TP
d)
Finally an implementation-defined directory may be used.
-.PP
+.P
The string returned by
.BR tempnam ()
is allocated using
.BR mkstemp (3)
or
.BR tmpfile (3).
-.PP
+.P
SUSv2 does not mention the use of
.BR TMPDIR ;
glibc will use it only
On SVr4, the directory used under \fBd)\fP is
.I /tmp
(and this is what glibc does).
-.PP
+.P
Because it dynamically allocates memory used to return the pathname,
.BR tempnam ()
is reentrant, and thus thread safe, unlike
.BR tmpnam (3).
-.PP
+.P
The
.BR tempnam ()
function generates a different string each time it is called,
.B TMP_MAX
times,
the behavior is implementation defined.
-.PP
+.P
.BR tempnam ()
uses at most the first five bytes from
.IR pfx .
-.PP
+.P
The glibc implementation of
.BR tempnam ()
fails with the error
.nf
.B #include <termios.h>
.B #include <unistd.h>
-.PP
+.P
.BI "int tcgetattr(int " fd ", struct termios *" termios_p );
.BI "int tcsetattr(int " fd ", int " optional_actions ,
.BI " const struct termios *" termios_p );
-.PP
+.P
.BI "int tcsendbreak(int " fd ", int " duration );
.BI "int tcdrain(int " fd );
.BI "int tcflush(int " fd ", int " queue_selector );
.BI "int tcflow(int " fd ", int " action );
-.PP
+.P
.BI "void cfmakeraw(struct termios *" termios_p );
-.PP
+.P
.BI "speed_t cfgetispeed(const struct termios *" termios_p );
.BI "speed_t cfgetospeed(const struct termios *" termios_p );
-.PP
+.P
.BI "int cfsetispeed(struct termios *" termios_p ", speed_t " speed );
.BI "int cfsetospeed(struct termios *" termios_p ", speed_t " speed );
.BI "int cfsetspeed(struct termios *" termios_p ", speed_t " speed );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR cfsetspeed (),
.BR cfmakeraw ():
.nf
Many of the functions described here have a \fItermios_p\fP argument
that is a pointer to a \fItermios\fP structure.
This structure contains at least the following members:
-.PP
+.P
.in +4n
.EX
tcflag_t c_iflag; /* input modes */
cc_t c_cc[NCCS]; /* special characters */
.EE
.in
-.PP
+.P
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
exposed only if a specific feature test macro (see
.BR feature_test_macros (7))
is defined, as noted in brackets ("[]").
-.PP
+.P
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.
-.PP
+.P
\fIc_iflag\fP flag constants:
.TP
.B IGNBRK
.BR IUTF8 " (since Linux 2.6.4)"
(not in POSIX) Input is UTF8;
this allows character-erase to be correctly performed in cooked mode.
-.PP
+.P
.I c_oflag
flag constants:
.TP
.B _SVID_SOURCE
or
.BR _XOPEN_SOURCE ]
-.PP
+.P
\fIc_cflag\fP flag constants:
.TP
.B CBAUD
.B _BSD_SOURCE
or
.BR _SVID_SOURCE ]
-.PP
+.P
\fIc_lflag\fP flag constants:
.TP
.B ISIG
This flag, as well as \fBICANON\fP must be enabled for the
special characters EOL2, LNEXT, REPRINT, WERASE to be interpreted,
and for the \fBIUCLC\fP flag to be effective.
-.PP
+.P
The \fIc_cc\fP array defines the terminal special characters.
The symbolic indices (initial values) and meaning are:
.TP
and
.B IEXTEN
are set, and then not passed as input.
-.PP
+.P
An individual terminal special character can be disabled by setting
the value of the corresponding
.I c_cc
element to
.BR _POSIX_VDISABLE .
-.PP
+.P
The above symbolic subscript values are all different, except that
.BR VTIME ,
.B VMIN
This function may be invoked from a background process;
however, the terminal attributes may be subsequently changed by a
foreground process.
-.PP
+.P
.BR tcsetattr ()
sets the parameters associated with the terminal (unless support is
required from the underlying hardware that is not available) from the
By default,
.B ICANON
is set.
-.PP
+.P
In canonical mode:
.IP \[bu] 3
Input is made available line by line.
(but not including) any terminating newline is discarded.
This ensures that the terminal can always receive
more input until at least one line can be read.
-.PP
+.P
In noncanonical mode input is available immediately (without
the user having to type a line-delimiter character),
no input processing is performed,
If data is already available at the time of the call to
.BR read (2),
the call behaves as though the data was received immediately after the call.
-.PP
+.P
POSIX
.\" POSIX.1-2008 XBD 11.1.7
does not specify whether the setting of the
echoing is disabled, and all special processing of
terminal input and output characters is disabled.
The terminal attributes are set as follows:
-.PP
+.P
.in +4n
.EX
termios_p\->c_iflag &= \[ti](IGNBRK | BRKINT | PARMRK | ISTRIP
for at least 0.25 seconds, and not more than 0.5 seconds.
If \fIduration\fP is not zero, it sends zero-valued bits for some
implementation-defined length of time.
-.PP
+.P
If the terminal is not using asynchronous serial data transmission,
.BR tcsendbreak ()
returns without taking any action.
-.PP
+.P
.BR tcdrain ()
waits until all output written to the object referred to by
.I fd
has been transmitted.
-.PP
+.P
.BR tcflush ()
discards data written to the object referred to by
.I fd
.B TCIOFLUSH
flushes both data received but not read, and data written but not
transmitted.
-.PP
+.P
.BR tcflow ()
suspends transmission or reception of data on the object referred to by
.IR fd ,
.B TCION
transmits a START character, which starts the terminal device
transmitting data to the system.
-.PP
+.P
The default on open of a terminal file is that neither its input nor its
output is suspended.
.SS Line speed
until
.BR tcsetattr ()
is successfully called.
-.PP
+.P
Setting the speed to \fBB0\fP instructs the modem to "hang up".
The actual bit rate corresponding to \fBB38400\fP may be altered with
.BR setserial (8).
-.PP
+.P
The input and output baud rates are stored in the \fItermios\fP
structure.
-.PP
+.P
.BR cfgetospeed ()
returns the output baud rate stored in the \fItermios\fP structure
pointed to by
.IR termios_p .
-.PP
+.P
.BR cfsetospeed ()
sets the output baud rate stored in the \fItermios\fP structure pointed
to by \fItermios_p\fP to \fIspeed\fP, which must be one of these constants:
.TQ
.B B2000000
.RE
-.PP
+.P
These constants are additionally supported on the SPARC architecture:
.RS
.TP
.TQ
.B B614400
.RE
-.PP
+.P
These constants are additionally supported on non-SPARC architectures:
.RS
.TP
.TQ
.B B4000000
.RE
-.PP
+.P
Due to differences between architectures, portable applications should check
if a particular
.BI B nnn
constant is defined prior to using it.
-.PP
+.P
The zero baud rate,
.BR B0 ,
is used to terminate the connection.
Thus,
.BR B57600 " & " CBAUDEX
is nonzero.
-.PP
+.P
Setting the baud rate to a value other than those defined by
.BI B nnn
constants is possible via the
.B TCSETS2
ioctl; see
.BR ioctl_tty (2).
-.PP
+.P
.BR cfgetispeed ()
returns the input baud rate stored in the
.I termios
structure.
-.PP
+.P
.BR cfsetispeed ()
sets the input baud rate stored in the
.I termios
.BR B0 ),
the input baud rate will be
equal to the output baud rate.
-.PP
+.P
.BR cfsetspeed ()
is a 4.4BSD extension.
It takes the same arguments as
returns the input baud rate stored in the
\fItermios\fP
structure.
-.PP
+.P
.BR cfgetospeed ()
returns the output baud rate stored in the \fItermios\fP structure.
-.PP
+.P
All other functions return:
.TP
.B 0
on failure and set
.I errno
to indicate the error.
-.PP
+.P
Note that
.BR tcsetattr ()
returns success if \fIany\fP of the requested changes could be
.B EXTB
("External A" and "External B").
Many systems extend the list with much higher baud rates.
-.PP
+.P
The effect of a nonzero \fIduration\fP with
.BR tcsendbreak ()
varies.
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "double tgamma(double " x );
.BI "float tgammaf(float " x );
.BI "long double tgammal(long double " x );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR tgamma (),
.BR tgammaf (),
.BR tgammal ():
.SH DESCRIPTION
These functions calculate the Gamma function of
.IR x .
-.PP
+.P
The Gamma function is defined by
-.PP
+.P
.RS
Gamma(x) = integral from 0 to infinity of t\[ha](x\-1) e\[ha]\-t dt
.RE
-.PP
+.P
It is defined for every real number except for nonpositive integers.
For nonnegative integral
.I m
one has
-.PP
+.P
.RS
Gamma(m+1) = m!
.RE
-.PP
+.P
and, more generally, for all
.IR x :
-.PP
+.P
.RS
Gamma(x+1) = x * Gamma(x)
.RE
-.PP
+.P
Furthermore, the following is valid for all values of
.I x
outside the poles:
-.PP
+.P
.RS
Gamma(x) * Gamma(1 \- x) = PI / sin(PI * x)
.RE
.SH RETURN VALUE
On success, these functions return Gamma(x).
-.PP
+.P
If
.I x
is a NaN, a NaN is returned.
-.PP
+.P
If
.I x
is positive infinity, positive infinity is returned.
-.PP
+.P
If
.I x
is a negative integer, or is negative infinity,
a domain error occurs,
and a NaN is returned.
-.PP
+.P
If the result overflows,
a range error occurs,
and the functions return
or
.BR HUGE_VALL ,
respectively, with the correct mathematical sign.
-.PP
+.P
If the result underflows,
a range error occurs,
and the functions return 0, with the correct mathematical sign.
-.PP
+.P
If
.I x
is \-0 or +0,
.BR math_error (7)
for information on how to determine whether an error has occurred
when calling these functions.
-.PP
+.P
The following errors can occur:
.TP
Domain error: \fIx\fP is a negative integer, or negative infinity
An overflow floating-point exception
.RB ( FE_OVERFLOW )
is raised.
-.PP
+.P
glibc also gives the following error which is not specified
in C99 or POSIX.1-2001.
.TP
when
.I x
is negative infinity.
-.PP
+.P
Before glibc 2.19,
.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6810
the glibc implementation of these functions did not set
to
.B ERANGE
on an underflow range error.
-.PP
+.P
.\"
In glibc versions 2.3.3 and earlier,
an argument of +0 or \-0 incorrectly produced a domain error
.SH SYNOPSIS
.nf
.B #include <time.h>
-.PP
+.P
.BI "[[deprecated]] time_t timelocal(struct tm *" tm );
.BI "time_t timegm(struct tm *" tm );
-.PP
+.P
.fi
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR timelocal (),
.BR timegm ():
.nf
BSD.
.SH HISTORY
GNU, BSD.
-.PP
+.P
The
.BR timelocal ()
function is equivalent to the POSIX standard function
.SH SYNOPSIS
.nf
.B #include <sys/time.h>
-.PP
+.P
.BI "void timeradd(struct timeval *" a ", struct timeval *" b ,
.BI " struct timeval *" res );
.BI "void timersub(struct timeval *" a ", struct timeval *" b ,
.BI " struct timeval *" res );
-.PP
+.P
.BI "void timerclear(struct timeval *" tvp );
.BI "int timerisset(struct timeval *" tvp );
-.PP
+.P
.BI "int timercmp(struct timeval *" a ", struct timeval *" b ", " CMP );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
All functions shown above:
.nf
Since glibc 2.19:
structures, defined in
.I <sys/time.h>
as:
-.PP
+.P
.in +4n
.EX
struct timeval {
};
.EE
.in
-.PP
+.P
.BR timeradd ()
adds the time values in
.I a
The result is normalized such that
.I res\->tv_usec
has a value in the range 0 to 999,999.
-.PP
+.P
.BR timersub ()
subtracts the time value in
.I b
The result is normalized such that
.I res\->tv_usec
has a value in the range 0 to 999,999.
-.PP
+.P
.BR timerclear ()
zeros out the
.I timeval
structure pointed to by
.IR tvp ,
so that it represents the Epoch: 1970-01-01 00:00:00 +0000 (UTC).
-.PP
+.P
.BR timerisset ()
returns true (nonzero) if either field of the
.I timeval
structure pointed to by
.I tvp
contains a nonzero value.
-.PP
+.P
.BR timercmp ()
compares the timer values in
.I a
.I ==
do not work;
portable applications can instead use
-.PP
+.P
.in +4n
.EX
!timercmp(..., <)
.SH SYNOPSIS
.nf
.B #include <stdio.h>
-.PP
+.P
.B FILE *tmpfile(void);
.fi
.SH DESCRIPTION
.SH SYNOPSIS
.nf
.B #include <stdio.h>
-.PP
+.P
.BI "[[deprecated]] char *tmpnam(char *" s );
.BI "[[deprecated]] char *tmpnam_r(char *" s );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR tmpnam_r ()
.nf
Since glibc 2.19:
or
.BR tmpfile (3)
instead.
-.PP
+.P
The
.BR tmpnam ()
function returns a pointer to a string that is a valid filename,
and the value
.I s
is returned in case of success.
-.PP
+.P
The created pathname has a directory prefix
.IR P_tmpdir .
(Both
just like the
.B TMP_MAX
mentioned below.)
-.PP
+.P
The
.BR tmpnam_r ()
function performs the same task as
.B TMP_MAX
times,
the behavior is implementation defined.
-.PP
+.P
Although these functions generate names that are difficult to guess,
it is nevertheless possible that between the time that
the pathname is returned and the time that the program opens it,
.BR mkstemp (3)
or
.BR tmpfile (3).
-.PP
+.P
Portable applications that use threads cannot call
.BR tmpnam ()
with a NULL argument if either
.SH SYNOPSIS
.nf
.B #include <ctype.h>
-.PP
+.P
.BI "[[deprecated]] int toascii(int " c );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR toascii ():
.nf
_XOPEN_SOURCE
.SH SYNOPSIS
.nf
.B #include <ctype.h>
-.PP
+.P
.BI "int toupper(int " "c" );
.BI "int tolower(int " "c" );
-.PP
+.P
.BI "int toupper_l(int " c ", locale_t " locale );
.BI "int tolower_l(int " c ", locale_t " locale );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR toupper_l (),
.BR tolower_l ():
.nf
.fi
.SH DESCRIPTION
These functions convert lowercase letters to uppercase, and vice versa.
-.PP
+.P
If
.I c
is a lowercase letter,
function performs the same task,
but uses the locale referred to by the locale handle
.IR locale .
-.PP
+.P
If
.I c
is an uppercase letter,
function performs the same task,
but uses the locale referred to by the locale handle
.IR locale .
-.PP
+.P
If
.I c
is neither an
.BR EOF ,
the behavior of these functions
is undefined.
-.PP
+.P
The behavior of
.BR toupper_l ()
and
it must be cast to
.IR "unsigned char" ,
as in the following example:
-.PP
+.P
.in +4n
.EX
char c;
res = toupper((unsigned char) c);
.EE
.in
-.PP
+.P
This is necessary because
.I char
may be the equivalent
.IR int ,
yielding a value that is outside the range of
.IR "unsigned char" .
-.PP
+.P
The details of what constitutes an uppercase or lowercase letter depend
on the locale.
For example, the default
.B """C"""
locale does not know about umlauts, so no conversion is done for them.
-.PP
+.P
In some non-English locales, there are lowercase letters with no
corresponding uppercase equivalent;
.\" FIXME One day the statement about "sharp s" needs to be reworked,
.SH SYNOPSIS
.nf
.B #include <wctype.h>
-.PP
+.P
.BI "wint_t towctrans(wint_t " wc ", wctrans_t " desc );
.fi
.SH DESCRIPTION
.BR WEOF ,
.B WEOF
is returned.
-.PP
+.P
.I desc
must be a transliteration descriptor returned by
the
.SH SYNOPSIS
.nf
.B #include <wctype.h>
-.PP
+.P
.BI "wint_t towlower(wint_t " wc );
.BI "wint_t towlower_l(wint_t " wc ", locale_t " locale );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR towlower_l ():
.nf
Since glibc 2.10:
In all other cases,
.I wc
is returned unchanged.
-.PP
+.P
The
.BR towlower_l ()
function performs the same task,
(see
.BR duplocale (3))
or is not a valid locale object handle.
-.PP
+.P
The argument
.I wc
must be representable as a
The behavior of these functions depends on the
.B LC_CTYPE
category of the locale.
-.PP
+.P
These functions are not very appropriate for dealing with Unicode characters,
because Unicode knows about three cases: upper, lower, and title case.
.SH SEE ALSO
.SH SYNOPSIS
.nf
.B #include <wctype.h>
-.PP
+.P
.BI "wint_t towupper(wint_t " wc );
.BI "wint_t towupper_l(wint_t " wc ", locale_t " locale );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR towupper_l ():
.nf
Since glibc 2.10:
In all other cases,
.I wc
is returned unchanged.
-.PP
+.P
The
.BR towupper_l ()
function performs the same task,
(see
.BR duplocale (3))
or is not a valid locale object handle.
-.PP
+.P
The argument
.I wc
must be representable as a
The behavior of these functions depends on the
.B LC_CTYPE
category of the locale.
-.PP
+.P
These functions are not very appropriate for dealing with Unicode characters,
because Unicode knows about three cases: upper, lower, and title case.
.SH SEE ALSO
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "double trunc(double " x );
.BI "float truncf(float " x );
.BI "long double truncl(long double " x );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR trunc (),
.BR truncf (),
.BR truncl ():
.IR x .
.SH RETURN VALUE
These functions return the rounded integer value, in floating format.
-.PP
+.P
If
.I x
is integral, infinite, or NaN,
.SH SYNOPSIS
.nf
.B #include <search.h>
-.PP
+.P
.B typedef enum { preorder, postorder, endorder, leaf } VISIT;
-.PP
+.P
.BI "void *tsearch(const void *" key ", void **" rootp ,
.BI " int (*" compar ")(const void *, const void *));"
.BI "void *tfind(const void *" key ", void *const *" rootp ,
.BI "void twalk(const void *" root ,
.BI " void (*" action ")(const void *" nodep ", VISIT " which ,
.BI " int " depth ));
-.PP
+.P
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <search.h>
-.PP
+.P
.BI "void twalk_r(const void *" root ,
.BI " void (*" action ")(const void *" nodep ", VISIT " which ,
.BI " void *" closure ),
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.
-.PP
+.P
.BR tsearch ()
searches the tree for an item.
.I key
.BR tsearch ()
adds it, and returns a
pointer to the corresponding tree node.
-.PP
+.P
.BR tfind ()
is like
.BR tsearch (),
found, then
.BR tfind ()
returns NULL.
-.PP
+.P
.BR tdelete ()
deletes an item from the tree.
Its arguments are the same as for
.BR tsearch ().
-.PP
+.P
.BR twalk ()
performs depth-first, left-to-right traversal of a binary
tree.
.IR <search.h> .)
The third argument is the depth of the node;
the root node has depth zero.
-.PP
+.P
(More commonly,
.BR preorder ,
.BR postorder ,
Thus, the choice of name
.B post\%order
is rather confusing.)
-.PP
+.P
.BR twalk_r ()
is similar to
.BR twalk (),
This pointer can be used to pass information to and from
the callback function in a thread-safe fashion, without resorting
to global variables.
-.PP
+.P
.BR tdestroy ()
removes the whole tree pointed to by
.IR root ,
NULL if no match is found.
If there are multiple items that match the key,
the item whose node is returned is unspecified.
-.PP
+.P
.BR tdelete ()
returns a pointer to the parent of the node deleted, or
NULL if the item was not found.
If the deleted node was the root node,
.BR tdelete ()
returns a dangling pointer that must not be accessed.
-.PP
+.P
.BR tsearch (),
.BR tfind (),
and
.BR twalk ()
takes a pointer to the root, while the other functions
take a pointer to a variable which points to the root.
-.PP
+.P
.BR tdelete ()
frees the memory required for the node in the tree.
The user is responsible for freeing the memory for the corresponding
data.
-.PP
+.P
The example program depends on the fact that
.BR twalk ()
makes no
The following program inserts twelve random numbers into a binary
tree, where duplicate numbers are collapsed, then prints the numbers
in order.
-.PP
+.P
.\" SRC BEGIN (tsearch.c)
.EX
#define _GNU_SOURCE /* Expose declaration of tdestroy() */
.SH SYNOPSIS
.nf
.B #include <unistd.h>
-.PP
+.P
.BI "char *ttyname(int " fd );
.BI "int ttyname_r(int " fd ", char " buf [. buflen "], size_t " buflen );
.fi
.SH SYNOPSIS
.nf
.BR "#include <unistd.h>" " /* See NOTES */"
-.PP
+.P
.B "int ttyslot(void);"
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR ttyslot ():
.nf
Since glibc 2.24:
The legacy function
.BR ttyslot ()
returns the index of the current user's entry in some file.
-.PP
+.P
Now "What file?" you ask.
Well, let's first look at some history.
.SS Ancient history
Thus a typical line was "18\-".
A hang on some line was solved by changing the \[aq]1\[aq] to a \[aq]0\[aq],
signaling init, changing back again, and signaling init again.
-.PP
+.P
In UNIX\ V7 the format was changed: here the second character
was the argument to
.BR getty (8)
300-1200-150-110 baud; \[aq]4\[aq] 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".
-.PP
+.P
Later systems have more elaborate syntax.
System V-like systems have
.I /etc/inittab
.SH HISTORY
SUSv1; marked as LEGACY in SUSv2; removed in POSIX.1-2001.
SUSv2 requires \-1 on error.
-.PP
+.P
The glibc2 implementation of this function reads the file
.BR _PATH_TTYS ,
defined in
It returns 0 on error.
Since Linux systems do not usually have "/etc/ttys", it will
always return 0.
-.PP
+.P
On BSD-like systems and Linux, the declaration of
.BR ttyslot ()
is provided by
.I <stdlib.h>
also provides the declaration with the following
feature test macro definitions:
-.PP
+.P
.in +4n
.EX
(_XOPEN_SOURCE >= 500 ||
&& ! (_POSIX_C_SOURCE >= 200112L || _XOPEN_SOURCE >= 600)
.EE
.in
-.PP
+.P
Minix also has
.IR fttyslot ( fd ).
.\" .SH HISTORY
.SH SYNOPSIS
.nf
.B #include <time.h>
-.PP
+.P
.B void tzset(void);
-.PP
+.P
.BI "extern char *" tzname [2];
.BI "extern long " timezone ;
.BI "extern int " daylight ;
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR tzset ():
.nf
_POSIX_C_SOURCE
.fi
-.PP
+.P
.IR tzname :
.nf
_POSIX_C_SOURCE
.fi
-.PP
+.P
.IR timezone ,
.IR daylight :
.nf
(seconds West of UTC) and \fIdaylight\fP (to 0 if this timezone does not
have any daylight saving time rules, or to nonzero if there is a time,
past, present, or future when daylight saving time applies).
-.PP
+.P
If the
.B TZ
variable does not appear in the environment, the system timezone is used.
.IR /etc/localtime .
A timezone database of these files may be located in the system
timezone directory (see the \fBFILES\fP section below).
-.PP
+.P
If the
.B 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, then Coordinated Universal Time (UTC) is used.
-.PP
+.P
The value of
.B TZ
can be one of two formats.
The first format is a string of characters that directly represent the
timezone to be used:
-.PP
+.P
.in +4n
.EX
.IR "std offset" [ dst [ offset ][, start [ /time ], end [ /time ]]]
.EE
.in
-.PP
+.P
There are no spaces in the specification.
The \fIstd\fP string specifies an abbreviation for the timezone and must be
three or more alphabetic characters.
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 00 and 59:
-.PP
+.P
.in +4n
.EX
.RI [ + | \- ] hh [ :mm [ :ss ]]
.EE
.in
-.PP
+.P
The \fIdst\fP string and \fIoffset\fP specify the name and offset for the
corresponding daylight saving timezone.
If the offset is omitted,
it defaults to one hour ahead of standard time.
-.PP
+.P
The \fIstart\fP field specifies when daylight saving time goes into
effect and the \fIend\fP field specifies when the change is made back to
standard time.
the first week in which day \fId\fP occurs and week 5 is the last week
in which day \fId\fP occurs.
Day 0 is a Sunday.
-.PP
+.P
The \fItime\fP 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.
-.PP
+.P
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:
-.PP
+.P
.in +4n
.EX
TZ="NZST\-12:00:00NZDT\-13:00:00,M10.1.0,M3.3.0"
.EE
.in
-.PP
+.P
The second format specifies that the timezone information should be read
from a file:
-.PP
+.P
.in +4n
.EX
:[filespec]
.EE
.in
-.PP
+.P
If the file specification \fIfilespec\fP is omitted, or its value cannot
be interpreted, then Coordinated Universal Time (UTC) is used.
If \fIfilespec\fP is given, it specifies another
relative to the system timezone directory.
If the colon is omitted each
of the above \fBTZ\fP formats will be tried.
-.PP
+.P
Here's an example, once more for New Zealand:
-.PP
+.P
.in +4n
.EX
TZ=":Pacific/Auckland"
format.
By default, the zoneinfo Makefile hard links it to the
.IR America/New_York " tzfile."
-.PP
+.P
Above are the current standard file locations, but they are
configurable when glibc is compiled.
.SH ATTRIBUTES
POSIX.1-2008.
.SH HISTORY
POSIX.1-2001, SVr4, 4.3BSD.
-.PP
+.P
4.3BSD had a function
.BI "char *timezone(" zone ", " dst )
that returned the
.SH SYNOPSIS
.nf
.B "#include <unistd.h>"
-.PP
+.P
.BI "useconds_t ualarm(useconds_t " usecs ", useconds_t " interval );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR ualarm ():
.nf
Since glibc 2.12:
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.
-.PP
+.P
Unless caught or ignored, the
.B SIGALRM
signal will terminate the process.
-.PP
+.P
If the
.I interval
argument is nonzero, further
4.3BSD, POSIX.1-2001.
POSIX.1-2001 marks it as obsolete.
Removed in POSIX.1-2008.
-.PP
+.P
4.3BSD, SUSv2, and POSIX do not define any errors.
-.PP
+.P
POSIX.1-2001 does not specify what happens if the
.I usecs
argument is 0.
.\" This case is not documented in HP-US, Solar, FreeBSD, NetBSD, or OpenBSD!
On Linux (and probably most other systems),
the effect is to cancel any pending alarm.
-.PP
+.P
The type
.I useconds_t
is an unsigned integer type capable of holding integers
Programs will be more portable if they never mention
.I useconds_t
explicitly.
-.PP
+.P
The interaction of this function with
other timer functions such as
.BR alarm (2),
.BR timer_settime (2),
.BR usleep (3)
is unspecified.
-.PP
+.P
This function is obsolete.
Use
.BR setitimer (2)
.SH SYNOPSIS
.nf
.B #include <ulimit.h>
-.PP
+.P
.BI "[[deprecated]] long ulimit(int " cmd ", long " newlimit );
.fi
.SH DESCRIPTION
.BR ulimit ,
see
.BR bash (1).
-.PP
+.P
The
.BR ulimit ()
call will get or set some limit for the calling process.
.SH SYNOPSIS
.nf
.B #include <wchar.h>
-.PP
+.P
.BI "wint_t ungetwc(wint_t " wc ", FILE *" stream );
.fi
.SH DESCRIPTION
It pushes back a wide character onto
.I stream
and returns it.
-.PP
+.P
If
.I wc
is
.B EILSEQ
and returns
.BR WEOF .
-.PP
+.P
If
.I wc
is a valid wide character, it is pushed back onto the stream
The end-of-file
indicator is cleared.
The backing storage of the file is not affected.
-.PP
+.P
Note:
.I wc
need not be the last wide-character read from the stream;
it can be any other valid wide character.
-.PP
+.P
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.
.SH SYNOPSIS
.nf
.B #include <stdio.h>
-.PP
+.P
.BI "int getc_unlocked(FILE *" stream );
.B "int getchar_unlocked(void);"
.BI "int putc_unlocked(int " c ", FILE *" stream );
.BI "int putchar_unlocked(int " c );
-.PP
+.P
.BI "void clearerr_unlocked(FILE *" stream );
.BI "int feof_unlocked(FILE *" stream );
.BI "int ferror_unlocked(FILE *" stream );
.BI "int fileno_unlocked(FILE *" stream );
.BI "int fflush_unlocked(FILE *_Nullable " stream );
-.PP
+.P
.BI "int fgetc_unlocked(FILE *" stream );
.BI "int fputc_unlocked(int " c ", FILE *" stream );
-.PP
+.P
.BI "size_t fread_unlocked(void " ptr "[restrict ." size " * ." n ],
.BI " size_t " size ", size_t " n ,
.BI " FILE *restrict " stream );
.BI "size_t fwrite_unlocked(const void " ptr "[restrict ." size " * ." n ],
.BI " size_t " size ", size_t " n ,
.BI " FILE *restrict " stream );
-.PP
+.P
.BI "char *fgets_unlocked(char " s "[restrict ." n "], int " n \
", FILE *restrict " stream );
.BI "int fputs_unlocked(const char *restrict " s ", FILE *restrict " stream );
-.PP
+.P
.B #include <wchar.h>
-.PP
+.P
.BI "wint_t getwc_unlocked(FILE *" stream );
.B "wint_t getwchar_unlocked(void);"
.BI "wint_t fgetwc_unlocked(FILE *" stream );
-.PP
+.P
.BI "wint_t fputwc_unlocked(wchar_t " wc ", FILE *" stream );
.BI "wint_t putwc_unlocked(wchar_t " wc ", FILE *" stream );
.BI "wint_t putwchar_unlocked(wchar_t " wc );
-.PP
+.P
.BI "wchar_t *fgetws_unlocked(wchar_t " ws "[restrict ." n "], int " n ,
.BI " FILE *restrict " stream );
.BI "int fputws_unlocked(const wchar_t *restrict " ws ,
.BI " FILE *restrict " stream );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR \%getc_unlocked (),
.BR \%getchar_unlocked (),
.BR \%putc_unlocked (),
|| /* glibc <= 2.23: */ _POSIX_C_SOURCE
|| /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE
.fi
-.PP
+.P
.BR \%clearerr_unlocked (),
.BR \%feof_unlocked (),
.BR \%ferror_unlocked (),
/* glibc >= 2.19: */ _DEFAULT_SOURCE
|| /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE
.fi
-.PP
+.P
.BR \%fgets_unlocked (),
.BR \%fputs_unlocked (),
.BR \%getwc_unlocked (),
.nf
.B #define _XOPEN_SOURCE
.B #include <stdlib.h>
-.PP
+.P
.BI "int unlockpt(int " fd );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR unlockpt ():
.nf
Since glibc 2.24:
function unlocks the slave pseudoterminal device
corresponding to the master pseudoterminal referred to by the file descriptor
.IR fd .
-.PP
+.P
.BR unlockpt ()
should be called before opening the slave side of a pseudoterminal.
.SH RETURN VALUE
.SH SYNOPSIS
.nf
.B #include <utmp.h>
-.PP
+.P
.BI "void updwtmp(const char *" wtmp_file ", const struct utmp *" ut );
.BI "void logwtmp(const char *" line ", const char *" name \
", const char *" host );
appends the utmp structure
.I ut
to the wtmp file.
-.PP
+.P
.BR logwtmp ()
constructs a utmp structure using
.IR line ", " name ", " host ,
For consistency with the other "utmpx" functions (see
.BR getutxent (3)),
glibc provides (since glibc 2.1):
-.PP
+.P
.in +4n
.EX
.BR "#define _GNU_SOURCE " "/* See feature_test_macros(7) */"
.BI "void updwtmpx (const char *" wtmpx_file ", const struct utmpx *" utx );
.EE
.in
-.PP
+.P
This function performs the same task as
.BR updwtmp (),
but differs in that it takes a
.SH SYNOPSIS
.nf
.B #include <locale.h>
-.PP
+.P
.BI "locale_t uselocale(locale_t " newloc );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR uselocale ():
.nf
Since glibc 2.10:
any calls by this thread to functions that depend on the locale
will operate as though the locale has been set to
.IR newloc .
-.PP
+.P
The
.I newloc
argument can have one of the following values:
.SH SYNOPSIS
.nf
.B "#include <unistd.h>"
-.PP
+.P
.BI "int usleep(useconds_t " usec );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR usleep ():
.nf
Since glibc 2.12:
.BR nanosleep (2)
instead.
Removed in POSIX.1-2008.
-.PP
+.P
On the original BSD implementation,
and before glibc 2.2.2, the return type of this function is
.IR void .
The POSIX version returns
.IR int ,
and this is also the prototype used since glibc 2.2.2.
-.PP
+.P
Only the
.B EINVAL
error return is documented by SUSv2 and POSIX.1-2001.
.SH SYNOPSIS
.nf
.B #include <wchar.h>
-.PP
+.P
.BI "wchar_t *wcpcpy(wchar_t *restrict " dest \
", const wchar_t *restrict " src );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR wcpcpy ():
.nf
Since glibc 2.10:
including the terminating null wide character (L\[aq]\e0\[aq]),
to the array pointed to by
.IR dest .
-.PP
+.P
The strings may not overlap.
-.PP
+.P
The programmer must ensure that there
is room for at least
.I wcslen(src)+1
.SH SYNOPSIS
.nf
.B #include <wchar.h>
-.PP
+.P
.BI "wchar_t *wcpncpy(wchar_t " dest "[restrict ." n ],
.BI " const wchar_t " src "[restrict ." n ],
.BI " size_t " n );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR wcpncpy ():
.nf
Since glibc 2.10:
.I dest
will
not be L\[aq]\e0\[aq] terminated.
-.PP
+.P
The strings may not overlap.
-.PP
+.P
The programmer must ensure that there is room for at least
.I n
wide
.SH SYNOPSIS
.nf
.B #include <wchar.h>
-.PP
+.P
.BI "size_t wcrtomb(char *restrict " s ", wchar_t " wc \
", mbstate_t *restrict " ps );
.fi
that is, the number of bytes
written at
.IR s .
-.PP
+.P
A different case is when
.I s
is not NULL,
and returns the length of the shift sequence plus
one, that is, the number of bytes written at
.IR s .
-.PP
+.P
A third case is when
.I s
is NULL.
.I wc
is ignored,
and the function effectively returns
-.PP
+.P
.in +4n
.EX
wcrtomb(buf, L\[aq]\e0\[aq], ps)
.EE
.in
-.PP
+.P
where
.I buf
is an internal anonymous buffer.
-.PP
+.P
In all of the above cases, if
.I ps
is NULL, a static anonymous
.B LC_CTYPE
category of the
current locale.
-.PP
+.P
Passing NULL as
.I ps
is not multithread safe.
.SH SYNOPSIS
.nf
.B #include <wchar.h>
-.PP
+.P
.BI "int wcscasecmp(const wchar_t *" s1 ", const wchar_t *" s2 );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR wcscasecmp ():
.nf
Since glibc 2.10:
.SH SYNOPSIS
.nf
.B #include <wchar.h>
-.PP
+.P
.BI "wchar_t *wcscat(wchar_t *restrict " dest \
", const wchar_t *restrict " src );
.fi
including the terminating null wide character (L\[aq]\e0\[aq]),
to the end of the wide-character string pointed to by
.IR dest .
-.PP
+.P
The strings may not overlap.
-.PP
+.P
The programmer must ensure that there is room for at least
.IR wcslen(dest) + wcslen(src) +1
wide characters at
.SH SYNOPSIS
.nf
.B #include <wchar.h>
-.PP
+.P
.BI "wchar_t *wcschr(const wchar_t *" wcs ", wchar_t " wc );
.fi
.SH DESCRIPTION
.SH SYNOPSIS
.nf
.B #include <wchar.h>
-.PP
+.P
.BI "int wcscmp(const wchar_t *" s1 ", const wchar_t *" s2 );
.fi
.SH DESCRIPTION
.SH SYNOPSIS
.nf
.B #include <wchar.h>
-.PP
+.P
.BI "wchar_t *wcscpy(wchar_t *restrict " dest \
", const wchar_t *restrict " src );
.fi
including the terminating null wide character (L\[aq]\e0\[aq]),
to the array pointed to by
.IR dest .
-.PP
+.P
The strings may not overlap.
-.PP
+.P
The programmer must ensure that there is
room for at least
.I wcslen(src)+1
.SH SYNOPSIS
.nf
.B #include <wchar.h>
-.PP
+.P
.BI "size_t wcscspn(const wchar_t *" wcs ", const wchar_t *" reject );
.fi
.SH DESCRIPTION
.SH SYNOPSIS
.nf
.B #include <wchar.h>
-.PP
+.P
.BI "wchar_t *wcsdup(const wchar_t *" s );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR wcsdup ():
.nf
Since glibc 2.10:
It allocates and returns a new wide-character string whose initial
contents is a duplicate of the wide-character string pointed to by
.IR s .
-.PP
+.P
Memory for the new wide-character string is
obtained with
.BR malloc (3),
.SH SYNOPSIS
.nf
.B #include <wchar.h>
-.PP
+.P
.BI "size_t wcslen(const wchar_t *" s );
.fi
.SH DESCRIPTION
.SH SYNOPSIS
.nf
.B #include <wchar.h>
-.PP
+.P
.BI "int wcsncasecmp(const wchar_t " s1 [. n "], const wchar_t " s2 [. n "], s\
ize_t " n );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR wcsncasecmp ():
.nf
Since glibc 2.10:
.SH SYNOPSIS
.nf
.B #include <wchar.h>
-.PP
+.P
.BI "wchar_t *wcsncat(wchar_t " dest "[restrict ." n ],
.BI " const wchar_t " src "[restrict ." n ],
.BI " size_t " n );
to by
.IR dest ,
and adds a terminating null wide character (L\[aq]\e0\[aq]).
-.PP
+.P
The strings may not overlap.
-.PP
+.P
The programmer must ensure that there is room for at least
.IR wcslen(dest) + n +1
wide characters at
.SH SYNOPSIS
.nf
.B #include <wchar.h>
-.PP
+.P
.BI "int wcsncmp(const wchar_t " s1 [. n "], const wchar_t " s2 [. n "], \
size_t " n );
.fi
.SH SYNOPSIS
.nf
.B #include <wchar.h>
-.PP
+.P
.BI "wchar_t *wcsncpy(wchar_t " dest "[restrict ." n ],
.BI " const wchar_t " src "[restrict ." n ],
.BI " size_t " n );
the string pointed to by
.I dest
will not be terminated by a null wide character.
-.PP
+.P
The strings may not overlap.
-.PP
+.P
The programmer must ensure that there is room for at least
.I n
wide
.SH SYNOPSIS
.nf
.B #include <wchar.h>
-.PP
+.P
.BI "size_t wcsnlen(const wchar_t " s [. maxlen "], size_t " maxlen );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR wcsnlen ():
.nf
Since glibc 2.10:
.SH SYNOPSIS
.nf
.B #include <wchar.h>
-.PP
+.P
.BI "size_t wcsnrtombs(char " dest "[restrict ." len "], \
const wchar_t **restrict " src ,
.BI " size_t " nwc ", size_t " len ", \
mbstate_t *restrict " ps );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR wcsnrtombs ():
.nf
Since glibc 2.10:
.IR *src ,
is limited to
.IR nwc .
-.PP
+.P
If
.I dest
is not NULL,
.IR dest ,
excluding the terminating null byte (\[aq]\e0\[aq]), is
returned.
-.PP
+.P
If
.I dest
is NULL,
and the conversion proceeds as above,
except that the converted bytes are not written out to memory, and that
no destination length limit exists.
-.PP
+.P
In both of the above cases,
if
.I ps
state known only to the
.BR wcsnrtombs ()
function is used instead.
-.PP
+.P
The programmer must ensure that there is room for at least
.I len
bytes
.B LC_CTYPE
category of the
current locale.
-.PP
+.P
Passing NULL as
.I ps
is not multithread safe.
.SH SYNOPSIS
.nf
.B #include <wchar.h>
-.PP
+.P
.BI "wchar_t *wcspbrk(const wchar_t *" wcs ", const wchar_t *" accept );
.fi
.SH DESCRIPTION
.SH SYNOPSIS
.nf
.B #include <wchar.h>
-.PP
+.P
.BI "wchar_t *wcsrchr(const wchar_t *" wcs ", wchar_t " wc );
.fi
.SH DESCRIPTION
.SH SYNOPSIS
.nf
.B #include <wchar.h>
-.PP
+.P
.BI "size_t wcsrtombs(char " dest "[restrict ." len "], \
const wchar_t **restrict " src ,
.BI " size_t " len ", mbstate_t *restrict " ps );
.IR dest ,
excluding the terminating null byte (\[aq]\e0\[aq]),
is returned.
-.PP
+.P
If
.I dest
is NULL,
and the conversion proceeds as above, except that the converted bytes
are not written out to memory, and that
no length limit exists.
-.PP
+.P
In both of the above cases,
if
.I ps
state known only to the
.BR wcsrtombs ()
function is used instead.
-.PP
+.P
The programmer must ensure that there is room for at least
.I len
bytes
.B LC_CTYPE
category of the
current locale.
-.PP
+.P
Passing NULL as
.I ps
is not multithread safe.
.SH SYNOPSIS
.nf
.B #include <wchar.h>
-.PP
+.P
.BI "size_t wcsspn(const wchar_t *" wcs ", const wchar_t *" accept );
.fi
.SH DESCRIPTION
.SH SYNOPSIS
.nf
.B #include <wchar.h>
-.PP
+.P
.BI "wchar_t *wcsstr(const wchar_t *" haystack ", const wchar_t *" needle );
.fi
.SH DESCRIPTION
does not occur
as a substring in
.IR haystack .
-.PP
+.P
Note the special case:
If
.I needle
.nf
.B #include <stddef.h>
.B #include <inttypes.h>
-.PP
+.P
.BI "intmax_t wcstoimax(const wchar_t *restrict " nptr ,
.BI " wchar_t **restrict " endptr ", int " base );
.BI "uintmax_t wcstoumax(const wchar_t *restrict " nptr ,
.SH SYNOPSIS
.nf
.B #include <wchar.h>
-.PP
+.P
.BI "wchar_t *wcstok(wchar_t *restrict " wcs \
", const wchar_t *restrict " delim ,
.BI " wchar_t **restrict " ptr );
into tokens, where a token is
defined as a substring not containing any wide-characters from
.IR delim .
-.PP
+.P
The search starts at
.IR wcs ,
if
the operation.
.SH EXAMPLES
The following code loops over the tokens contained in a wide-character string.
-.PP
+.P
.EX
wchar_t *wcs = ...;
wchar_t *token;
.SH SYNOPSIS
.nf
.B #include <stdlib.h>
-.PP
+.P
.BI "size_t wcstombs(char " dest "[restrict ." n "], \
const wchar_t *restrict " src ,
.BI " size_t " n );
The number of bytes written to
.IR dest ,
excluding the terminating null byte (\[aq]\e0\[aq]), is returned.
-.PP
+.P
The programmer must ensure that there is room for at least
.I n
bytes
at
.IR dest .
-.PP
+.P
If
.I dest
is NULL,
is ignored, and the conversion proceeds as
above, except that the converted bytes are not written out to memory,
and no length limit exists.
-.PP
+.P
In order to avoid the case 2 above, the programmer should make sure
.I n
is greater than or equal to
.nf
.BR "#define _XOPEN_SOURCE" " /* See feature_test_macros(7) */"
.B #include <wchar.h>
-.PP
+.P
.BI "int wcswidth(const wchar_t *" s ", size_t " n );
.fi
.SH DESCRIPTION
.SH SYNOPSIS
.nf
.B #include <wchar.h>
-.PP
+.P
.BI "int wctob(wint_t " c );
.fi
.SH DESCRIPTION
byte.
If so, it is returned as an
.IR "unsigned char" .
-.PP
+.P
Never use this function.
It cannot help you in writing internationalized
programs.
.B LC_CTYPE
category of the
current locale.
-.PP
+.P
This function should never be used.
Internationalized programs must never
distinguish single-byte and multibyte characters.
.SH SYNOPSIS
.nf
.B #include <stdlib.h>
-.PP
+.P
.BI "int wctomb(char *" s ", wchar_t " wc );
.fi
.SH DESCRIPTION
that is, the number of
bytes written at
.IR s .
-.PP
+.P
The programmer must ensure that there is
room for at least
.B MB_CUR_MAX
bytes at
.IR s .
-.PP
+.P
If
.I s
is NULL, the
can not be
represented as a multibyte sequence (according
to the current locale), \-1 is returned.
-.PP
+.P
If
.I s
is NULL, the
.SH SYNOPSIS
.nf
.B #include <wctype.h>
-.PP
+.P
.BI "wctrans_t wctrans(const char *" name );
.fi
.SH DESCRIPTION
.BR towctrans (3)
function to actually perform
the wide-character mapping.
-.PP
+.P
The
.BR wctrans ()
function returns a mapping, given by its name.
.B LC_CTYPE
category of the current locale, but the
following names are valid in all locales.
-.PP
+.P
.nf
"tolower" \- realizes the \fBtolower\fP(3) mapping
"toupper" \- realizes the \fBtoupper\fP(3) mapping
.SH SYNOPSIS
.nf
.B #include <wctype.h>
-.PP
+.P
.BI "wctype_t wctype(const char *" name );
.fi
.SH DESCRIPTION
function
to actually test whether a given
wide character has the property.
-.PP
+.P
The
.BR wctype ()
function returns a property, given by its name.
.B LC_CTYPE
category of the current locale, but the
following names are valid in all locales.
-.PP
+.P
.nf
"alnum" \- realizes the \fBisalnum\fP(3) classification function
"alpha" \- realizes the \fBisalpha\fP(3) classification function
.nf
.BR "#define _XOPEN_SOURCE" " /* See feature_test_macros(7) */"
.B #include <wchar.h>
-.PP
+.P
.BI "int wcwidth(wchar_t " c );
.fi
.SH DESCRIPTION
POSIX.1-2008.
.SH HISTORY
POSIX.1-2001.
-.PP
+.P
Note that before glibc 2.2.5, glibc used the prototype
-.PP
+.P
.nf
.BI "int wcwidth(wint_t " c );
.fi
.SH SYNOPSIS
.nf
.B #include <wchar.h>
-.PP
+.P
.BI "wchar_t *wmemchr(const wchar_t " s [. n "], wchar_t " c ", size_t " n );
.fi
.SH DESCRIPTION
.SH SYNOPSIS
.nf
.B #include <wchar.h>
-.PP
+.P
.BI "int wmemcmp(const wchar_t " s1 [. n "], const wchar_t " s2 [. n "], \
size_t " n );
.fi
.SH SYNOPSIS
.nf
.B #include <wchar.h>
-.PP
+.P
.BI "wchar_t *wmemcpy(wchar_t " dest "[restrict ." n ],
.BI " const wchar_t " src "[restrict ." n ],
.BI " size_t " n );
.I src
to the array starting at
.IR dest .
-.PP
+.P
The arrays may not overlap; use
.BR wmemmove (3)
to copy between overlapping
arrays.
-.PP
+.P
The programmer must ensure that there is room for at least
.I n
wide
.SH SYNOPSIS
.nf
.B #include <wchar.h>
-.PP
+.P
.BI "wchar_t *wmemmove(wchar_t " dest [. n "], const wchar_t " src [. n "], \
size_t " n );
.fi
.IR dest .
The arrays may
overlap.
-.PP
+.P
The programmer must ensure that there is room for at least
.I n
wide
.SH SYNOPSIS
.nf
.B #include <wchar.h>
-.PP
+.P
.BI "wchar_t *wmemset(wchar_t " wcs [. n "], wchar_t " wc ", size_t " n );
.fi
.SH DESCRIPTION
.SH SYNOPSIS
.nf
.B "#include <wordexp.h>"
-.PP
+.P
.BI "int wordexp(const char *restrict " s ", wordexp_t *restrict " p \
", int " flags );
.BI "void wordfree(wordexp_t *" p );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR wordexp (),
.BR wordfree ():
.nf
see below) used to indicate the number of initial elements in the
.I we_wordv
array that should be filled with NULLs.
-.PP
+.P
The function
.BR wordfree ()
frees the allocated memory again.
In particular, there must not be any unescaped
newline or |, &, ;, <, >, (, ), {, } characters
outside a command substitution or parameter substitution context.
-.PP
+.P
If the argument
.I s
contains a word that starts with an unquoted comment character #,
variable FOO), command substitution (replacing $(command) or \`command\`
by the output of command), arithmetic expansion, field splitting,
wildcard expansion, quote removal.
-.PP
+.P
The result of expansion of special parameters
($@, $*, $#, $?, $\-, $$, $!, $0) is unspecified.
-.PP
+.P
Field splitting is done using the environment variable $IFS.
If it is not set, the field separators are space, tab, and newline.
.SS The output array
.BR wordfree ()
T} Thread safety MT-Safe
.TE
-.PP
+.P
In the above table,
.I utent
in
.SH EXAMPLES
The output of the following example program
is approximately that of "ls [a-c]*.c".
-.PP
+.P
.\" SRC BEGIN (wordexp.c)
.EX
#include <stdio.h>
.nf
.B #include <stdio.h>
.B #include <wchar.h>
-.PP
+.P
.BI "int wprintf(const wchar_t *restrict " format ", ...);"
.BI "int fwprintf(FILE *restrict " stream ,
.BI " const wchar_t *restrict " format ", ...);"
.BI "int swprintf(wchar_t " wcs "[restrict ." maxlen "], size_t " maxlen ,
.BI " const wchar_t *restrict " format ", ...);"
-.PP
+.P
.BI "int vwprintf(const wchar_t *restrict " format ", va_list " args );
.BI "int vfwprintf(FILE *restrict " stream ,
.BI " const wchar_t *restrict " format ", va_list " args );
.BI "int vswprintf(wchar_t " wcs "[restrict ." maxlen "], size_t " maxlen ,
.BI " const wchar_t *restrict " format ", va_list " args );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
All functions shown above:
.\" .BR wprintf (),
.\" .BR fwprintf (),
family of functions.
It performs formatted output of wide
characters.
-.PP
+.P
The
.BR wprintf ()
and
must not be byte oriented; see
.BR fwide (3)
for more information.
-.PP
+.P
The
.BR fwprintf ()
and
must not be byte oriented; see
.BR fwide (3)
for more information.
-.PP
+.P
The
.BR swprintf ()
and
wide
characters at
.IR wcs .
-.PP
+.P
These functions are like
the
.BR printf (3),
.I maxlen
argument, but these functions do not return \-1 upon
buffer overflow on Linux.)
-.PP
+.P
The treatment of the conversion characters
.B c
and
.B LC_CTYPE
category of the
current locale.
-.PP
+.P
If the
.I format
string contains non-ASCII wide characters, the program
.SH SYNOPSIS
.nf
.B "#include <rpc/des_crypt.h>"
-.PP
+.P
.BI "void passwd2des(char " *passwd ", char *" key ");"
-.PP
+.P
.BI "int xencrypt(char *" secret ", char *" passwd ");"
.BI "int xdecrypt(char *" secret ", char *" passwd ");"
.fi
.BR WARNING :
Do not use these functions in new code.
They do not achieve any type of acceptable cryptographic security guarantees.
-.PP
+.P
The function
.BR passwd2des ()
takes a character string
argument
.I passwd
into a DES key.
-.PP
+.P
The
.BR xencrypt ()
function takes the ASCII character string
as a hex string
.\" (over the alphabet 0123456789abcdef)
of the same length.
-.PP
+.P
The
.BR xdecrypt ()
function performs the converse operation.
arbitrary data structures in a machine-independent fashion.
Data for remote procedure calls are transmitted using these
routines.
-.PP
+.P
The prototypes below are declared in
.I <rpc/xdr.h>
and make use of the following types:
-.PP
+.P
.RS 4
.EX
.BI "typedef int " bool_t ;
-.PP
+.P
.BI "typedef bool_t (*" xdrproc_t ")(XDR *, void *,...);"
.EE
.RE
-.PP
+.P
For the declaration of the
.I XDR
type, see
.IR <rpc/xdr.h> .
-.PP
+.P
.nf
.BI "bool_t xdr_array(XDR *" xdrs ", char **" arrp ", unsigned int *" sizep ,
.BI " unsigned int " maxsize ", unsigned int " elsize ,
the array elements' C form, and their external
representation.
This routine returns one if it succeeds, zero otherwise.
-.PP
+.P
.nf
.BI "bool_t xdr_bool(XDR *" xdrs ", bool_t *" bp );
.fi
When encoding data, this
filter produces values of either one or zero.
This routine returns one if it succeeds, zero otherwise.
-.PP
+.P
.nf
.BI "bool_t xdr_bytes(XDR *" xdrs ", char **" sp ", unsigned int *" sizep ,
.BI " unsigned int " maxsize );
strings cannot be longer than
.IR maxsize .
This routine returns one if it succeeds, zero otherwise.
-.PP
+.P
.nf
.BI "bool_t xdr_char(XDR *" xdrs ", char *" cp );
.fi
.BR xdr_opaque (),
or
.BR xdr_string ().
-.PP
+.P
.nf
.BI "void xdr_destroy(XDR *" xdrs );
.fi
after invoking
.BR xdr_destroy ()
is undefined.
-.PP
+.P
.nf
.BI "bool_t xdr_double(XDR *" xdrs ", double *" dp );
.fi
.I double
precision numbers and their external representations.
This routine returns one if it succeeds, zero otherwise.
-.PP
+.P
.nf
.BI "bool_t xdr_enum(XDR *" xdrs ", enum_t *" ep );
.fi
.IR enum s
(actually integers) and their external representations.
This routine returns one if it succeeds, zero otherwise.
-.PP
+.P
.nf
.BI "bool_t xdr_float(XDR *" xdrs ", float *" fp );
.fi
.IR float s
and their external representations.
This routine returns one if it succeeds, zero otherwise.
-.PP
+.P
.nf
.BI "void xdr_free(xdrproc_t " proc ", char *" objp );
.fi
freed, but what it points to
.I is
freed (recursively).
-.PP
+.P
.nf
.BI "unsigned int xdr_getpos(XDR *" xdrs );
.fi
A desirable feature of XDR
streams is that simple arithmetic works with this number,
although the XDR stream instances need not guarantee this.
-.PP
+.P
.nf
.BI "long *xdr_inline(XDR *" xdrs ", int " len );
.fi
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.
-.PP
+.P
.nf
.BI "bool_t xdr_int(XDR *" xdrs ", int *" ip );
.fi
A filter primitive that translates between C integers
and their external representations.
This routine returns one if it succeeds, zero otherwise.
-.PP
+.P
.nf
.BI "bool_t xdr_long(XDR *" xdrs ", long *" lp );
.fi
.I long
integers and their external representations.
This routine returns one if it succeeds, zero otherwise.
-.PP
+.P
.nf
.BI "void xdrmem_create(XDR *" xdrs ", char *" addr ", unsigned int " size ,
.BI " enum xdr_op " op );
.BR XDR_DECODE ,
or
.BR XDR_FREE ).
-.PP
+.P
.nf
.BI "bool_t xdr_opaque(XDR *" xdrs ", char *" cp ", unsigned int " cnt );
.fi
.I cnt
is its size in bytes.
This routine returns one if it succeeds, zero otherwise.
-.PP
+.P
.nf
.BI "bool_t xdr_pointer(XDR *" xdrs ", char **" objpp ,
.BI " unsigned int " objsize ", xdrproc_t " xdrobj );
can represent
recursive data structures, such as binary trees or
linked lists.
-.PP
+.P
.nf
.BI "void xdrrec_create(XDR *" xdrs ", unsigned int " sendsize ,
.BI " unsigned int " recvsize ", char *" handle ,
Also, XDR streams created with different
.B xdr*_create
APIs are not compatible for the same reason.
-.PP
+.P
.nf
.BI "bool_t xdrrec_endofrecord(XDR *" xdrs ", int " sendnow );
.fi
.I sendnow
is nonzero.
This routine returns one if it succeeds, zero otherwise.
-.PP
+.P
.nf
.BI "bool_t xdrrec_eof(XDR *" xdrs );
.fi
After consuming the rest of the current record in the stream,
this routine returns one if the stream has no more input,
zero otherwise.
-.PP
+.P
.nf
.BI "bool_t xdrrec_skiprecord(XDR *" xdrs );
.fi
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.
-.PP
+.P
.nf
.BI "bool_t xdr_reference(XDR *" xdrs ", char **" pp ", unsigned int " size ,
.BI " xdrproc_t " proc );
Use
.BR xdr_pointer ()
instead.
-.PP
+.P
.nf
.BI "xdr_setpos(XDR *" xdrs ", unsigned int " pos );
.fi
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.
-.PP
+.P
.nf
.BI "bool_t xdr_short(XDR *" xdrs ", short *" sp );
.fi
.I short
integers and their external representations.
This routine returns one if it succeeds, zero otherwise.
-.PP
+.P
.nf
.BI "void xdrstdio_create(XDR *" xdrs ", FILE *" file ", enum xdr_op " op );
.fi
.I file
stream, but never
.BR fclose (3).
-.PP
+.P
.nf
.BI "bool_t xdr_string(XDR *" xdrs ", char **" sp ", unsigned int " maxsize );
.fi
.I sp
is the address of the string's pointer.
This routine returns one if it succeeds, zero otherwise.
-.PP
+.P
.nf
.BI "bool_t xdr_u_char(XDR *" xdrs ", unsigned char *" ucp );
.fi
.I unsigned
C characters and their external representations.
This routine returns one if it succeeds, zero otherwise.
-.PP
+.P
.nf
.BI "bool_t xdr_u_int(XDR *" xdrs ", unsigned int *" up );
.fi
.I unsigned
integers and their external representations.
This routine returns one if it succeeds, zero otherwise.
-.PP
+.P
.nf
.BI "bool_t xdr_u_long(XDR *" xdrs ", unsigned long *" ulp );
.fi
.I "unsigned long"
integers and their external representations.
This routine returns one if it succeeds, zero otherwise.
-.PP
+.P
.nf
.BI "bool_t xdr_u_short(XDR *" xdrs ", unsigned short *" usp );
.fi
.I "unsigned short"
integers and their external representations.
This routine returns one if it succeeds, zero otherwise.
-.PP
+.P
.nf
.BI "bool_t xdr_union(XDR *" xdrs ", enum_t *" dscmp ", char *" unp ,
.BI " const struct xdr_discrim *" choices ,
.I defaultarm
procedure is called (if it is not NULL).
Returns one if it succeeds, zero otherwise.
-.PP
+.P
.nf
.BI "bool_t xdr_vector(XDR *" xdrs ", char *" arrp ", unsigned int " size ,
.BI " unsigned int " elsize ", xdrproc_t " elproc );
the array elements' C form, and their external
representation.
This routine returns one if it succeeds, zero otherwise.
-.PP
+.P
.nf
.B bool_t xdr_void(void);
.fi
This routine always returns one.
It may be passed to RPC routines that require a function argument,
where nothing is to be done.
-.PP
+.P
.nf
.BI "bool_t xdr_wrapstring(XDR *" xdrs ", char **" sp );
.fi
.TE
.SH SEE ALSO
.BR rpc (3)
-.PP
+.P
The following manuals:
.RS
eXternal Data Representation Standard: Protocol Specification
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BI "double y0(double " x );
.BI "double y1(double " x );
.BI "double yn(int " n ", double " x );
-.PP
+.P
.BI "float y0f(float " x );
.BI "float y1f(float " x );
.BI "float ynf(int " n ", float " x );
-.PP
+.P
.BI "long double y0l(long double " x );
.BI "long double y1l(long double " x );
.BI "long double ynl(int " n ", long double " x );
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR y0 (),
.BR y1 (),
.BR yn ():
|| /* Since glibc 2.19: */ _DEFAULT_SOURCE
|| /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE
.fi
-.PP
+.P
.BR y0f (),
.BR y0l (),
.BR y1f (),
.I x
of the second kind of order
.IR n .
-.PP
+.P
The value of
.I x
must be positive.
-.PP
+.P
The
.BR y0f (),
.BR y1f (),
On success, these functions return the appropriate
Bessel value of the second kind for
.IR x .
-.PP
+.P
If
.I x
is a NaN, a NaN is returned.
-.PP
+.P
If
.I x
is negative,
.RB \- HUGE_VALL ,
respectively.
(POSIX.1-2001 also allows a NaN return for this case.)
-.PP
+.P
If
.I x
is 0.0,
or
.RB \- HUGE_VALL ,
respectively.
-.PP
+.P
If the result underflows,
a range error occurs,
and the functions return 0.0
-.PP
+.P
If the result overflows,
a range error occurs,
and the functions return
.BR math_error (7)
for information on how to determine whether an error has occurred
when calling these functions.
-.PP
+.P
The following errors can occur:
.TP
Domain error: \fIx\fP is negative
and no
.B FE_DIVBYZERO
exception was raised.
-.PP
+.P
Before glibc 2.17,
.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6808
did not set
.I errno
for "range error: result underflow".
-.PP
+.P
In glibc 2.3.2 and earlier,
.\" Actually, 2.3.2 is the earliest test result I have; so yet
.\" to confirm if this error occurs only in glibc 2.3.2.
.SH SYNOPSIS
.nf
.B #include <stdio.h>
-.PP
+.P
.BR "#define EOF " "/* ... */"
.fi
.SH DESCRIPTION
represents the end of an input file, or an error indication.
It is a negative value, of type
.IR int .
-.PP
+.P
.B EOF
is not a character
(it can't be represented by
.SH SYNOPSIS
.nf
.B #include <stdlib.h>
-.PP
+.P
.BR "#define EXIT_SUCCESS " 0
.BR "#define EXIT_FAILURE " "/* nonzero */"
.fi
.SH SYNOPSIS
.nf
.B #include <stddef.h>
-.PP
+.P
.B "#define NULL ((void *) 0)"
.fi
.SH DESCRIPTION
.SH CAVEATS
It is undefined behavior to dereference a null pointer,
and that usually causes a segmentation fault in practice.
-.PP
+.P
It is also undefined behavior to perform pointer arithmetic on it.
-.PP
+.P
.I NULL \- NULL
is undefined behavior, according to ISO C, but is defined to be 0 in C++.
-.PP
+.P
To avoid confusing human readers of the code,
do not compare pointer variables to
.BR 0 ,
to them.
Instead, always use
.BR NULL .
-.PP
+.P
.B NULL
shouldn't be confused with
.BR NUL ,
.SH SYNOPSIS
.nf
.B #include <printf.h>
-.PP
+.P
.BI "int register_printf_specifier(int " spec ", printf_function " func ,
.BI " printf_arginfo_size_function " arginfo );
.BI "int register_printf_modifier(const wchar_t *" str );
and optionally ORed with an appropriate length modifier
.RB ( PA_FLAG_ *).
.RS
-.PP
+.P
The type is determined by using one of the following constants:
.TP
.B PA_INT
the size of the type (in bytes) should also be specified through this array.
Otherwise, leave it unused.
.RE
-.PP
+.P
.I arginfo
is called before
.IR func ,
.I printf_function
should return the number of characters written,
or \-1 on error.
-.PP
+.P
The callback of type
.I \%printf_arginfo_size_function
should return the number of arguments to be parsed by this specifier.
.BR \%register_printf_specifier (),
and is now deprecated.
That function can't handle user-defined types.
-.PP
+.P
.BR \%register_printf_specifier ()
superseeds
.BR \%register_printf_function (3).
to print integers in binary format,
mirroring rules for other unsigned conversion specifiers like 'x' and 'u'.
This can be used to print in binary prior to C23.
-.PP
+.P
.\" SRC BEGIN (register_printf_specifier.c)
.EX
/* This code is in the public domain */
#define EX_OK 0 /* T{
successful termination */
T}
-.PP
+.P
#define EX__BASE 64 /* T{
base value for error messages */
T}
-.PP
+.P
#define EX_USAGE 64 /* T{
command line usage error */
T}
#define EX_CONFIG 78 /* T{
configuration error */
T}
-.PP
+.P
.T&
lB2 l2 l1 lX.
#define EX__MAX ... /* T{
.TE
.SH DESCRIPTION
A few programs exit with the following error codes.
-.PP
+.P
The successful exit is always indicated by a status of
.BR 0 ,
or
.TP
.B EX_CONFIG
Something was found in an unconfigured or misconfigured state.
-.PP
+.P
The numerical values corresponding to the symbolical ones
are given in parenthesis for easy reference.
.SH STANDARDS
.SH SYNOPSIS
.nf
.B #include <stdio.h>
-.PP
+.P
.BR typedef " /* ... */ " FILE;
.fi
.SH DESCRIPTION
.SH SYNOPSIS
.EX
.B #include <aio.h>
-.PP
+.P
.B struct aiocb {
.BR " int aio_fildes;" " /* File descriptor */"
.BR " off_t aio_offset;" " /* File offset */"
.SH SYNOPSIS
.nf
.B #include <sys/types.h>
-.PP
+.P
.BR typedef " /* ... */ " blkcnt_t;
.fi
.SH DESCRIPTION
.SH SYNOPSIS
.nf
.B #include <sys/types.h>
-.PP
+.P
.BR typedef " /* ... */ " blksize_t;
.fi
.SH DESCRIPTION
.SH SYNOPSIS
.nf
.B #include <termios.h>
-.PP
+.P
.BR typedef " /* ... */ " cc_t;
.BR typedef " /* ... */ " speed_t;
.BR typedef " /* ... */ " tcflag_t;
for baud rates, and
.I tcflag_t
for modes.
-.PP
+.P
All are unsigned integer types.
.SH STANDARDS
POSIX.1-2008.
.SH SYNOPSIS
.nf
.B #include <time.h>
-.PP
+.P
.BR typedef " /* ... */ " clock_t;
.fi
.SH DESCRIPTION
.SH SYNOPSIS
.nf
.B #include <sys/types.h>
-.PP
+.P
.BR typedef " /* ... */ " clockid_t;
.fi
.SH DESCRIPTION
.SH SYNOPSIS
.nf
.B #include <sys/types.h>
-.PP
+.P
.BR typedef " /* ... */ " dev_t;
.fi
.SH DESCRIPTION
.SH SYNOPSIS
.EX
.B #include <stdlib.h>
-.PP
+.P
.B typedef struct {
.BR " int quot;" " /* Quotient */"
.BR " int rem;" " /* Remainder */"
.B } div_t;
-.PP
+.P
.B typedef struct {
.BR " long quot;" " /* Quotient */"
.BR " long rem;" " /* Remainder */"
.B } ldiv_t;
-.PP
+.P
.B typedef struct {
.BR " long long quot;" " /* Quotient */"
.BR " long long rem;" " /* Remainder */"
.B } lldiv_t;
-.PP
+.P
.B #include <inttypes.h>
-.PP
+.P
.B typedef struct {
.BR " intmax_t quot;" " /* Quotient */"
.BR " intmax_t rem;" " /* Remainder */"
is the type of the value returned by the
.RB [[ l ] l ] div (3)
function.
-.PP
+.P
.I imaxdiv_t
is the type of the value returned by the
.BR imaxdiv (3)
.SH SYNOPSIS
.nf
.B #include <math.h>
-.PP
+.P
.BR typedef " /* ... */ " float_t;
.BR typedef " /* ... */ " double_t;
.fi
.B FLT_EVAL_METHOD
(defined in
.IR <float.h> ):
-.PP
+.P
.TS
lB rI rI.
FLT_EVAL_METHOD float_t double_t
1 double double
2 long double long double
.TE
-.PP
+.P
For other values of
.BR FLT_EVAL_METHOD ,
the types of
.SH SYNOPSIS
.EX
.B #include <sys/epoll.h>
-.PP
+.P
.B struct epoll_event {
.BR " uint32_t events;" " /* Epoll events */"
.BR " epoll_data_t data;" " /* User data variable */"
.B };
-.PP
+.P
.B union epoll_data {
.B " void *ptr;"
.B " int fd;"
.B " uint32_t u32;"
.B " uint64_t u64;"
.B };
-.PP
+.P
.B "typedef union epoll_data epoll_data_t;"
.EE
.SH DESCRIPTION
.SS C library/kernel differences
The Linux kernel headers also provide this type,
with a slightly different definition:
-.PP
+.P
.in +4n
.EX
#include <linux/eventpoll.h>
.SH SYNOPSIS
.nf
.B #include <fenv.h>
-.PP
+.P
.BR typedef " /* ... */ " fenv_t;
.BR typedef " /* ... */ " fexcept_t;
.fi
.I fenv_t
represents the entire floating-point environment,
including control modes and status flags.
-.PP
+.P
.I fexcept_t
represents the floating-point status flags collectively.
-.PP
+.P
For further details see
.BR fenv (3).
.SH STANDARDS
.SH SYNOPSIS
.nf
.B #include <sys/types.h>
-.PP
+.P
.BR typedef " /* ... */ " pid_t;
.BR typedef " /* ... */ " uid_t;
.BR typedef " /* ... */ " gid_t;
.I pid_t
is a type used for storing process IDs, process group IDs, and session IDs.
It is a signed integer type.
-.PP
+.P
.I uid_t
is a type used to hold user IDs.
It is an integer type.
-.PP
+.P
.I gid_t
is a type used to hold group IDs.
It is an integer type.
-.PP
+.P
.I id_t
is a type used to hold a general identifier.
It is an integer type that can be used to contain a
.IR <unistd.h> ,
and
.IR <utmpx.h> .
-.PP
+.P
The following headers also provide
.IR uid_t :
.IR <pwd.h> ,
.IR <sys/stat.h> ,
and
.IR <unistd.h> .
-.PP
+.P
The following headers also provide
.IR gid_t :
.IR <grp.h> ,
.IR <sys/stat.h> ,
and
.IR <unistd.h> .
-.PP
+.P
The following header also provides
.IR id_t :
.IR <sys/resource.h> .
.SH SYNOPSIS
.nf
.B #include <stdint.h>
-.PP
+.P
.BR typedef " /* ... */ " int8_t;
.BR typedef " /* ... */ " int16_t;
.BR typedef " /* ... */ " int32_t;
.BR typedef " /* ... */ " int64_t;
-.PP
+.P
.BR typedef " /* ... */ " uint8_t;
.BR typedef " /* ... */ " uint16_t;
.BR typedef " /* ... */ " uint32_t;
.BR typedef " /* ... */ " uint64_t;
-.PP
+.P
.B "#define INT8_WIDTH 8"
.B "#define INT16_WIDTH 16"
.B "#define INT32_WIDTH 32"
.B "#define INT64_WIDTH 64"
-.PP
+.P
.B "#define UINT8_WIDTH 8"
.B "#define UINT16_WIDTH 16"
.B "#define UINT32_WIDTH 32"
.B "#define UINT64_WIDTH 64"
-.PP
+.P
.BR "#define INT8_MAX " "/* 2**(INT8_WIDTH - 1) - 1 */"
.BR "#define INT16_MAX " "/* 2**(INT16_WIDTH - 1) - 1 */"
.BR "#define INT32_MAX " "/* 2**(INT32_WIDTH - 1) - 1 */"
.BR "#define INT64_MAX " "/* 2**(INT64_WIDTH - 1) - 1 */"
-.PP
+.P
.BR "#define INT8_MIN " "/* - 2**(INT8_WIDTH - 1) */"
.BR "#define INT16_MIN " "/* - 2**(INT16_WIDTH - 1) */"
.BR "#define INT32_MIN " "/* - 2**(INT32_WIDTH - 1) */"
.BR "#define INT64_MIN " "/* - 2**(INT64_WIDTH - 1) */"
-.PP
+.P
.BR "#define UINT8_MAX " "/* 2**INT8_WIDTH - 1 */"
.BR "#define UINT16_MAX " "/* 2**INT16_WIDTH - 1 */"
.BR "#define UINT32_MAX " "/* 2**INT32_WIDTH - 1 */"
.BR "#define UINT64_MAX " "/* 2**INT64_WIDTH - 1 */"
-.PP
+.P
.BI "#define INT8_C(" c ") " c " ## " "\fR/* ... */\fP"
.BI "#define INT16_C(" c ") " c " ## " "\fR/* ... */\fP"
.BI "#define INT32_C(" c ") " c " ## " "\fR/* ... */\fP"
.BI "#define INT64_C(" c ") " c " ## " "\fR/* ... */\fP"
-.PP
+.P
.BI "#define UINT8_C(" c ") " c " ## " "\fR/* ... */\fP"
.BI "#define UINT16_C(" c ") " c " ## " "\fR/* ... */\fP"
.BI "#define UINT32_C(" c ") " c " ## " "\fR/* ... */\fP"
substituting
.I N
by the appropriate number.
-.PP
+.P
.IR uint N _t
are
unsigned integer types
substituting
.I N
by the appropriate number.
-.PP
+.P
According to POSIX,
.RI [ u ] int8_t ,
.RI [ u ] int16_t ,
.RI [ u ] int64_t
are only required in implementations that provide integer types with width 64;
and all other types of this form are optional.
-.PP
+.P
The macros
.RB [ U ] INT \fIN\fP _WIDTH
expand to the width in bits of these types
.RI ( N ).
-.PP
+.P
The macros
.RB [ U ] INT \fIN\fP _MAX
expand to the maximum value that these types can hold.
-.PP
+.P
The macros
.BI INT N _MIN
expand to the minimum value that these types can hold.
-.PP
+.P
The macros
.RB [ U ] INT \fIN\fP _C ()
expand their argument to an integer constant of type
.RI [ u ] int N _t .
-.PP
+.P
The length modifiers for the
.RI [ u ] int N _t
types for the
C11, POSIX.1-2008.
.SH HISTORY
C99, POSIX.1-2001.
-.PP
+.P
The
.RB [ U ] INT \fIN\fP _WIDTH
macros were added in C23.
.SH SYNOPSIS
.nf
.B #include <stdint.h>
-.PP
+.P
.BR typedef " /* ... */ " intmax_t;
.BR typedef " /* ... */ " uintmax_t;
-.PP
+.P
.BR "#define INTMAX_WIDTH " "/* ... */"
.B "#define UINTMAX_WIDTH INTMAX_WIDTH"
-.PP
+.P
.BR "#define INTMAX_MAX " "/* 2**(INTMAX_WIDTH - 1) - 1 */"
.BR "#define INTMAX_MIN " "/* - 2**(INTMAX_WIDTH - 1) */"
.BR "#define UINTMAX_MAX " "/* 2**UINTMAX_WIDTH - 1 */"
-.PP
+.P
.BI "#define INTMAX_C(" c ) " c " ## " \fR/* ... */\fP"
.BI "#define UINTMAX_C(" c ) " c " ## " \fR/* ... */\fP"
.fi
It is capable of storing values in the range
.RB [ INTMAX_MIN ,
.BR INTMAX_MAX ].
-.PP
+.P
.I uintmax_t
is an unsigned integer type
capable of representing any value of any basic unsigned integer type
It is capable of storing values in the range
.RB [ 0 ,
.BR UINTMAX_MAX ].
-.PP
+.P
The macros
.RB [ U ] INTMAX_WIDTH
expand to the width in bits of these types.
-.PP
+.P
The macros
.RB [ U ] INTMAX_MAX
expand to the maximum value that these types can hold.
-.PP
+.P
The macro
.B INTMAX_MIN
expands to the minimum value that
.I intmax_t
can hold.
-.PP
+.P
The macros
.RB [ U ] INTMAX_C ()
expand their argument to an integer constant of type
.RI [ u ] intmax_t .
-.PP
+.P
The length modifier for
.RI [ u ] intmax_t
for the
.SH SYNOPSIS
.nf
.B #include <stdint.h>
-.PP
+.P
.BR typedef " /* ... */ " intptr_t;
.BR typedef " /* ... */ " uintptr_t;
-.PP
+.P
.BR "#define INTPTR_WIDTH" " /* ... */"
.B #define UINTPTR_WIDTH INTPTR_WIDTH
-.PP
+.P
.BR "#define INTPTR_MAX" " /* 2**(INTPTR_WIDTH \- 1) \- 1 */"
.BR "#define INTPTR_MIN" " /* \- 2**(INTPTR_WIDTH \- 1) */"
.BR "#define UINTPTR_MAX" " /* 2**UINTPTR_WIDTH \- 1 */"
It is capable of storing values in the range
.RB [ INTPTR_MIN ,
.BR INTPTR_MAX ].
-.PP
+.P
.I uintptr_t
is an unsigned integer type
such that any valid
It is capable of storing values in the range
.RB [ 0 ,
.BR INTPTR_MAX ].
-.PP
+.P
The macros
.RB [ U ] INTPTR_WIDTH
expand to the width in bits of these types.
-.PP
+.P
The macros
.RB [ U ] INTPTR_MAX
expand to the maximum value that these types can hold.
-.PP
+.P
The macro
.B INTPTR_MIN
expands to the minimum value that
.I intptr_t
can hold.
-.PP
+.P
The length modifiers for the
.RI [ u ] intptr_t
types
.SH SYNOPSIS
.EX
.B #include <sys/uio.h>
-.PP
+.P
.B struct iovec {
.BR " void *iov_base;" " /* Starting address */"
.BR " size_t iov_len;" " /* Size of the memory pointed to by "\c
.SH SYNOPSIS
.EX
.B #include <time.h>
-.PP
+.P
.B struct itimerspec {
.BR " struct timespec it_interval;" " /* Interval for periodic timer */"
.BR " struct timespec it_value;" " /* Initial expiration */"
.SH SYNOPSIS
.EX
.B #include <locale.h>
-.PP
+.P
.BR "struct lconv {" " /* Values in the \[dq]C\[dq] locale: */"
.BR " char *decimal_point;" " /* \[dq].\[dq] */"
.BR " char *thousands_sep;" " /* \[dq]\[dq] */"
.SH SYNOPSIS
.nf
.B #include <sys/types.h>
-.PP
+.P
.BR typedef " /* ... */ " mode_t;
.fi
.SH DESCRIPTION
.SH SYNOPSIS
.nf
.B #include <sys/types.h>
-.PP
+.P
.BR typedef " /* ... */ " off_t;
-.PP
+.P
.B #define _LARGEFILE64_SOURCE
.B #include <sys/types.h>
-.PP
+.P
.BR typedef " /* ... */ " off64_t;
-.PP
+.P
.B #define _GNU_SOURCE
.B #include <sys/types.h>
-.PP
+.P
.BR typedef " /* ... */ " loff_t;
.fi
.SH DESCRIPTION
.I off_t
is used for describing file sizes.
It is a signed integer type.
-.PP
+.P
.I off64_t
is a 64-bit version of the type,
used in glibc.
-.PP
+.P
.I loff_t
is a 64-bit version of the type,
introduced by the Linux kernel.
.TP
.I off_t
POSIX.1-2001.
-.PP
+.P
.I <aio.h>
and
.I <stdio.h>
.I off_t
can be controlled with the feature test macro
.BR _FILE_OFFSET_BITS .
-.PP
+.P
The following headers also provide
.IR off_t :
.IR <aio.h> ,
.SH SYNOPSIS
.nf
.B #include <stddef.h>
-.PP
+.P
.BR typedef " /* ... */ " ptrdiff_t;
.fi
.SH DESCRIPTION
capable of storing values in the range
.RB [ PTRDIFF_MIN ,
.BR PTRDIFF_MAX ].
-.PP
+.P
The length modifier for
.I ptrdiff_t
for the
.SH SYNOPSIS
.EX
.B #include <signal.h>
-.PP
+.P
.B struct sigevent {
.BR " int sigev_notify;" " /* Notification type */"
.BR " int sigev_signo;" " /* Signal number */"
.BR " " " /* ID of thread to signal"
.BR " " " (SIGEV_THREAD_ID) */"
.B };
-.PP
+.P
.BR "union sigval {" " /* Data passed with notification */"
.BR " int sival_int;" " /* Integer value */"
.BR " void *sival_ptr;" " /* Pointer value */"
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).
-.PP
+.P
The definition shown in the SYNOPSIS is approximate:
some of the fields in the
.I sigevent
Programs should employ only those fields relevant
to the value specified in
.IR sigev_notify .
-.PP
+.P
The
.I sigev_notify
field specifies how notification is to be performed.
POSIX.1-2008.
.SH HISTORY
POSIX.1-2001.
-.PP
+.P
.I <aio.h>
and
.I <time.h>
.SH SYNOPSIS
.nf
.B #include <stddef.h>
-.PP
+.P
.BR typedef " /* ... */ " size_t;
-.PP
+.P
.B #include <sys/types.h>
-.PP
+.P
.BR typedef " /* ... */ " ssize_t;
.fi
.SH DESCRIPTION
.TP
.I ssize_t
POSIX.1-2001.
-.PP
+.P
.IR <aio.h> ,
.IR <glob.h> ,
.IR <grp.h> ,
define
.I size_t
since POSIX.1-2008.
-.PP
+.P
.IR <aio.h> ,
.IR <mqueue.h> ,
and
.SH SYNOPSIS
.EX
.B #include <sys/socket.h>
-.PP
+.P
.B struct sockaddr {
.BR " sa_family_t sa_family;" " /* Address family */"
.BR " char sa_data[];" " /* Socket address */"
.B };
-.PP
+.P
.B struct sockaddr_storage {
.BR " sa_family_t ss_family;" " /* Address family */"
.B };
-.PP
+.P
.BR typedef " /* ... */ " socklen_t;
.BR typedef " /* ... */ " sa_family_t;
-.PP
+.P
.EE
.SS Internet domain sockets
.EX
.B #include <netinet/in.h>
-.PP
+.P
.B struct sockaddr_in {
.BR " sa_family_t sin_family;" " /* " AF_INET " */"
.BR " in_port_t sin_port;" " /* Port number */"
.BR " struct in_addr sin_addr;" " /* IPv4 address */"
.B };
-.PP
+.P
.B struct sockaddr_in6 {
.BR " sa_family_t sin6_family;" " /* " AF_INET6 " */"
.BR " in_port_t sin6_port;" " /* Port number */"
.BR " struct in6_addr sin6_addr;" " /* IPv6 address */"
.BR " uint32_t sin6_scope_id;" " /* Set of interfaces for a scope */"
.B };
-.PP
+.P
.B struct in_addr {
.B " in_addr_t s_addr;"
.B };
-.PP
+.P
.B struct in6_addr {
.B " uint8_t s6_addr[16];"
.B };
-.PP
+.P
.B typedef uint32_t in_addr_t;
.B typedef uint16_t in_port_t;
.EE
.SS UNIX domain sockets
.EX
.B #include <sys/un.h>
-.PP
+.P
.B struct sockaddr_un {
.BR " sa_family_t sun_family;" " /* Address family */"
.BR " char sun_path[];" " /* Socket pathname */"
POSIX.1-2008.
.SH HISTORY
POSIX.1-2001.
-.PP
+.P
.I socklen_t
was invented by POSIX.
See also
.BR accept (2).
-.PP
+.P
These structures were invented before modern ISO C strict-aliasing rules.
If aliasing rules are applied strictly,
these structures would be extremely difficult to use
.I socklen_t
is also defined in
.IR <netdb.h> .
-.PP
+.P
.I sa_family_t
is also defined in
.I <netinet/in.h>
.SH SYNOPSIS
.EX
.B #include <sys/stat.h>
-.PP
+.P
.B struct stat {
.BR " dev_t st_dev;" " /* ID of device containing file */"
.BR " ino_t st_ino;" " /* Inode number */"
.B "#define st_ctime st_ctim.tv_sec"
.B };
.EE
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.IR st_atim ,
.IR st_mtim ,
.IR st_ctim :
.fi
.SH DESCRIPTION
Describes information about a file.
-.PP
+.P
The fields are as follows:
.TP
.I st_dev
.I st_ctime
This is the file's last status change timestamp
(time of last change to the inode).
-.PP
+.P
For further information on the above fields, see
.BR inode (7).
.SH STANDARDS
POSIX.1-2008.
.SH HISTORY
POSIX.1-2001.
-.PP
+.P
Old kernels and old standards did not support nanosecond timestamp fields.
Instead, there were three timestamp
.RI fields\[em] st_atime ,
as
.I time_t
that recorded timestamps with one-second precision.
-.PP
+.P
Since Linux 2.5.48, the
.I stat
structure supports nanosecond resolution for the three file timestamp fields.
.SH SYNOPSIS
.nf
.B #include <time.h>
-.PP
+.P
.BR typedef " /* ... */ " time_t;
-.PP
+.P
.B #include <sys/types.h>
-.PP
+.P
.BR typedef " /* ... */ " suseconds_t;
.BR typedef " /* ... */ " useconds_t;
.fi
.TQ
.I useconds_t
POSIX.1-2001.
-.PP
+.P
.I <sched.h>
defines
.I time_t
since POSIX.1-2008.
-.PP
+.P
POSIX.1-2001 defined
.I useconds_t
in
.I time_t
can be controlled with the feature test macro
.BR _TIME_BITS .
-.PP
+.P
The following headers also provide
.IR time_t :
.IR <sched.h> ,
.IR <sys/types.h> ,
and
.IR <utime.h> .
-.PP
+.P
The following headers also provide
.IR suseconds_t :
.I <sys/select.h>
.SH SYNOPSIS
.nf
.B #include <sys/types.h>
-.PP
+.P
.BR typedef " /* ... */ " timer_t;
.fi
.SH DESCRIPTION
.SH SYNOPSIS
.EX
.B #include <time.h>
-.PP
+.P
.B struct timespec {
.BR " time_t tv_sec;" " /* Seconds */"
.RB " /* ... */" " tv_nsec;" \
.EE
.SH DESCRIPTION
Describes times in seconds and nanoseconds.
-.PP
+.P
.I tv_nsec
is of an implementation-defined signed type
capable of holding the specified range.
.SH SYNOPSIS
.EX
.B #include <sys/time.h>
-.PP
+.P
.B struct timeval {
.BR " time_t tv_sec;" " /* Seconds */"
.BR " suseconds_t tv_usec;" " /* Microseconds */"
.SH SYNOPSIS
.EX
.B #include <time.h>
-.PP
+.P
.B struct tm {
.BR " int tm_sec;" " /* Seconds [" 0 ", " 60 "] */"
.BR " int tm_min;" " /* Minutes [" 0 ", " 59 "] */"
.BR " int tm_yday;" \
" /* Day of the year [" 0 ", " 365 "] (Jan/01 = " 0 ") */"
.BR " int tm_isdst;" " /* Daylight savings flag */"
-.PP
+.P
.BR " long tm_gmtoff;" " /* Seconds East of UTC */"
.BR " const char *tm_zone;" " /* Timezone abbreviation */"
.B };
.EE
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.IR tm_gmtoff ,
.IR tm_zone :
.nf
.fi
.SH DESCRIPTION
Describes time, broken down into distinct components.
-.PP
+.P
.I tm_isdst
describes 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.
-.PP
+.P
.I tm_gmtoff
is the difference, in seconds,
of the timezone represented by this broken-down time and UTC
(this is the additive inverse of
.BR timezone (3)).
-.PP
+.P
.I tm_zone
is the equivalent of
.BR tzname (3)
so it was limited to
.B 60
in C99.
-.PP
+.P
.BR timezone (3),
as a variable, is an XSI extension: some systems provide the V7-compatible
.\" FreeBSD
The
.I tm_gmtoff
field provides an alternative (with the opposite sign) for those systems.
-.PP
+.P
.I tm_zone
points to static storage and may be overridden on subsequent calls to
.BR localtime (3)
C11, POSIX.1-2008.
.SH HISTORY
C89, POSIX.1-2001.
-.PP
+.P
.I tm_gmtoff
and
.I tm_zone
.SH SYNOPSIS
.nf
.B #include <stdarg.h>
-.PP
+.P
.BR typedef " /* ... */ " va_list;
.fi
.SH DESCRIPTION
may be converted to a pointer to
.I void
and back.
-.PP
+.P
Conversions from and to any other pointer type are done implicitly,
not requiring casts at all.
Note that this feature prevents any kind of type checking:
.I void *
value to a type incompatible to that of the underlying data,
because that would result in undefined behavior.
-.PP
+.P
This type is useful in function parameters and return value
to allow passing values of any type.
The function will typically use some mechanism to know
the real type of the data being passed via a pointer to
.IR void .
-.PP
+.P
A value of this type can't be dereferenced,
as it would give a value of type
.IR void ,
as it is superseded by the
.BR hpsa (4)
driver in newer kernels.
-.PP
+.P
.B cciss
is a block driver for older HP Smart Array RAID controllers.
.SS Options
driver is capable of controlling, which is to say, the
.B cciss
driver is restricted by this option to the following controllers:
-.PP
+.P
.nf
Smart Array 5300
Smart Array 5i
The
.B cciss
driver supports the following Smart Array boards:
-.PP
+.P
.nf
Smart Array 5300
Smart Array 5i
.SH FILES
.SS Device nodes
The device naming scheme is as follows:
-.PP
+.P
Major numbers:
.IP
.TS
110 cciss6
111 cciss7
.TE
-.PP
+.P
Minor numbers:
-.PP
+.P
.EX
b7 b6 b5 b4 b3 b2 b1 b0
|\-\-\-\-+\-\-\-\-| |\-\-\-\-+\-\-\-\-|
|
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- Logical Volume number
.EE
-.PP
+.P
The device naming scheme is:
.TS
li l.
contain information about
the configuration of each controller.
For example:
-.PP
+.P
.in +4n
.EX
$ \fBcd /proc/driver/cciss\fP
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.
-.PP
+.P
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
.IR /etc/init.d ,
but could vary depending on distribution).
For example:
-.PP
+.P
.in +4n
.EX
for x in /proc/driver/cciss/cciss[0\-9]*
done
.EE
.in
-.PP
+.P
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.)
-.PP
+.P
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.
For example:
.IP
echo "rescan" > /proc/scsi/cciss0/1
-.PP
+.P
This causes the driver to:
.RS
.IP (1) 5
make note of any new or removed sequential access devices
or medium changers.
.RE
-.PP
+.P
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.
-.PP
+.P
Note that the naming convention of the
.I /proc
filesystem entries
contains a number in addition to the driver name
(e.g., "cciss0"
instead of just "cciss", which you might expect).
-.PP
+.P
Note:
.I Only
sequential access devices and medium changers are presented
If that doesn't work, the SCSI bus is reset.
.IP (4)
If that doesn't work, the host bus adapter is reset.
-.PP
+.P
The
.B cciss
driver is a block
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.
-.PP
+.P
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
.BR cciss_vol_status (8),
.BR hpacucli (8),
.BR hpacuxe (8)
-.PP
+.P
.UR http://cciss.sf.net
.UE ,
and
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.
-.PP
+.P
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.
-.PP
+.P
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 \fBCharacter Sets\fP section below for discussion.
-.PP
+.P
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.
-.PP
+.P
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 \fBLinux Console Controls\fP section below for discussion.
-.PP
+.P
It is generally not good practice to hard-wire terminal controls into
programs.
Linux supports a
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.
-.PP
+.P
.B "Control characters"
-.PP
+.P
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),
On the other hand, in UTF-8 mode all codes 00\[en]1f are regarded
as control characters, regardless of any "display control characters"
mode.
-.PP
+.P
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.
.TP
CSI (0x9B)
is equivalent to ESC [.
-.PP
+.P
.B "ESC- but not CSI-sequences"
.ad l
.TS
T}
.TE
.ad
-.PP
+.P
.B "ECMA-48 CSI sequences"
-.PP
+.P
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.
-.PP
+.P
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.)
-.PP
+.P
The action of a CSI sequence is determined by its final character.
.ad l
.TS
T}
.TE
.ad
-.PP
+.P
.B ECMA-48 Select Graphic Rendition
-.PP
+.P
The ECMA-48 SGR sequence ESC [ \fIparameters\fP m sets display
attributes.
Several attributes can be set in the same sequence, separated by
T}
.TE
.ad
-.PP
+.P
Commands 38 and 48 require further arguments:
.TS
l lx.
24-bit color, r/g/b components are in the range 0..255
T}
.TE
-.PP
+.P
.B ECMA-48 Mode Switches
.TP
ESC [ 3 h
ESC [ 20 h
LF/NL (default off): Automatically follow echo of LF, VT, or FF with CR.
.\"
-.PP
+.P
.B ECMA-48 Status Report Commands
.\"
.TP
Cursor position report (CPR): Answer is ESC [ \fIy\fP ; \fIx\fP R,
where \fIx,y\fP is the cursor location.
.\"
-.PP
+.P
.B DEC Private Mode (DECSET/DECRST) sequences
-.PP
+.P
.\"
These are not described in ECMA-48.
We list the Set Mode sequences;
X11 Mouse Reporting (default off): Set reporting mode to 2 (or reset
to 0)\[em]see below.
.\"
-.PP
+.P
.B Linux Console Private CSI Sequences
-.PP
+.P
.\"
The following sequences are neither ECMA-48 nor native VT102.
They are native to the Linux console driver.
symbols.
The four tables are: a) Latin1 \-> PC,
b) VT100 graphics \-> PC, c) PC \-> PC, d) user-defined.
-.PP
+.P
There are two character sets, called G0 and G1, and one of them
is the current character set.
(Initially G0.)
Typing \fB\[ha]N\fP causes G1 to become current,
\fB\[ha]O\fP causes G0 to become current.
-.PP
+.P
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.
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.
-.PP
+.P
The sequence ESC c causes a terminal reset, which is what you want if the
screen is all garbled.
The oft-advised "echo \[ha]V\[ha]O" will make only G0 current,
that just does "echo \[ha][c".
If your terminfo entry for the console is correct
(and has an entry rs1=\eEc), then "tput reset" will also work.
-.PP
+.P
The user-defined mapping table can be set using
.BR mapscrn (8).
The result of the mapping is that if a symbol c is printed, the symbol
user-mode application such as the
.BR gpm (8)
daemon.
-.PP
+.P
The mouse tracking escape sequences generated by
\fBxterm\fP(1) encode numeric parameters in a single character as
\fIvalue\fP+040.
For example, \[aq]!\[aq] is 1.
The screen coordinate system is 1-based.
-.PP
+.P
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.
and \fIx\fP and \fIy\fP are the x and y coordinates of the mouse
when the button was pressed.
This is the same code the kernel also produces.
-.PP
+.P
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.
Linux console and the two most important others, the DEC VT102 and
.BR xterm (1).
.\"
-.PP
+.P
.B Control-character handling
-.PP
+.P
The VT102 also recognized the following control characters:
.TP
NUL (0x00)
DC3 (0x13, \fB\[ha]S\fP, XOFF)
caused VT100 to ignore (and stop transmitting)
all codes except XOFF and XON.
-.PP
+.P
VT100-like DC1/DC3 processing may be enabled by the terminal driver.
-.PP
+.P
The
.BR xterm (1)
program (in VT100 mode) recognizes the control characters
BEL, BS, HT, LF, VT, FF, CR, SO, SI, ESC.
.\"
-.PP
+.P
.B Escape sequences
-.PP
+.P
VT100 console sequences not implemented on the Linux console:
.TS
l l l.
ESC * ... Designate G2 character set
ESC + ... Designate G3 character set
.TE
-.PP
+.P
The program
.BR xterm (1)
(in VT100 mode) recognizes ESC c, ESC # 8, ESC >, ESC =,
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.
-.PP
+.P
The user can configure \fBxterm\fP(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.
-.PP
+.P
It accepts ESC ] (OSC) for the setting of certain resources.
In addition to the ECMA-48 string terminator (ST),
\fBxterm\fP(1) accepts a BEL to terminate an OSC string.
T}
ESC ] 5 0 ; \fIfn\fP ST Set font to \fIfn\fP.
.TE
-.PP
+.P
It recognizes the following with slightly modified meaning
(saving more state, behaving closer to VT100/VT220):
.TS
ESC 7 DECSC Save cursor
ESC 8 DECRC Restore cursor
.TE
-.PP
+.P
It also recognizes
.TS
l l lx.
ESC } LS2R Invoke the G2 character set as GR.
ESC \[ti] LS1R Invoke the G1 character set as GR.
.TE
-.PP
+.P
It also recognizes ESC % and provides a more complete UTF-8
implementation than Linux console.
.\"
-.PP
+.P
.B CSI Sequences
-.PP
+.P
Old versions of \fBxterm\fP(1), for example, from X11R5,
interpret the blink SGR as a bold SGR.
Later versions which implemented ANSI colors, for example,
.IR xterm ,
however \fBxterm\fP(1) implements several ECMA-48 and DEC control sequences
not recognized by Linux.
-.PP
+.P
The \fBxterm\fP(1)
program recognizes all of the DEC Private Mode sequences listed
above, but none of the Linux private-mode sequences.
available with the X distribution.
That document, though terse, is much longer than this manual page.
For a chronological overview,
-.PP
+.P
.RS
.UR http://invisible\-island.net\:/xterm\:/xterm.log.html
.UE
.RE
-.PP
+.P
details changes to xterm.
-.PP
+.P
The \fIvttest\fP program
-.PP
+.P
.RS
.UR http://invisible\-island.net\:/vttest/
.UE
.RE
-.PP
+.P
demonstrates many of these control sequences.
The \fBxterm\fP(1) source distribution also contains sample
scripts which exercise other features.
.SH BUGS
In Linux 2.0.23, CSI is broken, and NUL is not ignored inside
escape sequences.
-.PP
+.P
Some older kernel versions (after Linux 2.0) interpret 8-bit control
sequences.
These "C1 controls" use codes between 128 and 159 to replace
broken by changes to support UTF-8),
but the implementation is incomplete and should be regarded
as unreliable.
-.PP
+.P
Linux "private mode" sequences do not follow the rules in ECMA-48
for private mode control sequences.
In particular, those ending with ] do not use a standard terminating
To accommodate applications which have been hardcoded to use Linux
control sequences,
set the \fBxterm\fP(1) resource \fBbrokenLinuxOSC\fP to true.
-.PP
+.P
An older version of this document implied that Linux recognizes the
ECMA-48 control sequence for invisible text.
It is ignored.
cpuid \- x86 CPUID access device
.SH DESCRIPTION
CPUID provides an interface for querying information about the x86 CPU.
-.PP
+.P
This device is accessed by
.BR lseek (2)
or
.BR pread (2)
to the appropriate CPUID level and reading in chunks of 16 bytes.
A larger read size means multiple reads of consecutive levels.
-.PP
+.P
The lower 32 bits of the file position is used as the incoming
.IR %eax ,
and the upper 32 bits of the file position as the incoming
.I eax
levels like
.IR eax=4 .
-.PP
+.P
This driver uses
.IR /dev/cpu/CPUNUM/cpuid ,
where
.I CPUNUM
as listed in
.IR /proc/cpuinfo .
-.PP
+.P
This file is protected so that it can be read only by the user
.IR root ,
or members of the group
using inline assembler.
However this device allows convenient
access to all CPUs without changing process affinity.
-.PP
+.P
Most of the information in
.I cpuid
is reported by the kernel in cooked form either in
.IR /sys/devices/system/cpu .
Direct CPUID access through this device should only
be used in exceptional cases.
-.PP
+.P
The
.I cpuid
driver is not auto-loaded.
On modular kernels you might need to use the following command
to load it explicitly before use:
-.PP
+.P
.in +4n
.EX
$ modprobe cpuid
.EE
.in
-.PP
+.P
There is no support for CPUID functions that require additional
input registers.
-.PP
+.P
Very old x86 CPUs don't support CPUID.
.SH SEE ALSO
.BR cpuid (1)
-.PP
+.P
Intel Corporation, Intel 64 and IA-32 Architectures
Software Developer's Manual Volume 2A:
Instruction Set Reference, A-M, 3-180 CPUID reference.
-.PP
+.P
Intel Corporation, Intel Processor Identification and
the CPUID Instruction, Application note 485.
.SH SYNOPSIS
.nf
.B #include <asm/dsp56k.h>
-.PP
+.P
.BI "ssize_t read(int " fd ", void *" data ", size_t " length );
.BI "ssize_t write(int " fd ", void *" data ", size_t " length );
-.PP
+.P
.BI "int ioctl(int " fd ", DSP56K_UPLOAD, struct dsp56k_upload *" program );
.BI "int ioctl(int " fd ", DSP56K_SET_TX_WSIZE, int " wsize );
.BI "int ioctl(int " fd ", DSP56K_SET_RX_WSIZE, int " wsize );
The \fIdsp56k\fP special file is used to control the DSP56001, and
to send and receive data using the bidirectional handshaked host
port.
-.PP
+.P
To send a data stream to the signal processor, use
.BR write (2)
to the
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.
-.PP
+.P
The following
.BR ioctl (2)
calls are used to control the
controller.
In the following device tables, \fIn\fP represents the
drive number.
-.PP
+.P
\fBWarning: if you use formats with more tracks
than supported by your drive, you may cause it mechanical damage.\fP
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 formats, so as to prevent their usage.
-.PP
+.P
Drive-independent device files which automatically detect the media
format and capacity:
.TS
_
\fBfd\fP\fIn\fP 0
.TE
-.PP
+.P
5.25 inch double-density device files:
.TS
lw(1i) l l l l c
_
\fBfd\fP\fIn\fP\fBd360\fP 360 40 9 2 4
.TE
-.PP
+.P
5.25 inch high-density device files:
.TS
lw(1i) l l l l c
\fBfd\fP\fIn\fP\fBh1494\fP 1494 83 18 2 72
\fBfd\fP\fIn\fP\fBh1600\fP 1600 80 20 2 92
.TE
-.PP
+.P
3.5 inch double-density device files:
.TS
lw(1i) l l l l c
\fBfd\fP\fIn\fP\fBu1040\fP 1040 80 13 2 84
\fBfd\fP\fIn\fP\fBu1120\fP 1120 80 14 2 88
.TE
-.PP
+.P
3.5 inch high-density device files:
.TS
lw(1i) l l l l c
\fBfd\fP\fIn\fP\fBu1840\fP 1840 80 23 2 116
\fBfd\fP\fIn\fP\fBu1920\fP 1920 80 24 2 100
.TE
-.PP
+.P
3.5 inch extra-density device files:
.TS
lw(1i) l l l l c
.TP
.B FDRAWCMD
sends a raw command to the floppy controller.
-.PP
+.P
For more precise information, consult also the \fI<linux/fd.h>\fP and
\fI<linux/fdreg.h>\fP include files, as well as the
.BR floppycontrol (1)
performance may drop,
to the point of needing a few seconds to access an entire track.
To prevent this, use interleaved formats.
-.PP
+.P
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).
-.PP
+.P
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.
.I /dev/full
created already, it
can be created with the following commands:
-.PP
+.P
.in +4n
.EX
mknod \-m 666 /dev/full c 1 7
.I /dev/full
has major device number 1
and minor device number 7.
-.PP
+.P
Writes to the
.I /dev/full
device fail with an
.B ENOSPC
error.
This can be used to test how a program handles disk-full errors.
-.PP
+.P
Reads from the
.I /dev/full
device will return \e0 characters.
-.PP
+.P
Seeks on
.I /dev/full
will always succeed.
a user-space library such as
.I libfuse
that abstracts away the low-level interface.
-.PP
+.P
At its core, FUSE is a simple client-server protocol, in which the Linux
kernel is the client and the daemon is the server.
After obtaining a file descriptor for this device, the daemon may
.SS The basic protocol
Every message that is read by the daemon begins with a header described by
the following structure:
-.PP
+.P
.in +4n
.EX
struct fuse_in_header {
};
.EE
.in
-.PP
+.P
The header is followed by a variable-length data portion
(which may be empty) specific to the requested operation
(the requested operation is indicated by
.IR opcode ).
-.PP
+.P
The daemon should then process the request and if applicable send
a reply (almost all operations require a reply; if they do not,
this is documented below), by performing a
.BR write (2)
to the file descriptor.
All replies must start with the following header:
-.PP
+.P
.in +4n
.EX
struct fuse_out_header {
};
.EE
.in
-.PP
+.P
This header is also followed by (potentially empty) variable-sized
data depending on the executed request.
However, if the reply is an error reply (i.e.,
Linux.
.SH NOTES
The following messages are not yet documented in this manual page:
-.PP
+.P
.\" FIXME: Document the following.
.in +4n
.EX
.B hdc
and the slave is
.BR hdd .
-.PP
+.P
General IDE block device names have the form
.BI hd X\c
, or
\&.
Both DOS-type partitioning and BSD-disklabel partitioning are supported.
You can have at most 63 partitions on an IDE disk.
-.PP
+.P
For example,
.I /dev/hda
refers to all of the first IDE drive in the system; and
.I /dev/hdb3
refers to the third DOS "primary" partition on the second one.
-.PP
+.P
They are typically created by:
-.PP
+.P
.in +4n
.EX
mknod \-m 660 /dev/hda b 3 0
The
.B hpsa
driver supports the following Smart Array boards:
-.PP
+.P
.nf
Smart Array P700M
Smart Array P212
Smart Array P711m
StorageWorks P1210m
.fi
-.PP
+.P
.\" commit 135ae6edeb51979d0998daf1357f149a7d6ebb08
Since Linux 4.14, the following Smart Array boards are also supported:
-.PP
+.P
.nf
Smart Array 5300
Smart Array 5312
by which a logical drive or physical device can be addressed.
.IR c : b : t : l
are the controller, bus, target, and lun of the device.
-.PP
+.P
For example:
.IP
.in +4n
.BR cciss_vol_status (8),
.BR hpacucli (8),
.BR hpacuxe (8)
-.PP
+.P
.UR http://cciss.sf.net
.UE ,
and
If the Linux system does not have
.I /dev/initrd
already created, it can be created with the following commands:
-.PP
+.P
.in +4n
.EX
mknod \-m 400 /dev/initrd b 1 250
chown root:disk /dev/initrd
.EE
.in
-.PP
+.P
Also, support for both "RAM disk" and "Initial RAM disk"
(e.g.,
.B CONFIG_BLK_DEV_RAM=y
The kernel then can use
.IR /dev/initrd "'s"
contents for a two-phase system boot-up.
-.PP
+.P
In the first boot-up phase, the kernel starts up
and mounts an initial root filesystem from the contents of
.I /dev/initrd
and
.B LOADLIN
documentation.
-.PP
+.P
It is also possible for the
.I /linuxrc
executable to change the normal root device.
For example, the following shell command line would change
the normal root device to
.IR /dev/hdb1 :
-.PP
+.P
.in +4n
.EX
echo 0x365 >/proc/sys/kernel/real\-root\-dev
.EE
.in
-.PP
+.P
For an NFS example, the following shell command lines would change the
normal root device to the NFS directory
.I /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":
-.PP
+.P
.in +4n
.EX
echo /var/nfsroot >/proc/sys/kernel/nfs\-root\-name
echo 255 >/proc/sys/kernel/real\-root\-dev
.EE
.in
-.PP
+.P
.BR Note :
The use of
.I /proc/sys/kernel/real\-root\-dev
The main motivation for implementing
.B initrd
was to allow for modular kernel configuration at system installation.
-.PP
+.P
A possible system installation scenario is as follows:
.IP (1) 5
The loader program boots from floppy or other media with a minimal kernel
.IP (9)
The system is now bootable and additional installation tasks can be
performed.
-.PP
+.P
The key role of
.I /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.
-.PP
+.P
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
file or a file executed by
.I /linuxrc
would be different.
-.PP
+.P
A third scenario is more convenient recovery disks.
Because information like the location of the root filesystem
partition is not needed at boot time, the system loaded from
.I /dev/initrd
can use a dialog and/or auto-detection followed by a
possible sanity check.
-.PP
+.P
Last but not least, Linux distributions on CD-ROM may use
.B initrd
for easy installation from the CD-ROM.
.BR ram (4),
.BR freeramdisk (8),
.BR rdev (8)
-.PP
+.P
.I Documentation/admin\-guide/initrd.rst
.\" commit 9d85025b0418163fae079c9ba8f8445212de8568
(or
Most of these devices can receive, and some can send.
When receiving or sending data, the driver works in two different modes
depending on the underlying hardware.
-.PP
+.P
Some hardware (typically TV-cards) decodes the IR signal internally
and provides decoded button presses as scancode values.
Drivers for this kind of hardware work in
Furthermore, such hardware can only decode a limited set of IR protocols,
usually only the protocol of the specific remote which is
bundled with, for example, a TV-card.
-.PP
+.P
Other hardware provides a stream of pulse/space durations.
Such drivers work in
.B LIRC_MODE_MODE2
device.
Sometimes, this kind of hardware also supports
sending IR data.
-.PP
+.P
The \fBLIRC_GET_FEATURES\fR ioctl (see below) allows probing for whether
receiving and sending is supported, and in which modes, amongst other
features.
\&
int ioctl(int fd, int cmd, int *val);
.fi
-.PP
+.P
The following
.BR ioctl (2)
operations are provided by the
.TP 4
.BR LIRC_GET_FEATURES " (\fIvoid\fP)"
Returns a bit mask of combined features bits; see FEATURES.
-.PP
+.P
If a device returns an error code for
.BR LIRC_GET_FEATURES ,
it is safe to assume it is not a
.\"
.SH SEE ALSO
\fBir\-ctl\fP(1), \fBlircd\fP(8),\ \fBbpf\fP(2)
-.PP
+.P
.UR https://www.kernel.org/\:doc/\:html/\:latest/\:userspace\-api/\:media/\:rc/\:lirc\-dev.html
.UE
.BR mount (8)
command.
You could do
-.PP
+.P
.in +4n
.EX
$ \fBdd if=/dev/zero of=file.img bs=1MiB count=10\fP
$ \fBsudo mount /dev/loop4 /myloopdev\fP
.EE
.in
-.PP
+.P
See
.BR losetup (8)
for another example.
-.PP
+.P
A transfer function can be specified for each loop device for
encryption and decryption purposes.
-.PP
+.P
The following
.BR ioctl (2)
operations are provided by the loop block device:
in
.IR loop_config.info.lo_flags .
.RE
-.PP
+.P
Since Linux 2.6, there are two new
.BR ioctl (2)
operations:
opens a file to be used as the underlying storage for the device,
and then associates the loop device with the backing store.
The following shell session demonstrates the use of the program:
-.PP
+.P
.in +4n
.EX
$ \fBdd if=/dev/zero of=file.img bs=1MiB count=10\fP
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.
-.PP
+.P
Byte addresses in
.I /dev/mem
are interpreted as physical memory addresses.
References to nonexistent locations cause errors to be returned.
-.PP
+.P
Examining and patching is likely to lead to unexpected results
when read-only or write-only bits are present.
-.PP
+.P
Since Linux 2.6.26, and depending on the architecture, the
.B CONFIG_STRICT_DEVMEM
kernel configuration option limits the areas
which can be accessed through this file.
For example: on x86, RAM access is not allowed but accessing
memory-mapped PCI regions is.
-.PP
+.P
It is typically created by:
-.PP
+.P
.in +4n
.EX
mknod \-m 660 /dev/mem c 1 1
chown root:kmem /dev/mem
.EE
.in
-.PP
+.P
The file
.I /dev/kmem
is the same as
Since Linux 2.6.26, this file is available only if the
.B CONFIG_DEVKMEM
kernel configuration option is enabled.
-.PP
+.P
It is typically created by:
-.PP
+.P
.in +4n
.EX
mknod \-m 640 /dev/kmem c 1 2
chown root:kmem /dev/kmem
.EE
.in
-.PP
+.P
.I /dev/port
is similar to
.IR /dev/mem ,
but the I/O ports are accessed.
-.PP
+.P
It is typically created by:
-.PP
+.P
.in +4n
.EX
mknod \-m 660 /dev/port c 1 4
.SH DESCRIPTION
.SS Introduction
The pinout of the usual 9 pin plug as used for serial mice is:
-.PP
+.P
.TS
center;
r c l.
7 RTS +12 V, Imax = 10 mA
5 GND Ground
.TE
-.PP
+.P
This is the specification, in fact 9 V suffices with most mice.
-.PP
+.P
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 (\[aq]M\[aq]) on the data line.
After a further 63 ms, a Microsoft-compatible 3-button mouse will send
0x33 (\[aq]3\[aq]).
-.PP
+.P
The relative mouse movement is sent as
.I dx
(positive means right)
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:
-.PP
+.P
.TS
center;
l l.
2400 *o
1200 *n
.TE
-.PP
+.P
The first byte of a data packet can be used for synchronization purposes.
.SS Microsoft protocol
The
.RI ( rb )
are set when the left (right)
button is pressed:
-.PP
+.P
.TS
center;
r c c c c c c c.
.IR rb )
are cleared when the left (middle,
right) button is pressed:
-.PP
+.P
.TS
center;
r c c c c c c c c.
4 0 dxb6 dxb5 dxb4 dxb3 dxb2 dxb1 dxb0
5 0 dyb6 dyb5 dyb4 dyb3 dyb2 dyb1 dyb0
.TE
-.PP
+.P
Bytes 4 and 5 describe the change that occurred since bytes 2 and 3
were transmitted.
.SS Sun protocol
.IR rb )
are
set when the left (middle, right) button is pressed:
-.PP
+.P
.TS
center;
r c c c c c c c c.
.I CPUNUM
is the number of the CPU to access as listed in
.IR /proc/cpuinfo .
-.PP
+.P
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.
-.PP
+.P
This file is protected so that it can be read and written only by the user
.IR root ,
or members of the group
driver is not auto-loaded.
On modular kernels you might need to use the following command
to load it explicitly before use:
-.PP
+.P
.in +4n
.EX
$ modprobe msr
and
.I /dev/zero
special files is discarded.
-.PP
+.P
Reads from
.I /dev/null
always return end of file (i.e.,
returns 0), whereas reads from
.I /dev/zero
always return bytes containing zero (\[aq]\e0\[aq] characters).
-.PP
+.P
These devices are typically created by:
-.PP
+.P
.in +4n
.EX
mknod \-m 666 /dev/null c 1 3
.SH NOTES
If these devices are not writable and readable for all users, many
programs will act strangely.
-.PP
+.P
Since Linux 2.6.31,
.\" commit 2b83868723d090078ac0e2120e06a1cc94dbaef0
reads from
is a character file with major number 5 and
minor number 2, usually with mode 0666 and ownership root:root.
It is used to create a pseudoterminal master and slave pair.
-.PP
+.P
When a process opens
.IR /dev/ptmx ,
it gets a file
whose path can
be found by passing the file descriptor to
.BR ptsname (3).
-.PP
+.P
Before opening the pseudoterminal slave, you must pass the master's file
descriptor to
.BR grantpt (3)
and
.BR unlockpt (3).
-.PP
+.P
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.
-.PP
+.P
Data written to the slave is presented on the master file descriptor as input.
Data written to the master is presented to the slave as input.
-.PP
+.P
In practice, pseudoterminals are used for implementing terminal emulators
such as
.BR xterm (1),
.BR 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.
-.PP
+.P
Pseudoterminals can also be used to send input to programs that normally
refuse to read input from pipes (such as
.BR su (1),
The
.I ram
device is a block device to access the ram disk in raw mode.
-.PP
+.P
It is typically created by:
-.PP
+.P
.in +4n
.EX
mknod \-m 660 /dev/ram b 1 1
.SH SYNOPSIS
.nf
#include <linux/random.h>
-.PP
+.P
.BI "int ioctl(" fd ", RND" request ", " param ");"
.fi
.SH DESCRIPTION
The file
.I /dev/urandom
has major device number 1 and minor device number 9.
-.PP
+.P
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.
-.PP
+.P
Linux 3.17 and later provides the simpler and safer
.BR getrandom (2)
interface which requires no special files;
see the
.BR getrandom (2)
manual page for details.
-.PP
+.P
When read, the
.I /dev/urandom
device returns random bytes using a pseudorandom
number generator seeded from the entropy pool.
Reads from this device do not block (i.e., the CPU is not yielded),
but can incur an appreciable delay when requesting large amounts of data.
-.PP
+.P
When read during early boot time,
.I /dev/urandom
may return data prior to the entropy pool being initialized.
If this is of concern in your application, use
.BR getrandom (2)
or \fI/dev/random\fP instead.
-.PP
+.P
The \fI/dev/random\fP device is a legacy interface which dates back to
a time where the cryptographic primitives used in the implementation
of \fI/dev/urandom\fP were not widely trusted.
bits of fresh noise in the entropy pool, blocking if necessary.
\fI/dev/random\fP is suitable for applications that need
high quality randomness, and can afford indeterminate delays.
-.PP
+.P
When the entropy pool is empty, reads from \fI/dev/random\fP will block
until additional environmental noise is gathered.
Since Linux 5.6, the
.I errno
will be set to
.BR EAGAIN .
-.PP
+.P
The
.B O_NONBLOCK
flag has no effect when opening
requested number of bytes or fail with the error
.BR EINTR ,
if interrupted by a signal handler.
-.PP
+.P
Since Linux 3.16,
.\" commit 79a8468747c5f95ed3d5ce8376a3e82e0c5857fc
a
will return at most 512 bytes
.\" SEC_XFER_SIZE in drivers/char/random.c
(340 bytes before Linux 2.6.12).
-.PP
+.P
Writing to \fI/dev/random\fP or \fI/dev/urandom\fP will update the
entropy pool with the data written, but this will not result in a
higher entropy count.
.BR getrandom (2)
must be used instead,
because it will block until the entropy pool is initialized.
-.PP
+.P
If a seed file is saved across reboots as recommended below,
the output is
cryptographically secure against attackers without local root access as
If your system does not have
\fI/dev/random\fP and \fI/dev/urandom\fP created already, they
can be created with the following commands:
-.PP
+.P
.in +4n
.EX
mknod \-m 666 /dev/random c 1 8
chown root:root /dev/random /dev/urandom
.EE
.in
-.PP
+.P
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
entropy pool information across shut-downs and start-ups.
To do this, add the lines to an appropriate script
which is run during the Linux system start-up sequence:
-.PP
+.P
.in +4n
.EX
echo "Initializing random number generator..."
dd if=/dev/urandom of=$random_seed count=1 bs=$bytes
.EE
.in
-.PP
+.P
Also, add the following lines in an appropriate script which is
run during the Linux system shutdown:
-.PP
+.P
.in +4n
.EX
# Carry a random seed from shut\-down to start\-up
dd if=/dev/urandom of=$random_seed count=1 bs=$bytes
.EE
.in
-.PP
+.P
In the above examples, we assume Linux 2.6.0 or later, where
.I /proc/sys/kernel/random/poolsize
returns the size of the entropy pool in bits (see below).
.BR mknod (1),
.BR getrandom (2),
.BR random (7)
-.PP
+.P
RFC\ 1750, "Randomness Recommendations for Security"
.SH SYNOPSIS
.nf
#include <linux/rtc.h>
-.PP
+.P
.BI "int ioctl(" fd ", RTC_" request ", " param ");"
.fi
.SH DESCRIPTION
This is the interface to drivers for real-time clocks (RTCs).
-.PP
+.P
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.
-.PP
+.P
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.
-.PP
+.P
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.
(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.
-.PP
+.P
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.
or directly with the
.BR ioctl (2)
requests listed below.
-.PP
+.P
Besides tracking the date and time, many RTCs can also generate
interrupts
.IP \[bu] 3
any power-of-2 multiple in the range 2 Hz to 8192 Hz;
.IP \[bu]
on reaching a previously specified alarm time.
-.PP
+.P
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
or even "off" (called S5 in ACPI systems).
On some systems, the battery backed RTC can't issue
interrupts, but another one can.
-.PP
+.P
The
.I /dev/rtc
(or
.B 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:
-.PP
+.P
.RS
.in +4n
.EX
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.
-.PP
+.P
An RTC's Epoch has nothing to do with the POSIX Epoch which is
used only for the system clock.
-.PP
+.P
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.
-.PP
+.P
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 expects only a single alarm interrupt, and
will either disable or reinitialize the alarm after receiving it.
-.PP
+.P
Some RTCs support periodic interrupts with periods that are multiples
of a second rather than fractions of a second;
multiple alarms;
.BR gmtime (3),
.BR time (7),
.BR hwclock (8)
-.PP
+.P
.I Documentation/rtc.txt
in the Linux kernel source tree
Often, the partition number,
.IR p ,
will be left off when the device corresponds to the whole drive.
-.PP
+.P
SCSI disks have a major device number of 8, and a minor device number of
the form (16 *
.IR drive_number ") + " partition_number ,
partitions 1\[en]4 are the DOS "primary" partitions
.IP \[bu]
partitions 5\[en]8 are the DOS "extended" (or "logical") partitions
-.PP
+.P
For example,
.I /dev/sda
will have major 8, minor 0, and will refer to all of the first SCSI drive
.I /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.
-.PP
+.P
At this time, only block devices are provided.
Raw devices have not yet been implemented.
.SH DESCRIPTION
.TP
.B HDIO_GETGEO
Returns the BIOS disk parameters in the following structure:
-.PP
+.P
.in +4n
.EX
struct hd_geometry {
.hy 0
.BR Note :
This obsolete driver was removed in Linux 2.6.26.
-.PP
+.P
.B 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.
-.PP
+.P
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:
-.PP
+.P
.in +4n
.EX
insmod sk98lin.o AutoNeg_A=On,Off
.EE
.in
-.PP
+.P
After
.B sk98lin
is bound to one or more adapter cards and the
.I x
is the number of the interface that has been assigned to a
dedicated port by the system.
-.PP
+.P
If loading is finished, any desired IP address can be
assigned to the respective
.I eth[x]
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.
-.PP
+.P
The
.B sk98lin
also supports large frames (also called jumbo frames).
If for instance eth0 needs an IP
address and a large frame MTU size,
the following two commands might be used:
-.PP
+.P
.in +4n
.EX
ifconfig eth0 10.1.1.1
ifconfig eth0 mtu 9000
.EE
.in
-.PP
+.P
Those two commands might even be combined into one:
-.PP
+.P
.in +4n
.EX
ifconfig eth0 10.1.1.1 mtu 9000
.EE
.in
-.PP
+.P
Note that large frames can be used only if permitted by
your network infrastructure.
This means, that any switch being used in your Ethernet must
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.
-.PP
+.P
Switching back to the standard Ethernet frame size can be done by using the
.BR ifconfig (8)
command again:
-.PP
+.P
.in +4n
.EX
ifconfig eth0 mtu 1500
.EE
.in
-.PP
+.P
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 available only after installation of open source modules
which can be found on the Internet:
-.PP
+.P
.IR VLAN :
.UR http://www.candelatech.com\:/\[ti]greear\:/vlan.html
.UE
.IR Aggregation :
.UR http://www.st.rim.or.jp\:/\[ti]yumo
.UE
-.PP
+.P
Note that Marvell/SysKonnect does not offer any support for these
open source modules and does not take the responsibility for any
kind of failures or problems arising when using these modules.
.BR sd (4),
.BR st (4),
.BR sg (4)
-.PP
+.P
.I Documentation/ABI/testing/sysfs\-bus\-pci\-devices\-cciss
in the Linux kernel source tree.
.SH SYNOPSIS
.nf
.B #include <sys/mtio.h>
-.PP
+.P
.BI "int ioctl(int " fd ", int " request " [, (void *)" arg3 "]);"
.BI "int ioctl(int " fd ", MTIOCTOP, (struct mtop *)" mt_cmd );
.BI "int ioctl(int " fd ", MTIOCGET, (struct mtget *)" mt_status );
The
.B st
driver uses major device number 9.
-.PP
+.P
Each device uses eight minor device numbers.
The lowermost five bits
in the minor numbers are assigned sequentially in the order of
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).
-.PP
+.P
Within each group, four minor numbers are available to define
devices with different characteristics (block size, compression,
density, etc.)
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.)
-.PP
+.P
Devices are typically created by:
-.PP
+.P
.in +4n
.EX
mknod \-m 666 /dev/st0 c 9 0
mknod \-m 666 /dev/nst0a c 9 224
.EE
.in
-.PP
+.P
There is no corresponding block device.
-.PP
+.P
The driver uses an internal buffer that has to be large enough to hold
at least one tape block.
Before Linux 2.1.121, the buffer is
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).
-.PP
+.P
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
contiguous blocks of memory may fail and it is advisable not to rely
too much on dynamic buffer allocation before Linux 2.1.121
(this applies also to demand-loading the driver with kerneld or kmod).
-.PP
+.P
The driver does not specifically support any tape drive brand or
model.
After system start-up the tape device options are defined by
calls and remain in effect when the device is closed and reopened.
Setting the options affects both the auto-rewind and the nonrewind
device.
-.PP
+.P
Different options can be specified for the different devices within
the subgroup of four.
The options take effect when the device is
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).
-.PP
+.P
The driver supports
.B tape partitions
if they are supported by the drive.
The driver contains an
.BR ioctl (2)
that can format a tape with either one or two partitions.
-.PP
+.P
Device
.I /dev/tape
is usually created as a hard or soft link to the default tape device
on the system.
-.PP
+.P
Starting from Linux 2.6.2, the driver exports in the sysfs directory
.I /sys/class/scsi_tape
the attached devices and some parameters assigned to the devices.
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.
-.PP
+.P
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
returns the actual block size.
If the block size is larger than the
byte count, an error is returned.
-.PP
+.P
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.
In all other cases
(before Linux 2.1.121 with buffering disabled or newer kernel) the
write byte count must be a multiple of the tape block size.
-.PP
+.P
In Linux 2.6, the driver tries to use direct transfers between the user
buffer and the device.
If this is not possible, the driver's internal buffer
of the user buffer (default is 512 bytes but this can be changed by the HBA
driver), one or more pages of the user buffer not reachable by the
SCSI adapter, and so on.
-.PP
+.P
A filemark is automatically written to tape if the last tape operation
before close was a write.
-.PP
+.P
When a filemark is encountered while reading, the following
happens.
If there are data remaining in the buffer when the filemark
The driver returns an
.B EIO
error if the drive rejects an operation.
-.PP
+.P
.in +4n
.EX
/* Structure for MTIOCTOP \- mag tape op command: */
};
.EE
.in
-.PP
+.P
Magnetic tape operations for normal tape use:
.TP
.B MTBSF
Write
.I mt_count
setmarks.
-.PP
+.P
Magnetic tape operations for setting of device options (by the superuser):
.TP
.B MTSETDRVBUFFER
.BR MT_NO_WAIT " (Default: false)"
Enables immediate mode (i.e., don't wait for the command to finish) for some
commands (e.g., rewind).
-.PP
+.P
An example:
-.PP
+.P
.in +4n
.EX
struct mtop mt_cmd;
ioctl(fd, MTIOCTOP, mt_cmd);
.EE
.in
-.PP
+.P
The default block size for a device can be set with
.B MT_ST_DEF_BLKSIZE
and the default density code can be set with
.BR MT_ST_DEFDENSITY .
The values for the parameters are or'ed
with the operation code.
-.PP
+.P
With Linux 2.1.x and later, the timeout values can be set with the
subcommand
.B MT_ST_SET_TIMEOUT
practical values for a specific drive.
The timeouts set for one device
apply for all devices linked to the same drive.
-.PP
+.P
Starting from Linux 2.4.19 and Linux 2.5.43, the driver supports a status
bit which indicates whether the drive requests cleaning.
The method used by the
.SS MTIOCGET \[em] get status
This request takes an argument of type
.IR "(struct mtget\ *)" .
-.PP
+.P
.in +4n
.EX
/* structure for MTIOCGET \- mag tape get status command */
command (device-specific address)
or a Tandberg-compatible SCSI-1 drive (Tandberg, Archive
Viper, Wangtek, ... ).
-.PP
+.P
.in +4n
.EX
/* structure for MTIOCPOS \- mag tape get position command */
If this is not possible, direct transfers can be disabled.
.SH SEE ALSO
.BR mt (1)
-.PP
+.P
The file
.I drivers/scsi/README.st
or
is a character file with major number 5 and
minor number 0, usually with mode 0666 and ownership root:tty.
It is a synonym for the controlling terminal of a process, if any.
-.PP
+.P
In addition to the
.BR ioctl (2)
requests supported by the device that
is supported.
.SS TIOCNOTTY
Detach the calling process from its controlling terminal.
-.PP
+.P
If the process is the session leader,
then
.B SIGHUP
.B SIGCONT
signals are sent to the foreground process group
and all processes in the current session lose their controlling tty.
-.PP
+.P
This
.BR ioctl (2)
call works only on file descriptors connected
.SH DESCRIPTION
.B ttyS[0\-3]
are character devices for the serial terminal lines.
-.PP
+.P
They are typically created by:
-.PP
+.P
.in +4n
.EX
mknod \-m 660 /dev/ttyS0 c 4 64 # base address 0x3f8
0, usually with mode 0644 and ownership root:tty.
It refers to the memory of the currently
displayed virtual console terminal.
-.PP
+.P
.I /dev/vcs[1\-63]
are character devices for virtual console
terminals, they have major number 7 and minor number 1 to 63, usually
=
.I y
= 0 at the top left corner of the screen.)
-.PP
+.P
When a 512-character font is loaded,
the 9th bit position can be fetched by applying the
.BR ioctl (2)
pointed to by the third
.BR ioctl (2)
argument.
-.PP
+.P
These devices replace the screendump
.BR ioctl (2)
operations of
.BR ioctl_console (2),
so the system
administrator can control access using filesystem permissions.
-.PP
+.P
The devices for the first eight virtual consoles may be created by:
-.PP
+.P
.in +4n
.EX
for x in 0 1 2 3 4 5 6 7 8; do
chown root:tty /dev/vcs*
.EE
.in
-.PP
+.P
No
.BR ioctl (2)
requests are supported.
Introduced with Linux 1.1.92.
.SH EXAMPLES
You may do a screendump on vt3 by switching to vt1 and typing
-.PP
+.P
.in +4n
.EX
cat /dev/vcs3 >foo
.EE
.in
-.PP
+.P
Note that the output does not contain
newline characters, so some processing may be required, like
in
-.PP
+.P
.in +4n
.EX
fold \-w 81 /dev/vcs3 | lpr
.EE
.in
-.PP
+.P
or (horrors)
-.PP
+.P
.in +4n
.EX
setterm \-dump 3 \-file /proc/self/fd/1
.EE
.in
-.PP
+.P
The
.I /dev/vcsa0
device is used for Braille support.
-.PP
+.P
This program displays the character and screen attributes under the
cursor of the second virtual console, then changes the background color
there:
-.PP
+.P
.EX
#include <unistd.h>
#include <stdlib.h>
They can act as tunnels between network namespaces to create
a bridge to a physical network device in another namespace,
but can also be used as standalone network devices.
-.PP
+.P
.B veth
devices are always created in interconnected pairs.
A pair can be created using the command:
-.PP
+.P
.in +4n
.EX
# ip link add <p1-name> type veth peer name <p2-name>
.EE
.in
-.PP
+.P
In the above,
.I p1-name
and
.I p2-name
are the names assigned to the two connected end points.
-.PP
+.P
Packets transmitted on one device in the pair are immediately received on
the other device.
When either device is down, the link state of the pair is down.
-.PP
+.P
.B veth
device pairs are useful for combining the network
facilities of the kernel together in interesting ways.
To do this, one can provide the
.B netns
parameter when creating the interfaces:
-.PP
+.P
.in +4n
.EX
# ip link add <p1\-name> netns <p1\-ns> type veth peer <p2\-name> netns <p2\-ns>
.EE
.in
-.PP
+.P
or, for an existing
.B veth
pair, move one side to the other namespace:
-.PP
+.P
.in +4n
.EX
# ip link set <p2\-name> netns <p2\-ns>
.EE
.in
-.PP
+.P
.BR ethtool (8)
can be used to find the peer of a
.B veth
network interface, using commands something like:
-.PP
+.P
.in +4n
.EX
# \fBip link add ve_A type veth peer name ve_B\fP # Create veth pair
.SH DESCRIPTION
.I This driver is obsolete:
it was removed in Linux 2.6.35.
-.PP
+.P
.B wavelan
is the low-level device driver for the NCR / AT&T / Lucent
.B WaveLAN ISA
Wavelan cards.
If this happens for you, you must look in the source code on
how to add your card to the detection routine.
-.PP
+.P
Some of the mentioned features are optional.
You may enable or disable
them by changing flags in the driver header and recompile.
then calling
.BR acct (2)
starts process accounting, for example:
-.PP
+.P
.in +4n
acct("/var/log/pacct");
.in
-.PP
+.P
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
.I <sys/acct.h>
as follows:
-.PP
+.P
.in +4n
.EX
#define ACCT_COMM 16
};
.EE
.in
-.PP
+.P
The
.I comp_t
data type is a floating-point value consisting of a 3-bit, base-8 exponent,
A value,
.IR c ,
of this type can be converted to a (long) integer as follows:
-.PP
+.P
.nf
v = (c & 0x1fff) << (((c >> 13) & 0x7) * 3);
.fi
-.PP
+.P
The
.IR ac_utime ,
.IR ac_stime ,
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:
-.PP
+.P
.in +4n
.EX
struct acct_v3 {
None.
.SH HISTORY
glibc 2.6.
-.PP
+.P
Process accounting originated on BSD.
.SH NOTES
Records in the accounting file are ordered by termination time of
the process.
-.PP
+.P
Up to and including Linux 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.
-.PP
+.P
The
.I /proc/sys/kernel/acct
file, described in
.RI < mb_cur_max >.
If not specified, it defaults to
.RI < mb_cur_max >.
-.PP
+.P
The character set definition section starts with the keyword
.I CHARMAP
in the first column.
-.PP
+.P
The following lines may have one of the two following forms to
define the character set:
.TP
This form defines a character range and its byte sequence,
.I comment
being optional.
-.PP
+.P
The character set definition section ends with the string
.IR "END CHARMAP" .
-.PP
+.P
The character set definition section may optionally be followed by a
section to define widths of characters.
-.PP
+.P
The
.I WIDTH_DEFAULT
keyword can be used to define the default width for all characters
not explicitly listed.
The default character width is 1.
-.PP
+.P
The width section for individual characters starts with the keyword
.I WIDTH
in the first column.
-.PP
+.P
The following lines may have one of the two following forms to
define the widths of the characters:
.TP
.TP
.RI < character >...< character >\ width
This form defines the width for all the characters in the range.
-.PP
+.P
The width definition section ends with the string
.IR "END WIDTH" .
.SH FILES
The Euro sign is defined as follows in the
.I UTF\-8
charmap:
-.PP
+.P
.nf
<U20AC> /xe2/x82/xac EURO SIGN
.fi
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
.BR signal (7).
-.PP
+.P
A process can set its soft
.B 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
.BR getrlimit (2)
for details.
-.PP
+.P
There are various circumstances in which a core dump file is
not produced:
.IP \[bu] 3
The kernel was configured without the
.B CONFIG_COREDUMP
option.
-.PP
+.P
In addition,
a core dump may exclude part of the address space of the process if the
.BR madvise (2)
.B MADV_DONTDUMP
flag was employed.
-.PP
+.P
On systems that employ
.BR systemd (1)
as the
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:
-.PP
+.P
.RS 4
.PD 0
.TP 4
Numeric real UID of dumped process.
.PD
.RE
-.PP
+.P
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.
.I /proc/sys/kernel/core_uses_pid
(see below)
is nonzero, then .PID will be appended to the core filename.
-.PP
+.P
Paths are interpreted according to the settings that are active for the
crashing process.
That means the crashing process's mount namespace (see
.BR getcwd (2)),
and its root directory (see
.BR chroot (2)).
-.PP
+.P
Since Linux 2.4, Linux has also provided
a more primitive method of controlling
the name of the core dump file.
If this file contains a nonzero value, then the core dump file includes
the process ID in a name of the form
.IR core.PID .
-.PP
+.P
Since Linux 3.6,
.\" 9520628e8ceb69fa9a4aee6b57f22675d9e1b709
if
If the first character of this file is a pipe symbol (\fB|\fP),
then the remainder of the line is interpreted as the command-line for
a user-space program (or script) that is to be executed.
-.PP
+.P
Since Linux 5.3.0,
.\" commit 315c69261dd3fa12dbc830d4fa00d1fad98d3b03
the pipe template is split on spaces into an argument list
in earlier kernels,
meaning that the core dump handler needs to use mechanisms to find
the executable name.
-.PP
+.P
Instead of being written to a file, the core dump is given as
standard input to the program.
Note the following points:
This in turn creates the
possibility that a misbehaving collecting program can block
the reaping of a crashed process by simply never exiting.
-.PP
+.P
Since Linux 2.6.32,
.\" commit a293980c2e261bd5b0d2a77340dd04f684caff58
the
processes may be piped to user-space programs in parallel.
If this value is exceeded, then those crashing processes above this value
are noted in the kernel log and their core dumps are skipped.
-.PP
+.P
A value of 0 in this file is special.
It indicates that unlimited processes may be captured in parallel,
but that no waiting will take place (i.e., the collecting
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.
-.PP
+.P
The value in the file is a bit mask of memory mapping types (see
.BR 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:
-.PP
+.P
.PD 0
.RS 4
.TP
Dump shared DAX pages.
.RE
.PD
-.PP
+.P
By default, the following bits are set: 0, 1, 4 (if the
.B CONFIG_CORE_DUMP_DEFAULT_ELF_HEADERS
kernel configuration option is enabled), and 5.
This default can be modified at boot time using the
.I coredump_filter
boot option.
-.PP
+.P
The value of this file is displayed in hexadecimal.
(The default value is thus displayed as 33.)
-.PP
+.P
Memory-mapped I/O pages such as frame buffer are never dumped, and
virtual DSO
.RB ( vdso (7))
pages are always dumped, regardless of the
.I coredump_filter
value.
-.PP
+.P
A child process created via
.BR fork (2)
inherits its parent's
.I coredump_filter
value is preserved across an
.BR execve (2).
-.PP
+.P
It can be useful to set
.I coredump_filter
in the parent shell before running a program, for example:
-.PP
+.P
.in +4n
.EX
.RB "$" " echo 0x7 > /proc/self/coredump_filter"
.RB "$" " ./some_program"
.EE
.in
-.PP
+.P
This file is provided only if the kernel was built with the
.B CONFIG_ELF_CORE
configuration option.
One can verify this by checking whether core dumps are being piped to the
.BR systemd\-coredump (8)
program:
-.PP
+.P
.in +4n
.EX
$ \fBcat /proc/sys/kernel/core_pattern\fP
|/usr/lib/systemd/systemd\-coredump %P %u %g %s %t %c %e
.EE
.in
-.PP
+.P
In this case, core dumps will be placed in the location configured for
.BR systemd\-coredump (8),
typically as
.BR systemd\-coredump (8)
using
.BR coredumpctl (1):
-.PP
+.P
.EX
$ \fBcoredumpctl list | tail \-5\fP
Wed 2017\-10\-11 22:25:30 CEST 2748 1000 1000 3 present /usr/bin/sleep
Thu 2017\-10\-12 06:37:40 CEST 2918 1000 1000 3 present /usr/bin/cat
Thu 2017\-10\-12 08:13:07 CEST 2955 1000 1000 3 present /usr/bin/cat
.EE
-.PP
+.P
The information shown for each core dump includes the date and time
of the dump, the PID, UID, and GID of the dumping process,
the signal number that caused the core dump,
For example, to extract the core dump for PID 2955 shown above to a file named
.I core
in the current directory, one could use:
-.PP
+.P
.in +4n
.EX
$ \fBcoredumpctl dump 2955 \-o core\fP
.EE
.in
-.PP
+.P
For more extensive details, see the
.BR coredumpctl (1)
manual page.
-.PP
+.P
To (persistently) disable the
.BR systemd (1)
mechanism that archives core dumps, restoring to something more like
traditional Linux behavior, one can set an override for the
.BR systemd (1)
mechanism, using something like:
-.PP
+.P
.in +4n
.EX
# \fBecho "kernel.core_pattern=core.%p" > \e\fP
# \fB/lib/systemd/systemd\-sysctl\fP
.EE
.in
-.PP
+.P
It is also possible to temporarily (i.e., until the next reboot) change the
.I core_pattern
setting using a command such as the following
(which causes the names of core dump files to include the executable name
as well as the number of the signal which triggered the core dump):
-.PP
+.P
.in +4n
.EX
# \fBsysctl \-w kernel.core_pattern="%e\-%s.core"\fP
.BR gdb (1)
.I gcore
command can be used to obtain a core dump of a running process.
-.PP
+.P
In Linux versions up to and including 2.6.27,
.\" Changed with commit 6409324b385f3f63a03645b4422e3be67348d922
if a multithreaded process (or, more precisely, a process that
The following shell session demonstrates the use of this program
(compiled to create an executable named
.IR core_pattern_pipe_test ):
-.PP
+.P
.in +4n
.EX
.RB "$" " cc \-o core_pattern_pipe_test core_pattern_pipe_test.c"
.B LS_COLORS
to determine the colors in which the filenames are to be displayed.
This environment variable is usually set by a command like
-.PP
+.P
.RS
eval \`dircolors some_path/dir_colors\`
.RE
-.PP
+.P
found in a system default shell initialization file, like
.I /etc/profile
or
and can be overridden by a
.I .dir_colors
file in one's home directory.
-.PP
+.P
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.
-.PP
+.P
The
.I global
section of the file consists of any statement before the first
environment variable) the following declarations apply to.
It is always possible to override a global declaration by a subsequent
terminal-specific one.
-.PP
+.P
The following statements are recognized; case is insignificant:
.TP
.B TERM \fIterminal-type\fR
codes and harmlessly eliminate them from the output or emulate them.
.B ls
uses ISO 6429 codes by default, assuming colorization is enabled.
-.PP
+.P
ISO 6429 color sequences are composed of sequences of numbers
separated by semicolons.
The most common codes are:
47 for white (or gray) background
.TE
.RE
-.PP
+.P
Not all commands will work on all systems or display devices.
-.PP
+.P
.B ls
uses the following defaults:
.TS
CHR 44;37 Character device
EXEC 35 Executable file
.TE
-.PP
+.P
A few terminal programs do not recognize the default
properly.
If all text gets colorized after you do a directory
and
.B ENDCODE
definitions.
-.PP
+.P
When writing out a filename,
.B ls
generates the following output sequence:
If they are not appropriate for
your terminal, you can eliminate them by specifying the respective
keyword on a line by itself.
-.PP
+.P
.B NOTE:
If the
.B ENDCODE
\e# Hash mark (#)
.TE
.RE
-.PP
+.P
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.
.TP
.I \[ti]/.dir_colors
Per-user configuration file.
-.PP
+.P
This page describes the
.B dir_colors
file format as used in the fileutils-4.1 package;
RIGHTCODE m
.TE
.RE
-.PP
+.P
The default
.B ENDCODE
is undefined.
Amongst these files are
normal executable files, relocatable object files, core files, and shared
objects.
-.PP
+.P
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.
ELF header.
The two tables describe the rest of the particularities of
the file.
-.PP
+.P
.\" Applications which wish to process ELF binary files for their native
.\" architecture only should include
.\" .I <elf_abi.h>
.\" ELF_xxx".
.\" Applications written this way can be compiled on any architecture,
.\" regardless of whether the host is 32-bit or 64-bit.
-.\" .PP
+.\" .P
.\" Should an application need to process ELF files of an unknown
.\" architecture, then the application needs to explicitly use either
.\" "Elf32_xxx"
.\" "ELF32_xxx"
.\" or
.\" "ELF64_xxx".
-.\" .PP
+.\" .P
This header file describes the above mentioned headers as C structures
and also includes structures for dynamic sections, relocation sections and
symbol tables.
.I uint32_t
or
.IR uint64_t ):
-.PP
+.P
.in +4n
.EX
ElfN_Addr Unsigned program address, uintN_t
.\" Elf32_Size Unsigned object size
.EE
.in
-.PP
+.P
(Note: the *BSD terminology is a bit different.
There,
.I Elf64_Half
.IR uint16_t .
In order to avoid confusion these types are replaced by explicit ones
in the below.)
-.PP
+.P
All data structures that the file format defines follow the
"natural"
size and alignment guidelines for the relevant class.
.I Elf32_Ehdr
or
.IR Elf64_Ehdr :
-.PP
+.P
.in +4n
.EX
#define EI_NIDENT 16
} ElfN_Ehdr;
.EE
.in
-.PP
+.P
The fields have the following meanings:
.\"
.\"
or
.I Elf64_Phdr
depending on the architecture:
-.PP
+.P
.in +4n
.EX
typedef struct {
} Elf32_Phdr;
.EE
.in
-.PP
+.P
.in +4n
.EX
typedef struct {
} Elf64_Phdr;
.EE
.in
-.PP
+.P
The main difference between the 32-bit and the 64-bit program header lies
in the location of the
.I p_flags
holds the number of entries the section header table contains.
.I e_shentsize
holds the size in bytes of each entry.
-.PP
+.P
A section header table index is a subscript into this array.
Some section
header table indices are reserved:
inclusive.
The section header table does not contain entries for the
reserved indices.
-.PP
+.P
The section header has the following structure:
-.PP
+.P
.in +4n
.EX
typedef struct {
} Elf32_Shdr;
.EE
.in
-.PP
+.P
.in +4n
.EX
typedef struct {
} Elf64_Shdr;
.EE
.in
-.PP
+.P
No real differences exist between the 32-bit and 64-bit section headers.
.TP
.I sh_name
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.
-.PP
+.P
Various sections hold program and control information:
.TP
.I .bss
a null byte (\[aq]\e0\[aq]).
Similarly, a string table's last byte is defined to
hold a null byte, ensuring null termination for all strings.
-.PP
+.P
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.
-.PP
+.P
.in +4n
.EX
typedef struct {
} Elf32_Sym;
.EE
.in
-.PP
+.P
.in +4n
.EX
typedef struct {
} Elf64_Sym;
.EE
.in
-.PP
+.P
The 32-bit and 64-bit versions have the same members, just in a different
order.
.TP
Symbol is available to other modules,
but references in the local module always resolve to the local symbol.
.PD
-.PP
+.P
There are macros for extracting the visibility type:
-.PP
+.P
.BR ELF32_ST_VISIBILITY (other)
or
.BR ELF64_ST_VISIBILITY (other)
and shared object files to hold the right information for a process's
program image.
Relocation entries are these data.
-.PP
+.P
Relocation structures that do not need an addend:
-.PP
+.P
.in +4n
.EX
typedef struct {
} Elf32_Rel;
.EE
.in
-.PP
+.P
.in +4n
.EX
typedef struct {
} Elf64_Rel;
.EE
.in
-.PP
+.P
Relocation structures that need an addend:
-.PP
+.P
.in +4n
.EX
typedef struct {
} Elf32_Rela;
.EE
.in
-.PP
+.P
.in +4n
.EX
typedef struct {
member controls the interpretation
of
.IR d_un .
-.PP
+.P
.in +4n
.EX
typedef struct {
extern Elf32_Dyn _DYNAMIC[];
.EE
.in
-.PP
+.P
.in +4n
.EX
typedef struct {
For example,
the GNU tool chain uses ELF notes to pass information from
the linker to the C library.
-.PP
+.P
Note sections contain a series of notes (see the
.I struct
definitions below).
\fIn_namesz\fR) and then by the descriptor field (whose length is defined in
\fIn_descsz\fR) and whose starting address has a 4 byte alignment.
Neither field is defined in the note struct due to their arbitrary lengths.
-.PP
+.P
An example for parsing out two consecutive notes should clarify their layout
in memory:
-.PP
+.P
.in +4n
.EX
void *memory, *name, *desc;
ALIGN_UP(note\->n_descsz, 4);
.EE
.in
-.PP
+.P
Keep in mind that the interpretation of
.I n_type
depends on the namespace defined by the
one for core files and one for all other ELF types.
If the namespace is unknown, then tools will usually fallback to these sets
of notes as well.
-.PP
+.P
.in +4n
.EX
typedef struct {
} Elf32_Nhdr;
.EE
.in
-.PP
+.P
.in +4n
.EX
typedef struct {
ELF first appeared in
System V.
The ELF format is an adopted standard.
-.PP
+.P
The extensions for
.IR e_phnum ,
.IR e_shnum ,
.BR dl_iterate_phdr (3),
.BR core (5),
.BR ld.so (8)
-.PP
+.P
Hewlett-Packard,
.IR "Elf-64 Object File Format" .
-.PP
+.P
Santa Cruz Operation,
.IR "System V Application Binary Interface" .
-.PP
+.P
UNIX System Laboratories,
"Object Files",
.IR "Executable and Linking Format (ELF)" .
-.PP
+.P
Sun Microsystems,
.IR "Linker and Libraries Guide" .
-.PP
+.P
AMD64 ABI Draft,
.IR "System V Application Binary Interface AMD64 Architecture Processor Supplement" .
.B erofs
is a create-once read-only filesystem,
with support for compression and a multi-device backing store.
-.PP
+.P
There are two inode formats:
.IP \[bu] 3
32-byte compact with 16-bit UID/GID,
.BR mkfs.erofs (1),
.BR fsck.erofs (1),
.BR dump.erofs (1)
-.PP
+.P
.I Documentation/filesystems/erofs.txt
in the Linux source.
regardless of
.I /proc
availability and/or sanity.
-.PP
+.P
If you need a currently unsupported filesystem, insert the corresponding
kernel module or recompile the kernel.
-.PP
+.P
In order to use a filesystem, you have to
.I mount
it; see
.BR mount (2)
and
.BR mount (8).
-.PP
+.P
The following list provides a
short description of the available or historically available
filesystems in the Linux kernel.
This file is used not merely for
system administration purposes but also for improving security within a TCP/IP
networked environment.
-.PP
+.P
The
.B ftpusers
file 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.
-.PP
+.P
If your FTP server daemon doesn't use
.BR ftpusers ,
then it is suggested that you read its documentation to find out how to
For the glibc implementation, this can be achieved with the
.I /etc/gai.conf
file.
-.PP
+.P
Each line in the configuration file consists of a keyword and its parameters.
White spaces in any place are ignored.
Lines starting with \[aq]#\[aq] are comments and are ignored.
-.PP
+.P
The keywords currently recognized are:
.TP
\fBlabel\fR \fInetmask\fR \fIprecedence\fR
.SH EXAMPLES
The default table according to RFC\ 3484 would be specified with the
following configuration file:
-.PP
+.P
.in +4n
.EX
label ::1/128 0
.I /etc/group
file is a text file that defines the groups on the system.
There is one entry per line, with the following format:
-.PP
+.P
.in +4n
.EX
group_name:password:GID:user_list
.EE
.in
-.PP
+.P
The fields are as follows:
.TP
.I group_name
The
.BR nsswitch.conf (5)
file is the modern way of controlling the order of host lookups.
-.PP
+.P
In glibc 2.4 and earlier, the following keyword is recognized:
.TP
.I order
Overrides the
.I order
command.
-.PP
+.P
.\" commit 7d68cdaa4f748e87ee921f587ee2d483db624b3d
Since glibc 2.0.7, and up through glibc 2.24,
the following keywords and environment variable
For each host a single
line should be present with the following information:
.RS
-.PP
+.P
IP_address canonical_hostname [aliases...]
.RE
-.PP
+.P
The IP address can conform to either IPv4 or IPv6.
Fields of the entry are separated by any number of blanks and/or
tab characters.
.IR localhost ).
If required, a host may have two separate entries in this file;
one for each version of the Internet Protocol (IPv4 and IPv6).
-.PP
+.P
The Berkeley Internet Name Domain (BIND) Server implements the
Internet name server for UNIX systems.
It augments or replaces the
file or hostname lookup, and frees a host from relying on
.I /etc/hosts
being up to date and complete.
-.PP
+.P
In modern systems, even though the host table has been superseded by
DNS, it is still widely used for:
.TP
.SS Historical notes
RFC\ 952 gave the original format for the host table, though it has
since changed.
-.PP
+.P
Before the advent of DNS, the host table was the only way of resolving
hostnames on the fledgling Internet.
Indeed, this file could be
.BR resolver (5),
.BR hostname (7),
.BR named (8)
-.PP
+.P
Internet RFC\ 952
.\" .SH AUTHOR
.\" This manual page was written by Manoj Srivastava <srivasta@debian.org>,
.BR rcp )
without
supplying a password.
-.PP
+.P
The file uses the following format:
.TP
\fI+|[\-]hostname|+@netgroup|\-@netgroup\fP \fI[+|[\-]username|+@netgroup|\-@netgroup]\fP
-.PP
+.P
The
.I hostname
is the name of a host which is logically equivalent
including possibly a password.
For security reasons you should always
use the FQDN of the hostname and not the short hostname.
-.PP
+.P
The
.I username
entry grants a specific user access to all user
a minus (\-) sign.
This says that the user is not trusted no matter
what other entries for that host exist.
-.PP
+.P
Netgroups can be specified by preceding the netgroup by an @ sign.
-.PP
+.P
Be extremely careful when using the plus (+) sign.
A simple typographical
error could result in a standalone plus sign.
root and no write permission for anybody else.
Some exceptionally
paranoid systems even require that there be no other hard links to the file.
-.PP
+.P
Modern systems use the Pluggable Authentication Modules library (PAM).
With PAM a standalone plus sign is considered a wildcard
character which means "any host" only when the word
or
.I \[ti]/.rhosts
files.
-.PP
+.P
Allow any user to log in from any host:
-.PP
+.P
.in +4n
.EX
+
.EE
.in
-.PP
+.P
Allow any user from
.I host
with a matching local account to log in:
-.PP
+.P
.in +4n
.EX
host
.EE
.in
-.PP
+.P
Note: the use of
.I +host
is never a valid syntax,
including attempting to specify that any user from the host is allowed.
-.PP
+.P
Allow any user from
.I host
to log in:
-.PP
+.P
.in +4n
.EX
host +
.EE
.in
-.PP
+.P
Note: this is distinct from the previous example
since it does not require a matching local account.
-.PP
+.P
Allow
.I user
from
.I host
to log in as any non-root user:
-.PP
+.P
.in +4n
.EX
host user
.EE
.in
-.PP
+.P
Allow all users with matching local accounts from
.I host
to log in except for
.IR baduser :
-.PP
+.P
.in +4n
.EX
host \-baduser
host
.EE
.in
-.PP
+.P
Deny all users from
.IR host :
-.PP
+.P
.in +4n
.EX
\-host
.EE
.in
-.PP
+.P
Note: the use of
.I "\-host\ \-user"
is never a valid syntax,
including attempting to specify that a particular user from the host
is not trusted.
-.PP
+.P
Allow all users with matching local accounts on all hosts in a
.IR netgroup :
-.PP
+.P
.in +4n
.EX
+@netgroup
.EE
.in
-.PP
+.P
Disallow all users on all hosts in a
.IR netgroup :
-.PP
+.P
.in +4n
.EX
\-@netgroup
.EE
.in
-.PP
+.P
Allow all users in a
.I netgroup
to log in from
.I host
as any non-root user:
-.PP
+.P
.in +4n
.EX
host +@netgroup
.EE
.in
-.PP
+.P
Allow all users with matching local accounts on all hosts in a
.I netgroup
except
.IR baduser :
-.PP
+.P
.in +4n
.EX
+@netgroup \-baduser
+@netgroup
.EE
.in
-.PP
+.P
Note: the deny statements must always precede the allow statements because
the file is processed sequentially until the first matching rule is found.
.SH SEE ALSO
.SH DESCRIPTION
Section 5 of the manual describes various file formats,
as well as the corresponding C structures, if any.
-.PP
+.P
In addition,
this section contains a number of pages that document various filesystems.
.SH NOTES
definition file contains all the information that the
.BR localedef (1)
command needs to convert it into the binary locale database.
-.PP
+.P
The definition files consist of sections which each describe a
locale category in detail.
See
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 (#).
-.PP
+.P
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.
where a
.I copy
statement can be followed by locale-specific rules and selected overrides.
-.PP
+.P
When defining a locale or a category from scratch, an existing system-
provided locale definition file should be used as a reference to follow
common glibc conventions.
.B LC_NUMERIC
.IP \[bu]
.B LC_TIME
-.PP
+.P
In addition, since glibc 2.2,
the GNU C library supports the following nonstandard categories:
.IP \[bu] 3
.B LC_PAPER
.IP \[bu]
.B LC_TELEPHONE
-.PP
+.P
See
.BR locale (7)
for a more detailed description of each category.
The definition starts with the string
.I LC_ADDRESS
in the first column.
-.PP
+.P
The following keywords are allowed:
.TP
.I postal_fmt
.TP
%c
Country, as taken from data record.
-.PP
+.P
Each field descriptor may have an \[aq]R\[aq] after
the \[aq]%\[aq] to specify that the
information is taken from a Romanized version string of the
.I lang_term
over
.IR lang_lib .
-.PP
+.P
The
.B LC_ADDRESS
definition ends with the string
The definition starts with the string
.I LC_CTYPE
in the first column.
-.PP
+.P
The following keywords are allowed:
.TP
.I upper
.TP
.I translit_end
marks the end of the transliteration rules.
-.PP
+.P
The
.B LC_CTYPE
definition ends with the string
.SS LC_COLLATE
Note that glibc does not support all POSIX-defined options,
only the options described below are supported (as of glibc 2.23).
-.PP
+.P
The definition starts with the string
.I LC_COLLATE
in the first column.
-.PP
+.P
The following keywords are allowed:
.TP
.I coll_weight_max
.I symbol\-equivalence
followed by a collating-symbol to be equivalent to another defined
collating-symbol.
-.PP
+.P
The collation rule definition starts with a line:
.TP
.I order_start
The order definition consists of lines that describe the collation
order and is terminated with the keyword
.IR order_end .
-.PP
+.P
The
.B LC_COLLATE
definition ends with the string
The definition starts with the string
.I LC_IDENTIFICATION
in the first column.
-.PP
+.P
The following keywords are allowed:
.TP
.I title
.TP
.I date
followed by the revision date of this document.
-.PP
+.P
In addition, for each of the categories defined by the document,
there should be a line starting with the keyword
.IR category ,
one of the
.B LC_*
identifiers.
-.PP
+.P
The
.B LC_IDENTIFICATION
definition ends with the string
The definition starts with the string
.I LC_MESSAGES
in the first column.
-.PP
+.P
The following keywords are allowed:
.TP
.I yesexpr
.TP
.I nostr
followed by the output string corresponding to "no".
-.PP
+.P
The
.B LC_MESSAGES
definition ends with the string
The definition starts with the string
.I LC_MEASUREMENT
in the first column.
-.PP
+.P
The following keywords are allowed:
.TP
.I measurement
.B 2
US customary measurements.
.RE
-.PP
+.P
The
.B LC_MEASUREMENT
definition ends with the string
The definition starts with the string
.I LC_MONETARY
in the first column.
-.PP
+.P
The following keywords are allowed:
.TP
.I int_curr_symbol
internationally formatted monetary quantity.
The same values are recognized as for
.IR p_sign_posn .
-.PP
+.P
The
.B LC_MONETARY
definition ends with the string
The definition starts with the string
.I LC_NAME
in the first column.
-.PP
+.P
Various keywords are allowed, but only
.I name_fmt
is mandatory.
.TP
.I name_ms
followed by the salutation valid for all women.
-.PP
+.P
The
.B LC_NAME
definition ends with the string
The definition starts with the string
.I LC_NUMERIC
in the first column.
-.PP
+.P
The following keywords are allowed:
.TP
.I decimal_point
If the last integer is not \-1, then the size of the previous group
(if any) is repeatedly used for the remainder of the digits.
If the last integer is \-1, then no further grouping is performed.
-.PP
+.P
The
.B LC_NUMERIC
definition ends with the string
The definition starts with the string
.I LC_PAPER
in the first column.
-.PP
+.P
The following keywords are allowed:
.TP
.I height
.TP
.I width
followed by the width, in millimeters, of the standard paper format.
-.PP
+.P
The
.B LC_PAPER
definition ends with the string
The definition starts with the string
.I LC_TELEPHONE
in the first column.
-.PP
+.P
The following keywords are allowed:
.TP
.I tel_int_fmt
.TP
.I int_prefix
followed by the prefix used from other countries to dial this country.
-.PP
+.P
The
.B LC_TELEPHONE
definition ends with the string
The definition starts with the string
.I LC_TIME
in the first column.
-.PP
+.P
The following keywords are allowed:
.TP
.I abday
counted and displayed for each era in the locale.
Each string has the following format:
.RS
-.PP
+.P
.IR direction ":" offset ":" start_date ":" end_date ":" era_name ":" era_format
-.PP
+.P
The fields are to be defined as follows:
.TP 4
.I direction
.BR date (1)
(for syntax, see
.BR strftime (3)).
-.PP
+.P
The
.B LC_TIME
definition ends with the string
are displayed by
.BR login (1)
after a successful login but just before it executes the login shell.
-.PP
+.P
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).
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:
-.PP
+.P
.RS
.I name number aliases ...
.RE
-.PP
+.P
where the fields are delimited by spaces or tabs.
Empty lines are ignored.
The hash character (\fB#\fP) 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.
-.PP
+.P
The field descriptions are:
.TP
.I name
.TP
.I aliases
Optional aliases for the network.
-.PP
+.P
This file is read by the
.BR route (8)
and
A \[aq]#\[aq] (number sign) indicates the beginning of a
comment; following characters, up to the end of the line,
are not interpreted by nscd.
-.PP
+.P
Valid services are \fIpasswd\fP, \fIgroup\fP, \fIhosts\fP, \fIservices\fP,
or \fInetgroup\fP.
-.PP
+.P
.B logfile
.I debug-file-name
.RS
Specifies name of the file to which debug info should be written.
.RE
-.PP
+.P
.B debug\-level
.I value
.RS
3 (and above) shows all debug info.
The default is 0.
.RE
-.PP
+.P
.B threads
.I number
.RS
in response to demand from clients,
but never decreases.
.RE
-.PP
+.P
.B max\-threads
.I number
.RS
Specifies the maximum number of threads.
The default is 32.
.RE
-.PP
+.P
.B server\-user
.I user
.RS
If a separate cache for every user is used (\-S parameter), this
option is ignored.
.RE
-.PP
+.P
.B stat\-user
.I user
.RS
Specifies the user who is allowed to request statistics.
.RE
-.PP
+.P
.B reload\-count
unlimited |
.I number
A limit of 0 turns off the reloading feature.
See NOTES below for further discussion of reloading.
.RE
-.PP
+.P
.B paranoia
.I <yes|no>
.RS
Enabling paranoia mode causes nscd to restart itself periodically.
The default is no.
.RE
-.PP
+.P
.B restart\-interval
.I time
.RS
mode.
The default is 3600.
.RE
-.PP
+.P
.B enable\-cache
.I service
.I <yes|no>
cache.
The default is no.
.RE
-.PP
+.P
.B positive\-time\-to\-live
.I service
.I value
the TTL returned from the name service is used and
this attribute is ignored.
.RE
-.PP
+.P
.B negative\-time\-to\-live
.I service
.I value
example untarring the Linux kernel sources as root); should be kept small
to reduce cache coherency problems.
.RE
-.PP
+.P
.B suggested\-size
.I service
.I value
should remain a prime number for optimum efficiency.
The default is 211.
.RE
-.PP
+.P
.B check\-files
.I service
.I <yes|no>
.IR /etc/netgroup .
The default is yes.
.RE
-.PP
+.P
.B persistent
.I service
.I <yes|no>
mode is set.
The default is no.
.RE
-.PP
+.P
.B shared
.I service
.I <yes|no>
Note that a cache miss will still result in
asking the daemon over the socket.
.RE
-.PP
+.P
.B max\-db\-size
.I service
.I bytes
.IR service .
The default is 33554432.
.RE
-.PP
+.P
.B auto\-propagate
.I service
.I <yes|no>
.BR nscd (8)
has a feature called reloading,
whose behavior can be surprising.
-.PP
+.P
Reloading is enabled when the
.B reload-count
attribute has a non-zero value.
The default value in the source code enables reloading,
although your distribution may differ.
-.PP
+.P
When reloading is enabled,
positive cached entries (the results of successful queries)
do not simply expire when their TTL is up.
Purging the cache using
.I nscd\~-i
overrides the reload logic and removes the entry.
-.PP
+.P
Reloading has the effect of extending cache entry TTLs
without compromising on cache coherency,
at the cost of additional load on the backing name service.
the value of the
.B positive\-time\-to\-live
attribute.
-.PP
+.P
Please consider the following advice carefully:
.IP \[bu] 3
If your application will make a second request for the same name,
is almost never a good idea,
as it will result in a cache that never expires entries
and puts never-ending additional load on the backing name service.
-.PP
+.P
Some distributions have an init script for
.BR nscd (8)
with a
The various services
provided are implemented by independent modules, each of which
naturally varies widely from the other.
-.PP
+.P
The default implementations coming with the GNU C library are by
default conservative and do not use unsafe data.
This might be very costly in some situations, especially when the databases
taking shortcuts if these are known to be safe.
It is then the system administrator's responsibility to ensure the assumption
is correct.
-.PP
+.P
There are other modules where the implementation changed over time.
If an implementation used to sacrifice speed for memory consumption,
it might create problems if the preference is switched.
-.PP
+.P
The
.I /etc/default/nss
file contains a number of variable assignments.
White spaces are ignored.
Lines beginning with \[aq]#\[aq]
are treated as comments.
-.PP
+.P
The variables currently recognized are:
.TP
\fBNETID_AUTHORITATIVE =\fR \fITRUE\fR|\fIFALSE\fR
\fI/etc/default/nss\fR
.SH EXAMPLES
The default configuration corresponds to the following configuration file:
-.PP
+.P
.in +4n
.EX
NETID_AUTHORITATIVE=FALSE
a range of categories,
and in what order.
Each category of information is identified by a database name.
-.PP
+.P
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.
-.PP
+.P
The following databases are understood by the GNU C Library:
.TP 12
.B aliases
Shadow user passwords, used by
.BR getspnam (3)
and related functions.
-.PP
+.P
The GNU C Library ignores databases with unknown names.
Some applications use this to implement special handling for their own
databases.
and
.BR subgid (5)
for more details.
-.PP
+.P
Here is an example
.I /etc/nsswitch.conf
file:
-.PP
+.P
.in +4n
.EX
passwd: compat
services: nis [NOTFOUND=return] files
.EE
.in
-.PP
+.P
The first column is the database name.
The remaining columns specify:
.IP \[bu] 3
.IP \[bu]
Optional actions to perform if a particular result is obtained
from the preceding service, for example, "[NOTFOUND=return]".
-.PP
+.P
The service specifications supported on your system depend on the
presence of shared libraries, and are therefore extensible.
Libraries called
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".
-.PP
+.P
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:
-.PP
+.P
.RS 4
.RI [ STATUS = ACTION ]
.br
.RI [! STATUS = ACTION ]
.RE
-.PP
+.P
where
-.PP
+.P
.RS 4
.I STATUS
=>
|
.B merge
.RE
-.PP
+.P
The ! negates the test, matching all possible results except the
one specified.
The case of the keywords is not significant.
-.PP
+.P
The
.I STATUS
value is matched against the result of the lookup function called by
locked or a server currently cannot accept more connections.
The default action for this condition is "continue".
.RE
-.PP
+.P
The
.I ACTION
value can be one of:
for granting users or members of netgroups access to the system.
The following entries are valid in this mode:
.RS 4
-.PP
+.P
For
.B passwd
and
Include every user, except previously excluded ones, from the
NIS passwd/shadow map.
.RE
-.PP
+.P
For
.B group
database:
NIS group map.
.RE
.RE
-.PP
+.P
By default, the source is "nis", but this may be
overridden by specifying any NSS service except "compat" itself
as the source for the pseudo-databases
implements "nisplus" source.
.PD
.RE
-.PP
+.P
The following files are read when "files" source is specified
for respective databases:
.RS 4
In earlier versions, the entire file was read only once within each process.
If the file was later changed,
the process would continue using the old configuration.
-.PP
+.P
Traditionally, there was only a single source for service information,
often in the form of a single configuration
file (e.g., \fI/etc/passwd\fP).
.BR ls (1)
use it to map user IDs to usernames), but write access only for the
superuser.
-.PP
+.P
In the good old days there was no great problem with this general
read permission.
Everybody could read the encrypted passwords, but the
and the encrypted passwords are in
.IR /etc/shadow ,
which is readable by the superuser only.
-.PP
+.P
If the encrypted password, whether in
.I /etc/passwd
or in
.RB \[dq] nonull \[dq]
arguments to
.BR pam_unix (8)).
-.PP
+.P
If the encrypted password in
.I /etc/passwd
is "\fI*NP*\fP" (without the quotes),
the shadow record should be obtained from an NIS+ server.
-.PP
+.P
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 themself using a
password.
(But see NOTES below.)
-.PP
+.P
If you create a new login, first put an asterisk (*) in the password field,
then use
.BR passwd (1)
to set it.
-.PP
+.P
Each line of the file describes a single user,
and contains seven colon-separated fields:
-.PP
+.P
.in +4n
.EX
name:password:UID:GID:GECOS:directory:shell
.EE
.in
-.PP
+.P
The field are as follows:
.TP 12
.I name
If you want to create user groups, there must be an entry in
.IR /etc/group ,
or no group will exist.
-.PP
+.P
If the encrypted password is set to an asterisk (*), the user will be unable
to login using
.BR login (1),
.IR /proc .
Typically, it is mounted automatically by the system,
but it can also be mounted manually using a command such as:
-.PP
+.P
.in +4n
.EX
mount \-t proc proc /proc
.EE
.in
-.PP
+.P
Most of the files in the
.B proc
filesystem are read-only,
Various other files and subdirectories under
.I /proc
expose system-wide information.
-.PP
+.P
All of the above are described in more detail below.
.\"
.\" .SH FILES
with subfields terminated by null bytes (\[aq]\e0\[aq]).
When inspecting such files, you may find that the results are more readable
if you use a command of the following form to display them:
-.PP
+.P
.in +4n
.EX
.RB "$" " cat \fIfile\fP | tr \[aq]\e000\[aq] \[aq]\en\[aq]"
.BR procinfo (8),
.BR route (8),
.BR sysctl (8)
-.PP
+.P
The Linux kernel source files:
.IR Documentation/filesystems/proc.rst ,
.IR Documentation/admin\-guide/sysctl/fs.rst ,
even worse, just guessing them.
These numbers will occur in the
protocol field of any IP header.
-.PP
+.P
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).
.\" .. by the DDN Network Information Center.
-.PP
+.P
Each line is of the following format:
-.PP
+.P
.RS
.I protocol number aliases ...
.RE
-.PP
+.P
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.
-.PP
+.P
The field descriptions are:
.TP
.I protocol
.TP
.I aliases
optional aliases for the protocol.
-.PP
+.P
This file might be distributed over a network using a network-wide
naming service like Yellow Pages/NIS or BIND/Hesiod.
.SH FILES
The protocols definition file.
.SH SEE ALSO
.BR getprotoent (3)
-.PP
+.P
.UR http://www.iana.org\:/assignments\:/protocol\-numbers
.UE
for the rest of the file to mark characters that should be interpreted
in a special way.
It defaults to the backslash (\e).
-.PP
+.P
The mapping section starts with the keyword
.I CHARIDS
in the first column.
-.PP
+.P
The mapping lines have the following form:
.TP
.I <symbolic-name> <code-point> comment
This defines exactly one mapping,
.I comment
being optional.
-.PP
+.P
The mapping section ends with the string
.IR "END CHARIDS" .
.SH FILES
Repertoire maps are deprecated in favor of Unicode code points.
.SH EXAMPLES
A mnemonic for the Euro sign can be defined as follows:
-.PP
+.P
.nf
<Eu> <U20AC> EURO SIGN
.fi
see the
.B trust-ad
option below for details.
-.PP
+.P
If this file does not exist, only the name server on the local machine
will be queried, and the search list contains the local domain name
determined from the hostname.
-.PP
+.P
The different configuration options are:
.TP
\fBnameserver\fP Name server IP address
.RS
.IP
\fBoptions\fP \fIoption\fP \fI...\fP
-.PP
+.P
where \fIoption\fP is one of the following:
.TP
\fBdebug\fP
the AD is not set automatically in queries,
and is passed through unchanged to applications in responses.
.RE
-.PP
+.P
The \fIsearch\fP keyword of a system's \fIresolv.conf\fP file can be
overridden on a per-process basis by setting the environment variable
.B LOCALDOMAIN
to a space-separated list of search domains.
-.PP
+.P
The \fIoptions\fP keyword of a system's \fIresolv.conf\fP file can be
amended on a per-process basis by setting the environment variable
.B RES_OPTIONS
to a space-separated list of resolver options
as explained above under \fBoptions\fP.
-.PP
+.P
The keyword and value must appear on a single line, and the keyword
(e.g., \fBnameserver\fP) must start the line.
The value follows the keyword, separated by white space.
-.PP
+.P
Lines that contain a semicolon (;) or hash character (#)
in the first column are treated as comments.
.SH FILES
.BR nsswitch.conf (5),
.BR hostname (7),
.BR named (8)
-.PP
+.P
Name Server Operations Guide for BIND
file contains user readable names that
can be used in place of RPC program numbers.
Each line has the following information:
-.PP
+.P
.PD 0
.IP \[bu] 3
name of server for the RPC program
.IP \[bu]
aliases
.PD
-.PP
+.P
Items are separated by any number of blanks and/or
tab characters.
A \[aq]#\[aq] indicates the beginning of a comment; characters from
the \[aq]#\[aq] to the end of the line are not interpreted by routines
which search the file.
-.PP
+.P
Here is an example of the
.I /etc/rpc
file from the Sun RPC Source distribution.
-.PP
+.P
.in +4n
.EX
#
.IR /dev/ )
which are considered secure for the transmission of certain authentication
tokens.
-.PP
+.P
It is used by (some versions of)
.BR login (1)
to restrict the terminals
See
.BR login.defs (5)
if you use the shadow suite.
-.PP
+.P
On PAM enabled systems, it is used for the same purpose by
.BR pam_securetty (8)
to restrict the terminals on which empty passwords are accepted.
and
.BR endservent (3)
support querying this file from programs.
-.PP
+.P
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.
-.PP
+.P
Port numbers below 1024 (so-called "low numbered" ports) can be
bound to only by root (see
.BR bind (2),
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.
-.PP
+.P
The presence of an entry for a service in the
.B services
file does not necessarily mean that the service is currently running
.BR inetd.conf (5).
In particular, news (NNTP) and mail (SMTP) servers are often
initialized from the system boot scripts.
-.PP
+.P
The location of the
.B services
file is defined by
.IR <netdb.h> "."
This is usually set to
.IR /etc/services "."
-.PP
+.P
Each line describes one service, and is of the form:
.IP
\f2service-name\ \ \ port\f3/\f2protocol\ \ \ \f1[\f2aliases ...\f1]
service.
Again, the names are case
sensitive.
-.PP
+.P
Either spaces or tabs may be used to separate the fields.
-.PP
+.P
Comments are started by the hash sign (#) and continue until the end
of the line.
Blank lines are skipped.
-.PP
+.P
The
.I service-name
should begin in the first column of the file, since leading spaces are
compatibility problems.
For example, a\-z, 0\-9, and hyphen (\-) would seem a
sensible choice.
-.PP
+.P
Lines not matching this format should not be present in the
file.
(Currently, they are silently skipped by
and
.BR getservbyport (3).
However, this behavior should not be relied on.)
-.PP
+.P
.\" The following is not true as at glibc 2.8 (a line with a comma is
.\" ignored by getservent()); it's not clear if/when it was ever true.
.\" As a backward compatibility feature, the slash (/) between the
.\"
This file might be distributed over a network using a network-wide
naming service like Yellow Pages/NIS or BIND/Hesiod.
-.PP
+.P
A sample
.B services
file might look like this:
-.PP
+.P
.in +4n
.EX
netstat 15/tcp
.BR inetd.conf (5),
.BR protocols (5),
.BR inetd (8)
-.PP
+.P
Assigned Numbers RFC, most recently RFC\ 1700, (AKA STD0002).
This file is consulted by
.BR chsh (1)
and available to be queried by other programs.
-.PP
+.P
Be aware that there are programs which consult this file to
find out if a user is a normal user;
for example,
.SH EXAMPLES
.I /etc/shells
may contain the following paths:
-.PP
+.P
.in +4n
.EX
.I /bin/sh
gives statistics on these caches.
The following (edited) output shows an example of the
contents of this file:
-.PP
+.P
.EX
$ \fBsudo cat /proc/slabinfo\fP
slabinfo \- version: 2.1
kmalloc\-8192 96 96 8192 4 8 : tunables 0 0 0 : slabdata 24 24 0
\&...
.EE
-.PP
+.P
The first line of output includes a version number,
which allows an application that is reading the file to handle changes
in the file format.
(See VERSIONS, below.)
The next line lists the names of the columns in the remaining lines.
-.PP
+.P
Each of the remaining lines displays information about a specified cache.
Following the cache name,
the output shown in each line shows three components for each cache:
tunables
.IP \[bu]
slabdata
-.PP
+.P
The statistics are as follows:
.TP
.I active_objs
.TP
.I pagesperslab
The number of pages allocated for each slab.
-.PP
+.P
The
.I tunables
entries in each line show tunable parameters for the corresponding cache.
the tunables for a particular cache can be set by writing
lines of the following form to
.IR /proc/slabinfo :
-.PP
+.P
.in +4n
.EX
# \fBecho \[aq]name limit batchcount sharedfactor\[aq] > /proc/slabinfo\fP
.EE
.in
-.PP
+.P
Here,
.I name
is the cache name, and
should be nonnegative.
If any of the specified values is invalid,
the cache settings are left unchanged.
-.PP
+.P
The
.I tunables
entries in each line contain the following fields:
.I sharedfactor
[To be documented]
.\"
-.PP
+.P
The
.I slabdata
entries in each line contain the following fields:
.TP
.I sharedavail
[To be documented]
-.PP
+.P
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.
-.PP
+.P
Kernels configured with
.B CONFIG_DEBUG_SLAB
will also have additional statistics fields in each line,
write the
.I /proc/slabinfo
file.
-.PP
+.P
The total amount of memory allocated to the SLAB/SLUB cache is shown in the
.I Slab
field of
.IR /proc/meminfo .
.SH SEE ALSO
.BR slabtop (1)
-.PP
+.P
The kernel source file
.I Documentation/vm/slub.txt
and
.B sysfs
provide information about devices, kernel modules, filesystems,
and other kernel components.
-.PP
+.P
The
.B sysfs
filesystem is commonly mounted at
.IR /sys .
Typically, it is mounted automatically by the system,
but it can also be mounted manually using a command such as:
-.PP
+.P
.in +4n
.EX
mount \-t sysfs sysfs /sys
.EE
.in
-.PP
+.P
Many of the files in the
.B sysfs
filesystem are read-only,
.SH SEE ALSO
.BR proc (5),
.BR udev (7)
-.PP
+.P
P.\& Mochel. (2005).
.IR "The sysfs filesystem" .
Proceedings of the 2005 Ottawa Linux Symposium.
.\" https://www.kernel.org/pub/linux/kernel/people/mochel/doc/papers/ols-2005/mochel.pdf
-.PP
+.P
The kernel source file
.I Documentation/filesystems/sysfs.txt
and various other files in
new programs should use the
.BR terminfo (5)
database and associated libraries.
-.PP
+.P
.I /etc/termcap
is an ASCII file (the database master) that lists the capabilities of
many different types of terminals.
The termcap database is indexed on the
.B TERM
environment variable.
-.PP
+.P
Termcap entries must be defined on a single logical line, with \[aq]\e\[aq]
used to suppress the newline.
Fields are separated by \[aq]:\[aq].
The first field of each entry starts at the left-hand margin,
and contains a list of names for the terminal, separated by \[aq]|\[aq].
-.PP
+.P
The first subfield may (in BSD termcap entries from 4.3BSD and
earlier) 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.
-.PP
+.P
The second subfield (first, in the newer 4.4BSD format) contains the
name used by the environment variable
.BR TERM .
display).
The third subfield contains a long and descriptive name for
this termcap entry.
-.PP
+.P
Subsequent fields contain the terminal capabilities; any continued
capability lines must be indented one tab from the left margin.
-.PP
+.P
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.
-.PP
+.P
Example for:
.nf
-.PP
+.P
Head line: vt|vt101|DEC VT 101 terminal in 80 character mode:\e
Head line: Vt|vt101-w|DEC VT 101 terminal in (wide) 132 character mode:\e
Boolean: :bs:\e
wi Set window from line %1 to %2 and column %3 to %4
XF XOFF character if not \fB\[ha]S\fP
.fi
-.PP
+.P
There are several ways of defining the control codes for string capabilities:
-.PP
+.P
Every normal character represents itself,
except \[aq]\[ha]\[aq], \[aq]\e\[aq], and \[aq]%\[aq].
-.PP
+.P
A \fB\[ha]x\fP means Control-x.
Control-A equals 1 decimal.
-.PP
+.P
\ex means a special code.
x can be one of the following characters:
.RS
.TP
%
Print a \[aq]%\[aq]
-.PP
+.P
If you use binary output,
then you should avoid the null character (\[aq]\e0\[aq])
because it terminates the string.
Warning:
The above metacharacters for parameters may be wrong: they document Minix
termcap which may not be compatible with Linux termcap.
-.PP
+.P
The block graphic characters can be specified by three string capabilities:
.TP
as
pairs of characters.
The first character is the name of the block graphic
symbol and the second characters is its definition.
-.PP
+.P
The following names are available:
-.PP
+.P
.nf
+ right arrow (>)
, left arrow (<)
x vertical line (|)
\[ti] paragraph (???)
.fi
-.PP
+.P
The values in parentheses are suggested defaults which are used by the
.I curses
library, if the capabilities are missing.
in virtual memory.
Since the files on such filesystems typically reside in RAM,
file access is extremely fast.
-.PP
+.P
The filesystem is automatically created when mounting
a filesystem with the type
.B tmpfs
via a command such as the following:
-.PP
+.P
.in +4n
.EX
$ sudo mount \-t tmpfs \-o size=10M tmpfs /mnt/mytmpfs
.EE
.in
-.PP
+.P
A
.B tmpfs
filesystem has the following properties:
.RI ( "mount\ \-o\ remount" ),
the filesystem size can be changed
(without losing the existing contents of the filesystem).
-.PP
+.P
If a
.B tmpfs
filesystem is unmounted, its contents are discarded (lost).
filesystems, the kernel must be configured with the
.B CONFIG_TMPFS
option.
-.PP
+.P
The
.B tmpfs
filesystem supports extended attributes (see
but
.I user
extended attributes are not permitted.
-.PP
+.P
An internal shared memory filesystem is used for
System V shared memory
.RB ( shmget (2))
the kernel was configured with the
.B CONFIG_TMPFS
option.
-.PP
+.P
A
.B tmpfs
filesystem mounted at
.RB ( shm_overview (7))
and POSIX semaphores
.RB ( sem_overview (7)).
-.PP
+.P
The amount of memory consumed by all
.B tmpfs
filesystems is shown in the
.I shared
field displayed by
.BR free (1).
-.PP
+.P
The
.B tmpfs
facility was formerly called
.BR set_mempolicy (2),
.BR shm_open (3),
.BR mount (8)
-.PP
+.P
The kernel source files
.I Documentation/filesystems/tmpfs.txt
and
whitespace, followed by a tty name (a device name without the
.I /dev/
prefix).
-.PP
+.P
This association is used by the program
.BR tset (1)
to set the environment variable
.B TERM
to the default terminal name for
the user's current tty.
-.PP
+.P
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.
A typical
.I /etc/ttytype
is:
-.PP
+.P
.in +4n
.EX
con80x25 tty1
The number of bytes of time zone abbreviation strings
stored in the file.
.RE
-.PP
+.P
The above header is followed by the following fields, whose lengths
depend on the contents of the header:
.IP * 2
were specified as UT or local time.
If a UT/local indicator is set, the corresponding standard/wall indicator
must also be set.
-.PP
+.P
The standard/wall and UT/local indicators were designed for
transforming a TZif file's transition times into transitions appropriate
for another time zone specified via a POSIX-style TZ string that lacks rules.
TZ="Europe/Athens" for better historical coverage, falling back on
TZ="EET\*-2EEST,M3.5.0/3,M10.5.0/4" if POSIX conformance is required
and older timestamps need not be handled accurately.
-.PP
+.P
The
.BR localtime (3)
function
the added leap seconds will change how post-expiration timestamps are treated.
.SS Interoperability considerations
Future changes to the format may append more data.
-.PP
+.P
Version 1 files are considered a legacy format and
should not be generated, as they do not support transition
times after the year 2038.
Readers that understand only Version 1 must ignore
any data that extends beyond the calculated end of the version
1 data block.
-.PP
+.P
Other than version 1, writers should generate
the lowest version number needed by a file's data.
For example, a writer should generate a version 4 file
should generate a version 3 file only if
TZ string extensions are necessary to accurately
model transition times.
-.PP
+.P
The sequence of time changes defined by the version 1
header and data block should be a contiguous sub-sequence
of the time changes defined by the version 2+ header and data
.B tzh_timecnt
of zero
in the version 1 data block to save space.
-.PP
+.P
When a TZif file contains a leap second table expiration
time, TZif readers should either refuse to process
post-expiration timestamps, or process them as if the expiration
time did not exist (possibly with an error indication).
-.PP
+.P
Time zone designations should consist of at least three (3)
and no more than six (6) ASCII characters from the set of
alphanumerics,
.q "+".
This is for compatibility with POSIX requirements for
time zone abbreviations.
-.PP
+.P
When reading a version 2 or higher file, readers
should ignore the version 1 header and data block except for
the purpose of skipping over them.
-.PP
+.P
Readers should calculate the total lengths of the
headers and data blocks and check that they all fit within
the actual file size, as part of a validity check for the file.
-.PP
+.P
When a positive leap second occurs, readers should append an extra
second to the local minute containing the second just before the leap
second. If this occurs when the UTC offset is not a multiple of 60
.IP *
to help any future specification authors see what sort of
problems arise when the TZif format is changed.
-.PP
+.P
When new versions of the TZif format have been defined, a
design goal has been that a reader can successfully use a TZif
file even if the file is of a later TZif version than what the
This section attempts to document these compatibility issues and
workarounds, as well as to document other common bugs in
readers.
-.PP
+.P
Interoperability problems with TZif include the following:
.IP * 2
Some readers examine only version 1 data.
This has not yet been a practical problem, since no civil authority
has observed such UTC offsets since leap seconds were
introduced in 1972.
-.PP
+.P
Some interoperability problems are reader bugs that
are listed here mostly as warnings to developers of readers.
.IP * 2
.BR tzselect (8),
.BR zdump (8),
.BR zic (8).
-.PP
+.P
Olson A, Eggert P, Murchison K. The Time Zone Information Format (TZif).
2019 Feb.
.UR https://\:datatracker.ietf.org/\:doc/\:html/\:rfc8536
system.
There may be more users currently using the system, because not
all programs use utmp logging.
-.PP
+.P
.B Warning:
.I utmp
must not be writable by the user class "other",
modifications of system files if you leave
.I utmp
writable to any user other than the owner and group owner of the file.
-.PP
+.P
The file is a sequence of
.I utmp
structures,
.I <utmp.h>
(note that this is only one of several definitions
around; details depend on the version of libc):
-.PP
+.P
.in +4n
.EX
/* Values for ut_type field, below */
#define ut_addr ut_addr_v6[0]
.EE
.in
-.PP
+.P
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
String fields are terminated by a null byte (\[aq]\e0\[aq])
if they are shorter than the size
of the field.
-.PP
+.P
The first entries ever created result from
.BR init (1)
processing
creates a new one.
It sets \fIut_id\fP from the inittab, \fIut_pid\fP and \fIut_time\fP to the
current values, and \fIut_type\fP to \fBINIT_PROCESS\fP.
-.PP
+.P
.BR mingetty (8)
(or
.BR agetty (8))
.BR login (1),
records may be located by
\fIut_line\fP instead of the preferable \fIut_pid\fP.
-.PP
+.P
When
.BR init (1)
finds that a process has exited, it locates its utmp entry by
and
.I ut_time
with null bytes.
-.PP
+.P
.BR xterm (1)
and other terminal emulators directly create a
\fBUSER_PROCESS\fP record and generate the \fIut_id\fP by using the
will mark it as \fBDEAD_PROCESS\fP on exiting and it is advised that
they null \fIut_line\fP, \fIut_time\fP, \fIut_user\fP, and \fIut_host\fP
as well.
-.PP
+.P
.BR telnetd (8)
sets up a \fBLOGIN_PROCESS\fP entry and leaves the rest to
.BR login (1)
After the telnet session ends,
.BR telnetd (8)
cleans up utmp in the described way.
-.PP
+.P
The \fIwtmp\fP file records all logins and logouts.
Its format is exactly like \fIutmp\fP except that a null username
indicates a logout
and
.I ut_user
fields.
-.PP
+.P
Linux defines the
.I utmpx
structure to be the same as the
.SH HISTORY
Linux utmp entries conform neither to v7/BSD nor to System V; they are a
mix of the two.
-.PP
+.P
v7/BSD has fewer fields; most importantly it lacks
\fIut_type\fP, 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 \fIut_id\fP fields.
-.PP
+.P
In Linux (as in System V), the \fIut_id\fP field of a
record will never change once it has been set, which reserves that slot
without needing a configuration file.
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.
-.PP
+.P
.\" mtk: What is the referrent of "them" in the following sentence?
.\" System V only uses the type field to mark them and logs
.\" informative messages such as \fB"new time"\fP in the line field.
If you want to disable
.BR who (1),
then do not make utmp world readable.
-.PP
+.P
The file format is machine-dependent, so it is recommended that it be
processed only on the machine architecture where it was created.
-.PP
+.P
Note that on \fIbiarch\fP platforms, that is, systems which can run both
32-bit and 64-bit applications (x86-64, ppc64, s390x, etc.),
\fIut_tv\fP is the same size in 32-bit mode as in 64-bit mode.
.IR tv_usec .
Since \fIut_tv\fP may not be the same as \fIstruct timeval\fP,
then instead of the call:
-.PP
+.P
.in +4n
.EX
gettimeofday((struct timeval *) &ut.ut_tv, NULL);
.EE
.in
-.PP
+.P
the following method of setting this field is recommended:
-.PP
+.P
.in +4n
.EX
struct utmp ut;
ut.ut_tv.tv_usec = tv.tv_usec;
.EE
.in
-.\" .PP
+.\" .P
.\" Note that the \fIutmp\fP struct from libc5 has changed in libc6.
.\" Because of this,
.\" binaries using the old libc5 struct will corrupt
.nf
.BR "#include <sys/types.h>" " /* See NOTES */"
.B #include <sys/socket.h>
-.PP
+.P
.BI "int socket(int " domain ", int " type ", int " protocol );
.fi
.SH DESCRIPTION
the I/O operation in a variety of ways:
by delivery of a signal, by instantiation of a thread,
or no notification at all.
-.PP
+.P
The POSIX AIO interface consists of the following functions:
.TP
.BR aio_read (3)
.TP
.BR lio_listio (3)
Enqueue multiple I/O requests using a single function call.
-.PP
+.P
The
.I 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:
-.PP
+.P
.in +4n
.EX
#include <aiocb.h>
enum { LIO_READ, LIO_WRITE, LIO_NOP };
.EE
.in
-.PP
+.P
The fields of this structure are as follows:
.TP
.I aio_fildes
.I aio_lio_opcode
The type of operation to be performed; used only for
.BR lio_listio (3).
-.PP
+.P
In addition to the standard functions listed above,
the GNU C library provides the following extension to the POSIX AIO API:
.TP
.I 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.
-.PP
+.P
Simultaneous asynchronous read or write operations using the same
.I aiocb
structure yield undefined results.
-.PP
+.P
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.
After all I/O requests have completed,
the program retrieves their status using
.BR aio_return (3).
-.PP
+.P
The
.B SIGQUIT
signal (generated by typing control-\e) causes the program to request
cancelation of each of the outstanding requests using
.BR aio_cancel (3).
-.PP
+.P
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".
-.PP
+.P
.in +4n
.EX
$ \fB./a.out /dev/stdin /dev/stdin\fP
.BR aio_return (3),
.BR aio_write (3),
.BR lio_listio (3)
-.PP
+.P
"Asynchronous I/O Support in Linux 2.5",
Bhattacharya, Pratt, Pulavarty, and Morgan,
Proceedings of the Linux Symposium, 2003,
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.
-.PP
+.P
A user process can receive ARP packets by using
.BR packet (7)
sockets.
on any
.B AF_INET
socket.
-.PP
+.P
The ARP module maintains a cache of mappings between hardware addresses
and protocol addresses.
The cache has a limited size so old and less
tuned by the
.I /proc
interfaces described below.
-.PP
+.P
When there is no positive feedback for an existing mapping after some
time (see the
.I /proc
request to the network.
Requests are sent only when there is data queued
for sending.
-.PP
+.P
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.
They take a pointer to a
.I struct arpreq
as their argument.
-.PP
+.P
.in +4n
.EX
struct arpreq {
};
.EE
.in
-.PP
+.P
.BR SIOCSARP ", " SIOCDARP " and " SIOCGARP
respectively set, delete, and get an ARP mapping.
Setting and deleting ARP maps are privileged operations and may
be performed only by a process with the
.B CAP_NET_ADMIN
capability or an effective UID of 0.
-.PP
+.P
.I arp_pa
must be an
.B AF_INET
ATF_DONTPUB:Don't answer
.TE
.RE
-.PP
+.P
If the
.B ATF_NETMASK
flag is set, then
.I arp_dev
member and the ioctl numbers changed at the same time.
Support for the old ioctls was dropped in Linux 2.2.
-.PP
+.P
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).
-.PP
+.P
The
.I neigh/*
interfaces did not exist before Linux 2.2.
Some timer settings are specified in jiffies, which is architecture-
and kernel version-dependent; see
.BR time (7).
-.PP
+.P
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).
-.PP
+.P
This man page mashes together functionality that is IPv4-specific
with functionality that is shared between IPv4 and IPv6.
.SH SEE ALSO
.BR capabilities (7),
.BR ip (7),
.BR arpd (8)
-.PP
+.P
RFC\ 826 for a description of ARP.
RFC\ 2461 for a description of IPv6 neighbor discovery and the base
algorithms used.
It is a 7-bit code.
Many 8-bit codes (e.g., ISO 8859-1) contain ASCII as their lower half.
The international counterpart of ASCII is known as ISO 646-IRV.
-.PP
+.P
The following table contains the 128 ASCII characters.
-.PP
+.P
C program \f(CW\[aq]\eX\[aq]\fP escapes are noted.
-.PP
+.P
.EX
.TS
l l l l | l l l l.
.EE
.SS Tables
For convenience, below are more compact tables in hex and decimal.
-.PP
+.P
.EX
2 3 4 5 6 7 30 40 50 60 70 80 90 100 110 120
------------- ---------------------------------
.SH NOTES
.SS History
/etc/ascii (VII) appears in the UNIX Programmer's Manual.
-.PP
+.P
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.
-.PP
+.P
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.
-.PP
+.P
The ASCII standard was published by the United States of America
Standards Institute (USASI) in 1968.
.\"
the "POSIX Safety Concepts" section of the GNU C Library manual.
Further details on the topics described here can be found in that
manual.
-.PP
+.P
Various function manual pages include a section ATTRIBUTES
that describes the safety of calling the function in various contexts.
This section annotates functions with the following safety markings:
.\" keyword from safety notes.
.\" As long as the keyword remains, however,
.\" they are not to be regarded as a promise of future behavior.
-.PP
+.P
Other keywords that appear in safety notes are defined in subsequent sections.
.\"
.\"
root user-space process (\fIinit\fR and \fIinittab\fR)
.IP (5)
boot scripts
-.PP
+.P
Each of these is described below in more detail.
.SS Hardware
After power-on or hard reset, control is given
to a program stored in read-only memory (normally
PROM); for historical reasons involving the personal
computer, this program is often called "the \fBBIOS\fR".
-.PP
+.P
This program normally performs a basic self-test of the
machine and accesses nonvolatile memory to read
further parameters.
refer to it as "the \fBCMOS\fR"; outside
of the PC world, it is usually called "the \fBNVRAM\fR"
(nonvolatile RAM).
-.PP
+.P
The parameters stored in the NVRAM vary among
systems, but as a minimum, they should specify
which device can supply an OS loader, or at least which
kernel (maybe a backup in case the one last compiled
isn't functioning) and to pass optional parameters
to the kernel.
-.PP
+.P
In a traditional PC, the OS loader is located in the initial 512-byte block
of the boot device; this block is known as "the \fBMBR\fR"
(Master Boot Record).
-.PP
+.P
In most systems, the OS loader is very
limited due to various constraints.
Even on non-PC systems,
of this loader, but the size limitation of the PC MBR
(512 bytes, including the partition table) makes it
almost impossible to squeeze much functionality into it.
-.PP
+.P
Therefore, most systems split the role of loading the OS between
a primary OS loader and a secondary OS loader; this secondary
OS loader may be located within a larger portion of persistent
storage, such as a disk partition.
-.PP
+.P
In Linux, the OS loader is often
.BR grub (8)
(an alternative is
swapper (it is a kernel process, called "kswapd" in a modern Linux
kernel), and mounts some filesystem at the root path,
.IR / .
-.PP
+.P
Some of the parameters that may be passed to the kernel
relate to these activities (for example, the default root filesystem
can be overridden); for further information
on Linux kernel parameters, read
.BR bootparam (7).
-.PP
+.P
Only then does the kernel create the initial userland
process, which is given the number 1 as its
.B PID
.BR systemd (1),
for which the bootup process is detailed in its associated
.BR bootup (7).
-.PP
+.P
When
.I /sbin/init
starts, it reads
and run level
.B 2
entails running most network services).
-.PP
+.P
The administrator may change the current run level via
.BR init (1),
and query the current run level via
.BR runlevel (8).
-.PP
+.P
However, since it is not convenient to manage individual services
by editing this file,
.I /etc/inittab
The following description applies to an OS based on UNIX System V Release 4.
However, a number of widely used systems (Slackware Linux, FreeBSD, OpenBSD)
have a somewhat different scheme for boot scripts.
-.PP
+.P
For each managed service (mail, nfs server, cron, etc.), there is
a single startup script located in a specific directory
.RI ( /etc/init.d
In each of these directories,
there are links (usually symbolic) to the scripts in the \fI/etc/init.d\fR
directory.
-.PP
+.P
A primary script (usually \fI/etc/rc\fR) is called from
.BR inittab (5);
this primary script calls each service's script via a link in the
the argument "start" (thereby starting the service).
Each link whose name begins with \[aq]K\[aq] is called with
the argument "stop" (thereby stopping the service).
-.PP
+.P
To define the starting or stopping order within the same run level,
the name of a link contains an \fBorder-number\fR.
Also, for clarity, the name of a link usually
run level 2.
This happens after \fI/etc/rc2.d/S12syslog\fR is run
but before \fI/etc/rc2.d/S90xfs\fR is run.
-.PP
+.P
To manage these links is to manage the boot order and run levels;
under many systems, there are tools to help with this task
(e.g.,
some separate configuration file is used, and is located in a specific
directory where an associated boot script may find it
(\fI/etc/sysconfig\fR on older Red Hat systems).
-.PP
+.P
In older UNIX systems, such a file contained the actual command line
options for a daemon, but in modern Linux systems (and also
in HP-UX), it just contains shell variables.
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.
-.PP
+.P
When the kernel is booted directly by the BIOS,
you have no opportunity to specify any parameters.
So, in order to take advantage of this possibility you have to
The kernel command line is parsed into a list of strings
(boot arguments) separated by spaces.
Most of the boot arguments have the form:
-.PP
+.P
.in +4n
.EX
name[=value_1][,value_2]...[,value_10]
.EE
.in
-.PP
+.P
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 handles only 10 comma
(However, you can reuse the same
keyword with up to an additional 10 parameters in unusually
complicated situations, assuming the setup function supports it.)
-.PP
+.P
Most of the sorting is coded in the kernel source file
.IR 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.
-.PP
+.P
Then it walks a list of setup functions
to see if the specified argument string (such as 'foo') has
been associated with a setup function ('foo_setup()') for a particular
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.
-.PP
+.P
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.
-.PP
+.P
Any remaining arguments that were not picked up by the kernel and were
not interpreted as environment variables are then passed onto PID 1,
which is usually the
.IR /dev/initrd .)
.SS Boot arguments for SCSI devices
General notation for this section:
-.PP
+.P
.I 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.
-.PP
+.P
.I irq
-- the hardware interrupt that the card is configured to use.
Valid values will be dependent on the card in question, but will
The other values are usually
used for common peripherals like IDE hard disks, floppies, serial
ports, and so on.
-.PP
+.P
.I scsi\-id
-- the ID that the host adapter uses to identify itself on the
SCSI bus.
most have it permanently specified internally.
The usual default value
is 7, but the Seagate and Future Domain TMC-950 boards use 6.
-.PP
+.P
.I parity
-- whether the SCSI host adapter expects the attached devices
to supply a parity value with all information exchanges.
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:
-.PP
+.P
.in +4n
.EX
ether=irq,iobase[,param_1[,...param_8]],name
.EE
.in
-.PP
+.P
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.
-.PP
+.P
The most common use of this parameter is to force probing for a second
ethercard, as the default is to probe only for one.
This can be accomplished with a simple:
-.PP
+.P
.in +4n
.EX
ether=0,0,eth1
.EE
.in
-.PP
+.P
Note that the values of zero for the IRQ and I/O base in the above
example tell the driver(s) to autoprobe.
-.PP
+.P
The Ethernet-HowTo has extensive documentation on using multiple
cards and on the card/driver-specific implementation
of the param_n values where used.
in older kernel versions).
It accepts
a boot argument of the form:
-.PP
+.P
.in +4n
.EX
sound=device1[,device2[,device3...[,device10]]]
.EE
.in
-.PP
+.P
where each deviceN value is of the following format 0xTaaaId and the
bytes are used as follows:
-.PP
+.P
T \- device type: 1=FM, 2=SB, 3=PAS, 4=GUS, 5=MPU401, 6=SB16,
7=SB16-MPU401
-.PP
+.P
aaa \- I/O address in hex.
-.PP
+.P
I \- interrupt line in hex (i.e., 10=a, 11=b, ...)
-.PP
+.P
d \- DMA channel.
-.PP
+.P
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 argument of
.SH SEE ALSO
.BR klogd (8),
.BR mount (8)
-.PP
+.P
For up-to-date information, see the kernel source file
.IR Documentation/admin\-guide/kernel\-parameters.txt .
while unprivileged processes are subject to full permission
checking based on the process's credentials
(usually: effective UID, effective GID, and supplementary group list).
-.PP
+.P
Starting with Linux 2.2, Linux divides the privileges traditionally
associated with superuser into distinct units, known as
.IR capabilities ,
.IP \[bu]
The filesystem must support attaching capabilities to an executable file,
so that a process gains those capabilities when the file is executed.
-.PP
+.P
Before Linux 2.6.24, only the first two of these requirements are met;
since Linux 2.6.24, all three requirements are met.
.\"
.BR execve (2),
this does not trigger the secure-execution mode described in
.BR ld.so (8).
-.PP
+.P
A child created via
.BR fork (2)
inherits copies of its parent's capability sets.
affects capabilities, see
.I Transformation of capabilities during execve()
below.
-.PP
+.P
Using
.BR capset (2),
a thread may manipulate its own capability sets; see
.I Programmatically adjusting capability sets
below.
-.PP
+.P
Since Linux 3.2, the file
.I /proc/sys/kernel/cap_last_cap
.\" commit 73efc0394e148d0e15583e13712637831f926720
in conjunction with the capability sets of the thread,
determine the capabilities of a thread after an
.BR execve (2).
-.PP
+.P
The three file capability sets are:
.TP
.IR Permitted " (formerly known as " forced ):
that is, on a modern Linux system,
there may be some files with version 2 capabilities
while others have version 3 capabilities.
-.PP
+.P
Before Linux 4.14,
the only kind of file capability extended attribute
that could be attached to a file was a
.I security.capability
extended attribute that is attached to a file
depends on the circumstances in which the attribute was created.
-.PP
+.P
Starting with Linux 4.14, a
.I security.capability
extended attribute is automatically created as (or converted to)
capability in its own user namespace;
and (b) the UID and GID of the file inode have mappings in
the writer's user namespace.
-.PP
+.P
When a
.B VFS_CAP_REVISION_3
.I security.capability
extended attribute is created, the root user ID of the creating thread's
user namespace is saved in the extended attribute.
-.PP
+.P
By contrast, creating or modifying a
.I security.capability
extended attribute from a privileged
automatically results in the creation of a version 2
.RB ( VFS_CAP_REVISION_2 )
attribute.
-.PP
+.P
Note that the creation of a version 3
.I security.capability
extended attribute is automatic.
in order for those tools to be used to create and retrieve version 3
.I security.capability
attributes.
-.PP
+.P
Note that a file can have either a version 2 or a version 3
.I security.capability
extended attribute associated with it, but not both:
.BR execve (2),
the kernel calculates the new capabilities of
the process using the following algorithm:
-.PP
+.P
.in +4n
.EX
P'(ambient) = (file is privileged) ? 0 : P(ambient)
P'(bounding) = P(bounding) [i.e., unchanged]
.EE
.in
-.PP
+.P
where:
.RS 4
.TP
F()
denotes a file capability set
.RE
-.PP
+.P
Note the following details relating to the above capability
transformation rules:
.IP \[bu] 3
.BR execve (2)
in the same manner as shown above for
.IR P(bounding) .
-.PP
+.P
.IR Note :
during the capability transitions described above,
file capabilities may be ignored (treated as empty) for the same reasons
File capabilities are similarly ignored if the kernel was booted with the
.I no_file_caps
option.
-.PP
+.P
.IR Note :
according to the rules above,
if a process with nonzero user IDs performs an
enabled in the process effective set when executing the file.
The kernel recognizes a file which has the effective capability bit set
as capability-dumb for the purpose of the check described here.
-.PP
+.P
When executing a capability-dumb binary,
the kernel checks if the process obtained all permitted capabilities
that were specified in the file permitted set,
the kernel performs special treatment of file capabilities when
a process with UID 0 (root) executes a program and
when a set-user-ID-root program is executed.
-.PP
+.P
After having performed any changes to the process effective ID that
were triggered by the set-user-ID mode bit of the binary\[em]e.g.,
switching the effective user ID to 0 (root) because
If the effective user ID of the process is 0 (root) or
the file effective bit is in fact enabled,
then the file effective bit is notionally defined to be one (enabled).
-.PP
+.P
These notional values for the file's capability sets are then used
as described above to calculate the transformation of the process's
capabilities during
.BR execve (2).
-.PP
+.P
Thus, when a process with nonzero UIDs
.BR execve (2)s
a set-user-ID-root program that does not have capabilities attached,
.BR execve (2)s
a program, the calculation of the process's new
permitted capabilities simplifies to:
-.PP
+.P
.in +4n
.EX
P'(permitted) = P(inheritable) | P(bounding)
P'(effective) = P'(permitted)
.EE
.in
-.PP
+.P
Consequently, the process gains all capabilities in its permitted and
effective capability sets,
except those masked out by the capability bounding set.
(In the calculation of P'(permitted),
the P'(ambient) term can be simplified away because it is by
definition a proper subset of P(inheritable).)
-.PP
+.P
The special treatments of user ID 0 (root) described in this subsection
can be disabled using the securebits mechanism described below.
.\"
(i.e., not all capabilities,
as would occur when executing a set-user-ID-root program
that does not have any associated file capabilities).
-.PP
+.P
Note that one can assign empty capability sets to a program file,
and thus it is possible to create a set-user-ID-root program that
changes the effective and saved set-user-ID of the process
permitted set when it
.BR execve (2)s
a file that has the capability in its inheritable set.
-.PP
+.P
Note that the bounding set masks the file permitted capabilities,
but not the inheritable capabilities.
If a thread maintains a capability in its inheritable 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 inheritable set.
-.PP
+.P
Depending on the kernel version, the capability bounding set is either
a system-wide attribute, or a per-process attribute.
-.PP
+.P
.B "Capability bounding set from Linux 2.6.25 onward"
-.PP
+.P
From Linux 2.6.25, the
.I "capability bounding set"
is a per-thread attribute.
(The system-wide capability bounding set described below no longer exists.)
-.PP
+.P
The bounding set is inherited at
.BR fork (2)
from the thread's parent, and is preserved across an
.BR execve (2).
-.PP
+.P
A thread may remove capabilities from its capability bounding set using the
.BR prctl (2)
.B PR_CAPBSET_DROP
.BR prctl (2)
.B PR_CAPBSET_READ
operation.
-.PP
+.P
Removing capabilities from the bounding set is supported only if file
capabilities are compiled into the kernel.
Before Linux 2.6.33,
.BR CAP_SETPCAP ,
because this capability has a different meaning when there are
no file capabilities.
-.PP
+.P
Removing a capability from the bounding set does not remove it
from the thread's inheritable set.
However it does prevent the capability from being added
back into the thread's inheritable set in the future.
-.PP
+.P
.B "Capability bounding set prior to Linux 2.6.25"
-.PP
+.P
Before Linux 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
(Confusingly, this bit mask parameter is expressed as a
signed decimal number in
.IR /proc/sys/kernel/cap\-bound .)
-.PP
+.P
Only the
.B init
process may set capabilities in the capability bounding set;
other than that, the superuser (more precisely: a process with the
.B CAP_SYS_MODULE
capability) may only clear capabilities from this set.
-.PP
+.P
On a standard system the capability bounding set always masks out the
.B CAP_SETPCAP
capability.
in
.I include/linux/capability.h
and rebuild the kernel.
-.PP
+.P
The system-wide capability bounding set feature was added
to Linux 2.2.11.
.\"
If the filesystem 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.
-.PP
+.P
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
.BR prctl (2)
.B PR_CAP_AMBIENT_RAISE
operation.
-.PP
+.P
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
.BR SECBIT_NOROOT_LOCKED ,
and
.BR SECBIT_NO_CAP_AMBIENT_RAISE_LOCKED .
-.PP
+.P
The
.I securebits
flags can be modified and retrieved using the
constants are available only after including the
.I <linux/securebits.h>
header file.
-.PP
+.P
The
.I securebits
flags are inherited by child processes.
all of the flags are preserved, except
.B SECBIT_KEEP_CAPS
which is always cleared.
-.PP
+.P
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:
-.PP
+.P
.in +4n
.EX
prctl(PR_SET_SECUREBITS,
in the process's permitted and effective sets
when executed by any process inside that namespace
or any descendant user namespace.
-.PP
+.P
The rules about the transformation of the process's capabilities during the
.BR execve (2)
are exactly as described in
as per the rules described in
.I Transformation of capabilities during execve()
above.
-.PP
+.P
Because version 2 file capabilities confer capabilities to
the executing process regardless of which user namespace it resides in,
only privileged processes are permitted to associate capabilities with a file.
it can be desirable to be able to create a binary that
confers capabilities only to processes executed inside that container,
but not to processes that are executed outside the container.
-.PP
+.P
Linux 4.14 added so-called namespaced file capabilities
to support such use cases.
Namespaced file capabilities are recorded as version 3 (i.e.,
extended attribute is created,
the kernel records not just the capability masks in the extended attribute,
but also the namespace root user ID.
-.PP
+.P
As with a binary that has
.B VFS_CAP_REVISION_2
file capabilities, a binary with
.I \-u <username>
option useful.
Something like:
-.PP
+.P
.in +4n
.EX
$ \fBsudo strace \-o trace.log \-u ceci ./myprivprog\fP
.EE
.in
-.PP
+.P
From Linux 2.5.27 to Linux 2.6.26,
.\" commit 5915eb53861c5776cfec33ca4fcc1fd20d66dd27 removed
.\" CONFIG_SECURITY_CAPABILITIES
and could be enabled/disabled via the
.B CONFIG_SECURITY_CAPABILITIES
kernel configuration option.
-.PP
+.P
The
.IR /proc/ pid /task/TID/status
file can be used to view the capability sets of a thread.
all nonexistent capabilities (above
.BR CAP_LAST_CAP )
are shown as disabled (0).
-.PP
+.P
The
.I libcap
package provides a suite of routines for setting and
.br
.UR https://git.kernel.org\:/pub\:/scm\:/libs\:/libcap\:/libcap.git\:/refs/
.UE .
-.PP
+.P
Before Linux 2.6.24, and from Linux 2.6.24 to Linux 2.6.32 if
file capabilities are not enabled, a thread with the
.B CAP_SETPCAP
.BR netcap (8), \" from libcap-ng
.BR pscap (8), \" from libcap-ng
.BR setcap (8)
-.PP
+.P
.I include/linux/capability.h
in the Linux kernel source tree
.SH DESCRIPTION
For an overview of namespaces, see
.BR namespaces (7).
-.PP
+.P
Cgroup namespaces virtualize the view of a process's cgroups (see
.BR cgroups (7))
as seen via
.IR /proc/ pid /cgroup
and
.IR /proc/ pid /mountinfo .
-.PP
+.P
Each cgroup namespace has its own set of cgroup root directories.
These root directories are the base points for the relative
locations displayed in the corresponding records in the
of the new namespace.
(This applies both for the cgroups version 1 hierarchies
and the cgroups version 2 unified hierarchy.)
-.PP
+.P
When reading the cgroup memberships of a "target" process from
.IR /proc/ pid /cgroup ,
the pathname shown in the third field of each record will be
then the pathname will show
.I ../
entries for each ancestor level in the cgroup hierarchy.
-.PP
+.P
The following shell session demonstrates the effect of creating
a new cgroup namespace.
-.PP
+.P
First, (as superuser) in a shell in the initial cgroup namespace,
we create a child cgroup in the
.I freezer
hierarchy, and place a process in that cgroup that we will
use as part of the demonstration below:
-.PP
+.P
.in +4n
.EX
# \fBmkdir \-p /sys/fs/cgroup/freezer/sub2\fP
# \fBecho 20124 > /sys/fs/cgroup/freezer/sub2/cgroup.procs\fP
.EE
.in
-.PP
+.P
We then create another child cgroup in the
.I freezer
hierarchy and put the shell into that cgroup:
-.PP
+.P
.in +4n
.EX
# \fBmkdir \-p /sys/fs/cgroup/freezer/sub\fP
7:freezer:/sub
.EE
.in
-.PP
+.P
Next, we use
.BR unshare (1)
to create a process running a new shell in new cgroup and mount namespaces:
-.PP
+.P
.in +4n
.EX
# \fBPS1="sh2# " unshare \-Cm bash\fP
.EE
.in
-.PP
+.P
From the new shell started by
.BR unshare (1),
we then inspect the
.RI ( init ,
with PID 1), and the process in the sibling cgroup
.RI ( sub2 ):
-.PP
+.P
.in +4n
.EX
sh2# \fBcat /proc/self/cgroup | grep freezer\fP
7:freezer:/../sub2
.EE
.in
-.PP
+.P
From the output of the first command,
we see that the freezer cgroup membership of the new shell
(which is in the same cgroup as the initial shell)
in the new cgroup namespace is also
.IR /sub .
Thus, the new shell's cgroup membership is displayed as \[aq]/\[aq].)
-.PP
+.P
However, when we look in
.I /proc/self/mountinfo
we see the following anomaly:
-.PP
+.P
.in +4n
.EX
sh2# \fBcat /proc/self/mountinfo | grep freezer\fP
155 145 0:32 /.. /sys/fs/cgroup/freezer ...
.EE
.in
-.PP
+.P
The fourth field of this line
.RI ( /.. )
should show the
To fix this problem, we must remount the freezer cgroup filesystem
from the new shell (i.e., perform the mount from a process that is in the
new cgroup namespace), after which we see the expected results:
-.PP
+.P
.in +4n
.EX
sh2# \fBmount \-\-make\-rslave /\fP # Don\[aq]t propagate mount events
Use of cgroup namespaces requires a kernel that is configured with the
.B CONFIG_CGROUPS
option.
-.PP
+.P
The virtualization provided by cgroup namespaces serves a number of purposes:
.IP \[bu] 3
It prevents information leaks whereby cgroup directory paths outside of
.I cgroup
is a collection of processes that are bound to a set of
limits or parameters defined via the cgroup filesystem.
-.PP
+.P
A
.I subsystem
is a kernel component that modifies the behavior of
Subsystems are sometimes also known as
.I resource controllers
(or simply, controllers).
-.PP
+.P
The cgroups for a controller are arranged in a
.IR hierarchy .
This hierarchy is defined by creating, removing, and
(or
.I Documentation/cgroup\-v2.txt
in Linux 4.17 and earlier).
-.PP
+.P
Because of the problems with the initial cgroups implementation
(cgroups version 1),
starting in Linux 3.10, work began on a new,
.IR cgroup.sane_behavior ,
present in cgroups v1, is a relic of this mount option.
The file always reports "0" and is only retained for backward compatibility.
-.PP
+.P
Although cgroups v2 is intended as a replacement for cgroups v1,
the older system continues to exist
(and for compatibility reasons is unlikely to be removed).
It is also possible to comount multiple (or even all) cgroups v1 controllers
against the same cgroup filesystem, meaning that the comounted controllers
manage the same hierarchical organization of processes.
-.PP
+.P
For each mounted hierarchy,
the directory tree mirrors the control group hierarchy.
Each control group is represented by a directory, with each of its child
and called such in the remainder of this man page).
In cgroups v1, it is possible to independently manipulate
the cgroup memberships of the threads in a process.
-.PP
+.P
The cgroups v1 ability to split threads across different cgroups
caused problems in some cases.
For example, it made no sense for the
option.
In addition, each of the v1 controllers has an associated
configuration option that must be set in order to employ that controller.
-.PP
+.P
In order to use a v1 controller,
it must be mounted against a cgroup filesystem.
The usual place for such mounts is under a
Thus, one might mount the
.I cpu
controller as follows:
-.PP
+.P
.in +4n
.EX
mount \-t cgroup \-o cpu none /sys/fs/cgroup/cpu
.EE
.in
-.PP
+.P
It is possible to comount multiple controllers against the same hierarchy.
For example, here the
.I cpu
and
.I cpuacct
controllers are comounted against a single hierarchy:
-.PP
+.P
.in +4n
.EX
mount \-t cgroup \-o cpu,cpuacct none /sys/fs/cgroup/cpu,cpuacct
.EE
.in
-.PP
+.P
Comounting controllers has the effect that a process is in the same cgroup for
all of the comounted controllers.
Separately mounting controllers allows a process to
for one controller while being in
.I /foo2/foo3
for another.
-.PP
+.P
It is possible to comount all v1 controllers against the same hierarchy:
-.PP
+.P
.in +4n
.EX
mount \-t cgroup \-o all cgroup /sys/fs/cgroup
.EE
.in
-.PP
+.P
(One can achieve the same result by omitting
.IR "\-o all" ,
since it is the default if no controllers are explicitly specified.)
-.PP
+.P
It is not possible to mount the same controller
against multiple cgroup hierarchies.
For example, it is not possible to mount both the
the same set of comounted controllers.
However, in this case all that results is multiple mount points
providing a view of the same hierarchy.
-.PP
+.P
Note that on many systems, the v1 controllers are automatically mounted under
.IR /sys/fs/cgroup ;
in particular,
A mounted cgroup filesystem can be unmounted using the
.BR umount (8)
command, as in the following example:
-.PP
+.P
.in +4n
.EX
umount /sys/fs/cgroup/pids
.EE
.in
-.PP
+.P
.IR "But note well" :
a cgroup filesystem is unmounted only if it is not busy,
that is, it has no child cgroups.
A cgroup filesystem initially contains a single root cgroup, '/',
which all processes belong to.
A new cgroup is created by creating a directory in the cgroup filesystem:
-.PP
+.P
.in +4n
.EX
mkdir /sys/fs/cgroup/cpu/cg1
.EE
.in
-.PP
+.P
This creates a new empty cgroup.
-.PP
+.P
A process may be moved to this cgroup by writing its PID into the cgroup's
.I cgroup.procs
file:
-.PP
+.P
.in +4n
.EX
echo $$ > /sys/fs/cgroup/cpu/cg1/cgroup.procs
.EE
.in
-.PP
+.P
Only one PID at a time should be written to this file.
-.PP
+.P
Writing the value 0 to a
.I cgroup.procs
file causes the writing process to be moved to the corresponding cgroup.
-.PP
+.P
When writing a PID into the
.IR cgroup.procs ,
all threads in the process are moved into the new cgroup at once.
-.PP
+.P
Within a hierarchy, a process can be a member of exactly one cgroup.
Writing a process's PID to a
.I cgroup.procs
file automatically removes it from the cgroup of
which it was previously a member.
-.PP
+.P
The
.I cgroup.procs
file can be read to obtain a list of the processes that are
The returned list of PIDs is not guaranteed to be in order.
Nor is it guaranteed to be free of duplicates.
(For example, a PID may be recycled while reading from the list.)
-.PP
+.P
In cgroups v1, an individual thread can be moved to
another cgroup by writing its thread ID
(i.e., the kernel thread ID returned by
notifications when a cgroup becomes empty.
A cgroup is considered to be empty when it contains no child
cgroups and no member processes.
-.PP
+.P
A special file in the root directory of each cgroup hierarchy,
.IR release_agent ,
can be used to register the pathname of a program that may be invoked when
.I release_agent
program might remove the cgroup directory,
or perhaps repopulate it with a process.
-.PP
+.P
The default value of the
.I release_agent
file is empty, meaning that no release agent is invoked.
-.PP
+.P
The content of the
.I release_agent
file can also be specified via a mount option when the
cgroup filesystem is mounted:
-.PP
+.P
.in +4n
.EX
mount \-o release_agent=pathname ...
.EE
.in
-.PP
+.P
Whether or not the
.I release_agent
program is invoked when a particular cgroup becomes empty is determined
.SS Cgroup v1 named hierarchies
In cgroups v1,
it is possible to mount a cgroup hierarchy that has no attached controllers:
-.PP
+.P
.in +4n
.EX
mount \-t cgroup \-o none,name=somename none /some/mount/point
.EE
.in
-.PP
+.P
Multiple instances of such hierarchies can be mounted;
each hierarchy must have a unique name.
The only purpose of such hierarchies is to track processes.
cgroup hierarchy that is used by
.BR systemd (1)
to track services and user sessions.
-.PP
+.P
Since Linux 5.0, the
.I cgroup_no_v1
kernel boot option (described below) can be used to disable cgroup v1
mounted under the v1 and v2 hierarchies,
it is not possible to mount the same controller simultaneously
under both the v1 and the v2 hierarchies.
-.PP
+.P
The new behaviors in cgroups v2 are summarized here,
and in some cases elaborated in the following subsections.
.IP \[bu] 3
An improved mechanism for notification of empty cgroups is provided by the
.I cgroup.events
file.
-.PP
+.P
For more changes, see the
.I Documentation/admin\-guide/cgroup\-v2.rst
file in the kernel source
.I Documentation/cgroup\-v2.txt
in Linux 4.17 and earlier).
.
-.PP
+.P
Some of the new behaviors listed above saw subsequent modification with
the addition in Linux 4.14 of "thread mode" (described below).
.\"
The available controllers are automatically mounted,
meaning that it is not necessary (or possible) to specify the controllers
when mounting the cgroup v2 filesystem using a command such as the following:
-.PP
+.P
.in +4n
.EX
mount \-t cgroup2 none /mnt/cgroup2
.EE
.in
-.PP
+.P
A cgroup v2 controller is available only if it is not currently in use
via a mount against a cgroup v1 hierarchy.
Or, to put things another way, it is not possible to employ
(This situation is correctly handled by
.BR systemd (1),
which falls back to operating without the specified controllers.)
-.PP
+.P
Note that on many modern systems,
.BR systemd (1)
automatically mounts the
This is the same as the version 1
.I rdma
controller.
-.PP
+.P
There is no direct equivalent of the
.I net_cls
and
.BR iptables (8)
to allow eBPF filters that hook on cgroup v2 pathnames to make decisions
about network traffic on a per-cgroup basis.
-.PP
+.P
The v2
.I devices
controller provides no interface files;
error when writing to the
.I cgroup.subtree_control
file.
-.PP
+.P
Because the list of controllers in
.I cgroup.subtree_control
is a subset of those
.IR cgroup.controllers ,
a controller that has been disabled in one cgroup in the hierarchy
can never be re-enabled in the subtree below that cgroup.
-.PP
+.P
A cgroup's
.I cgroup.subtree_control
file determines the set of controllers that are exercised in the
only in leaf nodes (cgroups that do not themselves contain child cgroups).
This avoids the need to decide how to partition resources between
processes which are members of cgroup A and processes in child cgroups of A.
-.PP
+.P
For instance, if cgroup
.I /cg1/cg2
exists, then a process may reside in
and
.IR /cg1 's
other children.
-.PP
+.P
The "no internal processes" rule is in fact more subtle than stated above.
More precisely, the rule is that a (nonroot) cgroup can't both
(1) have member processes, and
but before controllers can be enabled for that cgroup,
the member processes must be moved out of the cgroup
(e.g., perhaps into the child cgroups).
-.PP
+.P
With the Linux 4.14 addition of "thread mode" (described below),
the "no internal processes" rule has been relaxed in some cases.
.\"
whose contents are key-value pairs
(delimited by newline characters, with the key and value separated by spaces)
providing state information about the cgroup:
-.PP
+.P
.in +4n
.EX
$ \fBcat mygrp/cgroup.events\fP
frozen 0
.EE
.in
-.PP
+.P
The following keys may appear in this file:
.TP
.I populated
.\" commit 76f969e8948d82e78e1bc4beb6b9465908e7487
The value of this key is 1 if this cgroup is currently frozen,
or 0 if it is not.
-.PP
+.P
The
.I cgroup.events
file can be monitored, in order to receive notification when the value of
contain no (nonzombie) member processes,
or 1, meaning that the cgroup (or one of its descendants)
contains member processes.
-.PP
+.P
The cgroups v2 release-notification mechanism
offers the following advantages over the cgroups v1
.I release_agent
Cgroups v2 supports delegation with containment by explicit design.
The focus of the discussion in this section is on delegation in cgroups v2,
with some differences for cgroups v1 noted along the way.
-.PP
+.P
Some terminology is required in order to describe delegation.
A
.I delegater
to manage some subhierarchy under that parent cgroup,
known as the
.IR "delegated subtree" .
-.PP
+.P
To perform delegation,
the delegater makes certain directories and files writable by the delegatee,
typically by changing the ownership of the objects to be the user ID
In cgroups v1, the corresponding file that should instead be delegated is the
.I tasks
file.
-.PP
+.P
The delegater should
.I not
change the ownership of any of the controller interfaces files (e.g.,
in order to distribute resources into the subtree,
and the delegatee should not have permission to change
the resources that are distributed into the delegated subtree.
-.PP
+.P
See also the discussion of the
.I /sys/kernel/cgroup/delegate
file in NOTES for information about further delegatable files in cgroups v2.
-.PP
+.P
After the aforementioned steps have been performed,
the delegatee can create child cgroups within the delegated subtree
(the cgroup subdirectories and the files they contain
we can remount it with the
.I nsdelegate
option as follows:
-.PP
+.P
.in +4n
.EX
mount \-t cgroup2 \-o remount,nsdelegate \e
.\"
.\" The effect of the latter option is to prevent systemd from employing
.\" its "hybrid" cgroup mode, where it tries to make use of cgroups v2.
-.PP
+.P
The effect of this mount option is to cause cgroup namespaces
to automatically become delegation boundaries.
More specifically,
move processes between cgroups
.I within
the subhierarchy under the namespace root.
-.PP
+.P
The ability to define cgroup namespaces as delegation boundaries
makes cgroup namespaces more useful.
To understand why, suppose that we already have one cgroup hierarchy
A process inside the inferior hierarchy could move processes
into and out of the inferior hierarchy if the cgroups in the
superior hierarchy were somehow visible.
-.PP
+.P
Employing the
.I nsdelegate
mount option prevents both of these possibilities.
-.PP
+.P
The
.I nsdelegate
mount option only has an effect when performed in
the initial mount namespace;
in other mount namespaces, the option is silently ignored.
-.PP
+.P
.IR Note :
On some systems,
.BR systemd (1)
.I nsdelegate
operation, it may be useful to boot the kernel with
the following command-line options:
-.PP
+.P
.in +4n
.EX
cgroup_no_v1=all systemd.legacy_systemd_cgroup_controller
.EE
.in
-.PP
+.P
These options cause the kernel to boot with the cgroups v1 controllers
disabled (meaning that the controllers are available in the v2 hierarchy),
and tells
(This was a historical requirement inherited from cgroups v1
that was later deemed unnecessary,
since the other rules suffice for containment in cgroups v2.)
-.PP
+.P
.IR Note :
one consequence of these delegation containment rules is that the
unprivileged delegatee can't place the first process into
.IR "No internal processes" :
a cgroup can't both have member processes and
exercise controllers on child cgroups.
-.PP
+.P
Both of these restrictions were added because
the lack of these restrictions had caused problems
in cgroups v1.
it made no sense to split threads across different
.I memory
cgroups.)
-.PP
+.P
Notwithstanding the initial design decision in cgroups v2,
there were use cases for certain controllers, notably the
.I cpu
To accommodate such use cases, Linux 4.14 added
.I "thread mode"
for cgroups v2.
-.PP
+.P
Thread mode allows the following:
.IP \[bu] 3
The creation of
so that, within a threaded subtree,
a cgroup can both contain member threads and
exercise resource control over child cgroups.
-.PP
+.P
With the addition of thread mode,
each nonroot cgroup now contains a new file,
.IR cgroup.type ,
.I """threaded"""
to each of these cgroups is somewhat cumbersome,
but allows for possible future extensions to the thread-mode model.
-.PP
+.P
The second way of creating a threaded subtree is as follows:
.IP (1) 5
In an existing cgroup,
.IR y ,
in order to convert them to the type
.IR threaded .
-.PP
+.P
One of the consequences of the above pathways to creating a threaded subtree
is that the threaded root cgroup can be a parent only to
.I threaded
.IR threaded ;
upon doing so, the corresponding controller interface files
appear in the children of that cgroup.
-.PP
+.P
A process can be moved into a threaded subtree by writing its PID to the
.I cgroup.procs
file in one of the cgroups inside the tree.
.I cgroup.threads
files in different cgroups inside the subtree.
The threads of a process must all reside in the same threaded subtree.
-.PP
+.P
As with writing to
.IR cgroup.procs ,
some containment rules apply when writing to the
.I domain
cgroup fails with the error
.BR EOPNOTSUPP .)
-.PP
+.P
The
.I cgroup.threads
file is present in each cgroup (including
that is present in the cgroup.
The set of thread IDs obtained when reading this file
is not guaranteed to be ordered or free of duplicates.
-.PP
+.P
The
.I cgroup.procs
file in the threaded root shows the PIDs of all processes
The
.I cgroup.procs
files in the other cgroups in the subtree are not readable.
-.PP
+.P
Domain controllers can't be enabled in a threaded subtree;
no controller-interface files appear inside the cgroups underneath the
threaded root.
threaded subtrees are invisible:
a multithreaded process inside a threaded subtree appears to a domain
controller as a process that resides in the threaded root cgroup.
-.PP
+.P
Within a threaded subtree, the "no internal processes" rule does not apply:
a cgroup can both contain member processes (or thread)
and exercise controllers on child cgroups.
In other words, the cgroups of a threaded subtree must be converted to the
.I threaded
state in a top-down manner.
-.PP
+.P
There are also some constraints that must be satisfied
in order to create a threaded subtree rooted at the cgroup
.IR x :
.IR x 's
.I cgroup.subtree_control
file.
-.PP
+.P
If any of the above constraints is violated, then an attempt to write
.I """threaded"""
to a
.IP \[bu]
A threaded controller is enabled inside the cgroup and
a process is made a member of the cgroup.
-.PP
+.P
A
.I domain threaded
cgroup,
.I x
no longer has threaded controllers enabled or
no longer has member processes.
-.PP
+.P
When a
.I domain threaded
cgroup
The type of any descendants of that cgroup that
are not part of lower-level threaded subtrees changes to
.IR "domain invalid" .
-.PP
+.P
Note that in this case, there is no cgroup whose type becomes
.IR "domain threaded" .
(Notionally, the root cgroup can be considered as the threaded root
for the cgroup whose type was changed to
.IR threaded .)
-.PP
+.P
The aim of this exceptional treatment for the root cgroup is to
allow a threaded cgroup that employs the
.I cpu
.I cgroup.subtree_control
file fails with the error
.BR EINVAL .)
-.PP
+.P
On some systems,
.BR systemd (1)
places certain realtime threads in nonroot cgroups in the v2 hierarchy.
inherits its parent's cgroup memberships.
A process's cgroup memberships are preserved across
.BR execve (2).
-.PP
+.P
The
.BR clone3 (2)
.B CLONE_INTO_CGROUP
.BR namespaces (7),
.BR sched (7),
.BR user_namespaces (7)
-.PP
+.P
The kernel source file
.IR Documentation/admin\-guide/cgroup\-v2.rst .
and how they were used on Linux before Unicode became ubiquitous.
Some of this information is still helpful for people working with legacy
systems and documents.
-.PP
+.P
Standards discussed include such as
ASCII, GB 2312, ISO 8859, JIS, KOI8-R, KS, and Unicode.
-.PP
+.P
The primary emphasis is on character sets that were actually used by
locale character sets, not the myriad others that could be found in data
from other systems.
Also known as US-ASCII.
It is currently described by the ISO 646:1991 IRV
(International Reference Version) standard.
-.PP
+.P
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
All are deprecated;
glibc does not support locales whose character sets are not true
supersets of ASCII.
-.PP
+.P
As Unicode, when using UTF-8, is ASCII-compatible, plain ASCII text
still renders properly on modern UTF-8 using systems.
.SS ISO 8859
ISO 8859 is a series of 15 8-bit character sets, all of which have ASCII
in their low (7-bit) half, invisible control characters in positions
128 to 159, and 96 fixed-width graphics in positions 160\[en]255.
-.PP
+.P
Of these, the most important is ISO 8859-1
("Latin Alphabet No. 1" / Latin-1).
It was widely adopted and supported by different systems,
and is gradually being replaced with Unicode.
The ISO 8859-1 characters are also the first 256 characters of Unicode.
-.PP
+.P
Console support for the other 8859 character sets is available under
Linux through user-mode utilities (such as
.BR setfont (8))
that modify keyboard bindings and the EGA graphics
table and employ the "user mapping" font table in the console
driver.
-.PP
+.P
Here are brief descriptions of each character set:
.TP
8859-1 (Latin-1)
KOI8-U, based on KOI8-R, has better support for Ukrainian.
Neither of these sets are ISO-2022 compatible,
unlike the ISO 8859 series.
-.PP
+.P
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.
.BR xterm (1).
Several ISO 2022-based character encodings have been defined,
especially for Japanese.
-.PP
+.P
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
It uses codes either
040\[en]0177 (041\[en]0176) or 0240\[en]0377 (0241\[en]0376).
G0 always has size 94 and uses codes 041\[en]0176.
-.PP
+.P
Switching between character sets is done using the shift functions
\fB\[ha]N\fP (SO or LS1), \fB\[ha]O\fP (SI or LS0), ESC n (LS2), ESC o (LS3),
ESC N (SS2), ESC O (SS3), ESC \[ti] (LS1R), ESC } (LS2R), ESC | (LS3R).
The function SS\fIn\fP makes character set G\fIn\fP (\fIn\fP=2 or 3)
the current one for the next character only (regardless of the value
of its high order bit).
-.PP
+.P
A 94-character set is designated as G\fIn\fP 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
instead of currency sign), ESC ( M selects a character set
for African languages, ESC ( ! A selects the Cuban character
set, and so on.
-.PP
+.P
A 96-character set is designated as G\fIn\fP 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.
-.PP
+.P
A multibyte character set is designated as G\fIn\fP 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.
-.PP
+.P
ISO 4873 stipulates a narrower use of character sets, where G0
is fixed (always ASCII), so that G1, G2, and G3
can be invoked only for codes with the high order bit set.
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).
-.PP
+.P
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.
-.PP
+.P
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
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.
-.PP
+.P
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
into xxxxyyyy yyzzzzzz.
(When UTF-8 is used to code the 31-bit ISO/IEC 10646
then this progression continues up to 6-byte codes.)
-.PP
+.P
For most texts in ISO 8859 character sets, this means that the
characters outside of ASCII are now coded with two bytes.
This tends
(especially ISO 8859-1) to Unicode, general conversion requires
carrying around conversion tables, which can be quite large for 16-bit
codes.
-.PP
+.P
Note that UTF-8 is self-synchronizing:
10xxxxxx is a tail,
any other byte is the head of a code.
In particular,
there are no embedded NULs (\[aq]\e0\[aq]) or \[aq]/\[aq]s
that form part of some larger code.
-.PP
+.P
Since ASCII, and, in particular, NUL and \[aq]/\[aq], 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.
-.PP
+.P
Rendering of Unicode data streams is typically handled through
"subfont" tables which map a subset of Unicode to glyphs.
Internally
.SH DESCRIPTION
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.
-.PP
+.P
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
and phi the angle between the X-axis and the line Oz.
Now
z = r*exp(i*phi) = r*(cos(phi)+i*sin(phi)).
-.PP
+.P
The basic operations are defined on z = a+b*i and w = c+d*i as:
.TP
.B addition: z+w = (a+c) + (b+d)*i
.B multiplication: z*w = (a*c \- b*d) + (a*d + b*c)*i
.TP
.B division: z/w = ((a*c + b*d)/(c*c + d*d)) + ((b*c \- a*d)/(c*c + d*d))*i
-.PP
+.P
Nearly all math function have a complex counterpart but there are
some complex-only functions.
.SH EXAMPLES
Your C-compiler can work with complex numbers if it supports the C99 standard.
The imaginary unit is represented by I.
-.PP
+.P
.EX
/* check that exp(i * pi) == \-1 */
#include <math.h> /* for atan */
and memory placement of processes.
It is commonly mounted at
.IR /dev/cpuset .
-.PP
+.P
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
on a system is not modified or if the cpuset filesystem
is not even mounted, then the cpuset mechanism,
though present, has no effect on the system's behavior.
-.PP
+.P
A cpuset defines a list of CPUs and memory nodes.
-.PP
+.P
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
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.
-.PP
+.P
Cpusets are represented as directories in a hierarchical
pseudo-filesystem, where the top directory in the hierarchy
.RI ( /dev/cpuset )
CPUs and memory nodes.
The directories and files representing cpusets have normal
filesystem permissions.
-.PP
+.P
Every process in the system belongs to exactly one cpuset.
A process is confined to run only on the CPUs in
the cpuset it belongs to, and to allocate memory only
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.
-.PP
+.P
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.
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.
-.PP
+.P
Cpusets are integrated with the
.BR sched_setaffinity (2)
scheduling affinity mechanism and the
a call ends up requesting an empty set of CPUs or
memory nodes, after that request is restricted to
the invoking process's cpuset.
-.PP
+.P
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
.I /dev/cpuset
represents a cpuset and contains a fixed set of pseudo-files
describing the state of that cpuset.
-.PP
+.P
New cpusets are created using the
.BR mkdir (2)
system call or the
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.
-.PP
+.P
The pseudo-files in each cpuset directory are automatically created when
the cpuset is created, as a result of the
.BR mkdir (2)
invocation.
It is not possible to directly add or remove these pseudo-files.
-.PP
+.P
A cpuset directory that contains no child cpuset directories,
and has no attached processes, can be removed using
.BR rmdir (2)
.BR rmdir (1).
It is not necessary, or possible,
to remove the pseudo-files inside the directory before removing it.
-.PP
+.P
The pseudo-files in each cpuset directory are
small text files that may be read and
written using traditional shell utilities such as
.BR write (2),
and
.BR close (2).
-.PP
+.P
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.
the range of CPUs over which immediate load balancing is attempted.
See \fBScheduler Relax Domain Level\fR, below, for further details.
.\" ================== proc cpuset ==================
-.PP
+.P
In addition to the above pseudo-files in each directory below
.IR /dev/cpuset ,
each process has a pseudo-file,
that displays the path of the process's cpuset directory
relative to the root of the cpuset filesystem.
.\" ================== proc status ==================
-.PP
+.P
Also the
.IR /proc/ pid /status
file for each process has four added lines,
(on which memory nodes it may obtain memory),
in the two formats \fBMask Format\fR and \fBList Format\fR (see below)
as shown in the following example:
-.PP
+.P
.in +4n
.EX
Cpus_allowed: ffffffff,ffffffff,ffffffff,ffffffff
Mems_allowed_list: 0\-63
.EE
.in
-.PP
+.P
The "allowed" fields were added in Linux 2.6.24;
the "allowed_list" fields were added in Linux 2.6.26.
.\" ================== EXTENDED CAPABILITIES ==================
.IR mem_exclusive ,
no other cpuset, other than a direct ancestor or descendant,
may share any of the same CPUs or memory nodes.
-.PP
+.P
A cpuset that is
.I mem_exclusive
restricts kernel allocations for
All cpusets, whether
.I hardwall
or not, restrict allocations of memory for user space.
-.PP
+.P
This enables configuring a system so that several independent
jobs can share common kernel data, such as filesystem pages,
while isolating each job's user allocation in its own cpuset.
job which are not
.I hardwall
cpusets.
-.PP
+.P
Only a small amount of kernel memory, such as requests from
interrupt handlers, is allowed to be taken outside even a
.I hardwall
supplying the pathname (relative to the mount point of the
cpuset filesystem) of the abandoned cpuset.
This enables automatic removal of abandoned cpusets.
-.PP
+.P
The default value of
.I notify_on_release
in the root cpuset at system boot is disabled (0).
is the current value of their parent's
.I notify_on_release
setting.
-.PP
+.P
The command
.I /sbin/cpuset_release_agent
is invoked, with the name
relative path)
of the to-be-released cpuset in
.IR argv[1] .
-.PP
+.P
The usual contents of the command
.I /sbin/cpuset_release_agent
is simply the shell script:
-.PP
+.P
.in +4n
.EX
#!/bin/sh
rmdir /dev/cpuset/$1
.EE
.in
-.PP
+.P
As with other flag values below, this flag can
be changed by writing an ASCII
number 0 or 1 (with optional trailing newline)
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.
-.PP
+.P
This enables batch managers that are monitoring jobs running in dedicated
cpusets to efficiently detect what level of memory pressure that job
is causing.
-.PP
+.P
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.
-.PP
+.P
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.
-.PP
+.P
Unless memory pressure calculation is enabled by setting the pseudo-file
.IR /dev/cpuset/cpuset.memory_pressure_enabled ,
it is not computed for any cpuset, and reads from any
.I memory_pressure
always return zero, as represented by the ASCII string "0\en".
See the \fBWARNINGS\fR section, below.
-.PP
+.P
A per-cpuset, running average is employed for the following reasons:
.IP \[bu] 3
Because this meter is per-cpuset rather than per-process or per virtual
pressure in a cpuset\[em]with a single read, rather than having to
query and accumulate results over all the (dynamically changing)
set of processes in the cpuset.
-.PP
+.P
The
.I memory_pressure
of a cpuset is calculated using a per-cpuset simple digital filter
For each cpuset, this filter tracks
the recent rate at which processes attached to that cpuset enter the
kernel direct reclaim code.
-.PP
+.P
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.
Unmodified filesystem buffer pages are repurposed
by simply dropping them, though if that page is needed again, it
will have to be reread from disk.
-.PP
+.P
The
.I cpuset.memory_pressure
file provides an integer number representing the recent (half-life of
.I cpuset.memory_spread_page
and
.IR cpuset.memory_spread_slab .
-.PP
+.P
If the per-cpuset Boolean flag file
.I cpuset.memory_spread_page
is set, then
the kernel will spread the filesystem 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.
-.PP
+.P
If the per-cpuset Boolean flag file
.I cpuset.memory_spread_slab
is set,
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.
-.PP
+.P
The setting of these flags does not affect the data segment
(see
.BR brk (2))
or stack segment pages of a process.
-.PP
+.P
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.
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.
-.PP
+.P
When new cpusets are created, they inherit the memory spread settings
of their parent.
-.PP
+.P
Setting memory spreading causes allocations for the affected page or
slab caches to ignore the process's NUMA memory policy and be spread
instead.
If cpuset memory spreading is subsequently turned off, the NUMA
memory policy most recently specified by these calls is automatically
reapplied.
-.PP
+.P
Both
.I cpuset.memory_spread_page
and
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.
-.PP
+.P
Cpuset-specified memory spreading behaves similarly to what is known
(in other contexts) as round-robin or interleave memory placement.
-.PP
+.P
Cpuset-specified memory spreading can provide substantial performance
improvements for jobs that:
.IP \[bu] 3
.IP \[bu]
need to access large filesystem data sets that must to be spread
across the several nodes in the job's cpuset in order to fit.
-.PP
+.P
Without this policy,
the memory allocation across the nodes in the job's cpuset
can become very uneven,
cpuset's memory-placement policy
.I mems
subsequently changes.
-.PP
+.P
When memory migration is enabled in a cpuset, if the
.I 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.
-.PP
+.P
Furthermore, if a process is moved into a cpuset with
.I 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.
-.PP
+.P
The relative placement of a migrated page within
the cpuset is preserved during these migration operations if possible.
For example,
overloaded CPUs and move those processes to the underutilized CPU,
within the constraints of such placement mechanisms as cpusets and
.BR sched_setaffinity (2).
-.PP
+.P
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.
on implementation details of the kernel process scheduler, which is
subject to change over time, as improved kernel scheduler algorithms
are implemented.)
-.PP
+.P
The per-cpuset flag
.I 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.
-.PP
+.P
By default, load balancing is done across all CPUs, except those
marked isolated using the kernel boot time "isolcpus=" argument.
(See \fBScheduler Relax Domain Level\fR, below, to change this default.)
-.PP
+.P
This default load balancing across all CPUs is not well suited to
the following two situations:
.IP \[bu] 3
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.
-.PP
+.P
When the per-cpuset flag
.I sched_load_balance
is enabled (the default setting),
as by
.BR sched_setaffinity (2))
from any CPU in that cpuset to any other.
-.PP
+.P
When the per-cpuset flag
.I sched_load_balance
is disabled, then the
has
.I sched_load_balance
enabled.
-.PP
+.P
So, for example, if the top cpuset has the flag
.I sched_load_balance
enabled, then the scheduler will load balance across all
.I sched_load_balance
flag in other cpusets has no effect,
as we're already fully load balancing.
-.PP
+.P
Therefore in the above two situations, the flag
.I sched_load_balance
should be disabled in the top cpuset, and only some of the smaller,
child cpusets would have this flag enabled.
-.PP
+.P
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
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.
-.PP
+.P
Of course, processes pinned to a particular CPU can be left in a cpuset
that disables
.I sched_load_balance
CPUs allowed by their cpuset, as modified by
.BR sched_setaffinity (2)
system calls.
-.PP
+.P
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.
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.
-.PP
+.P
The exact meaning of the small integer values of
.I sched_relax_domain_level
will depend on internal
non-uniform architecture of the hardware.
Both of these will evolve
over time and vary by system architecture and kernel version.
-.PP
+.P
As of this writing, when this capability was introduced in Linux
2.6.26, on certain popular architectures, the positive values of
.I sched_relax_domain_level
have the following meanings.
-.PP
+.P
.PD 0
.TP
.B 1
Perform immediate load balancing across over all CPUs
in system [On NUMA systems].
.PD
-.PP
+.P
The
.I sched_relax_domain_level
value of zero (0) always means
hence that load balancing is done only periodically,
not immediately when a CPU becomes available or another task becomes
runnable.
-.PP
+.P
The
.I sched_relax_domain_level
value of minus one (\-1)
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.
-.PP
+.P
In the case of multiple overlapping cpusets which have conflicting
.I sched_relax_domain_level
values, then the highest such value
in the
.IR /proc/ pid /status
file.
-.PP
+.P
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.
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.
-.PP
+.P
The number of 32-bit words displayed is the minimum number needed to
display all bits of the bit mask, based on the size of the bit mask.
-.PP
+.P
Examples of the \fBMask Format\fR:
-.PP
+.P
.in +4n
.EX
00000001 # just bit 0 set
00000000,000e3862 # 1,5,6,11\-13,17\-19 set
.EE
.in
-.PP
+.P
A mask with bits 0, 1, 2, 4, 8, 16, 32, and 64 set displays as:
-.PP
+.P
.in +4n
.EX
00000001,00000001,00010117
.EE
.in
-.PP
+.P
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.
.I mems
is a comma-separated list of CPU or memory-node
numbers and ranges of numbers, in ASCII decimal.
-.PP
+.P
Examples of the \fBList Format\fR:
-.PP
+.P
.in +4n
.EX
0\-4,9 # bits 0, 1, 2, 3, 4, and 9 set
of the directories and pseudo-files in the cpuset filesystem,
normally mounted at
.IR /dev/cpuset .
-.PP
+.P
For instance, a process can put itself in some other cpuset (than
its current one) if it can write the
.I tasks
and write permission on the
.I tasks
file.
-.PP
+.P
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
.BR kill (2)).
-.PP
+.P
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
or
.I mems
file.
-.PP
+.P
There is one minor difference between the manner in which these
permissions are evaluated and the manner in which normal filesystem
operation permissions are evaluated.
which is a bit unusual)
or if some user code converts the relative cpuset path to a
full filesystem path.
-.PP
+.P
In theory, this means that user code should specify cpusets
using absolute pathnames, which requires knowing the mount point of
the cpuset filesystem (usually, but not necessarily,
system call fails.
.\" Gack! csh(1)'s echo does this
For example, if the command:
-.PP
+.P
.in +4n
.EX
echo 19 > cpuset.mems
.EE
.in
-.PP
+.P
failed because memory node 19 was not allowed (perhaps
the current system does not have a memory node 19), then the
.B echo
command will display
.BR write (2)
errors, as in the example:
-.PP
+.P
.in +4n
.EX
/bin/echo 19 > cpuset.mems
.SS Memory placement
Not all allocations of system memory are constrained by cpusets,
for the following reasons.
-.PP
+.P
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
memory nodes taken offline.
User code should reconfigure cpusets to refer only to online CPUs
and memory nodes when using hot-plug to add or remove such resources.
-.PP
+.P
A few kernel-critical, internal memory-allocation requests, marked
GFP_ATOMIC, must be satisfied immediately.
The kernel may drop some
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.
-.PP
+.P
Allocations of memory requested by kernel drivers while processing
an interrupt lack any relevant process context, and are not confined
by cpusets.
The Linux kernel implementation of cpusets sets
.I errno
to specify the reason for a failed system call affecting cpusets.
-.PP
+.P
The possible
.I errno
settings and their meaning when set on
.SS Creating and attaching to a cpuset.
To create a new cpuset and attach the current command shell to it,
the steps are:
-.PP
+.P
.PD 0
.IP (1) 5
mkdir /dev/cpuset (if not already done)
.IP (5)
Attach the shell to the new cpuset.
.PD
-.PP
+.P
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.
-.PP
+.P
.in +4n
.EX
.RB "$" " mkdir /dev/cpuset"
to different CPUs and memory nodes in the system, including moving
the memory pages currently allocated to that job,
perform the following steps.
-.PP
+.P
.PD 0
.IP (1) 5
Let's say we want to move the job in cpuset
to
.IR beta .
.PD
-.PP
+.P
The following sequence of commands accomplishes this.
-.PP
+.P
.in +4n
.EX
.RB "$" " cd /dev/cpuset"
.RB "$" " while read i; do /bin/echo $i; done < ../alpha/tasks > tasks"
.EE
.in
-.PP
+.P
The above should move any processes in
.I alpha
to
.IR beta ,
and any memory held by these processes on memory nodes 2\[en]3 to memory
nodes 8\[en]9, respectively.
-.PP
+.P
Notice that the last step of the above sequence did not do:
-.PP
+.P
.in +4n
.EX
.RB "$" " cp ../alpha/tasks tasks"
.EE
.in
-.PP
+.P
The
.I while
loop, rather than the seemingly easier use of the
only one process PID at a time may be written to the
.I tasks
file.
-.PP
+.P
The same effect (writing one PID at a time) as the
.I while
loop can be accomplished more efficiently, in fewer keystrokes and in
.B \-u
(unbuffered) option of
.BR sed (1):
-.PP
+.P
.in +4n
.EX
.RB "$" " sed \-un p < ../alpha/tasks > tasks"
.BR sched (7),
.BR migratepages (8),
.BR numactl (8)
-.PP
+.P
.I Documentation/admin\-guide/cgroup\-v1/cpusets.rst
in the Linux kernel source tree
.\" commit 45ce80fb6b6f9594d1396d44dd7e7c02d596fef8
.I pid_t
(defined in
.IR <sys/types.h> ).
-.PP
+.P
PIDs are used in a range of system calls to identify the process
affected by the call, for example:
.BR kill (2),
.BR waitpid (2).
.\" .BR waitid (2),
.\" .BR wait4 (2),
-.PP
+.P
A process's PID is preserved across an
.BR execve (2).
.SS Parent process ID (PPID)
.BR getppid (2).
A PPID is represented using the type
.IR pid_t .
-.PP
+.P
A process's PPID is preserved across an
.BR execve (2).
.SS Process group ID and session ID
.BR getsid (2),
and its process group ID using
.BR getpgrp (2).
-.PP
+.P
A child created by
.BR 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
.BR execve (2).
-.PP
+.P
Sessions and process groups are abstractions devised to support shell
job control.
A process group (sometimes called a "job") is a collection of
.BR setpgid (2).
The process whose process ID is the same as its process group ID is the
\fIprocess group leader\fP for that group.
-.PP
+.P
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
as the PID of the process that called
.BR setsid (2).
The creator of the session is called the \fIsession leader\fP.
-.PP
+.P
All of the processes in a session share a
.IR "controlling terminal" .
The controlling terminal is established when the session leader
flag is specified when calling
.BR open (2)).
A terminal may be the controlling terminal of at most one session.
-.PP
+.P
At most one of the jobs in a session may be the
.IR "foreground job" ;
other jobs in the session are
.I interrupt
key, normally control-C)
are pressed, the signal is sent to the processes in the foreground job.
-.PP
+.P
Various system calls and library functions
may operate on all members of a process group,
including
.I gid_t
(defined in
.IR <sys/types.h> ).
-.PP
+.P
On Linux, each process has the following user and group identifiers:
.IP \[bu] 3
Real user ID and real group ID.
.\" As at 2.6.22-rc2, this file is still read-only.
A process can obtain its set of supplementary group IDs using
.BR getgroups (2).
-.PP
+.P
A child process created by
.BR fork (2)
inherits copies of its parent's user and groups IDs.
group IDs are preserved;
the effective and saved set IDs may be changed, as described in
.BR execve (2).
-.PP
+.P
Aside from the purposes noted above,
a process's user IDs are also employed in a number of other contexts:
.IP \[bu] 3
.TP
.BR setgroups (2)
Modify the process's supplementary group list.
-.PP
+.P
Any changes to a process's effective user (group) ID
are automatically carried over to the process's
filesystem user (group) ID.
Changes to a process's effective user or group ID can also affect the
process "dumpable" attribute, as described in
.BR prctl (2).
-.PP
+.P
Changes to process user and group IDs can affect the capabilities
of the process, as described in
.BR capabilities (7).
are specified in POSIX.1.
The real, effective, and saved set user and groups IDs,
and the supplementary group IDs, are specified in POSIX.1.
-.PP
+.P
The filesystem user and group IDs are a Linux extension.
.SH NOTES
Various fields in the
See
.BR proc (5)
for further information.
-.PP
+.P
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
.nf
.B #include <sys/socket.h>
.B #include <netatalk/at.h>
-.PP
+.P
.IB ddp_socket " = socket(AF_APPLETALK, SOCK_DGRAM, 0);"
.IB raw_socket " = socket(AF_APPLETALK, SOCK_RAW, " protocol ");"
.fi
libraries.
This page documents the interface for those who wish or need to
use the DDP layer directly.
-.PP
+.P
The communication between AppleTalk and the user program works using a
BSD-compatible socket interface.
For more information on sockets, see
.BR socket (7).
-.PP
+.P
An AppleTalk socket is created by calling the
.BR socket (2)
function with a
.B SOCK_RAW
you must specify
.BR ATPROTO_DDP .
-.PP
+.P
Raw sockets may be opened only by a process with effective user ID 0
or when the process has the
.B CAP_NET_RAW
.SS Address format
An AppleTalk socket address is defined as a combination of a network number,
a node number, and a port number.
-.PP
+.P
.in +4n
.EX
struct at_addr {
};
.EE
.in
-.PP
+.P
.I sat_family
is always set to
.BR AF_APPLETALK .
.TP
.I aarp\-tick\-time
The timer rate (in seconds) for the timer driving AARP.
-.PP
+.P
The default values match the specification and should never need to be
changed.
.SS Ioctls
Many BSD systems fail to check
.B SO_BROADCAST
when sending broadcast frames; this can lead to compatibility problems.
-.PP
+.P
The
raw
socket mode is unique to Linux and exists to support the alternative CAP
package and AppleTalk monitoring tools more easily.
.SH BUGS
There are too many inconsistent error values.
-.PP
+.P
The ioctls used to configure routing tables, devices,
AARP tables, and other devices are not yet described.
.SH SEE ALSO
it inherits a
.I copy
of its parent's environment.
-.PP
+.P
By convention, the strings in
.I environ
have the form "\fIname\fP\fB=\fP\fIvalue\fP".
The value can be anything that can be represented as a string.
The name and the value may not contain an embedded null byte (\[aq]\e0\[aq]),
since this is assumed to terminate the string.
-.PP
+.P
Environment variables may be placed in the shell's environment by the
.I export
command in
.I setenv
command if you use
.BR csh (1).
-.PP
+.P
The initial environment of the shell is populated in various ways,
such as definitions from
.I /etc/environment
script and per-user initializations script may include commands
that add variables to the shell's environment;
see the manual page of your preferred shell for details.
-.PP
+.P
Bourne-style shells support the syntax
-.PP
+.P
.in +4n
.EX
NAME=value command
.EE
.in
-.PP
+.P
to create an environment variable definition only in the scope
of the process that executes
.IR command .
Multiple variable definitions, separated by white space, may precede
.IR command .
-.PP
+.P
Arguments may also be placed in the
environment at the point of an
.BR exec (3).
.BR setenv (3),
and
.BR unsetenv (3).
-.PP
+.P
What follows is a list of environment variables typically seen on a
system.
This list is incomplete and includes only common variables seen
.\" .B BROWSER
.\" The user's preferred utility to browse URLs. Sequence of colon-separated
.\" browser commands. See http://www.catb.org/\[ti]esr/BROWSER/ .
-.PP
+.P
Note that the behavior of many programs and library routines is
influenced by the presence or value of certain environment variables.
Examples include the following:
.B _GNU_SOURCE
feature test macro is defined (see
.BR feature_test_macros (7)).
-.PP
+.P
The
.BR prctl (2)
.B PR_SET_MM_ENV_START
and
.B PR_SET_MM_ENV_END
operations can be used to control the location of the process's environment.
-.PP
+.P
The
.BR HOME ,
.BR LOGNAME ,
Many a system command has been
tricked into mischief by a user who specified unusual values for
.BR IFS " or " LD_LIBRARY_PATH .
-.PP
+.P
There is also the risk of name space pollution.
Programs like
.I make
.B 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.
-.PP
+.P
The central concept of the
.B epoll
API is the
the file descriptors in the interest list.
The ready list is dynamically populated
by the kernel as a result of I/O activity on those file descriptors.
-.PP
+.P
The following system calls are provided to
create and manage an
.B epoll
A call to
.BR epoll_wait (2)
is done.
-.PP
+.P
If the
.I rfd
file descriptor has been added to the
done in step
.B 5
might block indefinitely.
-.PP
+.P
An application that employs the
.B EPOLLET
flag should use nonblocking file descriptors to avoid having a blocking
.BR write (2)
return
.BR EAGAIN .
-.PP
+.P
By contrast, when used as a level-triggered interface
(the default, when
.B EPOLLET
.BR poll (2),
and can be used wherever the latter is used since it shares the
same semantics.
-.PP
+.P
Since even with edge-triggered
.BR epoll ,
multiple events can be generated upon receipt of multiple chunks of data,
.BR epoll_ctl (2)
with
.BR EPOLL_CTL_MOD .
-.PP
+.P
If multiple threads
(or processes, if child processes have inherited the
.B epoll
.BR epoll_ctl (2)
.B EPOLLWAKEUP
flag.
-.PP
+.P
When the
.B EPOLLWAKEUP
flag is set in the
or
.BR write (2)
from where it stopped before.
-.PP
+.P
.in +4n
.EX
#define MAX_EVENTS 10
}
.EE
.in
-.PP
+.P
When used as an edge-triggered interface, for performance reasons, it is
possible to add the file descriptor inside the
.B epoll
See
.BR proc (5)
for further details.
-.PP
+.P
The
.BR kcmp (2)
.B KCMP_EPOLL_TFD
(See
.BR inotify (7)
for details of an API that did notify those events pre Linux 5.1.)
-.PP
+.P
Additional capabilities compared to the
.BR inotify (7)
API include the ability to monitor all of the objects
in a mounted filesystem,
the ability to make access permission decisions, and the
possibility to read or modify files before access by other applications.
-.PP
+.P
The following system calls are used with this API:
.BR fanotify_init (2),
.BR fanotify_mark (2),
.BR fanotify_init (2)
system call creates and initializes an fanotify notification group
and returns a file descriptor referring to it.
-.PP
+.P
An fanotify notification group is a kernel-internal object that holds
a list of files, directories, filesystems, and mounts for which
events shall be created.
-.PP
+.P
For each entry in an fanotify notification group, two bit masks exist: the
.I mark
mask and the
Having these two types of masks permits a filesystem, mount, or
directory to be marked for receiving events, while at the same time
ignoring events for specific objects under a mount or directory.
-.PP
+.P
The
.BR fanotify_mark (2)
system call adds a file, directory, filesystem, or mount to a
notification group and specifies which events
shall be reported (or ignored), or removes or modifies such an entry.
-.PP
+.P
A possible usage of the ignore mask is for a file cache.
Events of interest for a file cache are modification of a file and closing
of the same.
Hence, the modify event can be added to the ignore mask.
Upon receiving the close event, the modify event can be removed from the
ignore mask and the file cache entry can be updated.
-.PP
+.P
The entries in the fanotify notification groups refer to files and
directories via their inode number and to mounts via their mount ID.
If files or directories are renamed or moved within the same mount,
from the fanotify file descriptor
returned by
.BR fanotify_init (2).
-.PP
+.P
Two types of events are generated:
.I notification
events and
whether permission for a file access shall be granted.
For these events, the recipient must write a response which decides whether
access is granted or not.
-.PP
+.P
An event is removed from the event queue of the fanotify group
when it has been read.
Permission events that have been read are kept in an internal list of the
until either a file event occurs or the call is interrupted by a signal
(see
.BR signal (7)).
-.PP
+.P
After a successful
.BR read (2),
the read buffer contains one or more of the following structures:
-.PP
+.P
.in +4n
.EX
struct fanotify_event_metadata {
};
.EE
.in
-.PP
+.P
Information records are
supplemental pieces of information that
may be provided alongside the generic
field of this structure in order to
determine the type of information record that
had been received for a given event.
-.PP
+.P
In cases where an fanotify group
identifies filesystem objects by file handles,
event listeners should also expect to
information record objects alongside the generic
.I fanotify_event_metadata
structure within the read buffer:
-.PP
+.P
.in +4n
.EX
struct fanotify_event_info_fid {
};
.EE
.in
-.PP
+.P
In cases where an fanotify group is initialized with
.BR FAN_REPORT_PIDFD ,
event listeners should expect to receive the below
information record object alongside the generic
.I fanotify_event_metadata
structure within the read buffer:
-.PP
+.P
.in +4n
.EX
struct fanotify_event_info_pidfd {
};
.EE
.in
-.PP
+.P
In case of a
.B FAN_FS_ERROR
event,
.I fanotify_event_metadata
structure within the read buffer.
This structure is defined as follows:
-.PP
+.P
.in +4n
.EX
struct fanotify_event_info_error {
};
.EE
.in
-.PP
+.P
All information records contain a nested structure of type
.IR fanotify_event_info_header .
This structure holds meta-information about the information record
.I fanotify_event_metadata
structure.
This structure is defined as follows:
-.PP
+.P
.in +4n
.EX
struct fanotify_event_info_header {
};
.EE
.in
-.PP
+.P
For performance reasons, it is recommended to use a large
buffer size (for example, 4096 bytes),
so that multiple events can be retrieved by a single
.BR read (2).
-.PP
+.P
The return value of
.BR read (2)
is the number of bytes placed in the buffer,
or \-1 in case of an error (but see BUGS).
-.PP
+.P
The fields of the
.I fanotify_event_metadata
structure are as follows:
.BR fanotify_init (2),
this is the TID of the thread that caused the event.
Otherwise, this the PID of the process that caused the event.
-.PP
+.P
A program listening to fanotify events can compare this PID
to the PID returned by
.BR getpid (2),
to determine whether the event is caused by the listener itself,
or is due to a file access by another process.
-.PP
+.P
The bit mask in
.I mask
indicates which events have occurred for a single filesystem object.
consecutive events for the same filesystem object and originating from the
same process may be merged into a single event, with the exception that two
permission events are never merged into one queue entry.
-.PP
+.P
The bits that may appear in
.I mask
are as follows:
See NOTES in
.BR fanotify_mark (2)
for additional details.
-.PP
+.P
To check for any close event, the following bit mask may be used:
.TP
.B FAN_CLOSE
FAN_CLOSE_WRITE | FAN_CLOSE_NOWRITE
.EE
.in
-.PP
+.P
To check for any move event, the following bit mask may be used:
.TP
.B FAN_MOVE
FAN_MOVED_FROM | FAN_MOVED_TO
.EE
.in
-.PP
+.P
The following bits may appear in
.I mask
only in conjunction with other event type bits:
.B FAN_ONDIR
flag is reported in an event mask only if the fanotify group identifies
filesystem objects by file handles.
-.PP
+.P
Information records that are supplied alongside the generic
.I fanotify_event_metadata
structure will always contain a nested structure of type
.RI ( event_len
\-
.IR metadata_len ).
-.PP
+.P
The fields of the
.I fanotify_event_info_fid
structure are as follows:
and the file handle is followed by a null terminated string that identifies the
name of a directory entry in that directory, or '.' to identify the directory
object itself.
-.PP
+.P
The fields of the
.I fanotify_event_info_pidfd
structure are as follows:
and the pidfd is no longer required,
the pidfd should be closed via
.BR close (2).
-.PP
+.P
The fields of the
.I fanotify_event_info_error
structure are as follows:
.I error_count
This is a counter of the number of errors suppressed
since the last error was read.
-.PP
+.P
The following macros are provided to iterate over a buffer containing
fanotify event metadata returned by a
.BR read (2)
.I meta\->event_len
from
.IR len ).
-.PP
+.P
In addition, there is:
.TP
.B FAN_EVENT_METADATA_LEN
.BR write (2)
a structure of the following form to the
fanotify file descriptor:
-.PP
+.P
.in +4n
.EX
struct fanotify_response {
};
.EE
.in
-.PP
+.P
The fields of this structure are as follows:
.TP
.I fd
to allow the file operation or
.B FAN_DENY
to deny the file operation.
-.PP
+.P
If access is denied, the requesting application call will receive an
.B EPERM
error.
.B FAN_FS_ERROR
event record,
but details about the errors are lost.
-.PP
+.P
Errors reported by
.B FAN_FS_ERROR
are generic
.I errno
values,
but not all kinds of error types are reported by all filesystems.
-.PP
+.P
Errors not directly related to a file (i.e. super block corruption)
are reported with an invalid
.IR handle .
See
.BR proc (5)
for details.
-.PP
+.P
Since Linux 5.13,
.\" commit 5b8fea65d197f408bb00b251c70d842826d6b70b
the following interfaces can be used to control the amount of
argument when calling
.BR fanotify_init (2)
and an event occurred for a monitored file that is currently being executed.
-.PP
+.P
In addition to the usual errors for
.BR write (2),
the following errors can occur when writing to the fanotify file descriptor:
filesystem API.
As a result,
it does not catch remote events that occur on network filesystems.
-.PP
+.P
The fanotify API does not report file accesses and modifications that
may occur because of
.BR mmap (2),
.BR msync (2),
and
.BR munmap (2).
-.PP
+.P
Events for directories are created only if the directory itself is opened,
read, and closed.
Adding, removing, or changing children of a marked directory does not create
events for the monitored directory itself.
-.PP
+.P
Fanotify monitoring of directories is not recursive:
to monitor subdirectories under a directory,
additional marks must be created.
in a race-free manner.
Monitoring filesystems offers the capability to monitor changes made from
any mount of a filesystem instance in a race-free manner.
-.PP
+.P
The event queue can overflow.
In this case, events are lost.
.SH BUGS
generate
.B FAN_MODIFY
events.
-.PP
+.P
As of Linux 3.17,
the following bugs exist:
.IP \[bu] 3
When a permission event occurs, a
.B FAN_ALLOW
response is given.
-.PP
+.P
The following shell session shows an example of
running this program.
This session involved editing the file
.B FAN_CLOSE_WRITE
event occurred.
Execution of the program ends when the user presses the ENTER key.
-.PP
+.P
.in +4n
.EX
# \fB./fanotify_example /home\fP
a file or a directory\[em]was created.
Once all events have been read from the buffer and processed accordingly,
the program simply terminates.
-.PP
+.P
The following shell sessions show two different invocations of
this program, with different actions performed on a watched object.
-.PP
+.P
The first session shows a mark being placed on
.IR /home/user .
This is followed by the creation of a regular file,
directory object and with the created file name.
Program execution ends once all events captured within the buffer have
been processed.
-.PP
+.P
.in +4n
.EX
# \fB./fanotify_fid /home/user\fP
$ \fBtouch /home/user/testfile.txt\fP # In another terminal
.EE
.in
-.PP
+.P
The second session shows a mark being placed on
.IR /home/user .
This is followed by the creation of a directory,
event being generated and is reported with the
.B FAN_ONDIR
flag set and with the created directory name.
-.PP
+.P
.in +4n
.EX
# \fB./fanotify_fid /home/user\fP
.SH DESCRIPTION
Feature test macros allow the programmer to control the definitions that
are exposed by system header files when a program is compiled.
-.PP
+.P
.B NOTE:
In order to be effective, a feature test macro
.IR "must be defined before including any header files" .
itself includes
.I <xyz.h>
(POSIX explicitly allows this):
-.PP
+.P
.in +4n
.EX
#include <abc.h>
#include <xyz.h>
.EE
.in
-.PP
+.P
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.
-.PP
+.P
The precise effects of each of the feature test macros described below
can be ascertained by inspecting the
.I <features.h>
(this example from the
.BR acct (2)
manual page):
-.PP
+.P
.RS
.B #include <unistd.h>
-.PP
+.P
.BI "int acct(const char *" filename );
-.PP
+.P
.RS -4
.EX
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.EE
.RE
-.PP
+.P
.BR acct ():
_BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500)
.RE
-.PP
+.P
The
.B ||
means that in order to obtain the declaration of
.I either
of the following macro
definitions must be made before including any header files:
-.PP
+.P
.in +4n
.EX
#define _BSD_SOURCE
#define _XOPEN_SOURCE /* or any value < 500 */
.EE
.in
-.PP
+.P
Alternatively, equivalent definitions can be included in the
compilation command:
-.PP
+.P
.in +4n
.EX
cc \-D_BSD_SOURCE
cc \-D_XOPEN_SOURCE # Or any value < 500
.EE
.in
-.PP
+.P
Note that, as described below,
.BR "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.
-.PP
+.P
In a few cases, manual pages use a shorthand for expressing the
feature test macro requirements (this example from
.BR readahead (2)):
-.PP
+.P
.RS +4
.EX
.B #define _GNU_SOURCE
.B #define _FILE_OFFSET_BITS 64
.B #include <fcntl.h>
-.PP
+.P
.BI "ssize_t readahead(int " fd ", off_t *" offset ", size_t " count );
.EE
.RE
-.PP
+.P
This format is employed when the feature test macros ensure
that the proper function declarations are visible,
and the macros are not defined by default.
in glibc 2.\fIx\fP,
.I x
> 0.
-.PP
+.P
First, though, a summary of a few details for the impatient:
.IP \[bu] 3
The macros that you most likely need to use in modern source code are
.\" The details in glibc 2.0 are simpler, but combining a
.\" a description of them with the details in later glibc versions
.\" would make for a complicated description.
-.PP
+.P
glibc understands the following feature test macros:
.TP
.B __STRICT_ANSI__
(200112L before glibc 2.10;
199506L before glibc 2.4;
199309L before glibc 2.1).
-.PP
+.P
If any of
.BR __STRICT_ANSI__ ,
.BR _ISOC99_SOURCE ,
and
.B _DEFAULT_SOURCE
are not defined by default.
-.PP
+.P
If
.B _POSIX_SOURCE
and
200112L, since glibc 2.4 to glibc 2.9; and
200809L, since glibc 2.10.
.RE
-.PP
+.P
Multiple macros can be defined; the results are additive.
.SH STANDARDS
POSIX.1 specifies
.BR _POSIX_SOURCE ,
and
.BR _XOPEN_SOURCE .
-.PP
+.P
.B _FILE_OFFSET_BITS
is not specified by any standard,
but is employed on some other implementations.
-.PP
+.P
.BR _BSD_SOURCE ,
.BR _SVID_SOURCE ,
.BR _DEFAULT_SOURCE ,
This header file is automatically included by other header files as
required: it is not necessary to explicitly include it in order to
employ feature test macros.
-.PP
+.P
According to which of the above feature test macros are defined,
.I <features.h>
internally defines various other macros that are checked by
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:
-.PP
+.P
.in +4n
.EX
$ \fBcc ftm.c\fP
.BR libc (7),
.BR standards (7),
.BR system_data_types (7)
-.PP
+.P
The section "Feature Test Macros" under
.IR "info libc" .
.\" But beware: the info libc document is out of date (Jul 07, mtk)
-.PP
+.P
.I /usr/include/features.h
contents on the filesystem; the filesystem entry merely
serves as a reference point so that processes can access
the pipe using a name in the filesystem.
-.PP
+.P
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.
-.PP
+.P
A process can open a FIFO in nonblocking mode.
In this
case, opening for read-only succeeds even if no one has
.B ENXIO
(no such device or address) unless the other
end has already been opened.
-.PP
+.P
Under Linux, opening a FIFO for read and write will succeed
both in blocking and nonblocking mode.
POSIX leaves this
.SH NOTES
For details of the semantics of I/O on FIFOs, see
.BR pipe (7).
-.PP
+.P
When a process tries to write to a FIFO that is not opened
for read on the other side, the process is sent a
.B SIGPIPE
signal.
-.PP
+.P
FIFO special files can be created by
.BR mkfifo (3),
and are indicated by
Futexes are very basic and lend themselves well for building higher-level
locking abstractions such as
mutexes, condition variables, read-write locks, barriers, and semaphores.
-.PP
+.P
Most programmers will in fact not be using futexes directly but will
instead rely on system libraries built on them,
such as the Native POSIX Thread Library (NPTL) (see
.BR pthreads (7)).
-.PP
+.P
A futex is identified by a piece of memory which can be
shared between processes or threads.
In these different processes, the futex 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.
-.PP
+.P
Futex operation occurs entirely in user space for the noncontended case.
The kernel is involved only to arbitrate the contended case.
As any sane design will strive for noncontention,
futexes are also optimized for this situation.
-.PP
+.P
In its bare form, a futex is an aligned integer which is
touched only by atomic assembler instructions.
This integer is four bytes long on all platforms.
but it may be necessary to communicate with the kernel using the
.BR futex (2)
system call.
-.PP
+.P
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.
-.PP
+.P
In the contended case, the atomic increment changed the counter
from \-1 (or some other negative number).
If this is detected, there are waiters.
kernel to wake up any waiters using the
.B FUTEX_WAKE
operation.
-.PP
+.P
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.
This is done using the
.B FUTEX_WAIT
operation.
-.PP
+.P
The
.BR futex (2)
system call can optionally be passed a timeout specifying how long
Implementors are expected to be assembly literate and to have read
the sources of the futex user-space library referenced
below.
-.PP
+.P
This man page illustrates the most common use of the
.BR futex (2)
primitives; it is by no means the only one.
.\" .SH AUTHORS
-.\" .PP
+.\" .P
.\" Futexes were designed and worked on by Hubertus Franke
.\" (IBM Thomas J. Watson Research Center),
.\" Matthew Kirkwood, Ingo Molnar (Red Hat) and
.BR set_robust_list (2),
.BR set_tid_address (2),
.BR pthreads (7)
-.PP
+.P
.I Fuss, Futexes and Furwocks: Fast Userlevel Locking in Linux
(proceedings of the Ottawa Linux Symposium 2002),
futex example library, futex-*.tar.bz2
.I /etc/glob
that would expand wildcard patterns.
Soon afterward this became a shell built-in.
-.PP
+.P
These days there is also a library routine
.BR glob (3)
that will perform this function for a user program.
-.PP
+.P
The rules are as follows (POSIX.2, 3.13).
.SS Wildcard matching
A string is a wildcard pattern if it contains one of the
that expands a wildcard pattern into the list of pathnames
matching the pattern.
Matching is defined by:
-.PP
+.P
A \[aq]?\[aq] (not between brackets) matches any single character.
-.PP
+.P
A \[aq]*\[aq] (not between brackets) matches any string,
including the empty string.
-.PP
+.P
.B "Character classes"
-.PP
+.P
An expression "\fI[...]\fP" where the first character after the
leading \[aq][\[aq] is not an \[aq]!\[aq] matches a single character,
namely any of the characters enclosed by the brackets.
that it is the first character.
(Thus, "\fI[][!]\fP" matches the
three characters \[aq][\[aq], \[aq]]\[aq], and \[aq]!\[aq].)
-.PP
+.P
.B Ranges
-.PP
+.P
There is one special convention:
two characters separated by \[aq]\-\[aq] denote a range.
(Thus,
and "\fI[\-\-0]\fP" matches the
three characters \[aq]\-\[aq], \[aq].\[aq], and \[aq]0\[aq],
since \[aq]/\[aq] cannot be matched.)
-.PP
+.P
.B Complementation
-.PP
+.P
An expression "\fI[!...]\fP" matches a single character, namely
any character that is not matched by the expression obtained
by removing the first \[aq]!\[aq] from it.
(Thus, "\fI[!]a\-]\fP" matches any
single character except \[aq]]\[aq], \[aq]a\[aq], and \[aq]\-\[aq].)
-.PP
+.P
One can remove the special meaning of \[aq]?\[aq], \[aq]*\[aq], and \[aq][\[aq]
by preceding them by a backslash,
or,
wildcard, or by a range like "\fI[.\-0]\fP".
A range containing an explicit \[aq]/\[aq] character is syntactically incorrect.
(POSIX requires that syntactically incorrect patterns are left unchanged.)
-.PP
+.P
If a filename starts with a \[aq].\[aq],
this character must be matched explicitly.
(Thus, \fIrm\ *\fP will not remove .profile, and \fItar\ c\ *\fP will not
definition.
It allowed one to have patterns that expand into
an empty list, as in
-.PP
+.P
.nf
xv \-wait 0 *.gif *.jpg
.fi
-.PP
+.P
where perhaps no *.gif files are present (and this is not
an error).
However, POSIX requires that a wildcard pattern is left
With
.I bash
one can force the classical behavior using this command:
-.PP
+.P
.in +4n
.EX
shopt \-s nullglob
.EE
.in
.\" In Bash v1, by setting allow_null_glob_expansion=true
-.PP
+.P
(Similar problems occur elsewhere.
For example, where old scripts have
-.PP
+.P
.in +4n
.EX
rm \`find . \-name "*\[ti]"\`
.EE
.in
-.PP
+.P
new scripts require
-.PP
+.P
.in +4n
.EX
rm \-f nosuchfile \`find . \-name "*\[ti]"\`
.EE
.in
-.PP
+.P
to avoid error messages from
.I rm
called with an empty argument list.)
filenames, rather than text, and secondly, the conventions
are not the same: for example, in a regular expression \[aq]*\[aq] means zero or
more copies of the preceding thing.
-.PP
+.P
Now that regular expressions have bracket expressions where
the negation is indicated by a \[aq]\[ha]\[aq], POSIX has declared the
effect of a wildcard pattern "\fI[\[ha]...]\fP" to be undefined.
and (iii) ranges.
POSIX specifies ranges in an internationally
more useful way and adds three more types:
-.PP
+.P
(iii) Ranges X\-Y comprise all characters that fall between X
and Y (inclusive) in the current collating sequence as defined
by the
.B LC_COLLATE
category in the current locale.
-.PP
+.P
(iv) Named character classes, like
-.PP
+.P
.nf
[:alnum:] [:alpha:] [:blank:] [:cntrl:]
[:digit:] [:graph:] [:lower:] [:print:]
[:punct:] [:space:] [:upper:] [:xdigit:]
.fi
-.PP
+.P
so that one can say "\fI[[:lower:]]\fP" instead of "\fI[a\-z]\fP", and have
things work in Denmark, too, where there are three letters past \[aq]z\[aq]
in the alphabet.
.B LC_CTYPE
category
in the current locale.
-.PP
+.P
(v) Collating symbols, like "\fI[.ch.]\fP" or "\fI[.a-acute.]\fP",
where the string between "\fI[.\fP" and "\fI.]\fP" is a collating
element defined for the current locale.
Note that this may
be a multicharacter element.
-.PP
+.P
(vi) Equivalence class expressions, like "\fI[=a=]\fP",
where the string between "\fI[=\fP" and "\fI=]\fP" is any collating
element from its equivalence class, as defined for the
.BR proc (5),
.BR file\-hierarchy (7),
.BR mount (8)
-.PP
+.P
The Filesystem Hierarchy Standard
Hostnames are domains, where a domain is a hierarchical, dot-separated
list of subdomains; for example, the machine "monet", in the "example"
subdomain of the "com" domain would be represented as "monet.example.com".
-.PP
+.P
Each element of the hostname must be from 1 to 63 characters long and the
entire hostname, including the dots, can be at most 253 characters long.
Valid characters for hostnames are
.IR 9 ,
and the hyphen (\-).
A hostname may not start with a hyphen.
-.PP
+.P
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
.BR getaddrinfo (3)
or the obsolete
.BR gethostbyname (3).)
-.PP
+.P
Hostnames are resolved by the NSS framework in glibc according
to the
.B hosts
(in the
.B dns
NSS service module) resolves them in the following fashion.
-.PP
+.P
If the name consists of a single component, that is, contains no dot,
and if the environment variable
.B HOSTALIASES
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.
-.PP
+.P
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.
-.PP
+.P
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,
.BR resolver (5),
.BR mailaddr (7),
.BR named (8)
-.PP
+.P
.UR http://www.ietf.org\:/rfc\:/rfc1123.txt
IETF RFC\ 1123
.UE
-.PP
+.P
.UR http://www.ietf.org\:/rfc\:/rfc1178.txt
IETF RFC\ 1178
.UE
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.
-.PP
+.P
A user protocol may receive ICMP packets for all local sockets by opening
a raw socket with the protocol
.BR IPPROTO_ICMP .
socket option.
ICMP packets are always processed by the kernel too, even
when passed to a user socket.
-.PP
+.P
Linux limits the rate of ICMP error packets to each destination.
.B ICMP_REDIRECT
and
I Address Mask Reply
.TE
.RE
-.PP
+.P
The bits marked with an asterisk are rate limited by default
(see the default mask above).
.TP
Support for the
.B ICMP_ADDRESS
request was removed in Linux 2.2.
-.PP
+.P
Support for
.B ICMP_SOURCE_QUENCH
was removed in Linux 2.2.
raw sockets, this feature
should not be relied on in portable programs.
.\" not really true ATM
-.\" .PP
+.\" .P
.\" Linux ICMP should be compliant to RFC 1122.
-.PP
+.P
.B ICMP_REDIRECT
packets are not sent when Linux is not acting as a router.
They are also accepted only from the old gateway defined in the
routing table and the redirect routes are expired after some time.
-.PP
+.P
The 64-bit timestamp returned by
.B ICMP_TIMESTAMP
is in milliseconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC).
-.PP
+.P
Linux ICMP internally uses a raw socket to send ICMPs.
This raw socket may appear in
.BR netstat (8)
.SH SEE ALSO
.BR ip (7),
.BR rdisc (8)
-.PP
+.P
RFC\ 792 for a description of the ICMP protocol.
which returns a
.I statx
structure.
-.PP
+.P
The following is a list of the information typically found in,
or associated with, the file inode,
with the names of the corresponding structure fields returned by
This is the file's last status change timestamp.
It is changed by writing or by setting inode information
(i.e., owner, group, link count, mode, etc.).
-.PP
+.P
The timestamp fields report time measured with a zero point at the
.IR Epoch ,
1970-01-01 00:00:00 +0000, UTC (see
.BR time (7)).
-.PP
+.P
Nanosecond timestamps are supported on XFS, JFS, Btrfs, and
ext4 (since Linux 2.6.23).
.\" commit ef7f38359ea8b3e9c7f2cae9a4d4935f55ca9e80
the
.I statx.stx_mode
field) contains the file type and mode.
-.PP
+.P
POSIX refers to the
.I stat.st_mode
bits corresponding to the mask
.I file mode bits
and the least significant 9 bits (0777) as the
.IR "file permission bits" .
-.PP
+.P
The following mask values are defined for the file type:
.in +4n
.TS
S_IFIFO 0010000 FIFO
.TE
.in
-.PP
+.P
Thus, to test for a regular file (for example), one could write:
-.PP
+.P
.in +4n
.EX
stat(pathname, &sb);
}
.EE
.in
-.PP
+.P
Because tests of the above form are common, additional
macros are defined by POSIX to allow the test of the file type in
.I st_mode
.BR S_ISSOCK (m)
socket? (Not in POSIX.1-1996.)
.RE
-.PP
+.P
The preceding code snippet could thus be rewritten as:
-.PP
+.P
.in +4n
.EX
stat(pathname, &sb);
}
.EE
.in
-.PP
+.P
The definitions of most of the above file type test macros
are provided if any of the following feature test macros is defined:
.B _BSD_SOURCE
are provided if
.B _XOPEN_SOURCE
is defined.
-.PP
+.P
The definition of
.B S_IFSOCK
can also be exposed either by defining
.B _XOPEN_SOURCE
and
.BR _XOPEN_SOURCE_EXTENDED .
-.PP
+.P
The definition of
.BR S_ISSOCK ()
is exposed if any of the following feature test macros is defined:
.B _XOPEN_SOURCE
and
.BR _XOPEN_SOURCE_EXTENDED .
-.PP
+.P
The following mask values are defined for
the file mode component of the
.I st_mode
T}
.TE
.in
-.PP
+.P
The set-group-ID bit
.RB ( S_ISGID )
has several special uses.
.RB ( S_IXGRP )
set,
the set-group-ID bit indicates mandatory file/record locking.
-.PP
+.P
The sticky bit
.RB ( S_ISVTX )
on a directory means that a file
POSIX.1-2008.
.SH HISTORY
POSIX.1-2001.
-.PP
+.P
POSIX.1-1990 did not describe the
.BR S_IFMT ,
.BR S_IFSOCK ,
the macros
.BR S_ISDIR ()
and so on.
-.PP
+.P
The
.BR S_ISLNK ()
and
macros were not in
POSIX.1-1996;
the former is from SVID 4, the latter from SUSv2.
-.PP
+.P
UNIX\ V7 (and later systems) had
.BR S_IREAD ,
.BR S_IWRITE ,
or to monitor directories.
When a directory is monitored, inotify will return events
for the directory itself, and for files inside the directory.
-.PP
+.P
The following system calls are used with this API:
.IP \[bu] 3
.BR inotify_init (2)
the underlying object and its resources are
freed for reuse by the kernel;
all associated watches are automatically freed.
-.PP
+.P
With careful programming,
an application can use inotify to efficiently monitor and cache
the state of a set of filesystem objects.
.BR EINTR ;
see
.BR signal (7)).
-.PP
+.P
Each successful
.BR read (2)
returns a buffer containing one or more of the following structures:
-.PP
+.P
.in +4n
.EX
struct inotify_event {
};
.EE
.in
-.PP
+.P
.I wd
identifies the watch for which this event occurs.
It is one of the watch descriptors returned by a previous call to
.BR inotify_add_watch (2).
-.PP
+.P
.I mask
contains bits that describe the event that occurred (see below).
-.PP
+.P
.I cookie
is a unique integer that connects related events.
Currently, this is used only for rename events, and
For all other event types,
.I cookie
is set to 0.
-.PP
+.P
The
.I name
field is present only when an event is returned
This filename is null-terminated,
and may include further null bytes (\[aq]\e0\[aq])
to align subsequent reads to a suitable address boundary.
-.PP
+.P
The
.I len
field counts all of the bytes in
.I inotify_event
structure is thus
.IR "sizeof(struct inotify_event)+len" .
-.PP
+.P
The behavior when the buffer given to
.BR read (2)
is too small to return information about the next event depends
fails with the error
.BR EINVAL .
Specifying a buffer of size
-.PP
+.P
.in +4n
.EX
sizeof(struct inotify_event) + NAME_MAX + 1
.EE
.in
-.PP
+.P
will be sufficient to read at least one event.
.SS inotify events
The
.BR IN_OPEN " (*)"
File or directory was opened.
.RE
-.PP
+.P
Inotify monitoring is inode-based: when monitoring a file
(but not when monitoring the directory containing a file),
an event can be generated for activity on any link to the file
(in the same or a different directory).
-.PP
+.P
When monitoring a directory:
.IP \[bu] 3
the events marked above with an asterisk (*) can occur both
.IP \[bu]
the events marked with a plus sign (+) occur only for objects
inside the directory (not for the directory itself).
-.PP
+.P
.IR Note :
when monitoring a directory,
events are not generated for the files inside the directory
when the events are performed via a pathname (i.e., a link)
that lies outside the monitored directory.
-.PP
+.P
When events are generated for objects inside a watched directory, the
.I name
field in the returned
.I inotify_event
structure identifies the name of the file within the directory.
-.PP
+.P
The
.B IN_ALL_EVENTS
macro is defined as a bit mask of all of the above events.
.I mask
argument when calling
.BR inotify_add_watch (2).
-.PP
+.P
Two additional convenience macros are defined:
.RS 4
.TP
Equates to
.BR "IN_CLOSE_WRITE | IN_CLOSE_NOWRITE" .
.RE
-.PP
+.P
The following further bits can be specified in
.I mask
when calling
.BR inotify_add_watch (2)
without this flag may clobber existing watch masks.
.RE
-.PP
+.P
The following bits may be set in the
.I mask
field returned by
and
.IR dir/myfile .
.RE
-.PP
+.P
Suppose an application is watching the directories
.I dir1
and
.I cookie
value.
.RE
-.PP
+.P
Suppose that
.I dir1/xx
and
event for
.IR dir1 .
.RE
-.PP
+.P
Suppose an application is watching the directory
.I dir
and (the empty) directory
and
.BR epoll (7).
When an event is available, the file descriptor indicates as readable.
-.PP
+.P
Since Linux 2.6.25,
signal-driven I/O notification is available for inotify file descriptors;
see the discussion of
.B POLLIN
is set in
.IR si_band .
-.PP
+.P
If successive output inotify events produced on the
inotify file descriptor are identical (same
.IR wd ,
This reduces the amount of kernel memory required for the event queue,
but also means that an application can't use inotify to reliably count
file events.
-.PP
+.P
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.
-.PP
+.P
The set of watch descriptors that is being monitored via
an inotify file descriptor can be viewed via the entry for
the inotify file descriptor in the process's
way for a process that is monitoring events via inotify
to distinguish events that it triggers
itself from those that are triggered by other processes.
-.PP
+.P
Inotify reports only events that a user-space program triggers through
the filesystem API.
As a result, it does not catch remote events that occur
and
.I /dev/pts
are not monitorable with inotify.
-.PP
+.P
The inotify API does not report file accesses and modifications that
may occur because of
.BR mmap (2),
.BR msync (2),
and
.BR munmap (2).
-.PP
+.P
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.
-.PP
+.P
The inotify API identifies events via watch descriptors.
It is the application's responsibility to cache a mapping
(if one is needed) between watch descriptors and pathnames.
Be aware that directory renamings may affect multiple cached pathnames.
-.PP
+.P
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.
-.PP
+.P
If monitoring an entire directory subtree,
and a new subdirectory is created in that tree or an existing directory
is renamed into that tree,
Therefore, you may want to scan the contents of the subdirectory
immediately after adding the watch (and, if desired,
recursively add watches for any subdirectories that it contains).
-.PP
+.P
Note that the event queue can overflow.
In this case, events are lost.
Robust applications should handle the possibility of
create a new inotify file descriptor,
and then re-create watches and cache entries
for the objects to be monitored.)
-.PP
+.P
If a filesystem is mounted on top of a monitored directory,
no event is generated, and no events are generated
for objects immediately under the new mount point.
.BR rename (2)
can be matched up via their shared cookie value.
However, the task of matching has some challenges.
-.PP
+.P
These two events are usually consecutive in the event stream available
when reading from the inotify file descriptor.
However, this is not guaranteed.
has appeared, but the
.B IN_MOVED_TO
has not.
-.PP
+.P
Matching up the
.B IN_MOVED_FROM
and
the watch descriptors in any pending events.
(Re-creating the inotify file descriptor and rebuilding the cache may
be useful to deal with this scenario.)
-.PP
+.P
Applications should also allow for the possibility that the
.B IN_MOVED_FROM
event was the last event that could fit in the buffer
generate
.B IN_MODIFY
events.
-.PP
+.P
.\" FIXME . kernel commit 611da04f7a31b2208e838be55a42c7a1310ae321
.\" implies that unmount events were buggy since Linux 2.6.11 to Linux 2.6.36
.\"
.B IN_ONESHOT
.I mask
flag does not work.
-.PP
+.P
As originally designed and implemented, the
.B IN_ONESHOT
flag did not cause an
since Linux 2.6.36, an
.B IN_IGNORED
event is generated in this case.
-.PP
+.P
Before Linux 2.6.25,
.\" commit 1c17d18e3775485bf1e0ce79575eb637a94494a2
the kernel code that was intended to coalesce successive identical events
instead checked if the most recent event could be coalesced with the
.I oldest
unread event.
-.PP
+.P
When a watch descriptor is removed by calling
.BR inotify_rm_watch (2)
(or because a watch file is deleted or the filesystem
.BR IN_CLOSE_NOWRITE ,
and
.BR IN_CLOSE_WRITE .
-.PP
+.P
The following output was recorded while editing the file
.I /home/user/temp/foo
and listing directory
.BR read (2),
.BR stat (2),
.BR fanotify (7)
-.PP
+.P
.I Documentation/filesystems/inotify.txt
in the Linux kernel source tree
.\" .B #include <linux/errqueue.h> -- never include <linux/foo.h>
.B #include <netinet/in.h>
.B #include <netinet/ip.h> \fR/* superset of previous */
-.PP
+.P
.IB tcp_socket " = socket(AF_INET, SOCK_STREAM, 0);"
.IB udp_socket " = socket(AF_INET, SOCK_DGRAM, 0);"
.IB raw_socket " = socket(AF_INET, SOCK_RAW, " protocol ");"
.B ip
contains a level 2 multicasting implementation conforming to RFC\ 1112.
It also contains an IP router including a packet filter.
-.PP
+.P
The programming interface is BSD-sockets compatible.
For more information on sockets, see
.BR socket (7).
-.PP
+.P
An IP socket is created using
.BR socket (2):
-.PP
+.P
.in +4n
.EX
socket(AF_INET, socket_type, protocol);
.EE
.in
-.PP
+.P
Valid socket types include
.B SOCK_STREAM
to open a stream socket,
to open a
.BR raw (7)
socket to access the IP protocol directly.
-.PP
+.P
.I protocol
is the IP protocol in the IP header to be received or sent.
Valid values for
for
.BR udplite (7)
datagram sockets.
-.PP
+.P
For
.B SOCK_RAW
you may specify a valid IANA IP protocol defined in
RFC\ 1700 assigned numbers.
-.PP
+.P
When a process wants to receive new incoming packets or connections, it
should bind a socket to a local interface address using
.BR bind (2).
to a random free port or to a usable shared port with the local address
set to
.BR INADDR_ANY .
-.PP
+.P
A TCP local socket address that has been bound is unavailable for
some time after closing, unless the
.B SO_REUSEADDR
On raw sockets
.I sin_port
is set to the IP protocol.
-.PP
+.P
.in +4n
.EX
struct sockaddr_in {
};
.EE
.in
-.PP
+.P
.I sin_family
is always set to
.BR AF_INET .
.BR tcp (7)
and
.BR udp (7).
-.PP
+.P
.I sin_addr
is the IP host address.
The
.BR inet_makeaddr (3)
library functions or directly with the name resolver (see
.BR gethostbyname (3)).
-.PP
+.P
IPv4 addresses are divided into unicast, broadcast,
and multicast addresses.
Unicast addresses specify a single interface of a host,
In the current implementation, connection-oriented sockets are allowed
to use only unicast addresses.
.\" Leave a loophole for XTP @)
-.PP
+.P
Note that the address and the port are always stored in
network byte order.
In particular, this means that you need to call
.\" commit 58fee5fc83658aaacf60246aeab738946a9ba516
it is treated as an ordinary unicast address
and can be assigned to an interface.
-.PP
+.P
Internet standards have traditionally also reserved various addresses
for particular uses, though Linux no longer treats
some of these specially.
.BR IPPROTO_IP .
.\" or SOL_IP on Linux
A boolean integer flag is zero when it is false, otherwise true.
-.PP
+.P
When an invalid socket option is specified,
.BR getsockopt (2)
and
.BR socket (7)
apply to
.BR ip .
-.PP
+.P
Ioctls to configure generic device parameters are described in
.BR netdevice (7).
.\" FIXME Add a discussion of multicasting
.TP
.B ESOCKTNOSUPPORT
The socket is not configured or an unknown socket type was requested.
-.PP
+.P
Other errors may be generated by the overlaying protocols; see
.BR tcp (7),
.BR raw (7),
are Linux-specific.
.\" IP_XFRM_POLICY is Linux-specific
.\" IP_IPSEC_POLICY is a nonstandard extension, also present on some BSDs
-.PP
+.P
Be very careful with the
.B SO_BROADCAST
option \- it is not privileged in Linux.
using the more modern multicast approach
to communicating with an open-ended
group of hosts on the local network.
-.PP
+.P
Some other BSD sockets implementations provide
.B IP_RCVDSTADDR
and
Linux has the more general
.B IP_PKTINFO
for the same task.
-.PP
+.P
Some BSD sockets implementations also provide an
.B IP_RECVTTL
option, but an ancillary message with type
This is different from the
.B IP_TTL
option used in Linux.
-.PP
+.P
Using the
.B SOL_IP
socket options level isn't portable; BSD-based stacks use the
.B IPPROTO_IP
level.
-.PP
+.P
.B INADDR_ANY
(0.0.0.0) and
.B INADDR_BROADCAST
.BR sockaddr_pkt .
.SH BUGS
There are too many inconsistent error values.
-.PP
+.P
The error used to diagnose exhaustion of the ephemeral port range differs
across the various system calls
.RB ( connect (2),
.BR listen (2),
.BR sendto (2))
that can assign ephemeral ports.
-.PP
+.P
The ioctls to configure IP-specific interface options and ARP tables are
not described.
-.\" .PP
+.\" .P
.\" Some versions of glibc forget to declare
.\" .IR in_pktinfo .
.\" Workaround currently is to copy it into your program from this man page.
-.PP
+.P
Receiving the original destination address with
.B MSG_ERRQUEUE
in
.BR tcp (7),
.BR udp (7),
.BR ip (8)
-.PP
+.P
The kernel source file
.IR Documentation/networking/ip\-sysctl.txt .
-.PP
+.P
RFC\ 791 for the original IP specification.
RFC\ 1122 for the IPv4 host requirements.
RFC\ 1812 for the IPv4 router requirements.
The common characteristic of these IPC mechanisms is that IPC
objects are identified by mechanisms other than filesystem
pathnames.
-.PP
+.P
Each IPC namespace has its own set of System V IPC identifiers and
its own POSIX message queue filesystem.
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.
-.PP
+.P
The following
.I /proc
interfaces are distinct in each IPC namespace:
.IP \[bu]
The System V IPC interfaces in
.IR /proc/sysvipc .
-.PP
+.P
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.
-.PP
+.P
Use of IPC namespaces requires a kernel that is configured with the
.B CONFIG_IPC_NS
option.
.nf
.B #include <sys/socket.h>
.B #include <netinet/in.h>
-.PP
+.P
.IB tcp6_socket " = socket(AF_INET6, SOCK_STREAM, 0);"
.IB raw6_socket " = socket(AF_INET6, SOCK_RAW, " protocol ");"
.IB udp6_socket " = socket(AF_INET6, SOCK_DGRAM, " protocol ");"
The interface
is based on the BSD sockets interface; see
.BR socket (7).
-.PP
+.P
The IPv6 API aims to be mostly compatible with the
IPv4 API (see
.BR ip (7)).
Only differences are described in this man page.
-.PP
+.P
To bind an
.B AF_INET6
socket to any process, the local address should be copied from the
.B IN6ADDR_ANY_INIT
may also be used, which expands to a constant expression.
Both of them are in network byte order.
-.PP
+.P
The IPv6 loopback address (::1) is available in the global
.I in6addr_loopback
variable.
For initializations,
.B IN6ADDR_LOOPBACK_INIT
should be used.
-.PP
+.P
IPv4 connections can be handled with the v6 API by using the
v4-mapped-on-v6 address type;
thus a program needs to support only this API type to
support both protocols.
This is handled transparently by the address
handling functions in the C library.
-.PP
+.P
IPv4 and IPv6 share the local port space.
When you get an IPv4 connection
or packet to an IPv6 socket,
};
.EE
.in
-.PP
+.P
.I sin6_family
is always set to
.BR AF_INET6 ;
.I sin6_scope_id
contains the interface index (see
.BR netdevice (7))
-.PP
+.P
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 an IPv4 host, and other reserved address types.
-.PP
+.P
The address notation for IPv6 is a group of 8 4-digit hexadecimal
numbers, separated with a \[aq]:\[aq].
\&"::" stands for a string of 0 bits.
Special addresses are ::1 for loopback and ::FFFF:<IPv4 address>
for IPv4-mapped-on-IPv6.
-.PP
+.P
The port space of IPv6 is shared with IPv4.
.SS Socket options
IPv6 supports some protocol-specific socket options that can be set with
into other structures may not be.
This is not
a problem for 32-bit hosts like i386.
-.PP
+.P
The
.I sin6_flowinfo
field is new in Linux 2.4.
need to be changed to use
.I struct sockaddr_storage
for that instead.
-.PP
+.P
.BR SOL_IP ,
.BR SOL_IPV6 ,
.BR SOL_ICMPV6 ,
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.
-.PP
+.P
IPSec support for EH and AH headers is missing.
-.PP
+.P
Flow label management is not complete and not documented here.
-.PP
+.P
This man page is not complete.
.SH SEE ALSO
.BR cmsg (3),
.BR ip (7)
-.PP
+.P
RFC\ 2553: IPv6 BASIC API;
Linux tries to be compliant to this.
RFC\ 2460: IPv6 specification.
modification of the kernel image and to prevent access to security and
cryptographic data located in kernel memory, whilst still permitting driver
modules to be loaded.
-.PP
+.P
If a prohibited or restricted feature is accessed or used, the kernel will emit
a message that looks like:
-.PP
+.P
.in +4n
.EX
Lockdown: X: Y is restricted, see man kernel_lockdown.7
.EE
.in
-.PP
+.P
where X indicates the process name and Y indicates what is restricted.
-.PP
+.P
On an EFI-enabled x86 or arm64 machine, lockdown will be automatically enabled
if the system boots in EFI Secure Boot mode.
.\"
use restricted.
This includes special device files and kernel services that allow
direct access of the kernel image:
-.PP
+.P
.RS
/dev/mem
.br
.br
kprobes
.RE
-.PP
+.P
and the ability to directly configure and control devices, so as to prevent
the use of a device to access or modify a kernel image:
.IP \[bu] 3
The specification of the ACPI RDSP address.
.IP \[bu]
The use of ACPI custom methods.
-.PP
+.P
Certain facilities are restricted:
.IP \[bu] 3
Only validly signed modules may be loaded (waived if the module file being
is primarily a way for various kernel components
to retain or cache security data,
authentication keys, encryption keys, and other data in the kernel.
-.PP
+.P
System call interfaces are provided so that user-space programs can manage
those objects and also use the facility for their own purposes; see
.BR add_key (2),
.BR request_key (2),
and
.BR keyctl (2).
-.PP
+.P
A library and some user-space utilities are provided to allow access to the
facility.
See
.\" commit 13100a72f40f5748a04017e0ab3df4cf27c809ef
the payload data is encrypted when stored in tmpfs,
thereby preventing it from being written unencrypted into swap space.
-.PP
+.P
There are more specialized key types available also,
but they aren't discussed here
because they aren't intended for normal user-space use.
-.PP
+.P
Key type names
that begin with a period (\[aq].\[aq]) are reserved to the implementation.
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
Keys may be linked to by multiple keyrings.
Keyrings may be considered as analogous to UNIX directories
where each directory contains a set of hard links to files.
-.PP
+.P
Various operations (system calls) may be applied only to keyrings:
.TP
Adding
form the branches and non-keyrings the leaves.
This tree may be searched for a key matching
a particular type and description.
-.PP
+.P
See
.BR keyctl_clear (3),
.BR keyctl_link (3),
To prevent a key from being garbage collected,
it must be anchored to keep its reference count elevated
when it is not in active use by the kernel.
-.PP
+.P
Keyrings are used to anchor other keys:
each link is a reference on a key.
Note that keyrings themselves are just keys and
are also subject to the same anchoring requirement to prevent
them being garbage collected.
-.PP
+.P
The kernel makes available a number of anchor keyrings.
Note that some of these keyrings will be created only when first accessed.
.TP
.IP
These special keyrings are usually closed to direct alteration
by user space.
-.PP
+.P
An originally planned "group keyring",
for storing keys associated with each GID known to the kernel,
is not so far implemented, is unlikely to be implemented.
.BR request_key (2)),
then it also possesses the requester's keyrings as in
rule (1) as if it were the requester.
-.PP
+.P
Note that possession is not a fundamental property of a key,
but must rather be calculated each time the key is needed.
-.PP
+.P
Possession is designed to allow set-user-ID programs run from, say
a user's shell to access the user's keys.
Granting permissions to the key possessor while denying them
to the key owner and group allows the prevention of access to keys
on the basis of UID and GID matches.
-.PP
+.P
When it creates the session keyring,
.BR pam_keyinit (8)
adds a link to the
A security label
.IP \[bu]
A permissions mask
-.PP
+.P
The permissions mask contains four sets of rights.
The first three sets are mutually exclusive.
One and only one will be in force for a particular access check.
.I other
The set specifies the rights granted
if neither the key's user ID nor group ID matched.
-.PP
+.P
The fourth set of rights is:
.TP
.I possessor
The set specifies the rights granted
if a key is determined to be possessed by the caller.
-.PP
+.P
The complete set of rights for a key is the union of whichever
of the first three sets is applicable plus the fourth set
if the key is possessed.
-.PP
+.P
The set of rights that may be granted in each of the four masks
is as follows:
.TP
.I setattr
The ownership details and security label of the key may be changed,
the key's expiration time may be set, and the key may be revoked.
-.PP
+.P
In addition to access rights, any active Linux Security Module (LSM) may
prevent access to a key if its policy so dictates.
A key may be given a
security label or other attribute by the LSM;
this label is retrievable via
.BR keyctl_get_security (3).
-.PP
+.P
See
.BR keyctl_chown (3),
.BR keyctl_describe (3),
access for user-space applications to find a key.
(Internally, the kernel has something similar available
for use by internal components that make use of keys.)
-.PP
+.P
The search algorithm works as follows:
.IP (1) 5
The process keyrings are searched in the following order: the
then the first noted error state is returned; otherwise, an
.B ENOKEY
error is returned.
-.PP
+.P
It is also possible to search a specific keyring, in which case only steps
(3) to (6) apply.
-.PP
+.P
See
.BR request_key (2)
and
argument, create a new key and then upcall to user space to
instantiate the key.
This allows keys to be created on an as-needed basis.
-.PP
+.P
Typically,
this will involve the kernel creating a new process that executes the
.BR request\-key (8)
program, which will then execute the appropriate handler based on its
configuration.
-.PP
+.P
The handler is passed a special authorization key that allows it
and only it to instantiate the new key.
This is also used to permit searches performed by the
handler program to also search the requester's keyrings.
-.PP
+.P
See
.BR request_key (2),
.BR keyctl_assume_authority (3),
operation.)
.IP
The default value in this file is 259200 (i.e., 3 days).
-.PP
+.P
The following files (which are writable by privileged processes)
are used to enforce quotas on the number of keys
and number of bytes of data that can be stored in key payloads:
.IP
.\"738c5d190f6540539a04baf36ce21d46b5da04bd
The default value in this file is 1,000,000 (200 before Linux 3.17).
-.PP
+.P
With respect to keyrings,
note that each link in a keyring consumes 4 bytes of the keyring payload.
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SS Users
The Linux key-management facility has a number of users and usages,
but is not limited to those that already exist.
-.PP
+.P
In-kernel users of this facility include:
.TP
Network filesystems - DNS
Module verification
The kernel build process can be made to cryptographically sign modules.
That signature is then checked when a module is loaded.
-.PP
+.P
User-space users of this facility include:
.TP
Kerberos key storage
.BR user\-session\-keyring (7),
.BR pam_keyinit (8),
.BR request\-key (8)
-.PP
+.P
The kernel source files
.I Documentation/crypto/asymmetric\-keys.txt
and under
This kind of sandbox is expected to help mitigate
the security impact of bugs,
and unexpected or malicious behaviors in applications.
-.PP
+.P
A Landlock security policy is a set of access rights
(e.g., open a file in read-only, make a directory, etc.)
tied to a file hierarchy.
.IP \[bu]
.BR landlock_restrict_self (2)
enforces a ruleset on the calling thread.
-.PP
+.P
To be able to use these system calls,
the running kernel must support Landlock and
it must be enabled at boot time.
and
.BR landlock_create_ruleset (2)
for more context.
-.PP
+.P
A file can only receive these access rights:
.TP
.B LANDLOCK_ACCESS_FS_EXECUTE
and
.BR LANDLOCK_ACCESS_FS_WRITE_FILE .
This access right is available since the third version of the Landlock ABI.
-.PP
+.P
A directory can receive access rights related to files or directories.
The following access right is applied to the directory itself,
and the directories beneath it:
.TP
.B LANDLOCK_ACCESS_FS_READ_DIR
Open a directory or list its content.
-.PP
+.P
However,
the following access rights only apply to the content of a directory,
not the directory itself:
potentially other rulesets already restricting this thread.
A sandboxed thread can then safely add more constraints to itself with a
new enforced ruleset.
-.PP
+.P
One policy layer grants access to a file path
if at least one of its rules encountered on the path grants the access.
A sandboxed thread can only access a file path
(cf.
.BR mount_namespaces (7))
but not with OverlayFS.
-.PP
+.P
A bind mount mirrors a source file hierarchy to a destination.
The destination hierarchy is then composed of the exact same files,
on which Landlock rules can be tied,
which means that they can restrict access to
multiple file hierarchies at the same time,
whether these hierarchies are the result of bind mounts or not.
-.PP
+.P
An OverlayFS mount point consists of upper and lower layers.
These layers are combined in a merge directory, result of the mount point.
This merge hierarchy may include files from the upper and lower layers,
but they will not be automatically applied to other sibling threads
(unlike POSIX thread credential changes, cf.
.BR nptl (7)).
-.PP
+.P
When a thread sandboxes itself,
we have the guarantee that the related security policy
will stay enforced on all this thread's descendants.
both change the contents of a file and sometimes overlap in
non-intuitive ways.
It is recommended to always specify both of these together.
-.PP
+.P
A particularly surprising example is
.BR creat (2).
The name suggests that this system call requires
the rights to create and write files.
However, it also requires the truncate right
if an existing file under the same name is already present.
-.PP
+.P
It should also be noted that truncating files does not require the
.B LANDLOCK_ACCESS_FS_WRITE_FILE
right.
.BR open (2)
with the flags
.IR "O_RDONLY\ |\ O_TRUNC" .
-.PP
+.P
When opening a file, the availability of the
.B LANDLOCK_ACCESS_FS_TRUNCATE
right is associated with the newly created file descriptor
and
.BR write (2)
calls.
-.PP
+.P
As a consequence,
it is possible to have multiple open file descriptors for the same file,
where one grants the right to truncate the file and the other does not.
even when these processes do not have an enforced Landlock ruleset.
.SH VERSIONS
Landlock was introduced in Linux 5.13.
-.PP
+.P
To determine which Landlock features are available,
users should query the Landlock ABI version:
.TS
_ _ _
3 6.2 LANDLOCK_ACCESS_FS_TRUNCATE
.TE
-.PP
+.P
Users should use the Landlock ABI version rather than the kernel version
to determine which features are available.
The mainline kernel versions listed here are only included for orientation.
Kernels from other sources may contain backported features,
and their version numbers may not match.
-.PP
+.P
To query the running kernel's Landlock ABI version,
programs may pass the
.B LANDLOCK_CREATE_RULESET_VERSION
flag to
.BR landlock_create_ruleset (2).
-.PP
+.P
When building fallback mechanisms for compatibility with older kernels,
users are advised to consider the special semantics of the
.B LANDLOCK_ACCESS_FS_REFER
Future Landlock evolutions will enable to restrict them.
.SH EXAMPLES
We first need to create the ruleset that will contain our rules.
-.PP
+.P
For this example,
the ruleset will contain rules that only allow read actions,
but write actions will be denied.
See the
.B DESCRIPTION
section for the description of filesystem actions.
-.PP
+.P
.in +4n
.EX
struct landlock_ruleset_attr attr = {0};
LANDLOCK_ACCESS_FS_TRUNCATE;
.EE
.in
-.PP
+.P
To be compatible with older Linux versions,
we detect the available Landlock ABI version,
and only use the available subset of access rights:
-.PP
+.P
.in +4n
.EX
/*
attr.handled_access_fs &= landlock_fs_access_rights[abi \- 1];
.EE
.in
-.PP
+.P
The available access rights for each ABI version are listed in the
.B VERSIONS
section.
-.PP
+.P
If our program needed to create hard links
or rename files between different directories
.RB ( LANDLOCK_ACCESS_FS_REFER ),
if the program needed to do file reparenting,
and if only Landlock ABI version 1 was available,
we could not restrict the process.
-.PP
+.P
Now that the ruleset attributes are determined,
we create the Landlock ruleset
and acquire a file descriptor as a handle to it,
using
.BR landlock_create_ruleset (2):
-.PP
+.P
.in +4n
.EX
ruleset_fd = landlock_create_ruleset(&attr, sizeof(attr), 0);
}
.EE
.in
-.PP
+.P
We can now add a new rule to the ruleset through the ruleset's file descriptor.
The requested access rights must be a subset of the access rights
which were specified in
.I attr.handled_access_fs
at ruleset creation time.
-.PP
+.P
In this example, the rule will only allow reading the file hierarchy
.IR /usr .
Without another rule, write actions would then be denied by the ruleset.
flag and fill the
.I struct landlock_path_beneath_attr
with this file descriptor.
-.PP
+.P
.in +4n
.EX
struct landlock_path_beneath_attr path_beneath = {0};
}
.EE
.in
-.PP
+.P
We now have a ruleset with one rule allowing read access to
.I /usr
while denying all other handled accesses for the filesystem.
The next step is to restrict the current thread from gaining more
privileges
(e.g., thanks to a set-user-ID binary).
-.PP
+.P
.in +4n
.EX
if (prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0)) {
}
.EE
.in
-.PP
+.P
The current thread is now ready to sandbox itself with the ruleset.
-.PP
+.P
.in +4n
.EX
if (landlock_restrict_self(ruleset_fd, 0)) {
close(ruleset_fd);
.EE
.in
-.PP
+.P
If the
.BR landlock_restrict_self (2)
system call succeeds, the current thread is now restricted and
only adding more restrictions is allowed.
These threads are now in a new Landlock domain,
merge of their parent one (if any) with the new ruleset.
-.PP
+.P
Full working code can be found in
.UR https://git.kernel.org/\:pub/\:scm/\:linux/\:kernel/\:git/\:stable/\:linux.git/\:tree/\:samples/\:landlock/\:sandboxer.c
.UE
.BR landlock_create_ruleset (2),
.BR landlock_add_rule (2),
.BR landlock_restrict_self (2)
-.PP
+.P
.UR https://landlock.io/
.UE
(There were earlier 0.x releases.)
The next major release of glibc was 2.0,
at the beginning of 1997.
-.PP
+.P
The pathname
.I /lib/libc.so.6
(or something similar)
.IR libc.so.5 .
For a while,
Linux libc was the standard C library in many Linux distributions.
-.PP
+.P
However,
notwithstanding the original motivations of the Linux libc effort,
by the time glibc 2.0 was released
To avoid any confusion with Linux libc versions,
glibc 2.0 and later used the shared library soname
.IR libc.so.6 .
-.PP
+.P
Since the switch from Linux libc to glibc 2.0 occurred long ago,
.I man-pages
no longer takes care to document Linux libc details.
conventions, and so on.
A program needs to be able to determine its locale
and act accordingly to be portable to different cultures.
-.PP
+.P
The header
.I <locale.h>
declares data types, functions, and macros which are useful in this
task.
-.PP
+.P
The functions it declares are
.BR setlocale (3)
to set the current locale, and
.BR localeconv (3)
to get information about number formatting.
-.PP
+.P
There are different categories for locale information a program might
need; they are declared as macros.
Using them as the first argument
.TP
.B LC_ALL
All of the above.
-.PP
+.P
If the second argument to
.BR setlocale (3)
is an empty string,
the value of
.B LANG
is used.
-.PP
+.P
Values about local numeric formatting is made available in a
.I struct lconv
returned by the
.BR localeconv (3)
function, which has the following declaration:
-.PP
+.P
.in +4n
.EX
struct lconv {
These extensions are designed to address the problem that
the traditional locale APIs do not mix well with multithreaded applications
and with applications that must deal with multiple locales.
-.PP
+.P
The extensions take the form of new functions for creating and
manipulating locale objects
.RB ( newlocale (3),
This manual page gives a brief introduction to SMTP mail addresses,
as used on the Internet.
These addresses are in the general format
-.PP
+.P
.in +4n
.EX
user@domain
.EE
.in
-.PP
+.P
where a domain is a hierarchical dot-separated list of subdomains.
These examples are valid forms of the same address:
-.PP
+.P
.in +4n
.EX
john.doe@monet.example.com
john.doe@monet.example.com (John Doe)
.EE
.in
-.PP
+.P
The domain part ("monet.example.com") 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.
-.PP
+.P
The local part ("john.doe") is often a username,
but its meaning is defined by the local software.
Sometimes it is case sensitive,
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:
-.PP
+.P
.in +4n
.EX
"surname/admd=telemail/c=us/o=hp/prmd=hp"@some.where
I2461572@some.where
.EE
.in
-.PP
+.P
(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.)
-.PP
+.P
The real-name part ("John Doe") 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 ".":
-.PP
+.P
.in +4n
.EX
"John Q. Doe" <john.doe@monet.example.com>
several hosts to get it to its final destination.
Addresses which show these relays are termed "route-addrs".
These use the syntax:
-.PP
+.P
.in +4n
.EX
<@hosta,@hostb:user@hostc>
.EE
.in
-.PP
+.P
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.
-.PP
+.P
Route-addrs are very unusual now.
They occur sometimes in old mail archives.
It is generally possible to ignore all but the "user@hostc"
.BR aliases (5),
.BR forward (5),
.BR sendmail (8)
-.PP
+.P
.UR http://www.ietf.org\:/rfc\:/rfc5322.txt
IETF RFC\ 5322
.UE
The first command in a man page should be a
.B TH
command:
-.PP
+.P
.RS
.B \&.TH
.I "title section date source manual-section"
.RE
-.PP
+.P
The arguments of the command are as follows:
.TP
.I title
sections.
Arrange a new manual page so that sections
are placed in the order shown in the list.
-.PP
+.P
.RS
.TS
l l.
\fBSEE ALSO\fP
.TE
.RE
-.PP
+.P
.IR "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
However, before doing this, consider whether you could use the
traditional headings, with some subsections (\fI.SS\fP) within
those sections.
-.PP
+.P
The following list elaborates on the contents of each of
the above sections.
.TP
.BR syscalls (2)
manual page also provides information about kernel versions
in which various system calls first appeared.
-.PP
+.P
Old versions of standards should be mentioned here,
rather than in STANDARDS,
for example,
Wrap the function prototype(s) in a
.IR .nf / .fi
pair to prevent filling.
-.PP
+.P
In general, where more than one function prototype is shown in the SYNOPSIS,
the prototypes should
.I not
be separated by blank lines.
However, blank lines (achieved using
-.IR .PP )
+.IR .P )
may be added in the following cases:
.IP \[bu] 3
to separate long lists of function prototypes into related groups
.BR list (3));
.IP \[bu]
in other cases that may improve readability.
-.PP
+.P
In the SYNOPSIS, a long function prototype may need to be
continued over to the next line.
The continuation line is indented according to the following rules:
macro pairs to allow table cells to be broken over multiple lines
(also bearing in mind that pages may sometimes be rendered to a
width of less than 80 columns).
-.PP
+.P
For examples of all of the above, see the source code of various pages.
.SH STYLE GUIDE
The following subsections describe the preferred style for the
For manual pages that describe a command (typically in Sections 1 and 8),
the arguments are always specified using italics,
.IR "even in the SYNOPSIS section" .
-.PP
+.P
The name of the command, and its options, should
always be formatted in bold.
.\"
the arguments are always specified using italics,
.IR "even in the SYNOPSIS section" ,
where the rest of the function is specified in bold:
-.PP
+.P
.BI " int myfunction(int " argc ", char **" argv );
-.PP
+.P
Variable names should, like argument names, be specified in italics.
-.PP
+.P
Any reference to the subject of the current manual page
should be written with the name in bold followed by
a pair of parentheses in Roman (normal) font.
man page, references to the subject of the page would be written as:
.BR fcntl ().
The preferred way to write this in the source file is:
-.PP
+.P
.EX
.BR fcntl ()
.EE
-.PP
+.P
(Using this format, rather than the use of "\efB...\efP()"
makes it easier to write tools that parse man page source files.)
.\"
Numbered notes
Not really a list,
but the syntax is identical to "positional lists".
-.PP
+.P
There should always be exactly
2 spaces between the list symbol and the elements.
This doesn't apply to "tagged paragraphs",
.\"
.SS Formatting conventions (general)
Paragraphs should be separated by suitable markers (usually either
-.I .PP
+.I .P
or
.IR .IP ).
Do
.I not
separate paragraphs using blank lines, as this results in poor rendering
in some output formats (such as PostScript and PDF).
-.PP
+.P
Filenames (whether pathnames, or references to header files)
are always in italics (e.g.,
.IR <stdio.h> ),
specify the header file surrounded by angle brackets,
in the usual C way (e.g.,
.IR <stdio.h> ).
-.PP
+.P
Special macros, which are usually in uppercase, are in bold (e.g.,
.BR MAXINT ).
Exception: don't boldface NULL.
-.PP
+.P
When enumerating a list of error codes, the codes are in bold (this list
usually uses the
.B \&.TP
macro).
-.PP
+.P
Complete commands should, if long,
be written as an indented line on their own,
with a blank line before and after the command, for example
-.PP
+.P
.in +4n
.EX
man 7 man\-pages
.EE
.in
-.PP
+.P
If the command is short, then it can be included inline in the text,
in italic format, for example,
.IR "man 7 man-pages" .
(\e[ti]) at suitable places in the command.
Command options should be written in italics (e.g.,
.IR \-l ).
-.PP
+.P
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.
-.PP
+.P
When showing example shell sessions,
user input should be formatted in bold,
for example
-.PP
+.P
.in +4n
.EX
$ \fBdate\fP
Thu Jul 7 13:01:27 CEST 2016
.EE
.in
-.PP
+.P
Any reference to another man page
should be written with the name in bold,
.I always
separating spaces (e.g.,
.BR intro (2)).
The preferred way to write this in the source file is:
-.PP
+.P
.EX
.BR intro (2)
.EE
-.PP
+.P
(Including the section number in cross references lets tools like
.BR man2html (1)
create properly hyperlinked pages.)
-.PP
+.P
Control characters should be written in bold face,
with no quotes; for example,
.BR \[ha]X .
follows American spelling conventions
(previously, there was a random mix of British and American spellings);
please write all new pages and patches according to these conventions.
-.PP
+.P
Aside from the well-known spelling differences,
there are a few other subtleties to watch for:
.IP \[bu] 3
except where English usage (e.g., proper nouns) or programming
language requirements (e.g., identifier names) dictate otherwise.
For example:
-.PP
+.P
.in +4n
.EX
\&.SS Unicode under Linux
and
.I .EE
macros, and surround them with suitable paragraph markers (either
-.I .PP
+.I .P
or
.IR .IP ).
For example:
-.PP
+.P
.in +4n
.EX
-\&.PP
+\&.P
\&.in +4n
\&.EX
int
}
\&.EE
\&.in
-\&.PP
+\&.P
.EE
.in
.SS Preferred terms
T}
zeros zeroes
.TE
-.PP
+.P
See also the discussion
.I Hyphenation of attributive compounds
below.
.IR "null byte" ,
a byte with the value 0, represented in C via the character constant
.IR \[aq]\e0\[aq] .
-.PP
+.P
The preferred term for the pointer is "null pointer" or simply "NULL";
avoid writing "NULL pointer".
-.PP
+.P
The preferred term for the byte is "null byte".
Avoid writing "NUL", since it is too easily confused with "NULL".
Avoid also the terms "zero byte" and "null character".
.BR groff_man (7)).
This produces proper hyperlinks that can be used in a web browser,
when rendering a page with, say:
-.PP
+.P
.in +4n
.EX
BROWSER=firefox man -H pagename
"cf.", and "a.k.a." should be avoided,
in favor of suitable full wordings
("for example", "that is", "and so on", "compare to", "also known as").
-.PP
+.P
The only place where such abbreviations may be acceptable is in
.I short
parenthetical asides (e.g., like this one).
-.PP
+.P
Always include periods in such abbreviations, as shown here.
In addition, "e.g." and "i.e." should always be followed by a comma.
.SS Em-dashes
subdirectory
subsystem
.TE
-.PP
+.P
Hyphens should be retained when the prefixes are used in nonstandard
English words, with trademarks, proper nouns, acronyms, or compound terms.
Some examples:
non-NULL
non-real-time
.TE
-.PP
+.P
Finally, note that "re-create" and "recreate" are two different verbs,
and the former is probably what you want.
.\"
or when writing options that have a leading dash, such as in
.IR "ls\ \-l"),
use the following form in the man page source:
-.PP
+.P
.in +4n
.EX
\e\-
.EE
.in
-.PP
+.P
This guideline applies also to code examples.
-.PP
+.P
The use of real minus signs serves the following purposes:
.\" https://lore.kernel.org/linux-man/20210121061158.5ul7226fgbrmodbt@localhost.localdomain/
.IP \[bu] 3
.IP \[bu]
To generate glyphs that when copied from rendered pages will
produce real minus signs when pasted into a terminal.
-.PP
+.P
To produce unslanted single quotes that render well in ASCII, UTF-8, and PDF,
use "\e[aq]" ("apostrophe quote"); for example
-.PP
+.P
.in +4n
.EX
\e[aq]C\e[aq]
.EE
.in
-.PP
+.P
where
.I C
is the quoted character.
This guideline applies also to character constants used in code examples.
-.PP
+.P
Where a proper caret (\[ha]) that renders well in both a terminal and PDF
is required, use "\\[ha]".
This is especially necessary in code samples,
to get a nicely rendered caret when rendering to PDF.
-.PP
+.P
Using a naked "\[ti]" character results in a poor rendering in PDF.
Instead use "\\[ti]".
This is especially necessary in code samples,
.in
.IP
Always do this if the explanatory text includes a shell session log.
-.PP
+.P
If you include a shell session log demonstrating the use of a program
or other system feature:
.IP \[bu] 3
.IP \[bu]
Boldface the user input text,
to distinguish it from output produced by the system.
-.PP
+.P
For some examples of what example programs should look like, see
.BR wait (2)
and
as outlined below)
described in
.BR fenv (3).
-.PP
+.P
A portable program that needs to check for an error from a mathematical
function should set
.I errno
to zero, and make the following call
-.PP
+.P
.in +4n
.EX
feclearexcept(FE_ALL_EXCEPT);
.EE
.in
-.PP
+.P
before calling a mathematical function.
-.PP
+.P
Upon return from the mathematical function, if
.I errno
is nonzero, or the following call (see
.BR fenv (3))
returns nonzero
-.PP
+.P
.in +4n
.EX
fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW |
FE_UNDERFLOW);
.EE
.in
-.PP
+.P
.\" enum
.\" {
.\" FE_INVALID = 0x01,
.\" FE_INEXACT = 0x20
.\" };
then an error occurred in the mathematical function.
-.PP
+.P
The error conditions that can occur for mathematical functions
are described below.
.SS Domain error
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.
-.PP
+.P
A floating result
.I overflows
if the result is finite,
and an "overflow"
.RB ( FE_OVERFLOW )
floating-point exception is raised.
-.PP
+.P
A floating result
.I underflows
if the result is too small to be represented in the result type.
and an "underflow"
.RB ( FE_UNDERFLOW )
floating-point exception may be raised.
-.PP
+.P
Some functions deliver a range error if the supplied argument value,
or the correct function result, would be
.IR subnormal .
but don't raise an exception.
A very few functions do neither.
See the individual manual pages for details.
-.PP
+.P
To avoid the complexities of using
.I errno
and
.BR log (3)'s
argument is not a NaN and is not zero (a pole error) or
less than zero (a domain error):
-.PP
+.P
.in +4n
.EX
double x, r;
r = log(x);
.EE
.in
-.PP
+.P
The discussion on this page does not apply to the complex
mathematical functions (i.e., those declared by
.IR <complex.h> ),
which in general are not required to return errors by C99
and POSIX.1.
-.PP
+.P
The
.BR gcc (1)
.I "\-fno\-math\-errno"
.BR isgreater (3),
.BR matherr (3),
.BR nan (3)
-.PP
+.P
.I "info libc"
.SH DESCRIPTION
For an overview of namespaces, see
.BR namespaces (7).
-.PP
+.P
Mount namespaces provide isolation of the list of mounts seen
by the processes in each namespace instance.
Thus, the processes in each of the mount namespace instances
will see distinct single-directory hierarchies.
-.PP
+.P
The views provided by the
.IR /proc/ pid /mounts ,
.IR /proc/ pid /mountinfo ,
resides.
(All of the processes that reside in the same mount namespace
will see the same view in these files.)
-.PP
+.P
A new mount namespace is created using either
.BR clone (2)
or
.BR unshare (2),
the mount list of the new namespace is a copy of
the mount list in the caller's previous mount namespace.
-.PP
+.P
Subsequent modifications to the mount list
.RB ( mount (2)
and
(or, more precisely, between the mounts that are members of a
.I peer group
that are propagating events to one another).
-.PP
+.P
Each mount is marked (via
.BR mount (2))
as having one of the following
any bind mounts within the subtree are automatically pruned
(i.e., not replicated)
when replicating that subtree to produce the target subtree.
-.PP
+.P
For a discussion of the propagation type assigned to a new mount,
see NOTES.
-.PP
+.P
The propagation type is a per-mount-point setting;
some mounts may be marked as shared
(with each shared mount being a member of a distinct peer group),
while others are private
(or slaved or unbindable).
-.PP
+.P
Note that a mount's propagation type determines whether
.BR mount (2)
and
the propagation type that is in effect for the
.I parent
of the mount.
-.PP
+.P
Members are added to a
.I peer group
when a mount is marked as shared and either:
the mount is replicated during the creation of a new mount namespace; or
.IP (b)
a new bind mount is created from the mount.
-.PP
+.P
In both of these cases, the new mount joins the peer group
of which the existing mount is a member.
-.PP
+.P
A new peer group is also created when a child mount is created under
an existing mount that is marked as shared.
In this case, the new child mount is also marked as shared and
the resulting peer group consists of all the mounts
that are replicated under the peers of parent mounts.
-.PP
+.P
A mount ceases to be a member of a peer group when either
the mount is explicitly unmounted,
or when the mount is implicitly unmounted because a mount namespace is removed
(because it has no more member processes).
-.PP
+.P
The propagation type of the mounts in a mount namespace
can be discovered via the "optional fields" exposed in
.IR /proc/ pid /mountinfo .
.TP
.I unbindable
This is an unbindable mount.
-.PP
+.P
If none of the above tags is present, then this is a private mount.
.SS MS_SHARED and MS_PRIVATE example
Suppose that on a terminal in the initial mount namespace,
we mark one mount as shared and another as private,
and then view the mounts in
.IR /proc/self/mountinfo :
-.PP
+.P
.in +4n
.EX
sh1# \fBmount \-\-make\-shared /mntS\fP
83 61 8:15 / /mntP rw,relatime
.EE
.in
-.PP
+.P
From the
.I /proc/self/mountinfo
output, we see that
is the root directory,
.IR / ,
which is mounted as private:
-.PP
+.P
.in +4n
.EX
sh1# \fBcat /proc/self/mountinfo | awk \[aq]$1 == 61\[aq] | sed \[aq]s/ \- .*//\[aq]\fP
61 0 8:2 / / rw,relatime
.EE
.in
-.PP
+.P
On a second terminal,
we create a new mount namespace where we run a second shell
and inspect the mounts:
-.PP
+.P
.in +4n
.EX
$ \fBPS1=\[aq]sh2# \[aq] sudo unshare \-m \-\-propagation unchanged sh\fP
225 145 8:15 / /mntP rw,relatime
.EE
.in
-.PP
+.P
The new mount namespace received a copy of the initial mount namespace's
mounts.
These new mounts maintain the same propagation types,
from marking all mounts as private when creating a new mount namespace,
.\" Since util-linux 2.27
which it does by default.)
-.PP
+.P
In the second terminal, we then create submounts under each of
.I /mntS
and
.I /mntP
and inspect the set-up:
-.PP
+.P
.in +4n
.EX
sh2# \fBmkdir /mntS/a\fP
230 225 8:23 / /mntP/b rw,relatime
.EE
.in
-.PP
+.P
From the above, it can be seen that
.I /mntS/a
was created as shared (inheriting this setting from its parent mount) and
.I /mntP/b
was created as a private mount.
-.PP
+.P
Returning to the first terminal and inspecting the set-up,
we see that the new mount created under the shared mount
.I /mntS
but the new mount created under the private mount
.I /mntP
did not propagate:
-.PP
+.P
.in +4n
.EX
sh1# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq]\fP
.BR umount (2)
events under the slave mount
from having side effects in other namespaces.
-.PP
+.P
We can demonstrate the effect of slaving by first marking
two mounts as shared in the initial mount namespace:
-.PP
+.P
.in +4n
.EX
sh1# \fBmount \-\-make\-shared /mntX\fP
133 83 8:22 / /mntY rw,relatime shared:2
.EE
.in
-.PP
+.P
On a second terminal,
we create a new mount namespace and inspect the mounts:
-.PP
+.P
.in +4n
.EX
sh2# \fBunshare \-m \-\-propagation unchanged sh\fP
169 167 8:22 / /mntY rw,relatime shared:2
.EE
.in
-.PP
+.P
In the new mount namespace, we then mark one of the mounts as a slave:
-.PP
+.P
.in +4n
.EX
sh2# \fBmount \-\-make\-slave /mntY\fP
169 167 8:22 / /mntY rw,relatime master:2
.EE
.in
-.PP
+.P
From the above output, we see that
.I /mntY
is now a slave mount that is receiving propagation events from
the shared peer group with the ID 2.
-.PP
+.P
Continuing in the new namespace, we create submounts under each of
.I /mntX
and
.IR /mntY :
-.PP
+.P
.in +4n
.EX
sh2# \fBmkdir /mntX/a\fP
sh2# \fBmount /dev/sda5 /mntY/b\fP
.EE
.in
-.PP
+.P
When we inspect the state of the mounts in the new mount namespace,
we see that
.I /mntX/a
(inheriting the "shared" setting from its parent mount) and
.I /mntY/b
was created as a private mount:
-.PP
+.P
.in +4n
.EX
sh2# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq]\fP
175 169 8:5 / /mntY/b rw,relatime
.EE
.in
-.PP
+.P
Returning to the first terminal (in the initial mount namespace),
we see that the mount
.I /mntX/a
but the mount
.I /mntY/b
was not propagated:
-.PP
+.P
.in +4n
.EX
sh1# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq]\fP
174 132 8:3 / /mntX/a rw,relatime shared:3
.EE
.in
-.PP
+.P
Now we create a new mount under
.I /mntY
in the first shell:
-.PP
+.P
.in +4n
.EX
sh1# \fBmkdir /mntY/c\fP
178 133 8:1 / /mntY/c rw,relatime shared:4
.EE
.in
-.PP
+.P
When we examine the mounts in the second mount namespace,
we see that in this case the new mount has been propagated
to the slave mount,
and that the new mount is itself a slave mount (to peer group 4):
-.PP
+.P
.in +4n
.EX
sh2# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq]\fP
the "mount explosion" problem when repeatedly performing bind mounts
of a higher-level subtree at a lower-level mount.
The problem is illustrated by the following shell session.
-.PP
+.P
Suppose we have a system with the following mounts:
-.PP
+.P
.in +4n
.EX
# \fBmount | awk \[aq]{print $1, $2, $3}\[aq]\fP
/dev/sdb7 on /mntY
.EE
.in
-.PP
+.P
Suppose furthermore that we wish to recursively bind mount
the root directory under several users' home directories.
We do this for the first user, and inspect the mounts:
-.PP
+.P
.in +4n
.EX
# \fBmount \-\-rbind / /home/cecilia/\fP
/dev/sdb7 on /home/cecilia/mntY
.EE
.in
-.PP
+.P
When we repeat this operation for the second user,
we start to see the explosion problem:
-.PP
+.P
.in +4n
.EX
# \fBmount \-\-rbind / /home/henry\fP
/dev/sdb7 on /home/henry/home/cecilia/mntY
.EE
.in
-.PP
+.P
Under
.IR /home/henry ,
we have not only recursively added the
that were created in the previous step.
Upon repeating the step for a third user,
it becomes obvious that the explosion is exponential in nature:
-.PP
+.P
.in +4n
.EX
# \fBmount \-\-rbind / /home/otto\fP
/dev/sdb7 on /home/otto/home/henry/home/cecilia/mntY
.EE
.in
-.PP
+.P
The mount explosion problem in the above scenario can be avoided
by making each of the new mounts unbindable.
The effect of doing this is that recursive mounts of the root
directory will not replicate the unbindable mounts.
We make such a mount for the first user:
-.PP
+.P
.in +4n
.EX
# \fBmount \-\-rbind \-\-make\-unbindable / /home/cecilia\fP
.EE
.in
-.PP
+.P
Before going further, we show that unbindable mounts are indeed unbindable:
-.PP
+.P
.in +4n
.EX
# \fBmkdir /mntZ\fP
dmesg | tail or so.
.EE
.in
-.PP
+.P
Now we create unbindable recursive bind mounts for the other two users:
-.PP
+.P
.in +4n
.EX
# \fBmount \-\-rbind \-\-make\-unbindable / /home/henry\fP
# \fBmount \-\-rbind \-\-make\-unbindable / /home/otto\fP
.EE
.in
-.PP
+.P
Upon examining the list of mounts,
we see there has been no explosion of mounts,
because the unbindable mounts were not replicated
under each user's directory:
-.PP
+.P
.in +4n
.EX
# \fBmount | awk \[aq]{print $1, $2, $3}\[aq]\fP
private shared priv [2] priv unbind
unbindable shared unbind [2] priv unbind
.TE
-.PP
+.P
Note the following details to the table:
.IP [1] 5
If a shared mount is the only mount in its peer group,
.\"
.SS Bind (MS_BIND) semantics
Suppose that the following command is performed:
-.PP
+.P
.in +4n
.EX
mount \-\-bind A/a B/b
.EE
.in
-.PP
+.P
Here,
.I A
is the source mount,
and
.IR B ,
and is summarized in the following table.
-.PP
+.P
.TS
lb2 lb1 lb2 lb2 lb2 lb0
lb2 lb1 lb2 lb2 lb2 lb0
dest(B) shared shared shared slave+shared invalid
nonshared shared private slave invalid
.TE
-.PP
+.P
Note that a recursive bind of a subtree follows the same semantics
as for a bind operation on each mount in the subtree.
(Unbindable mounts are automatically pruned at the target mount point.)
-.PP
+.P
For further details, see
.I Documentation/filesystems/sharedsubtree.rst
in the kernel source tree.
.\"
.SS Move (MS_MOVE) semantics
Suppose that the following command is performed:
-.PP
+.P
.in +4n
.EX
mount \-\-move A B/b
.EE
.in
-.PP
+.P
Here,
.I A
is the source mount,
and
.IR B ,
and is summarized in the following table.
-.PP
+.P
.TS
lb2 lb1 lb2 lb2 lb2 lb0
lb2 lb1 lb2 lb2 lb2 lb0
dest(B) shared shared shared slave+shared invalid
nonshared shared private slave unbindable
.TE
-.PP
+.P
Note: moving a mount that resides under a shared mount is invalid.
-.PP
+.P
For further details, see
.I Documentation/filesystems/sharedsubtree.rst
in the kernel source tree.
.\"
.SS Mount semantics
Suppose that we use the following command to create a mount:
-.PP
+.P
.in +4n
.EX
mount device B/b
.EE
.in
-.PP
+.P
Here,
.I B
is the destination mount, and
.\"
.SS Unmount semantics
Suppose that we use the following command to tear down a mount:
-.PP
+.P
.in +4n
.EX
umount A
.EE
.in
-.PP
+.P
Here,
.I A
is a mount on
the filesystem root directory)
and so cannot determine the
chain of propagation between the mounts it can see.
-.PP
+.P
In the following example, we first create a two-link master-slave chain
between the mounts
.IR /mnt ,
creating a situation where the master of
.I /mnt/tmp/etc
is not reachable from the (new) root directory of the process.
-.PP
+.P
First, we bind mount the root directory onto
.I /mnt
and then bind mount
.BR proc (5)
filesystem remains visible at the correct location
in the chroot-ed environment.
-.PP
+.P
.in +4n
.EX
# \fBmkdir \-p /mnt/proc\fP
# \fBmount \-\-bind /proc /mnt/proc\fP
.EE
.in
-.PP
+.P
Next, we ensure that the
.I /mnt
mount is a shared mount in a new peer group (with no peers):
-.PP
+.P
.in +4n
.EX
# \fBmount \-\-make\-private /mnt\fP # Isolate from any previous peer group
248 239 0:4 / /mnt/proc ... shared:5
.EE
.in
-.PP
+.P
Next, we bind mount
.I /mnt/etc
onto
.IR /tmp/etc :
-.PP
+.P
.in +4n
.EX
# \fBmkdir \-p /tmp/etc\fP
267 40 8:2 /etc /tmp/etc ... shared:102
.EE
.in
-.PP
+.P
Initially, these two mounts are in the same peer group,
but we then make the
.I /tmp/etc
.I /tmp/etc
shared as well,
so that it can propagate events to the next slave in the chain:
-.PP
+.P
.in +4n
.EX
# \fBmount \-\-make\-slave /tmp/etc\fP
267 40 8:2 /etc /tmp/etc ... shared:105 master:102
.EE
.in
-.PP
+.P
Then we bind mount
.I /tmp/etc
onto
.I /mnt/tmp/etc
a slave of
.IR /tmp/etc :
-.PP
+.P
.in +4n
.EX
# \fBmkdir \-p /mnt/tmp/etc\fP
273 239 8:2 /etc /mnt/tmp/etc ... master:105
.EE
.in
-.PP
+.P
From the above, we see that
.I /mnt
is the master of the slave
.IR /tmp/etc ,
which in turn is the master of the slave
.IR /mnt/tmp/etc .
-.PP
+.P
We then
.BR chroot (1)
to the
.I /mnt
directory, which renders the mount with ID 267 unreachable
from the (new) root directory:
-.PP
+.P
.in +4n
.EX
# \fBchroot /mnt\fP
.EE
.in
-.PP
+.P
When we examine the state of the mounts inside the chroot-ed environment,
we see the following:
-.PP
+.P
.in +4n
.EX
# \fBcat /proc/self/mountinfo | sed \[aq]s/ \- .*//\[aq]\fP
273 239 8:2 /etc /tmp/etc ... master:105 propagate_from:102
.EE
.in
-.PP
+.P
Above, we see that the mount with ID 273
is a slave whose master is the peer group 105.
The mount point for that master is unreachable, and so a
.BR MS_SHARED .
Otherwise, the propagation type of the new mount is
.BR MS_PRIVATE .
-.PP
+.P
Notwithstanding the fact that the default propagation type
for new mount is in many cases
.BR MS_PRIVATE ,
on system startup.
Thus, on most modern systems, the default propagation type is in practice
.BR MS_SHARED .
-.PP
+.P
Since, when one uses
.BR unshare (1)
to create a mount namespace,
That is,
.BR unshare (1)
performs the equivalent of the following in the new mount namespace:
-.PP
+.P
.in +4n
.EX
mount \-\-make\-rprivate /
.EE
.in
-.PP
+.P
To prevent this, one can use the
.I \-\-propagation\~unchanged
option to
.BR unshare (1).
-.PP
+.P
An application that creates a new mount namespace directly using
.BR clone (2)
or
or
.BR MS_PRIVATE ,
using a call such as the following:
-.PP
+.P
.in +4n
.EX
mount(NULL, "/", MS_SLAVE | MS_REC, NULL);
.EE
.in
-.PP
+.P
For a discussion of propagation types when moving mounts
.RB ( MS_MOVE )
and creating bind mounts
.BR pam_namespace (8),
.BR pivot_root (8),
.BR umount (8)
-.PP
+.P
.I Documentation/filesystems/sharedsubtree.rst
in the kernel source tree.
.BR msgsnd (2),
.BR msgrcv (2),
etc.), but provides similar functionality.
-.PP
+.P
Message queues are created and opened using
.BR mq_open (3);
this function returns a
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
.BR mq_open (3).
-.PP
+.P
Messages are transferred to and from a queue using
.BR mq_send (3)
and
A process can request asynchronous notification
of the arrival of a message on a previously empty queue using
.BR mq_notify (3).
-.PP
+.P
A message queue descriptor is a reference to an
.I "open message queue description"
(see
Corresponding message queue descriptors in the two processes share the flags
.RI ( mq_flags )
that are associated with the open message queue description.
-.PP
+.P
Each message has an associated
.IR priority ,
and messages are always delivered to the receiving process
returns 32768, but POSIX.1 requires only that
an implementation support at least priorities in the range 0 to 31;
some implementations provide only this range.
-.PP
+.P
The remainder of this section describes some specific details
of the Linux implementation of POSIX message queues.
.SS Library interfaces and system calls
but the details are likely to differ.)
This filesystem can be mounted (by the superuser) using the following
commands:
-.PP
+.P
.in +4n
.EX
.RB "#" " mkdir /dev/mqueue"
.RB "#" " mount \-t mqueue none /dev/mqueue"
.EE
.in
-.PP
+.P
The sticky bit is automatically enabled on the mount directory.
-.PP
+.P
After the filesystem has been mounted, the message queues on the system
can be viewed and manipulated using the commands usually used for files
(e.g.,
.BR ls (1)
and
.BR rm (1)).
-.PP
+.P
The contents of each file in the directory consist of a single line
containing information about the queue:
-.PP
+.P
.in +4n
.EX
.RB "$" " cat /dev/mqueue/mymq"
QSIZE:129 NOTIFY:2 SIGNO:0 NOTIFY_PID:8260
.EE
.in
-.PP
+.P
These fields are as follows:
.TP
.B QSIZE
or
.BR epoll (7).
This is not portable.
-.PP
+.P
The close-on-exec flag (see
.BR open (2))
is automatically set on the file descriptor returned by
System V message queues;
on the other hand POSIX message queues are less widely available
(especially on older systems) than System V message queues.
-.PP
+.P
Linux does not currently (Linux 2.6.26) support the use of access control
lists (ACLs) for POSIX message queues.
.SH BUGS
and the ceiling was enforced even for privileged processes.
This ceiling value was removed in Linux 3.14,
and patches to stable Linux 3.5.x to Linux 3.13.x also removed the ceiling.
-.PP
+.P
As originally implemented (and documented),
the QSIZE field displayed the total number of (user-supplied)
bytes in all messages in the message queue.
Changes to the global resource are visible to other processes
that are members of the namespace, but are invisible to other processes.
One use of namespaces is to implement containers.
-.PP
+.P
This page provides pointers to information on the various namespace types,
describes the associated
.I /proc
operations can be used to discover information about namespaces.
These operations are described in
.BR ioctl_ns (2).
-.PP
+.P
Creation of new namespaces using
.BR clone (2)
and
subdirectory containing one entry for each namespace that
supports being manipulated by
.BR setns (2):
-.PP
+.P
.in +4n
.EX
$ \fBls \-l /proc/$$/ns | awk \[aq]{print $1, $9, $10, $11}\[aq]\fP
lrwxrwxrwx. uts \-> uts:[4026531838]
.EE
.in
-.PP
+.P
Bind mounting (see
.BR mount (2))
one of the files in this directory
the corresponding namespace of the process specified by
.I pid
alive even if all processes currently in the namespace terminate.
-.PP
+.P
Opening one of the files in this directory
(or a file that is bind mounted to one of these files)
returns a file handle for
even if all processes in the namespace terminate.
The file descriptor can be passed to
.BR setns (2).
-.PP
+.P
In Linux 3.7 and earlier, these files were visible as hard links.
Since Linux 3.8,
.\" commit bf056bfa80596a5d14b26b17276a56a0dcb080e5
.BR stat (2).
The content of this symbolic link is a string containing
the namespace type and inode number as in the following example:
-.PP
+.P
.in +4n
.EX
$ \fBreadlink /proc/$$/ns/uts\fP
uts:[4026531838]
.EE
.in
-.PP
+.P
The symbolic links in this subdirectory are as follows:
.TP
.IR /proc/ pid /ns/cgroup " (since Linux 4.6)"
.TP
.IR /proc/ pid /ns/uts " (since Linux 3.0)"
This file is a handle for the UTS namespace of the process.
-.PP
+.P
Permission to dereference or read
.RB ( readlink (2))
these symbolic links is governed by a ptrace access mode
.I max_uts_namespaces
The value in this file defines a per-user limit on the number of
uts namespaces that may be created in the user namespace.
-.PP
+.P
Note the following details about these files:
.IP \[bu] 3
The values in these files are modifiable by privileged processes.
.SH DESCRIPTION
This man page describes the sockets interface which is used to configure
network devices.
-.PP
+.P
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.
Most of them pass an
.I ifreq
structure:
-.PP
+.P
.in +4n
.EX
struct ifreq {
};
.EE
.in
-.PP
+.P
.B AF_INET6
is an exception.
It passes an
.I in6_ifreq
structure:
-.PP
+.P
.in +4n
.EX
struct in6_ifreq {
};
.EE
.in
-.PP
+.P
Normally, the user specifies which device to affect by setting
.I ifr_name
to the name of the interface or
IFF_ECHO:Echo sent packets (since Linux 2.6.25)
.TE
.ad
-.PP
+.P
Setting the active flag word is a privileged operation, but any
process may read it.
.TP
IFF_SLAVE_NEEDARP:Interface needs ARPs for validation.
IFF_ISATAP:Interface is RFC4214 ISATAP interface.
.TE
-.PP
+.P
Setting the extended (private) interface flags is a privileged operation.
.TP
.B SIOCGIFADDR
.\" Get or set the slave device using
.\" .IR ifr_slave .
.\" Setting the slave device is a privileged operation.
-.\" .PP
+.\" .P
.\" FIXME . add amateur radio stuff.
-.PP
+.P
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
.BR ip (7).
-.PP
+.P
In addition, some devices support private ioctls.
These are not described here.
.SH NOTES
socket addresses
are IP-specific and perhaps should rather be documented in
.BR ip (7).
-.PP
+.P
The names of interfaces with no addresses or that don't have the
.B IFF_RUNNING
flag set can be found via
.IR /proc/net/dev .
-.PP
+.P
.B AF_INET6
IPv6 addresses can be read from
.I /proc/net/if_inet6
macro in
.IR <net/if.h> .
Add the following to your program as a workaround:
-.PP
+.P
.in +4n
.EX
#ifndef ifr_newname
.B #include <asm/types.h>
.B #include <sys/socket.h>
.B #include <linux/netlink.h>
-.PP
+.P
.BI "netlink_socket = socket(AF_NETLINK, " socket_type ", " netlink_family );
.fi
.SH DESCRIPTION
There is also an obsolete netlink interface
via netlink character devices; this interface is not documented here
and is provided only for backward compatibility.
-.PP
+.P
Netlink is a datagram-oriented service.
Both
.B SOCK_RAW
.IR socket_type .
However, the netlink protocol does not distinguish between datagram
and raw sockets.
-.PP
+.P
.I netlink_family
selects the kernel module or netlink group to communicate with.
The currently assigned netlink families are:
Netlink interface to request information about ciphers registered
with the kernel crypto API as well as allow configuration of the
kernel crypto API.
-.PP
+.P
Netlink messages consist of a byte stream with one or multiple
.I nlmsghdr
headers and associated payload.
See
.BR netlink (3)
for further information.
-.PP
+.P
In multipart messages (multiple
.I nlmsghdr
headers with associated payload in one byte stream) the first and all
.B NLM_F_MULTI
flag set, except for the last header which has the type
.BR NLMSG_DONE .
-.PP
+.P
After each
.I nlmsghdr
the payload follows.
-.PP
+.P
.in +4n
.EX
struct nlmsghdr {
};
.EE
.in
-.PP
+.P
.I nlmsg_type
can be one of the standard message types:
.B NLMSG_NOOP
Error messages get the
original request appended, unless the user requests to cap the
error message, and get extra error data if requested.
-.PP
+.P
.in +4n
.EX
struct nlmsgerr {
};
.EE
.in
-.PP
+.P
A netlink family usually specifies more message types, see the
appropriate manual pages for that, for example,
.BR rtnetlink (7)
T}
.TE
.\" FIXME NLM_F_ATOMIC is not used anymore?
-.PP
+.P
Note that
.B NLM_F_ATOMIC
requires the
Add to the end of the object list.
T}
.TE
-.PP
+.P
.I nlmsg_seq
and
.I nlmsg_pid
See the
.B ADDRESS FORMATS
section for further information.
-.PP
+.P
Both
.I nlmsg_seq
and
.I nlmsg_pid
.\" FIXME Explain more about nlmsg_seq and nlmsg_pid.
are opaque to netlink core.
-.PP
+.P
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
.B NLMSG_ERROR
message for every failed packet.
A user process should follow this convention too.
-.PP
+.P
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:
netlink multicast groups
.RI ( nl_groups
not equal 0).
-.PP
+.P
.in +4n
.EX
struct sockaddr_nl {
};
.EE
.in
-.PP
+.P
.I nl_pid
is the unicast address of netlink socket.
It's always 0 if the destination is in the kernel.
opens and assigns a unique
.I nl_pid
to every netlink socket that the process subsequently creates.
-.PP
+.P
.I nl_groups
is a bit mask with every bit representing a netlink group number.
Each netlink family has a set of 32 multicast groups.
sequence number which message triggered the acknowledgement.
.SH VERSIONS
The socket interface to netlink first appeared Linux 2.2.
-.PP
+.P
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.
(network interface create/delete/up/down events) and
.B RTMGRP_IPV4_IFADDR
(IPv4 addresses add/delete events) multicast groups.
-.PP
+.P
.in +4n
.EX
struct sockaddr_nl sa;
bind(fd, (struct sockaddr *) &sa, sizeof(sa));
.EE
.in
-.PP
+.P
The next example demonstrates how to send a netlink message to the
kernel (pid 0).
Note that the application must take care of message sequence numbers
in order to reliably track acknowledgements.
-.PP
+.P
.in +4n
.EX
struct nlmsghdr *nh; /* The nlmsghdr with payload to send */
sendmsg(fd, &msg, 0);
.EE
.in
-.PP
+.P
And the last example is about reading netlink message.
-.PP
+.P
.in +4n
.EX
int len;
.BR capabilities (7),
.BR rtnetlink (7),
.BR sock_diag (7)
-.PP
+.P
.UR ftp://ftp.inr.ac.ru\:/ip\-routing\:/iproute2*
information about libnetlink
.UE
-.PP
+.P
.UR http://www.infradead.org\:/\[ti]tgr\:/libnl/
information about libnl
.UE
-.PP
+.P
RFC 3549 "Linux Netlink as an IP Services Protocol"
In addition,
network namespaces isolate the UNIX domain abstract socket namespace (see
.BR unix (7)).
-.PP
+.P
A physical network device can live in exactly one
network namespace.
When a network namespace is freed
its physical network devices are moved back to the
initial network namespace
(not to the namespace of the parent of the process).
-.PP
+.P
A virtual network
.RB ( veth (4))
device pair provides a pipe-like abstraction
When a namespace is freed, the
.BR veth (4)
devices that it contains are destroyed.
-.PP
+.P
Use of network namespaces requires a kernel that is configured with the
.B CONFIG_NET_NS
option.
the other is used as part of a mechanism that ensures all threads in
a process always have the same UIDs and GIDs, as required by POSIX.
These signals cannot be used in applications.
-.PP
+.P
To prevent accidental use of these signals in applications,
which might interfere with the operation of the NPTL implementation,
various glibc library functions and system call wrapper functions
change process credentials with functions that,
in addition to invoking the underlying system call,
arrange for all other threads in the process to also change their credentials.
-.PP
+.P
The implementation of each of these system calls involves the use of
a real-time signal that is sent (using
.BR tgkill (2))
in a global buffer.
A signal handler in the receiving thread(s) fetches this information and
then uses the same system call to change its credentials.
-.PP
+.P
Wrapper functions employing this technique are provided for
.BR setgid (2),
.BR setuid (2),
.\" See also Changelog-2.6.14
This file displays information about a process's
NUMA memory policy and allocation.
-.PP
+.P
Each line contains information about a memory range used by the process,
displaying\[em]among other information\[em]the effective memory policy for
that memory range and on which nodes the pages have been allocated.
-.PP
+.P
.I numa_maps
is a read-only file.
When
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.
-.PP
+.P
The first field of each line shows the starting address of the memory range.
This field allows a correlation with the contents of the
.IR /proc/ pid /maps
file,
which contains the end address of the range and other information,
such as the access permissions and sharing.
-.PP
+.P
The second field shows the memory policy currently in effect for the
memory range.
Note that the effective policy is not necessarily the policy
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".
-.PP
+.P
The rest of the line contains information about the pages allocated in
the memory range, as follows:
.TP
header are available in the
.I numactl
package.
-.PP
+.P
However, applications should not use these system calls directly.
Instead, the higher level interface provided by the
.BR numa (3)
operator \- C operator precedence and order of evaluation
.SH DESCRIPTION
This manual page lists C operators and their precedence in evaluation.
-.PP
+.P
.TS
lb lb lb
l l l.
= *= /= %= += \-= <<= >>= &= \[ha]= |= right to left
, left to right
.TE
-.PP
+.P
The following notes provide further information to the above table:
-.PP
+.P
.PD 0
.IP [1] 5
The ++ and \-\- operators at this precedence level are
.B #include <sys/socket.h>
.B #include <linux/if_packet.h>
.B #include <net/ethernet.h> /* the L2 protocols */
-.PP
+.P
.BI "packet_socket = socket(AF_PACKET, int " socket_type ", int "protocol );
.fi
.SH DESCRIPTION
(OSI Layer 2) level.
They allow the user to implement protocol modules in user space
on top of the physical layer.
-.PP
+.P
The
.I socket_type
is either
can optionally be called with a nonzero
.I sll_protocol
to start receiving packets for the protocols specified.
-.PP
+.P
In order to create a packet socket, a process must have the
.B CAP_NET_RAW
capability in the user namespace that governs its network namespace.
-.PP
+.P
.B SOCK_RAW
packets are passed to and from the device driver without any changes in
the packet data.
is similar to but not compatible with the obsolete
.B AF_INET/SOCK_PACKET
of Linux 2.0.
-.PP
+.P
.B SOCK_DGRAM
operates on a slightly higher level.
The physical header is removed before the packet is passed to the user.
information in the
.I sockaddr_ll
destination address before they are queued.
-.PP
+.P
By default, all packets of the specified protocol type
are passed to a packet socket.
To get packets only from a specific interface use
.IR sll_protocol ,
and
.IR sll_ifindex .
-.PP
+.P
The
.BR connect (2)
operation is not supported on packet sockets.
-.PP
+.P
When the
.B MSG_TRUNC
flag is passed to
The
.I sockaddr_ll
structure is a device-independent physical-layer address.
-.PP
+.P
.in +4n
.EX
struct sockaddr_ll {
};
.EE
.in
-.PP
+.P
The fields of this structure are as follows:
.TP
.I sll_protocol
.I sll_halen
contain the physical-layer (e.g., IEEE 802.3) address and its length.
The exact interpretation depends on the device.
-.PP
+.P
When you send packets, it is enough to specify
.IR sll_family ,
.IR sll_addr ,
.I struct timeval
variable.
.\" FIXME Document SIOCGSTAMPNS
-.PP
+.P
In addition, all standard ioctls defined in
.BR netdevice (7)
and
.TP
.B EPERM
User has insufficient privileges to carry out this operation.
-.PP
+.P
In addition, other errors may be generated by the low-level driver.
.SH VERSIONS
.B AF_PACKET
although this covers only a subset of the
.B AF_PACKET
features.
-.PP
+.P
The
.B SOCK_DGRAM
packet sockets make no attempt to create or parse the IEEE 802.2 LLC
instead and do the protocol multiplex yourself.
The default for sending is the standard Ethernet DIX
encapsulation with the protocol filled in.
-.PP
+.P
Packet sockets are not subject to the input or output firewall chains.
.SS Compatibility
In Linux 2.0, the only way to get a packet socket was with the call:
-.PP
+.P
.in +4n
.EX
socket(AF_INET, SOCK_PACKET, protocol)
.EE
.in
-.PP
+.P
This is still supported, but deprecated and strongly discouraged.
The main difference between the two methods is that
.B SOCK_PACKET
.I struct sockaddr_pkt
to specify an interface, which doesn't provide physical-layer
independence.
-.PP
+.P
.in +4n
.EX
struct sockaddr_pkt {
};
.EE
.in
-.PP
+.P
.I spkt_family
contains
the device type,
and
.I spkt_device
is the device name as a null-terminated string, for example, eth0.
-.PP
+.P
This structure is obsolete and should not be used in new code.
.SH BUGS
.SS LLC header handling
will be truncated to fit into
.IR spkt_device .
All these lengths include the terminating null byte (\[aq]\e0\[aq])).
-.PP
+.P
Issues from this with old code typically show up with
very long interface names used by the
.B Predictable Network Interface Names
feature enabled by default in many modern Linux distributions.
-.PP
+.P
The preferred solution is to rewrite code to avoid
.BR SOCK_PACKET .
Possible user solutions are to disable
.BR raw (7),
.BR socket (7),
.BR ip (8),
-.PP
+.P
RFC\ 894 for the standard IP Ethernet encapsulation.
RFC\ 1700 for the IEEE 802.3 IP encapsulation.
-.PP
+.P
The
.I <linux/if_ether.h>
include file for physical-layer protocols.
-.PP
+.P
The Linux kernel source tree.
.I Documentation/networking/filter.rst
describes how to apply Berkeley Packet Filters to packet sockets.
with the
.B RESOLVE_IN_ROOT
flag set.
-.PP
+.P
A process may get an entirely private mount namespace in case
it\[em]or one of its ancestors\[em]was started by an invocation of the
.BR clone (2)
.B CLONE_NEWNS
flag set.
This handles the \[aq]/\[aq] part of the pathname.
-.PP
+.P
If the pathname does not start with the \[aq]/\[aq] character, the starting
lookup directory of the resolution process is the current working directory of
the process \[em] or in the case of
be changed by use of the
.BR chdir (2)
system call.
-.PP
+.P
Pathnames starting with a \[aq]/\[aq] character are called absolute pathnames.
Pathnames not starting with a \[aq]/\[aq] are called relative pathnames.
.SS Step 2: walk along the path
Now, for each nonfinal component of the pathname, where a component
is a substring delimited by \[aq]/\[aq] characters, this component is looked up
in the current lookup directory.
-.PP
+.P
If the process does not have search permission on
the current lookup directory,
an
.B EACCES
error is returned ("Permission denied").
-.PP
+.P
If the component is not found, an
.B ENOENT
error is returned
("No such file or directory").
-.PP
+.P
If the component is found, but is neither a directory nor a symbolic link,
an
.B ENOTDIR
error is returned ("Not a directory").
-.PP
+.P
If the component is found and is a directory, we set the
current lookup directory to that directory, and go to the
next component.
-.PP
+.P
If the component is found and is a symbolic link,
we first resolve this symbolic link
(with the current lookup directory
.B ELOOP
error is returned when the maximum is
exceeded ("Too many levels of symbolic links").
-.PP
+.P
.\"
.\" presently: max recursion depth during symlink resolution: 5
.\" max total number of symbolic links followed: 40
was reworked to eliminate the use of recursion,
so that the only limit that remains is the maximum of 40
resolutions for the entire pathname.
-.PP
+.P
The resolution of symbolic links during this stage can be blocked by using
.BR openat2 (2),
with the
By convention, every directory has the entries "." and "..",
which refer to the directory itself and to its parent directory,
respectively.
-.PP
+.P
The path resolution process will assume that these entries have
their conventional meanings, regardless of whether they are
actually present in the physical filesystem.
-.PP
+.P
One cannot walk up past the root: "/.." is the same as "/".
.SS Mount points
After a
command, the pathname "path" refers to
the root of the filesystem hierarchy on the device "dev", and no
longer to whatever it referred to earlier.
-.PP
+.P
One can walk out of a mounted filesystem: "path/.." refers to
the parent directory of "path",
outside of the filesystem hierarchy on "dev".
-.PP
+.P
Traversal of mount points can be blocked by using
.BR openat2 (2),
with the
supplementary group IDs of the calling process (as set by
.BR setgroups (2)).
When neither holds, the third group is used.
-.PP
+.P
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.
-.PP
+.P
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
.BR setfsuid (2).
-.PP
+.P
(Here "fsuid" stands for something like "filesystem 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
It is obsolete now.
Nobody should use
.BR setfsuid (2).)
-.PP
+.P
Similarly, Linux uses the fsgid ("filesystem group ID")
instead of the effective group ID.
See
.\" on some implementations (e.g., Solaris, FreeBSD),
.\" access(X_OK) by superuser will report success, regardless
.\" of the file's execute permission bits. -- MTK (Oct 05)
-.PP
+.P
On Linux, superuser privileges are divided into capabilities (see
.BR capabilities (7)).
Two capabilities are relevant for file permissions checks:
and
.BR CAP_DAC_READ_SEARCH .
(A process has these capabilities if its fsuid is 0.)
-.PP
+.P
The
.B CAP_DAC_OVERRIDE
capability overrides all permission checking,
but grants execute permission only when at least one
of the file's three execute permission bits is set.
-.PP
+.P
The
.B CAP_DAC_READ_SEARCH
capability grants read and search permission
where
.I <UID>
is the user ID of the corresponding user.
-.PP
+.P
The persistent keyring may not be accessed directly,
even by processes with the appropriate UID.
.\" FIXME The meaning of the preceding sentence isn't clear. What is meant?
This linking is done with the
.BR keyctl_get_persistent (3)
function.
-.PP
+.P
If a persistent keyring does not exist when it is accessed by the
.BR keyctl_get_persistent (3)
operation, it will be automatically created.
-.PP
+.P
Each time the
.BR keyctl_get_persistent (3)
operation is performed,
the persistent keyring's expiration timer is reset to the value in:
-.PP
+.P
.in +4n
.EX
/proc/sys/kernel/keys/persistent_keyring_expiry
.EE
.in
-.PP
+.P
Should the timeout be reached,
the persistent keyring will be removed and
everything it pins can then be garbage collected.
The keyring will then be re-created on a subsequent call to
.BR keyctl_get_persistent (3).
-.PP
+.P
The persistent keyring is not directly searched by
.BR request_key (2);
it is searched only if it is linked into one of the keyrings
that is searched by
.BR request_key (2).
-.PP
+.P
The persistent keyring is independent of
.BR clone (2),
.BR fork (2),
hold authentication tokens for processes that run without user interaction,
such as programs started by
.BR cron (8).
-.PP
+.P
The persistent keyring is used to store UID-specific objects that
themselves have limited lifetimes (e.g., kerberos tokens).
If those tokens cease to be used
.SH DESCRIPTION
For an overview of namespaces, see
.BR namespaces (7).
-.PP
+.P
PID namespaces isolate the process ID number space,
meaning that processes in different PID namespaces can have the same PID.
PID namespaces allow containers to provide functionality
such as suspending/resuming the set of processes in the container and
migrating the container to a new host
while the processes inside the container maintain the same PIDs.
-.PP
+.P
PIDs in a new PID namespace start at 1,
somewhat like a standalone system, and calls to
.BR fork (2),
or
.BR clone (2)
will produce processes with PIDs that are unique within the namespace.
-.PP
+.P
Use of PID namespaces requires a kernel that is configured with the
.B CONFIG_PID_NS
option.
This process becomes the parent of any child processes that are orphaned
because a process that resides in this PID namespace terminated
(see below for further details).
-.PP
+.P
If the "init" process of a PID namespace terminates,
the kernel terminates all of the processes in the namespace via a
.B SIGKILL
.BR fork (2)
fail with
.BR ENOMEM .
-.PP
+.P
Only signals for which the "init" process has established a signal handler
can be sent to the "init" process by other members of the PID namespace.
This restriction applies even to privileged processes,
and prevents other members of the PID namespace from
accidentally killing the "init" process.
-.PP
+.P
Likewise, a process in an ancestor namespace
can\[em]subject to the usual permission checks described in
.BR kill (2)\[em]send
Neither of these signals can be caught by the "init" process,
and so will result in the usual actions associated with those signals
(respectively, terminating and stopping the process).
-.PP
+.P
Starting with Linux 3.4, the
.BR reboot (2)
system call causes a signal to be sent to the namespace "init" process.
.\" commit f2302505775fd13ba93f034206f1e2a587017929
.\" The kernel constant MAX_PID_NS_LEVEL
the kernel limits the maximum nesting depth for PID namespaces to 32.
-.PP
+.P
A process is visible to other processes in its PID namespace,
and to the processes in each direct ancestor PID namespace
going back to the root PID namespace.
.BR setpriority (2),
etc.) only processes contained in its own PID namespace
and in descendants of that namespace.
-.PP
+.P
A process has one process ID in each of the layers of the PID
namespace hierarchy in which is visible,
and walking back though each direct ancestor namespace
.BR getpid (2)
always returns the PID associated with the namespace in which
the process was created.
-.PP
+.P
Some processes in a PID namespace may have parents
that are outside of the namespace.
For example, the parent of the initial process in the namespace
Calls to
.BR getppid (2)
for such processes return 0.
-.PP
+.P
While processes may freely descend into child PID namespaces
(e.g., using
.BR setns (2)
That is to say, processes may not enter any ancestor namespaces
(parent, grandparent, etc.).
Changing PID namespaces is a one-way operation.
-.PP
+.P
The
.B NS_GET_PARENT
.BR ioctl (2)
(as reported by
.BR getpid ()),
which would break many applications and libraries.
-.PP
+.P
To put things another way:
a process's PID namespace membership is determined when the process is created
and cannot be changed thereafter.
between processes mirrors the parental relationship between PID namespaces:
the parent of a process is either in the same namespace
or resides in the immediate parent PID namespace.
-.PP
+.P
A process may call
.BR unshare (2)
with the
Since this is computed when a signal is enqueued,
a signal queue shared by processes in multiple PID namespaces
would defeat that.
-.PP
+.P
.\" Note these restrictions were all introduced in
.\" 8382fcac1b813ad0a4e68a838fc7ae93fa39eda0
.\" when CLONE_NEWPID|CLONE_VM was disallowed
of the process that performed the mount, even if the
.I /proc
filesystem is viewed from processes in other namespaces.
-.PP
+.P
After creating a new PID namespace,
it is useful for the child to change its root directory
and mount a new procfs instance at
then it isn't necessary to change the root directory:
a new procfs instance can be mounted directly over
.IR /proc .
-.PP
+.P
From a shell, the command to mount
.I /proc
is:
-.PP
+.P
.in +4n
.EX
$ mount \-t proc proc /proc
.EE
.in
-.PP
+.P
Calling
.BR readlink (2)
on the path
.IR "write end" .
Data written to the write end of a pipe can be read
from the read end of the pipe.
-.PP
+.P
A pipe is created using
.BR pipe (2),
which creates a new pipe and returns two file descriptors,
processes; see
.BR pipe (2)
for an example.
-.PP
+.P
A FIFO (short for First In First Out) has a name within the filesystem
(created using
.BR mkfifo (3)),
they are created and opened.
Once these tasks have been accomplished,
I/O on pipes and FIFOs has exactly the same semantics.
-.PP
+.P
If a process attempts to read from an empty pipe, then
.BR read (2)
will block until data is available.
.BR write (2)
blocks until sufficient data has been read from the pipe
to allow the write to complete.
-.PP
+.P
Nonblocking I/O is possible by using the
.BR fcntl (2)
.B F_SETFL
If any process has the pipe open for writing, reads fail with
.BR EAGAIN ;
otherwise\[em]with no potential writers\[em]reads succeed and return empty.
-.PP
+.P
The communication channel provided by a pipe is a
.IR "byte stream" :
there is no concept of message boundaries.
-.PP
+.P
If all file descriptors referring to the write end of a pipe
have been closed, then an attempt to
.BR read (2)
this ensures that end-of-file and
.BR SIGPIPE / EPIPE
are delivered when appropriate.
-.PP
+.P
It is not possible to apply
.BR lseek (2)
to a pipe.
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.
-.PP
+.P
Before Linux 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 16 pages
See
.BR fcntl (2)
for more information.
-.PP
+.P
The following
.BR ioctl (2)
operation, which can be applied to a file descriptor
places a count of the number of unread bytes in the pipe in the
.I int
buffer pointed to by the final argument of the call:
-.PP
+.P
.in +4n
.EX
ioctl(fd, FIONREAD, &nbytes);
.EE
.in
-.PP
+.P
The
.B FIONREAD
operation is not specified in any standard,
When the value of this limit is zero, no soft limit is applied.
The default value for this file is 16384,
which permits creating up to 1024 pipes with the default capacity.
-.PP
+.P
Before Linux 4.9, some bugs affected the handling of the
.I pipe\-user\-pages\-soft
and
.B O_NONBLOCK
and
.BR O_ASYNC .
-.PP
+.P
Setting the
.B O_ASYNC
flag for the read end of a pipe causes a signal
Starting with Linux 4.9,
the accounting step is performed before doing the allocation,
and the operation fails if the limit would be exceeded.
-.PP
+.P
Before Linux 4.9, bugs similar to points (a) and (c) could also occur
when the kernel allocated memory for a new pipe buffer;
that is, when calling
Memory Protection Keys provide a mechanism for changing
protections without requiring modification of the page tables on
every permission change.
-.PP
+.P
To use pkeys, software must first "tag" a page in the page tables
with a pkey.
After this tag is in place, an application only has
to change the contents of a register in order to remove write
access, or all access to a tagged page.
-.PP
+.P
Protection keys work in conjunction with the existing
.BR PROT_READ ,
.BR PROT_WRITE ,
.BR mmap (2),
but always act to further restrict these traditional permission
mechanisms.
-.PP
+.P
If a process performs an access that violates pkey
restrictions, it receives a
.B SIGSEGV
See
.BR sigaction (2)
for details of the information available with that signal.
-.PP
+.P
To use the pkeys feature, the processor must support it, and the kernel
must contain support for the feature on a given processor.
As of early 2016 only future Intel x86 processors are supported,
The default key is assigned to any memory region for which a
pkey has not been explicitly assigned via
.BR pkey_mprotect (2).
-.PP
+.P
Protection keys have the potential to add a layer of security and
reliability to applications.
But they have not been primarily designed as
For instance, WRPKRU is a completely unprivileged
instruction, so pkeys are useless in any case that an attacker controls
the PKRU register or can execute arbitrary instructions.
-.PP
+.P
Applications should be very careful to ensure that they do not "leak"
protection keys.
For instance, before calling
file for memory regions with the pkey assigned.
Further details can be found in
.BR proc (5).
-.PP
+.P
Any application wanting to use protection keys needs to be able
to function without them.
They might be unavailable because the hardware that the
and test whether the call succeeds,
instead of attempting to detect support for the
feature in any other way.
-.PP
+.P
Although unnecessary, hardware support for protection keys may be
enumerated with the
.I cpuid
The string "pku" in this field indicates hardware support for protection
keys and the string "ospke" indicates that the kernel contains and has
enabled protection keys support.
-.PP
+.P
Applications using threads and protection keys should be especially
careful.
Threads inherit the protection key rights of the parent at the time
from the defaults.
The rights of any interrupted context are restored when the signal
handler returns.
-.PP
+.P
This signal behavior is unusual and is due to the fact that the x86 PKRU
register (which stores protection key access rights) is managed with the
same hardware mechanism (XSAVE) that manages floating-point registers.
.BR pkey_alloc (2),
and
.BR pkey_free (2).
-.PP
+.P
The Linux pkey system calls are available only if the kernel was
configured and built with the
.B CONFIG_X86_INTEL_MEMORY_PROTECTION_KEYS
disallows access to the page by using the WRPKRU instruction.
It then tries to access the page,
which we now expect to cause a fatal signal to the application.
-.PP
+.P
.in +4n
.EX
.RB "$" " ./a.out"
.BR getconf (1).
For more detail, see
.BR sysconf (3).
-.PP
+.P
We give the name of the POSIX abbreviation, the option, the name of the
.BR sysconf (3)
parameter used to inquire about the option, and possibly
versions of which can nowadays be accessed freely on the web.
.SS ADV - _POSIX_ADVISORY_INFO - _SC_ADVISORY_INFO
The following advisory functions are present:
-.PP
+.P
.nf
.in +4n
.IR posix_fadvise ()
.I <aio.h>
is present.
The following functions are present:
-.PP
+.P
.nf
.in +4n
.IR aio_cancel ()
.B _POSIX_THREAD_SAFE_FUNCTIONS
options.
The following functions are present:
-.PP
+.P
.nf
.in +4n
.IR pthread_barrier_destroy ()
then only root may change the owner of a file, and nonroot can
set the group of a file only to one of the groups it belongs to.
This affects the following functions
-.PP
+.P
.nf
.in +4n
.IR chown ()
.B _POSIX_TIMERS
option.
The following functions are present:
-.PP
+.P
.nf
.in +4n
.IR pthread_condattr_getclock ()
.IR clock_nanosleep ()
.in
.fi
-.PP
+.P
If
.B CLOCK_REALTIME
is changed by the function
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:
-.PP
+.P
.nf
.in +4n
.IR setpgid ()
.I <sys/mman.h>
is present.
The following functions are present:
-.PP
+.P
.nf
.in +4n
.IR mmap ()
.SS ML - _POSIX_MEMLOCK - _SC_MEMLOCK
Shared memory can be locked into core.
The following functions are present:
-.PP
+.P
.nf
.in +4n
.IR mlockall ()
.SS MR/MLR - _POSIX_MEMLOCK_RANGE - _SC_MEMLOCK_RANGE
More precisely, ranges can be locked into core.
The following functions are present:
-.PP
+.P
.nf
.in +4n
.IR mlock ()
.I <mqueue.h>
is present.
The following functions are present:
-.PP
+.P
.nf
.in +4n
.IR mq_close ()
.B _POSIX_TIMERS
option.
The following functions are affected:
-.PP
+.P
.nf
.in +4n
.IR aio_suspend ()
.SS PIO - _POSIX_PRIORITIZED_IO - _SC_PRIORITIZED_IO
This option says that one can specify priorities for asynchronous I/O.
This affects the functions
-.PP
+.P
.nf
.in +4n
.IR aio_read ()
.I <sched.h>
is present.
The following functions are present:
-.PP
+.P
.nf
.in +4n
.IR sched_get_priority_max ()
.IR sched_yield ()
.in
.fi
-.PP
+.P
If also
.B _POSIX_SPAWN
is in effect, then the following functions are present:
-.PP
+.P
.nf
.in +4n
.IR posix_spawnattr_getschedparam ()
.SS RS - _POSIX_RAW_SOCKETS
Raw sockets are supported.
The following functions are affected:
-.PP
+.P
.nf
.in +4n
.IR getsockopt ()
under POSIX.1-2001 the
.B _POSIX_THREADS
option implies this option.
-.PP
+.P
The following functions are present:
-.PP
+.P
.in +4n
.nf
.IR pthread_rwlock_destroy ()
.SS RTS - _POSIX_REALTIME_SIGNALS - _SC_REALTIME_SIGNALS
Realtime signals are supported.
The following functions are present:
-.PP
+.P
.nf
.in +4n
.IR sigqueue ()
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:
-.PP
+.P
.nf
.in +4n
.IR regcomp ()
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.
The following functions are affected:
-.PP
+.P
.nf
.in +4n
.IR exec ()
.I <semaphore.h>
is present.
The following functions are present:
-.PP
+.P
.nf
.in +4n
.IR sem_close ()
.fi
.SS SHM - _POSIX_SHARED_MEMORY_OBJECTS - _SC_SHARED_MEMORY_OBJECTS
The following functions are present:
-.PP
+.P
.nf
.in +4n
.IR mmap ()
it is difficult or impossible to use
.IR fork (),
for example, because no MMU is present.
-.PP
+.P
If
.B _POSIX_SPAWN
is in effect, then the include file
.I <spawn.h>
and the following functions are present:
-.PP
+.P
.nf
.in +4n
.IR posix_spawn ()
.IR posix_spawnp ()
.in
.fi
-.PP
+.P
If also
.B _POSIX_PRIORITY_SCHEDULING
is in effect, then
the following functions are present:
-.PP
+.P
.nf
.in +4n
.IR posix_spawnattr_getschedparam ()
.B _POSIX_THREAD_SAFE_FUNCTIONS
options.
The following functions are present:
-.PP
+.P
.nf
.in +4n
.IR pthread_spin_destroy ()
.B _POSIX_PRIORITY_SCHEDULING
option.
The following functions are affected:
-.PP
+.P
.nf
.in +4n
.IR sched_setparam ()
.fi
.SS SIO - _POSIX_SYNCHRONIZED_IO - _SC_SYNCHRONIZED_IO
The following functions are affected:
-.PP
+.P
.nf
.in +4n
.IR open ()
.fi
.SS TSA - _POSIX_THREAD_ATTR_STACKADDR - _SC_THREAD_ATTR_STACKADDR
The following functions are affected:
-.PP
+.P
.nf
.in +4n
.IR pthread_attr_getstack ()
.fi
.SS TSS - _POSIX_THREAD_ATTR_STACKSIZE - _SC_THREAD_ATTR_STACKSIZE
The following functions are affected:
-.PP
+.P
.nf
.in +4n
.IR pthread_attr_getstack ()
.B _POSIX_TIMERS
option.
The following functions are affected:
-.PP
+.P
.nf
.in +4n
.IR pthread_getcpuclockid ()
.fi
.SS TPI - _POSIX_THREAD_PRIO_INHERIT - _SC_THREAD_PRIO_INHERIT
The following functions are affected:
-.PP
+.P
.nf
.in +4n
.IR pthread_mutexattr_getprotocol ()
.fi
.SS TPP - _POSIX_THREAD_PRIO_PROTECT - _SC_THREAD_PRIO_PROTECT
The following functions are affected:
-.PP
+.P
.nf
.in +4n
.IR pthread_mutex_getprioceiling ()
If this option is in effect, the different threads inside a process
can run with different priorities and/or different schedulers.
The following functions are affected:
-.PP
+.P
.nf
.in +4n
.IR pthread_attr_getinheritsched ()
.fi
.SS TSH - _POSIX_THREAD_PROCESS_SHARED - _SC_THREAD_PROCESS_SHARED
The following functions are affected:
-.PP
+.P
.nf
.in +4n
.IR pthread_barrierattr_getpshared ()
.fi
.SS TSF - _POSIX_THREAD_SAFE_FUNCTIONS - _SC_THREAD_SAFE_FUNCTIONS
The following functions are affected:
-.PP
+.P
.nf
.in +4n
.IR readdir_r ()
.B _POSIX_THREAD_PRIORITY_SCHEDULING
option.
The following functions are affected:
-.PP
+.P
.nf
.in +4n
.IR sched_getparam ()
.SS THR - _POSIX_THREADS - _SC_THREADS
Basic support for POSIX threads is available.
The following functions are present:
-.PP
+.P
.nf
.in +4n
.IR pthread_atfork ()
.fi
.SS TMO - _POSIX_TIMEOUTS - _SC_TIMEOUTS
The following functions are present:
-.PP
+.P
.nf
.in +4n
.IR mq_timedreceive ()
.fi
.SS TMR - _POSIX_TIMERS - _SC_TIMERS
The following functions are present:
-.PP
+.P
.nf
.in +4n
.IR clock_getres ()
.SS TRC - _POSIX_TRACE - _SC_TRACE
POSIX tracing is available.
The following functions are present:
-.PP
+.P
.nf
.in +4n
.IR posix_trace_attr_destroy ()
.B _POSIX_TRACE
option.
The following functions are present:
-.PP
+.P
.nf
.in +4n
.IR posix_trace_eventset_add ()
.B _POSIX_TRACE
option.
The following functions are present:
-.PP
+.P
.nf
.in +4n
.IR posix_trace_attr_getinherited ()
.B _POSIX_TRACE
option.
The following functions are present:
-.PP
+.P
.nf
.in +4n
.IR posix_trace_attr_getlogfullpolicy ()
.fi
.SS TYM - _POSIX_TYPED_MEMORY_OBJECTS - _SC_TYPED_MEMORY_OBJECT
The following functions are present:
-.PP
+.P
.nf
.in +4n
.IR posix_mem_offset ()
.SH X/OPEN SYSTEM INTERFACE EXTENSIONS
.SS XSI - _XOPEN_CRYPT - _SC_XOPEN_CRYPT
The following functions are present:
-.PP
+.P
.nf
.in +4n
.IR crypt ()
.fi
.SS XSI - _XOPEN_REALTIME - _SC_XOPEN_REALTIME
This option implies the following options:
-.PP
+.P
.PD 0
.TP
.BR _POSIX_ASYNCHRONOUS_IO == 200112L
.SS ADV - --- - ---
The Advanced Realtime option group implies that the following options
are all defined to 200112L:
-.PP
+.P
.PD 0
.TP
.B _POSIX_ADVISORY_INFO
.SS XSI - _XOPEN_REALTIME_THREADS - _SC_XOPEN_REALTIME_THREADS
This option implies that the following options
are all defined to 200112L:
-.PP
+.P
.PD 0
.TP
.B _POSIX_THREAD_PRIO_INHERIT
.SS ADVANCED REALTIME THREADS - --- - ---
This option implies that the following options
are all defined to 200112L:
-.PP
+.P
.PD 0
.TP
.B _POSIX_BARRIERS
.SS TRACING - --- - ---
This option implies that the following options
are all defined to 200112L:
-.PP
+.P
.PD 0
.TP
.B _POSIX_TRACE
.PD
.SS STREAMS - _XOPEN_STREAMS - _SC_XOPEN_STREAMS
The following functions are present:
-.PP
+.P
.nf
.in +4n
.IR fattach ()
Functions included in the legacy option group were previously mandatory,
but are now optional in this version.
The following functions are present:
-.PP
+.P
.nf
.in +4n
.IR bcmp ()
.fi
.SS XSI - _XOPEN_UNIX - _SC_XOPEN_UNIX
The following functions are present:
-.PP
+.P
.nf
.in +4n
.IR mmap ()
.IR msync ()
.in
.fi
-.PP
+.P
This option implies the following options:
-.PP
+.P
.PD 0
.TP
.B _POSIX_FSYNC
.TP
.B _POSIX_THREADS
.PD
-.PP
+.P
This option may imply the following options from the XSI option groups:
-.PP
+.P
.PD 0
.TP
.RB "Encryption (" _XOPEN_CRYPT )
It is created only when a process requests it.
The process keyring has the name (description)
.IR _pid .
-.PP
+.P
A special serial number value,
.BR KEY_SPEC_PROCESS_KEYRING ,
is defined that can be used in lieu of the actual serial number of
the calling process's process keyring.
-.PP
+.P
From the
.BR keyctl (1)
utility, '\fB@p\fP' can be used instead of a numeric key ID in
much the same way, but since
.BR keyctl (1)
is a program run after forking, this is of no utility.
-.PP
+.P
A thread created using the
.BR clone (2)
.B CLONE_THREAD
.BR execve (2).
The process keyring is destroyed when the last
thread that refers to it terminates.
-.PP
+.P
If a process doesn't have a process keyring when it is accessed,
then the process keyring will be created if the keyring is to be modified;
otherwise, the error
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).
-.PP
+.P
POSIX.1 also requires that threads share a range of other attributes
(i.e., these attributes are process-wide rather than per-thread):
.IP \[bu] 3
.RB ( times (2))
and resources
.RB ( getrusage (2))
-.PP
+.P
As well as the stack, POSIX.1 specifies that various other
attributes are distinct for each thread, including:
.IP \[bu] 3
.IP \[bu]
real-time scheduling policy and priority
.RB ( sched (7))
-.PP
+.P
The following Linux-specific features are also per-thread:
.IP \[bu] 3
capabilities (see
.BR pthread_create (3),
and a thread can obtain its own thread identifier using
.BR pthread_self (3).
-.PP
+.P
Thread IDs are guaranteed to be unique only within a process.
(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.)
-.PP
+.P
The system may reuse a thread ID after a terminated thread has been joined,
or a detached thread has terminated.
POSIX says: "If an application attempts to use a thread ID whose
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.
-.PP
+.P
POSIX.1-2001 and POSIX.1-2008 require that all functions specified
in the standard shall be thread-safe,
except for the following functions:
-.PP
+.P
.in +4n
.EX
asctime()
An async-cancel-safe function is one that can be safely called
in an application where asynchronous cancelability is enabled (see
.BR pthread_setcancelstate (3)).
-.PP
+.P
Only the following functions are required to be async-cancel-safe by
POSIX.1-2001 and POSIX.1-2008:
-.PP
+.P
.in +4n
.EX
pthread_cancel()
and a cancelation request is pending for the thread,
then the thread is canceled when it calls a function
that is a cancelation point.
-.PP
+.P
The following functions are required to be cancelation points by
POSIX.1-2001 and/or POSIX.1-2008:
-.PP
+.P
.\" FIXME
.\" Document the list of all functions that are cancelation points in glibc
.in +4n
writev()
.EE
.in
-.PP
+.P
The following functions may be cancelation points according to
POSIX.1-2001 and/or POSIX.1-2008:
-.PP
+.P
.in +4n
.EX
access()
wscanf()
.EE
.in
-.PP
+.P
An implementation may also mark other functions
not specified in the standard as cancelation points.
In particular, an implementation is likely to mark
any nonstandard function that may block as a cancelation point.
(This includes most functions that can touch files.)
-.PP
+.P
It should be noted that even if an application is not using
asynchronous cancelation, that calling a function from the above list
from an asynchronous signal handler may cause the equivalent of
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.
-.PP
+.P
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
LinuxThreads threads (including the manager thread)
are visible as separate processes using
.BR ps (1).
-.PP
+.P
The LinuxThreads implementation deviates from the POSIX.1
specification in a number of ways, including the following:
.IP \[bu] 3
in the same thread group;
all members of a thread group share the same PID.
NPTL does not employ a manager thread.
-.PP
+.P
NPTL makes internal use of the first two real-time signals;
these signals cannot be used in applications.
See
.BR nptl (7)
for further details.
-.PP
+.P
NPTL still has at least one nonconformance with POSIX.1:
.IP \[bu] 3
Threads do not share a common nice value.
.\" Sep 08: there is a patch by Denys Vlasenko to address this
.\" "make setpriority POSIX compliant; introduce PRIO_THREAD extension"
.\" Monitor this to see if it makes it into mainline.
-.PP
+.P
Some NPTL nonconformances occur only with older kernels:
.IP \[bu] 3
The information returned by
are copied from the thread that created it, so that
the threads initially share an alternate signal stack
(fixed in Linux 2.6.16).
-.PP
+.P
Note the following further points about the NPTL implementation:
.IP \[bu] 3
If the stack size soft resource limit (see the description of
.BR getconf (1)
command can be used to determine
the system's threading implementation, for example:
-.PP
+.P
.in +4n
.EX
bash$ getconf GNU_LIBPTHREAD_VERSION
NPTL 2.3.4
.EE
.in
-.PP
+.P
With older glibc versions, a command such as the following should
be sufficient to determine the default threading implementation:
-.PP
+.P
.in +4n
.EX
bash$ $( ldd /bin/ls | grep libc.so | awk \[aq]{print $3}\[aq] ) | \e
(broken) application that depends on some nonconformant behavior
in LinuxThreads.)
For example:
-.PP
+.P
.in +4n
.EX
bash$ $( LD_ASSUME_KERNEL=2.2.5 ldd /bin/ls | grep libc.so | \e
.BR nptl (7),
.BR sigevent (3type),
.BR signal (7)
-.PP
+.P
Various Pthreads manual pages, for example:
.BR pthread_atfork (3),
.BR pthread_attr_init (3),
.IR master ;
the other end is called the
.IR slave .
-.PP
+.P
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,
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.
-.PP
+.P
Data flow between master and slave is handled asynchronously,
much like data flow with a physical terminal.
Data written to the slave will be available at the master promptly,
but may not be available immediately.
Similarly, there may be a small processing delay between
a write to the master, and the effect being visible at the slave.
-.PP
+.P
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.
-.PP
+.P
Linux provides both BSD-style and (standardized) System V-style
pseudoterminals.
System V-style terminals are commonly called UNIX 98 pseudoterminals
on Linux systems.
-.PP
+.P
Since Linux 2.6.4, BSD-style pseudoterminals are considered deprecated:
support can be disabled when building the kernel by disabling the
.B CONFIG_LEGACY_PTYS
.BR ptsname (3)
in a call to
.BR open (2).
-.PP
+.P
The Linux kernel imposes a limit on the number of available
UNIX 98 pseudoterminals.
Up to and including Linux 2.6.3, this limit is configured
.BR unbuffer (1),
and
.BR expect (1).
-.PP
+.P
A description of the
.B TIOCPKT
.BR ioctl (2),
which controls packet mode operation, can be found in
.BR ioctl_tty (2).
-.PP
+.P
The BSD
.BR ioctl (2)
operations
.TP
CIRCLEQ
doubly linked circular queues
-.PP
+.P
All structures support the following functionality:
.IP \[bu] 3
Insertion of a new entry at the head of the list.
Forward traversal through the list.
.\".IP \[bu]
.\" Swapping the contents of two lists.
-.PP
+.P
Code size and execution time
depend on the complexity of the data structure being used,
so programmers should take care to choose the appropriate one.
O(n) removal of any entry in the list.
.IP \[bu]
They may be concatenated.
-.PP
+.P
However:
.IP \[bu] 3
All list insertions must specify the head of the list.
.IP \[bu]
Each head entry requires two pointers rather than one.
-.PP
+.P
Singly linked tail queues are ideal for applications with
large datasets and few or no removals,
or for implementing a FIFO queue.
Insertion of a new entry before any element in the list.
.IP \[bu]
O(1) removal of any entry in the list.
-.PP
+.P
However:
.IP \[bu] 3
Each element requires two pointers rather than one.
They add the following functionality over the above:
.IP \[bu] 3
They may be traversed backwards.
-.PP
+.P
However:
.IP \[bu] 3
To traverse backwards, an entry to begin the traversal and the list in
They may be traversed backwards, from tail to head.
.IP \[bu]
They may be concatenated.
-.PP
+.P
However:
.IP \[bu] 3
All list insertions and removals must specify the head of the list.
Circular queues add the following functionality over the above:
.IP \[bu] 3
The first and last entries are connected.
-.PP
+.P
However:
.IP \[bu] 3
The termination condition for traversal is more complex.
device drivers and other sources of environmental noise to seed
a cryptographically secure pseudorandom number generator (CSPRNG).
It is designed for security, rather than speed.
-.PP
+.P
The following interfaces provide access to output from the kernel CSPRNG:
.IP \[bu] 3
The
The cryptographic algorithms used for the
.I urandom
source are quite conservative, and so should be sufficient for all purposes.
-.PP
+.P
The disadvantage of
.B GRND_RANDOM
and reads from
(it requires about 2\[ha]128 operations to break) so a key generator
needs only 128 bits (16 bytes) of seed material from
.IR /dev/random .
-.PP
+.P
While some safety margin above that minimum is reasonable, as a guard
against flaws in the CSPRNG algorithm, no cryptographic primitive
available today can hope to promise more than 256 bits of security,
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.
-.PP
+.P
The IPv4 layer generates an IP header when sending a packet unless the
.B 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.
-.PP
+.P
In order to create a raw socket, a process must have the
.B CAP_NET_RAW
capability in the user namespace that governs its network namespace.
-.PP
+.P
All packets or errors matching the
.I protocol
number specified
.UE
and
.BR getprotobyname (3).
-.PP
+.P
A protocol of
.B IPPROTO_RAW
implies enabled
Total Length:Always filled in
.TE
.RE
-.PP
+.P
If
.B IP_HDRINCL
is specified and the IP header has a nonzero destination address, then
is specified, the destination address should refer to a local interface,
otherwise a routing table lookup is done anyway but gatewayed routes
are ignored.
-.PP
+.P
If
.B IP_HDRINCL
isn't set, then IP header options can be set on raw sockets with
see
.BR ip (7)
for more information.
-.PP
+.P
Starting with Linux 2.2, all IP header fields and options can be set using
IP socket options.
This means raw sockets are usually needed only for new
protocols or protocols with no user interface (like ICMP).
-.PP
+.P
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).
The value has a bit set for each ICMP message type which
should be filtered out.
The default is to filter no ICMP messages.
-.PP
+.P
In addition, all
.BR ip (7)
.B IPPROTO_IP
.B ICMP_FILTER
are new in Linux 2.2.
They are Linux extensions and should not be used in portable programs.
-.PP
+.P
Linux 2.0 enabled some bug-to-bug compatibility with BSD in the
raw socket code when the
.B SO_BSDCOMPAT
that exceed the interface MTU.
However, disabling it is not recommended
for performance and reliability reasons.
-.PP
+.P
A raw socket can be bound to a specific local address using the
.BR bind (2)
call.
.BR SO_BINDTODEVICE ;
see
.BR socket (7).
-.PP
+.P
An
.B IPPROTO_RAW
socket is send only.
protocol.
Note that packet sockets don't reassemble IP fragments,
unlike raw sockets.
-.PP
+.P
If you want to receive all ICMP packets for a datagram socket,
it is often better to use
.B IP_RECVERR
on that particular socket; see
.BR ip (7).
-.PP
+.P
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.
-.PP
+.P
Linux never changes headers passed from the user (except for filling
in some zeroed fields as described for
.BR IP_HDRINCL ).
This differs from many other implementations of raw sockets.
-.PP
+.P
Raw sockets are generally rather unportable and should be avoided in
programs intended to be portable.
-.PP
+.P
Sending on raw sockets should take the IP protocol from
.IR sin_port ;
this ability was lost in Linux 2.2.
.BR IP_HDRINCL .
.SH BUGS
Transparent proxy extensions are not described.
-.PP
+.P
When the
.B IP_HDRINCL
option is set, datagrams will not be fragmented and are limited to
the interface MTU.
-.PP
+.P
Setting the IP protocol for sending in
.I sin_port
got lost in Linux 2.2.
.BR capabilities (7),
.BR ip (7),
.BR socket (7)
-.PP
+.P
.B RFC\ 1191
for path MTU discovery.
.B RFC\ 791
POSIX.2 leaves some aspects of RE syntax and semantics open;
"\*(dg" marks decisions on these aspects that
may not be fully portable to other POSIX.2 implementations.
-.PP
+.P
A (modern) RE is one\*(dg or more nonempty\*(dg \fIbranches\fR,
separated by \[aq]|\[aq].
It matches anything that matches one of the branches.
-.PP
+.P
A branch is one\*(dg or more \fIpieces\fR, concatenated.
It matches a match for the first, followed by a match for the second,
and so on.
-.PP
+.P
A piece is an \fIatom\fR possibly followed
by a single\*(dg \[aq]*\[aq], \[aq]+\[aq], \[aq]?\[aq], or \fIbound\fR.
An atom followed by \[aq]*\[aq]
matches a sequence of 1 or more matches of the atom.
An atom followed by \[aq]?\[aq]
matches a sequence of 0 or 1 matches of the atom.
-.PP
+.P
A \fIbound\fR is \[aq]{\[aq] followed by an unsigned decimal integer,
possibly followed by \[aq],\[aq]
possibly followed by another unsigned decimal integer,
An atom followed by a bound
containing two integers \fIi\fR and \fIj\fR matches
a sequence of \fIi\fR through \fIj\fR (inclusive) matches of the atom.
-.PP
+.P
An atom is a regular expression enclosed in "\fI()\fP"
(matching a match for the regular expression),
an empty set of "\fI()\fP" (matching the null string)\*(dg,
is an ordinary character,
not the beginning of a bound\*(dg.
It is illegal to end an RE with \[aq]\e\[aq].
-.PP
+.P
A \fIbracket expression\fR is a list of characters enclosed in "\fI[]\fP".
It normally matches any single character from the list (but see below).
If the list begins with \[aq]\[ha]\[aq],
endpoint, for example, "\fIa\-c\-e\fP".
Ranges are very collating-sequence-dependent,
and portable programs should avoid relying on them.
-.PP
+.P
To include a literal \[aq]]\[aq] in the list, make it the first character
(following a possible \[aq]\[ha]\[aq]).
To include a literal \[aq]\-\[aq], make it the first or last character,
With the exception of these and some combinations using \[aq][\[aq] (see next
paragraphs), all other special characters, including \[aq]\e\[aq], lose their
special significance within a bracket expression.
-.PP
+.P
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)
for example, if the collating sequence includes a "ch" collating element,
then the RE "\fI[[.ch.]]*c\fP" matches the first five characters
of "chchcc".
-.PP
+.P
Within a bracket expression, a collating element enclosed in "\fI[=\fP" and
"\fI=]\fP" is an equivalence class, standing for the sequences of characters
of all collating elements equivalent to that one, including itself.
and "\fI[o\(^o]\fP" are all synonymous.
An equivalence class may not\*(dg be an endpoint
of a range.
-.PP
+.P
Within a bracket expression, the name of a \fIcharacter class\fR enclosed
in "\fI[:\fP" and "\fI:]\fP" stands for the list
of all characters belonging to that
class.
Standard character class names are:
-.PP
+.P
.RS
.TS
l l l.
cntrl print xdigit
.TE
.RE
-.PP
+.P
These stand for the character classes defined in
.BR wctype (3).
A locale may provide others.
A character class may not be used as an endpoint of a range.
.\" As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=295666
.\" The following does not seem to apply in the glibc implementation
-.\" .PP
+.\" .P
.\" There are two special cases\*(dg of bracket expressions:
.\" the bracket expressions "\fI[[:<:]]\fP" and "\fI[[:>:]]\fP" match
.\" the null string at the beginning and end of a word respectively.
.\" compatible with but not specified by POSIX.2,
.\" and should be used with
.\" caution in software intended to be portable to other systems.
-.PP
+.P
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.
ones starting later.
Note that higher-level subexpressions thus take priority over
their lower-level component subexpressions.
-.PP
+.P
Match lengths are measured in characters, not collating elements.
A null string is considered longer than no match at all.
For example,
when "\fI(a*)*\fP" is matched against "bc"
both the whole RE and the parenthesized
subexpression match the null string.
-.PP
+.P
If case-independent matching is specified,
the effect is much as if all case distinctions had vanished from the
alphabet.
When it appears inside a bracket expression, all case counterparts
of it are added to the bracket expression, so that, for example, "\fI[x]\fP"
becomes "\fI[xX]\fP" and "\fI[\[ha]x]\fP" becomes "\fI[\[ha]xX]\fP".
-.PP
+.P
No particular limit is imposed on the length of REs\*(dg.
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.
-.PP
+.P
Obsolete ("basic") regular expressions differ in several respects.
\[aq]|\[aq], \[aq]+\[aq], and \[aq]?\[aq] are
ordinary characters and there is no equivalent
and \[aq]*\[aq] is an ordinary character if it appears at the beginning of the
RE or the beginning of a parenthesized subexpression
(after a possible leading \[aq]\[ha]\[aq]).
-.PP
+.P
Finally, there is one new type of atom, a \fIback reference\fR:
\[aq]\e\[aq] followed by a nonzero decimal digit \fId\fR
matches the same sequence of characters
so that, for example, "\fI\e([bc]\e)\e1\fP" matches "bb" or "cc" but not "bc".
.SH BUGS
Having two kinds of REs is a botch.
-.PP
+.P
The current POSIX.2 spec says that \[aq])\[aq] is an ordinary character in
the absence of an unmatched \[aq](\[aq];
this was an unintentional result of a wording error,
and change is likely.
Avoid relying on it.
-.PP
+.P
Back references are a dreadful botch,
posing major problems for efficient implementations.
They are also somewhat vaguely defined
(does
"\fIa\e(\e(b\e)*\e2\e)*d\fP" match "abbbd"?).
Avoid using them.
-.PP
+.P
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.
.\" As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=295666
.\" The following does not seem to apply in the glibc implementation
-.\" .PP
+.\" .P
.\" The syntax for word boundaries is incredibly ugly.
.SH AUTHOR
.\" Sigh... The page license means we must have the author's name
.SH SEE ALSO
.BR grep (1),
.BR regex (3)
-.PP
+.P
POSIX.2, section 2.8 (Regular Expression Notation).
Solaris run-time linker.
The necessary constants and prototypes are defined by including
.IR <link.h> .
-.PP
+.P
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.
-.PP
+.P
To employ the auditing interface, the environment variable
.B LD_AUDIT
must be defined to contain a colon-separated list of shared libraries,
.nf
.BI "unsigned int la_version(unsigned int " version );
.fi
-.PP
+.P
This is the only function that
.I must
be defined by an auditing library:
When invoking this function, the dynamic linker passes, in
.IR version ,
the highest version of the auditing interface that the linker supports.
-.PP
+.P
A typical implementation of this function simply returns the constant
.BR LAV_CURRENT ,
which indicates the version of
activate this audit module.
If the function returns zero, the dynamic
linker also does not activate this audit module.
-.PP
+.P
In order to enable backwards compatibility with older dynamic linkers,
an audit module can examine the
.I version
.BI "char *la_objsearch(const char *" name ", uintptr_t *" cookie ,
.BI " unsigned int " flag );
.fi
-.PP
+.P
The dynamic linker invokes this function to inform the auditing library
that it is about to search for a shared object.
The
.B LA_SER_SECURE
.I name
is specific to a secure object (unused on Linux).
-.PP
+.P
As its function result,
.BR la_objsearch ()
returns the pathname that the dynamic linker should use
.nf
.BI "void la_activity( uintptr_t *" cookie ", unsigned int "flag );
.fi
-.PP
+.P
The dynamic linker calls this function to inform the auditing library
that link-map activity is occurring.
.I cookie
.BI "unsigned int la_objopen(struct link_map *" map ", Lmid_t " lmid ,
.BI " uintptr_t *" cookie );
.fi
-.PP
+.P
The dynamic linker calls this function when a new shared object is loaded.
The
.I map
.B LM_ID_NEWLM
Link map is part of a new namespace requested via
.BR dlmopen (3).
-.PP
+.P
.I cookie
is a pointer to an identifier for this object.
The identifier is provided to later calls to functions
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.
-.PP
+.P
As its return value,
.BR la_objopen ()
returns a bit mask created by ORing zero or more of the
.TP
.B LA_FLG_BINDFROM
Audit symbol bindings from this object.
-.PP
+.P
A return value of 0 from
.BR la_objopen ()
indicates that no symbol bindings should be audited for this object.
.nf
.BI "unsigned int la_objclose(uintptr_t *" cookie );
.fi
-.PP
+.P
The dynamic linker invokes this function after any finalization
code for the object has been executed,
before the object is unloaded.
.I cookie
argument is the identifier obtained from a previous invocation of
.BR la_objopen ().
-.PP
+.P
In the current implementation, the value returned by
.BR la_objclose ()
is ignored.
.nf
.BI "void la_preinit(uintptr_t *" cookie );
.fi
-.PP
+.P
The dynamic linker invokes this function after all shared objects
have been loaded, before control is passed to the application
(i.e., before calling
.BI " uintptr_t *" refcook ", uintptr_t *" defcook ,
.BI " unsigned int *" flags ", const char *" symname );
.fi
-.PP
+.P
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
the
.BR la_symbind64 ()
function is employed on 64-bit platforms.
-.PP
+.P
The
.I sym
argument is a pointer to a structure
Among the fields of this structure,
.I st_value
indicates the address to which the symbol is bound.
-.PP
+.P
The
.I ndx
argument gives the index of the symbol in the symbol table
of the bound shared object.
-.PP
+.P
The
.I refcook
argument identifies the shared object that is making the symbol reference;
.BR la_objopen ()
function that returned
.BR LA_FLG_BINDTO .
-.PP
+.P
The
.I symname
argument points a string containing the name of the symbol.
-.PP
+.P
The
.I flags
argument is a bit mask that both provides information about the symbol
A previous
.BR la_symbind* ()
call returned an alternate value for this symbol.
-.PP
+.P
By default, if the auditing library implements
.BR la_pltenter ()
and
Don't call
.BR la_pltexit ()
for this symbol.
-.PP
+.P
The return value of
.BR la_symbind32 ()
and
(The appropriate definition is supplied by
.IR <link.h> .)
Here is the definition for x86-32:
-.PP
+.P
.nf
.BI "Elf32_Addr la_i86_gnu_pltenter(Elf32_Sym *" sym ", unsigned int " ndx ,
.BI " uintptr_t *" refcook ", uintptr_t *" defcook ,
.BI " La_i86_regs *" regs ", unsigned int *" flags ,
.BI " const char *" symname ", long *" framesizep );
.fi
-.PP
+.P
This function is invoked just before a PLT entry is called,
between two shared objects that have been marked for binding notification.
-.PP
+.P
The
.IR sym ,
.IR ndx ,
.I symname
are as for
.BR la_symbind* ().
-.PP
+.P
The
.I regs
argument points to a structure (defined in
.IR <link.h> )
containing the values of registers to be used for
the call to this PLT entry.
-.PP
+.P
The
.I 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
.BR la_symbind* ().
-.PP
+.P
.\" FIXME . Is the following correct?
The
.I framesizep
.BR la_pltexit ()
function is called only if this buffer is
explicitly set to a suitable value.
-.PP
+.P
The return value of
.BR la_pltenter ()
is as for
(The appropriate definition is supplied by
.IR <link.h> .)
Here is the definition for x86-32:
-.PP
+.P
.nf
.BI "unsigned int la_i86_gnu_pltexit(Elf32_Sym *" sym ", unsigned int " ndx ,
.BI " uintptr_t *" refcook ", uintptr_t *" defcook ,
.BI " const La_i86_regs *" inregs ", La_i86_retval *" outregs ,
.BI " const char *" symname );
.fi
-.PP
+.P
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.
-.PP
+.P
The
.IR sym ,
.IR ndx ,
.I symname
are as for
.BR la_symbind* ().
-.PP
+.P
The
.I inregs
argument points to a structure (defined in
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.
-.PP
+.P
In the current GNU implementation, the return value of
.BR la_pltexit ()
is ignored.
.B #include <linux/netlink.h>
.B #include <linux/rtnetlink.h>
.B #include <sys/socket.h>
-.PP
+.P
.BI "rtnetlink_socket = socket(AF_NETLINK, int " socket_type ", NETLINK_ROUTE);"
.fi
.SH DESCRIPTION
.\" FIXME . ? all these macros could be moved to rtnetlink(3)
.SS Routing attributes
Some rtnetlink messages have optional attributes after the initial header:
-.PP
+.P
.in +4n
.EX
struct rtattr {
};
.EE
.in
-.PP
+.P
These attributes should be manipulated using only the RTA_* macros
or libnetlink, see
.BR rtnetlink (3).
.IR sched_priority .
The scheduler makes its decisions based on knowledge of the scheduling
policy and static priority of all threads on the system.
-.PP
+.P
For threads scheduled under one of the normal scheduling policies
(\fBSCHED_OTHER\fP, \fBSCHED_IDLE\fP, \fBSCHED_BATCH\fP),
\fIsched_priority\fP is not used in scheduling
decisions (it must be specified as 0).
-.PP
+.P
Processes scheduled under one of the real-time policies
(\fBSCHED_FIFO\fP, \fBSCHED_RR\fP) have a
\fIsched_priority\fP value in the range 1 (low) to 99 (high).
and
.BR sched_get_priority_max (2)
to find the range of priorities supported for a particular policy.
-.PP
+.P
Conceptually, the scheduler maintains a list of runnable
threads for each possible \fIsched_priority\fP value.
In order to determine which thread runs next, the scheduler looks for
the nonempty list with the highest static priority and selects the
thread at the head of this list.
-.PP
+.P
A thread's scheduling policy determines
where it will be inserted into the list of threads
with equal static priority and how it will move inside this list.
-.PP
+.P
All scheduling is preemptive: if a thread with a higher static
priority becomes ready to run, the currently running thread
will be preempted and
A thread calling
.BR sched_yield (2)
will be put at the end of the list.
-.PP
+.P
No other events will move a thread
scheduled under the \fBSCHED_FIFO\fP policy in the wait list of
runnable threads with equal static priority.
-.PP
+.P
A \fBSCHED_FIFO\fP
thread runs until either it is blocked by an I/O request, it is
preempted by a higher priority thread, or it calls
and
.BR sched_getattr (2)
system calls.
-.PP
+.P
A sporadic task is one that has a sequence of jobs, where each
job is activated at most once per period.
Each job also has a
The
.I absolute deadline
is thus obtained by adding the relative deadline to the arrival time.
-.PP
+.P
The following diagram clarifies these terms:
-.PP
+.P
.in +4n
.EX
arrival/wakeup absolute deadline
|<-------------- period ------------------->|
.EE
.in
-.PP
+.P
When setting a
.B SCHED_DEADLINE
policy for a thread using
Thus, for
.B SCHED_DEADLINE
scheduling, we have:
-.PP
+.P
.in +4n
.EX
arrival/wakeup absolute deadline
|<-------------- Period ------------------->|
.EE
.in
-.PP
+.P
The three deadline-scheduling parameters correspond to the
.IR sched_runtime ,
.IR sched_deadline ,
.I sched_period
is specified as 0, then it is made the same as
.IR sched_deadline .
-.PP
+.P
The kernel requires that:
-.PP
+.P
.in +4n
.EX
sched_runtime <= sched_deadline <= sched_period
.EE
.in
-.PP
+.P
.\" See __checkparam_dl in kernel/sched/core.c
In addition, under the current implementation,
all of the parameter values must be at least 1024
.BR sched_setattr (2)
fails with the error
.BR EINVAL .
-.PP
+.P
The CBS guarantees non-interference between tasks, by throttling
threads that attempt to over-run their specified Runtime.
-.PP
+.P
To ensure deadline scheduling guarantees,
the kernel must prevent situations where the set of
.B SCHED_DEADLINE
.BR sched_setattr (2)
fails with the error
.BR EBUSY .
-.PP
+.P
For example, it is required (but not necessarily sufficient) for
the total utilization to be less than or equal to the total number of
CPUs available, where, since each thread can maximally run for
Runtime per Period, that thread's utilization is its
Runtime divided by its Period.
-.PP
+.P
In order to fulfill the guarantees that are made when
a thread is admitted to the
.B SCHED_DEADLINE
.B SCHED_DEADLINE
thread is runnable,
it will preempt any thread scheduled under one of the other policies.
-.PP
+.P
A call to
.BR fork (2)
by a thread scheduled under the
policy fails with the error
.BR EAGAIN ,
unless the thread has its reset-on-fork flag set (see below).
-.PP
+.P
A
.B SCHED_DEADLINE
thread that calls
\fBSCHED_OTHER\fP is the standard Linux time-sharing scheduler that is
intended for all threads that do not require the special
real-time mechanisms.
-.PP
+.P
The thread to run is chosen from the static
priority 0 list based on a \fIdynamic\fP priority that is determined only
inside this list.
and is increased for each time quantum the thread is ready to run,
but denied to run by the scheduler.
This ensures fair progress among all \fBSCHED_OTHER\fP threads.
-.PP
+.P
In the Linux kernel source code, the
.B SCHED_OTHER
policy is actually named
.BR setpriority (2),
or
.BR sched_setattr (2).
-.PP
+.P
According to POSIX.1, the nice value is a per-process attribute;
that is, the threads in a process should share a nice value.
However, on Linux, the nice value is a per-thread attribute:
different threads in the same process may have different nice values.
-.PP
+.P
The range of the nice value
varies across UNIX systems.
On modern Linux, the range is \-20 (high priority) to +19 (low priority).
Very early Linux kernels (before Linux 2.0) had the range \-infinity..15.
.\" Linux before 1.3.36 had \-infinity..15.
.\" Since Linux 1.3.43, Linux has the range \-20..19.
-.PP
+.P
The degree to which the nice value affects the relative scheduling of
.B SCHED_OTHER
processes likewise varies across UNIX systems and
across Linux kernel versions.
-.PP
+.P
With the advent of the CFS scheduler in Linux 2.6.23,
Linux adopted an algorithm that causes
relative differences in nice values to have a much stronger effect.
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).
-.PP
+.P
On Linux, the
.B RLIMIT_NICE
resource limit can be used to define a limit to which
an unprivileged process's nice value can be raised; see
.BR setrlimit (2)
for details.
-.PP
+.P
For further details on the nice value, see the subsections on
the autogroup feature and group scheduling, below.
.\"
Consequently, the scheduler will apply a small scheduling
penalty with respect to wakeup behavior,
so that this thread is mildly disfavored in scheduling decisions.
-.PP
+.P
.\" The following paragraph is drawn largely from the text that
.\" accompanied Ingo Molnar's patch for the implementation of
.\" SCHED_BATCH.
(Since Linux 2.6.23.)
\fBSCHED_IDLE\fP can be used only at static priority 0;
the process nice value has no influence for this policy.
-.PP
+.P
This policy is intended for running jobs at extremely low
priority (lower even than a +19 nice value with the
.B SCHED_OTHER
.I attr.sched_flags
when calling
.BR sched_setattr (2).
-.PP
+.P
Note that the constants used with these two APIs have different names.
The state of the reset-on-fork flag can analogously be retrieved using
.BR sched_getscheduler (2)
and
.BR sched_getattr (2).
-.PP
+.P
The reset-on-fork feature is intended for media-playback applications,
and can be used to prevent applications evading the
.B RLIMIT_RTTIME
resource limit (see
.BR getrlimit (2))
by creating multiple child processes.
-.PP
+.P
More precisely, if the reset-on-fork flag is set,
the following rules apply for subsequently created children:
.IP \[bu] 3
.IP \[bu]
If the calling process has a negative nice value,
the nice value is reset to zero in child processes.
-.PP
+.P
After the reset-on-fork flag has been enabled,
it can be reset only if the thread has the
.B CAP_SYS_NICE
(i.e., the thread specified by
.IR pid )
whose policy is being changed.
-.PP
+.P
A thread must be privileged
.RB ( CAP_SYS_NICE )
in order to set or modify a
.B SCHED_DEADLINE
policy.
-.PP
+.P
Since Linux 2.6.12, the
.B RLIMIT_RTPRIO
resource limit defines a ceiling on an unprivileged thread's
.B RLIMIT_NICE
resource limit (see
.BR getrlimit (2)).
-.PP
+.P
Privileged
.RB ( CAP_SYS_NICE )
threads ignore the
a shell scheduled under a higher static priority than the tested application.
This allows an emergency kill of tested
real-time applications that do not block or terminate as expected.
-.PP
+.P
Since Linux 2.6.25, there are other techniques for dealing with runaway
real-time and deadline processes.
One of these is to use the
See
.BR getrlimit (2)
for details.
-.PP
+.P
Since Linux 2.6.25, Linux also provides two
.I /proc
files that can be used to reserve a certain amount of CPU time
.BR fork (2).
The scheduling policy and parameters are preserved across
.BR execve (2).
-.PP
+.P
Memory locking is usually needed for real-time processes to avoid
paging delays; this can be done with
.BR mlock (2)
.BR make (1)
.B \-j
flag).
-.PP
+.P
This feature operates in conjunction with the
CFS scheduler and requires a kernel that is configured with
.BR CONFIG_SCHED_AUTOGROUP .
The default value in this file is 1, unless the kernel was booted with the
.I noautogroup
parameter.
-.PP
+.P
A new autogroup is created when a new session is created via
.BR setsid (2);
this happens, for example, when a new terminal window is started.
Thus, all of the processes in a session are members of the same autogroup.
An autogroup is automatically destroyed when the last process
in the group terminates.
-.PP
+.P
When autogrouping is enabled, all of the members of an autogroup
are placed in the same kernel scheduler "task group".
The CFS scheduler employs an algorithm that equalizes the
distribution of CPU cycles across task groups.
The benefits of this for interactive desktop performance
can be described via the following example.
-.PP
+.P
Suppose that there are two autogroups competing for the same CPU
(i.e., presume either a single CPU system or the use of
.BR taskset (1)
an autogroup that contains a large number of CPU-bound processes
does not end up hogging CPU cycles at the expense of the other
jobs on the system.
-.PP
+.P
A process's autogroup (task group) membership can be viewed via the file
.IR /proc/ pid /autogroup :
-.PP
+.P
.in +4n
.EX
$ \fBcat /proc/1/autogroup\fP
/autogroup\-1 nice 0
.EE
.in
-.PP
+.P
This file can also be used to modify the CPU bandwidth allocated
to an autogroup.
This is done by writing a number in the "nice" range to the file
.\" A patch was posted on 23 Nov 2016
.\" ("sched/autogroup: Fix 64bit kernel nice adjustment";
.\" check later to see in which kernel version it lands.
-.PP
+.P
The autogroup nice setting has the same meaning as the process nice value,
but applies to distribution of CPU cycles to the autogroup as a whole,
based on the relative nice values of other autogroups.
(compared to other autogroups)
and the process's nice value
(compared to other processes in the same autogroup.
-.PP
+.P
The use of the
.BR cgroups (7)
CPU controller to place processes in cgroups other than the
root CPU cgroup overrides the effect of autogrouping.
-.PP
+.P
The autogroup feature groups only processes scheduled under
non-real-time policies
.RB ( SCHED_OTHER ,
if the kernel was configured with the
.B CONFIG_FAIR_GROUP_SCHED
option (which is typical).
-.PP
+.P
Under group scheduling, threads are scheduled in "task groups".
Task groups have a hierarchical relationship,
rooted under the initial task group on the system,
.BR CONFIG_FAIR_GROUP_SCHED ),
then all of the processes on the system are notionally placed
in a single task group.
-.PP
+.P
Under group scheduling,
a thread's nice value has an effect for scheduling decisions
.IR "only relative to other threads in the same task group" .
on a process has an effect only for scheduling relative
to other processes executed in the same session
(typically: the same terminal window).
-.PP
+.P
Conversely, for two processes that are (for example)
the sole CPU-bound processes in different sessions
(e.g., different terminal windows,
the following to modify the autogroup nice value for
.I all
of the processes in a terminal session:
-.PP
+.P
.in +4n
.EX
$ \fBecho 10 > /proc/self/autogroup\fP
mainline kernel,
they must be installed to achieve the best real-time performance.
These patches are named:
-.PP
+.P
.in +4n
.EX
patch\-\fIkernelversion\fP\-rt\fIpatchversion\fP
.EE
.in
-.PP
+.P
and can be downloaded from
.UR http://www.kernel.org\:/pub\:/linux\:/kernel\:/projects\:/rt/
.UE .
-.PP
+.P
Without the patches and prior to their full inclusion into the mainline
kernel, the kernel configuration offers only the three preemption classes
.BR CONFIG_PREEMPT_NONE ,
.B CONFIG_PREEMPT_DESKTOP
which respectively provide no, some, and considerable
reduction of the worst-case scheduling latency.
-.PP
+.P
With the patches applied or after their full inclusion into the mainline
kernel, the additional configuration item
.B CONFIG_PREEMPT_RT
.BR cgroups (7)
CPU controller can be used to limit the CPU consumption of
groups of processes.
-.PP
+.P
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
.BR capabilities (7),
.BR cpuset (7)
.ad
-.PP
+.P
.I Programming for the real world \- POSIX.4
by Bill O.\& Gallmeister, O'Reilly & Associates, Inc., ISBN 1-56592-074-0.
-.PP
+.P
The Linux kernel source files
.IR \%Documentation/\:scheduler/\:sched\-deadline\:.txt ,
.IR \%Documentation/\:scheduler/\:sched\-rt\-group\:.txt ,
sem_overview \- overview of POSIX semaphores
.SH DESCRIPTION
POSIX semaphores allow processes and threads to synchronize their actions.
-.PP
+.P
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
If the value of a semaphore is currently zero, then a
.BR sem_wait (3)
operation will block until the value becomes greater than zero.
-.PP
+.P
POSIX semaphores come in two forms: named semaphores and
unnamed semaphores.
.TP
and before the memory in which it is located is deallocated,
the semaphore should be destroyed using
.BR sem_destroy (3).
-.PP
+.P
The remainder of this section describes some specific details
of the Linux implementation of POSIX semaphores.
.SS Versions
rather than
.B NAME_MAX
characters.)
-.PP
+.P
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.
.SH NOTES
(In typical configurations, PAM does do this revocation.)
The session keyring has the name (description)
.IR _ses .
-.PP
+.P
A special serial number value,
.BR KEY_SPEC_SESSION_KEYRING ,
is defined that can be used in lieu of the actual serial number of
the calling process's session keyring.
-.PP
+.P
From the
.BR keyctl (1)
utility, '\fB@s\fP' can be used instead of a numeric key ID in
much the same way.
-.PP
+.P
A process's session keyring is inherited across
.BR clone (2),
.BR fork (2),
even when the executable is set-user-ID or set-group-ID or has capabilities.
The session keyring is destroyed when the last process that
refers to it exits.
-.PP
+.P
If a process doesn't have a session keyring when it is accessed, then,
under certain circumstances, the
.BR user\-session\-keyring (7)
.BR keyctl (2)
.B KEYCTL_SESSION_TO_PARENT
operation.)
-.PP
+.P
These operations are also exposed through the
.BR keyctl (1)
utility as:
-.PP
+.P
.in +4n
.EX
keyctl session
keyctl session <name> [<prog> <arg1> <arg2> ...]
.EE
.in
-.PP
+.P
and:
-.PP
+.P
.in +4n
.EX
keyctl new_session
.SH DESCRIPTION
The POSIX shared memory API allows processes to communicate information
by sharing a region of memory.
-.PP
+.P
The interfaces employed in the API are:
.TP 15
.BR shm_open (3)
.SH NOTES
Typically, processes must synchronize their access to a shared
memory object, using, for example, POSIX semaphores.
-.PP
+.P
System V shared memory
.RB ( shmget (2),
.BR shmop (2),
async-signal-safe.
In particular,
nonreentrant functions are generally unsafe to call from a signal handler.
-.PP
+.P
The kinds of issues that render a function
unsafe can be quickly understood when one considers
the implementation of the
.I stdio
library, all of whose functions are not async-signal-safe.
-.PP
+.P
When performing buffered I/O on a file, the
.I stdio
functions must maintain a statically allocated data buffer
then the second call to
.BR printf (3)
will operate on inconsistent data, with unpredictable results.
-.PP
+.P
To avoid problems with unsafe functions, there are two possible choices:
.IP (a) 5
Ensure that
Block signal delivery in the main program when calling functions
that are unsafe or operating on global data that is also accessed
by the signal handler.
-.PP
+.P
Generally, the second choice is difficult in programs of any complexity,
so the first choice is taken.
-.PP
+.P
POSIX.1 specifies a set of functions that an implementation
must make async-signal-safe.
(An implementation may provide safe implementations of additional functions,
but this is not required by the standard and other implementations
may not provide the same guarantees.)
-.PP
+.P
In general, a function is async-signal-safe either because it is reentrant
or because it is atomic with respect to signals
(i.e., its execution can't be interrupted by a signal handler).
-.PP
+.P
The set of functions required to be async-signal-safe by POSIX.1
is shown in the following table.
The functions not otherwise noted were required to be async-signal-safe
in POSIX.1-2001;
the table details changes in the subsequent standards.
-.PP
+.P
.TS
lb lb
l l.
\fBwmemset\fP(3) Added in POSIX.1-2008 TC2
\fBwrite\fP(2)
.TE
-.PP
+.P
Notes:
.IP \[bu] 3
POSIX.1-2001 and POSIX.1-2001 TC2 required the functions
.IR disposition ,
which determines how the process behaves when it is delivered
the signal.
-.PP
+.P
The entries in the "Action" column of the table below specify
the default disposition for each signal, as follows:
.TP
.TP
Cont
Default action is to continue the process if it is currently stopped.
-.PP
+.P
A process can change the disposition of a signal using
.BR sigaction (2)
or
.IR "signal handler" ,
a programmer-defined function that is automatically invoked
when the signal is delivered.
-.PP
+.P
By default, a signal handler is invoked on the
normal process stack.
It is possible to arrange that the signal handler
uses an alternate stack; see
.BR sigaltstack (2)
for a discussion of how to do this and when it might be useful.
-.PP
+.P
The signal disposition is a per-process attribute:
in a multithreaded application, the disposition of a
particular signal is the same for all threads.
-.PP
+.P
A child created via
.BR fork (2)
inherits a copy of its parent's signal dispositions.
Between the time when it is generated and when it is delivered
a signal is said to be
.IR pending .
-.PP
+.P
Each thread in a process has an independent
.IR "signal mask" ,
which indicates the set of signals that the thread is currently blocking.
In a traditional single-threaded application,
.BR sigprocmask (2)
can be used to manipulate the signal mask.
-.PP
+.P
A child created via
.BR fork (2)
inherits a copy of its parent's signal mask;
the signal mask is preserved across
.BR execve (2).
-.PP
+.P
A signal may be process-directed or thread-directed.
A process-directed signal is one that is targeted at (and thus pending for)
the process as a whole.
.BR tgkill (2)
or
.BR pthread_kill (3).
-.PP
+.P
A process-directed signal may be delivered to any one of the
threads that does not currently have the signal blocked.
.\" Joseph C. Sible notes:
.\"
If more than one of the threads has the signal unblocked, then the
kernel chooses an arbitrary thread to which to deliver the signal.
-.PP
+.P
A thread can obtain the set of signals that it currently has pending
using
.BR 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.
-.PP
+.P
A child created via
.BR fork (2)
initially has an empty pending signal set;
the kernel transfers control back to user space,
and the thread recommences execution at the point where it was
interrupted by the signal handler.
-.PP
+.P
Note that if the signal handler does not return
(e.g., control is transferred out of the handler using
.BR siglongjmp (3),
.I savesigs
value that was specified in the corresponding call to
.BR sigsetjmp (3).)
-.PP
+.P
From the kernel's point of view,
execution of the signal handler code is exactly the same as the execution
of any other user-space code.
see \fBsetrlimit\fP(2)
SIGWINCH \- Ign Window resize signal (4.3BSD, Sun)
.TE
-.PP
+.P
The signals
.B SIGKILL
and
.B SIGSTOP
cannot be caught, blocked, or ignored.
-.PP
+.P
Up to and including Linux 2.2, the default behavior for
.BR SIGSYS ", " SIGXCPU ", " SIGXFSZ ,
and (on architectures other than SPARC and MIPS)
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.
-.PP
+.P
.B 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.
-.PP
+.P
.B SIGPWR
(which is not specified in POSIX.1-2001) is typically ignored
by default on those other UNIX systems where it appears.
-.PP
+.P
.B SIGIO
(which is not specified in POSIX.1-2001) is ignored by default
on several other UNIX systems.
.SS Queueing and delivery semantics for standard signals
If multiple standard signals are pending for a process,
the order in which the signals are delivered is unspecified.
-.PP
+.P
Standard signals do not queue.
If multiple instances of a standard signal are generated while
that signal is blocked,
SIGSYS 31 12 12 31
SIGUNUSED 31 \- \- 31
.TE
-.PP
+.P
Note the following:
.IP \[bu] 3
Where defined,
POSIX.1-2001 requires that an implementation support at least
.B _POSIX_RTSIG_MAX
(8) real-time signals.
-.PP
+.P
The Linux kernel supports a range of 33 different real-time
signals, numbered 32 to 64.
However, the glibc POSIX threads implementation internally uses
.BR SIGRTMIN +n
does not exceed
.BR SIGRTMAX .
-.PP
+.P
Unlike standard signals, real-time signals have no predefined meanings:
the entire set of real-time signals can be used for application-defined
purposes.
-.PP
+.P
The default action for an unhandled real-time signal is to terminate the
receiving process.
-.PP
+.P
Real-time signals are distinguished by the following:
.IP \[bu] 3
Multiple instances of real-time signals can be queued.
(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.
-.PP
+.P
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.
-.PP
+.P
According to POSIX, an implementation should permit at least
.B _POSIX_SIGQUEUE_MAX
(32) real-time signals to be queued to
signals; see
.BR setrlimit (2)
for further details.
-.PP
+.P
The addition of real-time signals required the widening
of the signal set structure
.RI ( sigset_t )
.IP \[bu]
the call fails with the error
.BR EINTR .
-.PP
+.P
Which of these two behaviors occurs depends on the interface and
whether or not the signal handler was established using the
.B SA_RESTART
.BR sigaction (2)).
The details vary across UNIX systems;
below, the details for Linux.
-.PP
+.P
If a blocked call to one of the following interfaces is interrupted
by a signal handler, then the call is automatically restarted
after the signal handler returns if the
.\" commit 1ca39ab9d21ac93f94b9e3eb364ea9a5cf2aba06
beforehand, always failed with
.BR EINTR ).
-.PP
+.P
The following interfaces are never restarted after
being interrupted by a signal handler,
regardless of the use of
.BR usleep (3).
.IP \[bu]
.BR io_getevents (2).
-.PP
+.P
The
.BR sleep (3)
function is also never restarted if interrupted by a handler,
but gives a success return: the number of seconds remaining to sleep.
-.PP
+.P
In certain circumstances, the
.BR seccomp (2)
user-space notification feature can lead to restarting of system calls
.BR SIGCONT .
This behavior is not sanctioned by POSIX.1, and doesn't occur
on other systems.
-.PP
+.P
The Linux interfaces that display this behavior are:
.IP \[bu] 3
"Input" socket interfaces, when a timeout
.SH NOTES
For a discussion of async-signal-safe functions, see
.BR signal\-safety (7).
-.PP
+.P
The
.IR /proc/ pid /task/ tid /status
file contains various fields that show the signals
Which of these signals is delivered,
for any given hardware exception,
is not documented and does not always make sense.
-.PP
+.P
For example, an invalid memory access that causes delivery of
.B SIGSEGV
on one CPU architecture may cause delivery of
.B SIGBUS
on another architecture, or vice versa.
-.PP
+.P
For another example, using the x86
.I int
instruction with a forbidden argument
.B #include <linux/sock_diag.h>
.BR "#include <linux/unix_diag.h>" " /* for UNIX domain sockets */"
.BR "#include <linux/inet_diag.h>" " /* for IPv4 and IPv6 sockets */"
-.PP
+.P
.BI "diag_socket = socket(AF_NETLINK, " socket_type ", NETLINK_SOCK_DIAG);"
.fi
.SH DESCRIPTION
information about sockets of various address families from the kernel.
This subsystem can be used to obtain information about individual
sockets or request a list of sockets.
-.PP
+.P
In the request, the caller can specify additional information it would
like to obtain about the socket, for example, memory information or
information specific to the address family.
-.PP
+.P
When requesting a list of sockets, the caller can specify filters that
would be applied by the kernel to select a subset of sockets to report.
For now, there is only the ability to filter sockets by state (connected,
listening, and so on.)
-.PP
+.P
Note that sock_diag reports only those sockets that have a name;
that is, either sockets bound explicitly with
.BR bind (2)
.BR SOCK_DIAG_BY_FAMILY .
It is followed by a header specific to the address family that starts with
a common part shared by all address families:
-.PP
+.P
.in +4n
.EX
struct sock_diag_req {
};
.EE
.in
-.PP
+.P
The fields of this structure are as follows:
.TP
.I sdiag_family
and
.BR AF_INET6 ,
and to 0 otherwise.
-.PP
+.P
If the
.I nlmsg_flags
field of the
macros from the
.BR netlink (3)
API.
-.PP
+.P
Each object is the NLA (netlink attributes) list that is to be accessed
with the
.B RTA_*
.\"
.SS UNIX domain sockets
For UNIX domain sockets the request is represented in the following structure:
-.PP
+.P
.in +4n
.EX
struct unix_diag_req {
};
.EE
.in
-.PP
+.P
The fields of this structure are as follows:
.TP
.I sdiag_family
The address family; it should be set to
.BR AF_UNIX .
-.PP
+.P
.I sdiag_protocol
.PD 0
.TP
Only those sockets whose states are in this mask will be reported.
Ignored when querying for an individual socket.
Supported values are:
-.PP
+.P
.RS 12
1 <<
.B TCP_ESTABLISHED
-.PP
+.P
1 <<
.B TCP_LISTEN
.RE
.BR UNIX_DIAG_MEMINFO .
The payload associated with this attribute is an array of __u32 values
described below in the subsection "Socket memory information".
-.PP
+.P
The following attributes are reported back without any specific request:
.TP
.B UNIX_DIAG_SHUTDOWN
to specify an individual socket.
It is ignored when querying for a list
of sockets, as well as when all its elements are set to \-1.
-.PP
+.P
The response to a query for UNIX domain sockets is represented as an array of
-.PP
+.P
.in +4n
.EX
struct unix_diag_msg {
};
.EE
.in
-.PP
+.P
followed by netlink attributes.
-.PP
+.P
The fields of this structure are as follows:
.TP
.I udiag_family
.SS IPv4 and IPv6 sockets
For IPv4 and IPv6 sockets,
the request is represented in the following structure:
-.PP
+.P
.in +4n
.EX
struct inet_diag_req_v2 {
};
.EE
.in
-.PP
+.P
where
.I "struct inet_diag_sockid"
is defined as follows:
-.PP
+.P
.in +4n
.EX
struct inet_diag_sockid {
};
.EE
.in
-.PP
+.P
The fields of
.I "struct inet_diag_req_v2"
are as follows:
Unlike UNIX domain sockets, IPv4 and IPv6 sockets are identified
using addresses and ports.
All values are in network byte order.
-.PP
+.P
The fields of
.I "struct inet_diag_sockid"
are as follows:
other fields of this structure to specify an individual socket.
It is ignored when querying for a list of sockets, as well as
when all its elements are set to \-1.
-.PP
+.P
The response to a query for IPv4 or IPv6 sockets is represented as an array of
-.PP
+.P
.in +4n
.EX
struct inet_diag_msg {
};
.EE
.in
-.PP
+.P
followed by netlink attributes.
-.PP
+.P
The fields of this structure are as follows:
.TP
.I idiag_family
and extended to support
.B AF_UNIX
sockets.
-.PP
+.P
.B UNIX_DIAG_MEMINFO
and
.B INET_DIAG_SKMEMINFO
.SH EXAMPLES
The following example program prints inode number, peer's inode number,
and name of all UNIX domain sockets in the current namespace.
-.PP
+.P
.EX
#include <errno.h>
#include <stdio.h>
.SH SYNOPSIS
.nf
.B #include <sys/socket.h>
-.PP
+.P
.IB sockfd " = socket(int " socket_family ", int " socket_type ", int " protocol );
.fi
.SH DESCRIPTION
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.
-.PP
+.P
.BR socket (2)
creates a socket,
.BR connect (2)
returns two connected anonymous sockets (implemented only for a few
local families like
.BR AF_UNIX )
-.PP
+.P
.BR send (2),
.BR sendto (2),
and
and
.BR readv (2)
can be used to read and write data.
-.PP
+.P
.BR getsockname (2)
returns the local socket address and
.BR getpeername (2)
are used to set or get socket layer or protocol options.
.BR ioctl (2)
can be used to set or read some other options.
-.PP
+.P
.BR close (2)
is used to close a socket.
.BR shutdown (2)
closes parts of a full-duplex socket connection.
-.PP
+.P
Seeking, or calling
.BR pread (2)
or
.BR pwrite (2)
with a nonzero position is not supported on sockets.
-.PP
+.P
It is possible to do nonblocking I/O on sockets by setting the
.B O_NONBLOCK
flag on a socket file descriptor using
.\" or
.\" .BR close (2).
.TE
-.PP
+.P
An alternative to
.BR poll (2)
and
.BR getpeername (2)),
which are generic to all socket domains,
to determine the domain of a particular socket address.
-.PP
+.P
To allow any type of socket address to be passed to
interfaces in the sockets API,
the type
domain-specific socket address types to a "generic" type,
so as to avoid compiler warnings about type mismatches in
calls to the sockets API.
-.PP
+.P
In addition, the sockets API provides the data type
.IR "struct sockaddr_storage".
This type
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:
-.PP
+.P
.in +4n
.EX
sa_family_t ss_family;
.EE
.in
-.PP
+.P
The
.I sockaddr_storage
structure is useful in programs that must handle socket addresses
specified the
.B MSG_NOSIGNAL
flag.
-.PP
+.P
When requested with the
.B FIOSETOWN
.BR fcntl (2)
See
.BR fcntl (2)
for more information.
-.PP
+.P
Under some circumstances (e.g., multiple processes accessing a
single socket), the condition that caused the
.B SIGIO
.SS Ioctls
These operations can be accessed using
.BR ioctl (2):
-.PP
+.P
.in +4n
.EX
.IB error " = ioctl(" ip_socket ", " ioctl_type ", " &value_result ");"
signals,
or 0
when none is set.
-.PP
+.P
Valid
.BR fcntl (2)
operations:
kernel structures; thus the values in the corresponding
.I /proc
files are twice what can be observed on the wire.
-.PP
+.P
Linux will allow port reuse only with the
.B SO_REUSEADDR
option
The SPU filesystem is used on PowerPC machines that implement the
Cell Broadband Engine Architecture in order to access Synergistic
Processor Units (SPUs).
-.PP
+.P
The filesystem provides a name space similar to POSIX shared
memory or message queues.
Users that have write permissions
to establish SPU contexts under the
.B spufs
root directory.
-.PP
+.P
Every SPU context is represented by a directory containing
a predefined set of files.
These files can be
This list details the supported
operations and the deviations from the standard behavior described
in the respective man pages.
-.PP
+.P
All files that support the
.BR read (2)
operation also support
.IR st_uid ,
and
.IR st_gid .
-.PP
+.P
All files support the
.BR chmod (2)/\c
.BR fchmod (2)
the possible operations (e.g., read access on the
.I wbox
file).
-.PP
+.P
The current set of files is:
.TP
.I /capabilities
.TP
.B step
This context can be run in single-step mode, for debugging.
-.PP
+.P
New capabilities flags may be added in the future.
.RE
.TP
.BR spu_create (2),
.BR spu_run (2),
.BR capabilities (7)
-.PP
+.P
.I The Cell Broadband Engine Architecture (CBEA) specification
.B SUSv4 2018 edition
This is equivalent to POSIX.1-2017, with the addition of
the XCurses specification.
-.PP
+.P
The interfaces documented in POSIX.1/SUS are available as
manual pages under sections 0p (header files), 1p (commands),
and 3p (functions);
.nf
// Chain-copy a string.
.BI "char *stpcpy(char *restrict " dst ", const char *restrict " src );
-.PP
+.P
// Copy/catenate a string.
.BI "char *strcpy(char *restrict " dst ", const char *restrict " src );
.BI "char *strcat(char *restrict " dst ", const char *restrict " src );
-.PP
+.P
// Chain-copy a string with truncation.
.BI "char *stpecpy(char *" dst ", char " end "[0], const char *restrict " src );
-.PP
+.P
// Copy/catenate a string with truncation.
.BI "size_t strlcpy(char " dst "[restrict ." sz "], \
const char *restrict " src ,
.BI "char *stpncpy(char " dst "[restrict ." sz "], \
const char *restrict " src ,
.BI " size_t " sz );
-.PP
+.P
// Zero a fixed-width buffer, and
// copy a string into a character sequence with truncation.
.BI "char *strncpy(char " dst "[restrict ." sz "], \
const char *restrict " src ,
.BI " size_t " sz );
-.PP
+.P
// Chain-copy a null-padded character sequence into a character sequence.
.BI "char *zustr2ustp(char *restrict " dst ", \
const char " src "[restrict ." sz ],
.BI " size_t " sz );
-.PP
+.P
// Chain-copy a null-padded character sequence into a string.
.BI "char *zustr2stp(char *restrict " dst ", \
const char " src "[restrict ." sz ],
.BI " size_t " sz );
-.PP
+.P
// Catenate a null-padded character sequence into a string.
.BI "char *strncat(char *restrict " dst ", const char " src "[restrict ." sz ],
.BI " size_t " sz );
.BI "char *ustpcpy(char *restrict " dst ", \
const char " src "[restrict ." len ],
.BI " size_t " len );
-.PP
+.P
// Chain-copy a measured character sequence into a string.
.BI "char *ustr2stp(char *restrict " dst ", \
const char " src "[restrict ." len ],
However, functions that catenate have a much simpler use,
so if performance is not important,
it can make sense to use them for improving readability.
-.PP
+.P
The pointer returned by functions that allow chaining
is a byproduct of the copy operation,
so it has no performance costs.
.RB * stp *(),
since it's common to name the pointer just
.IR p .
-.PP
+.P
Chain-copying functions that truncate
should accept a pointer to the end of the destination buffer,
and have names of the form
The first thing to note is that programmers should be careful with buffers,
so they always have the correct size,
and truncation is not necessary.
-.PP
+.P
In most cases,
truncation is not desired,
and it is simpler to just do the copy.
Simpler code is safer code.
Programming against programming mistakes by adding more code
just adds more points where mistakes can be made.
-.PP
+.P
Nowadays,
compilers can detect most programmer errors with features like
compiler warnings,
.BR ftm (7)).
Keeping the code simple
helps these overflow-detection features be more precise.
-.PP
+.P
When validating user input,
however,
it makes sense to truncate.
Remember to check the return value of such function calls.
-.PP
+.P
Functions that truncate:
.IP \[bu] 3
.BR stpecpy (3)
use null-padded character sequences in fixed-width buffers.
To interface with them,
specialized functions need to be used.
-.PP
+.P
To copy strings into them, use
.BR stpncpy (3).
-.PP
+.P
To copy from an unterminated string within a fixed-width buffer into a string,
ignoring any trailing null bytes in the source fixed-width buffer,
you should use
.BR zustr2stp (3)
or
.BR strncat (3).
-.PP
+.P
To copy from an unterminated string within a fixed-width buffer
into a character sequence,
ignoring any trailing null bytes in the source fixed-width buffer,
.BR mempcpy (3)
copies character sequences,
so you need to explicitly set the terminating null byte if you need a string.
-.PP
+.P
However,
for keeping type safety,
it's good to add a wrapper that uses
instead of
.IR void\~* :
.BR ustpcpy (3).
-.PP
+.P
In programs that make considerable use of strings or character sequences,
and need the best performance,
using overlapping character sequences can make a big difference.
It allows holding subsequences of a larger character sequence,
while not duplicating memory
nor using time to do a copy.
-.PP
+.P
However, this is delicate,
since it requires using character sequences.
C library APIs use strings,
so programs that use character sequences
will have to take care of differentiating strings from character sequences.
-.PP
+.P
To copy a measured character sequence, use
.BR ustpcpy (3).
-.PP
+.P
To copy a measured character sequence into a string, use
.BR ustr2stp (3).
-.PP
+.P
Because these functions ask for the length,
and a string is by nature composed of a character sequence of the same length
plus a terminating null byte,
.BR strlcpy (3bsd),
.BR strlcat (3bsd)
.PD
-.PP
+.P
Other functions require an input string,
but create a character sequence as output.
These functions have confusing names,
.IP \[bu]
.BR strncpy (3)
.PD
-.PP
+.P
Other functions operate on an input character sequence,
and create an output string.
Functions that catenate
.IP \[bu]
.BR ustr2stp (3)
.PD
-.PP
+.P
Other functions operate on an input character sequence
to create an output character sequence.
List of functions:
.IP \[bu]
.BR zustr2stp (3)
.PD
-.PP
+.P
The following function returns
a pointer to the terminating null byte in the destination string,
except when truncation occurs;
it returns a pointer to the end of the destination buffer.
.IP \[bu] 3
.BR stpecpy (3)
-.PP
+.P
The following function returns
a pointer to one after the last character
in the destination character sequence;
a pointer to the end of the destination buffer.
.IP \[bu] 3
.BR stpncpy (3)
-.PP
+.P
The following functions return
a pointer to one after the last character
in the destination character sequence.
.IP \[bu]
.BR ustpcpy (3)
.PD
-.PP
+.P
The following functions return
the length of the total string that they tried to create
(as if truncation didn't occur).
.IP \[bu] 3
.BR strlcpy (3bsd),
.BR strlcat (3bsd)
-.PP
+.P
The following functions return the
.I dst
pointer,
.\" ----- EXAMPLES :: Implementations :: ------------------------------/
.SS Implementations
Here are reference implementations for functions not provided by libc.
-.PP
+.P
.in +4n
.EX
/* This code is in the public domain. */
The
.BR make (1)
utility is driven by rules based on file suffix.
-.PP
+.P
Following is a list of suffixes which are likely to be found on a
Linux system.
-.PP
+.P
.TS
l | l
_ | _
Symbolic links are files that act as pointers to other files.
To understand their behavior, you must first understand how hard links
work.
-.PP
+.P
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
which would confuse many programs)
and may not refer to files on different filesystems
(because inode numbers are not unique across filesystems).
-.PP
+.P
A symbolic link is a special type of file whose contents are a string
that is the pathname of another file, the file to which the link refers.
(The contents of a symbolic link can be read using
and not to an underlying object.
For this reason, symbolic links may refer to directories and may cross
filesystem boundaries.
-.PP
+.P
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
.IR "dangling link" .
-.PP
+.P
Because a symbolic link and its referenced object coexist in the filesystem
name space, confusion can arise in distinguishing between the link itself
and the referenced object.
As such, these magic links allow users to
access files which cannot be referenced with normal paths (such as unlinked
files still referenced by a running program ).
-.PP
+.P
Because they can bypass ordinary
.BR mount_namespaces (7)-based
restrictions,
.I fs.protected_symlinks
sysctl is set (see
.BR proc (5)).
-.PP
+.P
The last access and last modification timestamps
of a symbolic link can be changed using
.BR utimensat (2)
or
.BR lutimes (3).
-.PP
+.P
.\" Linux does not currently implement an lchmod(2).
On Linux, the permissions of an ordinary symbolic link are not used in any
operations; the permissions are always 0777 (read, write, and execute for all
user categories), and can't be changed.
-.PP
+.P
However, magic links do not follow this rule.
They can have a non-0777 mode,
though this mode is not currently used in any permission checks.
-.\" .PP
+.\" .P
.\" The
.\" 4.4BSD
.\" system differs from historical
.BR readlinkat (2),
in order to operate on the symbolic link itself
(rather than the file to which it refers).
-.PP
+.P
By default
(i.e., if the
.B AT_SYMLINK_FOLLOW
(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.)
-.PP
+.P
There are three separate areas that need to be discussed.
They are as follows:
.IP \[bu] 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).
-.PP
+.P
Before describing the treatment of symbolic links by system calls and commands,
we require some terminology.
Given a pathname of the form
.SS Treatment of symbolic links in system calls
The first area is symbolic links used as filename arguments for
system calls.
-.PP
+.P
The treatment of symbolic links within a pathname passed to
a system call is as follows:
.IP (1) 5
.I "open(""slink"" ...\&)"
would return a file descriptor referring to the file
.IR afile .
-.PP
+.P
Various system calls do not follow links in
the basename component of a pathname,
and operate on the symbolic link itself.
.BR rmdir (2),
and
.BR unlink (2).
-.PP
+.P
Certain other system calls optionally follow symbolic links
in the basename component of a pathname.
They are:
.BR rmdir (2)
is applied to a symbolic link, it fails with the error
.BR ENOTDIR .
-.PP
+.P
.BR link (2)
warrants special discussion.
POSIX.1-2001 specifies that
.SS Commands not traversing a file tree
The second area is symbolic links, specified as command-line
filename arguments, to commands which are not traversing a file tree.
-.PP
+.P
Except as noted below, commands follow symbolic links named as
command-line arguments.
For example, if there were a symbolic link
.I "cat slink"
would display the contents of the file
.IR afile .
-.PP
+.P
It is important to realize that this rule includes commands which may
optionally traverse file trees; for example, the command
.I "chown file"
.IR "chown\ \-R file" ,
which performs a tree traversal, is not.
(The latter is described in the third area, below.)
-.PP
+.P
If it is explicitly intended that the command operate on the symbolic
link instead of following the symbolic link\[em]for example, it is desired that
.I "chown slink"
would change the ownership of
.I slink
itself.
-.PP
+.P
There are some exceptions to this rule:
.IP \[bu] 3
The
.BR rm (1),
and
.BR tar (1).
-.PP
+.P
It is important to realize that the following rules apply equally to
symbolic links encountered during the file tree traversal and symbolic
links listed as command-line arguments.
-.PP
+.P
The \fIfirst rule\fP 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.
-.PP
+.P
The command
.I "rm\ \-r slink directory"
will remove
.BR rm (1)
affect the file referred to by
.IR slink .
-.PP
+.P
The \fIsecond rule\fP applies to symbolic links that refer to directories.
Symbolic 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 that refer to directories are followed).
-.PP
+.P
Certain conventions are (should be) followed as consistently as
possible by commands that perform file tree walks:
.IP \[bu] 3
(for "physical") flag.
This flag is intended to make the entire name space look like the
physical name space.
-.PP
+.P
For commands that do not by default do file tree traversals, the
.IR \-H ,
.IR \-L ,
the last one specified determines the command's behavior.
This is intended to permit you to alias commands to behave one way
or the other, and then override that behavior on the command line.
-.PP
+.P
The
.BR ls (1)
and
.IR <signal.h> .
Alternatively,
.IR <sys/wait.h> .
-.PP
+.P
.EX
typedef struct {
int si_signo; /* Signal number */
union sigval si_value; /* Signal value */
} siginfo_t;
.EE
-.PP
+.P
Information associated with a signal.
For further details on this structure
(including additional, Linux-specific fields), see
.BR sigaction (2).
-.PP
+.P
.IR "Conforming to" :
POSIX.1-2001 and later.
-.PP
+.P
.IR "See also" :
.BR pidfd_send_signal (2),
.BR rt_sigqueueinfo (2),
.IR <spawn.h> ,
or
.IR <sys/select.h> .
-.PP
+.P
This is a type that represents a set of signals.
According to POSIX, this shall be an integer or structure type.
-.PP
+.P
.IR "Conforming to" :
POSIX.1-2001 and later.
-.PP
+.P
.IR "See also" :
.BR epoll_pwait (2),
.BR ppoll (2),
.SH NOTES
The structures described in this manual page shall contain,
at least, the members shown in their definition, in no particular order.
-.PP
+.P
Most of the integer types described in this page don't have
a corresponding length modifier for the
.BR printf (3)
C99 and later and POSIX.1-2001 and later.
Some types may be specified in earlier versions of one of these standards,
but in the interests of simplicity we omit details from earlier standards.
-.PP
+.P
In "Include", we first note the "primary" header(s) that
define the type according to either the C or POSIX.1 standards.
Under "Alternatively", we note additional headers that
.IR intmax_t ,
and the appropriate range checks,
are used as explained in the notes section above.
-.PP
+.P
.EX
#include <stdint.h>
#include <stdio.h>
POSIX message queues provide an alternative API for achieving the same result;
see
.BR mq_overview (7).
-.PP
+.P
The System V message queue API consists of the following system calls:
.TP
.BR msgget (2)
POSIX semaphores provide an alternative API for achieving the same result;
see
.BR sem_overview (7).
-.PP
+.P
The System V semaphore API consists of the following system calls:
.TP
.BR semget (2)
(a "segment").
POSIX shared memory is an alternative API for achieving the same result; see
.BR shm_overview (7).
-.PP
+.P
The System V shared memory API consists of the following system calls:
.TP
.BR shmget (2)
.B #include <sys/socket.h>
.B #include <netinet/in.h>
.B #include <netinet/tcp.h>
-.PP
+.P
.IB tcp_socket " = socket(AF_INET, SOCK_STREAM, 0);"
.fi
.SH DESCRIPTION
It generates and checks a per-packet checksum to catch
transmission errors.
TCP does not preserve record boundaries.
-.PP
+.P
A newly created TCP socket has no remote or local address and is not
fully specified.
To create an outgoing TCP connection use
.BR connect (2)
successfully called on it is fully specified and may transmit data.
Data cannot be transmitted on listening or not yet connected sockets.
-.PP
+.P
Linux supports RFC\ 1323 TCP high performance
extensions.
These include Protection Against Wrapped
socket options with the
.BR setsockopt (2)
call.
-.PP
+.P
The maximum sizes for socket buffers declared via the
.B SO_SNDBUF
and
See
.BR socket (7)
for more information.
-.PP
+.P
TCP supports urgent data.
Urgent data is used to signal the
receiver that some important message is part of the data
.BR recv (2)
or
.BR recvmsg (2).
-.PP
+.P
When out-of-band data is present,
.BR select (2)
indicates the file descriptor as having an exceptional condition and
indicates a
.B POLLPRI
event.
-.PP
+.P
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
socket options are valid on TCP sockets.
For more information see
.BR ip (7).
-.PP
+.P
Following is a list of TCP-specific socket options.
For details of some other socket options that are also applicable
for TCP sockets, see
.B SO_OOBINLINE
is not set).
This differs from BSD-based stacks.
-.PP
+.P
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
.IR /proc/sys/net/ipv4/tcp_stdurg .
-.PP
+.P
It is possible to peek at out-of-band data using the
.BR recv (2)
.B MSG_PEEK
flag.
-.PP
+.P
Since Linux 2.4, Linux supports the use of
.B MSG_TRUNC
in the
calls return information in
.IR value .
The correct syntax is:
-.PP
+.P
.RS
.nf
.BI int " value";
.IB error " = ioctl(" tcp_socket ", " ioctl_type ", &" value ");"
.fi
.RE
-.PP
+.P
.I ioctl_type
is one of the following:
.TP
If it doesn't succeed after some time, either
.B ETIMEDOUT
or the last received error on this connection is reported.
-.PP
+.P
Some applications require a quicker error notification.
This can be enabled with the
.B IPPROTO_IP
.TP
.B ETIMEDOUT
The other end didn't acknowledge retransmitted data after some time.
-.PP
+.P
Any errors defined for
.BR ip (7)
or the generic socket layer may also be returned for TCP.
and per-connection keepalive socket options were introduced in Linux 2.3.
.SH BUGS
Not all errors are documented.
-.PP
+.P
IPv6 is not described.
.\" Only a single Linux kernel version is described
.\" Info for 2.2 was lost. Should be added again,
.BR socket (2),
.BR ip (7),
.BR socket (7)
-.PP
+.P
The kernel source file
.IR Documentation/networking/ip\-sysctl.txt .
-.PP
+.P
RFC\ 793 for the TCP specification.
.br
RFC\ 1122 for the TCP requirements and a description of the Nagle algorithm.
structure used to store terminal settings, and a range of
.BR ioctl (2)
operations to get and set terminal attributes.
-.PP
+.P
The
.B termio
interface is now obsolete: POSIX.1-1990 standardized a modified
.BR ioctl (2)
was unstandardized, and its variadic third argument
does not allow argument type checking.)
-.PP
+.P
If you're looking for a page called "termio", then you can probably
find most of the information that you seek in either
.BR termios (3)
It is created only when a thread requests it.
The thread keyring has the name (description)
.IR _tid .
-.PP
+.P
A special serial number value,
.BR KEY_SPEC_THREAD_KEYRING ,
is defined that can be used in lieu of the actual serial number of
the calling thread's thread keyring.
-.PP
+.P
From the
.BR keyctl (1)
utility, '\fB@t\fP' can be used instead of a numeric key ID in
much the same way, but as
.BR keyctl (1)
is a program run after forking, this is of no utility.
-.PP
+.P
Thread keyrings are not inherited across
.BR clone (2)
and
and are cleared by
.BR execve (2).
A thread keyring is destroyed when the thread that refers to it terminates.
-.PP
+.P
Initially, a thread does not have a thread keyring.
If a thread doesn't have a thread keyring when it is accessed,
then it will be created if it is to be modified;
(see the description of the Epoch and calendar time below),
or from some point (e.g., the start) in the life of a process
.RI ( "elapsed time" ).
-.PP
+.P
.I "Process time"
is defined as the amount of CPU time used by a process.
This is sometimes divided into
.IR jiffies .
The size of a jiffy is determined by the value of the kernel constant
.IR HZ .
-.PP
+.P
The value of
.I HZ
varies across kernel versions and hardware platforms.
Since Linux 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).
-.PP
+.P
The
.BR times (2)
system call is a special case.
.SS 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.
-.PP
+.P
Since Linux 2.6.21, Linux supports high-resolution timers (HRTs),
optionally configurable via
.BR CONFIG_HIGH_RES_TIMERS .
.BR clock_getres (2)
or looking at the "resolution" entries in
.IR /proc/timer_list .
-.PP
+.P
HRTs are not supported on all hardware architectures.
(Support is provided on x86, ARM, and PowerPC, among others.)
.SS The Epoch
UNIX systems represent time in seconds since the
.IR Epoch ,
1970-01-01 00:00:00 +0000 (UTC).
-.PP
+.P
A program can determine the
.I "calendar time"
via the
.BR clock_nanosleep (2),
and
.BR sleep (3).
-.PP
+.P
Various system calls allow a process to set a timer that expires
at some point in the future, and optionally at repeated intervals;
see
a nonsettable clock that is identical to
.BR CLOCK_MONOTONIC ,
except that it also includes any time that the system is suspended.
-.PP
+.P
Thus, the processes in a time namespace share per-namespace values
for these clocks.
This affects various APIs that measure against these clocks, including:
.BR timerfd_settime (2),
and
.IR /proc/uptime .
-.PP
+.P
Currently, the only way to create a time namespace is by calling
.BR unshare (2)
with the
Within this file,
the offsets are expressed as lines consisting of
three space-delimited fields:
-.PP
+.P
.in +4n
.EX
<clock-id> <offset-secs> <offset-nanosecs>
.EE
.in
-.PP
+.P
The
.I clock-id
is a string that identifies the clock whose offsets are being shown.
value can be negative, subject to restrictions noted below;
.I offset-nanosecs
is an unsigned value.
-.PP
+.P
In the initial time namespace, the contents of the
.I timens_offsets
file are as follows:
-.PP
+.P
.in +4n
.EX
$ \fBcat /proc/self/timens_offsets\fP
boottime 0 0
.EE
.in
-.PP
+.P
In a new time namespace that has had no member processes,
the clock offsets can be modified by writing newline-terminated
records of the same form to the
file, a process must have the
.B CAP_SYS_TIME
capability in the user namespace that owns the time namespace.
-.PP
+.P
Writes to the
.I timens_offsets
file can fail with the following errors:
.B KTIME_SEC_MAX
(this limits the clock value to a maximum of approximately 146 years).
.RE
-.PP
+.P
In a new time namespace created by
.BR unshare (2),
the contents of the
Use of time namespaces requires a kernel that is configured with the
.B CONFIG_TIME_NS
option.
-.PP
+.P
Note that time namespaces do not virtualize the
.B CLOCK_REALTIME
clock.
Virtualization of this clock was avoided for reasons of complexity
and overhead within the kernel.
-.PP
+.P
For compatibility with the initial implementation, when writing a
.I clock-id
to the
and 7 instead of
.IR boottime .
For readability, the use of the symbolic names over the numbers is preferred.
-.PP
+.P
The motivation for adding time namespaces was to allow
the monotonic and boot-time clocks to maintain consistent values
during container migration and checkpoint/restore.
The following shell session demonstrates the operation of time namespaces.
We begin by displaying the inode number of the time namespace
of a shell in the initial time namespace:
-.PP
+.P
.in +4n
.EX
$ \fBreadlink /proc/$$/ns/time\fP
time:[4026531834]
.EE
.in
-.PP
+.P
Continuing in the initial time namespace, we display the system uptime using
.BR uptime (1)
and use the
example program shown in
.BR clock_getres (2)
to display the values of various clocks:
-.PP
+.P
.in +4n
.EX
$ \fBuptime \-\-pretty\fP
CLOCK_BOOTTIME : 76633.544 (21h 17m 13s)
.EE
.in
-.PP
+.P
We then use
.BR unshare (1)
to create a time namespace and execute a
and the offset for the
.B CLOCK_BOOTTIME
clock forward 7 days:
-.PP
+.P
.in +4n
.EX
$ \fBPS1="ns2# " sudo unshare \-T \-\- bash \-\-norc\fP
ns2# \fBecho "boottime $((7*24*60*60)) 0" > /proc/$$/timens_offsets\fP
.EE
.in
-.PP
+.P
Above, we started the
.BR bash (1)
shell with the
shell before we have a chance to update the
.I timens_offsets
file.
-.PP
+.P
We then use
.BR cat (1)
to display the contents of the
after which further attempts to update the
.I timens_offsets
file produce an error.
-.PP
+.P
.in +4n
.EX
ns2# \fBcat /proc/$$/timens_offsets\fP
bash: echo: write error: Permission denied
.EE
.in
-.PP
+.P
Continuing in the new namespace, we execute
.BR uptime (1)
and the
.I clock_times
example program:
-.PP
+.P
.in +4n
.EX
ns2# \fBuptime \-\-pretty\fP
CLOCK_BOOTTIME : 681488.629 (7 days + 21h 18m 8s)
.EE
.in
-.PP
+.P
From the above output, we can see that the monotonic
and boot-time clocks have different values in the new time namespace.
-.PP
+.P
Examining the
.IR /proc/ pid /ns/time
and
.IR /proc/ pid /ns/time_for_children
symbolic links, we see that the shell is a member of the initial time
namespace, but its children are created in the new namespace.
-.PP
+.P
.in +4n
.EX
ns2# \fBreadlink /proc/$$/ns/time\fP
time:[4026532900]
.EE
.in
-.PP
+.P
Returning to the shell in the initial time namespace,
we see that the monotonic and boot-time clocks
are unaffected by the
.I timens_offsets
changes that were made in the other time namespace:
-.PP
+.P
.in +4n
.EX
$ \fBuptime \-\-pretty\fP
.B #include <sys/socket.h>
.B #include <netinet/in.h>
.B #include <netinet/udp.h>
-.PP
+.P
.IB udp_socket " = socket(AF_INET, SOCK_DGRAM, 0);"
.fi
.SH DESCRIPTION
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.
-.PP
+.P
When a UDP socket is created,
its local and remote addresses are unspecified.
Datagrams can be sent immediately using
.I /proc/sys/net/ipv4/ip_local_port_range
and bind the socket to
.BR INADDR_ANY .
-.PP
+.P
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
flag is set.
.B MSG_WAITALL
is not supported.
-.PP
+.P
IP options may be sent or received using the socket options described in
.BR ip (7).
They are processed by the kernel only when the appropriate
is enabled (but still passed to the user even when it is turned off).
See
.BR ip (7).
-.PP
+.P
When the
.B MSG_DONTROUTE
flag is set on sending, the destination address must refer to a local
interface address and the packet is sent only to that interface.
-.PP
+.P
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
which don't pass any errors unless the socket is connected.
Linux's behavior is mandated by
.BR RFC\ 1122 .
-.PP
+.P
For compatibility with legacy code, in Linux 2.0 and 2.2
it was possible to set the
.B SO_BSDCOMPAT
Support for this socket option was removed in later kernels; see
.BR socket (7)
for further information.
-.PP
+.P
When the
.B IP_RECVERR
option is enabled, all errors are stored in the socket error queue,
.I optval
is a pointer to an
.IR int .
-.PP
+.P
Following is a list of UDP-specific socket options.
For details of some other socket options that are also applicable
for UDP sockets, see
These ioctls can be accessed using
.BR ioctl (2).
The correct syntax is:
-.PP
+.P
.RS
.nf
.BI int " value";
.BR TIOCOUTQ " (" SIOCOUTQ )
Returns the number of data bytes in the local send queue.
Supported only with Linux 2.4 and above.
-.PP
+.P
In addition, all ioctls documented in
.BR ip (7)
and
.BR raw (7),
.BR socket (7),
.BR udplite (7)
-.PP
+.P
The kernel source file
.IR Documentation/networking/ip\-sysctl.txt .
-.PP
+.P
RFC\ 768 for the User Datagram Protocol.
.br
RFC\ 1122 for the host requirements.
.\" FIXME . see #defines under `BUGS',
.\" when glibc supports this, add
.\" #include <netinet/udplite.h>
-.PP
+.P
.B sockfd = socket(AF_INET, SOCK_DGRAM, IPPROTO_UDPLITE);
.fi
.SH DESCRIPTION
This is an implementation of the Lightweight User Datagram Protocol
(UDP-Lite), as described in RFC\ 3828.
-.PP
+.P
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.
-.PP
+.P
The variable-length checksum coverage is set via a
.BR setsockopt (2)
option.
If this option is not set, the only difference from UDP is
in using a different IP protocol identifier (IANA number 136).
-.PP
+.P
The UDP-Lite implementation is a full extension of
.BR udp (7)\[em]that
is, it shares the same API and API behavior, and in addition
See
.BR udp (7)
for more information.
-.PP
+.P
The following two options are specific to UDP-Lite.
.TP
.B UDPLITE_SEND_CSCOV
but may generate a warning message in the system log.
.\" SO_NO_CHECK exists and is supported by UDPv4, but is
.\" commented out in socket(7), hence also commented out here
-.\".PP
+.\".P
.\"Since UDP-Lite mandates checksums, checksumming can not be disabled
.\"via the
.\".B SO_NO_CHECK
.SH BUGS
.\" FIXME . remove this section once glibc supports UDP-Lite
Where glibc support is missing, the following definitions are needed:
-.PP
+.P
.in +4n
.EX
#define IPPROTO_UDPLITE 136
.BR ipv6 (7),
.BR socket (7),
.BR udp (7)
-.PP
+.P
RFC\ 3828 for the Lightweight User Datagram Protocol (UDP-Lite).
-.PP
+.P
.I Documentation/networking/udplite.txt
in the Linux kernel source tree
in other words,
conversion tables can be built such that no information is lost
when a string is converted from any other encoding to UCS and back.
-.PP
+.P
UCS contains the characters required to represent practically all
known languages.
This includes not only the Latin, Greek, Cyrillic,
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.
-.PP
+.P
The UCS standard (ISO/IEC 10646) describes a
31-bit character set architecture
consisting of 128 24-bit
ISO/IEC 10646-2 cover only more exotic characters for special scientific,
dictionary printing, publishing industry, higher-level protocol and
enthusiast needs.
-.PP
+.P
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.
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.
-.PP
+.P
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
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.
-.PP
+.P
Combining characters are essential for instance for encoding the Thai
script or for mathematical typesetting and users of the International
Phonetic Alphabet.
.TP
Level 3
All UCS characters are supported.
-.PP
+.P
The Unicode 3.0 Standard
published by the Unicode Consortium
contains exactly the UCS Basic Multilingual Plane
C library to applications by defining the constant
.B __STDC_ISO_10646__
as specified in the ISO C99 standard.
-.PP
+.P
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.
.I locale
has to be selected via environment variables (e.g.,
"LANG=en_GB.UTF-8").
-.PP
+.P
The
.B nl_langinfo(CODESET)
function returns the name of the selected encoding.
(or
.I Documentation/unicode.txt
before Linux 4.10).
-.PP
+.P
Two other planes are reserved for private usage, plane 15
(Supplementary Private Use Area-A, range 0xf0000 to 0xffffd)
and plane 16 (Supplementary Private Use Area-B, range
Q quetta 10\[ha]30 = 1000000000000000000000000000000
.TE
.RE
-.PP
+.P
The symbol for micro is the Greek letter mu, often written u
in an ASCII context where this Greek letter is not available.
.SS Binary prefixes
common to use k=1000 and K=1024, just like b=bit, B=byte.
Unfortunately, the M is capital already, and cannot be
capitalized to indicate binary-ness.
-.PP
+.P
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
But then disk technology changed, and disk sizes became arbitrary numbers.
After a period of uncertainty all disk manufacturers settled on the
standard, namely k=1000, M=1000\ k, G=1000\ M.
-.PP
+.P
The situation was messy: in the 14k4 modems, k=1000; in the 1.44\ MB
.\" also common: 14.4k modem
diskettes, M=1024000; and so on.
In 1998 the IEC approved the standard
that defines the binary prefixes given above, enabling people
to be precise and unambiguous.
-.PP
+.P
Thus, today, MB = 1000000\ B and MiB = 1048576\ B.
-.PP
+.P
In the free software world programs are slowly
being changed to conform.
When the Linux kernel boots and says
-.PP
+.P
.in +4n
.EX
hda: 120064896 sectors (61473 MB) w/2048KiB Cache
.EE
.in
-.PP
+.P
the MB are megabytes and the KiB are kibibytes.
.SH SEE ALSO
.UR https://www.bipm.org/\:documents/\:20126/\:41483022/\:SI\-Brochure\-9.pdf
.nf
.B #include <sys/socket.h>
.B #include <sys/un.h>
-.PP
+.P
.IB unix_socket " = socket(AF_UNIX, type, 0);"
.IB error " = socketpair(AF_UNIX, type, 0, int *" sv ");"
.fi
or bound to a filesystem pathname (marked as being of type socket).
Linux also supports an abstract namespace which is independent of the
filesystem.
-.PP
+.P
Valid socket types in the UNIX domain are:
.BR SOCK_STREAM ,
for a stream-oriented socket;
for a sequenced-packet socket that is connection-oriented,
preserves message boundaries,
and delivers messages in the order that they were sent.
-.PP
+.P
UNIX domain sockets support passing file descriptors or process credentials
to other processes using ancillary data.
.SS Address format
A UNIX domain socket address is represented in the following structure:
-.PP
+.P
.in +4n
.EX
.\" #define UNIX_PATH_MAX 108
};
.EE
.in
-.PP
+.P
The
.I sun_family
field always contains
On Linux,
.I sun_path
is 108 bytes in size; see also BUGS, below.
-.PP
+.P
Various systems calls (for example,
.BR bind (2),
.BR connect (2),
and
.BR accept (2))
return an argument of this type.
-.PP
+.P
Three types of address are distinguished in the
.I sockaddr_un
structure:
.I addrlen
can be specified as
.IR "sizeof(struct sockaddr_un)" .
-.PP
+.P
There is some variation in how implementations handle UNIX domain
socket addresses that do not follow the above rules.
For example, some (but not all) implementations
.\" is 108 bytes
append a null terminator if none is present in the supplied
.IR sun_path .
-.PP
+.P
When coding portable applications,
keep in mind that some implementations
.\" HP-UX
as short as 92 bytes.
.\" Modern BSDs generally have 104, Tru64 and AIX have 104,
.\" Solaris and Irix have 108
-.PP
+.P
Various system calls
.RB ( accept (2),
.BR recvfrom (2),
pathname sockets honor the permissions of the directory they are in.
Creation of a new socket fails if the process does not have write and
search (execute) permission on the directory in which the socket is created.
-.PP
+.P
On Linux,
connecting to a stream socket object requires write permission on that socket;
sending a datagram to a datagram socket likewise
the socket permissions are ignored.
Portable programs should not rely on
this feature for security.
-.PP
+.P
When creating a new socket, the owner and group of the socket file
are set according to the usual rules.
The socket file has all permissions enabled,
other than those that are turned off by the process
.BR umask (2).
-.PP
+.P
The owner, group, and permissions of a pathname socket can be changed (using
.BR chown (2)
and
and
.BR fchmod (2))
has no effect on the accessibility of the socket.
-.PP
+.P
Abstract sockets automatically disappear when all open references
to the socket are closed.
-.PP
+.P
The abstract socket namespace is a nonportable Linux extension.
.\"
.SS Socket options
.SS Sockets API
The following paragraphs describe domain-specific details and
unsupported features of the sockets API for UNIX domain sockets on Linux.
-.PP
+.P
UNIX domain sockets do not support the transmission of
out-of-band data (the
.B MSG_OOB
.BR send (2)
and
.BR recv (2)).
-.PP
+.P
The
.BR send (2)
.B MSG_MORE
flag is not supported by UNIX domain sockets.
-.PP
+.P
Before Linux 3.4,
.\" commit 9f6f9af7694ede6314bed281eec74d588ba9474f
the use of
argument of
.BR recv (2)
was not supported by UNIX domain sockets.
-.PP
+.P
The
.B SO_SNDBUF
socket option does have an effect for UNIX domain sockets, but the
To receive the security context, the
.B SO_PASSSEC
option must be enabled on the socket (see above).
-.PP
+.P
When sending ancillary data with
.BR sendmsg (2),
only one item of each of the above types may be included in the sent message.
-.PP
+.P
At least one byte of real data should be sent when sending ancillary data.
On Linux, this is required to successfully send ancillary data over
a UNIX domain stream socket.
it is not necessary on Linux to send any accompanying real data.
However, portable applications should also include at least one byte
of real data when sending ancillary data over a datagram socket.
-.PP
+.P
When receiving from a stream socket,
ancillary data forms a kind of barrier for the received data.
For example, suppose that the sender transmits as follows:
-.PP
+.P
.RS
.PD 0
.IP (1) 5
of four bytes, with no ancillary data.
.PD
.RE
-.PP
+.P
Suppose that the receiver now performs
.BR recvmsg (2)
calls each with a buffer size of 20 bytes.
.BR sendmsg (2)
call.
The next call will receive the remaining four bytes of data.
-.PP
+.P
If the space allocated for receiving incoming ancillary data is too small
then the ancillary data is truncated to the number of headers
that will fit in the supplied buffer (or, in the case of an
calls return information in
.IR value .
The correct syntax is:
-.PP
+.P
.RS
.nf
.BI int " value";
.IB error " = ioctl(" unix_socket ", " ioctl_type ", &" value ");"
.fi
.RE
-.PP
+.P
.I ioctl_type
can be:
.TP
and then closing the file descriptor so that it was not accounted against the
.B RLIMIT_NOFILE
resource limit.
-.PP
+.P
Other errors can be generated by the generic socket layer or
by the filesystem while generating a filesystem socket object.
See the appropriate manual pages for more information.
The usual UNIX close-behind semantics apply; the socket can be unlinked
at any time and will be finally removed from the filesystem when the last
reference to it is closed.
-.PP
+.P
To pass file descriptors or credentials over a
.B SOCK_STREAM
socket, you must
or
.BR recvmsg (2)
call.
-.PP
+.P
UNIX domain stream sockets do not support the notion of out-of-band data.
.\"
.SH BUGS
.I won't
have a null terminator in
.IR sun_path .
-.PP
+.P
In addition, some implementations
.\" i.e., traditional BSD
don't require a null terminator when binding a socket (the
and when the socket address is retrieved on these implementations,
there is no null terminator in
.IR sun_path .
-.PP
+.P
Applications that retrieve socket addresses can (portably) code
to handle the possibility that there is no null terminator in
.I sun_path
by respecting the fact that the number of valid bytes in the pathname is:
-.PP
+.P
.in +4n
.EX
strnlen(addr.sun_path, addrlen \- offsetof(sockaddr_un, sun_path))
.\" 2012-04-18
.\"
.\" FIXME . Track http://austingroupbugs.net/view.php?id=561
-.PP
+.P
Alternatively, an application can retrieve
the socket address by allocating a buffer of size
.I "sizeof(struct sockaddr_un)+1"
and the extra zero byte ensures that there will be
a null terminator for the string returned in
.IR sun_path :
-.PP
+.P
.in +4n
.EX
void *addrp;
printf("sun_path = %s\en", ((struct sockaddr_un *) addrp)\->sun_path);
.EE
.in
-.PP
+.P
This sort of messiness can be avoided if it is guaranteed
that the applications that
.I create
The client prints the sum and exits.
The server waits for the next client to connect.
To stop the server, the client is called with the command-line argument "DOWN".
-.PP
+.P
The following output was recorded while running the server in the background
and repeatedly executing the client.
Execution of the server program ends when it receives the "DOWN" command.
exit(EXIT_SUCCESS);
}
.EE
-.PP
+.P
For examples of the use of
.BR SCM_RIGHTS ,
see
.RB [\~\[dq] # \[dq]\~\c
.IR fragment \~]
.YS
-.PP
+.P
.SY "\fIabsoluteURI\fP \fR=\fP"
.I scheme\~\c
.RB \[dq] : \[dq]
|
.IR opaque_part \~)
.YS
-.PP
+.P
.SY "\fIrelativeURI\fP \fR=\fP"
.RI (\~ net_path
|
.RB [\~\[dq] ? \[dq]\~\c
.IR query \~]
.YS
-.PP
+.P
.SY "\fIscheme\fP \fR=\fP"
.RB \[dq] http \[dq]
|
.RB \[dq] wais \[dq]
| \&...
.YS
-.PP
+.P
.SY "\fIhierarchical_part\fP \fR=\fP"
.RI (\~ net_path
|
.RB [\~\[dq] ? \[dq]\~\c
.IR query \~]
.YS
-.PP
+.P
.SY "\fInet_path\fP \fR=\fP"
.RB \[dq] // \[dq]\~\c
.I authority
.RI [\~ absolute_path \~]
.YS
-.PP
+.P
.SY "\fIabsolute_path\fP \fR=\fP"
.RB \[dq] / \[dq]\~\c
.I path_segments
.YS
-.PP
+.P
.SY "\fIrelative_path\fP \fR=\fP"
.I relative_segment
.RI [\~ absolute_path \~]
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.
-.PP
+.P
URIs are the standard way to name hypertext link destinations
for tools such as web browsers.
The string "http://www.kernel.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).
-.PP
+.P
URIs can be absolute or relative.
An absolute identifier refers to a resource independent of
context, while a relative
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|".
-.PP
+.P
A fragment identifier,
if included,
refers to a particular named portion (fragment) of a resource;
permit the authority to be the following format, called here an
.I ip_server
(square brackets show what's optional):
-.PP
+.P
.IR "ip_server = " [ user " [ : " password " ] @ ] " host " [ : " port ]
-.PP
+.P
This format allows you to optionally insert a username,
a user plus password, and/or a port number.
The
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.
-.PP
+.P
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.
-.PP
+.P
.B "http \- Web (HTTP) server"
-.PP
+.P
.RI http:// ip_server / path
.br
.RI http:// ip_server / path ? query
-.PP
+.P
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
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>.
-.PP
+.P
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
.UR http://www.w3.org\:/CGI
.UE
for more information.
-.PP
+.P
.B "ftp \- File Transfer Protocol (FTP)"
-.PP
+.P
.RI ftp:// ip_server / path
-.PP
+.P
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
Internet email address.
An example is
<ftp://ftp.is.co.za/rfc/rfc1808.txt>.
-.PP
+.P
.B "gopher \- Gopher server"
-.PP
+.P
.RI gopher:// ip_server / "gophertype selector"
.br
.RI gopher:// ip_server / "gophertype selector" %09 search
.br
.RI gopher:// ip_server / "gophertype selector" %09 search %09 gopher+_string
.br
-.PP
+.P
The default gopher port is 70.
.I gophertype
is a single-character field to denote the
The entire path may also be empty, in
which case the delimiting "/" is also optional and the gophertype
defaults to "1".
-.PP
+.P
.I 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 character LF), and 0D (US-ASCII character CR).
-.PP
+.P
.B "mailto \- Email address"
-.PP
+.P
.RI mailto: email-address
-.PP
+.P
This is an email address, usually of the form
.IR name @ hostname .
See
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>.
-.PP
+.P
.B "news \- Newsgroup or News message"
-.PP
+.P
.RI news: newsgroup-name
.br
.RI news: message-id
-.PP
+.P
A
.I newsgroup-name
is a period-delimited hierarchical name, such as
If <newsgroup-name> is "*" (as in <news:*>), it is used to refer
to "all available news groups".
An example is <news:comp.lang.ada>.
-.PP
+.P
A
.I message-id
corresponds to the Message-ID of
.IR unique @ full_domain_name .
A message identifier may be distinguished from a news group name by the
presence of the "@" character.
-.PP
+.P
.B "telnet \- Telnet login"
-.PP
+.P
.RI telnet:// ip_server /
-.PP
+.P
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 <telnet://melvyl.ucop.edu/>.
-.PP
+.P
.B "file \- Normal file"
-.PP
+.P
.RI file:// ip_server / path_segments
.br
.RI file: path_segments
-.PP
+.P
This represents a file or directory accessible locally.
As a special case,
.I ip_server
.BR glob (7)
and
.BR glob (3)).
-.PP
+.P
The second format (e.g., <file:/etc/passwd>)
is a correct format for referring to
a local file.
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>.
-.PP
+.P
.B "man \- Man page documentation"
-.PP
+.P
.RI man: command-name
.br
.RI man: command-name ( section )
-.PP
+.P
This refers to local online manual (man) reference pages.
The command name can optionally be followed by a
parenthesis and section number; see
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)>.
-.PP
+.P
.B "info \- Info page documentation"
-.PP
+.P
.RI info: virtual-filename
.br
.RI info: virtual-filename # nodename
.RI info:( virtual-filename )
.br
.RI info:( virtual-filename ) nodename
-.PP
+.P
This scheme refers to online info reference pages (generated from
texinfo files),
a documentation format used by programs such as the GNU tools.
nodename 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>.
-.PP
+.P
.B "whatis \- Documentation search"
-.PP
+.P
.RI whatis: string
-.PP
+.P
This scheme searches the database of short (one-line) descriptions of
commands and returns a list of descriptions containing that string.
Only complete word matches are returned.
.BR whatis (1).
This URI scheme is unique to UNIX-like systems (such as Linux)
and is not currently registered by the IETF.
-.PP
+.P
.B "ghelp \- GNOME help documentation"
-.PP
+.P
.RI ghelp: name-of-application
-.PP
+.P
This loads GNOME help for the given application.
Note that not much documentation currently exists in this format.
-.PP
+.P
.B "ldap \- Lightweight Directory Access Protocol"
-.PP
+.P
.RI ldap:// hostport
.br
.RI ldap:// hostport /
.RI ldap:// hostport / dn ? attributes ? scope ? filter
.br
.RI ldap:// hostport / dn ? attributes ? scope ? filter ? extensions
-.PP
+.P
This scheme supports queries to the
Lightweight Directory Access Protocol (LDAP), a protocol for querying
a set of servers for hierarchically organized information
requiring it.
An extension prefixed with a \[aq]!\[aq] is critical
(must be supported to be valid), otherwise it is noncritical (optional).
-.PP
+.P
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.:
-.PP
+.P
.nf
ldap://ldap.itd.umich.edu/o=University%20of%20Michigan,c=US
.fi
-.PP
+.P
To just get its postal address attribute, request:
-.PP
+.P
.nf
ldap://ldap.itd.umich.edu/o=University%20of%20Michigan,c=US?postalAddress
.fi
-.PP
+.P
To ask a host.com at port 6666 for information about the person
with common name (cn) "Babs Jensen" at University of Michigan, request:
-.PP
+.P
.nf
ldap://host.com:6666/o=University%20of%20Michigan,c=US??sub?(cn=Babs%20Jensen)
.fi
-.PP
+.P
.B "wais \- Wide Area Information Servers"
-.PP
+.P
.RI wais:// hostport / database
.br
.RI wais:// hostport / database ? search
.br
.RI wais:// hostport / database / wtype / wpath
-.PP
+.P
This scheme designates a WAIS database, search, or document
(see
.UR 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).
-.PP
+.P
The first form designates a WAIS database for searching.
The second form designates a particular search of the WAIS database
.IR database .
is the WAIS designation of the type of the object and
.I wpath
is the WAIS document-id.
-.PP
+.P
.B "other schemes"
-.PP
+.P
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,
.SS Character encoding
URIs use a limited number of characters so that they can be
typed in and used in a variety of situations.
-.PP
+.P
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):
; / ? : @ & = + $ ,
.EE
.in
-.PP
+.P
Unreserved characters may be included in a URI.
Unreserved characters
include uppercase and lowercase Latin letters,
\- _ . ! \[ti] * ' ( )
.EE
.in
-.PP
+.P
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
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.
-.PP
+.P
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 "\[ti]" in an HTTP URL
path, but the two are equivalent for an HTTP URL.
-.PP
+.P
For URIs which must handle characters outside the US ASCII character set,
the HTML 4.01 specification (section B.2) and
IETF RFC\~3986 (last paragraph of section 2.5)
is preferred practice in Great Britain and in various European languages.
Older documents suggested inserting the prefix "URL:"
just before the URI, but this form has never caught on.
-.PP
+.P
The URI syntax was designed to be unambiguous.
However, as URIs have become commonplace, traditional media
(television, radio, newspapers, billboards, etc.) have increasingly
schemes described here, including the man: and info: schemes.
Handling them by invoking some other program is
fine and in fact encouraged.
-.PP
+.P
Technically the fragment isn't part of the URI.
-.PP
+.P
For information on how to embed URIs (including URLs) in a data format,
see documentation on that format.
HTML uses the format <A HREF="\fIuri\fP">
Texinfo files use the format @uref{\fIuri\fP}.
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).
-.PP
+.P
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
later point in time; such a guarantee can be
obtained only from the person(s) controlling that namespace and the
resource in question.
-.PP
+.P
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 associated with the resource, will in fact
operation.
An example has been the use of a gopher URL to cause an
unintended or impersonating message to be sent via a SMTP server.
-.PP
+.P
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.
-.PP
+.P
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.
characters to be used to simulate an extra operation or parameter in
that protocol, which might lead to an unexpected and possibly harmful
remote operation to be performed.
-.PP
+.P
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
Alternatively, a future version of the filesystem specification may
specify file locations sufficiently so that the file: scheme will
be able to locate documentation.
-.PP
+.P
Many programs and file formats don't include a way to incorporate
or implement links using URIs.
-.PP
+.P
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,
.BR man2html (1),
.BR mailaddr (7),
.BR utf\-8 (7)
-.PP
+.P
.UR http://www.ietf.org\:/rfc\:/rfc2255.txt
IETF RFC\ 2255
.UE
where
.I <UID>
is the user ID of the corresponding user.
-.PP
+.P
The user keyring is associated with the record that the kernel maintains
for the UID.
It comes into existence upon the first attempt to access either the
running with that real UID or files opened by those processes remain open.
(The keyring can also be pinned indefinitely by linking it
into another keyring.)
-.PP
+.P
Typically, the user keyring is created by
.BR pam_keyinit (8)
when a user logs in.
-.PP
+.P
The user keyring is not searched by default by
.BR request_key (2).
When
.BR pam_keyinit (8)
creates a session keyring, it adds to it a link to the user
keyring so that the user keyring will be searched when the session keyring is.
-.PP
+.P
A special serial number value,
.BR KEY_SPEC_USER_KEYRING ,
is defined that can be used in lieu of the actual serial number of
the calling process's user keyring.
-.PP
+.P
From the
.BR keyctl (1)
utility, '\fB@u\fP' can be used instead of a numeric key ID in
much the same way.
-.PP
+.P
User keyrings are independent of
.BR clone (2),
.BR fork (2),
.BR _exit (2)
excepting that the keyring is destroyed when the UID record is destroyed when
the last process pinning it exits.
-.PP
+.P
If it is necessary for a key associated with a user to exist beyond the UID
record being garbage collected\[em]for example, for use by a
.BR cron (8)
script\[em]then the
.BR persistent\-keyring (7)
should be used instead.
-.PP
+.P
If a user keyring does not exist when it is accessed, it will be created.
.SH SEE ALSO
.ad l
where
.I <UID>
is the user ID of the corresponding user.
-.PP
+.P
The user session keyring is associated with the record that
the kernel maintains for the UID.
It comes into existence upon the first attempt to access either the
running with that real UID or files opened by those processes remain open.
(The keyring can also be pinned indefinitely by linking it
into another keyring.)
-.PP
+.P
The user session keyring is created on demand when a thread requests it
or when a thread asks for its
.BR session\-keyring (7)
In the latter case, a user session keyring will be created and,
if the session keyring wasn't to be created,
the user session keyring will be set as the process's actual session keyring.
-.PP
+.P
The user session keyring is searched by
.BR request_key (2)
if the actual session keyring does not exist and is ignored otherwise.
-.PP
+.P
A special serial number value,
.BR KEY_SPEC_USER_SESSION_KEYRING ,
is defined
that can be used in lieu of the actual serial number of
the calling process's user session keyring.
-.PP
+.P
From the
.BR keyctl (1)
utility, '\fB@us\fP' can be used instead of a numeric key ID in
much the same way.
-.PP
+.P
User session keyrings are independent of
.BR clone (2),
.BR fork (2),
.BR _exit (2)
excepting that the keyring is destroyed when the UID record is destroyed
when the last process pinning it exits.
-.PP
+.P
If a user session keyring does not exist when it is accessed,
it will be created.
-.PP
+.P
Rather than relying on the user session keyring,
it is strongly recommended\[em]especially if the process
is running as root\[em]that a
.SH DESCRIPTION
For an overview of namespaces, see
.BR namespaces (7).
-.PP
+.P
User namespaces isolate security-related identifiers and attributes,
in particular,
user IDs and group IDs (see
with the
.B CLONE_NEWUSER
flag.
-.PP
+.P
The kernel imposes (since Linux 3.11) a limit of 32 nested levels of
.\" commit 8742f229b635bf1c1c84a3dfe5e47c814c20b5c8
user namespaces.
.BR clone (2)
that would cause this limit to be exceeded fail with the error
.BR EUSERS .
-.PP
+.P
Each process is a member of exactly one user namespace.
A process created via
.BR fork (2)
.B CAP_SYS_ADMIN
in that namespace;
upon doing so, it gains a full set of capabilities in that namespace.
-.PP
+.P
A call to
.BR clone (2)
or
or the caller (for
.BR unshare (2))
a member of the new user namespace created by the call.
-.PP
+.P
The
.B NS_GET_PARENT
.BR ioctl (2)
operation can be used to discover the parental relationship
between user namespaces; see
.BR ioctl_ns (2).
-.PP
+.P
A task that changes one of its effective IDs
will have its dumpability reset to the value in
.IR /proc/sys/fs/suid_dumpable .
user namespace,
even if the new namespace is created or joined by the root user
(i.e., a process with user ID 0 in the root namespace).
-.PP
+.P
Note that a call to
.BR execve (2)
will cause a process's capabilities to be recalculated in the usual way (see
or the executable file has a nonempty inheritable capabilities mask,
the process will lose all capabilities.
See the discussion of user and group ID mappings, below.
-.PP
+.P
A call to
.BR clone (2)
or
.BR setns (2)
calls to move to another user namespace and then return to
its original user namespace.
-.PP
+.P
The rules for determining whether or not a process has a capability
in a particular user namespace are as follows:
.IP \[bu] 3
to perform privileged operations on resources that are governed by (nonuser)
namespaces owned by (associated with) the user namespace
(see the next subsection).
-.PP
+.P
On the other hand, there are many privileged operations that affect
resources that are not associated with any namespace type,
for example, changing the system (i.e., calendar) time (governed by
Only a process with privileges in the
.I initial
user namespace can perform such operations.
-.PP
+.P
Holding
.B CAP_SYS_ADMIN
within the user namespace that owns a process's mount namespace
allows that process to create bind mounts
and mount the following types of filesystems:
.\" fs_flags = FS_USERNS_MOUNT in kernel sources
-.PP
+.P
.RS 4
.PD 0
.IP \[bu] 3
(since Linux 5.11)
.PD
.RE
-.PP
+.P
Holding
.B CAP_SYS_ADMIN
within the user namespace that owns a process's cgroup namespace
(i.e., cgroup filesystems mounted with the
.I """none,name="""
option).
-.PP
+.P
Holding
.B CAP_SYS_ADMIN
within the user namespace that owns a process's PID namespace
that process to mount
.I /proc
filesystems.
-.PP
+.P
Note, however, that mounting block-based filesystems can be done
only by a process that holds
.B CAP_SYS_ADMIN
and the other types of namespaces can be created with just the
.B CAP_SYS_ADMIN
capability in the caller's user namespace.
-.PP
+.P
When a nonuser namespace is created,
it is owned by the user namespace in which the creating process
was a member at the time of the creation of the namespace.
Privileged operations on resources governed by the nonuser namespace
require that the process has the necessary capabilities
in the user namespace that owns the nonuser namespace.
-.PP
+.P
If
.B CLONE_NEWUSER
is specified along with other
privileges over the remaining namespaces created by the call.
Thus, it is possible for an unprivileged caller to specify this combination
of flags.
-.PP
+.P
When a new namespace (other than a user namespace) is created via
.BR clone (2)
or
required capability
.RB ( CAP_SYS_ADMIN )
in that user namespace.
-.PP
+.P
The
.B NS_GET_USERNS
.BR ioctl (2)
.IR pid .
These files can be read to view the mappings in a user namespace and
written to (once) to define the mappings.
-.PP
+.P
The description in the following paragraphs explains the details for
.IR uid_map ;
.I gid_map
is exactly the same,
but each instance of "user ID" is replaced by "group ID".
-.PP
+.P
The
.I uid_map
file exposes the mapping of user IDs from the user namespace
.I uid_map
file, depending on the user ID mappings for the user namespaces
of the reading processes.
-.PP
+.P
Each line in the
.I uid_map
file specifies a 1-to-1 mapping of a range of contiguous
.IP (3)
The length of the range of user IDs that is mapped between the two
user namespaces.
-.PP
+.P
System calls that return user IDs (group IDs)\[em]for example,
.BR getuid (2),
.BR getgid (2),
and the credential fields in the structure returned by
.BR stat (2)\[em]return
the user ID (group ID) mapped into the caller's user namespace.
-.PP
+.P
When a process accesses a file, its user and group IDs
are mapped into the initial user namespace for the purpose of permission
checking and assigning IDs when creating a file.
.BR stat (2),
the IDs are mapped in the opposite direction,
to produce values relative to the process user and group ID mappings.
-.PP
+.P
The initial user namespace has no parent namespace,
but, for consistency, the kernel provides dummy user and group
ID mapping files for this namespace.
file
.RI ( gid_map
is the same) from a shell in the initial namespace shows:
-.PP
+.P
.in +4n
.EX
$ \fBcat /proc/$$/uid_map\fP
0 0 4294967295
.EE
.in
-.PP
+.P
This mapping tells us
that the range starting at user ID 0 in this namespace
maps to a range starting at 0 in the (nonexistent) parent namespace,
Similar rules apply for
.I gid_map
files.
-.PP
+.P
The lines written to
.I uid_map
.RI ( gid_map )
fix this limitation, allowing any valid set of nonoverlapping maps.
.IP \[bu]
At least one line must be written to the file.
-.PP
+.P
Writes that violate the above rules fail with the error
.BR EINVAL .
-.PP
+.P
In order for a process to write to the
.IR /proc/ pid /uid_map
.RI ( /proc/ pid /gid_map )
.IR gid_map .
.RE
.RE
-.PP
+.P
Writes that violate the above rules fail with the error
.BR EPERM .
.\"
.BR setquota (8)
and
.BR quotactl (2).)
-.PP
+.P
Project ID mappings are defined by writing to the
.IR /proc/ pid /projid_map
file (present since
.\" commit f76d207a66c3a53defea67e7d36c3eb1b7d6d61d
Linux 3.7).
-.PP
+.P
The validity rules for writing to the
.IR /proc/ pid /projid_map
file are as for writing to the
.BR write (2)
to fail with the error
.BR EINVAL .
-.PP
+.P
The permission rules for writing to the
.IR /proc/ pid /projid_map
file are as follows:
.IP \[bu]
The mapped project IDs must in turn have a mapping
in the parent user namespace.
-.PP
+.P
Violation of these rules causes
.BR write (2)
to fail with the error
.I gid_map
files have been written, only the mapped values may be used in
system calls that change user and group IDs.
-.PP
+.P
For user IDs, the relevant system calls include
.BR setuid (2),
.BR setfsuid (2),
.BR setresgid (2),
and
.BR setgroups (2).
-.PP
+.P
Writing
.RI \[dq] deny \[dq]
to the
are also not permitted if
.IR /proc/ pid /gid_map
has not yet been set.
-.PP
+.P
A privileged process (one with the
.B CAP_SYS_ADMIN
capability in the namespace) may write either of the strings
.RI \[dq] deny \[dq]
prevents any process in the user namespace from employing
.BR setgroups (2).
-.PP
+.P
The essence of the restrictions described in the preceding
paragraph is that it is permitted to write to
.IR /proc/ pid /setgroups
being disallowed to
.BR setgroups (2)
being allowed.
-.PP
+.P
The default value of this file in the initial user namespace is
.RI \[dq] allow \[dq].
-.PP
+.P
Once
.IR /proc/ pid /gid_map
has been written to
.IR /proc/ pid /setgroups
(the write fails with the error
.BR EPERM ).
-.PP
+.P
A child user namespace inherits the
.IR /proc/ pid /setgroups
setting from its parent.
-.PP
+.P
If the
.I setgroups
file has the value
.BR EPERM .)
This restriction also propagates down to all child user namespaces of
this user namespace.
-.PP
+.P
The
.IR /proc/ pid /setgroups
file was added in Linux 3.19,
.I /proc/sys/kernel/overflowgid
in
.BR proc (5).
-.PP
+.P
The cases where unmapped IDs are mapped in this fashion include
system calls that return user IDs
.RB ( getuid (2),
.BR acct (5)),
and credentials returned with POSIX message queue notifications (see
.BR mq_notify (3)).
-.PP
+.P
There is one notable case where unmapped user and group IDs are
.I not
.\" from_kuid(), from_kgid()
.BR CAP_FOWNER ,
and
.BR CAP_FSETID .
-.PP
+.P
Within a user namespace,
these capabilities allow a process to bypass the rules
if the process has the relevant capability over the file,
.IP \[bu]
the file's user ID and group ID both have valid mappings
in the user namespace.
-.PP
+.P
The
.B CAP_FOWNER
capability is treated somewhat exceptionally:
the kernel.
When an unsupported subsystem is configured into the kernel,
it is not possible to configure user namespaces support.
-.PP
+.P
As at Linux 3.8, most relevant subsystems supported user namespaces,
but a number of filesystems did not have the infrastructure needed
to map user and group IDs between user namespaces.
.IR usage ()
function inside the program provide a full explanation of the program.
The following shell session demonstrates its use.
-.PP
+.P
First, we look at the run-time environment:
-.PP
+.P
.in +4n
.EX
$ \fBuname \-rs\fP # Need Linux 3.8 or later
1000
.EE
.in
-.PP
+.P
Now start a new shell in new user
.RI ( \-U ),
mount
and group ID
.RI ( \-G )
1000 mapped to 0 inside the user namespace:
-.PP
+.P
.in +4n
.EX
$ \fB./userns_child_exec \-p \-m \-U \-M \[aq]0 1000 1\[aq] \-G \[aq]0 1000 1\[aq] bash\fP
.EE
.in
-.PP
+.P
The shell has PID 1, because it is the first process in the new
PID namespace:
-.PP
+.P
.in +4n
.EX
bash$ \fBecho $$\fP
1
.EE
.in
-.PP
+.P
Mounting a new
.I /proc
filesystem and listing all of the processes visible
in the new PID namespace shows that the shell can't see
any processes outside the PID namespace:
-.PP
+.P
.in +4n
.EX
bash$ \fBmount \-t proc proc /proc\fP
22 pts/3 R+ 0:00 ps ax
.EE
.in
-.PP
+.P
Inside the user namespace, the shell has user and group ID 0,
and a full set of permitted and effective capabilities:
-.PP
+.P
.in +4n
.EX
bash$ \fBcat /proc/$$/status | egrep \[aq]\[ha][UG]id\[aq]\fP
.BR credentials (7),
.BR namespaces (7),
.BR pid_namespaces (7)
-.PP
+.P
The kernel source file
.IR Documentation/admin\-guide/namespaces/resource\-control.rst .
a superset of Unicode, occupies an even larger code
space\[em]31\ bits\[em]and the obvious
UCS-4 encoding for it (a sequence of 32-bit words) has the same problems.
-.PP
+.P
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.
.RI 10 xxxxxx
.RI 10 xxxxxx
.RI 10 xxxxxx
-.PP
+.P
The
.I xxx
bit positions are filled with the bits of the character code number in
binary representation, most significant bit first (big-endian).
Only the shortest possible multibyte sequence
which can represent the code number of the character can be used.
-.PP
+.P
The UCS code values 0xd800\[en]0xdfff (UTF-16 surrogates) as well as 0xfffe and
0xffff (UCS noncharacters) should not appear in conforming UTF-8 streams.
According to RFC 3629 no point above U+10FFFF should be used,
.SS Example
The Unicode character 0xa9 = 1010 1001 (the copyright sign) is encoded
in UTF-8 as
-.PP
+.P
.RS
11000010 10101001 = 0xc2 0xa9
.RE
-.PP
+.P
and character 0x2260 = 0010 0010 0110 0000 (the "not equal" symbol) is
encoded as:
-.PP
+.P
.RS
11100010 10001001 10100000 = 0xe2 0x89 0xa0
.RE
.SS Application notes
Users have to select a UTF-8 locale, for example with
-.PP
+.P
.RS
export LANG=en_GB.UTF-8
.RE
-.PP
+.P
in order to activate the UTF-8 support in applications.
-.PP
+.P
Application software that has to be aware of the used character
encoding should always set the locale with for example
-.PP
+.P
.RS
setlocale(LC_CTYPE, "")
.RE
-.PP
+.P
and programmers can then test the expression
-.PP
+.P
.RS
strcmp(nl_langinfo(CODESET), "UTF-8") == 0
.RE
-.PP
+.P
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.
-.PP
+.P
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.
and
.BR wcswidth (3)
should be used today to count characters and cursor positions.
-.PP
+.P
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
Changes made to these identifiers are visible to all other
processes in the same UTS namespace,
but are not visible to processes in other UTS namespaces.
-.PP
+.P
When a process creates a new UTS namespace using
.BR clone (2)
or
.B CLONE_NEWUTS
flag, the hostname and domain name of the new UTS namespace are copied
from the corresponding values in the caller's UTS namespace.
-.PP
+.P
Use of UTS namespaces requires a kernel that is configured with the
.B CONFIG_UTS_NS
option.
.SH SYNOPSIS
.nf
.B #include <sys/auxv.h>
-.PP
+.P
.B void *vdso = (uintptr_t) getauxval(AT_SYSINFO_EHDR);
.fi
.SH DESCRIPTION
This way you can code in the normal way using standard functions
and the C library will take care
of using any functionality that is available via the vDSO.
-.PP
+.P
Why does the vDSO exist at all?
There are some system calls the kernel provides that
user-space code ends up using frequently,
This is due both to the frequency of the call as well as the
context-switch overhead that results
from exiting user space and entering the kernel.
-.PP
+.P
The rest of this documentation is geared toward the curious and/or
C library writers rather than general developers.
If you're trying to call the vDSO in your own application rather than using
available at run time,
the C library can use functions provided by the kernel in
the vDSO.
-.PP
+.P
Note that the terminology can be confusing.
On x86 systems, the vDSO function
used to determine the preferred method of making a system call is
named "__kernel_vsyscall", but on x86-64,
the term "vsyscall" also refers to an obsolete way to ask the kernel
what time it is or what CPU the caller is on.
-.PP
+.P
One frequently used system call is
.BR gettimeofday (2).
This system call is called both directly by user-space applications
via the
.B AT_SYSINFO_EHDR
tag.
-.PP
+.P
You must not assume the vDSO is mapped at any particular location in the
user's memory map.
The base address will usually be randomized at run time every time a new
time).
This is done for security reasons,
to prevent "return-to-libc" attacks.
-.PP
+.P
For some architectures, there is also an
.B AT_SYSINFO
tag.
run time when running under different kernel versions.
Oftentimes the C library will do detection with the first call and then
cache the result for subsequent calls.
-.PP
+.P
All symbols are also versioned (using the GNU version format).
This allows the kernel to update the function signature without breaking
backward compatibility.
Thus, when looking up a symbol in the vDSO,
you must always include the version
to match the ABI you expect.
-.PP
+.P
Typically the vDSO follows the naming convention of prefixing
all symbols with "__vdso_" or "__kernel_"
so as to distinguish them from other standard symbols.
For example, the "gettimeofday" function is named "__vdso_gettimeofday".
-.PP
+.P
You use the standard C calling conventions when calling
any of these functions.
No need to worry about weird register or stack behavior.
When you compile the kernel,
it will automatically compile and link the vDSO code for you.
You will frequently find it under the architecture-specific directory:
-.PP
+.P
.in +4n
.EX
find arch/$ARCH/ \-name \[aq]*vdso*.so*\[aq] \-o \-name \[aq]*gate*.so*\[aq]
.SH ARCHITECTURE-SPECIFIC NOTES
The subsections below provide architecture-specific notes
on the vDSO.
-.PP
+.P
Note that the vDSO that is used is based on the ABI of your user-space code
and not the ABI of the kernel.
Thus, for example,
.in
.ft P
\}
-.PP
+.P
.\" See linux/arch/arm/kernel/entry-armv.S
.\" See linux/Documentation/arm/kernel_user_helpers.rst
Additionally, the ARM port has a code page full of utility functions.
Since it's just a raw page of code, there is no ELF information for doing
symbol lookups or versioning.
It does provide support for different versions though.
-.PP
+.P
For information on this code page,
it's best to refer to the kernel documentation
as it's extremely detailed and covers everything you need to know:
beyond sniffing raw opcodes,
but as this is an embedded CPU, it can get away with things\[em]some of the
object formats it runs aren't even ELF based (they're bFLT/FLAT).
-.PP
+.P
For information on this code page,
it's best to refer to the public documentation:
.br
.in
.ft P
\}
-.PP
+.P
The Itanium port is somewhat tricky.
In addition to the vDSO above, it also has "light-weight system calls"
(also known as "fast syscalls" or "fsys").
The permissions on the page are such that merely executing those addresses
automatically executes with kernel privileges and not in user space.
This is done to match the way HP-UX works.
-.PP
+.P
Since it's just a raw page of code, there is no ELF information for doing
symbol lookups or versioning.
Simply call into the appropriate offset via the branch instruction,
for example:
-.PP
+.P
.in +4n
.EX
ble <offset>(%sr2, %r0)
.in
.ft P
\}
-.PP
+.P
Before Linux 5.6,
.\" commit 654abc69ef2e69712e6d4e8a6cb9292b97a4aa39
the
.in
.ft P
\}
-.PP
+.P
Before Linux 4.16,
.\" commit 5c929885f1bb4b77f85b1769c49405a0e0f154a1
the
.BR syscalls (2),
.BR getauxval (3),
.BR proc (5)
-.PP
+.P
The documents, examples, and source code in the Linux source code tree:
-.PP
+.P
.in +4n
.EX
Documentation/ABI/stable/vdso
Documentation/ia64/fsys.rst
Documentation/vDSO/* (includes examples of using the vDSO)
-.PP
+.P
find arch/ \-iname \[aq]*vdso*\[aq] \-o \-iname \[aq]*gate*\[aq]
.EE
.in
.nf
.B #include <sys/socket.h>
.B #include <linux/vm_sockets.h>
-.PP
+.P
.IB stream_socket " = socket(AF_VSOCK, SOCK_STREAM, 0);"
.IB datagram_socket " = socket(AF_VSOCK, SOCK_DGRAM, 0);"
.fi
This address family is used by guest agents and
hypervisor services that need a communications channel that is independent of
virtual machine network configuration.
-.PP
+.P
Valid socket types are
.B SOCK_STREAM
and
best-effort ordering.
Availability of these socket types is dependent on the
underlying hypervisor.
-.PP
+.P
A new socket is created with
-.PP
+.P
.in +4n
.EX
socket(AF_VSOCK, socket_type, 0);
.EE
.in
-.PP
+.P
When a process wants to establish a connection, it calls
.BR connect (2)
with a given destination socket address.
The socket is automatically bound to a free port if unbound.
-.PP
+.P
A process can listen for incoming connections by first binding to a socket
address using
.BR bind (2)
and then calling
.BR listen (2).
-.PP
+.P
Data is transmitted using the
.BR send (2)
or
which is either a virtual machine or the host.
The port number differentiates between multiple services running on
a single machine.
-.PP
+.P
.in +4n
.EX
struct sockaddr_vm {
};
.EE
.in
-.PP
+.P
.I svm_family
is always set to
.BR AF_VSOCK .
to these port numbers.
.I svm_zero
must be zero-filled.
-.PP
+.P
There are several special addresses:
.B VMADDR_CID_ANY
(\-1U)
.B VMADDR_CID_HOST
(2)
is the well-known address of the host.
-.PP
+.P
The special constant
.B VMADDR_PORT_ANY
(\-1U)
.B SOCK_STREAM
sockets become disconnected when the virtual machine migrates to a new host.
Applications must reconnect when this happens.
-.PP
+.P
The local CID may change across live migration if the old CID is
not available on the new host.
Bound sockets are automatically updated to the new CID.
(1) directs packets to the same host that generated them.
This is useful
for testing applications on a single host and for debugging.
-.PP
+.P
The local CID obtained with
.B IOCTL_VM_SOCKETS_GET_LOCAL_CID
can be used for the same purpose, but it is preferable to use
Support for VMware (VMCI) has been available since Linux 3.9.
KVM (virtio) is supported since Linux 4.8.
Hyper-V is supported since Linux 4.14.
-.PP
+.P
.B VMADDR_CID_LOCAL
is supported since Linux 5.6.
.\" commit ef343b35d46667668a099655fca4a5b2e43a5dfe
.nf
.B #include <sys/socket.h>
.B #include <linux/x25.h>
-.PP
+.P
.IB x25_socket " = socket(AF_X25, SOCK_SEQPACKET, 0);"
.fi
.SH DESCRIPTION
X25 sockets can also be used for communication
without an intermediate X.25 network (X.25 DTE-DTE mode) as described
in ISO-8208.
-.PP
+.P
Message boundaries are preserved \[em] a
.BR read (2)
from a socket will
.I struct sockaddr_x25
for representing network addresses as defined in ITU-T
recommendation X.121.
-.PP
+.P
.in +4n
.EX
struct sockaddr_x25 {
};
.EE
.in
-.PP
+.P
.I sx25_addr
contains a char array
.I x25_addr[]
.SH BUGS
Plenty, as the X.25 PLP implementation is
.BR CONFIG_EXPERIMENTAL .
-.PP
+.P
This man page is incomplete.
-.PP
+.P
There is no dedicated application programmer's header file yet;
you need to include the kernel header file
.IR <linux/x25.h> .
.B CONFIG_EXPERIMENTAL
might also imply that future versions of the
interface are not binary compatible.
-.PP
+.P
X.25 N-Reset events are not propagated to the user process yet.
Thus,
if a reset occurred, data might be lost without notice.
.SH SEE ALSO
.BR socket (2),
.BR socket (7)
-.PP
+.P
Jonathan Simon Naylor:
\[lq]The Re-Analysis and Re-Implementation of X.25.\[rq]
The URL is
with a process.
An attribute may be defined or undefined.
If it is defined, its value may be empty or non-empty.
-.PP
+.P
Extended attributes are extensions to the normal attributes which are
associated with all inodes in the system (i.e., the
.BR stat (2)
They are often used to provide additional functionality
to a filesystem\[em]for example, additional security features such as
Access Control Lists (ACLs) may be implemented using extended attributes.
-.PP
+.P
Users with search access to a file or directory may use
.BR listxattr (2)
to retrieve a list of attribute names defined for that file or directory.
-.PP
+.P
Extended attributes are accessed as atomic objects.
Reading
.RB ( getxattr (2))
Writing
.RB ( setxattr (2))
replaces any previous value with the new value.
-.PP
+.P
Space consumed for extended attributes may be counted towards the disk quotas
of the file owner and file group.
.SS Extended attribute namespaces
.IR system.posix_acl_access ,
or
.IR security.selinux .
-.PP
+.P
The namespace mechanism is used to define different classes of extended
attributes.
These different classes exist for several reasons;
for example, the permissions
and capabilities required for manipulating extended attributes of one
namespace may differ to another.
-.PP
+.P
Currently, the
.IR security ,
.IR system ,
attributes are defined by the file permission bits:
read permission is required to retrieve the attribute value,
and writer permission is required to change it.
-.PP
+.P
The file permission bits of regular files and directories are
interpreted differently from the file permission bits of special files
and symbolic links.
These differences would allow users to consume filesystem resources in
a way not controllable by disk quotas for group or world writable
special files and directories.
-.PP
+.P
For this reason,
user extended attributes are allowed only for regular files and directories,
and access to user extended attributes is restricted to the
can be returned is also limited to 64\ kB
(see BUGS in
.BR listxattr (2)).
-.PP
+.P
Some filesystems, such as Reiserfs (and, historically, ext2 and ext3),
require the filesystem to be mounted with the
.B user_xattr
mount option in order for user extended attributes to be used.
-.PP
+.P
In the current ext2, ext3, and ext4 filesystem implementations,
the total bytes used by the names and values of all of a file's
extended attributes must fit in a single filesystem block (1024, 2048
or 4096 bytes, depending on the block size specified when the
filesystem was created).
-.PP
+.P
In the Btrfs, XFS, and Reiserfs filesystem implementations, there is no
practical limit on the number of extended attributes
associated with a file, and the algorithms used to store extended
attribute information on disk are scalable.
-.PP
+.P
In the JFS, XFS, and Reiserfs filesystem implementations,
the limit on bytes used in an EA value is the ceiling imposed by the VFS.
-.PP
+.P
In the Btrfs filesystem implementation,
the total bytes used for the name, value, and implementation overhead bytes
is limited to the filesystem
be used on architectures with a different byte order and machine word
size, care should be taken to store attribute values in an
architecture-independent format.
-.PP
+.P
This page was formerly named
.BR attr (5).
.\" .SH AUTHORS
programs that use
.BR iconv (3),
so a caching mechanism is employed.
-.PP
+.P
The
.B iconvconfig
program reads iconv module configuration files and writes
a fast-loading gconv module configuration cache file.
-.PP
+.P
In addition to the system provided gconv modules, the user can specify
custom gconv module directories with the environment variable
.BR GCONV_PATH .
.TP
.I /usr/lib/gconv/gconv\-modules.cache
Usual system gconv module configuration cache.
-.PP
+.P
Depending on the architecture,
the above files may instead be located at directories with the path prefix
.IR /usr/lib64 .
which either can be or are used only by the superuser,
like system-administration commands, daemons,
and hardware-related commands.
-.PP
+.P
As with the commands described in Section 1, the commands described
in this section terminate with an exit status that indicates
whether the command succeeded or failed.
which is stored in the
.B .interp
section of the program is executed) or directly by running:
-.PP
+.P
.I /lib/ld\-linux.so.*
[OPTIONS] [PROGRAM [ARGUMENTS]]
.SH DESCRIPTION
.B ld\-linux.so*
find and load the shared objects (shared libraries) needed by a program,
prepare the program to run, and then run it.
-.PP
+.P
Linux binaries require dynamic linking (linking at run time)
unless the
.B \-static
option was given to
.BR ld (1)
during compilation.
-.PP
+.P
The program
.B ld.so
handles a.out binaries, a binary format used long ago.
.BR ldconfig (8),
and
.IR /etc/ld.so.conf ).
-.PP
+.P
When resolving shared object dependencies,
the dynamic linker first inspects each dependency
string to see if it contains a slash (this can occur if
If a slash is found, then the dependency string is interpreted as
a (relative or absolute) pathname,
and the shared object is loaded using that pathname.
-.PP
+.P
If a shared object dependency does not contain a slash,
then it is searched for in the following order:
.IP (1) 5
and
.BR dlmopen (3)
functions.
-.PP
+.P
The substituted tokens are as follows:
.TP
.IR $ORIGIN " (or equivalently " ${ORIGIN} )
.\"
.\" ld.so lets names be abbreviated, so $O will work for $ORIGIN;
.\" Don't do this!!
-.PP
+.P
Note that the dynamic string tokens have to be quoted properly when
set from a shell,
to prevent their expansion as shell or environment variables.
.BR TMPDIR ,
and
.BR TZDIR .
-.PP
+.P
A binary is executed in secure-execution mode if the
.B AT_SECURE
entry in the auxiliary vector (see
dependencies, as if run by
.BR ldd (1),
instead of running normally.
-.PP
+.P
Then there are lots of more or less obscure variables,
many obsolete or only for internal use.
.TP
and
.I /usr/lib64
are used for 64-bit libraries.
-.PP
+.P
The cache is used by the run-time linker,
.I ld.so
or
.B \%ldconfig
should normally be run by the superuser as it may require write
permission on some root owned directories and files.
-.PP
+.P
.B \%ldconfig
will look only at files that are named
.I lib*.so*
where the middle file
.RB ( libfoo.so.1
here) is the SONAME for the library:
-.PP
+.P
.in +4n
.EX
libfoo.so \-> libfoo.so.1 \-> libfoo.so.1.12
.EE
.in
-.PP
+.P
Failure to follow this pattern may result in compatibility issues
after an upgrade.
.SH OPTIONS
determines the behavior of the cache daemon.
See
.BR nscd.conf (5).
-.PP
+.P
.B nscd
provides caching for accesses of the
.BR passwd (5),
.BR getgrgid (3),
.BR gethostbyname (3),
and others.
-.PP
+.P
There are two caches for each database:
a positive one for items found, and a negative one
for items not found.
after changing the configuration file of the database so that
.B nscd
invalidates its cache:
-.PP
+.P
.in +4n
.EX
$ \fBnscd \-i\fP \fI<database>\fP
This means that if for some reason the dynamic linker is not working,
.B sln
can be used to make symbolic links to dynamic libraries.
-.PP
+.P
The command line has two forms.
In the first form, it creates
.I dest
as a new symbolic link to
.IR source .
-.PP
+.P
In the second form,
.I filelist
is a list of space-separated pathname pairs,
.B sln
was executed once for each line of the file,
with the two pathnames as the arguments.
-.PP
+.P
The
.B sln
program supports no command-line options.
program asks the user for information about the current location,
and outputs the resulting timezone to standard output.
The output is suitable as a value for the TZ environment variable.
-.PP
+.P
All interaction with the user is done via standard input and standard error.
.SH OPTIONS
.TP
.q "\fIdate time interval\fP",
one line for each transition time and following interval. Fields are
separated by single tabs.
-.PP
+.P
Dates are in
.IR yyyy - mm - dd
format and times are in 24-hour
characters. An isdst flag is omitted for standard time, and otherwise
is a decimal integer that is unsigned and positive (typically 1) for
daylight saving time and negative for unknown.
-.PP
+.P
In times and in UT offsets with absolute value less than 100 hours,
the seconds are omitted if they are zero, and
the minutes are also omitted if they are also zero. Positive UT
.q "\*-"
or is
.q "zzz".
-.PP
+.P
In double-quoted strings, escape sequences represent unusual
characters. The escape sequences are \es for space, and \e", \e\e,
\ef, \en, \er, \et, and \ev with their usual meaning in the C
programming language. E.g., the double-quoted string
\*(lq"CET\es\e"\e\e"\*(rq represents the character sequence \*(lqCET
"\e\*(rq.\""
-.PP
+.P
.ne 9
Here is an example of the output, with the leading empty line omitted.
(This example is shown with tab stops set far enough apart so that the
Immediately after the last transition the date is 1947-06-08 and the
time is 02:30:00, and the following time interval is 10 hours west of
UT, a standard time abbreviated HST.
-.PP
+.P
.ne 10
Here are excerpts from another example:
.nf
at twelve-hour intervals.
This works in all real-world cases;
one can construct artificial time zones for which this fails.
-.PP
+.P
In the
.B \*-v
and
.B \*-v
Be more verbose, and complain about the following situations:
.RS
-.PP
+.P
The input specifies a link to a link,
something not supported by some older parsers, including
.B zic
itself through release 2022e.
-.PP
+.P
A year that appears in a data file is outside the range
of representable years.
-.PP
+.P
A time of 24:00 or more appears in the input.
Pre-1998 versions of
.B zic
prohibit 24:00, and pre-2007 versions prohibit times greater than 24:00.
-.PP
+.P
A rule goes past the start or end of the month.
Pre-2004 versions of
.B zic
prohibit this.
-.PP
+.P
A time zone abbreviation uses a
.B %z
format.
Pre-2015 versions of
.B zic
do not support this.
-.PP
+.P
A timestamp contains fractional seconds.
Pre-2018 versions of
.B zic
do not support this.
-.PP
+.P
The input contains abbreviations that are mishandled by pre-2018 versions of
.B zic
due to a longstanding coding bug.
.q Su
for
.q Sun .
-.PP
+.P
The output file does not contain all the information about the
long-term future of a timezone, because the future cannot be summarized as
an extended POSIX TZ string. For example, as of 2023 this problem
occurs for Morocco's daylight-saving rules, as these rules are based
on predictions for when Ramadan will be observed, something that
an extended POSIX TZ string cannot represent.
-.PP
+.P
The output contains data that may not be handled properly by client
code designed for older
.B zic
output formats. These compatibility issues affect only timestamps
before 1970 or after the start of 2038.
-.PP
+.P
The output contains a truncated leap second table,
which can cause some older TZif readers to misbehave.
This can occur if the
the
.B "\*-r"
option is also used.
-.PP
+.P
The output file contains more than 1200 transitions,
which may be mishandled by some clients.
The current reference client supports at most 2000 transitions;
pre-2014 versions of the reference client support at most 1200
transitions.
-.PP
+.P
A time zone abbreviation has fewer than 3 or more than 6 characters.
POSIX requires at least 3, and requires implementations to support
at least 6.
-.PP
+.P
An output file name contains a byte that is not an ASCII letter,
.q "\*-" ,
.q "/" ,
Input files use the format described in this section; output files use
.BR tzfile (5)
format.
-.PP
+.P
Input files should be text files, that is, they should be a series of
zero or more lines, each ending in a newline byte and containing at
most 2048 bytes counting the newline, and without any NUL bytes.
limited to the restricted syntax described under the
.B \*-v
option.
-.PP
+.P
Input lines are made up of fields.
Fields are separated from one another by one or more white space characters.
The white space characters are space, form feed, carriage return, newline,
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.
-.PP
+.P
Names must be in English and are case insensitive.
They appear in several contexts, and include month and weekday names
and keywords such as
.BR "Zone" .
A name can be abbreviated by omitting all but an initial prefix; any
abbreviation must be unambiguous in context.
-.PP
+.P
A rule line has the form
.nf
.ti +.5i
If this field is
.q \*- ,
the variable part is null.
-.PP
+.P
A zone line has the form
.sp
.nf
.q "until"
information, just as zone lines do, indicating that the next line is a further
continuation.
-.PP
+.P
If a zone changes at the same instant that a rule would otherwise take
effect in the earlier zone or continuation line, the rule is ignored.
A zone or continuation line
first transition into standard time.
In a single zone it is an error if two rules take effect at the same
instant, or if two zone changes take effect at the same instant.
-.PP
+.P
If a continuation line subtracts
.I N
seconds from the UT offset after a transition that would be
.B zic
interprets this more sensibly as a single transition from 02:00 CST (\*-05) to
02:00 CDT (\*-05).
-.PP
+.P
A link line has the form
.sp
.nf
.fi
The two links are chained together, and G_M_T, Greenwich, and Etc/GMT
all name the same zone.
-.PP
+.P
Except for continuation lines,
lines may appear in any order in the input.
However, the behavior is unspecified if multiple zone or link lines
define the same name.
-.PP
+.P
The file that describes leap seconds can have leap lines and an
expiration line.
Leap lines have the following form:
.q "Rolling"
if the leap second time given by the other fields should be interpreted as
local (wall clock) time.
-.PP
+.P
Rolling leap seconds were implemented back when it was not
clear whether common practice was rolling or stationary,
with concerns that one would see
also, they are not supported if the
.B \*-r
option is used.
-.PP
+.P
The expiration line, if present, has the form:
.nf
.ti +.5i
.q "Rule Swiss")
apply. From 1981 to the present, EU daylight saving rules have
applied, and the UTC offset has remained at one hour.
-.PP
+.P
In 1941 and 1942, daylight saving time applied from the first Monday
in May at 01:00 to the first Monday in October at 02:00.
The pre-1981 EU daylight-saving rules have no effect
saving has begun on the last Sunday in March at 01:00 UTC.
Until 1995 it ended the last Sunday in September at 01:00 UTC,
but this changed to the last Sunday in October starting in 1996.
-.PP
+.P
For purposes of display,
.q "LMT"
and
.B AT
field of the earliest transition time's rule to ensure that
the earliest transition time recorded in the compiled file is correct.
-.PP
+.P
If,
for a particular timezone,
a clock advance caused by the start of daylight saving
projects / thirdparty / man-pages.git / commitdiff
