Post_Tenebras_TUX/Debian-9-Kernel
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
1edf9dca067d5dcadb5e6b9bf694f5d88da14161
Debian-9-Kernel/.metadata/.plugins/org.eclipse.linuxtools.cdt.libhover/C/glibc_library.libhover
T

17175 lines
1015 KiB
Plaintext
Raw Normal View History

UOPGRADE FROM KERNEL 4.9.330-0 to 4.9.337-0
2023-12-14 15:23:35 +01:00
¬ísr0org.eclipse.linuxtools.cdt.libhover.LibHoverInfoLclassestLjava/util/HashMap;L functionstLjava/util/TreeMap;Ltypedefsq~xpsrjava.util.HashMapÚÁÃ`ÑF
loadFactorI thresholdxp?@wxsrjava.util.TreeMap Áö>-%jæL
comparatortLjava/util/Comparator;xppw«t0-REQUIRED-SECTIONSsr0org.eclipse.linuxtools.cdt.libhover.FunctionInfoLdesctLjava/lang/String;LheaderstLjava/util/ArrayList;Lnameq~ L prototypeq~ L
returnTypeq~ xptȨ
The GNU C Library (Eclipse Libhover Version)
Based on The GNU C Library
EDITION 0.12
VERSION 2.8
UPDATED 2007-10-27
ISBN 1-882114-55-8
This file documents the GNU C library.
This is based on Edition 0.12, last updated 2007-10-27
of The GNU C Library Reference Manual, for version 2.8.
Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2001, 2002,
2003, 2007, 2008, 2010 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being ``Free Software Needs Free Documentation''
and ``GNU Lesser General Public License'', the Front-Cover texts being
``A GNU Manual'', and with the Back-Cover Texts as in (a) below. A
copy of the license is included in the section entitled "GNU Free
Documentation License".
(a) The FSF's Back-Cover Text is: ``You have the freedom to
copy and modify this GNU manual. Buying copies from the FSF
supports it in developing GNU and promoting software freedom.''
Authors
Sandra Loosemore
with
Richard M. Stallman, Roland McGrath, Andrew Oram, and Ulrich Drepper
Edition 0.12
last updated 2007-10-27
for version 2.8
Modified for use with Eclipse libhover plug-in by Jeff Johnston.
Modified documentation published by Eclipse Linux Tools project
Cover art for the Free Software Foundation's printed edition
by Etienne Suvasa.
==================================================================================================
Free Software Needs Free Documentation
The biggest deficiency in the free software community today is not in
the software---it is the lack of good free documentation that we can
include with the free software. Many of our most important
programs do not come with free reference manuals and free introductory
texts. Documentation is an essential part of any software package;
when an important free software package does not come with a free
manual and a free tutorial, that is a major gap. We have many such
gaps today.
Consider Perl, for instance. The tutorial manuals that people
normally use are non-free. How did this come about? Because the
authors of those manuals published them with restrictive terms---no
copying, no modification, source files not available---which exclude
them from the free software world.
That wasn't the first time this sort of thing happened, and it was far
from the last. Many times we have heard a GNU user eagerly describe a
manual that he is writing, his intended contribution to the community,
only to learn that he had ruined everything by signing a publication
contract to make it non-free.
Free documentation, like free software, is a matter of freedom, not
price. The problem with the non-free manual is not that publishers
charge a price for printed copies---that in itself is fine. (The Free
Software Foundation sells printed copies of manuals, too.) The
problem is the restrictions on the use of the manual. Free manuals
are available in source code form, and give you permission to copy and
modify. Non-free manuals do not allow this.
The criteria of freedom for a free manual are roughly the same as for
free software. Redistribution (including the normal kinds of
commercial redistribution) must be permitted, so that the manual can
accompany every copy of the program, both on-line and on paper.
Permission for modification of the technical content is crucial too.
When people modify the software, adding or changing features, if they
are conscientious they will change the manual too---so they can
provide accurate and clear documentation for the modified program. A
manual that leaves you no choice but to write a new manual to document
a changed version of the program is not really available to our
community.
Some kinds of limits on the way modification is handled are
acceptable. For example, requirements to preserve the original
author's copyright notice, the distribution terms, or the list of
authors, are ok. It is also no problem to require modified versions
to include notice that they were modified. Even entire sections that
may not be deleted or changed are acceptable, as long as they deal
with nontechnical topics (like this one). These kinds of restrictions
are acceptable because they don't obstruct the community's normal use
of the manual.
However, it must be possible to modify all the @emph{technical}
content of the manual, and then distribute the result in all the usual
media, through all the usual channels. Otherwise, the restrictions
obstruct the use of the manual, it is not free, and we need another
manual to replace it.
Please spread the word about this issue. Our community continues to
lose manuals to proprietary publishing. If we spread the word that
free software needs free reference manuals and free tutorials, perhaps
the next person who wants to contribute by writing documentation will
realize, before it is too late, that only free manuals contribute to
the free software community.
If you are writing documentation, please insist on publishing it under
the GNU Free Documentation License or another free documentation
license. Remember that this decision requires your approval---you
don't have to let the publisher decide. Some commercial publishers
will use a free license if you insist, but they will not propose the
option; it is up to you to raise the issue and say firmly that this is
what you want. If the publisher you are dealing with refuses, please
try other publishers. If you're not sure whether a proposed license
is free, write to @email{licensing@@gnu.org}.
You can encourage commercial publishers to sell more free, copylefted
manuals and tutorials by buying them, and particularly by buying
copies from the publishers that paid for their writing or for major
improvements. Meanwhile, try to avoid buying non-free documentation
at all. Check the distribution terms of a manual before you buy it,
and insist that whoever seeks your business must respect your freedom.
Check the history of the book, and try reward the publishers that have
paid or pay the authors to work on it.
The Free Software Foundation maintains a list of free documentation
published by other publishers, at
http://www.fsf.org/doc/other-free-books.html.
====================================================================================================
GNU Lesser General Public License
Version 2.1, February 1999
Copyright @copyright{} 1991, 1999 Free Software Foundation, Inc.
59 Temple Place -- Suite 330, Boston, MA 02111-1307, USA
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
[This is the first released version of the Lesser GPL. It also counts
as the successor of the GNU Library Public License, version 2, hence the
version number 2.1.]
Preamble
The licenses for most software are designed to take away your
freedom to share and change it. By contrast, the GNU General Public
Licenses are intended to guarantee your freedom to share and change
free software---to make sure the software is free for all its users.
This license, the Lesser General Public License, applies to some
specially designated software---typically libraries---of the Free
Software Foundation and other authors who decide to use it. You can use
it too, but we suggest you first think carefully about whether this
license or the ordinary General Public License is the better strategy to
use in any particular case, based on the explanations below.
When we speak of free software, we are referring to freedom of use,
not price. Our General Public Licenses are designed to make sure that
you have the freedom to distribute copies of free software (and charge
for this service if you wish); that you receive source code or can get
it if you want it; that you can change the software and use pieces of it
in new free programs; and that you are informed that you can do these
things.
To protect your rights, we need to make restrictions that forbid
distributors to deny you these rights or to ask you to surrender these
rights. These restrictions translate to certain responsibilities for
you if you distribute copies of the library or if you modify it.
For example, if you distribute copies of the library, whether gratis
or for a fee, you must give the recipients all the rights that we gave
you. You must make sure that they, too, receive or can get the source
code. If you link other code with the library, you must provide
complete object files to the recipients, so that they can relink them
with the library after making changes to the library and recompiling
it. And you must show them these terms so they know their rights.
We protect your rights with a two-step method: (1) we copyright the
library, and (2) we offer you this license, which gives you legal
permission to copy, distribute and/or modify the library.
To protect each distributor, we want to make it very clear that
there is no warranty for the free library. Also, if the library is
modified by someone else and passed on, the recipients should know
that what they have is not the original version, so that the original
author's reputation will not be affected by problems that might be
introduced by others.
Finally, software patents pose a constant threat to the existence of
any free program. We wish to make sure that a company cannot
effectively restrict the users of a free program by obtaining a
restrictive license from a patent holder. Therefore, we insist that
any patent license obtained for a version of the library must be
consistent with the full freedom of use specified in this license.
Most GNU software, including some libraries, is covered by the
ordinary GNU General Public License. This license, the GNU Lesser
General Public License, applies to certain designated libraries, and
is quite different from the ordinary General Public License. We use
this license for certain libraries in order to permit linking those
libraries into non-free programs.
When a program is linked with a library, whether statically or using
a shared library, the combination of the two is legally speaking a
combined work, a derivative of the original library. The ordinary
General Public License therefore permits such linking only if the
entire combination fits its criteria of freedom. The Lesser General
Public License permits more lax criteria for linking other code with
the library.
We call this license the @dfn{Lesser} General Public License because it
does @emph{Less} to protect the user's freedom than the ordinary General
Public License. It also provides other free software developers Less
of an advantage over competing non-free programs. These disadvantages
are the reason we use the ordinary General Public License for many
libraries. However, the Lesser license provides advantages in certain
special circumstances.
For example, on rare occasions, there may be a special need to
encourage the widest possible use of a certain library, so that it becomes
a de-facto standard. To achieve this, non-free programs must be
allowed to use the library. A more frequent case is that a free
library does the same job as widely used non-free libraries. In this
case, there is little to gain by limiting the free library to free
software only, so we use the Lesser General Public License.
In other cases, permission to use a particular library in non-free
programs enables a greater number of people to use a large body of
free software. For example, permission to use the GNU C Library in
non-free programs enables many more people to use the whole GNU
operating system, as well as its variant, the GNU/Linux operating
system.
Although the Lesser General Public License is Less protective of the
users' freedom, it does ensure that the user of a program that is
linked with the Library has the freedom and the wherewithal to run
that program using a modified version of the Library.
The precise terms and conditions for copying, distribution and
modification follow. Pay close attention to the difference between a
``work based on the library'' and a ``work that uses the library''. The
former contains code derived from the library, whereas the latter must
be combined with the library in order to run.
TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
0.
This License Agreement applies to any software library or other program
which contains a notice placed by the copyright holder or other
authorized party saying it may be distributed under the terms of this
Lesser General Public License (also called ``this License''). Each
licensee is addressed as ``you''.
A ``library'' means a collection of software functions and/or data
prepared so as to be conveniently linked with application programs
(which use some of those functions and data) to form executables.
The ``Library'', below, refers to any such software library or work
which has been distributed under these terms. A ``work based on the
Library'' means either the Library or any derivative work under
copyright law: that is to say, a work containing the Library or a
portion of it, either verbatim or with modifications and/or translated
straightforwardly into another language. (Hereinafter, translation is
included without limitation in the term ``modification''.)
``Source code'' for a work means the preferred form of the work for
making modifications to it. For a library, complete source code means
all the source code for all modules it contains, plus any associated
interface definition files, plus the scripts used to control compilation
and installation of the library.
Activities other than copying, distribution and modification are not
covered by this License; they are outside its scope. The act of
running a program using the Library is not restricted, and output from
such a program is covered only if its contents constitute a work based
on the Library (independent of the use of the Library in a tool for
writing it). Whether that is true depends on what the Library does
and what the program that uses the Library does.
1.
You may copy and distribute verbatim copies of the Library's
complete source code as you receive it, in any medium, provided that
you conspicuously and appropriately publish on each copy an
appropriate copyright notice and disclaimer of warranty; keep intact
all the notices that refer to this License and to the absence of any
warranty; and distribute a copy of this License along with the
Library.
You may charge a fee for the physical act of transferring a copy,
and you may at your option offer warranty protection in exchange for a
fee.
2.
You may modify your copy or copies of the Library or any portion
of it, thus forming a work based on the Library, and copy and
distribute such modifications or work under the terms of Section 1
above, provided that you also meet all of these conditions:
a. The modified work must itself be a software library.
b. You must cause the files modified to carry prominent notices
stating that you changed the files and the date of any change.
c. You must cause the whole of the work to be licensed at no
charge to all third parties under the terms of this License.
d. If a facility in the modified Library refers to a function or a
table of data to be supplied by an application program that uses
the facility, other than as an argument passed when the facility
is invoked, then you must make a good faith effort to ensure that,
in the event an application does not supply such function or
table, the facility still operates, and performs whatever part of
its purpose remains meaningful.
(For example, a function in a library to compute square roots has
a purpose that is entirely well-defined independent of the
application. Therefore, Subsection 2d requires that any
application-supplied function or table used by this function must
be optional: if the application does not supply it, the square
root function must still compute square roots.)
@end enumerate
These requirements apply to the modified work as a whole. If
identifiable sections of that work are not derived from the Library,
and can be reasonably considered independent and separate works in
themselves, then this License, and its terms, do not apply to those
sections when you distribute them as separate works. But when you
distribute the same sections as part of a whole which is a work based
on the Library, the distribution of the whole must be on the terms of
this License, whose permissions for other licensees extend to the
entire whole, and thus to each and every part regardless of who wrote
it.
Thus, it is not the intent of this section to claim rights or contest
your rights to work written entirely by you; rather, the intent is to
exercise the right to control the distribution of derivative or
collective works based on the Library.
In addition, mere aggregation of another work not based on the Library
with the Library (or with a work based on the Library) on a volume of
a storage or distribution medium does not bring the other work under
the scope of this License.
3.
You may opt to apply the terms of the ordinary GNU General Public
License instead of this License to a given copy of the Library. To do
this, you must alter all the notices that refer to this License, so
that they refer to the ordinary GNU General Public License, version 2,
instead of to this License. (If a newer version than version 2 of the
ordinary GNU General Public License has appeared, then you can specify
that version instead if you wish.) Do not make any other change in
these notices.
Once this change is made in a given copy, it is irreversible for
that copy, so the ordinary GNU General Public License applies to all
subsequent copies and derivative works made from that copy.
This option is useful when you wish to copy part of the code of
the Library into a program that is not a library.
4.
You may copy and distribute the Library (or a portion or
derivative of it, under Section 2) in object code or executable form
under the terms of Sections 1 and 2 above provided that you accompany
it with the complete corresponding machine-readable source code, which
must be distributed under the terms of Sections 1 and 2 above on a
medium customarily used for software interchange.
If distribution of object code is made by offering access to copy
from a designated place, then offering equivalent access to copy the
source code from the same place satisfies the requirement to
distribute the source code, even though third parties are not
compelled to copy the source along with the object code.
5.
A program that contains no derivative of any portion of the
Library, but is designed to work with the Library by being compiled or
linked with it, is called a ``work that uses the Library''. Such a
work, in isolation, is not a derivative work of the Library, and
therefore falls outside the scope of this License.
However, linking a ``work that uses the Library'' with the Library
creates an executable that is a derivative of the Library (because it
contains portions of the Library), rather than a ``work that uses the
library''. The executable is therefore covered by this License.
Section 6 states terms for distribution of such executables.
When a ``work that uses the Library'' uses material from a header file
that is part of the Library, the object code for the work may be a
derivative work of the Library even though the source code is not.
Whether this is true is especially significant if the work can be
linked without the Library, or if the work is itself a library. The
threshold for this to be true is not precisely defined by law.
If such an object file uses only numerical parameters, data
structure layouts and accessors, and small macros and small inline
functions (ten lines or less in length), then the use of the object
file is unrestricted, regardless of whether it is legally a derivative
work. (Executables containing this object code plus portions of the
Library will still fall under Section 6.)
Otherwise, if the work is a derivative of the Library, you may
distribute the object code for the work under the terms of Section 6.
Any executables containing that work also fall under Section 6,
whether or not they are linked directly with the Library itself.
6.
As an exception to the Sections above, you may also combine or
link a ``work that uses the Library'' with the Library to produce a
work containing portions of the Library, and distribute that work
under terms of your choice, provided that the terms permit
modification of the work for the customer's own use and reverse
engineering for debugging such modifications.
You must give prominent notice with each copy of the work that the
Library is used in it and that the Library and its use are covered by
this License. You must supply a copy of this License. If the work
during execution displays copyright notices, you must include the
copyright notice for the Library among them, as well as a reference
directing the user to the copy of this License. Also, you must do one
of these things:
a. Accompany the work with the complete corresponding
machine-readable source code for the Library including whatever
changes were used in the work (which must be distributed under
Sections 1 and 2 above); and, if the work is an executable linked
with the Library, with the complete machine-readable ``work that
uses the Library'', as object code and/or source code, so that the
user can modify the Library and then relink to produce a modified
executable containing the modified Library. (It is understood
that the user who changes the contents of definitions files in the
Library will not necessarily be able to recompile the application
to use the modified definitions.)
b. Use a suitable shared library mechanism for linking with the Library. A
suitable mechanism is one that (1) uses at run time a copy of the
library already present on the user's computer system, rather than
copying library functions into the executable, and (2) will operate
properly with a modified version of the library, if the user installs
one, as long as the modified version is interface-compatible with the
version that the work was made with.
c. Accompany the work with a written offer, valid for at
least three years, to give the same user the materials
specified in Subsection 6a, above, for a charge no more
than the cost of performing this distribution.
d. If distribution of the work is made by offering access to copy
from a designated place, offer equivalent access to copy the above
specified materials from the same place.
e. Verify that the user has already received a copy of these
materials or that you have already sent this user a copy.
@end enumerate
For an executable, the required form of the ``work that uses the
Library'' must include any data and utility programs needed for
reproducing the executable from it. However, as a special exception,
the materials to be distributed need not include anything that is
normally distributed (in either source or binary form) with the major
components (compiler, kernel, and so on) of the operating system on
which the executable runs, unless that component itself accompanies the
executable.
It may happen that this requirement contradicts the license
restrictions of other proprietary libraries that do not normally
accompany the operating system. Such a contradiction means you cannot
use both them and the Library together in an executable that you
distribute.
7.
You may place library facilities that are a work based on the
Library side-by-side in a single library together with other library
facilities not covered by this License, and distribute such a combined
library, provided that the separate distribution of the work based on
the Library and of the other library facilities is otherwise
permitted, and provided that you do these two things:
a. Accompany the combined library with a copy of the same work
based on the Library, uncombined with any other library
facilities. This must be distributed under the terms of the
Sections above.
b. Give prominent notice with the combined library of the fact
that part of it is a work based on the Library, and explaining
where to find the accompanying uncombined form of the same work.
8.
You may not copy, modify, sublicense, link with, or distribute
the Library except as expressly provided under this License. Any
attempt otherwise to copy, modify, sublicense, link with, or
distribute the Library is void, and will automatically terminate your
rights under this License. However, parties who have received copies,
or rights, from you under this License will not have their licenses
terminated so long as such parties remain in full compliance.
9.
You are not required to accept this License, since you have not
signed it. However, nothing else grants you permission to modify or
distribute the Library or its derivative works. These actions are
prohibited by law if you do not accept this License. Therefore, by
modifying or distributing the Library (or any work based on the
Library), you indicate your acceptance of this License to do so, and
all its terms and conditions for copying, distributing or modifying
the Library or works based on it.
10.
Each time you redistribute the Library (or any work based on the
Library), the recipient automatically receives a license from the
original licensor to copy, distribute, link with or modify the Library
subject to these terms and conditions. You may not impose any further
restrictions on the recipients' exercise of the rights granted herein.
You are not responsible for enforcing compliance by third parties with
this License.
11.
If, as a consequence of a court judgment or allegation of patent
infringement or for any other reason (not limited to patent issues),
conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License. If you cannot
distribute so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you
may not distribute the Library at all. For example, if a patent
license would not permit royalty-free redistribution of the Library by
all those who receive copies directly or indirectly through you, then
the only way you could satisfy both it and this License would be to
refrain entirely from distribution of the Library.
If any portion of this section is held invalid or unenforceable under any
particular circumstance, the balance of the section is intended to apply,
and the section as a whole is intended to apply in other circumstances.
It is not the purpose of this section to induce you to infringe any
patents or other property right claims or to contest validity of any
such claims; this section has the sole purpose of protecting the
integrity of the free software distribution system which is
implemented by public license practices. Many people have made
generous contributions to the wide range of software distributed
through that system in reliance on consistent application of that
system; it is up to the author/donor to decide if he or she is willing
to distribute software through any other system and a licensee cannot
impose that choice.
This section is intended to make thoroughly clear what is believed to
be a consequence of the rest of this License.
12.
If the distribution and/or use of the Library is restricted in
certain countries either by patents or by copyrighted interfaces, the
original copyright holder who places the Library under this License may add
an explicit geographical distribution limitation excluding those countries,
so that distribution is permitted only in or among countries not thus
excluded. In such case, this License incorporates the limitation as if
written in the body of this License.
13.
The Free Software Foundation may publish revised and/or new
versions of the Lesser General Public License from time to time.
Such new versions will be similar in spirit to the present version,
but may differ in detail to address new problems or concerns.
Each version is given a distinguishing version number. If the Library
specifies a version number of this License which applies to it and
``any later version'', you have the option of following the terms and
conditions either of that version or of any later version published by
the Free Software Foundation. If the Library does not specify a
license version number, you may choose any version ever published by
the Free Software Foundation.
14.
If you wish to incorporate parts of the Library into other free
programs whose distribution conditions are incompatible with these,
write to the author to ask for permission. For software which is
copyrighted by the Free Software Foundation, write to the Free
Software Foundation; we sometimes make exceptions for this. Our
decision will be guided by the two goals of preserving the free status
of all derivatives of our free software and of promoting the sharing
and reuse of software generally.
NO WARRANTY
15.
BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
OTHER PARTIES PROVIDE THE LIBRARY ``AS IS'' WITHOUT WARRANTY OF ANY
KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME
THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
16.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU
FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
DAMAGES.
END OF TERMS AND CONDITIONS
How to Apply These Terms to Your New Libraries
If you develop a new library, and you want it to be of the greatest
possible use to the public, we recommend making it free software that
everyone can redistribute and change. You can do so by permitting
redistribution under these terms (or, alternatively, under the terms of the
ordinary General Public License).
To apply these terms, attach the following notices to the library. It is
safest to attach them to the start of each source file to most effectively
convey the exclusion of warranty; and each file should have at least the
``copyright'' line and a pointer to where the full notice is found.
one line to give the library's name and an idea of what it does.
Copyright (C) year name of author
This library is free software; you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 2.1 of the License, or (at
your option) any later version.
This library is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307,
USA.
Also add information on how to contact you by electronic and paper mail.
You should also get your employer (if you work as a programmer) or your
school, if any, to sign a ``copyright disclaimer'' for the library, if
necessary. Here is a sample; alter the names:
Yoyodyne, Inc., hereby disclaims all copyright interest in the library
`Frob' (a library for tweaking knobs) written by James Random Hacker.
signature of Ty Coon, 1 April 1990
Ty Coon, President of Vice
That's all there is to it!
====================================================================================================
GNU Free Documentation License
Version 1.1, March 2000
Copyright @copyright{} 2000 Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA 02111-1307, USA
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
@end display
0.
PREAMBLE
The purpose of this License is to make a manual, textbook, or other
written document @dfn{free} in the sense of freedom: to assure everyone
the effective freedom to copy and redistribute it, with or without
modifying it, either commercially or noncommercially. Secondarily,
this License preserves for the author and publisher a way to get
credit for their work, while not being considered responsible for
modifications made by others.
This License is a kind of ``copyleft'', which means that derivative
works of the document must themselves be free in the same sense. It
complements the GNU General Public License, which is a copyleft
license designed for free software.
We have designed this License in order to use it for manuals for free
software, because free software needs free documentation: a free
program should come with manuals providing the same freedoms that the
software does. But this License is not limited to software manuals;
it can be used for any textual work, regardless of subject matter or
whether it is published as a printed book. We recommend this License
principally for works whose purpose is instruction or reference.
1.
APPLICABILITY AND DEFINITIONS
This License applies to any manual or other work that contains a
notice placed by the copyright holder saying it can be distributed
under the terms of this License. The ``Document'', below, refers to any
such manual or work. Any member of the public is a licensee, and is
addressed as ``you''.
A ``Modified Version'' of the Document means any work containing the
Document or a portion of it, either copied verbatim, or with
modifications and/or translated into another language.
A ``Secondary Section'' is a named appendix or a front-matter section of
the Document that deals exclusively with the relationship of the
publishers or authors of the Document to the Document's overall subject
(or to related matters) and contains nothing that could fall directly
within that overall subject. (For example, if the Document is in part a
textbook of mathematics, a Secondary Section may not explain any
mathematics.) The relationship could be a matter of historical
connection with the subject or with related matters, or of legal,
commercial, philosophical, ethical or political position regarding
them.
The ``Invariant Sections'' are certain Secondary Sections whose titles
are designated, as being those of Invariant Sections, in the notice
that says that the Document is released under this License.
The ``Cover Texts'' are certain short passages of text that are listed,
as Front-Cover Texts or Back-Cover Texts, in the notice that says that
the Document is released under this License.
A ``Transparent'' copy of the Document means a machine-readable copy,
represented in a format whose specification is available to the
general public, whose contents can be viewed and edited directly and
straightforwardly with generic text editors or (for images composed of
pixels) generic paint programs or (for drawings) some widely available
drawing editor, and that is suitable for input to text formatters or
for automatic translation to a variety of formats suitable for input
to text formatters. A copy made in an otherwise Transparent file
format whose markup has been designed to thwart or discourage
subsequent modification by readers is not Transparent. A copy that is
not ``Transparent'' is called ``Opaque''.
Examples of suitable formats for Transparent copies include plain
@sc{ascii} without markup, Texinfo input format, La@TeX{} input format,
@acronym{SGML} or @acronym{XML} using a publicly available
@acronym{DTD}, and standard-conforming simple @acronym{HTML} designed
for human modification. Opaque formats include PostScript,
@acronym{PDF}, proprietary formats that can be read and edited only by
proprietary word processors, @acronym{SGML} or @acronym{XML} for which
the @acronym{DTD} and/or processing tools are not generally available,
and the machine-generated @acronym{HTML} produced by some word
processors for output purposes only.
The ``Title Page'' means, for a printed book, the title page itself,
plus such following pages as are needed to hold, legibly, the material
this License requires to appear in the title page. For works in
formats which do not have any title page as such, ``Title Page'' means
the text near the most prominent appearance of the work's title,
preceding the beginning of the body of the text.
2.
VERBATIM COPYING
You may copy and distribute the Document in any medium, either
commercially or noncommercially, provided that this License, the
copyright notices, and the license notice saying this License applies
to the Document are reproduced in all copies, and that you add no other
conditions whatsoever to those of this License. You may not use
technical measures to obstruct or control the reading or further
copying of the copies you make or distribute. However, you may accept
compensation in exchange for copies. If you distribute a large enough
number of copies you must also follow the conditions in section 3.
You may also lend copies, under the same conditions stated above, and
you may publicly display copies.
3.
COPYING IN QUANTITY
If you publish printed copies of the Document numbering more than 100,
and the Document's license notice requires Cover Texts, you must enclose
the copies in covers that carry, clearly and legibly, all these Cover
Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
the back cover. Both covers must also clearly and legibly identify
you as the publisher of these copies. The front cover must present
the full title with all words of the title equally prominent and
visible. You may add other material on the covers in addition.
Copying with changes limited to the covers, as long as they preserve
the title of the Document and satisfy these conditions, can be treated
as verbatim copying in other respects.
If the required texts for either cover are too voluminous to fit
legibly, you should put the first ones listed (as many as fit
reasonably) on the actual cover, and continue the rest onto adjacent
pages.
If you publish or distribute Opaque copies of the Document numbering
more than 100, you must either include a machine-readable Transparent
copy along with each Opaque copy, or state in or with each Opaque copy
a publicly-accessible computer-network location containing a complete
Transparent copy of the Document, free of added material, which the
general network-using public has access to download anonymously at no
charge using public-standard network protocols. If you use the latter
option, you must take reasonably prudent steps, when you begin
distribution of Opaque copies in quantity, to ensure that this
Transparent copy will remain thus accessible at the stated location
until at least one year after the last time you distribute an Opaque
copy (directly or through your agents or retailers) of that edition to
the public.
It is requested, but not required, that you contact the authors of the
Document well before redistributing any large number of copies, to give
them a chance to provide you with an updated version of the Document.
4.
MODIFICATIONS
You may copy and distribute a Modified Version of the Document under
the conditions of sections 2 and 3 above, provided that you release
the Modified Version under precisely this License, with the Modified
Version filling the role of the Document, thus licensing distribution
and modification of the Modified Version to whoever possesses a copy
of it. In addition, you must do these things in the Modified Version:
A.
Use in the Title Page (and on the covers, if any) a title distinct
from that of the Document, and from those of previous versions
(which should, if there were any, be listed in the History section
of the Document). You may use the same title as a previous version
if the original publisher of that version gives permission.
B.
List on the Title Page, as authors, one or more persons or entities
responsible for authorship of the modifications in the Modified
Version, together with at least five of the principal authors of the
Document (all of its principal authors, if it has less than five).
C.
State on the Title page the name of the publisher of the
Modified Version, as the publisher.
D.
Preserve all the copyright notices of the Document.
E.
Add an appropriate copyright notice for your modifications
adjacent to the other copyright notices.
F.
Include, immediately after the copyright notices, a license notice
giving the public permission to use the Modified Version under the
terms of this License, in the form shown in the Addendum below.
G.
Preserve in that license notice the full lists of Invariant Sections
and required Cover Texts given in the Document's license notice.
H.
Include an unaltered copy of this License.
I.
Preserve the section entitled ``History'', and its title, and add to
it an item stating at least the title, year, new authors, and
publisher of the Modified Version as given on the Title Page. If
there is no section entitled ``History'' in the Document, create one
stating the title, year, authors, and publisher of the Document as
given on its Title Page, then add an item describing the Modified
Version as stated in the previous sentence.
J.
Preserve the network location, if any, given in the Document for
public access to a Transparent copy of the Document, and likewise
the network locations given in the Document for previous versions
it was based on. These may be placed in the ``History'' section.
You may omit a network location for a work that was published at
least four years before the Document itself, or if the original
publisher of the version it refers to gives permission.
K.
In any section entitled ``Acknowledgments'' or ``Dedications'',
preserve the section's title, and preserve in the section all the
substance and tone of each of the contributor acknowledgments
and/or dedications given therein.
L.
Preserve all the Invariant Sections of the Document,
unaltered in their text and in their titles. Section numbers
or the equivalent are not considered part of the section titles.
M.
Delete any section entitled ``Endorsements''. Such a section
may not be included in the Modified Version.
N.
Do not retitle any existing section as ``Endorsements''
or to conflict in title with any Invariant Section.
If the Modified Version includes new front-matter sections or
appendices that qualify as Secondary Sections and contain no material
copied from the Document, you may at your option designate some or all
of these sections as invariant. To do this, add their titles to the
list of Invariant Sections in the Modified Version's license notice.
These titles must be distinct from any other section titles.
You may add a section entitled ``Endorsements'', provided it contains
nothing but endorsements of your Modified Version by various
parties---for example, statements of peer review or that the text has
been approved by an organization as the authoritative definition of a
standard.
You may add a passage of up to five words as a Front-Cover Text, and a
passage of up to 25 words as a Back-Cover Text, to the end of the list
of Cover Texts in the Modified Version. Only one passage of
Front-Cover Text and one of Back-Cover Text may be added by (or
through arrangements made by) any one entity. If the Document already
includes a cover text for the same cover, previously added by you or
by arrangement made by the same entity you are acting on behalf of,
you may not add another; but you may replace the old one, on explicit
permission from the previous publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this License
give permission to use their names for publicity for or to assert or
imply endorsement of any Modified Version.
5.
COMBINING DOCUMENTS
You may combine the Document with other documents released under this
License, under the terms defined in section 4 above for modified
versions, provided that you include in the combination all of the
Invariant Sections of all of the original documents, unmodified, and
list them all as Invariant Sections of your combined work in its
license notice.
The combined work need only contain one copy of this License, and
multiple identical Invariant Sections may be replaced with a single
copy. If there are multiple Invariant Sections with the same name but
different contents, make the title of each such section unique by
adding at the end of it, in parentheses, the name of the original
author or publisher of that section if known, or else a unique number.
Make the same adjustment to the section titles in the list of
Invariant Sections in the license notice of the combined work.
In the combination, you must combine any sections entitled ``History''
in the various original documents, forming one section entitled
``History''; likewise combine any sections entitled ``Acknowledgments'',
and any sections entitled ``Dedications''. You must delete all sections
entitled ``Endorsements.''
6.
COLLECTIONS OF DOCUMENTS
You may make a collection consisting of the Document and other documents
released under this License, and replace the individual copies of this
License in the various documents with a single copy that is included in
the collection, provided that you follow the rules of this License for
verbatim copying of each of the documents in all other respects.
You may extract a single document from such a collection, and distribute
it individually under this License, provided you insert a copy of this
License into the extracted document, and follow this License in all
other respects regarding verbatim copying of that document.
7.
AGGREGATION WITH INDEPENDENT WORKS
A compilation of the Document or its derivatives with other separate
and independent documents or works, in or on a volume of a storage or
distribution medium, does not as a whole count as a Modified Version
of the Document, provided no compilation copyright is claimed for the
compilation. Such a compilation is called an ``aggregate'', and this
License does not apply to the other self-contained works thus compiled
with the Document, on account of their being thus compiled, if they
are not themselves derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these
copies of the Document, then if the Document is less than one quarter
of the entire aggregate, the Document's Cover Texts may be placed on
covers that surround only the Document within the aggregate.
Otherwise they must appear on covers around the whole aggregate.
8.
TRANSLATION
Translation is considered a kind of modification, so you may
distribute translations of the Document under the terms of section 4.
Replacing Invariant Sections with translations requires special
permission from their copyright holders, but you may include
translations of some or all Invariant Sections in addition to the
original versions of these Invariant Sections. You may include a
translation of this License provided that you also include the
original English version of this License. In case of a disagreement
between the translation and the original English version of this
License, the original English version will prevail.
9.
TERMINATION
You may not copy, modify, sublicense, or distribute the Document except
as expressly provided for under this License. Any other attempt to
copy, modify, sublicense or distribute the Document is void, and will
automatically terminate your rights under this License. However,
parties who have received copies, or rights, from you under this
License will not have their licenses terminated so long as such
parties remain in full compliance.
10.
FUTURE REVISIONS OF THIS LICENSE
The Free Software Foundation may publish new, revised versions
of the GNU Free Documentation License from time to time. Such new
versions will be similar in spirit to the present version, but may
differ in detail to address new problems or concerns. See
@uref{http://www.gnu.org/copyleft/}.
Each version of the License is given a distinguishing version number.
If the Document specifies that a particular numbered version of this
License ``or any later version'' applies to it, you have the option of
following the terms and conditions either of that specified version or
of any later version that has been published (not as a draft) by the
Free Software Foundation. If the Document does not specify a version
number of this License, you may choose any version ever published (not
as a draft) by the Free Software Foundation.
@end enumerate
ADDENDUM: How to use this License for your documents
To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and
license notices just after the title page:
Copyright (C) year your name.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1
or any later version published by the Free Software Foundation;
with the Invariant Sections being @var{list their titles}, with the
Front-Cover Texts being @var{list}, and with the Back-Cover Texts being @var{list}.
A copy of the license is included in the section entitled ``GNU
Free Documentation License''.
If you have no Invariant Sections, write ``with no Invariant Sections''
instead of saying which ones are invariant. If you have no
Front-Cover Texts, write ``no Front-Cover Texts'' instead of
``Front-Cover Texts being @var{list}''; likewise for Back-Cover Texts.
If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of
free software license, such as the GNU General Public License,
to permit their use in free software.
========================================================================================
A transparent copy of this modified document can be found along-side the binary .libhover file
in the org.eclipse.cdt.libhover.glibc plug-in jar under the data directory. The plug-in can be
unzipped via "unzip". The original un-modified document can be generated from the sources which
can be found at: http://ftp.gnu.org/gnu/glibc/glibc-2.14.tar.gz
srjava.util.ArrayListx�Ò™Ça�Isizexpwxq~ ptvoidt
DES_FAILEDsq~
t¤
This macro returns 1 if <VAR>err</VAR> is a `success' result code from
<CODE>ecb_crypt</CODE> or <CODE>cbc_crypt</CODE>, and 0 otherwise.
sq~wtrpc/des_crypt.hxq~tint errtintt_Exitsq~
t‰
The <CODE>_Exit</CODE> function is the ISO C equivalent to <CODE>_exit</CODE>.
The ISO C committee members were not sure whether the definitions of
<CODE>_exit</CODE> and <CODE>_Exit</CODE> were compatible so they have not used the
POSIX name.
<br><br> This function was introduced in ISO C99 and is declared in
<TT>stdlib.h</TT>.
sq~wtstdlib.hxq~t
int statustvoidt
__fbufsizesq~
t
The <CODE>__fbufsize</CODE> function return the size of the buffer in the
stream <VAR>stream</VAR>. This value can be used to optimize the use of the
stream.
<br><br> This function is declared in the <TT>stdio_ext.h</TT> header.
sq~wt stdio_ext.hxq~ t FILE *streamtsize_tt__flbfsq~
t
The <CODE>__flbf</CODE> function will return a nonzero value in case the
stream <VAR>stream</VAR> is line buffered. Otherwise the return value is
zero.
<br><br> This function is declared in the <TT>stdio_ext.h</TT> header.
sq~wt stdio_ext.hxq~'t FILE *streamtintt
__fpendingsq~
tG
function returns the number of bytes currently in the output buffer.
For wide-oriented stream the measuring unit is wide characters. This
function should not be used on buffers in read mode or opened read-only.
<br><br> This function is declared in the <TT>stdio_ext.h</TT> header.
sq~wt stdio_ext.hxq~.t FILE *streamtsize_tt__fpurgesq~
t½
The <CODE>__fpurge</CODE> function causes the buffer of the stream
<VAR>stream</VAR> to be emptied. If the stream is currently in read mode all
input in the buffer is lost. If the stream is in output mode the
buffered output is not written to the device (or whatever other
underlying storage) and the buffer the cleared.
<br><br> This function is declared in <TT>stdio_ext.h</TT>.
sq~wt stdio_ext.hxq~5t FILE *streamtvoidt __freadablesq~
t9
The <CODE>__freadable</CODE> function determines whether the stream
<VAR>stream</VAR> was opened to allow reading. In this case the return value
is nonzero. For write-only streams the function returns zero.
<br><br> This function is declared in <TT>stdio_ext.h</TT>.
sq~wt stdio_ext.hxq~<t FILE *streamtintt
__freadingsq~
tø
The <CODE>__freading</CODE> function determines whether the stream
<VAR>stream</VAR> was last read from or whether it is opened read-only. In
this case the return value is nonzero, otherwise it is zero.
Determining whether a stream opened for reading and writing was last
used for writing allows to draw conclusions about the content about the
buffer, among other things.
<br><br> This function is declared in <TT>stdio_ext.h</TT>.
sq~wt stdio_ext.hxq~Ct FILE *streamtintt
__fsetlockingsq~
tu
<br><br> The <CODE>__fsetlocking</CODE> function can be used to select whether the
stream operations will implicitly acquire the locking object of the
stream <VAR>stream</VAR>. By default this is done but it can be disabled and
reinstated using this function. There are three values defined for the
<VAR>type</VAR> parameter.
<br><br> <DL>
<DT><CODE>FSETLOCKING_INTERNAL</CODE>
<DD>
The stream <CODE>stream</CODE> will from now on use the default internal
locking. Every stream operation with exception of the <CODE>_unlocked</CODE>
variants will implicitly lock the stream.
<br><br> <DT><CODE>FSETLOCKING_BYCALLER</CODE>
<DD>
After the <CODE>__fsetlocking</CODE> function returns the user is responsible
for locking the stream. None of the stream operations will implicitly
do this anymore until the state is set back to
<CODE>FSETLOCKING_INTERNAL</CODE>.
<br><br> <DT><CODE>FSETLOCKING_QUERY</CODE>
<DD>
<CODE>__fsetlocking</CODE> only queries the current locking state of the
stream. The return value will be <CODE>FSETLOCKING_INTERNAL</CODE> or
<CODE>FSETLOCKING_BYCALLER</CODE> depending on the state.
</DL>
<br><br> The return value of <CODE>__fsetlocking</CODE> is either
<CODE>FSETLOCKING_INTERNAL</CODE> or <CODE>FSETLOCKING_BYCALLER</CODE> depending on
the state of the stream before the call.
<br><br> This function and the values for the <VAR>type</VAR> parameter are declared
in <TT>stdio_ext.h</TT>.
sq~wt stdio_ext.hxq~JtFILE *stream, int typetintt __fwritablesq~
t8
The <CODE>__fwritable</CODE> function determines whether the stream
<VAR>stream</VAR> was opened to allow writing. In this case the return value
is nonzero. For read-only streams the function returns zero.
<br><br> This function is declared in <TT>stdio_ext.h</TT>.
sq~wt stdio_ext.hxq~Qt FILE *streamtintt
__fwritingsq~
t6
The <CODE>__fwriting</CODE> function determines whether the stream
<VAR>stream</VAR> was last written to or whether it is opened write-only. In
this case the return value is nonzero, otherwise it is zero.
<br><br> This function is declared in <TT>stdio_ext.h</TT>.
sq~wt stdio_ext.hxq~Xt FILE *streamtintt_exitsq~
t
The <CODE>_exit</CODE> function is the primitive for causing a process to
terminate with status <VAR>status</VAR>. Calling this function does not
execute cleanup functions registered with <CODE>atexit</CODE> or
<CODE>on_exit</CODE>.
sq~wtunistd.hxq~_t
int statustvoidt _flushlbfsq~
tÂ
The <CODE>_flushlbf</CODE> function flushes all line buffered streams
currently opened.
<br><br> This function is declared in the <TT>stdio_ext.h</TT> header.
sq~wt stdio_ext.hxq~ftvoidtvoidt_tolowersq~
ty
This is identical to <CODE>tolower</CODE>, and is provided for compatibility
with the SVID. .
sq~wtctype.hxq~mtint ctintt_touppersq~
tv
This is identical to <CODE>toupper</CODE>, and is provided for compatibility
with the SVID.
sq~wtctype.hxq~ttint ctintta64lsq~
tN
The parameter <VAR>string</VAR> should contain a string which was produced by
a call to <CODE>l64a</CODE>. The function processes at least 6 characters of
this string, and decodes the characters it finds according to the table
below. It stops decoding when it finds a character not in the table,
rather like <CODE>atoi</CODE>; if you have a buffer which has been broken into
lines, you must be careful to skip over the end-of-line characters.
<br><br> The decoded number is returned as a <CODE>long int</CODE> value.
sq~wtstdlib.hxq~{tconst char *stringtlong inttabortsq~
t 
The <CODE>abort</CODE> function causes abnormal program termination. This
does not execute cleanup functions registered with <CODE>atexit</CODE> or
<CODE>on_exit</CODE>.
<br><br> This function actually terminates the process by raising a
<CODE>SIGABRT</CODE> signal, and your program can include a handler to
intercept this signal; see Signal Handling.
sq~wtstdlib.hxq~‚tvoidtvoidtabssq~
t
These functions return the absolute value of <VAR>number</VAR>.
<br><br> Most computers use a two's complement integer representation, in which
the absolute value of <CODE>INT_MIN</CODE> (the smallest possible <CODE>int</CODE>)
cannot be represented; thus, <CODE>abs (INT_MIN)</CODE> is not defined.
<br><br> <CODE>llabs</CODE> and <CODE>imaxdiv</CODE> are new to ISO C99.
<br><br> See Integers for a description of the <CODE>intmax_t</CODE> type.
<br><br>
sq~wtstdlib.hxq~‰t
int numbertinttacceptsq~
tµ
This function is used to accept a connection request on the server
socket <VAR>socket</VAR>.
<br><br> The <CODE>accept</CODE> function waits if there are no connections pending,
unless the socket <VAR>socket</VAR> has nonblocking mode set. (You can use
<CODE>select</CODE> to wait for a pending connection, with a nonblocking
socket.) , for information about nonblocking
mode.
<br><br> The <VAR>addr</VAR> and <VAR>length-ptr</VAR> arguments are used to return
information about the name of the client socket that initiated the
connection. , for information about the format
of the information.
<br><br> Accepting a connection does not make <VAR>socket</VAR> part of the
connection. Instead, it creates a new socket which becomes
connected. The normal return value of <CODE>accept</CODE> is the file
descriptor for the new socket.
<br><br> After <CODE>accept</CODE>, the original socket <VAR>socket</VAR> remains open and
unconnected, and continues listening until you close it. You can
accept further connections with <VAR>socket</VAR> by calling <CODE>accept</CODE>
again.
<br><br> If an error occurs, <CODE>accept</CODE> returns <CODE>-1</CODE>. The following
<CODE>errno</CODE> error conditions are defined for this function:
<br><br> <DL>
<DT><CODE>EBADF</CODE>
<DD>
The <VAR>socket</VAR> argument is not a valid file descriptor.
<br><br> <LI> ENOTSOCK
The descriptor <VAR>socket</VAR> argument is not a socket.
<br><br> <LI> EOPNOTSUPP
The descriptor <VAR>socket</VAR> does not support this operation.
<br><br> <LI> EWOULDBLOCK
<VAR>socket</VAR> has nonblocking mode set, and there are no pending
connections immediately available.
<br><br> This function is defined as a cancellation point in multi-threaded
programs, so one has to be prepared for this and make sure that
allocated resources (like memory, files descriptors, semaphores or
whatever) are freed even if the thread is canceled.
sq~wt sys/socket.hxq~�t8int socket, struct sockaddr *addr, socklen_t *length_ptrtinttaccesssq~
t¸
The <CODE>access</CODE> function checks to see whether the file named by
<VAR>filename</VAR> can be accessed in the way specified by the <VAR>how</VAR>
argument. The <VAR>how</VAR> argument either can be the bitwise OR of the
flags <CODE>R_OK</CODE>, <CODE>W_OK</CODE>, <CODE>X_OK</CODE>, or the existence test
<CODE>F_OK</CODE>.
<br><br> This function uses the <EM>real</EM> user and group IDs of the calling
process, rather than the <EM>effective</EM> IDs, to check for access
permission. As a result, if you use the function from a <CODE>setuid</CODE>
or <CODE>setgid</CODE> program , it gives
information relative to the user who actually ran the program.
<br><br> The return value is <CODE>0</CODE> if the access is permitted, and <CODE>-1</CODE>
otherwise. (In other words, treated as a predicate function,
<CODE>access</CODE> returns true if the requested access is <EM>denied</EM>.)
<br><br> In addition to the usual file name errors , the following <CODE>errno</CODE> error conditions are defined for
this function:
<br><br> <DL>
<DT><CODE>EACCES</CODE>
<DD>
The access specified by <VAR>how</VAR> is denied.
<br><br> <LI> ENOENT
The file doesn't exist.
<br><br> <LI> EROFS
Write permission was requested for a file on a read-only file system.
sq~wtunistd.hxq~—tconst char *filename, int howtinttacossq~
t-
These functions compute the arc cosine of <VAR>x</VAR>---that is, the value
whose cosine is <VAR>x</VAR>. The value is in units of radians.
Mathematically, there are infinitely many such values; the one actually
returned is the one between <CODE>0</CODE> and <CODE>pi</CODE> (inclusive).
<br><br> The arc cosine function is defined mathematically only
over the domain <CODE>-1</CODE> to <CODE>1</CODE>. If <VAR>x</VAR> is outside the
domain, <CODE>acos</CODE> signals a domain error.
sq~wtmath.hxq~žtdouble xtdoubletacosfsq~
t-
These functions compute the arc cosine of <VAR>x</VAR>---that is, the value
whose cosine is <VAR>x</VAR>. The value is in units of radians.
Mathematically, there are infinitely many such values; the one actually
returned is the one between <CODE>0</CODE> and <CODE>pi</CODE> (inclusive).
<br><br> The arc cosine function is defined mathematically only
over the domain <CODE>-1</CODE> to <CODE>1</CODE>. If <VAR>x</VAR> is outside the
domain, <CODE>acos</CODE> signals a domain error.
sq~wtmath.hxq~¥tfloat xtfloattacoshsq~
tö
These functions return the inverse hyperbolic cosine of <VAR>x</VAR>---the
value whose hyperbolic cosine is <VAR>x</VAR>. If <VAR>x</VAR> is less than
<CODE>1</CODE>, <CODE>acosh</CODE> signals a domain error.
sq~wtmath.hxq~¬tdouble xtdoubletacoshfsq~
tö
These functions return the inverse hyperbolic cosine of <VAR>x</VAR>---the
value whose hyperbolic cosine is <VAR>x</VAR>. If <VAR>x</VAR> is less than
<CODE>1</CODE>, <CODE>acosh</CODE> signals a domain error.
sq~wtmath.hxq~³tfloat xtfloattacoshlsq~
tö
These functions return the inverse hyperbolic cosine of <VAR>x</VAR>---the
value whose hyperbolic cosine is <VAR>x</VAR>. If <VAR>x</VAR> is less than
<CODE>1</CODE>, <CODE>acosh</CODE> signals a domain error.
sq~wtmath.hxq~ºt
long double xt long doubletacoslsq~
t-
These functions compute the arc cosine of <VAR>x</VAR>---that is, the value
whose cosine is <VAR>x</VAR>. The value is in units of radians.
Mathematically, there are infinitely many such values; the one actually
returned is the one between <CODE>0</CODE> and <CODE>pi</CODE> (inclusive).
<br><br> The arc cosine function is defined mathematically only
over the domain <CODE>-1</CODE> to <CODE>1</CODE>. If <VAR>x</VAR> is outside the
domain, <CODE>acos</CODE> signals a domain error.
sq~wtmath.hxq~Át
long double xt long doublet addmntentsq~
t.
The <CODE>addmntent</CODE> function allows adding a new entry to the file
previously opened with <CODE>setmntent</CODE>. The new entries are always
appended. I.e., even if the position of the file descriptor is not at
the end of the file this function does not overwrite an existing entry
following the current position.
<br><br> The implication of this is that to remove an entry from a file one has
to create a new file while leaving out the entry to be removed and after
closing the file remove the old one and rename the new file to the
chosen name.
<br><br> This function takes care of spaces and tab characters in the names to be
written to the file. It converts them and the backslash character into
the format describe in the <CODE>getmntent</CODE> description above.
<br><br> This function returns 0 in case the operation was successful.
Otherwise the return value is 1 and <CODE>errno</CODE> is set
appropriately.
sq~wtmntent.hxq~Èt&FILE *stream, const struct mntent *mnttintt addseveritysq~
t/
This function allows the introduction of new severity classes which can be
addressed by the <VAR>severity</VAR> parameter of the <CODE>fmtmsg</CODE> function.
The <VAR>severity</VAR> parameter of <CODE>addseverity</CODE> must match the value
for the parameter with the same name of <CODE>fmtmsg</CODE>, and <VAR>string</VAR>
is the string printed in the actual messages instead of the numeric
value.
<br><br> If <VAR>string</VAR> is <CODE>NULL</CODE> the severity class with the numeric value
according to <VAR>severity</VAR> is removed.
<br><br> It is not possible to overwrite or remove one of the default severity
classes. All calls to <CODE>addseverity</CODE> with <VAR>severity</VAR> set to one
of the values for the default classes will fail.
<br><br> The return value is <CODE>MM_OK</CODE> if the task was successfully performed.
If the return value is <CODE>MM_NOTOK</CODE> something went wrong. This could
mean that no more memory is available or a class is not available when
it has to be removed.
<br><br> This function is not specified in the X/Open Portability Guide although
the <CODE>fmtsmg</CODE> function is. It is available on System V systems.
sq~wxq~Ït int severity, const char *stringtinttadjtimesq~
tp
This function speeds up or slows down the system clock in order to make
a gradual adjustment. This ensures that the calendar time reported by
the system clock is always monotonically increasing, which might not
happen if you simply set the clock.
<br><br> The <VAR>delta</VAR> argument specifies a relative adjustment to be made to
the clock time. If negative, the system clock is slowed down for a
while until it has lost this much elapsed time. If positive, the system
clock is speeded up for a while.
<br><br> If the <VAR>olddelta</VAR> argument is not a null pointer, the <CODE>adjtime</CODE>
function returns information about any previous time adjustment that
has not yet completed.
<br><br> This function is typically used to synchronize the clocks of computers
in a local network. You must be a privileged user to use it.
<br><br> With a Linux kernel, you can use the <CODE>adjtimex</CODE> function to
permanently change the clock speed.
<br><br> The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on failure. The
following <CODE>errno</CODE> error condition is defined for this function:
<br><br> <DL>
<DT><CODE>EPERM</CODE>
<DD>
You do not have privilege to set the time.
sq~wt
sys/time.hxq~Õt5const struct timeval *delta, struct timeval *olddeltatinttadjtimexsq~
tÉ
<br><br> <CODE>adjtimex</CODE> is functionally identical to <CODE>ntp_adjtime</CODE>.
.
<br><br> This function is present only with a Linux kernel.
<br><br>
sq~wt sys/timex.hxq~Ütstruct timex *timextintt
aio_cancelsq~
t
+
The <CODE>aio_cancel</CODE> function can be used to cancel one or more
outstanding requests. If the <VAR>aiocbp</VAR> parameter is <CODE>NULL</CODE>, the
function tries to cancel all of the outstanding requests which would process
the file descriptor <VAR>fildes</VAR> (i.e., whose <CODE>aio_fildes</CODE> member
is <VAR>fildes</VAR>). If <VAR>aiocbp</VAR> is not <CODE>NULL</CODE>, <CODE>aio_cancel</CODE>
attempts to cancel the specific request pointed to by <VAR>aiocbp</VAR>.
<br><br> For requests which were successfully canceled, the normal notification
about the termination of the request should take place. I.e., depending
on the <CODE>struct sigevent</CODE> object which controls this, nothing
happens, a signal is sent or a thread is started. If the request cannot
be canceled, it terminates the usual way after performing the operation.
<br><br> After a request is successfully canceled, a call to <CODE>aio_error</CODE> with
a reference to this request as the parameter will return
<CODE>ECANCELED</CODE> and a call to <CODE>aio_return</CODE> will return -1.
If the request wasn't canceled and is still running the error status is
still <CODE>EINPROGRESS</CODE>.
<br><br> The return value of the function is <CODE>AIO_CANCELED</CODE> if there were
requests which haven't terminated and which were successfully canceled.
If there is one or more requests left which couldn't be canceled, the
return value is <CODE>AIO_NOTCANCELED</CODE>. In this case <CODE>aio_error</CODE>
must be used to find out which of the, perhaps multiple, requests (in
<VAR>aiocbp</VAR> is <CODE>NULL</CODE>) weren't successfully canceled. If all
requests already terminated at the time <CODE>aio_cancel</CODE> is called the
return value is <CODE>AIO_ALLDONE</CODE>.
<br><br> If an error occurred during the execution of <CODE>aio_cancel</CODE> the
function returns -1 and sets <CODE>errno</CODE> to one of the following
values.
<br><br> <DL>
<DT><CODE>EBADF</CODE>
<DD>
The file descriptor <VAR>fildes</VAR> is not valid.
<LI> ENOSYS
<CODE>aio_cancel</CODE> is not implemented.
<br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE>, this
function is in fact <CODE>aio_cancel64</CODE> since the LFS interface
transparently replaces the normal implementation.
sq~wtaio.hxq~ãt int fildes, struct aiocb *aiocbptintt aio_cancel64sq~
tÌ
This function is similar to <CODE>aio_cancel</CODE> with the only difference
that the argument is a reference to a variable of type <CODE>struct
aiocb64</CODE>.
<br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE>, this
function is available under the name <CODE>aio_cancel</CODE> and so
transparently replaces the interface for small files on 32 bit
machines.
sq~wtaio.hxq~êt"int fildes, struct aiocb64 *aiocbptintt aio_errorsq~
ta
This function determines the error state of the request described by the
<CODE>struct aiocb</CODE> variable pointed to by <VAR>aiocbp</VAR>. If the
request has not yet terminated the value returned is always
<CODE>EINPROGRESS</CODE>. Once the request has terminated the value
<CODE>aio_error</CODE> returns is either 0 if the request completed
successfully or it returns the value which would be stored in the
<CODE>errno</CODE> variable if the request would have been done using
<CODE>read</CODE>, <CODE>write</CODE>, or <CODE>fsync</CODE>.
<br><br> The function can return <CODE>ENOSYS</CODE> if it is not implemented. It
could also return <CODE>EINVAL</CODE> if the <VAR>aiocbp</VAR> parameter does not
refer to an asynchronous operation whose return status is not yet known.
<br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> this
function is in fact <CODE>aio_error64</CODE> since the LFS interface
transparently replaces the normal implementation.
sq~wtaio.hxq~ñtconst struct aiocb *aiocbptintt aio_error64sq~
tÉ
This function is similar to <CODE>aio_error</CODE> with the only difference
that the argument is a reference to a variable of type <CODE>struct
aiocb64</CODE>.
<br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> this
function is available under the name <CODE>aio_error</CODE> and so
transparently replaces the interface for small files on 32 bit
machines.
sq~wtaio.hxq~øtconst struct aiocb64 *aiocbptintt aio_fsyncsq~
t ð
Calling this function forces all I/O operations operating queued at the
time of the function call operating on the file descriptor
<CODE>aiocbp->aio_fildes</CODE> into the synchronized I/O completion state
. The <CODE>aio_fsync</CODE> function returns
immediately but the notification through the method described in
<CODE>aiocbp->aio_sigevent</CODE> will happen only after all requests for this
file descriptor have terminated and the file is synchronized. This also
means that requests for this very same file descriptor which are queued
after the synchronization request are not affected.
<br><br> If <VAR>op</VAR> is <CODE>O_DSYNC</CODE> the synchronization happens as with a call
to <CODE>fdatasync</CODE>. Otherwise <VAR>op</VAR> should be <CODE>O_SYNC</CODE> and
the synchronization happens as with <CODE>fsync</CODE>.
<br><br> As long as the synchronization has not happened, a call to
<CODE>aio_error</CODE> with the reference to the object pointed to by
<VAR>aiocbp</VAR> returns <CODE>EINPROGRESS</CODE>. Once the synchronization is
done <CODE>aio_error</CODE> return 0 if the synchronization was not
successful. Otherwise the value returned is the value to which the
<CODE>fsync</CODE> or <CODE>fdatasync</CODE> function would have set the
<CODE>errno</CODE> variable. In this case nothing can be assumed about the
consistency for the data written to this file descriptor.
<br><br> The return value of this function is 0 if the request was
successfully enqueued. Otherwise the return value is -1 and
<CODE>errno</CODE> is set to one of the following values:
<br><br> <DL>
<DT><CODE>EAGAIN</CODE>
<DD>
The request could not be enqueued due to temporary lack of resources.
<LI> EBADF
The file descriptor <CODE>aiocbp->aio_fildes</CODE> is not valid or not open
for writing.
<LI> EINVAL
The implementation does not support I/O synchronization or the <VAR>op</VAR>
parameter is other than <CODE>O_DSYNC</CODE> and <CODE>O_SYNC</CODE>.
<LI> ENOSYS
This function is not implemented.
<br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> this
function is in fact <CODE>aio_fsync64</CODE> since the LFS interface
transparently replaces the normal implementation.
sq~wtaio.hxq~ÿtint op, struct aiocb *aiocbptintt aio_fsync64sq~
tÉ
This function is similar to <CODE>aio_fsync</CODE> with the only difference
that the argument is a reference to a variable of type <CODE>struct
aiocb64</CODE>.
<br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> this
function is available under the name <CODE>aio_fsync</CODE> and so
transparently replaces the interface for small files on 32 bit
machines.
sq~wtaio.hxq~tint op, struct aiocb64 *aiocbptinttaio_initsq~
të
This function must be called before any other AIO function. Calling it
is completely voluntary, as it is only meant to help the AIO
implementation perform better.
<br><br> Before calling the <CODE>aio_init</CODE>, function the members of a variable of
type <CODE>struct aioinit</CODE> must be initialized. Then a reference to
this variable is passed as the parameter to <CODE>aio_init</CODE> which itself
may or may not pay attention to the hints.
<br><br> The function has no return value and no error cases are defined. It is
a extension which follows a proposal from the SGI implementation in
Irix 6. It is not covered by POSIX.1b or Unix98.
sq~wtaio.hxq~
tconst struct aioinit *inittvoidtaio_readsq~
t ‘
This function initiates an asynchronous read operation. It
immediately returns after the operation was enqueued or when an
error was encountered.
<br><br> The first <CODE>aiocbp->aio_nbytes</CODE> bytes of the file for which
<CODE>aiocbp->aio_fildes</CODE> is a descriptor are written to the buffer
starting at <CODE>aiocbp->aio_buf</CODE>. Reading starts at the absolute
position <CODE>aiocbp->aio_offset</CODE> in the file.
<br><br> If prioritized I/O is supported by the platform the
<CODE>aiocbp->aio_reqprio</CODE> value is used to adjust the priority before
the request is actually enqueued.
<br><br> The calling process is notified about the termination of the read
request according to the <CODE>aiocbp->aio_sigevent</CODE> value.
<br><br> When <CODE>aio_read</CODE> returns, the return value is zero if no error
occurred that can be found before the process is enqueued. If such an
early error is found, the function returns -1 and sets
<CODE>errno</CODE> to one of the following values:
<br><br> <DL>
<DT><CODE>EAGAIN</CODE>
<DD>
The request was not enqueued due to (temporarily) exceeded resource
limitations.
<DT><CODE>ENOSYS</CODE>
<DD>
The <CODE>aio_read</CODE> function is not implemented.
<LI> EBADF
The <CODE>aiocbp->aio_fildes</CODE> descriptor is not valid. This condition
need not be recognized before enqueueing the request and so this error
might also be signaled asynchronously.
<LI> EINVAL
The <CODE>aiocbp->aio_offset</CODE> or <CODE>aiocbp->aio_reqpiro</CODE> value is
invalid. This condition need not be recognized before enqueueing the
request and so this error might also be signaled asynchronously.
<br><br> If <CODE>aio_read</CODE> returns zero, the current status of the request
can be queried using <CODE>aio_error</CODE> and <CODE>aio_return</CODE> functions.
As long as the value returned by <CODE>aio_error</CODE> is <CODE>EINPROGRESS</CODE>
the operation has not yet completed. If <CODE>aio_error</CODE> returns zero,
the operation successfully terminated, otherwise the value is to be
interpreted as an error code. If the function terminated, the result of
the operation can be obtained using a call to <CODE>aio_return</CODE>. The
returned value is the same as an equivalent call to <CODE>read</CODE> would
have returned. Possible error codes returned by <CODE>aio_error</CODE> are:
<br><br> <DL>
<LI> EBADF
The <CODE>aiocbp->aio_fildes</CODE> descriptor is not valid.
<LI> ECANCELED
The operation was canceled before the operation was finished
<LI> EINVAL
The <CODE>aiocbp->aio_offset</CODE> value is invalid.
<br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> this
function is in fact <CODE>aio_read64</CODE> since the LFS interface transparently
replaces the normal implementation.
sq~wtaio.hxq~tstruct aiocb *aiocbptintt
aio_read64sq~
tÅ
This function is similar to the <CODE>aio_read</CODE> function. The only
difference is that on 32 bit machines, the file descriptor should
be opened in the large file mode. Internally, <CODE>aio_read64</CODE> uses
functionality equivalent to <CODE>lseek64</CODE> to position the file descriptor correctly for the reading,
as opposed to <CODE>lseek</CODE> functionality used in <CODE>aio_read</CODE>.
<br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE>, this
function is available under the name <CODE>aio_read</CODE> and so transparently
replaces the interface for small files on 32 bit machines.
sq~wtaio.hxq~tstruct aiocb *aiocbptintt
aio_returnsq~
t°
This function can be used to retrieve the return status of the operation
carried out by the request described in the variable pointed to by
<VAR>aiocbp</VAR>. As long as the error status of this request as returned
by <CODE>aio_error</CODE> is <CODE>EINPROGRESS</CODE> the return of this function is
undefined.
<br><br> Once the request is finished this function can be used exactly once to
retrieve the return value. Following calls might lead to undefined
behavior. The return value itself is the value which would have been
returned by the <CODE>read</CODE>, <CODE>write</CODE>, or <CODE>fsync</CODE> call.
<br><br> The function can return <CODE>ENOSYS</CODE> if it is not implemented. It
could also return <CODE>EINVAL</CODE> if the <VAR>aiocbp</VAR> parameter does not
refer to an asynchronous operation whose return status is not yet known.
<br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> this
function is in fact <CODE>aio_return64</CODE> since the LFS interface
transparently replaces the normal implementation.
sq~wtaio.hxq~"tconst struct aiocb *aiocbptssize_tt aio_return64sq~
tË
This function is similar to <CODE>aio_return</CODE> with the only difference
that the argument is a reference to a variable of type <CODE>struct
aiocb64</CODE>.
<br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> this
function is available under the name <CODE>aio_return</CODE> and so
transparently replaces the interface for small files on 32 bit
machines.
sq~wtaio.hxq~)tconst struct aiocb64 *aiocbptintt aio_suspendsq~
t³
When calling this function, the calling thread is suspended until at
least one of the requests pointed to by the <VAR>nent</VAR> elements of the
array <VAR>list</VAR> has completed. If any of the requests has already
completed at the time <CODE>aio_suspend</CODE> is called, the function returns
immediately. Whether a request has terminated or not is determined by
comparing the error status of the request with <CODE>EINPROGRESS</CODE>. If
an element of <VAR>list</VAR> is <CODE>NULL</CODE>, the entry is simply ignored.
<br><br> If no request has finished, the calling process is suspended. If
<VAR>timeout</VAR> is <CODE>NULL</CODE>, the process is not woken until a request
has finished. If <VAR>timeout</VAR> is not <CODE>NULL</CODE>, the process remains
suspended at least as long as specified in <VAR>timeout</VAR>. In this case,
<CODE>aio_suspend</CODE> returns with an error.
<br><br> The return value of the function is 0 if one or more requests
from the <VAR>list</VAR> have terminated. Otherwise the function returns
-1 and <CODE>errno</CODE> is set to one of the following values:
<br><br> <DL>
<DT><CODE>EAGAIN</CODE>
<DD>
None of the requests from the <VAR>list</VAR> completed in the time specified
by <VAR>timeout</VAR>.
<LI> EINTR
A signal interrupted the <CODE>aio_suspend</CODE> function. This signal might
also be sent by the AIO implementation while signalling the termination
of one of the requests.
<LI> ENOSYS
The <CODE>aio_suspend</CODE> function is not implemented.
<br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> this
function is in fact <CODE>aio_suspend64</CODE> since the LFS interface
transparently replaces the normal implementation.
sq~wtaio.hxq~0tJconst struct aiocb *const list[], int nent, const struct timespec *timeouttintt
aio_suspend64sq~
tÍ
This function is similar to <CODE>aio_suspend</CODE> with the only difference
that the argument is a reference to a variable of type <CODE>struct
aiocb64</CODE>.
<br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> this
function is available under the name <CODE>aio_suspend</CODE> and so
transparently replaces the interface for small files on 32 bit
machines.
sq~wtaio.hxq~7tLconst struct aiocb64 *const list[], int nent, const struct timespec *timeouttintt aio_writesq~
t Â
This function initiates an asynchronous write operation. The function
call immediately returns after the operation was enqueued or if before
this happens an error was encountered.
<br><br> The first <CODE>aiocbp->aio_nbytes</CODE> bytes from the buffer starting at
<CODE>aiocbp->aio_buf</CODE> are written to the file for which
<CODE>aiocbp->aio_fildes</CODE> is an descriptor, starting at the absolute
position <CODE>aiocbp->aio_offset</CODE> in the file.
<br><br> If prioritized I/O is supported by the platform, the
<CODE>aiocbp->aio_reqprio</CODE> value is used to adjust the priority before
the request is actually enqueued.
<br><br> The calling process is notified about the termination of the read
request according to the <CODE>aiocbp->aio_sigevent</CODE> value.
<br><br> When <CODE>aio_write</CODE> returns, the return value is zero if no error
occurred that can be found before the process is enqueued. If such an
early error is found the function returns -1 and sets
<CODE>errno</CODE> to one of the following values.
<br><br> <DL>
<DT><CODE>EAGAIN</CODE>
<DD>
The request was not enqueued due to (temporarily) exceeded resource
limitations.
<DT><CODE>ENOSYS</CODE>
<DD>
The <CODE>aio_write</CODE> function is not implemented.
<LI> EBADF
The <CODE>aiocbp->aio_fildes</CODE> descriptor is not valid. This condition
may not be recognized before enqueueing the request, and so this error
might also be signaled asynchronously.
<LI> EINVAL
The <CODE>aiocbp->aio_offset</CODE> or <CODE>aiocbp->aio_reqprio</CODE> value is
invalid. This condition may not be recognized before enqueueing the
request and so this error might also be signaled asynchronously.
<br><br> In the case <CODE>aio_write</CODE> returns zero, the current status of the
request can be queried using <CODE>aio_error</CODE> and <CODE>aio_return</CODE>
functions. As long as the value returned by <CODE>aio_error</CODE> is
<CODE>EINPROGRESS</CODE> the operation has not yet completed. If
<CODE>aio_error</CODE> returns zero, the operation successfully terminated,
otherwise the value is to be interpreted as an error code. If the
function terminated, the result of the operation can be get using a call
to <CODE>aio_return</CODE>. The returned value is the same as an equivalent
call to <CODE>read</CODE> would have returned. Possible error codes returned
by <CODE>aio_error</CODE> are:
<br><br> <DL>
<LI> EBADF
The <CODE>aiocbp->aio_fildes</CODE> descriptor is not valid.
<LI> ECANCELED
The operation was canceled before the operation was finished.
<LI> EINVAL
The <CODE>aiocbp->aio_offset</CODE> value is invalid.
<br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE>, this
function is in fact <CODE>aio_write64</CODE> since the LFS interface transparently
replaces the normal implementation.
sq~wtaio.hxq~>tstruct aiocb *aiocbptintt aio_write64sq~
tÇ
This function is similar to the <CODE>aio_write</CODE> function. The only
difference is that on 32 bit machines the file descriptor should
be opened in the large file mode. Internally <CODE>aio_write64</CODE> uses
functionality equivalent to <CODE>lseek64</CODE> to position the file descriptor correctly for the writing,
as opposed to <CODE>lseek</CODE> functionality used in <CODE>aio_write</CODE>.
<br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE>, this
function is available under the name <CODE>aio_write</CODE> and so transparently
replaces the interface for small files on 32 bit machines.
sq~wtaio.hxq~Etstruct aiocb *aiocbptinttalarmsq~
tÛ
The <CODE>alarm</CODE> function sets the real-time timer to expire in
<VAR>seconds</VAR> seconds. If you want to cancel any existing alarm, you
can do this by calling <CODE>alarm</CODE> with a <VAR>seconds</VAR> argument of
zero.
<br><br> The return value indicates how many seconds remain before the previous
alarm would have been sent. If there is no previous alarm, <CODE>alarm</CODE>
returns zero.
sq~wt
sys/time.htunistd.hxq~Ltunsigned int secondst unsigned inttallocasq~
t
The return value of <CODE>alloca</CODE> is the address of a block of <VAR>size</VAR>
bytes of memory, allocated in the stack frame of the calling function.
sq~wtstdlib.hxq~Tt size_t sizetvoid *t alphasortsq~
t·
The <CODE>alphasort</CODE> function behaves like the <CODE>strcoll</CODE> function
. The difference is that the arguments
are not string pointers but instead they are of type
<CODE>struct dirent **</CODE>.
<br><br> The return value of <CODE>alphasort</CODE> is less than, equal to, or greater
than zero depending on the order of the two entries <VAR>a</VAR> and <VAR>b</VAR>.
sq~wtdirent.hxq~[tconst void *a, const void *btintt alphasort64sq~
t¹
The <CODE>alphasort64</CODE> function behaves like the <CODE>strcoll</CODE> function
. The difference is that the arguments
are not string pointers but instead they are of type
<CODE>struct dirent64 **</CODE>.
<br><br> Return value of <CODE>alphasort64</CODE> is less than, equal to, or greater
than zero depending on the order of the two entries <VAR>a</VAR> and <VAR>b</VAR>.
sq~wtdirent.hxq~btconst void *a, const void *btintt
argp_errorsq~
t>
Prints the printf format string <VAR>fmt</VAR> and following args, preceded
by the program name and <samp>:</samp>, and followed by a <samp>Try <small>...</small>
--help</samp> message, and terminates the program with an exit status of
<CODE>argp_err_exit_status</CODE>. .
sq~wtargp.hxq~it4const struct argp_state *state, const char *fmt, ...tvoidt argp_failuresq~
t;
Similar to the standard gnu error-reporting function <CODE>error</CODE>, this
prints the program name and <samp>:</samp>, the printf format string
<VAR>fmt</VAR>, and the appropriate following args. If it is non-zero, the
standard unix error text for <VAR>errnum</VAR> is printed. If <VAR>status</VAR> is
non-zero, it terminates the program with that value as its exit status.
<br><br> The difference between <CODE>argp_failure</CODE> and <CODE>argp_error</CODE> is that
<CODE>argp_error</CODE> is for <EM>parsing errors</EM>, whereas
<CODE>argp_failure</CODE> is for other problems that occur during parsing but
don't reflect a syntactic problem with the input, such as illegal values
for options, bad phase of the moon, etc.
sq~wtargp.hxq~ptLconst struct argp_state *state, int status, int errnum, const char *fmt, ...tvoidt argp_helpsq~
té
This outputs a help message for the argp parser <VAR>argp</VAR> to
<VAR>stream</VAR>. The type of messages printed will be determined by
<VAR>flags</VAR>.
<br><br> Any options such as <samp>--help</samp> that are implemented automatically by
argp itself will <EM>not</EM> be present in the help output; for this
reason it is best to use <CODE>argp_state_help</CODE> if calling from within
an argp parser function. .
sq~wtargp.hxq~wtAconst struct argp *argp, FILE *stream, unsigned flags, char *nametvoidt
argp_parsesq~
tÆ
The <CODE>argp_parse</CODE> function parses the arguments in <VAR>argv</VAR>, of
length <VAR>argc</VAR>, using the argp parser <VAR>argp</VAR>. .
<br><br> A value of zero is the same as a <CODE>struct argp</CODE>containing all
zeros. <VAR>flags</VAR> is a set of flag bits that modify the parsing
behavior. . <VAR>input</VAR> is passed through to the argp
parser <VAR>argp</VAR>, and has meaning defined by <VAR>argp</VAR>. A typical
usage is to pass a pointer to a structure which is used for specifying
parameters to the parser and passing back the results.
<br><br> Unless the <CODE>ARGP_NO_EXIT</CODE> or <CODE>ARGP_NO_HELP</CODE> flags are included
in <VAR>flags</VAR>, calling <CODE>argp_parse</CODE> may result in the program
exiting. This behavior is true if an error is detected, or when an
unknown option is encountered. .
<br><br> If <VAR>arg_index</VAR> is non-null, the index of the first unparsed option
in <VAR>argv</VAR> is returned as a value.
<br><br> The return value is zero for successful parsing, or an error code
if an error is detected. Different argp parsers
may return arbitrary error codes, but the standard error codes are:
<CODE>ENOMEM</CODE> if a memory allocation error occurred, or <CODE>EINVAL</CODE> if
an unknown option or option argument is encountered.
sq~wtgconv.htargp.hxq~~t[const struct argp *argp, int argc, char **argv, unsigned flags, int *arg_index, void *inputterror_ttargp_state_helpsq~
tÙ
Outputs a help message for the argp parser referred to by <VAR>state</VAR>,
to <VAR>stream</VAR>. The <VAR>flags</VAR> argument determines what sort of help
message is produced. .
sq~wtargp.hxq~†t<const struct argp_state *state, FILE *stream, unsigned flagstvoidt
argp_usagesq~
tó
Outputs the standard usage message for the argp parser referred to by
<VAR>state</VAR> to <CODE><VAR>state</VAR>->err_stream</CODE> and terminate the program
with <CODE>exit (argp_err_exit_status)</CODE>. .
sq~wtargp.hxq~�tconst struct argp_state *statetvoidtargz_addsq~
tÿ
The <CODE>argz_add</CODE> function adds the string <VAR>str</VAR> to the end of the
argz vector <CODE>*<VAR>argz</VAR></CODE>, and updates <CODE>*<VAR>argz</VAR></CODE> and
<CODE>*<VAR>argz_len</VAR></CODE> accordingly.
sq~wtargz.hxq~”t.char **argz, size_t *argz_len, const char *strterror_tt argz_add_sepsq~
t‘
The <CODE>argz_add_sep</CODE> function is similar to <CODE>argz_add</CODE>, but
<VAR>str</VAR> is split into separate elements in the result at occurrences of
the character <VAR>delim</VAR>. This is useful, for instance, for
adding the components of a Unix search path to an argz vector, by using
a value of <CODE>':'</CODE> for <VAR>delim</VAR>.
sq~wtargz.hxq~›t9char **argz, size_t *argz_len, const char *str, int delimterror_tt argz_appendsq~
tB
The <CODE>argz_append</CODE> function appends <VAR>buf_len</VAR> bytes starting at
<VAR>buf</VAR> to the argz vector <CODE>*<VAR>argz</VAR></CODE>, reallocating
<CODE>*<VAR>argz</VAR></CODE> to accommodate it, and adding <VAR>buf_len</VAR> to
<CODE>*<VAR>argz_len</VAR></CODE>.
sq~wtargz.hxq~¢t>char **argz, size_t *argz_len, const char *buf, size_t buf_lenterror_tt
argz_countsq~
tu
Returns the number of elements in the argz vector <VAR>argz</VAR> and
<VAR>argz_len</VAR>.
sq~wtargz.hxq~©t const char *argz, size_t arg_lentsize_tt argz_createsq~
tG
The <CODE>argz_create</CODE> function converts the Unix-style argument vector
<VAR>argv</VAR> (a vector of pointers to normal C strings, terminated by
<CODE>(char *)0</CODE>; ) into an argz vector with
the same elements, which is returned in <VAR>argz</VAR> and <VAR>argz_len</VAR>.
sq~wtargz.hxq~°t1char *const argv[], char **argz, size_t *argz_lenterror_ttargz_create_sepsq~
t)
The <CODE>argz_create_sep</CODE> function converts the null-terminated string
<VAR>string</VAR> into an argz vector (returned in <VAR>argz</VAR> and
<VAR>argz_len</VAR>) by splitting it into elements at every occurrence of the
character <VAR>sep</VAR>.
sq~wtargz.hxq~·t:const char *string, int sep, char **argz, size_t *argz_lenterror_tt argz_deletesq~
t
If <VAR>entry</VAR> points to the beginning of one of the elements in the
argz vector <CODE>*<VAR>argz</VAR></CODE>, the <CODE>argz_delete</CODE> function will
remove this entry and reallocate <CODE>*<VAR>argz</VAR></CODE>, modifying
<CODE>*<VAR>argz</VAR></CODE> and <CODE>*<VAR>argz_len</VAR></CODE> accordingly. Note that as
destructive argz functions usually reallocate their argz argument,
pointers into argz vectors such as <VAR>entry</VAR> will then become invalid.
sq~wtargz.hxq~¾t*char **argz, size_t *argz_len, char *entrytvoidt argz_extractsq~
tØ
The <CODE>argz_extract</CODE> function converts the argz vector <VAR>argz</VAR> and
<VAR>argz_len</VAR> into a Unix-style argument vector stored in <VAR>argv</VAR>,
by putting pointers to every element in <VAR>argz</VAR> into successive
positions in <VAR>argv</VAR>, followed by a terminator of <CODE>0</CODE>.
<VAR>Argv</VAR> must be pre-allocated with enough space to hold all the
elements in <VAR>argz</VAR> plus the terminating <CODE>(char *)0</CODE>
(<CODE>(argz_count (<VAR>argz</VAR>, <VAR>argz_len</VAR>) + 1) * sizeof (char *)</CODE>
bytes should be enough). Note that the string pointers stored into
<VAR>argv</VAR> point into <VAR>argz</VAR>---they are not copies---and so
<VAR>argz</VAR> must be copied if it will be changed while <VAR>argv</VAR> is
still active. This function is useful for passing the elements in
<VAR>argz</VAR> to an exec function .
sq~wtargz.hxq~Åt(char *argz, size_t argz_len, char **argvtvoidt argz_insertsq~
tê
The <CODE>argz_insert</CODE> function inserts the string <VAR>entry</VAR> into the
argz vector <CODE>*<VAR>argz</VAR></CODE> at a point just before the existing
element pointed to by <VAR>before</VAR>, reallocating <CODE>*<VAR>argz</VAR></CODE> and
updating <CODE>*<VAR>argz</VAR></CODE> and <CODE>*<VAR>argz_len</VAR></CODE>. If <VAR>before</VAR>
is <CODE>0</CODE>, <VAR>entry</VAR> is added to the end instead (as if by
<CODE>argz_add</CODE>). Since the first element is in fact the same as
<CODE>*<VAR>argz</VAR></CODE>, passing in <CODE>*<VAR>argz</VAR></CODE> as the value of
<VAR>before</VAR> will result in <VAR>entry</VAR> being inserted at the beginning.
sq~wtargz.hxq~Ìt>char **argz, size_t *argz_len, char *before, const char *entryterror_tt argz_nextsq~
t–
The <CODE>argz_next</CODE> function provides a convenient way of iterating
over the elements in the argz vector <VAR>argz</VAR>. It returns a pointer
to the next element in <VAR>argz</VAR> after the element <VAR>entry</VAR>, or
<CODE>0</CODE> if there are no elements following <VAR>entry</VAR>. If <VAR>entry</VAR>
is <CODE>0</CODE>, the first element of <VAR>argz</VAR> is returned.
<br><br> This behavior suggests two styles of iteration:
<br><br> <pre><br>
char *entry = 0;<br>
while ((entry = argz_next (<VAR>argz</VAR>, <VAR>argz_len</VAR>, entry)))<br>
<VAR>action</VAR>;<br>
</pre><br>
<br><br> (the double parentheses are necessary to make some C compilers shut up<br>
about what they consider a questionable <CODE>while</CODE>-test) and:<br>
<br><br> <pre><br>
char *entry;<br>
for (entry = <VAR>argz</VAR>;<br>
entry;<br>
entry = argz_next (<VAR>argz</VAR>, <VAR>argz_len</VAR>, entry))<br>
<VAR>action</VAR>;<br>
</pre>
<br><br> Note that the latter depends on <VAR>argz</VAR> having a value of <CODE>0</CODE> if
it is empty (rather than a pointer to an empty block of memory); this
invariant is maintained for argz vectors created by the functions here.
sq~wtargz.hxq~Ót.char *argz, size_t argz_len, const char *entrytchar *t argz_replacesq~
t?
Replace any occurrences of the string <VAR>str</VAR> in <VAR>argz</VAR> with
<VAR>with</VAR>, reallocating <VAR>argz</VAR> as necessary. If
<VAR>replace_count</VAR> is non-zero, <CODE>*<VAR>replace_count</VAR></CODE> will be
incremented by number of replacements performed.
sq~wtargz.hxq~Úpterror_ttargz_stringifysq~
t…
The <CODE>argz_stringify</CODE> converts <VAR>argz</VAR> into a normal string with
the elements separated by the character <VAR>sep</VAR>, by replacing each
<CODE>'\0'</CODE> inside <VAR>argz</VAR> (except the last one, which terminates the
string) with <VAR>sep</VAR>. This is handy for printing <VAR>argz</VAR> in a
readable manner.
sq~wtargz.hxq~àtchar *argz, size_t len, int septvoidtasctimesq~
tû
The <CODE>asctime</CODE> function converts the broken-down time value that
<VAR>brokentime</VAR> points to into a string in a standard format:
<br><br> <pre><br>
"Tue May 21 13:46:22 1991\n"<br>
</pre>
<br><br> The abbreviations for the days of week are: <samp>Sun</samp>, <samp>Mon</samp>,
<samp>Tue</samp>, <samp>Wed</samp>, <samp>Thu</samp>, <samp>Fri</samp>, and <samp>Sat</samp>.
<br><br> The abbreviations for the months are: <samp>Jan</samp>, <samp>Feb</samp>,
<samp>Mar</samp>, <samp>Apr</samp>, <samp>May</samp>, <samp>Jun</samp>, <samp>Jul</samp>, <samp>Aug</samp>,
<samp>Sep</samp>, <samp>Oct</samp>, <samp>Nov</samp>, and <samp>Dec</samp>.
<br><br> The return value points to a statically allocated string, which might be
overwritten by subsequent calls to <CODE>asctime</CODE> or <CODE>ctime</CODE>.
(But no other library function overwrites the contents of this
string.)
sq~wttime.hxq~çtconst struct tm *brokentimetchar *t asctime_rsq~
t
This function is similar to <CODE>asctime</CODE> but instead of placing the
result in a static buffer it writes the string in the buffer pointed to
by the parameter <VAR>buffer</VAR>. This buffer should have room
for at least 26 bytes, including the terminating null.
<br><br> If no error occurred the function returns a pointer to the string the
result was written into, i.e., it returns <VAR>buffer</VAR>. Otherwise
return <CODE>NULL</CODE>.
sq~wttime.hxq~ît)const struct tm *brokentime, char *buffertchar *tasinsq~
t.
These functions compute the arc sine of <VAR>x</VAR>---that is, the value whose
sine is <VAR>x</VAR>. The value is in units of radians. Mathematically,
there are infinitely many such values; the one actually returned is the
one between <CODE>-pi/2</CODE> and <CODE>pi/2</CODE> (inclusive).
<br><br> The arc sine function is defined mathematically only
over the domain <CODE>-1</CODE> to <CODE>1</CODE>. If <VAR>x</VAR> is outside the
domain, <CODE>asin</CODE> signals a domain error.
sq~wtmath.hxq~õtdouble xtdoubletasinfsq~
t.
These functions compute the arc sine of <VAR>x</VAR>---that is, the value whose
sine is <VAR>x</VAR>. The value is in units of radians. Mathematically,
there are infinitely many such values; the one actually returned is the
one between <CODE>-pi/2</CODE> and <CODE>pi/2</CODE> (inclusive).
<br><br> The arc sine function is defined mathematically only
over the domain <CODE>-1</CODE> to <CODE>1</CODE>. If <VAR>x</VAR> is outside the
domain, <CODE>asin</CODE> signals a domain error.
sq~wtmath.hxq~ütfloat xtfloattasinhsq~
t�
These functions return the inverse hyperbolic sine of <VAR>x</VAR>---the
value whose hyperbolic sine is <VAR>x</VAR>.
sq~wtmath.hxq~tdouble xtdoubletasinhfsq~
t�
These functions return the inverse hyperbolic sine of <VAR>x</VAR>---the
value whose hyperbolic sine is <VAR>x</VAR>.
sq~wtmath.hxq~
tfloat xtfloattasinhlsq~
t�
These functions return the inverse hyperbolic sine of <VAR>x</VAR>---the
value whose hyperbolic sine is <VAR>x</VAR>.
sq~wtmath.hxq~t
long double xt long doubletasinlsq~
t.
These functions compute the arc sine of <VAR>x</VAR>---that is, the value whose
sine is <VAR>x</VAR>. The value is in units of radians. Mathematically,
there are infinitely many such values; the one actually returned is the
one between <CODE>-pi/2</CODE> and <CODE>pi/2</CODE> (inclusive).
<br><br> The arc sine function is defined mathematically only
over the domain <CODE>-1</CODE> to <CODE>1</CODE>. If <VAR>x</VAR> is outside the
domain, <CODE>asin</CODE> signals a domain error.
sq~wtmath.hxq~t
long double xt long doubletasprintfsq~
t
This function is similar to <CODE>sprintf</CODE>, except that it dynamically
allocates a string (as with <CODE>malloc</CODE>; ) to hold the output, instead of putting the output in a
buffer you allocate in advance. The <VAR>ptr</VAR> argument should be the
address of a <CODE>char *</CODE> object, and a successful call to
<CODE>asprintf</CODE> stores a pointer to the newly allocated string at that
location.
<br><br> The return value is the number of characters allocated for the buffer, or
less than zero if an error occurred. Usually this means that the buffer
could not be allocated.
<br><br> Here is how to use <CODE>asprintf</CODE> to get the same result as the
<CODE>snprintf</CODE> example, but more easily:
<br><br> <pre><br>
/* Construct a message describing the value of a variable<br>
whose name is <VAR>name</VAR> and whose value is <VAR>value</VAR>. */<br>
char *<br>
make_message (char *name, char *value)<br>
{<br>
char *result;<br>
if (asprintf (&result, "value of %s is %s", name, value) < 0)<br>
return NULL;<br>
return result;<br>
}<br>
</pre>
sq~wtstdio.hxq~t%char **ptr, const char *template, ...tinttatansq~
tU
These functions compute the arc tangent of <VAR>x</VAR>---that is, the value
whose tangent is <VAR>x</VAR>. The value is in units of radians.
Mathematically, there are infinitely many such values; the one actually
returned is the one between <CODE>-pi/2</CODE> and <CODE>pi/2</CODE> (inclusive).
sq~wtmath.hxq~&tdouble xtdoubletatan2sq~
th
This function computes the arc tangent of <VAR>y</VAR>/<VAR>x</VAR>, but the signs
of both arguments are used to determine the quadrant of the result, and
<VAR>x</VAR> is permitted to be zero. The return value is given in radians
and is in the range <CODE>-pi</CODE> to <CODE>pi</CODE>, inclusive.
<br><br> If <VAR>x</VAR> and <VAR>y</VAR> are coordinates of a point in the plane,
<CODE>atan2</CODE> returns the signed angle between the line from the origin
to that point and the x-axis. Thus, <CODE>atan2</CODE> is useful for
converting Cartesian coordinates to polar coordinates. (To compute the
radial coordinate, use <CODE>hypot</CODE>; see Exponents and
Logarithms.)
<br><br> If both <VAR>x</VAR> and <VAR>y</VAR> are zero, <CODE>atan2</CODE> returns zero.
sq~wtmath.hxq~-tdouble y, double xtdoubletatan2fsq~
th
This function computes the arc tangent of <VAR>y</VAR>/<VAR>x</VAR>, but the signs
of both arguments are used to determine the quadrant of the result, and
<VAR>x</VAR> is permitted to be zero. The return value is given in radians
and is in the range <CODE>-pi</CODE> to <CODE>pi</CODE>, inclusive.
<br><br> If <VAR>x</VAR> and <VAR>y</VAR> are coordinates of a point in the plane,
<CODE>atan2</CODE> returns the signed angle between the line from the origin
to that point and the x-axis. Thus, <CODE>atan2</CODE> is useful for
converting Cartesian coordinates to polar coordinates. (To compute the
radial coordinate, use <CODE>hypot</CODE>; see Exponents and
Logarithms.)
<br><br> If both <VAR>x</VAR> and <VAR>y</VAR> are zero, <CODE>atan2</CODE> returns zero.
sq~wtmath.hxq~4tfloat y, float xtfloattatan2lsq~
th
This function computes the arc tangent of <VAR>y</VAR>/<VAR>x</VAR>, but the signs
of both arguments are used to determine the quadrant of the result, and
<VAR>x</VAR> is permitted to be zero. The return value is given in radians
and is in the range <CODE>-pi</CODE> to <CODE>pi</CODE>, inclusive.
<br><br> If <VAR>x</VAR> and <VAR>y</VAR> are coordinates of a point in the plane,
<CODE>atan2</CODE> returns the signed angle between the line from the origin
to that point and the x-axis. Thus, <CODE>atan2</CODE> is useful for
converting Cartesian coordinates to polar coordinates. (To compute the
radial coordinate, use <CODE>hypot</CODE>; see Exponents and
Logarithms.)
<br><br> If both <VAR>x</VAR> and <VAR>y</VAR> are zero, <CODE>atan2</CODE> returns zero.
sq~wtmath.hxq~;tlong double y, long double xt long doubletatanfsq~
tU
These functions compute the arc tangent of <VAR>x</VAR>---that is, the value
whose tangent is <VAR>x</VAR>. The value is in units of radians.
Mathematically, there are infinitely many such values; the one actually
returned is the one between <CODE>-pi/2</CODE> and <CODE>pi/2</CODE> (inclusive).
sq~wtmath.hxq~Btfloat xtfloattatanhsq~
tT
These functions return the inverse hyperbolic tangent of <VAR>x</VAR>---the
value whose hyperbolic tangent is <VAR>x</VAR>. If the absolute value of
<VAR>x</VAR> is greater than <CODE>1</CODE>, <CODE>atanh</CODE> signals a domain error;
if it is equal to 1, <CODE>atanh</CODE> returns infinity.
sq~wtmath.hxq~Itdouble xtdoubletatanhfsq~
tT
These functions return the inverse hyperbolic tangent of <VAR>x</VAR>---the
value whose hyperbolic tangent is <VAR>x</VAR>. If the absolute value of
<VAR>x</VAR> is greater than <CODE>1</CODE>, <CODE>atanh</CODE> signals a domain error;
if it is equal to 1, <CODE>atanh</CODE> returns infinity.
sq~wtmath.hxq~Ptfloat xtfloattatanhlsq~
tT
These functions return the inverse hyperbolic tangent of <VAR>x</VAR>---the
value whose hyperbolic tangent is <VAR>x</VAR>. If the absolute value of
<VAR>x</VAR> is greater than <CODE>1</CODE>, <CODE>atanh</CODE> signals a domain error;
if it is equal to 1, <CODE>atanh</CODE> returns infinity.
sq~wtmath.hxq~Wt
long double xt long doubletatanlsq~
tU
These functions compute the arc tangent of <VAR>x</VAR>---that is, the value
whose tangent is <VAR>x</VAR>. The value is in units of radians.
Mathematically, there are infinitely many such values; the one actually
returned is the one between <CODE>-pi/2</CODE> and <CODE>pi/2</CODE> (inclusive).
sq~wtmath.hxq~^t
long double xt long doubletatexitsq~
t[
The <CODE>atexit</CODE> function registers the function <VAR>function</VAR> to be
called at normal program termination. The <VAR>function</VAR> is called with
no arguments.
<br><br> The return value from <CODE>atexit</CODE> is zero on success and nonzero if
the function cannot be registered.
sq~wtstdlib.hxq~etvoid (*function) (void)tinttatofsq~
t+
This function is similar to the <CODE>strtod</CODE> function, except that it
need not detect overflow and underflow errors. The <CODE>atof</CODE> function
is provided mostly for compatibility with existing code; using
<CODE>strtod</CODE> is more robust.
sq~wtstdlib.hxq~ltconst char *stringtdoubletatoisq~
tÕ
This function is like <CODE>atol</CODE>, except that it returns an <CODE>int</CODE>.
The <CODE>atoi</CODE> function is also considered obsolete; use <CODE>strtol</CODE>
instead.
sq~wtstdlib.hxq~stconst char *stringtinttatolsq~
tO
This function is similar to the <CODE>strtol</CODE> function with a <VAR>base</VAR>
argument of <CODE>10</CODE>, except that it need not detect overflow errors.
The <CODE>atol</CODE> function is provided mostly for compatibility with
existing code; using <CODE>strtol</CODE> is more robust.
sq~wtstdlib.hxq~ztconst char *stringtlong inttatollsq~
t'
This function is similar to <CODE>atol</CODE>, except it returns a <CODE>long
long int</CODE>.
<br><br> The <CODE>atoll</CODE> function was introduced in ISO C99. It too is
obsolete (despite having just been added); use <CODE>strtoll</CODE> instead.
sq~wtstdlib.hxq~�tconst char *stringt
long long intt backtracesq~
tõ
The <CODE>backtrace</CODE> function obtains a backtrace for the current
thread, as a list of pointers, and places the information into
<VAR>buffer</VAR>. The argument <VAR>size</VAR> should be the number of
<CODE>void *</CODE> elements that will fit into <VAR>buffer</VAR>. The return
value is the actual number of entries of <VAR>buffer</VAR> that are obtained,
and is at most <VAR>size</VAR>.
<br><br> The pointers placed in <VAR>buffer</VAR> are actually return addresses
obtained by inspecting the stack, one return address per stack frame.
<br><br> Note that certain compiler optimizations may interfere with obtaining a
valid backtrace. Function inlining causes the inlined function to not
have a stack frame; tail call optimization replaces one stack frame with
another; frame pointer elimination will stop <CODE>backtrace</CODE> from
interpreting the stack contents correctly.
sq~wt wordexp.ht
execinfo.hxq~ˆtvoid **buffer, int sizetinttbacktrace_symbolssq~
tÐ
The <CODE>backtrace_symbols</CODE> function translates the information
obtained from the <CODE>backtrace</CODE> function into an array of strings.
The argument <VAR>buffer</VAR> should be a pointer to an array of addresses
obtained via the <CODE>backtrace</CODE> function, and <VAR>size</VAR> is the number
of entries in that array (the return value of <CODE>backtrace</CODE>).
<br><br> The return value is a pointer to an array of strings, which has
<VAR>size</VAR> entries just like the array <VAR>buffer</VAR>. Each string
contains a printable representation of the corresponding element of
<VAR>buffer</VAR>. It includes the function name (if this can be
determined), an offset into the function, and the actual return address
(in hexadecimal).
<br><br> Currently, the function name and offset only be obtained on systems that
use the ELF binary format for programs and libraries. On other systems,
only the hexadecimal return address will be present. Also, you may need
to pass additional flags to the linker to make the function names
available to the program. (For example, on systems using GNU ld, you
must pass (<CODE>-rdynamic</CODE>.)
<br><br> The return value of <CODE>backtrace_symbols</CODE> is a pointer obtained via
the <CODE>malloc</CODE> function, and it is the responsibility of the caller
to <CODE>free</CODE> that pointer. Note that only the return value need be
freed, not the individual strings.
<br><br> The return value is <CODE>NULL</CODE> if sufficient memory for the strings
cannot be obtained.
sq~wt
execinfo.hxq~�tvoid *const *buffer, int sizetchar **tbacktrace_symbols_fdsq~
t±
The <CODE>backtrace_symbols_fd</CODE> function performs the same translation
as the function <CODE>backtrace_symbols</CODE> function. Instead of returning
the strings to the caller, it writes the strings to the file descriptor
<VAR>fd</VAR>, one per line. It does not use the <CODE>malloc</CODE> function, and
can therefore be used in situations where that function might fail.
sq~wt
execinfo.hxq~—t%void *const *buffer, int size, int fdtvoidtbasenamesq~
t'
This is the standard XPG defined <CODE>basename</CODE>. It is similar in
spirit to the GNU version, but may modify the <VAR>path</VAR> by removing
trailing '/' characters. If the <VAR>path</VAR> is made up entirely of '/'
characters, then "/" will be returned. Also, if <VAR>path</VAR> is
<CODE>NULL</CODE> or an empty string, then "." is returned. The prototype for
the XPG version can be found in <TT>libgen.h</TT>.
<br><br> Example of using XPG <CODE>basename</CODE>:
<br><br> <pre><br>
#include <libgen.h><br>
<br><br> int<br>
main (int argc, char *argv[])<br>
{<br>
char *prog;<br>
char *path = strdupa (argv[0]);<br>
<br><br> prog = basename (path);<br>
<br><br> if (argc < 2)<br>
{<br>
fprintf (stderr, "Usage %s <arg>\n", prog);<br>
exit (1);<br>
}<br>
<br><br> <small>...</small><br>
<br><br> }<br>
</pre>
sq~wtlibgen.hxtbasenamet
char *pathtchar *tbcmpsq~
tV
This is an obsolete alias for <CODE>memcmp</CODE>, derived from BSD.
sq~wtstring.hxq~¦t+const void *a1, const void *a2, size_t sizetinttbcopysq~
t
This is a partially obsolete alternative for <CODE>memmove</CODE>, derived from
BSD. Note that it is not quite equivalent to <CODE>memmove</CODE>, because the
arguments are not in the same order and there is no return value.
sq~wtstring.hxq~­t'const void *from, void *to, size_t sizetvoidtbindsq~
t
The <CODE>bind</CODE> function assigns an address to the socket
<VAR>socket</VAR>. The <VAR>addr</VAR> and <VAR>length</VAR> arguments specify the
address; the detailed format of the address depends on the namespace.
The first part of the address is always the format designator, which
specifies a namespace, and says that the address is in the format of
that namespace.
<br><br> The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on failure. The
following <CODE>errno</CODE> error conditions are defined for this function:
<br><br> <DL>
<DT><CODE>EBADF</CODE>
<DD>
The <VAR>socket</VAR> argument is not a valid file descriptor.
<br><br> <LI> ENOTSOCK
The descriptor <VAR>socket</VAR> is not a socket.
<br><br> <LI> EADDRNOTAVAIL
The specified address is not available on this machine.
<br><br> <LI> EADDRINUSE
Some other socket is already using the specified address.
<br><br> <LI> EINVAL
The socket <VAR>socket</VAR> already has an address.
<br><br> <LI> EACCES
You do not have permission to access the requested address. (In the
Internet domain, only the super-user is allowed to specify a port number
in the range 0 through <CODE>IPPORT_RESERVED</CODE> minus one; see
Ports.)
<br><br> Additional conditions may be possible depending on the particular namespace
of the socket.
sq~wt sys/socket.hxq~´t3int socket, struct sockaddr *addr, socklen_t lengthtinttbindtextdomainsq~
t"
The <CODE>bindtextdomain</CODE> function can be used to specify the directory
which contains the message catalogs for domain <VAR>domainname</VAR> for the
different languages. To be correct, this is the directory where the
hierarchy of directories is expected. Details are explained below.
<br><br> For the programmer it is important to note that the translations which
come with the program have be placed in a directory hierarchy starting
at, say, <TT>/foo/bar</TT>. Then the program should make a
<CODE>bindtextdomain</CODE> call to bind the domain for the current program to
this directory. So it is made sure the catalogs are found. A correctly
running program does not depend on the user setting an environment
variable.
<br><br> The <CODE>bindtextdomain</CODE> function can be used several times and if the
<VAR>domainname</VAR> argument is different the previously bound domains
will not be overwritten.
<br><br> If the program which wish to use <CODE>bindtextdomain</CODE> at some point of
time use the <CODE>chdir</CODE> function to change the current working
directory it is important that the <VAR>dirname</VAR> strings ought to be an
absolute pathname. Otherwise the addressed directory might vary with
the time.
<br><br> If the <VAR>dirname</VAR> parameter is the null pointer <CODE>bindtextdomain</CODE>
returns the currently selected directory for the domain with the name
<VAR>domainname</VAR>.
<br><br> The <CODE>bindtextdomain</CODE> function returns a pointer to a string
containing the name of the selected directory name. The string is
allocated internally in the function and must not be changed by the
user. If the system went out of core during the execution of
<CODE>bindtextdomain</CODE> the return value is <CODE>NULL</CODE> and the global
variable <VAR>errno</VAR> is set accordingly.
sq~wt libintl.hxq~»t+const char *domainname, const char *dirnametchar *tbrksq~
te
<br><br> <CODE>brk</CODE> sets the high end of the calling process' data segment to
<VAR>addr</VAR>.
<br><br> The address of the end of a segment is defined to be the address of the
last byte in the segment plus 1.
<br><br> The function has no effect if <VAR>addr</VAR> is lower than the low end of
the data segment. (This is considered success, by the way).
<br><br> The function fails if it would cause the data segment to overlap another
segment or exceed the process' data storage limit .
<br><br> The function is named for a common historical case where data storage
and the stack are in the same segment. Data storage allocation grows
upward from the bottom of the segment while the stack grows downward
toward it from the top of the segment and the curtain between them is
called the break.
<br><br> The return value is zero on success. On failure, the return value is
<CODE>-1</CODE> and <CODE>errno</CODE> is set accordingly. The following <CODE>errno</CODE>
values are specific to this function:
<br><br> <DL>
<DT><CODE>ENOMEM</CODE>
<DD>
The request would cause the data segment to overlap another segment or
exceed the process' data storage limit.
<br><br> <br><br>
sq~wtunistd.hxq~Ât
void *addrtinttbsearchsq~
tZ
The <CODE>bsearch</CODE> function searches the sorted array <VAR>array</VAR> for an object
that is equivalent to <VAR>key</VAR>. The array contains <VAR>count</VAR> elements,
each of which is of size <VAR>size</VAR> bytes.
<br><br> The <VAR>compare</VAR> function is used to perform the comparison. This
function is called with two pointer arguments and should return an
integer less than, equal to, or greater than zero corresponding to
whether its first argument is considered less than, equal to, or greater
than its second argument. The elements of the <VAR>array</VAR> must already
be sorted in ascending order according to this comparison function.
<br><br> The return value is a pointer to the matching array element, or a null
pointer if no match is found. If the array contains more than one element
that matches, the one that is returned is unspecified.
<br><br> This function derives its name from the fact that it is implemented
using the binary search algorithm.
sq~wtstdlib.hxq~ÉtVconst void *key, const void *array, size_t count, size_t size, comparison_fn_t comparetvoid *tbtowcsq~
t«
The <CODE>btowc</CODE> function (``byte to wide character'') converts a valid
single byte character <VAR>c</VAR> in the initial shift state into the wide
character equivalent using the conversion rules from the currently
selected locale of the <CODE>LC_CTYPE</CODE> category.
<br><br> If <CODE>(unsigned char) <VAR>c</VAR></CODE> is no valid single byte multibyte
character or if <VAR>c</VAR> is <CODE>EOF</CODE>, the function returns <CODE>WEOF</CODE>.
<br><br> Please note the restriction of <VAR>c</VAR> being tested for validity only in
the initial shift state. No <CODE>mbstate_t</CODE> object is used from
which the state information is taken, and the function also does not use
any static state.
<br><br> The <CODE>btowc</CODE> function was introduced in Amendment 1 to ISO C90
and is declared in <TT>wchar.h</TT>.
sq~wtwchar.hxq~Ðtint ctwint_ttbzerosq~
tÜ
This is a partially obsolete alternative for <CODE>memset</CODE>, derived from
BSD. Note that it is not as general as <CODE>memset</CODE>, because the only
value it can store is zero.
sq~wtstring.hxq~×tvoid *block, size_t sizetvoidtcabssq~
tP
These functions return the absolute value of the complex number <VAR>z</VAR>
. The absolute value of a complex number is:
<br><br> <pre><br>
sqrt (creal (<VAR>z</VAR>) * creal (<VAR>z</VAR>) + cimag (<VAR>z</VAR>) * cimag (<VAR>z</VAR>))<br>
</pre>
<br><br> This function should always be used instead of the direct formula
because it takes special care to avoid losing precision. It may also
take advantage of hardware support for this operation. See <CODE>hypot</CODE>
in Exponents and Logarithms.
sq~wt complex.hxq~Þtcomplex double ztdoubletcabsfsq~
tP
These functions return the absolute value of the complex number <VAR>z</VAR>
. The absolute value of a complex number is:
<br><br> <pre><br>
sqrt (creal (<VAR>z</VAR>) * creal (<VAR>z</VAR>) + cimag (<VAR>z</VAR>) * cimag (<VAR>z</VAR>))<br>
</pre>
<br><br> This function should always be used instead of the direct formula
because it takes special care to avoid losing precision. It may also
take advantage of hardware support for this operation. See <CODE>hypot</CODE>
in Exponents and Logarithms.
sq~wt complex.hxq~åtcomplex float ztfloattcabslsq~
tP
These functions return the absolute value of the complex number <VAR>z</VAR>
. The absolute value of a complex number is:
<br><br> <pre><br>
sqrt (creal (<VAR>z</VAR>) * creal (<VAR>z</VAR>) + cimag (<VAR>z</VAR>) * cimag (<VAR>z</VAR>))<br>
</pre>
<br><br> This function should always be used instead of the direct formula
because it takes special care to avoid losing precision. It may also
take advantage of hardware support for this operation. See <CODE>hypot</CODE>
in Exponents and Logarithms.
sq~wt complex.hxq~ìtcomplex long double zt long doubletcacossq~
t*
These functions compute the complex arc cosine of <VAR>z</VAR>---that is, the
value whose cosine is <VAR>z</VAR>. The value returned is in radians.
<br><br> Unlike the real-valued functions, <CODE>cacos</CODE> is defined for all
values of <VAR>z</VAR>.
sq~wt complex.hxq~ótcomplex double ztcomplex doubletcacosfsq~
t*
These functions compute the complex arc cosine of <VAR>z</VAR>---that is, the
value whose cosine is <VAR>z</VAR>. The value returned is in radians.
<br><br> Unlike the real-valued functions, <CODE>cacos</CODE> is defined for all
values of <VAR>z</VAR>.
sq~wt complex.hxq~útcomplex float zt
complex floattcacoshsq~
t
These functions return the inverse complex hyperbolic cosine of
<VAR>z</VAR>---the value whose complex hyperbolic cosine is <VAR>z</VAR>. Unlike
the real-valued functions, there are no restrictions on the value of <VAR>z</VAR>.
sq~wt complex.hxq~tcomplex double ztcomplex doubletcacoshfsq~
t
These functions return the inverse complex hyperbolic cosine of
<VAR>z</VAR>---the value whose complex hyperbolic cosine is <VAR>z</VAR>. Unlike
the real-valued functions, there are no restrictions on the value of <VAR>z</VAR>.
sq~wt complex.hxq~tcomplex float zt
complex floattcacoshlsq~
t
These functions return the inverse complex hyperbolic cosine of
<VAR>z</VAR>---the value whose complex hyperbolic cosine is <VAR>z</VAR>. Unlike
the real-valued functions, there are no restrictions on the value of <VAR>z</VAR>.
sq~wt complex.hxq~tcomplex long double ztcomplex long doubletcacoslsq~
t*
These functions compute the complex arc cosine of <VAR>z</VAR>---that is, the
value whose cosine is <VAR>z</VAR>. The value returned is in radians.
<br><br> Unlike the real-valued functions, <CODE>cacos</CODE> is defined for all
values of <VAR>z</VAR>.
sq~wt complex.hxq~tcomplex long double ztcomplex long doubletcallocsq~
tè
This function allocates a block long enough to contain a vector of
<VAR>count</VAR> elements, each of size <VAR>eltsize</VAR>. Its contents are
cleared to zero before <CODE>calloc</CODE> returns.
sq~wtstdlib.hxq~tsize_t count, size_t eltsizetvoid *tcanonicalize_file_namesq~
t®
<br><br> The <CODE>canonicalize_file_name</CODE> function returns the absolute name of
the file named by <VAR>name</VAR> which contains no <CODE>.</CODE>, <CODE>..</CODE>
components nor any repeated path separators (<CODE>/</CODE>) or symlinks. The
result is passed back as the return value of the function in a block of
memory allocated with <CODE>malloc</CODE>. If the result is not used anymore
the memory should be freed with a call to <CODE>free</CODE>.
<br><br> If any of the path components is missing the function returns a NULL
pointer. This is also what is returned if the length of the path
reaches or exceeds <CODE>PATH_MAX</CODE> characters. In any case
<CODE>errno</CODE> is set accordingly.
<br><br> <DL>
<DT><CODE>ENAMETOOLONG</CODE>
<DD>
The resulting path is too long. This error only occurs on systems which
have a limit on the file name length.
<br><br> <LI> EACCES
At least one of the path components is not readable.
<br><br> <LI> ENOENT
The input file name is empty.
<br><br> <LI> ENOENT
At least one of the path components does not exist.
<br><br> <LI> ELOOP
More than <CODE>MAXSYMLINKS</CODE> many symlinks have been followed.
<br><br> This function is a GNU extension and is declared in <TT>stdlib.h</TT>.
sq~wtstdlib.hxq~$tconst char *nametchar *tcargsq~
t§
These functions return the argument of the complex number <VAR>z</VAR>.
The argument of a complex number is the angle in the complex plane
between the positive real axis and a line passing through zero and the
number. This angle is measured in the usual fashion and ranges from 0
to 2.
<br><br> <CODE>carg</CODE> has a branch cut along the positive real axis.
sq~wt complex.hxq~+tcomplex double ztdoubletcargfsq~
t§
These functions return the argument of the complex number <VAR>z</VAR>.
The argument of a complex number is the angle in the complex plane
between the positive real axis and a line passing through zero and the
number. This angle is measured in the usual fashion and ranges from 0
to 2.
<br><br> <CODE>carg</CODE> has a branch cut along the positive real axis.
sq~wt complex.hxq~2tcomplex float ztfloattcarglsq~
t§
These functions return the argument of the complex number <VAR>z</VAR>.
The argument of a complex number is the angle in the complex plane
between the positive real axis and a line passing through zero and the
number. This angle is measured in the usual fashion and ranges from 0
to 2.
<br><br> <CODE>carg</CODE> has a branch cut along the positive real axis.
sq~wt complex.hxq~9tcomplex long double zt long doubletcasinsq~
t&
These functions compute the complex arc sine of <VAR>z</VAR>---that is, the
value whose sine is <VAR>z</VAR>. The value returned is in radians.
<br><br> Unlike the real-valued functions, <CODE>casin</CODE> is defined for all
values of <VAR>z</VAR>.
sq~wt complex.hxq~@tcomplex double ztcomplex doubletcasinfsq~
t&
These functions compute the complex arc sine of <VAR>z</VAR>---that is, the
value whose sine is <VAR>z</VAR>. The value returned is in radians.
<br><br> Unlike the real-valued functions, <CODE>casin</CODE> is defined for all
values of <VAR>z</VAR>.
sq~wt complex.hxq~Gtcomplex float zt
complex floattcasinhsq~
t 
These functions return the inverse complex hyperbolic sine of
<VAR>z</VAR>---the value whose complex hyperbolic sine is <VAR>z</VAR>.
sq~wt complex.hxq~Ntcomplex double ztcomplex doubletcasinhfsq~
t 
These functions return the inverse complex hyperbolic sine of
<VAR>z</VAR>---the value whose complex hyperbolic sine is <VAR>z</VAR>.
sq~wt complex.hxq~Utcomplex float zt
complex floattcasinhlsq~
t 
These functions return the inverse complex hyperbolic sine of
<VAR>z</VAR>---the value whose complex hyperbolic sine is <VAR>z</VAR>.
sq~wt complex.hxq~\tcomplex long double ztcomplex long doubletcasinlsq~
t&
These functions compute the complex arc sine of <VAR>z</VAR>---that is, the
value whose sine is <VAR>z</VAR>. The value returned is in radians.
<br><br> Unlike the real-valued functions, <CODE>casin</CODE> is defined for all
values of <VAR>z</VAR>.
sq~wt complex.hxq~ctcomplex long double ztcomplex long doubletcatansq~
t±
These functions compute the complex arc tangent of <VAR>z</VAR>---that is,
the value whose tangent is <VAR>z</VAR>. The value is in units of radians.
sq~wt complex.hxq~jtcomplex double ztcomplex doubletcatanfsq~
t±
These functions compute the complex arc tangent of <VAR>z</VAR>---that is,
the value whose tangent is <VAR>z</VAR>. The value is in units of radians.
sq~wt complex.hxq~qtcomplex float zt
complex floattcatanhsq~
t
These functions return the inverse complex hyperbolic tangent of
<VAR>z</VAR>---the value whose complex hyperbolic tangent is <VAR>z</VAR>. Unlike
the real-valued functions, there are no restrictions on the value of
<VAR>z</VAR>.
sq~wt complex.hxq~xtcomplex double ztcomplex doubletcatanhfsq~
t
These functions return the inverse complex hyperbolic tangent of
<VAR>z</VAR>---the value whose complex hyperbolic tangent is <VAR>z</VAR>. Unlike
the real-valued functions, there are no restrictions on the value of
<VAR>z</VAR>.
sq~wt complex.hxq~tcomplex float zt
complex floattcatanhlsq~
t
These functions return the inverse complex hyperbolic tangent of
<VAR>z</VAR>---the value whose complex hyperbolic tangent is <VAR>z</VAR>. Unlike
the real-valued functions, there are no restrictions on the value of
<VAR>z</VAR>.
sq~wt complex.hxq~†tcomplex long double ztcomplex long doubletcatanlsq~
t±
These functions compute the complex arc tangent of <VAR>z</VAR>---that is,
the value whose tangent is <VAR>z</VAR>. The value is in units of radians.
sq~wt complex.hxq~�tcomplex long double ztcomplex long doubletcatclosesq~
t!
The <CODE>catclose</CODE> function can be used to free the resources
associated with a message catalog which previously was opened by a call
to <CODE>catopen</CODE>. If the resources can be successfully freed the
function returns <CODE>0</CODE>. Otherwise it return <CODE></CODE>1 and the
global variable <VAR>errno</VAR> is set. Errors can occur if the catalog
descriptor <VAR>catalog_desc</VAR> is not valid in which case <VAR>errno</VAR> is
set to <CODE>EBADF</CODE>.
sq~wxq~”tnl_catd catalog_desctinttcatgetssq~
t(
The function <CODE>catgets</CODE> has to be used to access the massage catalog
previously opened using the <CODE>catopen</CODE> function. The
<VAR>catalog_desc</VAR> parameter must be a value previously returned by
<CODE>catopen</CODE>.
<br><br> The next two parameters, <VAR>set</VAR> and <VAR>message</VAR>, reflect the
internal organization of the message catalog files. This will be
explained in detail below. For now it is interesting to know that a
catalog can consists of several set and the messages in each thread are
individually numbered using numbers. Neither the set number nor the
message number must be consecutive. They can be arbitrarily chosen.
But each message (unless equal to another one) must have its own unique
pair of set and message number.
<br><br> Since it is not guaranteed that the message catalog for the language
selected by the user exists the last parameter <VAR>string</VAR> helps to
handle this case gracefully. If no matching string can be found
<VAR>string</VAR> is returned. This means for the programmer that
<br><br> <OL>
<LI>
the <VAR>string</VAR> parameters should contain reasonable text (this also
helps to understand the program seems otherwise there would be no hint
on the string which is expected to be returned.
<LI>
all <VAR>string</VAR> arguments should be written in the same language.
</OL>
sq~wxq~št>nl_catd catalog_desc, int set, int message, const char *stringtchar *tcatopensq~
te
The <CODE>catgets</CODE> function tries to locate the message data file names
<VAR>cat_name</VAR> and loads it when found. The return value is of an
opaque type and can be used in calls to the other functions to refer to
this loaded catalog.
<br><br> The return value is <CODE>(nl_catd) -1</CODE> in case the function failed and
no catalog was loaded. The global variable <VAR>errno</VAR> contains a code
for the error causing the failure. But even if the function call
succeeded this does not mean that all messages can be translated.
<br><br> Locating the catalog file must happen in a way which lets the user of
the program influence the decision. It is up to the user to decide
about the language to use and sometimes it is useful to use alternate
catalog files. All this can be specified by the user by setting some
environment variables.
<br><br> The first problem is to find out where all the message catalogs are
stored. Every program could have its own place to keep all the
different files but usually the catalog files are grouped by languages
and the catalogs for all programs are kept in the same place.
<br><br> environment variable
To tell the <CODE>catopen</CODE> function where the catalog for the program
can be found the user can set the environment variable <CODE>NLSPATH</CODE> to
a value which describes her/his choice. Since this value must be usable
for different languages and locales it cannot be a simple string.
Instead it is a format string (similar to <CODE>printf</CODE>'s). An example
is
<br><br> <pre><br>
/usr/share/locale/%L/%N:/usr/share/locale/%L/LC_MESSAGES/%N<br>
</pre><br>
<br><br> First one can see that more than one directory can be specified (with<br>
the usual syntax of separating them by colons). The next things to<br>
observe are the format string, <CODE>%L</CODE> and <CODE>%N</CODE> in this case.<br>
The <CODE>catopen</CODE> function knows about several of them and the<br>
replacement for all of them is of course different.<br>
<br><br> <DL>
<br>
<DT><CODE>%N<br></CODE>
<DD>
This format element is substituted with the name of the catalog file.<br>
This is the value of the <VAR>cat_name</VAR> argument given to<br>
<CODE>catgets</CODE>.<br>
<br><br> <DT><CODE>%L<br></CODE>
<DD>
This format element is substituted with the name of the currently<br>
selected locale for translating messages. How this is determined is<br>
explained below.<br>
<br><br> <LI> %l<br>
(This is the lowercase ell.) This format element is substituted with the<br>
language element of the locale name. The string describing the selected<br>
locale is expected to have the form<br>
<CODE><VAR>lang</VAR>[_<VAR>terr</VAR>[.<VAR>codeset</VAR>]]</CODE> and this format uses the<br>
first part <VAR>lang</VAR>.<br>
<br><br> <LI> %t<br>
This format element is substituted by the territory part <VAR>terr</VAR> of<br>
the name of the currently selected locale. See the explanation of the<br>
format above.<br>
<br><br> <LI> %c<br>
This format element is substituted by the codeset part <VAR>codeset</VAR> of<br>
the name of the currently selected locale. See the explanation of the<br>
format above.<br>
<br><br> <LI> %%<br>
Since <CODE>%</CODE> is used in a meta character there must be a way to<br>
express the <CODE>%</CODE> character in the result itself. Using <CODE>%%</CODE><br>
does this just like it works for <CODE>printf</CODE>.<br>
<br>
<br><br> <br><br> Using <CODE>NLSPATH</CODE> allows arbitrary directories to be searched for<br>
message catalogs while still allowing different languages to be used.<br>
If the <CODE>NLSPATH</CODE> environment variable is not set, the default value<br>
is<br>
<br><br> <pre><br>
<VAR>prefix</VAR>/share/locale/%L/%N:<VAR>prefix</VAR>/share/locale/%L/LC_MESSAGES/%N<br>
</pre><br>
<br><br> <br>
where <VAR>prefix</VAR> is given to <CODE>configure</CODE> while installing the GNU<br>
C Library (this value is in many cases <CODE>/usr</CODE> or the empty string).<br>
<br><br> The remaining problem is to decide which must be used. The value<br>
decides about the substitution of the format elements mentioned above.<br>
First of all the user can specify a path in the message catalog name<br>
(i.e., the name contains a slash character). In this situation the<br>
<CODE>NLSPATH</CODE> environment variable is not used. The catalog must exist<br>
as specified in the program, perhaps relative to the current working<br>
directory. This situation in not desirable and catalogs names never<br>
should be written this way. Beside this, this behavior is not portable<br>
to all other platforms providing the <CODE>catgets</CODE> interface.<br>
<br><br> environment variable<br>
environment variable<br>
environment variable<br>
Otherwise the values of environment variables from the standard<br>
environment are examined. Which<br>
variables are examined is decided by the <VAR>flag</VAR> parameter of<br>
<CODE>catopen</CODE>. If the value is <CODE>NL_CAT_LOCALE</CODE> (which is defined<br>
in <TT>nl_types.h</TT>) then the <CODE>catopen</CODE> function use the name of<br>
the locale currently selected for the <CODE>LC_MESSAGES</CODE> category.<br>
<br><br> If <VAR>flag</VAR> is zero the <CODE>LANG</CODE> environment variable is examined.<br>
This is a left-over from the early days where the concept of the locales<br>
had not even reached the level of POSIX locales.<br>
<br><br> The environment variable and the locale name should have a value of the<br>
form <CODE><VAR>lang</VAR>[_<VAR>terr</VAR>[.<VAR>codeset</VAR>]]</CODE> as explained above.<br>
If no environment variable is set the <CODE>"C"</CODE> locale is used which<br>
prevents any translation.<br>
<br><br> The return value of the function is in any case a valid string. Either<br>
it is a translation from a message catalog or it is the same as the<br>
<VAR>string</VAR> parameter. So a piece of code to decide whether a<br>
translation actually happened must look like this:<br>
<br><br> <pre><br>
{<br>
char *trans = catgets (desc, set, msg, input_string);<br>
if (trans == input_string)<br>
{<br>
/* Something went wrong. */<br>
}<br>
}<br>
</pre>
<br><br>
When an error occurred the global variable <VAR>errno</VAR> is set to
<br><br> <DL>
<LI> EBADF
The catalog does not exist.
<LI> ENOMSG
The set/message tuple does not name an existing element in the
message catalog.
<br><br> While it sometimes can be useful to test for errors programs normally
will avoid any test. If the translation is not available it is no big
problem if the original, untranslated message is printed. Either the
user understands this as well or s/he will look for the reason why the
messages are not translated.
sq~wt
nl_types.hxq~ tconst char *cat_name, int flagtnl_catdt cbc_cryptsq~
t²
<br><br> The function <CODE>cbc_crypt</CODE> encrypts or decrypts one or more blocks
using DES in Cipher Block Chaining mode.
<br><br> For encryption in CBC mode, each block is exclusive-ored with <VAR>ivec</VAR>
before being encrypted, then <VAR>ivec</VAR> is replaced with the result of
the encryption, then the next block is processed. Decryption is the
reverse of this process.
<br><br> This has the advantage that blocks which are the same before being
encrypted are very unlikely to be the same after being encrypted, making
it much harder to detect patterns in the data.
<br><br> Usually, <VAR>ivec</VAR> is set to 8 random bytes before encryption starts.
Then the 8 random bytes are transmitted along with the encrypted data
(without themselves being encrypted), and passed back in as <VAR>ivec</VAR>
for decryption. Another possibility is to set <VAR>ivec</VAR> to 8 zeroes
initially, and have the first the block encrypted consist of 8 random
bytes.
<br><br> Otherwise, all the parameters are similar to those for <CODE>ecb_crypt</CODE>.
sq~wtrpc/des_crypt.hxq~§t@char *key, char *blocks, unsigned len, unsigned mode, char *ivectinttcbrtsq~
t¦
These functions return the cube root of <VAR>x</VAR>. They cannot
fail; every representable real value has a representable real cube root.
sq~wtmath.hxq~®tdouble xtdoubletcbrtfsq~
t¦
These functions return the cube root of <VAR>x</VAR>. They cannot
fail; every representable real value has a representable real cube root.
sq~wtmath.hxq~µtfloat xtfloattcbrtlsq~
t¦
These functions return the cube root of <VAR>x</VAR>. They cannot
fail; every representable real value has a representable real cube root.
sq~wtmath.hxq~¼t
long double xt long doubletccossq~
tÐ
These functions return the complex cosine of <VAR>z</VAR>.
The mathematical definition of the complex cosine is
<br><br>
cos (z) = 1/2 * (exp (z*i) + exp (-z*i))
sq~wt complex.hxq~Ãtcomplex double ztcomplex doubletccosfsq~
tÐ
These functions return the complex cosine of <VAR>z</VAR>.
The mathematical definition of the complex cosine is
<br><br>
cos (z) = 1/2 * (exp (z*i) + exp (-z*i))
sq~wt complex.hxq~Êtcomplex float zt
complex floattccoshsq~
t·
These functions return the complex hyperbolic cosine of <VAR>z</VAR>, defined
mathematically as <CODE>(exp (<VAR>z</VAR>) + exp (-<VAR>z</VAR>)) / 2</CODE>.
sq~wt complex.hxq~Ñtcomplex double ztcomplex doubletccoshfsq~
t·
These functions return the complex hyperbolic cosine of <VAR>z</VAR>, defined
mathematically as <CODE>(exp (<VAR>z</VAR>) + exp (-<VAR>z</VAR>)) / 2</CODE>.
sq~wt complex.hxq~Øtcomplex float zt
complex floattccoshlsq~
t·
These functions return the complex hyperbolic cosine of <VAR>z</VAR>, defined
mathematically as <CODE>(exp (<VAR>z</VAR>) + exp (-<VAR>z</VAR>)) / 2</CODE>.
sq~wt complex.hxq~ßtcomplex long double ztcomplex long doubletccoslsq~
tÐ
These functions return the complex cosine of <VAR>z</VAR>.
The mathematical definition of the complex cosine is
<br><br>
cos (z) = 1/2 * (exp (z*i) + exp (-z*i))
sq~wt complex.hxq~ætcomplex long double ztcomplex long doubletceilsq~
tÉ
These functions round <VAR>x</VAR> upwards to the nearest integer,
returning that value as a <CODE>double</CODE>. Thus, <CODE>ceil (1.5)</CODE>
is <CODE>2.0</CODE>.
sq~wtmath.hxq~ítdouble xtdoubletceilfsq~
tÉ
These functions round <VAR>x</VAR> upwards to the nearest integer,
returning that value as a <CODE>double</CODE>. Thus, <CODE>ceil (1.5)</CODE>
is <CODE>2.0</CODE>.
sq~wtmath.hxq~ôtfloat xtfloattceillsq~
tÉ
These functions round <VAR>x</VAR> upwards to the nearest integer,
returning that value as a <CODE>double</CODE>. Thus, <CODE>ceil (1.5)</CODE>
is <CODE>2.0</CODE>.
sq~wtmath.hxq~ût
long double xt long doubletcexpsq~
t
These functions return <CODE>e</CODE> (the base of natural
logarithms) raised to the power of <VAR>z</VAR>.
Mathematically, this corresponds to the value
<br><br>
exp (z) = exp (creal (z)) * (cos (cimag (z)) + I * sin (cimag (z)))
sq~wt complex.hxq~tcomplex double ztcomplex doubletcexpfsq~
t
These functions return <CODE>e</CODE> (the base of natural
logarithms) raised to the power of <VAR>z</VAR>.
Mathematically, this corresponds to the value
<br><br>
exp (z) = exp (creal (z)) * (cos (cimag (z)) + I * sin (cimag (z)))
sq~wt complex.hxq~ tcomplex float zt
complex floattcexplsq~
t
These functions return <CODE>e</CODE> (the base of natural
logarithms) raised to the power of <VAR>z</VAR>.
Mathematically, this corresponds to the value
<br><br>
exp (z) = exp (creal (z)) * (cos (cimag (z)) + I * sin (cimag (z)))
sq~wt complex.hxq~tcomplex long double ztcomplex long doublet cfgetispeedsq~
t�
This function returns the input line speed stored in the structure
<CODE>*<VAR>termios-p</VAR></CODE>.
sq~wt termios.hxq~tconst struct termios *termios-ptspeed_tt cfgetospeedsq~
t‚
This function returns the output line speed stored in the structure
<CODE>*<VAR>termios-p</VAR></CODE>.
sq~wt termios.hxq~tconst struct termios *termios-ptspeed_tt cfmakerawsq~
t
This function provides an easy way to set up <CODE>*<VAR>termios-p</VAR></CODE> for
what has traditionally been called ``raw mode'' in BSD. This uses
noncanonical input, and turns off most processing to give an unmodified
channel to the terminal.
<br><br> It does exactly this:
<pre><br>
<VAR>termios-p</VAR>->c_iflag &= ~(IGNBRK|BRKINT|PARMRK|ISTRIP<br>
|INLCR|IGNCR|ICRNL|IXON);<br>
<VAR>termios-p</VAR>->c_oflag &= ~OPOST;<br>
<VAR>termios-p</VAR>->c_lflag &= ~(ECHO|ECHONL|ICANON|ISIG|IEXTEN);<br>
<VAR>termios-p</VAR>->c_cflag &= ~(CSIZE|PARENB);<br>
<VAR>termios-p</VAR>->c_cflag |= CS8;<br>
</pre>
sq~wt termios.hxq~%tstruct termios *termios-ptvoidtcfreesq~
t²
This function does the same thing as <CODE>free</CODE>. It's provided for
backward compatibility with SunOS; you should use <CODE>free</CODE> instead.
sq~wtstdlib.hxq~,t void *ptrtvoidt cfsetispeedsq~
t
This function stores <VAR>speed</VAR> in <CODE>*<VAR>termios-p</VAR></CODE> as the input
speed. The normal return value is 0; a value of -1
indicates an error. If <VAR>speed</VAR> is not a speed, <CODE>cfsetospeed</CODE>
returns -1.
sq~wt termios.hxq~3t(struct termios *termios-p, speed_t speedtintt cfsetospeedsq~
t
This function stores <VAR>speed</VAR> in <CODE>*<VAR>termios-p</VAR></CODE> as the output
speed. The normal return value is 0; a value of -1
indicates an error. If <VAR>speed</VAR> is not a speed, <CODE>cfsetospeed</CODE>
returns -1.
sq~wt termios.hxq~:t(struct termios *termios-p, speed_t speedtintt
cfsetspeedsq~
t[
This function stores <VAR>speed</VAR> in <CODE>*<VAR>termios-p</VAR></CODE> as both the
input and output speeds. The normal return value is 0; a value
of -1 indicates an error. If <VAR>speed</VAR> is not a speed,
<CODE>cfsetspeed</CODE> returns -1. This function is an extension in
4.4 BSD.
sq~wt termios.hxq~At(struct termios *termios-p, speed_t speedtinttchdirsq~
të
This function is used to set the process's working directory to
<VAR>filename</VAR>.
<br><br> The normal, successful return value from <CODE>chdir</CODE> is <CODE>0</CODE>. A
value of <CODE>-1</CODE> is returned to indicate an error. The <CODE>errno</CODE>
error conditions defined for this function are the usual file name
syntax errors , plus <CODE>ENOTDIR</CODE> if the
file <VAR>filename</VAR> is not a directory.
sq~wtunistd.hxq~Htconst char *filenametinttchmodsq~
t€
The <CODE>chmod</CODE> function sets the access permission bits for the file
named by <VAR>filename</VAR> to <VAR>mode</VAR>.
<br><br> If <VAR>filename</VAR> is a symbolic link, <CODE>chmod</CODE> changes the
permissions of the file pointed to by the link, not those of the link
itself.
<br><br> This function returns <CODE>0</CODE> if successful and <CODE>-1</CODE> if not. In
addition to the usual file name errors , the following <CODE>errno</CODE> error conditions are defined for
this function:
<br><br> <DL>
<DT><CODE>ENOENT</CODE>
<DD>
The named file doesn't exist.
<br><br> <LI> EPERM
This process does not have permission to change the access permissions
of this file. Only the file's owner (as judged by the effective user ID
of the process) or a privileged user can change them.
<br><br> <LI> EROFS
The file resides on a read-only file system.
<br><br> <LI> EFTYPE
<VAR>mode</VAR> has the <CODE>S_ISVTX</CODE> bit (the ``sticky bit'') set,
and the named file is not a directory. Some systems do not allow setting the
sticky bit on non-directory files, and some do (and only some of those
assign a useful meaning to the bit for non-directory files).
<br><br> You only get <CODE>EFTYPE</CODE> on systems where the sticky bit has no useful
meaning for non-directory files, so it is always safe to just clear the
bit in <VAR>mode</VAR> and call <CODE>chmod</CODE> again. ,
for full details on the sticky bit.
sq~wt
sys/stat.hxq~Ot!const char *filename, mode_t modetinttchownsq~
t¡
The <CODE>chown</CODE> function changes the owner of the file <VAR>filename</VAR> to
<VAR>owner</VAR>, and its group owner to <VAR>group</VAR>.
<br><br> Changing the owner of the file on certain systems clears the set-user-ID
and set-group-ID permission bits. (This is because those bits may not
be appropriate for the new owner.) Other file permission bits are not
changed.
<br><br> The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on failure.
In addition to the usual file name errors ,
the following <CODE>errno</CODE> error conditions are defined for this function:
<br><br> <DL>
<DT><CODE>EPERM</CODE>
<DD>
This process lacks permission to make the requested change.
<br><br> Only privileged users or the file's owner can change the file's group.
On most file systems, only privileged users can change the file owner;
some file systems allow you to change the owner if you are currently the
owner. When you access a remote file system, the behavior you encounter
is determined by the system that actually holds the file, not by the
system your program is running on.
<br><br> , for information about the
<CODE>_POSIX_CHOWN_RESTRICTED</CODE> macro.
<br><br> <LI> EROFS
The file is on a read-only file system.
sq~wtunistd.hxq~Vt.const char *filename, uid_t owner, gid_t grouptinttcimagsq~
t_
These functions return the imaginary part of the complex number <VAR>z</VAR>.
sq~wt complex.hxq~]tcomplex double ztdoubletcimagfsq~
t_
These functions return the imaginary part of the complex number <VAR>z</VAR>.
sq~wt complex.hxq~dtcomplex float ztfloattcimaglsq~
t_
These functions return the imaginary part of the complex number <VAR>z</VAR>.
sq~wt complex.hxq~ktcomplex long double zt long doubletclearenvsq~
tD
The <CODE>clearenv</CODE> function removes all entries from the environment.
Using <CODE>putenv</CODE> and <CODE>setenv</CODE> new entries can be added again
later.
<br><br> If the function is successful it returns <CODE>0</CODE>. Otherwise the return
value is nonzero.
sq~wtstdlib.hxq~rtvoidtinttclearerrsq~
tæ
This function clears the end-of-file and error indicators for the
stream <VAR>stream</VAR>.
<br><br> The file positioning functions also clear the
end-of-file indicator for the stream.
sq~wtstdio.hxq~yt FILE *streamtvoidtclearerr_unlockedsq~
tâ
The <CODE>clearerr_unlocked</CODE> function is equivalent to the <CODE>clearerr</CODE>
function except that it does not implicitly lock the stream.
<br><br> This function is a GNU extension.
sq~wtstdio.hxq~€t FILE *streamtvoidtclocksq~
tÝ
This function returns the calling process' current CPU time. If the CPU
time is not available or cannot be represented, <CODE>clock</CODE> returns the
value <CODE>(clock_t)(-1)</CODE>.
sq~wt
sys/time.httime.hxq~‡tvoidtclock_ttclogsq~
tœ
These functions return the natural logarithm of <VAR>z</VAR>.
Mathematically, this corresponds to the value
<br><br>
log (z) = log (cabs (z)) + I * carg (z)
<br><br>
<CODE>clog</CODE> has a pole at 0, and will signal overflow if <VAR>z</VAR> equals
or is very close to 0. It is well-defined for all other values of
<VAR>z</VAR>.
sq~wt complex.hxq~�tcomplex double ztcomplex doubletclog10sq~
t
These functions return the base 10 logarithm of the complex value
<VAR>z</VAR>. Mathematically, this corresponds to the value
<br><br>
log (z) = log10 (cabs (z)) + I * carg (z)
<br><br> These functions are GNU extensions.
sq~wt complex.hxq~–tcomplex double ztcomplex doubletclog10fsq~
t
These functions return the base 10 logarithm of the complex value
<VAR>z</VAR>. Mathematically, this corresponds to the value
<br><br>
log (z) = log10 (cabs (z)) + I * carg (z)
<br><br> These functions are GNU extensions.
sq~wt complex.hxq~�tcomplex float zt
complex floattclog10lsq~
t
These functions return the base 10 logarithm of the complex value
<VAR>z</VAR>. Mathematically, this corresponds to the value
<br><br>
log (z) = log10 (cabs (z)) + I * carg (z)
<br><br> These functions are GNU extensions.
sq~wt complex.hxq~¤tcomplex long double ztcomplex long doubletclogfsq~
tœ
These functions return the natural logarithm of <VAR>z</VAR>.
Mathematically, this corresponds to the value
<br><br>
log (z) = log (cabs (z)) + I * carg (z)
<br><br>
<CODE>clog</CODE> has a pole at 0, and will signal overflow if <VAR>z</VAR> equals
or is very close to 0. It is well-defined for all other values of
<VAR>z</VAR>.
sq~wt complex.hxq~«tcomplex float zt
complex floattcloglsq~
tœ
These functions return the natural logarithm of <VAR>z</VAR>.
Mathematically, this corresponds to the value
<br><br>
log (z) = log (cabs (z)) + I * carg (z)
<br><br>
<CODE>clog</CODE> has a pole at 0, and will signal overflow if <VAR>z</VAR> equals
or is very close to 0. It is well-defined for all other values of
<VAR>z</VAR>.
sq~wt complex.hxq~²tcomplex long double ztcomplex long doubletclosesq~
t˜
The function <CODE>close</CODE> closes the file descriptor <VAR>filedes</VAR>.
Closing a file has the following consequences:
<br><br> <OL>
<LI>
The file descriptor is deallocated.
<br><br> <LI>
Any record locks owned by the process on the file are unlocked.
<br><br> <LI>
When all file descriptors associated with a pipe or FIFO have been closed,
any unread data is discarded.
</OL>
<br><br> This function is a cancellation point in multi-threaded programs. This
is a problem if the thread allocates some resources (like memory, file
descriptors, semaphores or whatever) at the time <CODE>close</CODE> is
called. If the thread gets canceled these resources stay allocated
until the program ends. To avoid this, calls to <CODE>close</CODE> should be
protected using cancellation handlers.
<br><br> The normal return value from <CODE>close</CODE> is 0; a value of -1
is returned in case of failure. The following <CODE>errno</CODE> error
conditions are defined for this function:
<br><br> <DL>
<DT><CODE>EBADF</CODE>
<DD>
The <VAR>filedes</VAR> argument is not a valid file descriptor.
<br><br> <LI> EINTR
The <CODE>close</CODE> call was interrupted by a signal.
.
Here is an example of how to handle <CODE>EINTR</CODE> properly:
<br><br> <pre><br>
TEMP_FAILURE_RETRY (close (desc));<br>
</pre>
<br><br> <LI> ENOSPC
<LI>x EIO
<LI>x EDQUOT
When the file is accessed by NFS, these errors from <CODE>write</CODE> can sometimes
not be detected until <CODE>close</CODE>. , for details
on their meaning.
<br><br> Please note that there is <EM>no</EM> separate <CODE>close64</CODE> function.
This is not necessary since this function does not determine nor depend
on the mode of the file. The kernel which performs the <CODE>close</CODE>
operation knows which mode the descriptor is used for and can handle
this situation.
sq~wtunistd.hxq~¹t int filedestinttclosedirsq~
tƒ
This function closes the directory stream <VAR>dirstream</VAR>. It returns
<CODE>0</CODE> on success and <CODE>-1</CODE> on failure.
<br><br> The following <CODE>errno</CODE> error conditions are defined for this
function:
<br><br> <DL>
<DT><CODE>EBADF</CODE>
<DD>
The <VAR>dirstream</VAR> argument is not valid.
sq~wtdirent.hxq~ÀtDIR *dirstreamtinttcloselogsq~
tX
<br><br> <CODE>closelog</CODE> closes the current Syslog connection, if there is one.
This includes closing the <TT>dev/log</TT> socket, if it is open.
<CODE>closelog</CODE> also sets the identification string for Syslog messages
back to the default, if <CODE>openlog</CODE> was called with a non-NULL argument
to <VAR>ident</VAR>. The default identification string is the program name
taken from argv[0].
<br><br> If you are writing shared library code that uses <CODE>openlog</CODE> to
generate custom syslog output, you should use <CODE>closelog</CODE> to drop the
GNU C library's internal reference to the <VAR>ident</VAR> pointer when you are
done. Please read the section on <CODE>openlog</CODE> for more information:
.
<br><br> <CODE>closelog</CODE> does not flush any buffers. You do not have to call
<CODE>closelog</CODE> before re-opening a Syslog connection with <CODE>initlog</CODE>.
Syslog connections are automatically closed on exec or exit.
<br><br>
sq~wtsyslog.hxq~Çtvoidtvoidtconfstrsq~
tÖ
This function reads the value of a string-valued system parameter,
storing the string into <VAR>len</VAR> bytes of memory space starting at
<VAR>buf</VAR>. The <VAR>parameter</VAR> argument should be one of the
<samp>_CS_</samp> symbols listed below.
<br><br> The normal return value from <CODE>confstr</CODE> is the length of the string
value that you asked for. If you supply a null pointer for <VAR>buf</VAR>,
then <CODE>confstr</CODE> does not try to store the string; it just returns
its length. A value of <CODE>0</CODE> indicates an error.
<br><br> If the string you asked for is too long for the buffer (that is, longer
than <CODE><VAR>len</VAR> - 1</CODE>), then <CODE>confstr</CODE> stores just that much
(leaving room for the terminating null character). You can tell that
this has happened because <CODE>confstr</CODE> returns a value greater than or
equal to <VAR>len</VAR>.
<br><br> The following <CODE>errno</CODE> error conditions are defined for this function:
<br><br> <DL>
<DT><CODE>EINVAL</CODE>
<DD>
The value of the <VAR>parameter</VAR> is invalid.
sq~wtunistd.htlimits.hxq~Ît$int parameter, char *buf, size_t lentsize_ttconjsq~
t
These functions return the conjugate value of the complex number
<VAR>z</VAR>. The conjugate of a complex number has the same real part and a
negated imaginary part. In other words, <samp>conj(a + bi) = a + -bi</samp>.
sq~wt complex.hxq~Ötcomplex double ztcomplex doubletconjfsq~
t
These functions return the conjugate value of the complex number
<VAR>z</VAR>. The conjugate of a complex number has the same real part and a
negated imaginary part. In other words, <samp>conj(a + bi) = a + -bi</samp>.
sq~wt complex.hxq~Ýtcomplex float zt
complex floattconjlsq~
t
These functions return the conjugate value of the complex number
<VAR>z</VAR>. The conjugate of a complex number has the same real part and a
negated imaginary part. In other words, <samp>conj(a + bi) = a + -bi</samp>.
sq~wt complex.hxq~ätcomplex long double ztcomplex long doubletconnectsq~
t 9
The <CODE>connect</CODE> function initiates a connection from the socket
with file descriptor <VAR>socket</VAR> to the socket whose address is
specified by the <VAR>addr</VAR> and <VAR>length</VAR> arguments. (This socket
is typically on another machine, and it must be already set up as a
server.) , for information about how these
arguments are interpreted.
<br><br> Normally, <CODE>connect</CODE> waits until the server responds to the request
before it returns. You can set nonblocking mode on the socket
<VAR>socket</VAR> to make <CODE>connect</CODE> return immediately without waiting
for the response. , for information about
nonblocking mode.
<br><br> The normal return value from <CODE>connect</CODE> is <CODE>0</CODE>. If an error
occurs, <CODE>connect</CODE> returns <CODE>-1</CODE>. The following <CODE>errno</CODE>
error conditions are defined for this function:
<br><br> <DL>
<DT><CODE>EBADF</CODE>
<DD>
The socket <VAR>socket</VAR> is not a valid file descriptor.
<br><br> <LI> ENOTSOCK
File descriptor <VAR>socket</VAR> is not a socket.
<br><br> <LI> EADDRNOTAVAIL
The specified address is not available on the remote machine.
<br><br> <LI> EAFNOSUPPORT
The namespace of the <VAR>addr</VAR> is not supported by this socket.
<br><br> <LI> EISCONN
The socket <VAR>socket</VAR> is already connected.
<br><br> <LI> ETIMEDOUT
The attempt to establish the connection timed out.
<br><br> <LI> ECONNREFUSED
The server has actively refused to establish the connection.
<br><br> <LI> ENETUNREACH
The network of the given <VAR>addr</VAR> isn't reachable from this host.
<br><br> <LI> EADDRINUSE
The socket address of the given <VAR>addr</VAR> is already in use.
<br><br> <LI> EINPROGRESS
The socket <VAR>socket</VAR> is non-blocking and the connection could not be
established immediately. You can determine when the connection is
completely established with <CODE>select</CODE>; .
Another <CODE>connect</CODE> call on the same socket, before the connection is
completely established, will fail with <CODE>EALREADY</CODE>.
<br><br> <LI> EALREADY
The socket <VAR>socket</VAR> is non-blocking and already has a pending
connection in progress (see <CODE>EINPROGRESS</CODE> above).
<br><br> This function is defined as a cancellation point in multi-threaded
programs, so one has to be prepared for this and make sure that
allocated resources (like memory, files descriptors, semaphores or
whatever) are freed even if the thread is canceled.
sq~wt sys/socket.hxq~ët3int socket, struct sockaddr *addr, socklen_t lengthtinttcopysignsq~
t
These functions return <VAR>x</VAR> but with the sign of <VAR>y</VAR>. They work
even if <VAR>x</VAR> or <VAR>y</VAR> are NaN or zero. Both of these can carry a
sign (although not all implementations support it) and this is one of
the few operations that can tell the difference.
<br><br> <CODE>copysign</CODE> never raises an exception.
<br><br> This function is defined in IEC 559 (and the appendix with
recommended functions in IEEE 754/IEEE 854).
sq~wtmath.hxq~òtdouble x, double ytdoublet copysignfsq~
t
These functions return <VAR>x</VAR> but with the sign of <VAR>y</VAR>. They work
even if <VAR>x</VAR> or <VAR>y</VAR> are NaN or zero. Both of these can carry a
sign (although not all implementations support it) and this is one of
the few operations that can tell the difference.
<br><br> <CODE>copysign</CODE> never raises an exception.
<br><br> This function is defined in IEC 559 (and the appendix with
recommended functions in IEEE 754/IEEE 854).
sq~wtmath.hxq~ùtfloat x, float ytfloatt copysignlsq~
t
These functions return <VAR>x</VAR> but with the sign of <VAR>y</VAR>. They work
even if <VAR>x</VAR> or <VAR>y</VAR> are NaN or zero. Both of these can carry a
sign (although not all implementations support it) and this is one of
the few operations that can tell the difference.
<br><br> <CODE>copysign</CODE> never raises an exception.
<br><br> This function is defined in IEC 559 (and the appendix with
recommended functions in IEEE 754/IEEE 854).
sq~wtmath.hxq~tlong double x, long double yt long doubletcossq~
tº
These functions return the cosine of <VAR>x</VAR>, where <VAR>x</VAR> is given in
radians. The return value is in the range <CODE>-1</CODE> to <CODE>1</CODE>.
sq~wtmath.hxq~tdouble xtdoubletcosfsq~
tº
These functions return the cosine of <VAR>x</VAR>, where <VAR>x</VAR> is given in
radians. The return value is in the range <CODE>-1</CODE> to <CODE>1</CODE>.
sq~wtmath.hxq~tfloat xtfloattcoshsq~
tî
These function return the hyperbolic cosine of <VAR>x</VAR>,
defined mathematically as <CODE>(exp (<VAR>x</VAR>) + exp (-<VAR>x</VAR>)) / 2</CODE>.
They may signal overflow if <VAR>x</VAR> is too large.
sq~wtmath.hxq~tdouble xtdoubletcoshfsq~
tî
These function return the hyperbolic cosine of <VAR>x</VAR>,
defined mathematically as <CODE>(exp (<VAR>x</VAR>) + exp (-<VAR>x</VAR>)) / 2</CODE>.
They may signal overflow if <VAR>x</VAR> is too large.
sq~wtmath.hxq~tfloat xtfloattcoshlsq~
tî
These function return the hyperbolic cosine of <VAR>x</VAR>,
defined mathematically as <CODE>(exp (<VAR>x</VAR>) + exp (-<VAR>x</VAR>)) / 2</CODE>.
They may signal overflow if <VAR>x</VAR> is too large.
sq~wtmath.hxq~#t
long double xt long doubletcoslsq~
tº
These functions return the cosine of <VAR>x</VAR>, where <VAR>x</VAR> is given in
radians. The return value is in the range <CODE>-1</CODE> to <CODE>1</CODE>.
sq~wtmath.hxq~*t
long double xt long doubletcpowsq~
t¢
These functions return <VAR>base</VAR> raised to the power of
<VAR>power</VAR>. This is equivalent to <CODE>cexp (y * clog (x))</CODE>
sq~wt complex.hxq~1t)complex double base, complex double powertcomplex doubletcpowfsq~
t¢
These functions return <VAR>base</VAR> raised to the power of
<VAR>power</VAR>. This is equivalent to <CODE>cexp (y * clog (x))</CODE>
sq~wt complex.hxq~8t'complex float base, complex float powert
complex floattcpowlsq~
t¢
These functions return <VAR>base</VAR> raised to the power of
<VAR>power</VAR>. This is equivalent to <CODE>cexp (y * clog (x))</CODE>
sq~wt complex.hxq~?t3complex long double base, complex long double powertcomplex long doubletcprojsq~
t¤
These functions return the projection of the complex value <VAR>z</VAR> onto
the Riemann sphere. Values with a infinite imaginary part are projected
to positive infinity on the real axis, even if the real part is NaN. If
the real part is infinite, the result is equivalent to
<br><br> <pre><br>
INFINITY + I * copysign (0.0, cimag (z))<br>
</pre>
sq~wt complex.hxq~Ftcomplex double ztcomplex doubletcprojfsq~
t¤
These functions return the projection of the complex value <VAR>z</VAR> onto
the Riemann sphere. Values with a infinite imaginary part are projected
to positive infinity on the real axis, even if the real part is NaN. If
the real part is infinite, the result is equivalent to
<br><br> <pre><br>
INFINITY + I * copysign (0.0, cimag (z))<br>
</pre>
sq~wt complex.hxq~Mtcomplex float zt
complex floattcprojlsq~
t¤
These functions return the projection of the complex value <VAR>z</VAR> onto
the Riemann sphere. Values with a infinite imaginary part are projected
to positive infinity on the real axis, even if the real part is NaN. If
the real part is infinite, the result is equivalent to
<br><br> <pre><br>
INFINITY + I * copysign (0.0, cimag (z))<br>
</pre>
sq~wt complex.hxq~Ttcomplex long double ztcomplex long doubletcrealsq~
tZ
These functions return the real part of the complex number <VAR>z</VAR>.
sq~wt complex.hxq~[tcomplex double ztdoubletcrealfsq~
tZ
These functions return the real part of the complex number <VAR>z</VAR>.
sq~wt complex.hxq~btcomplex float ztfloattcreallsq~
tZ
These functions return the real part of the complex number <VAR>z</VAR>.
sq~wt complex.hxq~itcomplex long double zt long doubletcryptsq~
t ¼
<br><br> The <CODE>crypt</CODE> function takes a password, <VAR>key</VAR>, as a string, and
a <VAR>salt</VAR> character array which is described below, and returns a
printable ASCII string which starts with another salt. It is believed
that, given the output of the function, the best way to find a <VAR>key</VAR>
that will produce that output is to guess values of <VAR>key</VAR> until the
original value of <VAR>key</VAR> is found.
<br><br> The <VAR>salt</VAR> parameter does two things. Firstly, it selects which
algorithm is used, the MD5-based one or the DES-based one. Secondly, it
makes life harder for someone trying to guess passwords against a file
containing many passwords; without a <VAR>salt</VAR>, an intruder can make a
guess, run <CODE>crypt</CODE> on it once, and compare the result with all the
passwords. With a <VAR>salt</VAR>, the intruder must run <CODE>crypt</CODE> once
for each different salt.
<br><br> For the MD5-based algorithm, the <VAR>salt</VAR> should consist of the string
<CODE>$1$</CODE>, followed by up to 8 characters, terminated by either
another <CODE>$</CODE> or the end of the string. The result of <CODE>crypt</CODE>
will be the <VAR>salt</VAR>, followed by a <CODE>$</CODE> if the salt didn't end
with one, followed by 22 characters from the alphabet
<CODE>./0-9A-Za-z</CODE>, up to 34 characters total. Every character in the
<VAR>key</VAR> is significant.
<br><br> For the DES-based algorithm, the <VAR>salt</VAR> should consist of two
characters from the alphabet <CODE>./0-9A-Za-z</CODE>, and the result of
<CODE>crypt</CODE> will be those two characters followed by 11 more from the
same alphabet, 13 in total. Only the first 8 characters in the
<VAR>key</VAR> are significant.
<br><br> The MD5-based algorithm has no limit on the useful length of the
password used, and is slightly more secure. It is therefore preferred
over the DES-based algorithm.
<br><br> When the user enters their password for the first time, the <VAR>salt</VAR>
should be set to a new string which is reasonably random. To verify a
password against the result of a previous call to <CODE>crypt</CODE>, pass
the result of the previous call as the <VAR>salt</VAR>.
sq~wtcrypt.hxq~pt!const char *key, const char *salttchar *tcrypt_rsq~
t§
<br><br> The <CODE>crypt_r</CODE> function does the same thing as <CODE>crypt</CODE>, but
takes an extra parameter which includes space for its result (among
other things), so it can be reentrant. <CODE>data-></CODE>initialized must be
cleared to zero before the first time <CODE>crypt_r</CODE> is called.
<br><br> The <CODE>crypt_r</CODE> function is a GNU extension.
sq~wtcrypt.hxq~wt=const char *key, const char *salt, {struct crypt_data *} datatchar *tcsinsq~
tÑ
These functions return the complex sine of <VAR>z</VAR>.
The mathematical definition of the complex sine is
<br><br>
sin (z) = 1/(2*i) * (exp (z*i) - exp (-z*i)).
sq~wt complex.hxq~~tcomplex double ztcomplex doubletcsinfsq~
tÑ
These functions return the complex sine of <VAR>z</VAR>.
The mathematical definition of the complex sine is
<br><br>
sin (z) = 1/(2*i) * (exp (z*i) - exp (-z*i)).
sq~wt complex.hxq~…tcomplex float zt
complex floattcsinhsq~
tµ
These functions return the complex hyperbolic sine of <VAR>z</VAR>, defined
mathematically as <CODE>(exp (<VAR>z</VAR>) - exp (-<VAR>z</VAR>)) / 2</CODE>.
sq~wt complex.hxq~Œtcomplex double ztcomplex doubletcsinhfsq~
tµ
These functions return the complex hyperbolic sine of <VAR>z</VAR>, defined
mathematically as <CODE>(exp (<VAR>z</VAR>) - exp (-<VAR>z</VAR>)) / 2</CODE>.
sq~wt complex.hxq~“tcomplex float zt
complex floattcsinhlsq~
tµ
These functions return the complex hyperbolic sine of <VAR>z</VAR>, defined
mathematically as <CODE>(exp (<VAR>z</VAR>) - exp (-<VAR>z</VAR>)) / 2</CODE>.
sq~wt complex.hxq~štcomplex long double ztcomplex long doubletcsinlsq~
tÑ
These functions return the complex sine of <VAR>z</VAR>.
The mathematical definition of the complex sine is
<br><br>
sin (z) = 1/(2*i) * (exp (z*i) - exp (-z*i)).
sq~wt complex.hxq~¡tcomplex long double ztcomplex long doubletcsqrtsq~
t»
These functions return the complex square root of the argument <VAR>z</VAR>. Unlike
the real-valued functions, they are defined for all values of <VAR>z</VAR>.
sq~wt complex.hxq~¨tcomplex double ztcomplex doubletcsqrtfsq~
t»
These functions return the complex square root of the argument <VAR>z</VAR>. Unlike
the real-valued functions, they are defined for all values of <VAR>z</VAR>.
sq~wt complex.hxq~¯tcomplex float zt
complex floattcsqrtlsq~
t»
These functions return the complex square root of the argument <VAR>z</VAR>. Unlike
the real-valued functions, they are defined for all values of <VAR>z</VAR>.
sq~wt complex.hxq~¶tcomplex long double ztcomplex long doubletctansq~
t«
These functions return the complex tangent of <VAR>z</VAR>.
The mathematical definition of the complex tangent is
<br><br>
tan (z) = -i * (exp (z*i) - exp (-z*i)) / (exp (z*i) + exp (-z*i))
<br><br>
The complex tangent has poles at pi/2 + 2n, where n is an
integer. <CODE>ctan</CODE> may signal overflow if <VAR>z</VAR> is too close to a
pole.
sq~wt complex.hxq~½tcomplex double ztcomplex doubletctanfsq~
t«
These functions return the complex tangent of <VAR>z</VAR>.
The mathematical definition of the complex tangent is
<br><br>
tan (z) = -i * (exp (z*i) - exp (-z*i)) / (exp (z*i) + exp (-z*i))
<br><br>
The complex tangent has poles at pi/2 + 2n, where n is an
integer. <CODE>ctan</CODE> may signal overflow if <VAR>z</VAR> is too close to a
pole.
sq~wt complex.hxq~Ätcomplex float zt
complex floattctanhsq~
tµ
These functions return the complex hyperbolic tangent of <VAR>z</VAR>,
defined mathematically as <CODE>csinh (<VAR>z</VAR>) / ccosh (<VAR>z</VAR>)</CODE>.
sq~wt complex.hxq~Ëtcomplex double ztcomplex doubletctanhfsq~
tµ
These functions return the complex hyperbolic tangent of <VAR>z</VAR>,
defined mathematically as <CODE>csinh (<VAR>z</VAR>) / ccosh (<VAR>z</VAR>)</CODE>.
sq~wt complex.hxq~Òtcomplex float zt
complex floattctanhlsq~
tµ
These functions return the complex hyperbolic tangent of <VAR>z</VAR>,
defined mathematically as <CODE>csinh (<VAR>z</VAR>) / ccosh (<VAR>z</VAR>)</CODE>.
sq~wt complex.hxq~Ùtcomplex long double ztcomplex long doubletctanlsq~
t«
These functions return the complex tangent of <VAR>z</VAR>.
The mathematical definition of the complex tangent is
<br><br>
tan (z) = -i * (exp (z*i) - exp (-z*i)) / (exp (z*i) + exp (-z*i))
<br><br>
The complex tangent has poles at pi/2 + 2n, where n is an
integer. <CODE>ctan</CODE> may signal overflow if <VAR>z</VAR> is too close to a
pole.
sq~wt complex.hxq~àtcomplex long double ztcomplex long doubletctermidsq~
t¯
The <CODE>ctermid</CODE> function returns a string containing the file name of
the controlling terminal for the current process. If <VAR>string</VAR> is
not a null pointer, it should be an array that can hold at least
<CODE>L_ctermid</CODE> characters; the string is returned in this array.
Otherwise, a pointer to a string in a static area is returned, which
might get overwritten on subsequent calls to this function.
<br><br> An empty string is returned if the file name cannot be determined for
any reason. Even if a file name is returned, access to the file it
represents is not guaranteed.
sq~wtstdio.hxq~çt char *stringtchar *tctimesq~
tç
The <CODE>ctime</CODE> function is similar to <CODE>asctime</CODE>, except that you
specify the calendar time argument as a <CODE>time_t</CODE> simple time value
rather than in broken-down local time format. It is equivalent to
<br><br> <pre><br>
asctime (localtime (<VAR>time</VAR>))<br>
</pre>
<br><br> <CODE>ctime</CODE> sets the variable <CODE>tzname</CODE>, because <CODE>localtime</CODE>
does so. .
sq~wttime.hxq~îtconst time_t *timetchar *tctime_rsq~
t
This function is similar to <CODE>ctime</CODE>, but places the result in the
string pointed to by <VAR>buffer</VAR>. It is equivalent to (written using
gcc extensions, ):
<br><br> <pre><br>
({ struct tm tm; asctime_r (localtime_r (time, &tm), buf); })<br>
</pre>
<br><br> If no error occurred the function returns a pointer to the string the
result was written into, i.e., it returns <VAR>buffer</VAR>. Otherwise
return <CODE>NULL</CODE>.
sq~wttime.hxq~õt const time_t *time, char *buffertchar *tcuseridsq~
tç
The <CODE>cuserid</CODE> function returns a pointer to a string containing a
user name associated with the effective ID of the process. If
<VAR>string</VAR> is not a null pointer, it should be an array that can hold
at least <CODE>L_cuserid</CODE> characters; the string is returned in this
array. Otherwise, a pointer to a string in a static area is returned.
This string is statically allocated and might be overwritten on
subsequent calls to this function or to <CODE>getlogin</CODE>.
<br><br> The use of this function is deprecated since it is marked to be
withdrawn in XPG4.2 and has already been removed from newer revisions of
POSIX.1.
sq~wtstdio.hxq~üt char *stringtchar *t dcgettextsq~
tš
The <CODE>dcgettext</CODE> adds another argument to those which
<CODE>dgettext</CODE> takes. This argument <VAR>category</VAR> specifies the last
piece of information needed to localize the message catalog. I.e., the
domain name and the locale category exactly specify which message
catalog has to be used (relative to a given directory, see below).
<br><br> The <CODE>dgettext</CODE> function can be expressed in terms of
<CODE>dcgettext</CODE> by using
<br><br> <pre><br>
dcgettext (domain, string, LC_MESSAGES)<br>
</pre><br>
<br><br> <br>
instead of<br>
<br><br> <pre><br>
dgettext (domain, string)<br>
</pre>
<br><br> This also shows which values are expected for the third parameter. One
has to use the available selectors for the categories available in
<TT>locale.h</TT>. Normally the available values are <CODE>LC_CTYPE</CODE>,
<CODE>LC_COLLATE</CODE>, <CODE>LC_MESSAGES</CODE>, <CODE>LC_MONETARY</CODE>,
<CODE>LC_NUMERIC</CODE>, and <CODE>LC_TIME</CODE>. Please note that <CODE>LC_ALL</CODE>
must not be used and even though the names might suggest this, there is
no relation to the environments variables of this name.
<br><br> The <CODE>dcgettext</CODE> function is only implemented for compatibility with
other systems which have <CODE>gettext</CODE> functions. There is not really
any situation where it is necessary (or useful) to use a different value
but <CODE>LC_MESSAGES</CODE> in for the <VAR>category</VAR> parameter. We are
dealing with messages here and any other choice can only be irritating.
<br><br> As for <CODE>gettext</CODE> the return value type is <CODE>char *</CODE> which is an
anachronism. The returned string must never be modified.
sq~wt libintl.hxq~t7const char *domainname, const char *msgid, int categorytchar *t
dcngettextsq~
tU
The <CODE>dcngettext</CODE> is similar to the <CODE>dcgettext</CODE> function in the
way the message catalog is selected. The difference is that it takes
two extra parameter to provide the correct plural form. These two
parameters are handled in the same way <CODE>ngettext</CODE> handles them.
sq~wt libintl.hxq~
t]const char *domain, const char *msgid1, const char *msgid2, unsigned long int n, int categorytchar *t
des_setparitysq~
tÏ
<br><br> The function <CODE>des_setparity</CODE> changes the 64-bit <VAR>key</VAR>, stored
packed in 8-bit bytes, to have odd parity by altering the low bits of
each byte.
sq~wtrpc/des_crypt.hxq~t char *keytvoidtdgettextsq~
t�
The <CODE>dgettext</CODE> functions acts just like the <CODE>gettext</CODE>
function. It only takes an additional first argument <VAR>domainname</VAR>
which guides the selection of the message catalogs which are searched
for the translation. If the <VAR>domainname</VAR> parameter is the null
pointer the <CODE>dgettext</CODE> function is exactly equivalent to
<CODE>gettext</CODE> since the default value for the domain name is used.
<br><br> As for <CODE>gettext</CODE> the return value type is <CODE>char *</CODE> which is an
anachronism. The returned string must never be modified.
sq~wt libintl.hxq~t)const char *domainname, const char *msgidtchar *tdifftimesq~
t'
The <CODE>difftime</CODE> function returns the number of seconds of elapsed
time between calendar time <VAR>time1</VAR> and calendar time <VAR>time0</VAR>, as
a value of type <CODE>double</CODE>. The difference ignores leap seconds
unless leap second support is enabled.
<br><br> In the GNU system, you can simply subtract <CODE>time_t</CODE> values. But on
other systems, the <CODE>time_t</CODE> data type might use some other encoding
where subtraction doesn't work directly.
sq~wttime.hxq~ttime_t time1, time_t time0tdoubletdirfdsq~
tn
The function <CODE>dirfd</CODE> returns the file descriptor associated with
the directory stream <VAR>dirstream</VAR>. This descriptor can be used until
the directory is closed with <CODE>closedir</CODE>. If the directory stream
implementation is not using file descriptors the return value is
<CODE>-1</CODE>.
sq~wtdirent.hxq~&tDIR *dirstreamtinttdirnamesq~
t•
The <CODE>dirname</CODE> function is the compliment to the XPG version of
<CODE>basename</CODE>. It returns the parent directory of the file specified
by <VAR>path</VAR>. If <VAR>path</VAR> is <CODE>NULL</CODE>, an empty string, or
contains no '/' characters, then "." is returned. The prototype for this
function can be found in <TT>libgen.h</TT>.
sq~wtlibgen.hxq~-t
char *pathtchar *tdivsq~
tŠ
This function <CODE>div</CODE> computes the quotient and remainder from
the division of <VAR>numerator</VAR> by <VAR>denominator</VAR>, returning the
result in a structure of type <CODE>div_t</CODE>.
<br><br> If the result cannot be represented (as in a division by zero), the
behavior is undefined.
<br><br> Here is an example, albeit not a very useful one.
<br><br> <pre><br>
div_t result;<br>
result = div (20, -6);<br>
</pre>
<br><br>
Now <CODE>result.quot</CODE> is <CODE>-3</CODE> and <CODE>result.rem</CODE> is <CODE>2</CODE>.
sq~wtstdlib.hxq~4tint numerator, int denominatortdiv_tt dngettextsq~
tS
The <CODE>dngettext</CODE> is similar to the <CODE>dgettext</CODE> function in the
way the message catalog is selected. The difference is that it takes
two extra parameter to provide the correct plural form. These two
parameters are handled in the same way <CODE>ngettext</CODE> handles them.
sq~wt libintl.hxq~;tOconst char *domain, const char *msgid1, const char *msgid2, unsigned long int ntchar *tdrand48sq~
t)
This function returns a <CODE>double</CODE> value in the range of <CODE>0.0</CODE>
to <CODE>1.0</CODE> (exclusive). The random bits are determined by the global
state of the random number generator in the C library.
<br><br> Since the <CODE>double</CODE> type according to IEEE 754 has a 52-bit
mantissa this means 4 bits are not initialized by the random number
generator. These are (of course) chosen to be the least significant
bits and they are initialized to <CODE>0</CODE>.
sq~wtstdlib.hxq~Btvoidtdoublet drand48_rsq~
t½
This function is equivalent to the <CODE>drand48</CODE> function with the
difference that it does not modify the global random number generator
parameters but instead the parameters in the buffer supplied through the
pointer <VAR>buffer</VAR>. The random number is returned in the variable
pointed to by <VAR>result</VAR>.
<br><br> The return value of the function indicates whether the call succeeded.
If the value is less than <CODE>0</CODE> an error occurred and <VAR>errno</VAR> is
set to indicate the problem.
<br><br> This function is a GNU extension and should not be used in portable
programs.
sq~wtstdlib.hxq~It+struct drand48_data *buffer, double *resulttinttdremsq~
t;
These functions are like <CODE>fmod</CODE> except that they round the
internal quotient <VAR>n</VAR> to the nearest integer instead of towards zero
to an integer. For example, <CODE>drem (6.5, 2.3)</CODE> returns <CODE>-0.4</CODE>,
which is <CODE>6.5</CODE> minus <CODE>6.9</CODE>.
<br><br> The absolute value of the result is less than or equal to half the
absolute value of the <VAR>denominator</VAR>. The difference between
<CODE>fmod (<VAR>numerator</VAR>, <VAR>denominator</VAR>)</CODE> and <CODE>drem
(<VAR>numerator</VAR>, <VAR>denominator</VAR>)</CODE> is always either
<VAR>denominator</VAR>, minus <VAR>denominator</VAR>, or zero.
<br><br> If <VAR>denominator</VAR> is zero, <CODE>drem</CODE> signals a domain error.
sq~wtmath.hxq~Pt$double numerator, double denominatortdoubletdremfsq~
t;
These functions are like <CODE>fmod</CODE> except that they round the
internal quotient <VAR>n</VAR> to the nearest integer instead of towards zero
to an integer. For example, <CODE>drem (6.5, 2.3)</CODE> returns <CODE>-0.4</CODE>,
which is <CODE>6.5</CODE> minus <CODE>6.9</CODE>.
<br><br> The absolute value of the result is less than or equal to half the
absolute value of the <VAR>denominator</VAR>. The difference between
<CODE>fmod (<VAR>numerator</VAR>, <VAR>denominator</VAR>)</CODE> and <CODE>drem
(<VAR>numerator</VAR>, <VAR>denominator</VAR>)</CODE> is always either
<VAR>denominator</VAR>, minus <VAR>denominator</VAR>, or zero.
<br><br> If <VAR>denominator</VAR> is zero, <CODE>drem</CODE> signals a domain error.
sq~wtmath.hxq~Wt"float numerator, float denominatortfloattdremlsq~
t;
These functions are like <CODE>fmod</CODE> except that they round the
internal quotient <VAR>n</VAR> to the nearest integer instead of towards zero
to an integer. For example, <CODE>drem (6.5, 2.3)</CODE> returns <CODE>-0.4</CODE>,
which is <CODE>6.5</CODE> minus <CODE>6.9</CODE>.
<br><br> The absolute value of the result is less than or equal to half the
absolute value of the <VAR>denominator</VAR>. The difference between
<CODE>fmod (<VAR>numerator</VAR>, <VAR>denominator</VAR>)</CODE> and <CODE>drem
(<VAR>numerator</VAR>, <VAR>denominator</VAR>)</CODE> is always either
<VAR>denominator</VAR>, minus <VAR>denominator</VAR>, or zero.
<br><br> If <VAR>denominator</VAR> is zero, <CODE>drem</CODE> signals a domain error.
sq~wtmath.hxq~^t.long double numerator, long double denominatort long doubletdupsq~
tè
This function copies descriptor <VAR>old</VAR> to the first available
descriptor number (the first number not currently open). It is
equivalent to <CODE>fcntl (<VAR>old</VAR>, F_DUPFD, 0)</CODE>.
sq~wtunistd.hxq~etint oldtinttdup2sq~
tÆ
This function copies the descriptor <VAR>old</VAR> to descriptor number
<VAR>new</VAR>.
<br><br> If <VAR>old</VAR> is an invalid descriptor, then <CODE>dup2</CODE> does nothing; it
does not close <VAR>new</VAR>. Otherwise, the new duplicate of <VAR>old</VAR>
replaces any previous meaning of descriptor <VAR>new</VAR>, as if <VAR>new</VAR>
were closed first.
<br><br> If <VAR>old</VAR> and <VAR>new</VAR> are different numbers, and <VAR>old</VAR> is a
valid descriptor number, then <CODE>dup2</CODE> is equivalent to:
<br><br> <pre><br>
close (<VAR>new</VAR>);<br>
fcntl (<VAR>old</VAR>, F_DUPFD, <VAR>new</VAR>)<br>
</pre>
<br><br> However, <CODE>dup2</CODE> does this atomically; there is no instant in the
middle of calling <CODE>dup2</CODE> at which <VAR>new</VAR> is closed and not yet a
duplicate of <VAR>old</VAR>.
sq~wtunistd.hxq~ltint old, int newtintt ecb_cryptsq~
t |
<br><br> The function <CODE>ecb_crypt</CODE> encrypts or decrypts one or more blocks
using DES. Each block is encrypted independently.
<br><br> The <VAR>blocks</VAR> and the <VAR>key</VAR> are stored packed in 8-bit bytes, so
that the first bit of the key is the most-significant bit of
<CODE>key[0]</CODE> and the 63rd bit of the key is stored as the
least-significant bit of <CODE>key[7]</CODE>. The <VAR>key</VAR> should have the
correct parity.
<br><br> <VAR>len</VAR> is the number of bytes in <VAR>blocks</VAR>. It should be a
multiple of 8 (so that there is a whole number of blocks to encrypt).
<VAR>len</VAR> is limited to a maximum of <CODE>DES_MAXDATA</CODE> bytes.
<br><br> The result of the encryption replaces the input in <VAR>blocks</VAR>.
<br><br> The <VAR>mode</VAR> parameter is the bitwise OR of two of the following:
<br><br> <DL>
<DT><CODE>DES_ENCRYPT</CODE>
<DD>
This constant, used in the <VAR>mode</VAR> parameter, specifies that
<VAR>blocks</VAR> is to be encrypted.
<br><br> <DT><CODE>DES_DECRYPT</CODE>
<DD>
This constant, used in the <VAR>mode</VAR> parameter, specifies that
<VAR>blocks</VAR> is to be decrypted.
<br><br> <DT><CODE>DES_HW</CODE>
<DD>
This constant, used in the <VAR>mode</VAR> parameter, asks to use a hardware
device. If no hardware device is available, encryption happens anyway,
but in software.
<br><br> <DT><CODE>DES_SW</CODE>
<DD>
This constant, used in the <VAR>mode</VAR> parameter, specifies that no
hardware device is to be used.
</DL>
<br><br> The result of the function will be one of these values:
<br><br> <DL>
<DT><CODE>DESERR_NONE</CODE>
<DD>
The encryption succeeded.
<br><br> <DT><CODE>DESERR_NOHWDEVICE</CODE>
<DD>
The encryption succeeded, but there was no hardware device available.
<br><br> <DT><CODE>DESERR_HWERROR</CODE>
<DD>
The encryption failed because of a hardware problem.
<br><br> <DT><CODE>DESERR_BADPARAM</CODE>
<DD>
The encryption failed because of a bad parameter, for instance <VAR>len</VAR>
is not a multiple of 8 or <VAR>len</VAR> is larger than <CODE>DES_MAXDATA</CODE>.
</DL>
sq~wtrpc/des_crypt.hxq~st4char *key, char *blocks, unsigned len, unsigned modetinttecvtsq~
tØ
The function <CODE>ecvt</CODE> converts the floating-point number <VAR>value</VAR>
to a string with at most <VAR>ndigit</VAR> decimal digits. The
returned string contains no decimal point or sign. The first digit of
the string is non-zero (unless <VAR>value</VAR> is actually zero) and the
last digit is rounded to nearest. <CODE>*<VAR>decpt</VAR></CODE> is set to the
index in the string of the first digit after the decimal point.
<CODE>*<VAR>neg</VAR></CODE> is set to a nonzero value if <VAR>value</VAR> is negative,
zero otherwise.
<br><br> If <VAR>ndigit</VAR> decimal digits would exceed the precision of a
<CODE>double</CODE> it is reduced to a system-specific value.
<br><br> The returned string is statically allocated and overwritten by each call
to <CODE>ecvt</CODE>.
<br><br> If <VAR>value</VAR> is zero, it is implementation defined whether
<CODE>*<VAR>decpt</VAR></CODE> is <CODE>0</CODE> or <CODE>1</CODE>.
<br><br> For example: <CODE>ecvt (12.3, 5, &d, &n)</CODE> returns <CODE>"12300"</CODE>
and sets <VAR>d</VAR> to <CODE>2</CODE> and <VAR>n</VAR> to <CODE>0</CODE>.
sq~wtstdlib.hxq~zt.double value, int ndigit, int *decpt, int *negtchar *tecvt_rsq~
tj
The <CODE>ecvt_r</CODE> function is the same as <CODE>ecvt</CODE>, except
that it places its result into the user-specified buffer pointed to by
<VAR>buf</VAR>, with length <VAR>len</VAR>. The return value is <CODE>-1</CODE> in
case of an error and zero otherwise.
<br><br> This function is a GNU extension.
sq~wtstdlib.hxq~�tEdouble value, int ndigit, int *decpt, int *neg, char *buf, size_t lentinttencryptsq~
tÒ
<br><br> The <CODE>encrypt</CODE> function encrypts <VAR>block</VAR> if
<VAR>edflag</VAR> is 0, otherwise it decrypts <VAR>block</VAR>, using a key
previously set by <CODE>setkey</CODE>. The result is
placed in <VAR>block</VAR>.
<br><br> Like <CODE>setkey</CODE>, <VAR>block</VAR> is specified as an array of 64 bits each
stored in a <CODE>char</CODE>, but there are no parity bits in <VAR>block</VAR>.
sq~wtcrypt.hxq~ˆtchar *block, int edflagtvoidt encrypt_rsq~
tS
<br><br> These are reentrant versions of <CODE>setkey</CODE> and <CODE>encrypt</CODE>. The
only difference is the extra parameter, which stores the expanded
version of <VAR>key</VAR>. Before calling <CODE>setkey_r</CODE> the first time,
<CODE>data->initialized</CODE> must be cleared to zero.
sq~wtcrypt.hxq~�t3char *block, int edflag, {struct crypt_data *} datatvoidtendfsentsq~
tÈ
This function makes sure that all resources acquired by a prior call to
<CODE>setfsent</CODE> (explicitly or implicitly by calling <CODE>getfsent</CODE>) are
freed.
sq~wtfstab.hxq~–tvoidtvoidtendgrentsq~
t}
This function closes the internal stream used by <CODE>getgrent</CODE> or
<CODE>getgrent_r</CODE>.
sq~wtgrp.hxq~�tvoidtvoidt
endhostentsq~
t:
This function closes the hosts database.
sq~wtnetdb.hxq~¤tvoidtvoidt endmntentsq~
tP
This function takes for the <VAR>stream</VAR> parameter a file handle which
previously was returned from the <CODE>setmntent</CODE> call.
<CODE>endmntent</CODE> closes the stream and frees all resources.
<br><br> The return value is 1 unless an error occurred in which case it
is 0.
sq~wtmntent.hxq~«t FILE *streamtintt endnetentsq~
t=
This function closes the networks database.
sq~wtnetdb.hxq~²tvoidtvoidt endnetgrentsq~
tæ
This function frees all buffers which were allocated to process the last
selected netgroup. As a result all string pointers returned by calls
to <CODE>getnetgrent</CODE> are invalid afterwards.
sq~wtnetdb.hxq~¹tvoidtvoidt endprotoentsq~
t>
This function closes the protocols database.
sq~wtnetdb.hxq~Àtvoidtvoidtendpwentsq~
t}
This function closes the internal stream used by <CODE>getpwent</CODE> or
<CODE>getpwent_r</CODE>.
sq~wtpwd.hxq~Çtvoidtvoidt
endserventsq~
t=
This function closes the services database.
sq~wtnetdb.hxq~Îtvoidtvoidtendutentsq~
tD
This function closes the user accounting database.
sq~wtutmp.hxq~Õtvoidtvoidt endutxentsq~
t‘
This function is similar to <CODE>endutent</CODE>. On the GNU system it is
simply an alias for <CODE>endutent</CODE>.
sq~wtutmpx.hxq~Ütvoidtvoidtenvz_addsq~
tä
The <CODE>envz_add</CODE> function adds an entry to <CODE>*<VAR>envz</VAR></CODE>
(updating <CODE>*<VAR>envz</VAR></CODE> and <CODE>*<VAR>envz_len</VAR></CODE>) with the name
<VAR>name</VAR>, and value <VAR>value</VAR>. If an entry with the same name
already exists in <VAR>envz</VAR>, it is removed first. If <VAR>value</VAR> is
<CODE>0</CODE>, then the new entry will the special null type of entry
(mentioned above).
sq~wtenvz.hxq~ãtBchar **envz, size_t *envz_len, const char *name, const char *valueterror_tt
envz_entrysq~
tf
The <CODE>envz_entry</CODE> function finds the entry in <VAR>envz</VAR> with the name
<VAR>name</VAR>, and returns a pointer to the whole entry---that is, the argz
element which begins with <VAR>name</VAR> followed by a <CODE>'='</CODE> character. If
there is no entry with that name, <CODE>0</CODE> is returned.
sq~wtenvz.hxq~êt3const char *envz, size_t envz_len, const char *nametchar *tenvz_getsq~
td
The <CODE>envz_get</CODE> function finds the entry in <VAR>envz</VAR> with the name
<VAR>name</VAR> (like <CODE>envz_entry</CODE>), and returns a pointer to the value
portion of that entry (following the <CODE>'='</CODE>). If there is no entry with
that name (or only a null entry), <CODE>0</CODE> is returned.
sq~wtenvz.hxq~ñt3const char *envz, size_t envz_len, const char *nametchar *t
envz_mergesq~
tŽ
The <CODE>envz_merge</CODE> function adds each entry in <VAR>envz2</VAR> to <VAR>envz</VAR>,
as if with <CODE>envz_add</CODE>, updating <CODE>*<VAR>envz</VAR></CODE> and
<CODE>*<VAR>envz_len</VAR></CODE>. If <VAR>override</VAR> is true, then values in <VAR>envz2</VAR>
will supersede those with the same name in <VAR>envz</VAR>, otherwise not.
<br><br> Null entries are treated just like other entries in this respect, so a null
entry in <VAR>envz</VAR> can prevent an entry of the same name in <VAR>envz2</VAR> from
being added to <VAR>envz</VAR>, if <VAR>override</VAR> is false.
sq~wtenvz.hxq~øtPchar **envz, size_t *envz_len, const char *envz2, size_t envz2_len, int overrideterror_tt
envz_stripsq~
t¼
The <CODE>envz_strip</CODE> function removes any null entries from <VAR>envz</VAR>,
updating <CODE>*<VAR>envz</VAR></CODE> and <CODE>*<VAR>envz_len</VAR></CODE>.
sq~wtenvz.hxq~ÿtchar **envz, size_t *envz_lentvoidterand48sq~
té
This function returns a <CODE>double</CODE> value in the range of <CODE>0.0</CODE>
to <CODE>1.0</CODE> (exclusive), similarly to <CODE>drand48</CODE>. The argument is
an array describing the state of the random number generator.
<br><br> This function can be called subsequently since it updates the array to
guarantee random numbers. The array should have been initialized before
initial use to obtain reproducible results.
sq~wtstdlib.hxq~tunsigned short int xsubi[3]tdoublet erand48_rsq~
tš
The <CODE>erand48_r</CODE> function works like <CODE>erand48</CODE>, but in addition
it takes an argument <VAR>buffer</VAR> which describes the random number
generator. The state of the random number generator is taken from the
<CODE>xsubi</CODE> array, the parameters for the congruential formula from the
global random number generator data. The random number is returned in
the variable pointed to by <VAR>result</VAR>.
<br><br> The return value is non-negative if the call succeeded.
<br><br> This function is a GNU extension and should not be used in portable
programs.
sq~wtstdlib.hxq~
tHunsigned short int xsubi[3], struct drand48_data *buffer, double *resulttintterfsq~
tè
<CODE>erf</CODE> returns the error function of <VAR>x</VAR>. The error
function is defined as
<pre><br>
erf (x) = 2/sqrt(pi) * integral from 0 to x of exp(-t^2) dt<br>
</pre>
sq~wtmath.hxq~tdouble xtdoubleterfcsq~
t¬
<CODE>erfc</CODE> returns <CODE>1.0 - erf(<VAR>x</VAR>)</CODE>, but computed in a
fashion that avoids round-off error when <VAR>x</VAR> is large.
sq~wtmath.hxq~tdouble xtdoubleterfcfsq~
t¬
<CODE>erfc</CODE> returns <CODE>1.0 - erf(<VAR>x</VAR>)</CODE>, but computed in a
fashion that avoids round-off error when <VAR>x</VAR> is large.
sq~wtmath.hxq~"tfloat xtfloatterfclsq~
t¬
<CODE>erfc</CODE> returns <CODE>1.0 - erf(<VAR>x</VAR>)</CODE>, but computed in a
fashion that avoids round-off error when <VAR>x</VAR> is large.
sq~wtmath.hxq~)t
long double xt long doubleterffsq~
tè
<CODE>erf</CODE> returns the error function of <VAR>x</VAR>. The error
function is defined as
<pre><br>
erf (x) = 2/sqrt(pi) * integral from 0 to x of exp(-t^2) dt<br>
</pre>
sq~wtmath.hxq~0tfloat xtfloatterflsq~
tè
<CODE>erf</CODE> returns the error function of <VAR>x</VAR>. The error
function is defined as
<pre><br>
erf (x) = 2/sqrt(pi) * integral from 0 to x of exp(-t^2) dt<br>
</pre>
sq~wtmath.hxq~7t
long double xt long doubleterrsq~
t`
The <CODE>err</CODE> function is roughly equivalent to a call like
<pre><br>
error (status, errno, format, the parameters)<br>
</pre>
except that the global variables <CODE>error</CODE> respects and modifies
are not used and that the program is exited even if <VAR>status</VAR> is zero.
sq~wterr.hxq~>t#int status, const char *format, ...tvoidterrorsq~
tŽ
The <CODE>error</CODE> function can be used to report general problems during
program execution. The <VAR>format</VAR> argument is a format string just
like those given to the <CODE>printf</CODE> family of functions. The
arguments required for the format can follow the <VAR>format</VAR> parameter.
Just like <CODE>perror</CODE>, <CODE>error</CODE> also can report an error code in
textual form. But unlike <CODE>perror</CODE> the error value is explicitly
passed to the function in the <VAR>errnum</VAR> parameter. This eliminates
the problem mentioned above that the error reporting function must be
called immediately after the function causing the error since otherwise
<CODE>errno</CODE> might have a different value.
<br><br> The <CODE>error</CODE> prints first the program name. If the application
defined a global variable <CODE>error_print_progname</CODE> and points it to a
function this function will be called to print the program name.
Otherwise the string from the global variable <CODE>program_name</CODE> is
used. The program name is followed by a colon and a space which in turn
is followed by the output produced by the format string. If the
<VAR>errnum</VAR> parameter is non-zero the format string output is followed
by a colon and a space, followed by the error message for the error code
<VAR>errnum</VAR>. In any case is the output terminated with a newline.
<br><br> The output is directed to the <CODE>stderr</CODE> stream. If the
<CODE>stderr</CODE> wasn't oriented before the call it will be narrow-oriented
afterwards.
<br><br> The function will return unless the <VAR>status</VAR> parameter has a
non-zero value. In this case the function will call <CODE>exit</CODE> with
the <VAR>status</VAR> value for its parameter and therefore never return. If
<CODE>error</CODE> returns the global variable <CODE>error_message_count</CODE> is
incremented by one to keep track of the number of errors reported.
sq~wterrno.hterror.hxq~Et/int status, int errnum, const char *format, ...tvoidt
error_at_linesq~
tª
<br><br> The <CODE>error_at_line</CODE> function is very similar to the <CODE>error</CODE>
function. The only difference are the additional parameters <VAR>fname</VAR>
and <VAR>lineno</VAR>. The handling of the other parameters is identical to
that of <CODE>error</CODE> except that between the program name and the string
generated by the format string additional text is inserted.
<br><br> Directly following the program name a colon, followed by the file name
pointer to by <VAR>fname</VAR>, another colon, and a value of <VAR>lineno</VAR> is
printed.
<br><br> This additional output of course is meant to be used to locate an error
in an input file (like a programming language source code file etc).
<br><br> If the global variable <CODE>error_one_per_line</CODE> is set to a non-zero
value <CODE>error_at_line</CODE> will avoid printing consecutive messages for
the same file and line. Repetition which are not directly following
each other are not caught.
<br><br> Just like <CODE>error</CODE> this function only returned if <VAR>status</VAR> is
zero. Otherwise <CODE>exit</CODE> is called with the non-zero value. If
<CODE>error</CODE> returns the global variable <CODE>error_message_count</CODE> is
incremented by one to keep track of the number of errors reported.
sq~wterror.hxq~MtWint status, int errnum, const char *fname, unsigned int lineno, const char *format, ...tvoidterrxsq~
t¾
The <CODE>errx</CODE> function is roughly equivalent to a call like
<pre><br>
error (status, 0, format, the parameters)<br>
</pre>
except that the global variables <CODE>error</CODE> respects and modifies
are not used and that the program is exited even if <VAR>status</VAR>
is zero. The difference to <CODE>err</CODE> is that no error number
string is printed.
sq~wterr.hxq~Tt#int status, const char *format, ...tvoidtexeclsq~
t×
This is similar to <CODE>execv</CODE>, but the <VAR>argv</VAR> strings are
specified individually instead of as an array. A null pointer must be
passed as the last such argument.
sq~wtunistd.hxq~[t+const char *filename, const char *arg0, ...tinttexeclesq~
ts
This is similar to <CODE>execl</CODE>, but permits you to specify the
environment for the new program explicitly. The environment argument is
passed following the null pointer that marks the last <VAR>argv</VAR>
argument, and should be an array of strings in the same format as for
the <CODE>environ</CODE> variable.
sq~wtunistd.hxq~bt>const char *filename, const char *arg0, char *const env[], ...tinttexeclpsq~
tž
This function is like <CODE>execl</CODE>, except that it performs the same
file name searching as the <CODE>execvp</CODE> function.
sq~wtunistd.hxq~it+const char *filename, const char *arg0, ...tinttexecvsq~
t8
The <CODE>execv</CODE> function executes the file named by <VAR>filename</VAR> as a
new process image.
<br><br> The <VAR>argv</VAR> argument is an array of null-terminated strings that is
used to provide a value for the <CODE>argv</CODE> argument to the <CODE>main</CODE>
function of the program to be executed. The last element of this array
must be a null pointer. By convention, the first element of this array
is the file name of the program sans directory names. , for full details on how programs can access these arguments.
<br><br> The environment for the new process image is taken from the
<CODE>environ</CODE> variable of the current process image; see
Environment Variables, for information about environments.
sq~wtunistd.hxq~pt(const char *filename, char *const argv[]tinttexecvesq~
t6
This is similar to <CODE>execv</CODE>, but permits you to specify the environment
for the new program explicitly as the <VAR>env</VAR> argument. This should
be an array of strings in the same format as for the <CODE>environ</CODE>
variable; see Environment Access.
sq~wtunistd.hxq~wt;const char *filename, char *const argv[], char *const env[]tinttexecvpsq~
t
The <CODE>execvp</CODE> function is similar to <CODE>execv</CODE>, except that it
searches the directories listed in the <CODE>PATH</CODE> environment variable
to find the full file name of a
file from <VAR>filename</VAR> if <VAR>filename</VAR> does not contain a slash.
<br><br> This function is useful for executing system utility programs, because
it looks for them in the places that the user has chosen. Shells use it
to run the commands that users type.
sq~wtunistd.hxq~~t(const char *filename, char *const argv[]tinttexitsq~
t0
The <CODE>exit</CODE> function tells the system that the program is done, which
causes it to terminate the process.
<br><br> <VAR>status</VAR> is the program's exit status, which becomes part of the
process' termination status. This function does not return.
sq~wtstdlib.hxq~…t
int statustvoidtexpsq~
t
These functions compute <CODE>e</CODE> (the base of natural logarithms) raised
to the power <VAR>x</VAR>.
<br><br> If the magnitude of the result is too large to be representable,
<CODE>exp</CODE> signals overflow.
sq~wtmath.hxq~Œtdouble xtdoubletexp10sq~
tf
These functions compute <CODE>10</CODE> raised to the power <VAR>x</VAR>.
Mathematically, <CODE>exp10 (x)</CODE> is the same as <CODE>exp (x * log (10))</CODE>.
<br><br> These functions are GNU extensions. The name <CODE>exp10</CODE> is
preferred, since it is analogous to <CODE>exp</CODE> and <CODE>exp2</CODE>.
sq~wtmath.hxq~“tdouble xtdoubletexp10fsq~
tf
These functions compute <CODE>10</CODE> raised to the power <VAR>x</VAR>.
Mathematically, <CODE>exp10 (x)</CODE> is the same as <CODE>exp (x * log (10))</CODE>.
<br><br> These functions are GNU extensions. The name <CODE>exp10</CODE> is
preferred, since it is analogous to <CODE>exp</CODE> and <CODE>exp2</CODE>.
sq~wtmath.hxq~štfloat xtfloattexp10lsq~
tf
These functions compute <CODE>10</CODE> raised to the power <VAR>x</VAR>.
Mathematically, <CODE>exp10 (x)</CODE> is the same as <CODE>exp (x * log (10))</CODE>.
<br><br> These functions are GNU extensions. The name <CODE>exp10</CODE> is
preferred, since it is analogous to <CODE>exp</CODE> and <CODE>exp2</CODE>.
sq~wtmath.hxq~¡t
long double xt long doubletexp2sq~
t¸
These functions compute <CODE>2</CODE> raised to the power <VAR>x</VAR>.
Mathematically, <CODE>exp2 (x)</CODE> is the same as <CODE>exp (x * log (2))</CODE>.
sq~wtmath.hxq~¨tdouble xtdoubletexp2fsq~
t¸
These functions compute <CODE>2</CODE> raised to the power <VAR>x</VAR>.
Mathematically, <CODE>exp2 (x)</CODE> is the same as <CODE>exp (x * log (2))</CODE>.
sq~wtmath.hxq~¯tfloat xtfloattexp2lsq~
t¸
These functions compute <CODE>2</CODE> raised to the power <VAR>x</VAR>.
Mathematically, <CODE>exp2 (x)</CODE> is the same as <CODE>exp (x * log (2))</CODE>.
sq~wtmath.hxq~¶t
long double xt long doubletexpfsq~
t
These functions compute <CODE>e</CODE> (the base of natural logarithms) raised
to the power <VAR>x</VAR>.
<br><br> If the magnitude of the result is too large to be representable,
<CODE>exp</CODE> signals overflow.
sq~wtmath.hxq~½tfloat xtfloattexplsq~
t
These functions compute <CODE>e</CODE> (the base of natural logarithms) raised
to the power <VAR>x</VAR>.
<br><br> If the magnitude of the result is too large to be representable,
<CODE>exp</CODE> signals overflow.
sq~wtmath.hxq~Ät
long double xt long doubletexpm1sq~
tN
These functions return a value equivalent to <CODE>exp (<VAR>x</VAR>) - 1</CODE>.
They are computed in a way that is accurate even if <VAR>x</VAR> is
near zero---a case where <CODE>exp (<VAR>x</VAR>) - 1</CODE> would be inaccurate owing
to subtraction of two numbers that are nearly equal.
sq~wtmath.hxq~Ëtdouble xtdoubletexpm1fsq~
tN
These functions return a value equivalent to <CODE>exp (<VAR>x</VAR>) - 1</CODE>.
They are computed in a way that is accurate even if <VAR>x</VAR> is
near zero---a case where <CODE>exp (<VAR>x</VAR>) - 1</CODE> would be inaccurate owing
to subtraction of two numbers that are nearly equal.
sq~wtmath.hxq~Òtfloat xtfloattexpm1lsq~
tN
These functions return a value equivalent to <CODE>exp (<VAR>x</VAR>) - 1</CODE>.
They are computed in a way that is accurate even if <VAR>x</VAR> is
near zero---a case where <CODE>exp (<VAR>x</VAR>) - 1</CODE> would be inaccurate owing
to subtraction of two numbers that are nearly equal.
sq~wtmath.hxq~Ùt
long double xt long doubletfabssq~
ts
This function returns the absolute value of the floating-point number
<VAR>number</VAR>.
sq~wtmath.hxq~àt
double numbertdoubletfabsfsq~
ts
This function returns the absolute value of the floating-point number
<VAR>number</VAR>.
sq~wtmath.hxq~çt float numbertfloattfabslsq~
ts
This function returns the absolute value of the floating-point number
<VAR>number</VAR>.
sq~wtmath.hxq~îtlong double numbert long doubletfchdirsq~
tš
This function is used to set the process's working directory to
directory associated with the file descriptor <VAR>filedes</VAR>.
<br><br> The normal, successful return value from <CODE>fchdir</CODE> is <CODE>0</CODE>. A
value of <CODE>-1</CODE> is returned to indicate an error. The following
<CODE>errno</CODE> error conditions are defined for this function:
<br><br> <DL>
<DT><CODE>EACCES</CODE>
<DD>
Read permission is denied for the directory named by <CODE>dirname</CODE>.
<br><br> <LI> EBADF
The <VAR>filedes</VAR> argument is not a valid file descriptor.
<br><br> <LI> ENOTDIR
The file descriptor <VAR>filedes</VAR> is not associated with a directory.
<br><br> <LI> EINTR
The function call was interrupt by a signal.
<br><br> <LI> EIO
An I/O error occurred.
sq~wtunistd.hxq~õt int filedestinttfchmodsq~
tú
This is like <CODE>chmod</CODE>, except that it changes the permissions of the
currently open file given by <VAR>filedes</VAR>.
<br><br> The return value from <CODE>fchmod</CODE> is <CODE>0</CODE> on success and <CODE>-1</CODE>
on failure. The following <CODE>errno</CODE> error codes are defined for this
function:
<br><br> <DL>
<DT><CODE>EBADF</CODE>
<DD>
The <VAR>filedes</VAR> argument is not a valid file descriptor.
<br><br> <LI> EINVAL
The <VAR>filedes</VAR> argument corresponds to a pipe or socket, or something
else that doesn't really have access permissions.
<br><br> <LI> EPERM
This process does not have permission to change the access permissions
of this file. Only the file's owner (as judged by the effective user ID
of the process) or a privileged user can change them.
<br><br> <LI> EROFS
The file resides on a read-only file system.
sq~wt
sys/stat.hxq~ütint filedes, int modetinttfchownsq~
t`
This is like <CODE>chown</CODE>, except that it changes the owner of the open
file with descriptor <VAR>filedes</VAR>.
<br><br> The return value from <CODE>fchown</CODE> is <CODE>0</CODE> on success and <CODE>-1</CODE>
on failure. The following <CODE>errno</CODE> error codes are defined for this
function:
<br><br> <DL>
<DT><CODE>EBADF</CODE>
<DD>
The <VAR>filedes</VAR> argument is not a valid file descriptor.
<br><br> <LI> EINVAL
The <VAR>filedes</VAR> argument corresponds to a pipe or socket, not an ordinary
file.
<br><br> <LI> EPERM
This process lacks permission to make the requested change. For details
see <CODE>chmod</CODE> above.
<br><br> <LI> EROFS
The file resides on a read-only file system.
sq~wtunistd.hxq~t!int filedes, int owner, int grouptinttfcleansq~
t
Clean up the stream <VAR>stream</VAR> so that its buffer is empty. If
<VAR>stream</VAR> is doing output, force it out. If <VAR>stream</VAR> is doing
input, give the data in the buffer back to the system, arranging to
reread it.
sq~wtunistd.htstdio.hxq~
t FILE *streamtinttfclosesq~
t–
This function causes <VAR>stream</VAR> to be closed and the connection to
the corresponding file to be broken. Any buffered output is written
and any buffered input is discarded. The <CODE>fclose</CODE> function returns
a value of <CODE>0</CODE> if the file was closed successfully, and <CODE>EOF</CODE>
if an error was detected.
<br><br> It is important to check for errors when you call <CODE>fclose</CODE> to close
an output stream, because real, everyday errors can be detected at this
time. For example, when <CODE>fclose</CODE> writes the remaining buffered
output, it might get an error because the disk is full. Even if you
know the buffer is empty, errors can still occur when closing a file if
you are using NFS.
<br><br> The function <CODE>fclose</CODE> is declared in <TT>stdio.h</TT>.
sq~wtstdio.hxq~t FILE *streamtintt fcloseallsq~
tU
This function causes all open streams of the process to be closed and
the connection to corresponding files to be broken. All buffered data
is written and any buffered input is discarded. The <CODE>fcloseall</CODE>
function returns a value of <CODE>0</CODE> if all the files were closed
successfully, and <CODE>EOF</CODE> if an error was detected.
<br><br> This function should be used only in special situations, e.g., when an
error occurred and the program must be aborted. Normally each single
stream should be closed separately so that problems with individual
streams can be identified. It is also problematic since the standard
streams will also be closed.
<br><br> The function <CODE>fcloseall</CODE> is declared in <TT>stdio.h</TT>.
sq~wtstdio.hxq~tvoidtinttfcntlsq~
t|
The <CODE>fcntl</CODE> function performs the operation specified by
<VAR>command</VAR> on the file descriptor <VAR>filedes</VAR>. Some commands
require additional arguments to be supplied. These additional arguments
and the return value and error conditions are given in the detailed
descriptions of the individual commands.
<br><br> Briefly, here is a list of what the various commands are.
<br><br> <DL>
<DT><CODE>F_DUPFD</CODE>
<DD>
Duplicate the file descriptor (return another file descriptor pointing
to the same open file). .
<br><br> <LI> F_GETFD
Get flags associated with the file descriptor. .
<br><br> <LI> F_SETFD
Set flags associated with the file descriptor. .
<br><br> <LI> F_GETFL
Get flags associated with the open file. .
<br><br> <LI> F_SETFL
Set flags associated with the open file. .
<br><br> <LI> F_GETLK
Get a file lock. .
<br><br> <LI> F_SETLK
Set or clear a file lock. .
<br><br> <LI> F_SETLKW
Like <CODE>F_SETLK</CODE>, but wait for completion. .
<br><br> <LI> F_GETOWN
Get process or process group ID to receive <CODE>SIGIO</CODE> signals.
.
<br><br> <LI> F_SETOWN
Set process or process group ID to receive <CODE>SIGIO</CODE> signals.
.
<br><br> This function is a cancellation point in multi-threaded programs. This
is a problem if the thread allocates some resources (like memory, file
descriptors, semaphores or whatever) at the time <CODE>fcntl</CODE> is
called. If the thread gets canceled these resources stay allocated
until the program ends. To avoid this calls to <CODE>fcntl</CODE> should be
protected using cancellation handlers.
sq~wtfcntl.hxq~ tint filedes, int command, ...tinttfcvtsq~
t”
The function <CODE>fcvt</CODE> is like <CODE>ecvt</CODE>, but <VAR>ndigit</VAR> specifies
the number of digits after the decimal point. If <VAR>ndigit</VAR> is less
than zero, <VAR>value</VAR> is rounded to the <VAR>ndigit</VAR>+1'th place to the
left of the decimal point. For example, if <VAR>ndigit</VAR> is <CODE>-1</CODE>,
<VAR>value</VAR> will be rounded to the nearest 10. If <VAR>ndigit</VAR> is
negative and larger than the number of digits to the left of the decimal
point in <VAR>value</VAR>, <VAR>value</VAR> will be rounded to one significant digit.
<br><br> If <VAR>ndigit</VAR> decimal digits would exceed the precision of a
<CODE>double</CODE> it is reduced to a system-specific value.
<br><br> The returned string is statically allocated and overwritten by each call
to <CODE>fcvt</CODE>.
sq~wtstdlib.hxq~'t.double value, int ndigit, int *decpt, int *negtchar *tfcvt_rsq~
tj
The <CODE>fcvt_r</CODE> function is the same as <CODE>fcvt</CODE>, except that it
places its result into the user-specified buffer pointed to by
<VAR>buf</VAR>, with length <VAR>len</VAR>. The return value is <CODE>-1</CODE> in
case of an error and zero otherwise.
<br><br> This function is a GNU extension.
sq~wtstdlib.hxq~.tEdouble value, int ndigit, int *decpt, int *neg, char *buf, size_t lentintt fdatasyncsq~
t
When a call to the <CODE>fdatasync</CODE> function returns, it is ensured
that all of the file data is written to the device. For all pending I/O
operations, the parts guaranteeing data integrity finished.
<br><br> Not all systems implement the <CODE>fdatasync</CODE> operation. On systems
missing this functionality <CODE>fdatasync</CODE> is emulated by a call to
<CODE>fsync</CODE> since the performed actions are a superset of those
required by <CODE>fdatasync</CODE>.
<br><br> The prototype for <CODE>fdatasync</CODE> is in <TT>unistd.h</TT>.
<br><br> The return value of the function is zero if no error occurred. Otherwise
it is -1 and the global variable <VAR>errno</VAR> is set to the
following values:
<DL>
<DT><CODE>EBADF</CODE>
<DD>
The descriptor <VAR>fildes</VAR> is not valid.
<br><br> <LI> EINVAL
No synchronization is possible since the system does not implement this.
sq~wtunistd.hxq~5t
int fildestinttfdimsq~
tS
The <CODE>fdim</CODE> function returns the positive difference between
<VAR>x</VAR> and <VAR>y</VAR>. The positive difference is <VAR>x</VAR> -
<VAR>y</VAR> if <VAR>x</VAR> is greater than <VAR>y</VAR>, and 0 otherwise.
<br><br> If <VAR>x</VAR>, <VAR>y</VAR>, or both are NaN, NaN is returned.
sq~wtmath.hxq~<tdouble x, double ytdoubletfdimfsq~
tS
The <CODE>fdim</CODE> function returns the positive difference between
<VAR>x</VAR> and <VAR>y</VAR>. The positive difference is <VAR>x</VAR> -
<VAR>y</VAR> if <VAR>x</VAR> is greater than <VAR>y</VAR>, and 0 otherwise.
<br><br> If <VAR>x</VAR>, <VAR>y</VAR>, or both are NaN, NaN is returned.
sq~wtmath.hxq~Ctfloat x, float ytfloattfdimlsq~
tS
The <CODE>fdim</CODE> function returns the positive difference between
<VAR>x</VAR> and <VAR>y</VAR>. The positive difference is <VAR>x</VAR> -
<VAR>y</VAR> if <VAR>x</VAR> is greater than <VAR>y</VAR>, and 0 otherwise.
<br><br> If <VAR>x</VAR>, <VAR>y</VAR>, or both are NaN, NaN is returned.
sq~wtmath.hxq~Jtlong double x, long double yt long doubletfdopensq~
tî
The <CODE>fdopen</CODE> function returns a new stream for the file descriptor
<VAR>filedes</VAR>.
<br><br> The <VAR>opentype</VAR> argument is interpreted in the same way as for the
<CODE>fopen</CODE> function , except that
the <samp>b</samp> option is not permitted; this is because GNU makes no
distinction between text and binary files. Also, <CODE>"w"</CODE> and
<CODE>"w+"</CODE> do not cause truncation of the file; these have an effect only
when opening a file, and in this case the file has already been opened.
You must make sure that the <VAR>opentype</VAR> argument matches the actual
mode of the open file descriptor.
<br><br> The return value is the new stream. If the stream cannot be created
(for example, if the modes for the file indicated by the file descriptor
do not permit the access specified by the <VAR>opentype</VAR> argument), a
null pointer is returned instead.
<br><br> In some other systems, <CODE>fdopen</CODE> may fail to detect that the modes
for file descriptor do not permit the access specified by
<CODE>opentype</CODE>. The GNU C library always checks for this.
sq~wt sys/types.htstdio.hxq~Qt!int filedes, const char *opentypetFILE *t fdopendirsq~
t|
The <CODE>fdopendir</CODE> function works just like <CODE>opendir</CODE> but
instead of taking a file name and opening a file descriptor for the
directory the caller is required to provide a file descriptor. This
file descriptor is then used in subsequent uses of the returned
directory stream object.
<br><br> The caller must make sure the file descriptor is associated with a
directory and it allows reading.
<br><br> If the <CODE>fdopendir</CODE> call returns successfully the file descriptor
is now under the control of the system. It can be used in the same
way the descriptor implicitly created by <CODE>opendir</CODE> can be used
but the program must not close the descriptor.
<br><br> In case the function is unsuccessful it returns a null pointer and the
file descriptor remains to be usable by the program. The following
<CODE>errno</CODE> error conditions are defined for this function:
<br><br> <DL>
<DT><CODE>EBADF</CODE>
<DD>
The file descriptor is not valid.
<br><br> <LI> ENOTDIR
The file descriptor is not associated with a directory.
<br><br> <LI> EINVAL
The descriptor does not allow reading the directory content.
<br><br> <LI> ENOMEM
Not enough memory available.
sq~wtdirent.hxq~Ytint fdtDIR *t
feclearexceptsq~
tì
This function clears all of the supported exception flags indicated by
<VAR>excepts</VAR>.
<br><br> The function returns zero in case the operation was successful, a
non-zero value otherwise.
sq~wtmath.htfenv.hxq~`t int exceptstinttfedisableexceptsq~
tË
This functions disables traps for each of the exceptions as indicated by
the parameter <VAR>except</VAR>. The individual excepetions are described in
Status bit operations. Only the specified exceptions are
disabled, the status of the other exceptions is not changed.
<br><br> The function returns the previous enabled exceptions in case the
operation was successful, <CODE>-1</CODE> otherwise.
sq~wtfenv.hxq~ht int exceptstinttfeenableexceptsq~
tÉ
This functions enables traps for each of the exceptions as indicated by
the parameter <VAR>except</VAR>. The individual excepetions are described in
Status bit operations. Only the specified exceptions are
enabled, the status of the other exceptions is not changed.
<br><br> The function returns the previous enabled exceptions in case the
operation was successful, <CODE>-1</CODE> otherwise.
sq~wtfenv.hxq~ot int exceptstinttfegetenvsq~
tå
Store the floating-point environment in the variable pointed to by
<VAR>envp</VAR>.
<br><br> The function returns zero in case the operation was successful, a
non-zero value otherwise.
sq~wtfenv.hxq~vt fenv_t *envptintt fegetexceptsq~
tŽ
The function returns a bitmask of all currently enabled exceptions. It
returns <CODE>-1</CODE> in case of failure.
sq~wtfenv.hxq~}t int exceptstinttfegetexceptflagsq~
tW
This function stores in the variable pointed to by <VAR>flagp</VAR> an
implementation-defined value representing the current setting of the
exception flags indicated by <VAR>excepts</VAR>.
<br><br> The function returns zero in case the operation was successful, a
non-zero value otherwise.
sq~wtfenv.hxq~„tfexcept_t *flagp, int exceptstintt
fegetroundsq~
tŽ
Returns the currently selected rounding mode, represented by one of the
values of the defined rounding mode macros.
sq~wtmath.htfenv.hxq~‹tvoidtintt feholdexceptsq~
tt
Store the current floating-point environment in the object pointed to by
<VAR>envp</VAR>. Then clear all exception flags, and set the FPU to trap no
exceptions. Not all FPUs support trapping no exceptions; if
<CODE>feholdexcept</CODE> cannot set this mode, it returns nonzero value. If it
succeeds, it returns zero.
sq~wtfenv.hxq~“t fenv_t *envptinttfeofsq~
tÚ
The <CODE>feof</CODE> function returns nonzero if and only if the end-of-file
indicator for the stream <VAR>stream</VAR> is set.
<br><br> This symbol is declared in <TT>stdio.h</TT>.
sq~wtstdio.htwchar.hxq~št FILE *streamtintt
feof_unlockedsq~
t
The <CODE>feof_unlocked</CODE> function is equivalent to the <CODE>feof</CODE>
function except that it does not implicitly lock the stream.
<br><br> This function is a GNU extension.
<br><br> This symbol is declared in <TT>stdio.h</TT>.
sq~wtstdio.hxq~¢t FILE *streamtintt
feraiseexceptsq~
t|
This function raises the supported exceptions indicated by
<VAR>excepts</VAR>. If more than one exception bit in <VAR>excepts</VAR> is set
the order in which the exceptions are raised is undefined except that
overflow (<CODE>FE_OVERFLOW</CODE>) or underflow (<CODE>FE_UNDERFLOW</CODE>) are
raised before inexact (<CODE>FE_INEXACT</CODE>). Whether for overflow or
underflow the inexact exception is also raised is also implementation
dependent.
<br><br> The function returns zero in case the operation was successful, a
non-zero value otherwise.
sq~wtfenv.hxq~©t int exceptstinttferrorsq~
t,
The <CODE>ferror</CODE> function returns nonzero if and only if the error
indicator for the stream <VAR>stream</VAR> is set, indicating that an error
has occurred on a previous operation on the stream.
<br><br> This symbol is declared in <TT>stdio.h</TT>.
sq~wtstdio.hxq~°t FILE *streamtinttferror_unlockedsq~
t
The <CODE>ferror_unlocked</CODE> function is equivalent to the <CODE>ferror</CODE>
function except that it does not implicitly lock the stream.
<br><br> This function is a GNU extension.
<br><br> This symbol is declared in <TT>stdio.h</TT>.
sq~wtstdio.hxq~·t FILE *streamtinttfesetenvsq~
tÑ
Set the floating-point environment to that described by <VAR>envp</VAR>.
<br><br> The function returns zero in case the operation was successful, a
non-zero value otherwise.
sq~wtfenv.hxq~¾tconst fenv_t *envptinttfesetexceptflagsq~
t3
This function restores the flags for the exceptions indicated by
<VAR>excepts</VAR> to the values stored in the variable pointed to by
<VAR>flagp</VAR>.
<br><br> The function returns zero in case the operation was successful, a
non-zero value otherwise.
sq~wtfenv.hxq~Åt#const fexcept_t *flagp, int exceptstintt
fesetroundsq~
tG
Changes the currently selected rounding mode to <VAR>round</VAR>. If
<VAR>round</VAR> does not correspond to one of the supported rounding modes
nothing is changed. <CODE>fesetround</CODE> returns zero if it changed the
rounding mode, a nonzero value if the mode is not supported.
sq~wtfenv.hxq~Ìt int roundtintt fetestexceptsq~
tþ
Test whether the exception flags indicated by the parameter <VAR>except</VAR>
are currently set. If any of them are, a nonzero value is returned
which specifies which exceptions are set. Otherwise the result is zero.
sq~wtfenv.hxq~Ót int exceptstintt feupdateenvsq~
tT
Like <CODE>fesetenv</CODE>, this function sets the floating-point environment
to that described by <VAR>envp</VAR>. However, if any exceptions were
flagged in the status word before <CODE>feupdateenv</CODE> was called, they
remain flagged after the call. In other words, after <CODE>feupdateenv</CODE>
is called, the status word is the bitwise OR of the previous status word
and the one saved in <VAR>envp</VAR>.
<br><br> The function returns zero in case the operation was successful, a
non-zero value otherwise.
sq~wtfenv.hxq~Útconst fenv_t *envptinttfflushsq~
t�
This function causes any buffered output on <VAR>stream</VAR> to be delivered
to the file. If <VAR>stream</VAR> is a null pointer, then
<CODE>fflush</CODE> causes buffered output on <EM>all</EM> open output streams
to be flushed.
<br><br> This function returns <CODE>EOF</CODE> if a write error occurs, or zero
otherwise.
sq~wtstdio.hxq~át FILE *streamtinttfflush_unlockedsq~
tª
The <CODE>fflush_unlocked</CODE> function is equivalent to the <CODE>fflush</CODE>
function except that it does not implicitly lock the stream.
sq~wtstdio.hxq~èt FILE *streamtinttfgetcsq~
t(
This function reads the next character as an <CODE>unsigned char</CODE> from
the stream <VAR>stream</VAR> and returns its value, converted to an
<CODE>int</CODE>. If an end-of-file condition or read error occurs,
<CODE>EOF</CODE> is returned instead.
sq~wtstdio.hxq~ït FILE *streamtinttfgetc_unlockedsq~
t¨
The <CODE>fgetc_unlocked</CODE> function is equivalent to the <CODE>fgetc</CODE>
function except that it does not implicitly lock the stream.
sq~wtstdio.hxq~öt FILE *streamtintt fgetgrentsq~
tÜ
The <CODE>fgetgrent</CODE> function reads the next entry from <VAR>stream</VAR>.
It returns a pointer to the entry. The structure is statically
allocated and is overwritten on subsequent calls to <CODE>fgetgrent</CODE>. You
must copy the contents of the structure if you wish to save the
information.
<br><br> The stream must correspond to a file in the same format as the standard
group database file.
sq~wtgrp.hxq~ýt FILE *streamtstruct group *t fgetgrent_rsq~
tf
This function is similar to <CODE>fgetgrent</CODE> in that it reads the next
user entry from <VAR>stream</VAR>. But the result is returned in the
structure pointed to by <VAR>result_buf</VAR>. The first <VAR>buflen</VAR> bytes
of the additional buffer pointed to by <VAR>buffer</VAR> are used to contain
additional information, normally strings which are pointed to by the
elements of the result structure.
<br><br> This stream must correspond to a file in the same format as the standard
group database file.
<br><br> If the function returns zero <VAR>result</VAR> points to the structure with
the wanted data (normally this is in <VAR>result_buf</VAR>). If errors
occurred the return value is non-zero and <VAR>result</VAR> contains a null
pointer.
sq~wtgrp.hxq~ tZFILE *stream, struct group *result_buf, char *buffer, size_t buflen, struct group **resulttinttfgetpossq~
tn
This function stores the value of the file position indicator for the
stream <VAR>stream</VAR> in the <CODE>fpos_t</CODE> object pointed to by
<VAR>position</VAR>. If successful, <CODE>fgetpos</CODE> returns zero; otherwise
it returns a nonzero value and stores an implementation-defined positive
value in <CODE>errno</CODE>.
<br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> on a
32 bit system the function is in fact <CODE>fgetpos64</CODE>. I.e., the LFS
interface transparently replaces the old interface.
sq~wt
sys/file.htstdio.hxq~ tFILE *stream, fpos_t *positiontintt fgetpos64sq~
t
This function is similar to <CODE>fgetpos</CODE> but the file position is
returned in a variable of type <CODE>fpos64_t</CODE> to which <VAR>position</VAR>
points.
<br><br> If the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> on a 32
bits machine this function is available under the name <CODE>fgetpos</CODE>
and so transparently replaces the old interface.
sq~wtstdio.hxq~ t FILE *stream, fpos64_t *positiontintt fgetpwentsq~
tÃ
This function reads the next user entry from <VAR>stream</VAR> and returns a
pointer to the entry. The structure is statically allocated and is
rewritten on subsequent calls to <CODE>fgetpwent</CODE>. You must copy the
contents of the structure if you wish to save the information.
<br><br> The stream must correspond to a file in the same format as the standard
password database file.
sq~wtpwd.hxq~ t FILE *streamtstruct passwd *t fgetpwent_rsq~
tg
This function is similar to <CODE>fgetpwent</CODE> in that it reads the next
user entry from <VAR>stream</VAR>. But the result is returned in the
structure pointed to by <VAR>result_buf</VAR>. The
first <VAR>buflen</VAR> bytes of the additional buffer pointed to by
<VAR>buffer</VAR> are used to contain additional information, normally
strings which are pointed to by the elements of the result structure.
<br><br> The stream must correspond to a file in the same format as the standard
password database file.
<br><br> If the function returns zero <VAR>result</VAR> points to the structure with
the wanted data (normally this is in <VAR>result_buf</VAR>). If errors
occurred the return value is nonzero and <VAR>result</VAR> contains a null
pointer.
sq~wtpwd.hxq~ !t\FILE *stream, struct passwd *result_buf, char *buffer, size_t buflen, struct passwd **resulttinttfgetssq~
t
The <CODE>fgets</CODE> function reads characters from the stream <VAR>stream</VAR>
up to and including a newline character and stores them in the string
<VAR>s</VAR>, adding a null character to mark the end of the string. You
must supply <VAR>count</VAR> characters worth of space in <VAR>s</VAR>, but the
number of characters read is at most <VAR>count</VAR> 1. The extra
character space is used to hold the null character at the end of the
string.
<br><br> If the system is already at end of file when you call <CODE>fgets</CODE>, then
the contents of the array <VAR>s</VAR> are unchanged and a null pointer is
returned. A null pointer is also returned if a read error occurs.
Otherwise, the return value is the pointer <VAR>s</VAR>.
<br><br> Warning: If the input data has a null character, you can't tell.
So don't use <CODE>fgets</CODE> unless you know the data cannot contain a null.
Don't use it to read files edited by the user because, if the user inserts
a null character, you should either handle it properly or print a clear
error message. We recommend using <CODE>getline</CODE> instead of <CODE>fgets</CODE>.
sq~wtstdio.hxq~ (t char *s, int count, FILE *streamtchar *tfgets_unlockedsq~
tÜ
The <CODE>fgets_unlocked</CODE> function is equivalent to the <CODE>fgets</CODE>
function except that it does not implicitly lock the stream.
<br><br> This function is a GNU extension.
sq~wtstdio.hxq~ /t char *s, int count, FILE *streamtchar *tfgetwcsq~
tâ
This function reads the next wide character from the stream <VAR>stream</VAR>
and returns its value. If an end-of-file condition or read error
occurs, <CODE>WEOF</CODE> is returned instead.
sq~wtwchar.hxq~ 6t FILE *streamtwint_ttfgetwc_unlockedsq~
tÞ
The <CODE>fgetwc_unlocked</CODE> function is equivalent to the <CODE>fgetwc</CODE>
function except that it does not implicitly lock the stream.
<br><br> This function is a GNU extension.
sq~wtwchar.hxq~ =t FILE *streamtwint_ttfgetwssq~
t
The <CODE>fgetws</CODE> function reads wide characters from the stream
<VAR>stream</VAR> up to and including a newline character and stores them in
the string <VAR>ws</VAR>, adding a null wide character to mark the end of the
string. You must supply <VAR>count</VAR> wide characters worth of space in
<VAR>ws</VAR>, but the number of characters read is at most <VAR>count</VAR>
1. The extra character space is used to hold the null wide
character at the end of the string.
<br><br> If the system is already at end of file when you call <CODE>fgetws</CODE>, then
the contents of the array <VAR>ws</VAR> are unchanged and a null pointer is
returned. A null pointer is also returned if a read error occurs.
Otherwise, the return value is the pointer <VAR>ws</VAR>.
<br><br> Warning: If the input data has a null wide character (which are
null bytes in the input stream), you can't tell. So don't use
<CODE>fgetws</CODE> unless you know the data cannot contain a null. Don't use
it to read files edited by the user because, if the user inserts a null
character, you should either handle it properly or print a clear error
message.
sq~wtwchar.hxq~ Dt$wchar_t *ws, int count, FILE *streamt wchar_t *tfgetws_unlockedsq~
tÞ
The <CODE>fgetws_unlocked</CODE> function is equivalent to the <CODE>fgetws</CODE>
function except that it does not implicitly lock the stream.
<br><br> This function is a GNU extension.
sq~wtwchar.hxq~ Kt$wchar_t *ws, int count, FILE *streamt wchar_t *tfilenosq~
t%
This function returns the file descriptor associated with the stream
<VAR>stream</VAR>. If an error is detected (for example, if the <VAR>stream</VAR>
is not valid) or if <VAR>stream</VAR> does not do I/O to a file,
<CODE>fileno</CODE> returns -1.
sq~wtstdio.hxq~ Rt FILE *streamtinttfileno_unlockedsq~
t
The <CODE>fileno_unlocked</CODE> function is equivalent to the <CODE>fileno</CODE>
function except that it does not implicitly lock the stream if the state
is <CODE>FSETLOCKING_INTERNAL</CODE>.
<br><br> This function is a GNU extension.
sq~wtstdio.hxq~ Yt FILE *streamtinttfinitesq~
t‹
This function returns a nonzero value if <VAR>x</VAR> is finite or a ``not a
number'' value, and zero otherwise.
sq~wtmath.hxq~ `tdouble xtinttfinitefsq~
t‹
This function returns a nonzero value if <VAR>x</VAR> is finite or a ``not a
number'' value, and zero otherwise.
sq~wtmath.hxq~ gtfloat xtinttfinitelsq~
t‹
This function returns a nonzero value if <VAR>x</VAR> is finite or a ``not a
number'' value, and zero otherwise.
sq~wtmath.hxq~ nt
long double xtintt flockfilesq~
tæ
The <CODE>flockfile</CODE> function acquires the internal locking object
associated with the stream <VAR>stream</VAR>. This ensures that no other
thread can explicitly through <CODE>flockfile</CODE>/<CODE>ftrylockfile</CODE> or
implicit through a call of a stream function lock the stream. The
thread will block until the lock is acquired. An explicit call to
<CODE>funlockfile</CODE> has to be used to release the lock.
sq~wtstdio.hxq~ ut FILE *streamtvoidtfloorsq~
tÿ
These functions round <VAR>x</VAR> downwards to the nearest
integer, returning that value as a <CODE>double</CODE>. Thus, <CODE>floor
(1.5)</CODE> is <CODE>1.0</CODE> and <CODE>floor (-1.5)</CODE> is <CODE>-2.0</CODE>.
sq~wtmath.hxq~ |tdouble xtdoubletfloorfsq~
tÿ
These functions round <VAR>x</VAR> downwards to the nearest
integer, returning that value as a <CODE>double</CODE>. Thus, <CODE>floor
(1.5)</CODE> is <CODE>1.0</CODE> and <CODE>floor (-1.5)</CODE> is <CODE>-2.0</CODE>.
sq~wtmath.hxq~ ƒtfloat xtfloattfloorlsq~
tÿ
These functions round <VAR>x</VAR> downwards to the nearest
integer, returning that value as a <CODE>double</CODE>. Thus, <CODE>floor
(1.5)</CODE> is <CODE>1.0</CODE> and <CODE>floor (-1.5)</CODE> is <CODE>-2.0</CODE>.
sq~wtmath.hxq~ Št
long double xt long doubletfmasq~
tª
The <CODE>fma</CODE> function performs floating-point multiply-add. This is
the operation (<VAR>x</VAR> <VAR>y</VAR>) + <VAR>z</VAR>, but the
intermediate result is not rounded to the destination type. This can
sometimes improve the precision of a calculation.
<br><br> This function was introduced because some processors have a special
instruction to perform multiply-add. The C compiler cannot use it
directly, because the expression <samp>x*y + z</samp> is defined to round the
intermediate result. <CODE>fma</CODE> lets you choose when you want to round
only once.
<br><br>
On processors which do not implement multiply-add in hardware,
<CODE>fma</CODE> can be very slow since it must avoid intermediate rounding.
<TT>math.h</TT> defines the symbols <CODE>FP_FAST_FMA</CODE>,
<CODE>FP_FAST_FMAF</CODE>, and <CODE>FP_FAST_FMAL</CODE> when the corresponding
version of <CODE>fma</CODE> is no slower than the expression <samp>x*y + z</samp>.
In the GNU C library, this always means the operation is implemented in
hardware.
sq~wtmath.hxq~ ‘tdouble x, double y, double ztdoubletfmafsq~
tª
The <CODE>fma</CODE> function performs floating-point multiply-add. This is
the operation (<VAR>x</VAR> <VAR>y</VAR>) + <VAR>z</VAR>, but the
intermediate result is not rounded to the destination type. This can
sometimes improve the precision of a calculation.
<br><br> This function was introduced because some processors have a special
instruction to perform multiply-add. The C compiler cannot use it
directly, because the expression <samp>x*y + z</samp> is defined to round the
intermediate result. <CODE>fma</CODE> lets you choose when you want to round
only once.
<br><br>
On processors which do not implement multiply-add in hardware,
<CODE>fma</CODE> can be very slow since it must avoid intermediate rounding.
<TT>math.h</TT> defines the symbols <CODE>FP_FAST_FMA</CODE>,
<CODE>FP_FAST_FMAF</CODE>, and <CODE>FP_FAST_FMAL</CODE> when the corresponding
version of <CODE>fma</CODE> is no slower than the expression <samp>x*y + z</samp>.
In the GNU C library, this always means the operation is implemented in
hardware.
sq~wtmath.hxq~ ˜tfloat x, float y, float ztfloattfmalsq~
tª
The <CODE>fma</CODE> function performs floating-point multiply-add. This is
the operation (<VAR>x</VAR> <VAR>y</VAR>) + <VAR>z</VAR>, but the
intermediate result is not rounded to the destination type. This can
sometimes improve the precision of a calculation.
<br><br> This function was introduced because some processors have a special
instruction to perform multiply-add. The C compiler cannot use it
directly, because the expression <samp>x*y + z</samp> is defined to round the
intermediate result. <CODE>fma</CODE> lets you choose when you want to round
only once.
<br><br>
On processors which do not implement multiply-add in hardware,
<CODE>fma</CODE> can be very slow since it must avoid intermediate rounding.
<TT>math.h</TT> defines the symbols <CODE>FP_FAST_FMA</CODE>,
<CODE>FP_FAST_FMAF</CODE>, and <CODE>FP_FAST_FMAL</CODE> when the corresponding
version of <CODE>fma</CODE> is no slower than the expression <samp>x*y + z</samp>.
In the GNU C library, this always means the operation is implemented in
hardware.
sq~wtmath.hxq~ Ÿt+long double x, long double y, long double zt long doubletfmaxsq~
tý
The <CODE>fmax</CODE> function returns the greater of the two values <VAR>x</VAR>
and <VAR>y</VAR>.
<br><br> If an argument is NaN, the other argument is returned. If both arguments
are NaN, NaN is returned.
sq~wtmath.hxq~ ¦tdouble x, double ytdoubletfmaxfsq~
tý
The <CODE>fmax</CODE> function returns the greater of the two values <VAR>x</VAR>
and <VAR>y</VAR>.
<br><br> If an argument is NaN, the other argument is returned. If both arguments
are NaN, NaN is returned.
sq~wtmath.hxq~ ­tfloat x, float ytfloattfmaxlsq~
tý
The <CODE>fmax</CODE> function returns the greater of the two values <VAR>x</VAR>
and <VAR>y</VAR>.
<br><br> If an argument is NaN, the other argument is returned. If both arguments
are NaN, NaN is returned.
sq~wtmath.hxq~ ´tlong double x, long double yt long doubletfmemopensq~
t]
This function opens a stream that allows the access specified by the
<VAR>opentype</VAR> argument, that reads from or writes to the buffer specified
by the argument <VAR>buf</VAR>. This array must be at least <VAR>size</VAR> bytes long.
<br><br> If you specify a null pointer as the <VAR>buf</VAR> argument, <CODE>fmemopen</CODE>
dynamically allocates an array <VAR>size</VAR> bytes long (as with <CODE>malloc</CODE>;
). This is really only useful
if you are going to write things to the buffer and then read them back
in again, because you have no way of actually getting a pointer to the
buffer (for this, try <CODE>open_memstream</CODE>, below). The buffer is
freed when the stream is closed.
<br><br> The argument <VAR>opentype</VAR> is the same as in <CODE>fopen</CODE>
. If the <VAR>opentype</VAR> specifies
append mode, then the initial file position is set to the first null
character in the buffer. Otherwise the initial file position is at the
beginning of the buffer.
<br><br> When a stream open for writing is flushed or closed, a null character
(zero byte) is written at the end of the buffer if it fits. You
should add an extra byte to the <VAR>size</VAR> argument to account for this.
Attempts to write more than <VAR>size</VAR> bytes to the buffer result
in an error.
<br><br> For a stream open for reading, null characters (zero bytes) in the
buffer do not count as ``end of file''. Read operations indicate end of
file only when the file position advances past <VAR>size</VAR> bytes. So, if
you want to read characters from a null-terminated string, you should
supply the length of the string as the <VAR>size</VAR> argument.
sq~wtstdio.hxq~ »t,void *buf, size_t size, const char *opentypetFILE *tfminsq~
t±
The <CODE>fmin</CODE> function returns the lesser of the two values <VAR>x</VAR>
and <VAR>y</VAR>. It is similar to the expression
<pre><br>
((x) < (y) ? (x) : (y))<br>
</pre>
except that <VAR>x</VAR> and <VAR>y</VAR> are only evaluated once.
<br><br> If an argument is NaN, the other argument is returned. If both arguments
are NaN, NaN is returned.
sq~wtmath.hxq~ Âtdouble x, double ytdoubletfminfsq~
t±
The <CODE>fmin</CODE> function returns the lesser of the two values <VAR>x</VAR>
and <VAR>y</VAR>. It is similar to the expression
<pre><br>
((x) < (y) ? (x) : (y))<br>
</pre>
except that <VAR>x</VAR> and <VAR>y</VAR> are only evaluated once.
<br><br> If an argument is NaN, the other argument is returned. If both arguments
are NaN, NaN is returned.
sq~wtmath.hxq~ Étfloat x, float ytfloattfminlsq~
t±
The <CODE>fmin</CODE> function returns the lesser of the two values <VAR>x</VAR>
and <VAR>y</VAR>. It is similar to the expression
<pre><br>
((x) < (y) ? (x) : (y))<br>
</pre>
except that <VAR>x</VAR> and <VAR>y</VAR> are only evaluated once.
<br><br> If an argument is NaN, the other argument is returned. If both arguments
are NaN, NaN is returned.
sq~wtmath.hxq~ Ðtlong double x, long double yt long doubletfmodsq~
t
These functions compute the remainder from the division of
<VAR>numerator</VAR> by <VAR>denominator</VAR>. Specifically, the return value is
<CODE><VAR>numerator</VAR> - <VAR>n</VAR> * <VAR>denominator</VAR></CODE>, where <VAR>n</VAR>
is the quotient of <VAR>numerator</VAR> divided by <VAR>denominator</VAR>, rounded
towards zero to an integer. Thus, <CODE>fmod (6.5, 2.3)</CODE> returns
<CODE>1.9</CODE>, which is <CODE>6.5</CODE> minus <CODE>4.6</CODE>.
<br><br> The result has the same sign as the <VAR>numerator</VAR> and has magnitude
less than the magnitude of the <VAR>denominator</VAR>.
<br><br> If <VAR>denominator</VAR> is zero, <CODE>fmod</CODE> signals a domain error.
sq~wtmath.hxq~ ×t$double numerator, double denominatortdoubletfmodfsq~
t
These functions compute the remainder from the division of
<VAR>numerator</VAR> by <VAR>denominator</VAR>. Specifically, the return value is
<CODE><VAR>numerator</VAR> - <VAR>n</VAR> * <VAR>denominator</VAR></CODE>, where <VAR>n</VAR>
is the quotient of <VAR>numerator</VAR> divided by <VAR>denominator</VAR>, rounded
towards zero to an integer. Thus, <CODE>fmod (6.5, 2.3)</CODE> returns
<CODE>1.9</CODE>, which is <CODE>6.5</CODE> minus <CODE>4.6</CODE>.
<br><br> The result has the same sign as the <VAR>numerator</VAR> and has magnitude
less than the magnitude of the <VAR>denominator</VAR>.
<br><br> If <VAR>denominator</VAR> is zero, <CODE>fmod</CODE> signals a domain error.
sq~wtmath.hxq~ Þt"float numerator, float denominatortfloattfmodlsq~
t
These functions compute the remainder from the division of
<VAR>numerator</VAR> by <VAR>denominator</VAR>. Specifically, the return value is
<CODE><VAR>numerator</VAR> - <VAR>n</VAR> * <VAR>denominator</VAR></CODE>, where <VAR>n</VAR>
is the quotient of <VAR>numerator</VAR> divided by <VAR>denominator</VAR>, rounded
towards zero to an integer. Thus, <CODE>fmod (6.5, 2.3)</CODE> returns
<CODE>1.9</CODE>, which is <CODE>6.5</CODE> minus <CODE>4.6</CODE>.
<br><br> The result has the same sign as the <VAR>numerator</VAR> and has magnitude
less than the magnitude of the <VAR>denominator</VAR>.
<br><br> If <VAR>denominator</VAR> is zero, <CODE>fmod</CODE> signals a domain error.
sq~wtmath.hxq~ åt.long double numerator, long double denominatort long doubletfmtmsgsq~
tß
Display a message described by its parameters on the device(s) specified
in the <VAR>classification</VAR> parameter. The <VAR>label</VAR> parameter
identifies the source of the message. The string should consist of two
colon separated parts where the first part has not more than 10 and the
second part not more than 14 characters. The <VAR>text</VAR> parameter
describes the condition of the error, the <VAR>action</VAR> parameter possible
steps to recover from the error and the <VAR>tag</VAR> parameter is a
reference to the online documentation where more information can be
found. It should contain the <VAR>label</VAR> value and a unique
identification number.
<br><br> Each of the parameters can be a special value which means this value
is to be omitted. The symbolic names for these values are:
<br><br> <DL>
<DT><CODE>MM_NULLLBL</CODE>
<DD>
Ignore <VAR>label</VAR> parameter.
<DT><CODE>MM_NULLSEV</CODE>
<DD>
Ignore <VAR>severity</VAR> parameter.
<DT><CODE>MM_NULLMC</CODE>
<DD>
Ignore <VAR>classification</VAR> parameter. This implies that nothing is
actually printed.
<DT><CODE>MM_NULLTXT</CODE>
<DD>
Ignore <VAR>text</VAR> parameter.
<DT><CODE>MM_NULLACT</CODE>
<DD>
Ignore <VAR>action</VAR> parameter.
<DT><CODE>MM_NULLTAG</CODE>
<DD>
Ignore <VAR>tag</VAR> parameter.
</DL>
<br><br> There is another way certain fields can be omitted from the output to
standard error. This is described below in the description of
environment variables influencing the behavior.
<br><br> The <VAR>severity</VAR> parameter can have one of the values in the following
table:
class
<br><br> <DL>
<DT><CODE>MM_NOSEV</CODE>
<DD>
Nothing is printed, this value is the same as <CODE>MM_NULLSEV</CODE>.
<DT><CODE>MM_HALT</CODE>
<DD>
This value is printed as <CODE>HALT</CODE>.
<DT><CODE>MM_ERROR</CODE>
<DD>
This value is printed as <CODE>ERROR</CODE>.
<DT><CODE>MM_WARNING</CODE>
<DD>
This value is printed as <CODE>WARNING</CODE>.
<DT><CODE>MM_INFO</CODE>
<DD>
This value is printed as <CODE>INFO</CODE>.
</DL>
<br><br> The numeric value of these five macros are between <CODE>0</CODE> and
<CODE>4</CODE>. Using the environment variable <CODE>SEV_LEVEL</CODE> or using the
<CODE>addseverity</CODE> function one can add more severity levels with their
corresponding string to print. This is described below
.
<br><br>
If no parameter is ignored the output looks like this:
<br><br> <pre><br>
<VAR>label</VAR>: <VAR>severity-string</VAR>: <VAR>text</VAR><br>
TO FIX: <VAR>action</VAR> <VAR>tag</VAR><br>
</pre>
<br><br> The colons, new line characters and the <CODE>TO FIX</CODE> string are
inserted if necessary, i.e., if the corresponding parameter is not
ignored.
<br><br> This function is specified in the X/Open Portability Guide. It is also
available on all systems derived from System V.
<br><br> The function returns the value <CODE>MM_OK</CODE> if no error occurred. If
only the printing to standard error failed, it returns <CODE>MM_NOMSG</CODE>.
If printing to the console fails, it returns <CODE>MM_NOCON</CODE>. If
nothing is printed <CODE>MM_NOTOK</CODE> is returned. Among situations where
all outputs fail this last value is also returned if a parameter value
is incorrect.
sq~wtstdio.htfmtmsg.hxq~ ìtolong int classification, const char *label, int severity, const char *text, const char *action, const char *tagtinttfnmatchsq~
tc
This function tests whether the string <VAR>string</VAR> matches the pattern
<VAR>pattern</VAR>. It returns <CODE>0</CODE> if they do match; otherwise, it
returns the nonzero value <CODE>FNM_NOMATCH</CODE>. The arguments
<VAR>pattern</VAR> and <VAR>string</VAR> are both strings.
<br><br> The argument <VAR>flags</VAR> is a combination of flag bits that alter the
details of matching. See below for a list of the defined flags.
<br><br> In the GNU C Library, <CODE>fnmatch</CODE> cannot experience an ``error''---it
always returns an answer for whether the match succeeds. However, other
implementations of <CODE>fnmatch</CODE> might sometimes report ``errors''.
They would do so by returning nonzero values that are not equal to
<CODE>FNM_NOMATCH</CODE>.
sq~wt fnmatch.hxq~ ôt2const char *pattern, const char *string, int flagstinttfopensq~
t7
The <CODE>fopen</CODE> function opens a stream for I/O to the file
<VAR>filename</VAR>, and returns a pointer to the stream.
<br><br> The <VAR>opentype</VAR> argument is a string that controls how the file is
opened and specifies attributes of the resulting stream. It must begin
with one of the following sequences of characters:
<br><br> <DL>
<DT><SAMP>r</SAMP>
<DD>
Open an existing file for reading only.
<br><br> <DT><SAMP>w</SAMP>
<DD>
Open the file for writing only. If the file already exists, it is
truncated to zero length. Otherwise a new file is created.
<br><br> <DT><SAMP>a</SAMP>
<DD>
Open a file for append access; that is, writing at the end of file only.
If the file already exists, its initial contents are unchanged and
output to the stream is appended to the end of the file.
Otherwise, a new, empty file is created.
<br><br> <DT><SAMP>r+</SAMP>
<DD>
Open an existing file for both reading and writing. The initial contents
of the file are unchanged and the initial file position is at the
beginning of the file.
<br><br> <DT><SAMP>w+</SAMP>
<DD>
Open a file for both reading and writing. If the file already exists, it
is truncated to zero length. Otherwise, a new file is created.
<br><br> <DT><SAMP>a+</SAMP>
<DD>
Open or create file for both reading and appending. If the file exists,
its initial contents are unchanged. Otherwise, a new file is created.
The initial file position for reading is at the beginning of the file,
but output is always appended to the end of the file.
</DL>
<br><br> As you can see, <samp>+</samp> requests a stream that can do both input and
output. When using such a stream, you must call <CODE>fflush</CODE>
or a file positioning function such as
<CODE>fseek</CODE> when switching from reading
to writing or vice versa. Otherwise, internal buffers might not be
emptied properly.
<br><br> Additional characters may appear after these to specify flags for the
call. Always put the mode (<samp>r</samp>, <samp>w+</samp>, etc.) first; that is
the only part you are guaranteed will be understood by all systems.
<br><br> The GNU C library defines one additional character for use in
<VAR>opentype</VAR>: the character <samp>x</samp> insists on creating a new
file---if a file <VAR>filename</VAR> already exists, <CODE>fopen</CODE> fails
rather than opening it. If you use <samp>x</samp> you are guaranteed that
you will not clobber an existing file. This is equivalent to the
<CODE>O_EXCL</CODE> option to the <CODE>open</CODE> function .
<br><br> The character <samp>b</samp> in <VAR>opentype</VAR> has a standard meaning; it
requests a binary stream rather than a text stream. But this makes no
difference in POSIX systems (including the GNU system). If both
<samp>+</samp> and <samp>b</samp> are specified, they can appear in either order.
.
<br><br> orientation
, stream
If the <VAR>opentype</VAR> string contains the sequence
<CODE>,ccs=<VAR>STRING</VAR></CODE> then <VAR>STRING</VAR> is taken as the name of a
coded character set and <CODE>fopen</CODE> will mark the stream as
wide-oriented which appropriate conversion functions in place to convert
from and to the character set <VAR>STRING</VAR> is place. Any other stream
is opened initially unoriented and the orientation is decided with the
first file operation. If the first operation is a wide character
operation, the stream is not only marked as wide-oriented, also the
conversion functions to convert to the coded character set used for the
current locale are loaded. This will not change anymore from this point
on even if the locale selected for the <CODE>LC_CTYPE</CODE> category is
changed.
<br><br> Any other characters in <VAR>opentype</VAR> are simply ignored. They may be
meaningful in other systems.
<br><br> If the open fails, <CODE>fopen</CODE> returns a null pointer.
<br><br> When the sources are compiling with <CODE>_FILE_OFFSET_BITS == 64</CODE> on a
32 bit machine this function is in fact <CODE>fopen64</CODE> since the LFS
interface replaces transparently the old interface.
sq~wtstdio.hxq~ ût*const char *filename, const char *opentypetFILE *tfopen64sq~
t…
This function is similar to <CODE>fopen</CODE> but the stream it returns a
pointer for is opened using <CODE>open64</CODE>. Therefore this stream can be
used even on files larger then 2^31 bytes on 32 bit machines.
<br><br> Please note that the return type is still <CODE>FILE *</CODE>. There is no
special <CODE>FILE</CODE> type for the LFS interface.
<br><br> If the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> on a 32
bits machine this function is available under the name <CODE>fopen</CODE>
and so transparently replaces the old interface.
sq~wtstdio.hxq~
t*const char *filename, const char *opentypetFILE *t fopencookiesq~
t
This function actually creates the stream for communicating with the
<VAR>cookie</VAR> using the functions in the <VAR>io-functions</VAR> argument.
The <VAR>opentype</VAR> argument is interpreted as for <CODE>fopen</CODE>;
see Opening Streams. (But note that the ``truncate on
open'' option is ignored.) The new stream is fully buffered.
<br><br> The <CODE>fopencookie</CODE> function returns the newly created stream, or a null
pointer in case of an error.
sq~wtstdio.hxq~
tFvoid *cookie, const char *opentype, cookie_io_functions_t io-functionstFILE *tforksq~
tû
The <CODE>fork</CODE> function creates a new process.
<br><br> If the operation is successful, there are then both parent and child
processes and both see <CODE>fork</CODE> return, but with different values: it
returns a value of <CODE>0</CODE> in the child process and returns the child's
process ID in the parent process.
<br><br> If process creation failed, <CODE>fork</CODE> returns a value of <CODE>-1</CODE> in
the parent process. The following <CODE>errno</CODE> error conditions are
defined for <CODE>fork</CODE>:
<br><br> <DL>
<DT><CODE>EAGAIN</CODE>
<DD>
There aren't enough system resources to create another process, or the
user already has too many processes running. This means exceeding the
<CODE>RLIMIT_NPROC</CODE> resource limit, which can usually be increased;
.
<br><br> <LI> ENOMEM
The process requires more space than the system can supply.
sq~wtunistd.hxq~
tvoidtpid_ttforkptysq~
tv
This function is similar to the <CODE>openpty</CODE> function, but in
addition, forks a new process and makes the
newly opened slave pseudo-terminal device the controlling terminal
for the child process.
<br><br> If the operation is successful, there are then both parent and child
processes and both see <CODE>forkpty</CODE> return, but with different values:
it returns a value of 0 in the child process and returns the child's
process ID in the parent process.
<br><br> If the allocation of a pseudo-terminal pair or the process creation
failed, <CODE>forkpty</CODE> returns a value of -1 in the parent
process.
<br><br> Warning: The <CODE>forkpty</CODE> function has the same problems with
respect to the <VAR>name</VAR> argument as <CODE>openpty</CODE>.
sq~wtpty.hxq~
tQint *amaster, char *name, const struct termios *termp, const struct winsize *winptintt fpathconfsq~
te
This is just like <CODE>pathconf</CODE> except that an open file descriptor
is used to specify the file for which information is requested, instead
of a file name.
<br><br> The following <CODE>errno</CODE> error conditions are defined for this function:
<br><br> <DL>
<DT><CODE>EBADF</CODE>
<DD>
The <VAR>filedes</VAR> argument is not a valid file descriptor.
<br><br> <LI> EINVAL
The value of <VAR>parameter</VAR> is invalid, or the implementation doesn't
support the <VAR>parameter</VAR> for the specific file.
sq~wtunistd.hxq~
tint filedes, int parametertlong inttfprintfsq~
t¬
This function is just like <CODE>printf</CODE>, except that the output is
written to the stream <VAR>stream</VAR> instead of <CODE>stdout</CODE>.
sq~wtstdio.hxq~
%t'FILE *stream, const char *template, ...tinttfputcsq~
t+
The <CODE>fputc</CODE> function converts the character <VAR>c</VAR> to type
<CODE>unsigned char</CODE>, and writes it to the stream <VAR>stream</VAR>.
<CODE>EOF</CODE> is returned if a write error occurs; otherwise the
character <VAR>c</VAR> is returned.
sq~wtstdio.hxq~
,tint c, FILE *streamtinttfputc_unlockedsq~
t¨
The <CODE>fputc_unlocked</CODE> function is equivalent to the <CODE>fputc</CODE>
function except that it does not implicitly lock the stream.
sq~wtstdio.hxq~
3tint c, FILE *streamtinttfputssq~
tÉ
The function <CODE>fputs</CODE> writes the string <VAR>s</VAR> to the stream
<VAR>stream</VAR>. The terminating null character is not written.
This function does <EM>not</EM> add a newline character, either.
It outputs only the characters in the string.
<br><br> This function returns <CODE>EOF</CODE> if a write error occurs, and otherwise
a non-negative value.
<br><br> For example:
<br><br> <pre><br>
fputs ("Are ", stdout);<br>
fputs ("you ", stdout);<br>
fputs ("hungry?\n", stdout);<br>
</pre>
<br><br>
outputs the text <samp>Are you hungry?</samp> followed by a newline.
sq~wtstdio.hxq~
:tconst char *s, FILE *streamtinttfputs_unlockedsq~
tÜ
The <CODE>fputs_unlocked</CODE> function is equivalent to the <CODE>fputs</CODE>
function except that it does not implicitly lock the stream.
<br><br> This function is a GNU extension.
sq~wtstdio.hxq~
Atconst char *s, FILE *streamtinttfputwcsq~
tø
The <CODE>fputwc</CODE> function writes the wide character <VAR>wc</VAR> to the
stream <VAR>stream</VAR>. <CODE>WEOF</CODE> is returned if a write error occurs;
otherwise the character <VAR>wc</VAR> is returned.
sq~wtwchar.hxq~
Htwchar_t wc, FILE *streamtwint_ttfputwc_unlockedsq~
tÞ
The <CODE>fputwc_unlocked</CODE> function is equivalent to the <CODE>fputwc</CODE>
function except that it does not implicitly lock the stream.
<br><br> This function is a GNU extension.
sq~wtwchar.hxq~
Otwint_t wc, FILE *streamtwint_ttfputwssq~
t½
The function <CODE>fputws</CODE> writes the wide character string <VAR>ws</VAR> to
the stream <VAR>stream</VAR>. The terminating null character is not written.
This function does <EM>not</EM> add a newline character, either. It
outputs only the characters in the string.
<br><br> This function returns <CODE>WEOF</CODE> if a write error occurs, and otherwise
a non-negative value.
sq~wtwchar.hxq~
Vtconst wchar_t *ws, FILE *streamtinttfputws_unlockedsq~
tÞ
The <CODE>fputws_unlocked</CODE> function is equivalent to the <CODE>fputws</CODE>
function except that it does not implicitly lock the stream.
<br><br> This function is a GNU extension.
sq~wtwchar.hxq~
]tconst wchar_t *ws, FILE *streamtinttfreadsq~
t×
This function reads up to <VAR>count</VAR> objects of size <VAR>size</VAR> into
the array <VAR>data</VAR>, from the stream <VAR>stream</VAR>. It returns the
number of objects actually read, which might be less than <VAR>count</VAR> if
a read error occurs or the end of the file is reached. This function
returns a value of zero (and doesn't read anything) if either <VAR>size</VAR>
or <VAR>count</VAR> is zero.
<br><br> If <CODE>fread</CODE> encounters end of file in the middle of an object, it
returns the number of complete objects read, and discards the partial
object. Therefore, the stream remains at the actual end of the file.
sq~wtstdio.hxq~
dt3void *data, size_t size, size_t count, FILE *streamtsize_ttfread_unlockedsq~
tÜ
The <CODE>fread_unlocked</CODE> function is equivalent to the <CODE>fread</CODE>
function except that it does not implicitly lock the stream.
<br><br> This function is a GNU extension.
sq~wtstdio.hxq~
kt3void *data, size_t size, size_t count, FILE *streamtsize_ttfreesq~
tw
The <CODE>free</CODE> function deallocates the block of memory pointed at
by <VAR>ptr</VAR>.
sq~wtstdlib.hxq~
rt void *ptrtvoidtfreopensq~
tµ
This function is like a combination of <CODE>fclose</CODE> and <CODE>fopen</CODE>.
It first closes the stream referred to by <VAR>stream</VAR>, ignoring any
errors that are detected in the process. (Because errors are ignored,
you should not use <CODE>freopen</CODE> on an output stream if you have
actually done any output using the stream.) Then the file named by
<VAR>filename</VAR> is opened with mode <VAR>opentype</VAR> as for <CODE>fopen</CODE>,
and associated with the same stream object <VAR>stream</VAR>.
<br><br> If the operation fails, a null pointer is returned; otherwise,
<CODE>freopen</CODE> returns <VAR>stream</VAR>.
<br><br> <CODE>freopen</CODE> has traditionally been used to connect a standard stream
such as <CODE>stdin</CODE> with a file of your own choice. This is useful in
programs in which use of a standard stream for certain purposes is
hard-coded. In the GNU C library, you can simply close the standard
streams and open new ones with <CODE>fopen</CODE>. But other systems lack
this ability, so using <CODE>freopen</CODE> is more portable.
<br><br> When the sources are compiling with <CODE>_FILE_OFFSET_BITS == 64</CODE> on a
32 bit machine this function is in fact <CODE>freopen64</CODE> since the LFS
interface replaces transparently the old interface.
sq~wtstdio.hxq~
yt8const char *filename, const char *opentype, FILE *streamtFILE *t freopen64sq~
t¯
This function is similar to <CODE>freopen</CODE>. The only difference is that
on 32 bit machine the stream returned is able to read beyond the
2^31 bytes limits imposed by the normal interface. It should be
noted that the stream pointed to by <VAR>stream</VAR> need not be opened
using <CODE>fopen64</CODE> or <CODE>freopen64</CODE> since its mode is not important
for this function.
<br><br> If the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> on a 32
bits machine this function is available under the name <CODE>freopen</CODE>
and so transparently replaces the old interface.
sq~wtstdio.hxq~
€t8const char *filename, const char *opentype, FILE *streamtFILE *tfrexpsq~
t;
These functions are used to split the number <VAR>value</VAR>
into a normalized fraction and an exponent.
<br><br> If the argument <VAR>value</VAR> is not zero, the return value is <VAR>value</VAR>
times a power of two, and is always in the range 1/2 (inclusive) to 1
(exclusive). The corresponding exponent is stored in
<CODE>*<VAR>exponent</VAR></CODE>; the return value multiplied by 2 raised to this
exponent equals the original number <VAR>value</VAR>.
<br><br> For example, <CODE>frexp (12.8, &exponent)</CODE> returns <CODE>0.8</CODE> and
stores <CODE>4</CODE> in <CODE>exponent</CODE>.
<br><br> If <VAR>value</VAR> is zero, then the return value is zero and
zero is stored in <CODE>*<VAR>exponent</VAR></CODE>.
sq~wtmath.hxq~
‡tdouble value, int *exponenttdoubletfrexpfsq~
t;
These functions are used to split the number <VAR>value</VAR>
into a normalized fraction and an exponent.
<br><br> If the argument <VAR>value</VAR> is not zero, the return value is <VAR>value</VAR>
times a power of two, and is always in the range 1/2 (inclusive) to 1
(exclusive). The corresponding exponent is stored in
<CODE>*<VAR>exponent</VAR></CODE>; the return value multiplied by 2 raised to this
exponent equals the original number <VAR>value</VAR>.
<br><br> For example, <CODE>frexp (12.8, &exponent)</CODE> returns <CODE>0.8</CODE> and
stores <CODE>4</CODE> in <CODE>exponent</CODE>.
<br><br> If <VAR>value</VAR> is zero, then the return value is zero and
zero is stored in <CODE>*<VAR>exponent</VAR></CODE>.
sq~wtmath.hxq~
Žtfloat value, int *exponenttfloattfrexplsq~
t;
These functions are used to split the number <VAR>value</VAR>
into a normalized fraction and an exponent.
<br><br> If the argument <VAR>value</VAR> is not zero, the return value is <VAR>value</VAR>
times a power of two, and is always in the range 1/2 (inclusive) to 1
(exclusive). The corresponding exponent is stored in
<CODE>*<VAR>exponent</VAR></CODE>; the return value multiplied by 2 raised to this
exponent equals the original number <VAR>value</VAR>.
<br><br> For example, <CODE>frexp (12.8, &exponent)</CODE> returns <CODE>0.8</CODE> and
stores <CODE>4</CODE> in <CODE>exponent</CODE>.
<br><br> If <VAR>value</VAR> is zero, then the return value is zero and
zero is stored in <CODE>*<VAR>exponent</VAR></CODE>.
sq~wtmath.hxq~
•t long double value, int *exponentt long doubletfscanfsq~
t¨
This function is just like <CODE>scanf</CODE>, except that the input is read
from the stream <VAR>stream</VAR> instead of <CODE>stdin</CODE>.
sq~wtstdio.hxq~
œt'FILE *stream, const char *template, ...tinttfseeksq~
tÅ
The <CODE>fseek</CODE> function is used to change the file position of the
stream <VAR>stream</VAR>. The value of <VAR>whence</VAR> must be one of the
constants <CODE>SEEK_SET</CODE>, <CODE>SEEK_CUR</CODE>, or <CODE>SEEK_END</CODE>, to
indicate whether the <VAR>offset</VAR> is relative to the beginning of the
file, the current file position, or the end of the file, respectively.
<br><br> This function returns a value of zero if the operation was successful,
and a nonzero value to indicate failure. A successful call also clears
the end-of-file indicator of <VAR>stream</VAR> and discards any characters
that were ``pushed back'' by the use of <CODE>ungetc</CODE>.
<br><br> <CODE>fseek</CODE> either flushes any buffered output before setting the file
position or else remembers it so it will be written later in its proper
place in the file.
sq~wtstdio.hxq~
£t)FILE *stream, long int offset, int whencetinttfseekosq~
tú
This function is similar to <CODE>fseek</CODE> but it corrects a problem with
<CODE>fseek</CODE> in a system with POSIX types. Using a value of type
<CODE>long int</CODE> for the offset is not compatible with POSIX.
<CODE>fseeko</CODE> uses the correct type <CODE>off_t</CODE> for the <VAR>offset</VAR>
parameter.
<br><br> For this reason it is a good idea to prefer <CODE>ftello</CODE> whenever it is
available since its functionality is (if different at all) closer the
underlying definition.
<br><br> The functionality and return value is the same as for <CODE>fseek</CODE>.
<br><br> The function is an extension defined in the Unix Single Specification
version 2.
<br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> on a
32 bit system this function is in fact <CODE>fseeko64</CODE>. I.e., the
LFS interface transparently replaces the old interface.
sq~wtstdio.hxq~
ªt&FILE *stream, off_t offset, int whencetinttfseeko64sq~
tÅ
This function is similar to <CODE>fseeko</CODE> with the only difference that
the <VAR>offset</VAR> parameter is of type <CODE>off64_t</CODE>. This also
requires that the stream <VAR>stream</VAR> was opened using either
<CODE>fopen64</CODE>, <CODE>freopen64</CODE>, or <CODE>tmpfile64</CODE> since otherwise
the underlying file operations to position the file pointer beyond the
2^31 bytes limit might fail.
<br><br> If the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> on a 32
bits machine this function is available under the name <CODE>fseeko</CODE>
and so transparently replaces the old interface.
sq~wtstdio.hxq~
±t(FILE *stream, off64_t offset, int whencetinttfsetpossq~
tQ
This function sets the file position indicator for the stream <VAR>stream</VAR>
to the position <VAR>position</VAR>, which must have been set by a previous
call to <CODE>fgetpos</CODE> on the same stream. If successful, <CODE>fsetpos</CODE>
clears the end-of-file indicator on the stream, discards any characters
that were ``pushed back'' by the use of <CODE>ungetc</CODE>, and returns a value
of zero. Otherwise, <CODE>fsetpos</CODE> returns a nonzero value and stores
an implementation-defined positive value in <CODE>errno</CODE>.
<br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> on a
32 bit system the function is in fact <CODE>fsetpos64</CODE>. I.e., the LFS
interface transparently replaces the old interface.
sq~wtstdio.hxq~
¸t$FILE *stream, const fpos_t *positiontintt fsetpos64sq~
tË
This function is similar to <CODE>fsetpos</CODE> but the file position used
for positioning is provided in a variable of type <CODE>fpos64_t</CODE> to
which <VAR>position</VAR> points.
<br><br> If the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> on a 32
bits machine this function is available under the name <CODE>fsetpos</CODE>
and so transparently replaces the old interface.
sq~wtstdio.hxq~
¿t&FILE *stream, const fpos64_t *positiontinttfstatsq~
t
The <CODE>fstat</CODE> function is like <CODE>stat</CODE>, except that it takes an
open file descriptor as an argument instead of a file name.
.
<br><br> Like <CODE>stat</CODE>, <CODE>fstat</CODE> returns <CODE>0</CODE> on success and <CODE>-1</CODE>
on failure. The following <CODE>errno</CODE> error conditions are defined for
<CODE>fstat</CODE>:
<br><br> <DL>
<DT><CODE>EBADF</CODE>
<DD>
The <VAR>filedes</VAR> argument is not a valid file descriptor.
<br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> this
function is in fact <CODE>fstat64</CODE> since the LFS interface transparently
replaces the normal implementation.
sq~wt
sys/stat.hxq~
Ætint filedes, struct stat *buftinttfstat64sq~
t‘
This function is similar to <CODE>fstat</CODE> but is able to work on large
files on 32-bit platforms. For large files the file descriptor
<VAR>filedes</VAR> should be obtained by <CODE>open64</CODE> or <CODE>creat64</CODE>.
The <VAR>buf</VAR> pointer points to a variable of type <CODE>struct stat64</CODE>
which is able to represent the larger values.
<br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> this
function is available under the name <CODE>fstat</CODE> and so transparently
replaces the interface for small files on 32-bit machines.
sq~wt
sys/stat.hxq~
Ítint filedes, struct stat64 *buftinttfsyncsq~
tß
The <CODE>fsync</CODE> function can be used to make sure all data associated with
the open file <VAR>fildes</VAR> is written to the device associated with the
descriptor. The function call does not return unless all actions have
finished.
<br><br> A prototype for <CODE>fsync</CODE> can be found in <TT>unistd.h</TT>.
<br><br> This function is a cancellation point in multi-threaded programs. This
is a problem if the thread allocates some resources (like memory, file
descriptors, semaphores or whatever) at the time <CODE>fsync</CODE> is
called. If the thread gets canceled these resources stay allocated
until the program ends. To avoid this, calls to <CODE>fsync</CODE> should be
protected using cancellation handlers.
<br><br> The return value of the function is zero if no error occurred. Otherwise
it is -1 and the global variable <VAR>errno</VAR> is set to the
following values:
<DL>
<DT><CODE>EBADF</CODE>
<DD>
The descriptor <VAR>fildes</VAR> is not valid.
<br><br> <LI> EINVAL
No synchronization is possible since the system does not implement this.
sq~wtunistd.hxq~
Ôt
int fildestinttftellsq~
tŽ
This function returns the current file position of the stream
<VAR>stream</VAR>.
<br><br> This function can fail if the stream doesn't support file positioning,
or if the file position can't be represented in a <CODE>long int</CODE>, and
possibly for other reasons as well. If a failure occurs, a value of
<CODE>-1</CODE> is returned.
sq~wtstdio.hxq~
Ût FILE *streamtlong inttftellosq~
t„
The <CODE>ftello</CODE> function is similar to <CODE>ftell</CODE>, except that it
returns a value of type <CODE>off_t</CODE>. Systems which support this type
use it to describe all file positions, unlike the POSIX specification
which uses a long int. The two are not necessarily the same size.
Therefore, using ftell can lead to problems if the implementation is
written on top of a POSIX compliant low-level I/O implementation, and using
<CODE>ftello</CODE> is preferable whenever it is available.
<br><br> If this function fails it returns <CODE>(off_t) -1</CODE>. This can happen due
to missing support for file positioning or internal errors. Otherwise
the return value is the current file position.
<br><br> The function is an extension defined in the Unix Single Specification
version 2.
<br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> on a
32 bit system this function is in fact <CODE>ftello64</CODE>. I.e., the
LFS interface transparently replaces the old interface.
sq~wtstdio.hxq~
ât FILE *streamtoff_ttftello64sq~
t
This function is similar to <CODE>ftello</CODE> with the only difference that
the return value is of type <CODE>off64_t</CODE>. This also requires that the
stream <VAR>stream</VAR> was opened using either <CODE>fopen64</CODE>,
<CODE>freopen64</CODE>, or <CODE>tmpfile64</CODE> since otherwise the underlying
file operations to position the file pointer beyond the 2^31
bytes limit might fail.
<br><br> If the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> on a 32
bits machine this function is available under the name <CODE>ftello</CODE>
and so transparently replaces the old interface.
sq~wtstdio.hxq~
ét FILE *streamtoff64_tt ftruncatesq~
t u
<br><br> This is like <CODE>truncate</CODE>, but it works on a file descriptor <VAR>fd</VAR>
for an opened file instead of a file name to identify the object. The
file must be opened for writing to successfully carry out the operation.
<br><br> The POSIX standard leaves it implementation defined what happens if the
specified new <VAR>length</VAR> of the file is bigger than the original size.
The <CODE>ftruncate</CODE> function might simply leave the file alone and do
nothing or it can increase the size to the desired size. In this later
case the extended area should be zero-filled. So using <CODE>ftruncate</CODE>
is no reliable way to increase the file size but if it is possible it is
probably the fastest way. The function also operates on POSIX shared
memory segments if these are implemented by the system.
<br><br> <CODE>ftruncate</CODE> is especially useful in combination with <CODE>mmap</CODE>.
Since the mapped region must have a fixed size one cannot enlarge the
file by writing something beyond the last mapped page. Instead one has
to enlarge the file itself and then remap the file with the new size.
The example below shows how this works.
<br><br> When the source file is compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> the
<CODE>ftruncate</CODE> function is in fact <CODE>ftruncate64</CODE> and the type
<CODE>off_t</CODE> has 64 bits which makes it possible to handle files up to
2^63 bytes in length.
<br><br> The return value is 0 for success, or -1 for an error. The
following errors may occur:
<br><br> <DL>
<br><br> <DT><CODE>EBADF</CODE>
<DD>
<VAR>fd</VAR> does not correspond to an open file.
<br><br> <LI> EACCES
<VAR>fd</VAR> is a directory or not open for writing.
<br><br> <LI> EINVAL
<VAR>length</VAR> is negative.
<br><br> <LI> EFBIG
The operation would extend the file beyond the limits of the operating system.
<br><br> <LI> EIO
A hardware I/O error occurred.
<br><br> <LI> EPERM
The file is "append-only" or "immutable".
<br><br> <LI> EINTR
The operation was interrupted by a signal.
<br><br> <br><br>
<br><br>
sq~wtunistd.hxq~
ðtint fd, off_t lengthtintt ftruncate64sq~
t
This function is similar to the <CODE>ftruncate</CODE> function. The
difference is that the <VAR>length</VAR> argument is 64 bits wide even on 32
bits machines which allows the handling of files with sizes up to
2^63 bytes.
<br><br> When the source file is compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> on a
32 bits machine this function is actually available under the name
<CODE>ftruncate</CODE> and so transparently replaces the 32 bits interface.
sq~wtunistd.hxq~
÷tint id, off64_t lengthtintt ftrylockfilesq~
tÁ
The <CODE>ftrylockfile</CODE> function tries to acquire the internal locking
object associated with the stream <VAR>stream</VAR> just like
<CODE>flockfile</CODE>. But unlike <CODE>flockfile</CODE> this function does not
block if the lock is not available. <CODE>ftrylockfile</CODE> returns zero if
the lock was successfully acquired. Otherwise the stream is locked by
another thread.
sq~wtstdio.hxq~
þt FILE *streamtinttftwsq~
t
The <CODE>ftw</CODE> function calls the callback function given in the
parameter <VAR>func</VAR> for every item which is found in the directory
specified by <VAR>filename</VAR> and all directories below. The function
follows symbolic links if necessary but does not process an item twice.
If <VAR>filename</VAR> is not a directory then it itself is the only object
returned to the callback function.
<br><br> The file name passed to the callback function is constructed by taking
the <VAR>filename</VAR> parameter and appending the names of all passed
directories and then the local file name. So the callback function can
use this parameter to access the file. <CODE>ftw</CODE> also calls
<CODE>stat</CODE> for the file and passes that information on to the callback
function. If this <CODE>stat</CODE> call was not successful the failure is
indicated by setting the third argument of the callback function to
<CODE>FTW_NS</CODE>. Otherwise it is set according to the description given
in the account of <CODE>__ftw_func_t</CODE> above.
<br><br> The callback function is expected to return 0 to indicate that no
error occurred and that processing should continue. If an error
occurred in the callback function or it wants <CODE>ftw</CODE> to return
immediately, the callback function can return a value other than
0. This is the only correct way to stop the function. The
program must not use <CODE>setjmp</CODE> or similar techniques to continue
from another place. This would leave resources allocated by the
<CODE>ftw</CODE> function unfreed.
<br><br> The <VAR>descriptors</VAR> parameter to <CODE>ftw</CODE> specifies how many file
descriptors it is allowed to consume. The function runs faster the more
descriptors it can use. For each level in the directory hierarchy at
most one descriptor is used, but for very deep ones any limit on open
file descriptors for the process or the system may be exceeded.
Moreover, file descriptor limits in a multi-threaded program apply to
all the threads as a group, and therefore it is a good idea to supply a
reasonable limit to the number of open descriptors.
<br><br> The return value of the <CODE>ftw</CODE> function is 0 if all callback
function calls returned 0 and all actions performed by the
<CODE>ftw</CODE> succeeded. If a function call failed (other than calling
<CODE>stat</CODE> on an item) the function returns -1. If a callback
function returns a value other than 0 this value is returned as
the return value of <CODE>ftw</CODE>.
<br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> on a
32-bit system this function is in fact <CODE>ftw64</CODE>, i.e., the LFS
interface transparently replaces the old interface.
sq~wtftw.hxq~ t8const char *filename, __ftw_func_t func, int descriptorstinttftw64sq~
t
This function is similar to <CODE>ftw</CODE> but it can work on filesystems
with large files. File information is reported using a variable of type
<CODE>struct stat64</CODE> which is passed by reference to the callback
function.
<br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> on a
32-bit system this function is available under the name <CODE>ftw</CODE> and
transparently replaces the old implementation.
sq~wtftw.hxq~ t:const char *filename, __ftw64_func_t func, int descriptorstintt funlockfilesq~
t
The <CODE>funlockfile</CODE> function releases the internal locking object of
the stream <VAR>stream</VAR>. The stream must have been locked before by a
call to <CODE>flockfile</CODE> or a successful call of <CODE>ftrylockfile</CODE>.
The implicit locking performed by the stream operations do not count.
The <CODE>funlockfile</CODE> function does not return an error status and the
behavior of a call for a stream which is not locked by the current
thread is undefined.
sq~wtstdio.hxq~ t FILE *streamtvoidtfutimessq~
tÝ
This function is like <CODE>utimes</CODE>, except that it takes an open file
descriptor as an argument instead of a file name. . This function comes from FreeBSD, and is not available on all
platforms (if not available, it will fail with <CODE>ENOSYS</CODE>).
<br><br> Like <CODE>utimes</CODE>, <CODE>futimes</CODE> returns <CODE>0</CODE> on success and <CODE>-1</CODE>
on failure. The following <CODE>errno</CODE> error conditions are defined for
<CODE>futimes</CODE>:
<br><br> <DL>
<DT><CODE>EACCES</CODE>
<DD>
There is a permission problem in the case where a null pointer was
passed as the <VAR>times</VAR> argument. In order to update the time stamp on
the file, you must either be the owner of the file, have write
permission for the file, or be a privileged user.
<br><br> <LI> EBADF
The <VAR>filedes</VAR> argument is not a valid file descriptor.
<br><br> <LI> EPERM
If the <VAR>times</VAR> argument is not a null pointer, you must either be
the owner of the file or be a privileged user.
<br><br> <LI> EROFS
The file lives on a read-only file system.
sq~wt
sys/time.hxq~ tint fd, struct timeval tvp[2]tinttfwidesq~
t”
<br><br> The <CODE>fwide</CODE> function can be used to set and query the state of the
orientation of the stream <VAR>stream</VAR>. If the <VAR>mode</VAR> parameter has
a positive value the streams get wide oriented, for negative values
narrow oriented. It is not possible to overwrite previous orientations
with <CODE>fwide</CODE>. I.e., if the stream <VAR>stream</VAR> was already
oriented before the call nothing is done.
<br><br> If <VAR>mode</VAR> is zero the current orientation state is queried and
nothing is changed.
<br><br> The <CODE>fwide</CODE> function returns a negative value, zero, or a positive
value if the stream is narrow, not at all, or wide oriented
respectively.
<br><br> This function was introduced in Amendment 1 to ISO C90 and is
declared in <TT>wchar.h</TT>.
sq~wtwchar.hxq~ !tFILE *stream, int modetinttfwprintfsq~
t­
This function is just like <CODE>wprintf</CODE>, except that the output is
written to the stream <VAR>stream</VAR> instead of <CODE>stdout</CODE>.
sq~wtwchar.hxq~ (t*FILE *stream, const wchar_t *template, ...tinttfwritesq~
tL
This function writes up to <VAR>count</VAR> objects of size <VAR>size</VAR> from
the array <VAR>data</VAR>, to the stream <VAR>stream</VAR>. The return value is
normally <VAR>count</VAR>, if the call succeeds. Any other value indicates
some sort of error, such as running out of space.
sq~wtstdio.hxq~ /t9const void *data, size_t size, size_t count, FILE *streamtsize_ttfwrite_unlockedsq~
tÞ
The <CODE>fwrite_unlocked</CODE> function is equivalent to the <CODE>fwrite</CODE>
function except that it does not implicitly lock the stream.
<br><br> This function is a GNU extension.
sq~wtstdio.hxq~ 6t9const void *data, size_t size, size_t count, FILE *streamtsize_ttfwscanfsq~
t©
This function is just like <CODE>wscanf</CODE>, except that the input is read
from the stream <VAR>stream</VAR> instead of <CODE>stdin</CODE>.
sq~wtwchar.hxq~ =t*FILE *stream, const wchar_t *template, ...tinttgammasq~
tO
These functions exist for compatibility reasons. They are equivalent to
<CODE>lgamma</CODE> etc. It is better to use <CODE>lgamma</CODE> since for one the
name reflects better the actual computation, moreover <CODE>lgamma</CODE> is
standardized in ISO C99 while <CODE>gamma</CODE> is not.
sq~wtmath.hxq~ Dtdouble xtdoubletgammafsq~
tO
These functions exist for compatibility reasons. They are equivalent to
<CODE>lgamma</CODE> etc. It is better to use <CODE>lgamma</CODE> since for one the
name reflects better the actual computation, moreover <CODE>lgamma</CODE> is
standardized in ISO C99 while <CODE>gamma</CODE> is not.
sq~wtmath.hxq~ Ktfloat xtfloattgammalsq~
tO
These functions exist for compatibility reasons. They are equivalent to
<CODE>lgamma</CODE> etc. It is better to use <CODE>lgamma</CODE> since for one the
name reflects better the actual computation, moreover <CODE>lgamma</CODE> is
standardized in ISO C99 while <CODE>gamma</CODE> is not.
sq~wtmath.hxq~ Rt
long double xt long doubletgcvtsq~
tk
<CODE>gcvt</CODE> is functionally equivalent to <samp>sprintf(buf, "%*g",
ndigit, value</samp>. It is provided only for compatibility's sake. It
returns <VAR>buf</VAR>.
<br><br> If <VAR>ndigit</VAR> decimal digits would exceed the precision of a
<CODE>double</CODE> it is reduced to a system-specific value.
sq~wtstdlib.hxq~ Yt#double value, int ndigit, char *buftchar *tget_avphys_pagessq~
t
The <CODE>get_phys_pages</CODE> function returns the number of available pages of
physical the system has. To get the amount of memory this number has to
be multiplied by the page size.
<br><br> This function is a GNU extension.
sq~wt
sys/sysinfo.hxq~ `tvoidtlong inttget_current_dir_namesq~
tV
This <CODE>get_current_dir_name</CODE> function is basically equivalent to
<CODE>getcwd (NULL, 0)</CODE>. The only difference is that the value of
the <CODE>PWD</CODE> variable is returned if this value is correct. This is a
subtle difference which is visible if the path described by the
<CODE>PWD</CODE> value is using one or more symbol links in which case the
value returned by <CODE>getcwd</CODE> can resolve the symbol links and
therefore yield a different result.
<br><br> This function is a GNU extension.
sq~wtunistd.hxq~ gtvoidtchar *t
get_nprocssq~
t–
The <CODE>get_nprocs</CODE> function returns the number of available processors.
<br><br> This function is a GNU extension.
sq~wt
sys/sysinfo.hxq~ ntvoidtinttget_nprocs_confsq~
tº
The <CODE>get_nprocs_conf</CODE> function returns the number of processors the
operating system configured.
<br><br> This function is a GNU extension.
sq~wt
sys/sysinfo.hxq~ utvoidtinttget_phys_pagessq~
t
The <CODE>get_phys_pages</CODE> function returns the total number of pages of
physical the system has. To get the amount of memory this number has to
be multiplied by the page size.
<br><br> This function is a GNU extension.
sq~wt
sys/sysinfo.hxq~ |tvoidtlong inttgetcsq~
t]
This is just like <CODE>fgetc</CODE>, except that it is permissible (and
typical) for it to be implemented as a macro that evaluates the
<VAR>stream</VAR> argument more than once. <CODE>getc</CODE> is often highly
optimized, so it is usually the best function to use to read a single
character.
sq~wtstdio.hxq~ ƒt FILE *streamtintt
getc_unlockedsq~
t¦
The <CODE>getc_unlocked</CODE> function is equivalent to the <CODE>getc</CODE>
function except that it does not implicitly lock the stream.
sq~wtstdio.hxq~ Št FILE *streamtinttgetcharsq~
t§
The <CODE>getchar</CODE> function is equivalent to <CODE>getc</CODE> with <CODE>stdin</CODE>
as the value of the <VAR>stream</VAR> argument.
sq~wtstdio.hxq~ ‘tvoidtinttgetchar_unlockedsq~
t¬
The <CODE>getchar_unlocked</CODE> function is equivalent to the <CODE>getchar</CODE>
function except that it does not implicitly lock the stream.
sq~wtstdio.hxq~ ˜tvoidtintt
getcontextsq~
t
The <CODE>getcontext</CODE> function initializes the variable pointed to by
<VAR>ucp</VAR> with the context of the calling thread. The context contains
the content of the registers, the signal mask, and the current stack.
Executing the contents would start at the point where the
<CODE>getcontext</CODE> call just returned.
<br><br> The function returns <CODE>0</CODE> if successful. Otherwise it returns
<CODE>-1</CODE> and sets <VAR>errno</VAR> accordingly.
sq~wt
ucontext.hxq~ Ÿtucontext_t *ucptinttgetcwdsq~
t\
The <CODE>getcwd</CODE> function returns an absolute file name representing
the current working directory, storing it in the character array
<VAR>buffer</VAR> that you provide. The <VAR>size</VAR> argument is how you tell
the system the allocation size of <VAR>buffer</VAR>.
<br><br> The GNU library version of this function also permits you to specify a
null pointer for the <VAR>buffer</VAR> argument. Then <CODE>getcwd</CODE>
allocates a buffer automatically, as with <CODE>malloc</CODE>
. If the <VAR>size</VAR> is greater than
zero, then the buffer is that large; otherwise, the buffer is as large
as necessary to hold the result.
<br><br> The return value is <VAR>buffer</VAR> on success and a null pointer on failure.
The following <CODE>errno</CODE> error conditions are defined for this function:
<br><br> <DL>
<DT><CODE>EINVAL</CODE>
<DD>
The <VAR>size</VAR> argument is zero and <VAR>buffer</VAR> is not a null pointer.
<br><br> <LI> ERANGE
The <VAR>size</VAR> argument is less than the length of the working directory
name. You need to allocate a bigger array and try again.
<br><br> <LI> EACCES
Permission to read or search a component of the file name was denied.
sq~wtunistd.hxq~ ¦tchar *buffer, size_t sizetchar *tgetdatesq~
tý
The interface to <CODE>getdate</CODE> is the simplest possible for a function
to parse a string and return the value. <VAR>string</VAR> is the input
string and the result is returned in a statically-allocated variable.
<br><br> The details about how the string is processed are hidden from the user.
In fact, they can be outside the control of the program. Which formats
are recognized is controlled by the file named by the environment
variable <CODE>DATEMSK</CODE>. This file should contain
lines of valid format strings which could be passed to <CODE>strptime</CODE>.
<br><br> The <CODE>getdate</CODE> function reads these format strings one after the
other and tries to match the input string. The first line which
completely matches the input string is used.
<br><br> Elements not initialized through the format string retain the values
present at the time of the <CODE>getdate</CODE> function call.
<br><br> The formats recognized by <CODE>getdate</CODE> are the same as for
<CODE>strptime</CODE>. See above for an explanation. There are only a few
extensions to the <CODE>strptime</CODE> behavior:
<br><br> <OL>
<LI>
If the <CODE>%Z</CODE> format is given the broken-down time is based on the
current time of the timezone matched, not of the current timezone of the
runtime environment.
<br><br> <EM>Note</EM>: This is not implemented (currently). The problem is that
timezone names are not unique. If a fixed timezone is assumed for a
given string (say <CODE>EST</CODE> meaning US East Coast time), then uses for
countries other than the USA will fail. So far we have found no good
solution to this.
<br><br> <LI>
If only the weekday is specified the selected day depends on the current
date. If the current weekday is greater or equal to the <CODE>tm_wday</CODE>
value the current week's day is chosen, otherwise the day next week is chosen.
<br><br> <LI>
A similar heuristic is used when only the month is given and not the
year. If the month is greater than or equal to the current month, then
the current year is used. Otherwise it wraps to next year. The first
day of the month is assumed if one is not explicitly specified.
<br><br> <LI>
The current hour, minute, and second are used if the appropriate value is
not set through the format.
<br><br> <LI>
If no date is given tomorrow's date is used if the time is
smaller than the current time. Otherwise today's date is taken.
</OL>
<br><br> It should be noted that the format in the template file need not only
contain format elements. The following is a list of possible format
strings (taken from the Unix standard):
<br><br> <pre><br>
%m<br>
%A %B %d, %Y %H:%M:%S<br>
%A<br>
%B<br>
%m/%d/%y %I %p<br>
%d,%m,%Y %H:%M<br>
at %A the %dst of %B in %Y<br>
run job at %I %p,%B %dnd<br>
%A den %d. %B %Y %H.%M Uhr<br>
</pre>
<br><br> As you can see, the template list can contain very specific strings like
<CODE>run job at %I %p,%B %dnd</CODE>. Using the above list of templates and
assuming the current time is Mon Sep 22 12:19:47 EDT 1986 we can obtain the
following results for the given input.
<br><br> <DL>
<DT><pre>Input Match Result</pre>
<DD><br> <DT><pre>Mon %a Mon Sep 22 12:19:47 EDT 1986</pre>
<DD><br> <DT><pre>Sun %a Sun Sep 28 12:19:47 EDT 1986</pre>
<DD><br> <DT><pre>Fri %a Fri Sep 26 12:19:47 EDT 1986</pre>
<DD><br> <DT><pre>September %B Mon Sep 1 12:19:47 EDT 1986</pre>
<DD><br> <DT><pre>January %B Thu Jan 1 12:19:47 EST 1987</pre>
<DD><br> <DT><pre>December %B Mon Dec 1 12:19:47 EST 1986</pre>
<DD><br> <DT><pre>Sep Mon %b %a Mon Sep 1 12:19:47 EDT 1986</pre>
<DD><br> <DT><pre>Jan Fri %b %a Fri Jan 2 12:19:47 EST 1987</pre>
<DD><br> <DT><pre>Dec Mon %b %a Mon Dec 1 12:19:47 EST 1986</pre>
<DD><br> <DT><pre>Jan Wed 1989 %b %a %Y Wed Jan 4 12:19:47 EST 1989</pre>
<DD><br> <DT><pre>Fri 9 %a %H Fri Sep 26 09:00:00 EDT 1986</pre>
<DD><br> <DT><pre>Feb 10:30 %b %H:%S Sun Feb 1 10:00:30 EST 1987</pre>
<DD><br> <DT><pre>10:30 %H:%M Tue Sep 23 10:30:00 EDT 1986</pre>
<DD><br> <DT><pre>13:30 %H:%M Mon Sep 22 13:30:00 EDT 1986</pre>
<DD><br> </DL>
<br><br> The return value of the function is a pointer to a static variable of
type <CODE>struct tm</CODE>, or a null pointer if an error occurred. The
result is only valid until the next <CODE>getdate</CODE> call, making this
function unusable in multi-threaded applications.
<br><br> The <CODE>errno</CODE> variable is <EM>not</EM> changed. Error conditions are
stored in the global variable <CODE>getdate_err</CODE>. See the
description above for a list of the possible error values.
<br><br> <EM>Warning:</EM> The <CODE>getdate</CODE> function should <EM>never</EM> be
used in SUID-programs. The reason is obvious: using the
<CODE>DATEMSK</CODE> environment variable you can get the function to open
any arbitrary file and chances are high that with some bogus input
(such as a binary file) the program will crash.
sq~wttime.hxq~ ­tconst char *stringt struct tm *t getdate_rsq~
th
The <CODE>getdate_r</CODE> function is the reentrant counterpart of
<CODE>getdate</CODE>. It does not use the global variable <CODE>getdate_err</CODE>
to signal an error, but instead returns an error code. The same error
codes as described in the <CODE>getdate_err</CODE> documentation above are
used, with 0 meaning success.
<br><br> Moreover, <CODE>getdate_r</CODE> stores the broken-down time in the variable
of type <CODE>struct tm</CODE> pointed to by the second argument, rather than
in a static variable.
<br><br> This function is not defined in the Unix standard. Nevertheless it is
available on some other Unix systems as well.
<br><br> The warning against using <CODE>getdate</CODE> in SUID-programs applies to
<CODE>getdate_r</CODE> as well.
sq~wttime.hxq~ ´t!const char *string, struct tm *tptinttgetdelimsq~
tŠ
This function is like <CODE>getline</CODE> except that the character which
tells it to stop reading is not necessarily newline. The argument
<VAR>delimiter</VAR> specifies the delimiter character; <CODE>getdelim</CODE> keeps
reading until it sees that character (or end of file).
<br><br> The text is stored in <VAR>lineptr</VAR>, including the delimiter character
and a terminating null. Like <CODE>getline</CODE>, <CODE>getdelim</CODE> makes
<VAR>lineptr</VAR> bigger if it isn't big enough.
<br><br> <CODE>getline</CODE> is in fact implemented in terms of <CODE>getdelim</CODE>, just
like this:
<br><br> <pre><br>
ssize_t<br>
getline (char **lineptr, size_t *n, FILE *stream)<br>
{<br>
return getdelim (lineptr, n, '\n', stream);<br>
}<br>
</pre>
sq~wtstdio.hxq~ »t6char **lineptr, size_t *n, int delimiter, FILE *streamtssize_ttgetdomainnnamesq~
t”
domain name
domain name
<br><br> <CODE>getdomainname</CODE> returns the NIS (aka YP) domain name of the system
on which it is called. Note that this is not the more popular DNS
domain name. Get that with <CODE>gethostname</CODE>.
<br><br> The specifics of this function are analogous to <CODE>gethostname</CODE>, above.
<br><br>
sq~wtunistd.hxq~ Âtchar *name, size_t lengthtinttgetegidsq~
tb
The <CODE>getegid</CODE> function returns the effective group ID of the process.
sq~wtunistd.hxq~ Étvoidtgid_ttgetenvsq~
t¹
This function returns a string that is the value of the environment
variable <VAR>name</VAR>. You must not modify this string. In some non-Unix
systems not using the GNU library, it might be overwritten by subsequent
calls to <CODE>getenv</CODE> (but not by any other library function). If the
environment variable <VAR>name</VAR> is not defined, the value is a null
pointer.
sq~wtstdlib.hxq~ Ðtconst char *nametchar *tgeteuidsq~
ta
The <CODE>geteuid</CODE> function returns the effective user ID of the process.
sq~wtunistd.hxq~ ×tvoidtuid_ttgetfsentsq~
t6
This function returns the next entry of the <TT>fstab</TT> file. If this
is the first call to any of the functions handling <TT>fstab</TT> since
program start or the last call of <CODE>endfsent</CODE>, the file will be
opened.
<br><br> The function returns a pointer to a variable of type <CODE>struct
fstab</CODE>. This variable is shared by all threads and therefore this
function is not thread-safe. If an error occurred <CODE>getfsent</CODE>
returns a <CODE>NULL</CODE> pointer.
sq~wtfstab.hxq~ Þtvoidtstruct fstab *t getfsfilesq~
t9
This function returns the next entry of the <TT>fstab</TT> file which has
a string equal to <VAR>name</VAR> pointed to by the <CODE>fs_file</CODE> element.
Since there is normally exactly one entry for each mount point it
makes no sense to call this function more than once for the same
argument. If this is the first call to any of the functions handling
<TT>fstab</TT> since program start or the last call of <CODE>endfsent</CODE>,
the file will be opened.
<br><br> The function returns a pointer to a variable of type <CODE>struct
fstab</CODE>. This variable is shared by all threads and therefore this
function is not thread-safe. If an error occurred <CODE>getfsent</CODE>
returns a <CODE>NULL</CODE> pointer.
sq~wtfstab.hxq~ åtconst char *nametstruct fstab *t getfsspecsq~
t<
This function returns the next entry of the <TT>fstab</TT> file which has
a string equal to <VAR>name</VAR> pointed to by the <CODE>fs_spec</CODE> element.
Since there is normally exactly one entry for each special device it
makes no sense to call this function more than once for the same
argument. If this is the first call to any of the functions handling
<TT>fstab</TT> since program start or the last call of <CODE>endfsent</CODE>,
the file will be opened.
<br><br> The function returns a pointer to a variable of type <CODE>struct
fstab</CODE>. This variable is shared by all threads and therefore this
function is not thread-safe. If an error occurred <CODE>getfsent</CODE>
returns a <CODE>NULL</CODE> pointer.
sq~wtfstab.hxq~ ìtconst char *nametstruct fstab *tgetgidsq~
t\
The <CODE>getgid</CODE> function returns the real group ID of the process.
sq~wtunistd.hxq~ ótvoidtgid_ttgetgrentsq~
t�
The <CODE>getgrent</CODE> function reads the next entry from the stream
initialized by <CODE>setgrent</CODE>. It returns a pointer to the entry. The
structure is statically allocated and is overwritten on subsequent calls
to <CODE>getgrent</CODE>. You must copy the contents of the structure if you
wish to save the information.
sq~wtgrp.hxq~ útvoidtstruct group *t
getgrent_rsq~
t9
This function is similar to <CODE>getgrent</CODE> in that it returns the next
entry from the stream initialized by <CODE>setgrent</CODE>. Like
<CODE>fgetgrent_r</CODE>, it places the result in user-supplied buffers
pointed to <VAR>result_buf</VAR> and <VAR>buffer</VAR>.
<br><br> If the function returns zero <VAR>result</VAR> contains a pointer to the data
(normally equal to <VAR>result_buf</VAR>). If errors occurred the return
value is non-zero and <VAR>result</VAR> contains a null pointer.
sq~wtgrp.hxq~ tLstruct group *result_buf, char *buffer, size_t buflen, struct group **resulttinttgetgrgidsq~
t^
This function returns a pointer to a statically-allocated structure
containing information about the group whose group ID is <VAR>gid</VAR>.
This structure may be overwritten by subsequent calls to
<CODE>getgrgid</CODE>.
<br><br> A null pointer indicates there is no group with ID <VAR>gid</VAR>.
sq~wtgrp.hxq~ t gid_t gidtstruct group *t
getgrgid_rsq~
t›
This function is similar to <CODE>getgrgid</CODE> in that it returns
information about the group whose group ID is <VAR>gid</VAR>. However, it
fills the user supplied structure pointed to by <VAR>result_buf</VAR> with
the information instead of using a static buffer. The first
<VAR>buflen</VAR> bytes of the additional buffer pointed to by <VAR>buffer</VAR>
are used to contain additional information, normally strings which are
pointed to by the elements of the result structure.
<br><br> If a group with ID <VAR>gid</VAR> is found, the pointer returned in
<VAR>result</VAR> points to the record which contains the wanted data (i.e.,
<VAR>result</VAR> contains the value <VAR>result_buf</VAR>). If no group is found
or if an error occurred, the pointer returned in <VAR>result</VAR> is a null
pointer. The function returns zero or an error code. If the buffer
<VAR>buffer</VAR> is too small to contain all the needed information, the
error code <CODE>ERANGE</CODE> is returned and <VAR>errno</VAR> is set to
<CODE>ERANGE</CODE>.
sq~wtgrp.hxq~ tWgid_t gid, struct group *result_buf, char *buffer, size_t buflen, struct group **resulttinttgetgrnamsq~
t`
This function returns a pointer to a statically-allocated structure
containing information about the group whose group name is <VAR>name</VAR>.
This structure may be overwritten by subsequent calls to
<CODE>getgrnam</CODE>.
<br><br> A null pointer indicates there is no group named <VAR>name</VAR>.
sq~wtgrp.hxq~ tconst char *nametstruct group *t
getgrnam_rsq~
t¦
This function is similar to <CODE>getgrnam</CODE> in that is returns
information about the group whose group name is <VAR>name</VAR>. Like
<CODE>getgrgid_r</CODE>, it uses the user supplied buffers in
<VAR>result_buf</VAR> and <VAR>buffer</VAR>, not a static buffer.
<br><br> The return values are the same as for <CODE>getgrgid_r</CODE>
<CODE>ERANGE</CODE>.
sq~wtgrp.hxq~ t^const char *name, struct group *result_buf, char *buffer, size_t buflen, struct group **resulttintt getgrouplistsq~
t
The <CODE>getgrouplist</CODE> function scans the group database for all the
groups <VAR>user</VAR> belongs to. Up to *<VAR>ngroups</VAR> group IDs
corresponding to these groups are stored in the array <VAR>groups</VAR>; the
return value from the function is the number of group IDs actually
stored. If *<VAR>ngroups</VAR> is smaller than the total number of groups
found, then <CODE>getgrouplist</CODE> returns a value of <CODE>-1</CODE> and stores
the actual number of groups in *<VAR>ngroups</VAR>. The group <VAR>group</VAR> is
automatically included in the list of groups returned by
<CODE>getgrouplist</CODE>.
<br><br> Here's how to use <CODE>getgrouplist</CODE> to read all supplementary groups
for <VAR>user</VAR>:
<br><br> <pre><br>
<br>
gid_t *<br>
supplementary_groups (char *user)<br>
{<br>
int ngroups = 16;<br>
gid_t *groups<br>
= (gid_t *) xmalloc (ngroups * sizeof (gid_t));<br>
struct passwd *pw = getpwnam (user);<br>
<br><br> if (pw == NULL)<br>
return NULL;<br>
<br><br> if (getgrouplist (pw->pw_name, pw->pw_gid, groups, &ngroups) < 0)<br>
{<br>
groups = xrealloc (ngroups * sizeof (gid_t));<br>
getgrouplist (pw->pw_name, pw->pw_gid, groups, &ngroups);<br>
}<br>
return groups;<br>
}<br>
<br>
</pre>
sq~wtgrp.hxq~ $t:const char *user, gid_t group, gid_t *groups, int *ngroupstintt getgroupssq~
tn
The <CODE>getgroups</CODE> function is used to inquire about the supplementary
group IDs of the process. Up to <VAR>count</VAR> of these group IDs are
stored in the array <VAR>groups</VAR>; the return value from the function is
the number of group IDs actually stored. If <VAR>count</VAR> is smaller than
the total number of supplementary group IDs, then <CODE>getgroups</CODE>
returns a value of <CODE>-1</CODE> and <CODE>errno</CODE> is set to <CODE>EINVAL</CODE>.
<br><br> If <VAR>count</VAR> is zero, then <CODE>getgroups</CODE> just returns the total
number of supplementary group IDs. On systems that do not support
supplementary groups, this will always be zero.
<br><br> Here's how to use <CODE>getgroups</CODE> to read all the supplementary group
IDs:
<br><br> <pre><br>
<br>
gid_t *<br>
read_all_groups (void)<br>
{<br>
int ngroups = getgroups (0, NULL);<br>
gid_t *groups<br>
= (gid_t *) xmalloc (ngroups * sizeof (gid_t));<br>
int val = getgroups (ngroups, groups);<br>
if (val < 0)<br>
{<br>
free (groups);<br>
return NULL;<br>
}<br>
return groups;<br>
}<br>
<br>
</pre>
sq~wtunistd.hxq~ +tint count, gid_t *groupstintt
gethostbyaddrsq~
t‘
The <CODE>gethostbyaddr</CODE> function returns information about the host
with Internet address <VAR>addr</VAR>. The parameter <VAR>addr</VAR> is not
really a pointer to char - it can be a pointer to an IPv4 or an IPv6
address. The <VAR>length</VAR> argument is the size (in bytes) of the address
at <VAR>addr</VAR>. <VAR>format</VAR> specifies the address format; for an IPv4
Internet address, specify a value of <CODE>AF_INET</CODE>; for an IPv6
Internet address, use <CODE>AF_INET6</CODE>.
<br><br> If the lookup fails, <CODE>gethostbyaddr</CODE> returns a null pointer.
sq~wtnetdb.hxq~ 2t+const char *addr, size_t length, int formattstruct hostent *tgethostbyaddr_rsq~
t§
The <CODE>gethostbyaddr_r</CODE> function returns information about the host
with Internet address <VAR>addr</VAR>. The parameter <VAR>addr</VAR> is not
really a pointer to char - it can be a pointer to an IPv4 or an IPv6
address. The <VAR>length</VAR> argument is the size (in bytes) of the address
at <VAR>addr</VAR>. <VAR>format</VAR> specifies the address format; for an IPv4
Internet address, specify a value of <CODE>AF_INET</CODE>; for an IPv6
Internet address, use <CODE>AF_INET6</CODE>.
<br><br> Similar to the <CODE>gethostbyname_r</CODE> function, the caller must provide
buffers for the result and memory used internally. In case of success
the function returns zero. Otherwise the value is an error number where
<CODE>ERANGE</CODE> has the special meaning that the caller-provided buffer is
too small.
sq~wtnetdb.hxq~ 9t­const char *addr, size_t length, int format, struct hostent *restrict result_buf, char *restrict buf, size_t buflen, struct hostent **restrict result, int *restrict h_errnoptintt
gethostbynamesq~
t­
The <CODE>gethostbyname</CODE> function returns information about the host
named <VAR>name</VAR>. If the lookup fails, it returns a null pointer.
sq~wtnetdb.hxq~ @tconst char *nametstruct hostent *tgethostbyname2sq~
tñ
The <CODE>gethostbyname2</CODE> function is like <CODE>gethostbyname</CODE>, but
allows the caller to specify the desired address family (e.g.:
<CODE>AF_INET</CODE> or <CODE>AF_INET6</CODE>) of the result.
sq~wtnetdb.hxq~ Gtconst char *name, int aftstruct hostent *tgethostbyname2_rsq~
tö
The <CODE>gethostbyname2_r</CODE> function is like <CODE>gethostbyname_r</CODE>, but
allows the caller to specify the desired address family (e.g.:
<CODE>AF_INET</CODE> or <CODE>AF_INET6</CODE>) for the result.
sq~wtnetdb.hxq~ Ntšconst char *name, int af, struct hostent *restrict result_buf, char *restrict buf, size_t buflen, struct hostent **restrict result, int *restrict h_errnoptinttgethostbyname_rsq~
t£
The <CODE>gethostbyname_r</CODE> function returns information about the host
named <VAR>name</VAR>. The caller must pass a pointer to an object of type
<CODE>struct hostent</CODE> in the <VAR>result_buf</VAR> parameter. In addition
the function may need extra buffer space and the caller must pass an
pointer and the size of the buffer in the <VAR>buf</VAR> and <VAR>buflen</VAR>
parameters.
<br><br> A pointer to the buffer, in which the result is stored, is available in
<CODE>*<VAR>result</VAR></CODE> after the function call successfully returned. If
an error occurs or if no entry is found, the pointer <CODE>*<VAR>result</VAR></CODE>
is a null pointer. Success is signalled by a zero return value. If the
function failed the return value is an error number. In addition to the
errors defined for <CODE>gethostbyname</CODE> it can also be <CODE>ERANGE</CODE>.
In this case the call should be repeated with a larger buffer.
Additional error information is not stored in the global variable
<CODE>h_errno</CODE> but instead in the object pointed to by <VAR>h_errnop</VAR>.
<br><br> Here's a small example:
<pre><br>
struct hostent *<br>
gethostname (char *host)<br>
{<br>
struct hostent hostbuf, *hp;<br>
size_t hstbuflen;<br>
char *tmphstbuf;<br>
int res;<br>
int herr;<br>
<br><br> hstbuflen = 1024;<br>
/* Allocate buffer, remember to free it to avoid memory leakage. */<br>
tmphstbuf = malloc (hstbuflen);<br>
<br><br> while ((res = gethostbyname_r (host, &hostbuf, tmphstbuf, hstbuflen,<br>
&hp, &herr)) == ERANGE)<br>
{<br>
/* Enlarge the buffer. */<br>
hstbuflen *= 2;<br>
tmphstbuf = realloc (tmphstbuf, hstbuflen);<br>
}<br>
/* Check for errors. */<br>
if (res || hp == NULL)<br>
return NULL;<br>
return hp;<br>
}<br>
</pre>
sq~wtnetdb.hxq~ Ut›const char *restrict name, struct hostent *restrict result_buf, char *restrict buf, size_t buflen, struct hostent **restrict result, int *restrict h_errnoptintt
gethostentsq~
t�
This function returns the next entry in the hosts database. It
returns a null pointer if there are no more entries.
sq~wtnetdb.hxq~ \tvoidtstruct hostent *t gethostidsq~
tª
This function returns the ``host ID'' of the machine the program is
running on. By convention, this is usually the primary Internet IP address
of that machine, converted to a <CODE>long int</CODE>. However, on some
systems it is a meaningless but unique number which is hard-coded for
each machine.
<br><br> This is not widely used. It arose in BSD 4.2, but was dropped in BSD 4.4.
It is not required by POSIX.
<br><br> The proper way to query the IP address is to use <CODE>gethostbyname</CODE>
on the results of <CODE>gethostname</CODE>. For more information on IP addresses,
.
sq~wtunistd.hxq~ ctvoidtlong intt gethostnamesq~
tf
This function returns the host name of the system on which it is called,
in the array <VAR>name</VAR>. The <VAR>size</VAR> argument specifies the size of
this array, in bytes. Note that this is <EM>not</EM> the DNS hostname.
If the system participates in DNS, this is the FQDN (see above).
<br><br> The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on failure. In
the GNU C library, <CODE>gethostname</CODE> fails if <VAR>size</VAR> is not large
enough; then you can try again with a larger array. The following
<CODE>errno</CODE> error condition is defined for this function:
<br><br> <DL>
<DT><CODE>ENAMETOOLONG</CODE>
<DD>
The <VAR>size</VAR> argument is less than the size of the host name plus one.
<br><br> On some systems, there is a symbol for the maximum possible host name
length: <CODE>MAXHOSTNAMELEN</CODE>. It is defined in <TT>sys/param.h</TT>.
But you can't count on this to exist, so it is cleaner to handle
failure and try again.
<br><br> <CODE>gethostname</CODE> stores the beginning of the host name in <VAR>name</VAR>
even if the host name won't entirely fit. For some purposes, a
truncated host name is good enough. If it is, you can ignore the
error code.
sq~wtunistd.hxq~ jtchar *name, size_t sizetintt getitimersq~
t
The <CODE>getitimer</CODE> function stores information about the timer specified
by <VAR>which</VAR> in the structure pointed at by <VAR>old</VAR>.
<br><br> The return value and error conditions are the same as for <CODE>setitimer</CODE>.
sq~wt
sys/time.hxq~ qt int which, struct itimerval *oldtinttgetlinesq~
tl
This function reads an entire line from <VAR>stream</VAR>, storing the text
(including the newline and a terminating null character) in a buffer
and storing the buffer address in <CODE>*<VAR>lineptr</VAR></CODE>.
<br><br> Before calling <CODE>getline</CODE>, you should place in <CODE>*<VAR>lineptr</VAR></CODE>
the address of a buffer <CODE>*<VAR>n</VAR></CODE> bytes long, allocated with
<CODE>malloc</CODE>. If this buffer is long enough to hold the line,
<CODE>getline</CODE> stores the line in this buffer. Otherwise,
<CODE>getline</CODE> makes the buffer bigger using <CODE>realloc</CODE>, storing the
new buffer address back in <CODE>*<VAR>lineptr</VAR></CODE> and the increased size
back in <CODE>*<VAR>n</VAR></CODE>.
.
<br><br> If you set <CODE>*<VAR>lineptr</VAR></CODE> to a null pointer, and <CODE>*<VAR>n</VAR></CODE>
to zero, before the call, then <CODE>getline</CODE> allocates the initial
buffer for you by calling <CODE>malloc</CODE>.
<br><br> In either case, when <CODE>getline</CODE> returns, <CODE>*<VAR>lineptr</VAR></CODE> is
a <CODE>char *</CODE> which points to the text of the line.
<br><br> When <CODE>getline</CODE> is successful, it returns the number of characters
read (including the newline, but not including the terminating null).
This value enables you to distinguish null characters that are part of
the line from the null character inserted as a terminator.
<br><br> This function is a GNU extension, but it is the recommended way to read
lines from a stream. The alternative standard functions are unreliable.
<br><br> If an error occurs or end of file is reached without any bytes read,
<CODE>getline</CODE> returns <CODE>-1</CODE>.
sq~wtstdio.hxq~ xt'char **lineptr, size_t *n, FILE *streamtssize_tt
getloadavgsq~
t¿
This function gets the 1, 5 and 15 minute load averages of the
system. The values are placed in <VAR>loadavg</VAR>. <CODE>getloadavg</CODE> will
place at most <VAR>nelem</VAR> elements into the array but never more than
three elements. The return value is the number of elements written to
<VAR>loadavg</VAR>, or -1 on error.
<br><br> This function is declared in <TT>stdlib.h</TT>.
sq~wtstdlib.hxq~ tdouble loadavg[], int nelemtinttgetloginsq~
t†
The <CODE>getlogin</CODE> function returns a pointer to a string containing the
name of the user logged in on the controlling terminal of the process,
or a null pointer if this information cannot be determined. The string
is statically allocated and might be overwritten on subsequent calls to
this function or to <CODE>cuserid</CODE>.
sq~wtunistd.hxq~ †tvoidtchar *t getmntentsq~
tJ
The <CODE>getmntent</CODE> function takes as the parameter a file handle
previously returned by successful call to <CODE>setmntent</CODE>. It returns
a pointer to a static variable of type <CODE>struct mntent</CODE> which is
filled with the information from the next entry from the file currently
read.
<br><br> The file format used prescribes the use of spaces or tab characters to
separate the fields. This makes it harder to use name containing one
of these characters (e.g., mount points using spaces). Therefore
these characters are encoded in the files and the <CODE>getmntent</CODE>
function takes care of the decoding while reading the entries back in.
<CODE>'\040'</CODE> is used to encode a space character, <CODE>'\011'</CODE> to
encode a tab character, <CODE>'\012'</CODE> to encode a newline character,
and <CODE>'\\'</CODE> to encode a backslash.
<br><br> If there was an error or the end of the file is reached the return value
is <CODE>NULL</CODE>.
<br><br> This function is not thread-safe since all calls to this function return
a pointer to the same static variable. <CODE>getmntent_r</CODE> should be
used in situations where multiple threads access the file.
sq~wtmntent.hxq~ �t FILE *streamtstruct mntent *t getmntent_rsq~
t
The <CODE>getmntent_r</CODE> function is the reentrant variant of
<CODE>getmntent</CODE>. It also returns the next entry from the file and
returns a pointer. The actual variable the values are stored in is not
static, though. Instead the function stores the values in the variable
pointed to by the <VAR>result</VAR> parameter. Additional information (e.g.,
the strings pointed to by the elements of the result) are kept in the
buffer of size <VAR>bufsize</VAR> pointed to by <VAR>buffer</VAR>.
<br><br> Escaped characters (space, tab, backslash) are converted back in the
same way as it happens for <CODE>getmentent</CODE>.
<br><br> The function returns a <CODE>NULL</CODE> pointer in error cases. Errors could be:
<OL>
<LI>
error while reading the file,
<LI>
end of file reached,
<LI>
<VAR>bufsize</VAR> is too small for reading a complete new entry.
</OL>
sq~wtmntent.hxq~ ”t?FILE *stream, struct mentent *result, char *buffer, int bufsizetstruct mntent *t getnetbyaddrsq~
ty
The <CODE>getnetbyaddr</CODE> function returns information about the network
of type <VAR>type</VAR> with number <VAR>net</VAR>. You should specify a value of
<CODE>AF_INET</CODE> for the <VAR>type</VAR> argument for Internet networks.
<br><br> <CODE>getnetbyaddr</CODE> returns a null pointer if there is no such
network.
sq~wtnetdb.hxq~ ›tunsigned long int net, int typetstruct netent *t getnetbynamesq~
t¿
The <CODE>getnetbyname</CODE> function returns information about the network
named <VAR>name</VAR>. It returns a null pointer if there is no such
network.
sq~wt sys/socket.htnetdb.hxq~ ¢tconst char *nametstruct netent *t getnetentsq~
t’
This function returns the next entry in the networks database. It
returns a null pointer if there are no more entries.
sq~wtnetdb.hxq~ ªtvoidtstruct netent *t getnetgrentsq~
tÚ
This function returns the next unprocessed entry of the currently
selected netgroup. The string pointers, in which addresses are passed in
the arguments <VAR>hostp</VAR>, <VAR>userp</VAR>, and <VAR>domainp</VAR>, will contain
after a successful call pointers to appropriate strings. If the string
in the next entry is empty the pointer has the value <CODE>NULL</CODE>.
The returned string pointers are only valid if none of the netgroup
related functions are called.
<br><br> The return value is <CODE>1</CODE> if the next entry was successfully read. A
value of <CODE>0</CODE> means no further entries exist or internal errors occurred.
sq~wtnetdb.hxq~ ±t*char **hostp, char **userp, char **domainptintt
getnetgrent_rsq~
t\
This function is similar to <CODE>getnetgrent</CODE> with only one exception:
the strings the three string pointers <VAR>hostp</VAR>, <VAR>userp</VAR>, and
<VAR>domainp</VAR> point to, are placed in the buffer of <VAR>buflen</VAR> bytes
starting at <VAR>buffer</VAR>. This means the returned values are valid
even after other netgroup related functions are called.
<br><br> The return value is <CODE>1</CODE> if the next entry was successfully read and
the buffer contains enough room to place the strings in it. <CODE>0</CODE> is
returned in case no more entries are found, the buffer is too small, or
internal errors occurred.
<br><br> This function is a GNU extension. The original implementation in the
SunOS libc does not provide this function.
sq~wtnetdb.hxq~ ¸tDchar **hostp, char **userp, char **domainp, char *buffer, int buflentinttgetoptsq~
t ª
The <CODE>getopt</CODE> function gets the next option argument from the
argument list specified by the <VAR>argv</VAR> and <VAR>argc</VAR> arguments.
Normally these values come directly from the arguments received by
<CODE>main</CODE>.
<br><br> The <VAR>options</VAR> argument is a string that specifies the option
characters that are valid for this program. An option character in this
string can be followed by a colon (<samp>:</samp>) to indicate that it takes a
required argument. If an option character is followed by two colons
(<samp>::</samp>), its argument is optional; this is a GNU extension.
<br><br> <CODE>getopt</CODE> has three ways to deal with options that follow
non-options <VAR>argv</VAR> elements. The special argument <samp>--</samp> forces
in all cases the end of option scanning.
<br><br> <OL>
<LI>
The default is to permute the contents of <VAR>argv</VAR> while scanning it
so that eventually all the non-options are at the end. This allows
options to be given in any order, even with programs that were not
written to expect this.
<br><br> <LI>
If the <VAR>options</VAR> argument string begins with a hyphen (<samp>-</samp>), this
is treated specially. It permits arguments that are not options to be
returned as if they were associated with option character <samp>\1</samp>.
<br><br> <LI>
POSIX demands the following behavior: The first non-option stops option
processing. This mode is selected by either setting the environment
variable <CODE>POSIXLY_CORRECT</CODE> or beginning the <VAR>options</VAR> argument
string with a plus sign (<samp>+</samp>).
</OL>
<br><br> The <CODE>getopt</CODE> function returns the option character for the next
command line option. When no more option arguments are available, it
returns <CODE>-1</CODE>. There may still be more non-option arguments; you
must compare the external variable <CODE>optind</CODE> against the <VAR>argc</VAR>
parameter to check this.
<br><br> If the option has an argument, <CODE>getopt</CODE> returns the argument by
storing it in the variable <VAR>optarg</VAR>. You don't ordinarily need to
copy the <CODE>optarg</CODE> string, since it is a pointer into the original
<VAR>argv</VAR> array, not into a static area that might be overwritten.
<br><br> If <CODE>getopt</CODE> finds an option character in <VAR>argv</VAR> that was not
included in <VAR>options</VAR>, or a missing option argument, it returns
<samp>?</samp> and sets the external variable <CODE>optopt</CODE> to the actual
option character. If the first character of <VAR>options</VAR> is a colon
(<samp>:</samp>), then <CODE>getopt</CODE> returns <samp>:</samp> instead of <samp>?</samp> to
indicate a missing option argument. In addition, if the external
variable <CODE>opterr</CODE> is nonzero (which is the default), <CODE>getopt</CODE>
prints an error message.
sq~wtunistd.hxq~ ¿t*int argc, char **argv, const char *optionstintt getopt_longsq~
t *
Decode options from the vector <VAR>argv</VAR> (whose length is <VAR>argc</VAR>).
The argument <VAR>shortopts</VAR> describes the short options to accept, just as
it does in <CODE>getopt</CODE>. The argument <VAR>longopts</VAR> describes the long
options to accept (see above).
<br><br> When <CODE>getopt_long</CODE> encounters a short option, it does the same
thing that <CODE>getopt</CODE> would do: it returns the character code for the
option, and stores the options argument (if it has one) in <CODE>optarg</CODE>.
<br><br> When <CODE>getopt_long</CODE> encounters a long option, it takes actions based
on the <CODE>flag</CODE> and <CODE>val</CODE> fields of the definition of that
option.
<br><br> If <CODE>flag</CODE> is a null pointer, then <CODE>getopt_long</CODE> returns the
contents of <CODE>val</CODE> to indicate which option it found. You should
arrange distinct values in the <CODE>val</CODE> field for options with
different meanings, so you can decode these values after
<CODE>getopt_long</CODE> returns. If the long option is equivalent to a short
option, you can use the short option's character code in <CODE>val</CODE>.
<br><br> If <CODE>flag</CODE> is not a null pointer, that means this option should just
set a flag in the program. The flag is a variable of type <CODE>int</CODE>
that you define. Put the address of the flag in the <CODE>flag</CODE> field.
Put in the <CODE>val</CODE> field the value you would like this option to
store in the flag. In this case, <CODE>getopt_long</CODE> returns <CODE>0</CODE>.
<br><br> For any long option, <CODE>getopt_long</CODE> tells you the index in the array
<VAR>longopts</VAR> of the options definition, by storing it into
<CODE>*<VAR>indexptr</VAR></CODE>. You can get the name of the option with
<CODE><VAR>longopts</VAR>[*<VAR>indexptr</VAR>].name</CODE>. So you can distinguish among
long options either by the values in their <CODE>val</CODE> fields or by their
indices. You can also distinguish in this way among long options that
set flags.
<br><br> When a long option has an argument, <CODE>getopt_long</CODE> puts the argument
value in the variable <CODE>optarg</CODE> before returning. When the option
has no argument, the value in <CODE>optarg</CODE> is a null pointer. This is
how you can tell whether an optional argument was supplied.
<br><br> When <CODE>getopt_long</CODE> has no more options to handle, it returns
<CODE>-1</CODE>, and leaves in the variable <CODE>optind</CODE> the index in
<VAR>argv</VAR> of the next remaining argument.
sq~wtgetopt.hxq~ Æt`int argc, char *const *argv, const char *shortopts, const struct option *longopts, int *indexptrtinttgetopt_long_onlysq~
t²
<br><br> The <CODE>getopt_long_only</CODE> function is equivalent to the
<CODE>getopt_long</CODE> function but it allows to specify the user of the
application to pass long options with only <samp>-</samp> instead of
<samp>--</samp>. The <samp>--</samp> prefix is still recognized but instead of
looking through the short options if a <samp>-</samp> is seen it is first
tried whether this parameter names a long option. If not, it is parsed
as a short option.
<br><br> Assuming <CODE>getopt_long_only</CODE> is used starting an application with
<br><br> <pre><br>
app -foo<br>
</pre>
<br><br>
the <CODE>getopt_long_only</CODE> will first look for a long option named
<samp>foo</samp>. If this is not found, the short options <samp>f</samp>, <samp>o</samp>,
and again <samp>o</samp> are recognized.
sq~wtgetopt.hxq~ Ít`int argc, char *const *argv, const char *shortopts, const struct option *longopts, int *indexptrtintt getpagesizesq~
t
The <CODE>getpagesize</CODE> function returns the page size of the process.
This value is fixed for the runtime of the process but can vary in
different runs of the application.
<br><br> The function is declared in <TT>unistd.h</TT>.
sq~wtunistd.hxq~ Ôtvoidtinttgetpasssq~
t
<br><br> <CODE>getpass</CODE> outputs <VAR>prompt</VAR>, then reads a string in from the
terminal without echoing it. It tries to connect to the real terminal,
<TT>/dev/tty</TT>, if possible, to encourage users not to put plaintext
passwords in files; otherwise, it uses <CODE>stdin</CODE> and <CODE>stderr</CODE>.
<CODE>getpass</CODE> also disables the INTR, QUIT, and SUSP characters on the
terminal using the <CODE>ISIG</CODE> terminal attribute .
The terminal is flushed before and after <CODE>getpass</CODE>, so that
characters of a mistyped password are not accidentally visible.
<br><br> In other C libraries, <CODE>getpass</CODE> may only return the first
<CODE>PASS_MAX</CODE> bytes of a password. The GNU C library has no limit, so
<CODE>PASS_MAX</CODE> is undefined.
<br><br> The prototype for this function is in <TT>unistd.h</TT>. <CODE>PASS_MAX</CODE>
would be defined in <TT>limits.h</TT>.
sq~wtunistd.hxq~ Ûtconst char *prompttchar *t getpeernamesq~
tQ
The <CODE>getpeername</CODE> function returns the address of the socket that
<VAR>socket</VAR> is connected to; it stores the address in the memory space
specified by <VAR>addr</VAR> and <VAR>length-ptr</VAR>. It stores the length of
the address in <CODE>*<VAR>length-ptr</VAR></CODE>.
<br><br> , for information about the format of the
address. In some operating systems, <CODE>getpeername</CODE> works only for
sockets in the Internet domain.
<br><br> The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on error. The
following <CODE>errno</CODE> error conditions are defined for this function:
<br><br> <DL>
<DT><CODE>EBADF</CODE>
<DD>
The argument <VAR>socket</VAR> is not a valid file descriptor.
<br><br> <LI> ENOTSOCK
The descriptor <VAR>socket</VAR> is not a socket.
<br><br> <LI> ENOTCONN
The socket <VAR>socket</VAR> is not connected.
<br><br> <LI> ENOBUFS
There are not enough internal buffers available.
sq~wt sys/socket.hxq~ ât8int socket, struct sockaddr *addr, socklen_t *length-ptrtinttgetpidsq~
ta
The <CODE>getpid</CODE> function returns the process ID of the current process.
sq~wt sys/types.htunistd.hxq~ étvoidtpid_ttgetppidsq~
ty
The <CODE>getppid</CODE> function returns the process ID of the parent of the
current process.
sq~wtunistd.hxq~ ñtvoidtpid_tt getprioritysq~
t.
Return the nice value of a set of processes; <VAR>class</VAR> and <VAR>id</VAR>
specify which ones (see below). If the processes specified do not all
have the same nice value, this returns the lowest value that any of them
has.
<br><br> On success, the return value is <CODE>0</CODE>. Otherwise, it is <CODE>-1</CODE>
and <CODE>ERRNO</CODE> is set accordingly. The <CODE>errno</CODE> values specific
to this function are:
<br><br> <DL>
<DT><CODE>ESRCH</CODE>
<DD>
The combination of <VAR>class</VAR> and <VAR>id</VAR> does not match any existing
process.
<br><br> <LI> EINVAL
The value of <VAR>class</VAR> is not valid.
<br><br> If the return value is <CODE>-1</CODE>, it could indicate failure, or it could
be the nice value. The only way to make certain is to set <CODE>errno =
0</CODE> before calling <CODE>getpriority</CODE>, then use <CODE>errno != 0</CODE>
afterward as the criterion for failure.
sq~wtsys/resource.hxq~ øtint class, int idtinttgetprotobynamesq~
tÌ
The <CODE>getprotobyname</CODE> function returns information about the
network protocol named <VAR>name</VAR>. If there is no such protocol, it
returns a null pointer.
sq~wtnetdb.hxq~ ÿtconst char *nametstruct protoent *tgetprotobynumbersq~
tØ
The <CODE>getprotobynumber</CODE> function returns information about the
network protocol with number <VAR>protocol</VAR>. If there is no such
protocol, it returns a null pointer.
sq~wtnetdb.hxq~
t int protocoltstruct protoent *t getprotoentsq~
t“
This function returns the next entry in the protocols database. It
returns a null pointer if there are no more entries.
sq~wtnetdb.hxq~
tvoidtstruct protoent *tgetptsq~
t8
The <CODE>getpt</CODE> function returns a new file descriptor for the next
available master pseudo-terminal. The normal return value from
<CODE>getpt</CODE> is a non-negative integer file descriptor. In the case of
an error, a value of -1 is returned instead. The following
<CODE>errno</CODE> conditions are defined for this function:
<br><br> <DL>
<DT><CODE>ENOENT</CODE>
<DD>
There are no free master pseudo-terminals available.
<br><br> This function is a GNU extension.
sq~wtstdlib.hxq~
tvoidtinttgetpwentsq~
tÐ
The <CODE>getpwent</CODE> function reads the next entry from the stream
initialized by <CODE>setpwent</CODE>. It returns a pointer to the entry. The
structure is statically allocated and is rewritten on subsequent calls
to <CODE>getpwent</CODE>. You must copy the contents of the structure if you
wish to save the information.
<br><br> A null pointer is returned when no more entries are available.
sq~wtpwd.hxq~
tvoidtstruct passwd *t
getpwent_rsq~
t°
This function is similar to <CODE>getpwent</CODE> in that it returns the next
entry from the stream initialized by <CODE>setpwent</CODE>. Like
<CODE>fgetpwent_r</CODE>, it uses the user-supplied buffers in
<VAR>result_buf</VAR> and <VAR>buffer</VAR> to return the information requested.
<br><br> The return values are the same as for <CODE>fgetpwent_r</CODE>.
<br><br>
sq~wtpwd.hxq~
"tKstruct passwd *result_buf, char *buffer, int buflen, struct passwd **resulttinttgetpwnamsq~
td
This function returns a pointer to a statically-allocated structure
containing information about the user whose user name is <VAR>name</VAR>.
This structure may be overwritten on subsequent calls to
<CODE>getpwnam</CODE>.
<br><br> A null pointer return indicates there is no user named <VAR>name</VAR>.
sq~wtpwd.hxq~
)tconst char *nametstruct passwd *t
getpwnam_rsq~
t»
This function is similar to <CODE>getpwnam</CODE> in that is returns
information about the user whose user name is <VAR>name</VAR>. However, like
<CODE>getpwuid_r</CODE>, it fills the user supplied buffers in
<VAR>result_buf</VAR> and <VAR>buffer</VAR> with the information instead of using
a static buffer.
<br><br> The return values are the same as for <CODE>getpwuid_r</CODE>.
sq~wtpwd.hxq~
0t`const char *name, struct passwd *result_buf, char *buffer, size_t buflen, struct passwd **resulttinttgetpwuidsq~
tx
This function returns a pointer to a statically-allocated structure
containing information about the user whose user ID is <VAR>uid</VAR>. This
structure may be overwritten on subsequent calls to <CODE>getpwuid</CODE>.
<br><br> A null pointer value indicates there is no user in the data base with
user ID <VAR>uid</VAR>.
sq~wtpwd.hxq~
7t uid_t uidtstruct passwd *t
getpwuid_rsq~
t—
This function is similar to <CODE>getpwuid</CODE> in that it returns
information about the user whose user ID is <VAR>uid</VAR>. However, it
fills the user supplied structure pointed to by <VAR>result_buf</VAR> with
the information instead of using a static buffer. The first
<VAR>buflen</VAR> bytes of the additional buffer pointed to by <VAR>buffer</VAR>
are used to contain additional information, normally strings which are
pointed to by the elements of the result structure.
<br><br> If a user with ID <VAR>uid</VAR> is found, the pointer returned in
<VAR>result</VAR> points to the record which contains the wanted data (i.e.,
<VAR>result</VAR> contains the value <VAR>result_buf</VAR>). If no user is found
or if an error occurred, the pointer returned in <VAR>result</VAR> is a null
pointer. The function returns zero or an error code. If the buffer
<VAR>buffer</VAR> is too small to contain all the needed information, the
error code <CODE>ERANGE</CODE> is returned and <VAR>errno</VAR> is set to
<CODE>ERANGE</CODE>.
sq~wtpwd.hxq~
>tYuid_t uid, struct passwd *result_buf, char *buffer, size_t buflen, struct passwd **resulttintt getrlimitsq~
t?
Read the current and maximum limits for the resource <VAR>resource</VAR>
and store them in <CODE>*<VAR>rlp</VAR></CODE>.
<br><br> The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on failure. The
only possible <CODE>errno</CODE> error condition is <CODE>EFAULT</CODE>.
<br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> on a
32-bit system this function is in fact <CODE>getrlimit64</CODE>. Thus, the
LFS interface transparently replaces the old interface.
sq~wtsys/resource.hxq~
Et int resource, struct rlimit *rlptintt getrlimit64sq~
t
This function is similar to <CODE>getrlimit</CODE> but its second parameter is
a pointer to a variable of type <CODE>struct rlimit64</CODE>, which allows it
to read values which wouldn't fit in the member of a <CODE>struct
rlimit</CODE>.
<br><br> If the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> on a
32-bit machine, this function is available under the name
<CODE>getrlimit</CODE> and so transparently replaces the old interface.
sq~wtsys/resource.hxq~
Lt"int resource, struct rlimit64 *rlptintt getrusagesq~
t[
This function reports resource usage totals for processes specified by
<VAR>processes</VAR>, storing the information in <CODE>*<VAR>rusage</VAR></CODE>.
<br><br> In most systems, <VAR>processes</VAR> has only two valid values:
<br><br> <DL>
<DT><CODE>RUSAGE_SELF</CODE>
<DD>
Just the current process.
<br><br> <DT><CODE>RUSAGE_CHILDREN</CODE>
<DD>
All child processes (direct and indirect) that have already terminated.
<br><br> In the GNU system, you can also inquire about a particular child process
by specifying its process ID.
<br><br> The return value of <CODE>getrusage</CODE> is zero for success, and <CODE>-1</CODE>
for failure.
<br><br> <DL>
<LI> EINVAL
The argument <VAR>processes</VAR> is not valid.
sq~wtmalloc.htsys/resource.hxq~
St$int processes, struct rusage *rusagetintt
getservbynamesq~
t{
The <CODE>getservbyname</CODE> function returns information about the
service named <VAR>name</VAR> using protocol <VAR>proto</VAR>. If it can't find
such a service, it returns a null pointer.
<br><br> This function is useful for servers as well as for clients; servers
use it to determine which port they should listen on .
sq~wt netinet/in.htnetdb.hxq~
[t#const char *name, const char *prototstruct servent *t
getservbyportsq~
tç
The <CODE>getservbyport</CODE> function returns information about the
service at port <VAR>port</VAR> using protocol <VAR>proto</VAR>. If it can't
find such a service, it returns a null pointer.
sq~wtnetdb.hxq~
ctint port, const char *prototstruct servent *t
getserventsq~
t“
This function returns the next entry in the services database. If
there are no more entries, it returns a null pointer.
sq~wtnetdb.hxq~
jtvoidtstruct servent *tgetsidsq~
t…
<br><br> The <CODE>getsid</CODE> function returns the process group ID of the session
leader of the specified process. If a <VAR>pid</VAR> is <CODE>0</CODE>, the
process group ID of the session leader of the current process is
returned.
<br><br> In case of error <CODE>-1</CODE> is returned and <CODE>errno</CODE> is set. The
following <CODE>errno</CODE> error conditions are defined for this function:
<br><br> <DL>
<DT><CODE>ESRCH</CODE>
<DD>
There is no process with the given process ID <VAR>pid</VAR>.
<LI> EPERM
The calling process and the process specified by <VAR>pid</VAR> are in
different sessions, and the implementation doesn't allow to access the
process group ID of the session leader of the process with ID <VAR>pid</VAR>
from the calling process.
sq~wtunistd.hxq~
qt pid_t pidtpid_tt getsocknamesq~
tª
The <CODE>getsockname</CODE> function returns information about the
address of the socket <VAR>socket</VAR> in the locations specified by the
<VAR>addr</VAR> and <VAR>length-ptr</VAR> arguments. Note that the
<VAR>length-ptr</VAR> is a pointer; you should initialize it to be the
allocation size of <VAR>addr</VAR>, and on return it contains the actual
size of the address data.
<br><br> The format of the address data depends on the socket namespace. The
length of the information is usually fixed for a given namespace, so
normally you can know exactly how much space is needed and can provide
that much. The usual practice is to allocate a place for the value
using the proper data type for the socket's namespace, then cast its
address to <CODE>struct sockaddr *</CODE> to pass it to <CODE>getsockname</CODE>.
<br><br> The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on error. The
following <CODE>errno</CODE> error conditions are defined for this function:
<br><br> <DL>
<DT><CODE>EBADF</CODE>
<DD>
The <VAR>socket</VAR> argument is not a valid file descriptor.
<br><br> <LI> ENOTSOCK
The descriptor <VAR>socket</VAR> is not a socket.
<br><br> <LI> ENOBUFS
There are not enough internal buffers available for the operation.
sq~wt sys/socket.hxq~
xt8int socket, struct sockaddr *addr, socklen_t *length-ptrtintt
getsockoptsq~
t…
The <CODE>getsockopt</CODE> function gets information about the value of
option <VAR>optname</VAR> at level <VAR>level</VAR> for socket <VAR>socket</VAR>.
<br><br> The option value is stored in a buffer that <VAR>optval</VAR> points to.
Before the call, you should supply in <CODE>*<VAR>optlen-ptr</VAR></CODE> the
size of this buffer; on return, it contains the number of bytes of
information actually stored in the buffer.
<br><br> Most options interpret the <VAR>optval</VAR> buffer as a single <CODE>int</CODE>
value.
<br><br> The actual return value of <CODE>getsockopt</CODE> is <CODE>0</CODE> on success
and <CODE>-1</CODE> on failure. The following <CODE>errno</CODE> error conditions
are defined:
<br><br> <DL>
<DT><CODE>EBADF</CODE>
<DD>
The <VAR>socket</VAR> argument is not a valid file descriptor.
<br><br> <LI> ENOTSOCK
The descriptor <VAR>socket</VAR> is not a socket.
<br><br> <LI> ENOPROTOOPT
The <VAR>optname</VAR> doesn't make sense for the given <VAR>level</VAR>.
sq~wt sys/socket.hxq~
tGint socket, int level, int optname, void *optval, socklen_t *optlen-ptrtintt getsuboptsq~
të
<br><br> The <VAR>optionp</VAR> parameter must be a pointer to a variable containing
the address of the string to process. When the function returns the
reference is updated to point to the next suboption or to the
terminating <samp>\0</samp> character if there is no more suboption available.
<br><br> The <VAR>tokens</VAR> parameter references an array of strings containing the
known suboptions. All strings must be <samp>\0</samp> terminated and to mark
the end a null pointer must be stored. When <CODE>getsubopt</CODE> finds a
possible legal suboption it compares it with all strings available in
the <VAR>tokens</VAR> array and returns the index in the string as the
indicator.
<br><br> In case the suboption has an associated value introduced by a <samp>=</samp>
character, a pointer to the value is returned in <VAR>valuep</VAR>. The
string is <samp>\0</samp> terminated. If no argument is available
<VAR>valuep</VAR> is set to the null pointer. By doing this the caller can
check whether a necessary value is given or whether no unexpected value
is present.
<br><br> In case the next suboption in the string is not mentioned in the
<VAR>tokens</VAR> array the starting address of the suboption including a
possible value is returned in <VAR>valuep</VAR> and the return value of the
function is <samp>-1</samp>.
sq~wtstdlib.hxq~
†t8char **optionp, const char* const *tokens, char **valueptinttgettextsq~
tD
The <CODE>gettext</CODE> function searches the currently selected message
catalogs for a string which is equal to <VAR>msgid</VAR>. If there is such a
string available it is returned. Otherwise the argument string
<VAR>msgid</VAR> is returned.
<br><br> Please note that all though the return value is <CODE>char *</CODE> the
returned string must not be changed. This broken type results from the
history of the function and does not reflect the way the function should
be used.
<br><br> Please note that above we wrote ``message catalogs'' (plural). This is
a specialty of the GNU implementation of these functions and we will
say more about this when we talk about the ways message catalogs are
selected .
<br><br> The <CODE>gettext</CODE> function does not modify the value of the global
<VAR>errno</VAR> variable. This is necessary to make it possible to write
something like
<br><br> <pre><br>
printf (gettext ("Operation failed: %m\n"));<br>
</pre>
<br><br> Here the <VAR>errno</VAR> value is used in the <CODE>printf</CODE> function while
processing the <CODE>%m</CODE> format element and if the <CODE>gettext</CODE>
function would change this value (it is called before <CODE>printf</CODE> is
called) we would get a wrong message.
<br><br> So there is no easy way to detect a missing message catalog beside
comparing the argument string with the result. But it is normally the
task of the user to react on missing catalogs. The program cannot guess
when a message catalog is really necessary since for a user who speaks
the language the program was developed in does not need any translation.
sq~wt libintl.hxq~
�tconst char *msgidtchar *t gettimeofdaysq~
tD
The <CODE>gettimeofday</CODE> function returns the current calendar time as
the elapsed time since the epoch in the <CODE>struct timeval</CODE> structure
indicated by <VAR>tp</VAR>. ( for a description of
<CODE>struct timeval</CODE>). Information about the time zone is returned in
the structure pointed at <VAR>tzp</VAR>. If the <VAR>tzp</VAR> argument is a null
pointer, time zone information is ignored.
<br><br> The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on failure. The
following <CODE>errno</CODE> error condition is defined for this function:
<br><br> <DL>
<DT><CODE>ENOSYS</CODE>
<DD>
The operating system does not support getting time zone information, and
<VAR>tzp</VAR> is not a null pointer. The GNU operating system does not
support using <CODE>struct timezone</CODE> to represent time zone
information; that is an obsolete feature of 4.3 BSD.
Instead, use the facilities described in Time Zone Functions.
sq~wt
sys/time.hxq~
”t(struct timeval *tp, struct timezone *tzptinttgetuidsq~
t[
The <CODE>getuid</CODE> function returns the real user ID of the process.
sq~wt sys/types.htunistd.hxq~
›tvoidtuid_ttgetumasksq~
t‰
Return the current value of the file creation mask for the current
process. This function is a GNU extension.
sq~wt
sys/stat.hxq~
£tvoidtmode_ttgetutentsq~
t*
The <CODE>getutent</CODE> function reads the next entry from the user
accounting database. It returns a pointer to the entry, which is
statically allocated and may be overwritten by subsequent calls to
<CODE>getutent</CODE>. You must copy the contents of the structure if you
wish to save the information or you can use the <CODE>getutent_r</CODE>
function which stores the data in a user-provided buffer.
<br><br> A null pointer is returned in case no further entry is available.
sq~wtutmp.hxq~
ªtvoidt
struct utmp *t
getutent_rsq~
t
The <CODE>getutent_r</CODE> is equivalent to the <CODE>getutent</CODE> function. It
returns the next entry from the database. But instead of storing the
information in a static buffer it stores it in the buffer pointed to by
the parameter <VAR>buffer</VAR>.
<br><br> If the call was successful, the function returns <CODE>0</CODE> and the
pointer variable pointed to by the parameter <VAR>result</VAR> contains a
pointer to the buffer which contains the result (this is most probably
the same value as <VAR>buffer</VAR>). If something went wrong during the
execution of <CODE>getutent_r</CODE> the function returns <CODE>-1</CODE>.
<br><br> This function is a GNU extension.
sq~wtutmp.hxq~
±t)struct utmp *buffer, struct utmp **resulttinttgetutidsq~
t
This function searches forward from the current point in the database
for an entry that matches <VAR>id</VAR>. If the <CODE>ut_type</CODE> member of the
<VAR>id</VAR> structure is one of <CODE>RUN_LVL</CODE>, <CODE>BOOT_TIME</CODE>,
<CODE>OLD_TIME</CODE> or <CODE>NEW_TIME</CODE> the entries match if the
<CODE>ut_type</CODE> members are identical. If the <CODE>ut_type</CODE> member of
the <VAR>id</VAR> structure is <CODE>INIT_PROCESS</CODE>, <CODE>LOGIN_PROCESS</CODE>,
<CODE>USER_PROCESS</CODE> or <CODE>DEAD_PROCESS</CODE>, the entries match if the
<CODE>ut_type</CODE> member of the entry read from the database is one of
these four, and the <CODE>ut_id</CODE> members match. However if the
<CODE>ut_id</CODE> member of either the <VAR>id</VAR> structure or the entry read
from the database is empty it checks if the <CODE>ut_line</CODE> members match
instead. If a matching entry is found, <CODE>getutid</CODE> returns a pointer
to the entry, which is statically allocated, and may be overwritten by a
subsequent call to <CODE>getutent</CODE>, <CODE>getutid</CODE> or <CODE>getutline</CODE>.
You must copy the contents of the structure if you wish to save the
information.
<br><br> A null pointer is returned in case the end of the database is reached
without a match.
<br><br> The <CODE>getutid</CODE> function may cache the last read entry. Therefore,
if you are using <CODE>getutid</CODE> to search for multiple occurrences, it
is necessary to zero out the static data after each call. Otherwise
<CODE>getutid</CODE> could just return a pointer to the same entry over and
over again.
sq~wtutmp.hxq~
¸tconst struct utmp *idt
struct utmp *t getutid_rsq~
t^
This function retrieves just like <CODE>getutid</CODE> the next entry matching
the information stored in <VAR>id</VAR>. But the result is stored in the
buffer pointed to by the parameter <VAR>buffer</VAR>.
<br><br> If successful the function returns <CODE>0</CODE> and the pointer variable
pointed to by the parameter <VAR>result</VAR> contains a pointer to the
buffer with the result (probably the same as <VAR>result</VAR>. If not
successful the function return <CODE>-1</CODE>.
<br><br> This function is a GNU extension.
sq~wtutmp.hxq~
¿t@const struct utmp *id, struct utmp *buffer, struct utmp **resulttintt getutlinesq~
tƒ
This function searches forward from the current point in the database
until it finds an entry whose <CODE>ut_type</CODE> value is
<CODE>LOGIN_PROCESS</CODE> or <CODE>USER_PROCESS</CODE>, and whose <CODE>ut_line</CODE>
member matches the <CODE>ut_line</CODE> member of the <VAR>line</VAR> structure.
If it finds such an entry, it returns a pointer to the entry which is
statically allocated, and may be overwritten by a subsequent call to
<CODE>getutent</CODE>, <CODE>getutid</CODE> or <CODE>getutline</CODE>. You must copy the
contents of the structure if you wish to save the information.
<br><br> A null pointer is returned in case the end of the database is reached
without a match.
<br><br> The <CODE>getutline</CODE> function may cache the last read entry. Therefore
if you are using <CODE>getutline</CODE> to search for multiple occurrences, it
is necessary to zero out the static data after each call. Otherwise
<CODE>getutline</CODE> could just return a pointer to the same entry over and
over again.
sq~wtutmp.hxq~
Ætconst struct utmp *linet
struct utmp *t getutline_rsq~
tb
This function retrieves just like <CODE>getutline</CODE> the next entry
matching the information stored in <VAR>line</VAR>. But the result is stored
in the buffer pointed to by the parameter <VAR>buffer</VAR>.
<br><br> If successful the function returns <CODE>0</CODE> and the pointer variable
pointed to by the parameter <VAR>result</VAR> contains a pointer to the
buffer with the result (probably the same as <VAR>result</VAR>. If not
successful the function return <CODE>-1</CODE>.
<br><br> This function is a GNU extension.
sq~wtutmp.hxq~
ÍtBconst struct utmp *line, struct utmp *buffer, struct utmp **resulttinttgetutmpsq~
t›
<CODE>getutmp</CODE> copies the information, insofar as the structures are
compatible, from <VAR>utmpx</VAR> to <VAR>utmp</VAR>.
sq~wtutmpx.htutmp.hxq~
Ôt,const struct utmpx *utmpx, struct utmp *utmptinttgetutmpxsq~
tœ
<CODE>getutmpx</CODE> copies the information, insofar as the structures are
compatible, from <VAR>utmp</VAR> to <VAR>utmpx</VAR>.
sq~wtutmpx.htutmp.hxq~
Üt,const struct utmp *utmp, struct utmpx *utmpxtintt getutxentsq~
t
The <CODE>getutxent</CODE> function is similar to <CODE>getutent</CODE>, but returns
a pointer to a <CODE>struct utmpx</CODE> instead of <CODE>struct utmp</CODE>. On
the GNU system it simply is an alias for <CODE>getutent</CODE>.
sq~wtutmpx.hxq~
ätvoidtstruct utmpx *tgetutxidsq~
tà
This function is similar to <CODE>getutid</CODE>, but uses <CODE>struct utmpx</CODE>
instead of <CODE>struct utmp</CODE>. On the GNU system it is simply an alias
for <CODE>getutid</CODE>.
sq~wtutmpx.hxq~
ëtconst struct utmpx *idtstruct utmpx *t
getutxlinesq~
tâ
This function is similar to <CODE>getutid</CODE>, but uses <CODE>struct utmpx</CODE>
instead of <CODE>struct utmp</CODE>. On the GNU system it is simply an alias
for <CODE>getutline</CODE>.
sq~wtutmpx.hxq~
òtconst struct utmpx *linetstruct utmpx *tgetwsq~
tÝ
This function reads a word (that is, an <CODE>int</CODE>) from <VAR>stream</VAR>.
It's provided for compatibility with SVID. We recommend you use
<CODE>fread</CODE> instead. Unlike <CODE>getc</CODE>,
any <CODE>int</CODE> value could be a valid result. <CODE>getw</CODE> returns
<CODE>EOF</CODE> when it encounters end-of-file or an error, but there is no
way to distinguish this from an input word with value -1.
sq~wtstdio.hxq~
ùt FILE *streamtinttgetwcsq~
tK
This is just like <CODE>fgetwc</CODE>, except that it is permissible for it to
be implemented as a macro that evaluates the <VAR>stream</VAR> argument more
than once. <CODE>getwc</CODE> can be highly optimized, so it is usually the
best function to use to read a single wide character.
sq~wtwchar.hxq~t FILE *streamtwint_ttgetwc_unlockedsq~
tÜ
The <CODE>getwc_unlocked</CODE> function is equivalent to the <CODE>getwc</CODE>
function except that it does not implicitly lock the stream.
<br><br> This function is a GNU extension.
sq~wtwchar.hxq~t FILE *streamtwint_ttgetwcharsq~
t©
The <CODE>getwchar</CODE> function is equivalent to <CODE>getwc</CODE> with <CODE>stdin</CODE>
as the value of the <VAR>stream</VAR> argument.
sq~wtwchar.hxq~tvoidtwint_ttgetwchar_unlockedsq~
tâ
The <CODE>getwchar_unlocked</CODE> function is equivalent to the <CODE>getwchar</CODE>
function except that it does not implicitly lock the stream.
<br><br> This function is a GNU extension.
sq~wtwchar.hxq~tvoidtwint_ttglobsq~
t „
The function <CODE>glob</CODE> does globbing using the pattern <VAR>pattern</VAR>
in the current directory. It puts the result in a newly allocated
vector, and stores the size and address of this vector into
<CODE>*<VAR>vector-ptr</VAR></CODE>. The argument <VAR>flags</VAR> is a combination of
bit flags; see Flags for Globbing, for details of the flags.
<br><br> The result of globbing is a sequence of file names. The function
<CODE>glob</CODE> allocates a string for each resulting word, then
allocates a vector of type <CODE>char **</CODE> to store the addresses of
these strings. The last element of the vector is a null pointer.
This vector is called the word vector.
<br><br> To return this vector, <CODE>glob</CODE> stores both its address and its
length (number of elements, not counting the terminating null pointer)
into <CODE>*<VAR>vector-ptr</VAR></CODE>.
<br><br> Normally, <CODE>glob</CODE> sorts the file names alphabetically before
returning them. You can turn this off with the flag <CODE>GLOB_NOSORT</CODE>
if you want to get the information as fast as possible. Usually it's
a good idea to let <CODE>glob</CODE> sort them---if you process the files in
alphabetical order, the users will have a feel for the rate of progress
that your application is making.
<br><br> If <CODE>glob</CODE> succeeds, it returns 0. Otherwise, it returns one
of these error codes:
<br><br> <DL>
<DT><CODE>GLOB_ABORTED</CODE>
<DD>
There was an error opening a directory, and you used the flag
<CODE>GLOB_ERR</CODE> or your specified <VAR>errfunc</VAR> returned a nonzero
value.
,
for an explanation of the <CODE>GLOB_ERR</CODE> flag and <VAR>errfunc</VAR>.
<br><br> <DT><CODE>GLOB_NOMATCH</CODE>
<DD>
The pattern didn't match any existing files. If you use the
<CODE>GLOB_NOCHECK</CODE> flag, then you never get this error code, because
that flag tells <CODE>glob</CODE> to <EM>pretend</EM> that the pattern matched
at least one file.
<br><br> <DT><CODE>GLOB_NOSPACE</CODE>
<DD>
It was impossible to allocate memory to hold the result.
</DL>
<br><br> In the event of an error, <CODE>glob</CODE> stores information in
<CODE>*<VAR>vector-ptr</VAR></CODE> about all the matches it has found so far.
<br><br> It is important to notice that the <CODE>glob</CODE> function will not fail if
it encounters directories or files which cannot be handled without the
LFS interfaces. The implementation of <CODE>glob</CODE> is supposed to use
these functions internally. This at least is the assumptions made by
the Unix standard. The GNU extension of allowing the user to provide
own directory handling and <CODE>stat</CODE> functions complicates things a
bit. If these callback functions are used and a large file or directory
is encountered <CODE>glob</CODE> <EM>can</EM> fail.
sq~wt fnmatch.htglob.hxq~ticonst char *pattern, int flags, int (*errfunc) (const char *filename, int error-code), glob_t *vector-ptrtinttglob64sq~
tˆ
The <CODE>glob64</CODE> function was added as part of the Large File Summit
extensions but is not part of the original LFS proposal. The reason for
this is simple: it is not necessary. The necessity for a <CODE>glob64</CODE>
function is added by the extensions of the GNU <CODE>glob</CODE>
implementation which allows the user to provide own directory handling
and <CODE>stat</CODE> functions. The <CODE>readdir</CODE> and <CODE>stat</CODE> functions
do depend on the choice of <CODE>_FILE_OFFSET_BITS</CODE> since the definition
of the types <CODE>struct dirent</CODE> and <CODE>struct stat</CODE> will change
depending on the choice.
<br><br> Beside this difference the <CODE>glob64</CODE> works just like <CODE>glob</CODE> in
all aspects.
<br><br> This function is a GNU extension.
sq~wtglob.hxq~$tkconst char *pattern, int flags, int (*errfunc) (const char *filename, int error-code), glob64_t *vector-ptrtinttglobfreesq~
t@
The <CODE>globfree</CODE> function frees all resources allocated by previous
calls to <CODE>glob</CODE> associated with the object pointed to by
<VAR>pglob</VAR>. This function should be called whenever the currently used
<CODE>glob_t</CODE> typed object isn't used anymore.
sq~wtglob.hxq~+t
glob_t *pglobtvoidt
globfree64sq~
t¯
This function is equivalent to <CODE>globfree</CODE> but it frees records of
type <CODE>glob64_t</CODE> which were allocated by <CODE>glob64</CODE>.
sq~wtglob.hxq~2tglob64_t *pglobtvoidtgmtimesq~
t
This function is similar to <CODE>localtime</CODE>, except that the broken-down
time is expressed as Coordinated Universal Time (UTC) (formerly called
Greenwich Mean Time (GMT)) rather than relative to a local time zone.
<br><br>
sq~wttime.hxq~9tconst time_t *timet struct tm *tgmtime_rsq~
t^
This function is similar to <CODE>localtime_r</CODE>, except that it converts
just like <CODE>gmtime</CODE> the given time as Coordinated Universal Time.
<br><br> If the conversion is successful the function returns a pointer to the
object the result was written into, i.e., it returns <VAR>resultp</VAR>.
sq~wttime.hxq~@t&const time_t *time, struct tm *resultpt struct tm *tgrantptsq~
t
The <CODE>grantpt</CODE> function changes the ownership and access permission
of the slave pseudo-terminal device corresponding to the master
pseudo-terminal device associated with the file descriptor
<VAR>filedes</VAR>. The owner is set from the real user ID of the calling
process , and the group is set to a special
group (typically tty) or from the real group ID of the calling
process. The access permission is set such that the file is both
readable and writable by the owner and only writable by the group.
<br><br> On some systems this function is implemented by invoking a special
<CODE>setuid</CODE> root program. As a
consequence, installing a signal handler for the <CODE>SIGCHLD</CODE> signal
may interfere with a call to
<CODE>grantpt</CODE>.
<br><br> The normal return value from <CODE>grantpt</CODE> is 0; a value of
-1 is returned in case of failure. The following <CODE>errno</CODE>
error conditions are defined for this function:
<br><br> <DL>
<DT><CODE>EBADF</CODE>
<DD>
The <VAR>filedes</VAR> argument is not a valid file descriptor.
<br><br> <LI> EINVAL
The <VAR>filedes</VAR> argument is not associated with a master pseudo-terminal
device.
<br><br> <LI> EACCES
The slave pseudo-terminal device corresponding to the master associated
with <VAR>filedes</VAR> could not be accessed.
<br><br>
sq~wtstdlib.hxq~Gt int filedestinttgsignalsq~
t˜
The <CODE>gsignal</CODE> function does the same thing as <CODE>raise</CODE>; it is
provided only for compatibility with SVID.
sq~wtsignal.hxq~Nt
int signumtinttgttysq~
tö
This function gets the attributes of a terminal.
<br><br> <CODE>gtty</CODE> sets *<VAR>attributes</VAR> to describe the terminal attributes
of the terminal which is open with file descriptor <VAR>filedes</VAR>.
sq~wt termios.htsgtty.hxq~Ut&int filedes, struct sgttyb *attributestintt hasmntoptsq~
t™
This function can be used to check whether the string pointed to by the
<CODE>mnt_opts</CODE> element of the variable pointed to by <VAR>mnt</VAR> contains
the option <VAR>opt</VAR>. If this is true a pointer to the beginning of the
option in the <CODE>mnt_opts</CODE> element is returned. If no such option
exists the function returns <CODE>NULL</CODE>.
<br><br> This function is useful to test whether a specific option is present but
when all options have to be processed one is better off with using the
<CODE>getsubopt</CODE> function to iterate over all options in the string.
sq~wtmntent.hxq~]t)const struct mntent *mnt, const char *opttchar *thcreatesq~
tH
The <CODE>hcreate</CODE> function creates a hashing table which can contain at
least <VAR>nel</VAR> elements. There is no possibility to grow this table so
it is necessary to choose the value for <VAR>nel</VAR> wisely. The method
used to implement this function might make it necessary to make the
number of elements in the hashing table larger than the expected maximal
number of elements. Hashing tables usually work inefficiently if they are
filled 80% or more. The constant access time guaranteed by hashing can
only be achieved if few collisions exist. See Knuth's ``The Art of
Computer Programming, Part 3: Searching and Sorting'' for more
information.
<br><br> The weakest aspect of this function is that there can be at most one
hashing table used through the whole program. The table is allocated
in local memory out of control of the programmer. As an extension the
GNU C library provides an additional set of functions with an reentrant
interface which provide a similar interface but which allow to keep
arbitrarily many hashing tables.
<br><br> It is possible to use more than one hashing table in the program run if
the former table is first destroyed by a call to <CODE>hdestroy</CODE>.
<br><br> The function returns a non-zero value if successful. If it return zero
something went wrong. This could either mean there is already a hashing
table in use or the program runs out of memory.
sq~wtsearch.hxq~dt
size_t neltintt hcreate_rsq~
t)
The <CODE>hcreate_r</CODE> function initializes the object pointed to by
<VAR>htab</VAR> to contain a hashing table with at least <VAR>nel</VAR> elements.
So this function is equivalent to the <CODE>hcreate</CODE> function except
that the initialized data structure is controlled by the user.
<br><br> This allows having more than one hashing table at one time. The memory
necessary for the <CODE>struct hsearch_data</CODE> object can be allocated
dynamically. It must be initialized with zero before calling this
function.
<br><br> The return value is non-zero if the operation was successful. If the
return value is zero, something went wrong, which probably means the
programs ran out of memory.
sq~wtsearch.hxq~kt%size_t nel, struct hsearch_data *htabtintthdestroysq~
tà
The <CODE>hdestroy</CODE> function can be used to free all the resources
allocated in a previous call of <CODE>hcreate</CODE>. After a call to this
function it is again possible to call <CODE>hcreate</CODE> and allocate a new
table with possibly different size.
<br><br> It is important to remember that the elements contained in the hashing
table at the time <CODE>hdestroy</CODE> is called are <EM>not</EM> freed by this
function. It is the responsibility of the program code to free those
strings (if necessary at all). Freeing all the element memory is not
possible without extra, separately kept information since there is no
function to iterate through all available elements in the hashing table.
If it is really necessary to free a table and all elements the
programmer has to keep a list of all table elements and before calling
<CODE>hdestroy</CODE> s/he has to free all element's data using this list.
This is a very unpleasant mechanism and it also shows that this kind of
hashing tables is mainly meant for tables which are created once and
used until the end of the program run.
sq~wtsearch.hxq~rtvoidtvoidt
hdestroy_rsq~
t4
The <CODE>hdestroy_r</CODE> function frees all resources allocated by the
<CODE>hcreate_r</CODE> function for this very same object <VAR>htab</VAR>. As for
<CODE>hdestroy</CODE> it is the programs responsibility to free the strings
for the elements of the table.
sq~wtsearch.hxq~ytstruct hsearch_data *htabtvoidthsearchsq~
t˜
To search in a hashing table created using <CODE>hcreate</CODE> the
<CODE>hsearch</CODE> function must be used. This function can perform simple
search for an element (if <VAR>action</VAR> has the <CODE>FIND</CODE>) or it can
alternatively insert the key element into the hashing table. Entries
are never replaced.
<br><br> The key is denoted by a pointer to an object of type <CODE>ENTRY</CODE>. For
locating the corresponding position in the hashing table only the
<CODE>key</CODE> element of the structure is used.
<br><br> If an entry with matching key is found the <VAR>action</VAR> parameter is
irrelevant. The found entry is returned. If no matching entry is found
and the <VAR>action</VAR> parameter has the value <CODE>FIND</CODE> the function
returns a <CODE>NULL</CODE> pointer. If no entry is found and the
<VAR>action</VAR> parameter has the value <CODE>ENTER</CODE> a new entry is added
to the hashing table which is initialized with the parameter <VAR>item</VAR>.
A pointer to the newly added entry is returned.
sq~wtsearch.hxq~€tENTRY item, ACTION actiontENTRY *t hsearch_rsq~
tð
The <CODE>hsearch_r</CODE> function is equivalent to <CODE>hsearch</CODE>. The
meaning of the first two arguments is identical. But instead of
operating on a single global hashing table the function works on the
table described by the object pointed to by <VAR>htab</VAR> (which is
initialized by a call to <CODE>hcreate_r</CODE>).
<br><br> Another difference to <CODE>hcreate</CODE> is that the pointer to the found
entry in the table is not the return value of the functions. It is
returned by storing it in a pointer variables pointed to by the
<VAR>retval</VAR> parameter. The return value of the function is an integer
value indicating success if it is non-zero and failure if it is zero.
In the latter case the global variable <VAR>errno</VAR> signals the reason for
the failure.
<br><br> <DL>
<DT><CODE>ENOMEM</CODE>
<DD>
The table is filled and <CODE>hsearch_r</CODE> was called with an so far
unknown key and <VAR>action</VAR> set to <CODE>ENTER</CODE>.
<LI> ESRCH
The <VAR>action</VAR> parameter is <CODE>FIND</CODE> and no corresponding element
is found in the table.
sq~wtsearch.hxq~‡tDENTRY item, ACTION action, ENTRY **retval, struct hsearch_data *htabtintthtonlsq~
tÏ
This function converts the <CODE>uint32_t</CODE> integer <VAR>hostlong</VAR> from
host byte order to network byte order.
<br><br> This is used for IPv4 Internet addresses.
sq~wt netinet/in.hxq~Žtuint32_t hostlongtuint32_tthtonssq~
t”
This function converts the <CODE>uint16_t</CODE> integer <VAR>hostshort</VAR> from
host byte order to network byte order.
sq~wt netinet/in.hxq~•tuint16_t hostshorttuint16_tthypotsq~
tò
These functions return <CODE>sqrt (<VAR>x</VAR>*<VAR>x</VAR> +
<VAR>y</VAR>*<VAR>y</VAR>)</CODE>. This is the length of the hypotenuse of a right
triangle with sides of length <VAR>x</VAR> and <VAR>y</VAR>, or the distance
of the point (<VAR>x</VAR>, <VAR>y</VAR>) from the origin. Using this function
instead of the direct formula is wise, since the error is
much smaller. See also the function <CODE>cabs</CODE> in Absolute Value.
sq~wtmath.hxq~œtdouble x, double ytdoublethypotfsq~
tò
These functions return <CODE>sqrt (<VAR>x</VAR>*<VAR>x</VAR> +
<VAR>y</VAR>*<VAR>y</VAR>)</CODE>. This is the length of the hypotenuse of a right
triangle with sides of length <VAR>x</VAR> and <VAR>y</VAR>, or the distance
of the point (<VAR>x</VAR>, <VAR>y</VAR>) from the origin. Using this function
instead of the direct formula is wise, since the error is
much smaller. See also the function <CODE>cabs</CODE> in Absolute Value.
sq~wtmath.hxq~£tfloat x, float ytfloatthypotlsq~
tò
These functions return <CODE>sqrt (<VAR>x</VAR>*<VAR>x</VAR> +
<VAR>y</VAR>*<VAR>y</VAR>)</CODE>. This is the length of the hypotenuse of a right
triangle with sides of length <VAR>x</VAR> and <VAR>y</VAR>, or the distance
of the point (<VAR>x</VAR>, <VAR>y</VAR>) from the origin. Using this function
instead of the direct formula is wise, since the error is
much smaller. See also the function <CODE>cabs</CODE> in Absolute Value.
sq~wtmath.hxq~ªtlong double x, long double yt long doubleticonvsq~
tµ
The <CODE>iconv</CODE> function converts the text in the input buffer
according to the rules associated with the descriptor <VAR>cd</VAR> and
stores the result in the output buffer. It is possible to call the
function for the same text several times in a row since for stateful
character sets the necessary state information is kept in the data
structures associated with the descriptor.
<br><br> The input buffer is specified by <CODE>*<VAR>inbuf</VAR></CODE> and it contains
<CODE>*<VAR>inbytesleft</VAR></CODE> bytes. The extra indirection is necessary for
communicating the used input back to the caller (see below). It is
important to note that the buffer pointer is of type <CODE>char</CODE> and the
length is measured in bytes even if the input text is encoded in wide
characters.
<br><br> The output buffer is specified in a similar way. <CODE>*<VAR>outbuf</VAR></CODE>
points to the beginning of the buffer with at least
<CODE>*<VAR>outbytesleft</VAR></CODE> bytes room for the result. The buffer
pointer again is of type <CODE>char</CODE> and the length is measured in
bytes. If <VAR>outbuf</VAR> or <CODE>*<VAR>outbuf</VAR></CODE> is a null pointer, the
conversion is performed but no output is available.
<br><br> If <VAR>inbuf</VAR> is a null pointer, the <CODE>iconv</CODE> function performs the
necessary action to put the state of the conversion into the initial
state. This is obviously a no-op for non-stateful encodings, but if the
encoding has a state, such a function call might put some byte sequences
in the output buffer, which perform the necessary state changes. The
next call with <VAR>inbuf</VAR> not being a null pointer then simply goes on
from the initial state. It is important that the programmer never makes
any assumption as to whether the conversion has to deal with states.
Even if the input and output character sets are not stateful, the
implementation might still have to keep states. This is due to the
implementation chosen for the GNU C library as it is described below.
Therefore an <CODE>iconv</CODE> call to reset the state should always be
performed if some protocol requires this for the output text.
<br><br> The conversion stops for one of three reasons. The first is that all
characters from the input buffer are converted. This actually can mean
two things: either all bytes from the input buffer are consumed or
there are some bytes at the end of the buffer that possibly can form a
complete character but the input is incomplete. The second reason for a
stop is that the output buffer is full. And the third reason is that
the input contains invalid characters.
<br><br> In all of these cases the buffer pointers after the last successful
conversion, for input and output buffer, are stored in <VAR>inbuf</VAR> and
<VAR>outbuf</VAR>, and the available room in each buffer is stored in
<VAR>inbytesleft</VAR> and <VAR>outbytesleft</VAR>.
<br><br> Since the character sets selected in the <CODE>iconv_open</CODE> call can be
almost arbitrary, there can be situations where the input buffer contains
valid characters, which have no identical representation in the output
character set. The behavior in this situation is undefined. The
<EM>current</EM> behavior of the GNU C library in this situation is to
return with an error immediately. This certainly is not the most
desirable solution; therefore, future versions will provide better ones,
but they are not yet finished.
<br><br> If all input from the input buffer is successfully converted and stored
in the output buffer, the function returns the number of non-reversible
conversions performed. In all other cases the return value is
<CODE>(size_t) -1</CODE> and <CODE>errno</CODE> is set appropriately. In such cases
the value pointed to by <VAR>inbytesleft</VAR> is nonzero.
<br><br> <DL>
<DT><CODE>EILSEQ</CODE>
<DD>
The conversion stopped because of an invalid byte sequence in the input.
After the call, <CODE>*<VAR>inbuf</VAR></CODE> points at the first byte of the
invalid byte sequence.
<br><br> <LI> E2BIG
The conversion stopped because it ran out of space in the output buffer.
<br><br> <LI> EINVAL
The conversion stopped because of an incomplete byte sequence at the end
of the input buffer.
<br><br> <LI> EBADF
The <VAR>cd</VAR> argument is invalid.
<br><br> The <CODE>iconv</CODE> function was introduced in the XPG2 standard and is
declared in the <TT>iconv.h</TT> header.
sq~wticonv.hxq~±tRiconv_t cd, char **inbuf, size_t *inbytesleft, char **outbuf, size_t *outbyteslefttsize_tt iconv_closesq~
tº
The <CODE>iconv_close</CODE> function frees all resources associated with the
handle <VAR>cd</VAR>, which must have been returned by a successful call to
the <CODE>iconv_open</CODE> function.
<br><br> If the function call was successful the return value is 0.
Otherwise it is -1 and <CODE>errno</CODE> is set appropriately.
Defined error are:
<br><br> <DL>
<DT><CODE>EBADF</CODE>
<DD>
The conversion descriptor is invalid.
<br><br> The <CODE>iconv_close</CODE> function was introduced together with the rest
of the <CODE>iconv</CODE> functions in XPG2 and is declared in <TT>iconv.h</TT>.
sq~wticonv.hxq~¸t
iconv_t cdtintt
iconv_opensq~
t h
The <CODE>iconv_open</CODE> function has to be used before starting a
conversion. The two parameters this function takes determine the
source and destination character set for the conversion, and if the
implementation has the possibility to perform such a conversion, the
function returns a handle.
<br><br> If the wanted conversion is not available, the <CODE>iconv_open</CODE> function
returns <CODE>(iconv_t) -1</CODE>. In this case the global variable
<CODE>errno</CODE> can have the following values:
<br><br> <DL>
<DT><CODE>EMFILE</CODE>
<DD>
The process already has <CODE>OPEN_MAX</CODE> file descriptors open.
<LI> ENFILE
The system limit of open file is reached.
<LI> ENOMEM
Not enough memory to carry out the operation.
<LI> EINVAL
The conversion from <VAR>fromcode</VAR> to <VAR>tocode</VAR> is not supported.
<br><br> It is not possible to use the same descriptor in different threads to
perform independent conversions. The data structures associated
with the descriptor include information about the conversion state.
This must not be messed up by using it in different conversions.
<br><br> An <CODE>iconv</CODE> descriptor is like a file descriptor as for every use a
new descriptor must be created. The descriptor does not stand for all
of the conversions from <VAR>fromset</VAR> to <VAR>toset</VAR>.
<br><br> The GNU C library implementation of <CODE>iconv_open</CODE> has one
significant extension to other implementations. To ease the extension
of the set of available conversions, the implementation allows storing
the necessary files with data and code in an arbitrary number of
directories. How this extension must be written will be explained below
. Here it is only important to say
that all directories mentioned in the <CODE>GCONV_PATH</CODE> environment
variable are considered only if they contain a file <TT>gconv-modules</TT>.
These directories need not necessarily be created by the system
administrator. In fact, this extension is introduced to help users
writing and using their own, new conversions. Of course, this does not
work for security reasons in SUID binaries; in this case only the system
directory is considered and this normally is
<TT><VAR>prefix</VAR>/lib/gconv</TT>. The <CODE>GCONV_PATH</CODE> environment
variable is examined exactly once at the first call of the
<CODE>iconv_open</CODE> function. Later modifications of the variable have no
effect.
<br><br> The <CODE>iconv_open</CODE> function was introduced early in the X/Open
Portability Guide, version 2. It is supported by all commercial
Unices as it is required for the Unix branding. However, the quality and
completeness of the implementation varies widely. The <CODE>iconv_open</CODE>
function is declared in <TT>iconv.h</TT>.
sq~wticonv.hxq~¿t(const char *tocode, const char *fromcodeticonv_ttif_freenameindexsq~
tv
This function frees the structure returned by an earlier call to
<CODE>if_nameindex</CODE>.
sq~wtnet/if.hxq~Ætstruct if_nameindex *ptrtvoidtif_indextonamesq~
tq
This function maps an interface index to its corresponding name. The
returned name is placed in the buffer pointed to by <CODE>ifname</CODE>, which
must be at least <CODE>IFNAMSIZ</CODE> bytes in length. If the index was
invalid, the function's return value is a null pointer, otherwise it is
<CODE>ifname</CODE>.
sq~wtnet/if.hxq~Ít"unsigned int ifindex, char *ifnametchar *t if_nameindexsq~
t§
This function returns an array of <CODE>if_nameindex</CODE> structures, one
for every interface that is present. The end of the list is indicated
by a structure with an interface of 0 and a null name pointer. If an
error occurs, this function returns a null pointer.
<br><br> The returned structure must be freed with <CODE>if_freenameindex</CODE> after
use.
sq~wtnet/if.hxq~Ôtvoidtstruct if_nameindex *tif_nametoindexsq~
t¢
This function yields the interface index corresponding to a particular
name. If no interface exists with the name given, it returns 0.
sq~wtnet/if.hxq~Ûtconst char *ifnamet unsigned inttilogbsq~
t™
These functions are equivalent to the corresponding <CODE>logb</CODE>
functions except that they return signed integer values.
sq~wtmath.hxq~âtdouble xtinttilogbfsq~
t™
These functions are equivalent to the corresponding <CODE>logb</CODE>
functions except that they return signed integer values.
sq~wtmath.hxq~étfloat xtinttilogblsq~
t™
These functions are equivalent to the corresponding <CODE>logb</CODE>
functions except that they return signed integer values.
sq~wtmath.hxq~ðt
long double xtinttimaxabssq~
t
These functions return the absolute value of <VAR>number</VAR>.
<br><br> Most computers use a two's complement integer representation, in which
the absolute value of <CODE>INT_MIN</CODE> (the smallest possible <CODE>int</CODE>)
cannot be represented; thus, <CODE>abs (INT_MIN)</CODE> is not defined.
<br><br> <CODE>llabs</CODE> and <CODE>imaxdiv</CODE> are new to ISO C99.
<br><br> See Integers for a description of the <CODE>intmax_t</CODE> type.
<br><br>
sq~wt
inttypes.hxq~÷tintmax_t numbertintmax_ttimaxdivsq~
tˆ
The <CODE>imaxdiv</CODE> function is like the <CODE>div</CODE> function, but the
arguments are of type <CODE>intmax_t</CODE> and the result is returned as
a structure of type <CODE>imaxdiv_t</CODE>.
<br><br> See Integers for a description of the <CODE>intmax_t</CODE> type.
<br><br> The <CODE>imaxdiv</CODE> function was added in ISO C99.
sq~wt
inttypes.hxq~þt(intmax_t numerator, intmax_t denominatort imaxdiv_ttindexsq~
t9
<CODE>index</CODE> is another name for <CODE>strchr</CODE>; they are exactly the same.
New code should always use <CODE>strchr</CODE> since this name is defined in
ISO C while <CODE>index</CODE> is a BSD invention which never was available
on System V derived systems.
sq~wtstring.hxq~tconst char *string, int ctchar *t inet_addrsq~
t
This function converts the IPv4 Internet host address <VAR>name</VAR> from the
standard numbers-and-dots notation into binary data. If the input is
not valid, <CODE>inet_addr</CODE> returns <CODE>INADDR_NONE</CODE>. This is an
obsolete interface to <CODE>inet_aton</CODE>, described immediately above. It
is obsolete because <CODE>INADDR_NONE</CODE> is a valid address
(255.255.255.255), and <CODE>inet_aton</CODE> provides a cleaner way to
indicate error return.
sq~wt arpa/inet.hxq~ tconst char *nametuint32_tt inet_atonsq~
tM
This function converts the IPv4 Internet host address <VAR>name</VAR>
from the standard numbers-and-dots notation into binary data and stores
it in the <CODE>struct in_addr</CODE> that <VAR>addr</VAR> points to.
<CODE>inet_aton</CODE> returns nonzero if the address is valid, zero if not.
sq~wt sys/socket.ht netinet/in.ht arpa/inet.hxq~t&const char *name, struct in_addr *addrtintt
inet_lnaofsq~
t?
This function returns the local-address-within-network part of the
Internet host address <VAR>addr</VAR>.
<br><br> The function works only with traditional IPv4 class A, B and C network
types. It doesn't work with classless addresses and shouldn't be used
anymore.
sq~wt arpa/inet.hxq~tstruct in_addr addrtuint32_tt
inet_makeaddrsq~
tÃ
This function makes an IPv4 Internet host address by combining the network
number <VAR>net</VAR> with the local-address-within-network number
<VAR>local</VAR>.
sq~wt arpa/inet.hxq~#tuint32_t net, uint32_t localtstruct in_addrt
inet_netofsq~
t1
This function returns the network number part of the Internet host
address <VAR>addr</VAR>.
<br><br> The function works only with traditional IPv4 class A, B and C network
types. It doesn't work with classless addresses and shouldn't be used
anymore.
sq~wt arpa/inet.hxq~*tstruct in_addr addrtuint32_tt inet_networksq~
tÙ
This function extracts the network number from the address <VAR>name</VAR>,
given in the standard numbers-and-dots notation. The returned address is
in host order. If the input is not valid, <CODE>inet_network</CODE> returns
<CODE>-1</CODE>.
<br><br> The function works only with traditional IPv4 class A, B and C network
types. It doesn't work with classless addresses and shouldn't be used
anymore.
sq~wt arpa/inet.hxq~1tconst char *nametuint32_tt inet_ntoasq~
t
This function converts the IPv4 Internet host address <VAR>addr</VAR> to a
string in the standard numbers-and-dots notation. The return value is
a pointer into a statically-allocated buffer. Subsequent calls will
overwrite the same buffer, so you should copy the string if you need
to save it.
<br><br> In multi-threaded programs each thread has an own statically-allocated
buffer. But still subsequent calls of <CODE>inet_ntoa</CODE> in the same
thread will overwrite the result of the last call.
<br><br> Instead of <CODE>inet_ntoa</CODE> the newer function <CODE>inet_ntop</CODE> which is
described below should be used since it handles both IPv4 and IPv6
addresses.
sq~wt arpa/inet.hxq~8tstruct in_addr addrtchar *t inet_ntopsq~
t
This function converts an Internet address (either IPv4 or IPv6) from
network (binary) to presentation (textual) form. <VAR>af</VAR> should be
either <CODE>AF_INET</CODE> or <CODE>AF_INET6</CODE>, as appropriate. <VAR>cp</VAR> is a
pointer to the address to be converted. <VAR>buf</VAR> should be a pointer
to a buffer to hold the result, and <VAR>len</VAR> is the length of this
buffer. The return value from the function will be this buffer address.
sq~wt arpa/inet.hxq~?t-int af, const void *cp, char *buf, size_t lent const char *t inet_ptonsq~
t÷
This function converts an Internet address (either IPv4 or IPv6) from
presentation (textual) to network (binary) format. <VAR>af</VAR> should be
either <CODE>AF_INET</CODE> or <CODE>AF_INET6</CODE>, as appropriate for the type of
address being converted. <VAR>cp</VAR> is a pointer to the input string, and
<VAR>buf</VAR> is a pointer to a buffer for the result. It is the caller's
responsibility to make sure the buffer is large enough.
sq~wt arpa/inet.hxq~Ft!int af, const char *cp, void *buftintt
initgroupssq~
t"
The <CODE>initgroups</CODE> function sets the process's supplementary group
IDs to be the normal default for the user name <VAR>user</VAR>. The group
<VAR>group</VAR> is automatically included.
<br><br> This function works by scanning the group database for all the groups
<VAR>user</VAR> belongs to. It then calls <CODE>setgroups</CODE> with the list it
has constructed.
<br><br> The return values and error conditions are the same as for
<CODE>setgroups</CODE>.
sq~wtgrp.hxq~Mtconst char *user, gid_t grouptintt initstatesq~
tl
The <CODE>initstate</CODE> function is used to initialize the random number
generator state. The argument <VAR>state</VAR> is an array of <VAR>size</VAR>
bytes, used to hold the state information. It is initialized based on
<VAR>seed</VAR>. The size must be between 8 and 256 bytes, and should be a
power of two. The bigger the <VAR>state</VAR> array, the better.
<br><br> The return value is the previous value of the state information array.
You can use this value later as an argument to <CODE>setstate</CODE> to
restore that state.
sq~wtstdlib.hxq~Tt+unsigned int seed, void *state, size_t sizetvoid *t initstate_rsq~
tû
The <CODE>initstate_r</CODE> function behaves exactly like the <CODE>initstate</CODE>
function except that it uses and modifies the state in the object
pointed to by the fourth parameter instead of the global state.
sq~wtstdlib.hxq~[t]unsigned int seed, char *restrict statebuf, size_t statelen, struct random_data *restrict buftinttinnetgrsq~
t 
This function tests whether the triple specified by the parameters
<VAR>hostp</VAR>, <VAR>userp</VAR>, and <VAR>domainp</VAR> is part of the netgroup
<VAR>netgroup</VAR>. Using this function has the advantage that
<br><br> <OL>
<LI>
no other netgroup function can use the global netgroup state since
internal locking is used and
<LI>
the function is implemented more efficiently than successive calls
to the other <CODE>set</CODE>/<CODE>get</CODE>/<CODE>endnetgrent</CODE> functions.
</OL>
<br><br> Any of the pointers <VAR>hostp</VAR>, <VAR>userp</VAR>, and <VAR>domainp</VAR> can be
<CODE>NULL</CODE> which means any value is accepted in this position. This is
also true for the name <CODE>-</CODE> which should not match any other string
otherwise.
<br><br> The return value is <CODE>1</CODE> if an entry matching the given triple is
found in the netgroup. The return value is <CODE>0</CODE> if the netgroup
itself is not found, the netgroup does not contain the triple or
internal errors occurred.
sq~wtnetdb.hxq~btLconst char *netgroup, const char *host, const char *user, const char *domaintinttioctlsq~
t³
<br><br> The <CODE>ioctl</CODE> function performs the generic I/O operation
<VAR>command</VAR> on <VAR>filedes</VAR>.
<br><br> A third argument is usually present, either a single number or a pointer
to a structure. The meaning of this argument, the returned value, and
any error codes depends upon the command used. Often -1 is
returned for a failure.
<br><br>
sq~wtfcntl.ht sys/ioctl.hxq~itint filedes, int command, ...tinttisalnumsq~
tú
Returns true if <VAR>c</VAR> is an alphanumeric character (a letter or
number); in other words, if either <CODE>isalpha</CODE> or <CODE>isdigit</CODE> is
true of a character, then <CODE>isalnum</CODE> is also true.
sq~wtctype.hxq~qtint ctinttisalphasq~
tî
Returns true if <VAR>c</VAR> is an alphabetic character (a letter). If
<CODE>islower</CODE> or <CODE>isupper</CODE> is true of a character, then
<CODE>isalpha</CODE> is also true.
<br><br> In some locales, there may be additional characters for which
<CODE>isalpha</CODE> is true---letters which are neither upper case nor lower
case. But in the standard <CODE>"C"</CODE> locale, there are no such
additional characters.
sq~wtctype.hxq~xtint ctinttisasciisq~
tÛ
Returns true if <VAR>c</VAR> is a 7-bit <CODE>unsigned char</CODE> value that fits
into the US/UK ASCII character set. This function is a BSD extension
and is also an SVID extension.
sq~wtctype.hxq~tint ctinttisattysq~
t¤
This function returns <CODE>1</CODE> if <VAR>filedes</VAR> is a file descriptor
associated with an open terminal device, and 0 otherwise.
sq~wtunistd.hxq~†t int filedestinttisblanksq~
t°
Returns true if <VAR>c</VAR> is a blank character; that is, a space or a tab.
This function was originally a GNU extension, but was added in ISO C99.
sq~wtctype.hxq~�tint ctinttiscntrlsq~
t‡
Returns true if <VAR>c</VAR> is a control character (that is, a character that
is not a printing character).
sq~wtctype.hxq~”tint ctinttisdigitsq~
tj
Returns true if <VAR>c</VAR> is a decimal digit (<samp>0</samp> through <samp>9</samp>).
sq~wtctype.hxq~›tint ctinttisgraphsq~
tÉ
Returns true if <VAR>c</VAR> is a graphic character; that is, a character
that has a glyph associated with it. The whitespace characters are not
considered graphic.
sq~wtctype.hxq~¢tint ctinttisinfsq~
tÉ
This function returns <CODE>-1</CODE> if <VAR>x</VAR> represents negative infinity,
<CODE>1</CODE> if <VAR>x</VAR> represents positive infinity, and <CODE>0</CODE> otherwise.
sq~wtmath.hxq~©tdouble xtinttisinffsq~
tÉ
This function returns <CODE>-1</CODE> if <VAR>x</VAR> represents negative infinity,
<CODE>1</CODE> if <VAR>x</VAR> represents positive infinity, and <CODE>0</CODE> otherwise.
sq~wtmath.hxq~°tfloat xtinttisinflsq~
tÉ
This function returns <CODE>-1</CODE> if <VAR>x</VAR> represents negative infinity,
<CODE>1</CODE> if <VAR>x</VAR> represents positive infinity, and <CODE>0</CODE> otherwise.
sq~wtmath.hxq~·t
long double xtinttislowersq~
t¥
Returns true if <VAR>c</VAR> is a lower-case letter. The letter need not be
from the Latin alphabet, any alphabet representable is valid.
sq~wtctype.hxq~¾tint ctinttisnansq~
tå
This function returns a nonzero value if <VAR>x</VAR> is a ``not a number''
value, and zero otherwise.
<br><br> NB: The <CODE>isnan</CODE> macro defined by ISO C99 overrides
the BSD function. This is normally not a problem, because the two
routines behave identically. However, if you really need to get the BSD
function for some reason, you can write
<br><br> <pre><br>
(isnan) (x)<br>
</pre>
sq~wtmath.hxq~Åtdouble xtinttisnanfsq~
tå
This function returns a nonzero value if <VAR>x</VAR> is a ``not a number''
value, and zero otherwise.
<br><br> NB: The <CODE>isnan</CODE> macro defined by ISO C99 overrides
the BSD function. This is normally not a problem, because the two
routines behave identically. However, if you really need to get the BSD
function for some reason, you can write
<br><br> <pre><br>
(isnan) (x)<br>
</pre>
sq~wtmath.hxq~Ìtfloat xtinttisnanlsq~
tå
This function returns a nonzero value if <VAR>x</VAR> is a ``not a number''
value, and zero otherwise.
<br><br> NB: The <CODE>isnan</CODE> macro defined by ISO C99 overrides
the BSD function. This is normally not a problem, because the two
routines behave identically. However, if you really need to get the BSD
function for some reason, you can write
<br><br> <pre><br>
(isnan) (x)<br>
</pre>
sq~wtmath.hxq~Ót
long double xtinttisprintsq~
t´
Returns true if <VAR>c</VAR> is a printing character. Printing characters
include all the graphic characters, plus the space (<samp> </samp>) character.
sq~wtctype.hxq~Útint ctinttispunctsq~
t­
Returns true if <VAR>c</VAR> is a punctuation character.
This means any printing character that is not alphanumeric or a space
character.
sq~wtctype.hxq~átint ctinttisspacesq~
t
Returns true if <VAR>c</VAR> is a whitespace character. In the standard
<CODE>"C"</CODE> locale, <CODE>isspace</CODE> returns true for only the standard
whitespace characters:
<br><br> <DL>
<DT><CODE>' '</CODE>
<DD>
space
<br><br> <LI> '\f'
formfeed
<br><br> <LI> '\n'
newline
<br><br> <LI> '\r'
carriage return
<br><br> <LI> '\t'
horizontal tab
<br><br> <LI> '\v'
vertical tab
sq~wtctype.hxq~ètint ctinttisuppersq~
t¦
Returns true if <VAR>c</VAR> is an upper-case letter. The letter need not be
from the Latin alphabet, any alphabet representable is valid.
sq~wtctype.hxq~ïtint ctinttiswalnumsq~
tò
This function returns a nonzero value if <VAR>wc</VAR> is an alphanumeric
character (a letter or number); in other words, if either <CODE>iswalpha</CODE>
or <CODE>iswdigit</CODE> is true of a character, then <CODE>iswalnum</CODE> is also
true.
<br><br>
This function can be implemented using
<br><br> <pre><br>
iswctype (wc, wctype ("alnum"))<br>
</pre>
<br><br> It is declared in <TT>wctype.h</TT>.
sq~wtwctype.hxq~öt wint_t wctinttiswalphasq~
tÅ
Returns true if <VAR>wc</VAR> is an alphabetic character (a letter). If
<CODE>iswlower</CODE> or <CODE>iswupper</CODE> is true of a character, then
<CODE>iswalpha</CODE> is also true.
<br><br> In some locales, there may be additional characters for which
<CODE>iswalpha</CODE> is true---letters which are neither upper case nor lower
case. But in the standard <CODE>"C"</CODE> locale, there are no such
additional characters.
<br><br>
This function can be implemented using
<br><br> <pre><br>
iswctype (wc, wctype ("alpha"))<br>
</pre>
<br><br> It is declared in <TT>wctype.h</TT>.
sq~wtwctype.hxq~ýt wint_t wctinttiswblanksq~
tÞ
Returns true if <VAR>wc</VAR> is a blank character; that is, a space or a tab.
This function was originally a GNU extension, but was added in ISO C99.
It is declared in <TT>wchar.h</TT>.
sq~wtwctype.hxq~t wint_t wctinttiswcntrlsq~
tZ
Returns true if <VAR>wc</VAR> is a control character (that is, a character that
is not a printing character).
<br><br>
This function can be implemented using
<br><br> <pre><br>
iswctype (wc, wctype ("cntrl"))<br>
</pre>
<br><br> It is declared in <TT>wctype.h</TT>.
sq~wtwctype.hxq~ t wint_t wctinttiswctypesq~
t.
This function returns a nonzero value if <VAR>wc</VAR> is in the character
class specified by <VAR>desc</VAR>. <VAR>desc</VAR> must previously be returned
by a successful call to <CODE>wctype</CODE>.
<br><br> This function is declared in <TT>wctype.h</TT>.
sq~wtwctype.hxq~twint_t wc, wctype_t desctinttiswdigitsq~
t
Returns true if <VAR>wc</VAR> is a digit (e.g., <samp>0</samp> through <samp>9</samp>).
Please note that this function does not only return a nonzero value for
<EM>decimal</EM> digits, but for all kinds of digits. A consequence is
that code like the following will <h3>not</h3> work unconditionally for
wide characters:
<br><br> <pre><br>
n = 0;<br>
while (iswdigit (*wc))<br>
{<br>
n *= 10;<br>
n += *wc++ - L'0';<br>
}<br>
</pre><br>
<br><br> <br>
This function can be implemented using<br>
<br><br> <pre><br>
iswctype (wc, wctype ("digit"))<br>
</pre>
<br><br> It is declared in <TT>wctype.h</TT>.
sq~wtwctype.hxq~t wint_t wctinttiswgraphsq~
tœ
Returns true if <VAR>wc</VAR> is a graphic character; that is, a character
that has a glyph associated with it. The whitespace characters are not
considered graphic.
<br><br>
This function can be implemented using
<br><br> <pre><br>
iswctype (wc, wctype ("graph"))<br>
</pre>
<br><br> It is declared in <TT>wctype.h</TT>.
sq~wtwctype.hxq~ t wint_t wctinttiswlowersq~
tx
Returns true if <VAR>wc</VAR> is a lower-case letter. The letter need not be
from the Latin alphabet, any alphabet representable is valid.
<br><br>
This function can be implemented using
<br><br> <pre><br>
iswctype (wc, wctype ("lower"))<br>
</pre>
<br><br> It is declared in <TT>wctype.h</TT>.
sq~wtctype.hxq~'t wint_t wctinttiswprintsq~
t‡
Returns true if <VAR>wc</VAR> is a printing character. Printing characters
include all the graphic characters, plus the space (<samp> </samp>) character.
<br><br>
This function can be implemented using
<br><br> <pre><br>
iswctype (wc, wctype ("print"))<br>
</pre>
<br><br> It is declared in <TT>wctype.h</TT>.
sq~wtwctype.hxq~.t wint_t wctinttiswpunctsq~
t€
Returns true if <VAR>wc</VAR> is a punctuation character.
This means any printing character that is not alphanumeric or a space
character.
<br><br>
This function can be implemented using
<br><br> <pre><br>
iswctype (wc, wctype ("punct"))<br>
</pre>
<br><br> It is declared in <TT>wctype.h</TT>.
sq~wtwctype.hxq~5t wint_t wctinttiswspacesq~
tï
Returns true if <VAR>wc</VAR> is a whitespace character. In the standard
<CODE>"C"</CODE> locale, <CODE>iswspace</CODE> returns true for only the standard
whitespace characters:
<br><br> <DL>
<DT><CODE>L' '</CODE>
<DD>
space
<br><br> <LI> L'\f'
formfeed
<br><br> <LI> L'\n'
newline
<br><br> <LI> L'\r'
carriage return
<br><br> <LI> L'\t'
horizontal tab
<br><br> <LI> L'\v'
vertical tab
<br><br>
This function can be implemented using
<br><br> <pre><br>
iswctype (wc, wctype ("space"))<br>
</pre>
<br><br> It is declared in <TT>wctype.h</TT>.
sq~wtwctype.hxq~<t wint_t wctinttiswuppersq~
ty
Returns true if <VAR>wc</VAR> is an upper-case letter. The letter need not be
from the Latin alphabet, any alphabet representable is valid.
<br><br>
This function can be implemented using
<br><br> <pre><br>
iswctype (wc, wctype ("upper"))<br>
</pre>
<br><br> It is declared in <TT>wctype.h</TT>.
sq~wtwctype.hxq~Ct wint_t wctintt iswxdigitsq~
tñ
Returns true if <VAR>wc</VAR> is a hexadecimal digit.
Hexadecimal digits include the normal decimal digits <samp>0</samp> through
<samp>9</samp> and the letters <samp>A</samp> through <samp>F</samp> and
<samp>a</samp> through <samp>f</samp>.
<br><br>
This function can be implemented using
<br><br> <pre><br>
iswctype (wc, wctype ("xdigit"))<br>
</pre>
<br><br> It is declared in <TT>wctype.h</TT>.
sq~wtwctype.hxq~Jt wint_t wctinttisxdigitsq~
t
Returns true if <VAR>c</VAR> is a hexadecimal digit.
Hexadecimal digits include the normal decimal digits <samp>0</samp> through
<samp>9</samp> and the letters <samp>A</samp> through <samp>F</samp> and
<samp>a</samp> through <samp>f</samp>.
sq~wtctype.hxq~Qtint ctinttj0sq~
t«
<CODE>j0</CODE> returns the Bessel function of the first kind of order 0 of
<VAR>x</VAR>. It may signal underflow if <VAR>x</VAR> is too large.
sq~wtmath.hxq~Xtdouble xtdoubletj0fsq~
t«
<CODE>j0</CODE> returns the Bessel function of the first kind of order 0 of
<VAR>x</VAR>. It may signal underflow if <VAR>x</VAR> is too large.
sq~wtmath.hxq~_tfloat xtfloattj0lsq~
t«
<CODE>j0</CODE> returns the Bessel function of the first kind of order 0 of
<VAR>x</VAR>. It may signal underflow if <VAR>x</VAR> is too large.
sq~wtmath.hxq~ft
long double xt long doubletj1sq~
t«
<CODE>j1</CODE> returns the Bessel function of the first kind of order 1 of
<VAR>x</VAR>. It may signal underflow if <VAR>x</VAR> is too large.
sq~wtmath.hxq~mtdouble xtdoubletj1fsq~
t«
<CODE>j1</CODE> returns the Bessel function of the first kind of order 1 of
<VAR>x</VAR>. It may signal underflow if <VAR>x</VAR> is too large.
sq~wtmath.hxq~ttfloat xtfloattj1lsq~
t«
<CODE>j1</CODE> returns the Bessel function of the first kind of order 1 of
<VAR>x</VAR>. It may signal underflow if <VAR>x</VAR> is too large.
sq~wtmath.hxq~{t
long double xt long doubletjnsq~
t
<CODE>jn</CODE> returns the Bessel function of the first kind of order
<VAR>n</VAR> of <VAR>x</VAR>. It may signal underflow if <VAR>x</VAR> is too large.
sq~wtmath.hxq~‚tint n, double xtdoubletjnfsq~
t
<CODE>jn</CODE> returns the Bessel function of the first kind of order
<VAR>n</VAR> of <VAR>x</VAR>. It may signal underflow if <VAR>x</VAR> is too large.
sq~wtmath.hxq~‰tint n, float xtfloattjnlsq~
t
<CODE>jn</CODE> returns the Bessel function of the first kind of order
<VAR>n</VAR> of <VAR>x</VAR>. It may signal underflow if <VAR>x</VAR> is too large.
sq~wtmath.hxq~�tint n, long double xt long doubletjrand48sq~
t5
The <CODE>jrand48</CODE> function is similar to <CODE>nrand48</CODE>. The only
difference is that the numbers returned are in the range <CODE>-2^31</CODE> to
<CODE>2^31</CODE> (exclusive). For the <CODE>xsubi</CODE> parameter the same
requirements are necessary.
sq~wtstdlib.hxq~—tunsigned short int xsubi[3]tlong intt jrand48_rsq~
t÷
The <CODE>jrand48_r</CODE> function is similar to <CODE>jrand48</CODE>. Like the
other reentrant functions of this function family it uses the
congruential formula parameters from the buffer pointed to by
<VAR>buffer</VAR>.
<br><br> If the return value is non-negative the variable pointed to by
<VAR>result</VAR> contains the result.
<br><br> This function is a GNU extension and should not be used in portable
programs.
sq~wtstdlib.hxq~žtJunsigned short int xsubi[3], struct drand48_data *buffer, long int *resulttinttkillsq~
t £
The <CODE>kill</CODE> function sends the signal <VAR>signum</VAR> to the process
or process group specified by <VAR>pid</VAR>. Besides the signals listed in
Standard Signals, <VAR>signum</VAR> can also have a value of zero to
check the validity of the <VAR>pid</VAR>.
<br><br> The <VAR>pid</VAR> specifies the process or process group to receive the
signal:
<br><br> <DL>
<DT><CODE><VAR>pid</VAR> > 0</CODE>
<DD>
The process whose identifier is <VAR>pid</VAR>.
<br><br> <DT><CODE><VAR>pid</VAR> == 0</CODE>
<DD>
All processes in the same process group as the sender.
<br><br> <LI> <VAR>pid</VAR> < -1
The process group whose identifier is <VAR>pid</VAR>.
<br><br> <LI> <VAR>pid</VAR> == -1
If the process is privileged, send the signal to all processes except
for some special system processes. Otherwise, send the signal to all
processes with the same effective user ID.
<br><br> A process can send a signal to itself with a call like <CODE>kill
(getpid(), <VAR>signum</VAR>)</CODE>. If <CODE>kill</CODE> is used by a process to send
a signal to itself, and the signal is not blocked, then <CODE>kill</CODE>
delivers at least one signal (which might be some other pending
unblocked signal instead of the signal <VAR>signum</VAR>) to that process
before it returns.
<br><br> The return value from <CODE>kill</CODE> is zero if the signal can be sent
successfully. Otherwise, no signal is sent, and a value of <CODE>-1</CODE> is
returned. If <VAR>pid</VAR> specifies sending a signal to several processes,
<CODE>kill</CODE> succeeds if it can send the signal to at least one of them.
There's no way you can tell which of the processes got the signal
or whether all of them did.
<br><br> The following <CODE>errno</CODE> error conditions are defined for this function:
<br><br> <DL>
<LI> EINVAL
The <VAR>signum</VAR> argument is an invalid or unsupported number.
<br><br> <LI> EPERM
You do not have the privilege to send a signal to the process or any of
the processes in the process group named by <VAR>pid</VAR>.
<br><br> <LI> ESRCH
The <VAR>pid</VAR> argument does not refer to an existing process or group.
sq~wtsignal.hxq~¥tpid_t pid, int signumtinttkillpgsq~
tþ
This is similar to <CODE>kill</CODE>, but sends signal <VAR>signum</VAR> to the
process group <VAR>pgid</VAR>. This function is provided for compatibility
with BSD; using <CODE>kill</CODE> to do this is more portable.
sq~wtsignal.hxq~¬tint pgid, int signumtinttl64asq~
t Ö
This function encodes a 32-bit input value using characters from the
basic character set. It returns a pointer to a 7 character buffer which
contains an encoded version of <VAR>n</VAR>. To encode a series of bytes the
user must copy the returned string to a destination buffer. It returns
the empty string if <VAR>n</VAR> is zero, which is somewhat bizarre but
mandated by the standard.*
Warning: Since a static buffer is used this function should not
be used in multi-threaded programs. There is no thread-safe alternative
to this function in the C library.*
Compatibility Note: The XPG standard states that the return
value of <CODE>l64a</CODE> is undefined if <VAR>n</VAR> is negative. In the GNU
implementation, <CODE>l64a</CODE> treats its argument as unsigned, so it will
return a sensible encoding for any nonzero <VAR>n</VAR>; however, portable
programs should not rely on this.
<br><br> To encode a large buffer <CODE>l64a</CODE> must be called in a loop, once for
each 32-bit word of the buffer. For example, one could do something
like this:
<br><br> <pre><br>
char *<br>
encode (const void *buf, size_t len)<br>
{<br>
/* We know in advance how long the buffer has to be. */<br>
unsigned char *in = (unsigned char *) buf;<br>
char *out = malloc (6 + ((len + 3) / 4) * 6 + 1);<br>
char *cp = out, *p;<br>
<br><br> /* Encode the length. */<br>
/* Using `htonl' is necessary so that the data can be<br>
decoded even on machines with different byte order.<br>
`l64a' can return a string shorter than 6 bytes, so <br>
we pad it with encoding of 0 ('.') at the end by <br>
hand. */<br>
<br><br> p = stpcpy (cp, l64a (htonl (len)));<br>
cp = mempcpy (p, "......", 6 - (p - cp));<br>
<br><br> while (len > 3)<br>
{<br>
unsigned long int n = *in++;<br>
n = (n << 8) | *in++;<br>
n = (n << 8) | *in++;<br>
n = (n << 8) | *in++;<br>
len -= 4;<br>
p = stpcpy (cp, l64a (htonl (n)));<br>
cp = mempcpy (p, "......", 6 - (p - cp));<br>
}<br>
if (len > 0)<br>
{<br>
unsigned long int n = *in++;<br>
if (--len > 0)<br>
{<br>
n = (n << 8) | *in++;<br>
if (--len > 0)<br>
n = (n << 8) | *in;<br>
}<br>
cp = stpcpy (cp, l64a (htonl (n)));<br>
}<br>
*cp = '\0';<br>
return out;<br>
}<br>
</pre>
<br><br> It is strange that the library does not provide the complete
functionality needed but so be it.
<br><br>
sq~wtstdlib.hxq~³t
long int ntchar *tlabssq~
t
These functions return the absolute value of <VAR>number</VAR>.
<br><br> Most computers use a two's complement integer representation, in which
the absolute value of <CODE>INT_MIN</CODE> (the smallest possible <CODE>int</CODE>)
cannot be represented; thus, <CODE>abs (INT_MIN)</CODE> is not defined.
<br><br> <CODE>llabs</CODE> and <CODE>imaxdiv</CODE> are new to ISO C99.
<br><br> See Integers for a description of the <CODE>intmax_t</CODE> type.
<br><br>
sq~wtstdlib.hxq~ºtlong int numbertlong inttlcong48sq~
tÿ
The <CODE>lcong48</CODE> function allows the user to change the complete state
of the random number generator. Unlike <CODE>srand48</CODE> and
<CODE>seed48</CODE>, this function also changes the constants in the
congruential formula.
<br><br> From the seven elements in the array <VAR>param</VAR> the least significant
16 bits of the entries <CODE><VAR>param</VAR>[0]</CODE> to <CODE><VAR>param</VAR>[2]</CODE>
determine the initial state, the least significant 16 bits of
<CODE><VAR>param</VAR>[3]</CODE> to <CODE><VAR>param</VAR>[5]</CODE> determine the 48 bit
constant <CODE>a</CODE> and <CODE><VAR>param</VAR>[6]</CODE> determines the 16-bit value
<CODE>c</CODE>.
sq~wtstdlib.hxq~Átunsigned short int param[7]tvoidt lcong48_rsq~
tŒ
This function initializes all aspects of the random number generator
described in <VAR>buffer</VAR> with the data in <VAR>param</VAR>. Here it is
especially true that the function does more than just copying the
contents of <VAR>param</VAR> and <VAR>buffer</VAR>. More work is required and
therefore it is important to use this function rather than initializing
the random number generator directly.
<br><br> If the return value is non-negative the function call succeeded.
<br><br> This function is a GNU extension and should not be used in portable
programs.
sq~wtstdlib.hxq~Èt8unsigned short int param[7], struct drand48_data *buffertinttldexpsq~
tp
These functions return the result of multiplying the floating-point
number <VAR>value</VAR> by 2 raised to the power <VAR>exponent</VAR>. (It can
be used to reassemble floating-point numbers that were taken apart
by <CODE>frexp</CODE>.)
<br><br> For example, <CODE>ldexp (0.8, 4)</CODE> returns <CODE>12.8</CODE>.
sq~wtmath.hxq~Ïtdouble value, int exponenttdoubletldexpfsq~
tp
These functions return the result of multiplying the floating-point
number <VAR>value</VAR> by 2 raised to the power <VAR>exponent</VAR>. (It can
be used to reassemble floating-point numbers that were taken apart
by <CODE>frexp</CODE>.)
<br><br> For example, <CODE>ldexp (0.8, 4)</CODE> returns <CODE>12.8</CODE>.
sq~wtmath.hxq~Ötfloat value, int exponenttfloattldexplsq~
tp
These functions return the result of multiplying the floating-point
number <VAR>value</VAR> by 2 raised to the power <VAR>exponent</VAR>. (It can
be used to reassemble floating-point numbers that were taken apart
by <CODE>frexp</CODE>.)
<br><br> For example, <CODE>ldexp (0.8, 4)</CODE> returns <CODE>12.8</CODE>.
sq~wtmath.hxq~Ýtlong double value, int exponentt long doubletldivsq~
tå
The <CODE>ldiv</CODE> function is similar to <CODE>div</CODE>, except that the
arguments are of type <CODE>long int</CODE> and the result is returned as a
structure of type <CODE>ldiv_t</CODE>.
sq~wtstdlib.hxq~ät(long int numerator, long int denominatortldiv_ttlfindsq~
tR
The <CODE>lfind</CODE> function searches in the array with <CODE>*<VAR>nmemb</VAR></CODE>
elements of <VAR>size</VAR> bytes pointed to by <VAR>base</VAR> for an element
which matches the one pointed to by <VAR>key</VAR>. The function pointed to
by <VAR>compar</VAR> is used decide whether two elements match.
<br><br> The return value is a pointer to the matching element in the array
starting at <VAR>base</VAR> if it is found. If no matching element is
available <CODE>NULL</CODE> is returned.
<br><br> The mean runtime of this function is <CODE>*<VAR>nmemb</VAR></CODE>/2. This
function should only be used if elements often get added to or deleted from
the array in which case it might not be useful to sort the array before
searching.
sq~wtstdlib.htsearch.hxq~ëtOconst void *key, void *base, size_t *nmemb, size_t size, comparison_fn_t compartvoid *tlgammasq~
t$
<CODE>lgamma</CODE> returns the natural logarithm of the absolute value of
the gamma function of <VAR>x</VAR>. The gamma function is defined as
<pre><br>
gamma (x) = integral from 0 to infinity{} of t^(x-1) e^-t dt<br>
</pre><br>
<br>
<br><br> <br>
The sign of the gamma function is stored in the global variable<br>
<VAR>signgam</VAR>, which is declared in <TT>math.h</TT>. It is <CODE>1</CODE> if<br>
the intermediate result was positive or zero, or <CODE>-1</CODE> if it was<br>
negative.<br>
<br><br> To compute the real gamma function you can use the <CODE>tgamma</CODE><br>
function or you can compute the values as follows:<br>
<pre><br>
lgam = lgamma(x);<br>
gam = signgam*exp(lgam);<br>
</pre>
<br><br> The gamma function has singularities at the non-positive integers.
<CODE>lgamma</CODE> will raise the zero divide exception if evaluated at a
singularity.
sq~wtmath.hxq~ótdouble xtdoubletlgamma_rsq~
t
<CODE>lgamma_r</CODE> is just like <CODE>lgamma</CODE>, but it stores the sign of
the intermediate result in the variable pointed to by <VAR>signp</VAR>
instead of in the <VAR>signgam</VAR> global. This means it is reentrant.
sq~wtmath.hxq~útdouble x, int *signptdoubletlgammafsq~
t$
<CODE>lgamma</CODE> returns the natural logarithm of the absolute value of
the gamma function of <VAR>x</VAR>. The gamma function is defined as
<pre><br>
gamma (x) = integral from 0 to infinity{} of t^(x-1) e^-t dt<br>
</pre><br>
<br>
<br><br> <br>
The sign of the gamma function is stored in the global variable<br>
<VAR>signgam</VAR>, which is declared in <TT>math.h</TT>. It is <CODE>1</CODE> if<br>
the intermediate result was positive or zero, or <CODE>-1</CODE> if it was<br>
negative.<br>
<br><br> To compute the real gamma function you can use the <CODE>tgamma</CODE><br>
function or you can compute the values as follows:<br>
<pre><br>
lgam = lgamma(x);<br>
gam = signgam*exp(lgam);<br>
</pre>
<br><br> The gamma function has singularities at the non-positive integers.
<CODE>lgamma</CODE> will raise the zero divide exception if evaluated at a
singularity.
sq~wtmath.hxq~tfloat xtfloatt lgammaf_rsq~
t
<CODE>lgamma_r</CODE> is just like <CODE>lgamma</CODE>, but it stores the sign of
the intermediate result in the variable pointed to by <VAR>signp</VAR>
instead of in the <VAR>signgam</VAR> global. This means it is reentrant.
sq~wtmath.hxq~tfloat x, int *signptfloattlgammalsq~
t$
<CODE>lgamma</CODE> returns the natural logarithm of the absolute value of
the gamma function of <VAR>x</VAR>. The gamma function is defined as
<pre><br>
gamma (x) = integral from 0 to infinity{} of t^(x-1) e^-t dt<br>
</pre><br>
<br>
<br><br> <br>
The sign of the gamma function is stored in the global variable<br>
<VAR>signgam</VAR>, which is declared in <TT>math.h</TT>. It is <CODE>1</CODE> if<br>
the intermediate result was positive or zero, or <CODE>-1</CODE> if it was<br>
negative.<br>
<br><br> To compute the real gamma function you can use the <CODE>tgamma</CODE><br>
function or you can compute the values as follows:<br>
<pre><br>
lgam = lgamma(x);<br>
gam = signgam*exp(lgam);<br>
</pre>
<br><br> The gamma function has singularities at the non-positive integers.
<CODE>lgamma</CODE> will raise the zero divide exception if evaluated at a
singularity.
sq~wtmath.hxq~t
long double xt long doublet lgammal_rsq~
t
<CODE>lgamma_r</CODE> is just like <CODE>lgamma</CODE>, but it stores the sign of
the intermediate result in the variable pointed to by <VAR>signp</VAR>
instead of in the <VAR>signgam</VAR> global. This means it is reentrant.
sq~wtmath.hxq~tlong double x, int *signpt long doubletlinksq~
tÃ
The <CODE>link</CODE> function makes a new link to the existing file named by
<VAR>oldname</VAR>, under the new name <VAR>newname</VAR>.
<br><br> This function returns a value of <CODE>0</CODE> if it is successful and
<CODE>-1</CODE> on failure. In addition to the usual file name errors
for both <VAR>oldname</VAR> and <VAR>newname</VAR>, the
following <CODE>errno</CODE> error conditions are defined for this function:
<br><br> <DL>
<DT><CODE>EACCES</CODE>
<DD>
You are not allowed to write to the directory in which the new link is
to be written.
<br><br> <LI> EEXIST
There is already a file named <VAR>newname</VAR>. If you want to replace
this link with a new link, you must remove the old link explicitly first.
<br><br> <LI> EMLINK
There are already too many links to the file named by <VAR>oldname</VAR>.
(The maximum number of links to a file is <CODE>LINK_MAX</CODE>; see
Limits for Files.)
<br><br> <LI> ENOENT
The file named by <VAR>oldname</VAR> doesn't exist. You can't make a link to
a file that doesn't exist.
<br><br> <LI> ENOSPC
The directory or file system that would contain the new link is full
and cannot be extended.
<br><br> <LI> EPERM
In the GNU system and some others, you cannot make links to directories.
Many systems allow only privileged users to do so. This error
is used to report the problem.
<br><br> <LI> EROFS
The directory containing the new link can't be modified because it's on
a read-only file system.
<br><br> <LI> EXDEV
The directory specified in <VAR>newname</VAR> is on a different file system
than the existing file.
<br><br> <LI> EIO
A hardware error occurred while trying to read or write the to filesystem.
sq~wtunistd.hxq~t(const char *oldname, const char *newnametintt
lio_listiosq~
tm
The <CODE>lio_listio</CODE> function can be used to enqueue an arbitrary
number of read and write requests at one time. The requests can all be
meant for the same file, all for different files or every solution in
between.
<br><br> <CODE>lio_listio</CODE> gets the <VAR>nent</VAR> requests from the array pointed to
by <VAR>list</VAR>. The operation to be performed is determined by the
<CODE>aio_lio_opcode</CODE> member in each element of <VAR>list</VAR>. If this
field is <CODE>LIO_READ</CODE> a read operation is enqueued, similar to a call
of <CODE>aio_read</CODE> for this element of the array (except that the way
the termination is signalled is different, as we will see below). If
the <CODE>aio_lio_opcode</CODE> member is <CODE>LIO_WRITE</CODE> a write operation
is enqueued. Otherwise the <CODE>aio_lio_opcode</CODE> must be <CODE>LIO_NOP</CODE>
in which case this element of <VAR>list</VAR> is simply ignored. This
``operation'' is useful in situations where one has a fixed array of
<CODE>struct aiocb</CODE> elements from which only a few need to be handled at
a time. Another situation is where the <CODE>lio_listio</CODE> call was
canceled before all requests are processed and the remaining requests have to be reissued.
<br><br> The other members of each element of the array pointed to by
<CODE>list</CODE> must have values suitable for the operation as described in
the documentation for <CODE>aio_read</CODE> and <CODE>aio_write</CODE> above.
<br><br> The <VAR>mode</VAR> argument determines how <CODE>lio_listio</CODE> behaves after
having enqueued all the requests. If <VAR>mode</VAR> is <CODE>LIO_WAIT</CODE> it
waits until all requests terminated. Otherwise <VAR>mode</VAR> must be
<CODE>LIO_NOWAIT</CODE> and in this case the function returns immediately after
having enqueued all the requests. In this case the caller gets a
notification of the termination of all requests according to the
<VAR>sig</VAR> parameter. If <VAR>sig</VAR> is <CODE>NULL</CODE> no notification is
send. Otherwise a signal is sent or a thread is started, just as
described in the description for <CODE>aio_read</CODE> or <CODE>aio_write</CODE>.
<br><br> If <VAR>mode</VAR> is <CODE>LIO_WAIT</CODE>, the return value of <CODE>lio_listio</CODE>
is 0 when all requests completed successfully. Otherwise the
function return -1 and <CODE>errno</CODE> is set accordingly. To find
out which request or requests failed one has to use the <CODE>aio_error</CODE>
function on all the elements of the array <VAR>list</VAR>.
<br><br> In case <VAR>mode</VAR> is <CODE>LIO_NOWAIT</CODE>, the function returns 0 if
all requests were enqueued correctly. The current state of the requests
can be found using <CODE>aio_error</CODE> and <CODE>aio_return</CODE> as described
above. If <CODE>lio_listio</CODE> returns -1 in this mode, the
global variable <CODE>errno</CODE> is set accordingly. If a request did not
yet terminate, a call to <CODE>aio_error</CODE> returns <CODE>EINPROGRESS</CODE>. If
the value is different, the request is finished and the error value (or
0) is returned and the result of the operation can be retrieved
using <CODE>aio_return</CODE>.
<br><br> Possible values for <CODE>errno</CODE> are:
<br><br> <DL>
<DT><CODE>EAGAIN</CODE>
<DD>
The resources necessary to queue all the requests are not available at
the moment. The error status for each element of <VAR>list</VAR> must be
checked to determine which request failed.
<br><br> Another reason could be that the system wide limit of AIO requests is
exceeded. This cannot be the case for the implementation on GNU systems
since no arbitrary limits exist.
<LI> EINVAL
The <VAR>mode</VAR> parameter is invalid or <VAR>nent</VAR> is larger than
<CODE>AIO_LISTIO_MAX</CODE>.
<LI> EIO
One or more of the request's I/O operations failed. The error status of
each request should be checked to determine which one failed.
<LI> ENOSYS
The <CODE>lio_listio</CODE> function is not supported.
<br><br> If the <VAR>mode</VAR> parameter is <CODE>LIO_NOWAIT</CODE> and the caller cancels
a request, the error status for this request returned by
<CODE>aio_error</CODE> is <CODE>ECANCELED</CODE>.
<br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE>, this
function is in fact <CODE>lio_listio64</CODE> since the LFS interface
transparently replaces the normal implementation.
sq~wtaio.hxq~$tDint mode, struct aiocb *const list[], int nent, struct sigevent *sigtintt lio_listio64sq~
tê
This function is similar to the <CODE>lio_listio</CODE> function. The only
difference is that on 32 bit machines, the file descriptor should
be opened in the large file mode. Internally, <CODE>lio_listio64</CODE> uses
functionality equivalent to <CODE>lseek64</CODE> to position the file descriptor correctly for the reading or
writing, as opposed to <CODE>lseek</CODE> functionality used in
<CODE>lio_listio</CODE>.
<br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE>, this
function is available under the name <CODE>lio_listio</CODE> and so
transparently replaces the interface for small files on 32 bit
machines.
sq~wtaio.hxq~+tBint mode, struct aiocb *const list, int nent, struct sigevent *sigtinttlistensq~
té
The <CODE>listen</CODE> function enables the socket <VAR>socket</VAR> to accept
connections, thus making it a server socket.
<br><br> The argument <VAR>n</VAR> specifies the length of the queue for pending
connections. When the queue fills, new clients attempting to connect
fail with <CODE>ECONNREFUSED</CODE> until the server calls <CODE>accept</CODE> to
accept a connection from the queue.
<br><br> The <CODE>listen</CODE> function returns <CODE>0</CODE> on success and <CODE>-1</CODE>
on failure. The following <CODE>errno</CODE> error conditions are defined
for this function:
<br><br> <DL>
<DT><CODE>EBADF</CODE>
<DD>
The argument <VAR>socket</VAR> is not a valid file descriptor.
<br><br> <LI> ENOTSOCK
The argument <VAR>socket</VAR> is not a socket.
<br><br> <LI> EOPNOTSUPP
The socket <VAR>socket</VAR> does not support this operation.
sq~wt sys/socket.hxq~2tint socket, int ntinttllabssq~
t
These functions return the absolute value of <VAR>number</VAR>.
<br><br> Most computers use a two's complement integer representation, in which
the absolute value of <CODE>INT_MIN</CODE> (the smallest possible <CODE>int</CODE>)
cannot be represented; thus, <CODE>abs (INT_MIN)</CODE> is not defined.
<br><br> <CODE>llabs</CODE> and <CODE>imaxdiv</CODE> are new to ISO C99.
<br><br> See Integers for a description of the <CODE>intmax_t</CODE> type.
<br><br>
sq~wtstdlib.hxq~9tlong long int numbert
long long inttlldivsq~
t3
The <CODE>lldiv</CODE> function is like the <CODE>div</CODE> function, but the
arguments are of type <CODE>long long int</CODE> and the result is returned as
a structure of type <CODE>lldiv_t</CODE>.
<br><br> The <CODE>lldiv</CODE> function was added in ISO C99.
sq~wtstdlib.hxq~@t2long long int numerator, long long int denominatortlldiv_ttllrintsq~
tœ
These functions are just like <CODE>rint</CODE>, but they return a
<CODE>long long int</CODE> instead of a floating-point number.
sq~wtmath.hxq~Gtdouble xt
long long inttllrintfsq~
tœ
These functions are just like <CODE>rint</CODE>, but they return a
<CODE>long long int</CODE> instead of a floating-point number.
sq~wtmath.hxq~Ntfloat xt
long long inttllrintlsq~
tœ
These functions are just like <CODE>rint</CODE>, but they return a
<CODE>long long int</CODE> instead of a floating-point number.
sq~wtmath.hxq~Ut
long double xt
long long inttllroundsq~
t�
These functions are just like <CODE>round</CODE>, but they return a
<CODE>long long int</CODE> instead of a floating-point number.
sq~wtmath.hxq~\tdouble xt
long long inttllroundfsq~
t�
These functions are just like <CODE>round</CODE>, but they return a
<CODE>long long int</CODE> instead of a floating-point number.
sq~wtmath.hxq~ctfloat xt
long long inttllroundlsq~
t�
These functions are just like <CODE>round</CODE>, but they return a
<CODE>long long int</CODE> instead of a floating-point number.
sq~wtmath.hxq~jt
long double xt
long long intt
localeconvsq~
tø
The <CODE>localeconv</CODE> function returns a pointer to a structure whose
components contain information about how numeric and monetary values
should be formatted in the current locale.
<br><br> You should not modify the structure or its contents. The structure might
be overwritten by subsequent calls to <CODE>localeconv</CODE>, or by calls to
<CODE>setlocale</CODE>, but no other function in the library overwrites this
value.
sq~wtlocale.hxq~qtvoidtstruct lconv *t localtimesq~
t…
The <CODE>localtime</CODE> function converts the simple time pointed to by
<VAR>time</VAR> to broken-down time representation, expressed relative to the
user's specified time zone.
<br><br> The return value is a pointer to a static broken-down time structure, which
might be overwritten by subsequent calls to <CODE>ctime</CODE>, <CODE>gmtime</CODE>,
or <CODE>localtime</CODE>. (But no other library function overwrites the contents
of this object.)
<br><br> The return value is the null pointer if <VAR>time</VAR> cannot be represented
as a broken-down time; typically this is because the year cannot fit into
an <CODE>int</CODE>.
<br><br> Calling <CODE>localtime</CODE> has one other effect: it sets the variable
<CODE>tzname</CODE> with information about the current time zone. .
sq~wttime.hxq~xtconst time_t *timet struct tm *t localtime_rsq~
t]
The <CODE>localtime_r</CODE> function works just like the <CODE>localtime</CODE>
function. It takes a pointer to a variable containing a simple time
and converts it to the broken-down time format.
<br><br> But the result is not placed in a static buffer. Instead it is placed
in the object of type <CODE>struct tm</CODE> to which the parameter
<VAR>resultp</VAR> points.
<br><br> If the conversion is successful the function returns a pointer to the
object the result was written into, i.e., it returns <VAR>resultp</VAR>.
sq~wttime.hxq~t&const time_t *time, struct tm *resultpt struct tm *tlogsq~
t­
These functions compute the natural logarithm of <VAR>x</VAR>. <CODE>exp (log
(<VAR>x</VAR>))</CODE> equals <VAR>x</VAR>, exactly in mathematics and approximately in
C.
<br><br> If <VAR>x</VAR> is negative, <CODE>log</CODE> signals a domain error. If <VAR>x</VAR>
is zero, it returns negative infinity; if <VAR>x</VAR> is too close to zero,
it may signal overflow.
sq~wtmath.hxq~†tdouble xtdoubletlog10sq~
t¿
These functions return the base-10 logarithm of <VAR>x</VAR>.
<CODE>log10 (<VAR>x</VAR>)</CODE> equals <CODE>log (<VAR>x</VAR>) / log (10)</CODE>.
<br><br>
sq~wtmath.hxq~�tdouble xtdoubletlog10fsq~
t¿
These functions return the base-10 logarithm of <VAR>x</VAR>.
<CODE>log10 (<VAR>x</VAR>)</CODE> equals <CODE>log (<VAR>x</VAR>) / log (10)</CODE>.
<br><br>
sq~wtmath.hxq~”tfloat xtfloattlog10lsq~
t¿
These functions return the base-10 logarithm of <VAR>x</VAR>.
<CODE>log10 (<VAR>x</VAR>)</CODE> equals <CODE>log (<VAR>x</VAR>) / log (10)</CODE>.
<br><br>
sq~wtmath.hxq~›t
long double xt long doubletlog1psq~
tÅ
These functions returns a value equivalent to <CODE>log (1 + <VAR>x</VAR>)</CODE>.
They are computed in a way that is accurate even if <VAR>x</VAR> is
near zero.
sq~wtmath.hxq~¢tdouble xtdoubletlog1pfsq~
tÅ
These functions returns a value equivalent to <CODE>log (1 + <VAR>x</VAR>)</CODE>.
They are computed in a way that is accurate even if <VAR>x</VAR> is
near zero.
sq~wtmath.hxq~©tfloat xtfloattlog1plsq~
tÅ
These functions returns a value equivalent to <CODE>log (1 + <VAR>x</VAR>)</CODE>.
They are computed in a way that is accurate even if <VAR>x</VAR> is
near zero.
sq~wtmath.hxq~°t
long double xt long doubletlog2sq~
tª
These functions return the base-2 logarithm of <VAR>x</VAR>.
<CODE>log2 (<VAR>x</VAR>)</CODE> equals <CODE>log (<VAR>x</VAR>) / log (2)</CODE>.
sq~wtmath.hxq~·tdouble xtdoubletlog2fsq~
tª
These functions return the base-2 logarithm of <VAR>x</VAR>.
<CODE>log2 (<VAR>x</VAR>)</CODE> equals <CODE>log (<VAR>x</VAR>) / log (2)</CODE>.
sq~wtmath.hxq~¾tfloat xtfloattlog2lsq~
tª
These functions return the base-2 logarithm of <VAR>x</VAR>.
<CODE>log2 (<VAR>x</VAR>)</CODE> equals <CODE>log (<VAR>x</VAR>) / log (2)</CODE>.
sq~wtmath.hxq~Åt
long double xt long doubletlogbsq~
tS
These functions extract the exponent of <VAR>x</VAR> and return it as a
floating-point value. If <CODE>FLT_RADIX</CODE> is two, <CODE>logb</CODE> is equal
to <CODE>floor (log2 (x))</CODE>, except it's probably faster.
<br><br> If <VAR>x</VAR> is de-normalized, <CODE>logb</CODE> returns the exponent <VAR>x</VAR>
would have if it were normalized. If <VAR>x</VAR> is infinity (positive or
negative), <CODE>logb</CODE> returns infinity{}. If <VAR>x</VAR> is zero,
<CODE>logb</CODE> returns infinity{}. It does not signal.
sq~wtmath.hxq~Ìtdouble xtdoubletlogbfsq~
tS
These functions extract the exponent of <VAR>x</VAR> and return it as a
floating-point value. If <CODE>FLT_RADIX</CODE> is two, <CODE>logb</CODE> is equal
to <CODE>floor (log2 (x))</CODE>, except it's probably faster.
<br><br> If <VAR>x</VAR> is de-normalized, <CODE>logb</CODE> returns the exponent <VAR>x</VAR>
would have if it were normalized. If <VAR>x</VAR> is infinity (positive or
negative), <CODE>logb</CODE> returns infinity{}. If <VAR>x</VAR> is zero,
<CODE>logb</CODE> returns infinity{}. It does not signal.
sq~wtmath.hxq~Ótfloat xtfloattlogblsq~
tS
These functions extract the exponent of <VAR>x</VAR> and return it as a
floating-point value. If <CODE>FLT_RADIX</CODE> is two, <CODE>logb</CODE> is equal
to <CODE>floor (log2 (x))</CODE>, except it's probably faster.
<br><br> If <VAR>x</VAR> is de-normalized, <CODE>logb</CODE> returns the exponent <VAR>x</VAR>
would have if it were normalized. If <VAR>x</VAR> is infinity (positive or
negative), <CODE>logb</CODE> returns infinity{}. If <VAR>x</VAR> is zero,
<CODE>logb</CODE> returns infinity{}. It does not signal.
sq~wtmath.hxq~Út
long double xt long doubletlogfsq~
t­
These functions compute the natural logarithm of <VAR>x</VAR>. <CODE>exp (log
(<VAR>x</VAR>))</CODE> equals <VAR>x</VAR>, exactly in mathematics and approximately in
C.
<br><br> If <VAR>x</VAR> is negative, <CODE>log</CODE> signals a domain error. If <VAR>x</VAR>
is zero, it returns negative infinity; if <VAR>x</VAR> is too close to zero,
it may signal overflow.
sq~wtmath.hxq~átfloat xtfloattloginsq~
tõ
The <CODE>login</CODE> functions inserts an entry into the user accounting
database. The <CODE>ut_line</CODE> member is set to the name of the terminal
on standard input. If standard input is not a terminal <CODE>login</CODE>
uses standard output or standard error output to determine the name of
the terminal. If <CODE>struct utmp</CODE> has a <CODE>ut_type</CODE> member,
<CODE>login</CODE> sets it to <CODE>USER_PROCESS</CODE>, and if there is an
<CODE>ut_pid</CODE> member, it will be set to the process ID of the current
process. The remaining entries are copied from <VAR>entry</VAR>.
<br><br> A copy of the entry is written to the user accounting log file.
sq~wtutmp.hxq~ètconst struct utmp *entrytvoidt login_ttysq~
th
This function makes <VAR>filedes</VAR> the controlling terminal of the
current process, redirects standard input, standard output and
standard error output to this terminal, and closes <VAR>filedes</VAR>.
<br><br> This function returns <CODE>0</CODE> on successful completion, and <CODE>-1</CODE>
on error.
sq~wtutmp.hxq~ït int filedestinttloglsq~
t­
These functions compute the natural logarithm of <VAR>x</VAR>. <CODE>exp (log
(<VAR>x</VAR>))</CODE> equals <VAR>x</VAR>, exactly in mathematics and approximately in
C.
<br><br> If <VAR>x</VAR> is negative, <CODE>log</CODE> signals a domain error. If <VAR>x</VAR>
is zero, it returns negative infinity; if <VAR>x</VAR> is too close to zero,
it may signal overflow.
sq~wtmath.hxq~öt
long double xt long doubletlogoutsq~
t4
This function modifies the user accounting database to indicate that the
user on <VAR>ut_line</VAR> has logged out.
<br><br> The <CODE>logout</CODE> function returns <CODE>1</CODE> if the entry was successfully
written to the database, or <CODE>0</CODE> on error.
sq~wtutmp.hxq~ýtconst char *ut_linetinttlogwtmpsq~
tù
The <CODE>logwtmp</CODE> function appends an entry to the user accounting log
file, for the current time and the information provided in the
<VAR>ut_line</VAR>, <VAR>ut_name</VAR> and <VAR>ut_host</VAR> arguments.
sq~wtutmp.hxq~t=const char *ut_line, const char *ut_name, const char *ut_hosttvoidtlongjmpsq~
t
This function restores current execution to the state saved in
<VAR>state</VAR>, and continues execution from the call to <CODE>setjmp</CODE> that
established that return point. Returning from <CODE>setjmp</CODE> by means of
<CODE>longjmp</CODE> returns the <VAR>value</VAR> argument that was passed to
<CODE>longjmp</CODE>, rather than <CODE>0</CODE>. (But if <VAR>value</VAR> is given as
<CODE>0</CODE>, <CODE>setjmp</CODE> returns <CODE>1</CODE>).
sq~wtsetjmp.hxq~ tjmp_buf state, int valuetvoidtlrand48sq~
t…
The <CODE>lrand48</CODE> function returns an integer value in the range of
<CODE>0</CODE> to <CODE>2^31</CODE> (exclusive). Even if the size of the <CODE>long
int</CODE> type can take more than 32 bits, no higher numbers are returned.
The random bits are determined by the global state of the random number
generator in the C library.
sq~wtstdlib.hxq~tvoidtlong intt lrand48_rsq~
tð
This function is similar to <CODE>lrand48</CODE>, but in addition it takes a
pointer to a buffer describing the state of the random number generator
just like <CODE>drand48</CODE>.
<br><br> If the return value of the function is non-negative the variable pointed
to by <VAR>result</VAR> contains the result. Otherwise an error occurred.
<br><br> This function is a GNU extension and should not be used in portable
programs.
sq~wtstdlib.hxq~t+struct drand48_data *buffer, double *resulttinttlrintsq~
t—
These functions are just like <CODE>rint</CODE>, but they return a
<CODE>long int</CODE> instead of a floating-point number.
sq~wtmath.hxq~ tdouble xtlong inttlrintfsq~
t—
These functions are just like <CODE>rint</CODE>, but they return a
<CODE>long int</CODE> instead of a floating-point number.
sq~wtmath.hxq~'tfloat xtlong inttlrintlsq~
t—
These functions are just like <CODE>rint</CODE>, but they return a
<CODE>long int</CODE> instead of a floating-point number.
sq~wtmath.hxq~.t
long double xtlong inttlroundsq~
t˜
These functions are just like <CODE>round</CODE>, but they return a
<CODE>long int</CODE> instead of a floating-point number.
sq~wtmath.hxq~5tdouble xtlong inttlroundfsq~
t˜
These functions are just like <CODE>round</CODE>, but they return a
<CODE>long int</CODE> instead of a floating-point number.
sq~wtmath.hxq~<tfloat xtlong inttlroundlsq~
t˜
These functions are just like <CODE>round</CODE>, but they return a
<CODE>long int</CODE> instead of a floating-point number.
sq~wtmath.hxq~Ct
long double xtlong inttlsearchsq~
t½
The <CODE>lsearch</CODE> function is similar to the <CODE>lfind</CODE> function. It
searches the given array for an element and returns it if found. The
difference is that if no matching element is found the <CODE>lsearch</CODE>
function adds the object pointed to by <VAR>key</VAR> (with a size of
<VAR>size</VAR> bytes) at the end of the array and it increments the value of
<CODE>*<VAR>nmemb</VAR></CODE> to reflect this addition.
<br><br> This means for the caller that if it is not sure that the array contains
the element one is searching for the memory allocated for the array
starting at <VAR>base</VAR> must have room for at least <VAR>size</VAR> more
bytes. If one is sure the element is in the array it is better to use
<CODE>lfind</CODE> so having more room in the array is always necessary when
calling <CODE>lsearch</CODE>.
sq~wtsearch.hxq~JtOconst void *key, void *base, size_t *nmemb, size_t size, comparison_fn_t compartvoid *tlseeksq~
tM
The <CODE>lseek</CODE> function is used to change the file position of the
file with descriptor <VAR>filedes</VAR>.
<br><br> The <VAR>whence</VAR> argument specifies how the <VAR>offset</VAR> should be
interpreted, in the same way as for the <CODE>fseek</CODE> function, and it must
be one of the symbolic constants <CODE>SEEK_SET</CODE>, <CODE>SEEK_CUR</CODE>, or
<CODE>SEEK_END</CODE>.
<br><br> <DL>
<DT><CODE>SEEK_SET</CODE>
<DD>
Specifies that <VAR>whence</VAR> is a count of characters from the beginning
of the file.
<br><br> <DT><CODE>SEEK_CUR</CODE>
<DD>
Specifies that <VAR>whence</VAR> is a count of characters from the current
file position. This count may be positive or negative.
<br><br> <LI> SEEK_END
Specifies that <VAR>whence</VAR> is a count of characters from the end of
the file. A negative count specifies a position within the current
extent of the file; a positive count specifies a position past the
current end. If you set the position past the current end, and
actually write data, you will extend the file with zeros up to that
position.
<br><br> The return value from <CODE>lseek</CODE> is normally the resulting file
position, measured in bytes from the beginning of the file.
You can use this feature together with <CODE>SEEK_CUR</CODE> to read the
current file position.
<br><br> If you want to append to the file, setting the file position to the
current end of file with <CODE>SEEK_END</CODE> is not sufficient. Another
process may write more data after you seek but before you write,
extending the file so the position you write onto clobbers their data.
Instead, use the <CODE>O_APPEND</CODE> operating mode; .
<br><br> You can set the file position past the current end of the file. This
does not by itself make the file longer; <CODE>lseek</CODE> never changes the
file. But subsequent output at that position will extend the file.
Characters between the previous end of file and the new position are
filled with zeros. Extending the file in this way can create a
``hole'': the blocks of zeros are not actually allocated on disk, so the
file takes up less space than it appears to; it is then called a
``sparse file''.
files
in files
<br><br> If the file position cannot be changed, or the operation is in some way
invalid, <CODE>lseek</CODE> returns a value of -1. The following
<CODE>errno</CODE> error conditions are defined for this function:
<br><br> <DL>
<LI> EBADF
The <VAR>filedes</VAR> is not a valid file descriptor.
<br><br> <LI> EINVAL
The <VAR>whence</VAR> argument value is not valid, or the resulting
file offset is not valid. A file offset is invalid.
<br><br> <LI> ESPIPE
The <VAR>filedes</VAR> corresponds to an object that cannot be positioned,
such as a pipe, FIFO or terminal device. (POSIX.1 specifies this error
only for pipes and FIFOs, but in the GNU system, you always get
<CODE>ESPIPE</CODE> if the object is not seekable.)
<br><br> When the source file is compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> the
<CODE>lseek</CODE> function is in fact <CODE>lseek64</CODE> and the type
<CODE>off_t</CODE> has 64 bits which makes it possible to handle files up to
2^63 bytes in length.
<br><br> This function is a cancellation point in multi-threaded programs. This
is a problem if the thread allocates some resources (like memory, file
descriptors, semaphores or whatever) at the time <CODE>lseek</CODE> is
called. If the thread gets canceled these resources stay allocated
until the program ends. To avoid this calls to <CODE>lseek</CODE> should be
protected using cancellation handlers.
<br><br> The <CODE>lseek</CODE> function is the underlying primitive for the
<CODE>fseek</CODE>, <CODE>fseeko</CODE>, <CODE>ftell</CODE>, <CODE>ftello</CODE> and
<CODE>rewind</CODE> functions, which operate on streams instead of file
descriptors.
sq~wtunistd.hxq~Qt%int filedes, off_t offset, int whencetoff_ttlseek64sq~
t3
This function is similar to the <CODE>lseek</CODE> function. The difference
is that the <VAR>offset</VAR> parameter is of type <CODE>off64_t</CODE> instead of
<CODE>off_t</CODE> which makes it possible on 32 bit machines to address
files larger than 2^31 bytes and up to 2^63 bytes. The
file descriptor <CODE>filedes</CODE> must be opened using <CODE>open64</CODE> since
otherwise the large offsets possible with <CODE>off64_t</CODE> will lead to
errors with a descriptor in small file mode.
<br><br> When the source file is compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> on a
32 bits machine this function is actually available under the name
<CODE>lseek</CODE> and so transparently replaces the 32 bit interface.
sq~wtunistd.hxq~Xt'int filedes, off64_t offset, int whencetoff64_ttlstatsq~
t.
The <CODE>lstat</CODE> function is like <CODE>stat</CODE>, except that it does not
follow symbolic links. If <VAR>filename</VAR> is the name of a symbolic
link, <CODE>lstat</CODE> returns information about the link itself; otherwise
<CODE>lstat</CODE> works like <CODE>stat</CODE>. .
<br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> this
function is in fact <CODE>lstat64</CODE> since the LFS interface transparently
replaces the normal implementation.
sq~wt
sys/stat.hxq~_t&const char *filename, struct stat *buftinttlstat64sq~
t$
This function is similar to <CODE>lstat</CODE> but it is also able to work on
files larger then 2^31 bytes on 32-bit systems. To be able to do
this the result is stored in a variable of type <CODE>struct stat64</CODE> to
which <VAR>buf</VAR> must point.
<br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> this
function is available under the name <CODE>lstat</CODE> and so transparently
replaces the interface for small files on 32-bit machines.
sq~wt
sys/stat.hxq~ft(const char *filename, struct stat64 *buftinttlutimessq~
tØ
This function is like <CODE>utimes</CODE>, except that it does not follow
symbolic links. If <VAR>filename</VAR> is the name of a symbolic link,
<CODE>lutimes</CODE> sets the file access and modification times of the
symbolic link special file itself (as seen by <CODE>lstat</CODE>;
) while <CODE>utimes</CODE> sets the file access and
modification times of the file the symbolic link refers to. This
function comes from FreeBSD, and is not available on all platforms (if
not available, it will fail with <CODE>ENOSYS</CODE>).
<br><br> The return values and error conditions are the same as for the <CODE>utime</CODE>
function.
sq~wt
sys/time.hxq~mt+const char *filename, struct timeval tvp[2]tinttmadvisesq~
t 
<br><br> This function can be used to provide the system with <VAR>advice</VAR> about
the intended usage patterns of the memory region starting at <VAR>addr</VAR>
and extending <VAR>length</VAR> bytes.
<br><br> The valid BSD values for <VAR>advice</VAR> are:
<br><br> <DL>
<br><br> <DT><CODE>MADV_NORMAL</CODE>
<DD>
The region should receive no further special treatment.
<br><br> <DT><CODE>MADV_RANDOM</CODE>
<DD>
The region will be accessed via random page references. The kernel
should page-in the minimal number of pages for each page fault.
<br><br> <DT><CODE>MADV_SEQUENTIAL</CODE>
<DD>
The region will be accessed via sequential page references. This
may cause the kernel to aggressively read-ahead, expecting further
sequential references after any page fault within this region.
<br><br> <LI> MADV_WILLNEED
The region will be needed. The pages within this region may
be pre-faulted in by the kernel.
<br><br> <LI> MADV_DONTNEED
The region is no longer needed. The kernel may free these pages,
causing any changes to the pages to be lost, as well as swapped
out pages to be discarded.
<br><br>
<br><br> The POSIX names are slightly different, but with the same meanings:
<br><br> <DL>
<br><br> <LI> POSIX_MADV_NORMAL
This corresponds with BSD's <CODE>MADV_NORMAL</CODE>.
<br><br> <LI> POSIX_MADV_RANDOM
This corresponds with BSD's <CODE>MADV_RANDOM</CODE>.
<br><br> <LI> POSIX_MADV_SEQUENTIAL
This corresponds with BSD's <CODE>MADV_SEQUENTIAL</CODE>.
<br><br> <LI> POSIX_MADV_WILLNEED
This corresponds with BSD's <CODE>MADV_WILLNEED</CODE>.
<br><br> <LI> POSIX_MADV_DONTNEED
This corresponds with BSD's <CODE>MADV_DONTNEED</CODE>.
<br><br>
<br><br> <CODE>msync</CODE> returns 0 for success and -1 for
error. Errors include:
<DL>
<br><br> <LI> EINVAL
An invalid region was given, or the <VAR>advice</VAR> was invalid.
<br><br> <LI> EFAULT
There is no existing mapping in at least part of the given region.
<br><br>
sq~wt
sys/mman.hxq~tt%void *addr, size_t length, int advicetintt makecontextsq~
t¾
<br><br> The <VAR>ucp</VAR> parameter passed to the <CODE>makecontext</CODE> shall be
initialized by a call to <CODE>getcontext</CODE>. The context will be
modified to in a way so that if the context is resumed it will start by
calling the function <CODE>func</CODE> which gets <VAR>argc</VAR> integer arguments
passed. The integer arguments which are to be passed should follow the
<VAR>argc</VAR> parameter in the call to <CODE>makecontext</CODE>.
<br><br> Before the call to this function the <CODE>uc_stack</CODE> and <CODE>uc_link</CODE>
element of the <VAR>ucp</VAR> structure should be initialized. The
<CODE>uc_stack</CODE> element describes the stack which is used for this
context. No two contexts which are used at the same time should use the
same memory region for a stack.
<br><br> The <CODE>uc_link</CODE> element of the object pointed to by <VAR>ucp</VAR> should
be a pointer to the context to be executed when the function <VAR>func</VAR>
returns or it should be a null pointer. See <CODE>setcontext</CODE> for more
information about the exact use.
sq~wt
ucontext.hxq~{t3ucontext_t *ucp, void (*func) (void), int argc, ...tvoidtmallinfosq~
t˜
This function returns information about the current dynamic memory usage
in a structure of type <CODE>struct mallinfo</CODE>.
sq~wtmalloc.hxq~‚tvoidtstruct mallinfotmallocsq~
t¨
This function returns a pointer to a newly allocated block <VAR>size</VAR>
bytes long, or a null pointer if the block could not be allocated.
sq~wtstdlib.hxq~‰t size_t sizetvoid *tmalloptsq~
tW
When calling <CODE>mallopt</CODE>, the <VAR>param</VAR> argument specifies the
parameter to be set, and <VAR>value</VAR> the new value to be set. Possible
choices for <VAR>param</VAR>, as defined in <TT>malloc.h</TT>, are:
<br><br> <DL>
<DT><CODE>M_TRIM_THRESHOLD</CODE>
<DD>
This is the minimum size (in bytes) of the top-most, releasable chunk
that will cause <CODE>sbrk</CODE> to be called with a negative argument in
order to return memory to the system.
<LI> M_TOP_PAD
This parameter determines the amount of extra memory to obtain from the
system when a call to <CODE>sbrk</CODE> is required. It also specifies the
number of bytes to retain when shrinking the heap by calling <CODE>sbrk</CODE>
with a negative argument. This provides the necessary hysteresis in
heap size such that excessive amounts of system calls can be avoided.
<LI> M_MMAP_THRESHOLD
All chunks larger than this value are allocated outside the normal
heap, using the <CODE>mmap</CODE> system call. This way it is guaranteed
that the memory for these chunks can be returned to the system on
<CODE>free</CODE>. Note that requests smaller than this threshold might still
be allocated via <CODE>mmap</CODE>.
<LI> M_MMAP_MAX
The maximum number of chunks to allocate with <CODE>mmap</CODE>. Setting this
to zero disables all use of <CODE>mmap</CODE>.
<LI> M_PERTURB
If non-zero, memory blocks are filled with values depending on some
low order bits of this parameter when they are allocated (except when
allocated by <CODE>calloc</CODE>) and freed. This can be used to debug the
use of uninitialized or freed heap memory.
<br><br>
sq~wxq~�tint param, int valuetinttmblensq~
tû
The <CODE>mblen</CODE> function with a non-null <VAR>string</VAR> argument returns
the number of bytes that make up the multibyte character beginning at
<VAR>string</VAR>, never examining more than <VAR>size</VAR> bytes. (The idea is
to supply for <VAR>size</VAR> the number of bytes of data you have in hand.)
<br><br> The return value of <CODE>mblen</CODE> distinguishes three possibilities: the
first <VAR>size</VAR> bytes at <VAR>string</VAR> start with valid multibyte
characters, they start with an invalid byte sequence or just part of a
character, or <VAR>string</VAR> points to an empty string (a null character).
<br><br> For a valid multibyte character, <CODE>mblen</CODE> returns the number of
bytes in that character (always at least <CODE>1</CODE> and never more than
<VAR>size</VAR>). For an invalid byte sequence, <CODE>mblen</CODE> returns
-1. For an empty string, it returns 0.
<br><br> If the multibyte character code uses shift characters, then <CODE>mblen</CODE>
maintains and updates a shift state as it scans. If you call
<CODE>mblen</CODE> with a null pointer for <VAR>string</VAR>, that initializes the
shift state to its standard initial value. It also returns a nonzero
value if the multibyte character code in use actually has a shift state.
.
<br><br> The function <CODE>mblen</CODE> is declared in <TT>stdlib.h</TT>.
sq~wtstdlib.hxq~–tconst char *string, size_t sizetinttmbrlensq~
t¥
The <CODE>mbrlen</CODE> function (``multibyte restartable length'') computes
the number of at most <VAR>n</VAR> bytes starting at <VAR>s</VAR>, which form the
next valid and complete multibyte character.
<br><br> If the next multibyte character corresponds to the NUL wide character,
the return value is 0. If the next <VAR>n</VAR> bytes form a valid
multibyte character, the number of bytes belonging to this multibyte
character byte sequence is returned.
<br><br> If the first <VAR>n</VAR> bytes possibly form a valid multibyte
character but the character is incomplete, the return value is
<CODE>(size_t) -2</CODE>. Otherwise the multibyte character sequence is invalid
and the return value is <CODE>(size_t) -1</CODE>.
<br><br> The multibyte sequence is interpreted in the state represented by the
object pointed to by <VAR>ps</VAR>. If <VAR>ps</VAR> is a null pointer, a state
object local to <CODE>mbrlen</CODE> is used.
<br><br> <CODE>mbrlen</CODE> was introduced in Amendment 1 to ISO C90 and
is declared in <TT>wchar.h</TT>.
sq~wtwchar.hxq~�t/const char *restrict s, size_t n, mbstate_t *pstsize_ttmbrtowcsq~
t ‰
The <CODE>mbrtowc</CODE> function (``multibyte restartable to wide
character'') converts the next multibyte character in the string pointed
to by <VAR>s</VAR> into a wide character and stores it in the wide character
string pointed to by <VAR>pwc</VAR>. The conversion is performed according
to the locale currently selected for the <CODE>LC_CTYPE</CODE> category. If
the conversion for the character set used in the locale requires a state,
the multibyte string is interpreted in the state represented by the
object pointed to by <VAR>ps</VAR>. If <VAR>ps</VAR> is a null pointer, a static,
internal state variable used only by the <CODE>mbrtowc</CODE> function is
used.
<br><br> If the next multibyte character corresponds to the NUL wide character,
the return value of the function is 0 and the state object is
afterwards in the initial state. If the next <VAR>n</VAR> or fewer bytes
form a correct multibyte character, the return value is the number of
bytes starting from <VAR>s</VAR> that form the multibyte character. The
conversion state is updated according to the bytes consumed in the
conversion. In both cases the wide character (either the <CODE>L'\0'</CODE>
or the one found in the conversion) is stored in the string pointed to
by <VAR>pwc</VAR> if <VAR>pwc</VAR> is not null.
<br><br> If the first <VAR>n</VAR> bytes of the multibyte string possibly form a valid
multibyte character but there are more than <VAR>n</VAR> bytes needed to
complete it, the return value of the function is <CODE>(size_t) -2</CODE> and
no value is stored. Please note that this can happen even if <VAR>n</VAR>
has a value greater than or equal to <CODE>MB_CUR_MAX</CODE> since the input
might contain redundant shift sequences.
<br><br> If the first <CODE>n</CODE> bytes of the multibyte string cannot possibly form
a valid multibyte character, no value is stored, the global variable
<CODE>errno</CODE> is set to the value <CODE>EILSEQ</CODE>, and the function returns
<CODE>(size_t) -1</CODE>. The conversion state is afterwards undefined.
<br><br> <CODE>mbrtowc</CODE> was introduced in Amendment 1 to ISO C90 and
is declared in <TT>wchar.h</TT>.
sq~wtwchar.hxq~¤tOwchar_t *restrict pwc, const char *restrict s, size_t n, mbstate_t *restrict pstsize_ttmbsinitsq~
t£
The <CODE>mbsinit</CODE> function determines whether the state object pointed
to by <VAR>ps</VAR> is in the initial state. If <VAR>ps</VAR> is a null pointer or
the object is in the initial state the return value is nonzero. Otherwise
it is zero.
<br><br> <CODE>mbsinit</CODE> was introduced in Amendment 1 to ISO C90 and is
declared in <TT>wchar.h</TT>.
sq~wtstddef.htwchar.htlimits.htstdlib.hxq~«tconst mbstate_t *pstintt
mbsnrtowcssq~
t¼
The <CODE>mbsnrtowcs</CODE> function is very similar to the <CODE>mbsrtowcs</CODE>
function. All the parameters are the same except for <VAR>nmc</VAR>, which is
new. The return value is the same as for <CODE>mbsrtowcs</CODE>.
<br><br> This new parameter specifies how many bytes at most can be used from the
multibyte character string. In other words, the multibyte character
string <CODE>*<VAR>src</VAR></CODE> need not be NUL-terminated. But if a NUL byte
is found within the <VAR>nmc</VAR> first bytes of the string, the conversion
stops here.
<br><br> This function is a GNU extension. It is meant to work around the
problems mentioned above. Now it is possible to convert a buffer with
multibyte character text piece for piece without having to care about
inserting NUL bytes and the effect of NUL bytes on the conversion state.
sq~wtwchar.hxq~µt`wchar_t *restrict dst, const char **restrict src, size_t nmc, size_t len, mbstate_t *restrict pstsize_tt mbsrtowcssq~
t,
The <CODE>mbsrtowcs</CODE> function (``multibyte string restartable to wide
character string'') converts an NUL-terminated multibyte character
string at <CODE>*<VAR>src</VAR></CODE> into an equivalent wide character string,
including the NUL wide character at the end. The conversion is started
using the state information from the object pointed to by <VAR>ps</VAR> or
from an internal object of <CODE>mbsrtowcs</CODE> if <VAR>ps</VAR> is a null
pointer. Before returning, the state object is updated to match the state
after the last converted character. The state is the initial state if the
terminating NUL byte is reached and converted.
<br><br> If <VAR>dst</VAR> is not a null pointer, the result is stored in the array
pointed to by <VAR>dst</VAR>; otherwise, the conversion result is not
available since it is stored in an internal buffer.
<br><br> If <VAR>len</VAR> wide characters are stored in the array <VAR>dst</VAR> before
reaching the end of the input string, the conversion stops and <VAR>len</VAR>
is returned. If <VAR>dst</VAR> is a null pointer, <VAR>len</VAR> is never checked.
<br><br> Another reason for a premature return from the function call is if the
input string contains an invalid multibyte sequence. In this case the
global variable <CODE>errno</CODE> is set to <CODE>EILSEQ</CODE> and the function
returns <CODE>(size_t) -1</CODE>.
<br><br> <br><br> In all other cases the function returns the number of wide characters
converted during this call. If <VAR>dst</VAR> is not null, <CODE>mbsrtowcs</CODE>
stores in the pointer pointed to by <VAR>src</VAR> either a null pointer (if
the NUL byte in the input string was reached) or the address of the byte
following the last converted multibyte character.
<br><br> <CODE>mbsrtowcs</CODE> was introduced in Amendment 1 to ISO C90 and is
declared in <TT>wchar.h</TT>.
sq~wtwchar.hxq~¼tTwchar_t *restrict dst, const char **restrict src, size_t len, mbstate_t *restrict pstsize_ttmbstowcssq~
tµ
The <CODE>mbstowcs</CODE> (``multibyte string to wide character string'')
function converts the null-terminated string of multibyte characters
<VAR>string</VAR> to an array of wide character codes, storing not more than
<VAR>size</VAR> wide characters into the array beginning at <VAR>wstring</VAR>.
The terminating null character counts towards the size, so if <VAR>size</VAR>
is less than the actual number of wide characters resulting from
<VAR>string</VAR>, no terminating null character is stored.
<br><br> The conversion of characters from <VAR>string</VAR> begins in the initial
shift state.
<br><br> If an invalid multibyte character sequence is found, the <CODE>mbstowcs</CODE>
function returns a value of -1. Otherwise, it returns the number
of wide characters stored in the array <VAR>wstring</VAR>. This number does
not include the terminating null character, which is present if the
number is less than <VAR>size</VAR>.
<br><br> Here is an example showing how to convert a string of multibyte
characters, allocating enough space for the result.
<br><br> <pre><br>
wchar_t *<br>
mbstowcs_alloc (const char *string)<br>
{<br>
size_t size = strlen (string) + 1;<br>
wchar_t *buf = xmalloc (size * sizeof (wchar_t));<br>
<br><br> size = mbstowcs (buf, string, size);<br>
if (size == (size_t) -1)<br>
return NULL;<br>
buf = xrealloc (buf, (size + 1) * sizeof (wchar_t));<br>
return buf;<br>
}<br>
</pre>
<br><br>
sq~wtstdlib.hxq~Ãt1wchar_t *wstring, const char *string, size_t sizetsize_ttmbtowcsq~
t
The <CODE>mbtowc</CODE> (``multibyte to wide character'') function when called
with non-null <VAR>string</VAR> converts the first multibyte character
beginning at <VAR>string</VAR> to its corresponding wide character code. It
stores the result in <CODE>*<VAR>result</VAR></CODE>.
<br><br> <CODE>mbtowc</CODE> never examines more than <VAR>size</VAR> bytes. (The idea is
to supply for <VAR>size</VAR> the number of bytes of data you have in hand.)
<br><br> <CODE>mbtowc</CODE> with non-null <VAR>string</VAR> distinguishes three
possibilities: the first <VAR>size</VAR> bytes at <VAR>string</VAR> start with
valid multibyte characters, they start with an invalid byte sequence or
just part of a character, or <VAR>string</VAR> points to an empty string (a
null character).
<br><br> For a valid multibyte character, <CODE>mbtowc</CODE> converts it to a wide
character and stores that in <CODE>*<VAR>result</VAR></CODE>, and returns the
number of bytes in that character (always at least 1 and never
more than <VAR>size</VAR>).
<br><br> For an invalid byte sequence, <CODE>mbtowc</CODE> returns -1. For an
empty string, it returns 0, also storing <CODE>'\0'</CODE> in
<CODE>*<VAR>result</VAR></CODE>.
<br><br> If the multibyte character code uses shift characters, then
<CODE>mbtowc</CODE> maintains and updates a shift state as it scans. If you
call <CODE>mbtowc</CODE> with a null pointer for <VAR>string</VAR>, that
initializes the shift state to its standard initial value. It also
returns nonzero if the multibyte character code in use actually has a
shift state. .
sq~wtstdlib.hxq~ÊtBwchar_t *restrict result, const char *restrict string, size_t sizetinttmchecksq~
tB
Calling <CODE>mcheck</CODE> tells <CODE>malloc</CODE> to perform occasional
consistency checks. These will catch things such as writing
past the end of a block that was allocated with <CODE>malloc</CODE>.
<br><br> The <VAR>abortfn</VAR> argument is the function to call when an inconsistency
is found. If you supply a null pointer, then <CODE>mcheck</CODE> uses a
default function which prints a message and calls <CODE>abort</CODE>
. The function you supply is called with
one argument, which says what sort of inconsistency was detected; its
type is described below.
<br><br> It is too late to begin allocation checking once you have allocated
anything with <CODE>malloc</CODE>. So <CODE>mcheck</CODE> does nothing in that
case. The function returns <CODE>-1</CODE> if you call it too late, and
<CODE>0</CODE> otherwise (when it is successful).
<br><br> The easiest way to arrange to call <CODE>mcheck</CODE> early enough is to use
the option <samp>-lmcheck</samp> when you link your program; then you don't
need to modify your program source at all. Alternatively you might use
a debugger to insert a call to <CODE>mcheck</CODE> whenever the program is
started, for example these gdb commands will automatically call <CODE>mcheck</CODE>
whenever the program starts:
<br><br> <pre><br>
(gdb) break main<br>
Breakpoint 1, main (argc=2, argv=0xbffff964) at whatever.c:10<br>
(gdb) command 1<br>
Type commands for when breakpoint 1 is hit, one per line.<br>
End with a line saying just "end".<br>
>call mcheck(0)<br>
>continue<br>
>end<br>
(gdb) <small>...</small><br>
</pre>
<br><br> This will however only work if no initialization function of any object
involved calls any of the <CODE>malloc</CODE> functions since <CODE>mcheck</CODE>
must be called before the first such function.
<br><br>
sq~wtmcheck.hxq~Ñt+void (*abortfn) (enum mcheck_status status)tinttmemalignsq~
t‹
The <CODE>memalign</CODE> function allocates a block of <VAR>size</VAR> bytes whose
address is a multiple of <VAR>boundary</VAR>. The <VAR>boundary</VAR> must be a
power of two! The function <CODE>memalign</CODE> works by allocating a
somewhat larger block, and then returning an address within the block
that is on the specified boundary.
sq~wtmalloc.hxq~Øtsize_t boundary, size_t sizetvoid *tmemccpysq~
t™
This function copies no more than <VAR>size</VAR> bytes from <VAR>from</VAR> to
<VAR>to</VAR>, stopping if a byte matching <VAR>c</VAR> is found. The return
value is a pointer into <VAR>to</VAR> one byte past where <VAR>c</VAR> was copied,
or a null pointer if no byte matching <VAR>c</VAR> appeared in the first
<VAR>size</VAR> bytes of <VAR>from</VAR>.
sq~wtstring.hxq~ßt@void *restrict to, const void *restrict from, int c, size_t sizetvoid *tmemchrsq~
tJ
This function finds the first occurrence of the byte <VAR>c</VAR> (converted
to an <CODE>unsigned char</CODE>) in the initial <VAR>size</VAR> bytes of the
object beginning at <VAR>block</VAR>. The return value is a pointer to the
located byte, or a null pointer if no match was found.
sq~wtstring.hxq~æt%const void *block, int c, size_t sizetvoid *tmemcmpsq~
t
The function <CODE>memcmp</CODE> compares the <VAR>size</VAR> bytes of memory
beginning at <VAR>a1</VAR> against the <VAR>size</VAR> bytes of memory beginning
at <VAR>a2</VAR>. The value returned has the same sign as the difference
between the first differing pair of bytes (interpreted as <CODE>unsigned
char</CODE> objects, then promoted to <CODE>int</CODE>).
<br><br> If the contents of the two blocks are equal, <CODE>memcmp</CODE> returns
<CODE>0</CODE>.
sq~wtstring.hxq~ít+const void *a1, const void *a2, size_t sizetinttmemcpysq~
t
The <CODE>memcpy</CODE> function copies <VAR>size</VAR> bytes from the object
beginning at <VAR>from</VAR> into the object beginning at <VAR>to</VAR>. The
behavior of this function is undefined if the two arrays <VAR>to</VAR> and
<VAR>from</VAR> overlap; use <CODE>memmove</CODE> instead if overlapping is possible.
<br><br> The value returned by <CODE>memcpy</CODE> is the value of <VAR>to</VAR>.
<br><br> Here is an example of how you might use <CODE>memcpy</CODE> to copy the
contents of an array:
<br><br> <pre><br>
struct foo *oldarray, *newarray;<br>
int arraysize;<br>
<small>...</small><br>
memcpy (new, old, arraysize * sizeof (struct foo));<br>
</pre>
sq~wtstring.hxq~ôt9void *restrict to, const void *restrict from, size_t sizetvoid *tmemfrobsq~
tG
<br><br> <CODE>memfrob</CODE> transforms (frobnicates) each byte of the data structure
at <VAR>mem</VAR>, which is <VAR>length</VAR> bytes long, by bitwise exclusive
oring it with binary 00101010. It does the transformation in place and
its return value is always <VAR>mem</VAR>.
<br><br> Note that <CODE>memfrob</CODE> a second time on the same data structure
returns it to its original state.
<br><br> This is a good function for hiding information from someone who doesn't
want to see it or doesn't want to see it very much. To really prevent
people from retrieving the information, use stronger encryption such as
that described in .
<br><br> Portability Note: This function is unique to the GNU C library.
<br><br>
sq~wtstring.hxq~ûtvoid *mem, size_t lengthtvoid *tmemmemsq~
ta
This is like <CODE>strstr</CODE>, but <VAR>needle</VAR> and <VAR>haystack</VAR> are byte
arrays rather than null-terminated strings. <VAR>needle-len</VAR> is the
length of <VAR>needle</VAR> and <VAR>haystack-len</VAR> is the length of
<VAR>haystack</VAR>.
<br><br> This function is a GNU extension.
sq~wtstring.hxq~tOconst void *haystack, size_t haystack-len,const void *needle, size_t needle-lentvoid *tmemmovesq~
t
<CODE>memmove</CODE> copies the <VAR>size</VAR> bytes at <VAR>from</VAR> into the
<VAR>size</VAR> bytes at <VAR>to</VAR>, even if those two blocks of space
overlap. In the case of overlap, <CODE>memmove</CODE> is careful to copy the
original values of the bytes in the block at <VAR>from</VAR>, including those
bytes which also belong to the block at <VAR>to</VAR>.
<br><br> The value returned by <CODE>memmove</CODE> is the value of <VAR>to</VAR>.
sq~wtstring.hxq~ t'void *to, const void *from, size_t sizetvoid *tmempcpysq~
t
The <CODE>mempcpy</CODE> function is nearly identical to the <CODE>memcpy</CODE>
function. It copies <VAR>size</VAR> bytes from the object beginning at
<CODE>from</CODE> into the object pointed to by <VAR>to</VAR>. But instead of
returning the value of <VAR>to</VAR> it returns a pointer to the byte
following the last written byte in the object beginning at <VAR>to</VAR>.
I.e., the value is <CODE>((void *) ((char *) <VAR>to</VAR> + <VAR>size</VAR>))</CODE>.
<br><br> This function is useful in situations where a number of objects shall be
copied to consecutive memory positions.
<br><br> <pre><br>
void *<br>
combine (void *o1, size_t s1, void *o2, size_t s2)<br>
{<br>
void *result = malloc (s1 + s2);<br>
if (result != NULL)<br>
mempcpy (mempcpy (result, o1, s1), o2, s2);<br>
return result;<br>
}<br>
</pre>
<br><br> This function is a GNU extension.
sq~wtstring.hxq~t9void *restrict to, const void *restrict from, size_t sizetvoid *tmemrchrsq~
t(
The function <CODE>memrchr</CODE> is like <CODE>memchr</CODE>, except that it searches
backwards from the end of the block defined by <VAR>block</VAR> and <VAR>size</VAR>
(instead of forwards from the front).
<br><br> This function is a GNU extension.
sq~wtstring.hxq~t%const void *block, int c, size_t sizetvoid *tmemsetsq~
t
This function copies the value of <VAR>c</VAR> (converted to an
<CODE>unsigned char</CODE>) into each of the first <VAR>size</VAR> bytes of the
object beginning at <VAR>block</VAR>. It returns the value of <VAR>block</VAR>.
sq~wtstring.hxq~tvoid *block, int c, size_t sizetvoid *tmkdirsq~
tE
The <CODE>mkdir</CODE> function creates a new, empty directory with name
<VAR>filename</VAR>.
<br><br> The argument <VAR>mode</VAR> specifies the file permissions for the new
directory file. , for more information about
this.
<br><br> A return value of <CODE>0</CODE> indicates successful completion, and
<CODE>-1</CODE> indicates failure. In addition to the usual file name syntax
errors , the following <CODE>errno</CODE> error
conditions are defined for this function:
<br><br> <DL>
<DT><CODE>EACCES</CODE>
<DD>
Write permission is denied for the parent directory in which the new
directory is to be added.
<br><br> <LI> EEXIST
A file named <VAR>filename</VAR> already exists.
<br><br> <LI> EMLINK
The parent directory has too many links (entries).
<br><br> Well-designed file systems never report this error, because they permit
more links than your disk could possibly hold. However, you must still
take account of the possibility of this error, as it could result from
network access to a file system on another machine.
<br><br> <LI> ENOSPC
The file system doesn't have enough room to create the new directory.
<br><br> <LI> EROFS
The parent directory of the directory being created is on a read-only
file system and cannot be modified.
<br><br> To use this function, your program should include the header file
<TT>sys/stat.h</TT>.
sq~wt
sys/stat.hxq~%t!const char *filename, mode_t modetinttmkdtempsq~
tT
The <CODE>mkdtemp</CODE> function creates a directory with a unique name. If
it succeeds, it overwrites <VAR>template</VAR> with the name of the
directory, and returns <VAR>template</VAR>. As with <CODE>mktemp</CODE> and
<CODE>mkstemp</CODE>, <VAR>template</VAR> should be a string ending with
<samp>XXXXXX</samp>.
<br><br> If <CODE>mkdtemp</CODE> cannot create an uniquely named directory, it returns
<CODE>NULL</CODE> and sets <VAR>errno</VAR> appropriately. If <VAR>template</VAR> does
not end with <samp>XXXXXX</samp>, <CODE>mkdtemp</CODE> returns <CODE>NULL</CODE> and does
not modify <VAR>template</VAR>. <VAR>errno</VAR> will be set to <CODE>EINVAL</CODE> in
this case.
<br><br> The directory is created using mode <CODE>0700</CODE>.
sq~wtstdlib.hxq~,tchar *templatetchar *tmkfifosq~
tI
The <CODE>mkfifo</CODE> function makes a FIFO special file with name
<VAR>filename</VAR>. The <VAR>mode</VAR> argument is used to set the file's
permissions; see Setting Permissions.
<br><br> The normal, successful return value from <CODE>mkfifo</CODE> is <CODE>0</CODE>. In
the case of an error, <CODE>-1</CODE> is returned. In addition to the usual
file name errors , the following
<CODE>errno</CODE> error conditions are defined for this function:
<br><br> <DL>
<DT><CODE>EEXIST</CODE>
<DD>
The named file already exists.
<br><br> <LI> ENOSPC
The directory or file system cannot be extended.
<br><br> <LI> EROFS
The directory that would contain the file resides on a read-only file
system.
sq~wt
sys/stat.hxq~3t!const char *filename, mode_t modetinttmknodsq~
tq
The <CODE>mknod</CODE> function makes a special file with name <VAR>filename</VAR>.
The <VAR>mode</VAR> specifies the mode of the file, and may include the various
special file bits, such as <CODE>S_IFCHR</CODE> (for a character special file)
or <CODE>S_IFBLK</CODE> (for a block special file). .
<br><br> The <VAR>dev</VAR> argument specifies which device the special file refers to.
Its exact interpretation depends on the kind of special file being created.
<br><br> The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on error. In addition
to the usual file name errors , the
following <CODE>errno</CODE> error conditions are defined for this function:
<br><br> <DL>
<DT><CODE>EPERM</CODE>
<DD>
The calling process is not privileged. Only the superuser can create
special files.
<br><br> <LI> ENOSPC
The directory or file system that would contain the new file is full
and cannot be extended.
<br><br> <LI> EROFS
The directory containing the new file can't be modified because it's on
a read-only file system.
<br><br> <LI> EEXIST
There is already a file named <VAR>filename</VAR>. If you want to replace
this file, you must remove the old file explicitly first.
sq~wt
sys/stat.hxq~:t'const char *filename, int mode, int devtinttmkstempsq~
t
The <CODE>mkstemp</CODE> function generates a unique file name just as
<CODE>mktemp</CODE> does, but it also opens the file for you with <CODE>open</CODE>
. If successful, it modifies
<VAR>template</VAR> in place and returns a file descriptor for that file open
for reading and writing. If <CODE>mkstemp</CODE> cannot create a
uniquely-named file, it returns <CODE>-1</CODE>. If <VAR>template</VAR> does not
end with <samp>XXXXXX</samp>, <CODE>mkstemp</CODE> returns <CODE>-1</CODE> and does not
modify <VAR>template</VAR>.
<br><br> The file is opened using mode <CODE>0600</CODE>. If the file is meant to be
used by other users this mode must be changed explicitly.
sq~wtstdlib.hxq~Atchar *templatetinttmktempsq~
t¤
The <CODE>mktemp</CODE> function generates a unique file name by modifying
<VAR>template</VAR> as described above. If successful, it returns
<VAR>template</VAR> as modified. If <CODE>mktemp</CODE> cannot find a unique file
name, it makes <VAR>template</VAR> an empty string and returns that. If
<VAR>template</VAR> does not end with <samp>XXXXXX</samp>, <CODE>mktemp</CODE> returns a
null pointer.
<br><br> Warning: Between the time the pathname is constructed and the
file is created another process might have created a file with the same
name using <CODE>mktemp</CODE>, leading to a possible security hole. The
implementation generates names which can hardly be predicted, but when
opening the file you should use the <CODE>O_EXCL</CODE> flag. Using
<CODE>mkstemp</CODE> is a safe way to avoid this problem.
sq~wtstdio.htstdlib.hxq~Htchar *templatetchar *tmktimesq~
tþ
The <CODE>mktime</CODE> function is used to convert a broken-down time structure
to a simple time representation. It also ``normalizes'' the contents of
the broken-down time structure, by filling in the day of week and day of
year based on the other date and time components.
<br><br> The <CODE>mktime</CODE> function ignores the specified contents of the
<CODE>tm_wday</CODE> and <CODE>tm_yday</CODE> members of the broken-down time
structure. It uses the values of the other components to determine the
calendar time; it's permissible for these components to have
unnormalized values outside their normal ranges. The last thing that
<CODE>mktime</CODE> does is adjust the components of the <VAR>brokentime</VAR>
structure (including the <CODE>tm_wday</CODE> and <CODE>tm_yday</CODE>).
<br><br> If the specified broken-down time cannot be represented as a simple time,
<CODE>mktime</CODE> returns a value of <CODE>(time_t)(-1)</CODE> and does not modify
the contents of <VAR>brokentime</VAR>.
<br><br> Calling <CODE>mktime</CODE> also sets the variable <CODE>tzname</CODE> with
information about the current time zone. .
sq~wttime.hxq~Ptstruct tm *brokentimettime_ttmlocksq~
tË
<br><br> <CODE>mlock</CODE> locks a range of the calling process' virtual pages.
<br><br> The range of memory starts at address <VAR>addr</VAR> and is <VAR>len</VAR> bytes
long. Actually, since you must lock whole pages, it is the range of
pages that include any part of the specified range.
<br><br> When the function returns successfully, each of those pages is backed by
(connected to) a real frame (is resident) and is marked to stay that
way. This means the function may cause page-ins and have to wait for
them.
<br><br> When the function fails, it does not affect the lock status of any
pages.
<br><br> The return value is zero if the function succeeds. Otherwise, it is
<CODE>-1</CODE> and <CODE>errno</CODE> is set accordingly. <CODE>errno</CODE> values
specific to this function are:
<br><br> <DL>
<DT><CODE>ENOMEM</CODE>
<DD>
<OL>
<LI>
At least some of the specified address range does not exist in the
calling process' virtual address space.
<LI>
The locking would cause the process to exceed its locked page limit.
</OL>
<br><br> <LI> EPERM
The calling process is not superuser.
<br><br> <LI> EINVAL
<VAR>len</VAR> is not positive.
<br><br> <LI> ENOSYS
The kernel does not provide <CODE>mlock</CODE> capability.
<br><br>
<br><br> You can lock <EM>all</EM> a process' memory with <CODE>mlockall</CODE>. You
unlock memory with <CODE>munlock</CODE> or <CODE>munlockall</CODE>.
<br><br> To avoid all page faults in a C program, you have to use
<CODE>mlockall</CODE>, because some of the memory a program uses is hidden
from the C code, e.g. the stack and automatic variables, and you
wouldn't know what address to tell <CODE>mlock</CODE>.
<br><br>
sq~wtunistd.ht
sys/mman.hxq~Wtconst void *addr, size_t lentinttmlockallsq~
t }
<br><br> <CODE>mlockall</CODE> locks all the pages in a process' virtual memory address
space, and/or any that are added to it in the future. This includes the
pages of the code, data and stack segment, as well as shared libraries,
user space kernel data, shared memory, and memory mapped files.
<br><br> <VAR>flags</VAR> is a string of single bit flags represented by the following
macros. They tell <CODE>mlockall</CODE> which of its functions you want. All
other bits must be zero.
<br><br> <DL>
<br><br> <DT><CODE>MCL_CURRENT</CODE>
<DD>
Lock all pages which currently exist in the calling process' virtual
address space.
<br><br> <DT><CODE>MCL_FUTURE</CODE>
<DD>
Set a mode such that any pages added to the process' virtual address
space in the future will be locked from birth. This mode does not
affect future address spaces owned by the same process so exec, which
replaces a process' address space, wipes out <CODE>MCL_FUTURE</CODE>.
.
<br><br>
<br><br> When the function returns successfully, and you specified
<CODE>MCL_CURRENT</CODE>, all of the process' pages are backed by (connected
to) real frames (they are resident) and are marked to stay that way.
This means the function may cause page-ins and have to wait for them.
<br><br> When the process is in <CODE>MCL_FUTURE</CODE> mode because it successfully
executed this function and specified <CODE>MCL_CURRENT</CODE>, any system call
by the process that requires space be added to its virtual address space
fails with <CODE>errno</CODE> = <CODE>ENOMEM</CODE> if locking the additional space
would cause the process to exceed its locked page limit. In the case
that the address space addition that can't be accommodated is stack
expansion, the stack expansion fails and the kernel sends a
<CODE>SIGSEGV</CODE> signal to the process.
<br><br> When the function fails, it does not affect the lock status of any pages
or the future locking mode.
<br><br> The return value is zero if the function succeeds. Otherwise, it is
<CODE>-1</CODE> and <CODE>errno</CODE> is set accordingly. <CODE>errno</CODE> values
specific to this function are:
<br><br> <DL>
<LI> ENOMEM
<OL>
<LI>
At least some of the specified address range does not exist in the
calling process' virtual address space.
<LI>
The locking would cause the process to exceed its locked page limit.
</OL>
<br><br> <LI> EPERM
The calling process is not superuser.
<br><br> <LI> EINVAL
Undefined bits in <VAR>flags</VAR> are not zero.
<br><br> <LI> ENOSYS
The kernel does not provide <CODE>mlockall</CODE> capability.
<br><br>
<br><br> You can lock just specific pages with <CODE>mlock</CODE>. You unlock pages
with <CODE>munlockall</CODE> and <CODE>munlock</CODE>.
<br><br>
sq~wt
sys/mman.hxq~_t int flagstinttmmapsq~
tp
<br><br> The <CODE>mmap</CODE> function creates a new mapping, connected to bytes
(<VAR>offset</VAR>) to (<VAR>offset</VAR> + <VAR>length</VAR> - 1) in the file open on
<VAR>filedes</VAR>. A new reference for the file specified by <VAR>filedes</VAR>
is created, which is not removed by closing the file.
<br><br> <VAR>address</VAR> gives a preferred starting address for the mapping.
<CODE>NULL</CODE> expresses no preference. Any previous mapping at that
address is automatically removed. The address you give may still be
changed, unless you use the <CODE>MAP_FIXED</CODE> flag.
<br><br>
<VAR>protect</VAR> contains flags that control what kind of access is
permitted. They include <CODE>PROT_READ</CODE>, <CODE>PROT_WRITE</CODE>, and
<CODE>PROT_EXEC</CODE>, which permit reading, writing, and execution,
respectively. Inappropriate access will cause a segfault .
<br><br> Note that most hardware designs cannot support write permission without
read permission, and many do not distinguish read and execute permission.
Thus, you may receive wider permissions than you ask for, and mappings of
write-only files may be denied even if you do not use <CODE>PROT_READ</CODE>.
<br><br> <VAR>flags</VAR> contains flags that control the nature of the map.
One of <CODE>MAP_SHARED</CODE> or <CODE>MAP_PRIVATE</CODE> must be specified.
<br><br> They include:
<br><br> <DL>
<DT><CODE>MAP_PRIVATE</CODE>
<DD>
This specifies that writes to the region should never be written back
to the attached file. Instead, a copy is made for the process, and the
region will be swapped normally if memory runs low. No other process will
see the changes.
<br><br> Since private mappings effectively revert to ordinary memory
when written to, you must have enough virtual memory for a copy of
the entire mmapped region if you use this mode with <CODE>PROT_WRITE</CODE>.
<br><br> <DT><CODE>MAP_SHARED</CODE>
<DD>
This specifies that writes to the region will be written back to the
file. Changes made will be shared immediately with other processes
mmaping the same file.
<br><br> Note that actual writing may take place at any time. You need to use
<CODE>msync</CODE>, described below, if it is important that other processes
using conventional I/O get a consistent view of the file.
<br><br> <DT><CODE>MAP_FIXED</CODE>
<DD>
This forces the system to use the exact mapping address specified in
<VAR>address</VAR> and fail if it can't.
<br><br> <DT><CODE>MAP_ANONYMOUS</CODE>
<DD>
<LI>x MAP_ANON
This flag tells the system to create an anonymous mapping, not connected
to a file. <VAR>filedes</VAR> and <VAR>off</VAR> are ignored, and the region is
initialized with zeros.
<br><br> Anonymous maps are used as the basic primitive to extend the heap on some
systems. They are also useful to share data between multiple tasks
without creating a file.
<br><br> On some systems using private anonymous mmaps is more efficient than using
<CODE>malloc</CODE> for large blocks. This is not an issue with the GNU C library,
as the included <CODE>malloc</CODE> automatically uses <CODE>mmap</CODE> where appropriate.
<br><br> <br><br> </DL>
<br><br> <CODE>mmap</CODE> returns the address of the new mapping, or -1 for an
error.
<br><br> Possible errors include:
<br><br> <DL>
<br><br> <DT><CODE>EINVAL</CODE>
<DD>
<br><br> Either <VAR>address</VAR> was unusable, or inconsistent <VAR>flags</VAR> were
given.
<br><br> <LI> EACCES
<br><br> <VAR>filedes</VAR> was not open for the type of access specified in <VAR>protect</VAR>.
<br><br> <LI> ENOMEM
<br><br> Either there is not enough memory for the operation, or the process is
out of address space.
<br><br> <LI> ENODEV
<br><br> This file is of a type that doesn't support mapping.
<br><br> <LI> ENOEXEC
<br><br> The file is on a filesystem that doesn't support mapping.
<br><br>
<br><br>
<br><br>
sq~wt
sys/mman.hxq~ftNvoid *address, size_t length,int protect, int flags, int filedes, off_t offsettvoid *tmmap64sq~
t+
The <CODE>mmap64</CODE> function is equivalent to the <CODE>mmap</CODE> function but
the <VAR>offset</VAR> parameter is of type <CODE>off64_t</CODE>. On 32-bit systems
this allows the file associated with the <VAR>filedes</VAR> descriptor to be
larger than 2GB. <VAR>filedes</VAR> must be a descriptor returned from a
call to <CODE>open64</CODE> or <CODE>fopen64</CODE> and <CODE>freopen64</CODE> where the
descriptor is retrieved with <CODE>fileno</CODE>.
<br><br> When the sources are translated with <CODE>_FILE_OFFSET_BITS == 64</CODE> this
function is actually available under the name <CODE>mmap</CODE>. I.e., the
new, extended API using 64 bit file sizes and offsets transparently
replaces the old API.
sq~wt
sys/mman.hxq~mtPvoid *address, size_t length,int protect, int flags, int filedes, off64_t offsettvoid *tmodfsq~
to
These functions break the argument <VAR>value</VAR> into an integer part and a
fractional part (between <CODE>-1</CODE> and <CODE>1</CODE>, exclusive). Their sum
equals <VAR>value</VAR>. Each of the parts has the same sign as <VAR>value</VAR>,
and the integer part is always rounded toward zero.
<br><br> <CODE>modf</CODE> stores the integer part in <CODE>*<VAR>integer-part</VAR></CODE>, and
returns the fractional part. For example, <CODE>modf (2.5, &intpart)</CODE>
returns <CODE>0.5</CODE> and stores <CODE>2.0</CODE> into <CODE>intpart</CODE>.
sq~wtmath.hxq~tt"double value, double *integer-parttdoubletmodffsq~
to
These functions break the argument <VAR>value</VAR> into an integer part and a
fractional part (between <CODE>-1</CODE> and <CODE>1</CODE>, exclusive). Their sum
equals <VAR>value</VAR>. Each of the parts has the same sign as <VAR>value</VAR>,
and the integer part is always rounded toward zero.
<br><br> <CODE>modf</CODE> stores the integer part in <CODE>*<VAR>integer-part</VAR></CODE>, and
returns the fractional part. For example, <CODE>modf (2.5, &intpart)</CODE>
returns <CODE>0.5</CODE> and stores <CODE>2.0</CODE> into <CODE>intpart</CODE>.
sq~wtmath.hxq~{t float value, float *integer-parttfloattmodflsq~
to
These functions break the argument <VAR>value</VAR> into an integer part and a
fractional part (between <CODE>-1</CODE> and <CODE>1</CODE>, exclusive). Their sum
equals <VAR>value</VAR>. Each of the parts has the same sign as <VAR>value</VAR>,
and the integer part is always rounded toward zero.
<br><br> <CODE>modf</CODE> stores the integer part in <CODE>*<VAR>integer-part</VAR></CODE>, and
returns the fractional part. For example, <CODE>modf (2.5, &intpart)</CODE>
returns <CODE>0.5</CODE> and stores <CODE>2.0</CODE> into <CODE>intpart</CODE>.
sq~wtmath.hxq~‚t,long double value, long double *integer-partt long doubletmountsq~
t!>
<br><br> <CODE>mount</CODE> mounts or remounts a filesystem. The two operations are
quite different and are merged rather unnaturally into this one function.
The <CODE>MS_REMOUNT</CODE> option, explained below, determines whether
<CODE>mount</CODE> mounts or remounts.
<br><br> For a mount, the filesystem on the block device represented by the
device special file named <VAR>special_file</VAR> gets mounted over the mount
point <VAR>dir</VAR>. This means that the directory <VAR>dir</VAR> (along with any
files in it) is no longer visible; in its place (and still with the name
<VAR>dir</VAR>) is the root directory of the filesystem on the device.
<br><br> As an exception, if the filesystem type (see below) is one which is not
based on a device (e.g. ``proc''), <CODE>mount</CODE> instantiates a
filesystem and mounts it over <VAR>dir</VAR> and ignores <VAR>special_file</VAR>.
<br><br> For a remount, <VAR>dir</VAR> specifies the mount point where the filesystem
to be remounted is (and remains) mounted and <VAR>special_file</VAR> is
ignored. Remounting a filesystem means changing the options that control
operations on the filesystem while it is mounted. It does not mean
unmounting and mounting again.
<br><br> For a mount, you must identify the type of the filesystem as
<VAR>fstype</VAR>. This type tells the kernel how to access the filesystem
and can be thought of as the name of a filesystem driver. The
acceptable values are system dependent. On a system with a Linux kernel
and the <CODE>proc</CODE> filesystem, the list of possible values is in the
file <TT>filesystems</TT> in the <CODE>proc</CODE> filesystem (e.g. type
<KBD>cat /proc/filesystems</KBD> to see the list). With a Linux kernel, the
types of filesystems that <CODE>mount</CODE> can mount, and their type names,
depends on what filesystem drivers are configured into the kernel or
loaded as loadable kernel modules. An example of a common value for
<VAR>fstype</VAR> is <CODE>ext2</CODE>.
<br><br> For a remount, <CODE>mount</CODE> ignores <VAR>fstype</VAR>.
<br><br> <VAR>options</VAR> specifies a variety of options that apply until the
filesystem is unmounted or remounted. The precise meaning of an option
depends on the filesystem and with some filesystems, an option may have
no effect at all. Furthermore, for some filesystems, some of these
options (but never <CODE>MS_RDONLY</CODE>) can be overridden for individual
file accesses via <CODE>ioctl</CODE>.
<br><br> <VAR>options</VAR> is a bit string with bit fields defined using the
following mask and masked value macros:
<br><br> <DL>
<DT><CODE>MS_MGC_MASK</CODE>
<DD>
This multibit field contains a magic number. If it does not have the value
<CODE>MS_MGC_VAL</CODE>, <CODE>mount</CODE> assumes all the following bits are zero and
the <VAR>data</VAR> argument is a null string, regardless of their actual values.
<br><br> <DT><CODE>MS_REMOUNT</CODE>
<DD>
This bit on means to remount the filesystem. Off means to mount it.
<br><br> <LI> MS_RDONLY
This bit on specifies that no writing to the filesystem shall be allowed
while it is mounted. This cannot be overridden by <CODE>ioctl</CODE>. This
option is available on nearly all filesystems.
<br><br> <LI> S_IMMUTABLE
This bit on specifies that no writing to the files in the filesystem
shall be allowed while it is mounted. This can be overridden for a
particular file access by a properly privileged call to <CODE>ioctl</CODE>.
This option is a relatively new invention and is not available on many
filesystems.
<br><br> <LI> S_APPEND
This bit on specifies that the only file writing that shall be allowed
while the filesystem is mounted is appending. Some filesystems allow
this to be overridden for a particular process by a properly privileged
call to <CODE>ioctl</CODE>. This is a relatively new invention and is not
available on many filesystems.
<br><br> <LI> MS_NOSUID
This bit on specifies that Setuid and Setgid permissions on files in the
filesystem shall be ignored while it is mounted.
<br><br> <LI> MS_NOEXEC
This bit on specifies that no files in the filesystem shall be executed
while the filesystem is mounted.
<br><br> <LI> MS_NODEV
This bit on specifies that no device special files in the filesystem
shall be accessible while the filesystem is mounted.
<br><br> <LI> MS_SYNCHRONOUS
This bit on specifies that all writes to the filesystem while it is
mounted shall be synchronous; i.e., data shall be synced before each
write completes rather than held in the buffer cache.
<br><br> <LI> MS_MANDLOCK
This bit on specifies that mandatory locks on files shall be permitted while
the filesystem is mounted.
<br><br> <LI> MS_NOATIME
This bit on specifies that access times of files shall not be updated when
the files are accessed while the filesystem is mounted.
<br><br> <LI> MS_NODIRATIME
This bit on specifies that access times of directories shall not be updated
when the directories are accessed while the filesystem in mounted.
<br><br> <br><br>
<br><br> Any bits not covered by the above masks should be set off; otherwise,
results are undefined.
<br><br> The meaning of <VAR>data</VAR> depends on the filesystem type and is controlled
entirely by the filesystem driver in the kernel.
<br><br> Example:
<br><br> <pre><br>
<br>
#include <sys/mount.h><br>
<br><br> mount("/dev/hdb", "/cdrom", MS_MGC_VAL | MS_RDONLY | MS_NOSUID, "");<br>
<br><br> mount("/dev/hda2", "/mnt", MS_MGC_VAL | MS_REMOUNT, "");<br>
<br><br> <br>
</pre>
<br><br> Appropriate arguments for <CODE>mount</CODE> are conventionally recorded in
the <TT>fstab</TT> table. .
<br><br> The return value is zero if the mount or remount is successful. Otherwise,
it is <CODE>-1</CODE> and <CODE>errno</CODE> is set appropriately. The values of
<CODE>errno</CODE> are filesystem dependent, but here is a general list:
<br><br> <DL>
<LI> EPERM
The process is not superuser.
<LI> ENODEV
The file system type <VAR>fstype</VAR> is not known to the kernel.
<LI> ENOTBLK
The file <VAR>dev</VAR> is not a block device special file.
<LI> EBUSY
<br><br> <OL>
<br><br> <LI>
The device is already mounted.
<br><br> <LI>
The mount point is busy. (E.g. it is some process' working directory or
has a filesystem mounted on it already).
<br><br> <LI>
The request is to remount read-only, but there are files open for write.
</OL>
<br><br> <LI> EINVAL
<OL>
<br><br> <LI>
A remount was attempted, but there is no filesystem mounted over the
specified mount point.
<br><br> <LI>
The supposed filesystem has an invalid superblock.
<br><br> </OL>
<br><br> <LI> EACCES
<OL>
<br><br> <LI>
The filesystem is inherently read-only (possibly due to a switch on the
device) and the process attempted to mount it read/write (by setting the
<CODE>MS_RDONLY</CODE> bit off).
<br><br> <LI>
<VAR>special_file</VAR> or <VAR>dir</VAR> is not accessible due to file permissions.
<br><br> <LI>
<VAR>special_file</VAR> is not accessible because it is in a filesystem that is
mounted with the <CODE>MS_NODEV</CODE> option.
<br><br> </OL>
<br><br> <LI> EM_FILE
The table of dummy devices is full. <CODE>mount</CODE> needs to create a
dummy device (aka ``unnamed'' device) if the filesystem being mounted is
not one that uses a device.
<br><br>
<br><br>
sq~wt sys/mount.hxq~‰tjconst char *special_file, const char *dir, const char *fstype, unsigned long int options, const void *datatinttmprobesq~
t„
The <CODE>mprobe</CODE> function lets you explicitly check for inconsistencies
in a particular allocated block. You must have already called
<CODE>mcheck</CODE> at the beginning of the program, to do its occasional
checks; calling <CODE>mprobe</CODE> requests an additional consistency check
to be done at the time of the call.
<br><br> The argument <VAR>pointer</VAR> must be a pointer returned by <CODE>malloc</CODE>
or <CODE>realloc</CODE>. <CODE>mprobe</CODE> returns a value that says what
inconsistency, if any, was found. The values are described below.
sq~wxq~�t
void *pointertenum mcheck_statustmrand48sq~
tá
The <CODE>mrand48</CODE> function is similar to <CODE>lrand48</CODE>. The only
difference is that the numbers returned are in the range <CODE>-2^31</CODE> to
<CODE>2^31</CODE> (exclusive).
sq~wtstdlib.hxq~–tvoidtlong intt mrand48_rsq~
tÏ
This function is similar to <CODE>mrand48</CODE> but like the other reentrant
functions it uses the random number generator described by the value in
the buffer pointed to by <VAR>buffer</VAR>.
<br><br> If the return value is non-negative the variable pointed to by
<VAR>result</VAR> contains the result.
<br><br> This function is a GNU extension and should not be used in portable
programs.
sq~wtstdlib.hxq~�t+struct drand48_data *buffer, double *resulttinttmremapsq~
t±
<br><br> This function can be used to change the size of an existing memory
area. <VAR>address</VAR> and <VAR>length</VAR> must cover a region entirely mapped
in the same <CODE>mmap</CODE> statement. A new mapping with the same
characteristics will be returned with the length <VAR>new_length</VAR>.
<br><br> One option is possible, <CODE>MREMAP_MAYMOVE</CODE>. If it is given in
<VAR>flags</VAR>, the system may remove the existing mapping and create a new
one of the desired length in another location.
<br><br> The address of the resulting mapping is returned, or -1. Possible
error codes include:
<br><br> <DL>
<br><br> <DT><CODE>EFAULT</CODE>
<DD>
There is no existing mapping in at least part of the original region, or
the region covers two or more distinct mappings.
<br><br> <LI> EINVAL
The address given is misaligned or inappropriate.
<br><br> <LI> EAGAIN
The region has pages locked, and if extended it would exceed the
process's resource limit for locked pages. .
<br><br> <LI> ENOMEM
The region is private writable, and insufficient virtual memory is
available to extend it. Also, this error will occur if
<CODE>MREMAP_MAYMOVE</CODE> is not given and the extension would collide with
another mapped region.
<br><br>
sq~wt
sys/mman.hxq~¤t9void *address, size_t length, size_t new_length, int flagtvoid *tmsyncsq~
tÛ
<br><br> When using shared mappings, the kernel can write the file at any time
before the mapping is removed. To be certain data has actually been
written to the file and will be accessible to non-memory-mapped I/O, it
is necessary to use this function.
<br><br> It operates on the region <VAR>address</VAR> to (<VAR>address</VAR> + <VAR>length</VAR>).
It may be used on part of a mapping or multiple mappings, however the
region given should not contain any unmapped space.
<br><br> <VAR>flags</VAR> can contain some options:
<br><br> <DL>
<br><br> <DT><CODE>MS_SYNC</CODE>
<DD>
<br><br> This flag makes sure the data is actually written <EM>to disk</EM>.
Normally <CODE>msync</CODE> only makes sure that accesses to a file with
conventional I/O reflect the recent changes.
<br><br> <DT><CODE>MS_ASYNC</CODE>
<DD>
<br><br> This tells <CODE>msync</CODE> to begin the synchronization, but not to wait for
it to complete.
<br><br> <br><br> </DL>
<br><br> <CODE>msync</CODE> returns 0 for success and -1 for
error. Errors include:
<br><br> <DL>
<br><br> <DT><CODE>EINVAL</CODE>
<DD>
An invalid region was given, or the <VAR>flags</VAR> were invalid.
<br><br> <LI> EFAULT
There is no existing mapping in at least part of the given region.
<br><br>
<br><br>
sq~wt
sys/mman.hxq~«t'void *address, size_t length, int flagstinttmtracesq~
tÆ
When the <CODE>mtrace</CODE> function is called it looks for an environment
variable named <CODE>MALLOC_TRACE</CODE>. This variable is supposed to
contain a valid file name. The user must have write access. If the
file already exists it is truncated. If the environment variable is not
set or it does not name a valid file which can be opened for writing
nothing is done. The behavior of <CODE>malloc</CODE> etc. is not changed.
For obvious reasons this also happens if the application is installed
with the SUID or SGID bit set.
<br><br> If the named file is successfully opened, <CODE>mtrace</CODE> installs special
handlers for the functions <CODE>malloc</CODE>, <CODE>realloc</CODE>, and
<CODE>free</CODE> . From then on, all uses of these
functions are traced and protocolled into the file. There is now of
course a speed penalty for all calls to the traced functions so tracing
should not be enabled during normal use.
<br><br> This function is a GNU extension and generally not available on other
systems. The prototype can be found in <TT>mcheck.h</TT>.
sq~wtmcheck.hxq~²tvoidtvoidtmunlocksq~
tF
<br><br> <CODE>munlock</CODE> unlocks a range of the calling process' virtual pages.
<br><br> <CODE>munlock</CODE> is the inverse of <CODE>mlock</CODE> and functions completely
analogously to <CODE>mlock</CODE>, except that there is no <CODE>EPERM</CODE>
failure.
<br><br>
sq~wt
sys/mman.hxq~¹tconst void *addr, size_t lentintt
munlockallsq~
t
<br><br> <CODE>munlockall</CODE> unlocks every page in the calling process' virtual
address space and turn off <CODE>MCL_FUTURE</CODE> future locking mode.
<br><br> The return value is zero if the function succeeds. Otherwise, it is
<CODE>-1</CODE> and <CODE>errno</CODE> is set accordingly. The only way this
function can fail is for generic reasons that all functions and system
calls can fail, so there are no specific <CODE>errno</CODE> values.
<br><br>
sq~wt
sys/mman.hxq~Àtvoidtinttmunmapsq~
tA
<br><br> <CODE>munmap</CODE> removes any memory maps from (<VAR>addr</VAR>) to (<VAR>addr</VAR> +
<VAR>length</VAR>). <VAR>length</VAR> should be the length of the mapping.
<br><br> It is safe to unmap multiple mappings in one command, or include unmapped
space in the range. It is also possible to unmap only part of an existing
mapping. However, only entire pages can be removed. If <VAR>length</VAR> is not
an even number of pages, it will be rounded up.
<br><br> It returns 0 for success and -1 for an error.
<br><br> One error is possible:
<br><br> <DL>
<br><br> <DT><CODE>EINVAL</CODE>
<DD>
The memory range given was outside the user mmap range or wasn't page
aligned.
<br><br>
<br><br>
sq~wt
sys/mman.hxq~Çtvoid *addr, size_t lengthtinttmuntracesq~
tž
The <CODE>muntrace</CODE> function can be called after <CODE>mtrace</CODE> was used
to enable tracing the <CODE>malloc</CODE> calls. If no (successful) call of
<CODE>mtrace</CODE> was made <CODE>muntrace</CODE> does nothing.
<br><br> Otherwise it deinstalls the handlers for <CODE>malloc</CODE>, <CODE>realloc</CODE>,
and <CODE>free</CODE> and then closes the protocol file. No calls are
protocolled anymore and the program runs again at full speed.
<br><br> This function is a GNU extension and generally not available on other
systems. The prototype can be found in <TT>mcheck.h</TT>.
sq~wtmcheck.hxq~Îtvoidtvoidtnansq~
t
The <CODE>nan</CODE> function returns a representation of NaN, provided that
NaN is supported by the target platform.
<CODE>nan ("<VAR>n-char-sequence</VAR>")</CODE> is equivalent to
<CODE>strtod ("NAN(<VAR>n-char-sequence</VAR>)")</CODE>.
<br><br> The argument <VAR>tagp</VAR> is used in an unspecified manner. On IEEE
754 systems, there are many representations of NaN, and <VAR>tagp</VAR>
selects one. On other systems it may do nothing.
sq~wtmath.hxq~Õtconst char *tagptdoubletnanfsq~
t
The <CODE>nan</CODE> function returns a representation of NaN, provided that
NaN is supported by the target platform.
<CODE>nan ("<VAR>n-char-sequence</VAR>")</CODE> is equivalent to
<CODE>strtod ("NAN(<VAR>n-char-sequence</VAR>)")</CODE>.
<br><br> The argument <VAR>tagp</VAR> is used in an unspecified manner. On IEEE
754 systems, there are many representations of NaN, and <VAR>tagp</VAR>
selects one. On other systems it may do nothing.
sq~wtmath.hxq~Ütconst char *tagptfloattnanlsq~
t
The <CODE>nan</CODE> function returns a representation of NaN, provided that
NaN is supported by the target platform.
<CODE>nan ("<VAR>n-char-sequence</VAR>")</CODE> is equivalent to
<CODE>strtod ("NAN(<VAR>n-char-sequence</VAR>)")</CODE>.
<br><br> The argument <VAR>tagp</VAR> is used in an unspecified manner. On IEEE
754 systems, there are many representations of NaN, and <VAR>tagp</VAR>
selects one. On other systems it may do nothing.
sq~wtmath.hxq~ãtconst char *tagpt long doublet nanosleepsq~
t_
If resolution to seconds is not enough the <CODE>nanosleep</CODE> function can
be used. As the name suggests the sleep interval can be specified in
nanoseconds. The actual elapsed time of the sleep interval might be
longer since the system rounds the elapsed time you request up to the
next integer multiple of the actual resolution the system can deliver.
<br><br> *<CODE>requested_time</CODE> is the elapsed time of the interval you want to
sleep.
<br><br> The function returns as *<CODE>remaining</CODE> the elapsed time left in the
interval for which you requested to sleep. If the interval completed
without getting interrupted by a signal, this is zero.
<br><br> <CODE>struct timespec</CODE> is described in .
<br><br> If the function returns because the interval is over the return value is
zero. If the function returns -1 the global variable <VAR>errno</VAR>
is set to the following values:
<br><br> <DL>
<DT><CODE>EINTR</CODE>
<DD>
The call was interrupted because a signal was delivered to the thread.
If the <VAR>remaining</VAR> parameter is not the null pointer the structure
pointed to by <VAR>remaining</VAR> is updated to contain the remaining
elapsed time.
<br><br> <LI> EINVAL
The nanosecond value in the <VAR>requested_time</VAR> parameter contains an
illegal value. Either the value is negative or greater than or equal to
1000 million.
<br><br> This function is a cancellation point in multi-threaded programs. This
is a problem if the thread allocates some resources (like memory, file
descriptors, semaphores or whatever) at the time <CODE>nanosleep</CODE> is
called. If the thread gets canceled these resources stay allocated
until the program ends. To avoid this calls to <CODE>nanosleep</CODE> should
be protected using cancellation handlers.
<br><br> The <CODE>nanosleep</CODE> function is declared in <TT>time.h</TT>.
sq~wttime.hxq~êtAconst struct timespec *requested_time, struct timespec *remainingtintt nearbyintsq~
t®
These functions return the same value as the <CODE>rint</CODE> functions, but
do not raise the inexact exception if <VAR>x</VAR> is not an integer.
sq~wtmath.hxq~ñtdouble xtdoublet
nearbyintfsq~
t®
These functions return the same value as the <CODE>rint</CODE> functions, but
do not raise the inexact exception if <VAR>x</VAR> is not an integer.
sq~wtmath.hxq~øtfloat xtfloatt
nearbyintlsq~
t®
These functions return the same value as the <CODE>rint</CODE> functions, but
do not raise the inexact exception if <VAR>x</VAR> is not an integer.
sq~wtmath.hxq~ÿt
long double xt long doublet nextaftersq~
tQ
The <CODE>nextafter</CODE> function returns the next representable neighbor of
<VAR>x</VAR> in the direction towards <VAR>y</VAR>. The size of the step between
<VAR>x</VAR> and the result depends on the type of the result. If
<VAR>x</VAR> = <VAR>y</VAR> the function simply returns <VAR>y</VAR>. If either
value is <CODE>NaN</CODE>, <CODE>NaN</CODE> is returned. Otherwise
a value corresponding to the value of the least significant bit in the
mantissa is added or subtracted, depending on the direction.
<CODE>nextafter</CODE> will signal overflow or underflow if the result goes
outside of the range of normalized numbers.
<br><br> This function is defined in IEC 559 (and the appendix with
recommended functions in IEEE 754/IEEE 854).
sq~wtmath.hxq~tdouble x, double ytdoublet
nextafterfsq~
tQ
The <CODE>nextafter</CODE> function returns the next representable neighbor of
<VAR>x</VAR> in the direction towards <VAR>y</VAR>. The size of the step between
<VAR>x</VAR> and the result depends on the type of the result. If
<VAR>x</VAR> = <VAR>y</VAR> the function simply returns <VAR>y</VAR>. If either
value is <CODE>NaN</CODE>, <CODE>NaN</CODE> is returned. Otherwise
a value corresponding to the value of the least significant bit in the
mantissa is added or subtracted, depending on the direction.
<CODE>nextafter</CODE> will signal overflow or underflow if the result goes
outside of the range of normalized numbers.
<br><br> This function is defined in IEC 559 (and the appendix with
recommended functions in IEEE 754/IEEE 854).
sq~wtmath.hxq~
tfloat x, float ytfloatt
nextafterlsq~
tQ
The <CODE>nextafter</CODE> function returns the next representable neighbor of
<VAR>x</VAR> in the direction towards <VAR>y</VAR>. The size of the step between
<VAR>x</VAR> and the result depends on the type of the result. If
<VAR>x</VAR> = <VAR>y</VAR> the function simply returns <VAR>y</VAR>. If either
value is <CODE>NaN</CODE>, <CODE>NaN</CODE> is returned. Otherwise
a value corresponding to the value of the least significant bit in the
mantissa is added or subtracted, depending on the direction.
<CODE>nextafter</CODE> will signal overflow or underflow if the result goes
outside of the range of normalized numbers.
<br><br> This function is defined in IEC 559 (and the appendix with
recommended functions in IEEE 754/IEEE 854).
sq~wtmath.hxq~tlong double x, long double yt long doublet
nexttowardsq~
tº
These functions are identical to the corresponding versions of
<CODE>nextafter</CODE> except that their second argument is a <CODE>long
double</CODE>.
sq~wtmath.hxq~tdouble x, long double ytdoublet nexttowardfsq~
tº
These functions are identical to the corresponding versions of
<CODE>nextafter</CODE> except that their second argument is a <CODE>long
double</CODE>.
sq~wtmath.hxq~"tfloat x, long double ytfloatt nexttowardlsq~
tº
These functions are identical to the corresponding versions of
<CODE>nextafter</CODE> except that their second argument is a <CODE>long
double</CODE>.
sq~wtmath.hxq~)tlong double x, long double yt long doubletnftwsq~
t
Ò
The <CODE>nftw</CODE> function works like the <CODE>ftw</CODE> functions. They call
the callback function <VAR>func</VAR> for all items found in the directory
<VAR>filename</VAR> and below. At most <VAR>descriptors</VAR> file descriptors
are consumed during the <CODE>nftw</CODE> call.
<br><br> One difference is that the callback function is of a different type. It
is of type <CODE>struct FTW *</CODE> and provides the callback function
with the extra information described above.
<br><br> A second difference is that <CODE>nftw</CODE> takes a fourth argument, which
is 0 or a bitwise-OR combination of any of the following values.
<br><br> <DL>
<DT><CODE>FTW_PHYS</CODE>
<DD>
While traversing the directory symbolic links are not followed. Instead
symbolic links are reported using the <CODE>FTW_SL</CODE> value for the type
parameter to the callback function. If the file referenced by a
symbolic link does not exist <CODE>FTW_SLN</CODE> is returned instead.
<DT><CODE>FTW_MOUNT</CODE>
<DD>
The callback function is only called for items which are on the same
mounted filesystem as the directory given by the <VAR>filename</VAR>
parameter to <CODE>nftw</CODE>.
<DT><CODE>FTW_CHDIR</CODE>
<DD>
If this flag is given the current working directory is changed to the
directory of the reported object before the callback function is called.
When <CODE>ntfw</CODE> finally returns the current directory is restored to
its original value.
<DT><CODE>FTW_DEPTH</CODE>
<DD>
If this option is specified then all subdirectories and files within
them are processed before processing the top directory itself
(depth-first processing). This also means the type flag given to the
callback function is <CODE>FTW_DP</CODE> and not <CODE>FTW_D</CODE>.
<DT><CODE>FTW_ACTIONRETVAL</CODE>
<DD>
If this option is specified then return values from callbacks
are handled differently. If the callback returns <CODE>FTW_CONTINUE</CODE>,
walking continues normally. <CODE>FTW_STOP</CODE> means walking stops
and <CODE>FTW_STOP</CODE> is returned to the caller. If <CODE>FTW_SKIP_SUBTREE</CODE>
is returned by the callback with <CODE>FTW_D</CODE> argument, the subtree
is skipped and walking continues with next sibling of the directory.
If <CODE>FTW_SKIP_SIBLINGS</CODE> is returned by the callback, all siblings
of the current entry are skipped and walking continues in its parent.
No other return values should be returned from the callbacks if
this option is set. This option is a GNU extension.
</DL>
<br><br> The return value is computed in the same way as for <CODE>ftw</CODE>.
<CODE>nftw</CODE> returns 0 if no failures occurred and all callback
functions returned 0. In case of internal errors, such as memory
problems, the return value is -1 and <VAR>errno</VAR> is set
accordingly. If the return value of a callback invocation was non-zero
then that value is returned.
<br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> on a
32-bit system this function is in fact <CODE>nftw64</CODE>, i.e., the LFS
interface transparently replaces the old interface.
sq~wtftw.hxq~0tCconst char *filename, __nftw_func_t func, int descriptors, int flagtinttnftw64sq~
t
This function is similar to <CODE>nftw</CODE> but it can work on filesystems
with large files. File information is reported using a variable of type
<CODE>struct stat64</CODE> which is passed by reference to the callback
function.
<br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> on a
32-bit system this function is available under the name <CODE>nftw</CODE> and
transparently replaces the old implementation.
sq~wtftw.hxq~7tEconst char *filename, __nftw64_func_t func, int descriptors, int flagtinttngettextsq~
t
The <CODE>ngettext</CODE> function is similar to the <CODE>gettext</CODE> function
as it finds the message catalogs in the same way. But it takes two
extra arguments. The <VAR>msgid1</VAR> parameter must contain the singular
form of the string to be converted. It is also used as the key for the
search in the catalog. The <VAR>msgid2</VAR> parameter is the plural form.
The parameter <VAR>n</VAR> is used to determine the plural form. If no
message catalog is found <VAR>msgid1</VAR> is returned if <CODE>n == 1</CODE>,
otherwise <CODE>msgid2</CODE>.
<br><br> An example for the us of this function is:
<br><br> <pre><br>
printf (ngettext ("%d file removed", "%d files removed", n), n);<br>
</pre>
<br><br> Please note that the numeric value <VAR>n</VAR> has to be passed to the
<CODE>printf</CODE> function as well. It is not sufficient to pass it only to
<CODE>ngettext</CODE>.
sq~wt libintl.hxq~>t;const char *msgid1, const char *msgid2, unsigned long int ntchar *tnicesq~
t
Increment the nice value of the calling process by <VAR>increment</VAR>.
The return value is the new nice value on success, and <CODE>-1</CODE> on
failure. In the case of failure, <CODE>errno</CODE> will be set to the
same values as for <CODE>setpriority</CODE>.
<br><br> <br><br> Here is an equivalent definition of <CODE>nice</CODE>:
<br><br> <pre><br>
int<br>
nice (int increment)<br>
{<br>
int result, old = getpriority (PRIO_PROCESS, 0);<br>
result = setpriority (PRIO_PROCESS, 0, old + increment);<br>
if (result != -1)<br>
return old + increment;<br>
else<br>
return -1;<br>
}<br>
</pre>
sq~wtsys/resource.htunistd.hxq~Et
int incrementtintt nl_langinfosq~
t3e
The <CODE>nl_langinfo</CODE> function can be used to access individual
elements of the locale categories. Unlike the <CODE>localeconv</CODE>
function, which returns all the information, <CODE>nl_langinfo</CODE>
lets the caller select what information it requires. This is very
fast and it is not a problem to call this function multiple times.
<br><br> A second advantage is that in addition to the numeric and monetary
formatting information, information from the
<CODE>LC_TIME</CODE> and <CODE>LC_MESSAGES</CODE> categories is available.
<br><br> The type <CODE>nl_type</CODE> is defined in <TT>nl_types.h</TT>. The argument
<VAR>item</VAR> is a numeric value defined in the header <TT>langinfo.h</TT>.
The X/Open standard defines the following values:
<br><br> <DL>
<DT><CODE>CODESET</CODE>
<DD>
<CODE>nl_langinfo</CODE> returns a string with the name of the coded character
set used in the selected locale.
<br><br> <DT><CODE>ABDAY_1</CODE>
<DD>
<LI>x ABDAY_2
<LI>x ABDAY_3
<LI>x ABDAY_4
<LI>x ABDAY_5
<LI>x ABDAY_6
<LI>x ABDAY_7
<CODE>nl_langinfo</CODE> returns the abbreviated weekday name. <CODE>ABDAY_1</CODE>
corresponds to Sunday.
<DT><CODE>DAY_1</CODE>
<DD>
<LI>x DAY_2
<LI>x DAY_3
<LI>x DAY_4
<LI>x DAY_5
<LI>x DAY_6
<LI>x DAY_7
Similar to <CODE>ABDAY_1</CODE> etc., but here the return value is the
unabbreviated weekday name.
<DT><CODE>ABMON_1</CODE>
<DD>
<LI>x ABMON_2
<LI>x ABMON_3
<LI>x ABMON_4
<LI>x ABMON_5
<LI>x ABMON_6
<LI>x ABMON_7
<LI>x ABMON_8
<LI>x ABMON_9
<LI>x ABMON_10
<LI>x ABMON_11
<LI>x ABMON_12
The return value is abbreviated name of the month. <CODE>ABMON_1</CODE>
corresponds to January.
<DT><CODE>MON_1</CODE>
<DD>
<LI>x MON_2
<LI>x MON_3
<LI>x MON_4
<LI>x MON_5
<LI>x MON_6
<LI>x MON_7
<LI>x MON_8
<LI>x MON_9
<LI>x MON_10
<LI>x MON_11
<LI>x MON_12
Similar to <CODE>ABMON_1</CODE> etc., but here the month names are not abbreviated.
Here the first value <CODE>MON_1</CODE> also corresponds to January.
<DT><CODE>AM_STR</CODE>
<DD>
<LI>x PM_STR
The return values are strings which can be used in the representation of time
as an hour from 1 to 12 plus an am/pm specifier.
<br><br> Note that in locales which do not use this time representation
these strings might be empty, in which case the am/pm format
cannot be used at all.
<DT><CODE>D_T_FMT</CODE>
<DD>
The return value can be used as a format string for <CODE>strftime</CODE> to
represent time and date in a locale-specific way.
<DT><CODE>D_FMT</CODE>
<DD>
The return value can be used as a format string for <CODE>strftime</CODE> to
represent a date in a locale-specific way.
<DT><CODE>T_FMT</CODE>
<DD>
The return value can be used as a format string for <CODE>strftime</CODE> to
represent time in a locale-specific way.
<DT><CODE>T_FMT_AMPM</CODE>
<DD>
The return value can be used as a format string for <CODE>strftime</CODE> to
represent time in the am/pm format.
<br><br> Note that if the am/pm format does not make any sense for the
selected locale, the return value might be the same as the one for
<CODE>T_FMT</CODE>.
<DT><CODE>ERA</CODE>
<DD>
The return value represents the era used in the current locale.
<br><br> Most locales do not define this value. An example of a locale which
does define this value is the Japanese one. In Japan, the traditional
representation of dates includes the name of the era corresponding to
the then-emperor's reign.
<br><br> Normally it should not be necessary to use this value directly.
Specifying the <CODE>E</CODE> modifier in their format strings causes the
<CODE>strftime</CODE> functions to use this information. The format of the
returned string is not specified, and therefore you should not assume
knowledge of it on different systems.
<DT><CODE>ERA_YEAR</CODE>
<DD>
The return value gives the year in the relevant era of the locale.
As for <CODE>ERA</CODE> it should not be necessary to use this value directly.
<DT><CODE>ERA_D_T_FMT</CODE>
<DD>
This return value can be used as a format string for <CODE>strftime</CODE> to
represent dates and times in a locale-specific era-based way.
<DT><CODE>ERA_D_FMT</CODE>
<DD>
This return value can be used as a format string for <CODE>strftime</CODE> to
represent a date in a locale-specific era-based way.
<DT><CODE>ERA_T_FMT</CODE>
<DD>
This return value can be used as a format string for <CODE>strftime</CODE> to
represent time in a locale-specific era-based way.
<DT><CODE>ALT_DIGITS</CODE>
<DD>
The return value is a representation of up to 100 values used to
represent the values 0 to 99. As for <CODE>ERA</CODE> this
value is not intended to be used directly, but instead indirectly
through the <CODE>strftime</CODE> function. When the modifier <CODE>O</CODE> is
used in a format which would otherwise use numerals to represent hours,
minutes, seconds, weekdays, months, or weeks, the appropriate value for
the locale is used instead.
<DT><CODE>INT_CURR_SYMBOL</CODE>
<DD>
The same as the value returned by <CODE>localeconv</CODE> in the
<CODE>int_curr_symbol</CODE> element of the <CODE>struct lconv</CODE>.
<DT><CODE>CURRENCY_SYMBOL</CODE>
<DD>
<LI>x CRNCYSTR
The same as the value returned by <CODE>localeconv</CODE> in the
<CODE>currency_symbol</CODE> element of the <CODE>struct lconv</CODE>.
<br><br> <CODE>CRNCYSTR</CODE> is a deprecated alias still required by Unix98.
<DT><CODE>MON_DECIMAL_POINT</CODE>
<DD>
The same as the value returned by <CODE>localeconv</CODE> in the
<CODE>mon_decimal_point</CODE> element of the <CODE>struct lconv</CODE>.
<DT><CODE>MON_THOUSANDS_SEP</CODE>
<DD>
The same as the value returned by <CODE>localeconv</CODE> in the
<CODE>mon_thousands_sep</CODE> element of the <CODE>struct lconv</CODE>.
<DT><CODE>MON_GROUPING</CODE>
<DD>
The same as the value returned by <CODE>localeconv</CODE> in the
<CODE>mon_grouping</CODE> element of the <CODE>struct lconv</CODE>.
<DT><CODE>POSITIVE_SIGN</CODE>
<DD>
The same as the value returned by <CODE>localeconv</CODE> in the
<CODE>positive_sign</CODE> element of the <CODE>struct lconv</CODE>.
<DT><CODE>NEGATIVE_SIGN</CODE>
<DD>
The same as the value returned by <CODE>localeconv</CODE> in the
<CODE>negative_sign</CODE> element of the <CODE>struct lconv</CODE>.
<DT><CODE>INT_FRAC_DIGITS</CODE>
<DD>
The same as the value returned by <CODE>localeconv</CODE> in the
<CODE>int_frac_digits</CODE> element of the <CODE>struct lconv</CODE>.
<DT><CODE>FRAC_DIGITS</CODE>
<DD>
The same as the value returned by <CODE>localeconv</CODE> in the
<CODE>frac_digits</CODE> element of the <CODE>struct lconv</CODE>.
<DT><CODE>P_CS_PRECEDES</CODE>
<DD>
The same as the value returned by <CODE>localeconv</CODE> in the
<CODE>p_cs_precedes</CODE> element of the <CODE>struct lconv</CODE>.
<DT><CODE>P_SEP_BY_SPACE</CODE>
<DD>
The same as the value returned by <CODE>localeconv</CODE> in the
<CODE>p_sep_by_space</CODE> element of the <CODE>struct lconv</CODE>.
<DT><CODE>N_CS_PRECEDES</CODE>
<DD>
The same as the value returned by <CODE>localeconv</CODE> in the
<CODE>n_cs_precedes</CODE> element of the <CODE>struct lconv</CODE>.
<DT><CODE>N_SEP_BY_SPACE</CODE>
<DD>
The same as the value returned by <CODE>localeconv</CODE> in the
<CODE>n_sep_by_space</CODE> element of the <CODE>struct lconv</CODE>.
<DT><CODE>P_SIGN_POSN</CODE>
<DD>
The same as the value returned by <CODE>localeconv</CODE> in the
<CODE>p_sign_posn</CODE> element of the <CODE>struct lconv</CODE>.
<DT><CODE>N_SIGN_POSN</CODE>
<DD>
The same as the value returned by <CODE>localeconv</CODE> in the
<CODE>n_sign_posn</CODE> element of the <CODE>struct lconv</CODE>.
<br><br> <DT><CODE>INT_P_CS_PRECEDES</CODE>
<DD>
The same as the value returned by <CODE>localeconv</CODE> in the
<CODE>int_p_cs_precedes</CODE> element of the <CODE>struct lconv</CODE>.
<DT><CODE>INT_P_SEP_BY_SPACE</CODE>
<DD>
The same as the value returned by <CODE>localeconv</CODE> in the
<CODE>int_p_sep_by_space</CODE> element of the <CODE>struct lconv</CODE>.
<DT><CODE>INT_N_CS_PRECEDES</CODE>
<DD>
The same as the value returned by <CODE>localeconv</CODE> in the
<CODE>int_n_cs_precedes</CODE> element of the <CODE>struct lconv</CODE>.
<DT><CODE>INT_N_SEP_BY_SPACE</CODE>
<DD>
The same as the value returned by <CODE>localeconv</CODE> in the
<CODE>int_n_sep_by_space</CODE> element of the <CODE>struct lconv</CODE>.
<DT><CODE>INT_P_SIGN_POSN</CODE>
<DD>
The same as the value returned by <CODE>localeconv</CODE> in the
<CODE>int_p_sign_posn</CODE> element of the <CODE>struct lconv</CODE>.
<DT><CODE>INT_N_SIGN_POSN</CODE>
<DD>
The same as the value returned by <CODE>localeconv</CODE> in the
<CODE>int_n_sign_posn</CODE> element of the <CODE>struct lconv</CODE>.
<br><br> <DT><CODE>DECIMAL_POINT</CODE>
<DD>
<LI>x RADIXCHAR
The same as the value returned by <CODE>localeconv</CODE> in the
<CODE>decimal_point</CODE> element of the <CODE>struct lconv</CODE>.
<br><br> The name <CODE>RADIXCHAR</CODE> is a deprecated alias still used in Unix98.
<DT><CODE>THOUSANDS_SEP</CODE>
<DD>
<LI>x THOUSEP
The same as the value returned by <CODE>localeconv</CODE> in the
<CODE>thousands_sep</CODE> element of the <CODE>struct lconv</CODE>.
<br><br> The name <CODE>THOUSEP</CODE> is a deprecated alias still used in Unix98.
<DT><CODE>GROUPING</CODE>
<DD>
The same as the value returned by <CODE>localeconv</CODE> in the
<CODE>grouping</CODE> element of the <CODE>struct lconv</CODE>.
<DT><CODE>YESEXPR</CODE>
<DD>
The return value is a regular expression which can be used with the
<CODE>regex</CODE> function to recognize a positive response to a yes/no
question. The GNU C library provides the <CODE>rpmatch</CODE> function for
easier handling in applications.
<DT><CODE>NOEXPR</CODE>
<DD>
The return value is a regular expression which can be used with the
<CODE>regex</CODE> function to recognize a negative response to a yes/no
question.
<DT><CODE>YESSTR</CODE>
<DD>
The return value is a locale-specific translation of the positive response
to a yes/no question.
<br><br> Using this value is deprecated since it is a very special case of
message translation, and is better handled by the message
translation functions .
<br><br> The use of this symbol is deprecated. Instead message translation
should be used.
<DT><CODE>NOSTR</CODE>
<DD>
The return value is a locale-specific translation of the negative response
to a yes/no question. What is said for <CODE>YESSTR</CODE> is also true here.
<br><br> The use of this symbol is deprecated. Instead message translation
should be used.
</DL>
<br><br> The file <TT>langinfo.h</TT> defines a lot more symbols but none of them
is official. Using them is not portable, and the format of the
return values might change. Therefore we recommended you not use
them.
<br><br> Note that the return value for any valid argument can be used for
in all situations (with the possible exception of the am/pm time formatting
codes). If the user has not selected any locale for the
appropriate category, <CODE>nl_langinfo</CODE> returns the information from the
<CODE>"C"</CODE> locale. It is therefore possible to use this function as
shown in the example below.
<br><br> If the argument <VAR>item</VAR> is not valid, a pointer to an empty string is
returned.
sq~wtlocale.ht
langinfo.hxq~Mt nl_item itemtchar *tnrand48sq~
t…
This function is similar to the <CODE>lrand48</CODE> function in that it
returns a number in the range of <CODE>0</CODE> to <CODE>2^31</CODE> (exclusive) but
the state of the random number generator used to produce the random bits
is determined by the array provided as the parameter to the function.
<br><br> The numbers in the array are updated afterwards so that subsequent calls
to this function yield different results (as is expected of a random
number generator). The array should have been initialized before the
first call to obtain reproducible results.
sq~wtstdlib.hxq~Utunsigned short int xsubi[3]tlong intt nrand48_rsq~
t†
The <CODE>nrand48_r</CODE> function works like <CODE>nrand48</CODE> in that it
produces a random number in the range <CODE>0</CODE> to <CODE>2^31</CODE>. But instead
of using the global parameters for the congruential formula it uses the
information from the buffer pointed to by <VAR>buffer</VAR>. The state is
described by the values in <VAR>xsubi</VAR>.
<br><br> If the return value is non-negative the variable pointed to by
<VAR>result</VAR> contains the result.
<br><br> This function is a GNU extension and should not be used in portable
programs.
sq~wtstdlib.hxq~\tJunsigned short int xsubi[3], struct drand48_data *buffer, long int *resulttinttntohlsq~
tÎ
This function converts the <CODE>uint32_t</CODE> integer <VAR>netlong</VAR> from
network byte order to host byte order.
<br><br> This is used for IPv4 Internet addresses.
sq~wt netinet/in.hxq~ctuint32_t netlongtuint32_ttntohssq~
t“
This function converts the <CODE>uint16_t</CODE> integer <VAR>netshort</VAR> from
network byte order to host byte order.
sq~wt netinet/in.hxq~jtuint16_t netshorttuint16_tt ntp_adjtimesq~
tL
The <CODE>ntp_adjtime</CODE> function sets the structure specified by
<VAR>tptr</VAR> to current values.
<br><br> In addition, <CODE>ntp_adjtime</CODE> updates some settings to match what you
pass to it in *<VAR>tptr</VAR>. Use the <CODE>modes</CODE> element of *<VAR>tptr</VAR>
to select what settings to update. You can set <CODE>offset</CODE>,
<CODE>freq</CODE>, <CODE>maxerror</CODE>, <CODE>esterror</CODE>, <CODE>status</CODE>,
<CODE>constant</CODE>, and <CODE>tick</CODE>.
<br><br> <CODE>modes</CODE> = zero means set nothing.
<br><br> Only the superuser can update settings.
<br><br> <br><br> The return value is <CODE>0</CODE> on success and other values on failure. The
following <CODE>errno</CODE> error conditions are defined for this function:
<br><br> <DL>
<DT><CODE>TIME_ERROR</CODE>
<DD>
The high accuracy clock model is not properly set up at the moment, thus the
clock must be considered unsynchronized, and the values should be
treated with care. Another reason could be that the specified new values
are not allowed.
<br><br> <LI> EPERM
The process specified a settings update, but is not superuser.
<br><br>
<br><br> For more details see RFC1305 (Network Time Protocol, Version 3) and
related documents.
<br><br> Portability note: Early versions of the GNU C library did not
have this function but did have the synonymous <CODE>adjtimex</CODE>.
<br><br>
sq~wt sys/timex.hxq~qtstruct timex *tptrtintt ntp_gettimesq~
t$
The <CODE>ntp_gettime</CODE> function sets the structure pointed to by
<VAR>tptr</VAR> to current values. The elements of the structure afterwards
contain the values the timer implementation in the kernel assumes. They
might or might not be correct. If they are not a <CODE>ntp_adjtime</CODE>
call is necessary.
<br><br> The return value is <CODE>0</CODE> on success and other values on failure. The
following <CODE>errno</CODE> error conditions are defined for this function:
<br><br> <DL>
<DT><CODE>TIME_ERROR</CODE>
<DD>
The precision clock model is not properly set up at the moment, thus the
clock must be considered unsynchronized, and the values should be
treated with care.
sq~wt sys/timex.hxq~xtstruct ntptimeval *tptrtintt
obstack_1growsq~
t¬
To add one character at a time, use the function <CODE>obstack_1grow</CODE>.
It adds a single byte containing <VAR>c</VAR> to the growing object.
sq~wt obstack.hxq~t#struct obstack *obstack-ptr, char ctvoidtobstack_1grow_fastsq~
t´
The function <CODE>obstack_1grow_fast</CODE> adds one byte containing the
character <VAR>c</VAR> to the growing object in obstack <VAR>obstack-ptr</VAR>.
sq~wt obstack.hxq~†t#struct obstack *obstack-ptr, char ctvoidt
obstack_allocsq~
tÌ
This allocates an uninitialized block of <VAR>size</VAR> bytes in an obstack
and returns its address. Here <VAR>obstack-ptr</VAR> specifies which obstack
to allocate the block in; it is the address of the <CODE>struct obstack</CODE>
object which represents the obstack. Each obstack function or macro
requires you to specify an <VAR>obstack-ptr</VAR> as the first argument.
<br><br> This function calls the obstack's <CODE>obstack_chunk_alloc</CODE> function if
it needs to allocate a new chunk of memory; it calls
<CODE>obstack_alloc_failed_handler</CODE> if allocation of memory by
<CODE>obstack_chunk_alloc</CODE> failed.
sq~wt obstack.hxq~�t%struct obstack *obstack-ptr, int sizetvoid *t obstack_basesq~
tô
This function returns the tentative address of the beginning of the
currently growing object in <VAR>obstack-ptr</VAR>. If you finish the object
immediately, it will have that address. If you make it larger first, it
may outgrow the current chunk---then its address will change!
<br><br> If no object is growing, this value says where the next object you
allocate will start (once again assuming it fits in the current
chunk).
sq~wt obstack.hxq~”tstruct obstack *obstack-ptrtvoid *t
obstack_blanksq~
tš
The most basic function for adding to a growing object is
<CODE>obstack_blank</CODE>, which adds space without initializing it.
sq~wt obstack.hxq~›t%struct obstack *obstack-ptr, int sizetvoidtobstack_blank_fastsq~
tµ
The function <CODE>obstack_blank_fast</CODE> adds <VAR>size</VAR> bytes to the
growing object in obstack <VAR>obstack-ptr</VAR> without initializing them.
sq~wt obstack.hxq~¢t%struct obstack *obstack-ptr, int sizetvoidt obstack_copysq~
t
This allocates a block and initializes it by copying <VAR>size</VAR>
bytes of data starting at <VAR>address</VAR>. It calls
<CODE>obstack_alloc_failed_handler</CODE> if allocation of memory by
<CODE>obstack_chunk_alloc</CODE> failed.
sq~wt obstack.hxq~©t4struct obstack *obstack-ptr, void *address, int sizetvoid *t
obstack_copy0sq~
t²
Like <CODE>obstack_copy</CODE>, but appends an extra byte containing a null
character. This extra byte is not counted in the argument <VAR>size</VAR>.
sq~wt obstack.hxq~°t4struct obstack *obstack-ptr, void *address, int sizetvoid *tobstack_finishsq~
tª
When you are finished growing the object, use the function
<CODE>obstack_finish</CODE> to close it off and return its final address.
<br><br> Once you have finished the object, the obstack is available for ordinary
allocation or for growing another object.
<br><br> This function can return a null pointer under the same conditions as
<CODE>obstack_alloc</CODE> .
sq~wt obstack.hxq~·tstruct obstack *obstack-ptrtvoid *t obstack_freesq~
tL
If <VAR>object</VAR> is a null pointer, everything allocated in the obstack
is freed. Otherwise, <VAR>object</VAR> must be the address of an object
allocated in the obstack. Then <VAR>object</VAR> is freed, along with
everything allocated in <VAR>obstack</VAR> since <VAR>object</VAR>.
sq~wt obstack.hxq~¾t)struct obstack *obstack-ptr, void *objecttvoidt obstack_growsq~
t
To add a block of initialized space, use <CODE>obstack_grow</CODE>, which is
the growing-object analogue of <CODE>obstack_copy</CODE>. It adds <VAR>size</VAR>
bytes of data to the growing object, copying the contents from
<VAR>data</VAR>.
sq~wt obstack.hxq~Åt1struct obstack *obstack-ptr, void *data, int sizetvoidt
obstack_grow0sq~
tÌ
This is the growing-object analogue of <CODE>obstack_copy0</CODE>. It adds
<VAR>size</VAR> bytes copied from <VAR>data</VAR>, followed by an additional null
character.
sq~wt obstack.hxq~Ìt1struct obstack *obstack-ptr, void *data, int sizetvoidt obstack_initsq~
tÎ
Initialize obstack <VAR>obstack-ptr</VAR> for allocation of objects. This
function calls the obstack's <CODE>obstack_chunk_alloc</CODE> function. If
allocation of memory fails, the function pointed to by
<CODE>obstack_alloc_failed_handler</CODE> is called. The <CODE>obstack_init</CODE>
function always returns 1 (Compatibility notice: Former versions of
obstack returned 0 if allocation failed).
sq~wt obstack.hxq~Ótstruct obstack *obstack-ptrtinttobstack_int_growsq~
t
A single value of type <CODE>int</CODE> can be added by using the
<CODE>obstack_int_grow</CODE> function. It adds <CODE>sizeof (int)</CODE> bytes to
the growing object and initializes them with the value of <VAR>data</VAR>.
sq~wt obstack.hxq~Út%struct obstack *obstack-ptr, int datatvoidtobstack_int_grow_fastsq~
tÙ
The function <CODE>obstack_int_grow_fast</CODE> adds <CODE>sizeof (int)</CODE> bytes
containing the value of <VAR>data</VAR> to the growing object in obstack
<VAR>obstack-ptr</VAR>.
sq~wt obstack.hxq~át%struct obstack *obstack-ptr, int datatvoidtobstack_next_freesq~
t=
This function returns the address of the first free byte in the current
chunk of obstack <VAR>obstack-ptr</VAR>. This is the end of the currently
growing object. If no object is growing, <CODE>obstack_next_free</CODE>
returns the same value as <CODE>obstack_base</CODE>.
sq~wt obstack.hxq~ètstruct obstack *obstack-ptrtvoid *tobstack_object_sizesq~
t
This function returns the size in bytes of the currently growing object.
This is equivalent to
<br><br> <pre><br>
obstack_next_free (<VAR>obstack-ptr</VAR>) - obstack_base (<VAR>obstack-ptr</VAR>)<br>
</pre>
sq~wt obstack.hxtobstack_object_sizetstruct obstack *obstack-ptrtinttobstack_printfsq~
tK
This function is similar to <CODE>asprintf</CODE>, except that it uses the
obstack <VAR>obstack</VAR> to allocate the space. .
<br><br> The characters are written onto the end of the current object.
To get at them, you must finish the object with <CODE>obstack_finish</CODE>
.
sq~wtstdio.hxq~÷t2struct obstack *obstack, const char *template, ...tinttobstack_ptr_growsq~
tÎ
Adding the value of a pointer one can use the function
<CODE>obstack_ptr_grow</CODE>. It adds <CODE>sizeof (void *)</CODE> bytes
containing the value of <VAR>data</VAR>.
sq~wt obstack.hxq~þt'struct obstack *obstack-ptr, void *datatvoidtobstack_ptr_grow_fastsq~
tÜ
The function <CODE>obstack_ptr_grow_fast</CODE> adds <CODE>sizeof (void *)</CODE>
bytes containing the value of <VAR>data</VAR> to the growing object in
obstack <VAR>obstack-ptr</VAR>.
sq~wt obstack.hxq~t'struct obstack *obstack-ptr, void *datatvoidt obstack_roomsq~
tà
This returns the number of bytes that can be added safely to the current
growing object (or to an object about to be started) in obstack
<VAR>obstack</VAR> using the fast growth functions.
sq~wt obstack.hxq~ tstruct obstack *obstack-ptrtinttobstack_vprintfsq~
tÎ
The <CODE>obstack_vprintf</CODE> function is the equivalent of
<CODE>obstack_printf</CODE> with the variable argument list specified directly
as for <CODE>vprintf</CODE>.
sq~wtstdio.hxq~t9struct obstack *obstack, const char *template, va_list aptintton_exitsq~
t)
This function is a somewhat more powerful variant of <CODE>atexit</CODE>. It
accepts two arguments, a function <VAR>function</VAR> and an arbitrary
pointer <VAR>arg</VAR>. At normal program termination, the <VAR>function</VAR> is
called with two arguments: the <VAR>status</VAR> value passed to <CODE>exit</CODE>,
and the <VAR>arg</VAR>.
<br><br> This function is included in the GNU C library only for compatibility
for SunOS, and may not be supported by other implementations.
sq~wtstdlib.hxq~t2void (*function)(int status, void *arg), void *argtinttopensq~
t|
The <CODE>open</CODE> function creates and returns a new file descriptor
for the file named by <VAR>filename</VAR>. Initially, the file position
indicator for the file is at the beginning of the file. The argument
<VAR>mode</VAR> is used only when a file is created, but it doesn't hurt
to supply the argument in any case.
<br><br> The <VAR>flags</VAR> argument controls how the file is to be opened. This is
a bit mask; you create the value by the bitwise OR of the appropriate
parameters (using the <samp>|</samp> operator in C).
, for the parameters available.
<br><br> The normal return value from <CODE>open</CODE> is a non-negative integer file
descriptor. In the case of an error, a value of -1 is returned
instead. In addition to the usual file name errors , the following <CODE>errno</CODE> error conditions are defined
for this function:
<br><br> <DL>
<DT><CODE>EACCES</CODE>
<DD>
The file exists but is not readable/writable as requested by the <VAR>flags</VAR>
argument, the file does not exist and the directory is unwritable so
it cannot be created.
<br><br> <LI> EEXIST
Both <CODE>O_CREAT</CODE> and <CODE>O_EXCL</CODE> are set, and the named file already
exists.
<br><br> <LI> EINTR
The <CODE>open</CODE> operation was interrupted by a signal.
.
<br><br> <LI> EISDIR
The <VAR>flags</VAR> argument specified write access, and the file is a directory.
<br><br> <LI> EMFILE
The process has too many files open.
The maximum number of file descriptors is controlled by the
<CODE>RLIMIT_NOFILE</CODE> resource limit; .
<br><br> <LI> ENFILE
The entire system, or perhaps the file system which contains the
directory, cannot support any additional open files at the moment.
(This problem cannot happen on the GNU system.)
<br><br> <LI> ENOENT
The named file does not exist, and <CODE>O_CREAT</CODE> is not specified.
<br><br> <LI> ENOSPC
The directory or file system that would contain the new file cannot be
extended, because there is no disk space left.
<br><br> <LI> ENXIO
<CODE>O_NONBLOCK</CODE> and <CODE>O_WRONLY</CODE> are both set in the <VAR>flags</VAR>
argument, the file named by <VAR>filename</VAR> is a FIFO , and no process has the file open for reading.
<br><br> <LI> EROFS
The file resides on a read-only file system and any of <CODE>O_WRONLY</CODE>,
<CODE>O_RDWR</CODE>, and <CODE>O_TRUNC</CODE> are set in the <VAR>flags</VAR> argument,
or <CODE>O_CREAT</CODE> is set and the file does not already exist.
<br><br> <br><br> If on a 32 bit machine the sources are translated with
<CODE>_FILE_OFFSET_BITS == 64</CODE> the function <CODE>open</CODE> returns a file
descriptor opened in the large file mode which enables the file handling
functions to use files up to 2^63 bytes in size and offset from
-2^63 to 2^63. This happens transparently for the user
since all of the lowlevel file handling functions are equally replaced.
<br><br> This function is a cancellation point in multi-threaded programs. This
is a problem if the thread allocates some resources (like memory, file
descriptors, semaphores or whatever) at the time <CODE>open</CODE> is
called. If the thread gets canceled these resources stay allocated
until the program ends. To avoid this calls to <CODE>open</CODE> should be
protected using cancellation handlers.
<br><br> The <CODE>open</CODE> function is the underlying primitive for the <CODE>fopen</CODE>
and <CODE>freopen</CODE> functions, that create streams.
sq~wtfcntl.hxq~!t.const char *filename, int flags[, mode_t mode]tinttopen64sq~
tp
This function is similar to <CODE>open</CODE>. It returns a file descriptor
which can be used to access the file named by <VAR>filename</VAR>. The only
difference is that on 32 bit systems the file is opened in the
large file mode. I.e., file length and file offsets can exceed 31 bits.
<br><br> When the sources are translated with <CODE>_FILE_OFFSET_BITS == 64</CODE> this
function is actually available under the name <CODE>open</CODE>. I.e., the
new, extended API using 64 bit file sizes and offsets transparently
replaces the old API.
sq~wtfcntl.hxq~(t.const char *filename, int flags[, mode_t mode]tinttopen_memstreamsq~
t±
This function opens a stream for writing to a buffer. The buffer is
allocated dynamically and grown as necessary, using <CODE>malloc</CODE>.
After you've closed the stream, this buffer is your responsibility to
clean up using <CODE>free</CODE> or <CODE>realloc</CODE>. .
<br><br> When the stream is closed with <CODE>fclose</CODE> or flushed with
<CODE>fflush</CODE>, the locations <VAR>ptr</VAR> and <VAR>sizeloc</VAR> are updated to
contain the pointer to the buffer and its size. The values thus stored
remain valid only as long as no further output on the stream takes
place. If you do more output, you must flush the stream again to store
new values before you use them again.
<br><br> A null character is written at the end of the buffer. This null character
is <EM>not</EM> included in the size value stored at <VAR>sizeloc</VAR>.
<br><br> You can move the stream's file position with <CODE>fseek</CODE> or
<CODE>fseeko</CODE> . Moving the file position past
the end of the data already written fills the intervening space with
zeroes.
sq~wtstdio.hxq~/tchar **ptr, size_t *sizeloctFILE *topen_obstack_streamsq~
tî
This function opens a stream for writing data into the obstack <VAR>obstack</VAR>.
This starts an object in the obstack and makes it grow as data is
written .
<br><br> Calling <CODE>fflush</CODE> on this stream updates the current size of the
object to match the amount of data that has been written. After a call
to <CODE>fflush</CODE>, you can examine the object temporarily.
<br><br> You can move the file position of an obstack stream with <CODE>fseek</CODE> or
<CODE>fseeko</CODE> . Moving the file position past
the end of the data written fills the intervening space with zeros.
<br><br> To make the object permanent, update the obstack with <CODE>fflush</CODE>, and
then use <CODE>obstack_finish</CODE> to finalize the object and get its address.
The following write to the stream starts a new object in the obstack,
and later writes add to that object until you do another <CODE>fflush</CODE>
and <CODE>obstack_finish</CODE>.
<br><br> But how do you find out how long the object is? You can get the length
in bytes by calling <CODE>obstack_object_size</CODE> , or you can null-terminate the object like this:
<br><br> <pre><br>
obstack_1grow (<VAR>obstack</VAR>, 0);<br>
</pre>
<br><br> Whichever one you do, you must do it <EM>before</EM> calling
<CODE>obstack_finish</CODE>. (You can do both if you wish.)
sq~wtstdio.hxq~6tstruct obstack *obstacktFILE *topendirsq~
tê
The <CODE>opendir</CODE> function opens and returns a directory stream for
reading the directory whose file name is <VAR>dirname</VAR>. The stream has
type <CODE>DIR *</CODE>.
<br><br> If unsuccessful, <CODE>opendir</CODE> returns a null pointer. In addition to
the usual file name errors , the
following <CODE>errno</CODE> error conditions are defined for this function:
<br><br> <DL>
<DT><CODE>EACCES</CODE>
<DD>
Read permission is denied for the directory named by <CODE>dirname</CODE>.
<br><br> <LI> EMFILE
The process has too many files open.
<br><br> <LI> ENFILE
The entire system, or perhaps the file system which contains the
directory, cannot support any additional open files at the moment.
(This problem cannot happen on the GNU system.)
<br><br> <LI> ENOMEM
Not enough memory available.
<br><br> The <CODE>DIR</CODE> type is typically implemented using a file descriptor,
and the <CODE>opendir</CODE> function in terms of the <CODE>open</CODE> function.
. Directory streams and the underlying
file descriptors are closed on <CODE>exec</CODE> .
sq~wtdirent.hxq~=tconst char *dirnametDIR *topenlogsq~
te
<br><br> <CODE>openlog</CODE> opens or reopens a connection to Syslog in preparation
for submitting messages.
<br><br> <VAR>ident</VAR> is an arbitrary identification string which future
<CODE>syslog</CODE> invocations will prefix to each message. This is intended
to identify the source of the message, and people conventionally set it
to the name of the program that will submit the messages.
<br><br> If <VAR>ident</VAR> is NULL, or if <CODE>openlog</CODE> is not called, the default
identification string used in Syslog messages will be the program name,
taken from argv[0].
<br><br> Please note that the string pointer <VAR>ident</VAR> will be retained
internally by the Syslog routines. You must not free the memory that
<VAR>ident</VAR> points to. It is also dangerous to pass a reference to an
automatic variable since leaving the scope would mean ending the
lifetime of the variable. If you want to change the <VAR>ident</VAR> string,
you must call <CODE>openlog</CODE> again; overwriting the string pointed to by
<VAR>ident</VAR> is not thread-safe.
<br><br> You can cause the Syslog routines to drop the reference to <VAR>ident</VAR> and
go back to the default string (the program name taken from argv[0]), by
calling <CODE>closelog</CODE>: .
<br><br> In particular, if you are writing code for a shared library that might get
loaded and then unloaded (e.g. a PAM module), and you use <CODE>openlog</CODE>,
you must call <CODE>closelog</CODE> before any point where your library might
get unloaded, as in this example:
<br><br> <pre><br>
#include <syslog.h><br>
<br><br> void<br>
shared_library_function (void)<br>
{<br>
openlog ("mylibrary", option, priority);<br>
<br><br> syslog (LOG_INFO, "shared library has been invoked");<br>
<br><br> closelog ();<br>
}<br>
</pre>
<br><br> Without the call to <CODE>closelog</CODE>, future invocations of <CODE>syslog</CODE>
by the program using the shared library may crash, if the library gets
unloaded and the memory containing the string <CODE>"mylibrary"</CODE> becomes
unmapped. This is a limitation of the BSD syslog interface.
<br><br> <CODE>openlog</CODE> may or may not open the <TT>/dev/log</TT> socket, depending
on <VAR>option</VAR>. If it does, it tries to open it and connect it as a
stream socket. If that doesn't work, it tries to open it and connect it
as a datagram socket. The socket has the ``Close on Exec'' attribute,
so the kernel will close it if the process performs an exec.
<br><br> You don't have to use <CODE>openlog</CODE>. If you call <CODE>syslog</CODE> without
having called <CODE>openlog</CODE>, <CODE>syslog</CODE> just opens the connection
implicitly and uses defaults for the information in <VAR>ident</VAR> and
<VAR>options</VAR>.
<br><br> <VAR>options</VAR> is a bit string, with the bits as defined by the following
single bit masks:
<br><br> <DL>
<DT><CODE>LOG_PERROR</CODE>
<DD>
If on, <CODE>openlog</CODE> sets up the connection so that any <CODE>syslog</CODE>
on this connection writes its message to the calling process' Standard
Error stream in addition to submitting it to Syslog. If off, <CODE>syslog</CODE>
does not write the message to Standard Error.
<br><br> <LI> LOG_CONS
If on, <CODE>openlog</CODE> sets up the connection so that a <CODE>syslog</CODE> on
this connection that fails to submit a message to Syslog writes the
message instead to system console. If off, <CODE>syslog</CODE> does not write
to the system console (but of course Syslog may write messages it
receives to the console).
<br><br> <LI> LOG_PID
When on, <CODE>openlog</CODE> sets up the connection so that a <CODE>syslog</CODE>
on this connection inserts the calling process' Process ID (PID) into
the message. When off, <CODE>openlog</CODE> does not insert the PID.
<br><br> <LI> LOG_NDELAY
When on, <CODE>openlog</CODE> opens and connects the <TT>/dev/log</TT> socket.
When off, a future <CODE>syslog</CODE> call must open and connect the socket.
<br><br> Portability note: In early systems, the sense of this bit was
exactly the opposite.
<br><br> <LI> LOG_ODELAY
This bit does nothing. It exists for backward compatibility.
<br><br>
<br><br> If any other bit in <VAR>options</VAR> is on, the result is undefined.
<br><br> <VAR>facility</VAR> is the default facility code for this connection. A
<CODE>syslog</CODE> on this connection that specifies default facility causes
this facility to be associated with the message. See <CODE>syslog</CODE> for
possible values. A value of zero means the default default, which is
<CODE>LOG_USER</CODE>.
<br><br> If a Syslog connection is already open when you call <CODE>openlog</CODE>,
<CODE>openlog</CODE> ``reopens'' the connection. Reopening is like opening
except that if you specify zero for the default facility code, the
default facility code simply remains unchanged and if you specify
LOG_NDELAY and the socket is already open and connected, <CODE>openlog</CODE>
just leaves it that way.
<br><br> <br><br>
sq~wtsyslog.hxq~Dt+const char *ident, int option, int facilitytvoidtopenptysq~
tõ
This function allocates and opens a pseudo-terminal pair, returning the
file descriptor for the master in <VAR>*amaster</VAR>, and the file
descriptor for the slave in <VAR>*aslave</VAR>. If the argument <VAR>name</VAR>
is not a null pointer, the file name of the slave pseudo-terminal
device is stored in <CODE>*name</CODE>. If <VAR>termp</VAR> is not a null pointer,
the terminal attributes of the slave are set to the ones specified in
the structure that <VAR>termp</VAR> points to .
Likewise, if the <VAR>winp</VAR> is not a null pointer, the screen size of
the slave is set to the values specified in the structure that
<VAR>winp</VAR> points to.
<br><br> The normal return value from <CODE>openpty</CODE> is 0; a value of
-1 is returned in case of failure. The following <CODE>errno</CODE>
conditions are defined for this function:
<br><br> <DL>
<DT><CODE>ENOENT</CODE>
<DD>
There are no free pseudo-terminal pairs available.
<br><br> Warning: Using the <CODE>openpty</CODE> function with <VAR>name</VAR> not
set to <CODE>NULL</CODE> is very dangerous because it provides no
protection against overflowing the string <VAR>name</VAR>. You should use
the <CODE>ttyname</CODE> function on the file descriptor returned in
<VAR>*slave</VAR> to find out the file name of the slave pseudo-terminal
device instead.
sq~wtpty.hxq~Kt^int *amaster, int *aslave, char *name, const struct termios *termp, const struct winsize *winptinttparse_printf_formatsq~
t
This function returns information about the number and types of
arguments expected by the <CODE>printf</CODE> template string <VAR>template</VAR>.
The information is stored in the array <VAR>argtypes</VAR>; each element of
this array describes one argument. This information is encoded using
the various <samp>PA_</samp> macros, listed below.
<br><br> The argument <VAR>n</VAR> specifies the number of elements in the array
<VAR>argtypes</VAR>. This is the maximum number of elements that
<CODE>parse_printf_format</CODE> will try to write.
<br><br> <CODE>parse_printf_format</CODE> returns the total number of arguments required
by <VAR>template</VAR>. If this number is greater than <VAR>n</VAR>, then the
information returned describes only the first <VAR>n</VAR> arguments. If you
want information about additional arguments, allocate a bigger
array and call <CODE>parse_printf_format</CODE> again.
sq~wtprintf.hxq~Rt-const char *template, size_t n, int *argtypestsize_ttpathconfsq~
t^
This function is used to inquire about the limits that apply to
the file named <VAR>filename</VAR>.
<br><br> The <VAR>parameter</VAR> argument should be one of the <samp>_PC_</samp> constants
listed below.
<br><br> The normal return value from <CODE>pathconf</CODE> is the value you requested.
A value of <CODE>-1</CODE> is returned both if the implementation does not
impose a limit, and in case of an error. In the former case,
<CODE>errno</CODE> is not set, while in the latter case, <CODE>errno</CODE> is set
to indicate the cause of the problem. So the only way to use this
function robustly is to store <CODE>0</CODE> into <CODE>errno</CODE> just before
calling it.
<br><br> Besides the usual file name errors ,
the following error condition is defined for this function:
<br><br> <DL>
<DT><CODE>EINVAL</CODE>
<DD>
The value of <VAR>parameter</VAR> is invalid, or the implementation doesn't
support the <VAR>parameter</VAR> for the specific file.
sq~wtunistd.ht unistdh.htlimits.htdirent.htstdio.hxq~Yt#const char *filename, int parametertlong inttpausesq~
t
The <CODE>pause</CODE> function suspends program execution until a signal
arrives whose action is either to execute a handler function, or to
terminate the process.
<br><br> If the signal causes a handler function to be executed, then
<CODE>pause</CODE> returns. This is considered an unsuccessful return (since
``successful'' behavior would be to suspend the program forever), so the
return value is <CODE>-1</CODE>. Even if you specify that other primitives
should resume when a system handler returns , this has no effect on <CODE>pause</CODE>; it always fails when a
signal is handled.
<br><br> The following <CODE>errno</CODE> error conditions are defined for this function:
<br><br> <DL>
<DT><CODE>EINTR</CODE>
<DD>
The function was interrupted by delivery of a signal.
<br><br> If the signal causes program termination, <CODE>pause</CODE> doesn't return
(obviously).
<br><br> This function is a cancellation point in multithreaded programs. This
is a problem if the thread allocates some resources (like memory, file
descriptors, semaphores or whatever) at the time <CODE>pause</CODE> is
called. If the thread gets cancelled these resources stay allocated
until the program ends. To avoid this calls to <CODE>pause</CODE> should be
protected using cancellation handlers.
<br><br> The <CODE>pause</CODE> function is declared in <TT>unistd.h</TT>.
sq~wtunistd.hxq~dttinttpclosesq~
tð
The <CODE>pclose</CODE> function is used to close a stream created by <CODE>popen</CODE>.
It waits for the child process to terminate and returns its status value,
as for the <CODE>system</CODE> function.
sq~wtstdio.hxq~kt FILE *streamtinttperrorsq~
t7
This function prints an error message to the stream <CODE>stderr</CODE>;
see Standard Streams. The orientation of <CODE>stderr</CODE> is not
changed.
<br><br> If you call <CODE>perror</CODE> with a <VAR>message</VAR> that is either a null
pointer or an empty string, <CODE>perror</CODE> just prints the error message
corresponding to <CODE>errno</CODE>, adding a trailing newline.
<br><br> If you supply a non-null <VAR>message</VAR> argument, then <CODE>perror</CODE>
prefixes its output with this string. It adds a colon and a space
character to separate the <VAR>message</VAR> from the error string corresponding
to <CODE>errno</CODE>.
<br><br> The function <CODE>perror</CODE> is declared in <TT>stdio.h</TT>.
sq~wtstdio.hxq~rtconst char *messagetvoidtpipesq~
tä
The <CODE>pipe</CODE> function creates a pipe and puts the file descriptors
for the reading and writing ends of the pipe (respectively) into
<CODE><VAR>filedes</VAR>[0]</CODE> and <CODE><VAR>filedes</VAR>[1]</CODE>.
<br><br> An easy way to remember that the input end comes first is that file
descriptor <CODE>0</CODE> is standard input, and file descriptor <CODE>1</CODE> is
standard output.
<br><br> If successful, <CODE>pipe</CODE> returns a value of <CODE>0</CODE>. On failure,
<CODE>-1</CODE> is returned. The following <CODE>errno</CODE> error conditions are
defined for this function:
<br><br> <DL>
<DT><CODE>EMFILE</CODE>
<DD>
The process has too many files open.
<br><br> <LI> ENFILE
There are too many open files in the entire system. ,
for more information about <CODE>ENFILE</CODE>. This error never occurs in
the GNU system.
sq~wtunistd.hxq~ytint filedes[2]tinttpopensq~
t—
The <CODE>popen</CODE> function is closely related to the <CODE>system</CODE>
function; see Running a Command. It executes the shell command
<VAR>command</VAR> as a subprocess. However, instead of waiting for the
command to complete, it creates a pipe to the subprocess and returns a
stream that corresponds to that pipe.
<br><br> If you specify a <VAR>mode</VAR> argument of <CODE>"r"</CODE>, you can read from the
stream to retrieve data from the standard output channel of the subprocess.
The subprocess inherits its standard input channel from the parent process.
<br><br> Similarly, if you specify a <VAR>mode</VAR> argument of <CODE>"w"</CODE>, you can
write to the stream to send data to the standard input channel of the
subprocess. The subprocess inherits its standard output channel from
the parent process.
<br><br> In the event of an error <CODE>popen</CODE> returns a null pointer. This
might happen if the pipe or stream cannot be created, if the subprocess
cannot be forked, or if the program cannot be executed.
sq~wtstdio.hxq~€t%const char *command, const char *modetFILE *tposix_memalignsq~
tÊ
The <CODE>posix_memalign</CODE> function is similar to the <CODE>memalign</CODE>
function in that it returns a buffer of <VAR>size</VAR> bytes aligned to a
multiple of <VAR>alignment</VAR>. But it adds one requirement to the
parameter <VAR>alignment</VAR>: the value must be a power of two multiple of
<CODE>sizeof (void *)</CODE>.
<br><br> If the function succeeds in allocation memory a pointer to the allocated
memory is returned in <CODE>*<VAR>memptr</VAR></CODE> and the return value is zero.
Otherwise the function returns an error value indicating the problem.
<br><br> This function was introduced in POSIX 1003.1d.
sq~wtstdlib.hxq~‡t,void **memptr, size_t alignment, size_t sizetinttpowsq~
tÅ
These are general exponentiation functions, returning <VAR>base</VAR> raised
to <VAR>power</VAR>.
<br><br> Mathematically, <CODE>pow</CODE> would return a complex number when <VAR>base</VAR>
is negative and <VAR>power</VAR> is not an integral value. <CODE>pow</CODE> can't
do that, so instead it signals a domain error. <CODE>pow</CODE> may also
underflow or overflow the destination type.
sq~wtmath.hxq~Žtdouble base, double powertdoubletpow10sq~
tf
These functions compute <CODE>10</CODE> raised to the power <VAR>x</VAR>.
Mathematically, <CODE>exp10 (x)</CODE> is the same as <CODE>exp (x * log (10))</CODE>.
<br><br> These functions are GNU extensions. The name <CODE>exp10</CODE> is
preferred, since it is analogous to <CODE>exp</CODE> and <CODE>exp2</CODE>.
sq~wtmath.hxq~•tdouble xtdoubletpow10fsq~
tf
These functions compute <CODE>10</CODE> raised to the power <VAR>x</VAR>.
Mathematically, <CODE>exp10 (x)</CODE> is the same as <CODE>exp (x * log (10))</CODE>.
<br><br> These functions are GNU extensions. The name <CODE>exp10</CODE> is
preferred, since it is analogous to <CODE>exp</CODE> and <CODE>exp2</CODE>.
sq~wtmath.hxq~œtfloat xtfloattpow10lsq~
tf
These functions compute <CODE>10</CODE> raised to the power <VAR>x</VAR>.
Mathematically, <CODE>exp10 (x)</CODE> is the same as <CODE>exp (x * log (10))</CODE>.
<br><br> These functions are GNU extensions. The name <CODE>exp10</CODE> is
preferred, since it is analogous to <CODE>exp</CODE> and <CODE>exp2</CODE>.
sq~wtmath.hxq~£t
long double xt long doubletpowfsq~
tÅ
These are general exponentiation functions, returning <VAR>base</VAR> raised
to <VAR>power</VAR>.
<br><br> Mathematically, <CODE>pow</CODE> would return a complex number when <VAR>base</VAR>
is negative and <VAR>power</VAR> is not an integral value. <CODE>pow</CODE> can't
do that, so instead it signals a domain error. <CODE>pow</CODE> may also
underflow or overflow the destination type.
sq~wtmath.hxq~ªtfloat base, float powertfloattpowlsq~
tÅ
These are general exponentiation functions, returning <VAR>base</VAR> raised
to <VAR>power</VAR>.
<br><br> Mathematically, <CODE>pow</CODE> would return a complex number when <VAR>base</VAR>
is negative and <VAR>power</VAR> is not an integral value. <CODE>pow</CODE> can't
do that, so instead it signals a domain error. <CODE>pow</CODE> may also
underflow or overflow the destination type.
sq~wtmath.hxq~±t#long double base, long double powert long doubletpreadsq~
t4
The <CODE>pread</CODE> function is similar to the <CODE>read</CODE> function. The
first three arguments are identical, and the return values and error
codes also correspond.
<br><br> The difference is the fourth argument and its handling. The data block
is not read from the current position of the file descriptor
<CODE>filedes</CODE>. Instead the data is read from the file starting at
position <VAR>offset</VAR>. The position of the file descriptor itself is
not affected by the operation. The value is the same as before the call.
<br><br> When the source file is compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> the
<CODE>pread</CODE> function is in fact <CODE>pread64</CODE> and the type
<CODE>off_t</CODE> has 64 bits, which makes it possible to handle files up to
2^63 bytes in length.
<br><br> The return value of <CODE>pread</CODE> describes the number of bytes read.
In the error case it returns -1 like <CODE>read</CODE> does and the
error codes are also the same, with these additions:
<br><br> <DL>
<DT><CODE>EINVAL</CODE>
<DD>
The value given for <VAR>offset</VAR> is negative and therefore illegal.
<br><br> <LI> ESPIPE
The file descriptor <VAR>filedes</VAR> is associate with a pipe or a FIFO and
this device does not allow positioning of the file pointer.
<br><br> The function is an extension defined in the Unix Single Specification
version 2.
sq~wtunistd.hxq~¸t4int filedes, void *buffer, size_t size, off_t offsettssize_ttpread64sq~
t2
This function is similar to the <CODE>pread</CODE> function. The difference
is that the <VAR>offset</VAR> parameter is of type <CODE>off64_t</CODE> instead of
<CODE>off_t</CODE> which makes it possible on 32 bit machines to address
files larger than 2^31 bytes and up to 2^63 bytes. The
file descriptor <CODE>filedes</CODE> must be opened using <CODE>open64</CODE> since
otherwise the large offsets possible with <CODE>off64_t</CODE> will lead to
errors with a descriptor in small file mode.
<br><br> When the source file is compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> on a
32 bit machine this function is actually available under the name
<CODE>pread</CODE> and so transparently replaces the 32 bit interface.
sq~wtunistd.hxq~¿t6int filedes, void *buffer, size_t size, off64_t offsettssize_ttprintfsq~
t+
The <CODE>printf</CODE> function prints the optional arguments under the
control of the template string <VAR>template</VAR> to the stream
<CODE>stdout</CODE>. It returns the number of characters printed, or a
negative value if there was an output error.
sq~wtstdio.hxq~Ætconst char *template, ...tintt printf_sizesq~
t¾
Print a given floating point number as for the format <CODE>%f</CODE> except
that there is a postfix character indicating the divisor for the
number to make this less than 1000. There are two possible divisors:
powers of 1024 or powers of 1000. Which one is used depends on the
format character specified while registered this handler. If the
character is of lower case, 1024 is used. For upper case characters,
1000 is used.
<br><br> The postfix tag corresponds to bytes, kilobytes, megabytes, gigabytes,
etc. The full table is:
<br><br>
<DL>
<DT><pre>low Multiplier From Upper Multiplier</pre>
<DD><br> <DT><pre>' ' 1 ' ' 1</pre>
<DD><br> <DT><pre>k 2^10 (1024) kilo K 10^3 (1000)</pre>
<DD><br> <DT><pre>m 2^20 mega M 10^6</pre>
<DD><br> <DT><pre>g 2^30 giga G 10^9</pre>
<DD><br> <DT><pre>t 2^40 tera T 10^12</pre>
<DD><br> <DT><pre>p 2^50 peta P 10^15</pre>
<DD><br> <DT><pre>e 2^60 exa E 10^18</pre>
<DD><br> <DT><pre>z 2^70 zetta Z 10^21</pre>
<DD><br> <DT><pre>y 2^80 yotta Y 10^24</pre>
<DD><br> </DL>
<br><br> The default precision is 3, i.e., 1024 is printed with a lower-case
format character as if it were <CODE>%.3fk</CODE> and will yield <CODE>1.000k</CODE>.
sq~wtprintf.hxq~ÍtAFILE *fp, const struct printf_info *info, const void *const *argstinttprintf_size_infosq~
tå
This function will return in <VAR>argtypes</VAR> the information about the
used parameters in the way the <CODE>vfprintf</CODE> implementation expects
it. The format always takes one argument.
sq~wtprintf.hxq~Ôt7const struct printf_info *info, size_t n, int *argtypestinttpsignalsq~
t/
This function prints a message describing the signal <VAR>signum</VAR> to the
standard error output stream <CODE>stderr</CODE>; see Standard Streams.
<br><br> If you call <CODE>psignal</CODE> with a <VAR>message</VAR> that is either a null
pointer or an empty string, <CODE>psignal</CODE> just prints the message
corresponding to <VAR>signum</VAR>, adding a trailing newline.
<br><br> If you supply a non-null <VAR>message</VAR> argument, then <CODE>psignal</CODE>
prefixes its output with this string. It adds a colon and a space
character to separate the <VAR>message</VAR> from the string corresponding
to <VAR>signum</VAR>.
<br><br> This function is a BSD feature, declared in the header file <TT>signal.h</TT>.
sq~wtsignal.hxq~Ûtint signum, const char *messagetvoidtptsnamesq~
t�
If the file descriptor <VAR>filedes</VAR> is associated with a
master pseudo-terminal device, the <CODE>ptsname</CODE> function returns a
pointer to a statically-allocated, null-terminated string containing the
file name of the associated slave pseudo-terminal file. This string
might be overwritten by subsequent calls to <CODE>ptsname</CODE>.
sq~wtstdlib.hxq~ât int filedestchar *t ptsname_rsq~
t"
The <CODE>ptsname_r</CODE> function is similar to the <CODE>ptsname</CODE> function
except that it places its result into the user-specified buffer starting
at <VAR>buf</VAR> with length <VAR>len</VAR>.
<br><br> This function is a GNU extension.
sq~wtstdlib.hxq~ét"int filedes, char *buf, size_t lentinttputcsq~
t„
This is just like <CODE>fputc</CODE>, except that most systems implement it as
a macro, making it faster. One consequence is that it may evaluate the
<VAR>stream</VAR> argument more than once, which is an exception to the
general rule for macros. <CODE>putc</CODE> is usually the best function to
use for writing a single character.
sq~wtstdio.hxq~ðtint c, FILE *streamtintt
putc_unlockedsq~
t¦
The <CODE>putc_unlocked</CODE> function is equivalent to the <CODE>putc</CODE>
function except that it does not implicitly lock the stream.
sq~wtstdio.hxq~÷tint c, FILE *streamtinttputcharsq~
t¨
The <CODE>putchar</CODE> function is equivalent to <CODE>putc</CODE> with
<CODE>stdout</CODE> as the value of the <VAR>stream</VAR> argument.
sq~wtstdio.hxq~þtint ctinttputchar_unlockedsq~
t¬
The <CODE>putchar_unlocked</CODE> function is equivalent to the <CODE>putchar</CODE>
function except that it does not implicitly lock the stream.
sq~wtstdio.hxq~tint ctinttputenvsq~
tÜ
The <CODE>putenv</CODE> function adds or removes definitions from the environment.
If the <VAR>string</VAR> is of the form <samp><VAR>name</VAR>=<VAR>value</VAR></samp>, the
definition is added to the environment. Otherwise, the <VAR>string</VAR> is
interpreted as the name of an environment variable, and any definition
for this variable in the environment is removed.
<br><br> The difference to the <CODE>setenv</CODE> function is that the exact string
given as the parameter <VAR>string</VAR> is put into the environment. If the
user should change the string after the <CODE>putenv</CODE> call this will
reflect in automatically in the environment. This also requires that
<VAR>string</VAR> is no automatic variable which scope is left before the
variable is removed from the environment. The same applies of course to
dynamically allocated variables which are freed later.
<br><br> This function is part of the extended Unix interface. Since it was also
available in old SVID libraries you should define either
<VAR>_XOPEN_SOURCE</VAR> or <VAR>_SVID_SOURCE</VAR> before including any header.
sq~wtstdlib.hxq~ t char *stringtinttputpwentsq~
t§
This function writes the user entry <CODE>*<VAR>p</VAR></CODE> to the stream
<VAR>stream</VAR>, in the format used for the standard user database
file. The return value is zero on success and nonzero on failure.
<br><br> This function exists for compatibility with SVID. We recommend that you
avoid using it, because it makes sense only on the assumption that the
<CODE>struct passwd</CODE> structure has no members except the standard ones;
on a system which merges the traditional Unix data base with other
extended information about users, adding an entry using this function
would inevitably leave out much of the important information.
<br><br> The group and user ID fields are left empty if the group or user name
starts with a - or +.
<br><br> The function <CODE>putpwent</CODE> is declared in <TT>pwd.h</TT>.
sq~wtpwd.hxq~t$const struct passwd *p, FILE *streamtinttputssq~
tl
The <CODE>puts</CODE> function writes the string <VAR>s</VAR> to the stream
<CODE>stdout</CODE> followed by a newline. The terminating null character of
the string is not written. (Note that <CODE>fputs</CODE> does <EM>not</EM>
write a newline as this function does.)
<br><br> <CODE>puts</CODE> is the most convenient function for printing simple
messages. For example:
<br><br> <pre><br>
puts ("This is a message.");<br>
</pre>
<br><br>
outputs the text <samp>This is a message.</samp> followed by a newline.
sq~wtstdio.hxq~t
const char *stintt pututlinesq~
t
The <CODE>pututline</CODE> function inserts the entry <CODE>*<VAR>utmp</VAR></CODE> at
the appropriate place in the user accounting database. If it finds that
it is not already at the correct place in the database, it uses
<CODE>getutid</CODE> to search for the position to insert the entry, however
this will not modify the static structure returned by <CODE>getutent</CODE>,
<CODE>getutid</CODE> and <CODE>getutline</CODE>. If this search fails, the entry
is appended to the database.
<br><br> The <CODE>pututline</CODE> function returns a pointer to a copy of the entry
inserted in the user accounting database, or a null pointer if the entry
could not be added. The following <CODE>errno</CODE> error conditions are
defined for this function:
<br><br> <DL>
<DT><CODE>EPERM</CODE>
<DD>
The process does not have the appropriate privileges; you cannot modify
the user accounting database.
sq~wtutmp.hxq~!tconst struct utmp *utmpt
struct utmp *t
pututxlinesq~
t)
The <CODE>pututxline</CODE> function is functionally identical to
<CODE>pututline</CODE>, but uses <CODE>struct utmpx</CODE> instead of <CODE>struct
utmp</CODE>. On the GNU system, <CODE>pututxline</CODE> is simply an alias for
<CODE>pututline</CODE>.
sq~wtutmpx.hxq~(tconst struct utmpx *utmptstruct utmpx *tputwsq~
tç
This function writes the word <VAR>w</VAR> (that is, an <CODE>int</CODE>) to
<VAR>stream</VAR>. It is provided for compatibility with SVID, but we
recommend you use <CODE>fwrite</CODE> instead .
sq~wtstdio.hxq~/tint w, FILE *streamtinttputwcsq~
t…
This is just like <CODE>fputwc</CODE>, except that it can be implement as
a macro, making it faster. One consequence is that it may evaluate the
<VAR>stream</VAR> argument more than once, which is an exception to the
general rule for macros. <CODE>putwc</CODE> is usually the best function to
use for writing a single wide character.
sq~wtwchar.hxq~6twchar_t wc, FILE *streamtwint_ttputwc_unlockedsq~
tÜ
The <CODE>putwc_unlocked</CODE> function is equivalent to the <CODE>putwc</CODE>
function except that it does not implicitly lock the stream.
<br><br> This function is a GNU extension.
sq~wtwchar.hxq~=twchar_t wc, FILE *streamtwint_ttputwcharsq~
tª
The <CODE>putwchar</CODE> function is equivalent to <CODE>putwc</CODE> with
<CODE>stdout</CODE> as the value of the <VAR>stream</VAR> argument.
sq~wtwchar.hxq~Dt
wchar_t wctwint_ttputwchar_unlockedsq~
tâ
The <CODE>putwchar_unlocked</CODE> function is equivalent to the <CODE>putwchar</CODE>
function except that it does not implicitly lock the stream.
<br><br> This function is a GNU extension.
sq~wtwchar.hxq~Kt
wchar_t wctwint_ttpwritesq~
t@
The <CODE>pwrite</CODE> function is similar to the <CODE>write</CODE> function. The
first three arguments are identical, and the return values and error codes
also correspond.
<br><br> The difference is the fourth argument and its handling. The data block
is not written to the current position of the file descriptor
<CODE>filedes</CODE>. Instead the data is written to the file starting at
position <VAR>offset</VAR>. The position of the file descriptor itself is
not affected by the operation. The value is the same as before the call.
<br><br> When the source file is compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> the
<CODE>pwrite</CODE> function is in fact <CODE>pwrite64</CODE> and the type
<CODE>off_t</CODE> has 64 bits, which makes it possible to handle files up to
2^63 bytes in length.
<br><br> The return value of <CODE>pwrite</CODE> describes the number of written bytes.
In the error case it returns -1 like <CODE>write</CODE> does and the
error codes are also the same, with these additions:
<br><br> <DL>
<DT><CODE>EINVAL</CODE>
<DD>
The value given for <VAR>offset</VAR> is negative and therefore illegal.
<br><br> <LI> ESPIPE
The file descriptor <VAR>filedes</VAR> is associated with a pipe or a FIFO and
this device does not allow positioning of the file pointer.
<br><br> The function is an extension defined in the Unix Single Specification
version 2.
sq~wtunistd.hxq~Rt:int filedes, const void *buffer, size_t size, off_t offsettssize_ttpwrite64sq~
t5
This function is similar to the <CODE>pwrite</CODE> function. The difference
is that the <VAR>offset</VAR> parameter is of type <CODE>off64_t</CODE> instead of
<CODE>off_t</CODE> which makes it possible on 32 bit machines to address
files larger than 2^31 bytes and up to 2^63 bytes. The
file descriptor <CODE>filedes</CODE> must be opened using <CODE>open64</CODE> since
otherwise the large offsets possible with <CODE>off64_t</CODE> will lead to
errors with a descriptor in small file mode.
<br><br> When the source file is compiled using <CODE>_FILE_OFFSET_BITS == 64</CODE> on a
32 bit machine this function is actually available under the name
<CODE>pwrite</CODE> and so transparently replaces the 32 bit interface.
sq~wtunistd.hxq~Yt<int filedes, const void *buffer, size_t size, off64_t offsettssize_ttqecvtsq~
tõ
This function is equivalent to <CODE>ecvt</CODE> except that it takes a
<CODE>long double</CODE> for the first parameter and that <VAR>ndigit</VAR> is
restricted by the precision of a <CODE>long double</CODE>.
sq~wtstdlib.hxq~`t3long double value, int ndigit, int *decpt, int *negtchar *tqecvt_rsq~
tl
The <CODE>qecvt_r</CODE> function is the same as <CODE>qecvt</CODE>, except
that it places its result into the user-specified buffer pointed to by
<VAR>buf</VAR>, with length <VAR>len</VAR>. The return value is <CODE>-1</CODE> in
case of an error and zero otherwise.
<br><br> This function is a GNU extension.
sq~wtstdlib.hxq~gtJlong double value, int ndigit, int *decpt, int *neg, char *buf, size_t lentinttqfcvtsq~
tõ
This function is equivalent to <CODE>fcvt</CODE> except that it
takes a <CODE>long double</CODE> for the first parameter and that <VAR>ndigit</VAR> is
restricted by the precision of a <CODE>long double</CODE>.
sq~wtstdlib.hxq~nt3long double value, int ndigit, int *decpt, int *negtchar *tqfcvt_rsq~
tl
The <CODE>qfcvt_r</CODE> function is the same as <CODE>qfcvt</CODE>, except
that it places its result into the user-specified buffer pointed to by
<VAR>buf</VAR>, with length <VAR>len</VAR>. The return value is <CODE>-1</CODE> in
case of an error and zero otherwise.
<br><br> This function is a GNU extension.
sq~wtstdlib.hxq~utJlong double value, int ndigit, int *decpt, int *neg, char *buf, size_t lentinttqgcvtsq~
tõ
This function is equivalent to <CODE>gcvt</CODE> except that it takes a
<CODE>long double</CODE> for the first parameter and that <VAR>ndigit</VAR> is
restricted by the precision of a <CODE>long double</CODE>.
sq~wtstdlib.hxq~|t(long double value, int ndigit, char *buftchar *tqsortsq~
tÏ
The <VAR>qsort</VAR> function sorts the array <VAR>array</VAR>. The array contains
<VAR>count</VAR> elements, each of which is of size <VAR>size</VAR>.
<br><br> The <VAR>compare</VAR> function is used to perform the comparison on the
array elements. This function is called with two pointer arguments and
should return an integer less than, equal to, or greater than zero
corresponding to whether its first argument is considered less than,
equal to, or greater than its second argument.
<br><br> sorting
Warning: If two objects compare as equal, their order after
sorting is unpredictable. That is to say, the sorting is not stable.
This can make a difference when the comparison considers only part of
the elements. Two elements with the same sort key may differ in other
respects.
<br><br> If you want the effect of a stable sort, you can get this result by
writing the comparison function so that, lacking other reason
distinguish between two elements, it compares them by their addresses.
Note that doing this may make the sorting algorithm less efficient, so
do it only if necessary.
<br><br> Here is a simple example of sorting an array of doubles in numerical
order, using the comparison function defined above :
<br><br> <pre><br>
{<br>
double *array;<br>
int size;<br>
<small>...</small><br>
qsort (array, size, sizeof (double), compare_doubles);<br>
}<br>
</pre>
<br><br> The <CODE>qsort</CODE> function derives its name from the fact that it was
originally implemented using the ``quick sort'' algorithm.
<br><br> The implementation of <CODE>qsort</CODE> in this library might not be an
in-place sort and might thereby use an extra amount of memory to store
the array.
sq~wtstdlib.hxq~ƒt?void *array, size_t count, size_t size, comparison_fn_t comparetvoidtraisesq~
t
The <CODE>raise</CODE> function sends the signal <VAR>signum</VAR> to the calling
process. It returns zero if successful and a nonzero value if it fails.
About the only reason for failure would be if the value of <VAR>signum</VAR>
is invalid.
sq~wtsignal.htunistd.hxq~Št
int signumtinttrandsq~
t®
The <CODE>rand</CODE> function returns the next pseudo-random number in the
series. The value ranges from <CODE>0</CODE> to <CODE>RAND_MAX</CODE>.
sq~wtstdlib.hxq~’tvoidtinttrand_rsq~
tx
This function returns a random number in the range 0 to <CODE>RAND_MAX</CODE>
just as <CODE>rand</CODE> does. However, all its state is stored in the
<VAR>seed</VAR> argument. This means the RNG's state can only have as many
bits as the type <CODE>unsigned int</CODE> has. This is far too few to
provide a good RNG.
<br><br> If your program requires a reentrant RNG, we recommend you use the
reentrant GNU extensions to the SVID random number generator. The
POSIX.1 interface should only be used when the GNU extensions are not
available.
sq~wtstdlib.hxq~™tunsigned int *seedtinttrandomsq~
tô
This function returns the next pseudo-random number in the sequence.
The value returned ranges from <CODE>0</CODE> to <CODE>RAND_MAX</CODE>.
<br><br> NB: Temporarily this function was defined to return a
<CODE>int32_t</CODE> value to indicate that the return value always contains
32 bits even if <CODE>long int</CODE> is wider. The standard demands it
differently. Users must always be aware of the 32-bit limitation,
though.
sq~wtstdlib.hxq~ tvoidtlong inttrandom_rsq~
tô
The <CODE>random_r</CODE> function behaves exactly like the <CODE>random</CODE>
function except that it uses and modifies the state in the object
pointed to by the first parameter instead of the global state.
sq~wtstdlib.hxq~§t:struct random_data *restrict buf, int32_t *restrict resulttintt rawmemchrsq~
t+
Often the <CODE>memchr</CODE> function is used with the knowledge that the
byte <VAR>c</VAR> is available in the memory block specified by the
parameters. But this means that the <VAR>size</VAR> parameter is not really
needed and that the tests performed with it at runtime (to check whether
the end of the block is reached) are not needed.
<br><br> The <CODE>rawmemchr</CODE> function exists for just this situation which is
surprisingly frequent. The interface is similar to <CODE>memchr</CODE> except
that the <VAR>size</VAR> parameter is missing. The function will look beyond
the end of the block pointed to by <VAR>block</VAR> in case the programmer
made an error in assuming that the byte <VAR>c</VAR> is present in the block.
In this case the result is unspecified. Otherwise the return value is a
pointer to the located byte.
<br><br> This function is of special interest when looking for the end of a
string. Since all strings are terminated by a null byte a call like
<br><br> <pre><br>
rawmemchr (str, '\0')<br>
</pre>
<br><br>
will never go beyond the end of the string.
<br><br> This function is a GNU extension.
sq~wtstring.hxq~®tconst void *block, int ctvoid *treadsq~
tÃ
The <CODE>read</CODE> function reads up to <VAR>size</VAR> bytes from the file
with descriptor <VAR>filedes</VAR>, storing the results in the <VAR>buffer</VAR>.
(This is not necessarily a character string, and no terminating null
character is added.)
<br><br> -of-file, on a file descriptor
The return value is the number of bytes actually read. This might be
less than <VAR>size</VAR>; for example, if there aren't that many bytes left
in the file or if there aren't that many bytes immediately available.
The exact behavior depends on what kind of file it is. Note that
reading less than <VAR>size</VAR> bytes is not an error.
<br><br> A value of zero indicates end-of-file (except if the value of the
<VAR>size</VAR> argument is also zero). This is not considered an error.
If you keep calling <CODE>read</CODE> while at end-of-file, it will keep
returning zero and doing nothing else.
<br><br> If <CODE>read</CODE> returns at least one character, there is no way you can
tell whether end-of-file was reached. But if you did reach the end, the
next read will return zero.
<br><br> In case of an error, <CODE>read</CODE> returns -1. The following
<CODE>errno</CODE> error conditions are defined for this function:
<br><br> <DL>
<DT><CODE>EAGAIN</CODE>
<DD>
Normally, when no input is immediately available, <CODE>read</CODE> waits for
some input. But if the <CODE>O_NONBLOCK</CODE> flag is set for the file
, <CODE>read</CODE> returns immediately without
reading any data, and reports this error.
<br><br> Compatibility Note: Most versions of BSD Unix use a different
error code for this: <CODE>EWOULDBLOCK</CODE>. In the GNU library,
<CODE>EWOULDBLOCK</CODE> is an alias for <CODE>EAGAIN</CODE>, so it doesn't matter
which name you use.
<br><br> On some systems, reading a large amount of data from a character special
file can also fail with <CODE>EAGAIN</CODE> if the kernel cannot find enough
physical memory to lock down the user's pages. This is limited to
devices that transfer with direct memory access into the user's memory,
which means it does not include terminals, since they always use
separate buffers inside the kernel. This problem never happens in the
GNU system.
<br><br> Any condition that could result in <CODE>EAGAIN</CODE> can instead result in a
successful <CODE>read</CODE> which returns fewer bytes than requested.
Calling <CODE>read</CODE> again immediately would result in <CODE>EAGAIN</CODE>.
<br><br> <LI> EBADF
The <VAR>filedes</VAR> argument is not a valid file descriptor,
or is not open for reading.
<br><br> <LI> EINTR
<CODE>read</CODE> was interrupted by a signal while it was waiting for input.
. A signal will not necessary cause
<CODE>read</CODE> to return <CODE>EINTR</CODE>; it may instead result in a
successful <CODE>read</CODE> which returns fewer bytes than requested.
<br><br> <LI> EIO
For many devices, and for disk files, this error code indicates
a hardware error.
<br><br> <CODE>EIO</CODE> also occurs when a background process tries to read from the
controlling terminal, and the normal action of stopping the process by
sending it a <CODE>SIGTTIN</CODE> signal isn't working. This might happen if
the signal is being blocked or ignored, or because the process group is
orphaned. , for more information about job control,
and Signal Handling, for information about signals.
<br><br> <LI> EINVAL
In some systems, when reading from a character or block device, position
and size offsets must be aligned to a particular block size. This error
indicates that the offsets were not properly aligned.
<br><br> Please note that there is no function named <CODE>read64</CODE>. This is not
necessary since this function does not directly modify or handle the
possibly wide file offset. Since the kernel handles this state
internally, the <CODE>read</CODE> function can be used for all cases.
<br><br> This function is a cancellation point in multi-threaded programs. This
is a problem if the thread allocates some resources (like memory, file
descriptors, semaphores or whatever) at the time <CODE>read</CODE> is
called. If the thread gets canceled these resources stay allocated
until the program ends. To avoid this, calls to <CODE>read</CODE> should be
protected using cancellation handlers.
<br><br> The <CODE>read</CODE> function is the underlying primitive for all of the
functions that read from streams, such as <CODE>fgetc</CODE>.
sq~wtunistd.hxq~µt&int filedes, void *buffer, size_t sizetssize_ttreaddirsq~
t.
This function reads the next entry from the directory. It normally
returns a pointer to a structure containing information about the file.
This structure is statically allocated and can be rewritten by a
subsequent call.
<br><br> Portability Note: On some systems <CODE>readdir</CODE> may not
return entries for <TT>.</TT> and <TT>..</TT>, even though these are always
valid file names in any directory. .
<br><br> If there are no more entries in the directory or an error is detected,
<CODE>readdir</CODE> returns a null pointer. The following <CODE>errno</CODE> error
conditions are defined for this function:
<br><br> <DL>
<DT><CODE>EBADF</CODE>
<DD>
The <VAR>dirstream</VAR> argument is not valid.
<br><br> <CODE>readdir</CODE> is not thread safe. Multiple threads using
<CODE>readdir</CODE> on the same <VAR>dirstream</VAR> may overwrite the return
value. Use <CODE>readdir_r</CODE> when this is critical.
sq~wtdirent.hxq~¼tDIR *dirstreamtstruct dirent *t readdir64sq~
tª
The <CODE>readdir64</CODE> function is just like the <CODE>readdir</CODE> function
except that it returns a pointer to a record of type <CODE>struct
dirent64</CODE>. Some of the members of this data type (notably <CODE>d_ino</CODE>)
might have a different size to allow large filesystems.
<br><br> In all other aspects this function is equivalent to <CODE>readdir</CODE>.
sq~wtdirent.hxq~ÃtDIR *dirstreamtstruct dirent64 *t readdir64_rsq~
t‚
The <CODE>readdir64_r</CODE> function is equivalent to the <CODE>readdir_r</CODE>
function except that it takes parameters of base type <CODE>struct
dirent64</CODE> instead of <CODE>struct dirent</CODE> in the second and third
position. The same precautions mentioned in the documentation of
<CODE>readdir_r</CODE> also apply here.
sq~wtdirent.hxq~Êt@DIR *dirstream, struct dirent64 *entry, struct dirent64 **resulttintt readdir_rsq~
t 
This function is the reentrant version of <CODE>readdir</CODE>. Like
<CODE>readdir</CODE> it returns the next entry from the directory. But to
prevent conflicts between simultaneously running threads the result is
not stored in statically allocated memory. Instead the argument
<VAR>entry</VAR> points to a place to store the result.
<br><br> Normally <CODE>readdir_r</CODE> returns zero and sets <CODE>*<VAR>result</VAR></CODE>
to <VAR>entry</VAR>. If there are no more entries in the directory or an
error is detected, <CODE>readdir_r</CODE> sets <CODE>*<VAR>result</VAR></CODE> to a
null pointer and returns a nonzero error code, also stored in
<CODE>errno</CODE>, as described for <CODE>readdir</CODE>.
<br><br> Portability Note: On some systems <CODE>readdir_r</CODE> may not
return a NUL terminated string for the file name, even when there is no
<CODE>d_reclen</CODE> field in <CODE>struct dirent</CODE> and the file
name is the maximum allowed size. Modern systems all have the
<CODE>d_reclen</CODE> field, and on old systems multi-threading is not
critical. In any case there is no such problem with the <CODE>readdir</CODE>
function, so that even on systems without the <CODE>d_reclen</CODE> member one
could use multiple threads by using external locking.
<br><br> It is also important to look at the definition of the <CODE>struct
dirent</CODE> type. Simply passing a pointer to an object of this type for
the second parameter of <CODE>readdir_r</CODE> might not be enough. Some
systems don't define the <CODE>d_name</CODE> element sufficiently long. In
this case the user has to provide additional space. There must be room
for at least <CODE>NAME_MAX + 1</CODE> characters in the <CODE>d_name</CODE> array.
Code to call <CODE>readdir_r</CODE> could look like this:
<br><br> <pre><br>
union<br>
{<br>
struct dirent d;<br>
char b[offsetof (struct dirent, d_name) + NAME_MAX + 1];<br>
} u;<br>
<br><br> if (readdir_r (dir, &u.d, &res) == 0)<br>
<small>...</small><br>
</pre>
sq~wtdirent.hxq~Ñt<DIR *dirstream, struct dirent *entry, struct dirent **resulttinttreadlinksq~
t(
The <CODE>readlink</CODE> function gets the value of the symbolic link
<VAR>filename</VAR>. The file name that the link points to is copied into
<VAR>buffer</VAR>. This file name string is <EM>not</EM> null-terminated;
<CODE>readlink</CODE> normally returns the number of characters copied. The
<VAR>size</VAR> argument specifies the maximum number of characters to copy,
usually the allocation size of <VAR>buffer</VAR>.
<br><br> If the return value equals <VAR>size</VAR>, you cannot tell whether or not
there was room to return the entire name. So make a bigger buffer and
call <CODE>readlink</CODE> again. Here is an example:
<br><br> <pre><br>
char *<br>
readlink_malloc (const char *filename)<br>
{<br>
int size = 100;<br>
char *buffer = NULL;<br>
<br><br> while (1)<br>
{<br>
buffer = (char *) xrealloc (buffer, size);<br>
int nchars = readlink (filename, buffer, size);<br>
if (nchars < 0)<br>
{<br>
free (buffer);<br>
return NULL;<br>
}<br>
if (nchars < size)<br>
return buffer;<br>
size *= 2;<br>
}<br>
}<br>
</pre>
<br><br> A value of <CODE>-1</CODE> is returned in case of error. In addition to the
usual file name errors , the following
<CODE>errno</CODE> error conditions are defined for this function:
<br><br> <DL>
<DT><CODE>EINVAL</CODE>
<DD>
The named file is not a symbolic link.
<br><br> <LI> EIO
A hardware error occurred while reading or writing data on the disk.
sq~wtunistd.hxq~Øt/const char *filename, char *buffer, size_t sizetinttreadvsq~
t¸
<br><br> The <CODE>readv</CODE> function reads data from <VAR>filedes</VAR> and scatters it
into the buffers described in <VAR>vector</VAR>, which is taken to be
<VAR>count</VAR> structures long. As each buffer is filled, data is sent to the
next.
<br><br> Note that <CODE>readv</CODE> is not guaranteed to fill all the buffers.
It may stop at any point, for the same reasons <CODE>read</CODE> would.
<br><br> The return value is a count of bytes (<EM>not</EM> buffers) read, 0
indicating end-of-file, or -1 indicating an error. The possible
errors are the same as in <CODE>read</CODE>.
<br><br>
sq~wt sys/uio.hxq~ßt2int filedes, const struct iovec *vector, int counttssize_ttreallocsq~
tx
The <CODE>realloc</CODE> function changes the size of the block whose address is
<VAR>ptr</VAR> to be <VAR>newsize</VAR>.
<br><br> Since the space after the end of the block may be in use, <CODE>realloc</CODE>
may find it necessary to copy the block to a new address where more free
space is available. The value of <CODE>realloc</CODE> is the new address of the
block. If the block needs to be moved, <CODE>realloc</CODE> copies the old
contents.
<br><br> If you pass a null pointer for <VAR>ptr</VAR>, <CODE>realloc</CODE> behaves just
like <samp>malloc (<VAR>newsize</VAR>)</samp>. This can be convenient, but beware
that older implementations (before ISO C) may not support this
behavior, and will probably crash when <CODE>realloc</CODE> is passed a null
pointer.
sq~wtstdlib.hxq~ætvoid *ptr, size_t newsizetvoid *trealpathsq~
tÉ
<br><br> A call to <CODE>realpath</CODE> where the <VAR>resolved</VAR> parameter is
<CODE>NULL</CODE> behaves exactly like <CODE>canonicalize_file_name</CODE>. The
function allocates a buffer for the file name and returns a pointer to
it. If <VAR>resolved</VAR> is not <CODE>NULL</CODE> it points to a buffer into
which the result is copied. It is the callers responsibility to
allocate a buffer which is large enough. On systems which define
<CODE>PATH_MAX</CODE> this means the buffer must be large enough for a
pathname of this size. For systems without limitations on the pathname
length the requirement cannot be met and programs should not call
<CODE>realpath</CODE> with anything but <CODE>NULL</CODE> for the second parameter.
<br><br> One other difference is that the buffer <VAR>resolved</VAR> (if nonzero) will
contain the part of the path component which does not exist or is not
readable if the function returns <CODE>NULL</CODE> and <CODE>errno</CODE> is set to
<CODE>EACCES</CODE> or <CODE>ENOENT</CODE>.
<br><br> This function is declared in <TT>stdlib.h</TT>.
sq~wtstdlib.hxq~ít2const char *restrict name, char *restrict resolvedtchar *trecvsq~
t
The <CODE>recv</CODE> function is like <CODE>read</CODE>, but with the additional
flags <VAR>flags</VAR>. The possible values of <VAR>flags</VAR> are described
in Socket Data Options.
<br><br> If nonblocking mode is set for <VAR>socket</VAR>, and no data are available to
be read, <CODE>recv</CODE> fails immediately rather than waiting. , for information about nonblocking mode.
<br><br> This function returns the number of bytes received, or <CODE>-1</CODE> on failure.
The following <CODE>errno</CODE> error conditions are defined for this function:
<br><br> <DL>
<DT><CODE>EBADF</CODE>
<DD>
The <VAR>socket</VAR> argument is not a valid file descriptor.
<br><br> <LI> ENOTSOCK
The descriptor <VAR>socket</VAR> is not a socket.
<br><br> <LI> EWOULDBLOCK
Nonblocking mode has been set on the socket, and the read operation
would block. (Normally, <CODE>recv</CODE> blocks until there is input
available to be read.)
<br><br> <LI> EINTR
The operation was interrupted by a signal before any data was read.
.
<br><br> <LI> ENOTCONN
You never connected this socket.
<br><br> This function is defined as a cancellation point in multi-threaded
programs, so one has to be prepared for this and make sure that
allocated resources (like memory, files descriptors, semaphores or
whatever) are freed even if the thread is canceled.
sq~wt sys/socket.hxq~ôt0int socket, void *buffer, size_t size, int flagstinttrecvfromsq~
t»
The <CODE>recvfrom</CODE> function reads one packet from the socket
<VAR>socket</VAR> into the buffer <VAR>buffer</VAR>. The <VAR>size</VAR> argument
specifies the maximum number of bytes to be read.
<br><br> If the packet is longer than <VAR>size</VAR> bytes, then you get the first
<VAR>size</VAR> bytes of the packet and the rest of the packet is lost.
There's no way to read the rest of the packet. Thus, when you use a
packet protocol, you must always know how long a packet to expect.
<br><br> The <VAR>addr</VAR> and <VAR>length-ptr</VAR> arguments are used to return the
address where the packet came from. . For a
socket in the local domain the address information won't be meaningful,
since you can't read the address of such a socket. You can specify a null pointer as the <VAR>addr</VAR> argument
if you are not interested in this information.
<br><br> The <VAR>flags</VAR> are interpreted the same way as for <CODE>recv</CODE>
. The return value and error conditions
are also the same as for <CODE>recv</CODE>.
<br><br> This function is defined as a cancellation point in multi-threaded
programs, so one has to be prepared for this and make sure that
allocated resources (like memory, files descriptors, semaphores or
whatever) are freed even if the thread is canceled.
sq~wt sys/socket.hxq~ût^int socket, void *buffer, size_t size, int flags, struct sockaddr *addr, socklen_t *length-ptrtinttrecvmsgsq~
t/
<br><br> This function is defined as a cancellation point in multi-threaded
programs, so one has to be prepared for this and make sure that
allocated resources (like memory, files descriptors, semaphores or
whatever) are freed even if the thread is canceled.
sq~wt sys/socket.hxq~t-int socket, struct msghdr *message, int flagstinttregcompsq~
tC
The function <CODE>regcomp</CODE> ``compiles'' a regular expression into a
data structure that you can use with <CODE>regexec</CODE> to match against a
string. The compiled regular expression format is designed for
efficient matching. <CODE>regcomp</CODE> stores it into <CODE>*<VAR>compiled</VAR></CODE>.
<br><br> It's up to you to allocate an object of type <CODE>regex_t</CODE> and pass its
address to <CODE>regcomp</CODE>.
<br><br> The argument <VAR>cflags</VAR> lets you specify various options that control
the syntax and semantics of regular expressions. .
<br><br> If you use the flag <CODE>REG_NOSUB</CODE>, then <CODE>regcomp</CODE> omits from
the compiled regular expression the information necessary to record
how subexpressions actually match. In this case, you might as well
pass <CODE>0</CODE> for the <VAR>matchptr</VAR> and <VAR>nmatch</VAR> arguments when
you call <CODE>regexec</CODE>.
<br><br> If you don't use <CODE>REG_NOSUB</CODE>, then the compiled regular expression
does have the capacity to record how subexpressions match. Also,
<CODE>regcomp</CODE> tells you how many subexpressions <VAR>pattern</VAR> has, by
storing the number in <CODE><VAR>compiled</VAR>->re_nsub</CODE>. You can use that
value to decide how long an array to allocate to hold information about
subexpression matches.
<br><br> <CODE>regcomp</CODE> returns <CODE>0</CODE> if it succeeds in compiling the regular
expression; otherwise, it returns a nonzero error code (see the table
below). You can use <CODE>regerror</CODE> to produce an error message string
describing the reason for a nonzero value; see Regexp Cleanup.
<br><br>
sq~wtregex.hxq~ tDregex_t *restrict compiled, const char *restrict pattern, int cflagstinttregerrorsq~
t¨
This function produces an error message string for the error code
<VAR>errcode</VAR>, and stores the string in <VAR>length</VAR> bytes of memory
starting at <VAR>buffer</VAR>. For the <VAR>compiled</VAR> argument, supply the
same compiled regular expression structure that <CODE>regcomp</CODE> or
<CODE>regexec</CODE> was working with when it got the error. Alternatively,
you can supply <CODE>NULL</CODE> for <VAR>compiled</VAR>; you will still get a
meaningful error message, but it might not be as detailed.
<br><br> If the error message can't fit in <VAR>length</VAR> bytes (including a
terminating null character), then <CODE>regerror</CODE> truncates it.
The string that <CODE>regerror</CODE> stores is always null-terminated
even if it has been truncated.
<br><br> The return value of <CODE>regerror</CODE> is the minimum length needed to
store the entire error message. If this is less than <VAR>length</VAR>, then
the error message was not truncated, and you can use it. Otherwise, you
should call <CODE>regerror</CODE> again with a larger buffer.
<br><br> Here is a function which uses <CODE>regerror</CODE>, but always dynamically
allocates a buffer for the error message:
<br><br> <pre><br>
char *get_regerror (int errcode, regex_t *compiled)<br>
{<br>
size_t length = regerror (errcode, compiled, NULL, 0);<br>
char *buffer = xmalloc (length);<br>
(void) regerror (errcode, compiled, buffer, length);<br>
return buffer;<br>
}<br>
</pre>
sq~wtregex.hxq~tSint errcode, const regex_t *restrict compiled, char *restrict buffer, size_t lengthtsize_ttregexecsq~
t¼
This function tries to match the compiled regular expression
<CODE>*<VAR>compiled</VAR></CODE> against <VAR>string</VAR>.
<br><br> <CODE>regexec</CODE> returns <CODE>0</CODE> if the regular expression matches;
otherwise, it returns a nonzero value. See the table below for
what nonzero values mean. You can use <CODE>regerror</CODE> to produce an
error message string describing the reason for a nonzero value;
see Regexp Cleanup.
<br><br> The argument <VAR>eflags</VAR> is a word of bit flags that enable various
options.
<br><br> If you want to get information about what part of <VAR>string</VAR> actually
matched the regular expression or its subexpressions, use the arguments
<VAR>matchptr</VAR> and <VAR>nmatch</VAR>. Otherwise, pass <CODE>0</CODE> for
<VAR>nmatch</VAR>, and <CODE>NULL</CODE> for <VAR>matchptr</VAR>. .
sq~wtregex.hxq~twconst regex_t *restrict compiled, const char *restrict string, size_t nmatch, regmatch_t matchptr[restrict], int eflagstinttregfreesq~
tf
Calling <CODE>regfree</CODE> frees all the storage that <CODE>*<VAR>compiled</VAR></CODE>
points to. This includes various internal fields of the <CODE>regex_t</CODE>
structure that aren't documented in this manual.
<br><br> <CODE>regfree</CODE> does not free the object <CODE>*<VAR>compiled</VAR></CODE> itself.
sq~wtregex.hxq~tregex_t *compiledtvoidtregister_printf_functionsq~
t
This function defines the conversion specifier character <VAR>spec</VAR>.
Thus, if <VAR>spec</VAR> is <CODE>'Y'</CODE>, it defines the conversion <samp>%Y</samp>.
You can redefine the built-in conversions like <samp>%s</samp>, but flag
characters like <samp>#</samp> and type modifiers like <samp>l</samp> can never be
used as conversions; calling <CODE>register_printf_function</CODE> for those
characters has no effect. It is advisable not to use lowercase letters,
since the ISO C standard warns that additional lowercase letters may be
standardized in future editions of the standard.
<br><br> The <VAR>handler-function</VAR> is the function called by <CODE>printf</CODE> and
friends when this conversion appears in a template string.
, for information about how to define
a function to pass as this argument. If you specify a null pointer, any
existing handler function for <VAR>spec</VAR> is removed.
<br><br> The <VAR>arginfo-function</VAR> is the function called by
<CODE>parse_printf_format</CODE> when this conversion appears in a
template string. , for information
about this.
<br><br>
<br><br> Attention: In the GNU C library versions before 2.0 the
<VAR>arginfo-function</VAR> function did not need to be installed unless
the user used the <CODE>parse_printf_format</CODE> function. This has changed.
Now a call to any of the <CODE>printf</CODE> functions will call this
function when this format specifier appears in the format string.
<br><br> The return value is <CODE>0</CODE> on success, and <CODE>-1</CODE> on failure
(which occurs if <VAR>spec</VAR> is out of range).
<br><br> You can redefine the standard output conversions, but this is probably
not a good idea because of the potential for confusion. Library routines
written by other people could break if you do this.
sq~wtprintf.hxq~%tTint spec, printf_function handler-function, printf_arginfo_function arginfo-functiontintt remaindersq~
tF
This function is another name for <CODE>drem</CODE>.
sq~wtmath.hxq~,t$double numerator, double denominatortdoublet
remainderfsq~
tF
This function is another name for <CODE>drem</CODE>.
sq~wtmath.hxq~3t"float numerator, float denominatortfloatt
remainderlsq~
tF
This function is another name for <CODE>drem</CODE>.
sq~wtmath.hxq~:t.long double numerator, long double denominatort long doubletremovesq~
tß
This is the ISO C function to remove a file. It works like
<CODE>unlink</CODE> for files and like <CODE>rmdir</CODE> for directories.
<CODE>remove</CODE> is declared in <TT>stdio.h</TT>.
sq~wtstdio.hxq~Atconst char *filenametinttrenamesq~
tP
The <CODE>rename</CODE> function renames the file <VAR>oldname</VAR> to
<VAR>newname</VAR>. The file formerly accessible under the name
<VAR>oldname</VAR> is afterwards accessible as <VAR>newname</VAR> instead. (If
the file had any other names aside from <VAR>oldname</VAR>, it continues to
have those names.)
<br><br> The directory containing the name <VAR>newname</VAR> must be on the same file
system as the directory containing the name <VAR>oldname</VAR>.
<br><br> One special case for <CODE>rename</CODE> is when <VAR>oldname</VAR> and
<VAR>newname</VAR> are two names for the same file. The consistent way to
handle this case is to delete <VAR>oldname</VAR>. However, in this case
POSIX requires that <CODE>rename</CODE> do nothing and report success---which
is inconsistent. We don't know what your operating system will do.
<br><br> If <VAR>oldname</VAR> is not a directory, then any existing file named
<VAR>newname</VAR> is removed during the renaming operation. However, if
<VAR>newname</VAR> is the name of a directory, <CODE>rename</CODE> fails in this
case.
<br><br> If <VAR>oldname</VAR> is a directory, then either <VAR>newname</VAR> must not
exist or it must name a directory that is empty. In the latter case,
the existing directory named <VAR>newname</VAR> is deleted first. The name
<VAR>newname</VAR> must not specify a subdirectory of the directory
<CODE>oldname</CODE> which is being renamed.
<br><br> One useful feature of <CODE>rename</CODE> is that the meaning of <VAR>newname</VAR>
changes ``atomically'' from any previously existing file by that name to
its new meaning (i.e., the file that was called <VAR>oldname</VAR>). There is
no instant at which <VAR>newname</VAR> is non-existent ``in between'' the old
meaning and the new meaning. If there is a system crash during the
operation, it is possible for both names to still exist; but
<VAR>newname</VAR> will always be intact if it exists at all.
<br><br> If <CODE>rename</CODE> fails, it returns <CODE>-1</CODE>. In addition to the usual
file name errors , the following
<CODE>errno</CODE> error conditions are defined for this function:
<br><br> <DL>
<DT><CODE>EACCES</CODE>
<DD>
One of the directories containing <VAR>newname</VAR> or <VAR>oldname</VAR>
refuses write permission; or <VAR>newname</VAR> and <VAR>oldname</VAR> are
directories and write permission is refused for one of them.
<br><br> <LI> EBUSY
A directory named by <VAR>oldname</VAR> or <VAR>newname</VAR> is being used by
the system in a way that prevents the renaming from working. This includes
directories that are mount points for filesystems, and directories
that are the current working directories of processes.
<br><br> <LI> ENOTEMPTY
<LI>x EEXIST
The directory <VAR>newname</VAR> isn't empty. The GNU system always returns
<CODE>ENOTEMPTY</CODE> for this, but some other systems return <CODE>EEXIST</CODE>.
<br><br> <LI> EINVAL
<VAR>oldname</VAR> is a directory that contains <VAR>newname</VAR>.
<br><br> <LI> EISDIR
<VAR>newname</VAR> is a directory but the <VAR>oldname</VAR> isn't.
<br><br> <LI> EMLINK
The parent directory of <VAR>newname</VAR> would have too many links
(entries).
<br><br> <LI> ENOENT
The file <VAR>oldname</VAR> doesn't exist.
<br><br> <LI> ENOSPC
The directory that would contain <VAR>newname</VAR> has no room for another
entry, and there is no space left in the file system to expand it.
<br><br> <LI> EROFS
The operation would involve writing to a directory on a read-only file
system.
<br><br> <LI> EXDEV
The two file names <VAR>newname</VAR> and <VAR>oldname</VAR> are on different
file systems.
sq~wtstdio.hxq~Ht(const char *oldname, const char *newnametinttrewindsq~
tÐ
The <CODE>rewind</CODE> function positions the stream <VAR>stream</VAR> at the
beginning of the file. It is equivalent to calling <CODE>fseek</CODE> or
<CODE>fseeko</CODE> on the <VAR>stream</VAR> with an <VAR>offset</VAR> argument of
<CODE>0L</CODE> and a <VAR>whence</VAR> argument of <CODE>SEEK_SET</CODE>, except that
the return value is discarded and the error indicator for the stream is
reset.
sq~wtstdio.hxq~Ot FILE *streamtvoidt rewinddirsq~
t[
The <CODE>rewinddir</CODE> function is used to reinitialize the directory
stream <VAR>dirstream</VAR>, so that if you call <CODE>readdir</CODE> it
returns information about the first entry in the directory again. This
function also notices if files have been added or removed to the
directory since it was opened with <CODE>opendir</CODE>. (Entries for these
files might or might not be returned by <CODE>readdir</CODE> if they were
added or removed since you last called <CODE>opendir</CODE> or
<CODE>rewinddir</CODE>.)
sq~wtdirent.hxq~VtDIR *dirstreamtvoidtrindexsq~
t=
<CODE>rindex</CODE> is another name for <CODE>strrchr</CODE>; they are exactly the same.
New code should always use <CODE>strrchr</CODE> since this name is defined in
ISO C while <CODE>rindex</CODE> is a BSD invention which never was available
on System V derived systems.
sq~wtstring.hxq~]tconst char *string, int ctchar *trintsq~
tô
These functions round <VAR>x</VAR> to an integer value according to the
current rounding mode. , for
information about the various rounding modes. The default
rounding mode is to round to the nearest integer; some machines
support other modes, but round-to-nearest is always used unless
you explicitly select another.
<br><br> If <VAR>x</VAR> was not initially an integer, these functions raise the
inexact exception.
sq~wtmath.hxq~dtdouble xtdoubletrintfsq~
tô
These functions round <VAR>x</VAR> to an integer value according to the
current rounding mode. , for
information about the various rounding modes. The default
rounding mode is to round to the nearest integer; some machines
support other modes, but round-to-nearest is always used unless
you explicitly select another.
<br><br> If <VAR>x</VAR> was not initially an integer, these functions raise the
inexact exception.
sq~wtmath.hxq~ktfloat xtfloattrintlsq~
tô
These functions round <VAR>x</VAR> to an integer value according to the
current rounding mode. , for
information about the various rounding modes. The default
rounding mode is to round to the nearest integer; some machines
support other modes, but round-to-nearest is always used unless
you explicitly select another.
<br><br> If <VAR>x</VAR> was not initially an integer, these functions raise the
inexact exception.
sq~wtmath.hxq~rt
long double xt long doubletrmdirsq~
to
, deleting
a directory
The <CODE>rmdir</CODE> function deletes a directory. The directory must be
empty before it can be removed; in other words, it can only contain
entries for <TT>.</TT> and <TT>..</TT>.
<br><br> In most other respects, <CODE>rmdir</CODE> behaves like <CODE>unlink</CODE>. There
are two additional <CODE>errno</CODE> error conditions defined for
<CODE>rmdir</CODE>:
<br><br> <DL>
<DT><CODE>ENOTEMPTY</CODE>
<DD>
<LI>x EEXIST
The directory to be deleted is not empty.
<br><br> These two error codes are synonymous; some systems use one, and some use
the other. The GNU system always uses <CODE>ENOTEMPTY</CODE>.
<br><br> The prototype for this function is declared in the header file
<TT>unistd.h</TT>.
sq~wtunistd.hxq~ytconst char *filenametinttroundsq~
tÅ
These functions are similar to <CODE>rint</CODE>, but they round halfway
cases away from zero instead of to the nearest integer (or other
current rounding mode).
sq~wtmath.hxq~€tdouble xtdoubletroundfsq~
tÅ
These functions are similar to <CODE>rint</CODE>, but they round halfway
cases away from zero instead of to the nearest integer (or other
current rounding mode).
sq~wtmath.hxq~‡tfloat xtfloattroundlsq~
tÅ
These functions are similar to <CODE>rint</CODE>, but they round halfway
cases away from zero instead of to the nearest integer (or other
current rounding mode).
sq~wtmath.hxq~Žt
long double xt long doubletrpmatchsq~
t>
The function <CODE>rpmatch</CODE> checks the string in <VAR>response</VAR> whether
or not it is a correct yes-or-no answer and if yes, which one. The
check uses the <CODE>YESEXPR</CODE> and <CODE>NOEXPR</CODE> data in the
<CODE>LC_MESSAGES</CODE> category of the currently selected locale. The
return value is as follows:
<br><br> <DL>
<DT><CODE>1</CODE>
<DD>
The user entered an affirmative answer.
<br><br> <LI> 0
The user entered a negative answer.
<br><br> <LI> -1
The answer matched neither the <CODE>YESEXPR</CODE> nor the <CODE>NOEXPR</CODE>
regular expression.
<br><br> This function is not standardized but available beside in GNU libc at
least also in the IBM AIX library.
sq~wtstdlib.hxq~•tconst char *responsetinttscalbsq~
tY
The <CODE>scalb</CODE> function is the BSD name for <CODE>ldexp</CODE>.
sq~wtmath.hxq~œtdouble value, int exponenttdoubletscalbfsq~
tY
The <CODE>scalb</CODE> function is the BSD name for <CODE>ldexp</CODE>.
sq~wtmath.hxq~£tfloat value, int exponenttfloattscalblsq~
tY
The <CODE>scalb</CODE> function is the BSD name for <CODE>ldexp</CODE>.
sq~wtmath.hxq~ªtlong double value, int exponentt long doubletscalblnsq~
t¸
<CODE>scalbln</CODE> is identical to <CODE>scalb</CODE>, except that the exponent
<VAR>n</VAR> is a <CODE>long int</CODE> instead of a floating-point number.
sq~wtmath.hxq~±tdouble x, long int nt
long long inttscalblnfsq~
t¸
<CODE>scalbln</CODE> is identical to <CODE>scalb</CODE>, except that the exponent
<VAR>n</VAR> is a <CODE>long int</CODE> instead of a floating-point number.
sq~wtmath.hxq~¸tfloat x, long int nt
long long inttscalblnlsq~
t¸
<CODE>scalbln</CODE> is identical to <CODE>scalb</CODE>, except that the exponent
<VAR>n</VAR> is a <CODE>long int</CODE> instead of a floating-point number.
sq~wtmath.hxq~¿tlong double x, long int nt
long long inttscalbnsq~
t³
<CODE>scalbn</CODE> is identical to <CODE>scalb</CODE>, except that the exponent
<VAR>n</VAR> is an <CODE>int</CODE> instead of a floating-point number.
sq~wtmath.hxq~Ætdouble x, int nt
long long inttscalbnfsq~
t³
<CODE>scalbn</CODE> is identical to <CODE>scalb</CODE>, except that the exponent
<VAR>n</VAR> is an <CODE>int</CODE> instead of a floating-point number.
sq~wtmath.hxq~Ítfloat x, int nt
long long inttscalbnlsq~
t³
<CODE>scalbn</CODE> is identical to <CODE>scalb</CODE>, except that the exponent
<VAR>n</VAR> is an <CODE>int</CODE> instead of a floating-point number.
sq~wtmath.hxq~Ôtlong double x, int nt
long long inttscandirsq~
t†
<br><br> The <CODE>scandir</CODE> function scans the contents of the directory selected
by <VAR>dir</VAR>. The result in *<VAR>namelist</VAR> is an array of pointers to
structure of type <CODE>struct dirent</CODE> which describe all selected
directory entries and which is allocated using <CODE>malloc</CODE>. Instead
of always getting all directory entries returned, the user supplied
function <VAR>selector</VAR> can be used to decide which entries are in the
result. Only the entries for which <VAR>selector</VAR> returns a non-zero
value are selected.
<br><br> Finally the entries in *<VAR>namelist</VAR> are sorted using the
user-supplied function <VAR>cmp</VAR>. The arguments passed to the <VAR>cmp</VAR>
function are of type <CODE>struct dirent **</CODE>, therefore one cannot
directly use the <CODE>strcmp</CODE> or <CODE>strcoll</CODE> functions; instead see
the functions <CODE>alphasort</CODE> and <CODE>versionsort</CODE> below.
<br><br> The return value of the function is the number of entries placed in
*<VAR>namelist</VAR>. If it is <CODE>-1</CODE> an error occurred (either the
directory could not be opened for reading or the malloc call failed) and
the global variable <CODE>errno</CODE> contains more information on the error.
sq~wtdirent.hxq~Ût|const char *dir, struct dirent ***namelist, int (*selector) (const struct dirent *), int (*cmp) (const void *, const void *)tintt scandir64sq~
t^
The <CODE>scandir64</CODE> function works like the <CODE>scandir</CODE> function
except that the directory entries it returns are described by elements
of type <CODE>struct dirent64</CODE>. The function pointed to by
<VAR>selector</VAR> is again used to select the desired entries, except that
<VAR>selector</VAR> now must point to a function which takes a
<CODE>struct dirent64 *</CODE> parameter.
<br><br> Similarly the <VAR>cmp</VAR> function should expect its two arguments to be
of type <CODE>struct dirent64 **</CODE>.
sq~wtdirent.hxq~ât€const char *dir, struct dirent64 ***namelist, int (*selector) (const struct dirent64 *), int (*cmp) (const void *, const void *)tinttscanfsq~
tD
The <CODE>scanf</CODE> function reads formatted input from the stream
<CODE>stdin</CODE> under the control of the template string <VAR>template</VAR>.
The optional arguments are pointers to the places which receive the
resulting values.
<br><br> The return value is normally the number of successful assignments. If
an end-of-file condition is detected before any matches are performed,
including matches against whitespace and literal characters in the
template, then <CODE>EOF</CODE> is returned.
sq~wtstdio.hxq~étconst char *template, ...tinttsched_get_priority_maxsq~
tx
<br><br> This function returns the highest absolute priority value that is
allowable for a process that with scheduling policy <VAR>policy</VAR>.
<br><br> On Linux, it is 0 for SCHED_OTHER and 99 for everything else.
<br><br> On success, the return value is <CODE>0</CODE>. Otherwise, it is <CODE>-1</CODE>
and <CODE>ERRNO</CODE> is set accordingly. The <CODE>errno</CODE> values specific
to this function are:
<br><br> <DL>
<DT><CODE>EINVAL</CODE>
<DD>
<VAR>policy</VAR> does not identify an existing scheduling policy.
<br><br>
sq~wtsched.hxq~ðt int *policytinttsched_get_priority_minsq~
tq
<br><br> This function returns the lowest absolute priority value that is
allowable for a process with scheduling policy <VAR>policy</VAR>.
<br><br> On Linux, it is 0 for SCHED_OTHER and 1 for everything else.
<br><br> On success, the return value is <CODE>0</CODE>. Otherwise, it is <CODE>-1</CODE>
and <CODE>ERRNO</CODE> is set accordingly. The <CODE>errno</CODE> values specific
to this function are:
<br><br> <DL>
<DT><CODE>EINVAL</CODE>
<DD>
<VAR>policy</VAR> does not identify an existing scheduling policy.
<br><br>
sq~wtsched.hxq~÷t int *policytinttsched_getaffinitysq~
tˆ
<br><br> This functions stores the CPU affinity mask for the process or thread
with the ID <VAR>pid</VAR> in the <VAR>cpusetsize</VAR> bytes long bitmap
pointed to by <VAR>cpuset</VAR>. If successful, the function always
initializes all bits in the <CODE>cpu_set_t</CODE> object and returns zero.
<br><br> If <VAR>pid</VAR> does not correspond to a process or thread on the system
the or the function fails for some other reason, it returns <CODE>-1</CODE>
and <CODE>errno</CODE> is set to represent the error condition.
<br><br> <DL>
<DT><CODE>ESRCH</CODE>
<DD>
No process or thread with the given ID found.
<br><br> <LI> EFAULT
The pointer <VAR>cpuset</VAR> is does not point to a valid object.
<br><br> This function is a GNU extension and is declared in <TT>sched.h</TT>.
sq~wtsched.hxq~þt/pid_t pid, size_t cpusetsize, cpu_set_t *cpusettinttsched_getparamsq~
t)
<br><br> This function returns a process' absolute priority.
<br><br> <VAR>pid</VAR> is the Process ID (pid) of the process whose absolute priority
you want to know.
<br><br> <VAR>param</VAR> is a pointer to a structure in which the function stores the
absolute priority of the process.
<br><br> On success, the return value is <CODE>0</CODE>. Otherwise, it is <CODE>-1</CODE>
and <CODE>ERRNO</CODE> is set accordingly. The <CODE>errno</CODE> values specific
to this function are:
<br><br> <DL>
<br><br> <DT><CODE>ESRCH</CODE>
<DD>
There is no process with pid <VAR>pid</VAR> and it is not zero.
<br><br> <LI> EINVAL
<VAR>pid</VAR> is negative.
<br><br>
<br><br>
sq~wtsched.hxq~t*pid_t pid, const struct sched_param *paramtinttsched_getschedulersq~
tO
<br><br> This function returns the scheduling policy assigned to the process with
Process ID (pid) <VAR>pid</VAR>, or the calling process if <VAR>pid</VAR> is zero.
<br><br> The return value is the scheduling policy. See
<CODE>sched_setscheduler</CODE> for the possible values.
<br><br> If the function fails, the return value is instead <CODE>-1</CODE> and
<CODE>errno</CODE> is set accordingly.
<br><br> The <CODE>errno</CODE> values specific to this function are:
<br><br> <DL>
<br><br> <DT><CODE>ESRCH</CODE>
<DD>
There is no process with pid <VAR>pid</VAR> and it is not zero.
<br><br> <LI> EINVAL
<VAR>pid</VAR> is negative.
<br><br>
<br><br> Note that this function is not an exact mate to <CODE>sched_setscheduler</CODE>
because while that function sets the scheduling policy and the absolute
priority, this function gets only the scheduling policy. To get the
absolute priority, use <CODE>sched_getparam</CODE>.
<br><br>
sq~wtsched.hxq~ t pid_t pidtinttsched_rr_get_intervalsq~
t
<br><br> This function returns the length of the quantum (time slice) used with
the Round Robin scheduling policy, if it is used, for the process with
Process ID <VAR>pid</VAR>.
<br><br> It returns the length of time as <VAR>interval</VAR>.
<br><br> With a Linux kernel, the round robin time slice is always 150
microseconds, and <VAR>pid</VAR> need not even be a real pid.
<br><br> The return value is <CODE>0</CODE> on success and in the pathological case
that it fails, the return value is <CODE>-1</CODE> and <CODE>errno</CODE> is set
accordingly. There is nothing specific that can go wrong with this
function, so there are no specific <CODE>errno</CODE> values.
<br><br>
sq~wtsched.hxq~t$pid_t pid, struct timespec *intervaltinttsched_setaffinitysq~
t³
<br><br> This function installs the <VAR>cpusetsize</VAR> bytes long affinity mask
pointed to by <VAR>cpuset</VAR> for the process or thread with the ID <VAR>pid</VAR>.
If successful the function returns zero and the scheduler will in future
take the affinity information into account.
<br><br> If the function fails it will return <CODE>-1</CODE> and <CODE>errno</CODE> is set
to the error code:
<br><br> <DL>
<DT><CODE>ESRCH</CODE>
<DD>
No process or thread with the given ID found.
<br><br> <LI> EFAULT
The pointer <VAR>cpuset</VAR> is does not point to a valid object.
<br><br> <LI> EINVAL
The bitset is not valid. This might mean that the affinity set might
not leave a processor for the process or thread to run on.
<br><br> This function is a GNU extension and is declared in <TT>sched.h</TT>.
sq~wtsched.hxq~t5pid_t pid, size_t cpusetsize, const cpu_set_t *cpusettinttsched_setparamsq~
të
<br><br> This function sets a process' absolute priority.
<br><br> It is functionally identical to <CODE>sched_setscheduler</CODE> with
<VAR>policy</VAR> = <CODE>-1</CODE>.
<br><br> <br><br>
sq~wtsched.hxq~!t*pid_t pid, const struct sched_param *paramtinttsched_setschedulersq~
t D
<br><br> This function sets both the absolute priority and the scheduling policy
for a process.
<br><br> It assigns the absolute priority value given by <VAR>param</VAR> and the
scheduling policy <VAR>policy</VAR> to the process with Process ID <VAR>pid</VAR>,
or the calling process if <VAR>pid</VAR> is zero. If <VAR>policy</VAR> is
negative, <CODE>sched_setscheduler</CODE> keeps the existing scheduling policy.
<br><br> The following macros represent the valid values for <VAR>policy</VAR>:
<br><br> <DL>
<DT><CODE>SCHED_OTHER</CODE>
<DD>
Traditional Scheduling
<DT><CODE>SCHED_FIFO</CODE>
<DD>
First In First Out
<LI> SCHED_RR
Round Robin
<br><br> <br><br> On success, the return value is <CODE>0</CODE>. Otherwise, it is <CODE>-1</CODE>
and <CODE>ERRNO</CODE> is set accordingly. The <CODE>errno</CODE> values specific
to this function are:
<br><br> <DL>
<LI> EPERM
<OL>
<LI>
The calling process does not have <CODE>CAP_SYS_NICE</CODE> permission and
<VAR>policy</VAR> is not <CODE>SCHED_OTHER</CODE> (or it's negative and the
existing policy is not <CODE>SCHED_OTHER</CODE>.
<br><br> <LI>
The calling process does not have <CODE>CAP_SYS_NICE</CODE> permission and its
owner is not the target process' owner. I.e., the effective uid of the
calling process is neither the effective nor the real uid of process
<VAR>pid</VAR>.
</OL>
<br><br> <LI> ESRCH
There is no process with pid <VAR>pid</VAR> and <VAR>pid</VAR> is not zero.
<br><br> <LI> EINVAL
<OL>
<LI>
<VAR>policy</VAR> does not identify an existing scheduling policy.
<br><br> <LI>
The absolute priority value identified by *<VAR>param</VAR> is outside the
valid range for the scheduling policy <VAR>policy</VAR> (or the existing
scheduling policy if <VAR>policy</VAR> is negative) or <VAR>param</VAR> is
null. <CODE>sched_get_priority_max</CODE> and <CODE>sched_get_priority_min</CODE>
tell you what the valid range is.
<br><br> <LI>
<VAR>pid</VAR> is negative.
</OL>
<br><br>
sq~wtsched.hxq~(t6pid_t pid, int policy, const struct sched_param *paramtintt sched_yieldsq~
tV
<br><br> This function voluntarily gives up the process' claim on the CPU.
<br><br> Technically, <CODE>sched_yield</CODE> causes the calling process to be made
immediately ready to run (as opposed to running, which is what it was
before). This means that if it has absolute priority higher than 0, it
gets pushed onto the tail of the queue of processes that share its
absolute priority and are ready to run, and it will run again when its
turn next arrives. If its absolute priority is 0, it is more
complicated, but still has the effect of yielding the CPU to other
processes.
<br><br> If there are no other processes that share the calling process' absolute
priority, this function doesn't have any effect.
<br><br> To the extent that the containing program is oblivious to what other
processes in the system are doing and how fast it executes, this
function appears as a no-op.
<br><br> The return value is <CODE>0</CODE> on success and in the pathological case
that it fails, the return value is <CODE>-1</CODE> and <CODE>errno</CODE> is set
accordingly. There is nothing specific that can go wrong with this
function, so there are no specific <CODE>errno</CODE> values.
<br><br>
sq~wtsched.hxq~/tvoidtinttseed48sq~
t�
The <CODE>seed48</CODE> function initializes all 48 bits of the state of the
internal random number generator from the contents of the parameter
<VAR>seed16v</VAR>. Here the lower 16 bits of the first element of
<VAR>see16v</VAR> initialize the least significant 16 bits of the internal
state, the lower 16 bits of <CODE><VAR>seed16v</VAR>[1]</CODE> initialize the mid-order
16 bits of the state and the 16 lower bits of <CODE><VAR>seed16v</VAR>[2]</CODE>
initialize the most significant 16 bits of the state.
<br><br> Unlike <CODE>srand48</CODE> this function lets the user initialize all 48 bits
of the state.
<br><br> The value returned by <CODE>seed48</CODE> is a pointer to an array containing
the values of the internal state before the change. This might be
useful to restart the random number generator at a certain state.
Otherwise the value can simply be ignored.
<br><br> As for <CODE>srand48</CODE>, the values <CODE>a</CODE> and <CODE>c</CODE> from the
congruential formula are reset to the default values.
sq~wtstdlib.hxq~6tunsigned short int seed16v[3]tunsigned short int *tseed48_rsq~
t”
This function is similar to <CODE>srand48_r</CODE> but like <CODE>seed48</CODE> it
initializes all 48 bits of the state from the parameter <VAR>seed16v</VAR>.
<br><br> If the return value is non-negative the function call succeeded. It
does not return a pointer to the previous state of the random number
generator like the <CODE>seed48</CODE> function does. If the user wants to
preserve the state for a later re-run s/he can copy the whole buffer
pointed to by <VAR>buffer</VAR>.
<br><br> This function is a GNU extension and should not be used in portable
programs.
sq~wtstdlib.hxq~=t:unsigned short int seed16v[3], struct drand48_data *buffertinttseekdirsq~
t}
The <CODE>seekdir</CODE> function sets the file position of the directory
stream <VAR>dirstream</VAR> to <VAR>pos</VAR>. The value <VAR>pos</VAR> must be the
result of a previous call to <CODE>telldir</CODE> on this particular stream;
closing and reopening the directory can invalidate values returned by
<CODE>telldir</CODE>.
sq~wtdirent.hxq~DtDIR *dirstream, long int postvoidtselectsq~
tu
The <CODE>select</CODE> function blocks the calling process until there is
activity on any of the specified sets of file descriptors, or until the
timeout period has expired.
<br><br> The file descriptors specified by the <VAR>read-fds</VAR> argument are
checked to see if they are ready for reading; the <VAR>write-fds</VAR> file
descriptors are checked to see if they are ready for writing; and the
<VAR>except-fds</VAR> file descriptors are checked for exceptional
conditions. You can pass a null pointer for any of these arguments if
you are not interested in checking for that kind of condition.
<br><br> A file descriptor is considered ready for reading if a <CODE>read</CODE>
call will not block. This usually includes the read offset being at
the end of the file or there is an error to report. A server socket
is considered ready for reading if there is a pending connection which
can be accepted with <CODE>accept</CODE>; . A
client socket is ready for writing when its connection is fully
established; .
<br><br> ``Exceptional conditions'' does not mean errors---errors are reported
immediately when an erroneous system call is executed, and do not
constitute a state of the descriptor. Rather, they include conditions
such as the presence of an urgent message on a socket. (,
for information on urgent messages.)
<br><br> The <CODE>select</CODE> function checks only the first <VAR>nfds</VAR> file
descriptors. The usual thing is to pass <CODE>FD_SETSIZE</CODE> as the value
of this argument.
<br><br> The <VAR>timeout</VAR> specifies the maximum time to wait. If you pass a
null pointer for this argument, it means to block indefinitely until one
of the file descriptors is ready. Otherwise, you should provide the
time in <CODE>struct timeval</CODE> format; see High-Resolution
Calendar. Specify zero as the time (a <CODE>struct timeval</CODE> containing
all zeros) if you want to find out which descriptors are ready without
waiting if none are ready.
<br><br> The normal return value from <CODE>select</CODE> is the total number of ready file
descriptors in all of the sets. Each of the argument sets is overwritten
with information about the descriptors that are ready for the corresponding
operation. Thus, to see if a particular descriptor <VAR>desc</VAR> has input,
use <CODE>FD_ISSET (<VAR>desc</VAR>, <VAR>read-fds</VAR>)</CODE> after <CODE>select</CODE> returns.
<br><br> If <CODE>select</CODE> returns because the timeout period expires, it returns
a value of zero.
<br><br> Any signal will cause <CODE>select</CODE> to return immediately. So if your
program uses signals, you can't rely on <CODE>select</CODE> to keep waiting
for the full time specified. If you want to be sure of waiting for a
particular amount of time, you must check for <CODE>EINTR</CODE> and repeat
the <CODE>select</CODE> with a newly calculated timeout based on the current
time. See the example below. See also Interrupted Primitives.
<br><br> If an error occurs, <CODE>select</CODE> returns <CODE>-1</CODE> and does not modify
the argument file descriptor sets. The following <CODE>errno</CODE> error
conditions are defined for this function:
<br><br> <DL>
<DT><CODE>EBADF</CODE>
<DD>
One of the file descriptor sets specified an invalid file descriptor.
<br><br> <LI> EINTR
The operation was interrupted by a signal. .
<br><br> <LI> EINVAL
The <VAR>timeout</VAR> argument is invalid; one of the components is negative
or too large.
sq~wt sys/types.hxq~KtZint nfds, fd_set *read-fds, fd_set *write-fds, fd_set *except-fds, struct timeval *timeouttinttsendsq~
t
The <CODE>send</CODE> function is like <CODE>write</CODE>, but with the additional
flags <VAR>flags</VAR>. The possible values of <VAR>flags</VAR> are described
in Socket Data Options.
<br><br> This function returns the number of bytes transmitted, or <CODE>-1</CODE> on
failure. If the socket is nonblocking, then <CODE>send</CODE> (like
<CODE>write</CODE>) can return after sending just part of the data.
, for information about nonblocking mode.
<br><br> Note, however, that a successful return value merely indicates that
the message has been sent without error, not necessarily that it has
been received without error.
<br><br> The following <CODE>errno</CODE> error conditions are defined for this function:
<br><br> <DL>
<DT><CODE>EBADF</CODE>
<DD>
The <VAR>socket</VAR> argument is not a valid file descriptor.
<br><br> <LI> EINTR
The operation was interrupted by a signal before any data was sent.
.
<br><br> <LI> ENOTSOCK
The descriptor <VAR>socket</VAR> is not a socket.
<br><br> <LI> EMSGSIZE
The socket type requires that the message be sent atomically, but the
message is too large for this to be possible.
<br><br> <LI> EWOULDBLOCK
Nonblocking mode has been set on the socket, and the write operation
would block. (Normally <CODE>send</CODE> blocks until the operation can be
completed.)
<br><br> <LI> ENOBUFS
There is not enough internal buffer space available.
<br><br> <LI> ENOTCONN
You never connected this socket.
<br><br> <LI> EPIPE
This socket was connected but the connection is now broken. In this
case, <CODE>send</CODE> generates a <CODE>SIGPIPE</CODE> signal first; if that
signal is ignored or blocked, or if its handler returns, then
<CODE>send</CODE> fails with <CODE>EPIPE</CODE>.
<br><br> This function is defined as a cancellation point in multi-threaded
programs, so one has to be prepared for this and make sure that
allocated resources (like memory, files descriptors, semaphores or
whatever) are freed even if the thread is canceled.
sq~wt sys/socket.hxq~Rt0int socket, void *buffer, size_t size, int flagstinttsendmsgsq~
t-
<br><br> This function is defined as a cancellation point in multi-threaded
programs, so one has to be prepared for this and make sure that
allocated resources (like memory, files descriptors, semaphores or
whatever) are freed even if the thread is cancel.
sq~wt sys/socket.hxq~Yt3int socket, const struct msghdr *message, int flagstinttsendtosq~
t
The <CODE>sendto</CODE> function transmits the data in the <VAR>buffer</VAR>
through the socket <VAR>socket</VAR> to the destination address specified
by the <VAR>addr</VAR> and <VAR>length</VAR> arguments. The <VAR>size</VAR> argument
specifies the number of bytes to be transmitted.
<br><br> The <VAR>flags</VAR> are interpreted the same way as for <CODE>send</CODE>; see
Socket Data Options.
<br><br> The return value and error conditions are also the same as for
<CODE>send</CODE>, but you cannot rely on the system to detect errors and
report them; the most common error is that the packet is lost or there
is no-one at the specified address to receive it, and the operating
system on your machine usually does not know this.
<br><br> It is also possible for one call to <CODE>sendto</CODE> to report an error
owing to a problem related to a previous call.
<br><br> This function is defined as a cancellation point in multi-threaded
programs, so one has to be prepared for this and make sure that
allocated resources (like memory, files descriptors, semaphores or
whatever) are freed even if the thread is canceled.
sq~wt sys/socket.hxq~`tYint socket, void *buffer, size_t size, int flags, struct sockaddr *addr, socklen_t lengthtinttsetbufsq~
t)
If <VAR>buf</VAR> is a null pointer, the effect of this function is
equivalent to calling <CODE>setvbuf</CODE> with a <VAR>mode</VAR> argument of
<CODE>_IONBF</CODE>. Otherwise, it is equivalent to calling <CODE>setvbuf</CODE>
with <VAR>buf</VAR>, and a <VAR>mode</VAR> of <CODE>_IOFBF</CODE> and a <VAR>size</VAR>
argument of <CODE>BUFSIZ</CODE>.
<br><br> The <CODE>setbuf</CODE> function is provided for compatibility with old code;
use <CODE>setvbuf</CODE> in all new programs.
sq~wtstdio.hxq~gtFILE *stream, char *buftvoidt setbuffersq~
t–
If <VAR>buf</VAR> is a null pointer, this function makes <VAR>stream</VAR> unbuffered.
Otherwise, it makes <VAR>stream</VAR> fully buffered using <VAR>buf</VAR> as the
buffer. The <VAR>size</VAR> argument specifies the length of <VAR>buf</VAR>.
<br><br> This function is provided for compatibility with old BSD code. Use
<CODE>setvbuf</CODE> instead.
sq~wtstdio.hxq~nt$FILE *stream, char *buf, size_t sizetvoidt
setcontextsq~
t&
<br><br> The <CODE>setcontext</CODE> function restores the context described by
<VAR>ucp</VAR>. The context is not modified and can be reused as often as
wanted.
<br><br> If the context was created by <CODE>getcontext</CODE> execution resumes with
the registers filled with the same values and the same stack as if the
<CODE>getcontext</CODE> call just returned.
<br><br> If the context was modified with a call to <CODE>makecontext</CODE> execution
continues with the function passed to <CODE>makecontext</CODE> which gets the
specified parameters passed. If this function returns execution is
resumed in the context which was referenced by the <CODE>uc_link</CODE>
element of the context structure passed to <CODE>makecontext</CODE> at the
time of the call. If <CODE>uc_link</CODE> was a null pointer the application
terminates in this case.
<br><br> Since the context contains information about the stack no two threads
should use the same context at the same time. The result in most cases
would be disastrous.
<br><br> The <CODE>setcontext</CODE> function does not return unless an error occurred
in which case it returns <CODE>-1</CODE>.
sq~wt
ucontext.hxq~utconst ucontext_t *ucptintt
setdomainnamesq~
t‘
domain name
domain name
<br><br> <CODE>getdomainname</CODE> sets the NIS (aka YP) domain name of the system
on which it is called. Note that this is not the more popular DNS
domain name. Set that with <CODE>sethostname</CODE>.
<br><br> The specifics of this function are analogous to <CODE>sethostname</CODE>, above.
<br><br>
sq~wtunistd.hxq~|tconst char *name, size_t lengthtinttsetegidsq~
tc
This function sets the effective group ID of the process to
<VAR>newgid</VAR>, provided that the process is allowed to change its group
ID. Just as with <CODE>seteuid</CODE>, if the process is privileged it may
change its effective group ID to any value; if it isn't, but it has a
file group ID, then it may change to its real group ID or file group ID;
otherwise it may not change its effective group ID.
<br><br> Note that a process is only privileged if its effective <EM>user</EM> ID
is zero. The effective group ID only affects access permissions.
<br><br> The return values and error conditions for <CODE>setegid</CODE> are the same
as those for <CODE>seteuid</CODE>.
<br><br> This function is only present if <CODE>_POSIX_SAVED_IDS</CODE> is defined.
sq~wtunistd.hxq~ƒt gid_t newgidtinttsetenvsq~
tÀ
The <CODE>setenv</CODE> function can be used to add a new definition to the
environment. The entry with the name <VAR>name</VAR> is replaced by the
value <samp><VAR>name</VAR>=<VAR>value</VAR></samp>. Please note that this is also true
if <VAR>value</VAR> is the empty string. To do this a new string is created
and the strings <VAR>name</VAR> and <VAR>value</VAR> are copied. A null pointer
for the <VAR>value</VAR> parameter is illegal. If the environment already
contains an entry with key <VAR>name</VAR> the <VAR>replace</VAR> parameter
controls the action. If replace is zero, nothing happens. Otherwise
the old entry is replaced by the new one.
<br><br> Please note that you cannot remove an entry completely using this function.
<br><br> This function was originally part of the BSD library but is now part of
the Unix standard.
sq~wtstdlib.hxq~Št0const char *name, const char *value, int replacetinttseteuidsq~
t_
This function sets the effective user ID of a process to <VAR>newuid</VAR>,
provided that the process is allowed to change its effective user ID. A
privileged process (effective user ID zero) can change its effective
user ID to any legal value. An unprivileged process with a file user ID
can change its effective user ID to its real user ID or to its file user
ID. Otherwise, a process may not change its effective user ID at all.
<br><br> The <CODE>seteuid</CODE> function returns a value of <CODE>0</CODE> to indicate
successful completion, and a value of <CODE>-1</CODE> to indicate an error.
The following <CODE>errno</CODE> error conditions are defined for this
function:
<br><br> <DL>
<DT><CODE>EINVAL</CODE>
<DD>
The value of the <VAR>newuid</VAR> argument is invalid.
<br><br> <LI> EPERM
The process may not change to the specified ID.
<br><br> Older systems (those without the <CODE>_POSIX_SAVED_IDS</CODE> feature) do not
have this function.
sq~wtunistd.hxq~‘t
uid_t neweuidtinttsetfsentsq~
t
This function makes sure that the internal read pointer for the
<TT>fstab</TT> file is at the beginning of the file. This is done by
either opening the file or resetting the read pointer.
<br><br> Since the file handle is internal to the libc this function is not
thread-safe.
<br><br> This function returns a non-zero value if the operation was successful
and the <CODE>getfs*</CODE> functions can be used to read the entries of the
file.
sq~wtfstab.hxq~˜tvoidtinttsetgidsq~
tØ
This function sets both the real and effective group ID of the process
to <VAR>newgid</VAR>, provided that the process is privileged. It also
deletes the file group ID, if any.
<br><br> If the process is not privileged, then <CODE>setgid</CODE> behaves like
<CODE>setegid</CODE>.
<br><br> The return values and error conditions for <CODE>setgid</CODE> are the same
as those for <CODE>seteuid</CODE>.
sq~wtunistd.hxq~Ÿt gid_t newgidtinttsetgrentsq~
t´
This function initializes a stream for reading from the group data base.
You use this stream by calling <CODE>getgrent</CODE> or <CODE>getgrent_r</CODE>.
sq~wtgrp.hxq~¦tvoidtvoidt setgroupssq~
t$
This function sets the process's supplementary group IDs. It can only
be called from privileged processes. The <VAR>count</VAR> argument specifies
the number of group IDs in the array <VAR>groups</VAR>.
<br><br> This function returns <CODE>0</CODE> if successful and <CODE>-1</CODE> on error.
The following <CODE>errno</CODE> error conditions are defined for this
function:
<br><br> <DL>
<DT><CODE>EPERM</CODE>
<DD>
The calling process is not privileged.
sq~wtgrp.hxq~­tsize_t count, gid_t *groupstintt
sethostentsq~
t
This function opens the hosts database to begin scanning it. You can
then call <CODE>gethostent</CODE> to read the entries.
<br><br> If the <VAR>stayopen</VAR> argument is nonzero, this sets a flag so that
subsequent calls to <CODE>gethostbyname</CODE> or <CODE>gethostbyaddr</CODE> will
not close the database (as they usually would). This makes for more
efficiency if you call those functions several times, by avoiding
reopening the database for each call.
sq~wtnetdb.hxq~´t int stayopentvoidt sethostidsq~
t�
The <CODE>sethostid</CODE> function sets the ``host ID'' of the host machine
to <VAR>id</VAR>. Only privileged processes are permitted to do this. Usually
it happens just once, at system boot time.
<br><br> The proper way to establish the primary IP address of a system
is to configure the IP address resolver to associate that IP address with
the system's host name as returned by <CODE>gethostname</CODE>. For example,
put a record for the system in <TT>/etc/hosts</TT>.
<br><br> See <CODE>gethostid</CODE> above for more information on host ids.
<br><br> The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on failure.
The following <CODE>errno</CODE> error conditions are defined for this function:
<br><br> <DL>
<DT><CODE>EPERM</CODE>
<DD>
This process cannot set the host name because it is not privileged.
<br><br> <LI> ENOSYS
The operating system does not support setting the host ID. On some
systems, the host ID is a meaningless but unique number hard-coded for
each machine.
sq~wtunistd.hxq~»t long int idtintt sethostnamesq~
t‘
The <CODE>sethostname</CODE> function sets the host name of the system that
calls it to <VAR>name</VAR>, a string with length <VAR>length</VAR>. Only
privileged processes are permitted to do this.
<br><br> Usually <CODE>sethostname</CODE> gets called just once, at system boot time.
Often, the program that calls it sets it to the value it finds in the
file <CODE>/etc/hostname</CODE>.
/etc/hostname
<br><br> Be sure to set the host name to the full host name, not just the DNS
hostname (see above).
<br><br> The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on failure.
The following <CODE>errno</CODE> error condition is defined for this function:
<br><br> <DL>
<DT><CODE>EPERM</CODE>
<DD>
This process cannot set the host name because it is not privileged.
sq~wtunistd.hxq~Âtconst char *name, size_t lengthtintt setitimersq~
t
The <CODE>setitimer</CODE> function sets the timer specified by <VAR>which</VAR>
according to <VAR>new</VAR>. The <VAR>which</VAR> argument can have a value of
<CODE>ITIMER_REAL</CODE>, <CODE>ITIMER_VIRTUAL</CODE>, or <CODE>ITIMER_PROF</CODE>.
<br><br> If <VAR>old</VAR> is not a null pointer, <CODE>setitimer</CODE> returns information
about any previous unexpired timer of the same kind in the structure it
points to.
<br><br> The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on failure. The
following <CODE>errno</CODE> error conditions are defined for this function:
<br><br> <DL>
<DT><CODE>EINVAL</CODE>
<DD>
The timer period is too large.
sq~wttime.ht
sys/time.hxq~Ét7int which, struct itimerval *new, struct itimerval *oldtinttsetkeysq~
t„
<br><br> The <CODE>setkey</CODE> function sets an internal data structure to be an
expanded form of <VAR>key</VAR>. <VAR>key</VAR> is specified as an array of 64
bits each stored in a <CODE>char</CODE>, the first bit is <CODE>key[0]</CODE> and
the 64th bit is <CODE>key[63]</CODE>. The <VAR>key</VAR> should have the correct
parity.
sq~wtcrypt.hxq~Ñtconst char *keytvoidtsetkey_rsq~
tS
<br><br> These are reentrant versions of <CODE>setkey</CODE> and <CODE>encrypt</CODE>. The
only difference is the extra parameter, which stores the expanded
version of <VAR>key</VAR>. Before calling <CODE>setkey_r</CODE> the first time,
<CODE>data->initialized</CODE> must be cleared to zero.
sq~wtcrypt.hxq~Øt+const char *key, {struct crypt_data *} datatvoidt
setlinebufsq~
tñ
This function makes <VAR>stream</VAR> be line buffered, and allocates the
buffer for you.
<br><br> This function is provided for compatibility with old BSD code. Use
<CODE>setvbuf</CODE> instead.
sq~wtstdio.hxq~ßt FILE *streamtvoidt setlocalesq~
t ‚
The function <CODE>setlocale</CODE> sets the current locale for category
<VAR>category</VAR> to <VAR>locale</VAR>. A list of all the locales the system
provides can be created by running
<br><br> <pre><br>
locale -a<br>
</pre>
<br><br> If <VAR>category</VAR> is <CODE>LC_ALL</CODE>, this specifies the locale for all
purposes. The other possible values of <VAR>category</VAR> specify an
single purpose .
<br><br> You can also use this function to find out the current locale by passing
a null pointer as the <VAR>locale</VAR> argument. In this case,
<CODE>setlocale</CODE> returns a string that is the name of the locale
currently selected for category <VAR>category</VAR>.
<br><br> The string returned by <CODE>setlocale</CODE> can be overwritten by subsequent
calls, so you should make a copy of the string if you want to save it past any further calls to
<CODE>setlocale</CODE>. (The standard library is guaranteed never to call
<CODE>setlocale</CODE> itself.)
<br><br> You should not modify the string returned by <CODE>setlocale</CODE>. It might
be the same string that was passed as an argument in a previous call to
<CODE>setlocale</CODE>. One requirement is that the <VAR>category</VAR> must be
the same in the call the string was returned and the one when the string
is passed in as <VAR>locale</VAR> parameter.
<br><br> When you read the current locale for category <CODE>LC_ALL</CODE>, the value
encodes the entire combination of selected locales for all categories.
In this case, the value is not just a single locale name. In fact, we
don't make any promises about what it looks like. But if you specify
the same ``locale name'' with <CODE>LC_ALL</CODE> in a subsequent call to
<CODE>setlocale</CODE>, it restores the same combination of locale selections.
<br><br> To be sure you can use the returned string encoding the currently selected
locale at a later time, you must make a copy of the string. It is not
guaranteed that the returned pointer remains valid over time.
<br><br> When the <VAR>locale</VAR> argument is not a null pointer, the string returned
by <CODE>setlocale</CODE> reflects the newly-modified locale.
<br><br> If you specify an empty string for <VAR>locale</VAR>, this means to read the
appropriate environment variable and use its value to select the locale
for <VAR>category</VAR>.
<br><br> If a nonempty string is given for <VAR>locale</VAR>, then the locale of that
name is used if possible.
<br><br> If you specify an invalid locale name, <CODE>setlocale</CODE> returns a null
pointer and leaves the current locale unchanged.
sq~wtunistd.htlocale.hxq~æt int category, const char *localetchar *t
setlogmasksq~
t
<br><br> <CODE>setlogmask</CODE> sets a mask (the ``logmask'') that determines which
future <CODE>syslog</CODE> calls shall be ignored. If a program has not
called <CODE>setlogmask</CODE>, <CODE>syslog</CODE> doesn't ignore any calls. You
can use <CODE>setlogmask</CODE> to specify that messages of particular
priorities shall be ignored in the future.
<br><br> A <CODE>setlogmask</CODE> call overrides any previous <CODE>setlogmask</CODE> call.
<br><br> Note that the logmask exists entirely independently of opening and
closing of Syslog connections.
<br><br> Setting the logmask has a similar effect to, but is not the same as,
configuring Syslog. The Syslog configuration may cause Syslog to
discard certain messages it receives, but the logmask causes certain
messages never to get submitted to Syslog in the first place.
<br><br> <VAR>mask</VAR> is a bit string with one bit corresponding to each of the
possible message priorities. If the bit is on, <CODE>syslog</CODE> handles
messages of that priority normally. If it is off, <CODE>syslog</CODE>
discards messages of that priority. Use the message priority macros
described in syslog; vsyslog and the <CODE>LOG_MASK</CODE> to construct
an appropriate <VAR>mask</VAR> value, as in this example:
<br><br> <pre><br>
LOG_MASK(LOG_EMERG) | LOG_MASK(LOG_ERROR)<br>
</pre><br>
<br><br> or<br>
<br><br> <pre><br>
~(LOG_MASK(LOG_INFO))<br>
</pre><br>
<br><br> There is also a <CODE>LOG_UPTO</CODE> macro, which generates a mask with the bits<br>
on for a certain priority and all priorities above it:<br>
<br><br> <pre><br>
LOG_UPTO(LOG_ERROR)<br>
</pre>
<br><br> The unfortunate naming of the macro is due to the fact that internally,
higher numbers are used for lower message priorities.
<br><br>
sq~wtsyslog.hxq~îtint masktintt setmntentsq~
tÇ
The <CODE>setmntent</CODE> function prepares the file named <VAR>FILE</VAR> which
must be in the format of a <TT>fstab</TT> and <TT>mtab</TT> file for the
upcoming processing through the other functions of the family. The
<VAR>mode</VAR> parameter can be chosen in the way the <VAR>opentype</VAR>
parameter for <CODE>fopen</CODE> can be chosen. If
the file is opened for writing the file is also allowed to be empty.
<br><br> If the file was successfully opened <CODE>setmntent</CODE> returns a file
descriptor for future use. Otherwise the return value is <CODE>NULL</CODE>
and <CODE>errno</CODE> is set accordingly.
sq~wtmntent.hxq~õt"const char *file, const char *modetFILE *t setnetentsq~
tÄ
This function opens and rewinds the networks database.
<br><br> If the <VAR>stayopen</VAR> argument is nonzero, this sets a flag so that
subsequent calls to <CODE>getnetbyname</CODE> or <CODE>getnetbyaddr</CODE> will
not close the database (as they usually would). This makes for more
efficiency if you call those functions several times, by avoiding
reopening the database for each call.
sq~wtnetdb.hxq~üt int stayopentvoidt setnetgrentsq~
tè
A call to this function initializes the internal state of the library to
allow following calls of the <CODE>getnetgrent</CODE> to iterate over all entries
in the netgroup with name <VAR>netgroup</VAR>.
<br><br> When the call is successful (i.e., when a netgroup with this name exists)
the return value is <CODE>1</CODE>. When the return value is <CODE>0</CODE> no
netgroup of this name is known or some other error occurred.
sq~wtnetdb.hxq~tconst char *netgrouptinttsetpgidsq~
tœ
The <CODE>setpgid</CODE> function puts the process <VAR>pid</VAR> into the process
group <VAR>pgid</VAR>. As a special case, either <VAR>pid</VAR> or <VAR>pgid</VAR> can
be zero to indicate the process ID of the calling process.
<br><br> This function fails on a system that does not support job control.
, for more information.
<br><br> If the operation is successful, <CODE>setpgid</CODE> returns zero. Otherwise
it returns <CODE>-1</CODE>. The following <CODE>errno</CODE> error conditions are
defined for this function:
<br><br> <DL>
<DT><CODE>EACCES</CODE>
<DD>
The child process named by <VAR>pid</VAR> has executed an <CODE>exec</CODE>
function since it was forked.
<br><br> <LI> EINVAL
The value of the <VAR>pgid</VAR> is not valid.
<br><br> <LI> ENOSYS
The system doesn't support job control.
<br><br> <LI> EPERM
The process indicated by the <VAR>pid</VAR> argument is a session leader,
or is not in the same session as the calling process, or the value of
the <VAR>pgid</VAR> argument doesn't match a process group ID in the same
session as the calling process.
<br><br> <LI> ESRCH
The process indicated by the <VAR>pid</VAR> argument is not the calling
process or a child of the calling process.
sq~wtunistd.hxq~
tpid_t pid, pid_t pgidtinttsetpgrpsq~
ty
This is the BSD Unix name for <CODE>setpgid</CODE>. Both functions do exactly
the same thing.
sq~wtunistd.hxq~tpid_t pid, pid_t pgidtintt setprioritysq~
to
Set the nice value of a set of processes to <VAR>niceval</VAR>; <VAR>class</VAR>
and <VAR>id</VAR> specify which ones (see below).
<br><br> The return value is <CODE>0</CODE> on success, and <CODE>-1</CODE> on
failure. The following <CODE>errno</CODE> error condition are possible for
this function:
<br><br> <DL>
<DT><CODE>ESRCH</CODE>
<DD>
The combination of <VAR>class</VAR> and <VAR>id</VAR> does not match any existing
process.
<br><br> <LI> EINVAL
The value of <VAR>class</VAR> is not valid.
<br><br> <LI> EPERM
The call would set the nice value of a process which is owned by a different
user than the calling process (i.e., the target process' real or effective
uid does not match the calling process' effective uid) and the calling
process does not have <CODE>CAP_SYS_NICE</CODE> permission.
<br><br> <LI> EACCES
The call would lower the process' nice value and the process does not have
<CODE>CAP_SYS_NICE</CODE> permission.
<br><br>
sq~wtsys/resource.hxq~tint class, int id, int nicevaltintt setprotoentsq~
tÔ
This function opens the protocols database to begin scanning it.
<br><br> If the <VAR>stayopen</VAR> argument is nonzero, this sets a flag so that
subsequent calls to <CODE>getprotobyname</CODE> or <CODE>getprotobynumber</CODE> will
not close the database (as they usually would). This makes for more
efficiency if you call those functions several times, by avoiding
reopening the database for each call.
sq~wtnetdb.hxq~t int stayopentvoidtsetpwentsq~
t”
This function initializes a stream which <CODE>getpwent</CODE> and
<CODE>getpwent_r</CODE> use to read the user database.
sq~wtpwd.hxq~&tvoidtvoidtsetregidsq~
ty
This function sets the real group ID of the process to <VAR>rgid</VAR> and
the effective group ID to <VAR>egid</VAR>. If <VAR>rgid</VAR> is <CODE>-1</CODE>, it
means not to change the real group ID; likewise if <VAR>egid</VAR> is
<CODE>-1</CODE>, it means not to change the effective group ID.
<br><br> The <CODE>setregid</CODE> function is provided for compatibility with 4.3 BSD
Unix, which does not support file IDs. You can use this function to
swap the effective and real group IDs of the process. (Privileged
processes are not limited to this usage.) If file IDs are supported,
you should use that feature instead of using this function.
.
<br><br> The return values and error conditions for <CODE>setregid</CODE> are the same
as those for <CODE>setreuid</CODE>.
sq~wtunistd.hxq~-tgid_t rgid, gid_t egidtinttsetreuidsq~
tb
This function sets the real user ID of the process to <VAR>ruid</VAR> and the
effective user ID to <VAR>euid</VAR>. If <VAR>ruid</VAR> is <CODE>-1</CODE>, it means
not to change the real user ID; likewise if <VAR>euid</VAR> is <CODE>-1</CODE>, it
means not to change the effective user ID.
<br><br> The <CODE>setreuid</CODE> function exists for compatibility with 4.3 BSD Unix,
which does not support file IDs. You can use this function to swap the
effective and real user IDs of the process. (Privileged processes are
not limited to this particular usage.) If file IDs are supported, you
should use that feature instead of this function. .
<br><br> The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on failure.
The following <CODE>errno</CODE> error conditions are defined for this
function:
<br><br> <DL>
<DT><CODE>EPERM</CODE>
<DD>
The process does not have the appropriate privileges; you do not
have permission to change to the specified ID.
sq~wtunistd.hxq~4tuid_t ruid, uid_t euidtintt setrlimitsq~
t;
Store the current and maximum limits for the resource <VAR>resource</VAR>
in <CODE>*<VAR>rlp</VAR></CODE>.
<br><br> The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on failure. The
following <CODE>errno</CODE> error condition is possible:
<br><br> <DL>
<DT><CODE>EPERM</CODE>
<DD>
<OL>
<LI>
The process tried to raise a current limit beyond the maximum limit.
<br><br> <LI>
The process tried to raise a maximum limit, but is not superuser.
</OL>
<br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> on a
32-bit system this function is in fact <CODE>setrlimit64</CODE>. Thus, the
LFS interface transparently replaces the old interface.
sq~wtsys/resource.hxq~;t&int resource, const struct rlimit *rlptintt setrlimit64sq~
t
This function is similar to <CODE>setrlimit</CODE> but its second parameter is
a pointer to a variable of type <CODE>struct rlimit64</CODE> which allows it
to set values which wouldn't fit in the member of a <CODE>struct
rlimit</CODE>.
<br><br> If the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> on a
32-bit machine this function is available under the name
<CODE>setrlimit</CODE> and so transparently replaces the old interface.
sq~wtsys/resource.hxq~Bt(int resource, const struct rlimit64 *rlptintt
setserventsq~
tÏ
This function opens the services database to begin scanning it.
<br><br> If the <VAR>stayopen</VAR> argument is nonzero, this sets a flag so that
subsequent calls to <CODE>getservbyname</CODE> or <CODE>getservbyport</CODE> will
not close the database (as they usually would). This makes for more
efficiency if you call those functions several times, by avoiding
reopening the database for each call.
sq~wtnetdb.hxq~It int stayopentvoidtsetsidsq~
tÏ
The <CODE>setsid</CODE> function creates a new session. The calling process
becomes the session leader, and is put in a new process group whose
process group ID is the same as the process ID of that process. There
are initially no other processes in the new process group, and no other
process groups in the new session.
<br><br> This function also makes the calling process have no controlling terminal.
<br><br> The <CODE>setsid</CODE> function returns the new process group ID of the
calling process if successful. A return value of <CODE>-1</CODE> indicates an
error. The following <CODE>errno</CODE> error conditions are defined for this
function:
<br><br> <DL>
<DT><CODE>EPERM</CODE>
<DD>
The calling process is already a process group leader, or there is
already another process group around that has the same process group ID.
sq~wtstdio.htunistd.hxq~Ptvoidtpid_tt
setsockoptsq~
t�
This function is used to set the socket option <VAR>optname</VAR> at level
<VAR>level</VAR> for socket <VAR>socket</VAR>. The value of the option is passed
in the buffer <VAR>optval</VAR> of size <VAR>optlen</VAR>.
<br><br>
The return value and error codes for <CODE>setsockopt</CODE> are the same as
for <CODE>getsockopt</CODE>.
<br><br>
sq~wt sys/socket.hxq~XtBint socket, int level, int optname, void *optval, socklen_t optlentinttsetstatesq~
t
The <CODE>setstate</CODE> function restores the random number state
information <VAR>state</VAR>. The argument must have been the result of
a previous call to <VAR>initstate</VAR> or <VAR>setstate</VAR>.
<br><br> The return value is the previous value of the state information array.
You can use this value later as an argument to <CODE>setstate</CODE> to
restore that state.
<br><br> If the function fails the return value is <CODE>NULL</CODE>.
sq~wtstdlib.hxq~_t void *statetvoid *t
setstate_rsq~
tø
The <CODE>setstate_r</CODE> function behaves exactly like the <CODE>setstate</CODE>
function except that it uses and modifies the state in the object
pointed to by the first parameter instead of the global state.
sq~wtstdlib.hxq~ft9char *restrict statebuf, struct random_data *restrict buftintt settimeofdaysq~
t‚
The <CODE>settimeofday</CODE> function sets the current calendar time in the
system clock according to the arguments. As for <CODE>gettimeofday</CODE>,
the calendar time is represented as the elapsed time since the epoch.
As for <CODE>gettimeofday</CODE>, time zone information is ignored if
<VAR>tzp</VAR> is a null pointer.
<br><br> You must be a privileged user in order to use <CODE>settimeofday</CODE>.
<br><br> Some kernels automatically set the system clock from some source such as
a hardware clock when they start up. Others, including Linux, place the
system clock in an ``invalid'' state (in which attempts to read the clock
fail). A call of <CODE>stime</CODE> removes the system clock from an invalid
state, and system startup scripts typically run a program that calls
<CODE>stime</CODE>.
<br><br> <CODE>settimeofday</CODE> causes a sudden jump forwards or backwards, which
can cause a variety of problems in a system. Use <CODE>adjtime</CODE> (below)
to make a smooth transition from one time to another by temporarily
speeding up or slowing down the clock.
<br><br> With a Linux kernel, <CODE>adjtimex</CODE> does the same thing and can also
make permanent changes to the speed of the system clock so it doesn't
need to be corrected as often.
<br><br> The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on failure. The
following <CODE>errno</CODE> error conditions are defined for this function:
<br><br> <DL>
<DT><CODE>EPERM</CODE>
<DD>
This process cannot set the clock because it is not privileged.
<br><br> <LI> ENOSYS
The operating system does not support setting time zone information, and
<VAR>tzp</VAR> is not a null pointer.
sq~wt
sys/time.hxq~mt4const struct timeval *tp, const struct timezone *tzptinttsetuidsq~
t�
If the calling process is privileged, this function sets both the real
and effective user ID of the process to <VAR>newuid</VAR>. It also deletes
the file user ID of the process, if any. <VAR>newuid</VAR> may be any
legal value. (Once this has been done, there is no way to recover the
old effective user ID.)
<br><br> If the process is not privileged, and the system supports the
<CODE>_POSIX_SAVED_IDS</CODE> feature, then this function behaves like
<CODE>seteuid</CODE>.
<br><br> The return values and error conditions are the same as for <CODE>seteuid</CODE>.
sq~wtunistd.hxq~tt uid_t newuidtinttsetutentsq~
tq
This function opens the user accounting database to begin scanning it.
You can then call <CODE>getutent</CODE>, <CODE>getutid</CODE> or <CODE>getutline</CODE> to
read entries and <CODE>pututline</CODE> to write entries.
<br><br> If the database is already open, it resets the input to the beginning of
the database.
sq~wtstdio.htutmp.hxq~{tvoidtvoidt setutxentsq~
t‘
This function is similar to <CODE>setutent</CODE>. On the GNU system it is
simply an alias for <CODE>setutent</CODE>.
sq~wtutmpx.hxq~ƒtvoidtvoidtsetvbufsq~
tê
This function is used to specify that the stream <VAR>stream</VAR> should
have the buffering mode <VAR>mode</VAR>, which can be either <CODE>_IOFBF</CODE>
(for full buffering), <CODE>_IOLBF</CODE> (for line buffering), or
<CODE>_IONBF</CODE> (for unbuffered input/output).
<br><br> If you specify a null pointer as the <VAR>buf</VAR> argument, then <CODE>setvbuf</CODE>
allocates a buffer itself using <CODE>malloc</CODE>. This buffer will be freed
when you close the stream.
<br><br> Otherwise, <VAR>buf</VAR> should be a character array that can hold at least
<VAR>size</VAR> characters. You should not free the space for this array as
long as the stream remains open and this array remains its buffer. You
should usually either allocate it statically, or <CODE>malloc</CODE>
the buffer. Using an automatic array
is not a good idea unless you close the file before exiting the block
that declares the array.
<br><br> While the array remains a stream buffer, the stream I/O functions will
use the buffer for their internal purposes. You shouldn't try to access
the values in the array directly while the stream is using it for
buffering.
<br><br> The <CODE>setvbuf</CODE> function returns zero on success, or a nonzero value
if the value of <VAR>mode</VAR> is not valid or if the request could not
be honored.
sq~wtstdio.hxq~Št.FILE *stream, char *buf, int mode, size_t sizetinttshutdownsq~
tK
The <CODE>shutdown</CODE> function shuts down the connection of socket
<VAR>socket</VAR>. The argument <VAR>how</VAR> specifies what action to
perform:
<br><br> <DL>
<DT><CODE>0</CODE>
<DD>
Stop receiving data for this socket. If further data arrives,
reject it.
<br><br> <DT><CODE>1</CODE>
<DD>
Stop trying to transmit data from this socket. Discard any data
waiting to be sent. Stop looking for acknowledgement of data already
sent; don't retransmit it if it is lost.
<br><br> <LI> 2
Stop both reception and transmission.
<br><br> The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on failure. The
following <CODE>errno</CODE> error conditions are defined for this function:
<br><br> <DL>
<LI> EBADF
<VAR>socket</VAR> is not a valid file descriptor.
<br><br> <LI> ENOTSOCK
<VAR>socket</VAR> is not a socket.
<br><br> <LI> ENOTCONN
<VAR>socket</VAR> is not connected.
sq~wt sys/socket.hxq~‘tint socket, int howtintt sigactionsq~
tw
The <VAR>action</VAR> argument is used to set up a new action for the signal
<VAR>signum</VAR>, while the <VAR>old-action</VAR> argument is used to return
information about the action previously associated with this symbol.
(In other words, <VAR>old-action</VAR> has the same purpose as the
<CODE>signal</CODE> function's return value---you can check to see what the
old action in effect for the signal was, and restore it later if you
want.)
<br><br> Either <VAR>action</VAR> or <VAR>old-action</VAR> can be a null pointer. If
<VAR>old-action</VAR> is a null pointer, this simply suppresses the return
of information about the old action. If <VAR>action</VAR> is a null pointer,
the action associated with the signal <VAR>signum</VAR> is unchanged; this
allows you to inquire about how a signal is being handled without changing
that handling.
<br><br> The return value from <CODE>sigaction</CODE> is zero if it succeeds, and
<CODE>-1</CODE> on failure. The following <CODE>errno</CODE> error conditions are
defined for this function:
<br><br> <DL>
<DT><CODE>EINVAL</CODE>
<DD>
The <VAR>signum</VAR> argument is not valid, or you are trying to
trap or ignore <CODE>SIGKILL</CODE> or <CODE>SIGSTOP</CODE>.
sq~wtsignal.hxq~˜tZint signum, const struct sigaction *restrict action, struct sigaction *restrict old-actiontintt sigaddsetsq~
t
This function adds the signal <VAR>signum</VAR> to the signal set <VAR>set</VAR>.
All <CODE>sigaddset</CODE> does is modify <VAR>set</VAR>; it does not block or
unblock any signals.
<br><br> The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on failure.
The following <CODE>errno</CODE> error condition is defined for this function:
<br><br> <DL>
<DT><CODE>EINVAL</CODE>
<DD>
The <VAR>signum</VAR> argument doesn't specify a valid signal.
sq~wtsignal.hxq~Ÿtsigset_t *set, int signumtintt sigaltstacksq~
ts
The <CODE>sigaltstack</CODE> function specifies an alternate stack for use
during signal handling. When a signal is received by the process and
its action indicates that the signal stack is used, the system arranges
a switch to the currently installed signal stack while the handler for
that signal is executed.
<br><br> If <VAR>oldstack</VAR> is not a null pointer, information about the currently
installed signal stack is returned in the location it points to. If
<VAR>stack</VAR> is not a null pointer, then this is installed as the new
stack for use by signal handlers.
<br><br> The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on failure. If
<CODE>sigaltstack</CODE> fails, it sets <CODE>errno</CODE> to one of these values:
<br><br> <DL>
<DT><CODE>EINVAL</CODE>
<DD>
You tried to disable a stack that was in fact currently in use.
<br><br> <LI> ENOMEM
The size of the alternate stack was too small.
It must be greater than <CODE>MINSIGSTKSZ</CODE>.
sq~wtsignal.hxq~¦t9const stack_t *restrict stack, stack_t *restrict oldstacktinttsigblocksq~
t2
This function is equivalent to <CODE>sigprocmask</CODE> with a <VAR>how</VAR> argument of <CODE>SIG_BLOCK</CODE>: it adds the
signals specified by <VAR>mask</VAR> to the calling process's set of blocked
signals. The return value is the previous set of blocked signals.
sq~wtsignal.hxq~­tint masktintt sigdelsetsq~
t;
This function removes the signal <VAR>signum</VAR> from the signal set
<VAR>set</VAR>. All <CODE>sigdelset</CODE> does is modify <VAR>set</VAR>; it does not
block or unblock any signals. The return value and error conditions are
the same as for <CODE>sigaddset</CODE>.
sq~wtsignal.hxq~´tsigset_t *set, int signumtintt sigemptysetsq~
tœ
This function initializes the signal set <VAR>set</VAR> to exclude all of the
defined signals. It always returns <CODE>0</CODE>.
sq~wtsignal.hxq~»t
sigset_t *settintt
sigfillsetsq~
t¥
This function initializes the signal set <VAR>set</VAR> to include
all of the defined signals. Again, the return value is <CODE>0</CODE>.
sq~wtsignal.hxq~Ât
sigset_t *settintt siginterruptsq~
t„
This function specifies which approach to use when certain primitives
are interrupted by handling signal <VAR>signum</VAR>. If <VAR>failflag</VAR> is
false, signal <VAR>signum</VAR> restarts primitives. If <VAR>failflag</VAR> is
true, handling <VAR>signum</VAR> causes these primitives to fail with error
code <CODE>EINTR</CODE>. .
sq~wtsignal.hxq~Étint signum, int failflagtintt sigismembersq~
t
The <CODE>sigismember</CODE> function tests whether the signal <VAR>signum</VAR> is
a member of the signal set <VAR>set</VAR>. It returns <CODE>1</CODE> if the signal
is in the set, <CODE>0</CODE> if not, and <CODE>-1</CODE> if there is an error.
<br><br> The following <CODE>errno</CODE> error condition is defined for this function:
<br><br> <DL>
<DT><CODE>EINVAL</CODE>
<DD>
The <VAR>signum</VAR> argument doesn't specify a valid signal.
sq~wtsignal.hxq~Ðtconst sigset_t *set, int signumtintt
siglongjmpsq~
t8
This is similar to <CODE>longjmp</CODE> except for the type of its <VAR>state</VAR>
argument. If the <CODE>sigsetjmp</CODE> call that set this <VAR>state</VAR> used a
nonzero <VAR>savesigs</VAR> flag, <CODE>siglongjmp</CODE> also restores the set of
blocked signals.
sq~wtsetjmp.hxq~×tsigjmp_buf state, int valuetvoidtsignalsq~
t Á
The <CODE>signal</CODE> function establishes <VAR>action</VAR> as the action for
the signal <VAR>signum</VAR>.
<br><br> The first argument, <VAR>signum</VAR>, identifies the signal whose behavior
you want to control, and should be a signal number. The proper way to
specify a signal number is with one of the symbolic signal names
---don't use an explicit number, because
the numerical code for a given kind of signal may vary from operating
system to operating system.
<br><br> The second argument, <VAR>action</VAR>, specifies the action to use for the
signal <VAR>signum</VAR>. This can be one of the following:
<br><br> <DL>
<DT><CODE>SIG_DFL</CODE>
<DD>
action for a signal
<CODE>SIG_DFL</CODE> specifies the default action for the particular signal.
The default actions for various kinds of signals are stated in
Standard Signals.
<br><br> <DT><CODE>SIG_IGN</CODE>
<DD>
action for a signal
<CODE>SIG_IGN</CODE> specifies that the signal should be ignored.
<br><br> Your program generally should not ignore signals that represent serious
events or that are normally used to request termination. You cannot
ignore the <CODE>SIGKILL</CODE> or <CODE>SIGSTOP</CODE> signals at all. You can
ignore program error signals like <CODE>SIGSEGV</CODE>, but ignoring the error
won't enable the program to continue executing meaningfully. Ignoring
user requests such as <CODE>SIGINT</CODE>, <CODE>SIGQUIT</CODE>, and <CODE>SIGTSTP</CODE>
is unfriendly.
<br><br> When you do not wish signals to be delivered during a certain part of
the program, the thing to do is to block them, not ignore them.
.
<br><br> <LI> <VAR>handler</VAR>
Supply the address of a handler function in your program, to specify
running this handler as the way to deliver the signal.
<br><br> For more information about defining signal handler functions,
see Defining Handlers.
<br><br> If you set the action for a signal to <CODE>SIG_IGN</CODE>, or if you set it
to <CODE>SIG_DFL</CODE> and the default action is to ignore that signal, then
any pending signals of that type are discarded (even if they are
blocked). Discarding the pending signals means that they will never be
delivered, not even if you subsequently specify another action and
unblock this kind of signal.
<br><br> The <CODE>signal</CODE> function returns the action that was previously in
effect for the specified <VAR>signum</VAR>. You can save this value and
restore it later by calling <CODE>signal</CODE> again.
<br><br> If <CODE>signal</CODE> can't honor the request, it returns <CODE>SIG_ERR</CODE>
instead. The following <CODE>errno</CODE> error conditions are defined for
this function:
<br><br> <DL>
<LI> EINVAL
You specified an invalid <VAR>signum</VAR>; or you tried to ignore or provide
a handler for <CODE>SIGKILL</CODE> or <CODE>SIGSTOP</CODE>.
sq~wtsignal.hxq~Þtint signum, sighandler_t actiont sighandler_ttsignbitsq~
tÁ
<CODE>signbit</CODE> is a generic macro which can work on all floating-point
types. It returns a nonzero value if the value of <VAR>x</VAR> has its sign
bit set.
<br><br> This is not the same as <CODE>x < 0.0</CODE>, because IEEE 754 floating
point allows zero to be signed. The comparison <CODE>-0.0 < 0.0</CODE> is
false, but <CODE>signbit (-0.0)</CODE> will return a nonzero value.
sq~wtmath.hxq~åt xtintt significandsq~
tJ
<CODE>significand</CODE> returns the mantissa of <VAR>x</VAR> scaled to the range
[1, 2).
It is equivalent to <CODE>scalb (<VAR>x</VAR>, (double) -ilogb (<VAR>x</VAR>))</CODE>.
<br><br> This function exists mainly for use in certain standardized tests
of IEEE 754 conformance.
sq~wtmath.hxq~ìtdouble xt
long long intt significandfsq~
tJ
<CODE>significand</CODE> returns the mantissa of <VAR>x</VAR> scaled to the range
[1, 2).
It is equivalent to <CODE>scalb (<VAR>x</VAR>, (double) -ilogb (<VAR>x</VAR>))</CODE>.
<br><br> This function exists mainly for use in certain standardized tests
of IEEE 754 conformance.
sq~wtmath.hxq~ótfloat xt
long long intt significandlsq~
tJ
<CODE>significand</CODE> returns the mantissa of <VAR>x</VAR> scaled to the range
[1, 2).
It is equivalent to <CODE>scalb (<VAR>x</VAR>, (double) -ilogb (<VAR>x</VAR>))</CODE>.
<br><br> This function exists mainly for use in certain standardized tests
of IEEE 754 conformance.
sq~wtmath.hxq~út
long double xt
long long inttsigpausesq~
tý
This function is the equivalent of <CODE>sigsuspend</CODE> : it sets the calling process's signal mask to <VAR>mask</VAR>,
and waits for a signal to arrive. On return the previous set of blocked
signals is restored.
sq~wtsignal.hxq~tint masktintt
sigpendingsq~
tÞ
The <CODE>sigpending</CODE> function stores information about pending signals
in <VAR>set</VAR>. If there is a pending signal that is blocked from
delivery, then that signal is a member of the returned set. (You can
test whether a particular signal is a member of this set using
<CODE>sigismember</CODE>; see Signal Sets.)
<br><br> The return value is <CODE>0</CODE> if successful, and <CODE>-1</CODE> on failure.
sq~wtsignal.hxq~t
sigset_t *settintt sigprocmasksq~
t Ž
The <CODE>sigprocmask</CODE> function is used to examine or change the calling
process's signal mask. The <VAR>how</VAR> argument determines how the signal
mask is changed, and must be one of the following values:
<br><br> <DL>
<DT><CODE>SIG_BLOCK</CODE>
<DD>
Block the signals in <CODE>set</CODE>---add them to the existing mask. In
other words, the new mask is the union of the existing mask and
<VAR>set</VAR>.
<br><br>
<DT><CODE>SIG_UNBLOCK</CODE>
<DD>
Unblock the signals in <VAR>set</VAR>---remove them from the existing mask.
<br><br>
<LI> SIG_SETMASK
Use <VAR>set</VAR> for the mask; ignore the previous value of the mask.
<br><br> The last argument, <VAR>oldset</VAR>, is used to return information about the
old process signal mask. If you just want to change the mask without
looking at it, pass a null pointer as the <VAR>oldset</VAR> argument.
Similarly, if you want to know what's in the mask without changing it,
pass a null pointer for <VAR>set</VAR> (in this case the <VAR>how</VAR> argument
is not significant). The <VAR>oldset</VAR> argument is often used to
remember the previous signal mask in order to restore it later. (Since
the signal mask is inherited over <CODE>fork</CODE> and <CODE>exec</CODE> calls, you
can't predict what its contents are when your program starts running.)
<br><br> If invoking <CODE>sigprocmask</CODE> causes any pending signals to be
unblocked, at least one of those signals is delivered to the process
before <CODE>sigprocmask</CODE> returns. The order in which pending signals
are delivered is not specified, but you can control the order explicitly
by making multiple <CODE>sigprocmask</CODE> calls to unblock various signals
one at a time.
<br><br> The <CODE>sigprocmask</CODE> function returns <CODE>0</CODE> if successful, and <CODE>-1</CODE>
to indicate an error. The following <CODE>errno</CODE> error conditions are
defined for this function:
<br><br> <DL>
<LI> EINVAL
The <VAR>how</VAR> argument is invalid.
<br><br> You can't block the <CODE>SIGKILL</CODE> and <CODE>SIGSTOP</CODE> signals, but
if the signal set includes these, <CODE>sigprocmask</CODE> just ignores
them instead of returning an error status.
<br><br> Remember, too, that blocking program error signals such as <CODE>SIGFPE</CODE>
leads to undesirable results for signals generated by an actual program
error (as opposed to signals sent with <CODE>raise</CODE> or <CODE>kill</CODE>).
This is because your program may be too broken to be able to continue
executing to a point where the signal is unblocked again.
.
sq~wtsignal.hxq~t@int how, const sigset_t *restrict set, sigset_t *restrict oldsettintt sigsetjmpsq~
t
This is similar to <CODE>setjmp</CODE>. If <VAR>savesigs</VAR> is nonzero, the set
of blocked signals is saved in <VAR>state</VAR> and will be restored if a
<CODE>siglongjmp</CODE> is later performed with this <VAR>state</VAR>.
sq~wtsetjmp.hxq~tsigjmp_buf state, int savesigstintt
sigsetmasksq~
t
This function equivalent to <CODE>sigprocmask</CODE> with a <VAR>how</VAR> argument of <CODE>SIG_SETMASK</CODE>: it sets
the calling process's signal mask to <VAR>mask</VAR>. The return value is
the previous set of blocked signals.
sq~wtsignal.hxq~tint masktinttsigstacksq~
t÷
The <CODE>sigstack</CODE> function specifies an alternate stack for use during
signal handling. When a signal is received by the process and its
action indicates that the signal stack is used, the system arranges a
switch to the currently installed signal stack while the handler for
that signal is executed.
<br><br> If <VAR>oldstack</VAR> is not a null pointer, information about the currently
installed signal stack is returned in the location it points to. If
<VAR>stack</VAR> is not a null pointer, then this is installed as the new
stack for use by signal handlers.
<br><br> The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on failure.
sq~wtsignal.hxq~$t7const struct sigstack *stack, struct sigstack *oldstacktintt
sigsuspendsq~
t…
This function replaces the process's signal mask with <VAR>set</VAR> and then
suspends the process until a signal is delivered whose action is either
to terminate the process or invoke a signal handling function. In other
words, the program is effectively suspended until one of the signals that
is not a member of <VAR>set</VAR> arrives.
<br><br> If the process is woken up by delivery of a signal that invokes a handler
function, and the handler function returns, then <CODE>sigsuspend</CODE> also
returns.
<br><br> The mask remains <VAR>set</VAR> only as long as <CODE>sigsuspend</CODE> is waiting.
The function <CODE>sigsuspend</CODE> always restores the previous signal mask
when it returns.
<br><br> The return value and error conditions are the same as for <CODE>pause</CODE>.
sq~wtsignal.hxq~+tconst sigset_t *settinttsigvecsq~
t
This function is the equivalent of <CODE>sigaction</CODE> ; it installs the action <VAR>action</VAR> for the signal <VAR>signum</VAR>,
returning information about the previous action in effect for that signal
in <VAR>old-action</VAR>.
sq~wtsignal.hxq~2tAint signum, const struct sigvec *action,struct sigvec *old-actiontinttsinsq~
t¸
These functions return the sine of <VAR>x</VAR>, where <VAR>x</VAR> is given in
radians. The return value is in the range <CODE>-1</CODE> to <CODE>1</CODE>.
sq~wtmath.hxq~9tdouble xtdoubletsincossq~
tè
These functions return the sine of <VAR>x</VAR> in <CODE>*<VAR>sinx</VAR></CODE> and the
cosine of <VAR>x</VAR> in <CODE>*<VAR>cos</VAR></CODE>, where <VAR>x</VAR> is given in
radians. Both values, <CODE>*<VAR>sinx</VAR></CODE> and <CODE>*<VAR>cosx</VAR></CODE>, are in
the range of <CODE>-1</CODE> to <CODE>1</CODE>.
<br><br> This function is a GNU extension. Portable programs should be prepared
to cope with its absence.
sq~wtmath.hxq~@t$double x, double *sinx, double *cosxtvoidtsincosfsq~
tè
These functions return the sine of <VAR>x</VAR> in <CODE>*<VAR>sinx</VAR></CODE> and the
cosine of <VAR>x</VAR> in <CODE>*<VAR>cos</VAR></CODE>, where <VAR>x</VAR> is given in
radians. Both values, <CODE>*<VAR>sinx</VAR></CODE> and <CODE>*<VAR>cosx</VAR></CODE>, are in
the range of <CODE>-1</CODE> to <CODE>1</CODE>.
<br><br> This function is a GNU extension. Portable programs should be prepared
to cope with its absence.
sq~wtmath.hxq~Gt!float x, float *sinx, float *cosxtvoidtsincoslsq~
tè
These functions return the sine of <VAR>x</VAR> in <CODE>*<VAR>sinx</VAR></CODE> and the
cosine of <VAR>x</VAR> in <CODE>*<VAR>cos</VAR></CODE>, where <VAR>x</VAR> is given in
radians. Both values, <CODE>*<VAR>sinx</VAR></CODE> and <CODE>*<VAR>cosx</VAR></CODE>, are in
the range of <CODE>-1</CODE> to <CODE>1</CODE>.
<br><br> This function is a GNU extension. Portable programs should be prepared
to cope with its absence.
sq~wtmath.hxq~Nt3long double x, long double *sinx, long double *cosxtvoidtsinfsq~
t¸
These functions return the sine of <VAR>x</VAR>, where <VAR>x</VAR> is given in
radians. The return value is in the range <CODE>-1</CODE> to <CODE>1</CODE>.
sq~wtmath.hxq~Utfloat xtfloattsinhsq~
tî
These functions return the hyperbolic sine of <VAR>x</VAR>, defined
mathematically as <CODE>(exp (<VAR>x</VAR>) - exp (-<VAR>x</VAR>)) / 2</CODE>. They
may signal overflow if <VAR>x</VAR> is too large.
sq~wtmath.hxq~\tdouble xtdoubletsinhfsq~
tî
These functions return the hyperbolic sine of <VAR>x</VAR>, defined
mathematically as <CODE>(exp (<VAR>x</VAR>) - exp (-<VAR>x</VAR>)) / 2</CODE>. They
may signal overflow if <VAR>x</VAR> is too large.
sq~wtmath.hxq~ctfloat xtfloattsinhlsq~
tî
These functions return the hyperbolic sine of <VAR>x</VAR>, defined
mathematically as <CODE>(exp (<VAR>x</VAR>) - exp (-<VAR>x</VAR>)) / 2</CODE>. They
may signal overflow if <VAR>x</VAR> is too large.
sq~wtmath.hxq~jt
long double xt long doubletsinlsq~
t¸
These functions return the sine of <VAR>x</VAR>, where <VAR>x</VAR> is given in
radians. The return value is in the range <CODE>-1</CODE> to <CODE>1</CODE>.
sq~wtmath.hxq~qt
long double xt long doubletsleepsq~
tá
The <CODE>sleep</CODE> function waits for <VAR>seconds</VAR> or until a signal
is delivered, whichever happens first.
<br><br> If <CODE>sleep</CODE> function returns because the requested interval is over,
it returns a value of zero. If it returns because of delivery of a
signal, its return value is the remaining time in the sleep interval.
<br><br> The <CODE>sleep</CODE> function is declared in <TT>unistd.h</TT>.
sq~wtunistd.hxq~xtunsigned int secondst unsigned inttsnprintfsq~
t
The <CODE>snprintf</CODE> function is similar to <CODE>sprintf</CODE>, except that
the <VAR>size</VAR> argument specifies the maximum number of characters to
produce. The trailing null character is counted towards this limit, so
you should allocate at least <VAR>size</VAR> characters for the string <VAR>s</VAR>.
<br><br> The return value is the number of characters which would be generated
for the given input, excluding the trailing null. If this value is
greater or equal to <VAR>size</VAR>, not all characters from the result have
been stored in <VAR>s</VAR>. You should try again with a bigger output
string. Here is an example of doing this:
<br><br> <pre><br>
<br>
/* Construct a message describing the value of a variable<br>
whose name is <VAR>name</VAR> and whose value is <VAR>value</VAR>. */<br>
char *<br>
make_message (char *name, char *value)<br>
{<br>
/* Guess we need no more than 100 chars of space. */<br>
int size = 100;<br>
char *buffer = (char *) xmalloc (size);<br>
int nchars;<br>
<br>
<br>
if (buffer == NULL)<br>
return NULL;<br>
<br><br> /* Try to print in the allocated space. */<br>
nchars = snprintf (buffer, size, "value of %s is %s",<br>
name, value);<br>
<br>
<br>
if (nchars >= size)<br>
{<br>
/* Reallocate buffer now that we know<br>
how much space is needed. */<br>
size = nchars + 1;<br>
buffer = (char *) xrealloc (buffer, size);<br>
<br><br> if (buffer != NULL)<br>
/* Try again. */<br>
snprintf (buffer, size, "value of %s is %s",<br>
name, value);<br>
}<br>
/* The last call worked, return the string. */<br>
return buffer;<br>
}<br>
<br>
</pre>
<br><br> In practice, it is often easier just to use <CODE>asprintf</CODE>, below.
<br><br> Attention: In versions of the GNU C library prior to 2.1 the
return value is the number of characters stored, not including the
terminating null; unless there was not enough space in <VAR>s</VAR> to
store the result in which case <CODE>-1</CODE> is returned. This was
changed in order to comply with the ISO C99 standard.
sq~wtstdio.hxq~t/char *s, size_t size, const char *template, ...tinttsocketsq~
tÿ
This function creates a socket and specifies communication style
<VAR>style</VAR>, which should be one of the socket styles listed in
Communication Styles. The <VAR>namespace</VAR> argument specifies
the namespace; it must be <CODE>PF_LOCAL</CODE> or
<CODE>PF_INET</CODE> . <VAR>protocol</VAR>
designates the specific protocol ; zero is
usually right for <VAR>protocol</VAR>.
<br><br> The return value from <CODE>socket</CODE> is the file descriptor for the new
socket, or <CODE>-1</CODE> in case of error. The following <CODE>errno</CODE> error
conditions are defined for this function:
<br><br> <DL>
<DT><CODE>EPROTONOSUPPORT</CODE>
<DD>
The <VAR>protocol</VAR> or <VAR>style</VAR> is not supported by the
<VAR>namespace</VAR> specified.
<br><br> <LI> EMFILE
The process already has too many file descriptors open.
<br><br> <LI> ENFILE
The system already has too many file descriptors open.
<br><br> <LI> EACCES
The process does not have the privilege to create a socket of the specified
<VAR>style</VAR> or <VAR>protocol</VAR>.
<br><br> <LI> ENOBUFS
The system ran out of internal buffer space.
<br><br> The file descriptor returned by the <CODE>socket</CODE> function supports both
read and write operations. However, like pipes, sockets do not support file
positioning operations.
sq~wt sys/socket.hxq~†t&int namespace, int style, int protocoltintt
socketpairsq~
t½
This function creates a socket pair, returning the file descriptors in
<CODE><VAR>filedes</VAR>[0]</CODE> and <CODE><VAR>filedes</VAR>[1]</CODE>. The socket pair
is a full-duplex communications channel, so that both reading and writing
may be performed at either end.
<br><br> The <VAR>namespace</VAR>, <VAR>style</VAR> and <VAR>protocol</VAR> arguments are
interpreted as for the <CODE>socket</CODE> function. <VAR>style</VAR> should be
one of the communication styles listed in Communication Styles.
The <VAR>namespace</VAR> argument specifies the namespace, which must be
<CODE>AF_LOCAL</CODE> ; <VAR>protocol</VAR> specifies the
communications protocol, but zero is the only meaningful value.
<br><br> If <VAR>style</VAR> specifies a connectionless communication style, then
the two sockets you get are not <EM>connected</EM>, strictly speaking,
but each of them knows the other as the default destination address,
so they can send packets to each other.
<br><br> The <CODE>socketpair</CODE> function returns <CODE>0</CODE> on success and <CODE>-1</CODE>
on failure. The following <CODE>errno</CODE> error conditions are defined
for this function:
<br><br> <DL>
<DT><CODE>EMFILE</CODE>
<DD>
The process has too many file descriptors open.
<br><br> <LI> EAFNOSUPPORT
The specified namespace is not supported.
<br><br> <LI> EPROTONOSUPPORT
The specified protocol is not supported.
<br><br> <LI> EOPNOTSUPP
The specified protocol does not support the creation of socket pairs.
sq~wt sys/socket.hxq~�t6int namespace, int style, int protocol, int filedes[2]tinttsprintfsq~
te
This is like <CODE>printf</CODE>, except that the output is stored in the character
array <VAR>s</VAR> instead of written to a stream. A null character is written
to mark the end of the string.
<br><br> The <CODE>sprintf</CODE> function returns the number of characters stored in
the array <VAR>s</VAR>, not including the terminating null character.
<br><br> The behavior of this function is undefined if copying takes place
between objects that overlap---for example, if <VAR>s</VAR> is also given
as an argument to be printed under control of the <samp>%s</samp> conversion.
.
<br><br> Warning: The <CODE>sprintf</CODE> function can be <h3>dangerous</h3>
because it can potentially output more characters than can fit in the
allocation size of the string <VAR>s</VAR>. Remember that the field width
given in a conversion specification is only a <EM>minimum</EM> value.
<br><br> To avoid this problem, you can use <CODE>snprintf</CODE> or <CODE>asprintf</CODE>,
described below.
sq~wtstdio.hxq~”t"char *s, const char *template, ...tinttsqrtsq~
tê
These functions return the nonnegative square root of <VAR>x</VAR>.
<br><br> If <VAR>x</VAR> is negative, <CODE>sqrt</CODE> signals a domain error.
Mathematically, it should return a complex number.
sq~wtmath.hxq~›tdouble xtdoubletsqrtfsq~
tê
These functions return the nonnegative square root of <VAR>x</VAR>.
<br><br> If <VAR>x</VAR> is negative, <CODE>sqrt</CODE> signals a domain error.
Mathematically, it should return a complex number.
sq~wtmath.hxq~¢tfloat xtfloattsqrtlsq~
tê
These functions return the nonnegative square root of <VAR>x</VAR>.
<br><br> If <VAR>x</VAR> is negative, <CODE>sqrt</CODE> signals a domain error.
Mathematically, it should return a complex number.
sq~wtmath.hxq~©t
long double xt long doubletsrandsq~
t¤
This function establishes <VAR>seed</VAR> as the seed for a new series of
pseudo-random numbers. If you call <CODE>rand</CODE> before a seed has been
established with <CODE>srand</CODE>, it uses the value <CODE>1</CODE> as a default
seed.
<br><br> To produce a different pseudo-random series each time your program is
run, do <CODE>srand (time (0))</CODE>.
sq~wtstdlib.hxq~°tunsigned int seedtvoidtsrand48sq~
t½
The <CODE>srand48</CODE> function sets the most significant 32 bits of the
internal state of the random number generator to the least
significant 32 bits of the <VAR>seedval</VAR> parameter. The lower 16 bits
are initialized to the value <CODE>0x330E</CODE>. Even if the <CODE>long
int</CODE> type contains more than 32 bits only the lower 32 bits are used.
<br><br> Owing to this limitation, initialization of the state of this
function is not very useful. But it makes it easy to use a construct
like <CODE>srand48 (time (0))</CODE>.
<br><br> A side-effect of this function is that the values <CODE>a</CODE> and <CODE>c</CODE>
from the internal state, which are used in the congruential formula,
are reset to the default values given above. This is of importance once
the user has called the <CODE>lcong48</CODE> function (see below).
sq~wtstdlib.hxq~·tlong int seedvaltvoidt srand48_rsq~
t6
The description of the random number generator represented by the
information in <VAR>buffer</VAR> is initialized similarly to what the function
<CODE>srand48</CODE> does. The state is initialized from the parameter
<VAR>seedval</VAR> and the parameters for the congruential formula are
initialized to their default values.
<br><br> If the return value is non-negative the function call succeeded.
<br><br> This function is a GNU extension and should not be used in portable
programs.
sq~wtstdlib.hxq~¾t-long int seedval, struct drand48_data *buffertinttsrandomsq~
tÀ
The <CODE>srandom</CODE> function sets the state of the random number
generator based on the integer <VAR>seed</VAR>. If you supply a <VAR>seed</VAR> value
of <CODE>1</CODE>, this will cause <CODE>random</CODE> to reproduce the default set
of random numbers.
<br><br> To produce a different set of pseudo-random numbers each time your
program runs, do <CODE>srandom (time (0))</CODE>.
sq~wtstdlib.hxq~Åtunsigned int seedtvoidt srandom_rsq~
t÷
The <CODE>srandom_r</CODE> function behaves exactly like the <CODE>srandom</CODE>
function except that it uses and modifies the state in the object
pointed to by the second parameter instead of the global state.
sq~wtstdlib.hxq~Ìt*unsigned int seed, struct random_data *buftinttsscanfsq~
t/
This is like <CODE>scanf</CODE>, except that the characters are taken from the
null-terminated string <VAR>s</VAR> instead of from a stream. Reaching the
end of the string is treated as an end-of-file condition.
<br><br> The behavior of this function is undefined if copying takes place
between objects that overlap---for example, if <VAR>s</VAR> is also given
as an argument to receive a string read under control of the <samp>%s</samp>,
<samp>%S</samp>, or <samp>%[</samp> conversion.
sq~wtstdio.hxq~Ót(const char *s, const char *template, ...tinttssignalsq~
t™
The <CODE>ssignal</CODE> function does the same thing as <CODE>signal</CODE>; it is
provided only for compatibility with SVID.
sq~wtsignal.hxq~Útint signum, sighandler_t actiont sighandler_ttstatsq~
t9
The <CODE>stat</CODE> function returns information about the attributes of the
file named by <VAR>filename</VAR> in the structure pointed to by <VAR>buf</VAR>.
<br><br> If <VAR>filename</VAR> is the name of a symbolic link, the attributes you get
describe the file that the link points to. If the link points to a
nonexistent file name, then <CODE>stat</CODE> fails reporting a nonexistent
file.
<br><br> The return value is <CODE>0</CODE> if the operation is successful, or
<CODE>-1</CODE> on failure. In addition to the usual file name errors
(, the following <CODE>errno</CODE> error conditions
are defined for this function:
<br><br> <DL>
<DT><CODE>ENOENT</CODE>
<DD>
The file named by <VAR>filename</VAR> doesn't exist.
<br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> this
function is in fact <CODE>stat64</CODE> since the LFS interface transparently
replaces the normal implementation.
sq~wt
sys/stat.ht sys/types.hxq~át&const char *filename, struct stat *buftinttstat64sq~
t"
This function is similar to <CODE>stat</CODE> but it is also able to work on
files larger then 2^31 bytes on 32-bit systems. To be able to do
this the result is stored in a variable of type <CODE>struct stat64</CODE> to
which <VAR>buf</VAR> must point.
<br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> this
function is available under the name <CODE>stat</CODE> and so transparently
replaces the interface for small files on 32-bit machines.
sq~wt
sys/stat.hxq~ét(const char *filename, struct stat64 *buftinttstimesq~
t+
<CODE>stime</CODE> sets the system clock, i.e., it tells the system that the
current calendar time is <VAR>newtime</VAR>, where <CODE>newtime</CODE> is
interpreted as described in the above definition of <CODE>time_t</CODE>.
<br><br> <CODE>settimeofday</CODE> is a newer function which sets the system clock to
better than one second precision. <CODE>settimeofday</CODE> is generally a
better choice than <CODE>stime</CODE>. .
<br><br> Only the superuser can set the system clock.
<br><br> If the function succeeds, the return value is zero. Otherwise, it is
<CODE>-1</CODE> and <CODE>errno</CODE> is set accordingly:
<br><br> <DL>
<DT><CODE>EPERM</CODE>
<DD>
The process is not superuser.
sq~wttime.hxq~ðttime_t *newtimetinttstpcpysq~
t–
This function is like <CODE>strcpy</CODE>, except that it returns a pointer to
the end of the string <VAR>to</VAR> (that is, the address of the terminating
null character <CODE>to + strlen (from)</CODE>) rather than the beginning.
<br><br> For example, this program uses <CODE>stpcpy</CODE> to concatenate <samp>foo</samp>
and <samp>bar</samp> to produce <samp>foobar</samp>, which it then prints.
<br><br> <pre><br>
#include &lt;string.h&gt;<br>
#include &lt;stdio.h&gt;<br>
<br><br> int<br>
main (void)<br>
{<br>
char buffer[10];<br>
char *to = buffer;<br>
to = stpcpy (to, "foo");<br>
to = stpcpy (to, "bar");<br>
puts (buffer);<br>
return 0;<br>
}<br>
</pre>
<br><br> This function is not part of the ISO or POSIX standards, and is not
customary on Unix systems, but we did not invent it either. Perhaps it
comes from MS-DOG.
<br><br> Its behavior is undefined if the strings overlap. The function is
declared in <TT>string.h</TT>.
sq~wtstring.hxq~÷t,char *restrict to, const char *restrict fromtchar *tstpncpysq~
tÞ
This function is similar to <CODE>stpcpy</CODE> but copies always exactly
<VAR>size</VAR> characters into <VAR>to</VAR>.
<br><br> If the length of <VAR>from</VAR> is more then <VAR>size</VAR>, then <CODE>stpncpy</CODE>
copies just the first <VAR>size</VAR> characters and returns a pointer to the
character directly following the one which was copied last. Note that in
this case there is no null terminator written into <VAR>to</VAR>.
<br><br> If the length of <VAR>from</VAR> is less than <VAR>size</VAR>, then <CODE>stpncpy</CODE>
copies all of <VAR>from</VAR>, followed by enough null characters to add up
to <VAR>size</VAR> characters in all. This behavior is rarely useful, but it
is implemented to be useful in contexts where this behavior of the
<CODE>strncpy</CODE> is used. <CODE>stpncpy</CODE> returns a pointer to the
<EM>first</EM> written null character.
<br><br> This function is not part of ISO or POSIX but was found useful while
developing the GNU C Library itself.
<br><br> Its behavior is undefined if the strings overlap. The function is
declared in <TT>string.h</TT>.
sq~wtstring.hxq~þt9char *restrict to, const char *restrict from, size_t sizetchar *t
strcasecmpsq~
tß
This function is like <CODE>strcmp</CODE>, except that differences in case are
ignored. How uppercase and lowercase characters are related is
determined by the currently selected locale. In the standard <CODE>"C"</CODE>
locale the characters "A and "a do not match but in a locale which
regards these characters as parts of the alphabet they do match.
<br><br>
<CODE>strcasecmp</CODE> is derived from BSD.
sq~wtstring.hxq~tconst char *s1, const char *s2tintt
strcasestrsq~
tÍ
This is like <CODE>strstr</CODE>, except that it ignores case in searching for
the substring. Like <CODE>strcasecmp</CODE>, it is locale dependent how
uppercase and lowercase characters are related.
<br><br> <br><br> For example,
<pre><br>
strcasestr ("hello, world", "L")<br>
"llo, world"<br>
strcasestr ("hello, World", "wo")<br>
"World"<br>
</pre>
sq~wtstring.hxq~ t(const char *haystack, const char *needletchar *tstrcatsq~
tî
The <CODE>strcat</CODE> function is similar to <CODE>strcpy</CODE>, except that the
characters from <VAR>from</VAR> are concatenated or appended to the end of
<VAR>to</VAR>, instead of overwriting it. That is, the first character from
<VAR>from</VAR> overwrites the null character marking the end of <VAR>to</VAR>.
<br><br> An equivalent definition for <CODE>strcat</CODE> would be:
<br><br> <pre><br>
char *<br>
strcat (char *restrict to, const char *restrict from)<br>
{<br>
strcpy (to + strlen (to), from);<br>
return to;<br>
}<br>
</pre>
<br><br> This function has undefined results if the strings overlap.
sq~wtstring.hxq~t,char *restrict to, const char *restrict fromtchar *tstrchrsq~
tz
The <CODE>strchr</CODE> function finds the first occurrence of the character
<VAR>c</VAR> (converted to a <CODE>char</CODE>) in the null-terminated string
beginning at <VAR>string</VAR>. The return value is a pointer to the located
character, or a null pointer if no match was found.
<br><br> For example,
<pre><br>
strchr ("hello, world", 'l')<br>
"llo, world"<br>
strchr ("hello, world", '?')<br>
NULL<br>
</pre>
<br><br> The terminating null character is considered to be part of the string,
so you can use this function get a pointer to the end of a string by
specifying a null character as the value of the <VAR>c</VAR> argument. It
would be better (but less portable) to use <CODE>strchrnul</CODE> in this
case, though.
sq~wtstring.hxq~tconst char *string, int ctchar *t strchrnulsq~
t
<CODE>strchrnul</CODE> is the same as <CODE>strchr</CODE> except that if it does
not find the character, it returns a pointer to string's terminating
null character rather than a null pointer.
<br><br> This function is a GNU extension.
sq~wtstring.hxq~!tconst char *string, int ctchar *tstrcmpsq~
tN
The <CODE>strcmp</CODE> function compares the string <VAR>s1</VAR> against
<VAR>s2</VAR>, returning a value that has the same sign as the difference
between the first differing pair of characters (interpreted as
<CODE>unsigned char</CODE> objects, then promoted to <CODE>int</CODE>).
<br><br> If the two strings are equal, <CODE>strcmp</CODE> returns <CODE>0</CODE>.
<br><br> A consequence of the ordering used by <CODE>strcmp</CODE> is that if <VAR>s1</VAR>
is an initial substring of <VAR>s2</VAR>, then <VAR>s1</VAR> is considered to be
``less than'' <VAR>s2</VAR>.
<br><br> <CODE>strcmp</CODE> does not take sorting conventions of the language the
strings are written in into account. To get that one has to use
<CODE>strcoll</CODE>.
sq~wtstring.hxq~(tconst char *s1, const char *s2tinttstrcollsq~
tÑ
The <CODE>strcoll</CODE> function is similar to <CODE>strcmp</CODE> but uses the
collating sequence of the current locale for collation (the
<CODE>LC_COLLATE</CODE> locale).
sq~wtstring.hxq~/tconst char *s1, const char *s2tinttstrcpysq~
t?
This copies characters from the string <VAR>from</VAR> (up to and including
the terminating null character) into the string <VAR>to</VAR>. Like
<CODE>memcpy</CODE>, this function has undefined results if the strings
overlap. The return value is the value of <VAR>to</VAR>.
sq~wtstring.hxq~6t,char *restrict to, const char *restrict fromtchar *tstrcspnsq~
tt
The <CODE>strcspn</CODE> (``string complement span'') function returns the length
of the initial substring of <VAR>string</VAR> that consists entirely of characters
that are <EM>not</EM> members of the set specified by the string <VAR>stopset</VAR>.
(In other words, it returns the offset of the first character in <VAR>string</VAR>
that is a member of the set <VAR>stopset</VAR>.)
<br><br> For example,
<pre><br>
strcspn ("hello, world", " \t\n,.;!?")<br>
5<br>
</pre>
<br><br> Note that ``character'' is here used in the sense of byte. In a string
using a multibyte character encoding (abstract) character consisting of
more than one byte are not treated as an entity. Each byte is treated
separately. The function is not locale-dependent.
sq~wtstring.hxq~=t'const char *string, const char *stopsettsize_ttstrdupsq~
t„
This function copies the null-terminated string <VAR>s</VAR> into a newly
allocated string. The string is allocated using <CODE>malloc</CODE>; see
Unconstrained Allocation. If <CODE>malloc</CODE> cannot allocate space
for the new string, <CODE>strdup</CODE> returns a null pointer. Otherwise it
returns a pointer to the new string.
sq~wtstring.hxq~Dt
const char *stchar *tstrerrorsq~
tÁ
The <CODE>strerror</CODE> function maps the error code specified by the <VAR>errnum</VAR> argument to a descriptive error
message string. The return value is a pointer to this string.
<br><br> The value <VAR>errnum</VAR> normally comes from the variable <CODE>errno</CODE>.
<br><br> You should not modify the string returned by <CODE>strerror</CODE>. Also, if
you make subsequent calls to <CODE>strerror</CODE>, the string might be
overwritten. (But it's guaranteed that no library function ever calls
<CODE>strerror</CODE> behind your back.)
<br><br> The function <CODE>strerror</CODE> is declared in <TT>string.h</TT>.
sq~wterrno.htstring.hxq~Kt
int errnumtchar *t
strerror_rsq~
tÄ
The <CODE>strerror_r</CODE> function works like <CODE>strerror</CODE> but instead of
returning the error message in a statically allocated buffer shared by
all threads in the process, it returns a private copy for the
thread. This might be either some permanent global data or a message
string in the user supplied buffer starting at <VAR>buf</VAR> with the
length of <VAR>n</VAR> bytes.
<br><br> At most <VAR>n</VAR> characters are written (including the NUL byte) so it is
up to the user to select the buffer large enough.
<br><br> This function should always be used in multi-threaded programs since
there is no way to guarantee the string returned by <CODE>strerror</CODE>
really belongs to the last call of the current thread.
<br><br> This function <CODE>strerror_r</CODE> is a GNU extension and it is declared in
<TT>string.h</TT>.
sq~wtstring.hxq~Stint errnum, char *buf, size_t ntchar *tstrfmonsq~
tÈ
The <CODE>strfmon</CODE> function is similar to the <CODE>strftime</CODE> function
in that it takes a buffer, its size, a format string,
and values to write into the buffer as text in a form specified
by the format string. Like <CODE>strftime</CODE>, the function
also returns the number of bytes written into the buffer.
<br><br> There are two differences: <CODE>strfmon</CODE> can take more than one
argument, and, of course, the format specification is different. Like
<CODE>strftime</CODE>, the format string consists of normal text, which is
output as is, and format specifiers, which are indicated by a <samp>%</samp>.
Immediately after the <samp>%</samp>, you can optionally specify various flags
and formatting information before the main formatting character, in a
similar way to <CODE>printf</CODE>:
<br><br> <OL>
<LI>
Immediately following the <samp>%</samp> there can be one or more of the
following flags:
<DL>
<LI> <samp>=<VAR>f</VAR></samp>
The single byte character <VAR>f</VAR> is used for this field as the numeric
fill character. By default this character is a space character.
Filling with this character is only performed if a left precision
is specified. It is not just to fill to the given field width.
<LI> <samp>^</samp>
The number is printed without grouping the digits according to the rules
of the current locale. By default grouping is enabled.
<LI> <samp>+</samp>, <samp>(</samp>
At most one of these flags can be used. They select which format to
represent the sign of a currency amount. By default, and if
<samp>+</samp> is given, the locale equivalent of +/- is used. If
<samp>(</samp> is given, negative amounts are enclosed in parentheses. The
exact format is determined by the values of the <CODE>LC_MONETARY</CODE>
category of the locale selected at program runtime.
<LI> <samp>!</samp>
The output will not contain the currency symbol.
<LI> <samp>-</samp>
The output will be formatted left-justified instead of right-justified if
it does not fill the entire field width.
</DL>
</OL>
<br><br> The next part of a specification is an optional field width. If no
width is specified 0 is taken. During output, the function first
determines how much space is required. If it requires at least as many
characters as given by the field width, it is output using as much space
as necessary. Otherwise, it is extended to use the full width by
filling with the space character. The presence or absence of the
<samp>-</samp> flag determines the side at which such padding occurs. If
present, the spaces are added at the right making the output
left-justified, and vice versa.
<br><br> So far the format looks familiar, being similar to the <CODE>printf</CODE> and
<CODE>strftime</CODE> formats. However, the next two optional fields
introduce something new. The first one is a <samp>#</samp> character followed
by a decimal digit string. The value of the digit string specifies the
number of <EM>digit</EM> positions to the left of the decimal point (or
equivalent). This does <EM>not</EM> include the grouping character when
the <samp>^</samp> flag is not given. If the space needed to print the number
does not fill the whole width, the field is padded at the left side with
the fill character, which can be selected using the <samp>=</samp> flag and by
default is a space. For example, if the field width is selected as 6
and the number is 123, the fill character is <samp>*</samp> the result
will be <samp>***123</samp>.
<br><br> The second optional field starts with a <samp>.</samp> (period) and consists
of another decimal digit string. Its value describes the number of
characters printed after the decimal point. The default is selected
from the current locale (<CODE>frac_digits</CODE>, <CODE>int_frac_digits</CODE>, see
). If the exact representation needs more digits
than given by the field width, the displayed value is rounded. If the
number of fractional digits is selected to be zero, no decimal point is
printed.
<br><br> As a GNU extension, the <CODE>strfmon</CODE> implementation in the GNU libc
allows an optional <samp>L</samp> next as a format modifier. If this modifier
is given, the argument is expected to be a <CODE>long double</CODE> instead of
a <CODE>double</CODE> value.
<br><br> Finally, the last component is a format specifier. There are three
specifiers defined:
<br><br> <DL>
<LI> <samp>i</samp>
Use the locale's rules for formatting an international currency value.
<LI> <samp>n</samp>
Use the locale's rules for formatting a national currency value.
<LI> <samp>%</samp>
Place a <samp>%</samp> in the output. There must be no flag, width
specifier or modifier given, only <samp>%%</samp> is allowed.
</DL>
<br><br> As for <CODE>printf</CODE>, the function reads the format string
from left to right and uses the values passed to the function following
the format string. The values are expected to be either of type
<CODE>double</CODE> or <CODE>long double</CODE>, depending on the presence of the
modifier <samp>L</samp>. The result is stored in the buffer pointed to by
<VAR>s</VAR>. At most <VAR>maxsize</VAR> characters are stored.
<br><br> The return value of the function is the number of characters stored in
<VAR>s</VAR>, including the terminating <CODE>NULL</CODE> byte. If the number of
characters stored would exceed <VAR>maxsize</VAR>, the function returns
-1 and the content of the buffer <VAR>s</VAR> is unspecified. In this
case <CODE>errno</CODE> is set to <CODE>E2BIG</CODE>.
sq~wxq~Zt0char *s, size_t maxsize, const char *format, ...tssize_ttstrfrysq~
t
<br><br> <CODE>strfry</CODE> creates a pseudorandom anagram of a string, replacing the
input with the anagram in place. For each position in the string,
<CODE>strfry</CODE> swaps it with a position in the string selected at random
(from a uniform distribution). The two positions may be the same.
<br><br> The return value of <CODE>strfry</CODE> is always <VAR>string</VAR>.
<br><br> Portability Note: This function is unique to the GNU C library.
<br><br>
sq~wtstring.hxq~`t char *stringtchar *tstrftimesq~
t7á
This function is similar to the <CODE>sprintf</CODE> function , but the conversion specifications that can appear in the format
template <VAR>template</VAR> are specialized for printing components of the date
and time <VAR>brokentime</VAR> according to the locale currently specified for
time conversion .
<br><br> Ordinary characters appearing in the <VAR>template</VAR> are copied to the
output string <VAR>s</VAR>; this can include multibyte character sequences.
Conversion specifiers are introduced by a <samp>%</samp> character, followed
by an optional flag which can be one of the following. These flags
are all GNU extensions. The first three affect only the output of
numbers:
<br><br> <DL>
<DT><CODE>_</CODE>
<DD>
The number is padded with spaces.
<br><br> <DT><CODE>-</CODE>
<DD>
The number is not padded at all.
<br><br> <DT><CODE>0</CODE>
<DD>
The number is padded with zeros even if the format specifies padding
with spaces.
<br><br> <LI> ^
The output uses uppercase characters, but only if this is possible
.
<br><br> The default action is to pad the number with zeros to keep it a constant
width. Numbers that do not have a range indicated below are never
padded, since there is no natural width for them.
<br><br> Following the flag an optional specification of the width is possible.
This is specified in decimal notation. If the natural size of the
output is of the field has less than the specified number of characters,
the result is written right adjusted and space padded to the given
size.
<br><br> An optional modifier can follow the optional flag and width
specification. The modifiers, which were first standardized by
POSIX.2-1992 and by ISO C99, are:
<br><br> <DL>
<LI> E
Use the locale's alternate representation for date and time. This
modifier applies to the <CODE>%c</CODE>, <CODE>%C</CODE>, <CODE>%x</CODE>, <CODE>%X</CODE>,
<CODE>%y</CODE> and <CODE>%Y</CODE> format specifiers. In a Japanese locale, for
example, <CODE>%Ex</CODE> might yield a date format based on the Japanese
Emperors' reigns.
<br><br> <LI> O
Use the locale's alternate numeric symbols for numbers. This modifier
applies only to numeric format specifiers.
<br><br> If the format supports the modifier but no alternate representation
is available, it is ignored.
<br><br> The conversion specifier ends with a format specifier taken from the
following list. The whole <samp>%</samp> sequence is replaced in the output
string as follows:
<br><br> <DL>
<LI> %a
The abbreviated weekday name according to the current locale.
<br><br> <LI> %A
The full weekday name according to the current locale.
<br><br> <LI> %b
The abbreviated month name according to the current locale.
<br><br> <LI> %B
The full month name according to the current locale.
<br><br> Using <CODE>%B</CODE> together with <CODE>%d</CODE> produces grammatically
incorrect results for some locales.
<br><br> <LI> %c
The preferred calendar time representation for the current locale.
<br><br> <LI> %C
The century of the year. This is equivalent to the greatest integer not
greater than the year divided by 100.
<br><br> This format was first standardized by POSIX.2-1992 and by ISO C99.
<br><br> <LI> %d
The day of the month as a decimal number (range <CODE>01</CODE> through <CODE>31</CODE>).
<br><br> <LI> %D
The date using the format <CODE>%m/%d/%y</CODE>.
<br><br> This format was first standardized by POSIX.2-1992 and by ISO C99.
<br><br> <LI> %e
The day of the month like with <CODE>%d</CODE>, but padded with blank (range
<CODE> 1</CODE> through <CODE>31</CODE>).
<br><br> This format was first standardized by POSIX.2-1992 and by ISO C99.
<br><br> <LI> %F
The date using the format <CODE>%Y-%m-%d</CODE>. This is the form specified
in the ISO 8601 standard and is the preferred form for all uses.
<br><br> This format was first standardized by ISO C99 and by POSIX.1-2001.
<br><br> <LI> %g
The year corresponding to the ISO week number, but without the century
(range <CODE>00</CODE> through <CODE>99</CODE>). This has the same format and value
as <CODE>%y</CODE>, except that if the ISO week number (see <CODE>%V</CODE>) belongs
to the previous or next year, that year is used instead.
<br><br> This format was first standardized by ISO C99 and by POSIX.1-2001.
<br><br> <LI> %G
The year corresponding to the ISO week number. This has the same format
and value as <CODE>%Y</CODE>, except that if the ISO week number (see
<CODE>%V</CODE>) belongs to the previous or next year, that year is used
instead.
<br><br> This format was first standardized by ISO C99 and by POSIX.1-2001
but was previously available as a GNU extension.
<br><br> <LI> %h
The abbreviated month name according to the current locale. The action
is the same as for <CODE>%b</CODE>.
<br><br> This format was first standardized by POSIX.2-1992 and by ISO C99.
<br><br> <LI> %H
The hour as a decimal number, using a 24-hour clock (range <CODE>00</CODE> through
<CODE>23</CODE>).
<br><br> <LI> %I
The hour as a decimal number, using a 12-hour clock (range <CODE>01</CODE> through
<CODE>12</CODE>).
<br><br> <LI> %j
The day of the year as a decimal number (range <CODE>001</CODE> through <CODE>366</CODE>).
<br><br> <LI> %k
The hour as a decimal number, using a 24-hour clock like <CODE>%H</CODE>, but
padded with blank (range <CODE> 0</CODE> through <CODE>23</CODE>).
<br><br> This format is a GNU extension.
<br><br> <LI> %l
The hour as a decimal number, using a 12-hour clock like <CODE>%I</CODE>, but
padded with blank (range <CODE> 1</CODE> through <CODE>12</CODE>).
<br><br> This format is a GNU extension.
<br><br> <LI> %m
The month as a decimal number (range <CODE>01</CODE> through <CODE>12</CODE>).
<br><br> <LI> %M
The minute as a decimal number (range <CODE>00</CODE> through <CODE>59</CODE>).
<br><br> <LI> %n
A single <samp>\n</samp> (newline) character.
<br><br> This format was first standardized by POSIX.2-1992 and by ISO C99.
<br><br> <LI> %p
Either <samp>AM</samp> or <samp>PM</samp>, according to the given time value; or the
corresponding strings for the current locale. Noon is treated as
<samp>PM</samp> and midnight as <samp>AM</samp>. In most locales
<samp>AM</samp>/<samp>PM</samp> format is not supported, in such cases <CODE>"%p"</CODE>
yields an empty string.
<br><br>
<LI> %P
Either <samp>am</samp> or <samp>pm</samp>, according to the given time value; or the
corresponding strings for the current locale, printed in lowercase
characters. Noon is treated as <samp>pm</samp> and midnight as <samp>am</samp>. In
most locales <samp>AM</samp>/<samp>PM</samp> format is not supported, in such cases
<CODE>"%P"</CODE> yields an empty string.
<br><br> This format is a GNU extension.
<br><br> <LI> %r
The complete calendar time using the AM/PM format of the current locale.
<br><br> This format was first standardized by POSIX.2-1992 and by ISO C99.
In the POSIX locale, this format is equivalent to <CODE>%I:%M:%S %p</CODE>.
<br><br> <LI> %R
The hour and minute in decimal numbers using the format <CODE>%H:%M</CODE>.
<br><br> This format was first standardized by ISO C99 and by POSIX.1-2001
but was previously available as a GNU extension.
<br><br> <LI> %s
The number of seconds since the epoch, i.e., since 1970-01-01 00:00:00 UTC.
Leap seconds are not counted unless leap second support is available.
<br><br> This format is a GNU extension.
<br><br> <LI> %S
The seconds as a decimal number (range <CODE>00</CODE> through <CODE>60</CODE>).
<br><br> <LI> %t
A single <samp>\t</samp> (tabulator) character.
<br><br> This format was first standardized by POSIX.2-1992 and by ISO C99.
<br><br> <LI> %T
The time of day using decimal numbers using the format <CODE>%H:%M:%S</CODE>.
<br><br> This format was first standardized by POSIX.2-1992 and by ISO C99.
<br><br> <LI> %u
The day of the week as a decimal number (range <CODE>1</CODE> through
<CODE>7</CODE>), Monday being <CODE>1</CODE>.
<br><br> This format was first standardized by POSIX.2-1992 and by ISO C99.
<br><br> <LI> %U
The week number of the current year as a decimal number (range <CODE>00</CODE>
through <CODE>53</CODE>), starting with the first Sunday as the first day of
the first week. Days preceding the first Sunday in the year are
considered to be in week <CODE>00</CODE>.
<br><br> <LI> %V
The ISO 8601:1988 week number as a decimal number (range <CODE>01</CODE>
through <CODE>53</CODE>). ISO weeks start with Monday and end with Sunday.
Week <CODE>01</CODE> of a year is the first week which has the majority of its
days in that year; this is equivalent to the week containing the year's
first Thursday, and it is also equivalent to the week containing January
4. Week <CODE>01</CODE> of a year can contain days from the previous year.
The week before week <CODE>01</CODE> of a year is the last week (<CODE>52</CODE> or
<CODE>53</CODE>) of the previous year even if it contains days from the new
year.
<br><br> This format was first standardized by POSIX.2-1992 and by ISO C99.
<br><br> <LI> %w
The day of the week as a decimal number (range <CODE>0</CODE> through
<CODE>6</CODE>), Sunday being <CODE>0</CODE>.
<br><br> <LI> %W
The week number of the current year as a decimal number (range <CODE>00</CODE>
through <CODE>53</CODE>), starting with the first Monday as the first day of
the first week. All days preceding the first Monday in the year are
considered to be in week <CODE>00</CODE>.
<br><br> <LI> %x
The preferred date representation for the current locale.
<br><br> <LI> %X
The preferred time of day representation for the current locale.
<br><br> <LI> %y
The year without a century as a decimal number (range <CODE>00</CODE> through
<CODE>99</CODE>). This is equivalent to the year modulo 100.
<br><br> <LI> %Y
The year as a decimal number, using the Gregorian calendar. Years
before the year <CODE>1</CODE> are numbered <CODE>0</CODE>, <CODE>-1</CODE>, and so on.
<br><br> <LI> %z
RFC 822/ISO 8601:1988 style numeric time zone (e.g.,
<CODE>-0600</CODE> or <CODE>+0100</CODE>), or nothing if no time zone is
determinable.
<br><br> This format was first standardized by ISO C99 and by POSIX.1-2001
but was previously available as a GNU extension.
<br><br> In the POSIX locale, a full RFC 822 timestamp is generated by the format
<samp>"%a, %d %b %Y %H:%M:%S %z"</samp> (or the equivalent
<samp>"%a, %d %b %Y %T %z"</samp>).
<br><br> <LI> %Z
The time zone abbreviation (empty if the time zone can't be determined).
<br><br> <LI> %%
A literal <samp>%</samp> character.
<br><br> The <VAR>size</VAR> parameter can be used to specify the maximum number of
characters to be stored in the array <VAR>s</VAR>, including the terminating
null character. If the formatted time requires more than <VAR>size</VAR>
characters, <CODE>strftime</CODE> returns zero and the contents of the array
<VAR>s</VAR> are undefined. Otherwise the return value indicates the
number of characters placed in the array <VAR>s</VAR>, not including the
terminating null character.
<br><br> <EM>Warning:</EM> This convention for the return value which is prescribed
in ISO C can lead to problems in some situations. For certain
format strings and certain locales the output really can be the empty
string and this cannot be discovered by testing the return value only.
E.g., in most locales the AM/PM time format is not supported (most of
the world uses the 24 hour time representation). In such locales
<CODE>"%p"</CODE> will return the empty string, i.e., the return value is
zero. To detect situations like this something similar to the following
code should be used:
<br><br> <pre><br>
buf[0] = '\1';<br>
len = strftime (buf, bufsize, format, tp);<br>
if (len == 0 && buf[0] != '\0')<br>
{<br>
/* Something went wrong in the strftime call. */<br>
<small>...</small><br>
}<br>
</pre>
<br><br> If <VAR>s</VAR> is a null pointer, <CODE>strftime</CODE> does not actually write
anything, but instead returns the number of characters it would have written.
<br><br> According to POSIX.1 every call to <CODE>strftime</CODE> implies a call to
<CODE>tzset</CODE>. So the contents of the environment variable <CODE>TZ</CODE>
is examined before any output is produced.
<br><br> For an example of <CODE>strftime</CODE>, see Time Functions Example.
sq~wttime.hxq~gtGchar *s, size_t size, const char *template, const struct tm *brokentimetsize_ttstrlensq~
t ¥
The <CODE>strlen</CODE> function returns the length of the null-terminated
string <VAR>s</VAR> in bytes. (In other words, it returns the offset of the
terminating null character within the array.)
<br><br> For example,
<pre><br>
strlen ("hello, world")<br>
12<br>
</pre><br>
<br><br> When applied to a character array, the <CODE>strlen</CODE> function returns<br>
the length of the string stored there, not its allocated size. You can<br>
get the allocated size of the character array that holds a string using<br>
the <CODE>sizeof</CODE> operator:<br>
<br><br> <pre><br>
char string[32] = "hello, world";<br>
sizeof (string)<br>
32<br>
strlen (string)<br>
12<br>
</pre><br>
<br><br> But beware, this will not work unless <VAR>string</VAR> is the character<br>
array itself, not a pointer to it. For example:<br>
<br><br> <pre><br>
char string[32] = "hello, world";<br>
char *ptr = string;<br>
sizeof (string)<br>
32<br>
sizeof (ptr)<br>
4 /* (on a machine with 4 byte pointers) */<br>
</pre><br>
<br><br> This is an easy mistake to make when you are working with functions that<br>
take string arguments; those arguments are always pointers, not arrays.<br>
<br><br> It must also be noted that for multibyte encoded strings the return<br>
value does not have to correspond to the number of characters in the<br>
string. To get this value the string can be converted to wide<br>
characters and <CODE>wcslen</CODE> can be used or something like the following<br>
code can be used:<br>
<br><br> <pre><br>
/* The input is in <CODE>string</CODE>.<br>
The length is expected in <CODE>n</CODE>. */<br>
{<br>
mbstate_t t;<br>
char *scopy = string;<br>
/* In initial state. */<br>
memset (&t, '\0', sizeof (t));<br>
/* Determine number of characters. */<br>
n = mbsrtowcs (NULL, &scopy, strlen (scopy), &t);<br>
}<br>
</pre>
<br><br> This is cumbersome to do so if the number of characters (as opposed to
bytes) is needed often it is better to work with wide characters.
sq~wtstring.hxq~nt
const char *stsize_tt strncasecmpsq~
t.
This function is like <CODE>strncmp</CODE>, except that differences in case
are ignored. Like <CODE>strcasecmp</CODE>, it is locale dependent how
uppercase and lowercase characters are related.
<br><br>
<CODE>strncasecmp</CODE> is a GNU extension.
sq~wtstring.hxq~ut(const char *s1, const char *s2, size_t ntinttstrncatsq~
tƒ
This function is like <CODE>strcat</CODE> except that not more than <VAR>size</VAR>
characters from <VAR>from</VAR> are appended to the end of <VAR>to</VAR>. A
single null character is also always appended to <VAR>to</VAR>, so the total
allocated size of <VAR>to</VAR> must be at least <CODE><VAR>size</VAR> + 1</CODE> bytes
longer than its initial length.
<br><br> The <CODE>strncat</CODE> function could be implemented like this:
<br><br> <pre><br>
<br>
char *<br>
strncat (char *to, const char *from, size_t size)<br>
{<br>
to[strlen (to) + size] = '\0';<br>
strncpy (to + strlen (to), from, size);<br>
return to;<br>
}<br>
<br>
</pre>
<br><br> The behavior of <CODE>strncat</CODE> is undefined if the strings overlap.
sq~wtstring.hxq~|t9char *restrict to, const char *restrict from, size_t sizetchar *tstrncmpsq~
t
This function is the similar to <CODE>strcmp</CODE>, except that no more than
<VAR>size</VAR> characters are compared. In other words, if the two
strings are the same in their first <VAR>size</VAR> characters, the
return value is zero.
sq~wtstring.hxq~ƒt+const char *s1, const char *s2, size_t sizetinttstrncpysq~
t4
This function is similar to <CODE>strcpy</CODE> but always copies exactly
<VAR>size</VAR> characters into <VAR>to</VAR>.
<br><br> If the length of <VAR>from</VAR> is more than <VAR>size</VAR>, then <CODE>strncpy</CODE>
copies just the first <VAR>size</VAR> characters. Note that in this case
there is no null terminator written into <VAR>to</VAR>.
<br><br> If the length of <VAR>from</VAR> is less than <VAR>size</VAR>, then <CODE>strncpy</CODE>
copies all of <VAR>from</VAR>, followed by enough null characters to add up
to <VAR>size</VAR> characters in all. This behavior is rarely useful, but it
is specified by the ISO C standard.
<br><br> The behavior of <CODE>strncpy</CODE> is undefined if the strings overlap.
<br><br> Using <CODE>strncpy</CODE> as opposed to <CODE>strcpy</CODE> is a way to avoid bugs
relating to writing past the end of the allocated space for <VAR>to</VAR>.
However, it can also make your program much slower in one common case:
copying a string which is probably small into a potentially large buffer.
In this case, <VAR>size</VAR> may be large, and when it is, <CODE>strncpy</CODE> will
waste a considerable amount of time copying null characters.
sq~wtstring.hxq~Št9char *restrict to, const char *restrict from, size_t sizetchar *tstrndupsq~
ty
This function is similar to <CODE>strdup</CODE> but always copies at most
<VAR>size</VAR> characters into the newly allocated string.
<br><br> If the length of <VAR>s</VAR> is more than <VAR>size</VAR>, then <CODE>strndup</CODE>
copies just the first <VAR>size</VAR> characters and adds a closing null
terminator. Otherwise all characters are copied and the string is
terminated.
<br><br> This function is different to <CODE>strncpy</CODE> in that it always
terminates the destination string.
<br><br> <CODE>strndup</CODE> is a GNU extension.
sq~wtstring.hxq~‘tconst char *s, size_t sizetchar *tstrnlensq~
tò
The <CODE>strnlen</CODE> function returns the length of the string <VAR>s</VAR> in
bytes if this length is smaller than <VAR>maxlen</VAR> bytes. Otherwise it
returns <VAR>maxlen</VAR>. Therefore this function is equivalent to
<CODE>(strlen (<VAR>s</VAR>) < n ? strlen (<VAR>s</VAR>) : <VAR>maxlen</VAR>)</CODE> but it
is more efficient and works even if the string <VAR>s</VAR> is not
null-terminated.
<br><br> <pre><br>
char string[32] = "hello, world";<br>
strnlen (string, 32)<br>
12<br>
strnlen (string, 5)<br>
5<br>
</pre>
<br><br> This function is a GNU extension and is declared in <TT>string.h</TT>.
sq~wtstring.hxq~˜tconst char *s, size_t maxlentsize_ttstrpbrksq~
tf
The <CODE>strpbrk</CODE> (``string pointer break'') function is related to
<CODE>strcspn</CODE>, except that it returns a pointer to the first character
in <VAR>string</VAR> that is a member of the set <VAR>stopset</VAR> instead of the
length of the initial substring. It returns a null pointer if no such
character from <VAR>stopset</VAR> is found.
<br><br> For example,
<br><br> <pre><br>
strpbrk ("hello, world", " \t\n,.;!?")<br>
", world"<br>
</pre>
<br><br> Note that ``character'' is here used in the sense of byte. In a string
using a multibyte character encoding (abstract) character consisting of
more than one byte are not treated as an entity. Each byte is treated
separately. The function is not locale-dependent.
sq~wtstring.hxq~Ÿt'const char *string, const char *stopsettchar *tstrptimesq~
t3•
The <CODE>strptime</CODE> function parses the input string <VAR>s</VAR> according
to the format string <VAR>fmt</VAR> and stores its results in the
structure <VAR>tp</VAR>.
<br><br> The input string could be generated by a <CODE>strftime</CODE> call or
obtained any other way. It does not need to be in a human-recognizable
format; e.g. a date passed as <CODE>"02:1999:9"</CODE> is acceptable, even
though it is ambiguous without context. As long as the format string
<VAR>fmt</VAR> matches the input string the function will succeed.
<br><br> The user has to make sure, though, that the input can be parsed in a
unambiguous way. The string <CODE>"1999112"</CODE> can be parsed using the
format <CODE>"%Y%m%d"</CODE> as 1999-1-12, 1999-11-2, or even 19991-1-2. It
is necessary to add appropriate separators to reliably get results.
<br><br> The format string consists of the same components as the format string
of the <CODE>strftime</CODE> function. The only difference is that the flags
<CODE>_</CODE>, <CODE>-</CODE>, <CODE>0</CODE>, and <CODE>^</CODE> are not allowed.
Several of the distinct formats of <CODE>strftime</CODE> do the same work in
<CODE>strptime</CODE> since differences like case of the input do not matter.
For reasons of symmetry all formats are supported, though.
<br><br> The modifiers <CODE>E</CODE> and <CODE>O</CODE> are also allowed everywhere the
<CODE>strftime</CODE> function allows them.
<br><br> The formats are:
<br><br> <DL>
<DT><CODE>%a</CODE>
<DD>
<LI>x %A
The weekday name according to the current locale, in abbreviated form or
the full name.
<br><br> <LI> %b
<LI>x %B
<LI>x %h
The month name according to the current locale, in abbreviated form or
the full name.
<br><br> <LI> %c
The date and time representation for the current locale.
<br><br> <LI> %Ec
Like <CODE>%c</CODE> but the locale's alternative date and time format is used.
<br><br> <LI> %C
The century of the year.
<br><br> It makes sense to use this format only if the format string also
contains the <CODE>%y</CODE> format.
<br><br> <LI> %EC
The locale's representation of the period.
<br><br> Unlike <CODE>%C</CODE> it sometimes makes sense to use this format since some
cultures represent years relative to the beginning of eras instead of
using the Gregorian years.
<br><br> <LI> %d
<LI> %e
The day of the month as a decimal number (range <CODE>1</CODE> through <CODE>31</CODE>).
Leading zeroes are permitted but not required.
<br><br> <LI> %Od
<LI>x %Oe
Same as <CODE>%d</CODE> but using the locale's alternative numeric symbols.
<br><br> Leading zeroes are permitted but not required.
<br><br> <LI> %D
Equivalent to <CODE>%m/%d/%y</CODE>.
<br><br> <LI> %F
Equivalent to <CODE>%Y-%m-%d</CODE>, which is the ISO 8601 date
format.
<br><br> This is a GNU extension following an ISO C99 extension to
<CODE>strftime</CODE>.
<br><br> <LI> %g
The year corresponding to the ISO week number, but without the century
(range <CODE>00</CODE> through <CODE>99</CODE>).
<br><br> <EM>Note:</EM> Currently, this is not fully implemented. The format is
recognized, input is consumed but no field in <VAR>tm</VAR> is set.
<br><br> This format is a GNU extension following a GNU extension of <CODE>strftime</CODE>.
<br><br> <LI> %G
The year corresponding to the ISO week number.
<br><br> <EM>Note:</EM> Currently, this is not fully implemented. The format is
recognized, input is consumed but no field in <VAR>tm</VAR> is set.
<br><br> This format is a GNU extension following a GNU extension of <CODE>strftime</CODE>.
<br><br> <LI> %H
<LI>x %k
The hour as a decimal number, using a 24-hour clock (range <CODE>00</CODE> through
<CODE>23</CODE>).
<br><br> <CODE>%k</CODE> is a GNU extension following a GNU extension of <CODE>strftime</CODE>.
<br><br> <LI> %OH
Same as <CODE>%H</CODE> but using the locale's alternative numeric symbols.
<br><br> <LI> %I
<LI>x %l
The hour as a decimal number, using a 12-hour clock (range <CODE>01</CODE> through
<CODE>12</CODE>).
<br><br> <CODE>%l</CODE> is a GNU extension following a GNU extension of <CODE>strftime</CODE>.
<br><br> <LI> %OI
Same as <CODE>%I</CODE> but using the locale's alternative numeric symbols.
<br><br> <LI> %j
The day of the year as a decimal number (range <CODE>1</CODE> through <CODE>366</CODE>).
<br><br> Leading zeroes are permitted but not required.
<br><br> <LI> %m
The month as a decimal number (range <CODE>1</CODE> through <CODE>12</CODE>).
<br><br> Leading zeroes are permitted but not required.
<br><br> <LI> %Om
Same as <CODE>%m</CODE> but using the locale's alternative numeric symbols.
<br><br> <LI> %M
The minute as a decimal number (range <CODE>0</CODE> through <CODE>59</CODE>).
<br><br> Leading zeroes are permitted but not required.
<br><br> <LI> %OM
Same as <CODE>%M</CODE> but using the locale's alternative numeric symbols.
<br><br> <LI> %n
<LI>x %t
Matches any white space.
<br><br> <LI> %p
<LI> %P
The locale-dependent equivalent to <samp>AM</samp> or <samp>PM</samp>.
<br><br> This format is not useful unless <CODE>%I</CODE> or <CODE>%l</CODE> is also used.
Another complication is that the locale might not define these values at
all and therefore the conversion fails.
<br><br> <CODE>%P</CODE> is a GNU extension following a GNU extension to <CODE>strftime</CODE>.
<br><br> <LI> %r
The complete time using the AM/PM format of the current locale.
<br><br> A complication is that the locale might not define this format at all
and therefore the conversion fails.
<br><br> <LI> %R
The hour and minute in decimal numbers using the format <CODE>%H:%M</CODE>.
<br><br> <CODE>%R</CODE> is a GNU extension following a GNU extension to <CODE>strftime</CODE>.
<br><br> <LI> %s
The number of seconds since the epoch, i.e., since 1970-01-01 00:00:00 UTC.
Leap seconds are not counted unless leap second support is available.
<br><br> <CODE>%s</CODE> is a GNU extension following a GNU extension to <CODE>strftime</CODE>.
<br><br> <LI> %S
The seconds as a decimal number (range <CODE>0</CODE> through <CODE>60</CODE>).
<br><br> Leading zeroes are permitted but not required.
<br><br> NB: The Unix specification says the upper bound on this value
is <CODE>61</CODE>, a result of a decision to allow double leap seconds. You
will not see the value <CODE>61</CODE> because no minute has more than one
leap second, but the myth persists.
<br><br> <LI> %OS
Same as <CODE>%S</CODE> but using the locale's alternative numeric symbols.
<br><br> <LI> %T
Equivalent to the use of <CODE>%H:%M:%S</CODE> in this place.
<br><br> <LI> %u
The day of the week as a decimal number (range <CODE>1</CODE> through
<CODE>7</CODE>), Monday being <CODE>1</CODE>.
<br><br> Leading zeroes are permitted but not required.
<br><br> <EM>Note:</EM> Currently, this is not fully implemented. The format is
recognized, input is consumed but no field in <VAR>tm</VAR> is set.
<br><br> <LI> %U
The week number of the current year as a decimal number (range <CODE>0</CODE>
through <CODE>53</CODE>).
<br><br> Leading zeroes are permitted but not required.
<br><br> <LI> %OU
Same as <CODE>%U</CODE> but using the locale's alternative numeric symbols.
<br><br> <LI> %V
The ISO 8601:1988 week number as a decimal number (range <CODE>1</CODE>
through <CODE>53</CODE>).
<br><br> Leading zeroes are permitted but not required.
<br><br> <EM>Note:</EM> Currently, this is not fully implemented. The format is
recognized, input is consumed but no field in <VAR>tm</VAR> is set.
<br><br> <LI> %w
The day of the week as a decimal number (range <CODE>0</CODE> through
<CODE>6</CODE>), Sunday being <CODE>0</CODE>.
<br><br> Leading zeroes are permitted but not required.
<br><br> <EM>Note:</EM> Currently, this is not fully implemented. The format is
recognized, input is consumed but no field in <VAR>tm</VAR> is set.
<br><br> <LI> %Ow
Same as <CODE>%w</CODE> but using the locale's alternative numeric symbols.
<br><br> <LI> %W
The week number of the current year as a decimal number (range <CODE>0</CODE>
through <CODE>53</CODE>).
<br><br> Leading zeroes are permitted but not required.
<br><br> <EM>Note:</EM> Currently, this is not fully implemented. The format is
recognized, input is consumed but no field in <VAR>tm</VAR> is set.
<br><br> <LI> %OW
Same as <CODE>%W</CODE> but using the locale's alternative numeric symbols.
<br><br> <LI> %x
The date using the locale's date format.
<br><br> <LI> %Ex
Like <CODE>%x</CODE> but the locale's alternative data representation is used.
<br><br> <LI> %X
The time using the locale's time format.
<br><br> <LI> %EX
Like <CODE>%X</CODE> but the locale's alternative time representation is used.
<br><br> <LI> %y
The year without a century as a decimal number (range <CODE>0</CODE> through
<CODE>99</CODE>).
<br><br> Leading zeroes are permitted but not required.
<br><br> Note that it is questionable to use this format without
the <CODE>%C</CODE> format. The <CODE>strptime</CODE> function does regard input
values in the range 68 to 99 as the years 1969 to
1999 and the values 0 to 68 as the years
2000 to 2068. But maybe this heuristic fails for some
input data.
<br><br> Therefore it is best to avoid <CODE>%y</CODE> completely and use <CODE>%Y</CODE>
instead.
<br><br> <LI> %Ey
The offset from <CODE>%EC</CODE> in the locale's alternative representation.
<br><br> <LI> %Oy
The offset of the year (from <CODE>%C</CODE>) using the locale's alternative
numeric symbols.
<br><br> <LI> %Y
The year as a decimal number, using the Gregorian calendar.
<br><br> <LI> %EY
The full alternative year representation.
<br><br> <LI> %z
The offset from GMT in ISO 8601/RFC822 format.
<br><br> <LI> %Z
The timezone name.
<br><br> <EM>Note:</EM> Currently, this is not fully implemented. The format is
recognized, input is consumed but no field in <VAR>tm</VAR> is set.
<br><br> <LI> %%
A literal <samp>%</samp> character.
<br><br> All other characters in the format string must have a matching character
in the input string. Exceptions are white spaces in the input string
which can match zero or more whitespace characters in the format string.
<br><br> Portability Note: The XPG standard advises applications to use
at least one whitespace character (as specified by <CODE>isspace</CODE>) or
other non-alphanumeric characters between any two conversion
specifications. The GNU C Library does not have this limitation but
other libraries might have trouble parsing formats like
<CODE>"%d%m%Y%H%M%S"</CODE>.
<br><br> The <CODE>strptime</CODE> function processes the input string from right to
left. Each of the three possible input elements (white space, 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.
<br><br> The function returns a pointer to the first character it was unable to
process. If the input string contains more characters than required by
the format string the return value points right after the last consumed
input character. If the whole input string is consumed the return value
points to the <CODE>NULL</CODE> byte at the end of the string. If an error
occurs, i.e., <CODE>strptime</CODE> fails to match all of the format string,
the function returns <CODE>NULL</CODE>.
sq~wttime.hxq~¦t-const char *s, const char *fmt, struct tm *tptchar *tstrrchrsq~
t[
The function <CODE>strrchr</CODE> is like <CODE>strchr</CODE>, except that it searches
backwards from the end of the string <VAR>string</VAR> (instead of forwards
from the front).
<br><br> For example,
<pre><br>
strrchr ("hello, world", 'l')<br>
"ld"<br>
</pre>
sq~wtstring.hxq~­tconst char *string, int ctchar *tstrsepsq~
t
This function has a similar functionality as <CODE>strtok_r</CODE> with the
<VAR>newstring</VAR> argument replaced by the <VAR>save_ptr</VAR> argument. The
initialization of the moving pointer has to be done by the user.
Successive calls to <CODE>strsep</CODE> move the pointer along the tokens
separated by <VAR>delimiter</VAR>, returning the address of the next token
and updating <VAR>string_ptr</VAR> to point to the beginning of the next
token.
<br><br> One difference between <CODE>strsep</CODE> and <CODE>strtok_r</CODE> is that if the
input string contains more than one character from <VAR>delimiter</VAR> in a
row <CODE>strsep</CODE> returns an empty string for each pair of characters
from <VAR>delimiter</VAR>. This means that a program normally should test
for <CODE>strsep</CODE> returning an empty string before processing it.
<br><br> This function was introduced in 4.3BSD and therefore is widely available.
sq~wtstring.hxq~´t(char **string_ptr, const char *delimitertchar *t strsignalsq~
tÈ
This function returns a pointer to a statically-allocated string
containing a message describing the signal <VAR>signum</VAR>. You
should not modify the contents of this string; and, since it can be
rewritten on subsequent calls, you should save a copy of it if you need
to reference it later.
<br><br> This function is a GNU extension, declared in the header file
<TT>string.h</TT>.
sq~wtsignal.htstring.hxq~»t
int signumtchar *tstrspnsq~
t"
The <CODE>strspn</CODE> (``string span'') function returns the length of the
initial substring of <VAR>string</VAR> that consists entirely of characters that
are members of the set specified by the string <VAR>skipset</VAR>. The order
of the characters in <VAR>skipset</VAR> is not important.
<br><br> For example,
<pre><br>
strspn ("hello, world", "abcdefghijklmnopqrstuvwxyz")<br>
5<br>
</pre>
<br><br> Note that ``character'' is here used in the sense of byte. In a string
using a multibyte character encoding (abstract) character consisting of
more than one byte are not treated as an entity. Each byte is treated
separately. The function is not locale-dependent.
sq~wtstring.hxq~Ãt'const char *string, const char *skipsettsize_ttstrstrsq~
t
This is like <CODE>strchr</CODE>, except that it searches <VAR>haystack</VAR> for a
substring <VAR>needle</VAR> rather than just a single character. It
returns a pointer into the string <VAR>haystack</VAR> that is the first
character of the substring, or a null pointer if no match was found. If
<VAR>needle</VAR> is an empty string, the function returns <VAR>haystack</VAR>.
<br><br> For example,
<pre><br>
strstr ("hello, world", "l")<br>
"llo, world"<br>
strstr ("hello, world", "wo")<br>
"world"<br>
</pre>
sq~wtstring.hxq~Êt(const char *haystack, const char *needletchar *tstrtodsq~
t:
The <CODE>strtod</CODE> (``string-to-double'') function converts the initial
part of <VAR>string</VAR> to a floating-point number, which is returned as a
value of type <CODE>double</CODE>.
<br><br> This function attempts to decompose <VAR>string</VAR> as follows:
<br><br> <OL>
<LI>
A (possibly empty) sequence of whitespace characters. Which characters
are whitespace is determined by the <CODE>isspace</CODE> function
. These are discarded.
<br><br> <LI>
An optional plus or minus sign (<samp>+</samp> or <samp>-</samp>).
<br><br> <LI> A floating point number in decimal or hexadecimal format. The
decimal format is:
<UL>
<br><br> <LI>
A nonempty sequence of digits optionally containing a decimal-point
character---normally <samp>.</samp>, but it depends on the locale
.
<br><br> <LI>
An optional exponent part, consisting of a character <samp>e</samp> or
<samp>E</samp>, an optional sign, and a sequence of digits.
<br><br> </UL>
<br><br> The hexadecimal format is as follows:
<UL>
<br><br> <LI>
A 0x or 0X followed by a nonempty sequence of hexadecimal digits
optionally containing a decimal-point character---normally <samp>.</samp>, but
it depends on the locale .
<br><br> <LI>
An optional binary-exponent part, consisting of a character <samp>p</samp> or
<samp>P</samp>, an optional sign, and a sequence of digits.
<br><br> </UL>
<br><br> <LI>
Any remaining characters in the string. If <VAR>tailptr</VAR> is not a null
pointer, a pointer to this tail of the string is stored in
<CODE>*<VAR>tailptr</VAR></CODE>.
</OL>
<br><br> If the string is empty, contains only whitespace, or does not contain an
initial substring that has the expected syntax for a floating-point
number, no conversion is performed. In this case, <CODE>strtod</CODE> returns
a value of zero and the value returned in <CODE>*<VAR>tailptr</VAR></CODE> is the
value of <VAR>string</VAR>.
<br><br> In a locale other than the standard <CODE>"C"</CODE> or <CODE>"POSIX"</CODE> locales,
this function may recognize additional locale-dependent syntax.
<br><br> If the string has valid syntax for a floating-point number but the value
is outside the range of a <CODE>double</CODE>, <CODE>strtod</CODE> will signal
overflow or underflow as described in Math Error Reporting.
<br><br> <CODE>strtod</CODE> recognizes four special input strings. The strings
<CODE>"inf"</CODE> and <CODE>"infinity"</CODE> are converted to infinity{},
or to the largest representable value if the floating-point format
doesn't support infinities. You can prepend a <CODE>"+"</CODE> or <CODE>"-"</CODE>
to specify the sign. Case is ignored when scanning these strings.
<br><br> The strings <CODE>"nan"</CODE> and <CODE>"nan(<VAR>chars</VAR></CODE>)" are converted
to NaN. Again, case is ignored. If <VAR>chars</VAR> are provided, they
are used in some unspecified fashion to select a particular
representation of NaN (there can be several).
<br><br> Since zero is a valid result as well as the value returned on error, you
should check for errors in the same way as for <CODE>strtol</CODE>, by
examining <VAR>errno</VAR> and <VAR>tailptr</VAR>.
sq~wtstdlib.hxq~Ñt4const char *restrict string, char **restrict tailptrtdoubletstrtofsq~
tA
These functions are analogous to <CODE>strtod</CODE>, but return <CODE>float</CODE>
and <CODE>long double</CODE> values respectively. They report errors in the
same way as <CODE>strtod</CODE>. <CODE>strtof</CODE> can be substantially faster
than <CODE>strtod</CODE>, but has less precision; conversely, <CODE>strtold</CODE>
can be much slower but has more precision (on systems where <CODE>long
double</CODE> is a separate type).
<br><br> These functions have been GNU extensions and are new to ISO C99.
sq~wtstdlib.hxq~Øt"const char *string, char **tailptrtfloatt strtoimaxsq~
tÔ
The <CODE>strtoimax</CODE> function is like <CODE>strtol</CODE> except that it returns
a <CODE>intmax_t</CODE> value, and accepts numbers of a corresponding range.
<br><br> If the string has valid syntax for an integer but the value is not
representable because of overflow, <CODE>strtoimax</CODE> returns either
<CODE>INTMAX_MAX</CODE> or <CODE>INTMAX_MIN</CODE> , as
appropriate for the sign of the value. It also sets <CODE>errno</CODE> to
<CODE>ERANGE</CODE> to indicate there was overflow.
<br><br> See Integers for a description of the <CODE>intmax_t</CODE> type. The
<CODE>strtoimax</CODE> function was introduced in ISO C99.
sq~wt
inttypes.hxq~ßt>const char *restrict string, char **restrict tailptr, int basetintmax_ttstrtoksq~
t 
A string can be split into tokens by making a series of calls to the
function <CODE>strtok</CODE>.
<br><br> The string to be split up is passed as the <VAR>newstring</VAR> argument on
the first call only. The <CODE>strtok</CODE> function uses this to set up
some internal state information. Subsequent calls to get additional
tokens from the same string are indicated by passing a null pointer as
the <VAR>newstring</VAR> argument. Calling <CODE>strtok</CODE> with another
non-null <VAR>newstring</VAR> argument reinitializes the state information.
It is guaranteed that no other library function ever calls <CODE>strtok</CODE>
behind your back (which would mess up this internal state information).
<br><br> The <VAR>delimiters</VAR> argument is a string that specifies a set of delimiters
that may surround the token being extracted. All the initial characters
that are members of this set are discarded. The first character that is
<EM>not</EM> a member of this set of delimiters marks the beginning of the
next token. The end of the token is found by looking for the next
character that is a member of the delimiter set. This character in the
original string <VAR>newstring</VAR> is overwritten by a null character, and the
pointer to the beginning of the token in <VAR>newstring</VAR> is returned.
<br><br> On the next call to <CODE>strtok</CODE>, the searching begins at the next
character beyond the one that marked the end of the previous token.
Note that the set of delimiters <VAR>delimiters</VAR> do not have to be the
same on every call in a series of calls to <CODE>strtok</CODE>.
<br><br> If the end of the string <VAR>newstring</VAR> is reached, or if the remainder of
string consists only of delimiter characters, <CODE>strtok</CODE> returns
a null pointer.
<br><br> Note that ``character'' is here used in the sense of byte. In a string
using a multibyte character encoding (abstract) character consisting of
more than one byte are not treated as an entity. Each byte is treated
separately. The function is not locale-dependent.
sq~wtstring.hxq~æt9char *restrict newstring, const char *restrict delimiterstchar *tstrtok_rsq~
tÂ
Just like <CODE>strtok</CODE>, this function splits the string into several
tokens which can be accessed by successive calls to <CODE>strtok_r</CODE>.
The difference is that the information about the next token is stored in
the space pointed to by the third argument, <VAR>save_ptr</VAR>, which is a
pointer to a string pointer. Calling <CODE>strtok_r</CODE> with a null
pointer for <VAR>newstring</VAR> and leaving <VAR>save_ptr</VAR> between the calls
unchanged does the job without hindering reentrancy.
<br><br> This function is defined in POSIX.1 and can be found on many systems
which support multi-threading.
sq~wtstring.hxq~ít8char *newstring, const char *delimiters, char **save_ptrtchar *tstrtolsq~
t ‹
The <CODE>strtol</CODE> (``string-to-long'') function converts the initial
part of <VAR>string</VAR> to a signed integer, which is returned as a value
of type <CODE>long int</CODE>.
<br><br> This function attempts to decompose <VAR>string</VAR> as follows:
<br><br> <OL>
<LI>
A (possibly empty) sequence of whitespace characters. Which characters
are whitespace is determined by the <CODE>isspace</CODE> function
. These are discarded.
<br><br> <LI>
An optional plus or minus sign (<samp>+</samp> or <samp>-</samp>).
<br><br> <LI>
A nonempty sequence of digits in the radix specified by <VAR>base</VAR>.
<br><br> If <VAR>base</VAR> is zero, decimal radix is assumed unless the series of
digits begins with <samp>0</samp> (specifying octal radix), or <samp>0x</samp> or
<samp>0X</samp> (specifying hexadecimal radix); in other words, the same
syntax used for integer constants in C.
<br><br> Otherwise <VAR>base</VAR> must have a value between <CODE>2</CODE> and <CODE>36</CODE>.
If <VAR>base</VAR> is <CODE>16</CODE>, the digits may optionally be preceded by
<samp>0x</samp> or <samp>0X</samp>. If base has no legal value the value returned
is <CODE>0l</CODE> and the global variable <CODE>errno</CODE> is set to <CODE>EINVAL</CODE>.
<br><br> <LI>
Any remaining characters in the string. If <VAR>tailptr</VAR> is not a null
pointer, <CODE>strtol</CODE> stores a pointer to this tail in
<CODE>*<VAR>tailptr</VAR></CODE>.
</OL>
<br><br> If the string is empty, contains only whitespace, or does not contain an
initial substring that has the expected syntax for an integer in the
specified <VAR>base</VAR>, no conversion is performed. In this case,
<CODE>strtol</CODE> returns a value of zero and the value stored in
<CODE>*<VAR>tailptr</VAR></CODE> is the value of <VAR>string</VAR>.
<br><br> In a locale other than the standard <CODE>"C"</CODE> locale, this function
may recognize additional implementation-dependent syntax.
<br><br> If the string has valid syntax for an integer but the value is not
representable because of overflow, <CODE>strtol</CODE> returns either
<CODE>LONG_MAX</CODE> or <CODE>LONG_MIN</CODE> , as
appropriate for the sign of the value. It also sets <CODE>errno</CODE>
to <CODE>ERANGE</CODE> to indicate there was overflow.
<br><br> You should not check for errors by examining the return value of
<CODE>strtol</CODE>, because the string might be a valid representation of
<CODE>0l</CODE>, <CODE>LONG_MAX</CODE>, or <CODE>LONG_MIN</CODE>. Instead, check whether
<VAR>tailptr</VAR> points to what you expect after the number
(e.g. <CODE>'\0'</CODE> if the string should end after the number). You also
need to clear <VAR>errno</VAR> before the call and check it afterward, in
case there was overflow.
<br><br> There is an example at the end of this section.
sq~wtstdlib.hxq~ôt>const char *restrict string, char **restrict tailptr, int basetlong inttstrtoldsq~
tA
These functions are analogous to <CODE>strtod</CODE>, but return <CODE>float</CODE>
and <CODE>long double</CODE> values respectively. They report errors in the
same way as <CODE>strtod</CODE>. <CODE>strtof</CODE> can be substantially faster
than <CODE>strtod</CODE>, but has less precision; conversely, <CODE>strtold</CODE>
can be much slower but has more precision (on systems where <CODE>long
double</CODE> is a separate type).
<br><br> These functions have been GNU extensions and are new to ISO C99.
sq~wtstdlib.hxq~ût"const char *string, char **tailptrt long doubletstrtollsq~
t¡
The <CODE>strtoll</CODE> function is like <CODE>strtol</CODE> except that it returns
a <CODE>long long int</CODE> value, and accepts numbers with a correspondingly
larger range.
<br><br> If the string has valid syntax for an integer but the value is not
representable because of overflow, <CODE>strtoll</CODE> returns either
<CODE>LONG_LONG_MAX</CODE> or <CODE>LONG_LONG_MIN</CODE> , as
appropriate for the sign of the value. It also sets <CODE>errno</CODE> to
<CODE>ERANGE</CODE> to indicate there was overflow.
<br><br> The <CODE>strtoll</CODE> function was introduced in ISO C99.
sq~wtstdlib.hxq~t>const char *restrict string, char **restrict tailptr, int baset
long long inttstrtoqsq~
ti
<CODE>strtoq</CODE> (``string-to-quad-word'') is the BSD name for <CODE>strtoll</CODE>.
sq~wtstdlib.hxq~ t>const char *restrict string, char **restrict tailptr, int baset
long long inttstrtoulsq~
t|
The <CODE>strtoul</CODE> (``string-to-unsigned-long'') function is like
<CODE>strtol</CODE> except it converts to an <CODE>unsigned long int</CODE> value.
The syntax is the same as described above for <CODE>strtol</CODE>. The value
returned on overflow is <CODE>ULONG_MAX</CODE> .
<br><br> If <VAR>string</VAR> depicts a negative number, <CODE>strtoul</CODE> acts the same
as <VAR>strtol</VAR> but casts the result to an unsigned integer. That means
for example that <CODE>strtoul</CODE> on <CODE>"-1"</CODE> returns <CODE>ULONG_MAX</CODE>
and an input more negative than <CODE>LONG_MIN</CODE> returns
(<CODE>ULONG_MAX</CODE> + 1) / 2.
<br><br> <CODE>strtoul</CODE> sets <VAR>errno</VAR> to <CODE>EINVAL</CODE> if <VAR>base</VAR> is out of
range, or <CODE>ERANGE</CODE> on overflow.
sq~wtstdlib.hxq~t=const char *retrict string, char **restrict tailptr, int basetunsigned long inttstrtoullsq~
tõ
The <CODE>strtoull</CODE> function is related to <CODE>strtoll</CODE> the same way
<CODE>strtoul</CODE> is related to <CODE>strtol</CODE>.
<br><br> The <CODE>strtoull</CODE> function was introduced in ISO C99.
sq~wtstdlib.hxq~t>const char *restrict string, char **restrict tailptr, int basetunsigned long long intt strtoumaxsq~
tJ
The <CODE>strtoumax</CODE> function is related to <CODE>strtoimax</CODE>
the same way that <CODE>strtoul</CODE> is related to <CODE>strtol</CODE>.
<br><br> See Integers for a description of the <CODE>intmax_t</CODE> type. The
<CODE>strtoumax</CODE> function was introduced in ISO C99.
sq~wt
inttypes.hxq~t>const char *restrict string, char **restrict tailptr, int baset uintmax_ttstrtouqsq~
tQ
<CODE>strtouq</CODE> is the BSD name for <CODE>strtoull</CODE>.
sq~wtstdlib.hxq~%t>const char *restrict string, char **restrict tailptr, int basetunsigned long long intt
strverscmpsq~
tÉ
The <CODE>strverscmp</CODE> function compares the string <VAR>s1</VAR> against
<VAR>s2</VAR>, considering them as holding indices/version numbers. Return
value follows the same conventions as found in the <CODE>strverscmp</CODE>
function. In fact, if <VAR>s1</VAR> and <VAR>s2</VAR> contain no digits,
<CODE>strverscmp</CODE> behaves like <CODE>strcmp</CODE>.
<br><br> Basically, we compare strings normally (character by character), until
we find a digit in each string - then we enter a special comparison
mode, where each sequence of digits is taken as a whole. If we reach the
end of these two parts without noticing a difference, we return to the
standard comparison mode. There are two types of numeric parts:
"integral" and "fractional" (those begin with a '0'). The types
of the numeric parts affect the way we sort them:
<br><br> <OL>
<LI>
integral/integral: we compare values as you would expect.
<br><br> <LI>
fractional/integral: the fractional part is less than the integral one.
Again, no surprise.
<br><br> <LI>
fractional/fractional: the things become a bit more complex.
If the common prefix contains only leading zeroes, the longest part is less
than the other one; else the comparison behaves normally.
</OL>
<br><br> <pre><br>
strverscmp ("no digit", "no digit")<br>
0 /* same behavior as strcmp. */<br>
strverscmp ("item#99", "item#100")<br>
<0 /* same prefix, but 99 < 100. */<br>
strverscmp ("alpha1", "alpha001")<br>
>0 /* fractional part inferior to integral one. */<br>
strverscmp ("part1_f012", "part1_f01")<br>
>0 /* two fractional parts. */<br>
strverscmp ("foo.009", "foo.0")<br>
<0 /* idem, but with leading zeroes only. */<br>
</pre>
<br><br> This function is especially useful when dealing with filename sorting,
because filenames frequently hold indices/version numbers.
<br><br> <CODE>strverscmp</CODE> is a GNU extension.
sq~wtstring.hxq~,tconst char *s1, const char *s2tinttstrxfrmsq~
t
The function <CODE>strxfrm</CODE> transforms the string <VAR>from</VAR> using the
collation transformation determined by the locale currently selected for
collation, and stores the transformed string in the array <VAR>to</VAR>. Up
to <VAR>size</VAR> characters (including a terminating null character) are
stored.
<br><br> The behavior is undefined if the strings <VAR>to</VAR> and <VAR>from</VAR>
overlap; see Copying and Concatenation.
<br><br> The return value is the length of the entire transformed string. This
value is not affected by the value of <VAR>size</VAR>, but if it is greater
or equal than <VAR>size</VAR>, it means that the transformed string did not
entirely fit in the array <VAR>to</VAR>. In this case, only as much of the
string as actually fits was stored. To get the whole transformed
string, call <CODE>strxfrm</CODE> again with a bigger output array.
<br><br> The transformed string may be longer than the original string, and it
may also be shorter.
<br><br> If <VAR>size</VAR> is zero, no characters are stored in <VAR>to</VAR>. In this
case, <CODE>strxfrm</CODE> simply returns the number of characters that would
be the length of the transformed string. This is useful for determining
what size the allocated array should be. It does not matter what
<VAR>to</VAR> is if <VAR>size</VAR> is zero; <VAR>to</VAR> may even be a null pointer.
sq~wtstring.hxq~3t9char *restrict to, const char *restrict from, size_t sizetsize_ttsttysq~
t
<br><br> This function sets the attributes of a terminal.
<br><br> <CODE>stty</CODE> sets the terminal attributes of the terminal which is open with
file descriptor <VAR>filedes</VAR> to those described by *<VAR>filedes</VAR>.
sq~wtsgtty.hxq~:t'int filedes, struct sgttyb * attributestintt swapcontextsq~
t„
<br><br> The <CODE>swapcontext</CODE> function is similar to <CODE>setcontext</CODE> but
instead of just replacing the current context the latter is first saved
in the object pointed to by <VAR>oucp</VAR> as if this was a call to
<CODE>getcontext</CODE>. The saved context would resume after the call to
<CODE>swapcontext</CODE>.
<br><br> Once the current context is saved the context described in <VAR>ucp</VAR> is
installed and execution continues as described in this context.
<br><br> If <CODE>swapcontext</CODE> succeeds the function does not return unless the
context <VAR>oucp</VAR> is used without prior modification by
<CODE>makecontext</CODE>. The return value in this case is <CODE>0</CODE>. If the
function fails it returns <CODE>-1</CODE> and set <VAR>errno</VAR> accordingly.
sq~wt
ucontext.hxq~At9ucontext_t *restrict oucp, const ucontext_t *restrict ucptinttswprintfsq~
t2
This is like <CODE>wprintf</CODE>, except that the output is stored in the
wide character array <VAR>ws</VAR> instead of written to a stream. A null
wide character is written to mark the end of the string. The <VAR>size</VAR>
argument specifies the maximum number of characters to produce. The
trailing null character is counted towards this limit, so you should
allocate at least <VAR>size</VAR> wide characters for the string <VAR>ws</VAR>.
<br><br> The return value is the number of characters generated for the given
input, excluding the trailing null. If not all output fits into the
provided buffer a negative value is returned. You should try again with
a bigger output string. <EM>Note:</EM> this is different from how
<CODE>snprintf</CODE> handles this situation.
<br><br> Note that the corresponding narrow stream function takes fewer
parameters. <CODE>swprintf</CODE> in fact corresponds to the <CODE>snprintf</CODE>
function. Since the <CODE>sprintf</CODE> function can be dangerous and should
be avoided the ISO C committee refused to make the same mistake
again and decided to not define an function exactly corresponding to
<CODE>sprintf</CODE>.
sq~wtwchar.hxq~Ht5wchar_t *s, size_t size, const wchar_t *template, ...tinttswscanfsq~
t2
This is like <CODE>wscanf</CODE>, except that the characters are taken from the
null-terminated string <VAR>ws</VAR> instead of from a stream. Reaching the
end of the string is treated as an end-of-file condition.
<br><br> The behavior of this function is undefined if copying takes place
between objects that overlap---for example, if <VAR>ws</VAR> is also given as
an argument to receive a string read under control of the <samp>%s</samp>,
<samp>%S</samp>, or <samp>%[</samp> conversion.
sq~wtwchar.hxq~Ot,const wchar_t *ws, const char *template, ...tinttsymlinksq~
t†
The <CODE>symlink</CODE> function makes a symbolic link to <VAR>oldname</VAR> named
<VAR>newname</VAR>.
<br><br> The normal return value from <CODE>symlink</CODE> is <CODE>0</CODE>. A return value
of <CODE>-1</CODE> indicates an error. In addition to the usual file name
syntax errors , the following <CODE>errno</CODE>
error conditions are defined for this function:
<br><br> <DL>
<DT><CODE>EEXIST</CODE>
<DD>
There is already an existing file named <VAR>newname</VAR>.
<br><br> <LI> EROFS
The file <VAR>newname</VAR> would exist on a read-only file system.
<br><br> <LI> ENOSPC
The directory or file system cannot be extended to make the new link.
<br><br> <LI> EIO
A hardware error occurred while reading or writing data on the disk.
<br><br>
sq~wt sys/param.htunistd.hxq~Vt(const char *oldname, const char *newnametinttsyncsq~
tÃ
A call to this function will not return as long as there is data which
has not been written to the device. All dirty buffers in the kernel will
be written and so an overall consistent system can be achieved (if no
other process in parallel writes data).
<br><br> A prototype for <CODE>sync</CODE> can be found in <TT>unistd.h</TT>.
<br><br> The return value is zero to indicate no error.
sq~wtunistd.hxq~^tvoidtinttsyscallsq~
tw
<br><br> <CODE>syscall</CODE> performs a generic system call.
<br><br> call number
<VAR>sysno</VAR> is the system call number. Each kind of system call is
identified by a number. Macros for all the possible system call numbers
are defined in <TT>sys/syscall.h</TT>
<br><br> The remaining arguments are the arguments for the system call, in
order, and their meanings depend on the kind of system call. Each kind
of system call has a definite number of arguments, from zero to five.
If you code more arguments than the system call takes, the extra ones to
the right are ignored.
<br><br> The return value is the return value from the system call, unless the
system call failed. In that case, <CODE>syscall</CODE> returns <CODE>-1</CODE> and
sets <CODE>errno</CODE> to an error code that the system call returned. Note
that system calls do not return <CODE>-1</CODE> when they succeed.
<br><br> If you specify an invalid <VAR>sysno</VAR>, <CODE>syscall</CODE> returns <CODE>-1</CODE>
with <CODE>errno</CODE> = <CODE>ENOSYS</CODE>.
<br><br> Example:
<br><br> <pre><br>
<br><br> #include <unistd.h><br>
#include <sys/syscall.h><br>
#include <errno.h><br>
<br><br> <small>...</small><br>
<br><br> int rc;<br>
<br><br> rc = syscall(SYS_chmod, "/etc/passwd", 0444);<br>
<br><br> if (rc == -1)<br>
fprintf(stderr, "chmod failed, errno = %d\n", errno);<br>
<br><br> </pre><br>
<br><br> This, if all the compatibility stars are aligned, is equivalent to the<br>
following preferable code:<br>
<br><br> <pre><br>
<br><br> #include <sys/types.h><br>
#include <sys/stat.h><br>
#include <errno.h><br>
<br><br> <small>...</small><br>
<br><br> int rc;<br>
<br><br> rc = chmod("/etc/passwd", 0444);<br>
if (rc == -1)<br>
fprintf(stderr, "chmod failed, errno = %d\n", errno);<br>
<br><br> </pre>
<br><br>
sq~wtunistd.hxq~etlong int sysno, ...tlong inttsysconfsq~
tˆ
This function is used to inquire about runtime system parameters. The
<VAR>parameter</VAR> argument should be one of the <samp>_SC_</samp> symbols listed
below.
<br><br> The normal return value from <CODE>sysconf</CODE> is the value you requested.
A value of <CODE>-1</CODE> is returned both if the implementation does not
impose a limit, and in case of an error.
<br><br> The following <CODE>errno</CODE> error conditions are defined for this function:
<br><br> <DL>
<DT><CODE>EINVAL</CODE>
<DD>
The value of the <VAR>parameter</VAR> is invalid.
sq~wtlimits.htunistd.hxq~lt
int parametertlong inttsysctlsq~
t<
<br><br> <CODE>sysctl</CODE> gets or sets a specified system parameter. There are so
many of these parameters that it is not practical to list them all here,
but here are some examples:
<br><br> <OL>
<LI> network domain name
<LI> paging parameters
<LI> network Address Resolution Protocol timeout time
<LI> maximum number of files that may be open
<LI> root filesystem device
<LI> when kernel was built
</OL>
<br><br> The set of available parameters depends on the kernel configuration and
can change while the system is running, particularly when you load and
unload loadable kernel modules.
<br><br> The system parameters with which <CODE>syslog</CODE> is concerned are arranged
in a hierarchical structure like a hierarchical filesystem. To identify
a particular parameter, you specify a path through the structure in a
way analogous to specifying the pathname of a file. Each component of
the path is specified by an integer and each of these integers has a
macro defined for it by <TT>sysctl.h</TT>. <VAR>names</VAR> is the path, in
the form of an array of integers. Each component of the path is one
element of the array, in order. <VAR>nlen</VAR> is the number of components
in the path.
<br><br> For example, the first component of the path for all the paging
parameters is the value <CODE>CTL_VM</CODE>. For the free page thresholds, the
second component of the path is <CODE>VM_FREEPG</CODE>. So to get the free
page threshold values, make <VAR>names</VAR> an array containing the two
elements <CODE>CTL_VM</CODE> and <CODE>VM_FREEPG</CODE> and make <VAR>nlen</VAR> = 2.
<br><br> <br><br> The format of the value of a parameter depends on the parameter.
Sometimes it is an integer; sometimes it is an ASCII string; sometimes
it is an elaborate structure. In the case of the free page thresholds
used in the example above, the parameter value is a structure containing
several integers.
<br><br> In any case, you identify a place to return the parameter's value with
<VAR>oldval</VAR> and specify the amount of storage available at that
location as *<VAR>oldlenp</VAR>. *<VAR>oldlenp</VAR> does double duty because it
is also the output location that contains the actual length of the
returned value.
<br><br> If you don't want the parameter value returned, specify a null pointer
for <VAR>oldval</VAR>.
<br><br> To set the parameter, specify the address and length of the new value
as <VAR>newval</VAR> and <VAR>newlen</VAR>. If you don't want to set the parameter,
specify a null pointer as <VAR>newval</VAR>.
<br><br> If you get and set a parameter in the same <CODE>sysctl</CODE> call, the value
returned is the value of the parameter before it was set.
<br><br> Each system parameter has a set of permissions similar to the
permissions for a file (including the permissions on directories in its
path) that determine whether you may get or set it. For the purposes of
these permissions, every parameter is considered to be owned by the
superuser and Group 0 so processes with that effective uid or gid may
have more access to system parameters. Unlike with files, the superuser
does not invariably have full permission to all system parameters, because
some of them are designed not to be changed ever.
<br><br> <br><br> <CODE>sysctl</CODE> returns a zero return value if it succeeds. Otherwise, it
returns <CODE>-1</CODE> and sets <CODE>errno</CODE> appropriately. Besides the
failures that apply to all system calls, the following are the
<CODE>errno</CODE> codes for all possible failures:
<br><br> <DL>
<DT><CODE>EPERM</CODE>
<DD>
The process is not permitted to access one of the components of the
path of the system parameter or is not permitted to access the system parameter
itself in the way (read or write) that it requested.
<LI> ENOTDIR
There is no system parameter corresponding to <VAR>name</VAR>.
<LI> EFAULT
<VAR>oldval</VAR> is not null, which means the process wanted to read the parameter,
but *<VAR>oldlenp</VAR> is zero, so there is no place to return it.
<LI> EINVAL
<OL>
<LI>
The process attempted to set a system parameter to a value that is not valid
for that parameter.
<LI>
The space provided for the return of the system parameter is not the right
size for that parameter.
</OL>
<LI> ENOMEM
This value may be returned instead of the more correct <CODE>EINVAL</CODE> in some
cases where the space provided for the return of the system parameter is too
small.
<br><br>
<br><br>
sq~wtsysctl.hxq~ttPint *names, int nlen, void *oldval, size_t *oldlenp, void *newval, size_t newlentinttsyslogsq~
tñ
<br><br> <CODE>syslog</CODE> submits a message to the Syslog facility. It does this by
writing to the Unix domain socket <CODE>/dev/log</CODE>.
<br><br> <CODE>syslog</CODE> submits the message with the facility and priority indicated
by <VAR>facility_priority</VAR>. The macro <CODE>LOG_MAKEPRI</CODE> generates a
facility/priority from a facility and a priority, as in the following
example:
<br><br> <pre><br>
LOG_MAKEPRI(LOG_USER, LOG_WARNING)<br>
</pre><br>
<br><br> The possible values for the facility code are (macros):<br>
<br><br> <br><br> <DL>
<br>
<DT><CODE>LOG_USER<br></CODE>
<DD>
A miscellaneous user process<br>
<DT><CODE>LOG_MAIL<br></CODE>
<DD>
Mail<br>
<DT><CODE>LOG_DAEMON<br></CODE>
<DD>
A miscellaneous system daemon<br>
<DT><CODE>LOG_AUTH<br></CODE>
<DD>
Security (authorization)<br>
<DT><CODE>LOG_SYSLOG<br></CODE>
<DD>
Syslog<br>
<DT><CODE>LOG_LPR<br></CODE>
<DD>
Central printer<br>
<DT><CODE>LOG_NEWS<br></CODE>
<DD>
Network news (e.g. Usenet)<br>
<DT><CODE>LOG_UUCP<br></CODE>
<DD>
UUCP<br>
<DT><CODE>LOG_CRON<br></CODE>
<DD>
Cron and At<br>
<DT><CODE>LOG_AUTHPRIV<br></CODE>
<DD>
Private security (authorization)<br>
<DT><CODE>LOG_FTP<br></CODE>
<DD>
Ftp server<br>
<DT><CODE>LOG_LOCAL0<br></CODE>
<DD>
Locally defined<br>
<DT><CODE>LOG_LOCAL1<br></CODE>
<DD>
Locally defined<br>
<DT><CODE>LOG_LOCAL2<br></CODE>
<DD>
Locally defined<br>
<DT><CODE>LOG_LOCAL3<br></CODE>
<DD>
Locally defined<br>
<DT><CODE>LOG_LOCAL4<br></CODE>
<DD>
Locally defined<br>
<DT><CODE>LOG_LOCAL5<br></CODE>
<DD>
Locally defined<br>
<DT><CODE>LOG_LOCAL6<br></CODE>
<DD>
Locally defined<br>
<DT><CODE>LOG_LOCAL7<br></CODE>
<DD>
Locally defined<br>
</DL><br>
<br><br> Results are undefined if the facility code is anything else.<br>
<br><br> NB: <CODE>syslog</CODE> recognizes one other facility code: that of<br>
the kernel. But you can't specify that facility code with these<br>
functions. If you try, it looks the same to <CODE>syslog</CODE> as if you are<br>
requesting the default facility. But you wouldn't want to anyway,<br>
because any program that uses the GNU C library is not the kernel.<br>
<br><br> You can use just a priority code as <VAR>facility_priority</VAR>. In that<br>
case, <CODE>syslog</CODE> assumes the default facility established when the<br>
Syslog connection was opened. .<br>
<br><br> The possible values for the priority code are (macros):<br>
<br><br> <DL>
<br>
<DT><CODE>LOG_EMERG<br></CODE>
<DD>
The message says the system is unusable.<br>
<DT><CODE>LOG_ALERT<br></CODE>
<DD>
Action on the message must be taken immediately.<br>
<DT><CODE>LOG_CRIT<br></CODE>
<DD>
The message states a critical condition.<br>
<DT><CODE>LOG_ERR<br></CODE>
<DD>
The message describes an error.<br>
<DT><CODE>LOG_WARNING<br></CODE>
<DD>
The message is a warning.<br>
<DT><CODE>LOG_NOTICE<br></CODE>
<DD>
The message describes a normal but important event.<br>
<DT><CODE>LOG_INFO<br></CODE>
<DD>
The message is purely informational.<br>
<DT><CODE>LOG_DEBUG<br></CODE>
<DD>
The message is only for debugging purposes.<br>
</DL><br>
<br><br> Results are undefined if the priority code is anything else.<br>
<br><br> If the process does not presently have a Syslog connection open (i.e.,<br>
it did not call <CODE>openlog</CODE>), <CODE>syslog</CODE> implicitly opens the<br>
connection the same as <CODE>openlog</CODE> would, with the following defaults<br>
for information that would otherwise be included in an <CODE>openlog</CODE><br>
call: The default identification string is the program name. The<br>
default default facility is <CODE>LOG_USER</CODE>. The default for all the<br>
connection options in <VAR>options</VAR> is as if those bits were off.<br>
<CODE>syslog</CODE> leaves the Syslog connection open.<br>
<br><br> If the <TT>dev/log</TT> socket is not open and connected, <CODE>syslog</CODE><br>
opens and connects it, the same as <CODE>openlog</CODE> with the<br>
<CODE>LOG_NDELAY</CODE> option would.<br>
<br><br> <CODE>syslog</CODE> leaves <TT>/dev/log</TT> open and connected unless its attempt<br>
to send the message failed, in which case <CODE>syslog</CODE> closes it (with the<br>
hope that a future implicit open will restore the Syslog connection to a<br>
usable state).<br>
<br><br> Example:<br>
<br><br> <pre><br>
<br><br> #include <syslog.h><br>
syslog (LOG_MAKEPRI(LOG_LOCAL1, LOG_ERROR),<br>
"Unable to make network connection to %s. Error=%m", host);<br>
<br><br> </pre>
<br><br>
sq~wtsyslog.hxq~{t(int facility_priority, char *format, ...tvoidtsystemsq~
tÚ
This function executes <VAR>command</VAR> as a shell command. In the GNU C
library, it always uses the default shell <CODE>sh</CODE> to run the command.
In particular, it searches the directories in <CODE>PATH</CODE> to find
programs to execute. The return value is <CODE>-1</CODE> if it wasn't
possible to create the shell process, and otherwise is the status of the
shell process. , for details on how this
status code can be interpreted.
<br><br> If the <VAR>command</VAR> argument is a null pointer, a return value of zero
indicates that no command processor is available.
<br><br> This function is a cancellation point in multi-threaded programs. This
is a problem if the thread allocates some resources (like memory, file
descriptors, semaphores or whatever) at the time <CODE>system</CODE> is
called. If the thread gets canceled these resources stay allocated
until the program ends. To avoid this calls to <CODE>system</CODE> should be
protected using cancellation handlers.
<br><br> The <CODE>system</CODE> function is declared in the header file
<TT>stdlib.h</TT>.
sq~wtstdlib.hxq~‚tconst char *commandtintt sysv_signalsq~
t¾
The <CODE>sysv_signal</CODE> implements the behavior of the standard
<CODE>signal</CODE> function as found on SVID systems. The difference to BSD
systems is that the handler is deinstalled after a delivery of a signal.
<br><br> Compatibility Note: As said above for <CODE>signal</CODE>, this
function should be avoided when possible. <CODE>sigaction</CODE> is the
preferred method.
sq~wtsignal.hxq~‰tint signum, sighandler_t actiont sighandler_tttansq~
t\
These functions return the tangent of <VAR>x</VAR>, where <VAR>x</VAR> is given in
radians.
<br><br> Mathematically, the tangent function has singularities at odd multiples
of pi/2. If the argument <VAR>x</VAR> is too close to one of these
singularities, <CODE>tan</CODE> will signal overflow.
sq~wtmath.hxq~�tdouble xtdoublettanfsq~
t\
These functions return the tangent of <VAR>x</VAR>, where <VAR>x</VAR> is given in
radians.
<br><br> Mathematically, the tangent function has singularities at odd multiples
of pi/2. If the argument <VAR>x</VAR> is too close to one of these
singularities, <CODE>tan</CODE> will signal overflow.
sq~wtmath.hxq~—tfloat xtfloatttanhsq~
të
These functions return the hyperbolic tangent of <VAR>x</VAR>,
defined mathematically as <CODE>sinh (<VAR>x</VAR>) / cosh (<VAR>x</VAR>)</CODE>.
They may signal overflow if <VAR>x</VAR> is too large.
sq~wtmath.hxq~žtdouble xtdoublettanhfsq~
të
These functions return the hyperbolic tangent of <VAR>x</VAR>,
defined mathematically as <CODE>sinh (<VAR>x</VAR>) / cosh (<VAR>x</VAR>)</CODE>.
They may signal overflow if <VAR>x</VAR> is too large.
sq~wtmath.hxq~¥tfloat xtfloatttanhlsq~
të
These functions return the hyperbolic tangent of <VAR>x</VAR>,
defined mathematically as <CODE>sinh (<VAR>x</VAR>) / cosh (<VAR>x</VAR>)</CODE>.
They may signal overflow if <VAR>x</VAR> is too large.
sq~wtmath.hxq~¬t
long double xt long doublettanlsq~
t\
These functions return the tangent of <VAR>x</VAR>, where <VAR>x</VAR> is given in
radians.
<br><br> Mathematically, the tangent function has singularities at odd multiples
of pi/2. If the argument <VAR>x</VAR> is too close to one of these
singularities, <CODE>tan</CODE> will signal overflow.
sq~wtmath.hxq~³t
long double xt long doublettcdrainsq~
t�
The <CODE>tcdrain</CODE> function waits until all queued
output to the terminal <VAR>filedes</VAR> has been transmitted.
<br><br> This function is a cancellation point in multi-threaded programs. This
is a problem if the thread allocates some resources (like memory, file
descriptors, semaphores or whatever) at the time <CODE>tcdrain</CODE> is
called. If the thread gets canceled these resources stay allocated
until the program ends. To avoid this calls to <CODE>tcdrain</CODE> should be
protected using cancellation handlers.
<br><br> The return value is normally zero. In the event of an error, a value
of -1 is returned. The following <CODE>errno</CODE> error conditions
are defined for this function:
<br><br> <DL>
<DT><CODE>EBADF</CODE>
<DD>
The <VAR>filedes</VAR> is not a valid file descriptor.
<br><br> <LI> ENOTTY
The <VAR>filedes</VAR> is not associated with a terminal device.
<br><br> <LI> EINTR
The operation was interrupted by delivery of a signal.
.
sq~wt termios.hxq~ºt int filedestintttcflowsq~
t
The <CODE>tcflow</CODE> function is used to perform operations relating to
XON/XOFF flow control on the terminal file specified by <VAR>filedes</VAR>.
<br><br> The <VAR>action</VAR> argument specifies what operation to perform, and can
be one of the following values:
<br><br> <DL>
<DT><CODE>TCOOFF</CODE>
<DD>
Suspend transmission of output.
<br><br>
<DT><CODE>TCOON</CODE>
<DD>
Restart transmission of output.
<br><br>
<LI> TCIOFF
Transmit a STOP character.
<br><br>
<LI> TCION
Transmit a START character.
<br><br> For more information about the STOP and START characters, see Special
Characters.
<br><br> The return value is normally zero. In the event of an error, a value
of -1 is returned. The following <CODE>errno</CODE> error conditions
are defined for this function:
<br><br> <DL>
<LI> EBADF
The <VAR>filedes</VAR> is not a valid file descriptor.
<br><br>
<LI> ENOTTY
The <VAR>filedes</VAR> is not associated with a terminal device.
<br><br>
<LI> EINVAL
A bad value was supplied as the <VAR>action</VAR> argument.
sq~wt termios.hxq~Átint filedes, int actiontintttcflushsq~
t
The <CODE>tcflush</CODE> function is used to clear the input and/or output
queues associated with the terminal file <VAR>filedes</VAR>. The <VAR>queue</VAR>
argument specifies which queue(s) to clear, and can be one of the
following values:
<br><br> <DL>
<DT><CODE>TCIFLUSH</CODE>
<DD>
<br><br> Clear any input data received, but not yet read.
<br><br>
<DT><CODE>TCOFLUSH</CODE>
<DD>
<br><br> Clear any output data written, but not yet transmitted.
<br><br>
<LI> TCIOFLUSH
<br><br> Clear both queued input and output.
<br><br> The return value is normally zero. In the event of an error, a value
of -1 is returned. The following <CODE>errno</CODE> error conditions
are defined for this function:
<br><br> <DL>
<LI> EBADF
The <VAR>filedes</VAR> is not a valid file descriptor.
<br><br> <LI> ENOTTY
The <VAR>filedes</VAR> is not associated with a terminal device.
<br><br> <LI> EINVAL
A bad value was supplied as the <VAR>queue</VAR> argument.
<br><br> It is unfortunate that this function is named <CODE>tcflush</CODE>, because
the term ``flush'' is normally used for quite another operation---waiting
until all output is transmitted---and using it for discarding input or
output would be confusing. Unfortunately, the name <CODE>tcflush</CODE> comes
from POSIX and we cannot change it.
sq~wt termios.hxq~Ètint filedes, int queuetintt tcgetattrsq~
tŸ
This function is used to examine the attributes of the terminal
device with file descriptor <VAR>filedes</VAR>. The attributes are returned
in the structure that <VAR>termios-p</VAR> points to.
<br><br> If successful, <CODE>tcgetattr</CODE> returns 0. A return value of -1
indicates an error. The following <CODE>errno</CODE> error conditions are
defined for this function:
<br><br> <DL>
<DT><CODE>EBADF</CODE>
<DD>
The <VAR>filedes</VAR> argument is not a valid file descriptor.
<br><br> <LI> ENOTTY
The <VAR>filedes</VAR> is not associated with a terminal.
sq~wt termios.hxq~Ït&int filedes, struct termios *termios-ptintt tcgetpgrpsq~
tU
This function returns the process group ID of the foreground process
group associated with the terminal open on descriptor <VAR>filedes</VAR>.
<br><br> If there is no foreground process group, the return value is a number
greater than <CODE>1</CODE> that does not match the process group ID of any
existing process group. This can happen if all of the processes in the
job that was formerly the foreground job have terminated, and no other
job has yet been moved into the foreground.
<br><br> In case of an error, a value of <CODE>-1</CODE> is returned. The
following <CODE>errno</CODE> error conditions are defined for this function:
<br><br> <DL>
<DT><CODE>EBADF</CODE>
<DD>
The <VAR>filedes</VAR> argument is not a valid file descriptor.
<br><br> <LI> ENOSYS
The system doesn't support job control.
<br><br> <LI> ENOTTY
The terminal file associated with the <VAR>filedes</VAR> argument isn't the
controlling terminal of the calling process.
sq~wtunistd.hxq~Öt int filedestpid_tttcgetsidsq~
t”
This function is used to obtain the process group ID of the session
for which the terminal specified by <VAR>fildes</VAR> is the controlling terminal.
If the call is successful the group ID is returned. Otherwise the
return value is <CODE>(pid_t) -1</CODE> and the global variable <VAR>errno</VAR>
is set to the following value:
<DL>
<DT><CODE>EBADF</CODE>
<DD>
The <VAR>filedes</VAR> argument is not a valid file descriptor.
<br><br> <LI> ENOTTY
The calling process does not have a controlling terminal, or the file
is not the controlling terminal.
sq~wt termios.hxq~Ýt
int fildestpid_tt tcsendbreaksq~
t¸
This function generates a break condition by transmitting a stream of
zero bits on the terminal associated with the file descriptor
<VAR>filedes</VAR>. The duration of the break is controlled by the
<VAR>duration</VAR> argument. If zero, the duration is between 0.25 and 0.5
seconds. The meaning of a nonzero value depends on the operating system.
<br><br> This function does nothing if the terminal is not an asynchronous serial
data port.
<br><br> The return value is normally zero. In the event of an error, a value
of -1 is returned. The following <CODE>errno</CODE> error conditions
are defined for this function:
<br><br> <DL>
<DT><CODE>EBADF</CODE>
<DD>
The <VAR>filedes</VAR> is not a valid file descriptor.
<br><br> <LI> ENOTTY
The <VAR>filedes</VAR> is not associated with a terminal device.
sq~wt termios.hxq~ätint filedes, int durationtintt tcsetattrsq~
t œ
This function sets the attributes of the terminal device with file
descriptor <VAR>filedes</VAR>. The new attributes are taken from the
structure that <VAR>termios-p</VAR> points to.
<br><br> The <VAR>when</VAR> argument specifies how to deal with input and output
already queued. It can be one of the following values:
<br><br> <DL>
<DT><CODE>TCSANOW</CODE>
<DD>
Make the change immediately.
<br><br> <DT><CODE>TCSADRAIN</CODE>
<DD>
Make the change after waiting until all queued output has been written.
You should usually use this option when changing parameters that affect
output.
<br><br> <LI> TCSAFLUSH
This is like <CODE>TCSADRAIN</CODE>, but also discards any queued input.
<br><br> <LI> TCSASOFT
This is a flag bit that you can add to any of the above alternatives.
Its meaning is to inhibit alteration of the state of the terminal
hardware. It is a BSD extension; it is only supported on BSD systems
and the GNU system.
<br><br> Using <CODE>TCSASOFT</CODE> is exactly the same as setting the <CODE>CIGNORE</CODE>
bit in the <CODE>c_cflag</CODE> member of the structure <VAR>termios-p</VAR> points
to. , for a description of <CODE>CIGNORE</CODE>.
<br><br> If this function is called from a background process on its controlling
terminal, normally all processes in the process group are sent a
<CODE>SIGTTOU</CODE> signal, in the same way as if the process were trying to
write to the terminal. The exception is if the calling process itself
is ignoring or blocking <CODE>SIGTTOU</CODE> signals, in which case the
operation is performed and no signal is sent. .
<br><br> If successful, <CODE>tcsetattr</CODE> returns 0. A return value of
-1 indicates an error. The following <CODE>errno</CODE> error
conditions are defined for this function:
<br><br> <DL>
<LI> EBADF
The <VAR>filedes</VAR> argument is not a valid file descriptor.
<br><br> <LI> ENOTTY
The <VAR>filedes</VAR> is not associated with a terminal.
<br><br> <LI> EINVAL
Either the value of the <CODE>when</CODE> argument is not valid, or there is
something wrong with the data in the <VAR>termios-p</VAR> argument.
sq~wt termios.hxq~ët6int filedes, int when, const struct termios *termios-ptintt tcsetpgrpsq~
tA
This function is used to set a terminal's foreground process group ID.
The argument <VAR>filedes</VAR> is a descriptor which specifies the terminal;
<VAR>pgid</VAR> specifies the process group. The calling process must be a
member of the same session as <VAR>pgid</VAR> and must have the same
controlling terminal.
<br><br> For terminal access purposes, this function is treated as output. If it
is called from a background process on its controlling terminal,
normally all processes in the process group are sent a <CODE>SIGTTOU</CODE>
signal. The exception is if the calling process itself is ignoring or
blocking <CODE>SIGTTOU</CODE> signals, in which case the operation is
performed and no signal is sent.
<br><br> If successful, <CODE>tcsetpgrp</CODE> returns <CODE>0</CODE>. A return value of
<CODE>-1</CODE> indicates an error. The following <CODE>errno</CODE> error
conditions are defined for this function:
<br><br> <DL>
<DT><CODE>EBADF</CODE>
<DD>
The <VAR>filedes</VAR> argument is not a valid file descriptor.
<br><br> <LI> EINVAL
The <VAR>pgid</VAR> argument is not valid.
<br><br> <LI> ENOSYS
The system doesn't support job control.
<br><br> <LI> ENOTTY
The <VAR>filedes</VAR> isn't the controlling terminal of the calling process.
<br><br> <LI> EPERM
The <VAR>pgid</VAR> isn't a process group in the same session as the calling
process.
sq~wtunistd.hxq~òtint filedes, pid_t pgidtintttdeletesq~
ta
To remove a specific element matching <VAR>key</VAR> from the tree
<CODE>tdelete</CODE> can be used. It locates the matching element using the
same method as <CODE>tfind</CODE>. The corresponding element is then removed
and a pointer to the parent of the deleted node is returned by the
function. If there is no matching entry in the tree nothing can be
deleted and the function returns <CODE>NULL</CODE>. If the root of the tree
is deleted <CODE>tdelete</CODE> returns some unspecified value not equal to
<CODE>NULL</CODE>.
sq~wtsearch.hxq~ùt5const void *key, void **rootp, comparison_fn_t compartvoid *ttdestroysq~
t”
If the complete search tree has to be removed one can use
<CODE>tdestroy</CODE>. It frees all resources allocated by the <CODE>tsearch</CODE>
function to generate the tree pointed to by <VAR>vroot</VAR>.
<br><br> For the data in each tree node the function <VAR>freefct</VAR> is called.
The pointer to the data is passed as the argument to the function. If
no such work is necessary <VAR>freefct</VAR> must point to a function doing
nothing. It is called in any case.
<br><br> This function is a GNU extension and not covered by the System V or
X/Open specifications.
sq~wtsearch.hxq~t void *vroot, __free_fn_t freefcttvoidttempnamsq~
t‰
This function generates a unique temporary file name. If <VAR>prefix</VAR>
is not a null pointer, up to five characters of this string are used as
a prefix for the file name. The return value is a string newly
allocated with <CODE>malloc</CODE>, so you should release its storage with
<CODE>free</CODE> when it is no longer needed.
<br><br> Because the string is dynamically allocated this function is reentrant.
<br><br> The directory prefix for the temporary file name is determined by
testing each of the following in sequence. The directory must exist and
be writable.
<br><br> <OL>
<LI>
The environment variable <CODE>TMPDIR</CODE>, if it is defined. For security
reasons this only happens if the program is not SUID or SGID enabled.
<br><br> <LI>
The <VAR>dir</VAR> argument, if it is not a null pointer.
<br><br> <LI>
The value of the <CODE>P_tmpdir</CODE> macro.
<br><br> <LI>
The directory <TT>/tmp</TT>.
</OL>
<br><br> This function is defined for SVID compatibility.
<br><br> Warning: Between the time the pathname is constructed and the
file is created another process might have created a file with the same
name using <CODE>tempnam</CODE>, leading to a possible security hole. The
implementation generates names which can hardly be predicted, but when
opening the file you should use the <CODE>O_EXCL</CODE> flag. Using
<CODE>tmpfile</CODE> or <CODE>mkstemp</CODE> is a safe way to avoid this problem.
sq~wtstdio.hxq~t#const char *dir, const char *prefixtchar *t
textdomainsq~
t�
The <CODE>textdomain</CODE> function sets the default domain, which is used in
all future <CODE>gettext</CODE> calls, to <VAR>domainname</VAR>. Please note that
<CODE>dgettext</CODE> and <CODE>dcgettext</CODE> calls are not influenced if the
<VAR>domainname</VAR> parameter of these functions is not the null pointer.
<br><br> Before the first call to <CODE>textdomain</CODE> the default domain is
<CODE>messages</CODE>. This is the name specified in the specification of
the <CODE>gettext</CODE> API. This name is as good as any other name. No
program should ever really use a domain with this name since this can
only lead to problems.
<br><br> The function returns the value which is from now on taken as the default
domain. If the system went out of memory the returned value is
<CODE>NULL</CODE> and the global variable <VAR>errno</VAR> is set to <CODE>ENOMEM</CODE>.
Despite the return value type being <CODE>char *</CODE> the return string must
not be changed. It is allocated internally by the <CODE>textdomain</CODE>
function.
<br><br> If the <VAR>domainname</VAR> parameter is the null pointer no new default
domain is set. Instead the currently selected default domain is
returned.
<br><br> If the <VAR>domainname</VAR> parameter is the empty string the default domain
is reset to its initial value, the domain with the name <CODE>messages</CODE>.
This possibility is questionable to use since the domain <CODE>messages</CODE>
really never should be used.
sq~wt libintl.hxq~tconst char *domainnametchar *ttfindsq~
t¯
The <CODE>tfind</CODE> function is similar to the <CODE>tsearch</CODE> function. It
locates an element matching the one pointed to by <VAR>key</VAR> and returns
a pointer to this element. But if no matching element is available no
new element is entered (note that the <VAR>rootp</VAR> parameter points to a
constant pointer). Instead the function returns <CODE>NULL</CODE>.
sq~wtsearch.hxq~t;const void *key, void *const *rootp, comparison_fn_t compartvoid *ttgammasq~
t'
<CODE>tgamma</CODE> applies the gamma function to <VAR>x</VAR>. The gamma
function is defined as
<pre><br>
gamma (x) = integral from 0 to infinity{} of t^(x-1) e^-t dt<br>
</pre>
<br><br> This function was introduced in ISO C99.
sq~wtmath.hxq~tdouble xtdoublettgammafsq~
t'
<CODE>tgamma</CODE> applies the gamma function to <VAR>x</VAR>. The gamma
function is defined as
<pre><br>
gamma (x) = integral from 0 to infinity{} of t^(x-1) e^-t dt<br>
</pre>
<br><br> This function was introduced in ISO C99.
sq~wtmath.hxq~#tfloat xtfloatttgammalsq~
t'
<CODE>tgamma</CODE> applies the gamma function to <VAR>x</VAR>. The gamma
function is defined as
<pre><br>
gamma (x) = integral from 0 to infinity{} of t^(x-1) e^-t dt<br>
</pre>
<br><br> This function was introduced in ISO C99.
sq~wtmath.hxq~*t
long double xt long doublettimesq~
t„
The <CODE>time</CODE> function returns the current calendar time as a value of
type <CODE>time_t</CODE>. If the argument <VAR>result</VAR> is not a null pointer,
the calendar time value is also stored in <CODE>*<VAR>result</VAR></CODE>. If the
current calendar time is not available, the value
<CODE>(time_t)(-1)</CODE> is returned.
sq~wttime.hxq~1ttime_t *resultttime_tttimegmsq~
tº
<br><br> <CODE>timegm</CODE> is functionally identical to <CODE>mktime</CODE> except it
always takes the input values to be Coordinated Universal Time (UTC)
regardless of any local time zone setting.
<br><br> Note that <CODE>timegm</CODE> is the inverse of <CODE>gmtime</CODE>.
<br><br> Portability note: <CODE>mktime</CODE> is essentially universally
available. <CODE>timegm</CODE> is rather rare. For the most portable
conversion from a UTC broken-down time to a simple time, set
the <CODE>TZ</CODE> environment variable to UTC, call <CODE>mktime</CODE>, then set
<CODE>TZ</CODE> back.
<br><br>
sq~wttime.hxq~8tstruct tm *brokentimettime_tt timelocalsq~
ty
<br><br> <CODE>timelocal</CODE> is functionally identical to <CODE>mktime</CODE>, but more
mnemonically named. Note that it is the inverse of the <CODE>localtime</CODE>
function.
<br><br> Portability note: <CODE>mktime</CODE> is essentially universally
available. <CODE>timelocal</CODE> is rather rare.
<br><br>
sq~wttime.hxq~?tstruct tm *brokentimettime_tttimessq~
tc
The <CODE>times</CODE> function stores the processor time information for
the calling process in <VAR>buffer</VAR>.
<br><br> The return value is the calling process' CPU time (the same value you
get from <CODE>clock()</CODE>. <CODE>times</CODE> returns <CODE>(clock_t)(-1)</CODE> to
indicate failure.
sq~wt sys/times.hxq~Ftstruct tms *buffertclock_tttmpfilesq~
t�
This function creates a temporary binary file for update mode, as if by
calling <CODE>fopen</CODE> with mode <CODE>"wb+"</CODE>. The file is deleted
automatically when it is closed or when the program terminates. (On
some other ISO C systems the file may fail to be deleted if the program
terminates abnormally).
<br><br> This function is reentrant.
<br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> on a
32-bit system this function is in fact <CODE>tmpfile64</CODE>, i.e., the LFS
interface transparently replaces the old interface.
sq~wtstdio.hxq~MtvoidtFILE *t tmpfile64sq~
t‰
This function is similar to <CODE>tmpfile</CODE>, but the stream it returns a
pointer to was opened using <CODE>tmpfile64</CODE>. Therefore this stream can
be used for files larger then 2^31 bytes on 32-bit machines.
<br><br> Please note that the return type is still <CODE>FILE *</CODE>. There is no
special <CODE>FILE</CODE> type for the LFS interface.
<br><br> If the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> on a 32
bits machine this function is available under the name <CODE>tmpfile</CODE>
and so transparently replaces the old interface.
sq~wtstdio.hxq~TtvoidtFILE *ttmpnamsq~
t^
This function constructs and returns a valid file name that does not
refer to any existing file. If the <VAR>result</VAR> argument is a null
pointer, the return value is a pointer to an internal static string,
which might be modified by subsequent calls and therefore makes this
function non-reentrant. Otherwise, the <VAR>result</VAR> argument should be
a pointer to an array of at least <CODE>L_tmpnam</CODE> characters, and the
result is written into that array.
<br><br> It is possible for <CODE>tmpnam</CODE> to fail if you call it too many times
without removing previously-created files. This is because the limited
length of the temporary file names gives room for only a finite number
of different names. If <CODE>tmpnam</CODE> fails it returns a null pointer.
<br><br> Warning: Between the time the pathname is constructed and the
file is created another process might have created a file with the same
name using <CODE>tmpnam</CODE>, leading to a possible security hole. The
implementation generates names which can hardly be predicted, but when
opening the file you should use the <CODE>O_EXCL</CODE> flag. Using
<CODE>tmpfile</CODE> or <CODE>mkstemp</CODE> is a safe way to avoid this problem.
sq~wtstdio.hxq~[t char *resulttchar *ttmpnam_rsq~
t¦
This function is nearly identical to the <CODE>tmpnam</CODE> function, except
that if <VAR>result</VAR> is a null pointer it returns a null pointer.
<br><br> This guarantees reentrancy because the non-reentrant situation of
<CODE>tmpnam</CODE> cannot happen here.
<br><br> <h3>Warning</h3>: This function has the same security problems as
<CODE>tmpnam</CODE>.
sq~wtstdio.hxq~bt char *resulttchar *ttoasciisq~
t
This function converts <VAR>c</VAR> to a 7-bit <CODE>unsigned char</CODE> value
that fits into the US/UK ASCII character set, by clearing the high-order
bits. This function is a BSD extension and is also an SVID extension.
sq~wtctype.hxq~itint ctintttolowersq~
tà
If <VAR>c</VAR> is an upper-case letter, <CODE>tolower</CODE> returns the corresponding
lower-case letter. If <VAR>c</VAR> is not an upper-case letter,
<VAR>c</VAR> is returned unchanged.
sq~wtctype.hxq~ptint ctintttouppersq~
t³
If <VAR>c</VAR> is a lower-case letter, <CODE>toupper</CODE> returns the corresponding
upper-case letter. Otherwise <VAR>c</VAR> is returned unchanged.
sq~wtctype.hxq~wtint ctintt towctranssq~
tv
<CODE>towctrans</CODE> maps the input character <VAR>wc</VAR>
according to the rules of the mapping for which <VAR>desc</VAR> is a
descriptor, and returns the value it finds. <VAR>desc</VAR> must be
obtained by a successful call to <CODE>wctrans</CODE>.
<br><br>
This function is declared in <TT>wctype.h</TT>.
sq~wtwctype.hxq~~twint_t wc, wctrans_t desctwint_tttowlowersq~
tÖ
If <VAR>wc</VAR> is an upper-case letter, <CODE>towlower</CODE> returns the corresponding
lower-case letter. If <VAR>wc</VAR> is not an upper-case letter,
<VAR>wc</VAR> is returned unchanged.
<br><br>
<CODE>towlower</CODE> can be implemented using
<br><br> <pre><br>
towctrans (wc, wctrans ("tolower"))<br>
</pre>
<br><br>
This function is declared in <TT>wctype.h</TT>.
sq~wtwctype.hxq~…t wint_t wctwint_tttowuppersq~
t¨
If <VAR>wc</VAR> is a lower-case letter, <CODE>towupper</CODE> returns the corresponding
upper-case letter. Otherwise <VAR>wc</VAR> is returned unchanged.
<br><br>
<CODE>towupper</CODE> can be implemented using
<br><br> <pre><br>
towctrans (wc, wctrans ("toupper"))<br>
</pre>
<br><br>
This function is declared in <TT>wctype.h</TT>.
sq~wtwctype.hxq~Œt wint_t wctwint_tttruncsq~
t
The <CODE>trunc</CODE> functions round <VAR>x</VAR> towards zero to the nearest
integer (returned in floating-point format). Thus, <CODE>trunc (1.5)</CODE>
is <CODE>1.0</CODE> and <CODE>trunc (-1.5)</CODE> is <CODE>-1.0</CODE>.
sq~wtmath.hxq~“tdouble xtdoublettruncatesq~
tê
<br><br> The <CODE>truncate</CODE> function changes the size of <VAR>filename</VAR> to
<VAR>length</VAR>. If <VAR>length</VAR> is shorter than the previous length, data
at the end will be lost. The file must be writable by the user to
perform this operation.
<br><br> If <VAR>length</VAR> is longer, holes will be added to the end. However, some
systems do not support this feature and will leave the file unchanged.
<br><br> When the source file is compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> the
<CODE>truncate</CODE> function is in fact <CODE>truncate64</CODE> and the type
<CODE>off_t</CODE> has 64 bits which makes it possible to handle files up to
2^63 bytes in length.
<br><br> The return value is 0 for success, or -1 for an error. In
addition to the usual file name errors, the following errors may occur:
<br><br> <DL>
<br><br> <DT><CODE>EACCES</CODE>
<DD>
The file is a directory or not writable.
<br><br> <LI> EINVAL
<VAR>length</VAR> is negative.
<br><br> <LI> EFBIG
The operation would extend the file beyond the limits of the operating system.
<br><br> <LI> EIO
A hardware I/O error occurred.
<br><br> <LI> EPERM
The file is "append-only" or "immutable".
<br><br> <LI> EINTR
The operation was interrupted by a signal.
<br><br>
<br><br>
sq~wtunistd.hxq~št"const char *filename, off_t lengthtintt
truncate64sq~
t
This function is similar to the <CODE>truncate</CODE> function. The
difference is that the <VAR>length</VAR> argument is 64 bits wide even on 32
bits machines, which allows the handling of files with sizes up to
2^63 bytes.
<br><br> When the source file is compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> on a
32 bits machine this function is actually available under the name
<CODE>truncate</CODE> and so transparently replaces the 32 bits interface.
sq~wtunistd.hxq~¡t const char *name, off64_t lengthtintttruncfsq~
t
The <CODE>trunc</CODE> functions round <VAR>x</VAR> towards zero to the nearest
integer (returned in floating-point format). Thus, <CODE>trunc (1.5)</CODE>
is <CODE>1.0</CODE> and <CODE>trunc (-1.5)</CODE> is <CODE>-1.0</CODE>.
sq~wtmath.hxq~¨tfloat xtfloatttrunclsq~
t
The <CODE>trunc</CODE> functions round <VAR>x</VAR> towards zero to the nearest
integer (returned in floating-point format). Thus, <CODE>trunc (1.5)</CODE>
is <CODE>1.0</CODE> and <CODE>trunc (-1.5)</CODE> is <CODE>-1.0</CODE>.
sq~wtmath.hxq~¯t
long double xt long doublettsearchsq~
tE
The <CODE>tsearch</CODE> function searches in the tree pointed to by
<CODE>*<VAR>rootp</VAR></CODE> for an element matching <VAR>key</VAR>. The function
pointed to by <VAR>compar</VAR> is used to determine whether two elements
match. , for a specification of the functions
which can be used for the <VAR>compar</VAR> parameter.
<br><br> If the tree does not contain a matching entry the <VAR>key</VAR> value will
be added to the tree. <CODE>tsearch</CODE> does not make a copy of the object
pointed to by <VAR>key</VAR> (how could it since the size is unknown).
Instead it adds a reference to this object which means the object must
be available as long as the tree data structure is used.
<br><br> The tree is represented by a pointer to a pointer since it is sometimes
necessary to change the root node of the tree. So it must not be
assumed that the variable pointed to by <VAR>rootp</VAR> has the same value
after the call. This also shows that it is not safe to call the
<CODE>tsearch</CODE> function more than once at the same time using the same
tree. It is no problem to run it more than once at a time on different
trees.
<br><br> The return value is a pointer to the matching element in the tree. If a
new element was created the pointer points to the new data (which is in
fact <VAR>key</VAR>). If an entry had to be created and the program ran out
of space <CODE>NULL</CODE> is returned.
sq~wtsearch.hxq~¶t5const void *key, void **rootp, comparison_fn_t compartvoid *tttynamesq~
t—
If the file descriptor <VAR>filedes</VAR> is associated with a terminal
device, the <CODE>ttyname</CODE> function returns a pointer to a
statically-allocated, null-terminated string containing the file name of
the terminal file. The value is a null pointer if the file descriptor
isn't associated with a terminal, or the file name cannot be determined.
sq~wtunistd.hxq~½t int filedestchar *t ttyname_rsq~
tF
The <CODE>ttyname_r</CODE> function is similar to the <CODE>ttyname</CODE> function
except that it places its result into the user-specified buffer starting
at <VAR>buf</VAR> with length <VAR>len</VAR>.
<br><br> The normal return value from <CODE>ttyname_r</CODE> is 0. Otherwise an
error number is returned to indicate the error. The following
<CODE>errno</CODE> error conditions are defined for this function:
<br><br> <DL>
<DT><CODE>EBADF</CODE>
<DD>
The <VAR>filedes</VAR> argument is not a valid file descriptor.
<br><br> <LI> ENOTTY
The <VAR>filedes</VAR> is not associated with a terminal.
<br><br> <LI> ERANGE
The buffer length <VAR>len</VAR> is too small to store the string to be
returned.
sq~wtunistd.hxq~Ät"int filedes, char *buf, size_t lentintttwalksq~
td
For each node in the tree with a node pointed to by <VAR>root</VAR>, the
<CODE>twalk</CODE> function calls the function provided by the parameter
<VAR>action</VAR>. For leaf nodes the function is called exactly once with
<VAR>value</VAR> set to <CODE>leaf</CODE>. For internal nodes the function is
called three times, setting the <VAR>value</VAR> parameter or <VAR>action</VAR> to
the appropriate value. The <VAR>level</VAR> argument for the <VAR>action</VAR>
function is computed while descending the tree with increasing the value
by one for the descend to a child, starting with the value 0 for
the root node.
<br><br> Since the functions used for the <VAR>action</VAR> parameter to <CODE>twalk</CODE>
must not modify the tree data, it is safe to run <CODE>twalk</CODE> in more
than one thread at the same time, working on the same tree. It is also
safe to call <CODE>tfind</CODE> in parallel. Functions which modify the tree
must not be used, otherwise the behavior is undefined.
sq~wtsearch.hxq~Ët&const void *root, __action_fn_t actiontvoidttzsetsq~
tu
The <CODE>tzset</CODE> function initializes the <CODE>tzname</CODE> variable from
the value of the <CODE>TZ</CODE> environment variable. It is not usually
necessary for your program to call this function, because it is called
automatically when you use the other time conversion functions that
depend on the time zone.
sq~wttime.hxq~Òtvoidtvoidtulimitsq~
t$
<br><br> <CODE>ulimit</CODE> gets the current limit or sets the current and maximum
limit for a particular resource for the calling process according to the
command <VAR>cmd</VAR>.a
<br><br> If you are getting a limit, the command argument is the only argument.
If you are setting a limit, there is a second argument:
<CODE>long int</CODE> <VAR>limit</VAR> which is the value to which you are setting
the limit.
<br><br> The <VAR>cmd</VAR> values and the operations they specify are:
<DL>
<br><br> <DT><CODE>GETFSIZE</CODE>
<DD>
Get the current limit on the size of a file, in units of 512 bytes.
<br><br> <DT><CODE>SETFSIZE</CODE>
<DD>
Set the current and maximum limit on the size of a file to <VAR>limit</VAR> *
512 bytes.
<br><br>
<br><br> There are also some other <VAR>cmd</VAR> values that may do things on some
systems, but they are not supported.
<br><br> Only the superuser may increase a maximum limit.
<br><br> When you successfully get a limit, the return value of <CODE>ulimit</CODE> is
that limit, which is never negative. When you successfully set a limit,
the return value is zero. When the function fails, the return value is
<CODE>-1</CODE> and <CODE>errno</CODE> is set according to the reason:
<br><br> <DL>
<LI> EPERM
A process tried to increase a maximum limit, but is not superuser.
<br><br> <br><br>
sq~wtsys/resource.htulimit.hxq~Ùt int cmd, ...tinttumasksq~
t÷
The <CODE>umask</CODE> function sets the file creation mask of the current
process to <VAR>mask</VAR>, and returns the previous value of the file
creation mask.
<br><br> Here is an example showing how to read the mask with <CODE>umask</CODE>
without changing it permanently:
<br><br> <pre><br>
mode_t<br>
read_umask (void)<br>
{<br>
mode_t mask = umask (0);<br>
umask (mask);<br>
return mask;<br>
}<br>
</pre>
<br><br>
However, it is better to use <CODE>getumask</CODE> if you just want to read
the mask value, because it is reentrant (at least if you use the GNU
operating system).
sq~wt
sys/stat.hxq~át mode_t masktmode_ttumountsq~
tR
<br><br> <CODE>umount</CODE> does the same thing as <CODE>umount2</CODE> with <VAR>flags</VAR> set
to zeroes. It is more widely available than <CODE>umount2</CODE> but since it
lacks the possibility to forcefully unmount a filesystem is deprecated
when <CODE>umount2</CODE> is also available.
sq~wt sys/mount.hxq~ètconst char *filetinttumount2sq~
tê
<br><br> <CODE>umount2</CODE> unmounts a filesystem.
<br><br> You can identify the filesystem to unmount either by the device special
file that contains the filesystem or by the mount point. The effect is
the same. Specify either as the string <VAR>file</VAR>.
<br><br> <VAR>flags</VAR> contains the one-bit field identified by the following
mask macro:
<br><br> <DL>
<br><br> <DT><CODE>MNT_FORCE</CODE>
<DD>
This bit on means to force the unmounting even if the filesystem is
busy, by making it unbusy first. If the bit is off and the filesystem is
busy, <CODE>umount2</CODE> fails with <CODE>errno</CODE> = <CODE>EBUSY</CODE>. Depending
on the filesystem, this may override all, some, or no busy conditions.
<br><br>
<br><br> All other bits in <VAR>flags</VAR> should be set to zero; otherwise, the result
is undefined.
<br><br> Example:
<br><br> <pre><br>
<br>
#include <sys/mount.h><br>
<br><br> umount2("/mnt", MNT_FORCE);<br>
<br><br> umount2("/dev/hdd1", 0);<br>
<br><br> <br>
</pre>
<br><br> After the filesystem is unmounted, the directory that was the mount point
is visible, as are any files in it.
<br><br> As part of unmounting, <CODE>umount2</CODE> syncs the filesystem.
<br><br> If the unmounting is successful, the return value is zero. Otherwise, it
is <CODE>-1</CODE> and <CODE>errno</CODE> is set accordingly:
<br><br> <DL>
<LI> EPERM
The process is not superuser.
<LI> EBUSY
The filesystem cannot be unmounted because it is busy. E.g. it contains
a directory that is some process's working directory or a file that some
process has open. With some filesystems in some cases, you can avoid
this failure with the <CODE>MNT_FORCE</CODE> option.
<br><br> <LI> EINVAL
<VAR>file</VAR> validly refers to a file, but that file is neither a mount
point nor a device special file of a currently mounted filesystem.
<br><br>
</DL>
<br><br> This function is not available on all systems.
sq~wt sys/mount.hxq~ïtconst char *file, int flagstinttunamesq~
tÁ
The <CODE>uname</CODE> function fills in the structure pointed to by
<VAR>info</VAR> with information about the operating system and host machine.
A non-negative value indicates that the data was successfully stored.
<br><br> <CODE>-1</CODE> as the value indicates an error. The only error possible is
<CODE>EFAULT</CODE>, which we normally don't mention as it is always a
possibility.
sq~wt
sys/utsname.hxq~ötstruct utsname *infotinttungetcsq~
t
The <CODE>ungetc</CODE> function pushes back the character <VAR>c</VAR> onto the
input stream <VAR>stream</VAR>. So the next input from <VAR>stream</VAR> will
read <VAR>c</VAR> before anything else.
<br><br> If <VAR>c</VAR> is <CODE>EOF</CODE>, <CODE>ungetc</CODE> does nothing and just returns
<CODE>EOF</CODE>. This lets you call <CODE>ungetc</CODE> with the return value of
<CODE>getc</CODE> without needing to check for an error from <CODE>getc</CODE>.
<br><br> The character that you push back doesn't have to be the same as the last
character that was actually read from the stream. In fact, it isn't
necessary to actually read any characters from the stream before
unreading them with <CODE>ungetc</CODE>! But that is a strange way to write a
program; usually <CODE>ungetc</CODE> is used only to unread a character that
was just read from the same stream. The GNU C library supports this
even on files opened in binary mode, but other systems might not.
<br><br> The GNU C library only supports one character of pushback---in other
words, it does not work to call <CODE>ungetc</CODE> twice without doing input
in between. Other systems might let you push back multiple characters;
then reading from the stream retrieves the characters in the reverse
order that they were pushed.
<br><br> Pushing back characters doesn't alter the file; only the internal
buffering for the stream is affected. If a file positioning function
(such as <CODE>fseek</CODE>, <CODE>fseeko</CODE> or <CODE>rewind</CODE>; ) is called, any pending pushed-back characters are
discarded.
<br><br> Unreading a character on a stream that is at end of file clears the
end-of-file indicator for the stream, because it makes the character of
input available. After you read that character, trying to read again
will encounter end of file.
sq~wtstdio.hxq~ýtint c, FILE *streamtinttungetwcsq~
t�
The <CODE>ungetwc</CODE> function behaves just like <CODE>ungetc</CODE> just that it
pushes back a wide character.
sq~wtwchar.hxq~twint_t wc, FILE *streamtwint_ttunlinksq~
t
The <CODE>unlink</CODE> function deletes the file name <VAR>filename</VAR>. If
this is a file's sole name, the file itself is also deleted. (Actually,
if any process has the file open when this happens, deletion is
postponed until all processes have closed the file.)
<br><br> The function <CODE>unlink</CODE> is declared in the header file <TT>unistd.h</TT>.
<br><br> This function returns <CODE>0</CODE> on successful completion, and <CODE>-1</CODE>
on error. In addition to the usual file name errors
, the following <CODE>errno</CODE> error conditions are
defined for this function:
<br><br> <DL>
<DT><CODE>EACCES</CODE>
<DD>
Write permission is denied for the directory from which the file is to be
removed, or the directory has the sticky bit set and you do not own the file.
<br><br> <LI> EBUSY
This error indicates that the file is being used by the system in such a
way that it can't be unlinked. For example, you might see this error if
the file name specifies the root directory or a mount point for a file
system.
<br><br> <LI> ENOENT
The file name to be deleted doesn't exist.
<br><br> <LI> EPERM
On some systems <CODE>unlink</CODE> cannot be used to delete the name of a
directory, or at least can only be used this way by a privileged user.
To avoid such problems, use <CODE>rmdir</CODE> to delete directories. (In the
GNU system <CODE>unlink</CODE> can never delete the name of a directory.)
<br><br> <LI> EROFS
The directory containing the file name to be deleted is on a read-only
file system and can't be modified.
sq~wtunistd.hxq~ tconst char *filenametinttunlockptsq~
t{
The <CODE>unlockpt</CODE> function unlocks the slave pseudo-terminal device
corresponding to the master pseudo-terminal device associated with the
file descriptor <VAR>filedes</VAR>. On many systems, the slave can only be
opened after unlocking, so portable applications should always call
<CODE>unlockpt</CODE> before trying to open the slave.
<br><br> The normal return value from <CODE>unlockpt</CODE> is 0; a value of
-1 is returned in case of failure. The following <CODE>errno</CODE>
error conditions are defined for this function:
<br><br> <DL>
<DT><CODE>EBADF</CODE>
<DD>
The <VAR>filedes</VAR> argument is not a valid file descriptor.
<br><br> <LI> EINVAL
The <VAR>filedes</VAR> argument is not associated with a master pseudo-terminal
device.
sq~wtstdlib.hxq~t int filedestinttunsetenvsq~
tü
Using this function one can remove an entry completely from the
environment. If the environment contains an entry with the key
<VAR>name</VAR> this whole entry is removed. A call to this function is
equivalent to a call to <CODE>putenv</CODE> when the <VAR>value</VAR> part of the
string is empty.
<br><br> The function return <CODE>-1</CODE> if <VAR>name</VAR> is a null pointer, points to
an empty string, or points to a string containing a <CODE>=</CODE> character.
It returns <CODE>0</CODE> if the call succeeded.
<br><br> This function was originally part of the BSD library but is now part of
the Unix standard. The BSD version had no return value, though.
sq~wtstdlib.hxq~tconst char *nametinttupdwtmpsq~
tþ
The <CODE>updwtmp</CODE> function appends the entry *<VAR>utmp</VAR> to the
database specified by <VAR>wtmp_file</VAR>. For possible values for the
<VAR>wtmp_file</VAR> argument see the <CODE>utmpname</CODE> function.
sq~wtutmp.hxq~ t.const char *wtmp_file, const struct utmp *utmptvoidtutimesq~
tW
This function is used to modify the file times associated with the file
named <VAR>filename</VAR>.
<br><br> If <VAR>times</VAR> is a null pointer, then the access and modification times
of the file are set to the current time. Otherwise, they are set to the
values from the <CODE>actime</CODE> and <CODE>modtime</CODE> members (respectively)
of the <CODE>utimbuf</CODE> structure pointed to by <VAR>times</VAR>.
<br><br> The attribute modification time for the file is set to the current time
in either case (since changing the time stamps is itself a modification
of the file attributes).
<br><br> The <CODE>utime</CODE> function returns <CODE>0</CODE> if successful and <CODE>-1</CODE>
on failure. In addition to the usual file name errors
, the following <CODE>errno</CODE> error conditions
are defined for this function:
<br><br> <DL>
<DT><CODE>EACCES</CODE>
<DD>
There is a permission problem in the case where a null pointer was
passed as the <VAR>times</VAR> argument. In order to update the time stamp on
the file, you must either be the owner of the file, have write
permission for the file, or be a privileged user.
<br><br> <LI> ENOENT
The file doesn't exist.
<br><br> <LI> EPERM
If the <VAR>times</VAR> argument is not a null pointer, you must either be
the owner of the file or be a privileged user.
<br><br> <LI> EROFS
The file lives on a read-only file system.
sq~wtunistd.httime.hxq~'t1const char *filename, const struct utimbuf *timestinttutimessq~
tN
This function sets the file access and modification times of the file
<VAR>filename</VAR>. The new file access time is specified by
<CODE><VAR>tvp</VAR>[0]</CODE>, and the new modification time by
<CODE><VAR>tvp</VAR>[1]</CODE>. Similar to <CODE>utime</CODE>, if <VAR>tvp</VAR> is a null
pointer then the access and modification times of the file are set to
the current time. This function comes from BSD.
<br><br> The return values and error conditions are the same as for the <CODE>utime</CODE>
function.
sq~wt
sys/time.hxq~/t+const char *filename, struct timeval tvp[2]tinttutmpnamesq~
t+
The <CODE>utmpname</CODE> function changes the name of the database to be
examined to <VAR>file</VAR>, and closes any previously opened database. By
default <CODE>getutent</CODE>, <CODE>getutid</CODE>, <CODE>getutline</CODE> and
<CODE>pututline</CODE> read from and write to the user accounting database.
<br><br> The following macros are defined for use as the <VAR>file</VAR> argument:
<br><br> Macro {char *} _PATH_UTMP
This macro is used to specify the user accounting database.
<br><br> Macro {char *} _PATH_WTMP
This macro is used to specify the user accounting log file.
<br><br> The <CODE>utmpname</CODE> function returns a value of <CODE>0</CODE> if the new name
was successfully stored, and a value of <CODE>-1</CODE> to indicate an error.
Note that <CODE>utmpname</CODE> does not try to open the database, and that
therefore the return value does not say anything about whether the
database can be successfully opened.
sq~wtutmp.hxq~6tconst char *filetintt utmpxnamesq~
tÔ
The <CODE>utmpxname</CODE> function is functionally identical to
<CODE>utmpname</CODE>. On the GNU system, <CODE>utmpxname</CODE> is simply an
alias for <CODE>utmpname</CODE>.
sq~wtutmpx.hxq~=tconst char *filetinttvallocsq~
tÐ
Using <CODE>valloc</CODE> is like using <CODE>memalign</CODE> and passing the page size
as the value of the second argument. It is implemented like this:
<br><br> <pre><br>
void *<br>
valloc (size_t size)<br>
{<br>
return memalign (getpagesize (), size);<br>
}<br>
</pre>
<br><br> Query Memory Parameters for more information about the memory
subsystem.
sq~wtstdlib.hxq~Dt size_t sizetvoid *t vasprintfsq~
t¹
The <CODE>vasprintf</CODE> function is the equivalent of <CODE>asprintf</CODE> with the
variable argument list specified directly as for <CODE>vprintf</CODE>.
sq~wtstdio.hxq~Kt,char **ptr, const char *template, va_list aptinttverrsq~
të
The <CODE>verr</CODE> function is just like <CODE>err</CODE> except that the
parameters for the handling of the format string <VAR>format</VAR> are passed
in as an value of type <CODE>va_list</CODE>.
sq~wterr.hxq~Rt'int status, const char *format, va_listtvoidtverrxsq~
tí
The <CODE>verrx</CODE> function is just like <CODE>errx</CODE> except that the
parameters for the handling of the format string <VAR>format</VAR> are passed
in as an value of type <CODE>va_list</CODE>.
sq~wterr.hxq~Yt'int status, const char *format, va_listtvoidt versionsortsq~
t¤
The <CODE>versionsort</CODE> function is like <CODE>alphasort</CODE> except that it
uses the <CODE>strverscmp</CODE> function internally.
sq~wtdirent.hxq~`tconst void *a, const void *btintt
versionsort64sq~
t«
The <CODE>versionsort64</CODE> function is like <CODE>alphasort64</CODE>, excepted that it
uses the <CODE>strverscmp</CODE> function internally.
sq~wtdirent.hxq~gtconst void *a, const void *btinttvforksq~
t)
The <CODE>vfork</CODE> function is similar to <CODE>fork</CODE> but on some systems
it is more efficient; however, there are restrictions you must follow to
use it safely.
<br><br> While <CODE>fork</CODE> makes a complete copy of the calling process's address
space and allows both the parent and child to execute independently,
<CODE>vfork</CODE> does not make this copy. Instead, the child process
created with <CODE>vfork</CODE> shares its parent's address space until it
calls <CODE>_exit</CODE> or one of the <CODE>exec</CODE> functions. In the
meantime, the parent process suspends execution.
<br><br> You must be very careful not to allow the child process created with
<CODE>vfork</CODE> to modify any global data or even local variables shared
with the parent. Furthermore, the child process cannot return from (or
do a long jump out of) the function that called <CODE>vfork</CODE>! This
would leave the parent process's control information very confused. If
in doubt, use <CODE>fork</CODE> instead.
<br><br> Some operating systems don't really implement <CODE>vfork</CODE>. The GNU C
library permits you to use <CODE>vfork</CODE> on all systems, but actually
executes <CODE>fork</CODE> if <CODE>vfork</CODE> isn't available. If you follow
the proper precautions for using <CODE>vfork</CODE>, your program will still
work even if the system uses <CODE>fork</CODE> instead.
sq~wtunistd.hxq~ntvoidtpid_ttvfprintfsq~
t™
This is the equivalent of <CODE>fprintf</CODE> with the variable argument list
specified directly as for <CODE>vprintf</CODE>.
sq~wtstdio.hxq~ut.FILE *stream, const char *template, va_list aptinttvfscanfsq~
t—
This is the equivalent of <CODE>fscanf</CODE> with the variable argument list
specified directly as for <CODE>vscanf</CODE>.
sq~wtstdio.hxq~|t.FILE *stream, const char *template, va_list aptintt vfwprintfsq~
t›
This is the equivalent of <CODE>fwprintf</CODE> with the variable argument list
specified directly as for <CODE>vwprintf</CODE>.
sq~wtwchar.hxq~ƒt1FILE *stream, const wchar_t *template, va_list aptinttvfwscanfsq~
t™
This is the equivalent of <CODE>fwscanf</CODE> with the variable argument list
specified directly as for <CODE>vwscanf</CODE>.
sq~wtwchar.hxq~Št1FILE *stream, const wchar_t *template, va_list aptinttvlimitsq~
t©
<br><br> <CODE>vlimit</CODE> sets the current limit for a resource for a process.
<br><br> <VAR>resource</VAR> identifies the resource:
<br><br> <DL>
<DT><CODE>LIM_CPU</CODE>
<DD>
Maximum CPU time. Same as <CODE>RLIMIT_CPU</CODE> for <CODE>setrlimit</CODE>.
<DT><CODE>LIM_FSIZE</CODE>
<DD>
Maximum file size. Same as <CODE>RLIMIT_FSIZE</CODE> for <CODE>setrlimit</CODE>.
<LI> LIM_DATA
Maximum data memory. Same as <CODE>RLIMIT_DATA</CODE> for <CODE>setrlimit</CODE>.
<LI> LIM_STACK
Maximum stack size. Same as <CODE>RLIMIT_STACK</CODE> for <CODE>setrlimit</CODE>.
<LI> LIM_CORE
Maximum core file size. Same as <CODE>RLIMIT_COR</CODE> for <CODE>setrlimit</CODE>.
<LI> LIM_MAXRSS
Maximum physical memory. Same as <CODE>RLIMIT_RSS</CODE> for <CODE>setrlimit</CODE>.
<br><br> The return value is zero for success, and <CODE>-1</CODE> with <CODE>errno</CODE> set
accordingly for failure:
<br><br> <DL>
<LI> EPERM
The process tried to set its current limit beyond its maximum limit.
<br><br>
sq~wt sys/vlimit.hxq~‘tint resource, int limittinttvprintfsq~
tÌ
This function is similar to <CODE>printf</CODE> except that, instead of taking
a variable number of arguments directly, it takes an argument list
pointer <VAR>ap</VAR>.
sq~wtstdio.hxq~˜t const char *template, va_list aptinttvscanfsq~
tá
This function is similar to <CODE>scanf</CODE>, but instead of taking
a variable number of arguments directly, it takes an argument list
pointer <VAR>ap</VAR> of type <CODE>va_list</CODE> .
sq~wtstdio.hxq~Ÿt const char *template, va_list aptintt vsnprintfsq~
tš
This is the equivalent of <CODE>snprintf</CODE> with the variable argument list
specified directly as for <CODE>vprintf</CODE>.
sq~wtstdio.hxq~¦t6char *s, size_t size, const char *template, va_list aptinttvsprintfsq~
t™
This is the equivalent of <CODE>sprintf</CODE> with the variable argument list
specified directly as for <CODE>vprintf</CODE>.
sq~wtstdio.hxq~­t)char *s, const char *template, va_list aptinttvsscanfsq~
t—
This is the equivalent of <CODE>sscanf</CODE> with the variable argument list
specified directly as for <CODE>vscanf</CODE>.
sq~wtstdio.hxq~´t/const char *s, const char *template, va_list aptintt vswprintfsq~
t›
This is the equivalent of <CODE>swprintf</CODE> with the variable argument list
specified directly as for <CODE>vwprintf</CODE>.
sq~wtwchar.hxq~»t<wchar_t *s, size_t size, const wchar_t *template, va_list aptinttvswscanfsq~
t™
This is the equivalent of <CODE>swscanf</CODE> with the variable argument list
specified directly as for <CODE>vwscanf</CODE>.
sq~wtwchar.hxq~Ât5const wchar_t *s, const wchar_t *template, va_list aptinttvsyslogsq~
t™
<br><br> This is functionally identical to <CODE>syslog</CODE>, with the BSD style variable
length argument.
<br><br>
sq~wtsyslog.hxq~Ét4int facility_priority, char *format, va_list arglisttvoidtvtimessq~
tr
<br><br> <CODE>vtimes</CODE> reports resource usage totals for a process.
<br><br> If <VAR>current</VAR> is non-null, <CODE>vtimes</CODE> stores resource usage totals for
the invoking process alone in the structure to which it points. If
<VAR>child</VAR> is non-null, <CODE>vtimes</CODE> stores resource usage totals for all
past children (which have terminated) of the invoking process in the structure
to which it points.
<br><br> <h4>Data Type - struct vtimes</h4>
This data type contains information about the resource usage of a process.
Each member corresponds to a member of the <CODE>struct rusage</CODE> data type
described above.
<br><br> <DL>
<DT><CODE>vm_utime</CODE>
<DD>
User CPU time. Analogous to <CODE>ru_utime</CODE> in <CODE>struct rusage</CODE>
<LI> vm_stime
System CPU time. Analogous to <CODE>ru_stime</CODE> in <CODE>struct rusage</CODE>
<LI> vm_idsrss
Data and stack memory. The sum of the values that would be reported as
<CODE>ru_idrss</CODE> and <CODE>ru_isrss</CODE> in <CODE>struct rusage</CODE>
<LI> vm_ixrss
Shared memory. Analogous to <CODE>ru_ixrss</CODE> in <CODE>struct rusage</CODE>
<LI> vm_maxrss
Maximent resident set size. Analogous to <CODE>ru_maxrss</CODE> in
<CODE>struct rusage</CODE>
<LI> vm_majflt
Major page faults. Analogous to <CODE>ru_majflt</CODE> in <CODE>struct rusage</CODE>
<LI> vm_minflt
Minor page faults. Analogous to <CODE>ru_minflt</CODE> in <CODE>struct rusage</CODE>
<LI> vm_nswap
Swap count. Analogous to <CODE>ru_nswap</CODE> in <CODE>struct rusage</CODE>
<LI> vm_inblk
Disk reads. Analogous to <CODE>ru_inblk</CODE> in <CODE>struct rusage</CODE>
<LI> vm_oublk
Disk writes. Analogous to <CODE>ru_oublk</CODE> in <CODE>struct rusage</CODE>
<br><br> <br><br> The return value is zero if the function succeeds; <CODE>-1</CODE> otherwise.
<br><br> <br><br> <br><br>
sq~wtsys/resource.htvtimes.hxq~Ðt*struct vtimes current, struct vtimes childtinttvwarnsq~
tí
The <CODE>vwarn</CODE> function is just like <CODE>warn</CODE> except that the
parameters for the handling of the format string <VAR>format</VAR> are passed
in as an value of type <CODE>va_list</CODE>.
sq~wterr.hxq~Øtconst char *format, va_listtvoidtvwarnxsq~
tï
The <CODE>vwarnx</CODE> function is just like <CODE>warnx</CODE> except that the
parameters for the handling of the format string <VAR>format</VAR> are passed
in as an value of type <CODE>va_list</CODE>.
sq~wterr.hxq~ßtconst char *format, va_listtvoidtvwprintfsq~
tÍ
This function is similar to <CODE>wprintf</CODE> except that, instead of taking
a variable number of arguments directly, it takes an argument list
pointer <VAR>ap</VAR>.
sq~wtwchar.hxq~æt#const wchar_t *template, va_list aptinttvwscanfsq~
tâ
This function is similar to <CODE>wscanf</CODE>, but instead of taking
a variable number of arguments directly, it takes an argument list
pointer <VAR>ap</VAR> of type <CODE>va_list</CODE> .
sq~wtwchar.hxq~ít#const wchar_t *template, va_list aptinttwaitsq~
t>
This is a simplified version of <CODE>waitpid</CODE>, and is used to wait
until any one child process terminates. The call:
<br><br> <pre><br>
wait (&status)<br>
</pre><br>
<br><br> <br>
is exactly equivalent to:<br>
<br><br> <pre><br>
waitpid (-1, &status, 0)<br>
</pre>
<br><br> This function is a cancellation point in multi-threaded programs. This
is a problem if the thread allocates some resources (like memory, file
descriptors, semaphores or whatever) at the time <CODE>wait</CODE> is
called. If the thread gets canceled these resources stay allocated
until the program ends. To avoid this calls to <CODE>wait</CODE> should be
protected using cancellation handlers.
sq~wt
sys/wait.hxq~ôtint *status-ptrtpid_ttwait3sq~
t“
If <VAR>usage</VAR> is a null pointer, <CODE>wait3</CODE> is equivalent to
<CODE>waitpid (-1, <VAR>status-ptr</VAR>, <VAR>options</VAR>)</CODE>.
<br><br> If <VAR>usage</VAR> is not null, <CODE>wait3</CODE> stores usage figures for the
child process in <CODE>*<VAR>rusage</VAR></CODE> (but only if the child has
terminated, not if it has stopped). .
sq~wt
sys/wait.hxq~ût9union wait *status-ptr, int options, struct rusage *usagetpid_ttwait4sq~
tÓ
If <VAR>usage</VAR> is a null pointer, <CODE>wait4</CODE> is equivalent to
<CODE>waitpid (<VAR>pid</VAR>, <VAR>status-ptr</VAR>, <VAR>options</VAR>)</CODE>.
<br><br> If <VAR>usage</VAR> is not null, <CODE>wait4</CODE> stores usage figures for the
child process in <CODE>*<VAR>rusage</VAR></CODE> (but only if the child has
terminated, not if it has stopped). .
<br><br> This function is a BSD extension.
sq~wt
sys/wait.hxq~t=pid_t pid, int *status-ptr, int options, struct rusage *usagetpid_ttwaitpidsq~
tx
The <CODE>waitpid</CODE> function is used to request status information from a
child process whose process ID is <VAR>pid</VAR>. Normally, the calling
process is suspended until the child process makes status information
available by terminating.
<br><br> Other values for the <VAR>pid</VAR> argument have special interpretations. A
value of <CODE>-1</CODE> or <CODE>WAIT_ANY</CODE> requests status information for
any child process; a value of <CODE>0</CODE> or <CODE>WAIT_MYPGRP</CODE> requests
information for any child process in the same process group as the
calling process; and any other negative value <VAR>pgid</VAR>
requests information for any child process whose process group ID is
<VAR>pgid</VAR>.
<br><br> If status information for a child process is available immediately, this
function returns immediately without waiting. If more than one eligible
child process has status information available, one of them is chosen
randomly, and its status is returned immediately. To get the status
from the other eligible child processes, you need to call <CODE>waitpid</CODE>
again.
<br><br> The <VAR>options</VAR> argument is a bit mask. Its value should be the
bitwise OR (that is, the <samp>|</samp> operator) of zero or more of the
<CODE>WNOHANG</CODE> and <CODE>WUNTRACED</CODE> flags. You can use the
<CODE>WNOHANG</CODE> flag to indicate that the parent process shouldn't wait;
and the <CODE>WUNTRACED</CODE> flag to request status information from stopped
processes as well as processes that have terminated.
<br><br> The status information from the child process is stored in the object
that <VAR>status-ptr</VAR> points to, unless <VAR>status-ptr</VAR> is a null pointer.
<br><br> This function is a cancellation point in multi-threaded programs. This
is a problem if the thread allocates some resources (like memory, file
descriptors, semaphores or whatever) at the time <CODE>waitpid</CODE> is
called. If the thread gets canceled these resources stay allocated
until the program ends. To avoid this calls to <CODE>waitpid</CODE> should be
protected using cancellation handlers.
<br><br> The return value is normally the process ID of the child process whose
status is reported. If there are child processes but none of them is
waiting to be noticed, <CODE>waitpid</CODE> will block until one is. However,
if the <CODE>WNOHANG</CODE> option was specified, <CODE>waitpid</CODE> will return
zero instead of blocking.
<br><br> If a specific PID to wait for was given to <CODE>waitpid</CODE>, it will
ignore all other children (if any). Therefore if there are children
waiting to be noticed but the child whose PID was specified is not one
of them, <CODE>waitpid</CODE> will block or return zero as described above.
<br><br> A value of <CODE>-1</CODE> is returned in case of error. The following
<CODE>errno</CODE> error conditions are defined for this function:
<br><br> <DL>
<DT><CODE>EINTR</CODE>
<DD>
The function was interrupted by delivery of a signal to the calling
process. .
<br><br> <LI> ECHILD
There are no child processes to wait for, or the specified <VAR>pid</VAR>
is not a child of the calling process.
<br><br> <LI> EINVAL
An invalid value was provided for the <VAR>options</VAR> argument.
sq~wt
sys/wait.hxq~ t'pid_t pid, int *status-ptr, int optionstpid_ttwarnsq~
t
The <CODE>warn</CODE> function is roughly equivalent to a call like
<pre><br>
error (0, errno, format, the parameters)<br>
</pre>
except that the global variables <CODE>error</CODE> respects and modifies
are not used.
sq~wterror.hterr.hxq~tconst char *format, ...tvoidtwarnxsq~
tq
The <CODE>warnx</CODE> function is roughly equivalent to a call like
<pre><br>
error (0, 0, format, the parameters)<br>
</pre>
except that the global variables <CODE>error</CODE> respects and modifies
are not used. The difference to <CODE>warn</CODE> is that no error number
string is printed.
sq~wterr.hxq~tconst char *format, ...tvoidtwcpcpysq~
tK
This function is like <CODE>wcscpy</CODE>, except that it returns a pointer to
the end of the string <VAR>wto</VAR> (that is, the address of the terminating
null character <CODE>wto + strlen (wfrom)</CODE>) rather than the beginning.
<br><br> This function is not part of ISO or POSIX but was found useful while
developing the GNU C Library itself.
<br><br> The behavior of <CODE>wcpcpy</CODE> is undefined if the strings overlap.
<br><br> <CODE>wcpcpy</CODE> is a GNU extension and is declared in <TT>wchar.h</TT>.
sq~wtwchar.hxq~t4wchar_t *restrict wto, const wchar_t *restrict wfromt wchar_t *twcpncpysq~
t6
This function is similar to <CODE>wcpcpy</CODE> but copies always exactly
<VAR>wsize</VAR> characters into <VAR>wto</VAR>.
<br><br> If the length of <VAR>wfrom</VAR> is more then <VAR>size</VAR>, then
<CODE>wcpncpy</CODE> copies just the first <VAR>size</VAR> wide characters and
returns a pointer to the wide character directly following the last
non-null wide character which was copied last. Note that in this case
there is no null terminator written into <VAR>wto</VAR>.
<br><br> If the length of <VAR>wfrom</VAR> is less than <VAR>size</VAR>, then <CODE>wcpncpy</CODE>
copies all of <VAR>wfrom</VAR>, followed by enough null characters to add up
to <VAR>size</VAR> characters in all. This behavior is rarely useful, but it
is implemented to be useful in contexts where this behavior of the
<CODE>wcsncpy</CODE> is used. <CODE>wcpncpy</CODE> returns a pointer to the
<EM>first</EM> written null character.
<br><br> This function is not part of ISO or POSIX but was found useful while
developing the GNU C Library itself.
<br><br> Its behavior is undefined if the strings overlap.
<br><br> <CODE>wcpncpy</CODE> is a GNU extension and is declared in <TT>wchar.h</TT>.
sq~wtwchar.hxq~&tAwchar_t *restrict wto, const wchar_t *restrict wfrom, size_t sizet wchar_t *twcrtombsq~
t {
The <CODE>wcrtomb</CODE> function (``wide character restartable to
multibyte'') converts a single wide character into a multibyte string
corresponding to that wide character.
<br><br> If <VAR>s</VAR> is a null pointer, the function resets the state stored in
the objects pointed to by <VAR>ps</VAR> (or the internal <CODE>mbstate_t</CODE>
object) to the initial state. This can also be achieved by a call like
this:
<br><br> <pre><br>
wcrtombs (temp_buf, L'\0', ps)<br>
</pre>
<br><br>
since, if <VAR>s</VAR> is a null pointer, <CODE>wcrtomb</CODE> performs as if it
writes into an internal buffer, which is guaranteed to be large enough.
<br><br> If <VAR>wc</VAR> is the NUL wide character, <CODE>wcrtomb</CODE> emits, if
necessary, a shift sequence to get the state <VAR>ps</VAR> into the initial
state followed by a single NUL byte, which is stored in the string
<VAR>s</VAR>.
<br><br> Otherwise a byte sequence (possibly including shift sequences) is written
into the string <VAR>s</VAR>. This only happens if <VAR>wc</VAR> is a valid wide
character (i.e., it has a multibyte representation in the character set
selected by locale of the <CODE>LC_CTYPE</CODE> category). If <VAR>wc</VAR> is no
valid wide character, nothing is stored in the strings <VAR>s</VAR>,
<CODE>errno</CODE> is set to <CODE>EILSEQ</CODE>, the conversion state in <VAR>ps</VAR>
is undefined and the return value is <CODE>(size_t) -1</CODE>.
<br><br> If no error occurred the function returns the number of bytes stored in
the string <VAR>s</VAR>. This includes all bytes representing shift
sequences.
<br><br> One word about the interface of the function: there is no parameter
specifying the length of the array <VAR>s</VAR>. Instead the function
assumes that there are at least <CODE>MB_CUR_MAX</CODE> bytes available since
this is the maximum length of any byte sequence representing a single
character. So the caller has to make sure that there is enough space
available, otherwise buffer overruns can occur.
<br><br> <CODE>wcrtomb</CODE> was introduced in Amendment 1 to ISO C90 and is
declared in <TT>wchar.h</TT>.
sq~wtwchar.hxq~-t4char *restrict s, wchar_t wc, mbstate_t *restrict pstsize_tt
wcscasecmpsq~
tÞ
This function is like <CODE>wcscmp</CODE>, except that differences in case are
ignored. How uppercase and lowercase characters are related is
determined by the currently selected locale. In the standard <CODE>"C"</CODE>
locale the characters "A and "a do not match but in a locale which
regards these characters as parts of the alphabet they do match.
<br><br>
<CODE>wcscasecmp</CODE> is a GNU extension.
sq~wtwchar.hxq~4t&const wchar_t *ws1, const wchar_T *ws2tinttwcscatsq~
tï
The <CODE>wcscat</CODE> function is similar to <CODE>wcscpy</CODE>, except that the
characters from <VAR>wfrom</VAR> are concatenated or appended to the end of
<VAR>wto</VAR>, instead of overwriting it. That is, the first character from
<VAR>wfrom</VAR> overwrites the null character marking the end of <VAR>wto</VAR>.
<br><br> An equivalent definition for <CODE>wcscat</CODE> would be:
<br><br> <pre><br>
wchar_t *<br>
wcscat (wchar_t *wto, const wchar_t *wfrom)<br>
{<br>
wcscpy (wto + wcslen (wto), wfrom);<br>
return wto;<br>
}<br>
</pre>
<br><br> This function has undefined results if the strings overlap.
sq~wtwchar.hxq~;t4wchar_t *restrict wto, const wchar_t *restrict wfromt wchar_t *twcschrsq~
tÊ
The <CODE>wcschr</CODE> function finds the first occurrence of the wide
character <VAR>wc</VAR> in the null-terminated wide character string
beginning at <VAR>wstring</VAR>. The return value is a pointer to the
located wide character, or a null pointer if no match was found.
<br><br> The terminating null character is considered to be part of the wide
character string, so you can use this function get a pointer to the end
of a wide character string by specifying a null wude character as the
value of the <VAR>wc</VAR> argument. It would be better (but less portable)
to use <CODE>wcschrnul</CODE> in this case, though.
sq~wtwchar.hxq~Btconst wchar_t *wstring, int wct wchar_t *t wcschrnulsq~
t1
<CODE>wcschrnul</CODE> is the same as <CODE>wcschr</CODE> except that if it does not
find the wide character, it returns a pointer to wide character string's
terminating null wide character rather than a null pointer.
<br><br> This function is a GNU extension.
sq~wtwchar.hxq~It"const wchar_t *wstring, wchar_t wct wchar_t *twcscmpsq~
tu
<br><br> The <CODE>wcscmp</CODE> function compares the wide character string <VAR>ws1</VAR>
against <VAR>ws2</VAR>. The value returned is smaller than or larger than zero
depending on whether the first differing wide character is <VAR>ws1</VAR> is
smaller or larger than the corresponding character in <VAR>ws2</VAR>.
<br><br> If the two strings are equal, <CODE>wcscmp</CODE> returns <CODE>0</CODE>.
<br><br> A consequence of the ordering used by <CODE>wcscmp</CODE> is that if <VAR>ws1</VAR>
is an initial substring of <VAR>ws2</VAR>, then <VAR>ws1</VAR> is considered to be
``less than'' <VAR>ws2</VAR>.
<br><br> <CODE>wcscmp</CODE> does not take sorting conventions of the language the
strings are written in into account. To get that one has to use
<CODE>wcscoll</CODE>.
sq~wtwchar.hxq~Pt&const wchar_t *ws1, const wchar_t *ws2tinttwcscollsq~
tÑ
The <CODE>wcscoll</CODE> function is similar to <CODE>wcscmp</CODE> but uses the
collating sequence of the current locale for collation (the
<CODE>LC_COLLATE</CODE> locale).
sq~wtwchar.hxq~Wt&const wchar_t *ws1, const wchar_t *ws2tinttwcscpysq~
tM
This copies wide characters from the string <VAR>wfrom</VAR> (up to and
including the terminating null wide character) into the string
<VAR>wto</VAR>. Like <CODE>wmemcpy</CODE>, this function has undefined results if
the strings overlap. The return value is the value of <VAR>wto</VAR>.
sq~wtwchar.hxq~^t4wchar_t *restrict wto, const wchar_t *restrict wfromt wchar_t *twcscspnsq~
tÒ
The <CODE>wcscspn</CODE> (``wide character string complement span'') function
returns the length of the initial substring of <VAR>wstring</VAR> that
consists entirely of wide characters that are <EM>not</EM> members of the
set specified by the string <VAR>stopset</VAR>. (In other words, it returns
the offset of the first character in <VAR>string</VAR> that is a member of
the set <VAR>stopset</VAR>.)
sq~wtwchar.hxq~et.const wchar_t *wstring, const wchar_t *stopsettsize_ttwcsdupsq~
tà
This function copies the null-terminated wide character string <VAR>ws</VAR>
into a newly allocated string. The string is allocated using
<CODE>malloc</CODE>; see Unconstrained Allocation. If <CODE>malloc</CODE>
cannot allocate space for the new string, <CODE>wcsdup</CODE> returns a null
pointer. Otherwise it returns a pointer to the new wide character
string.
<br><br> This function is a GNU extension.
sq~wtwchar.hxq~ltconst wchar_t *wst wchar_t *twcsftimesq~
to
The <CODE>wcsftime</CODE> function is equivalent to the <CODE>strftime</CODE>
function with the difference that it operates on wide character
strings. The buffer where the result is stored, pointed to by <VAR>s</VAR>,
must be an array of wide characters. The parameter <VAR>size</VAR> which
specifies the size of the output buffer gives the number of wide
character, not the number of bytes.
<br><br> Also the format string <VAR>template</VAR> is a wide character string. Since
all characters needed to specify the format string are in the basic
character set it is portably possible to write format strings in the C
source code using the <CODE>L"<small>...</small>"</CODE> notation. The parameter
<VAR>brokentime</VAR> has the same meaning as in the <CODE>strftime</CODE> call.
<br><br> The <CODE>wcsftime</CODE> function supports the same flags, modifiers, and
format specifiers as the <CODE>strftime</CODE> function.
<br><br> The return value of <CODE>wcsftime</CODE> is the number of wide characters
stored in <CODE>s</CODE>. When more characters would have to be written than
can be placed in the buffer <VAR>s</VAR> the return value is zero, with the
same problems indicated in the <CODE>strftime</CODE> documentation.
sq~wttime.hxq~stMwchar_t *s, size_t size, const wchar_t *template, const struct tm *brokentimetsize_ttwcslensq~
t]
The <CODE>wcslen</CODE> function is the wide character equivalent to
<CODE>strlen</CODE>. The return value is the number of wide characters in the
wide character string pointed to by <VAR>ws</VAR> (this is also the offset of
the terminating null wide character of <VAR>ws</VAR>).
<br><br> Since there are no multi wide character sequences making up one
character the return value is not only the offset in the array, it is
also the number of wide characters.
<br><br> This function was introduced in Amendment 1 to ISO C90.
sq~wtwchar.hxq~ztconst wchar_t *wstsize_tt wcsncasecmpsq~
t.
This function is like <CODE>wcsncmp</CODE>, except that differences in case
are ignored. Like <CODE>wcscasecmp</CODE>, it is locale dependent how
uppercase and lowercase characters are related.
<br><br>
<CODE>wcsncasecmp</CODE> is a GNU extension.
sq~wtwchar.hxq~�t/const wchar_t *ws1, const wchar_t *s2, size_t ntinttwcsncatsq~
t¼
This function is like <CODE>wcscat</CODE> except that not more than <VAR>size</VAR>
characters from <VAR>from</VAR> are appended to the end of <VAR>to</VAR>. A
single null character is also always appended to <VAR>to</VAR>, so the total
allocated size of <VAR>to</VAR> must be at least <CODE><VAR>size</VAR> + 1</CODE> bytes
longer than its initial length.
<br><br> The <CODE>wcsncat</CODE> function could be implemented like this:
<br><br> <pre><br>
<br>
wchar_t *<br>
wcsncat (wchar_t *restrict wto, const wchar_t *restrict wfrom,<br>
size_t size)<br>
{<br>
wto[wcslen (to) + size] = L'\0';<br>
wcsncpy (wto + wcslen (wto), wfrom, size);<br>
return wto;<br>
}<br>
<br>
</pre>
<br><br> The behavior of <CODE>wcsncat</CODE> is undefined if the strings overlap.
sq~wtwchar.hxq~ˆtAwchar_t *restrict wto, const wchar_t *restrict wfrom, size_t sizet wchar_t *twcsncmpsq~
t#
This function is the similar to <CODE>wcscmp</CODE>, except that no more than
<VAR>size</VAR> wide characters are compared. In other words, if the two
strings are the same in their first <VAR>size</VAR> wide characters, the
return value is zero.
sq~wtwchar.hxq~�t3const wchar_t *ws1, const wchar_t *ws2, size_t sizetinttwcsncpysq~
t\
This function is similar to <CODE>wcscpy</CODE> but always copies exactly
<VAR>size</VAR> wide characters into <VAR>wto</VAR>.
<br><br> If the length of <VAR>wfrom</VAR> is more than <VAR>size</VAR>, then
<CODE>wcsncpy</CODE> copies just the first <VAR>size</VAR> wide characters. Note
that in this case there is no null terminator written into <VAR>wto</VAR>.
<br><br> If the length of <VAR>wfrom</VAR> is less than <VAR>size</VAR>, then
<CODE>wcsncpy</CODE> copies all of <VAR>wfrom</VAR>, followed by enough null wide
characters to add up to <VAR>size</VAR> wide characters in all. This
behavior is rarely useful, but it is specified by the ISO C
standard.
<br><br> The behavior of <CODE>wcsncpy</CODE> is undefined if the strings overlap.
<br><br> Using <CODE>wcsncpy</CODE> as opposed to <CODE>wcscpy</CODE> is a way to avoid bugs
relating to writing past the end of the allocated space for <VAR>wto</VAR>.
However, it can also make your program much slower in one common case:
copying a string which is probably small into a potentially large buffer.
In this case, <VAR>size</VAR> may be large, and when it is, <CODE>wcsncpy</CODE> will
waste a considerable amount of time copying null wide characters.
sq~wtwchar.hxq~–tAwchar_t *restrict wto, const wchar_t *restrict wfrom, size_t sizet wchar_t *twcsnlensq~
t
<CODE>wcsnlen</CODE> is the wide character equivalent to <CODE>strnlen</CODE>. The
<VAR>maxlen</VAR> parameter specifies the maximum number of wide characters.
<br><br> This function is a GNU extension and is declared in <TT>wchar.h</TT>.
sq~wtwchar.hxq~�t const wchar_t *ws, size_t maxlentsize_tt
wcsnrtombssq~
t*
The <CODE>wcsnrtombs</CODE> function implements the conversion from wide
character strings to multibyte character strings. It is similar to
<CODE>wcsrtombs</CODE> but, just like <CODE>mbsnrtowcs</CODE>, it takes an extra
parameter, which specifies the length of the input string.
<br><br> No more than <VAR>nwc</VAR> wide characters from the input string
<CODE>*<VAR>src</VAR></CODE> are converted. If the input string contains a NUL
wide character in the first <VAR>nwc</VAR> characters, the conversion stops at
this place.
<br><br> The <CODE>wcsnrtombs</CODE> function is a GNU extension and just like
<CODE>mbsnrtowcs</CODE> helps in situations where no NUL-terminated input
strings are available.
sq~wtwchar.hxq~¤t`char *restrict dst, const wchar_t **restrict src, size_t nwc, size_t len, mbstate_t *restrict pstsize_ttwcspbrksq~
t©
The <CODE>wcspbrk</CODE> (``wide character string pointer break'') function is
related to <CODE>wcscspn</CODE>, except that it returns a pointer to the first
wide character in <VAR>wstring</VAR> that is a member of the set
<VAR>stopset</VAR> instead of the length of the initial substring. It
returns a null pointer if no such character from <VAR>stopset</VAR> is found.
sq~wtwchar.hxq~«t.const wchar_t *wstring, const wchar_t *stopsett wchar_t *twcsrchrsq~
tØ
The function <CODE>wcsrchr</CODE> is like <CODE>wcschr</CODE>, except that it searches
backwards from the end of the string <VAR>wstring</VAR> (instead of forwards
from the front).
sq~wtwchar.hxq~²t!const wchar_t *wstring, wchar_t ct wchar_t *t wcsrtombssq~
t 
The <CODE>wcsrtombs</CODE> function (``wide character string restartable to
multibyte string'') converts the NUL-terminated wide character string at
<CODE>*<VAR>src</VAR></CODE> into an equivalent multibyte character string and
stores the result in the array pointed to by <VAR>dst</VAR>. The NUL wide
character is also converted. The conversion starts in the state
described in the object pointed to by <VAR>ps</VAR> or by a state object
locally to <CODE>wcsrtombs</CODE> in case <VAR>ps</VAR> is a null pointer. If
<VAR>dst</VAR> is a null pointer, the conversion is performed as usual but the
result is not available. If all characters of the input string were
successfully converted and if <VAR>dst</VAR> is not a null pointer, the
pointer pointed to by <VAR>src</VAR> gets assigned a null pointer.
<br><br> If one of the wide characters in the input string has no valid multibyte
character equivalent, the conversion stops early, sets the global
variable <CODE>errno</CODE> to <CODE>EILSEQ</CODE>, and returns <CODE>(size_t) -1</CODE>.
<br><br> Another reason for a premature stop is if <VAR>dst</VAR> is not a null
pointer and the next converted character would require more than
<VAR>len</VAR> bytes in total to the array <VAR>dst</VAR>. In this case (and if
<VAR>dest</VAR> is not a null pointer) the pointer pointed to by <VAR>src</VAR> is
assigned a value pointing to the wide character right after the last one
successfully converted.
<br><br> Except in the case of an encoding error the return value of the
<CODE>wcsrtombs</CODE> function is the number of bytes in all the multibyte
character sequences stored in <VAR>dst</VAR>. Before returning the state in
the object pointed to by <VAR>ps</VAR> (or the internal object in case
<VAR>ps</VAR> is a null pointer) is updated to reflect the state after the
last conversion. The state is the initial shift state in case the
terminating NUL wide character was converted.
<br><br> The <CODE>wcsrtombs</CODE> function was introduced in Amendment 1 to
ISO C90 and is declared in <TT>wchar.h</TT>.
sq~wtwchar.hxq~¹tTchar *restrict dst, const wchar_t **restrict src, size_t len, mbstate_t *restrict pstsize_ttwcsspnsq~
tu
The <CODE>wcsspn</CODE> (``wide character string span'') function returns the
length of the initial substring of <VAR>wstring</VAR> that consists entirely
of wide characters that are members of the set specified by the string
<VAR>skipset</VAR>. The order of the wide characters in <VAR>skipset</VAR> is not
important.
sq~wtwchar.hxq~Àt.const wchar_t *wstring, const wchar_t *skipsettsize_ttwcsstrsq~
t¹
This is like <CODE>wcschr</CODE>, except that it searches <VAR>haystack</VAR> for a
substring <VAR>needle</VAR> rather than just a single wide character. It
returns a pointer into the string <VAR>haystack</VAR> that is the first wide
character of the substring, or a null pointer if no match was found. If
<VAR>needle</VAR> is an empty string, the function returns <VAR>haystack</VAR>.
sq~wtwchar.hxq~Çt.const wchar_t *haystack, const wchar_t *needlet wchar_t *twcstodsq~
tØ
The <CODE>wcstod</CODE>, <CODE>wcstof</CODE>, and <CODE>wcstol</CODE> functions are
equivalent in nearly all aspect to the <CODE>strtod</CODE>, <CODE>strtof</CODE>, and
<CODE>strtold</CODE> functions but it handles wide character string.
<br><br> The <CODE>wcstod</CODE> function was introduced in Amendment 1 of ISO
C90. The <CODE>wcstof</CODE> and <CODE>wcstold</CODE> functions were introduced in
ISO C99.
sq~wtwchar.hxq~Ît:const wchar_t *restrict string, wchar_t **restrict tailptrtdoubletwcstofsq~
tØ
The <CODE>wcstod</CODE>, <CODE>wcstof</CODE>, and <CODE>wcstol</CODE> functions are
equivalent in nearly all aspect to the <CODE>strtod</CODE>, <CODE>strtof</CODE>, and
<CODE>strtold</CODE> functions but it handles wide character string.
<br><br> The <CODE>wcstod</CODE> function was introduced in Amendment 1 of ISO
C90. The <CODE>wcstof</CODE> and <CODE>wcstold</CODE> functions were introduced in
ISO C99.
sq~wtstdlib.hxq~Õt(const wchar_t *string, wchar_t **tailptrtfloatt wcstoimaxsq~
tþ
The <CODE>wcstoimax</CODE> function is equivalent to the <CODE>strtoimax</CODE> function
in nearly all aspects but handles wide character strings.
<br><br> The <CODE>wcstoimax</CODE> function was introduced in ISO C99.
sq~wtwchar.hxq~ÜtDconst wchar_t *restrict string, wchar_t **restrict tailptr, int basetintmax_ttwcstoksq~
t †
A string can be split into tokens by making a series of calls to the
function <CODE>wcstok</CODE>.
<br><br> The string to be split up is passed as the <VAR>newstring</VAR> argument on
the first call only. The <CODE>wcstok</CODE> function uses this to set up
some internal state information. Subsequent calls to get additional
tokens from the same wide character string are indicated by passing a
null pointer as the <VAR>newstring</VAR> argument. Calling <CODE>wcstok</CODE>
with another non-null <VAR>newstring</VAR> argument reinitializes the state
information. It is guaranteed that no other library function ever calls
<CODE>wcstok</CODE> behind your back (which would mess up this internal state
information).
<br><br> The <VAR>delimiters</VAR> argument is a wide character string that specifies
a set of delimiters that may surround the token being extracted. All
the initial wide characters that are members of this set are discarded.
The first wide character that is <EM>not</EM> a member of this set of
delimiters marks the beginning of the next token. The end of the token
is found by looking for the next wide character that is a member of the
delimiter set. This wide character in the original wide character
string <VAR>newstring</VAR> is overwritten by a null wide character, and the
pointer to the beginning of the token in <VAR>newstring</VAR> is returned.
<br><br> On the next call to <CODE>wcstok</CODE>, the searching begins at the next
wide character beyond the one that marked the end of the previous token.
Note that the set of delimiters <VAR>delimiters</VAR> do not have to be the
same on every call in a series of calls to <CODE>wcstok</CODE>.
<br><br> If the end of the wide character string <VAR>newstring</VAR> is reached, or
if the remainder of string consists only of delimiter wide characters,
<CODE>wcstok</CODE> returns a null pointer.
<br><br> Note that ``character'' is here used in the sense of byte. In a string
using a multibyte character encoding (abstract) character consisting of
more than one byte are not treated as an entity. Each byte is treated
separately. The function is not locale-dependent.
sq~wtwchar.hxq~ãt*wchar_t *newstring, const char *delimiterst wchar_t *twcstolsq~
t
The <CODE>wcstol</CODE> function is equivalent to the <CODE>strtol</CODE> function
in nearly all aspects but handles wide character strings.
<br><br> The <CODE>wcstol</CODE> function was introduced in Amendment 1 of ISO C90.
sq~wtwchar.hxq~êtDconst wchar_t *restrict string, wchar_t **restrict tailptr, int basetlong inttwcstoldsq~
tØ
The <CODE>wcstod</CODE>, <CODE>wcstof</CODE>, and <CODE>wcstol</CODE> functions are
equivalent in nearly all aspect to the <CODE>strtod</CODE>, <CODE>strtof</CODE>, and
<CODE>strtold</CODE> functions but it handles wide character string.
<br><br> The <CODE>wcstod</CODE> function was introduced in Amendment 1 of ISO
C90. The <CODE>wcstof</CODE> and <CODE>wcstold</CODE> functions were introduced in
ISO C99.
sq~wtstdlib.hxq~ñt(const wchar_t *string, wchar_t **tailptrt long doubletwcstollsq~
t
The <CODE>wcstoll</CODE> function is equivalent to the <CODE>strtoll</CODE> function
in nearly all aspects but handles wide character strings.
<br><br> The <CODE>wcstoll</CODE> function was introduced in Amendment 1 of ISO C90.
sq~wtwchar.hxq~øtDconst wchar_t *restrict string, wchar_t **restrict tailptr, int baset
long long inttwcstombssq~
tC
The <CODE>wcstombs</CODE> (``wide character string to multibyte string'')
function converts the null-terminated wide character array <VAR>wstring</VAR>
into a string containing multibyte characters, storing not more than
<VAR>size</VAR> bytes starting at <VAR>string</VAR>, followed by a terminating
null character if there is room. The conversion of characters begins in
the initial shift state.
<br><br> The terminating null character counts towards the size, so if <VAR>size</VAR>
is less than or equal to the number of bytes needed in <VAR>wstring</VAR>, no
terminating null character is stored.
<br><br> If a code that does not correspond to a valid multibyte character is
found, the <CODE>wcstombs</CODE> function returns a value of -1.
Otherwise, the return value is the number of bytes stored in the array
<VAR>string</VAR>. This number does not include the terminating null character,
which is present if the number is less than <VAR>size</VAR>.
sq~wtstdlib.hxq~ÿt1char *string, const wchar_t *wstring, size_t sizetsize_ttwcstoqsq~
tî
The <CODE>wcstoq</CODE> function is equivalent to the <CODE>strtoq</CODE> function
in nearly all aspects but handles wide character strings.
<br><br> The <CODE>wcstoq</CODE> function is a GNU extension.
sq~wtwchar.hxq~ tDconst wchar_t *restrict string, wchar_t **restrict tailptr, int baset
long long inttwcstoulsq~
t
The <CODE>wcstoul</CODE> function is equivalent to the <CODE>strtoul</CODE> function
in nearly all aspects but handles wide character strings.
<br><br> The <CODE>wcstoul</CODE> function was introduced in Amendment 1 of ISO C90.
sq~wtwchar.hxq~
tDconst wchar_t *restrict string, wchar_t **restrict tailptr, int basetunsigned long inttwcstoullsq~
t
The <CODE>wcstoull</CODE> function is equivalent to the <CODE>strtoull</CODE> function
in nearly all aspects but handles wide character strings.
<br><br> The <CODE>wcstoull</CODE> function was introduced in Amendment 1 of ISO C90.
sq~wtwchar.hxq~ tDconst wchar_t *restrict string, wchar_t **restrict tailptr, int basetunsigned long long intt wcstoumaxsq~
tþ
The <CODE>wcstoumax</CODE> function is equivalent to the <CODE>strtoumax</CODE> function
in nearly all aspects but handles wide character strings.
<br><br> The <CODE>wcstoumax</CODE> function was introduced in ISO C99.
sq~wtwchar.hxq~ tDconst wchar_t *restrict string, wchar_t **restrict tailptr, int baset uintmax_ttwcstouqsq~
tñ
The <CODE>wcstouq</CODE> function is equivalent to the <CODE>strtouq</CODE> function
in nearly all aspects but handles wide character strings.
<br><br> The <CODE>wcstouq</CODE> function is a GNU extension.
sq~wtwchar.hxq~ "tDconst wchar_t *restrict string, wchar_t **restrict tailptr, int basetunsigned long long inttwcswcssq~
tÚ
<CODE>wcswcs</CODE> is an deprecated alias for <CODE>wcsstr</CODE>. This is the
name originally used in the X/Open Portability Guide before the
Amendment 1 to ISO C90 was published.
sq~wtwchar.hxq~ )t.const wchar_t *haystack, const wchar_t *needlet wchar_t *twcsxfrmsq~
të
The function <CODE>wcsxfrm</CODE> transforms wide character string <VAR>wfrom</VAR>
using the collation transformation determined by the locale currently
selected for collation, and stores the transformed string in the array
<VAR>wto</VAR>. Up to <VAR>size</VAR> wide characters (including a terminating null
character) are stored.
<br><br> The behavior is undefined if the strings <VAR>wto</VAR> and <VAR>wfrom</VAR>
overlap; see Copying and Concatenation.
<br><br> The return value is the length of the entire transformed wide character
string. This value is not affected by the value of <VAR>size</VAR>, but if
it is greater or equal than <VAR>size</VAR>, it means that the transformed
wide character string did not entirely fit in the array <VAR>wto</VAR>. In
this case, only as much of the wide character string as actually fits
was stored. To get the whole transformed wide character string, call
<CODE>wcsxfrm</CODE> again with a bigger output array.
<br><br> The transformed wide character string may be longer than the original
wide character string, and it may also be shorter.
<br><br> If <VAR>size</VAR> is zero, no characters are stored in <VAR>to</VAR>. In this
case, <CODE>wcsxfrm</CODE> simply returns the number of wide characters that
would be the length of the transformed wide character string. This is
useful for determining what size the allocated array should be (remember
to multiply with <CODE>sizeof (wchar_t)</CODE>). It does not matter what
<VAR>wto</VAR> is if <VAR>size</VAR> is zero; <VAR>wto</VAR> may even be a null pointer.
sq~wtwchar.hxq~ 0t8wchar_t *restrict wto, const wchar_t *wfrom, size_t sizetsize_ttwctobsq~
tæ
The <CODE>wctob</CODE> function (``wide character to byte'') takes as the
parameter a valid wide character. If the multibyte representation for
this character in the initial state is exactly one byte long, the return
value of this function is this character. Otherwise the return value is
<CODE>EOF</CODE>.
<br><br> <CODE>wctob</CODE> was introduced in Amendment 1 to ISO C90 and
is declared in <TT>wchar.h</TT>.
sq~wtwchar.hxq~ 7twint_t ctinttwctombsq~
tV
The <CODE>wctomb</CODE> (``wide character to multibyte'') function converts
the wide character code <VAR>wchar</VAR> to its corresponding multibyte
character sequence, and stores the result in bytes starting at
<VAR>string</VAR>. At most <CODE>MB_CUR_MAX</CODE> characters are stored.
<br><br> <CODE>wctomb</CODE> with non-null <VAR>string</VAR> distinguishes three
possibilities for <VAR>wchar</VAR>: a valid wide character code (one that can
be translated to a multibyte character), an invalid code, and
<CODE>L'\0'</CODE>.
<br><br> Given a valid code, <CODE>wctomb</CODE> converts it to a multibyte character,
storing the bytes starting at <VAR>string</VAR>. Then it returns the number
of bytes in that character (always at least 1 and never more
than <CODE>MB_CUR_MAX</CODE>).
<br><br> If <VAR>wchar</VAR> is an invalid wide character code, <CODE>wctomb</CODE> returns
-1. If <VAR>wchar</VAR> is <CODE>L'\0'</CODE>, it returns <CODE>0</CODE>, also
storing <CODE>'\0'</CODE> in <CODE>*<VAR>string</VAR></CODE>.
<br><br> If the multibyte character code uses shift characters, then
<CODE>wctomb</CODE> maintains and updates a shift state as it scans. If you
call <CODE>wctomb</CODE> with a null pointer for <VAR>string</VAR>, that
initializes the shift state to its standard initial value. It also
returns nonzero if the multibyte character code in use actually has a
shift state. .
<br><br> Calling this function with a <VAR>wchar</VAR> argument of zero when
<VAR>string</VAR> is not null has the side-effect of reinitializing the
stored shift state <EM>as well as</EM> storing the multibyte character
<CODE>'\0'</CODE> and returning 0.
sq~wtstdlib.hxq~ >tchar *string, wchar_t wchartinttwctranssq~
tŒ
The <CODE>wctrans</CODE> function has to be used to find out whether a named
mapping is defined in the current locale selected for the
<CODE>LC_CTYPE</CODE> category. If the returned value is non-zero, you can use
it afterwards in calls to <CODE>towctrans</CODE>. If the return value is
zero no such mapping is known in the current locale.
<br><br> Beside locale-specific mappings there are two mappings which are
guaranteed to be available in every locale:
<br><br> <DT><pre></pre>
<DD><br>
<br><br>
These functions are declared in <TT>wctype.h</TT>.
sq~wtwctype.hxq~ Etconst char *propertyt wctrans_ttwctypesq~
tI
The <CODE>wctype</CODE> returns a value representing a class of wide
characters which is identified by the string <VAR>property</VAR>. Beside
some standard properties each locale can define its own ones. In case
no property with the given name is known for the current locale
selected for the <CODE>LC_CTYPE</CODE> category, the function returns zero.
<br><br>
The properties known in every locale are:
<br><br> <DT><pre></pre>
<DD><br>
<br><br> This function is declared in <TT>wctype.h</TT>.
sq~wtwctype.hxq~ Ltconst char *propertytwctype_ttwmemchrsq~
t<
This function finds the first occurrence of the wide character <VAR>wc</VAR>
in the initial <VAR>size</VAR> wide characters of the object beginning at
<VAR>block</VAR>. The return value is a pointer to the located wide
character, or a null pointer if no match was found.
sq~wtwchar.hxq~ St-const wchar_t *block, wchar_t wc, size_t sizet wchar_t *twmemcmpsq~
t%
The function <CODE>wmemcmp</CODE> compares the <VAR>size</VAR> wide characters
beginning at <VAR>a1</VAR> against the <VAR>size</VAR> wide characters beginning
at <VAR>a2</VAR>. The value returned is smaller than or larger than zero
depending on whether the first differing wide character is <VAR>a1</VAR> is
smaller or larger than the corresponding character in <VAR>a2</VAR>.
<br><br> If the contents of the two blocks are equal, <CODE>wmemcmp</CODE> returns
<CODE>0</CODE>.
sq~wtwcjar.hxq~ Zt1const wchar_t *a1, const wchar_t *a2, size_t sizetinttwmemcpysq~
tÉ
The <CODE>wmemcpy</CODE> function copies <VAR>size</VAR> wide characters from the object
beginning at <VAR>wfrom</VAR> into the object beginning at <VAR>wto</VAR>. The
behavior of this function is undefined if the two arrays <VAR>wto</VAR> and
<VAR>wfrom</VAR> overlap; use <CODE>wmemmove</CODE> instead if overlapping is possible.
<br><br> The following is a possible implementation of <CODE>wmemcpy</CODE> but there
are more optimizations possible.
<br><br> <pre><br>
wchar_t *<br>
wmemcpy (wchar_t *restrict wto, const wchar_t *restrict wfrom,<br>
size_t size)<br>
{<br>
return (wchar_t *) memcpy (wto, wfrom, size * sizeof (wchar_t));<br>
}<br>
</pre>
<br><br> The value returned by <CODE>wmemcpy</CODE> is the value of <VAR>wto</VAR>.
<br><br> This function was introduced in Amendment 1 to ISO C90.
sq~wtwchar.hxq~ atAwchar_t *restrict wto, const wchar_t *restrict wfrom, size_t sizet wchar_t *twmemmovesq~
t
<CODE>wmemmove</CODE> copies the <VAR>size</VAR> wide characters at <VAR>wfrom</VAR>
into the <VAR>size</VAR> wide characters at <VAR>wto</VAR>, even if those two
blocks of space overlap. In the case of overlap, <CODE>memmove</CODE> is
careful to copy the original values of the wide characters in the block
at <VAR>wfrom</VAR>, including those wide characters which also belong to the
block at <VAR>wto</VAR>.
<br><br> The following is a possible implementation of <CODE>wmemcpy</CODE> but there
are more optimizations possible.
<br><br> <pre><br>
wchar_t *<br>
wmempcpy (wchar_t *restrict wto, const wchar_t *restrict wfrom,<br>
size_t size)<br>
{<br>
return (wchar_t *) mempcpy (wto, wfrom, size * sizeof (wchar_t));<br>
}<br>
</pre>
<br><br> The value returned by <CODE>wmemmove</CODE> is the value of <VAR>wto</VAR>.
<br><br> This function is a GNU extension.
sq~wtwchar.hxq~ ht-wchar *wto, const wchar_t *wfrom, size_t sizet wchar_t *twmempcpysq~
t‰
The <CODE>wmempcpy</CODE> function is nearly identical to the <CODE>wmemcpy</CODE>
function. It copies <VAR>size</VAR> wide characters from the object
beginning at <CODE>wfrom</CODE> into the object pointed to by <VAR>wto</VAR>. But
instead of returning the value of <VAR>wto</VAR> it returns a pointer to the
wide character following the last written wide character in the object
beginning at <VAR>wto</VAR>. I.e., the value is <CODE><VAR>wto</VAR> + <VAR>size</VAR></CODE>.
<br><br> This function is useful in situations where a number of objects shall be
copied to consecutive memory positions.
<br><br> The following is a possible implementation of <CODE>wmemcpy</CODE> but there
are more optimizations possible.
<br><br> <pre><br>
wchar_t *<br>
wmempcpy (wchar_t *restrict wto, const wchar_t *restrict wfrom,<br>
size_t size)<br>
{<br>
return (wchar_t *) mempcpy (wto, wfrom, size * sizeof (wchar_t));<br>
}<br>
</pre>
<br><br> This function is a GNU extension.
sq~wtwchar.hxq~ otAwchar_t *restrict wto, const wchar_t *restrict wfrom, size_t sizet wchar_t *twmemsetsq~
tâ
This function copies the value of <VAR>wc</VAR> into each of the first
<VAR>size</VAR> wide characters of the object beginning at <VAR>block</VAR>. It
returns the value of <VAR>block</VAR>.
sq~wtwchar.hxq~ vt'wchar_t *block, wchar_t wc, size_t sizet wchar_t *twordexpsq~
t À
Perform word expansion on the string <VAR>words</VAR>, putting the result in
a newly allocated vector, and store the size and address of this vector
into <CODE>*<VAR>word-vector-ptr</VAR></CODE>. The argument <VAR>flags</VAR> is a
combination of bit flags; see Flags for Wordexp, for details of
the flags.
<br><br> You shouldn't use any of the characters <samp>|&;<></samp> in the string
<VAR>words</VAR> unless they are quoted; likewise for newline. If you use
these characters unquoted, you will get the <CODE>WRDE_BADCHAR</CODE> error
code. Don't use parentheses or braces unless they are quoted or part of
a word expansion construct. If you use quotation characters <samp>'"`</samp>,
they should come in pairs that balance.
<br><br> The results of word expansion are a sequence of words. The function
<CODE>wordexp</CODE> allocates a string for each resulting word, then
allocates a vector of type <CODE>char **</CODE> to store the addresses of
these strings. The last element of the vector is a null pointer.
This vector is called the word vector.
<br><br> To return this vector, <CODE>wordexp</CODE> stores both its address and its
length (number of elements, not counting the terminating null pointer)
into <CODE>*<VAR>word-vector-ptr</VAR></CODE>.
<br><br> If <CODE>wordexp</CODE> succeeds, it returns 0. Otherwise, it returns one
of these error codes:
<br><br> <DL>
<DT><CODE>WRDE_BADCHAR</CODE>
<DD>
The input string <VAR>words</VAR> contains an unquoted invalid character such
as <samp>|</samp>.
<br><br> <LI> WRDE_BADVAL
The input string refers to an undefined shell variable, and you used the flag
<CODE>WRDE_UNDEF</CODE> to forbid such references.
<br><br> <LI> WRDE_CMDSUB
The input string uses command substitution, and you used the flag
<CODE>WRDE_NOCMD</CODE> to forbid command substitution.
<br><br> <LI> WRDE_NOSPACE
It was impossible to allocate memory to hold the result. In this case,
<CODE>wordexp</CODE> can store part of the results---as much as it could
allocate room for.
<br><br> <LI> WRDE_SYNTAX
There was a syntax error in the input string. For example, an unmatched
quoting character is a syntax error.
sq~wt wordexp.hxq~ }t8const char *words, wordexp_t *word-vector-ptr, int flagstinttwordfreesq~
t
Free the storage used for the word-strings and vector that
<CODE>*<VAR>word-vector-ptr</VAR></CODE> points to. This does not free the
structure <CODE>*<VAR>word-vector-ptr</VAR></CODE> itself---only the other
data it points to.
Reference in New Issue Copy Permalink