Skip to main content
aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorJeff Johnston2012-06-08 16:40:46 -0400
committerJeff Johnston2012-06-08 16:48:27 -0400
commit3e731559e7557f8fde222fbb6c1a9ce94ffb0f12 (patch)
treef9d33ee078c0b09e94a98bcef3b535764d5c549f /libhover
parente64bf32dc5461a69b9907b59806f378b6aa18b16 (diff)
downloadorg.eclipse.linuxtools-3e731559e7557f8fde222fbb6c1a9ce94ffb0f12.tar.gz
org.eclipse.linuxtools-3e731559e7557f8fde222fbb6c1a9ce94ffb0f12.tar.xz
org.eclipse.linuxtools-3e731559e7557f8fde222fbb6c1a9ce94ffb0f12.zip
Fix for: https://bugs.eclipse.org/bugs/show_bug.cgi?id=381660
Update glibc libhover docs to 2.14. Also add the Invariant Sections as listed in the document's permission to modify clause to the binary libhover data. Provide the xml version of the libhover document as the transparent copy whereas the libhover version is the opaque version.
Diffstat (limited to 'libhover')
-rw-r--r--libhover/org.eclipse.linuxtools.cdt.libhover.glibc/ChangeLog9
-rw-r--r--libhover/org.eclipse.linuxtools.cdt.libhover.glibc/META-INF/MANIFEST.MF2
-rw-r--r--libhover/org.eclipse.linuxtools.cdt.libhover.glibc/build.properties1
-rw-r--r--libhover/org.eclipse.linuxtools.cdt.libhover.glibc/data/glibc-2.14.libhover (renamed from libhover/org.eclipse.linuxtools.cdt.libhover.glibc/data/glibc-2.7-2.libhover)bin999308 -> 1042692 bytes
-rw-r--r--libhover/org.eclipse.linuxtools.cdt.libhover.glibc/data/glibc-2.14.xml33624
-rw-r--r--libhover/org.eclipse.linuxtools.cdt.libhover.glibc/plugin.xml2
-rw-r--r--libhover/org.eclipse.linuxtools.cdt.libhover.glibc/pom.xml2
7 files changed, 33637 insertions, 3 deletions
diff --git a/libhover/org.eclipse.linuxtools.cdt.libhover.glibc/ChangeLog b/libhover/org.eclipse.linuxtools.cdt.libhover.glibc/ChangeLog
index 9a4de0b6b8..144294f654 100644
--- a/libhover/org.eclipse.linuxtools.cdt.libhover.glibc/ChangeLog
+++ b/libhover/org.eclipse.linuxtools.cdt.libhover.glibc/ChangeLog
@@ -1,3 +1,12 @@
+2012-06-08 Jeff Johnston <jjohnstn@redhat.com>
+
+ * data/glibc-2.14.libhover: New file.
+ * data/glibc-2.14.xml: New file.
+ * build.properties: Add new files and remove glibc-2.7-2.libhover.
+ * META-INF/MANIFEST.MF: Update version.
+ * plugin.xml: Update to use new libhover file.
+ * pom.xml: Update version.
+
2011-03-11 Jeff Johnston <jjohnstn@redhat.com>
* toc.xml: Change documentation anchor to be moreclibdocs.
diff --git a/libhover/org.eclipse.linuxtools.cdt.libhover.glibc/META-INF/MANIFEST.MF b/libhover/org.eclipse.linuxtools.cdt.libhover.glibc/META-INF/MANIFEST.MF
index 794200443d..dde9a6ffb4 100644
--- a/libhover/org.eclipse.linuxtools.cdt.libhover.glibc/META-INF/MANIFEST.MF
+++ b/libhover/org.eclipse.linuxtools.cdt.libhover.glibc/META-INF/MANIFEST.MF
@@ -2,7 +2,7 @@ Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: %bundleName
Bundle-SymbolicName: org.eclipse.linuxtools.cdt.libhover.glibc;singleton:=true
-Bundle-Version: 1.1.0.qualifier
+Bundle-Version: 1.2.0.qualifier
Bundle-Vendor: %provider
Bundle-Localization: plugin
Require-Bundle: org.eclipse.linuxtools.cdt.libhover.library.docs;bundle-version="1.0.0",
diff --git a/libhover/org.eclipse.linuxtools.cdt.libhover.glibc/build.properties b/libhover/org.eclipse.linuxtools.cdt.libhover.glibc/build.properties
index 528fb3a6da..c6b5ee0a81 100644
--- a/libhover/org.eclipse.linuxtools.cdt.libhover.glibc/build.properties
+++ b/libhover/org.eclipse.linuxtools.cdt.libhover.glibc/build.properties
@@ -6,3 +6,4 @@ bin.includes = META-INF/,\
data/
src.includes = about.html
+bin.excludes = data/glibc-2.7-2.libhover
diff --git a/libhover/org.eclipse.linuxtools.cdt.libhover.glibc/data/glibc-2.7-2.libhover b/libhover/org.eclipse.linuxtools.cdt.libhover.glibc/data/glibc-2.14.libhover
index b21635fa1d..38b5f24f34 100644
--- a/libhover/org.eclipse.linuxtools.cdt.libhover.glibc/data/glibc-2.7-2.libhover
+++ b/libhover/org.eclipse.linuxtools.cdt.libhover.glibc/data/glibc-2.14.libhover
Binary files differ
diff --git a/libhover/org.eclipse.linuxtools.cdt.libhover.glibc/data/glibc-2.14.xml b/libhover/org.eclipse.linuxtools.cdt.libhover.glibc/data/glibc-2.14.xml
new file mode 100644
index 0000000000..db124fb25f
--- /dev/null
+++ b/libhover/org.eclipse.linuxtools.cdt.libhover.glibc/data/glibc-2.14.xml
@@ -0,0 +1,33624 @@
+<!-- This file automatically generated by an Eclipse utility -->
+<!DOCTYPE descriptions [
+
+ <!ELEMENT descriptions (construct)*>
+
+ <!ELEMENT construct (structure|function)*>
+ <!ATTLIST construct
+ id ID #REQUIRED
+ type CDATA #REQUIRED
+ >
+
+ <!ELEMENT structure (synopsis?, elements?)?>
+
+ <!ELEMENT elements (element*)>
+
+ <!ELEMENT element (synopsis*)>
+ <!ATTLIST element
+ content CDATA #REQUIRED
+ >
+
+ <!ELEMENT synopsis (#PCDATA)*>
+
+ <!ELEMENT function (prototype,headers?,synopsis)>
+ <!ATTLIST function
+ returntype CDATA #REQUIRED
+ >
+
+ <!ELEMENT prototype (parameter+)?>
+
+ <!ELEMENT parameter (#PCDATA)*>
+ <!ATTLIST parameter
+ content CDATA #REQUIRED
+ >
+
+ <!ELEMENT headers (header+)?>
+
+ <!ELEMENT header (#PCDATA)*>
+ <!ATTLIST header
+ filename CDATA #REQUIRED
+ >
+
+]>
+
+<descriptions>
+ <!-- Following is needed to comply with the GFDL regarding modification and invariant sections. -->
+ <construct id="function-0-REQUIRED-SECTIONS" type="function">
+ <function returntype="void">
+ <prototype>
+ </prototype>
+ <synopsis>
+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
+
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-getpass" type="function">
+ <function returntype="char *">
+ <prototype>
+ <parameter content="const char *prompt"/>
+ </prototype>
+ <headers>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ &lt;br&gt;&lt;br&gt; &lt;CODE&gt;getpass&lt;/CODE&gt; outputs &lt;VAR&gt;prompt&lt;/VAR&gt;, then reads a string in from the
+ terminal without echoing it. It tries to connect to the real terminal,
+ &lt;TT&gt;/dev/tty&lt;/TT&gt;, if possible, to encourage users not to put plaintext
+ passwords in files; otherwise, it uses &lt;CODE&gt;stdin&lt;/CODE&gt; and &lt;CODE&gt;stderr&lt;/CODE&gt;.
+ &lt;CODE&gt;getpass&lt;/CODE&gt; also disables the INTR, QUIT, and SUSP characters on the
+ terminal using the &lt;CODE&gt;ISIG&lt;/CODE&gt; terminal attribute .
+ The terminal is flushed before and after &lt;CODE&gt;getpass&lt;/CODE&gt;, so that
+ characters of a mistyped password are not accidentally visible.
+ &lt;br&gt;&lt;br&gt; In other C libraries, &lt;CODE&gt;getpass&lt;/CODE&gt; may only return the first
+ &lt;CODE&gt;PASS_MAX&lt;/CODE&gt; bytes of a password. The GNU C library has no limit, so
+ &lt;CODE&gt;PASS_MAX&lt;/CODE&gt; is undefined.
+ &lt;br&gt;&lt;br&gt; The prototype for this function is in &lt;TT&gt;unistd.h&lt;/TT&gt;. &lt;CODE&gt;PASS_MAX&lt;/CODE&gt;
+ would be defined in &lt;TT&gt;limits.h&lt;/TT&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-crypt" type="function">
+ <function returntype="char *">
+ <prototype>
+ <parameter content="const char *key"/>
+ <parameter content="const char *salt"/>
+ </prototype>
+ <headers>
+ <header filename = "crypt.h"/>
+ </headers>
+ <synopsis>
+ &lt;br&gt;&lt;br&gt; The &lt;CODE&gt;crypt&lt;/CODE&gt; function takes a password, &lt;VAR&gt;key&lt;/VAR&gt;, as a string, and
+ a &lt;VAR&gt;salt&lt;/VAR&gt; 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 &lt;VAR&gt;key&lt;/VAR&gt;
+ that will produce that output is to guess values of &lt;VAR&gt;key&lt;/VAR&gt; until the
+ original value of &lt;VAR&gt;key&lt;/VAR&gt; is found.
+ &lt;br&gt;&lt;br&gt; The &lt;VAR&gt;salt&lt;/VAR&gt; 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 &lt;VAR&gt;salt&lt;/VAR&gt;, an intruder can make a
+ guess, run &lt;CODE&gt;crypt&lt;/CODE&gt; on it once, and compare the result with all the
+ passwords. With a &lt;VAR&gt;salt&lt;/VAR&gt;, the intruder must run &lt;CODE&gt;crypt&lt;/CODE&gt; once
+ for each different salt.
+ &lt;br&gt;&lt;br&gt; For the MD5-based algorithm, the &lt;VAR&gt;salt&lt;/VAR&gt; should consist of the string
+ &lt;CODE&gt;$1$&lt;/CODE&gt;, followed by up to 8 characters, terminated by either
+ another &lt;CODE&gt;$&lt;/CODE&gt; or the end of the string. The result of &lt;CODE&gt;crypt&lt;/CODE&gt;
+ will be the &lt;VAR&gt;salt&lt;/VAR&gt;, followed by a &lt;CODE&gt;$&lt;/CODE&gt; if the salt didn't end
+ with one, followed by 22 characters from the alphabet
+ &lt;CODE&gt;./0-9A-Za-z&lt;/CODE&gt;, up to 34 characters total. Every character in the
+ &lt;VAR&gt;key&lt;/VAR&gt; is significant.
+ &lt;br&gt;&lt;br&gt; For the DES-based algorithm, the &lt;VAR&gt;salt&lt;/VAR&gt; should consist of two
+ characters from the alphabet &lt;CODE&gt;./0-9A-Za-z&lt;/CODE&gt;, and the result of
+ &lt;CODE&gt;crypt&lt;/CODE&gt; will be those two characters followed by 11 more from the
+ same alphabet, 13 in total. Only the first 8 characters in the
+ &lt;VAR&gt;key&lt;/VAR&gt; are significant.
+ &lt;br&gt;&lt;br&gt; 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.
+ &lt;br&gt;&lt;br&gt; When the user enters their password for the first time, the &lt;VAR&gt;salt&lt;/VAR&gt;
+ should be set to a new string which is reasonably random. To verify a
+ password against the result of a previous call to &lt;CODE&gt;crypt&lt;/CODE&gt;, pass
+ the result of the previous call as the &lt;VAR&gt;salt&lt;/VAR&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-crypt_r" type="function">
+ <function returntype="char *">
+ <prototype>
+ <parameter content="const char *key"/>
+ <parameter content="const char *salt"/>
+ <parameter content="{struct crypt_data *} data"/>
+ </prototype>
+ <headers>
+ <header filename = "crypt.h"/>
+ </headers>
+ <synopsis>
+ &lt;br&gt;&lt;br&gt; The &lt;CODE&gt;crypt_r&lt;/CODE&gt; function does the same thing as &lt;CODE&gt;crypt&lt;/CODE&gt;, but
+ takes an extra parameter which includes space for its result (among
+ other things), so it can be reentrant. &lt;CODE&gt;data-&gt;&lt;/CODE&gt;initialized must be
+ cleared to zero before the first time &lt;CODE&gt;crypt_r&lt;/CODE&gt; is called.
+ &lt;br&gt;&lt;br&gt; The &lt;CODE&gt;crypt_r&lt;/CODE&gt; function is a GNU extension.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-setkey" type="function">
+ <function returntype="void">
+ <prototype>
+ <parameter content="const char *key"/>
+ </prototype>
+ <headers>
+ <header filename = "crypt.h"/>
+ </headers>
+ <synopsis>
+ &lt;br&gt;&lt;br&gt; The &lt;CODE&gt;setkey&lt;/CODE&gt; function sets an internal data structure to be an
+ expanded form of &lt;VAR&gt;key&lt;/VAR&gt;. &lt;VAR&gt;key&lt;/VAR&gt; is specified as an array of 64
+ bits each stored in a &lt;CODE&gt;char&lt;/CODE&gt;, the first bit is &lt;CODE&gt;key[0]&lt;/CODE&gt; and
+ the 64th bit is &lt;CODE&gt;key[63]&lt;/CODE&gt;. The &lt;VAR&gt;key&lt;/VAR&gt; should have the correct
+ parity.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-encrypt" type="function">
+ <function returntype="void">
+ <prototype>
+ <parameter content="char *block"/>
+ <parameter content="int edflag"/>
+ </prototype>
+ <headers>
+ <header filename = "crypt.h"/>
+ </headers>
+ <synopsis>
+ &lt;br&gt;&lt;br&gt; The &lt;CODE&gt;encrypt&lt;/CODE&gt; function encrypts &lt;VAR&gt;block&lt;/VAR&gt; if
+ &lt;VAR&gt;edflag&lt;/VAR&gt; is 0, otherwise it decrypts &lt;VAR&gt;block&lt;/VAR&gt;, using a key
+ previously set by &lt;CODE&gt;setkey&lt;/CODE&gt;. The result is
+ placed in &lt;VAR&gt;block&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; Like &lt;CODE&gt;setkey&lt;/CODE&gt;, &lt;VAR&gt;block&lt;/VAR&gt; is specified as an array of 64 bits each
+ stored in a &lt;CODE&gt;char&lt;/CODE&gt;, but there are no parity bits in &lt;VAR&gt;block&lt;/VAR&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-setkey_r" type="function">
+ <function returntype="void">
+ <prototype>
+ <parameter content="const char *key"/>
+ <parameter content="{struct crypt_data *} data"/>
+ </prototype>
+ <headers>
+ <header filename = "crypt.h"/>
+ </headers>
+ <synopsis>
+ &lt;br&gt;&lt;br&gt; These are reentrant versions of &lt;CODE&gt;setkey&lt;/CODE&gt; and &lt;CODE&gt;encrypt&lt;/CODE&gt;. The
+ only difference is the extra parameter, which stores the expanded
+ version of &lt;VAR&gt;key&lt;/VAR&gt;. Before calling &lt;CODE&gt;setkey_r&lt;/CODE&gt; the first time,
+ &lt;CODE&gt;data-&gt;initialized&lt;/CODE&gt; must be cleared to zero.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-encrypt_r" type="function">
+ <function returntype="void">
+ <prototype>
+ <parameter content="char *block"/>
+ <parameter content="int edflag"/>
+ <parameter content="{struct crypt_data *} data"/>
+ </prototype>
+ <headers>
+ <header filename = "crypt.h"/>
+ </headers>
+ <synopsis>
+ &lt;br&gt;&lt;br&gt; These are reentrant versions of &lt;CODE&gt;setkey&lt;/CODE&gt; and &lt;CODE&gt;encrypt&lt;/CODE&gt;. The
+ only difference is the extra parameter, which stores the expanded
+ version of &lt;VAR&gt;key&lt;/VAR&gt;. Before calling &lt;CODE&gt;setkey_r&lt;/CODE&gt; the first time,
+ &lt;CODE&gt;data-&gt;initialized&lt;/CODE&gt; must be cleared to zero.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-ecb_crypt" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="char *key"/>
+ <parameter content="char *blocks"/>
+ <parameter content="unsigned len"/>
+ <parameter content="unsigned mode"/>
+ </prototype>
+ <headers>
+ <header filename = "rpc/des_crypt.h"/>
+ </headers>
+ <synopsis>
+ &lt;br&gt;&lt;br&gt; The function &lt;CODE&gt;ecb_crypt&lt;/CODE&gt; encrypts or decrypts one or more blocks
+ using DES. Each block is encrypted independently.
+ &lt;br&gt;&lt;br&gt; The &lt;VAR&gt;blocks&lt;/VAR&gt; and the &lt;VAR&gt;key&lt;/VAR&gt; are stored packed in 8-bit bytes, so
+ that the first bit of the key is the most-significant bit of
+ &lt;CODE&gt;key[0]&lt;/CODE&gt; and the 63rd bit of the key is stored as the
+ least-significant bit of &lt;CODE&gt;key[7]&lt;/CODE&gt;. The &lt;VAR&gt;key&lt;/VAR&gt; should have the
+ correct parity.
+ &lt;br&gt;&lt;br&gt; &lt;VAR&gt;len&lt;/VAR&gt; is the number of bytes in &lt;VAR&gt;blocks&lt;/VAR&gt;. It should be a
+ multiple of 8 (so that there is a whole number of blocks to encrypt).
+ &lt;VAR&gt;len&lt;/VAR&gt; is limited to a maximum of &lt;CODE&gt;DES_MAXDATA&lt;/CODE&gt; bytes.
+ &lt;br&gt;&lt;br&gt; The result of the encryption replaces the input in &lt;VAR&gt;blocks&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; The &lt;VAR&gt;mode&lt;/VAR&gt; parameter is the bitwise OR of two of the following:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;DES_ENCRYPT&lt;/CODE&gt;
+&lt;DD&gt;
+ This constant, used in the &lt;VAR&gt;mode&lt;/VAR&gt; parameter, specifies that
+ &lt;VAR&gt;blocks&lt;/VAR&gt; is to be encrypted.
+ &lt;br&gt;&lt;br&gt; &lt;DT&gt;&lt;CODE&gt;DES_DECRYPT&lt;/CODE&gt;
+&lt;DD&gt;
+ This constant, used in the &lt;VAR&gt;mode&lt;/VAR&gt; parameter, specifies that
+ &lt;VAR&gt;blocks&lt;/VAR&gt; is to be decrypted.
+ &lt;br&gt;&lt;br&gt; &lt;DT&gt;&lt;CODE&gt;DES_HW&lt;/CODE&gt;
+&lt;DD&gt;
+ This constant, used in the &lt;VAR&gt;mode&lt;/VAR&gt; parameter, asks to use a hardware
+ device. If no hardware device is available, encryption happens anyway,
+ but in software.
+ &lt;br&gt;&lt;br&gt; &lt;DT&gt;&lt;CODE&gt;DES_SW&lt;/CODE&gt;
+&lt;DD&gt;
+ This constant, used in the &lt;VAR&gt;mode&lt;/VAR&gt; parameter, specifies that no
+ hardware device is to be used.
+ &lt;/DL&gt;
+ &lt;br&gt;&lt;br&gt; The result of the function will be one of these values:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;DESERR_NONE&lt;/CODE&gt;
+&lt;DD&gt;
+ The encryption succeeded.
+ &lt;br&gt;&lt;br&gt; &lt;DT&gt;&lt;CODE&gt;DESERR_NOHWDEVICE&lt;/CODE&gt;
+&lt;DD&gt;
+ The encryption succeeded, but there was no hardware device available.
+ &lt;br&gt;&lt;br&gt; &lt;DT&gt;&lt;CODE&gt;DESERR_HWERROR&lt;/CODE&gt;
+&lt;DD&gt;
+ The encryption failed because of a hardware problem.
+ &lt;br&gt;&lt;br&gt; &lt;DT&gt;&lt;CODE&gt;DESERR_BADPARAM&lt;/CODE&gt;
+&lt;DD&gt;
+ The encryption failed because of a bad parameter, for instance &lt;VAR&gt;len&lt;/VAR&gt;
+ is not a multiple of 8 or &lt;VAR&gt;len&lt;/VAR&gt; is larger than &lt;CODE&gt;DES_MAXDATA&lt;/CODE&gt;.
+ &lt;/DL&gt;
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-DES_FAILED" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="int err"/>
+ </prototype>
+ <headers>
+ <header filename = "rpc/des_crypt.h"/>
+ </headers>
+ <synopsis>
+ This macro returns 1 if &lt;VAR&gt;err&lt;/VAR&gt; is a `success' result code from
+ &lt;CODE&gt;ecb_crypt&lt;/CODE&gt; or &lt;CODE&gt;cbc_crypt&lt;/CODE&gt;, and 0 otherwise.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-cbc_crypt" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="char *key"/>
+ <parameter content="char *blocks"/>
+ <parameter content="unsigned len"/>
+ <parameter content="unsigned mode"/>
+ <parameter content="char *ivec"/>
+ </prototype>
+ <headers>
+ <header filename = "rpc/des_crypt.h"/>
+ </headers>
+ <synopsis>
+ &lt;br&gt;&lt;br&gt; The function &lt;CODE&gt;cbc_crypt&lt;/CODE&gt; encrypts or decrypts one or more blocks
+ using DES in Cipher Block Chaining mode.
+ &lt;br&gt;&lt;br&gt; For encryption in CBC mode, each block is exclusive-ored with &lt;VAR&gt;ivec&lt;/VAR&gt;
+ before being encrypted, then &lt;VAR&gt;ivec&lt;/VAR&gt; is replaced with the result of
+ the encryption, then the next block is processed. Decryption is the
+ reverse of this process.
+ &lt;br&gt;&lt;br&gt; 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.
+ &lt;br&gt;&lt;br&gt; Usually, &lt;VAR&gt;ivec&lt;/VAR&gt; 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 &lt;VAR&gt;ivec&lt;/VAR&gt;
+ for decryption. Another possibility is to set &lt;VAR&gt;ivec&lt;/VAR&gt; to 8 zeroes
+ initially, and have the first the block encrypted consist of 8 random
+ bytes.
+ &lt;br&gt;&lt;br&gt; Otherwise, all the parameters are similar to those for &lt;CODE&gt;ecb_crypt&lt;/CODE&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-des_setparity" type="function">
+ <function returntype="void">
+ <prototype>
+ <parameter content="char *key"/>
+ </prototype>
+ <headers>
+ <header filename = "rpc/des_crypt.h"/>
+ </headers>
+ <synopsis>
+ &lt;br&gt;&lt;br&gt; The function &lt;CODE&gt;des_setparity&lt;/CODE&gt; changes the 64-bit &lt;VAR&gt;key&lt;/VAR&gt;, stored
+ packed in 8-bit bytes, to have odd parity by altering the low bits of
+ each byte.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-gethostname" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="char *name"/>
+ <parameter content="size_t size"/>
+ </prototype>
+ <headers>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ This function returns the host name of the system on which it is called,
+ in the array &lt;VAR&gt;name&lt;/VAR&gt;. The &lt;VAR&gt;size&lt;/VAR&gt; argument specifies the size of
+ this array, in bytes. Note that this is &lt;EM&gt;not&lt;/EM&gt; the DNS hostname.
+ If the system participates in DNS, this is the FQDN (see above).
+ &lt;br&gt;&lt;br&gt; The return value is &lt;CODE&gt;0&lt;/CODE&gt; on success and &lt;CODE&gt;-1&lt;/CODE&gt; on failure. In
+ the GNU C library, &lt;CODE&gt;gethostname&lt;/CODE&gt; fails if &lt;VAR&gt;size&lt;/VAR&gt; is not large
+ enough; then you can try again with a larger array. The following
+ &lt;CODE&gt;errno&lt;/CODE&gt; error condition is defined for this function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;ENAMETOOLONG&lt;/CODE&gt;
+&lt;DD&gt;
+ The &lt;VAR&gt;size&lt;/VAR&gt; argument is less than the size of the host name plus one.
+
+ &lt;br&gt;&lt;br&gt; On some systems, there is a symbol for the maximum possible host name
+ length: &lt;CODE&gt;MAXHOSTNAMELEN&lt;/CODE&gt;. It is defined in &lt;TT&gt;sys/param.h&lt;/TT&gt;.
+ But you can't count on this to exist, so it is cleaner to handle
+ failure and try again.
+ &lt;br&gt;&lt;br&gt; &lt;CODE&gt;gethostname&lt;/CODE&gt; stores the beginning of the host name in &lt;VAR&gt;name&lt;/VAR&gt;
+ 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.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-sethostname" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *name"/>
+ <parameter content="size_t length"/>
+ </prototype>
+ <headers>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;sethostname&lt;/CODE&gt; function sets the host name of the system that
+ calls it to &lt;VAR&gt;name&lt;/VAR&gt;, a string with length &lt;VAR&gt;length&lt;/VAR&gt;. Only
+ privileged processes are permitted to do this.
+ &lt;br&gt;&lt;br&gt; Usually &lt;CODE&gt;sethostname&lt;/CODE&gt; gets called just once, at system boot time.
+ Often, the program that calls it sets it to the value it finds in the
+ file &lt;CODE&gt;/etc/hostname&lt;/CODE&gt;.
+ /etc/hostname
+ &lt;br&gt;&lt;br&gt; Be sure to set the host name to the full host name, not just the DNS
+ hostname (see above).
+ &lt;br&gt;&lt;br&gt; The return value is &lt;CODE&gt;0&lt;/CODE&gt; on success and &lt;CODE&gt;-1&lt;/CODE&gt; on failure.
+ The following &lt;CODE&gt;errno&lt;/CODE&gt; error condition is defined for this function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EPERM&lt;/CODE&gt;
+&lt;DD&gt;
+ This process cannot set the host name because it is not privileged.
+
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-getdomainnname" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="char *name"/>
+ <parameter content="size_t length"/>
+ </prototype>
+ <headers>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ domain name
+ domain name
+ &lt;br&gt;&lt;br&gt; &lt;CODE&gt;getdomainname&lt;/CODE&gt; 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 &lt;CODE&gt;gethostname&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; The specifics of this function are analogous to &lt;CODE&gt;gethostname&lt;/CODE&gt;, above.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-setdomainname" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *name"/>
+ <parameter content="size_t length"/>
+ </prototype>
+ <headers>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ domain name
+ domain name
+ &lt;br&gt;&lt;br&gt; &lt;CODE&gt;getdomainname&lt;/CODE&gt; 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 &lt;CODE&gt;sethostname&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; The specifics of this function are analogous to &lt;CODE&gt;sethostname&lt;/CODE&gt;, above.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-gethostid" type="function">
+ <function returntype="long int">
+ <prototype>
+ <parameter content="void"/>
+ </prototype>
+ <headers>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ 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 &lt;CODE&gt;long int&lt;/CODE&gt;. However, on some
+ systems it is a meaningless but unique number which is hard-coded for
+ each machine.
+ &lt;br&gt;&lt;br&gt; This is not widely used. It arose in BSD 4.2, but was dropped in BSD 4.4.
+ It is not required by POSIX.
+ &lt;br&gt;&lt;br&gt; The proper way to query the IP address is to use &lt;CODE&gt;gethostbyname&lt;/CODE&gt;
+ on the results of &lt;CODE&gt;gethostname&lt;/CODE&gt;. For more information on IP addresses,
+ .
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-sethostid" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="long int id"/>
+ </prototype>
+ <headers>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;sethostid&lt;/CODE&gt; function sets the ``host ID'' of the host machine
+ to &lt;VAR&gt;id&lt;/VAR&gt;. Only privileged processes are permitted to do this. Usually
+ it happens just once, at system boot time.
+ &lt;br&gt;&lt;br&gt; 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 &lt;CODE&gt;gethostname&lt;/CODE&gt;. For example,
+ put a record for the system in &lt;TT&gt;/etc/hosts&lt;/TT&gt;.
+ &lt;br&gt;&lt;br&gt; See &lt;CODE&gt;gethostid&lt;/CODE&gt; above for more information on host ids.
+ &lt;br&gt;&lt;br&gt; The return value is &lt;CODE&gt;0&lt;/CODE&gt; on success and &lt;CODE&gt;-1&lt;/CODE&gt; on failure.
+ The following &lt;CODE&gt;errno&lt;/CODE&gt; error conditions are defined for this function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EPERM&lt;/CODE&gt;
+&lt;DD&gt;
+ This process cannot set the host name because it is not privileged.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; 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.
+
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="struct-utsname" type="struct">
+ <structure>
+ <synopsis>
+ The &lt;CODE&gt;utsname&lt;/CODE&gt; structure is used to hold information returned
+ by the &lt;CODE&gt;uname&lt;/CODE&gt; function. It has the following members:
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ <elements>
+ <element content="char sysname[]">
+ <synopsis>
+ This is the name of the operating system in use.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="char release[]">
+ <synopsis>
+ This is the current release level of the operating system implementation.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="char version[]">
+ <synopsis>
+ This is the current version level within the release of the operating
+ system.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="char machine[]">
+ <synopsis>
+ This is a description of the type of hardware that is in use.
+ &lt;br&gt;&lt;br&gt; Some systems provide a mechanism to interrogate the kernel directly for
+ this information. On systems without such a mechanism, the GNU C
+ library fills in this field based on the configuration name that was
+ specified when building and installing the library.
+ &lt;br&gt;&lt;br&gt; GNU uses a three-part name to describe a system configuration; the three
+ parts are &lt;VAR&gt;cpu&lt;/VAR&gt;, &lt;VAR&gt;manufacturer&lt;/VAR&gt; and &lt;VAR&gt;system-type&lt;/VAR&gt;, and they
+ are separated with dashes. Any possible combination of three names is
+ potentially meaningful, but most such combinations are meaningless in
+ practice and even the meaningful ones are not necessarily supported by
+ any particular GNU program.
+ &lt;br&gt;&lt;br&gt; Since the value in &lt;CODE&gt;machine&lt;/CODE&gt; is supposed to describe just the
+ hardware, it consists of the first two parts of the configuration name:
+ &lt;samp&gt;&lt;VAR&gt;cpu&lt;/VAR&gt;-&lt;VAR&gt;manufacturer&lt;/VAR&gt;&lt;/samp&gt;. For example, it might be one of these:
+ &lt;br&gt;&lt;br&gt;
+ &lt;CODE&gt;"sparc-sun"&lt;/CODE&gt;,
+ &lt;CODE&gt;"i386-&lt;VAR&gt;anything&lt;/VAR&gt;"&lt;/CODE&gt;,
+ &lt;CODE&gt;"m68k-hp"&lt;/CODE&gt;,
+ &lt;CODE&gt;"m68k-sony"&lt;/CODE&gt;,
+ &lt;CODE&gt;"m68k-sun"&lt;/CODE&gt;,
+ &lt;CODE&gt;"mips-dec"&lt;/CODE&gt;
+
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="char nodename[]">
+ <synopsis>
+ This is the host name of this particular computer. In the GNU C
+ library, the value is the same as that returned by &lt;CODE&gt;gethostname&lt;/CODE&gt;;
+ see Host Identification.
+ &lt;br&gt;&lt;br&gt; @ gethostname() is implemented with a call to uname().
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ </elements>
+ </structure>
+ </construct>
+ <construct id="function-uname" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="struct utsname *info"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/utsname.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;uname&lt;/CODE&gt; function fills in the structure pointed to by
+ &lt;VAR&gt;info&lt;/VAR&gt; with information about the operating system and host machine.
+ A non-negative value indicates that the data was successfully stored.
+ &lt;br&gt;&lt;br&gt; &lt;CODE&gt;-1&lt;/CODE&gt; as the value indicates an error. The only error possible is
+ &lt;CODE&gt;EFAULT&lt;/CODE&gt;, which we normally don't mention as it is always a
+ possibility.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="struct-fstab" type="struct">
+ <structure>
+ <synopsis>
+ This structure is used with the &lt;CODE&gt;getfsent&lt;/CODE&gt;, &lt;CODE&gt;getfsspec&lt;/CODE&gt;, and
+ &lt;CODE&gt;getfsfile&lt;/CODE&gt; functions.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ <elements>
+ <element content="char *fs_spec">
+ <synopsis>
+ This element describes the device from which the filesystem is mounted.
+ Normally this is the name of a special device, such as a hard disk
+ partition, but it could also be a more or less generic string. For
+ NFS it would be a hostname and directory name combination.
+ &lt;br&gt;&lt;br&gt; Even though the element is not declared &lt;CODE&gt;const&lt;/CODE&gt; it shouldn't be
+ modified. The missing &lt;CODE&gt;const&lt;/CODE&gt; has historic reasons, since this
+ function predates ISO C. The same is true for the other string
+ elements of this structure.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="char *fs_file">
+ <synopsis>
+ This describes the mount point on the local system. I.e., accessing any
+ file in this filesystem has implicitly or explicitly this string as a
+ prefix.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="char *fs_vfstype">
+ <synopsis>
+ This is the type of the filesystem. Depending on what the underlying
+ kernel understands it can be any string.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="char *fs_mntops">
+ <synopsis>
+ This is a string containing options passed to the kernel with the
+ &lt;CODE&gt;mount&lt;/CODE&gt; call. Again, this can be almost anything. There can be
+ more than one option, separated from the others by a comma. Each option
+ consists of a name and an optional value part, introduced by an &lt;CODE&gt;=&lt;/CODE&gt;
+ character.
+ &lt;br&gt;&lt;br&gt; If the value of this element must be processed it should ideally be done
+ using the &lt;CODE&gt;getsubopt&lt;/CODE&gt; function; see Suboptions.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="const char *fs_type">
+ <synopsis>
+ This name is poorly chosen. This element points to a string (possibly
+ in the &lt;CODE&gt;fs_mntops&lt;/CODE&gt; string) which describes the modes with which the
+ filesystem is mounted. &lt;TT&gt;fstab&lt;/TT&gt; defines five macros to describe the
+ possible values:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ </synopsis>
+ </element>
+ <element content="FSTAB_RW">
+ <synopsis>
+ The filesystems gets mounted with read and write enabled.
+ </synopsis>
+ </element>
+ <element content="FSTAB_RQ">
+ <synopsis>
+ The filesystems gets mounted with read and write enabled. Write access
+ is restricted by quotas.
+ </synopsis>
+ </element>
+ <element content="FSTAB_RO">
+ <synopsis>
+ The filesystem gets mounted read-only.
+ </synopsis>
+ </element>
+ <element content="FSTAB_SW">
+ <synopsis>
+ This is not a real filesystem, it is a swap device.
+ </synopsis>
+ </element>
+ <element content="FSTAB_XX">
+ <synopsis>
+ This entry from the &lt;TT&gt;fstab&lt;/TT&gt; file is totally ignored.
+ &lt;/DL&gt;
+ &lt;br&gt;&lt;br&gt; Testing for equality with these value must happen using &lt;CODE&gt;strcmp&lt;/CODE&gt;
+ since these are all strings. Comparing the pointer will probably always
+ fail.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="int fs_freq">
+ <synopsis>
+ This element describes the dump frequency in days.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ </elements>
+ </structure>
+ </construct>
+ <construct id="function-setfsent" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="void"/>
+ </prototype>
+ <headers>
+ <header filename = "fstab.h"/>
+ </headers>
+ <synopsis>
+ This function makes sure that the internal read pointer for the
+ &lt;TT&gt;fstab&lt;/TT&gt; file is at the beginning of the file. This is done by
+ either opening the file or resetting the read pointer.
+ &lt;br&gt;&lt;br&gt; Since the file handle is internal to the libc this function is not
+ thread-safe.
+ &lt;br&gt;&lt;br&gt; This function returns a non-zero value if the operation was successful
+ and the &lt;CODE&gt;getfs*&lt;/CODE&gt; functions can be used to read the entries of the
+ file.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-endfsent" type="function">
+ <function returntype="void">
+ <prototype>
+ <parameter content="void"/>
+ </prototype>
+ <headers>
+ <header filename = "fstab.h"/>
+ </headers>
+ <synopsis>
+ This function makes sure that all resources acquired by a prior call to
+ &lt;CODE&gt;setfsent&lt;/CODE&gt; (explicitly or implicitly by calling &lt;CODE&gt;getfsent&lt;/CODE&gt;) are
+ freed.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-getfsent" type="function">
+ <function returntype="struct fstab *">
+ <prototype>
+ <parameter content="void"/>
+ </prototype>
+ <headers>
+ <header filename = "fstab.h"/>
+ </headers>
+ <synopsis>
+ This function returns the next entry of the &lt;TT&gt;fstab&lt;/TT&gt; file. If this
+ is the first call to any of the functions handling &lt;TT&gt;fstab&lt;/TT&gt; since
+ program start or the last call of &lt;CODE&gt;endfsent&lt;/CODE&gt;, the file will be
+ opened.
+ &lt;br&gt;&lt;br&gt; The function returns a pointer to a variable of type &lt;CODE&gt;struct
+ fstab&lt;/CODE&gt;. This variable is shared by all threads and therefore this
+ function is not thread-safe. If an error occurred &lt;CODE&gt;getfsent&lt;/CODE&gt;
+ returns a &lt;CODE&gt;NULL&lt;/CODE&gt; pointer.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-getfsspec" type="function">
+ <function returntype="struct fstab *">
+ <prototype>
+ <parameter content="const char *name"/>
+ </prototype>
+ <headers>
+ <header filename = "fstab.h"/>
+ </headers>
+ <synopsis>
+ This function returns the next entry of the &lt;TT&gt;fstab&lt;/TT&gt; file which has
+ a string equal to &lt;VAR&gt;name&lt;/VAR&gt; pointed to by the &lt;CODE&gt;fs_spec&lt;/CODE&gt; 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
+ &lt;TT&gt;fstab&lt;/TT&gt; since program start or the last call of &lt;CODE&gt;endfsent&lt;/CODE&gt;,
+ the file will be opened.
+ &lt;br&gt;&lt;br&gt; The function returns a pointer to a variable of type &lt;CODE&gt;struct
+ fstab&lt;/CODE&gt;. This variable is shared by all threads and therefore this
+ function is not thread-safe. If an error occurred &lt;CODE&gt;getfsent&lt;/CODE&gt;
+ returns a &lt;CODE&gt;NULL&lt;/CODE&gt; pointer.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-getfsfile" type="function">
+ <function returntype="struct fstab *">
+ <prototype>
+ <parameter content="const char *name"/>
+ </prototype>
+ <headers>
+ <header filename = "fstab.h"/>
+ </headers>
+ <synopsis>
+ This function returns the next entry of the &lt;TT&gt;fstab&lt;/TT&gt; file which has
+ a string equal to &lt;VAR&gt;name&lt;/VAR&gt; pointed to by the &lt;CODE&gt;fs_file&lt;/CODE&gt; 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
+ &lt;TT&gt;fstab&lt;/TT&gt; since program start or the last call of &lt;CODE&gt;endfsent&lt;/CODE&gt;,
+ the file will be opened.
+ &lt;br&gt;&lt;br&gt; The function returns a pointer to a variable of type &lt;CODE&gt;struct
+ fstab&lt;/CODE&gt;. This variable is shared by all threads and therefore this
+ function is not thread-safe. If an error occurred &lt;CODE&gt;getfsent&lt;/CODE&gt;
+ returns a &lt;CODE&gt;NULL&lt;/CODE&gt; pointer.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="struct-mntent" type="struct">
+ <structure>
+ <synopsis>
+ This structure is used with the &lt;CODE&gt;getmntent&lt;/CODE&gt;, &lt;CODE&gt;getmntent_t&lt;/CODE&gt;,
+ &lt;CODE&gt;addmntent&lt;/CODE&gt;, and &lt;CODE&gt;hasmntopt&lt;/CODE&gt; functions.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ <elements>
+ <element content="char *mnt_fsname">
+ <synopsis>
+ This element contains a pointer to a string describing the name of the
+ special device from which the filesystem is mounted. It corresponds to
+ the &lt;CODE&gt;fs_spec&lt;/CODE&gt; element in &lt;CODE&gt;struct fstab&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="char *mnt_dir">
+ <synopsis>
+ This element points to a string describing the mount point of the
+ filesystem. It corresponds to the &lt;CODE&gt;fs_file&lt;/CODE&gt; element in
+ &lt;CODE&gt;struct fstab&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="char *mnt_type">
+ <synopsis>
+ &lt;CODE&gt;mnt_type&lt;/CODE&gt; describes the filesystem type and is therefore
+ equivalent to &lt;CODE&gt;fs_vfstype&lt;/CODE&gt; in &lt;CODE&gt;struct fstab&lt;/CODE&gt;. &lt;TT&gt;mntent.h&lt;/TT&gt;
+ defines a few symbolic names for some of the values this string can have.
+ But since the kernel can support arbitrary filesystems it does not
+ make much sense to give them symbolic names. If one knows the symbol
+ name one also knows the filesystem name. Nevertheless here follows the
+ list of the symbols provided in &lt;TT&gt;mntent.h&lt;/TT&gt;.
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ </synopsis>
+ </element>
+ <element content="MNTTYPE_IGNORE">
+ <synopsis>
+ This symbol expands to &lt;CODE&gt;"ignore"&lt;/CODE&gt;. The value is sometime used in
+ &lt;TT&gt;fstab&lt;/TT&gt; files to make sure entries are not used without removing them.
+ </synopsis>
+ </element>
+ <element content="MNTTYPE_NFS">
+ <synopsis>
+ Expands to &lt;CODE&gt;"nfs"&lt;/CODE&gt;. Using this macro sometimes could make sense
+ since it names the default NFS implementation, in case both version 2
+ and 3 are supported.
+ </synopsis>
+ </element>
+ <element content="MNTTYPE_SWAP">
+ <synopsis>
+ This symbol expands to &lt;CODE&gt;"swap"&lt;/CODE&gt;. It names the special &lt;TT&gt;fstab&lt;/TT&gt;
+ entry which names one of the possibly multiple swap partitions.
+ &lt;/DL&gt;
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="char *mnt_opts">
+ <synopsis>
+ The element contains a string describing the options used while mounting
+ the filesystem. As for the equivalent element &lt;CODE&gt;fs_mntops&lt;/CODE&gt; of
+ &lt;CODE&gt;struct fstab&lt;/CODE&gt; it is best to use the function &lt;CODE&gt;getsubopt&lt;/CODE&gt;
+ to access the parts of this string.
+ &lt;br&gt;&lt;br&gt; The &lt;TT&gt;mntent.h&lt;/TT&gt; file defines a number of macros with string values
+ which correspond to some of the options understood by the kernel. There
+ might be many more options which are possible so it doesn't make much sense
+ to rely on these macros but to be consistent here is the list:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ </synopsis>
+ </element>
+ <element content="MNTOPT_DEFAULTS">
+ <synopsis>
+ Expands to &lt;CODE&gt;"defaults"&lt;/CODE&gt;. This option should be used alone since it
+ indicates all values for the customizable values are chosen to be the
+ default.
+ </synopsis>
+ </element>
+ <element content="MNTOPT_RO">
+ <synopsis>
+ Expands to &lt;CODE&gt;"ro"&lt;/CODE&gt;. See the &lt;CODE&gt;FSTAB_RO&lt;/CODE&gt; value, it means the
+ filesystem is mounted read-only.
+ </synopsis>
+ </element>
+ <element content="MNTOPT_RW">
+ <synopsis>
+ Expand to &lt;CODE&gt;"rw"&lt;/CODE&gt;. See the &lt;CODE&gt;FSTAB_RW&lt;/CODE&gt; value, it means the
+ filesystem is mounted with read and write permissions.
+ </synopsis>
+ </element>
+ <element content="MNTOPT_SUID">
+ <synopsis>
+ Expands to &lt;CODE&gt;"suid"&lt;/CODE&gt;. This means that the SUID bit is respected when a program from the filesystem is
+ started.
+ </synopsis>
+ </element>
+ <element content="MNTOPT_NOSUID">
+ <synopsis>
+ Expands to &lt;CODE&gt;"nosuid"&lt;/CODE&gt;. This is the opposite of &lt;CODE&gt;MNTOPT_SUID&lt;/CODE&gt;,
+ the SUID bit for all files from the filesystem is ignored.
+ </synopsis>
+ </element>
+ <element content="MNTOPT_NOAUTO">
+ <synopsis>
+ Expands to &lt;CODE&gt;"noauto"&lt;/CODE&gt;. At startup time the &lt;CODE&gt;mount&lt;/CODE&gt; program
+ will ignore this entry if it is started with the &lt;CODE&gt;-a&lt;/CODE&gt; option to
+ mount all filesystems mentioned in the &lt;TT&gt;fstab&lt;/TT&gt; file.
+ &lt;/DL&gt;
+ &lt;br&gt;&lt;br&gt; As for the &lt;CODE&gt;FSTAB_*&lt;/CODE&gt; entries introduced above it is important to
+ use &lt;CODE&gt;strcmp&lt;/CODE&gt; to check for equality.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="mnt_freq">
+ <synopsis>
+ This elements corresponds to &lt;CODE&gt;fs_freq&lt;/CODE&gt; and also specifies the
+ frequency in days in which dumps are made.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ </elements>
+ </structure>
+ </construct>
+ <construct id="function-setmntent" type="function">
+ <function returntype="FILE *">
+ <prototype>
+ <parameter content="const char *file"/>
+ <parameter content="const char *mode"/>
+ </prototype>
+ <headers>
+ <header filename = "mntent.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;setmntent&lt;/CODE&gt; function prepares the file named &lt;VAR&gt;FILE&lt;/VAR&gt; which
+ must be in the format of a &lt;TT&gt;fstab&lt;/TT&gt; and &lt;TT&gt;mtab&lt;/TT&gt; file for the
+ upcoming processing through the other functions of the family. The
+ &lt;VAR&gt;mode&lt;/VAR&gt; parameter can be chosen in the way the &lt;VAR&gt;opentype&lt;/VAR&gt;
+ parameter for &lt;CODE&gt;fopen&lt;/CODE&gt; can be chosen. If
+ the file is opened for writing the file is also allowed to be empty.
+ &lt;br&gt;&lt;br&gt; If the file was successfully opened &lt;CODE&gt;setmntent&lt;/CODE&gt; returns a file
+ descriptor for future use. Otherwise the return value is &lt;CODE&gt;NULL&lt;/CODE&gt;
+ and &lt;CODE&gt;errno&lt;/CODE&gt; is set accordingly.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-endmntent" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="FILE *stream"/>
+ </prototype>
+ <headers>
+ <header filename = "mntent.h"/>
+ </headers>
+ <synopsis>
+ This function takes for the &lt;VAR&gt;stream&lt;/VAR&gt; parameter a file handle which
+ previously was returned from the &lt;CODE&gt;setmntent&lt;/CODE&gt; call.
+ &lt;CODE&gt;endmntent&lt;/CODE&gt; closes the stream and frees all resources.
+ &lt;br&gt;&lt;br&gt; The return value is 1 unless an error occurred in which case it
+ is 0.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-getmntent" type="function">
+ <function returntype="struct mntent *">
+ <prototype>
+ <parameter content="FILE *stream"/>
+ </prototype>
+ <headers>
+ <header filename = "mntent.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;getmntent&lt;/CODE&gt; function takes as the parameter a file handle
+ previously returned by successful call to &lt;CODE&gt;setmntent&lt;/CODE&gt;. It returns
+ a pointer to a static variable of type &lt;CODE&gt;struct mntent&lt;/CODE&gt; which is
+ filled with the information from the next entry from the file currently
+ read.
+ &lt;br&gt;&lt;br&gt; 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 &lt;CODE&gt;getmntent&lt;/CODE&gt;
+ function takes care of the decoding while reading the entries back in.
+ &lt;CODE&gt;'\040'&lt;/CODE&gt; is used to encode a space character, &lt;CODE&gt;'\011'&lt;/CODE&gt; to
+ encode a tab character, &lt;CODE&gt;'\012'&lt;/CODE&gt; to encode a newline character,
+ and &lt;CODE&gt;'\\'&lt;/CODE&gt; to encode a backslash.
+ &lt;br&gt;&lt;br&gt; If there was an error or the end of the file is reached the return value
+ is &lt;CODE&gt;NULL&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; This function is not thread-safe since all calls to this function return
+ a pointer to the same static variable. &lt;CODE&gt;getmntent_r&lt;/CODE&gt; should be
+ used in situations where multiple threads access the file.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-getmntent_r" type="function">
+ <function returntype="struct mntent *">
+ <prototype>
+ <parameter content="FILE *stream"/>
+ <parameter content="struct mentent *result"/>
+ <parameter content="char *buffer"/>
+ <parameter content="int bufsize"/>
+ </prototype>
+ <headers>
+ <header filename = "mntent.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;getmntent_r&lt;/CODE&gt; function is the reentrant variant of
+ &lt;CODE&gt;getmntent&lt;/CODE&gt;. 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 &lt;VAR&gt;result&lt;/VAR&gt; parameter. Additional information (e.g.,
+ the strings pointed to by the elements of the result) are kept in the
+ buffer of size &lt;VAR&gt;bufsize&lt;/VAR&gt; pointed to by &lt;VAR&gt;buffer&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; Escaped characters (space, tab, backslash) are converted back in the
+ same way as it happens for &lt;CODE&gt;getmentent&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; The function returns a &lt;CODE&gt;NULL&lt;/CODE&gt; pointer in error cases. Errors could be:
+ &lt;OL&gt;
+ &lt;LI&gt;
+ error while reading the file,
+ &lt;LI&gt;
+ end of file reached,
+ &lt;LI&gt;
+ &lt;VAR&gt;bufsize&lt;/VAR&gt; is too small for reading a complete new entry.
+ &lt;/OL&gt;
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-addmntent" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="FILE *stream"/>
+ <parameter content="const struct mntent *mnt"/>
+ </prototype>
+ <headers>
+ <header filename = "mntent.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;addmntent&lt;/CODE&gt; function allows adding a new entry to the file
+ previously opened with &lt;CODE&gt;setmntent&lt;/CODE&gt;. 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.
+ &lt;br&gt;&lt;br&gt; 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.
+ &lt;br&gt;&lt;br&gt; 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 &lt;CODE&gt;getmntent&lt;/CODE&gt; description above.
+ &lt;br&gt;&lt;br&gt; This function returns 0 in case the operation was successful.
+ Otherwise the return value is 1 and &lt;CODE&gt;errno&lt;/CODE&gt; is set
+ appropriately.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-hasmntopt" type="function">
+ <function returntype="char *">
+ <prototype>
+ <parameter content="const struct mntent *mnt"/>
+ <parameter content="const char *opt"/>
+ </prototype>
+ <headers>
+ <header filename = "mntent.h"/>
+ </headers>
+ <synopsis>
+ This function can be used to check whether the string pointed to by the
+ &lt;CODE&gt;mnt_opts&lt;/CODE&gt; element of the variable pointed to by &lt;VAR&gt;mnt&lt;/VAR&gt; contains
+ the option &lt;VAR&gt;opt&lt;/VAR&gt;. If this is true a pointer to the beginning of the
+ option in the &lt;CODE&gt;mnt_opts&lt;/CODE&gt; element is returned. If no such option
+ exists the function returns &lt;CODE&gt;NULL&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; 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
+ &lt;CODE&gt;getsubopt&lt;/CODE&gt; function to iterate over all options in the string.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-mount" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *special_file"/>
+ <parameter content="const char *dir"/>
+ <parameter content="const char *fstype"/>
+ <parameter content="unsigned long int options"/>
+ <parameter content="const void *data"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/mount.h"/>
+ </headers>
+ <synopsis>
+ &lt;br&gt;&lt;br&gt; &lt;CODE&gt;mount&lt;/CODE&gt; mounts or remounts a filesystem. The two operations are
+ quite different and are merged rather unnaturally into this one function.
+ The &lt;CODE&gt;MS_REMOUNT&lt;/CODE&gt; option, explained below, determines whether
+ &lt;CODE&gt;mount&lt;/CODE&gt; mounts or remounts.
+ &lt;br&gt;&lt;br&gt; For a mount, the filesystem on the block device represented by the
+ device special file named &lt;VAR&gt;special_file&lt;/VAR&gt; gets mounted over the mount
+ point &lt;VAR&gt;dir&lt;/VAR&gt;. This means that the directory &lt;VAR&gt;dir&lt;/VAR&gt; (along with any
+ files in it) is no longer visible; in its place (and still with the name
+ &lt;VAR&gt;dir&lt;/VAR&gt;) is the root directory of the filesystem on the device.
+ &lt;br&gt;&lt;br&gt; As an exception, if the filesystem type (see below) is one which is not
+ based on a device (e.g. ``proc''), &lt;CODE&gt;mount&lt;/CODE&gt; instantiates a
+ filesystem and mounts it over &lt;VAR&gt;dir&lt;/VAR&gt; and ignores &lt;VAR&gt;special_file&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; For a remount, &lt;VAR&gt;dir&lt;/VAR&gt; specifies the mount point where the filesystem
+ to be remounted is (and remains) mounted and &lt;VAR&gt;special_file&lt;/VAR&gt; 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.
+ &lt;br&gt;&lt;br&gt; For a mount, you must identify the type of the filesystem as
+ &lt;VAR&gt;fstype&lt;/VAR&gt;. 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 &lt;CODE&gt;proc&lt;/CODE&gt; filesystem, the list of possible values is in the
+ file &lt;TT&gt;filesystems&lt;/TT&gt; in the &lt;CODE&gt;proc&lt;/CODE&gt; filesystem (e.g. type
+ &lt;KBD&gt;cat /proc/filesystems&lt;/KBD&gt; to see the list). With a Linux kernel, the
+ types of filesystems that &lt;CODE&gt;mount&lt;/CODE&gt; 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
+ &lt;VAR&gt;fstype&lt;/VAR&gt; is &lt;CODE&gt;ext2&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; For a remount, &lt;CODE&gt;mount&lt;/CODE&gt; ignores &lt;VAR&gt;fstype&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; &lt;VAR&gt;options&lt;/VAR&gt; 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 &lt;CODE&gt;MS_RDONLY&lt;/CODE&gt;) can be overridden for individual
+ file accesses via &lt;CODE&gt;ioctl&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; &lt;VAR&gt;options&lt;/VAR&gt; is a bit string with bit fields defined using the
+ following mask and masked value macros:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;MS_MGC_MASK&lt;/CODE&gt;
+&lt;DD&gt;
+ This multibit field contains a magic number. If it does not have the value
+ &lt;CODE&gt;MS_MGC_VAL&lt;/CODE&gt;, &lt;CODE&gt;mount&lt;/CODE&gt; assumes all the following bits are zero and
+ the &lt;VAR&gt;data&lt;/VAR&gt; argument is a null string, regardless of their actual values.
+ &lt;br&gt;&lt;br&gt; &lt;DT&gt;&lt;CODE&gt;MS_REMOUNT&lt;/CODE&gt;
+&lt;DD&gt;
+ This bit on means to remount the filesystem. Off means to mount it.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; MS_RDONLY
+ This bit on specifies that no writing to the filesystem shall be allowed
+ while it is mounted. This cannot be overridden by &lt;CODE&gt;ioctl&lt;/CODE&gt;. This
+ option is available on nearly all filesystems.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; 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 &lt;CODE&gt;ioctl&lt;/CODE&gt;.
+ This option is a relatively new invention and is not available on many
+ filesystems.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; 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 &lt;CODE&gt;ioctl&lt;/CODE&gt;. This is a relatively new invention and is not
+ available on many filesystems.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; MS_NOSUID
+ This bit on specifies that Setuid and Setgid permissions on files in the
+ filesystem shall be ignored while it is mounted.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; MS_NOEXEC
+ This bit on specifies that no files in the filesystem shall be executed
+ while the filesystem is mounted.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; MS_NODEV
+ This bit on specifies that no device special files in the filesystem
+ shall be accessible while the filesystem is mounted.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; 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.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; MS_MANDLOCK
+ This bit on specifies that mandatory locks on files shall be permitted while
+ the filesystem is mounted.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; 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.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; 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.
+ &lt;br&gt;&lt;br&gt; &lt;br&gt;&lt;br&gt;
+ &lt;br&gt;&lt;br&gt; Any bits not covered by the above masks should be set off; otherwise,
+ results are undefined.
+ &lt;br&gt;&lt;br&gt; The meaning of &lt;VAR&gt;data&lt;/VAR&gt; depends on the filesystem type and is controlled
+ entirely by the filesystem driver in the kernel.
+ &lt;br&gt;&lt;br&gt; Example:
+ &lt;br&gt;&lt;br&gt; &lt;pre&gt;&lt;br&gt;
+ &lt;br&gt;
+ #include &lt;sys/mount.h&gt;&lt;br&gt;
+ &lt;br&gt;&lt;br&gt; mount("/dev/hdb", "/cdrom", MS_MGC_VAL | MS_RDONLY | MS_NOSUID, "");&lt;br&gt;
+ &lt;br&gt;&lt;br&gt; mount("/dev/hda2", "/mnt", MS_MGC_VAL | MS_REMOUNT, "");&lt;br&gt;
+ &lt;br&gt;&lt;br&gt; &lt;br&gt;
+ &lt;/pre&gt;
+ &lt;br&gt;&lt;br&gt; Appropriate arguments for &lt;CODE&gt;mount&lt;/CODE&gt; are conventionally recorded in
+ the &lt;TT&gt;fstab&lt;/TT&gt; table. .
+ &lt;br&gt;&lt;br&gt; The return value is zero if the mount or remount is successful. Otherwise,
+ it is &lt;CODE&gt;-1&lt;/CODE&gt; and &lt;CODE&gt;errno&lt;/CODE&gt; is set appropriately. The values of
+ &lt;CODE&gt;errno&lt;/CODE&gt; are filesystem dependent, but here is a general list:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;LI&gt; EPERM
+ The process is not superuser.
+ &lt;LI&gt; ENODEV
+ The file system type &lt;VAR&gt;fstype&lt;/VAR&gt; is not known to the kernel.
+ &lt;LI&gt; ENOTBLK
+ The file &lt;VAR&gt;dev&lt;/VAR&gt; is not a block device special file.
+ &lt;LI&gt; EBUSY
+ &lt;br&gt;&lt;br&gt; &lt;OL&gt;
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt;
+ The device is already mounted.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt;
+ The mount point is busy. (E.g. it is some process' working directory or
+ has a filesystem mounted on it already).
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt;
+ The request is to remount read-only, but there are files open for write.
+ &lt;/OL&gt;
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EINVAL
+ &lt;OL&gt;
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt;
+ A remount was attempted, but there is no filesystem mounted over the
+ specified mount point.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt;
+ The supposed filesystem has an invalid superblock.
+ &lt;br&gt;&lt;br&gt; &lt;/OL&gt;
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EACCES
+ &lt;OL&gt;
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt;
+ 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
+ &lt;CODE&gt;MS_RDONLY&lt;/CODE&gt; bit off).
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt;
+ &lt;VAR&gt;special_file&lt;/VAR&gt; or &lt;VAR&gt;dir&lt;/VAR&gt; is not accessible due to file permissions.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt;
+ &lt;VAR&gt;special_file&lt;/VAR&gt; is not accessible because it is in a filesystem that is
+ mounted with the &lt;CODE&gt;MS_NODEV&lt;/CODE&gt; option.
+ &lt;br&gt;&lt;br&gt; &lt;/OL&gt;
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EM_FILE
+ The table of dummy devices is full. &lt;CODE&gt;mount&lt;/CODE&gt; needs to create a
+ dummy device (aka ``unnamed'' device) if the filesystem being mounted is
+ not one that uses a device.
+ &lt;br&gt;&lt;br&gt;
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-umount2" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *file"/>
+ <parameter content="int flags"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/mount.h"/>
+ </headers>
+ <synopsis>
+ &lt;br&gt;&lt;br&gt; &lt;CODE&gt;umount2&lt;/CODE&gt; unmounts a filesystem.
+ &lt;br&gt;&lt;br&gt; 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 &lt;VAR&gt;file&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; &lt;VAR&gt;flags&lt;/VAR&gt; contains the one-bit field identified by the following
+ mask macro:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;br&gt;&lt;br&gt; &lt;DT&gt;&lt;CODE&gt;MNT_FORCE&lt;/CODE&gt;
+&lt;DD&gt;
+ 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, &lt;CODE&gt;umount2&lt;/CODE&gt; fails with &lt;CODE&gt;errno&lt;/CODE&gt; = &lt;CODE&gt;EBUSY&lt;/CODE&gt;. Depending
+ on the filesystem, this may override all, some, or no busy conditions.
+ &lt;br&gt;&lt;br&gt;
+ &lt;br&gt;&lt;br&gt; All other bits in &lt;VAR&gt;flags&lt;/VAR&gt; should be set to zero; otherwise, the result
+ is undefined.
+ &lt;br&gt;&lt;br&gt; Example:
+ &lt;br&gt;&lt;br&gt; &lt;pre&gt;&lt;br&gt;
+ &lt;br&gt;
+ #include &lt;sys/mount.h&gt;&lt;br&gt;
+ &lt;br&gt;&lt;br&gt; umount2("/mnt", MNT_FORCE);&lt;br&gt;
+ &lt;br&gt;&lt;br&gt; umount2("/dev/hdd1", 0);&lt;br&gt;
+ &lt;br&gt;&lt;br&gt; &lt;br&gt;
+ &lt;/pre&gt;
+ &lt;br&gt;&lt;br&gt; After the filesystem is unmounted, the directory that was the mount point
+ is visible, as are any files in it.
+ &lt;br&gt;&lt;br&gt; As part of unmounting, &lt;CODE&gt;umount2&lt;/CODE&gt; syncs the filesystem.
+ &lt;br&gt;&lt;br&gt; If the unmounting is successful, the return value is zero. Otherwise, it
+ is &lt;CODE&gt;-1&lt;/CODE&gt; and &lt;CODE&gt;errno&lt;/CODE&gt; is set accordingly:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;LI&gt; EPERM
+ The process is not superuser.
+ &lt;LI&gt; 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 &lt;CODE&gt;MNT_FORCE&lt;/CODE&gt; option.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EINVAL
+ &lt;VAR&gt;file&lt;/VAR&gt; validly refers to a file, but that file is neither a mount
+ point nor a device special file of a currently mounted filesystem.
+ &lt;br&gt;&lt;br&gt;
+&lt;/DL&gt;
+ &lt;br&gt;&lt;br&gt; This function is not available on all systems.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-umount" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *file"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/mount.h"/>
+ </headers>
+ <synopsis>
+ &lt;br&gt;&lt;br&gt; &lt;CODE&gt;umount&lt;/CODE&gt; does the same thing as &lt;CODE&gt;umount2&lt;/CODE&gt; with &lt;VAR&gt;flags&lt;/VAR&gt; set
+ to zeroes. It is more widely available than &lt;CODE&gt;umount2&lt;/CODE&gt; but since it
+ lacks the possibility to forcefully unmount a filesystem is deprecated
+ when &lt;CODE&gt;umount2&lt;/CODE&gt; is also available.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-sysctl" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="int *names"/>
+ <parameter content="int nlen"/>
+ <parameter content="void *oldval"/>
+ <parameter content="size_t *oldlenp"/>
+ <parameter content="void *newval"/>
+ <parameter content="size_t newlen"/>
+ </prototype>
+ <headers>
+ <header filename = "sysctl.h"/>
+ </headers>
+ <synopsis>
+ &lt;br&gt;&lt;br&gt; &lt;CODE&gt;sysctl&lt;/CODE&gt; 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:
+ &lt;br&gt;&lt;br&gt; &lt;OL&gt;
+ &lt;LI&gt; network domain name
+ &lt;LI&gt; paging parameters
+ &lt;LI&gt; network Address Resolution Protocol timeout time
+ &lt;LI&gt; maximum number of files that may be open
+ &lt;LI&gt; root filesystem device
+ &lt;LI&gt; when kernel was built
+ &lt;/OL&gt;
+ &lt;br&gt;&lt;br&gt; 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.
+ &lt;br&gt;&lt;br&gt; The system parameters with which &lt;CODE&gt;syslog&lt;/CODE&gt; 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 &lt;TT&gt;sysctl.h&lt;/TT&gt;. &lt;VAR&gt;names&lt;/VAR&gt; is the path, in
+ the form of an array of integers. Each component of the path is one
+ element of the array, in order. &lt;VAR&gt;nlen&lt;/VAR&gt; is the number of components
+ in the path.
+ &lt;br&gt;&lt;br&gt; For example, the first component of the path for all the paging
+ parameters is the value &lt;CODE&gt;CTL_VM&lt;/CODE&gt;. For the free page thresholds, the
+ second component of the path is &lt;CODE&gt;VM_FREEPG&lt;/CODE&gt;. So to get the free
+ page threshold values, make &lt;VAR&gt;names&lt;/VAR&gt; an array containing the two
+ elements &lt;CODE&gt;CTL_VM&lt;/CODE&gt; and &lt;CODE&gt;VM_FREEPG&lt;/CODE&gt; and make &lt;VAR&gt;nlen&lt;/VAR&gt; = 2.
+ &lt;br&gt;&lt;br&gt; &lt;br&gt;&lt;br&gt; 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.
+ &lt;br&gt;&lt;br&gt; In any case, you identify a place to return the parameter's value with
+ &lt;VAR&gt;oldval&lt;/VAR&gt; and specify the amount of storage available at that
+ location as *&lt;VAR&gt;oldlenp&lt;/VAR&gt;. *&lt;VAR&gt;oldlenp&lt;/VAR&gt; does double duty because it
+ is also the output location that contains the actual length of the
+ returned value.
+ &lt;br&gt;&lt;br&gt; If you don't want the parameter value returned, specify a null pointer
+ for &lt;VAR&gt;oldval&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; To set the parameter, specify the address and length of the new value
+ as &lt;VAR&gt;newval&lt;/VAR&gt; and &lt;VAR&gt;newlen&lt;/VAR&gt;. If you don't want to set the parameter,
+ specify a null pointer as &lt;VAR&gt;newval&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; If you get and set a parameter in the same &lt;CODE&gt;sysctl&lt;/CODE&gt; call, the value
+ returned is the value of the parameter before it was set.
+ &lt;br&gt;&lt;br&gt; 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.
+ &lt;br&gt;&lt;br&gt; &lt;br&gt;&lt;br&gt; &lt;CODE&gt;sysctl&lt;/CODE&gt; returns a zero return value if it succeeds. Otherwise, it
+ returns &lt;CODE&gt;-1&lt;/CODE&gt; and sets &lt;CODE&gt;errno&lt;/CODE&gt; appropriately. Besides the
+ failures that apply to all system calls, the following are the
+ &lt;CODE&gt;errno&lt;/CODE&gt; codes for all possible failures:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EPERM&lt;/CODE&gt;
+&lt;DD&gt;
+ 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.
+ &lt;LI&gt; ENOTDIR
+ There is no system parameter corresponding to &lt;VAR&gt;name&lt;/VAR&gt;.
+ &lt;LI&gt; EFAULT
+ &lt;VAR&gt;oldval&lt;/VAR&gt; is not null, which means the process wanted to read the parameter,
+ but *&lt;VAR&gt;oldlenp&lt;/VAR&gt; is zero, so there is no place to return it.
+ &lt;LI&gt; EINVAL
+ &lt;OL&gt;
+ &lt;LI&gt;
+ The process attempted to set a system parameter to a value that is not valid
+ for that parameter.
+ &lt;LI&gt;
+ The space provided for the return of the system parameter is not the right
+ size for that parameter.
+ &lt;/OL&gt;
+ &lt;LI&gt; ENOMEM
+ This value may be returned instead of the more correct &lt;CODE&gt;EINVAL&lt;/CODE&gt; in some
+ cases where the space provided for the return of the system parameter is too
+ small.
+ &lt;br&gt;&lt;br&gt;
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="dtype-uid_t" type="dtype">
+ <structure>
+ </structure>
+ </construct>
+ <construct id="dtype-gid_t" type="dtype">
+ <structure>
+ </structure>
+ </construct>
+ <construct id="function-getuid" type="function">
+ <function returntype="uid_t">
+ <prototype>
+ <parameter content="void"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/types.h"/>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;getuid&lt;/CODE&gt; function returns the real user ID of the process.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-getgid" type="function">
+ <function returntype="gid_t">
+ <prototype>
+ <parameter content="void"/>
+ </prototype>
+ <headers>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;getgid&lt;/CODE&gt; function returns the real group ID of the process.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-geteuid" type="function">
+ <function returntype="uid_t">
+ <prototype>
+ <parameter content="void"/>
+ </prototype>
+ <headers>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;geteuid&lt;/CODE&gt; function returns the effective user ID of the process.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-getegid" type="function">
+ <function returntype="gid_t">
+ <prototype>
+ <parameter content="void"/>
+ </prototype>
+ <headers>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;getegid&lt;/CODE&gt; function returns the effective group ID of the process.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-getgroups" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="int count"/>
+ <parameter content="gid_t *groups"/>
+ </prototype>
+ <headers>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;getgroups&lt;/CODE&gt; function is used to inquire about the supplementary
+ group IDs of the process. Up to &lt;VAR&gt;count&lt;/VAR&gt; of these group IDs are
+ stored in the array &lt;VAR&gt;groups&lt;/VAR&gt;; the return value from the function is
+ the number of group IDs actually stored. If &lt;VAR&gt;count&lt;/VAR&gt; is smaller than
+ the total number of supplementary group IDs, then &lt;CODE&gt;getgroups&lt;/CODE&gt;
+ returns a value of &lt;CODE&gt;-1&lt;/CODE&gt; and &lt;CODE&gt;errno&lt;/CODE&gt; is set to &lt;CODE&gt;EINVAL&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; If &lt;VAR&gt;count&lt;/VAR&gt; is zero, then &lt;CODE&gt;getgroups&lt;/CODE&gt; just returns the total
+ number of supplementary group IDs. On systems that do not support
+ supplementary groups, this will always be zero.
+ &lt;br&gt;&lt;br&gt; Here's how to use &lt;CODE&gt;getgroups&lt;/CODE&gt; to read all the supplementary group
+ IDs:
+ &lt;br&gt;&lt;br&gt; &lt;pre&gt;&lt;br&gt;
+ &lt;br&gt;
+ gid_t *&lt;br&gt;
+ read_all_groups (void)&lt;br&gt;
+ {&lt;br&gt;
+ int ngroups = getgroups (0, NULL);&lt;br&gt;
+ gid_t *groups&lt;br&gt;
+ = (gid_t *) xmalloc (ngroups * sizeof (gid_t));&lt;br&gt;
+ int val = getgroups (ngroups, groups);&lt;br&gt;
+ if (val &lt; 0)&lt;br&gt;
+ {&lt;br&gt;
+ free (groups);&lt;br&gt;
+ return NULL;&lt;br&gt;
+ }&lt;br&gt;
+ return groups;&lt;br&gt;
+ }&lt;br&gt;
+ &lt;br&gt;
+ &lt;/pre&gt;
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-seteuid" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="uid_t neweuid"/>
+ </prototype>
+ <headers>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ This function sets the effective user ID of a process to &lt;VAR&gt;newuid&lt;/VAR&gt;,
+ 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.
+ &lt;br&gt;&lt;br&gt; The &lt;CODE&gt;seteuid&lt;/CODE&gt; function returns a value of &lt;CODE&gt;0&lt;/CODE&gt; to indicate
+ successful completion, and a value of &lt;CODE&gt;-1&lt;/CODE&gt; to indicate an error.
+ The following &lt;CODE&gt;errno&lt;/CODE&gt; error conditions are defined for this
+ function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EINVAL&lt;/CODE&gt;
+&lt;DD&gt;
+ The value of the &lt;VAR&gt;newuid&lt;/VAR&gt; argument is invalid.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EPERM
+ The process may not change to the specified ID.
+
+ &lt;br&gt;&lt;br&gt; Older systems (those without the &lt;CODE&gt;_POSIX_SAVED_IDS&lt;/CODE&gt; feature) do not
+ have this function.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-setuid" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="uid_t newuid"/>
+ </prototype>
+ <headers>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ If the calling process is privileged, this function sets both the real
+ and effective user ID of the process to &lt;VAR&gt;newuid&lt;/VAR&gt;. It also deletes
+ the file user ID of the process, if any. &lt;VAR&gt;newuid&lt;/VAR&gt; may be any
+ legal value. (Once this has been done, there is no way to recover the
+ old effective user ID.)
+ &lt;br&gt;&lt;br&gt; If the process is not privileged, and the system supports the
+ &lt;CODE&gt;_POSIX_SAVED_IDS&lt;/CODE&gt; feature, then this function behaves like
+ &lt;CODE&gt;seteuid&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; The return values and error conditions are the same as for &lt;CODE&gt;seteuid&lt;/CODE&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-setreuid" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="uid_t ruid"/>
+ <parameter content="uid_t euid"/>
+ </prototype>
+ <headers>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ This function sets the real user ID of the process to &lt;VAR&gt;ruid&lt;/VAR&gt; and the
+ effective user ID to &lt;VAR&gt;euid&lt;/VAR&gt;. If &lt;VAR&gt;ruid&lt;/VAR&gt; is &lt;CODE&gt;-1&lt;/CODE&gt;, it means
+ not to change the real user ID; likewise if &lt;VAR&gt;euid&lt;/VAR&gt; is &lt;CODE&gt;-1&lt;/CODE&gt;, it
+ means not to change the effective user ID.
+ &lt;br&gt;&lt;br&gt; The &lt;CODE&gt;setreuid&lt;/CODE&gt; 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. .
+ &lt;br&gt;&lt;br&gt; The return value is &lt;CODE&gt;0&lt;/CODE&gt; on success and &lt;CODE&gt;-1&lt;/CODE&gt; on failure.
+ The following &lt;CODE&gt;errno&lt;/CODE&gt; error conditions are defined for this
+ function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EPERM&lt;/CODE&gt;
+&lt;DD&gt;
+ The process does not have the appropriate privileges; you do not
+ have permission to change to the specified ID.
+
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-setegid" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="gid_t newgid"/>
+ </prototype>
+ <headers>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ This function sets the effective group ID of the process to
+ &lt;VAR&gt;newgid&lt;/VAR&gt;, provided that the process is allowed to change its group
+ ID. Just as with &lt;CODE&gt;seteuid&lt;/CODE&gt;, 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.
+ &lt;br&gt;&lt;br&gt; Note that a process is only privileged if its effective &lt;EM&gt;user&lt;/EM&gt; ID
+ is zero. The effective group ID only affects access permissions.
+ &lt;br&gt;&lt;br&gt; The return values and error conditions for &lt;CODE&gt;setegid&lt;/CODE&gt; are the same
+ as those for &lt;CODE&gt;seteuid&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; This function is only present if &lt;CODE&gt;_POSIX_SAVED_IDS&lt;/CODE&gt; is defined.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-setgid" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="gid_t newgid"/>
+ </prototype>
+ <headers>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ This function sets both the real and effective group ID of the process
+ to &lt;VAR&gt;newgid&lt;/VAR&gt;, provided that the process is privileged. It also
+ deletes the file group ID, if any.
+ &lt;br&gt;&lt;br&gt; If the process is not privileged, then &lt;CODE&gt;setgid&lt;/CODE&gt; behaves like
+ &lt;CODE&gt;setegid&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; The return values and error conditions for &lt;CODE&gt;setgid&lt;/CODE&gt; are the same
+ as those for &lt;CODE&gt;seteuid&lt;/CODE&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-setregid" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="gid_t rgid"/>
+ <parameter content="gid_t egid"/>
+ </prototype>
+ <headers>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ This function sets the real group ID of the process to &lt;VAR&gt;rgid&lt;/VAR&gt; and
+ the effective group ID to &lt;VAR&gt;egid&lt;/VAR&gt;. If &lt;VAR&gt;rgid&lt;/VAR&gt; is &lt;CODE&gt;-1&lt;/CODE&gt;, it
+ means not to change the real group ID; likewise if &lt;VAR&gt;egid&lt;/VAR&gt; is
+ &lt;CODE&gt;-1&lt;/CODE&gt;, it means not to change the effective group ID.
+ &lt;br&gt;&lt;br&gt; The &lt;CODE&gt;setregid&lt;/CODE&gt; 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.
+ .
+ &lt;br&gt;&lt;br&gt; The return values and error conditions for &lt;CODE&gt;setregid&lt;/CODE&gt; are the same
+ as those for &lt;CODE&gt;setreuid&lt;/CODE&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-setgroups" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="size_t count"/>
+ <parameter content="gid_t *groups"/>
+ </prototype>
+ <headers>
+ <header filename = "grp.h"/>
+ </headers>
+ <synopsis>
+ This function sets the process's supplementary group IDs. It can only
+ be called from privileged processes. The &lt;VAR&gt;count&lt;/VAR&gt; argument specifies
+ the number of group IDs in the array &lt;VAR&gt;groups&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; This function returns &lt;CODE&gt;0&lt;/CODE&gt; if successful and &lt;CODE&gt;-1&lt;/CODE&gt; on error.
+ The following &lt;CODE&gt;errno&lt;/CODE&gt; error conditions are defined for this
+ function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EPERM&lt;/CODE&gt;
+&lt;DD&gt;
+ The calling process is not privileged.
+
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-initgroups" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *user"/>
+ <parameter content="gid_t group"/>
+ </prototype>
+ <headers>
+ <header filename = "grp.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;initgroups&lt;/CODE&gt; function sets the process's supplementary group
+ IDs to be the normal default for the user name &lt;VAR&gt;user&lt;/VAR&gt;. The group
+ &lt;VAR&gt;group&lt;/VAR&gt; is automatically included.
+ &lt;br&gt;&lt;br&gt; This function works by scanning the group database for all the groups
+ &lt;VAR&gt;user&lt;/VAR&gt; belongs to. It then calls &lt;CODE&gt;setgroups&lt;/CODE&gt; with the list it
+ has constructed.
+ &lt;br&gt;&lt;br&gt; The return values and error conditions are the same as for
+ &lt;CODE&gt;setgroups&lt;/CODE&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-getgrouplist" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *user"/>
+ <parameter content="gid_t group"/>
+ <parameter content="gid_t *groups"/>
+ <parameter content="int *ngroups"/>
+ </prototype>
+ <headers>
+ <header filename = "grp.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;getgrouplist&lt;/CODE&gt; function scans the group database for all the
+ groups &lt;VAR&gt;user&lt;/VAR&gt; belongs to. Up to *&lt;VAR&gt;ngroups&lt;/VAR&gt; group IDs
+ corresponding to these groups are stored in the array &lt;VAR&gt;groups&lt;/VAR&gt;; the
+ return value from the function is the number of group IDs actually
+ stored. If *&lt;VAR&gt;ngroups&lt;/VAR&gt; is smaller than the total number of groups
+ found, then &lt;CODE&gt;getgrouplist&lt;/CODE&gt; returns a value of &lt;CODE&gt;-1&lt;/CODE&gt; and stores
+ the actual number of groups in *&lt;VAR&gt;ngroups&lt;/VAR&gt;. The group &lt;VAR&gt;group&lt;/VAR&gt; is
+ automatically included in the list of groups returned by
+ &lt;CODE&gt;getgrouplist&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; Here's how to use &lt;CODE&gt;getgrouplist&lt;/CODE&gt; to read all supplementary groups
+ for &lt;VAR&gt;user&lt;/VAR&gt;:
+ &lt;br&gt;&lt;br&gt; &lt;pre&gt;&lt;br&gt;
+ &lt;br&gt;
+ gid_t *&lt;br&gt;
+ supplementary_groups (char *user)&lt;br&gt;
+ {&lt;br&gt;
+ int ngroups = 16;&lt;br&gt;
+ gid_t *groups&lt;br&gt;
+ = (gid_t *) xmalloc (ngroups * sizeof (gid_t));&lt;br&gt;
+ struct passwd *pw = getpwnam (user);&lt;br&gt;
+ &lt;br&gt;&lt;br&gt; if (pw == NULL)&lt;br&gt;
+ return NULL;&lt;br&gt;
+ &lt;br&gt;&lt;br&gt; if (getgrouplist (pw-&gt;pw_name, pw-&gt;pw_gid, groups, &amp;ngroups) &lt; 0)&lt;br&gt;
+ {&lt;br&gt;
+ groups = xrealloc (ngroups * sizeof (gid_t));&lt;br&gt;
+ getgrouplist (pw-&gt;pw_name, pw-&gt;pw_gid, groups, &amp;ngroups);&lt;br&gt;
+ }&lt;br&gt;
+ return groups;&lt;br&gt;
+ }&lt;br&gt;
+ &lt;br&gt;
+ &lt;/pre&gt;
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-getlogin" type="function">
+ <function returntype="char *">
+ <prototype>
+ <parameter content="void"/>
+ </prototype>
+ <headers>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;getlogin&lt;/CODE&gt; 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 &lt;CODE&gt;cuserid&lt;/CODE&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-cuserid" type="function">
+ <function returntype="char *">
+ <prototype>
+ <parameter content="char *string"/>
+ </prototype>
+ <headers>
+ <header filename = "stdio.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;cuserid&lt;/CODE&gt; function returns a pointer to a string containing a
+ user name associated with the effective ID of the process. If
+ &lt;VAR&gt;string&lt;/VAR&gt; is not a null pointer, it should be an array that can hold
+ at least &lt;CODE&gt;L_cuserid&lt;/CODE&gt; 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 &lt;CODE&gt;getlogin&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; 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.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="struct-exit_status" type="struct">
+ <structure>
+ <synopsis>
+ The &lt;CODE&gt;exit_status&lt;/CODE&gt; data structure is used to hold information about
+ the exit status of processes marked as &lt;CODE&gt;DEAD_PROCESS&lt;/CODE&gt; in the user
+ accounting database.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ <elements>
+ <element content="short int e_termination">
+ <synopsis>
+ The exit status of the process.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ </elements>
+ </structure>
+ </construct>
+ <construct id="struct-utmp" type="struct">
+ <structure>
+ <synopsis>
+ The &lt;CODE&gt;utmp&lt;/CODE&gt; data structure is used to hold information about entries
+ in the user accounting database. On the GNU system it has the following
+ members:
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ <elements>
+ <element content="short int ut_type">
+ <synopsis>
+ Specifies the type of login; one of &lt;CODE&gt;EMPTY&lt;/CODE&gt;, &lt;CODE&gt;RUN_LVL&lt;/CODE&gt;,
+ &lt;CODE&gt;BOOT_TIME&lt;/CODE&gt;, &lt;CODE&gt;OLD_TIME&lt;/CODE&gt;, &lt;CODE&gt;NEW_TIME&lt;/CODE&gt;, &lt;CODE&gt;INIT_PROCESS&lt;/CODE&gt;,
+ &lt;CODE&gt;LOGIN_PROCESS&lt;/CODE&gt;, &lt;CODE&gt;USER_PROCESS&lt;/CODE&gt;, &lt;CODE&gt;DEAD_PROCESS&lt;/CODE&gt; or
+ &lt;CODE&gt;ACCOUNTING&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="pid_t ut_pid">
+ <synopsis>
+ The process ID number of the login process.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="char ut_line[]">
+ <synopsis>
+ The device name of the tty (without &lt;TT&gt;/dev/&lt;/TT&gt;).
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="char ut_id[]">
+ <synopsis>
+ The inittab ID of the process.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="char ut_user[]">
+ <synopsis>
+ The user's login name.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="char ut_host[]">
+ <synopsis>
+ The name of the host from which the user logged in.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="struct exit_status ut_exit">
+ <synopsis>
+ The exit status of a process marked as &lt;CODE&gt;DEAD_PROCESS&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="long ut_session">
+ <synopsis>
+ The Session ID, used for windowing.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="struct timeval ut_tv">
+ <synopsis>
+ Time the entry was made. For entries of type &lt;CODE&gt;OLD_TIME&lt;/CODE&gt; this is
+ the time when the system clock changed, and for entries of type
+ &lt;CODE&gt;NEW_TIME&lt;/CODE&gt; this is the time the system clock was set to.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ </elements>
+ </structure>
+ </construct>
+ <construct id="function-setutent" type="function">
+ <function returntype="void">
+ <prototype>
+ <parameter content="void"/>
+ </prototype>
+ <headers>
+ <header filename = "stdio.h"/>
+ <header filename = "utmp.h"/>
+ </headers>
+ <synopsis>
+ This function opens the user accounting database to begin scanning it.
+ You can then call &lt;CODE&gt;getutent&lt;/CODE&gt;, &lt;CODE&gt;getutid&lt;/CODE&gt; or &lt;CODE&gt;getutline&lt;/CODE&gt; to
+ read entries and &lt;CODE&gt;pututline&lt;/CODE&gt; to write entries.
+ &lt;br&gt;&lt;br&gt; If the database is already open, it resets the input to the beginning of
+ the database.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-getutent" type="function">
+ <function returntype="struct utmp *">
+ <prototype>
+ <parameter content="void"/>
+ </prototype>
+ <headers>
+ <header filename = "utmp.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;getutent&lt;/CODE&gt; 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
+ &lt;CODE&gt;getutent&lt;/CODE&gt;. You must copy the contents of the structure if you
+ wish to save the information or you can use the &lt;CODE&gt;getutent_r&lt;/CODE&gt;
+ function which stores the data in a user-provided buffer.
+ &lt;br&gt;&lt;br&gt; A null pointer is returned in case no further entry is available.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-endutent" type="function">
+ <function returntype="void">
+ <prototype>
+ <parameter content="void"/>
+ </prototype>
+ <headers>
+ <header filename = "utmp.h"/>
+ </headers>
+ <synopsis>
+ This function closes the user accounting database.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-getutid" type="function">
+ <function returntype="struct utmp *">
+ <prototype>
+ <parameter content="const struct utmp *id"/>
+ </prototype>
+ <headers>
+ <header filename = "utmp.h"/>
+ </headers>
+ <synopsis>
+ This function searches forward from the current point in the database
+ for an entry that matches &lt;VAR&gt;id&lt;/VAR&gt;. If the &lt;CODE&gt;ut_type&lt;/CODE&gt; member of the
+ &lt;VAR&gt;id&lt;/VAR&gt; structure is one of &lt;CODE&gt;RUN_LVL&lt;/CODE&gt;, &lt;CODE&gt;BOOT_TIME&lt;/CODE&gt;,
+ &lt;CODE&gt;OLD_TIME&lt;/CODE&gt; or &lt;CODE&gt;NEW_TIME&lt;/CODE&gt; the entries match if the
+ &lt;CODE&gt;ut_type&lt;/CODE&gt; members are identical. If the &lt;CODE&gt;ut_type&lt;/CODE&gt; member of
+ the &lt;VAR&gt;id&lt;/VAR&gt; structure is &lt;CODE&gt;INIT_PROCESS&lt;/CODE&gt;, &lt;CODE&gt;LOGIN_PROCESS&lt;/CODE&gt;,
+ &lt;CODE&gt;USER_PROCESS&lt;/CODE&gt; or &lt;CODE&gt;DEAD_PROCESS&lt;/CODE&gt;, the entries match if the
+ &lt;CODE&gt;ut_type&lt;/CODE&gt; member of the entry read from the database is one of
+ these four, and the &lt;CODE&gt;ut_id&lt;/CODE&gt; members match. However if the
+ &lt;CODE&gt;ut_id&lt;/CODE&gt; member of either the &lt;VAR&gt;id&lt;/VAR&gt; structure or the entry read
+ from the database is empty it checks if the &lt;CODE&gt;ut_line&lt;/CODE&gt; members match
+ instead. If a matching entry is found, &lt;CODE&gt;getutid&lt;/CODE&gt; returns a pointer
+ to the entry, which is statically allocated, and may be overwritten by a
+ subsequent call to &lt;CODE&gt;getutent&lt;/CODE&gt;, &lt;CODE&gt;getutid&lt;/CODE&gt; or &lt;CODE&gt;getutline&lt;/CODE&gt;.
+ You must copy the contents of the structure if you wish to save the
+ information.
+ &lt;br&gt;&lt;br&gt; A null pointer is returned in case the end of the database is reached
+ without a match.
+ &lt;br&gt;&lt;br&gt; The &lt;CODE&gt;getutid&lt;/CODE&gt; function may cache the last read entry. Therefore,
+ if you are using &lt;CODE&gt;getutid&lt;/CODE&gt; to search for multiple occurrences, it
+ is necessary to zero out the static data after each call. Otherwise
+ &lt;CODE&gt;getutid&lt;/CODE&gt; could just return a pointer to the same entry over and
+ over again.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-getutline" type="function">
+ <function returntype="struct utmp *">
+ <prototype>
+ <parameter content="const struct utmp *line"/>
+ </prototype>
+ <headers>
+ <header filename = "utmp.h"/>
+ </headers>
+ <synopsis>
+ This function searches forward from the current point in the database
+ until it finds an entry whose &lt;CODE&gt;ut_type&lt;/CODE&gt; value is
+ &lt;CODE&gt;LOGIN_PROCESS&lt;/CODE&gt; or &lt;CODE&gt;USER_PROCESS&lt;/CODE&gt;, and whose &lt;CODE&gt;ut_line&lt;/CODE&gt;
+ member matches the &lt;CODE&gt;ut_line&lt;/CODE&gt; member of the &lt;VAR&gt;line&lt;/VAR&gt; 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
+ &lt;CODE&gt;getutent&lt;/CODE&gt;, &lt;CODE&gt;getutid&lt;/CODE&gt; or &lt;CODE&gt;getutline&lt;/CODE&gt;. You must copy the
+ contents of the structure if you wish to save the information.
+ &lt;br&gt;&lt;br&gt; A null pointer is returned in case the end of the database is reached
+ without a match.
+ &lt;br&gt;&lt;br&gt; The &lt;CODE&gt;getutline&lt;/CODE&gt; function may cache the last read entry. Therefore
+ if you are using &lt;CODE&gt;getutline&lt;/CODE&gt; to search for multiple occurrences, it
+ is necessary to zero out the static data after each call. Otherwise
+ &lt;CODE&gt;getutline&lt;/CODE&gt; could just return a pointer to the same entry over and
+ over again.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-pututline" type="function">
+ <function returntype="struct utmp *">
+ <prototype>
+ <parameter content="const struct utmp *utmp"/>
+ </prototype>
+ <headers>
+ <header filename = "utmp.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;pututline&lt;/CODE&gt; function inserts the entry &lt;CODE&gt;*&lt;VAR&gt;utmp&lt;/VAR&gt;&lt;/CODE&gt; 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
+ &lt;CODE&gt;getutid&lt;/CODE&gt; to search for the position to insert the entry, however
+ this will not modify the static structure returned by &lt;CODE&gt;getutent&lt;/CODE&gt;,
+ &lt;CODE&gt;getutid&lt;/CODE&gt; and &lt;CODE&gt;getutline&lt;/CODE&gt;. If this search fails, the entry
+ is appended to the database.
+ &lt;br&gt;&lt;br&gt; The &lt;CODE&gt;pututline&lt;/CODE&gt; 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 &lt;CODE&gt;errno&lt;/CODE&gt; error conditions are
+ defined for this function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EPERM&lt;/CODE&gt;
+&lt;DD&gt;
+ The process does not have the appropriate privileges; you cannot modify
+ the user accounting database.
+
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-getutent_r" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="struct utmp *buffer"/>
+ <parameter content="struct utmp **result"/>
+ </prototype>
+ <headers>
+ <header filename = "utmp.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;getutent_r&lt;/CODE&gt; is equivalent to the &lt;CODE&gt;getutent&lt;/CODE&gt; 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 &lt;VAR&gt;buffer&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; If the call was successful, the function returns &lt;CODE&gt;0&lt;/CODE&gt; and the
+ pointer variable pointed to by the parameter &lt;VAR&gt;result&lt;/VAR&gt; contains a
+ pointer to the buffer which contains the result (this is most probably
+ the same value as &lt;VAR&gt;buffer&lt;/VAR&gt;). If something went wrong during the
+ execution of &lt;CODE&gt;getutent_r&lt;/CODE&gt; the function returns &lt;CODE&gt;-1&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; This function is a GNU extension.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-getutid_r" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const struct utmp *id"/>
+ <parameter content="struct utmp *buffer"/>
+ <parameter content="struct utmp **result"/>
+ </prototype>
+ <headers>
+ <header filename = "utmp.h"/>
+ </headers>
+ <synopsis>
+ This function retrieves just like &lt;CODE&gt;getutid&lt;/CODE&gt; the next entry matching
+ the information stored in &lt;VAR&gt;id&lt;/VAR&gt;. But the result is stored in the
+ buffer pointed to by the parameter &lt;VAR&gt;buffer&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; If successful the function returns &lt;CODE&gt;0&lt;/CODE&gt; and the pointer variable
+ pointed to by the parameter &lt;VAR&gt;result&lt;/VAR&gt; contains a pointer to the
+ buffer with the result (probably the same as &lt;VAR&gt;result&lt;/VAR&gt;. If not
+ successful the function return &lt;CODE&gt;-1&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; This function is a GNU extension.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-getutline_r" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const struct utmp *line"/>
+ <parameter content="struct utmp *buffer"/>
+ <parameter content="struct utmp **result"/>
+ </prototype>
+ <headers>
+ <header filename = "utmp.h"/>
+ </headers>
+ <synopsis>
+ This function retrieves just like &lt;CODE&gt;getutline&lt;/CODE&gt; the next entry
+ matching the information stored in &lt;VAR&gt;line&lt;/VAR&gt;. But the result is stored
+ in the buffer pointed to by the parameter &lt;VAR&gt;buffer&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; If successful the function returns &lt;CODE&gt;0&lt;/CODE&gt; and the pointer variable
+ pointed to by the parameter &lt;VAR&gt;result&lt;/VAR&gt; contains a pointer to the
+ buffer with the result (probably the same as &lt;VAR&gt;result&lt;/VAR&gt;. If not
+ successful the function return &lt;CODE&gt;-1&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; This function is a GNU extension.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-utmpname" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *file"/>
+ </prototype>
+ <headers>
+ <header filename = "utmp.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;utmpname&lt;/CODE&gt; function changes the name of the database to be
+ examined to &lt;VAR&gt;file&lt;/VAR&gt;, and closes any previously opened database. By
+ default &lt;CODE&gt;getutent&lt;/CODE&gt;, &lt;CODE&gt;getutid&lt;/CODE&gt;, &lt;CODE&gt;getutline&lt;/CODE&gt; and
+ &lt;CODE&gt;pututline&lt;/CODE&gt; read from and write to the user accounting database.
+ &lt;br&gt;&lt;br&gt; The following macros are defined for use as the &lt;VAR&gt;file&lt;/VAR&gt; argument:
+ &lt;br&gt;&lt;br&gt; Macro {char *} _PATH_UTMP
+ This macro is used to specify the user accounting database.
+
+ &lt;br&gt;&lt;br&gt; Macro {char *} _PATH_WTMP
+ This macro is used to specify the user accounting log file.
+
+ &lt;br&gt;&lt;br&gt; The &lt;CODE&gt;utmpname&lt;/CODE&gt; function returns a value of &lt;CODE&gt;0&lt;/CODE&gt; if the new name
+ was successfully stored, and a value of &lt;CODE&gt;-1&lt;/CODE&gt; to indicate an error.
+ Note that &lt;CODE&gt;utmpname&lt;/CODE&gt; 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.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-updwtmp" type="function">
+ <function returntype="void">
+ <prototype>
+ <parameter content="const char *wtmp_file"/>
+ <parameter content="const struct utmp *utmp"/>
+ </prototype>
+ <headers>
+ <header filename = "utmp.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;updwtmp&lt;/CODE&gt; function appends the entry *&lt;VAR&gt;utmp&lt;/VAR&gt; to the
+ database specified by &lt;VAR&gt;wtmp_file&lt;/VAR&gt;. For possible values for the
+ &lt;VAR&gt;wtmp_file&lt;/VAR&gt; argument see the &lt;CODE&gt;utmpname&lt;/CODE&gt; function.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="struct-utmpx" type="struct">
+ <structure>
+ <synopsis>
+ The &lt;CODE&gt;utmpx&lt;/CODE&gt; data structure contains at least the following members:
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ <elements>
+ <element content="short int ut_type">
+ <synopsis>
+ Specifies the type of login; one of &lt;CODE&gt;EMPTY&lt;/CODE&gt;, &lt;CODE&gt;RUN_LVL&lt;/CODE&gt;,
+ &lt;CODE&gt;BOOT_TIME&lt;/CODE&gt;, &lt;CODE&gt;OLD_TIME&lt;/CODE&gt;, &lt;CODE&gt;NEW_TIME&lt;/CODE&gt;, &lt;CODE&gt;INIT_PROCESS&lt;/CODE&gt;,
+ &lt;CODE&gt;LOGIN_PROCESS&lt;/CODE&gt;, &lt;CODE&gt;USER_PROCESS&lt;/CODE&gt; or &lt;CODE&gt;DEAD_PROCESS&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="pid_t ut_pid">
+ <synopsis>
+ The process ID number of the login process.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="char ut_line[]">
+ <synopsis>
+ The device name of the tty (without &lt;TT&gt;/dev/&lt;/TT&gt;).
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="char ut_id[]">
+ <synopsis>
+ The inittab ID of the process.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="char ut_user[]">
+ <synopsis>
+ The user's login name.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ </elements>
+ </structure>
+ </construct>
+ <construct id="function-setutxent" type="function">
+ <function returntype="void">
+ <prototype>
+ <parameter content="void"/>
+ </prototype>
+ <headers>
+ <header filename = "utmpx.h"/>
+ </headers>
+ <synopsis>
+ This function is similar to &lt;CODE&gt;setutent&lt;/CODE&gt;. On the GNU system it is
+ simply an alias for &lt;CODE&gt;setutent&lt;/CODE&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-getutxent" type="function">
+ <function returntype="struct utmpx *">
+ <prototype>
+ <parameter content="void"/>
+ </prototype>
+ <headers>
+ <header filename = "utmpx.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;getutxent&lt;/CODE&gt; function is similar to &lt;CODE&gt;getutent&lt;/CODE&gt;, but returns
+ a pointer to a &lt;CODE&gt;struct utmpx&lt;/CODE&gt; instead of &lt;CODE&gt;struct utmp&lt;/CODE&gt;. On
+ the GNU system it simply is an alias for &lt;CODE&gt;getutent&lt;/CODE&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-endutxent" type="function">
+ <function returntype="void">
+ <prototype>
+ <parameter content="void"/>
+ </prototype>
+ <headers>
+ <header filename = "utmpx.h"/>
+ </headers>
+ <synopsis>
+ This function is similar to &lt;CODE&gt;endutent&lt;/CODE&gt;. On the GNU system it is
+ simply an alias for &lt;CODE&gt;endutent&lt;/CODE&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-getutxid" type="function">
+ <function returntype="struct utmpx *">
+ <prototype>
+ <parameter content="const struct utmpx *id"/>
+ </prototype>
+ <headers>
+ <header filename = "utmpx.h"/>
+ </headers>
+ <synopsis>
+ This function is similar to &lt;CODE&gt;getutid&lt;/CODE&gt;, but uses &lt;CODE&gt;struct utmpx&lt;/CODE&gt;
+ instead of &lt;CODE&gt;struct utmp&lt;/CODE&gt;. On the GNU system it is simply an alias
+ for &lt;CODE&gt;getutid&lt;/CODE&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-getutxline" type="function">
+ <function returntype="struct utmpx *">
+ <prototype>
+ <parameter content="const struct utmpx *line"/>
+ </prototype>
+ <headers>
+ <header filename = "utmpx.h"/>
+ </headers>
+ <synopsis>
+ This function is similar to &lt;CODE&gt;getutid&lt;/CODE&gt;, but uses &lt;CODE&gt;struct utmpx&lt;/CODE&gt;
+ instead of &lt;CODE&gt;struct utmp&lt;/CODE&gt;. On the GNU system it is simply an alias
+ for &lt;CODE&gt;getutline&lt;/CODE&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-pututxline" type="function">
+ <function returntype="struct utmpx *">
+ <prototype>
+ <parameter content="const struct utmpx *utmp"/>
+ </prototype>
+ <headers>
+ <header filename = "utmpx.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;pututxline&lt;/CODE&gt; function is functionally identical to
+ &lt;CODE&gt;pututline&lt;/CODE&gt;, but uses &lt;CODE&gt;struct utmpx&lt;/CODE&gt; instead of &lt;CODE&gt;struct
+ utmp&lt;/CODE&gt;. On the GNU system, &lt;CODE&gt;pututxline&lt;/CODE&gt; is simply an alias for
+ &lt;CODE&gt;pututline&lt;/CODE&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-utmpxname" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *file"/>
+ </prototype>
+ <headers>
+ <header filename = "utmpx.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;utmpxname&lt;/CODE&gt; function is functionally identical to
+ &lt;CODE&gt;utmpname&lt;/CODE&gt;. On the GNU system, &lt;CODE&gt;utmpxname&lt;/CODE&gt; is simply an
+ alias for &lt;CODE&gt;utmpname&lt;/CODE&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-getutmp" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const struct utmpx *utmpx"/>
+ <parameter content="struct utmp *utmp"/>
+ </prototype>
+ <headers>
+ <header filename = "utmpx.h"/>
+ <header filename = "utmp.h"/>
+ </headers>
+ <synopsis>
+ &lt;CODE&gt;getutmp&lt;/CODE&gt; copies the information, insofar as the structures are
+ compatible, from &lt;VAR&gt;utmpx&lt;/VAR&gt; to &lt;VAR&gt;utmp&lt;/VAR&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-getutmpx" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const struct utmp *utmp"/>
+ <parameter content="struct utmpx *utmpx"/>
+ </prototype>
+ <headers>
+ <header filename = "utmpx.h"/>
+ <header filename = "utmp.h"/>
+ </headers>
+ <synopsis>
+ &lt;CODE&gt;getutmpx&lt;/CODE&gt; copies the information, insofar as the structures are
+ compatible, from &lt;VAR&gt;utmp&lt;/VAR&gt; to &lt;VAR&gt;utmpx&lt;/VAR&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-login_tty" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="int filedes"/>
+ </prototype>
+ <headers>
+ <header filename = "utmp.h"/>
+ </headers>
+ <synopsis>
+ This function makes &lt;VAR&gt;filedes&lt;/VAR&gt; the controlling terminal of the
+ current process, redirects standard input, standard output and
+ standard error output to this terminal, and closes &lt;VAR&gt;filedes&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; This function returns &lt;CODE&gt;0&lt;/CODE&gt; on successful completion, and &lt;CODE&gt;-1&lt;/CODE&gt;
+ on error.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-login" type="function">
+ <function returntype="void">
+ <prototype>
+ <parameter content="const struct utmp *entry"/>
+ </prototype>
+ <headers>
+ <header filename = "utmp.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;login&lt;/CODE&gt; functions inserts an entry into the user accounting
+ database. The &lt;CODE&gt;ut_line&lt;/CODE&gt; member is set to the name of the terminal
+ on standard input. If standard input is not a terminal &lt;CODE&gt;login&lt;/CODE&gt;
+ uses standard output or standard error output to determine the name of
+ the terminal. If &lt;CODE&gt;struct utmp&lt;/CODE&gt; has a &lt;CODE&gt;ut_type&lt;/CODE&gt; member,
+ &lt;CODE&gt;login&lt;/CODE&gt; sets it to &lt;CODE&gt;USER_PROCESS&lt;/CODE&gt;, and if there is an
+ &lt;CODE&gt;ut_pid&lt;/CODE&gt; member, it will be set to the process ID of the current
+ process. The remaining entries are copied from &lt;VAR&gt;entry&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; A copy of the entry is written to the user accounting log file.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-logout" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *ut_line"/>
+ </prototype>
+ <headers>
+ <header filename = "utmp.h"/>
+ </headers>
+ <synopsis>
+ This function modifies the user accounting database to indicate that the
+ user on &lt;VAR&gt;ut_line&lt;/VAR&gt; has logged out.
+ &lt;br&gt;&lt;br&gt; The &lt;CODE&gt;logout&lt;/CODE&gt; function returns &lt;CODE&gt;1&lt;/CODE&gt; if the entry was successfully
+ written to the database, or &lt;CODE&gt;0&lt;/CODE&gt; on error.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-logwtmp" type="function">
+ <function returntype="void">
+ <prototype>
+ <parameter content="const char *ut_line"/>
+ <parameter content="const char *ut_name"/>
+ <parameter content="const char *ut_host"/>
+ </prototype>
+ <headers>
+ <header filename = "utmp.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;logwtmp&lt;/CODE&gt; function appends an entry to the user accounting log
+ file, for the current time and the information provided in the
+ &lt;VAR&gt;ut_line&lt;/VAR&gt;, &lt;VAR&gt;ut_name&lt;/VAR&gt; and &lt;VAR&gt;ut_host&lt;/VAR&gt; arguments.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="struct-passwd" type="struct">
+ <structure>
+ <synopsis>
+ The &lt;CODE&gt;passwd&lt;/CODE&gt; data structure is used to hold information about
+ entries in the system user data base. It has at least the following members:
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ <elements>
+ <element content="char *pw_name">
+ <synopsis>
+ The user's login name.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="char *pw_passwd.">
+ <synopsis>
+ The encrypted password string.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="uid_t pw_uid">
+ <synopsis>
+ The user ID number.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="gid_t pw_gid">
+ <synopsis>
+ The user's default group ID number.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="char *pw_gecos">
+ <synopsis>
+ A string typically containing the user's real name, and possibly other
+ information such as a phone number.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="char *pw_dir">
+ <synopsis>
+ The user's home directory, or initial working directory. This might be
+ a null pointer, in which case the interpretation is system-dependent.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ </elements>
+ </structure>
+ </construct>
+ <construct id="function-getpwuid" type="function">
+ <function returntype="struct passwd *">
+ <prototype>
+ <parameter content="uid_t uid"/>
+ </prototype>
+ <headers>
+ <header filename = "pwd.h"/>
+ </headers>
+ <synopsis>
+ This function returns a pointer to a statically-allocated structure
+ containing information about the user whose user ID is &lt;VAR&gt;uid&lt;/VAR&gt;. This
+ structure may be overwritten on subsequent calls to &lt;CODE&gt;getpwuid&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; A null pointer value indicates there is no user in the data base with
+ user ID &lt;VAR&gt;uid&lt;/VAR&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-getpwuid_r" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="uid_t uid"/>
+ <parameter content="struct passwd *result_buf"/>
+ <parameter content="char *buffer"/>
+ <parameter content="size_t buflen"/>
+ <parameter content="struct passwd **result"/>
+ </prototype>
+ <headers>
+ <header filename = "pwd.h"/>
+ </headers>
+ <synopsis>
+ This function is similar to &lt;CODE&gt;getpwuid&lt;/CODE&gt; in that it returns
+ information about the user whose user ID is &lt;VAR&gt;uid&lt;/VAR&gt;. However, it
+ fills the user supplied structure pointed to by &lt;VAR&gt;result_buf&lt;/VAR&gt; with
+ the information instead of using a static buffer. The first
+ &lt;VAR&gt;buflen&lt;/VAR&gt; bytes of the additional buffer pointed to by &lt;VAR&gt;buffer&lt;/VAR&gt;
+ are used to contain additional information, normally strings which are
+ pointed to by the elements of the result structure.
+ &lt;br&gt;&lt;br&gt; If a user with ID &lt;VAR&gt;uid&lt;/VAR&gt; is found, the pointer returned in
+ &lt;VAR&gt;result&lt;/VAR&gt; points to the record which contains the wanted data (i.e.,
+ &lt;VAR&gt;result&lt;/VAR&gt; contains the value &lt;VAR&gt;result_buf&lt;/VAR&gt;). If no user is found
+ or if an error occurred, the pointer returned in &lt;VAR&gt;result&lt;/VAR&gt; is a null
+ pointer. The function returns zero or an error code. If the buffer
+ &lt;VAR&gt;buffer&lt;/VAR&gt; is too small to contain all the needed information, the
+ error code &lt;CODE&gt;ERANGE&lt;/CODE&gt; is returned and &lt;VAR&gt;errno&lt;/VAR&gt; is set to
+ &lt;CODE&gt;ERANGE&lt;/CODE&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-getpwnam" type="function">
+ <function returntype="struct passwd *">
+ <prototype>
+ <parameter content="const char *name"/>
+ </prototype>
+ <headers>
+ <header filename = "pwd.h"/>
+ </headers>
+ <synopsis>
+ This function returns a pointer to a statically-allocated structure
+ containing information about the user whose user name is &lt;VAR&gt;name&lt;/VAR&gt;.
+ This structure may be overwritten on subsequent calls to
+ &lt;CODE&gt;getpwnam&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; A null pointer return indicates there is no user named &lt;VAR&gt;name&lt;/VAR&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-getpwnam_r" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *name"/>
+ <parameter content="struct passwd *result_buf"/>
+ <parameter content="char *buffer"/>
+ <parameter content="size_t buflen"/>
+ <parameter content="struct passwd **result"/>
+ </prototype>
+ <headers>
+ <header filename = "pwd.h"/>
+ </headers>
+ <synopsis>
+ This function is similar to &lt;CODE&gt;getpwnam&lt;/CODE&gt; in that is returns
+ information about the user whose user name is &lt;VAR&gt;name&lt;/VAR&gt;. However, like
+ &lt;CODE&gt;getpwuid_r&lt;/CODE&gt;, it fills the user supplied buffers in
+ &lt;VAR&gt;result_buf&lt;/VAR&gt; and &lt;VAR&gt;buffer&lt;/VAR&gt; with the information instead of using
+ a static buffer.
+ &lt;br&gt;&lt;br&gt; The return values are the same as for &lt;CODE&gt;getpwuid_r&lt;/CODE&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-fgetpwent" type="function">
+ <function returntype="struct passwd *">
+ <prototype>
+ <parameter content="FILE *stream"/>
+ </prototype>
+ <headers>
+ <header filename = "pwd.h"/>
+ </headers>
+ <synopsis>
+ This function reads the next user entry from &lt;VAR&gt;stream&lt;/VAR&gt; and returns a
+ pointer to the entry. The structure is statically allocated and is
+ rewritten on subsequent calls to &lt;CODE&gt;fgetpwent&lt;/CODE&gt;. You must copy the
+ contents of the structure if you wish to save the information.
+ &lt;br&gt;&lt;br&gt; The stream must correspond to a file in the same format as the standard
+ password database file.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-fgetpwent_r" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="FILE *stream"/>
+ <parameter content="struct passwd *result_buf"/>
+ <parameter content="char *buffer"/>
+ <parameter content="size_t buflen"/>
+ <parameter content="struct passwd **result"/>
+ </prototype>
+ <headers>
+ <header filename = "pwd.h"/>
+ </headers>
+ <synopsis>
+ This function is similar to &lt;CODE&gt;fgetpwent&lt;/CODE&gt; in that it reads the next
+ user entry from &lt;VAR&gt;stream&lt;/VAR&gt;. But the result is returned in the
+ structure pointed to by &lt;VAR&gt;result_buf&lt;/VAR&gt;. The
+ first &lt;VAR&gt;buflen&lt;/VAR&gt; bytes of the additional buffer pointed to by
+ &lt;VAR&gt;buffer&lt;/VAR&gt; are used to contain additional information, normally
+ strings which are pointed to by the elements of the result structure.
+ &lt;br&gt;&lt;br&gt; The stream must correspond to a file in the same format as the standard
+ password database file.
+ &lt;br&gt;&lt;br&gt; If the function returns zero &lt;VAR&gt;result&lt;/VAR&gt; points to the structure with
+ the wanted data (normally this is in &lt;VAR&gt;result_buf&lt;/VAR&gt;). If errors
+ occurred the return value is nonzero and &lt;VAR&gt;result&lt;/VAR&gt; contains a null
+ pointer.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-setpwent" type="function">
+ <function returntype="void">
+ <prototype>
+ <parameter content="void"/>
+ </prototype>
+ <headers>
+ <header filename = "pwd.h"/>
+ </headers>
+ <synopsis>
+ This function initializes a stream which &lt;CODE&gt;getpwent&lt;/CODE&gt; and
+ &lt;CODE&gt;getpwent_r&lt;/CODE&gt; use to read the user database.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-getpwent" type="function">
+ <function returntype="struct passwd *">
+ <prototype>
+ <parameter content="void"/>
+ </prototype>
+ <headers>
+ <header filename = "pwd.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;getpwent&lt;/CODE&gt; function reads the next entry from the stream
+ initialized by &lt;CODE&gt;setpwent&lt;/CODE&gt;. It returns a pointer to the entry. The
+ structure is statically allocated and is rewritten on subsequent calls
+ to &lt;CODE&gt;getpwent&lt;/CODE&gt;. You must copy the contents of the structure if you
+ wish to save the information.
+ &lt;br&gt;&lt;br&gt; A null pointer is returned when no more entries are available.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-getpwent_r" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="struct passwd *result_buf"/>
+ <parameter content="char *buffer"/>
+ <parameter content="int buflen"/>
+ <parameter content="struct passwd **result"/>
+ </prototype>
+ <headers>
+ <header filename = "pwd.h"/>
+ </headers>
+ <synopsis>
+ This function is similar to &lt;CODE&gt;getpwent&lt;/CODE&gt; in that it returns the next
+ entry from the stream initialized by &lt;CODE&gt;setpwent&lt;/CODE&gt;. Like
+ &lt;CODE&gt;fgetpwent_r&lt;/CODE&gt;, it uses the user-supplied buffers in
+ &lt;VAR&gt;result_buf&lt;/VAR&gt; and &lt;VAR&gt;buffer&lt;/VAR&gt; to return the information requested.
+ &lt;br&gt;&lt;br&gt; The return values are the same as for &lt;CODE&gt;fgetpwent_r&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-endpwent" type="function">
+ <function returntype="void">
+ <prototype>
+ <parameter content="void"/>
+ </prototype>
+ <headers>
+ <header filename = "pwd.h"/>
+ </headers>
+ <synopsis>
+ This function closes the internal stream used by &lt;CODE&gt;getpwent&lt;/CODE&gt; or
+ &lt;CODE&gt;getpwent_r&lt;/CODE&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-putpwent" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const struct passwd *p"/>
+ <parameter content="FILE *stream"/>
+ </prototype>
+ <headers>
+ <header filename = "pwd.h"/>
+ </headers>
+ <synopsis>
+ This function writes the user entry &lt;CODE&gt;*&lt;VAR&gt;p&lt;/VAR&gt;&lt;/CODE&gt; to the stream
+ &lt;VAR&gt;stream&lt;/VAR&gt;, in the format used for the standard user database
+ file. The return value is zero on success and nonzero on failure.
+ &lt;br&gt;&lt;br&gt; This function exists for compatibility with SVID. We recommend that you
+ avoid using it, because it makes sense only on the assumption that the
+ &lt;CODE&gt;struct passwd&lt;/CODE&gt; 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.
+ &lt;br&gt;&lt;br&gt; The group and user ID fields are left empty if the group or user name
+ starts with a - or +.
+ &lt;br&gt;&lt;br&gt; The function &lt;CODE&gt;putpwent&lt;/CODE&gt; is declared in &lt;TT&gt;pwd.h&lt;/TT&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="struct-group" type="struct">
+ <structure>
+ <synopsis>
+ The &lt;CODE&gt;group&lt;/CODE&gt; structure is used to hold information about an entry in
+ the system group database. It has at least the following members:
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ <elements>
+ <element content="char *gr_name">
+ <synopsis>
+ The name of the group.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="gid_t gr_gid">
+ <synopsis>
+ The group ID of the group.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ </elements>
+ </structure>
+ </construct>
+ <construct id="function-getgrgid" type="function">
+ <function returntype="struct group *">
+ <prototype>
+ <parameter content="gid_t gid"/>
+ </prototype>
+ <headers>
+ <header filename = "grp.h"/>
+ </headers>
+ <synopsis>
+ This function returns a pointer to a statically-allocated structure
+ containing information about the group whose group ID is &lt;VAR&gt;gid&lt;/VAR&gt;.
+ This structure may be overwritten by subsequent calls to
+ &lt;CODE&gt;getgrgid&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; A null pointer indicates there is no group with ID &lt;VAR&gt;gid&lt;/VAR&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-getgrgid_r" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="gid_t gid"/>
+ <parameter content="struct group *result_buf"/>
+ <parameter content="char *buffer"/>
+ <parameter content="size_t buflen"/>
+ <parameter content="struct group **result"/>
+ </prototype>
+ <headers>
+ <header filename = "grp.h"/>
+ </headers>
+ <synopsis>
+ This function is similar to &lt;CODE&gt;getgrgid&lt;/CODE&gt; in that it returns
+ information about the group whose group ID is &lt;VAR&gt;gid&lt;/VAR&gt;. However, it
+ fills the user supplied structure pointed to by &lt;VAR&gt;result_buf&lt;/VAR&gt; with
+ the information instead of using a static buffer. The first
+ &lt;VAR&gt;buflen&lt;/VAR&gt; bytes of the additional buffer pointed to by &lt;VAR&gt;buffer&lt;/VAR&gt;
+ are used to contain additional information, normally strings which are
+ pointed to by the elements of the result structure.
+ &lt;br&gt;&lt;br&gt; If a group with ID &lt;VAR&gt;gid&lt;/VAR&gt; is found, the pointer returned in
+ &lt;VAR&gt;result&lt;/VAR&gt; points to the record which contains the wanted data (i.e.,
+ &lt;VAR&gt;result&lt;/VAR&gt; contains the value &lt;VAR&gt;result_buf&lt;/VAR&gt;). If no group is found
+ or if an error occurred, the pointer returned in &lt;VAR&gt;result&lt;/VAR&gt; is a null
+ pointer. The function returns zero or an error code. If the buffer
+ &lt;VAR&gt;buffer&lt;/VAR&gt; is too small to contain all the needed information, the
+ error code &lt;CODE&gt;ERANGE&lt;/CODE&gt; is returned and &lt;VAR&gt;errno&lt;/VAR&gt; is set to
+ &lt;CODE&gt;ERANGE&lt;/CODE&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-getgrnam" type="function">
+ <function returntype="struct group *">
+ <prototype>
+ <parameter content="const char *name"/>
+ </prototype>
+ <headers>
+ <header filename = "grp.h"/>
+ </headers>
+ <synopsis>
+ This function returns a pointer to a statically-allocated structure
+ containing information about the group whose group name is &lt;VAR&gt;name&lt;/VAR&gt;.
+ This structure may be overwritten by subsequent calls to
+ &lt;CODE&gt;getgrnam&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; A null pointer indicates there is no group named &lt;VAR&gt;name&lt;/VAR&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-getgrnam_r" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *name"/>
+ <parameter content="struct group *result_buf"/>
+ <parameter content="char *buffer"/>
+ <parameter content="size_t buflen"/>
+ <parameter content="struct group **result"/>
+ </prototype>
+ <headers>
+ <header filename = "grp.h"/>
+ </headers>
+ <synopsis>
+ This function is similar to &lt;CODE&gt;getgrnam&lt;/CODE&gt; in that is returns
+ information about the group whose group name is &lt;VAR&gt;name&lt;/VAR&gt;. Like
+ &lt;CODE&gt;getgrgid_r&lt;/CODE&gt;, it uses the user supplied buffers in
+ &lt;VAR&gt;result_buf&lt;/VAR&gt; and &lt;VAR&gt;buffer&lt;/VAR&gt;, not a static buffer.
+ &lt;br&gt;&lt;br&gt; The return values are the same as for &lt;CODE&gt;getgrgid_r&lt;/CODE&gt;
+ &lt;CODE&gt;ERANGE&lt;/CODE&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-fgetgrent" type="function">
+ <function returntype="struct group *">
+ <prototype>
+ <parameter content="FILE *stream"/>
+ </prototype>
+ <headers>
+ <header filename = "grp.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;fgetgrent&lt;/CODE&gt; function reads the next entry from &lt;VAR&gt;stream&lt;/VAR&gt;.
+ It returns a pointer to the entry. The structure is statically
+ allocated and is overwritten on subsequent calls to &lt;CODE&gt;fgetgrent&lt;/CODE&gt;. You
+ must copy the contents of the structure if you wish to save the
+ information.
+ &lt;br&gt;&lt;br&gt; The stream must correspond to a file in the same format as the standard
+ group database file.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-fgetgrent_r" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="FILE *stream"/>
+ <parameter content="struct group *result_buf"/>
+ <parameter content="char *buffer"/>
+ <parameter content="size_t buflen"/>
+ <parameter content="struct group **result"/>
+ </prototype>
+ <headers>
+ <header filename = "grp.h"/>
+ </headers>
+ <synopsis>
+ This function is similar to &lt;CODE&gt;fgetgrent&lt;/CODE&gt; in that it reads the next
+ user entry from &lt;VAR&gt;stream&lt;/VAR&gt;. But the result is returned in the
+ structure pointed to by &lt;VAR&gt;result_buf&lt;/VAR&gt;. The first &lt;VAR&gt;buflen&lt;/VAR&gt; bytes
+ of the additional buffer pointed to by &lt;VAR&gt;buffer&lt;/VAR&gt; are used to contain
+ additional information, normally strings which are pointed to by the
+ elements of the result structure.
+ &lt;br&gt;&lt;br&gt; This stream must correspond to a file in the same format as the standard
+ group database file.
+ &lt;br&gt;&lt;br&gt; If the function returns zero &lt;VAR&gt;result&lt;/VAR&gt; points to the structure with
+ the wanted data (normally this is in &lt;VAR&gt;result_buf&lt;/VAR&gt;). If errors
+ occurred the return value is non-zero and &lt;VAR&gt;result&lt;/VAR&gt; contains a null
+ pointer.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-setgrent" type="function">
+ <function returntype="void">
+ <prototype>
+ <parameter content="void"/>
+ </prototype>
+ <headers>
+ <header filename = "grp.h"/>
+ </headers>
+ <synopsis>
+ This function initializes a stream for reading from the group data base.
+ You use this stream by calling &lt;CODE&gt;getgrent&lt;/CODE&gt; or &lt;CODE&gt;getgrent_r&lt;/CODE&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-getgrent" type="function">
+ <function returntype="struct group *">
+ <prototype>
+ <parameter content="void"/>
+ </prototype>
+ <headers>
+ <header filename = "grp.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;getgrent&lt;/CODE&gt; function reads the next entry from the stream
+ initialized by &lt;CODE&gt;setgrent&lt;/CODE&gt;. It returns a pointer to the entry. The
+ structure is statically allocated and is overwritten on subsequent calls
+ to &lt;CODE&gt;getgrent&lt;/CODE&gt;. You must copy the contents of the structure if you
+ wish to save the information.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-getgrent_r" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="struct group *result_buf"/>
+ <parameter content="char *buffer"/>
+ <parameter content="size_t buflen"/>
+ <parameter content="struct group **result"/>
+ </prototype>
+ <headers>
+ <header filename = "grp.h"/>
+ </headers>
+ <synopsis>
+ This function is similar to &lt;CODE&gt;getgrent&lt;/CODE&gt; in that it returns the next
+ entry from the stream initialized by &lt;CODE&gt;setgrent&lt;/CODE&gt;. Like
+ &lt;CODE&gt;fgetgrent_r&lt;/CODE&gt;, it places the result in user-supplied buffers
+ pointed to &lt;VAR&gt;result_buf&lt;/VAR&gt; and &lt;VAR&gt;buffer&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; If the function returns zero &lt;VAR&gt;result&lt;/VAR&gt; contains a pointer to the data
+ (normally equal to &lt;VAR&gt;result_buf&lt;/VAR&gt;). If errors occurred the return
+ value is non-zero and &lt;VAR&gt;result&lt;/VAR&gt; contains a null pointer.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-endgrent" type="function">
+ <function returntype="void">
+ <prototype>
+ <parameter content="void"/>
+ </prototype>
+ <headers>
+ <header filename = "grp.h"/>
+ </headers>
+ <synopsis>
+ This function closes the internal stream used by &lt;CODE&gt;getgrent&lt;/CODE&gt; or
+ &lt;CODE&gt;getgrent_r&lt;/CODE&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-setnetgrent" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *netgroup"/>
+ </prototype>
+ <headers>
+ <header filename = "netdb.h"/>
+ </headers>
+ <synopsis>
+ A call to this function initializes the internal state of the library to
+ allow following calls of the &lt;CODE&gt;getnetgrent&lt;/CODE&gt; to iterate over all entries
+ in the netgroup with name &lt;VAR&gt;netgroup&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; When the call is successful (i.e., when a netgroup with this name exists)
+ the return value is &lt;CODE&gt;1&lt;/CODE&gt;. When the return value is &lt;CODE&gt;0&lt;/CODE&gt; no
+ netgroup of this name is known or some other error occurred.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-getnetgrent" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="char **hostp"/>
+ <parameter content="char **userp"/>
+ <parameter content="char **domainp"/>
+ </prototype>
+ <headers>
+ <header filename = "netdb.h"/>
+ </headers>
+ <synopsis>
+ This function returns the next unprocessed entry of the currently
+ selected netgroup. The string pointers, in which addresses are passed in
+ the arguments &lt;VAR&gt;hostp&lt;/VAR&gt;, &lt;VAR&gt;userp&lt;/VAR&gt;, and &lt;VAR&gt;domainp&lt;/VAR&gt;, will contain
+ after a successful call pointers to appropriate strings. If the string
+ in the next entry is empty the pointer has the value &lt;CODE&gt;NULL&lt;/CODE&gt;.
+ The returned string pointers are only valid if none of the netgroup
+ related functions are called.
+ &lt;br&gt;&lt;br&gt; The return value is &lt;CODE&gt;1&lt;/CODE&gt; if the next entry was successfully read. A
+ value of &lt;CODE&gt;0&lt;/CODE&gt; means no further entries exist or internal errors occurred.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-getnetgrent_r" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="char **hostp"/>
+ <parameter content="char **userp"/>
+ <parameter content="char **domainp"/>
+ <parameter content="char *buffer"/>
+ <parameter content="int buflen"/>
+ </prototype>
+ <headers>
+ <header filename = "netdb.h"/>
+ </headers>
+ <synopsis>
+ This function is similar to &lt;CODE&gt;getnetgrent&lt;/CODE&gt; with only one exception:
+ the strings the three string pointers &lt;VAR&gt;hostp&lt;/VAR&gt;, &lt;VAR&gt;userp&lt;/VAR&gt;, and
+ &lt;VAR&gt;domainp&lt;/VAR&gt; point to, are placed in the buffer of &lt;VAR&gt;buflen&lt;/VAR&gt; bytes
+ starting at &lt;VAR&gt;buffer&lt;/VAR&gt;. This means the returned values are valid
+ even after other netgroup related functions are called.
+ &lt;br&gt;&lt;br&gt; The return value is &lt;CODE&gt;1&lt;/CODE&gt; if the next entry was successfully read and
+ the buffer contains enough room to place the strings in it. &lt;CODE&gt;0&lt;/CODE&gt; is
+ returned in case no more entries are found, the buffer is too small, or
+ internal errors occurred.
+ &lt;br&gt;&lt;br&gt; This function is a GNU extension. The original implementation in the
+ SunOS libc does not provide this function.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-endnetgrent" type="function">
+ <function returntype="void">
+ <prototype>
+ <parameter content="void"/>
+ </prototype>
+ <headers>
+ <header filename = "netdb.h"/>
+ </headers>
+ <synopsis>
+ This function frees all buffers which were allocated to process the last
+ selected netgroup. As a result all string pointers returned by calls
+ to &lt;CODE&gt;getnetgrent&lt;/CODE&gt; are invalid afterwards.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-innetgr" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *netgroup"/>
+ <parameter content="const char *host"/>
+ <parameter content="const char *user"/>
+ <parameter content="const char *domain"/>
+ </prototype>
+ <headers>
+ <header filename = "netdb.h"/>
+ </headers>
+ <synopsis>
+ This function tests whether the triple specified by the parameters
+ &lt;VAR&gt;hostp&lt;/VAR&gt;, &lt;VAR&gt;userp&lt;/VAR&gt;, and &lt;VAR&gt;domainp&lt;/VAR&gt; is part of the netgroup
+ &lt;VAR&gt;netgroup&lt;/VAR&gt;. Using this function has the advantage that
+ &lt;br&gt;&lt;br&gt; &lt;OL&gt;
+ &lt;LI&gt;
+ no other netgroup function can use the global netgroup state since
+ internal locking is used and
+ &lt;LI&gt;
+ the function is implemented more efficiently than successive calls
+ to the other &lt;CODE&gt;set&lt;/CODE&gt;/&lt;CODE&gt;get&lt;/CODE&gt;/&lt;CODE&gt;endnetgrent&lt;/CODE&gt; functions.
+ &lt;/OL&gt;
+ &lt;br&gt;&lt;br&gt; Any of the pointers &lt;VAR&gt;hostp&lt;/VAR&gt;, &lt;VAR&gt;userp&lt;/VAR&gt;, and &lt;VAR&gt;domainp&lt;/VAR&gt; can be
+ &lt;CODE&gt;NULL&lt;/CODE&gt; which means any value is accepted in this position. This is
+ also true for the name &lt;CODE&gt;-&lt;/CODE&gt; which should not match any other string
+ otherwise.
+ &lt;br&gt;&lt;br&gt; The return value is &lt;CODE&gt;1&lt;/CODE&gt; if an entry matching the given triple is
+ found in the netgroup. The return value is &lt;CODE&gt;0&lt;/CODE&gt; if the netgroup
+ itself is not found, the netgroup does not contain the triple or
+ internal errors occurred.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="struct-sockaddr" type="struct">
+ <structure>
+ <synopsis>
+ The &lt;CODE&gt;struct sockaddr&lt;/CODE&gt; type itself has the following members:
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ <elements>
+ <element content="short int sa_family">
+ <synopsis>
+ This is the code for the address format of this address. It
+ identifies the format of the data which follows.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ </elements>
+ </structure>
+ </construct>
+ <construct id="function-bind" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="int socket"/>
+ <parameter content="struct sockaddr *addr"/>
+ <parameter content="socklen_t length"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/socket.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;bind&lt;/CODE&gt; function assigns an address to the socket
+ &lt;VAR&gt;socket&lt;/VAR&gt;. The &lt;VAR&gt;addr&lt;/VAR&gt; and &lt;VAR&gt;length&lt;/VAR&gt; 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.
+ &lt;br&gt;&lt;br&gt; The return value is &lt;CODE&gt;0&lt;/CODE&gt; on success and &lt;CODE&gt;-1&lt;/CODE&gt; on failure. The
+ following &lt;CODE&gt;errno&lt;/CODE&gt; error conditions are defined for this function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EBADF&lt;/CODE&gt;
+&lt;DD&gt;
+ The &lt;VAR&gt;socket&lt;/VAR&gt; argument is not a valid file descriptor.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ENOTSOCK
+ The descriptor &lt;VAR&gt;socket&lt;/VAR&gt; is not a socket.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EADDRNOTAVAIL
+ The specified address is not available on this machine.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EADDRINUSE
+ Some other socket is already using the specified address.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EINVAL
+ The socket &lt;VAR&gt;socket&lt;/VAR&gt; already has an address.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; 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 &lt;CODE&gt;IPPORT_RESERVED&lt;/CODE&gt; minus one; see
+ Ports.)
+
+ &lt;br&gt;&lt;br&gt; Additional conditions may be possible depending on the particular namespace
+ of the socket.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-getsockname" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="int socket"/>
+ <parameter content="struct sockaddr *addr"/>
+ <parameter content="socklen_t *length-ptr"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/socket.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;getsockname&lt;/CODE&gt; function returns information about the
+ address of the socket &lt;VAR&gt;socket&lt;/VAR&gt; in the locations specified by the
+ &lt;VAR&gt;addr&lt;/VAR&gt; and &lt;VAR&gt;length-ptr&lt;/VAR&gt; arguments. Note that the
+ &lt;VAR&gt;length-ptr&lt;/VAR&gt; is a pointer; you should initialize it to be the
+ allocation size of &lt;VAR&gt;addr&lt;/VAR&gt;, and on return it contains the actual
+ size of the address data.
+ &lt;br&gt;&lt;br&gt; 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 &lt;CODE&gt;struct sockaddr *&lt;/CODE&gt; to pass it to &lt;CODE&gt;getsockname&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; The return value is &lt;CODE&gt;0&lt;/CODE&gt; on success and &lt;CODE&gt;-1&lt;/CODE&gt; on error. The
+ following &lt;CODE&gt;errno&lt;/CODE&gt; error conditions are defined for this function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EBADF&lt;/CODE&gt;
+&lt;DD&gt;
+ The &lt;VAR&gt;socket&lt;/VAR&gt; argument is not a valid file descriptor.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ENOTSOCK
+ The descriptor &lt;VAR&gt;socket&lt;/VAR&gt; is not a socket.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ENOBUFS
+ There are not enough internal buffers available for the operation.
+
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-if_nametoindex" type="function">
+ <function returntype="unsigned int">
+ <prototype>
+ <parameter content="const char *ifname"/>
+ </prototype>
+ <headers>
+ <header filename = "net/if.h"/>
+ </headers>
+ <synopsis>
+ This function yields the interface index corresponding to a particular
+ name. If no interface exists with the name given, it returns 0.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-if_indextoname" type="function">
+ <function returntype="char *">
+ <prototype>
+ <parameter content="unsigned int ifindex"/>
+ <parameter content="char *ifname"/>
+ </prototype>
+ <headers>
+ <header filename = "net/if.h"/>
+ </headers>
+ <synopsis>
+ This function maps an interface index to its corresponding name. The
+ returned name is placed in the buffer pointed to by &lt;CODE&gt;ifname&lt;/CODE&gt;, which
+ must be at least &lt;CODE&gt;IFNAMSIZ&lt;/CODE&gt; bytes in length. If the index was
+ invalid, the function's return value is a null pointer, otherwise it is
+ &lt;CODE&gt;ifname&lt;/CODE&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="struct-if_nameindex" type="struct">
+ <structure>
+ <synopsis>
+ This data type is used to hold the information about a single
+ interface. It has the following members:
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ <elements>
+ <element content="unsigned int if_index;">
+ <synopsis>
+ This is the interface index.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ </elements>
+ </structure>
+ </construct>
+ <construct id="function-if_nameindex" type="function">
+ <function returntype="struct if_nameindex *">
+ <prototype>
+ <parameter content="void"/>
+ </prototype>
+ <headers>
+ <header filename = "net/if.h"/>
+ </headers>
+ <synopsis>
+ This function returns an array of &lt;CODE&gt;if_nameindex&lt;/CODE&gt; 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.
+ &lt;br&gt;&lt;br&gt; The returned structure must be freed with &lt;CODE&gt;if_freenameindex&lt;/CODE&gt; after
+ use.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-if_freenameindex" type="function">
+ <function returntype="void">
+ <prototype>
+ <parameter content="struct if_nameindex *ptr"/>
+ </prototype>
+ <headers>
+ <header filename = "net/if.h"/>
+ </headers>
+ <synopsis>
+ This function frees the structure returned by an earlier call to
+ &lt;CODE&gt;if_nameindex&lt;/CODE&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="struct-sockaddr_un" type="struct">
+ <structure>
+ <synopsis>
+ This structure is used to specify local namespace socket addresses. It has
+ the following members:
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ <elements>
+ <element content="short int sun_family">
+ <synopsis>
+ This identifies the address family or format of the socket address.
+ You should store the value &lt;CODE&gt;AF_LOCAL&lt;/CODE&gt; to designate the local
+ namespace. .
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ </elements>
+ </structure>
+ </construct>
+ <construct id="struct-sockaddr_in" type="struct">
+ <structure>
+ <synopsis>
+ This is the data type used to represent socket addresses in the
+ Internet namespace. It has the following members:
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ <elements>
+ <element content="sa_family_t sin_family">
+ <synopsis>
+ This identifies the address family or format of the socket address.
+ You should store the value &lt;CODE&gt;AF_INET&lt;/CODE&gt; in this member.
+ .
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="struct in_addr sin_addr">
+ <synopsis>
+ This is the Internet address of the host machine. , and Host Names, for how to get a value to store
+ here.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ </elements>
+ </structure>
+ </construct>
+ <construct id="struct-sockaddr_in6" type="struct">
+ <structure>
+ <synopsis>
+ This is the data type used to represent socket addresses in the IPv6
+ namespace. It has the following members:
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ <elements>
+ <element content="sa_family_t sin6_family">
+ <synopsis>
+ This identifies the address family or format of the socket address.
+ You should store the value of &lt;CODE&gt;AF_INET6&lt;/CODE&gt; in this member.
+ .
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="struct in6_addr sin6_addr">
+ <synopsis>
+ This is the IPv6 address of the host machine. , and Host Names, for how to get a value to store
+ here.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="uint32_t sin6_flowinfo">
+ <synopsis>
+ This is a currently unimplemented field.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ </elements>
+ </structure>
+ </construct>
+ <construct id="struct-in_addr" type="struct">
+ <structure>
+ </structure>
+ </construct>
+ <construct id="struct-in6_addr" type="struct">
+ <structure>
+ </structure>
+ </construct>
+ <construct id="function-inet_aton" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *name"/>
+ <parameter content="struct in_addr *addr"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/socket.h"/>
+ <header filename = "netinet/in.h"/>
+ <header filename = "arpa/inet.h"/>
+ </headers>
+ <synopsis>
+ This function converts the IPv4 Internet host address &lt;VAR&gt;name&lt;/VAR&gt;
+ from the standard numbers-and-dots notation into binary data and stores
+ it in the &lt;CODE&gt;struct in_addr&lt;/CODE&gt; that &lt;VAR&gt;addr&lt;/VAR&gt; points to.
+ &lt;CODE&gt;inet_aton&lt;/CODE&gt; returns nonzero if the address is valid, zero if not.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-inet_addr" type="function">
+ <function returntype="uint32_t">
+ <prototype>
+ <parameter content="const char *name"/>
+ </prototype>
+ <headers>
+ <header filename = "arpa/inet.h"/>
+ </headers>
+ <synopsis>
+ This function converts the IPv4 Internet host address &lt;VAR&gt;name&lt;/VAR&gt; from the
+ standard numbers-and-dots notation into binary data. If the input is
+ not valid, &lt;CODE&gt;inet_addr&lt;/CODE&gt; returns &lt;CODE&gt;INADDR_NONE&lt;/CODE&gt;. This is an
+ obsolete interface to &lt;CODE&gt;inet_aton&lt;/CODE&gt;, described immediately above. It
+ is obsolete because &lt;CODE&gt;INADDR_NONE&lt;/CODE&gt; is a valid address
+ (255.255.255.255), and &lt;CODE&gt;inet_aton&lt;/CODE&gt; provides a cleaner way to
+ indicate error return.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-inet_network" type="function">
+ <function returntype="uint32_t">
+ <prototype>
+ <parameter content="const char *name"/>
+ </prototype>
+ <headers>
+ <header filename = "arpa/inet.h"/>
+ </headers>
+ <synopsis>
+ This function extracts the network number from the address &lt;VAR&gt;name&lt;/VAR&gt;,
+ given in the standard numbers-and-dots notation. The returned address is
+ in host order. If the input is not valid, &lt;CODE&gt;inet_network&lt;/CODE&gt; returns
+ &lt;CODE&gt;-1&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; 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.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-inet_ntoa" type="function">
+ <function returntype="char *">
+ <prototype>
+ <parameter content="struct in_addr addr"/>
+ </prototype>
+ <headers>
+ <header filename = "arpa/inet.h"/>
+ </headers>
+ <synopsis>
+ This function converts the IPv4 Internet host address &lt;VAR&gt;addr&lt;/VAR&gt; 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.
+ &lt;br&gt;&lt;br&gt; In multi-threaded programs each thread has an own statically-allocated
+ buffer. But still subsequent calls of &lt;CODE&gt;inet_ntoa&lt;/CODE&gt; in the same
+ thread will overwrite the result of the last call.
+ &lt;br&gt;&lt;br&gt; Instead of &lt;CODE&gt;inet_ntoa&lt;/CODE&gt; the newer function &lt;CODE&gt;inet_ntop&lt;/CODE&gt; which is
+ described below should be used since it handles both IPv4 and IPv6
+ addresses.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-inet_makeaddr" type="function">
+ <function returntype="struct in_addr">
+ <prototype>
+ <parameter content="uint32_t net"/>
+ <parameter content="uint32_t local"/>
+ </prototype>
+ <headers>
+ <header filename = "arpa/inet.h"/>
+ </headers>
+ <synopsis>
+ This function makes an IPv4 Internet host address by combining the network
+ number &lt;VAR&gt;net&lt;/VAR&gt; with the local-address-within-network number
+ &lt;VAR&gt;local&lt;/VAR&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-inet_lnaof" type="function">
+ <function returntype="uint32_t">
+ <prototype>
+ <parameter content="struct in_addr addr"/>
+ </prototype>
+ <headers>
+ <header filename = "arpa/inet.h"/>
+ </headers>
+ <synopsis>
+ This function returns the local-address-within-network part of the
+ Internet host address &lt;VAR&gt;addr&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; 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.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-inet_netof" type="function">
+ <function returntype="uint32_t">
+ <prototype>
+ <parameter content="struct in_addr addr"/>
+ </prototype>
+ <headers>
+ <header filename = "arpa/inet.h"/>
+ </headers>
+ <synopsis>
+ This function returns the network number part of the Internet host
+ address &lt;VAR&gt;addr&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; 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.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-inet_pton" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="int af"/>
+ <parameter content="const char *cp"/>
+ <parameter content="void *buf"/>
+ </prototype>
+ <headers>
+ <header filename = "arpa/inet.h"/>
+ </headers>
+ <synopsis>
+ This function converts an Internet address (either IPv4 or IPv6) from
+ presentation (textual) to network (binary) format. &lt;VAR&gt;af&lt;/VAR&gt; should be
+ either &lt;CODE&gt;AF_INET&lt;/CODE&gt; or &lt;CODE&gt;AF_INET6&lt;/CODE&gt;, as appropriate for the type of
+ address being converted. &lt;VAR&gt;cp&lt;/VAR&gt; is a pointer to the input string, and
+ &lt;VAR&gt;buf&lt;/VAR&gt; is a pointer to a buffer for the result. It is the caller's
+ responsibility to make sure the buffer is large enough.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-inet_ntop" type="function">
+ <function returntype="const char *">
+ <prototype>
+ <parameter content="int af"/>
+ <parameter content="const void *cp"/>
+ <parameter content="char *buf"/>
+ <parameter content="size_t len"/>
+ </prototype>
+ <headers>
+ <header filename = "arpa/inet.h"/>
+ </headers>
+ <synopsis>
+ This function converts an Internet address (either IPv4 or IPv6) from
+ network (binary) to presentation (textual) form. &lt;VAR&gt;af&lt;/VAR&gt; should be
+ either &lt;CODE&gt;AF_INET&lt;/CODE&gt; or &lt;CODE&gt;AF_INET6&lt;/CODE&gt;, as appropriate. &lt;VAR&gt;cp&lt;/VAR&gt; is a
+ pointer to the address to be converted. &lt;VAR&gt;buf&lt;/VAR&gt; should be a pointer
+ to a buffer to hold the result, and &lt;VAR&gt;len&lt;/VAR&gt; is the length of this
+ buffer. The return value from the function will be this buffer address.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="struct-hostent" type="struct">
+ <structure>
+ <synopsis>
+ This data type is used to represent an entry in the hosts database. It
+ has the following members:
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ <elements>
+ <element content="char *h_name">
+ <synopsis>
+ This is the ``official'' name of the host.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="char **h_aliases">
+ <synopsis>
+ These are alternative names for the host, represented as a null-terminated
+ vector of strings.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="int h_addrtype">
+ <synopsis>
+ This is the host address type; in practice, its value is always either
+ &lt;CODE&gt;AF_INET&lt;/CODE&gt; or &lt;CODE&gt;AF_INET6&lt;/CODE&gt;, with the latter being used for IPv6
+ hosts. In principle other kinds of addresses could be represented in
+ the database as well as Internet addresses; if this were done, you
+ might find a value in this field other than &lt;CODE&gt;AF_INET&lt;/CODE&gt; or
+ &lt;CODE&gt;AF_INET6&lt;/CODE&gt;. .
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="int h_length">
+ <synopsis>
+ This is the length, in bytes, of each address.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="char **h_addr_list">
+ <synopsis>
+ This is the vector of addresses for the host. (Recall that the host
+ might be connected to multiple networks and have different addresses on
+ each one.) The vector is terminated by a null pointer.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ </elements>
+ </structure>
+ </construct>
+ <construct id="function-gethostbyname" type="function">
+ <function returntype="struct hostent *">
+ <prototype>
+ <parameter content="const char *name"/>
+ </prototype>
+ <headers>
+ <header filename = "netdb.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;gethostbyname&lt;/CODE&gt; function returns information about the host
+ named &lt;VAR&gt;name&lt;/VAR&gt;. If the lookup fails, it returns a null pointer.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-gethostbyname2" type="function">
+ <function returntype="struct hostent *">
+ <prototype>
+ <parameter content="const char *name"/>
+ <parameter content="int af"/>
+ </prototype>
+ <headers>
+ <header filename = "netdb.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;gethostbyname2&lt;/CODE&gt; function is like &lt;CODE&gt;gethostbyname&lt;/CODE&gt;, but
+ allows the caller to specify the desired address family (e.g.:
+ &lt;CODE&gt;AF_INET&lt;/CODE&gt; or &lt;CODE&gt;AF_INET6&lt;/CODE&gt;) of the result.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-gethostbyaddr" type="function">
+ <function returntype="struct hostent *">
+ <prototype>
+ <parameter content="const char *addr"/>
+ <parameter content="size_t length"/>
+ <parameter content="int format"/>
+ </prototype>
+ <headers>
+ <header filename = "netdb.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;gethostbyaddr&lt;/CODE&gt; function returns information about the host
+ with Internet address &lt;VAR&gt;addr&lt;/VAR&gt;. The parameter &lt;VAR&gt;addr&lt;/VAR&gt; is not
+ really a pointer to char - it can be a pointer to an IPv4 or an IPv6
+ address. The &lt;VAR&gt;length&lt;/VAR&gt; argument is the size (in bytes) of the address
+ at &lt;VAR&gt;addr&lt;/VAR&gt;. &lt;VAR&gt;format&lt;/VAR&gt; specifies the address format; for an IPv4
+ Internet address, specify a value of &lt;CODE&gt;AF_INET&lt;/CODE&gt;; for an IPv6
+ Internet address, use &lt;CODE&gt;AF_INET6&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; If the lookup fails, &lt;CODE&gt;gethostbyaddr&lt;/CODE&gt; returns a null pointer.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-gethostbyname_r" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *restrict name"/>
+ <parameter content="struct hostent *restrict result_buf"/>
+ <parameter content="char *restrict buf"/>
+ <parameter content="size_t buflen"/>
+ <parameter content="struct hostent **restrict result"/>
+ <parameter content="int *restrict h_errnop"/>
+ </prototype>
+ <headers>
+ <header filename = "netdb.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;gethostbyname_r&lt;/CODE&gt; function returns information about the host
+ named &lt;VAR&gt;name&lt;/VAR&gt;. The caller must pass a pointer to an object of type
+ &lt;CODE&gt;struct hostent&lt;/CODE&gt; in the &lt;VAR&gt;result_buf&lt;/VAR&gt; 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 &lt;VAR&gt;buf&lt;/VAR&gt; and &lt;VAR&gt;buflen&lt;/VAR&gt;
+ parameters.
+ &lt;br&gt;&lt;br&gt; A pointer to the buffer, in which the result is stored, is available in
+ &lt;CODE&gt;*&lt;VAR&gt;result&lt;/VAR&gt;&lt;/CODE&gt; after the function call successfully returned. If
+ an error occurs or if no entry is found, the pointer &lt;CODE&gt;*&lt;VAR&gt;result&lt;/VAR&gt;&lt;/CODE&gt;
+ 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 &lt;CODE&gt;gethostbyname&lt;/CODE&gt; it can also be &lt;CODE&gt;ERANGE&lt;/CODE&gt;.
+ In this case the call should be repeated with a larger buffer.
+ Additional error information is not stored in the global variable
+ &lt;CODE&gt;h_errno&lt;/CODE&gt; but instead in the object pointed to by &lt;VAR&gt;h_errnop&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; Here's a small example:
+ &lt;pre&gt;&lt;br&gt;
+ struct hostent *&lt;br&gt;
+ gethostname (char *host)&lt;br&gt;
+ {&lt;br&gt;
+ struct hostent hostbuf, *hp;&lt;br&gt;
+ size_t hstbuflen;&lt;br&gt;
+ char *tmphstbuf;&lt;br&gt;
+ int res;&lt;br&gt;
+ int herr;&lt;br&gt;
+ &lt;br&gt;&lt;br&gt; hstbuflen = 1024;&lt;br&gt;
+ /* Allocate buffer, remember to free it to avoid memory leakage. */&lt;br&gt;
+ tmphstbuf = malloc (hstbuflen);&lt;br&gt;
+ &lt;br&gt;&lt;br&gt; while ((res = gethostbyname_r (host, &amp;hostbuf, tmphstbuf, hstbuflen,&lt;br&gt;
+ &amp;hp, &amp;herr)) == ERANGE)&lt;br&gt;
+ {&lt;br&gt;
+ /* Enlarge the buffer. */&lt;br&gt;
+ hstbuflen *= 2;&lt;br&gt;
+ tmphstbuf = realloc (tmphstbuf, hstbuflen);&lt;br&gt;
+ }&lt;br&gt;
+ /* Check for errors. */&lt;br&gt;
+ if (res || hp == NULL)&lt;br&gt;
+ return NULL;&lt;br&gt;
+ return hp;&lt;br&gt;
+ }&lt;br&gt;
+ &lt;/pre&gt;
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-gethostbyname2_r" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *name"/>
+ <parameter content="int af"/>
+ <parameter content="struct hostent *restrict result_buf"/>
+ <parameter content="char *restrict buf"/>
+ <parameter content="size_t buflen"/>
+ <parameter content="struct hostent **restrict result"/>
+ <parameter content="int *restrict h_errnop"/>
+ </prototype>
+ <headers>
+ <header filename = "netdb.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;gethostbyname2_r&lt;/CODE&gt; function is like &lt;CODE&gt;gethostbyname_r&lt;/CODE&gt;, but
+ allows the caller to specify the desired address family (e.g.:
+ &lt;CODE&gt;AF_INET&lt;/CODE&gt; or &lt;CODE&gt;AF_INET6&lt;/CODE&gt;) for the result.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-gethostbyaddr_r" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *addr"/>
+ <parameter content="size_t length"/>
+ <parameter content="int format"/>
+ <parameter content="struct hostent *restrict result_buf"/>
+ <parameter content="char *restrict buf"/>
+ <parameter content="size_t buflen"/>
+ <parameter content="struct hostent **restrict result"/>
+ <parameter content="int *restrict h_errnop"/>
+ </prototype>
+ <headers>
+ <header filename = "netdb.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;gethostbyaddr_r&lt;/CODE&gt; function returns information about the host
+ with Internet address &lt;VAR&gt;addr&lt;/VAR&gt;. The parameter &lt;VAR&gt;addr&lt;/VAR&gt; is not
+ really a pointer to char - it can be a pointer to an IPv4 or an IPv6
+ address. The &lt;VAR&gt;length&lt;/VAR&gt; argument is the size (in bytes) of the address
+ at &lt;VAR&gt;addr&lt;/VAR&gt;. &lt;VAR&gt;format&lt;/VAR&gt; specifies the address format; for an IPv4
+ Internet address, specify a value of &lt;CODE&gt;AF_INET&lt;/CODE&gt;; for an IPv6
+ Internet address, use &lt;CODE&gt;AF_INET6&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; Similar to the &lt;CODE&gt;gethostbyname_r&lt;/CODE&gt; 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
+ &lt;CODE&gt;ERANGE&lt;/CODE&gt; has the special meaning that the caller-provided buffer is
+ too small.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-sethostent" type="function">
+ <function returntype="void">
+ <prototype>
+ <parameter content="int stayopen"/>
+ </prototype>
+ <headers>
+ <header filename = "netdb.h"/>
+ </headers>
+ <synopsis>
+ This function opens the hosts database to begin scanning it. You can
+ then call &lt;CODE&gt;gethostent&lt;/CODE&gt; to read the entries.
+ &lt;br&gt;&lt;br&gt; If the &lt;VAR&gt;stayopen&lt;/VAR&gt; argument is nonzero, this sets a flag so that
+ subsequent calls to &lt;CODE&gt;gethostbyname&lt;/CODE&gt; or &lt;CODE&gt;gethostbyaddr&lt;/CODE&gt; 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.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-gethostent" type="function">
+ <function returntype="struct hostent *">
+ <prototype>
+ <parameter content="void"/>
+ </prototype>
+ <headers>
+ <header filename = "netdb.h"/>
+ </headers>
+ <synopsis>
+ This function returns the next entry in the hosts database. It
+ returns a null pointer if there are no more entries.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-endhostent" type="function">
+ <function returntype="void">
+ <prototype>
+ <parameter content="void"/>
+ </prototype>
+ <headers>
+ <header filename = "netdb.h"/>
+ </headers>
+ <synopsis>
+ This function closes the hosts database.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="struct-servent" type="struct">
+ <structure>
+ <synopsis>
+ This data type holds information about entries from the services database.
+ It has the following members:
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ <elements>
+ <element content="char *s_name">
+ <synopsis>
+ This is the ``official'' name of the service.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="char **s_aliases">
+ <synopsis>
+ These are alternate names for the service, represented as an array of
+ strings. A null pointer terminates the array.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="int s_port">
+ <synopsis>
+ This is the port number for the service. Port numbers are given in
+ network byte order; see Byte Order.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ </elements>
+ </structure>
+ </construct>
+ <construct id="function-getservbyname" type="function">
+ <function returntype="struct servent *">
+ <prototype>
+ <parameter content="const char *name"/>
+ <parameter content="const char *proto"/>
+ </prototype>
+ <headers>
+ <header filename = "netinet/in.h"/>
+ <header filename = "netdb.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;getservbyname&lt;/CODE&gt; function returns information about the
+ service named &lt;VAR&gt;name&lt;/VAR&gt; using protocol &lt;VAR&gt;proto&lt;/VAR&gt;. If it can't find
+ such a service, it returns a null pointer.
+ &lt;br&gt;&lt;br&gt; This function is useful for servers as well as for clients; servers
+ use it to determine which port they should listen on .
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-getservbyport" type="function">
+ <function returntype="struct servent *">
+ <prototype>
+ <parameter content="int port"/>
+ <parameter content="const char *proto"/>
+ </prototype>
+ <headers>
+ <header filename = "netdb.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;getservbyport&lt;/CODE&gt; function returns information about the
+ service at port &lt;VAR&gt;port&lt;/VAR&gt; using protocol &lt;VAR&gt;proto&lt;/VAR&gt;. If it can't
+ find such a service, it returns a null pointer.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-setservent" type="function">
+ <function returntype="void">
+ <prototype>
+ <parameter content="int stayopen"/>
+ </prototype>
+ <headers>
+ <header filename = "netdb.h"/>
+ </headers>
+ <synopsis>
+ This function opens the services database to begin scanning it.
+ &lt;br&gt;&lt;br&gt; If the &lt;VAR&gt;stayopen&lt;/VAR&gt; argument is nonzero, this sets a flag so that
+ subsequent calls to &lt;CODE&gt;getservbyname&lt;/CODE&gt; or &lt;CODE&gt;getservbyport&lt;/CODE&gt; 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.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-getservent" type="function">
+ <function returntype="struct servent *">
+ <prototype>
+ <parameter content="void"/>
+ </prototype>
+ <headers>
+ <header filename = "netdb.h"/>
+ </headers>
+ <synopsis>
+ This function returns the next entry in the services database. If
+ there are no more entries, it returns a null pointer.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-endservent" type="function">
+ <function returntype="void">
+ <prototype>
+ <parameter content="void"/>
+ </prototype>
+ <headers>
+ <header filename = "netdb.h"/>
+ </headers>
+ <synopsis>
+ This function closes the services database.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-htons" type="function">
+ <function returntype="uint16_t">
+ <prototype>
+ <parameter content="uint16_t hostshort"/>
+ </prototype>
+ <headers>
+ <header filename = "netinet/in.h"/>
+ </headers>
+ <synopsis>
+ This function converts the &lt;CODE&gt;uint16_t&lt;/CODE&gt; integer &lt;VAR&gt;hostshort&lt;/VAR&gt; from
+ host byte order to network byte order.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-ntohs" type="function">
+ <function returntype="uint16_t">
+ <prototype>
+ <parameter content="uint16_t netshort"/>
+ </prototype>
+ <headers>
+ <header filename = "netinet/in.h"/>
+ </headers>
+ <synopsis>
+ This function converts the &lt;CODE&gt;uint16_t&lt;/CODE&gt; integer &lt;VAR&gt;netshort&lt;/VAR&gt; from
+ network byte order to host byte order.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-htonl" type="function">
+ <function returntype="uint32_t">
+ <prototype>
+ <parameter content="uint32_t hostlong"/>
+ </prototype>
+ <headers>
+ <header filename = "netinet/in.h"/>
+ </headers>
+ <synopsis>
+ This function converts the &lt;CODE&gt;uint32_t&lt;/CODE&gt; integer &lt;VAR&gt;hostlong&lt;/VAR&gt; from
+ host byte order to network byte order.
+ &lt;br&gt;&lt;br&gt; This is used for IPv4 Internet addresses.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-ntohl" type="function">
+ <function returntype="uint32_t">
+ <prototype>
+ <parameter content="uint32_t netlong"/>
+ </prototype>
+ <headers>
+ <header filename = "netinet/in.h"/>
+ </headers>
+ <synopsis>
+ This function converts the &lt;CODE&gt;uint32_t&lt;/CODE&gt; integer &lt;VAR&gt;netlong&lt;/VAR&gt; from
+ network byte order to host byte order.
+ &lt;br&gt;&lt;br&gt; This is used for IPv4 Internet addresses.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="struct-protoent" type="struct">
+ <structure>
+ <synopsis>
+ This data type is used to represent entries in the network protocols
+ database. It has the following members:
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ <elements>
+ <element content="char *p_name">
+ <synopsis>
+ This is the official name of the protocol.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="char **p_aliases">
+ <synopsis>
+ These are alternate names for the protocol, specified as an array of
+ strings. The last element of the array is a null pointer.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ </elements>
+ </structure>
+ </construct>
+ <construct id="function-getprotobyname" type="function">
+ <function returntype="struct protoent *">
+ <prototype>
+ <parameter content="const char *name"/>
+ </prototype>
+ <headers>
+ <header filename = "netdb.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;getprotobyname&lt;/CODE&gt; function returns information about the
+ network protocol named &lt;VAR&gt;name&lt;/VAR&gt;. If there is no such protocol, it
+ returns a null pointer.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-getprotobynumber" type="function">
+ <function returntype="struct protoent *">
+ <prototype>
+ <parameter content="int protocol"/>
+ </prototype>
+ <headers>
+ <header filename = "netdb.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;getprotobynumber&lt;/CODE&gt; function returns information about the
+ network protocol with number &lt;VAR&gt;protocol&lt;/VAR&gt;. If there is no such
+ protocol, it returns a null pointer.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-setprotoent" type="function">
+ <function returntype="void">
+ <prototype>
+ <parameter content="int stayopen"/>
+ </prototype>
+ <headers>
+ <header filename = "netdb.h"/>
+ </headers>
+ <synopsis>
+ This function opens the protocols database to begin scanning it.
+ &lt;br&gt;&lt;br&gt; If the &lt;VAR&gt;stayopen&lt;/VAR&gt; argument is nonzero, this sets a flag so that
+ subsequent calls to &lt;CODE&gt;getprotobyname&lt;/CODE&gt; or &lt;CODE&gt;getprotobynumber&lt;/CODE&gt; 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.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-getprotoent" type="function">
+ <function returntype="struct protoent *">
+ <prototype>
+ <parameter content="void"/>
+ </prototype>
+ <headers>
+ <header filename = "netdb.h"/>
+ </headers>
+ <synopsis>
+ This function returns the next entry in the protocols database. It
+ returns a null pointer if there are no more entries.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-endprotoent" type="function">
+ <function returntype="void">
+ <prototype>
+ <parameter content="void"/>
+ </prototype>
+ <headers>
+ <header filename = "netdb.h"/>
+ </headers>
+ <synopsis>
+ This function closes the protocols database.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-socket" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="int namespace"/>
+ <parameter content="int style"/>
+ <parameter content="int protocol"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/socket.h"/>
+ </headers>
+ <synopsis>
+ This function creates a socket and specifies communication style
+ &lt;VAR&gt;style&lt;/VAR&gt;, which should be one of the socket styles listed in
+ Communication Styles. The &lt;VAR&gt;namespace&lt;/VAR&gt; argument specifies
+ the namespace; it must be &lt;CODE&gt;PF_LOCAL&lt;/CODE&gt; or
+ &lt;CODE&gt;PF_INET&lt;/CODE&gt; . &lt;VAR&gt;protocol&lt;/VAR&gt;
+ designates the specific protocol ; zero is
+ usually right for &lt;VAR&gt;protocol&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; The return value from &lt;CODE&gt;socket&lt;/CODE&gt; is the file descriptor for the new
+ socket, or &lt;CODE&gt;-1&lt;/CODE&gt; in case of error. The following &lt;CODE&gt;errno&lt;/CODE&gt; error
+ conditions are defined for this function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EPROTONOSUPPORT&lt;/CODE&gt;
+&lt;DD&gt;
+ The &lt;VAR&gt;protocol&lt;/VAR&gt; or &lt;VAR&gt;style&lt;/VAR&gt; is not supported by the
+ &lt;VAR&gt;namespace&lt;/VAR&gt; specified.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EMFILE
+ The process already has too many file descriptors open.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ENFILE
+ The system already has too many file descriptors open.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EACCES
+ The process does not have the privilege to create a socket of the specified
+ &lt;VAR&gt;style&lt;/VAR&gt; or &lt;VAR&gt;protocol&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ENOBUFS
+ The system ran out of internal buffer space.
+
+ &lt;br&gt;&lt;br&gt; The file descriptor returned by the &lt;CODE&gt;socket&lt;/CODE&gt; function supports both
+ read and write operations. However, like pipes, sockets do not support file
+ positioning operations.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-shutdown" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="int socket"/>
+ <parameter content="int how"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/socket.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;shutdown&lt;/CODE&gt; function shuts down the connection of socket
+ &lt;VAR&gt;socket&lt;/VAR&gt;. The argument &lt;VAR&gt;how&lt;/VAR&gt; specifies what action to
+ perform:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;0&lt;/CODE&gt;
+&lt;DD&gt;
+ Stop receiving data for this socket. If further data arrives,
+ reject it.
+ &lt;br&gt;&lt;br&gt; &lt;DT&gt;&lt;CODE&gt;1&lt;/CODE&gt;
+&lt;DD&gt;
+ 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.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; 2
+ Stop both reception and transmission.
+
+ &lt;br&gt;&lt;br&gt; The return value is &lt;CODE&gt;0&lt;/CODE&gt; on success and &lt;CODE&gt;-1&lt;/CODE&gt; on failure. The
+ following &lt;CODE&gt;errno&lt;/CODE&gt; error conditions are defined for this function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;LI&gt; EBADF
+ &lt;VAR&gt;socket&lt;/VAR&gt; is not a valid file descriptor.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ENOTSOCK
+ &lt;VAR&gt;socket&lt;/VAR&gt; is not a socket.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ENOTCONN
+ &lt;VAR&gt;socket&lt;/VAR&gt; is not connected.
+
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-socketpair" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="int namespace"/>
+ <parameter content="int style"/>
+ <parameter content="int protocol"/>
+ <parameter content="int filedes[2]"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/socket.h"/>
+ </headers>
+ <synopsis>
+ This function creates a socket pair, returning the file descriptors in
+ &lt;CODE&gt;&lt;VAR&gt;filedes&lt;/VAR&gt;[0]&lt;/CODE&gt; and &lt;CODE&gt;&lt;VAR&gt;filedes&lt;/VAR&gt;[1]&lt;/CODE&gt;. The socket pair
+ is a full-duplex communications channel, so that both reading and writing
+ may be performed at either end.
+ &lt;br&gt;&lt;br&gt; The &lt;VAR&gt;namespace&lt;/VAR&gt;, &lt;VAR&gt;style&lt;/VAR&gt; and &lt;VAR&gt;protocol&lt;/VAR&gt; arguments are
+ interpreted as for the &lt;CODE&gt;socket&lt;/CODE&gt; function. &lt;VAR&gt;style&lt;/VAR&gt; should be
+ one of the communication styles listed in Communication Styles.
+ The &lt;VAR&gt;namespace&lt;/VAR&gt; argument specifies the namespace, which must be
+ &lt;CODE&gt;AF_LOCAL&lt;/CODE&gt; ; &lt;VAR&gt;protocol&lt;/VAR&gt; specifies the
+ communications protocol, but zero is the only meaningful value.
+ &lt;br&gt;&lt;br&gt; If &lt;VAR&gt;style&lt;/VAR&gt; specifies a connectionless communication style, then
+ the two sockets you get are not &lt;EM&gt;connected&lt;/EM&gt;, strictly speaking,
+ but each of them knows the other as the default destination address,
+ so they can send packets to each other.
+ &lt;br&gt;&lt;br&gt; The &lt;CODE&gt;socketpair&lt;/CODE&gt; function returns &lt;CODE&gt;0&lt;/CODE&gt; on success and &lt;CODE&gt;-1&lt;/CODE&gt;
+ on failure. The following &lt;CODE&gt;errno&lt;/CODE&gt; error conditions are defined
+ for this function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EMFILE&lt;/CODE&gt;
+&lt;DD&gt;
+ The process has too many file descriptors open.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EAFNOSUPPORT
+ The specified namespace is not supported.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EPROTONOSUPPORT
+ The specified protocol is not supported.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EOPNOTSUPP
+ The specified protocol does not support the creation of socket pairs.
+
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-connect" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="int socket"/>
+ <parameter content="struct sockaddr *addr"/>
+ <parameter content="socklen_t length"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/socket.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;connect&lt;/CODE&gt; function initiates a connection from the socket
+ with file descriptor &lt;VAR&gt;socket&lt;/VAR&gt; to the socket whose address is
+ specified by the &lt;VAR&gt;addr&lt;/VAR&gt; and &lt;VAR&gt;length&lt;/VAR&gt; 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.
+ &lt;br&gt;&lt;br&gt; Normally, &lt;CODE&gt;connect&lt;/CODE&gt; waits until the server responds to the request
+ before it returns. You can set nonblocking mode on the socket
+ &lt;VAR&gt;socket&lt;/VAR&gt; to make &lt;CODE&gt;connect&lt;/CODE&gt; return immediately without waiting
+ for the response. , for information about
+ nonblocking mode.
+ &lt;br&gt;&lt;br&gt; The normal return value from &lt;CODE&gt;connect&lt;/CODE&gt; is &lt;CODE&gt;0&lt;/CODE&gt;. If an error
+ occurs, &lt;CODE&gt;connect&lt;/CODE&gt; returns &lt;CODE&gt;-1&lt;/CODE&gt;. The following &lt;CODE&gt;errno&lt;/CODE&gt;
+ error conditions are defined for this function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EBADF&lt;/CODE&gt;
+&lt;DD&gt;
+ The socket &lt;VAR&gt;socket&lt;/VAR&gt; is not a valid file descriptor.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ENOTSOCK
+ File descriptor &lt;VAR&gt;socket&lt;/VAR&gt; is not a socket.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EADDRNOTAVAIL
+ The specified address is not available on the remote machine.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EAFNOSUPPORT
+ The namespace of the &lt;VAR&gt;addr&lt;/VAR&gt; is not supported by this socket.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EISCONN
+ The socket &lt;VAR&gt;socket&lt;/VAR&gt; is already connected.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ETIMEDOUT
+ The attempt to establish the connection timed out.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ECONNREFUSED
+ The server has actively refused to establish the connection.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ENETUNREACH
+ The network of the given &lt;VAR&gt;addr&lt;/VAR&gt; isn't reachable from this host.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EADDRINUSE
+ The socket address of the given &lt;VAR&gt;addr&lt;/VAR&gt; is already in use.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EINPROGRESS
+ The socket &lt;VAR&gt;socket&lt;/VAR&gt; is non-blocking and the connection could not be
+ established immediately. You can determine when the connection is
+ completely established with &lt;CODE&gt;select&lt;/CODE&gt;; .
+ Another &lt;CODE&gt;connect&lt;/CODE&gt; call on the same socket, before the connection is
+ completely established, will fail with &lt;CODE&gt;EALREADY&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EALREADY
+ The socket &lt;VAR&gt;socket&lt;/VAR&gt; is non-blocking and already has a pending
+ connection in progress (see &lt;CODE&gt;EINPROGRESS&lt;/CODE&gt; above).
+
+ &lt;br&gt;&lt;br&gt; 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.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-listen" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="int socket"/>
+ <parameter content="int n"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/socket.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;listen&lt;/CODE&gt; function enables the socket &lt;VAR&gt;socket&lt;/VAR&gt; to accept
+ connections, thus making it a server socket.
+ &lt;br&gt;&lt;br&gt; The argument &lt;VAR&gt;n&lt;/VAR&gt; specifies the length of the queue for pending
+ connections. When the queue fills, new clients attempting to connect
+ fail with &lt;CODE&gt;ECONNREFUSED&lt;/CODE&gt; until the server calls &lt;CODE&gt;accept&lt;/CODE&gt; to
+ accept a connection from the queue.
+ &lt;br&gt;&lt;br&gt; The &lt;CODE&gt;listen&lt;/CODE&gt; function returns &lt;CODE&gt;0&lt;/CODE&gt; on success and &lt;CODE&gt;-1&lt;/CODE&gt;
+ on failure. The following &lt;CODE&gt;errno&lt;/CODE&gt; error conditions are defined
+ for this function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EBADF&lt;/CODE&gt;
+&lt;DD&gt;
+ The argument &lt;VAR&gt;socket&lt;/VAR&gt; is not a valid file descriptor.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ENOTSOCK
+ The argument &lt;VAR&gt;socket&lt;/VAR&gt; is not a socket.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EOPNOTSUPP
+ The socket &lt;VAR&gt;socket&lt;/VAR&gt; does not support this operation.
+
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-accept" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="int socket"/>
+ <parameter content="struct sockaddr *addr"/>
+ <parameter content="socklen_t *length_ptr"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/socket.h"/>
+ </headers>
+ <synopsis>
+ This function is used to accept a connection request on the server
+ socket &lt;VAR&gt;socket&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; The &lt;CODE&gt;accept&lt;/CODE&gt; function waits if there are no connections pending,
+ unless the socket &lt;VAR&gt;socket&lt;/VAR&gt; has nonblocking mode set. (You can use
+ &lt;CODE&gt;select&lt;/CODE&gt; to wait for a pending connection, with a nonblocking
+ socket.) , for information about nonblocking
+ mode.
+ &lt;br&gt;&lt;br&gt; The &lt;VAR&gt;addr&lt;/VAR&gt; and &lt;VAR&gt;length-ptr&lt;/VAR&gt; 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.
+ &lt;br&gt;&lt;br&gt; Accepting a connection does not make &lt;VAR&gt;socket&lt;/VAR&gt; part of the
+ connection. Instead, it creates a new socket which becomes
+ connected. The normal return value of &lt;CODE&gt;accept&lt;/CODE&gt; is the file
+ descriptor for the new socket.
+ &lt;br&gt;&lt;br&gt; After &lt;CODE&gt;accept&lt;/CODE&gt;, the original socket &lt;VAR&gt;socket&lt;/VAR&gt; remains open and
+ unconnected, and continues listening until you close it. You can
+ accept further connections with &lt;VAR&gt;socket&lt;/VAR&gt; by calling &lt;CODE&gt;accept&lt;/CODE&gt;
+ again.
+ &lt;br&gt;&lt;br&gt; If an error occurs, &lt;CODE&gt;accept&lt;/CODE&gt; returns &lt;CODE&gt;-1&lt;/CODE&gt;. The following
+ &lt;CODE&gt;errno&lt;/CODE&gt; error conditions are defined for this function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EBADF&lt;/CODE&gt;
+&lt;DD&gt;
+ The &lt;VAR&gt;socket&lt;/VAR&gt; argument is not a valid file descriptor.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ENOTSOCK
+ The descriptor &lt;VAR&gt;socket&lt;/VAR&gt; argument is not a socket.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EOPNOTSUPP
+ The descriptor &lt;VAR&gt;socket&lt;/VAR&gt; does not support this operation.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EWOULDBLOCK
+ &lt;VAR&gt;socket&lt;/VAR&gt; has nonblocking mode set, and there are no pending
+ connections immediately available.
+
+ &lt;br&gt;&lt;br&gt; 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.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-getpeername" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="int socket"/>
+ <parameter content="struct sockaddr *addr"/>
+ <parameter content="socklen_t *length-ptr"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/socket.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;getpeername&lt;/CODE&gt; function returns the address of the socket that
+ &lt;VAR&gt;socket&lt;/VAR&gt; is connected to; it stores the address in the memory space
+ specified by &lt;VAR&gt;addr&lt;/VAR&gt; and &lt;VAR&gt;length-ptr&lt;/VAR&gt;. It stores the length of
+ the address in &lt;CODE&gt;*&lt;VAR&gt;length-ptr&lt;/VAR&gt;&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; , for information about the format of the
+ address. In some operating systems, &lt;CODE&gt;getpeername&lt;/CODE&gt; works only for
+ sockets in the Internet domain.
+ &lt;br&gt;&lt;br&gt; The return value is &lt;CODE&gt;0&lt;/CODE&gt; on success and &lt;CODE&gt;-1&lt;/CODE&gt; on error. The
+ following &lt;CODE&gt;errno&lt;/CODE&gt; error conditions are defined for this function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EBADF&lt;/CODE&gt;
+&lt;DD&gt;
+ The argument &lt;VAR&gt;socket&lt;/VAR&gt; is not a valid file descriptor.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ENOTSOCK
+ The descriptor &lt;VAR&gt;socket&lt;/VAR&gt; is not a socket.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ENOTCONN
+ The socket &lt;VAR&gt;socket&lt;/VAR&gt; is not connected.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ENOBUFS
+ There are not enough internal buffers available.
+
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-send" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="int socket"/>
+ <parameter content="void *buffer"/>
+ <parameter content="size_t size"/>
+ <parameter content="int flags"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/socket.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;send&lt;/CODE&gt; function is like &lt;CODE&gt;write&lt;/CODE&gt;, but with the additional
+ flags &lt;VAR&gt;flags&lt;/VAR&gt;. The possible values of &lt;VAR&gt;flags&lt;/VAR&gt; are described
+ in Socket Data Options.
+ &lt;br&gt;&lt;br&gt; This function returns the number of bytes transmitted, or &lt;CODE&gt;-1&lt;/CODE&gt; on
+ failure. If the socket is nonblocking, then &lt;CODE&gt;send&lt;/CODE&gt; (like
+ &lt;CODE&gt;write&lt;/CODE&gt;) can return after sending just part of the data.
+ , for information about nonblocking mode.
+ &lt;br&gt;&lt;br&gt; 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.
+ &lt;br&gt;&lt;br&gt; The following &lt;CODE&gt;errno&lt;/CODE&gt; error conditions are defined for this function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EBADF&lt;/CODE&gt;
+&lt;DD&gt;
+ The &lt;VAR&gt;socket&lt;/VAR&gt; argument is not a valid file descriptor.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EINTR
+ The operation was interrupted by a signal before any data was sent.
+ .
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ENOTSOCK
+ The descriptor &lt;VAR&gt;socket&lt;/VAR&gt; is not a socket.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EMSGSIZE
+ The socket type requires that the message be sent atomically, but the
+ message is too large for this to be possible.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EWOULDBLOCK
+ Nonblocking mode has been set on the socket, and the write operation
+ would block. (Normally &lt;CODE&gt;send&lt;/CODE&gt; blocks until the operation can be
+ completed.)
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ENOBUFS
+ There is not enough internal buffer space available.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ENOTCONN
+ You never connected this socket.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EPIPE
+ This socket was connected but the connection is now broken. In this
+ case, &lt;CODE&gt;send&lt;/CODE&gt; generates a &lt;CODE&gt;SIGPIPE&lt;/CODE&gt; signal first; if that
+ signal is ignored or blocked, or if its handler returns, then
+ &lt;CODE&gt;send&lt;/CODE&gt; fails with &lt;CODE&gt;EPIPE&lt;/CODE&gt;.
+
+ &lt;br&gt;&lt;br&gt; 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.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-recv" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="int socket"/>
+ <parameter content="void *buffer"/>
+ <parameter content="size_t size"/>
+ <parameter content="int flags"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/socket.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;recv&lt;/CODE&gt; function is like &lt;CODE&gt;read&lt;/CODE&gt;, but with the additional
+ flags &lt;VAR&gt;flags&lt;/VAR&gt;. The possible values of &lt;VAR&gt;flags&lt;/VAR&gt; are described
+ in Socket Data Options.
+ &lt;br&gt;&lt;br&gt; If nonblocking mode is set for &lt;VAR&gt;socket&lt;/VAR&gt;, and no data are available to
+ be read, &lt;CODE&gt;recv&lt;/CODE&gt; fails immediately rather than waiting. , for information about nonblocking mode.
+ &lt;br&gt;&lt;br&gt; This function returns the number of bytes received, or &lt;CODE&gt;-1&lt;/CODE&gt; on failure.
+ The following &lt;CODE&gt;errno&lt;/CODE&gt; error conditions are defined for this function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EBADF&lt;/CODE&gt;
+&lt;DD&gt;
+ The &lt;VAR&gt;socket&lt;/VAR&gt; argument is not a valid file descriptor.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ENOTSOCK
+ The descriptor &lt;VAR&gt;socket&lt;/VAR&gt; is not a socket.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EWOULDBLOCK
+ Nonblocking mode has been set on the socket, and the read operation
+ would block. (Normally, &lt;CODE&gt;recv&lt;/CODE&gt; blocks until there is input
+ available to be read.)
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EINTR
+ The operation was interrupted by a signal before any data was read.
+ .
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ENOTCONN
+ You never connected this socket.
+
+ &lt;br&gt;&lt;br&gt; 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.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-sendto" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="int socket"/>
+ <parameter content="void *buffer. size_t size"/>
+ <parameter content="int flags"/>
+ <parameter content="struct sockaddr *addr"/>
+ <parameter content="socklen_t length"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/socket.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;sendto&lt;/CODE&gt; function transmits the data in the &lt;VAR&gt;buffer&lt;/VAR&gt;
+ through the socket &lt;VAR&gt;socket&lt;/VAR&gt; to the destination address specified
+ by the &lt;VAR&gt;addr&lt;/VAR&gt; and &lt;VAR&gt;length&lt;/VAR&gt; arguments. The &lt;VAR&gt;size&lt;/VAR&gt; argument
+ specifies the number of bytes to be transmitted.
+ &lt;br&gt;&lt;br&gt; The &lt;VAR&gt;flags&lt;/VAR&gt; are interpreted the same way as for &lt;CODE&gt;send&lt;/CODE&gt;; see
+ Socket Data Options.
+ &lt;br&gt;&lt;br&gt; The return value and error conditions are also the same as for
+ &lt;CODE&gt;send&lt;/CODE&gt;, 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.
+ &lt;br&gt;&lt;br&gt; It is also possible for one call to &lt;CODE&gt;sendto&lt;/CODE&gt; to report an error
+ owing to a problem related to a previous call.
+ &lt;br&gt;&lt;br&gt; 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.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-recvfrom" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="int socket"/>
+ <parameter content="void *buffer"/>
+ <parameter content="size_t size"/>
+ <parameter content="int flags"/>
+ <parameter content="struct sockaddr *addr"/>
+ <parameter content="socklen_t *length-ptr"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/socket.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;recvfrom&lt;/CODE&gt; function reads one packet from the socket
+ &lt;VAR&gt;socket&lt;/VAR&gt; into the buffer &lt;VAR&gt;buffer&lt;/VAR&gt;. The &lt;VAR&gt;size&lt;/VAR&gt; argument
+ specifies the maximum number of bytes to be read.
+ &lt;br&gt;&lt;br&gt; If the packet is longer than &lt;VAR&gt;size&lt;/VAR&gt; bytes, then you get the first
+ &lt;VAR&gt;size&lt;/VAR&gt; 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.
+ &lt;br&gt;&lt;br&gt; The &lt;VAR&gt;addr&lt;/VAR&gt; and &lt;VAR&gt;length-ptr&lt;/VAR&gt; 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 &lt;VAR&gt;addr&lt;/VAR&gt; argument
+ if you are not interested in this information.
+ &lt;br&gt;&lt;br&gt; The &lt;VAR&gt;flags&lt;/VAR&gt; are interpreted the same way as for &lt;CODE&gt;recv&lt;/CODE&gt;
+ . The return value and error conditions
+ are also the same as for &lt;CODE&gt;recv&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; 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.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="struct-msghdr" type="struct">
+ <structure>
+ </structure>
+ </construct>
+ <construct id="function-sendmsg" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="int socket"/>
+ <parameter content="const struct msghdr *message"/>
+ <parameter content="int flags"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/socket.h"/>
+ </headers>
+ <synopsis>
+ &lt;br&gt;&lt;br&gt; 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.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-recvmsg" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="int socket"/>
+ <parameter content="struct msghdr *message"/>
+ <parameter content="int flags"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/socket.h"/>
+ </headers>
+ <synopsis>
+ &lt;br&gt;&lt;br&gt; 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.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-getsockopt" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="int socket"/>
+ <parameter content="int level"/>
+ <parameter content="int optname"/>
+ <parameter content="void *optval"/>
+ <parameter content="socklen_t *optlen-ptr"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/socket.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;getsockopt&lt;/CODE&gt; function gets information about the value of
+ option &lt;VAR&gt;optname&lt;/VAR&gt; at level &lt;VAR&gt;level&lt;/VAR&gt; for socket &lt;VAR&gt;socket&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; The option value is stored in a buffer that &lt;VAR&gt;optval&lt;/VAR&gt; points to.
+ Before the call, you should supply in &lt;CODE&gt;*&lt;VAR&gt;optlen-ptr&lt;/VAR&gt;&lt;/CODE&gt; the
+ size of this buffer; on return, it contains the number of bytes of
+ information actually stored in the buffer.
+ &lt;br&gt;&lt;br&gt; Most options interpret the &lt;VAR&gt;optval&lt;/VAR&gt; buffer as a single &lt;CODE&gt;int&lt;/CODE&gt;
+ value.
+ &lt;br&gt;&lt;br&gt; The actual return value of &lt;CODE&gt;getsockopt&lt;/CODE&gt; is &lt;CODE&gt;0&lt;/CODE&gt; on success
+ and &lt;CODE&gt;-1&lt;/CODE&gt; on failure. The following &lt;CODE&gt;errno&lt;/CODE&gt; error conditions
+ are defined:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EBADF&lt;/CODE&gt;
+&lt;DD&gt;
+ The &lt;VAR&gt;socket&lt;/VAR&gt; argument is not a valid file descriptor.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ENOTSOCK
+ The descriptor &lt;VAR&gt;socket&lt;/VAR&gt; is not a socket.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ENOPROTOOPT
+ The &lt;VAR&gt;optname&lt;/VAR&gt; doesn't make sense for the given &lt;VAR&gt;level&lt;/VAR&gt;.
+
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-setsockopt" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="int socket"/>
+ <parameter content="int level"/>
+ <parameter content="int optname"/>
+ <parameter content="void *optval"/>
+ <parameter content="socklen_t optlen"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/socket.h"/>
+ </headers>
+ <synopsis>
+ This function is used to set the socket option &lt;VAR&gt;optname&lt;/VAR&gt; at level
+ &lt;VAR&gt;level&lt;/VAR&gt; for socket &lt;VAR&gt;socket&lt;/VAR&gt;. The value of the option is passed
+ in the buffer &lt;VAR&gt;optval&lt;/VAR&gt; of size &lt;VAR&gt;optlen&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt;
+
+ The return value and error codes for &lt;CODE&gt;setsockopt&lt;/CODE&gt; are the same as
+ for &lt;CODE&gt;getsockopt&lt;/CODE&gt;.
+
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="struct-linger" type="struct">
+ <structure>
+ <synopsis>
+ This structure type has the following members:
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ <elements>
+ <element content="int l_onoff">
+ <synopsis>
+ This field is interpreted as a boolean. If nonzero, &lt;CODE&gt;close&lt;/CODE&gt;
+ blocks until the data are transmitted or the timeout period has expired.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ </elements>
+ </structure>
+ </construct>
+ <construct id="struct-netent" type="struct">
+ <structure>
+ <synopsis>
+ This data type is used to represent information about entries in the
+ networks database. It has the following members:
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ <elements>
+ <element content="char *n_name">
+ <synopsis>
+ This is the ``official'' name of the network.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="char **n_aliases">
+ <synopsis>
+ These are alternative names for the network, represented as a vector
+ of strings. A null pointer terminates the array.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="int n_addrtype">
+ <synopsis>
+ This is the type of the network number; this is always equal to
+ &lt;CODE&gt;AF_INET&lt;/CODE&gt; for Internet networks.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ </elements>
+ </structure>
+ </construct>
+ <construct id="function-getnetbyname" type="function">
+ <function returntype="struct netent *">
+ <prototype>
+ <parameter content="const char *name"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/socket.h"/>
+ <header filename = "netdb.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;getnetbyname&lt;/CODE&gt; function returns information about the network
+ named &lt;VAR&gt;name&lt;/VAR&gt;. It returns a null pointer if there is no such
+ network.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-getnetbyaddr" type="function">
+ <function returntype="struct netent *">
+ <prototype>
+ <parameter content="unsigned long int net"/>
+ <parameter content="int type"/>
+ </prototype>
+ <headers>
+ <header filename = "netdb.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;getnetbyaddr&lt;/CODE&gt; function returns information about the network
+ of type &lt;VAR&gt;type&lt;/VAR&gt; with number &lt;VAR&gt;net&lt;/VAR&gt;. You should specify a value of
+ &lt;CODE&gt;AF_INET&lt;/CODE&gt; for the &lt;VAR&gt;type&lt;/VAR&gt; argument for Internet networks.
+ &lt;br&gt;&lt;br&gt; &lt;CODE&gt;getnetbyaddr&lt;/CODE&gt; returns a null pointer if there is no such
+ network.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-setnetent" type="function">
+ <function returntype="void">
+ <prototype>
+ <parameter content="int stayopen"/>
+ </prototype>
+ <headers>
+ <header filename = "netdb.h"/>
+ </headers>
+ <synopsis>
+ This function opens and rewinds the networks database.
+ &lt;br&gt;&lt;br&gt; If the &lt;VAR&gt;stayopen&lt;/VAR&gt; argument is nonzero, this sets a flag so that
+ subsequent calls to &lt;CODE&gt;getnetbyname&lt;/CODE&gt; or &lt;CODE&gt;getnetbyaddr&lt;/CODE&gt; 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.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-getnetent" type="function">
+ <function returntype="struct netent *">
+ <prototype>
+ <parameter content="void"/>
+ </prototype>
+ <headers>
+ <header filename = "netdb.h"/>
+ </headers>
+ <synopsis>
+ This function returns the next entry in the networks database. It
+ returns a null pointer if there are no more entries.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-endnetent" type="function">
+ <function returntype="void">
+ <prototype>
+ <parameter content="void"/>
+ </prototype>
+ <headers>
+ <header filename = "netdb.h"/>
+ </headers>
+ <synopsis>
+ This function closes the networks database.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-difftime" type="function">
+ <function returntype="double">
+ <prototype>
+ <parameter content="time_t time1"/>
+ <parameter content="time_t time0"/>
+ </prototype>
+ <headers>
+ <header filename = "time.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;difftime&lt;/CODE&gt; function returns the number of seconds of elapsed
+ time between calendar time &lt;VAR&gt;time1&lt;/VAR&gt; and calendar time &lt;VAR&gt;time0&lt;/VAR&gt;, as
+ a value of type &lt;CODE&gt;double&lt;/CODE&gt;. The difference ignores leap seconds
+ unless leap second support is enabled.
+ &lt;br&gt;&lt;br&gt; In the GNU system, you can simply subtract &lt;CODE&gt;time_t&lt;/CODE&gt; values. But on
+ other systems, the &lt;CODE&gt;time_t&lt;/CODE&gt; data type might use some other encoding
+ where subtraction doesn't work directly.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="struct-timeval" type="struct">
+ <structure>
+ <synopsis>
+
+ The &lt;CODE&gt;struct timeval&lt;/CODE&gt; structure represents an elapsed time. It is
+ declared in &lt;TT&gt;sys/time.h&lt;/TT&gt; and has the following members:
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ <elements>
+ <element content="long int tv_sec">
+ <synopsis>
+ This represents the number of whole seconds of elapsed time.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ </elements>
+ </structure>
+ </construct>
+ <construct id="struct-timespec" type="struct">
+ <structure>
+ <synopsis>
+
+ The &lt;CODE&gt;struct timespec&lt;/CODE&gt; structure represents an elapsed time. It is
+ declared in &lt;TT&gt;time.h&lt;/TT&gt; and has the following members:
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ <elements>
+ <element content="long int tv_sec">
+ <synopsis>
+ This represents the number of whole seconds of elapsed time.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ </elements>
+ </structure>
+ </construct>
+ <construct id="dtype-clock_t" type="dtype">
+ <structure>
+ </structure>
+ </construct>
+ <construct id="function-clock" type="function">
+ <function returntype="clock_t">
+ <prototype>
+ <parameter content="void"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/time.h"/>
+ <header filename = "time.h"/>
+ </headers>
+ <synopsis>
+ This function returns the calling process' current CPU time. If the CPU
+ time is not available or cannot be represented, &lt;CODE&gt;clock&lt;/CODE&gt; returns the
+ value &lt;CODE&gt;(clock_t)(-1)&lt;/CODE&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="struct-tms" type="struct">
+ <structure>
+ <synopsis>
+ The &lt;CODE&gt;tms&lt;/CODE&gt; structure is used to return information about process
+ times. It contains at least the following members:
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ <elements>
+ <element content="clock_t tms_utime">
+ <synopsis>
+ This is the total processor time the calling process has used in
+ executing the instructions of its program.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="clock_t tms_stime">
+ <synopsis>
+ This is the processor time the system has used on behalf of the calling
+ process.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="clock_t tms_cutime">
+ <synopsis>
+ This is the sum of the &lt;CODE&gt;tms_utime&lt;/CODE&gt; values and the &lt;CODE&gt;tms_cutime&lt;/CODE&gt;
+ values of all terminated child processes of the calling process, whose
+ status has been reported to the parent process by &lt;CODE&gt;wait&lt;/CODE&gt; or
+ &lt;CODE&gt;waitpid&lt;/CODE&gt;; see Process Completion. In other words, it
+ represents the total processor time used in executing the instructions
+ of all the terminated child processes of the calling process, excluding
+ child processes which have not yet been reported by &lt;CODE&gt;wait&lt;/CODE&gt; or
+ &lt;CODE&gt;waitpid&lt;/CODE&gt;.
+ process
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ </elements>
+ </structure>
+ </construct>
+ <construct id="function-times" type="function">
+ <function returntype="clock_t">
+ <prototype>
+ <parameter content="struct tms *buffer"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/times.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;times&lt;/CODE&gt; function stores the processor time information for
+ the calling process in &lt;VAR&gt;buffer&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; The return value is the calling process' CPU time (the same value you
+ get from &lt;CODE&gt;clock()&lt;/CODE&gt;. &lt;CODE&gt;times&lt;/CODE&gt; returns &lt;CODE&gt;(clock_t)(-1)&lt;/CODE&gt; to
+ indicate failure.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="dtype-time_t" type="dtype">
+ <structure>
+ </structure>
+ </construct>
+ <construct id="function-time" type="function">
+ <function returntype="time_t">
+ <prototype>
+ <parameter content="time_t *result"/>
+ </prototype>
+ <headers>
+ <header filename = "time.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;time&lt;/CODE&gt; function returns the current calendar time as a value of
+ type &lt;CODE&gt;time_t&lt;/CODE&gt;. If the argument &lt;VAR&gt;result&lt;/VAR&gt; is not a null pointer,
+ the calendar time value is also stored in &lt;CODE&gt;*&lt;VAR&gt;result&lt;/VAR&gt;&lt;/CODE&gt;. If the
+ current calendar time is not available, the value
+ &lt;CODE&gt;(time_t)(-1)&lt;/CODE&gt; is returned.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-stime" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="time_t *newtime"/>
+ </prototype>
+ <headers>
+ <header filename = "time.h"/>
+ </headers>
+ <synopsis>
+ &lt;CODE&gt;stime&lt;/CODE&gt; sets the system clock, i.e., it tells the system that the
+ current calendar time is &lt;VAR&gt;newtime&lt;/VAR&gt;, where &lt;CODE&gt;newtime&lt;/CODE&gt; is
+ interpreted as described in the above definition of &lt;CODE&gt;time_t&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; &lt;CODE&gt;settimeofday&lt;/CODE&gt; is a newer function which sets the system clock to
+ better than one second precision. &lt;CODE&gt;settimeofday&lt;/CODE&gt; is generally a
+ better choice than &lt;CODE&gt;stime&lt;/CODE&gt;. .
+ &lt;br&gt;&lt;br&gt; Only the superuser can set the system clock.
+ &lt;br&gt;&lt;br&gt; If the function succeeds, the return value is zero. Otherwise, it is
+ &lt;CODE&gt;-1&lt;/CODE&gt; and &lt;CODE&gt;errno&lt;/CODE&gt; is set accordingly:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EPERM&lt;/CODE&gt;
+&lt;DD&gt;
+ The process is not superuser.
+
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="struct-timezone" type="struct">
+ <structure>
+ <synopsis>
+ The &lt;CODE&gt;struct timezone&lt;/CODE&gt; structure is used to hold minimal information
+ about the local time zone. It has the following members:
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ <elements>
+ <element content="int tz_minuteswest">
+ <synopsis>
+ This is the number of minutes west of UTC.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ </elements>
+ </structure>
+ </construct>
+ <construct id="function-gettimeofday" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="struct timeval *tp"/>
+ <parameter content="struct timezone *tzp"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/time.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;gettimeofday&lt;/CODE&gt; function returns the current calendar time as
+ the elapsed time since the epoch in the &lt;CODE&gt;struct timeval&lt;/CODE&gt; structure
+ indicated by &lt;VAR&gt;tp&lt;/VAR&gt;. ( for a description of
+ &lt;CODE&gt;struct timeval&lt;/CODE&gt;). Information about the time zone is returned in
+ the structure pointed at &lt;VAR&gt;tzp&lt;/VAR&gt;. If the &lt;VAR&gt;tzp&lt;/VAR&gt; argument is a null
+ pointer, time zone information is ignored.
+ &lt;br&gt;&lt;br&gt; The return value is &lt;CODE&gt;0&lt;/CODE&gt; on success and &lt;CODE&gt;-1&lt;/CODE&gt; on failure. The
+ following &lt;CODE&gt;errno&lt;/CODE&gt; error condition is defined for this function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;ENOSYS&lt;/CODE&gt;
+&lt;DD&gt;
+ The operating system does not support getting time zone information, and
+ &lt;VAR&gt;tzp&lt;/VAR&gt; is not a null pointer. The GNU operating system does not
+ support using &lt;CODE&gt;struct timezone&lt;/CODE&gt; to represent time zone
+ information; that is an obsolete feature of 4.3 BSD.
+ Instead, use the facilities described in Time Zone Functions.
+
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-settimeofday" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const struct timeval *tp"/>
+ <parameter content="const struct timezone *tzp"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/time.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;settimeofday&lt;/CODE&gt; function sets the current calendar time in the
+ system clock according to the arguments. As for &lt;CODE&gt;gettimeofday&lt;/CODE&gt;,
+ the calendar time is represented as the elapsed time since the epoch.
+ As for &lt;CODE&gt;gettimeofday&lt;/CODE&gt;, time zone information is ignored if
+ &lt;VAR&gt;tzp&lt;/VAR&gt; is a null pointer.
+ &lt;br&gt;&lt;br&gt; You must be a privileged user in order to use &lt;CODE&gt;settimeofday&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; 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 &lt;CODE&gt;stime&lt;/CODE&gt; removes the system clock from an invalid
+ state, and system startup scripts typically run a program that calls
+ &lt;CODE&gt;stime&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; &lt;CODE&gt;settimeofday&lt;/CODE&gt; causes a sudden jump forwards or backwards, which
+ can cause a variety of problems in a system. Use &lt;CODE&gt;adjtime&lt;/CODE&gt; (below)
+ to make a smooth transition from one time to another by temporarily
+ speeding up or slowing down the clock.
+ &lt;br&gt;&lt;br&gt; With a Linux kernel, &lt;CODE&gt;adjtimex&lt;/CODE&gt; 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.
+ &lt;br&gt;&lt;br&gt; The return value is &lt;CODE&gt;0&lt;/CODE&gt; on success and &lt;CODE&gt;-1&lt;/CODE&gt; on failure. The
+ following &lt;CODE&gt;errno&lt;/CODE&gt; error conditions are defined for this function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EPERM&lt;/CODE&gt;
+&lt;DD&gt;
+ This process cannot set the clock because it is not privileged.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ENOSYS
+ The operating system does not support setting time zone information, and
+ &lt;VAR&gt;tzp&lt;/VAR&gt; is not a null pointer.
+
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-adjtime" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const struct timeval *delta"/>
+ <parameter content="struct timeval *olddelta"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/time.h"/>
+ </headers>
+ <synopsis>
+ 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.
+ &lt;br&gt;&lt;br&gt; The &lt;VAR&gt;delta&lt;/VAR&gt; 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.
+ &lt;br&gt;&lt;br&gt; If the &lt;VAR&gt;olddelta&lt;/VAR&gt; argument is not a null pointer, the &lt;CODE&gt;adjtime&lt;/CODE&gt;
+ function returns information about any previous time adjustment that
+ has not yet completed.
+ &lt;br&gt;&lt;br&gt; This function is typically used to synchronize the clocks of computers
+ in a local network. You must be a privileged user to use it.
+ &lt;br&gt;&lt;br&gt; With a Linux kernel, you can use the &lt;CODE&gt;adjtimex&lt;/CODE&gt; function to
+ permanently change the clock speed.
+ &lt;br&gt;&lt;br&gt; The return value is &lt;CODE&gt;0&lt;/CODE&gt; on success and &lt;CODE&gt;-1&lt;/CODE&gt; on failure. The
+ following &lt;CODE&gt;errno&lt;/CODE&gt; error condition is defined for this function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EPERM&lt;/CODE&gt;
+&lt;DD&gt;
+ You do not have privilege to set the time.
+
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-adjtimex" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="struct timex *timex"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/timex.h"/>
+ </headers>
+ <synopsis>
+ &lt;br&gt;&lt;br&gt; &lt;CODE&gt;adjtimex&lt;/CODE&gt; is functionally identical to &lt;CODE&gt;ntp_adjtime&lt;/CODE&gt;.
+ .
+ &lt;br&gt;&lt;br&gt; This function is present only with a Linux kernel.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="struct-tm" type="struct">
+ <structure>
+ <synopsis>
+ This is the data type used to represent a broken-down time. The structure
+ contains at least the following members, which can appear in any order.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ <elements>
+ <element content="int tm_sec">
+ <synopsis>
+ This is the number of full seconds since the top of the minute (normally
+ in the range &lt;CODE&gt;0&lt;/CODE&gt; through &lt;CODE&gt;59&lt;/CODE&gt;, but the actual upper limit is
+ &lt;CODE&gt;60&lt;/CODE&gt;, to allow for leap seconds if leap second support is
+ available).
+ second
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="int tm_min">
+ <synopsis>
+ This is the number of full minutes since the top of the hour (in the
+ range &lt;CODE&gt;0&lt;/CODE&gt; through &lt;CODE&gt;59&lt;/CODE&gt;).
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="int tm_hour">
+ <synopsis>
+ This is the number of full hours past midnight (in the range &lt;CODE&gt;0&lt;/CODE&gt; through
+ &lt;CODE&gt;23&lt;/CODE&gt;).
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="int tm_mday">
+ <synopsis>
+ This is the ordinal day of the month (in the range &lt;CODE&gt;1&lt;/CODE&gt; through &lt;CODE&gt;31&lt;/CODE&gt;).
+ Watch out for this one! As the only ordinal number in the structure, it is
+ inconsistent with the rest of the structure.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="int tm_mon">
+ <synopsis>
+ This is the number of full calendar months since the beginning of the
+ year (in the range &lt;CODE&gt;0&lt;/CODE&gt; through &lt;CODE&gt;11&lt;/CODE&gt;). Watch out for this one!
+ People usually use ordinal numbers for month-of-year (where January = 1).
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="int tm_year">
+ <synopsis>
+ This is the number of full calendar years since 1900.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="int tm_wday">
+ <synopsis>
+ This is the number of full days since Sunday (in the range &lt;CODE&gt;0&lt;/CODE&gt; through
+ &lt;CODE&gt;6&lt;/CODE&gt;).
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="int tm_yday">
+ <synopsis>
+ This is the number of full days since the beginning of the year (in the
+ range &lt;CODE&gt;0&lt;/CODE&gt; through &lt;CODE&gt;365&lt;/CODE&gt;).
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="int tm_isdst">
+ <synopsis>
+ Saving Time
+ time
+ This is a flag that indicates whether Daylight Saving Time is (or was, or
+ will be) in effect at the time described. The value is positive if
+ Daylight Saving Time is in effect, zero if it is not, and negative if the
+ information is not available.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="long int tm_gmtoff">
+ <synopsis>
+ This field describes the time zone that was used to compute this
+ broken-down time value, including any adjustment for daylight saving; it
+ is the number of seconds that you must add to UTC to get local time.
+ You can also think of this as the number of seconds east of UTC. For
+ example, for U.S. Eastern Standard Time, the value is &lt;CODE&gt;-5*60*60&lt;/CODE&gt;.
+ The &lt;CODE&gt;tm_gmtoff&lt;/CODE&gt; field is derived from BSD and is a GNU library
+ extension; it is not visible in a strict ISO C environment.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ </elements>
+ </structure>
+ </construct>
+ <construct id="function-localtime" type="function">
+ <function returntype="struct tm *">
+ <prototype>
+ <parameter content="const time_t *time"/>
+ </prototype>
+ <headers>
+ <header filename = "time.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;localtime&lt;/CODE&gt; function converts the simple time pointed to by
+ &lt;VAR&gt;time&lt;/VAR&gt; to broken-down time representation, expressed relative to the
+ user's specified time zone.
+ &lt;br&gt;&lt;br&gt; The return value is a pointer to a static broken-down time structure, which
+ might be overwritten by subsequent calls to &lt;CODE&gt;ctime&lt;/CODE&gt;, &lt;CODE&gt;gmtime&lt;/CODE&gt;,
+ or &lt;CODE&gt;localtime&lt;/CODE&gt;. (But no other library function overwrites the contents
+ of this object.)
+ &lt;br&gt;&lt;br&gt; The return value is the null pointer if &lt;VAR&gt;time&lt;/VAR&gt; cannot be represented
+ as a broken-down time; typically this is because the year cannot fit into
+ an &lt;CODE&gt;int&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; Calling &lt;CODE&gt;localtime&lt;/CODE&gt; has one other effect: it sets the variable
+ &lt;CODE&gt;tzname&lt;/CODE&gt; with information about the current time zone. .
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-localtime_r" type="function">
+ <function returntype="struct tm *">
+ <prototype>
+ <parameter content="const time_t *time"/>
+ <parameter content="struct tm *resultp"/>
+ </prototype>
+ <headers>
+ <header filename = "time.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;localtime_r&lt;/CODE&gt; function works just like the &lt;CODE&gt;localtime&lt;/CODE&gt;
+ function. It takes a pointer to a variable containing a simple time
+ and converts it to the broken-down time format.
+ &lt;br&gt;&lt;br&gt; But the result is not placed in a static buffer. Instead it is placed
+ in the object of type &lt;CODE&gt;struct tm&lt;/CODE&gt; to which the parameter
+ &lt;VAR&gt;resultp&lt;/VAR&gt; points.
+ &lt;br&gt;&lt;br&gt; If the conversion is successful the function returns a pointer to the
+ object the result was written into, i.e., it returns &lt;VAR&gt;resultp&lt;/VAR&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-gmtime" type="function">
+ <function returntype="struct tm *">
+ <prototype>
+ <parameter content="const time_t *time"/>
+ </prototype>
+ <headers>
+ <header filename = "time.h"/>
+ </headers>
+ <synopsis>
+ This function is similar to &lt;CODE&gt;localtime&lt;/CODE&gt;, 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.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-gmtime_r" type="function">
+ <function returntype="struct tm *">
+ <prototype>
+ <parameter content="const time_t *time"/>
+ <parameter content="struct tm *resultp"/>
+ </prototype>
+ <headers>
+ <header filename = "time.h"/>
+ </headers>
+ <synopsis>
+ This function is similar to &lt;CODE&gt;localtime_r&lt;/CODE&gt;, except that it converts
+ just like &lt;CODE&gt;gmtime&lt;/CODE&gt; the given time as Coordinated Universal Time.
+ &lt;br&gt;&lt;br&gt; If the conversion is successful the function returns a pointer to the
+ object the result was written into, i.e., it returns &lt;VAR&gt;resultp&lt;/VAR&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-mktime" type="function">
+ <function returntype="time_t">
+ <prototype>
+ <parameter content="struct tm *brokentime"/>
+ </prototype>
+ <headers>
+ <header filename = "time.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;mktime&lt;/CODE&gt; 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.
+ &lt;br&gt;&lt;br&gt; The &lt;CODE&gt;mktime&lt;/CODE&gt; function ignores the specified contents of the
+ &lt;CODE&gt;tm_wday&lt;/CODE&gt; and &lt;CODE&gt;tm_yday&lt;/CODE&gt; 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
+ &lt;CODE&gt;mktime&lt;/CODE&gt; does is adjust the components of the &lt;VAR&gt;brokentime&lt;/VAR&gt;
+ structure (including the &lt;CODE&gt;tm_wday&lt;/CODE&gt; and &lt;CODE&gt;tm_yday&lt;/CODE&gt;).
+ &lt;br&gt;&lt;br&gt; If the specified broken-down time cannot be represented as a simple time,
+ &lt;CODE&gt;mktime&lt;/CODE&gt; returns a value of &lt;CODE&gt;(time_t)(-1)&lt;/CODE&gt; and does not modify
+ the contents of &lt;VAR&gt;brokentime&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; Calling &lt;CODE&gt;mktime&lt;/CODE&gt; also sets the variable &lt;CODE&gt;tzname&lt;/CODE&gt; with
+ information about the current time zone. .
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-timelocal" type="function">
+ <function returntype="time_t">
+ <prototype>
+ <parameter content="struct tm *brokentime"/>
+ </prototype>
+ <headers>
+ <header filename = "time.h"/>
+ </headers>
+ <synopsis>
+ &lt;br&gt;&lt;br&gt; &lt;CODE&gt;timelocal&lt;/CODE&gt; is functionally identical to &lt;CODE&gt;mktime&lt;/CODE&gt;, but more
+ mnemonically named. Note that it is the inverse of the &lt;CODE&gt;localtime&lt;/CODE&gt;
+ function.
+ &lt;br&gt;&lt;br&gt; Portability note: &lt;CODE&gt;mktime&lt;/CODE&gt; is essentially universally
+ available. &lt;CODE&gt;timelocal&lt;/CODE&gt; is rather rare.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-timegm" type="function">
+ <function returntype="time_t">
+ <prototype>
+ <parameter content="struct tm *brokentime"/>
+ </prototype>
+ <headers>
+ <header filename = "time.h"/>
+ </headers>
+ <synopsis>
+ &lt;br&gt;&lt;br&gt; &lt;CODE&gt;timegm&lt;/CODE&gt; is functionally identical to &lt;CODE&gt;mktime&lt;/CODE&gt; except it
+ always takes the input values to be Coordinated Universal Time (UTC)
+ regardless of any local time zone setting.
+ &lt;br&gt;&lt;br&gt; Note that &lt;CODE&gt;timegm&lt;/CODE&gt; is the inverse of &lt;CODE&gt;gmtime&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; Portability note: &lt;CODE&gt;mktime&lt;/CODE&gt; is essentially universally
+ available. &lt;CODE&gt;timegm&lt;/CODE&gt; is rather rare. For the most portable
+ conversion from a UTC broken-down time to a simple time, set
+ the &lt;CODE&gt;TZ&lt;/CODE&gt; environment variable to UTC, call &lt;CODE&gt;mktime&lt;/CODE&gt;, then set
+ &lt;CODE&gt;TZ&lt;/CODE&gt; back.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="struct-ntptimeval" type="struct">
+ <structure>
+ <synopsis>
+ This structure is used for information about the system clock. It
+ contains the following members:
+ </synopsis>
+ <elements>
+ <element content="struct timeval time">
+ <synopsis>
+ This is the current calendar time, expressed as the elapsed time since
+ the epoch. The &lt;CODE&gt;struct timeval&lt;/CODE&gt; data type is described in
+ Elapsed Time.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="long int maxerror">
+ <synopsis>
+ This is the maximum error, measured in microseconds. Unless updated
+ via &lt;CODE&gt;ntp_adjtime&lt;/CODE&gt; periodically, this value will reach some
+ platform-specific maximum value.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ </elements>
+ </structure>
+ </construct>
+ <construct id="function-ntp_gettime" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="struct ntptimeval *tptr"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/timex.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;ntp_gettime&lt;/CODE&gt; function sets the structure pointed to by
+ &lt;VAR&gt;tptr&lt;/VAR&gt; 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 &lt;CODE&gt;ntp_adjtime&lt;/CODE&gt;
+ call is necessary.
+ &lt;br&gt;&lt;br&gt; The return value is &lt;CODE&gt;0&lt;/CODE&gt; on success and other values on failure. The
+ following &lt;CODE&gt;errno&lt;/CODE&gt; error conditions are defined for this function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;TIME_ERROR&lt;/CODE&gt;
+&lt;DD&gt;
+ 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.
+
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="struct-timex" type="struct">
+ <structure>
+ <synopsis>
+ This structure is used to control and monitor the system clock. It
+ contains the following members:
+ </synopsis>
+ <elements>
+ <element content="unsigned int modes">
+ <synopsis>
+ This variable controls whether and which values are set. Several
+ symbolic constants have to be combined with &lt;EM&gt;binary or&lt;/EM&gt; to specify
+ the effective mode. These constants start with &lt;CODE&gt;MOD_&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="long int offset">
+ <synopsis>
+ This value indicates the current offset of the system clock from the true
+ calendar time. The value is given in microseconds. If bit
+ &lt;CODE&gt;MOD_OFFSET&lt;/CODE&gt; is set in &lt;CODE&gt;modes&lt;/CODE&gt;, the offset (and possibly other
+ dependent values) can be set. The offset's absolute value must not
+ exceed &lt;CODE&gt;MAXPHASE&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="long int frequency">
+ <synopsis>
+ This value indicates the difference in frequency between the true
+ calendar time and the system clock. The value is expressed as scaled
+ PPM (parts per million, 0.0001%). The scaling is &lt;CODE&gt;1 &lt;&lt;
+ SHIFT_USEC&lt;/CODE&gt;. The value can be set with bit &lt;CODE&gt;MOD_FREQUENCY&lt;/CODE&gt;, but
+ the absolute value must not exceed &lt;CODE&gt;MAXFREQ&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="long int maxerror">
+ <synopsis>
+ This is the maximum error, measured in microseconds. A new value can be
+ set using bit &lt;CODE&gt;MOD_MAXERROR&lt;/CODE&gt;. Unless updated via
+ &lt;CODE&gt;ntp_adjtime&lt;/CODE&gt; periodically, this value will increase steadily
+ and reach some platform-specific maximum value.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="long int esterror">
+ <synopsis>
+ This is the estimated error, measured in microseconds. This value can
+ be set using bit &lt;CODE&gt;MOD_ESTERROR&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="int status">
+ <synopsis>
+ This variable reflects the various states of the clock machinery. There
+ are symbolic constants for the significant bits, starting with
+ &lt;CODE&gt;STA_&lt;/CODE&gt;. Some of these flags can be updated using the
+ &lt;CODE&gt;MOD_STATUS&lt;/CODE&gt; bit.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="long int constant">
+ <synopsis>
+ This value represents the bandwidth or stiffness of the PLL (phase
+ locked loop) implemented in the kernel. The value can be changed using
+ bit &lt;CODE&gt;MOD_TIMECONST&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="long int precision">
+ <synopsis>
+ This value represents the accuracy or the maximum error when reading the
+ system clock. The value is expressed in microseconds.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="long int tolerance">
+ <synopsis>
+ This value represents the maximum frequency error of the system clock in
+ scaled PPM. This value is used to increase the &lt;CODE&gt;maxerror&lt;/CODE&gt; every
+ second.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="struct timeval time">
+ <synopsis>
+ The current calendar time.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="long int tick">
+ <synopsis>
+ The elapsed time between clock ticks in microseconds. A clock tick is a
+ periodic timer interrupt on which the system clock is based.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="long int ppsfreq">
+ <synopsis>
+ This is the first of a few optional variables that are present only if
+ the system clock can use a PPS (pulse per second) signal to discipline
+ the system clock. The value is expressed in scaled PPM and it denotes
+ the difference in frequency between the system clock and the PPS signal.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="long int jitter">
+ <synopsis>
+ This value expresses a median filtered average of the PPS signal's
+ dispersion in microseconds.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="int shift">
+ <synopsis>
+ This value is a binary exponent for the duration of the PPS calibration
+ interval, ranging from &lt;CODE&gt;PPS_SHIFT&lt;/CODE&gt; to &lt;CODE&gt;PPS_SHIFTMAX&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="long int stabil">
+ <synopsis>
+ This value represents the median filtered dispersion of the PPS
+ frequency in scaled PPM.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="long int jitcnt">
+ <synopsis>
+ This counter represents the number of pulses where the jitter exceeded
+ the allowed maximum &lt;CODE&gt;MAXTIME&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="long int calcnt">
+ <synopsis>
+ This counter reflects the number of successful calibration intervals.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="long int errcnt">
+ <synopsis>
+ This counter represents the number of calibration errors (caused by
+ large offsets or jitter).
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ </elements>
+ </structure>
+ </construct>
+ <construct id="function-ntp_adjtime" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="struct timex *tptr"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/timex.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;ntp_adjtime&lt;/CODE&gt; function sets the structure specified by
+ &lt;VAR&gt;tptr&lt;/VAR&gt; to current values.
+ &lt;br&gt;&lt;br&gt; In addition, &lt;CODE&gt;ntp_adjtime&lt;/CODE&gt; updates some settings to match what you
+ pass to it in *&lt;VAR&gt;tptr&lt;/VAR&gt;. Use the &lt;CODE&gt;modes&lt;/CODE&gt; element of *&lt;VAR&gt;tptr&lt;/VAR&gt;
+ to select what settings to update. You can set &lt;CODE&gt;offset&lt;/CODE&gt;,
+ &lt;CODE&gt;freq&lt;/CODE&gt;, &lt;CODE&gt;maxerror&lt;/CODE&gt;, &lt;CODE&gt;esterror&lt;/CODE&gt;, &lt;CODE&gt;status&lt;/CODE&gt;,
+ &lt;CODE&gt;constant&lt;/CODE&gt;, and &lt;CODE&gt;tick&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; &lt;CODE&gt;modes&lt;/CODE&gt; = zero means set nothing.
+ &lt;br&gt;&lt;br&gt; Only the superuser can update settings.
+ &lt;br&gt;&lt;br&gt; &lt;br&gt;&lt;br&gt; The return value is &lt;CODE&gt;0&lt;/CODE&gt; on success and other values on failure. The
+ following &lt;CODE&gt;errno&lt;/CODE&gt; error conditions are defined for this function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;TIME_ERROR&lt;/CODE&gt;
+&lt;DD&gt;
+ 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.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EPERM
+ The process specified a settings update, but is not superuser.
+ &lt;br&gt;&lt;br&gt;
+ &lt;br&gt;&lt;br&gt; For more details see RFC1305 (Network Time Protocol, Version 3) and
+ related documents.
+ &lt;br&gt;&lt;br&gt; Portability note: Early versions of the GNU C library did not
+ have this function but did have the synonymous &lt;CODE&gt;adjtimex&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-asctime" type="function">
+ <function returntype="char *">
+ <prototype>
+ <parameter content="const struct tm *brokentime"/>
+ </prototype>
+ <headers>
+ <header filename = "time.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;asctime&lt;/CODE&gt; function converts the broken-down time value that
+ &lt;VAR&gt;brokentime&lt;/VAR&gt; points to into a string in a standard format:
+ &lt;br&gt;&lt;br&gt; &lt;pre&gt;&lt;br&gt;
+ "Tue May 21 13:46:22 1991\n"&lt;br&gt;
+ &lt;/pre&gt;
+ &lt;br&gt;&lt;br&gt; The abbreviations for the days of week are: &lt;samp&gt;Sun&lt;/samp&gt;, &lt;samp&gt;Mon&lt;/samp&gt;,
+ &lt;samp&gt;Tue&lt;/samp&gt;, &lt;samp&gt;Wed&lt;/samp&gt;, &lt;samp&gt;Thu&lt;/samp&gt;, &lt;samp&gt;Fri&lt;/samp&gt;, and &lt;samp&gt;Sat&lt;/samp&gt;.
+ &lt;br&gt;&lt;br&gt; The abbreviations for the months are: &lt;samp&gt;Jan&lt;/samp&gt;, &lt;samp&gt;Feb&lt;/samp&gt;,
+ &lt;samp&gt;Mar&lt;/samp&gt;, &lt;samp&gt;Apr&lt;/samp&gt;, &lt;samp&gt;May&lt;/samp&gt;, &lt;samp&gt;Jun&lt;/samp&gt;, &lt;samp&gt;Jul&lt;/samp&gt;, &lt;samp&gt;Aug&lt;/samp&gt;,
+ &lt;samp&gt;Sep&lt;/samp&gt;, &lt;samp&gt;Oct&lt;/samp&gt;, &lt;samp&gt;Nov&lt;/samp&gt;, and &lt;samp&gt;Dec&lt;/samp&gt;.
+ &lt;br&gt;&lt;br&gt; The return value points to a statically allocated string, which might be
+ overwritten by subsequent calls to &lt;CODE&gt;asctime&lt;/CODE&gt; or &lt;CODE&gt;ctime&lt;/CODE&gt;.
+ (But no other library function overwrites the contents of this
+ string.)
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-asctime_r" type="function">
+ <function returntype="char *">
+ <prototype>
+ <parameter content="const struct tm *brokentime"/>
+ <parameter content="char *buffer"/>
+ </prototype>
+ <headers>
+ <header filename = "time.h"/>
+ </headers>
+ <synopsis>
+ This function is similar to &lt;CODE&gt;asctime&lt;/CODE&gt; but instead of placing the
+ result in a static buffer it writes the string in the buffer pointed to
+ by the parameter &lt;VAR&gt;buffer&lt;/VAR&gt;. This buffer should have room
+ for at least 26 bytes, including the terminating null.
+ &lt;br&gt;&lt;br&gt; If no error occurred the function returns a pointer to the string the
+ result was written into, i.e., it returns &lt;VAR&gt;buffer&lt;/VAR&gt;. Otherwise
+ return &lt;CODE&gt;NULL&lt;/CODE&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-ctime" type="function">
+ <function returntype="char *">
+ <prototype>
+ <parameter content="const time_t *time"/>
+ </prototype>
+ <headers>
+ <header filename = "time.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;ctime&lt;/CODE&gt; function is similar to &lt;CODE&gt;asctime&lt;/CODE&gt;, except that you
+ specify the calendar time argument as a &lt;CODE&gt;time_t&lt;/CODE&gt; simple time value
+ rather than in broken-down local time format. It is equivalent to
+ &lt;br&gt;&lt;br&gt; &lt;pre&gt;&lt;br&gt;
+ asctime (localtime (&lt;VAR&gt;time&lt;/VAR&gt;))&lt;br&gt;
+ &lt;/pre&gt;
+ &lt;br&gt;&lt;br&gt; &lt;CODE&gt;ctime&lt;/CODE&gt; sets the variable &lt;CODE&gt;tzname&lt;/CODE&gt;, because &lt;CODE&gt;localtime&lt;/CODE&gt;
+ does so. .
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-ctime_r" type="function">
+ <function returntype="char *">
+ <prototype>
+ <parameter content="const time_t *time"/>
+ <parameter content="char *buffer"/>
+ </prototype>
+ <headers>
+ <header filename = "time.h"/>
+ </headers>
+ <synopsis>
+ This function is similar to &lt;CODE&gt;ctime&lt;/CODE&gt;, but places the result in the
+ string pointed to by &lt;VAR&gt;buffer&lt;/VAR&gt;. It is equivalent to (written using
+ gcc extensions, ):
+ &lt;br&gt;&lt;br&gt; &lt;pre&gt;&lt;br&gt;
+ ({ struct tm tm; asctime_r (localtime_r (time, &amp;tm), buf); })&lt;br&gt;
+ &lt;/pre&gt;
+ &lt;br&gt;&lt;br&gt; If no error occurred the function returns a pointer to the string the
+ result was written into, i.e., it returns &lt;VAR&gt;buffer&lt;/VAR&gt;. Otherwise
+ return &lt;CODE&gt;NULL&lt;/CODE&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-strftime" type="function">
+ <function returntype="size_t">
+ <prototype>
+ <parameter content="char *s"/>
+ <parameter content="size_t size"/>
+ <parameter content="const char *template"/>
+ <parameter content="const struct tm *brokentime"/>
+ </prototype>
+ <headers>
+ <header filename = "time.h"/>
+ </headers>
+ <synopsis>
+ This function is similar to the &lt;CODE&gt;sprintf&lt;/CODE&gt; function , but the conversion specifications that can appear in the format
+ template &lt;VAR&gt;template&lt;/VAR&gt; are specialized for printing components of the date
+ and time &lt;VAR&gt;brokentime&lt;/VAR&gt; according to the locale currently specified for
+ time conversion .
+ &lt;br&gt;&lt;br&gt; Ordinary characters appearing in the &lt;VAR&gt;template&lt;/VAR&gt; are copied to the
+ output string &lt;VAR&gt;s&lt;/VAR&gt;; this can include multibyte character sequences.
+ Conversion specifiers are introduced by a &lt;samp&gt;%&lt;/samp&gt; 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:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;_&lt;/CODE&gt;
+&lt;DD&gt;
+ The number is padded with spaces.
+ &lt;br&gt;&lt;br&gt; &lt;DT&gt;&lt;CODE&gt;-&lt;/CODE&gt;
+&lt;DD&gt;
+ The number is not padded at all.
+ &lt;br&gt;&lt;br&gt; &lt;DT&gt;&lt;CODE&gt;0&lt;/CODE&gt;
+&lt;DD&gt;
+ The number is padded with zeros even if the format specifies padding
+ with spaces.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ^
+ The output uses uppercase characters, but only if this is possible
+ .
+
+ &lt;br&gt;&lt;br&gt; 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.
+ &lt;br&gt;&lt;br&gt; 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.
+ &lt;br&gt;&lt;br&gt; 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:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;LI&gt; E
+ Use the locale's alternate representation for date and time. This
+ modifier applies to the &lt;CODE&gt;%c&lt;/CODE&gt;, &lt;CODE&gt;%C&lt;/CODE&gt;, &lt;CODE&gt;%x&lt;/CODE&gt;, &lt;CODE&gt;%X&lt;/CODE&gt;,
+ &lt;CODE&gt;%y&lt;/CODE&gt; and &lt;CODE&gt;%Y&lt;/CODE&gt; format specifiers. In a Japanese locale, for
+ example, &lt;CODE&gt;%Ex&lt;/CODE&gt; might yield a date format based on the Japanese
+ Emperors' reigns.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; O
+ Use the locale's alternate numeric symbols for numbers. This modifier
+ applies only to numeric format specifiers.
+
+ &lt;br&gt;&lt;br&gt; If the format supports the modifier but no alternate representation
+ is available, it is ignored.
+ &lt;br&gt;&lt;br&gt; The conversion specifier ends with a format specifier taken from the
+ following list. The whole &lt;samp&gt;%&lt;/samp&gt; sequence is replaced in the output
+ string as follows:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;LI&gt; %a
+ The abbreviated weekday name according to the current locale.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %A
+ The full weekday name according to the current locale.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %b
+ The abbreviated month name according to the current locale.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %B
+ The full month name according to the current locale.
+ &lt;br&gt;&lt;br&gt; Using &lt;CODE&gt;%B&lt;/CODE&gt; together with &lt;CODE&gt;%d&lt;/CODE&gt; produces grammatically
+ incorrect results for some locales.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %c
+ The preferred calendar time representation for the current locale.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %C
+ The century of the year. This is equivalent to the greatest integer not
+ greater than the year divided by 100.
+ &lt;br&gt;&lt;br&gt; This format was first standardized by POSIX.2-1992 and by ISO C99.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %d
+ The day of the month as a decimal number (range &lt;CODE&gt;01&lt;/CODE&gt; through &lt;CODE&gt;31&lt;/CODE&gt;).
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %D
+ The date using the format &lt;CODE&gt;%m/%d/%y&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; This format was first standardized by POSIX.2-1992 and by ISO C99.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %e
+ The day of the month like with &lt;CODE&gt;%d&lt;/CODE&gt;, but padded with blank (range
+ &lt;CODE&gt; 1&lt;/CODE&gt; through &lt;CODE&gt;31&lt;/CODE&gt;).
+ &lt;br&gt;&lt;br&gt; This format was first standardized by POSIX.2-1992 and by ISO C99.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %F
+ The date using the format &lt;CODE&gt;%Y-%m-%d&lt;/CODE&gt;. This is the form specified
+ in the ISO 8601 standard and is the preferred form for all uses.
+ &lt;br&gt;&lt;br&gt; This format was first standardized by ISO C99 and by POSIX.1-2001.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %g
+ The year corresponding to the ISO week number, but without the century
+ (range &lt;CODE&gt;00&lt;/CODE&gt; through &lt;CODE&gt;99&lt;/CODE&gt;). This has the same format and value
+ as &lt;CODE&gt;%y&lt;/CODE&gt;, except that if the ISO week number (see &lt;CODE&gt;%V&lt;/CODE&gt;) belongs
+ to the previous or next year, that year is used instead.
+ &lt;br&gt;&lt;br&gt; This format was first standardized by ISO C99 and by POSIX.1-2001.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %G
+ The year corresponding to the ISO week number. This has the same format
+ and value as &lt;CODE&gt;%Y&lt;/CODE&gt;, except that if the ISO week number (see
+ &lt;CODE&gt;%V&lt;/CODE&gt;) belongs to the previous or next year, that year is used
+ instead.
+ &lt;br&gt;&lt;br&gt; This format was first standardized by ISO C99 and by POSIX.1-2001
+ but was previously available as a GNU extension.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %h
+ The abbreviated month name according to the current locale. The action
+ is the same as for &lt;CODE&gt;%b&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; This format was first standardized by POSIX.2-1992 and by ISO C99.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %H
+ The hour as a decimal number, using a 24-hour clock (range &lt;CODE&gt;00&lt;/CODE&gt; through
+ &lt;CODE&gt;23&lt;/CODE&gt;).
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %I
+ The hour as a decimal number, using a 12-hour clock (range &lt;CODE&gt;01&lt;/CODE&gt; through
+ &lt;CODE&gt;12&lt;/CODE&gt;).
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %j
+ The day of the year as a decimal number (range &lt;CODE&gt;001&lt;/CODE&gt; through &lt;CODE&gt;366&lt;/CODE&gt;).
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %k
+ The hour as a decimal number, using a 24-hour clock like &lt;CODE&gt;%H&lt;/CODE&gt;, but
+ padded with blank (range &lt;CODE&gt; 0&lt;/CODE&gt; through &lt;CODE&gt;23&lt;/CODE&gt;).
+ &lt;br&gt;&lt;br&gt; This format is a GNU extension.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %l
+ The hour as a decimal number, using a 12-hour clock like &lt;CODE&gt;%I&lt;/CODE&gt;, but
+ padded with blank (range &lt;CODE&gt; 1&lt;/CODE&gt; through &lt;CODE&gt;12&lt;/CODE&gt;).
+ &lt;br&gt;&lt;br&gt; This format is a GNU extension.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %m
+ The month as a decimal number (range &lt;CODE&gt;01&lt;/CODE&gt; through &lt;CODE&gt;12&lt;/CODE&gt;).
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %M
+ The minute as a decimal number (range &lt;CODE&gt;00&lt;/CODE&gt; through &lt;CODE&gt;59&lt;/CODE&gt;).
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %n
+ A single &lt;samp&gt;\n&lt;/samp&gt; (newline) character.
+ &lt;br&gt;&lt;br&gt; This format was first standardized by POSIX.2-1992 and by ISO C99.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %p
+ Either &lt;samp&gt;AM&lt;/samp&gt; or &lt;samp&gt;PM&lt;/samp&gt;, according to the given time value; or the
+ corresponding strings for the current locale. Noon is treated as
+ &lt;samp&gt;PM&lt;/samp&gt; and midnight as &lt;samp&gt;AM&lt;/samp&gt;. In most locales
+ &lt;samp&gt;AM&lt;/samp&gt;/&lt;samp&gt;PM&lt;/samp&gt; format is not supported, in such cases &lt;CODE&gt;"%p"&lt;/CODE&gt;
+ yields an empty string.
+ &lt;br&gt;&lt;br&gt;
+ &lt;LI&gt; %P
+ Either &lt;samp&gt;am&lt;/samp&gt; or &lt;samp&gt;pm&lt;/samp&gt;, according to the given time value; or the
+ corresponding strings for the current locale, printed in lowercase
+ characters. Noon is treated as &lt;samp&gt;pm&lt;/samp&gt; and midnight as &lt;samp&gt;am&lt;/samp&gt;. In
+ most locales &lt;samp&gt;AM&lt;/samp&gt;/&lt;samp&gt;PM&lt;/samp&gt; format is not supported, in such cases
+ &lt;CODE&gt;"%P"&lt;/CODE&gt; yields an empty string.
+ &lt;br&gt;&lt;br&gt; This format is a GNU extension.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %r
+ The complete calendar time using the AM/PM format of the current locale.
+ &lt;br&gt;&lt;br&gt; This format was first standardized by POSIX.2-1992 and by ISO C99.
+ In the POSIX locale, this format is equivalent to &lt;CODE&gt;%I:%M:%S %p&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %R
+ The hour and minute in decimal numbers using the format &lt;CODE&gt;%H:%M&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; This format was first standardized by ISO C99 and by POSIX.1-2001
+ but was previously available as a GNU extension.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %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.
+ &lt;br&gt;&lt;br&gt; This format is a GNU extension.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %S
+ The seconds as a decimal number (range &lt;CODE&gt;00&lt;/CODE&gt; through &lt;CODE&gt;60&lt;/CODE&gt;).
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %t
+ A single &lt;samp&gt;\t&lt;/samp&gt; (tabulator) character.
+ &lt;br&gt;&lt;br&gt; This format was first standardized by POSIX.2-1992 and by ISO C99.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %T
+ The time of day using decimal numbers using the format &lt;CODE&gt;%H:%M:%S&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; This format was first standardized by POSIX.2-1992 and by ISO C99.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %u
+ The day of the week as a decimal number (range &lt;CODE&gt;1&lt;/CODE&gt; through
+ &lt;CODE&gt;7&lt;/CODE&gt;), Monday being &lt;CODE&gt;1&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; This format was first standardized by POSIX.2-1992 and by ISO C99.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %U
+ The week number of the current year as a decimal number (range &lt;CODE&gt;00&lt;/CODE&gt;
+ through &lt;CODE&gt;53&lt;/CODE&gt;), 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 &lt;CODE&gt;00&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %V
+ The ISO 8601:1988 week number as a decimal number (range &lt;CODE&gt;01&lt;/CODE&gt;
+ through &lt;CODE&gt;53&lt;/CODE&gt;). ISO weeks start with Monday and end with Sunday.
+ Week &lt;CODE&gt;01&lt;/CODE&gt; 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 &lt;CODE&gt;01&lt;/CODE&gt; of a year can contain days from the previous year.
+ The week before week &lt;CODE&gt;01&lt;/CODE&gt; of a year is the last week (&lt;CODE&gt;52&lt;/CODE&gt; or
+ &lt;CODE&gt;53&lt;/CODE&gt;) of the previous year even if it contains days from the new
+ year.
+ &lt;br&gt;&lt;br&gt; This format was first standardized by POSIX.2-1992 and by ISO C99.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %w
+ The day of the week as a decimal number (range &lt;CODE&gt;0&lt;/CODE&gt; through
+ &lt;CODE&gt;6&lt;/CODE&gt;), Sunday being &lt;CODE&gt;0&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %W
+ The week number of the current year as a decimal number (range &lt;CODE&gt;00&lt;/CODE&gt;
+ through &lt;CODE&gt;53&lt;/CODE&gt;), 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 &lt;CODE&gt;00&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %x
+ The preferred date representation for the current locale.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %X
+ The preferred time of day representation for the current locale.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %y
+ The year without a century as a decimal number (range &lt;CODE&gt;00&lt;/CODE&gt; through
+ &lt;CODE&gt;99&lt;/CODE&gt;). This is equivalent to the year modulo 100.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %Y
+ The year as a decimal number, using the Gregorian calendar. Years
+ before the year &lt;CODE&gt;1&lt;/CODE&gt; are numbered &lt;CODE&gt;0&lt;/CODE&gt;, &lt;CODE&gt;-1&lt;/CODE&gt;, and so on.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %z
+ RFC 822/ISO 8601:1988 style numeric time zone (e.g.,
+ &lt;CODE&gt;-0600&lt;/CODE&gt; or &lt;CODE&gt;+0100&lt;/CODE&gt;), or nothing if no time zone is
+ determinable.
+ &lt;br&gt;&lt;br&gt; This format was first standardized by ISO C99 and by POSIX.1-2001
+ but was previously available as a GNU extension.
+ &lt;br&gt;&lt;br&gt; In the POSIX locale, a full RFC 822 timestamp is generated by the format
+ &lt;samp&gt;"%a, %d %b %Y %H:%M:%S %z"&lt;/samp&gt; (or the equivalent
+ &lt;samp&gt;"%a, %d %b %Y %T %z"&lt;/samp&gt;).
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %Z
+ The time zone abbreviation (empty if the time zone can't be determined).
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %%
+ A literal &lt;samp&gt;%&lt;/samp&gt; character.
+
+ &lt;br&gt;&lt;br&gt; The &lt;VAR&gt;size&lt;/VAR&gt; parameter can be used to specify the maximum number of
+ characters to be stored in the array &lt;VAR&gt;s&lt;/VAR&gt;, including the terminating
+ null character. If the formatted time requires more than &lt;VAR&gt;size&lt;/VAR&gt;
+ characters, &lt;CODE&gt;strftime&lt;/CODE&gt; returns zero and the contents of the array
+ &lt;VAR&gt;s&lt;/VAR&gt; are undefined. Otherwise the return value indicates the
+ number of characters placed in the array &lt;VAR&gt;s&lt;/VAR&gt;, not including the
+ terminating null character.
+ &lt;br&gt;&lt;br&gt; &lt;EM&gt;Warning:&lt;/EM&gt; 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
+ &lt;CODE&gt;"%p"&lt;/CODE&gt; 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:
+ &lt;br&gt;&lt;br&gt; &lt;pre&gt;&lt;br&gt;
+ buf[0] = '\1';&lt;br&gt;
+ len = strftime (buf, bufsize, format, tp);&lt;br&gt;
+ if (len == 0 &amp;&amp; buf[0] != '\0')&lt;br&gt;
+ {&lt;br&gt;
+ /* Something went wrong in the strftime call. */&lt;br&gt;
+ &lt;small&gt;...&lt;/small&gt;&lt;br&gt;
+ }&lt;br&gt;
+ &lt;/pre&gt;
+ &lt;br&gt;&lt;br&gt; If &lt;VAR&gt;s&lt;/VAR&gt; is a null pointer, &lt;CODE&gt;strftime&lt;/CODE&gt; does not actually write
+ anything, but instead returns the number of characters it would have written.
+ &lt;br&gt;&lt;br&gt; According to POSIX.1 every call to &lt;CODE&gt;strftime&lt;/CODE&gt; implies a call to
+ &lt;CODE&gt;tzset&lt;/CODE&gt;. So the contents of the environment variable &lt;CODE&gt;TZ&lt;/CODE&gt;
+ is examined before any output is produced.
+ &lt;br&gt;&lt;br&gt; For an example of &lt;CODE&gt;strftime&lt;/CODE&gt;, see Time Functions Example.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-wcsftime" type="function">
+ <function returntype="size_t">
+ <prototype>
+ <parameter content="wchar_t *s"/>
+ <parameter content="size_t size"/>
+ <parameter content="const wchar_t *template"/>
+ <parameter content="const struct tm *brokentime"/>
+ </prototype>
+ <headers>
+ <header filename = "time.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;wcsftime&lt;/CODE&gt; function is equivalent to the &lt;CODE&gt;strftime&lt;/CODE&gt;
+ function with the difference that it operates on wide character
+ strings. The buffer where the result is stored, pointed to by &lt;VAR&gt;s&lt;/VAR&gt;,
+ must be an array of wide characters. The parameter &lt;VAR&gt;size&lt;/VAR&gt; which
+ specifies the size of the output buffer gives the number of wide
+ character, not the number of bytes.
+ &lt;br&gt;&lt;br&gt; Also the format string &lt;VAR&gt;template&lt;/VAR&gt; 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 &lt;CODE&gt;L"&lt;small&gt;...&lt;/small&gt;"&lt;/CODE&gt; notation. The parameter
+ &lt;VAR&gt;brokentime&lt;/VAR&gt; has the same meaning as in the &lt;CODE&gt;strftime&lt;/CODE&gt; call.
+ &lt;br&gt;&lt;br&gt; The &lt;CODE&gt;wcsftime&lt;/CODE&gt; function supports the same flags, modifiers, and
+ format specifiers as the &lt;CODE&gt;strftime&lt;/CODE&gt; function.
+ &lt;br&gt;&lt;br&gt; The return value of &lt;CODE&gt;wcsftime&lt;/CODE&gt; is the number of wide characters
+ stored in &lt;CODE&gt;s&lt;/CODE&gt;. When more characters would have to be written than
+ can be placed in the buffer &lt;VAR&gt;s&lt;/VAR&gt; the return value is zero, with the
+ same problems indicated in the &lt;CODE&gt;strftime&lt;/CODE&gt; documentation.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-strptime" type="function">
+ <function returntype="char *">
+ <prototype>
+ <parameter content="const char *s"/>
+ <parameter content="const char *fmt"/>
+ <parameter content="struct tm *tp"/>
+ </prototype>
+ <headers>
+ <header filename = "time.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;strptime&lt;/CODE&gt; function parses the input string &lt;VAR&gt;s&lt;/VAR&gt; according
+ to the format string &lt;VAR&gt;fmt&lt;/VAR&gt; and stores its results in the
+ structure &lt;VAR&gt;tp&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; The input string could be generated by a &lt;CODE&gt;strftime&lt;/CODE&gt; call or
+ obtained any other way. It does not need to be in a human-recognizable
+ format; e.g. a date passed as &lt;CODE&gt;"02:1999:9"&lt;/CODE&gt; is acceptable, even
+ though it is ambiguous without context. As long as the format string
+ &lt;VAR&gt;fmt&lt;/VAR&gt; matches the input string the function will succeed.
+ &lt;br&gt;&lt;br&gt; The user has to make sure, though, that the input can be parsed in a
+ unambiguous way. The string &lt;CODE&gt;"1999112"&lt;/CODE&gt; can be parsed using the
+ format &lt;CODE&gt;"%Y%m%d"&lt;/CODE&gt; as 1999-1-12, 1999-11-2, or even 19991-1-2. It
+ is necessary to add appropriate separators to reliably get results.
+ &lt;br&gt;&lt;br&gt; The format string consists of the same components as the format string
+ of the &lt;CODE&gt;strftime&lt;/CODE&gt; function. The only difference is that the flags
+ &lt;CODE&gt;_&lt;/CODE&gt;, &lt;CODE&gt;-&lt;/CODE&gt;, &lt;CODE&gt;0&lt;/CODE&gt;, and &lt;CODE&gt;^&lt;/CODE&gt; are not allowed.
+ Several of the distinct formats of &lt;CODE&gt;strftime&lt;/CODE&gt; do the same work in
+ &lt;CODE&gt;strptime&lt;/CODE&gt; since differences like case of the input do not matter.
+ For reasons of symmetry all formats are supported, though.
+ &lt;br&gt;&lt;br&gt; The modifiers &lt;CODE&gt;E&lt;/CODE&gt; and &lt;CODE&gt;O&lt;/CODE&gt; are also allowed everywhere the
+ &lt;CODE&gt;strftime&lt;/CODE&gt; function allows them.
+ &lt;br&gt;&lt;br&gt; The formats are:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;%a&lt;/CODE&gt;
+&lt;DD&gt;
+ &lt;LI&gt;x %A
+ The weekday name according to the current locale, in abbreviated form or
+ the full name.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %b
+ &lt;LI&gt;x %B
+ &lt;LI&gt;x %h
+ The month name according to the current locale, in abbreviated form or
+ the full name.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %c
+ The date and time representation for the current locale.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %Ec
+ Like &lt;CODE&gt;%c&lt;/CODE&gt; but the locale's alternative date and time format is used.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %C
+ The century of the year.
+ &lt;br&gt;&lt;br&gt; It makes sense to use this format only if the format string also
+ contains the &lt;CODE&gt;%y&lt;/CODE&gt; format.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %EC
+ The locale's representation of the period.
+ &lt;br&gt;&lt;br&gt; Unlike &lt;CODE&gt;%C&lt;/CODE&gt; 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.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %d
+ &lt;LI&gt; %e
+ The day of the month as a decimal number (range &lt;CODE&gt;1&lt;/CODE&gt; through &lt;CODE&gt;31&lt;/CODE&gt;).
+ Leading zeroes are permitted but not required.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %Od
+ &lt;LI&gt;x %Oe
+ Same as &lt;CODE&gt;%d&lt;/CODE&gt; but using the locale's alternative numeric symbols.
+ &lt;br&gt;&lt;br&gt; Leading zeroes are permitted but not required.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %D
+ Equivalent to &lt;CODE&gt;%m/%d/%y&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %F
+ Equivalent to &lt;CODE&gt;%Y-%m-%d&lt;/CODE&gt;, which is the ISO 8601 date
+ format.
+ &lt;br&gt;&lt;br&gt; This is a GNU extension following an ISO C99 extension to
+ &lt;CODE&gt;strftime&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %g
+ The year corresponding to the ISO week number, but without the century
+ (range &lt;CODE&gt;00&lt;/CODE&gt; through &lt;CODE&gt;99&lt;/CODE&gt;).
+ &lt;br&gt;&lt;br&gt; &lt;EM&gt;Note:&lt;/EM&gt; Currently, this is not fully implemented. The format is
+ recognized, input is consumed but no field in &lt;VAR&gt;tm&lt;/VAR&gt; is set.
+ &lt;br&gt;&lt;br&gt; This format is a GNU extension following a GNU extension of &lt;CODE&gt;strftime&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %G
+ The year corresponding to the ISO week number.
+ &lt;br&gt;&lt;br&gt; &lt;EM&gt;Note:&lt;/EM&gt; Currently, this is not fully implemented. The format is
+ recognized, input is consumed but no field in &lt;VAR&gt;tm&lt;/VAR&gt; is set.
+ &lt;br&gt;&lt;br&gt; This format is a GNU extension following a GNU extension of &lt;CODE&gt;strftime&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %H
+ &lt;LI&gt;x %k
+ The hour as a decimal number, using a 24-hour clock (range &lt;CODE&gt;00&lt;/CODE&gt; through
+ &lt;CODE&gt;23&lt;/CODE&gt;).
+ &lt;br&gt;&lt;br&gt; &lt;CODE&gt;%k&lt;/CODE&gt; is a GNU extension following a GNU extension of &lt;CODE&gt;strftime&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %OH
+ Same as &lt;CODE&gt;%H&lt;/CODE&gt; but using the locale's alternative numeric symbols.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %I
+ &lt;LI&gt;x %l
+ The hour as a decimal number, using a 12-hour clock (range &lt;CODE&gt;01&lt;/CODE&gt; through
+ &lt;CODE&gt;12&lt;/CODE&gt;).
+ &lt;br&gt;&lt;br&gt; &lt;CODE&gt;%l&lt;/CODE&gt; is a GNU extension following a GNU extension of &lt;CODE&gt;strftime&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %OI
+ Same as &lt;CODE&gt;%I&lt;/CODE&gt; but using the locale's alternative numeric symbols.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %j
+ The day of the year as a decimal number (range &lt;CODE&gt;1&lt;/CODE&gt; through &lt;CODE&gt;366&lt;/CODE&gt;).
+ &lt;br&gt;&lt;br&gt; Leading zeroes are permitted but not required.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %m
+ The month as a decimal number (range &lt;CODE&gt;1&lt;/CODE&gt; through &lt;CODE&gt;12&lt;/CODE&gt;).
+ &lt;br&gt;&lt;br&gt; Leading zeroes are permitted but not required.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %Om
+ Same as &lt;CODE&gt;%m&lt;/CODE&gt; but using the locale's alternative numeric symbols.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %M
+ The minute as a decimal number (range &lt;CODE&gt;0&lt;/CODE&gt; through &lt;CODE&gt;59&lt;/CODE&gt;).
+ &lt;br&gt;&lt;br&gt; Leading zeroes are permitted but not required.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %OM
+ Same as &lt;CODE&gt;%M&lt;/CODE&gt; but using the locale's alternative numeric symbols.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %n
+ &lt;LI&gt;x %t
+ Matches any white space.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %p
+ &lt;LI&gt; %P
+ The locale-dependent equivalent to &lt;samp&gt;AM&lt;/samp&gt; or &lt;samp&gt;PM&lt;/samp&gt;.
+ &lt;br&gt;&lt;br&gt; This format is not useful unless &lt;CODE&gt;%I&lt;/CODE&gt; or &lt;CODE&gt;%l&lt;/CODE&gt; is also used.
+ Another complication is that the locale might not define these values at
+ all and therefore the conversion fails.
+ &lt;br&gt;&lt;br&gt; &lt;CODE&gt;%P&lt;/CODE&gt; is a GNU extension following a GNU extension to &lt;CODE&gt;strftime&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %r
+ The complete time using the AM/PM format of the current locale.
+ &lt;br&gt;&lt;br&gt; A complication is that the locale might not define this format at all
+ and therefore the conversion fails.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %R
+ The hour and minute in decimal numbers using the format &lt;CODE&gt;%H:%M&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; &lt;CODE&gt;%R&lt;/CODE&gt; is a GNU extension following a GNU extension to &lt;CODE&gt;strftime&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %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.
+ &lt;br&gt;&lt;br&gt; &lt;CODE&gt;%s&lt;/CODE&gt; is a GNU extension following a GNU extension to &lt;CODE&gt;strftime&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %S
+ The seconds as a decimal number (range &lt;CODE&gt;0&lt;/CODE&gt; through &lt;CODE&gt;60&lt;/CODE&gt;).
+ &lt;br&gt;&lt;br&gt; Leading zeroes are permitted but not required.
+ &lt;br&gt;&lt;br&gt; NB: The Unix specification says the upper bound on this value
+ is &lt;CODE&gt;61&lt;/CODE&gt;, a result of a decision to allow double leap seconds. You
+ will not see the value &lt;CODE&gt;61&lt;/CODE&gt; because no minute has more than one
+ leap second, but the myth persists.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %OS
+ Same as &lt;CODE&gt;%S&lt;/CODE&gt; but using the locale's alternative numeric symbols.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %T
+ Equivalent to the use of &lt;CODE&gt;%H:%M:%S&lt;/CODE&gt; in this place.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %u
+ The day of the week as a decimal number (range &lt;CODE&gt;1&lt;/CODE&gt; through
+ &lt;CODE&gt;7&lt;/CODE&gt;), Monday being &lt;CODE&gt;1&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; Leading zeroes are permitted but not required.
+ &lt;br&gt;&lt;br&gt; &lt;EM&gt;Note:&lt;/EM&gt; Currently, this is not fully implemented. The format is
+ recognized, input is consumed but no field in &lt;VAR&gt;tm&lt;/VAR&gt; is set.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %U
+ The week number of the current year as a decimal number (range &lt;CODE&gt;0&lt;/CODE&gt;
+ through &lt;CODE&gt;53&lt;/CODE&gt;).
+ &lt;br&gt;&lt;br&gt; Leading zeroes are permitted but not required.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %OU
+ Same as &lt;CODE&gt;%U&lt;/CODE&gt; but using the locale's alternative numeric symbols.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %V
+ The ISO 8601:1988 week number as a decimal number (range &lt;CODE&gt;1&lt;/CODE&gt;
+ through &lt;CODE&gt;53&lt;/CODE&gt;).
+ &lt;br&gt;&lt;br&gt; Leading zeroes are permitted but not required.
+ &lt;br&gt;&lt;br&gt; &lt;EM&gt;Note:&lt;/EM&gt; Currently, this is not fully implemented. The format is
+ recognized, input is consumed but no field in &lt;VAR&gt;tm&lt;/VAR&gt; is set.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %w
+ The day of the week as a decimal number (range &lt;CODE&gt;0&lt;/CODE&gt; through
+ &lt;CODE&gt;6&lt;/CODE&gt;), Sunday being &lt;CODE&gt;0&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; Leading zeroes are permitted but not required.
+ &lt;br&gt;&lt;br&gt; &lt;EM&gt;Note:&lt;/EM&gt; Currently, this is not fully implemented. The format is
+ recognized, input is consumed but no field in &lt;VAR&gt;tm&lt;/VAR&gt; is set.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %Ow
+ Same as &lt;CODE&gt;%w&lt;/CODE&gt; but using the locale's alternative numeric symbols.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %W
+ The week number of the current year as a decimal number (range &lt;CODE&gt;0&lt;/CODE&gt;
+ through &lt;CODE&gt;53&lt;/CODE&gt;).
+ &lt;br&gt;&lt;br&gt; Leading zeroes are permitted but not required.
+ &lt;br&gt;&lt;br&gt; &lt;EM&gt;Note:&lt;/EM&gt; Currently, this is not fully implemented. The format is
+ recognized, input is consumed but no field in &lt;VAR&gt;tm&lt;/VAR&gt; is set.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %OW
+ Same as &lt;CODE&gt;%W&lt;/CODE&gt; but using the locale's alternative numeric symbols.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %x
+ The date using the locale's date format.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %Ex
+ Like &lt;CODE&gt;%x&lt;/CODE&gt; but the locale's alternative data representation is used.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %X
+ The time using the locale's time format.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %EX
+ Like &lt;CODE&gt;%X&lt;/CODE&gt; but the locale's alternative time representation is used.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %y
+ The year without a century as a decimal number (range &lt;CODE&gt;0&lt;/CODE&gt; through
+ &lt;CODE&gt;99&lt;/CODE&gt;).
+ &lt;br&gt;&lt;br&gt; Leading zeroes are permitted but not required.
+ &lt;br&gt;&lt;br&gt; Note that it is questionable to use this format without
+ the &lt;CODE&gt;%C&lt;/CODE&gt; format. The &lt;CODE&gt;strptime&lt;/CODE&gt; 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.
+ &lt;br&gt;&lt;br&gt; Therefore it is best to avoid &lt;CODE&gt;%y&lt;/CODE&gt; completely and use &lt;CODE&gt;%Y&lt;/CODE&gt;
+ instead.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %Ey
+ The offset from &lt;CODE&gt;%EC&lt;/CODE&gt; in the locale's alternative representation.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %Oy
+ The offset of the year (from &lt;CODE&gt;%C&lt;/CODE&gt;) using the locale's alternative
+ numeric symbols.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %Y
+ The year as a decimal number, using the Gregorian calendar.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %EY
+ The full alternative year representation.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %z
+ The offset from GMT in ISO 8601/RFC822 format.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %Z
+ The timezone name.
+ &lt;br&gt;&lt;br&gt; &lt;EM&gt;Note:&lt;/EM&gt; Currently, this is not fully implemented. The format is
+ recognized, input is consumed but no field in &lt;VAR&gt;tm&lt;/VAR&gt; is set.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; %%
+ A literal &lt;samp&gt;%&lt;/samp&gt; character.
+
+ &lt;br&gt;&lt;br&gt; 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.
+ &lt;br&gt;&lt;br&gt; Portability Note: The XPG standard advises applications to use
+ at least one whitespace character (as specified by &lt;CODE&gt;isspace&lt;/CODE&gt;) 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
+ &lt;CODE&gt;"%d%m%Y%H%M%S"&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; The &lt;CODE&gt;strptime&lt;/CODE&gt; 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.
+ &lt;br&gt;&lt;br&gt; 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 &lt;CODE&gt;NULL&lt;/CODE&gt; byte at the end of the string. If an error
+ occurs, i.e., &lt;CODE&gt;strptime&lt;/CODE&gt; fails to match all of the format string,
+ the function returns &lt;CODE&gt;NULL&lt;/CODE&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-getdate" type="function">
+ <function returntype="struct tm *">
+ <prototype>
+ <parameter content="const char *string"/>
+ </prototype>
+ <headers>
+ <header filename = "time.h"/>
+ </headers>
+ <synopsis>
+ The interface to &lt;CODE&gt;getdate&lt;/CODE&gt; is the simplest possible for a function
+ to parse a string and return the value. &lt;VAR&gt;string&lt;/VAR&gt; is the input
+ string and the result is returned in a statically-allocated variable.
+ &lt;br&gt;&lt;br&gt; 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 &lt;CODE&gt;DATEMSK&lt;/CODE&gt;. This file should contain
+ lines of valid format strings which could be passed to &lt;CODE&gt;strptime&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; The &lt;CODE&gt;getdate&lt;/CODE&gt; 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.
+ &lt;br&gt;&lt;br&gt; Elements not initialized through the format string retain the values
+ present at the time of the &lt;CODE&gt;getdate&lt;/CODE&gt; function call.
+ &lt;br&gt;&lt;br&gt; The formats recognized by &lt;CODE&gt;getdate&lt;/CODE&gt; are the same as for
+ &lt;CODE&gt;strptime&lt;/CODE&gt;. See above for an explanation. There are only a few
+ extensions to the &lt;CODE&gt;strptime&lt;/CODE&gt; behavior:
+ &lt;br&gt;&lt;br&gt; &lt;OL&gt;
+ &lt;LI&gt;
+ If the &lt;CODE&gt;%Z&lt;/CODE&gt; 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.
+ &lt;br&gt;&lt;br&gt; &lt;EM&gt;Note&lt;/EM&gt;: 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 &lt;CODE&gt;EST&lt;/CODE&gt; 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.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt;
+ If only the weekday is specified the selected day depends on the current
+ date. If the current weekday is greater or equal to the &lt;CODE&gt;tm_wday&lt;/CODE&gt;
+ value the current week's day is chosen, otherwise the day next week is chosen.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt;
+ 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.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt;
+ The current hour, minute, and second are used if the appropriate value is
+ not set through the format.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt;
+ 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.
+ &lt;/OL&gt;
+ &lt;br&gt;&lt;br&gt; 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):
+ &lt;br&gt;&lt;br&gt; &lt;pre&gt;&lt;br&gt;
+ %m&lt;br&gt;
+ %A %B %d, %Y %H:%M:%S&lt;br&gt;
+ %A&lt;br&gt;
+ %B&lt;br&gt;
+ %m/%d/%y %I %p&lt;br&gt;
+ %d,%m,%Y %H:%M&lt;br&gt;
+ at %A the %dst of %B in %Y&lt;br&gt;
+ run job at %I %p,%B %dnd&lt;br&gt;
+ %A den %d. %B %Y %H.%M Uhr&lt;br&gt;
+ &lt;/pre&gt;
+ &lt;br&gt;&lt;br&gt; As you can see, the template list can contain very specific strings like
+ &lt;CODE&gt;run job at %I %p,%B %dnd&lt;/CODE&gt;. 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.
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+&lt;DT&gt;&lt;pre&gt;Input Match Result&lt;/pre&gt;
+&lt;DD&gt;&lt;br&gt; &lt;DT&gt;&lt;pre&gt;Mon %a Mon Sep 22 12:19:47 EDT 1986&lt;/pre&gt;
+&lt;DD&gt;&lt;br&gt; &lt;DT&gt;&lt;pre&gt;Sun %a Sun Sep 28 12:19:47 EDT 1986&lt;/pre&gt;
+&lt;DD&gt;&lt;br&gt; &lt;DT&gt;&lt;pre&gt;Fri %a Fri Sep 26 12:19:47 EDT 1986&lt;/pre&gt;
+&lt;DD&gt;&lt;br&gt; &lt;DT&gt;&lt;pre&gt;September %B Mon Sep 1 12:19:47 EDT 1986&lt;/pre&gt;
+&lt;DD&gt;&lt;br&gt; &lt;DT&gt;&lt;pre&gt;January %B Thu Jan 1 12:19:47 EST 1987&lt;/pre&gt;
+&lt;DD&gt;&lt;br&gt; &lt;DT&gt;&lt;pre&gt;December %B Mon Dec 1 12:19:47 EST 1986&lt;/pre&gt;
+&lt;DD&gt;&lt;br&gt; &lt;DT&gt;&lt;pre&gt;Sep Mon %b %a Mon Sep 1 12:19:47 EDT 1986&lt;/pre&gt;
+&lt;DD&gt;&lt;br&gt; &lt;DT&gt;&lt;pre&gt;Jan Fri %b %a Fri Jan 2 12:19:47 EST 1987&lt;/pre&gt;
+&lt;DD&gt;&lt;br&gt; &lt;DT&gt;&lt;pre&gt;Dec Mon %b %a Mon Dec 1 12:19:47 EST 1986&lt;/pre&gt;
+&lt;DD&gt;&lt;br&gt; &lt;DT&gt;&lt;pre&gt;Jan Wed 1989 %b %a %Y Wed Jan 4 12:19:47 EST 1989&lt;/pre&gt;
+&lt;DD&gt;&lt;br&gt; &lt;DT&gt;&lt;pre&gt;Fri 9 %a %H Fri Sep 26 09:00:00 EDT 1986&lt;/pre&gt;
+&lt;DD&gt;&lt;br&gt; &lt;DT&gt;&lt;pre&gt;Feb 10:30 %b %H:%S Sun Feb 1 10:00:30 EST 1987&lt;/pre&gt;
+&lt;DD&gt;&lt;br&gt; &lt;DT&gt;&lt;pre&gt;10:30 %H:%M Tue Sep 23 10:30:00 EDT 1986&lt;/pre&gt;
+&lt;DD&gt;&lt;br&gt; &lt;DT&gt;&lt;pre&gt;13:30 %H:%M Mon Sep 22 13:30:00 EDT 1986&lt;/pre&gt;
+&lt;DD&gt;&lt;br&gt; &lt;/DL&gt;
+ &lt;br&gt;&lt;br&gt; The return value of the function is a pointer to a static variable of
+ type &lt;CODE&gt;struct tm&lt;/CODE&gt;, or a null pointer if an error occurred. The
+ result is only valid until the next &lt;CODE&gt;getdate&lt;/CODE&gt; call, making this
+ function unusable in multi-threaded applications.
+ &lt;br&gt;&lt;br&gt; The &lt;CODE&gt;errno&lt;/CODE&gt; variable is &lt;EM&gt;not&lt;/EM&gt; changed. Error conditions are
+ stored in the global variable &lt;CODE&gt;getdate_err&lt;/CODE&gt;. See the
+ description above for a list of the possible error values.
+ &lt;br&gt;&lt;br&gt; &lt;EM&gt;Warning:&lt;/EM&gt; The &lt;CODE&gt;getdate&lt;/CODE&gt; function should &lt;EM&gt;never&lt;/EM&gt; be
+ used in SUID-programs. The reason is obvious: using the
+ &lt;CODE&gt;DATEMSK&lt;/CODE&gt; 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.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-getdate_r" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *string"/>
+ <parameter content="struct tm *tp"/>
+ </prototype>
+ <headers>
+ <header filename = "time.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;getdate_r&lt;/CODE&gt; function is the reentrant counterpart of
+ &lt;CODE&gt;getdate&lt;/CODE&gt;. It does not use the global variable &lt;CODE&gt;getdate_err&lt;/CODE&gt;
+ to signal an error, but instead returns an error code. The same error
+ codes as described in the &lt;CODE&gt;getdate_err&lt;/CODE&gt; documentation above are
+ used, with 0 meaning success.
+ &lt;br&gt;&lt;br&gt; Moreover, &lt;CODE&gt;getdate_r&lt;/CODE&gt; stores the broken-down time in the variable
+ of type &lt;CODE&gt;struct tm&lt;/CODE&gt; pointed to by the second argument, rather than
+ in a static variable.
+ &lt;br&gt;&lt;br&gt; This function is not defined in the Unix standard. Nevertheless it is
+ available on some other Unix systems as well.
+ &lt;br&gt;&lt;br&gt; The warning against using &lt;CODE&gt;getdate&lt;/CODE&gt; in SUID-programs applies to
+ &lt;CODE&gt;getdate_r&lt;/CODE&gt; as well.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-tzset" type="function">
+ <function returntype="void">
+ <prototype>
+ <parameter content="void"/>
+ </prototype>
+ <headers>
+ <header filename = "time.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;tzset&lt;/CODE&gt; function initializes the &lt;CODE&gt;tzname&lt;/CODE&gt; variable from
+ the value of the &lt;CODE&gt;TZ&lt;/CODE&gt; 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.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="struct-itimerval" type="struct">
+ <structure>
+ <synopsis>
+ This structure is used to specify when a timer should expire. It contains
+ the following members:
+ </synopsis>
+ <elements>
+ <element content="struct timeval it_interval">
+ <synopsis>
+ This is the period between successive timer interrupts. If zero, the
+ alarm will only be sent once.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ </elements>
+ </structure>
+ </construct>
+ <construct id="function-setitimer" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="int which"/>
+ <parameter content="struct itimerval *new"/>
+ <parameter content="struct itimerval *old"/>
+ </prototype>
+ <headers>
+ <header filename = "time.h"/>
+ <header filename = "sys/time.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;setitimer&lt;/CODE&gt; function sets the timer specified by &lt;VAR&gt;which&lt;/VAR&gt;
+ according to &lt;VAR&gt;new&lt;/VAR&gt;. The &lt;VAR&gt;which&lt;/VAR&gt; argument can have a value of
+ &lt;CODE&gt;ITIMER_REAL&lt;/CODE&gt;, &lt;CODE&gt;ITIMER_VIRTUAL&lt;/CODE&gt;, or &lt;CODE&gt;ITIMER_PROF&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; If &lt;VAR&gt;old&lt;/VAR&gt; is not a null pointer, &lt;CODE&gt;setitimer&lt;/CODE&gt; returns information
+ about any previous unexpired timer of the same kind in the structure it
+ points to.
+ &lt;br&gt;&lt;br&gt; The return value is &lt;CODE&gt;0&lt;/CODE&gt; on success and &lt;CODE&gt;-1&lt;/CODE&gt; on failure. The
+ following &lt;CODE&gt;errno&lt;/CODE&gt; error conditions are defined for this function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EINVAL&lt;/CODE&gt;
+&lt;DD&gt;
+ The timer period is too large.
+
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-getitimer" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="int which"/>
+ <parameter content="struct itimerval *old"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/time.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;getitimer&lt;/CODE&gt; function stores information about the timer specified
+ by &lt;VAR&gt;which&lt;/VAR&gt; in the structure pointed at by &lt;VAR&gt;old&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; The return value and error conditions are the same as for &lt;CODE&gt;setitimer&lt;/CODE&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-alarm" type="function">
+ <function returntype="unsigned int">
+ <prototype>
+ <parameter content="unsigned int seconds"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/time.h"/>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;alarm&lt;/CODE&gt; function sets the real-time timer to expire in
+ &lt;VAR&gt;seconds&lt;/VAR&gt; seconds. If you want to cancel any existing alarm, you
+ can do this by calling &lt;CODE&gt;alarm&lt;/CODE&gt; with a &lt;VAR&gt;seconds&lt;/VAR&gt; argument of
+ zero.
+ &lt;br&gt;&lt;br&gt; The return value indicates how many seconds remain before the previous
+ alarm would have been sent. If there is no previous alarm, &lt;CODE&gt;alarm&lt;/CODE&gt;
+ returns zero.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-sleep" type="function">
+ <function returntype="unsigned int">
+ <prototype>
+ <parameter content="unsigned int seconds"/>
+ </prototype>
+ <headers>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;sleep&lt;/CODE&gt; function waits for &lt;VAR&gt;seconds&lt;/VAR&gt; or until a signal
+ is delivered, whichever happens first.
+ &lt;br&gt;&lt;br&gt; If &lt;CODE&gt;sleep&lt;/CODE&gt; 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.
+ &lt;br&gt;&lt;br&gt; The &lt;CODE&gt;sleep&lt;/CODE&gt; function is declared in &lt;TT&gt;unistd.h&lt;/TT&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-nanosleep" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const struct timespec *requested_time"/>
+ <parameter content="struct timespec *remaining"/>
+ </prototype>
+ <headers>
+ <header filename = "time.h"/>
+ </headers>
+ <synopsis>
+ If resolution to seconds is not enough the &lt;CODE&gt;nanosleep&lt;/CODE&gt; 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.
+ &lt;br&gt;&lt;br&gt; *&lt;CODE&gt;requested_time&lt;/CODE&gt; is the elapsed time of the interval you want to
+ sleep.
+ &lt;br&gt;&lt;br&gt; The function returns as *&lt;CODE&gt;remaining&lt;/CODE&gt; 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.
+ &lt;br&gt;&lt;br&gt; &lt;CODE&gt;struct timespec&lt;/CODE&gt; is described in .
+ &lt;br&gt;&lt;br&gt; If the function returns because the interval is over the return value is
+ zero. If the function returns -1 the global variable &lt;VAR&gt;errno&lt;/VAR&gt;
+ is set to the following values:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EINTR&lt;/CODE&gt;
+&lt;DD&gt;
+ The call was interrupted because a signal was delivered to the thread.
+ If the &lt;VAR&gt;remaining&lt;/VAR&gt; parameter is not the null pointer the structure
+ pointed to by &lt;VAR&gt;remaining&lt;/VAR&gt; is updated to contain the remaining
+ elapsed time.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EINVAL
+ The nanosecond value in the &lt;VAR&gt;requested_time&lt;/VAR&gt; parameter contains an
+ illegal value. Either the value is negative or greater than or equal to
+ 1000 million.
+
+ &lt;br&gt;&lt;br&gt; 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 &lt;CODE&gt;nanosleep&lt;/CODE&gt; is
+ called. If the thread gets canceled these resources stay allocated
+ until the program ends. To avoid this calls to &lt;CODE&gt;nanosleep&lt;/CODE&gt; should
+ be protected using cancellation handlers.
+ &lt;br&gt;&lt;br&gt; The &lt;CODE&gt;nanosleep&lt;/CODE&gt; function is declared in &lt;TT&gt;time.h&lt;/TT&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="dtype-va_list" type="dtype">
+ <structure>
+ </structure>
+ </construct>
+ <construct id="dtype-ptrdiff_t" type="dtype">
+ <structure>
+ </structure>
+ </construct>
+ <construct id="dtype-size_t" type="dtype">
+ <structure>
+ </structure>
+ </construct>
+ <construct id="function-system" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *command"/>
+ </prototype>
+ <headers>
+ <header filename = "stdlib.h"/>
+ </headers>
+ <synopsis>
+ This function executes &lt;VAR&gt;command&lt;/VAR&gt; as a shell command. In the GNU C
+ library, it always uses the default shell &lt;CODE&gt;sh&lt;/CODE&gt; to run the command.
+ In particular, it searches the directories in &lt;CODE&gt;PATH&lt;/CODE&gt; to find
+ programs to execute. The return value is &lt;CODE&gt;-1&lt;/CODE&gt; 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.
+ &lt;br&gt;&lt;br&gt; If the &lt;VAR&gt;command&lt;/VAR&gt; argument is a null pointer, a return value of zero
+ indicates that no command processor is available.
+ &lt;br&gt;&lt;br&gt; 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 &lt;CODE&gt;system&lt;/CODE&gt; is
+ called. If the thread gets canceled these resources stay allocated
+ until the program ends. To avoid this calls to &lt;CODE&gt;system&lt;/CODE&gt; should be
+ protected using cancellation handlers.
+ &lt;br&gt;&lt;br&gt; The &lt;CODE&gt;system&lt;/CODE&gt; function is declared in the header file
+ &lt;TT&gt;stdlib.h&lt;/TT&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="dtype-pid_t" type="dtype">
+ <structure>
+ </structure>
+ </construct>
+ <construct id="function-getpid" type="function">
+ <function returntype="pid_t">
+ <prototype>
+ <parameter content="void"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/types.h"/>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;getpid&lt;/CODE&gt; function returns the process ID of the current process.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-getppid" type="function">
+ <function returntype="pid_t">
+ <prototype>
+ <parameter content="void"/>
+ </prototype>
+ <headers>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;getppid&lt;/CODE&gt; function returns the process ID of the parent of the
+ current process.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-fork" type="function">
+ <function returntype="pid_t">
+ <prototype>
+ <parameter content="void"/>
+ </prototype>
+ <headers>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;fork&lt;/CODE&gt; function creates a new process.
+ &lt;br&gt;&lt;br&gt; If the operation is successful, there are then both parent and child
+ processes and both see &lt;CODE&gt;fork&lt;/CODE&gt; return, but with different values: it
+ returns a value of &lt;CODE&gt;0&lt;/CODE&gt; in the child process and returns the child's
+ process ID in the parent process.
+ &lt;br&gt;&lt;br&gt; If process creation failed, &lt;CODE&gt;fork&lt;/CODE&gt; returns a value of &lt;CODE&gt;-1&lt;/CODE&gt; in
+ the parent process. The following &lt;CODE&gt;errno&lt;/CODE&gt; error conditions are
+ defined for &lt;CODE&gt;fork&lt;/CODE&gt;:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EAGAIN&lt;/CODE&gt;
+&lt;DD&gt;
+ There aren't enough system resources to create another process, or the
+ user already has too many processes running. This means exceeding the
+ &lt;CODE&gt;RLIMIT_NPROC&lt;/CODE&gt; resource limit, which can usually be increased;
+ .
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ENOMEM
+ The process requires more space than the system can supply.
+
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-vfork" type="function">
+ <function returntype="pid_t">
+ <prototype>
+ <parameter content="void"/>
+ </prototype>
+ <headers>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;vfork&lt;/CODE&gt; function is similar to &lt;CODE&gt;fork&lt;/CODE&gt; but on some systems
+ it is more efficient; however, there are restrictions you must follow to
+ use it safely.
+ &lt;br&gt;&lt;br&gt; While &lt;CODE&gt;fork&lt;/CODE&gt; makes a complete copy of the calling process's address
+ space and allows both the parent and child to execute independently,
+ &lt;CODE&gt;vfork&lt;/CODE&gt; does not make this copy. Instead, the child process
+ created with &lt;CODE&gt;vfork&lt;/CODE&gt; shares its parent's address space until it
+ calls &lt;CODE&gt;_exit&lt;/CODE&gt; or one of the &lt;CODE&gt;exec&lt;/CODE&gt; functions. In the
+ meantime, the parent process suspends execution.
+ &lt;br&gt;&lt;br&gt; You must be very careful not to allow the child process created with
+ &lt;CODE&gt;vfork&lt;/CODE&gt; 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 &lt;CODE&gt;vfork&lt;/CODE&gt;! This
+ would leave the parent process's control information very confused. If
+ in doubt, use &lt;CODE&gt;fork&lt;/CODE&gt; instead.
+ &lt;br&gt;&lt;br&gt; Some operating systems don't really implement &lt;CODE&gt;vfork&lt;/CODE&gt;. The GNU C
+ library permits you to use &lt;CODE&gt;vfork&lt;/CODE&gt; on all systems, but actually
+ executes &lt;CODE&gt;fork&lt;/CODE&gt; if &lt;CODE&gt;vfork&lt;/CODE&gt; isn't available. If you follow
+ the proper precautions for using &lt;CODE&gt;vfork&lt;/CODE&gt;, your program will still
+ work even if the system uses &lt;CODE&gt;fork&lt;/CODE&gt; instead.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-execv" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *filename"/>
+ <parameter content="char *const argv[]"/>
+ </prototype>
+ <headers>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;execv&lt;/CODE&gt; function executes the file named by &lt;VAR&gt;filename&lt;/VAR&gt; as a
+ new process image.
+ &lt;br&gt;&lt;br&gt; The &lt;VAR&gt;argv&lt;/VAR&gt; argument is an array of null-terminated strings that is
+ used to provide a value for the &lt;CODE&gt;argv&lt;/CODE&gt; argument to the &lt;CODE&gt;main&lt;/CODE&gt;
+ 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.
+ &lt;br&gt;&lt;br&gt; The environment for the new process image is taken from the
+ &lt;CODE&gt;environ&lt;/CODE&gt; variable of the current process image; see
+ Environment Variables, for information about environments.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-execl" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *filename"/>
+ <parameter content="const char *arg0"/>
+ <parameter content="..."/>
+ </prototype>
+ <headers>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ This is similar to &lt;CODE&gt;execv&lt;/CODE&gt;, but the &lt;VAR&gt;argv&lt;/VAR&gt; strings are
+ specified individually instead of as an array. A null pointer must be
+ passed as the last such argument.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-execve" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *filename"/>
+ <parameter content="char *const argv[]"/>
+ <parameter content="char *const env[]"/>
+ </prototype>
+ <headers>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ This is similar to &lt;CODE&gt;execv&lt;/CODE&gt;, but permits you to specify the environment
+ for the new program explicitly as the &lt;VAR&gt;env&lt;/VAR&gt; argument. This should
+ be an array of strings in the same format as for the &lt;CODE&gt;environ&lt;/CODE&gt;
+ variable; see Environment Access.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-execle" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *filename"/>
+ <parameter content="const char *arg0"/>
+ <parameter content="char *const env[]"/>
+ <parameter content="..."/>
+ </prototype>
+ <headers>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ This is similar to &lt;CODE&gt;execl&lt;/CODE&gt;, 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 &lt;VAR&gt;argv&lt;/VAR&gt;
+ argument, and should be an array of strings in the same format as for
+ the &lt;CODE&gt;environ&lt;/CODE&gt; variable.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-execvp" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *filename"/>
+ <parameter content="char *const argv[]"/>
+ </prototype>
+ <headers>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;execvp&lt;/CODE&gt; function is similar to &lt;CODE&gt;execv&lt;/CODE&gt;, except that it
+ searches the directories listed in the &lt;CODE&gt;PATH&lt;/CODE&gt; environment variable
+ to find the full file name of a
+ file from &lt;VAR&gt;filename&lt;/VAR&gt; if &lt;VAR&gt;filename&lt;/VAR&gt; does not contain a slash.
+ &lt;br&gt;&lt;br&gt; 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.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-execlp" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *filename"/>
+ <parameter content="const char *arg0"/>
+ <parameter content="..."/>
+ </prototype>
+ <headers>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ This function is like &lt;CODE&gt;execl&lt;/CODE&gt;, except that it performs the same
+ file name searching as the &lt;CODE&gt;execvp&lt;/CODE&gt; function.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-waitpid" type="function">
+ <function returntype="pid_t">
+ <prototype>
+ <parameter content="pid_t pid"/>
+ <parameter content="int *status-ptr"/>
+ <parameter content="int options"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/wait.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;waitpid&lt;/CODE&gt; function is used to request status information from a
+ child process whose process ID is &lt;VAR&gt;pid&lt;/VAR&gt;. Normally, the calling
+ process is suspended until the child process makes status information
+ available by terminating.
+ &lt;br&gt;&lt;br&gt; Other values for the &lt;VAR&gt;pid&lt;/VAR&gt; argument have special interpretations. A
+ value of &lt;CODE&gt;-1&lt;/CODE&gt; or &lt;CODE&gt;WAIT_ANY&lt;/CODE&gt; requests status information for
+ any child process; a value of &lt;CODE&gt;0&lt;/CODE&gt; or &lt;CODE&gt;WAIT_MYPGRP&lt;/CODE&gt; requests
+ information for any child process in the same process group as the
+ calling process; and any other negative value &lt;VAR&gt;pgid&lt;/VAR&gt;
+ requests information for any child process whose process group ID is
+ &lt;VAR&gt;pgid&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; 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 &lt;CODE&gt;waitpid&lt;/CODE&gt;
+ again.
+ &lt;br&gt;&lt;br&gt; The &lt;VAR&gt;options&lt;/VAR&gt; argument is a bit mask. Its value should be the
+ bitwise OR (that is, the &lt;samp&gt;|&lt;/samp&gt; operator) of zero or more of the
+ &lt;CODE&gt;WNOHANG&lt;/CODE&gt; and &lt;CODE&gt;WUNTRACED&lt;/CODE&gt; flags. You can use the
+ &lt;CODE&gt;WNOHANG&lt;/CODE&gt; flag to indicate that the parent process shouldn't wait;
+ and the &lt;CODE&gt;WUNTRACED&lt;/CODE&gt; flag to request status information from stopped
+ processes as well as processes that have terminated.
+ &lt;br&gt;&lt;br&gt; The status information from the child process is stored in the object
+ that &lt;VAR&gt;status-ptr&lt;/VAR&gt; points to, unless &lt;VAR&gt;status-ptr&lt;/VAR&gt; is a null pointer.
+ &lt;br&gt;&lt;br&gt; 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 &lt;CODE&gt;waitpid&lt;/CODE&gt; is
+ called. If the thread gets canceled these resources stay allocated
+ until the program ends. To avoid this calls to &lt;CODE&gt;waitpid&lt;/CODE&gt; should be
+ protected using cancellation handlers.
+ &lt;br&gt;&lt;br&gt; 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, &lt;CODE&gt;waitpid&lt;/CODE&gt; will block until one is. However,
+ if the &lt;CODE&gt;WNOHANG&lt;/CODE&gt; option was specified, &lt;CODE&gt;waitpid&lt;/CODE&gt; will return
+ zero instead of blocking.
+ &lt;br&gt;&lt;br&gt; If a specific PID to wait for was given to &lt;CODE&gt;waitpid&lt;/CODE&gt;, 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, &lt;CODE&gt;waitpid&lt;/CODE&gt; will block or return zero as described above.
+ &lt;br&gt;&lt;br&gt; A value of &lt;CODE&gt;-1&lt;/CODE&gt; is returned in case of error. The following
+ &lt;CODE&gt;errno&lt;/CODE&gt; error conditions are defined for this function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EINTR&lt;/CODE&gt;
+&lt;DD&gt;
+ The function was interrupted by delivery of a signal to the calling
+ process. .
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ECHILD
+ There are no child processes to wait for, or the specified &lt;VAR&gt;pid&lt;/VAR&gt;
+ is not a child of the calling process.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EINVAL
+ An invalid value was provided for the &lt;VAR&gt;options&lt;/VAR&gt; argument.
+
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-wait" type="function">
+ <function returntype="pid_t">
+ <prototype>
+ <parameter content="int *status-ptr"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/wait.h"/>
+ </headers>
+ <synopsis>
+ This is a simplified version of &lt;CODE&gt;waitpid&lt;/CODE&gt;, and is used to wait
+ until any one child process terminates. The call:
+ &lt;br&gt;&lt;br&gt; &lt;pre&gt;&lt;br&gt;
+ wait (&amp;status)&lt;br&gt;
+ &lt;/pre&gt;&lt;br&gt;
+ &lt;br&gt;&lt;br&gt; &lt;br&gt;
+ is exactly equivalent to:&lt;br&gt;
+ &lt;br&gt;&lt;br&gt; &lt;pre&gt;&lt;br&gt;
+ waitpid (-1, &amp;status, 0)&lt;br&gt;
+ &lt;/pre&gt;
+ &lt;br&gt;&lt;br&gt; 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 &lt;CODE&gt;wait&lt;/CODE&gt; is
+ called. If the thread gets canceled these resources stay allocated
+ until the program ends. To avoid this calls to &lt;CODE&gt;wait&lt;/CODE&gt; should be
+ protected using cancellation handlers.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-wait4" type="function">
+ <function returntype="pid_t">
+ <prototype>
+ <parameter content="pid_t pid"/>
+ <parameter content="int *status-ptr"/>
+ <parameter content="int options"/>
+ <parameter content="struct rusage *usage"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/wait.h"/>
+ </headers>
+ <synopsis>
+ If &lt;VAR&gt;usage&lt;/VAR&gt; is a null pointer, &lt;CODE&gt;wait4&lt;/CODE&gt; is equivalent to
+ &lt;CODE&gt;waitpid (&lt;VAR&gt;pid&lt;/VAR&gt;, &lt;VAR&gt;status-ptr&lt;/VAR&gt;, &lt;VAR&gt;options&lt;/VAR&gt;)&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; If &lt;VAR&gt;usage&lt;/VAR&gt; is not null, &lt;CODE&gt;wait4&lt;/CODE&gt; stores usage figures for the
+ child process in &lt;CODE&gt;*&lt;VAR&gt;rusage&lt;/VAR&gt;&lt;/CODE&gt; (but only if the child has
+ terminated, not if it has stopped). .
+ &lt;br&gt;&lt;br&gt; This function is a BSD extension.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="union-wait" type="union">
+ <structure>
+ <synopsis>
+ This data type represents program termination status values. It has
+ the following members:
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ <elements>
+ <element content="int w_termsig">
+ <synopsis>
+ The value of this member is the same as that of the
+ &lt;CODE&gt;WTERMSIG&lt;/CODE&gt; macro.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="int w_coredump">
+ <synopsis>
+ The value of this member is the same as that of the
+ &lt;CODE&gt;WCOREDUMP&lt;/CODE&gt; macro.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="int w_retcode">
+ <synopsis>
+ The value of this member is the same as that of the
+ &lt;CODE&gt;WEXITSTATUS&lt;/CODE&gt; macro.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ </elements>
+ </structure>
+ </construct>
+ <construct id="function-wait3" type="function">
+ <function returntype="pid_t">
+ <prototype>
+ <parameter content="union wait *status-ptr"/>
+ <parameter content="int options"/>
+ <parameter content="struct rusage *usage"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/wait.h"/>
+ </headers>
+ <synopsis>
+ If &lt;VAR&gt;usage&lt;/VAR&gt; is a null pointer, &lt;CODE&gt;wait3&lt;/CODE&gt; is equivalent to
+ &lt;CODE&gt;waitpid (-1, &lt;VAR&gt;status-ptr&lt;/VAR&gt;, &lt;VAR&gt;options&lt;/VAR&gt;)&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; If &lt;VAR&gt;usage&lt;/VAR&gt; is not null, &lt;CODE&gt;wait3&lt;/CODE&gt; stores usage figures for the
+ child process in &lt;CODE&gt;*&lt;VAR&gt;rusage&lt;/VAR&gt;&lt;/CODE&gt; (but only if the child has
+ terminated, not if it has stopped). .
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-getcwd" type="function">
+ <function returntype="char *">
+ <prototype>
+ <parameter content="char *buffer"/>
+ <parameter content="size_t size"/>
+ </prototype>
+ <headers>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;getcwd&lt;/CODE&gt; function returns an absolute file name representing
+ the current working directory, storing it in the character array
+ &lt;VAR&gt;buffer&lt;/VAR&gt; that you provide. The &lt;VAR&gt;size&lt;/VAR&gt; argument is how you tell
+ the system the allocation size of &lt;VAR&gt;buffer&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; The GNU library version of this function also permits you to specify a
+ null pointer for the &lt;VAR&gt;buffer&lt;/VAR&gt; argument. Then &lt;CODE&gt;getcwd&lt;/CODE&gt;
+ allocates a buffer automatically, as with &lt;CODE&gt;malloc&lt;/CODE&gt;
+ . If the &lt;VAR&gt;size&lt;/VAR&gt; is greater than
+ zero, then the buffer is that large; otherwise, the buffer is as large
+ as necessary to hold the result.
+ &lt;br&gt;&lt;br&gt; The return value is &lt;VAR&gt;buffer&lt;/VAR&gt; on success and a null pointer on failure.
+ The following &lt;CODE&gt;errno&lt;/CODE&gt; error conditions are defined for this function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EINVAL&lt;/CODE&gt;
+&lt;DD&gt;
+ The &lt;VAR&gt;size&lt;/VAR&gt; argument is zero and &lt;VAR&gt;buffer&lt;/VAR&gt; is not a null pointer.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ERANGE
+ The &lt;VAR&gt;size&lt;/VAR&gt; argument is less than the length of the working directory
+ name. You need to allocate a bigger array and try again.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EACCES
+ Permission to read or search a component of the file name was denied.
+
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-get_current_dir_name" type="function">
+ <function returntype="char *">
+ <prototype>
+ <parameter content="void"/>
+ </prototype>
+ <headers>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+
+ This &lt;CODE&gt;get_current_dir_name&lt;/CODE&gt; function is basically equivalent to
+ &lt;CODE&gt;getcwd (NULL, 0)&lt;/CODE&gt;. The only difference is that the value of
+ the &lt;CODE&gt;PWD&lt;/CODE&gt; variable is returned if this value is correct. This is a
+ subtle difference which is visible if the path described by the
+ &lt;CODE&gt;PWD&lt;/CODE&gt; value is using one or more symbol links in which case the
+ value returned by &lt;CODE&gt;getcwd&lt;/CODE&gt; can resolve the symbol links and
+ therefore yield a different result.
+ &lt;br&gt;&lt;br&gt; This function is a GNU extension.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-chdir" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *filename"/>
+ </prototype>
+ <headers>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ This function is used to set the process's working directory to
+ &lt;VAR&gt;filename&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; The normal, successful return value from &lt;CODE&gt;chdir&lt;/CODE&gt; is &lt;CODE&gt;0&lt;/CODE&gt;. A
+ value of &lt;CODE&gt;-1&lt;/CODE&gt; is returned to indicate an error. The &lt;CODE&gt;errno&lt;/CODE&gt;
+ error conditions defined for this function are the usual file name
+ syntax errors , plus &lt;CODE&gt;ENOTDIR&lt;/CODE&gt; if the
+ file &lt;VAR&gt;filename&lt;/VAR&gt; is not a directory.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-fchdir" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="int filedes"/>
+ </prototype>
+ <headers>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ This function is used to set the process's working directory to
+ directory associated with the file descriptor &lt;VAR&gt;filedes&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; The normal, successful return value from &lt;CODE&gt;fchdir&lt;/CODE&gt; is &lt;CODE&gt;0&lt;/CODE&gt;. A
+ value of &lt;CODE&gt;-1&lt;/CODE&gt; is returned to indicate an error. The following
+ &lt;CODE&gt;errno&lt;/CODE&gt; error conditions are defined for this function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EACCES&lt;/CODE&gt;
+&lt;DD&gt;
+ Read permission is denied for the directory named by &lt;CODE&gt;dirname&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EBADF
+ The &lt;VAR&gt;filedes&lt;/VAR&gt; argument is not a valid file descriptor.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ENOTDIR
+ The file descriptor &lt;VAR&gt;filedes&lt;/VAR&gt; is not associated with a directory.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EINTR
+ The function call was interrupt by a signal.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EIO
+ An I/O error occurred.
+
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="struct-dirent" type="struct">
+ <structure>
+ <synopsis>
+ This is a structure type used to return information about directory
+ entries. It contains the following fields:
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ <elements>
+ <element content="char d_name[]">
+ <synopsis>
+ This is the null-terminated file name component. This is the only
+ field you can count on in all POSIX systems.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="ino_t d_fileno">
+ <synopsis>
+ This is the file serial number. For BSD compatibility, you can also
+ refer to this member as &lt;CODE&gt;d_ino&lt;/CODE&gt;. In the GNU system and most POSIX
+ systems, for most files this the same as the &lt;CODE&gt;st_ino&lt;/CODE&gt; member that
+ &lt;CODE&gt;stat&lt;/CODE&gt; will return for the file. .
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="unsigned char d_namlen">
+ <synopsis>
+ This is the length of the file name, not including the terminating null
+ character. Its type is &lt;CODE&gt;unsigned char&lt;/CODE&gt; because that is the integer
+ type of the appropriate size
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="unsigned char d_type">
+ <synopsis>
+ This is the type of the file, possibly unknown. The following constants
+ are defined for its value:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ </synopsis>
+ </element>
+ <element content="DT_UNKNOWN">
+ <synopsis>
+ The type is unknown. On some systems this is the only value returned.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="DT_REG">
+ <synopsis>
+ A regular file.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="DT_DIR">
+ <synopsis>
+ A directory.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="DT_FIFO">
+ <synopsis>
+ A named pipe, or FIFO. .
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="DT_SOCK">
+ <synopsis>
+ A local-domain socket.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="DT_CHR">
+ <synopsis>
+ A character device.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ </elements>
+ </structure>
+ </construct>
+ <construct id="dtype-DIR" type="dtype">
+ <structure>
+ </structure>
+ </construct>
+ <construct id="function-opendir" type="function">
+ <function returntype="DIR *">
+ <prototype>
+ <parameter content="const char *dirname"/>
+ </prototype>
+ <headers>
+ <header filename = "dirent.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;opendir&lt;/CODE&gt; function opens and returns a directory stream for
+ reading the directory whose file name is &lt;VAR&gt;dirname&lt;/VAR&gt;. The stream has
+ type &lt;CODE&gt;DIR *&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; If unsuccessful, &lt;CODE&gt;opendir&lt;/CODE&gt; returns a null pointer. In addition to
+ the usual file name errors , the
+ following &lt;CODE&gt;errno&lt;/CODE&gt; error conditions are defined for this function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EACCES&lt;/CODE&gt;
+&lt;DD&gt;
+ Read permission is denied for the directory named by &lt;CODE&gt;dirname&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EMFILE
+ The process has too many files open.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; 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.)
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ENOMEM
+ Not enough memory available.
+
+ &lt;br&gt;&lt;br&gt; The &lt;CODE&gt;DIR&lt;/CODE&gt; type is typically implemented using a file descriptor,
+ and the &lt;CODE&gt;opendir&lt;/CODE&gt; function in terms of the &lt;CODE&gt;open&lt;/CODE&gt; function.
+ . Directory streams and the underlying
+ file descriptors are closed on &lt;CODE&gt;exec&lt;/CODE&gt; .
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-fdopendir" type="function">
+ <function returntype="DIR *">
+ <prototype>
+ <parameter content="int fd"/>
+ </prototype>
+ <headers>
+ <header filename = "dirent.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;fdopendir&lt;/CODE&gt; function works just like &lt;CODE&gt;opendir&lt;/CODE&gt; 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.
+ &lt;br&gt;&lt;br&gt; The caller must make sure the file descriptor is associated with a
+ directory and it allows reading.
+ &lt;br&gt;&lt;br&gt; If the &lt;CODE&gt;fdopendir&lt;/CODE&gt; 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 &lt;CODE&gt;opendir&lt;/CODE&gt; can be used
+ but the program must not close the descriptor.
+ &lt;br&gt;&lt;br&gt; In case the function is unsuccessful it returns a null pointer and the
+ file descriptor remains to be usable by the program. The following
+ &lt;CODE&gt;errno&lt;/CODE&gt; error conditions are defined for this function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EBADF&lt;/CODE&gt;
+&lt;DD&gt;
+ The file descriptor is not valid.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ENOTDIR
+ The file descriptor is not associated with a directory.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EINVAL
+ The descriptor does not allow reading the directory content.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ENOMEM
+ Not enough memory available.
+
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-dirfd" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="DIR *dirstream"/>
+ </prototype>
+ <headers>
+ <header filename = "dirent.h"/>
+ </headers>
+ <synopsis>
+ The function &lt;CODE&gt;dirfd&lt;/CODE&gt; returns the file descriptor associated with
+ the directory stream &lt;VAR&gt;dirstream&lt;/VAR&gt;. This descriptor can be used until
+ the directory is closed with &lt;CODE&gt;closedir&lt;/CODE&gt;. If the directory stream
+ implementation is not using file descriptors the return value is
+ &lt;CODE&gt;-1&lt;/CODE&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-readdir" type="function">
+ <function returntype="struct dirent *">
+ <prototype>
+ <parameter content="DIR *dirstream"/>
+ </prototype>
+ <headers>
+ <header filename = "dirent.h"/>
+ </headers>
+ <synopsis>
+ 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.
+ &lt;br&gt;&lt;br&gt; Portability Note: On some systems &lt;CODE&gt;readdir&lt;/CODE&gt; may not
+ return entries for &lt;TT&gt;.&lt;/TT&gt; and &lt;TT&gt;..&lt;/TT&gt;, even though these are always
+ valid file names in any directory. .
+ &lt;br&gt;&lt;br&gt; If there are no more entries in the directory or an error is detected,
+ &lt;CODE&gt;readdir&lt;/CODE&gt; returns a null pointer. The following &lt;CODE&gt;errno&lt;/CODE&gt; error
+ conditions are defined for this function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EBADF&lt;/CODE&gt;
+&lt;DD&gt;
+ The &lt;VAR&gt;dirstream&lt;/VAR&gt; argument is not valid.
+
+ &lt;br&gt;&lt;br&gt; &lt;CODE&gt;readdir&lt;/CODE&gt; is not thread safe. Multiple threads using
+ &lt;CODE&gt;readdir&lt;/CODE&gt; on the same &lt;VAR&gt;dirstream&lt;/VAR&gt; may overwrite the return
+ value. Use &lt;CODE&gt;readdir_r&lt;/CODE&gt; when this is critical.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-readdir_r" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="DIR *dirstream"/>
+ <parameter content="struct dirent *entry"/>
+ <parameter content="struct dirent **result"/>
+ </prototype>
+ <headers>
+ <header filename = "dirent.h"/>
+ </headers>
+ <synopsis>
+ This function is the reentrant version of &lt;CODE&gt;readdir&lt;/CODE&gt;. Like
+ &lt;CODE&gt;readdir&lt;/CODE&gt; 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
+ &lt;VAR&gt;entry&lt;/VAR&gt; points to a place to store the result.
+ &lt;br&gt;&lt;br&gt; Normally &lt;CODE&gt;readdir_r&lt;/CODE&gt; returns zero and sets &lt;CODE&gt;*&lt;VAR&gt;result&lt;/VAR&gt;&lt;/CODE&gt;
+ to &lt;VAR&gt;entry&lt;/VAR&gt;. If there are no more entries in the directory or an
+ error is detected, &lt;CODE&gt;readdir_r&lt;/CODE&gt; sets &lt;CODE&gt;*&lt;VAR&gt;result&lt;/VAR&gt;&lt;/CODE&gt; to a
+ null pointer and returns a nonzero error code, also stored in
+ &lt;CODE&gt;errno&lt;/CODE&gt;, as described for &lt;CODE&gt;readdir&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; Portability Note: On some systems &lt;CODE&gt;readdir_r&lt;/CODE&gt; may not
+ return a NUL terminated string for the file name, even when there is no
+ &lt;CODE&gt;d_reclen&lt;/CODE&gt; field in &lt;CODE&gt;struct dirent&lt;/CODE&gt; and the file
+ name is the maximum allowed size. Modern systems all have the
+ &lt;CODE&gt;d_reclen&lt;/CODE&gt; field, and on old systems multi-threading is not
+ critical. In any case there is no such problem with the &lt;CODE&gt;readdir&lt;/CODE&gt;
+ function, so that even on systems without the &lt;CODE&gt;d_reclen&lt;/CODE&gt; member one
+ could use multiple threads by using external locking.
+ &lt;br&gt;&lt;br&gt; It is also important to look at the definition of the &lt;CODE&gt;struct
+ dirent&lt;/CODE&gt; type. Simply passing a pointer to an object of this type for
+ the second parameter of &lt;CODE&gt;readdir_r&lt;/CODE&gt; might not be enough. Some
+ systems don't define the &lt;CODE&gt;d_name&lt;/CODE&gt; element sufficiently long. In
+ this case the user has to provide additional space. There must be room
+ for at least &lt;CODE&gt;NAME_MAX + 1&lt;/CODE&gt; characters in the &lt;CODE&gt;d_name&lt;/CODE&gt; array.
+ Code to call &lt;CODE&gt;readdir_r&lt;/CODE&gt; could look like this:
+ &lt;br&gt;&lt;br&gt; &lt;pre&gt;&lt;br&gt;
+ union&lt;br&gt;
+ {&lt;br&gt;
+ struct dirent d;&lt;br&gt;
+ char b[offsetof (struct dirent, d_name) + NAME_MAX + 1];&lt;br&gt;
+ } u;&lt;br&gt;
+ &lt;br&gt;&lt;br&gt; if (readdir_r (dir, &amp;u.d, &amp;res) == 0)&lt;br&gt;
+ &lt;small&gt;...&lt;/small&gt;&lt;br&gt;
+ &lt;/pre&gt;
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-readdir64" type="function">
+ <function returntype="struct dirent64 *">
+ <prototype>
+ <parameter content="DIR *dirstream"/>
+ </prototype>
+ <headers>
+ <header filename = "dirent.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;readdir64&lt;/CODE&gt; function is just like the &lt;CODE&gt;readdir&lt;/CODE&gt; function
+ except that it returns a pointer to a record of type &lt;CODE&gt;struct
+ dirent64&lt;/CODE&gt;. Some of the members of this data type (notably &lt;CODE&gt;d_ino&lt;/CODE&gt;)
+ might have a different size to allow large filesystems.
+ &lt;br&gt;&lt;br&gt; In all other aspects this function is equivalent to &lt;CODE&gt;readdir&lt;/CODE&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-readdir64_r" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="DIR *dirstream"/>
+ <parameter content="struct dirent64 *entry"/>
+ <parameter content="struct dirent64 **result"/>
+ </prototype>
+ <headers>
+ <header filename = "dirent.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;readdir64_r&lt;/CODE&gt; function is equivalent to the &lt;CODE&gt;readdir_r&lt;/CODE&gt;
+ function except that it takes parameters of base type &lt;CODE&gt;struct
+ dirent64&lt;/CODE&gt; instead of &lt;CODE&gt;struct dirent&lt;/CODE&gt; in the second and third
+ position. The same precautions mentioned in the documentation of
+ &lt;CODE&gt;readdir_r&lt;/CODE&gt; also apply here.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-closedir" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="DIR *dirstream"/>
+ </prototype>
+ <headers>
+ <header filename = "dirent.h"/>
+ </headers>
+ <synopsis>
+ This function closes the directory stream &lt;VAR&gt;dirstream&lt;/VAR&gt;. It returns
+ &lt;CODE&gt;0&lt;/CODE&gt; on success and &lt;CODE&gt;-1&lt;/CODE&gt; on failure.
+ &lt;br&gt;&lt;br&gt; The following &lt;CODE&gt;errno&lt;/CODE&gt; error conditions are defined for this
+ function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EBADF&lt;/CODE&gt;
+&lt;DD&gt;
+ The &lt;VAR&gt;dirstream&lt;/VAR&gt; argument is not valid.
+
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-rewinddir" type="function">
+ <function returntype="void">
+ <prototype>
+ <parameter content="DIR *dirstream"/>
+ </prototype>
+ <headers>
+ <header filename = "dirent.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;rewinddir&lt;/CODE&gt; function is used to reinitialize the directory
+ stream &lt;VAR&gt;dirstream&lt;/VAR&gt;, so that if you call &lt;CODE&gt;readdir&lt;/CODE&gt; 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 &lt;CODE&gt;opendir&lt;/CODE&gt;. (Entries for these
+ files might or might not be returned by &lt;CODE&gt;readdir&lt;/CODE&gt; if they were
+ added or removed since you last called &lt;CODE&gt;opendir&lt;/CODE&gt; or
+ &lt;CODE&gt;rewinddir&lt;/CODE&gt;.)
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-seekdir" type="function">
+ <function returntype="void">
+ <prototype>
+ <parameter content="DIR *dirstream"/>
+ <parameter content="long int pos"/>
+ </prototype>
+ <headers>
+ <header filename = "dirent.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;seekdir&lt;/CODE&gt; function sets the file position of the directory
+ stream &lt;VAR&gt;dirstream&lt;/VAR&gt; to &lt;VAR&gt;pos&lt;/VAR&gt;. The value &lt;VAR&gt;pos&lt;/VAR&gt; must be the
+ result of a previous call to &lt;CODE&gt;telldir&lt;/CODE&gt; on this particular stream;
+ closing and reopening the directory can invalidate values returned by
+ &lt;CODE&gt;telldir&lt;/CODE&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-scandir" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *dir"/>
+ <parameter content="struct dirent ***namelist"/>
+ <parameter content="int (*selector) (const struct dirent *)"/>
+ <parameter content="int (*cmp) (const void *"/>
+ <parameter content="const void *)"/>
+ </prototype>
+ <headers>
+ <header filename = "dirent.h"/>
+ </headers>
+ <synopsis>
+ &lt;br&gt;&lt;br&gt; The &lt;CODE&gt;scandir&lt;/CODE&gt; function scans the contents of the directory selected
+ by &lt;VAR&gt;dir&lt;/VAR&gt;. The result in *&lt;VAR&gt;namelist&lt;/VAR&gt; is an array of pointers to
+ structure of type &lt;CODE&gt;struct dirent&lt;/CODE&gt; which describe all selected
+ directory entries and which is allocated using &lt;CODE&gt;malloc&lt;/CODE&gt;. Instead
+ of always getting all directory entries returned, the user supplied
+ function &lt;VAR&gt;selector&lt;/VAR&gt; can be used to decide which entries are in the
+ result. Only the entries for which &lt;VAR&gt;selector&lt;/VAR&gt; returns a non-zero
+ value are selected.
+ &lt;br&gt;&lt;br&gt; Finally the entries in *&lt;VAR&gt;namelist&lt;/VAR&gt; are sorted using the
+ user-supplied function &lt;VAR&gt;cmp&lt;/VAR&gt;. The arguments passed to the &lt;VAR&gt;cmp&lt;/VAR&gt;
+ function are of type &lt;CODE&gt;struct dirent **&lt;/CODE&gt;, therefore one cannot
+ directly use the &lt;CODE&gt;strcmp&lt;/CODE&gt; or &lt;CODE&gt;strcoll&lt;/CODE&gt; functions; instead see
+ the functions &lt;CODE&gt;alphasort&lt;/CODE&gt; and &lt;CODE&gt;versionsort&lt;/CODE&gt; below.
+ &lt;br&gt;&lt;br&gt; The return value of the function is the number of entries placed in
+ *&lt;VAR&gt;namelist&lt;/VAR&gt;. If it is &lt;CODE&gt;-1&lt;/CODE&gt; an error occurred (either the
+ directory could not be opened for reading or the malloc call failed) and
+ the global variable &lt;CODE&gt;errno&lt;/CODE&gt; contains more information on the error.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-alphasort" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const void *a"/>
+ <parameter content="const void *b"/>
+ </prototype>
+ <headers>
+ <header filename = "dirent.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;alphasort&lt;/CODE&gt; function behaves like the &lt;CODE&gt;strcoll&lt;/CODE&gt; function
+ . The difference is that the arguments
+ are not string pointers but instead they are of type
+ &lt;CODE&gt;struct dirent **&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; The return value of &lt;CODE&gt;alphasort&lt;/CODE&gt; is less than, equal to, or greater
+ than zero depending on the order of the two entries &lt;VAR&gt;a&lt;/VAR&gt; and &lt;VAR&gt;b&lt;/VAR&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-versionsort" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const void *a"/>
+ <parameter content="const void *b"/>
+ </prototype>
+ <headers>
+ <header filename = "dirent.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;versionsort&lt;/CODE&gt; function is like &lt;CODE&gt;alphasort&lt;/CODE&gt; except that it
+ uses the &lt;CODE&gt;strverscmp&lt;/CODE&gt; function internally.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-scandir64" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *dir"/>
+ <parameter content="struct dirent64 ***namelist"/>
+ <parameter content="int (*selector) (const struct dirent64 *)"/>
+ <parameter content="int (*cmp) (const void *"/>
+ <parameter content="const void *)"/>
+ </prototype>
+ <headers>
+ <header filename = "dirent.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;scandir64&lt;/CODE&gt; function works like the &lt;CODE&gt;scandir&lt;/CODE&gt; function
+ except that the directory entries it returns are described by elements
+ of type &lt;CODE&gt;struct dirent64&lt;/CODE&gt;. The function pointed to by
+ &lt;VAR&gt;selector&lt;/VAR&gt; is again used to select the desired entries, except that
+ &lt;VAR&gt;selector&lt;/VAR&gt; now must point to a function which takes a
+ &lt;CODE&gt;struct dirent64 *&lt;/CODE&gt; parameter.
+ &lt;br&gt;&lt;br&gt; Similarly the &lt;VAR&gt;cmp&lt;/VAR&gt; function should expect its two arguments to be
+ of type &lt;CODE&gt;struct dirent64 **&lt;/CODE&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-alphasort64" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const void *a"/>
+ <parameter content="const void *b"/>
+ </prototype>
+ <headers>
+ <header filename = "dirent.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;alphasort64&lt;/CODE&gt; function behaves like the &lt;CODE&gt;strcoll&lt;/CODE&gt; function
+ . The difference is that the arguments
+ are not string pointers but instead they are of type
+ &lt;CODE&gt;struct dirent64 **&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; Return value of &lt;CODE&gt;alphasort64&lt;/CODE&gt; is less than, equal to, or greater
+ than zero depending on the order of the two entries &lt;VAR&gt;a&lt;/VAR&gt; and &lt;VAR&gt;b&lt;/VAR&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-versionsort64" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const void *a"/>
+ <parameter content="const void *b"/>
+ </prototype>
+ <headers>
+ <header filename = "dirent.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;versionsort64&lt;/CODE&gt; function is like &lt;CODE&gt;alphasort64&lt;/CODE&gt;, excepted that it
+ uses the &lt;CODE&gt;strverscmp&lt;/CODE&gt; function internally.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="dtype-__ftw_func_t" type="dtype">
+ <structure>
+ <synopsis>
+ &lt;br&gt;&lt;br&gt; &lt;pre&gt;&lt;br&gt;
+ int (*) (const char *, const struct stat *, int)&lt;br&gt;
+ &lt;/pre&gt;
+ &lt;br&gt;&lt;br&gt; The type of callback functions given to the &lt;CODE&gt;ftw&lt;/CODE&gt; function. The
+ first parameter points to the file name, the second parameter to an
+ object of type &lt;CODE&gt;struct stat&lt;/CODE&gt; which is filled in for the file named
+ in the first parameter.
+ &lt;br&gt;&lt;br&gt;
+ The last parameter is a flag giving more information about the current
+ file. It can have the following values:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ </synopsis>
+ <elements>
+ <element content="FTW_F">
+ <synopsis>
+ The item is either a normal file or a file which does not fit into one
+ of the following categories. This could be special files, sockets etc.
+ </synopsis>
+ </element>
+ <element content="FTW_D">
+ <synopsis>
+ The item is a directory.
+ </synopsis>
+ </element>
+ <element content="FTW_NS">
+ <synopsis>
+ The &lt;CODE&gt;stat&lt;/CODE&gt; call failed and so the information pointed to by the
+ second paramater is invalid.
+ </synopsis>
+ </element>
+ <element content="FTW_DNR">
+ <synopsis>
+ The item is a directory which cannot be read.
+ </synopsis>
+ </element>
+ </elements>
+ </structure>
+ </construct>
+ <construct id="dtype-__ftw64_func_t" type="dtype">
+ <structure>
+ </structure>
+ </construct>
+ <construct id="dtype-__nftw_func_t" type="dtype">
+ <structure>
+ <synopsis>
+ &lt;br&gt;&lt;br&gt; &lt;pre&gt;&lt;br&gt;
+ int (*) (const char *, const struct stat *, int, struct FTW *)&lt;br&gt;
+ &lt;/pre&gt;
+ &lt;br&gt;&lt;br&gt;
+
+ The first three arguments are the same as for the &lt;CODE&gt;__ftw_func_t&lt;/CODE&gt;
+ type. However for the third argument some additional values are defined
+ to allow finer differentiation:
+ </synopsis>
+ <elements>
+ <element content="FTW_DP">
+ <synopsis>
+ The current item is a directory and all subdirectories have already been
+ visited and reported. This flag is returned instead of &lt;CODE&gt;FTW_D&lt;/CODE&gt; if
+ the &lt;CODE&gt;FTW_DEPTH&lt;/CODE&gt; flag is passed to &lt;CODE&gt;nftw&lt;/CODE&gt; (see below).
+ </synopsis>
+ </element>
+ </elements>
+ </structure>
+ </construct>
+ <construct id="dtype-__nftw64_func_t" type="dtype">
+ <structure>
+ </structure>
+ </construct>
+ <construct id="struct-FTW" type="struct">
+ <structure>
+ <synopsis>
+ The information contained in this structure helps in interpreting the
+ name parameter and gives some information about the current state of the
+ traversal of the directory hierarchy.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ <elements>
+ <element content="int base">
+ <synopsis>
+ The value is the offset into the string passed in the first parameter to
+ the callback function of the beginning of the file name. The rest of
+ the string is the path of the file. This information is especially
+ important if the &lt;CODE&gt;FTW_CHDIR&lt;/CODE&gt; flag was set in calling &lt;CODE&gt;nftw&lt;/CODE&gt;
+ since then the current directory is the one the current item is found
+ in.
+ </synopsis>
+ </element>
+ </elements>
+ </structure>
+ </construct>
+ <construct id="function-ftw" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *filename"/>
+ <parameter content="__ftw_func_t func"/>
+ <parameter content="int descriptors"/>
+ </prototype>
+ <headers>
+ <header filename = "ftw.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;ftw&lt;/CODE&gt; function calls the callback function given in the
+ parameter &lt;VAR&gt;func&lt;/VAR&gt; for every item which is found in the directory
+ specified by &lt;VAR&gt;filename&lt;/VAR&gt; and all directories below. The function
+ follows symbolic links if necessary but does not process an item twice.
+ If &lt;VAR&gt;filename&lt;/VAR&gt; is not a directory then it itself is the only object
+ returned to the callback function.
+ &lt;br&gt;&lt;br&gt; The file name passed to the callback function is constructed by taking
+ the &lt;VAR&gt;filename&lt;/VAR&gt; 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. &lt;CODE&gt;ftw&lt;/CODE&gt; also calls
+ &lt;CODE&gt;stat&lt;/CODE&gt; for the file and passes that information on to the callback
+ function. If this &lt;CODE&gt;stat&lt;/CODE&gt; call was not successful the failure is
+ indicated by setting the third argument of the callback function to
+ &lt;CODE&gt;FTW_NS&lt;/CODE&gt;. Otherwise it is set according to the description given
+ in the account of &lt;CODE&gt;__ftw_func_t&lt;/CODE&gt; above.
+ &lt;br&gt;&lt;br&gt; 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 &lt;CODE&gt;ftw&lt;/CODE&gt; 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 &lt;CODE&gt;setjmp&lt;/CODE&gt; or similar techniques to continue
+ from another place. This would leave resources allocated by the
+ &lt;CODE&gt;ftw&lt;/CODE&gt; function unfreed.
+ &lt;br&gt;&lt;br&gt; The &lt;VAR&gt;descriptors&lt;/VAR&gt; parameter to &lt;CODE&gt;ftw&lt;/CODE&gt; 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.
+ &lt;br&gt;&lt;br&gt; The return value of the &lt;CODE&gt;ftw&lt;/CODE&gt; function is 0 if all callback
+ function calls returned 0 and all actions performed by the
+ &lt;CODE&gt;ftw&lt;/CODE&gt; succeeded. If a function call failed (other than calling
+ &lt;CODE&gt;stat&lt;/CODE&gt; 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 &lt;CODE&gt;ftw&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; When the sources are compiled with &lt;CODE&gt;_FILE_OFFSET_BITS == 64&lt;/CODE&gt; on a
+ 32-bit system this function is in fact &lt;CODE&gt;ftw64&lt;/CODE&gt;, i.e., the LFS
+ interface transparently replaces the old interface.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-ftw64" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *filename"/>
+ <parameter content="__ftw64_func_t func"/>
+ <parameter content="int descriptors"/>
+ </prototype>
+ <headers>
+ <header filename = "ftw.h"/>
+ </headers>
+ <synopsis>
+ This function is similar to &lt;CODE&gt;ftw&lt;/CODE&gt; but it can work on filesystems
+ with large files. File information is reported using a variable of type
+ &lt;CODE&gt;struct stat64&lt;/CODE&gt; which is passed by reference to the callback
+ function.
+ &lt;br&gt;&lt;br&gt; When the sources are compiled with &lt;CODE&gt;_FILE_OFFSET_BITS == 64&lt;/CODE&gt; on a
+ 32-bit system this function is available under the name &lt;CODE&gt;ftw&lt;/CODE&gt; and
+ transparently replaces the old implementation.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-nftw" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *filename"/>
+ <parameter content="__nftw_func_t func"/>
+ <parameter content="int descriptors"/>
+ <parameter content="int flag"/>
+ </prototype>
+ <headers>
+ <header filename = "ftw.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;nftw&lt;/CODE&gt; function works like the &lt;CODE&gt;ftw&lt;/CODE&gt; functions. They call
+ the callback function &lt;VAR&gt;func&lt;/VAR&gt; for all items found in the directory
+ &lt;VAR&gt;filename&lt;/VAR&gt; and below. At most &lt;VAR&gt;descriptors&lt;/VAR&gt; file descriptors
+ are consumed during the &lt;CODE&gt;nftw&lt;/CODE&gt; call.
+ &lt;br&gt;&lt;br&gt; One difference is that the callback function is of a different type. It
+ is of type &lt;CODE&gt;struct FTW *&lt;/CODE&gt; and provides the callback function
+ with the extra information described above.
+ &lt;br&gt;&lt;br&gt; A second difference is that &lt;CODE&gt;nftw&lt;/CODE&gt; takes a fourth argument, which
+ is 0 or a bitwise-OR combination of any of the following values.
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;FTW_PHYS&lt;/CODE&gt;
+&lt;DD&gt;
+ While traversing the directory symbolic links are not followed. Instead
+ symbolic links are reported using the &lt;CODE&gt;FTW_SL&lt;/CODE&gt; value for the type
+ parameter to the callback function. If the file referenced by a
+ symbolic link does not exist &lt;CODE&gt;FTW_SLN&lt;/CODE&gt; is returned instead.
+ &lt;DT&gt;&lt;CODE&gt;FTW_MOUNT&lt;/CODE&gt;
+&lt;DD&gt;
+ The callback function is only called for items which are on the same
+ mounted filesystem as the directory given by the &lt;VAR&gt;filename&lt;/VAR&gt;
+ parameter to &lt;CODE&gt;nftw&lt;/CODE&gt;.
+ &lt;DT&gt;&lt;CODE&gt;FTW_CHDIR&lt;/CODE&gt;
+&lt;DD&gt;
+ 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 &lt;CODE&gt;ntfw&lt;/CODE&gt; finally returns the current directory is restored to
+ its original value.
+ &lt;DT&gt;&lt;CODE&gt;FTW_DEPTH&lt;/CODE&gt;
+&lt;DD&gt;
+ 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 &lt;CODE&gt;FTW_DP&lt;/CODE&gt; and not &lt;CODE&gt;FTW_D&lt;/CODE&gt;.
+ &lt;DT&gt;&lt;CODE&gt;FTW_ACTIONRETVAL&lt;/CODE&gt;
+&lt;DD&gt;
+ If this option is specified then return values from callbacks
+ are handled differently. If the callback returns &lt;CODE&gt;FTW_CONTINUE&lt;/CODE&gt;,
+ walking continues normally. &lt;CODE&gt;FTW_STOP&lt;/CODE&gt; means walking stops
+ and &lt;CODE&gt;FTW_STOP&lt;/CODE&gt; is returned to the caller. If &lt;CODE&gt;FTW_SKIP_SUBTREE&lt;/CODE&gt;
+ is returned by the callback with &lt;CODE&gt;FTW_D&lt;/CODE&gt; argument, the subtree
+ is skipped and walking continues with next sibling of the directory.
+ If &lt;CODE&gt;FTW_SKIP_SIBLINGS&lt;/CODE&gt; 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.
+ &lt;/DL&gt;
+ &lt;br&gt;&lt;br&gt; The return value is computed in the same way as for &lt;CODE&gt;ftw&lt;/CODE&gt;.
+ &lt;CODE&gt;nftw&lt;/CODE&gt; 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 &lt;VAR&gt;errno&lt;/VAR&gt; is set
+ accordingly. If the return value of a callback invocation was non-zero
+ then that value is returned.
+ &lt;br&gt;&lt;br&gt; When the sources are compiled with &lt;CODE&gt;_FILE_OFFSET_BITS == 64&lt;/CODE&gt; on a
+ 32-bit system this function is in fact &lt;CODE&gt;nftw64&lt;/CODE&gt;, i.e., the LFS
+ interface transparently replaces the old interface.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-nftw64" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *filename"/>
+ <parameter content="__nftw64_func_t func"/>
+ <parameter content="int descriptors"/>
+ <parameter content="int flag"/>
+ </prototype>
+ <headers>
+ <header filename = "ftw.h"/>
+ </headers>
+ <synopsis>
+ This function is similar to &lt;CODE&gt;nftw&lt;/CODE&gt; but it can work on filesystems
+ with large files. File information is reported using a variable of type
+ &lt;CODE&gt;struct stat64&lt;/CODE&gt; which is passed by reference to the callback
+ function.
+ &lt;br&gt;&lt;br&gt; When the sources are compiled with &lt;CODE&gt;_FILE_OFFSET_BITS == 64&lt;/CODE&gt; on a
+ 32-bit system this function is available under the name &lt;CODE&gt;nftw&lt;/CODE&gt; and
+ transparently replaces the old implementation.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-link" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *oldname"/>
+ <parameter content="const char *newname"/>
+ </prototype>
+ <headers>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;link&lt;/CODE&gt; function makes a new link to the existing file named by
+ &lt;VAR&gt;oldname&lt;/VAR&gt;, under the new name &lt;VAR&gt;newname&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; This function returns a value of &lt;CODE&gt;0&lt;/CODE&gt; if it is successful and
+ &lt;CODE&gt;-1&lt;/CODE&gt; on failure. In addition to the usual file name errors
+ for both &lt;VAR&gt;oldname&lt;/VAR&gt; and &lt;VAR&gt;newname&lt;/VAR&gt;, the
+ following &lt;CODE&gt;errno&lt;/CODE&gt; error conditions are defined for this function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EACCES&lt;/CODE&gt;
+&lt;DD&gt;
+ You are not allowed to write to the directory in which the new link is
+ to be written.
+
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EEXIST
+ There is already a file named &lt;VAR&gt;newname&lt;/VAR&gt;. If you want to replace
+ this link with a new link, you must remove the old link explicitly first.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EMLINK
+ There are already too many links to the file named by &lt;VAR&gt;oldname&lt;/VAR&gt;.
+ (The maximum number of links to a file is &lt;CODE&gt;LINK_MAX&lt;/CODE&gt;; see
+ Limits for Files.)
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ENOENT
+ The file named by &lt;VAR&gt;oldname&lt;/VAR&gt; doesn't exist. You can't make a link to
+ a file that doesn't exist.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ENOSPC
+ The directory or file system that would contain the new link is full
+ and cannot be extended.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; 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.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EROFS
+ The directory containing the new link can't be modified because it's on
+ a read-only file system.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EXDEV
+ The directory specified in &lt;VAR&gt;newname&lt;/VAR&gt; is on a different file system
+ than the existing file.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EIO
+ A hardware error occurred while trying to read or write the to filesystem.
+
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-symlink" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *oldname"/>
+ <parameter content="const char *newname"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/param.h"/>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;symlink&lt;/CODE&gt; function makes a symbolic link to &lt;VAR&gt;oldname&lt;/VAR&gt; named
+ &lt;VAR&gt;newname&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; The normal return value from &lt;CODE&gt;symlink&lt;/CODE&gt; is &lt;CODE&gt;0&lt;/CODE&gt;. A return value
+ of &lt;CODE&gt;-1&lt;/CODE&gt; indicates an error. In addition to the usual file name
+ syntax errors , the following &lt;CODE&gt;errno&lt;/CODE&gt;
+ error conditions are defined for this function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EEXIST&lt;/CODE&gt;
+&lt;DD&gt;
+ There is already an existing file named &lt;VAR&gt;newname&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EROFS
+ The file &lt;VAR&gt;newname&lt;/VAR&gt; would exist on a read-only file system.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ENOSPC
+ The directory or file system cannot be extended to make the new link.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EIO
+ A hardware error occurred while reading or writing data on the disk.
+ &lt;br&gt;&lt;br&gt;
+
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-readlink" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *filename"/>
+ <parameter content="char *buffer"/>
+ <parameter content="size_t size"/>
+ </prototype>
+ <headers>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;readlink&lt;/CODE&gt; function gets the value of the symbolic link
+ &lt;VAR&gt;filename&lt;/VAR&gt;. The file name that the link points to is copied into
+ &lt;VAR&gt;buffer&lt;/VAR&gt;. This file name string is &lt;EM&gt;not&lt;/EM&gt; null-terminated;
+ &lt;CODE&gt;readlink&lt;/CODE&gt; normally returns the number of characters copied. The
+ &lt;VAR&gt;size&lt;/VAR&gt; argument specifies the maximum number of characters to copy,
+ usually the allocation size of &lt;VAR&gt;buffer&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; If the return value equals &lt;VAR&gt;size&lt;/VAR&gt;, you cannot tell whether or not
+ there was room to return the entire name. So make a bigger buffer and
+ call &lt;CODE&gt;readlink&lt;/CODE&gt; again. Here is an example:
+ &lt;br&gt;&lt;br&gt; &lt;pre&gt;&lt;br&gt;
+ char *&lt;br&gt;
+ readlink_malloc (const char *filename)&lt;br&gt;
+ {&lt;br&gt;
+ int size = 100;&lt;br&gt;
+ char *buffer = NULL;&lt;br&gt;
+ &lt;br&gt;&lt;br&gt; while (1)&lt;br&gt;
+ {&lt;br&gt;
+ buffer = (char *) xrealloc (buffer, size);&lt;br&gt;
+ int nchars = readlink (filename, buffer, size);&lt;br&gt;
+ if (nchars &lt; 0)&lt;br&gt;
+ {&lt;br&gt;
+ free (buffer);&lt;br&gt;
+ return NULL;&lt;br&gt;
+ }&lt;br&gt;
+ if (nchars &lt; size)&lt;br&gt;
+ return buffer;&lt;br&gt;
+ size *= 2;&lt;br&gt;
+ }&lt;br&gt;
+ }&lt;br&gt;
+ &lt;/pre&gt;
+ &lt;br&gt;&lt;br&gt; A value of &lt;CODE&gt;-1&lt;/CODE&gt; is returned in case of error. In addition to the
+ usual file name errors , the following
+ &lt;CODE&gt;errno&lt;/CODE&gt; error conditions are defined for this function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EINVAL&lt;/CODE&gt;
+&lt;DD&gt;
+ The named file is not a symbolic link.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EIO
+ A hardware error occurred while reading or writing data on the disk.
+
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-canonicalize_file_name" type="function">
+ <function returntype="char *">
+ <prototype>
+ <parameter content="const char *name"/>
+ </prototype>
+ <headers>
+ <header filename = "stdlib.h"/>
+ </headers>
+ <synopsis>
+ &lt;br&gt;&lt;br&gt; The &lt;CODE&gt;canonicalize_file_name&lt;/CODE&gt; function returns the absolute name of
+ the file named by &lt;VAR&gt;name&lt;/VAR&gt; which contains no &lt;CODE&gt;.&lt;/CODE&gt;, &lt;CODE&gt;..&lt;/CODE&gt;
+ components nor any repeated path separators (&lt;CODE&gt;/&lt;/CODE&gt;) or symlinks. The
+ result is passed back as the return value of the function in a block of
+ memory allocated with &lt;CODE&gt;malloc&lt;/CODE&gt;. If the result is not used anymore
+ the memory should be freed with a call to &lt;CODE&gt;free&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; 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 &lt;CODE&gt;PATH_MAX&lt;/CODE&gt; characters. In any case
+ &lt;CODE&gt;errno&lt;/CODE&gt; is set accordingly.
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;ENAMETOOLONG&lt;/CODE&gt;
+&lt;DD&gt;
+ The resulting path is too long. This error only occurs on systems which
+ have a limit on the file name length.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EACCES
+ At least one of the path components is not readable.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ENOENT
+ The input file name is empty.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ENOENT
+ At least one of the path components does not exist.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ELOOP
+ More than &lt;CODE&gt;MAXSYMLINKS&lt;/CODE&gt; many symlinks have been followed.
+
+ &lt;br&gt;&lt;br&gt; This function is a GNU extension and is declared in &lt;TT&gt;stdlib.h&lt;/TT&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-realpath" type="function">
+ <function returntype="char *">
+ <prototype>
+ <parameter content="const char *restrict name"/>
+ <parameter content="char *restrict resolved"/>
+ </prototype>
+ <headers>
+ <header filename = "stdlib.h"/>
+ </headers>
+ <synopsis>
+ &lt;br&gt;&lt;br&gt; A call to &lt;CODE&gt;realpath&lt;/CODE&gt; where the &lt;VAR&gt;resolved&lt;/VAR&gt; parameter is
+ &lt;CODE&gt;NULL&lt;/CODE&gt; behaves exactly like &lt;CODE&gt;canonicalize_file_name&lt;/CODE&gt;. The
+ function allocates a buffer for the file name and returns a pointer to
+ it. If &lt;VAR&gt;resolved&lt;/VAR&gt; is not &lt;CODE&gt;NULL&lt;/CODE&gt; 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
+ &lt;CODE&gt;PATH_MAX&lt;/CODE&gt; 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
+ &lt;CODE&gt;realpath&lt;/CODE&gt; with anything but &lt;CODE&gt;NULL&lt;/CODE&gt; for the second parameter.
+ &lt;br&gt;&lt;br&gt; One other difference is that the buffer &lt;VAR&gt;resolved&lt;/VAR&gt; (if nonzero) will
+ contain the part of the path component which does not exist or is not
+ readable if the function returns &lt;CODE&gt;NULL&lt;/CODE&gt; and &lt;CODE&gt;errno&lt;/CODE&gt; is set to
+ &lt;CODE&gt;EACCES&lt;/CODE&gt; or &lt;CODE&gt;ENOENT&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; This function is declared in &lt;TT&gt;stdlib.h&lt;/TT&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-unlink" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *filename"/>
+ </prototype>
+ <headers>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;unlink&lt;/CODE&gt; function deletes the file name &lt;VAR&gt;filename&lt;/VAR&gt;. 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.)
+ &lt;br&gt;&lt;br&gt; The function &lt;CODE&gt;unlink&lt;/CODE&gt; is declared in the header file &lt;TT&gt;unistd.h&lt;/TT&gt;.
+ &lt;br&gt;&lt;br&gt; This function returns &lt;CODE&gt;0&lt;/CODE&gt; on successful completion, and &lt;CODE&gt;-1&lt;/CODE&gt;
+ on error. In addition to the usual file name errors
+ , the following &lt;CODE&gt;errno&lt;/CODE&gt; error conditions are
+ defined for this function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EACCES&lt;/CODE&gt;
+&lt;DD&gt;
+ 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.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; 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.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ENOENT
+ The file name to be deleted doesn't exist.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EPERM
+ On some systems &lt;CODE&gt;unlink&lt;/CODE&gt; 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 &lt;CODE&gt;rmdir&lt;/CODE&gt; to delete directories. (In the
+ GNU system &lt;CODE&gt;unlink&lt;/CODE&gt; can never delete the name of a directory.)
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EROFS
+ The directory containing the file name to be deleted is on a read-only
+ file system and can't be modified.
+
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-rmdir" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *filename"/>
+ </prototype>
+ <headers>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ , deleting
+ a directory
+ The &lt;CODE&gt;rmdir&lt;/CODE&gt; function deletes a directory. The directory must be
+ empty before it can be removed; in other words, it can only contain
+ entries for &lt;TT&gt;.&lt;/TT&gt; and &lt;TT&gt;..&lt;/TT&gt;.
+ &lt;br&gt;&lt;br&gt; In most other respects, &lt;CODE&gt;rmdir&lt;/CODE&gt; behaves like &lt;CODE&gt;unlink&lt;/CODE&gt;. There
+ are two additional &lt;CODE&gt;errno&lt;/CODE&gt; error conditions defined for
+ &lt;CODE&gt;rmdir&lt;/CODE&gt;:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;ENOTEMPTY&lt;/CODE&gt;
+&lt;DD&gt;
+ &lt;LI&gt;x EEXIST
+ The directory to be deleted is not empty.
+
+ &lt;br&gt;&lt;br&gt; These two error codes are synonymous; some systems use one, and some use
+ the other. The GNU system always uses &lt;CODE&gt;ENOTEMPTY&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; The prototype for this function is declared in the header file
+ &lt;TT&gt;unistd.h&lt;/TT&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-remove" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *filename"/>
+ </prototype>
+ <headers>
+ <header filename = "stdio.h"/>
+ </headers>
+ <synopsis>
+ This is the ISO C function to remove a file. It works like
+ &lt;CODE&gt;unlink&lt;/CODE&gt; for files and like &lt;CODE&gt;rmdir&lt;/CODE&gt; for directories.
+ &lt;CODE&gt;remove&lt;/CODE&gt; is declared in &lt;TT&gt;stdio.h&lt;/TT&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-rename" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *oldname"/>
+ <parameter content="const char *newname"/>
+ </prototype>
+ <headers>
+ <header filename = "stdio.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;rename&lt;/CODE&gt; function renames the file &lt;VAR&gt;oldname&lt;/VAR&gt; to
+ &lt;VAR&gt;newname&lt;/VAR&gt;. The file formerly accessible under the name
+ &lt;VAR&gt;oldname&lt;/VAR&gt; is afterwards accessible as &lt;VAR&gt;newname&lt;/VAR&gt; instead. (If
+ the file had any other names aside from &lt;VAR&gt;oldname&lt;/VAR&gt;, it continues to
+ have those names.)
+ &lt;br&gt;&lt;br&gt; The directory containing the name &lt;VAR&gt;newname&lt;/VAR&gt; must be on the same file
+ system as the directory containing the name &lt;VAR&gt;oldname&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; One special case for &lt;CODE&gt;rename&lt;/CODE&gt; is when &lt;VAR&gt;oldname&lt;/VAR&gt; and
+ &lt;VAR&gt;newname&lt;/VAR&gt; are two names for the same file. The consistent way to
+ handle this case is to delete &lt;VAR&gt;oldname&lt;/VAR&gt;. However, in this case
+ POSIX requires that &lt;CODE&gt;rename&lt;/CODE&gt; do nothing and report success---which
+ is inconsistent. We don't know what your operating system will do.
+ &lt;br&gt;&lt;br&gt; If &lt;VAR&gt;oldname&lt;/VAR&gt; is not a directory, then any existing file named
+ &lt;VAR&gt;newname&lt;/VAR&gt; is removed during the renaming operation. However, if
+ &lt;VAR&gt;newname&lt;/VAR&gt; is the name of a directory, &lt;CODE&gt;rename&lt;/CODE&gt; fails in this
+ case.
+ &lt;br&gt;&lt;br&gt; If &lt;VAR&gt;oldname&lt;/VAR&gt; is a directory, then either &lt;VAR&gt;newname&lt;/VAR&gt; must not
+ exist or it must name a directory that is empty. In the latter case,
+ the existing directory named &lt;VAR&gt;newname&lt;/VAR&gt; is deleted first. The name
+ &lt;VAR&gt;newname&lt;/VAR&gt; must not specify a subdirectory of the directory
+ &lt;CODE&gt;oldname&lt;/CODE&gt; which is being renamed.
+ &lt;br&gt;&lt;br&gt; One useful feature of &lt;CODE&gt;rename&lt;/CODE&gt; is that the meaning of &lt;VAR&gt;newname&lt;/VAR&gt;
+ changes ``atomically'' from any previously existing file by that name to
+ its new meaning (i.e., the file that was called &lt;VAR&gt;oldname&lt;/VAR&gt;). There is
+ no instant at which &lt;VAR&gt;newname&lt;/VAR&gt; 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
+ &lt;VAR&gt;newname&lt;/VAR&gt; will always be intact if it exists at all.
+ &lt;br&gt;&lt;br&gt; If &lt;CODE&gt;rename&lt;/CODE&gt; fails, it returns &lt;CODE&gt;-1&lt;/CODE&gt;. In addition to the usual
+ file name errors , the following
+ &lt;CODE&gt;errno&lt;/CODE&gt; error conditions are defined for this function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EACCES&lt;/CODE&gt;
+&lt;DD&gt;
+ One of the directories containing &lt;VAR&gt;newname&lt;/VAR&gt; or &lt;VAR&gt;oldname&lt;/VAR&gt;
+ refuses write permission; or &lt;VAR&gt;newname&lt;/VAR&gt; and &lt;VAR&gt;oldname&lt;/VAR&gt; are
+ directories and write permission is refused for one of them.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EBUSY
+ A directory named by &lt;VAR&gt;oldname&lt;/VAR&gt; or &lt;VAR&gt;newname&lt;/VAR&gt; 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.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ENOTEMPTY
+ &lt;LI&gt;x EEXIST
+ The directory &lt;VAR&gt;newname&lt;/VAR&gt; isn't empty. The GNU system always returns
+ &lt;CODE&gt;ENOTEMPTY&lt;/CODE&gt; for this, but some other systems return &lt;CODE&gt;EEXIST&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EINVAL
+ &lt;VAR&gt;oldname&lt;/VAR&gt; is a directory that contains &lt;VAR&gt;newname&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EISDIR
+ &lt;VAR&gt;newname&lt;/VAR&gt; is a directory but the &lt;VAR&gt;oldname&lt;/VAR&gt; isn't.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EMLINK
+ The parent directory of &lt;VAR&gt;newname&lt;/VAR&gt; would have too many links
+ (entries).
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ENOENT
+ The file &lt;VAR&gt;oldname&lt;/VAR&gt; doesn't exist.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ENOSPC
+ The directory that would contain &lt;VAR&gt;newname&lt;/VAR&gt; has no room for another
+ entry, and there is no space left in the file system to expand it.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EROFS
+ The operation would involve writing to a directory on a read-only file
+ system.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EXDEV
+ The two file names &lt;VAR&gt;newname&lt;/VAR&gt; and &lt;VAR&gt;oldname&lt;/VAR&gt; are on different
+ file systems.
+
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-mkdir" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *filename"/>
+ <parameter content="mode_t mode"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/stat.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;mkdir&lt;/CODE&gt; function creates a new, empty directory with name
+ &lt;VAR&gt;filename&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; The argument &lt;VAR&gt;mode&lt;/VAR&gt; specifies the file permissions for the new
+ directory file. , for more information about
+ this.
+ &lt;br&gt;&lt;br&gt; A return value of &lt;CODE&gt;0&lt;/CODE&gt; indicates successful completion, and
+ &lt;CODE&gt;-1&lt;/CODE&gt; indicates failure. In addition to the usual file name syntax
+ errors , the following &lt;CODE&gt;errno&lt;/CODE&gt; error
+ conditions are defined for this function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EACCES&lt;/CODE&gt;
+&lt;DD&gt;
+ Write permission is denied for the parent directory in which the new
+ directory is to be added.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EEXIST
+ A file named &lt;VAR&gt;filename&lt;/VAR&gt; already exists.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EMLINK
+ The parent directory has too many links (entries).
+ &lt;br&gt;&lt;br&gt; 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.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ENOSPC
+ The file system doesn't have enough room to create the new directory.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EROFS
+ The parent directory of the directory being created is on a read-only
+ file system and cannot be modified.
+
+ &lt;br&gt;&lt;br&gt; To use this function, your program should include the header file
+ &lt;TT&gt;sys/stat.h&lt;/TT&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="struct-stat" type="struct">
+ <structure>
+ <synopsis>
+ The &lt;CODE&gt;stat&lt;/CODE&gt; structure type is used to return information about the
+ attributes of a file. It contains at least the following members:
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ <elements>
+ <element content="mode_t st_mode">
+ <synopsis>
+ Specifies the mode of the file. This includes file type information
+ and the file permission bits
+ .
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="ino_t st_ino">
+ <synopsis>
+ The file serial number, which distinguishes this file from all other
+ files on the same device.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="dev_t st_dev">
+ <synopsis>
+ Identifies the device containing the file. The &lt;CODE&gt;st_ino&lt;/CODE&gt; and
+ &lt;CODE&gt;st_dev&lt;/CODE&gt;, taken together, uniquely identify the file. The
+ &lt;CODE&gt;st_dev&lt;/CODE&gt; value is not necessarily consistent across reboots or
+ system crashes, however.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="nlink_t st_nlink">
+ <synopsis>
+ The number of hard links to the file. This count keeps track of how
+ many directories have entries for this file. If the count is ever
+ decremented to zero, then the file itself is discarded as soon as no
+ process still holds it open. Symbolic links are not counted in the
+ total.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="uid_t st_uid">
+ <synopsis>
+ The user ID of the file's owner. .
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="gid_t st_gid">
+ <synopsis>
+ The group ID of the file. .
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="off_t st_size">
+ <synopsis>
+ This specifies the size of a regular file in bytes. For files that are
+ really devices this field isn't usually meaningful. For symbolic links
+ this specifies the length of the file name the link refers to.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="time_t st_atime">
+ <synopsis>
+ This is the last access time for the file. .
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="unsigned long int st_atime_usec">
+ <synopsis>
+ This is the fractional part of the last access time for the file.
+ .
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="time_t st_mtime">
+ <synopsis>
+ This is the time of the last modification to the contents of the file.
+ .
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="unsigned long int st_mtime_usec">
+ <synopsis>
+ This is the fractional part of the time of the last modification to the
+ contents of the file. .
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="time_t st_ctime">
+ <synopsis>
+ This is the time of the last modification to the attributes of the file.
+ .
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="unsigned long int st_ctime_usec">
+ <synopsis>
+ This is the fractional part of the time of the last modification to the
+ attributes of the file. .
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="blkcnt_t st_blocks">
+ <synopsis>
+ This is the amount of disk space that the file occupies, measured in
+ units of 512-byte blocks.
+ &lt;br&gt;&lt;br&gt; The number of disk blocks is not strictly proportional to the size of
+ the file, for two reasons: the file system may use some blocks for
+ internal record keeping; and the file may be sparse---it may have
+ ``holes'' which contain zeros but do not actually take up space on the
+ disk.
+ &lt;br&gt;&lt;br&gt; You can tell (approximately) whether a file is sparse by comparing this
+ value with &lt;CODE&gt;st_size&lt;/CODE&gt;, like this:
+ &lt;br&gt;&lt;br&gt; &lt;pre&gt;&lt;br&gt;
+ (st.st_blocks * 512 &lt; st.st_size)&lt;br&gt;
+ &lt;/pre&gt;
+ &lt;br&gt;&lt;br&gt; This test is not perfect because a file that is just slightly sparse
+ might not be detected as sparse at all. For practical applications,
+ this is not a problem.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ </elements>
+ </structure>
+ </construct>
+ <construct id="struct-stat64" type="struct">
+ <structure>
+ <synopsis>
+ The members of this type are the same and have the same names as those
+ in &lt;CODE&gt;struct stat&lt;/CODE&gt;. The only difference is that the members
+ &lt;CODE&gt;st_ino&lt;/CODE&gt;, &lt;CODE&gt;st_size&lt;/CODE&gt;, and &lt;CODE&gt;st_blocks&lt;/CODE&gt; have a different
+ type to support larger values.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ <elements>
+ <element content="mode_t st_mode">
+ <synopsis>
+ Specifies the mode of the file. This includes file type information
+ and the file permission bits
+ .
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="ino64_t st_ino">
+ <synopsis>
+ The file serial number, which distinguishes this file from all other
+ files on the same device.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="dev_t st_dev">
+ <synopsis>
+ Identifies the device containing the file. The &lt;CODE&gt;st_ino&lt;/CODE&gt; and
+ &lt;CODE&gt;st_dev&lt;/CODE&gt;, taken together, uniquely identify the file. The
+ &lt;CODE&gt;st_dev&lt;/CODE&gt; value is not necessarily consistent across reboots or
+ system crashes, however.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="nlink_t st_nlink">
+ <synopsis>
+ The number of hard links to the file. This count keeps track of how
+ many directories have entries for this file. If the count is ever
+ decremented to zero, then the file itself is discarded as soon as no
+ process still holds it open. Symbolic links are not counted in the
+ total.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="uid_t st_uid">
+ <synopsis>
+ The user ID of the file's owner. .
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="gid_t st_gid">
+ <synopsis>
+ The group ID of the file. .
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="off64_t st_size">
+ <synopsis>
+ This specifies the size of a regular file in bytes. For files that are
+ really devices this field isn't usually meaningful. For symbolic links
+ this specifies the length of the file name the link refers to.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="time_t st_atime">
+ <synopsis>
+ This is the last access time for the file. .
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="unsigned long int st_atime_usec">
+ <synopsis>
+ This is the fractional part of the last access time for the file.
+ .
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="time_t st_mtime">
+ <synopsis>
+ This is the time of the last modification to the contents of the file.
+ .
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="unsigned long int st_mtime_usec">
+ <synopsis>
+ This is the fractional part of the time of the last modification to the
+ contents of the file. .
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="time_t st_ctime">
+ <synopsis>
+ This is the time of the last modification to the attributes of the file.
+ .
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="unsigned long int st_ctime_usec">
+ <synopsis>
+ This is the fractional part of the time of the last modification to the
+ attributes of the file. .
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="blkcnt64_t st_blocks">
+ <synopsis>
+ This is the amount of disk space that the file occupies, measured in
+ units of 512-byte blocks.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ </elements>
+ </structure>
+ </construct>
+ <construct id="dtype-mode_t" type="dtype">
+ <structure>
+ </structure>
+ </construct>
+ <construct id="dtype-ino_t" type="dtype">
+ <structure>
+ </structure>
+ </construct>
+ <construct id="dtype-ino64_t" type="dtype">
+ <structure>
+ </structure>
+ </construct>
+ <construct id="dtype-dev_t" type="dtype">
+ <structure>
+ </structure>
+ </construct>
+ <construct id="dtype-nlink_t" type="dtype">
+ <structure>
+ </structure>
+ </construct>
+ <construct id="dtype-blkcnt_t" type="dtype">
+ <structure>
+ </structure>
+ </construct>
+ <construct id="dtype-blkcnt64_t" type="dtype">
+ <structure>
+ </structure>
+ </construct>
+ <construct id="function-stat" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *filename"/>
+ <parameter content="struct stat *buf"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/stat.h"/>
+ <header filename = "sys/types.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;stat&lt;/CODE&gt; function returns information about the attributes of the
+ file named by &lt;VAR&gt;filename&lt;/VAR&gt; in the structure pointed to by &lt;VAR&gt;buf&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; If &lt;VAR&gt;filename&lt;/VAR&gt; 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 &lt;CODE&gt;stat&lt;/CODE&gt; fails reporting a nonexistent
+ file.
+ &lt;br&gt;&lt;br&gt; The return value is &lt;CODE&gt;0&lt;/CODE&gt; if the operation is successful, or
+ &lt;CODE&gt;-1&lt;/CODE&gt; on failure. In addition to the usual file name errors
+ (, the following &lt;CODE&gt;errno&lt;/CODE&gt; error conditions
+ are defined for this function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;ENOENT&lt;/CODE&gt;
+&lt;DD&gt;
+ The file named by &lt;VAR&gt;filename&lt;/VAR&gt; doesn't exist.
+
+ &lt;br&gt;&lt;br&gt; When the sources are compiled with &lt;CODE&gt;_FILE_OFFSET_BITS == 64&lt;/CODE&gt; this
+ function is in fact &lt;CODE&gt;stat64&lt;/CODE&gt; since the LFS interface transparently
+ replaces the normal implementation.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-stat64" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *filename"/>
+ <parameter content="struct stat64 *buf"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/stat.h"/>
+ </headers>
+ <synopsis>
+ This function is similar to &lt;CODE&gt;stat&lt;/CODE&gt; 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 &lt;CODE&gt;struct stat64&lt;/CODE&gt; to
+ which &lt;VAR&gt;buf&lt;/VAR&gt; must point.
+ &lt;br&gt;&lt;br&gt; When the sources are compiled with &lt;CODE&gt;_FILE_OFFSET_BITS == 64&lt;/CODE&gt; this
+ function is available under the name &lt;CODE&gt;stat&lt;/CODE&gt; and so transparently
+ replaces the interface for small files on 32-bit machines.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-fstat" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="int filedes"/>
+ <parameter content="struct stat *buf"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/stat.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;fstat&lt;/CODE&gt; function is like &lt;CODE&gt;stat&lt;/CODE&gt;, except that it takes an
+ open file descriptor as an argument instead of a file name.
+ .
+ &lt;br&gt;&lt;br&gt; Like &lt;CODE&gt;stat&lt;/CODE&gt;, &lt;CODE&gt;fstat&lt;/CODE&gt; returns &lt;CODE&gt;0&lt;/CODE&gt; on success and &lt;CODE&gt;-1&lt;/CODE&gt;
+ on failure. The following &lt;CODE&gt;errno&lt;/CODE&gt; error conditions are defined for
+ &lt;CODE&gt;fstat&lt;/CODE&gt;:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EBADF&lt;/CODE&gt;
+&lt;DD&gt;
+ The &lt;VAR&gt;filedes&lt;/VAR&gt; argument is not a valid file descriptor.
+
+ &lt;br&gt;&lt;br&gt; When the sources are compiled with &lt;CODE&gt;_FILE_OFFSET_BITS == 64&lt;/CODE&gt; this
+ function is in fact &lt;CODE&gt;fstat64&lt;/CODE&gt; since the LFS interface transparently
+ replaces the normal implementation.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-fstat64" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="int filedes"/>
+ <parameter content="struct stat64 *buf"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/stat.h"/>
+ </headers>
+ <synopsis>
+ This function is similar to &lt;CODE&gt;fstat&lt;/CODE&gt; but is able to work on large
+ files on 32-bit platforms. For large files the file descriptor
+ &lt;VAR&gt;filedes&lt;/VAR&gt; should be obtained by &lt;CODE&gt;open64&lt;/CODE&gt; or &lt;CODE&gt;creat64&lt;/CODE&gt;.
+ The &lt;VAR&gt;buf&lt;/VAR&gt; pointer points to a variable of type &lt;CODE&gt;struct stat64&lt;/CODE&gt;
+ which is able to represent the larger values.
+ &lt;br&gt;&lt;br&gt; When the sources are compiled with &lt;CODE&gt;_FILE_OFFSET_BITS == 64&lt;/CODE&gt; this
+ function is available under the name &lt;CODE&gt;fstat&lt;/CODE&gt; and so transparently
+ replaces the interface for small files on 32-bit machines.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-lstat" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *filename"/>
+ <parameter content="struct stat *buf"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/stat.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;lstat&lt;/CODE&gt; function is like &lt;CODE&gt;stat&lt;/CODE&gt;, except that it does not
+ follow symbolic links. If &lt;VAR&gt;filename&lt;/VAR&gt; is the name of a symbolic
+ link, &lt;CODE&gt;lstat&lt;/CODE&gt; returns information about the link itself; otherwise
+ &lt;CODE&gt;lstat&lt;/CODE&gt; works like &lt;CODE&gt;stat&lt;/CODE&gt;. .
+ &lt;br&gt;&lt;br&gt; When the sources are compiled with &lt;CODE&gt;_FILE_OFFSET_BITS == 64&lt;/CODE&gt; this
+ function is in fact &lt;CODE&gt;lstat64&lt;/CODE&gt; since the LFS interface transparently
+ replaces the normal implementation.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-lstat64" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *filename"/>
+ <parameter content="struct stat64 *buf"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/stat.h"/>
+ </headers>
+ <synopsis>
+ This function is similar to &lt;CODE&gt;lstat&lt;/CODE&gt; 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 &lt;CODE&gt;struct stat64&lt;/CODE&gt; to
+ which &lt;VAR&gt;buf&lt;/VAR&gt; must point.
+ &lt;br&gt;&lt;br&gt; When the sources are compiled with &lt;CODE&gt;_FILE_OFFSET_BITS == 64&lt;/CODE&gt; this
+ function is available under the name &lt;CODE&gt;lstat&lt;/CODE&gt; and so transparently
+ replaces the interface for small files on 32-bit machines.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-chown" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *filename"/>
+ <parameter content="uid_t owner"/>
+ <parameter content="gid_t group"/>
+ </prototype>
+ <headers>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;chown&lt;/CODE&gt; function changes the owner of the file &lt;VAR&gt;filename&lt;/VAR&gt; to
+ &lt;VAR&gt;owner&lt;/VAR&gt;, and its group owner to &lt;VAR&gt;group&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; 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.
+ &lt;br&gt;&lt;br&gt; The return value is &lt;CODE&gt;0&lt;/CODE&gt; on success and &lt;CODE&gt;-1&lt;/CODE&gt; on failure.
+ In addition to the usual file name errors ,
+ the following &lt;CODE&gt;errno&lt;/CODE&gt; error conditions are defined for this function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EPERM&lt;/CODE&gt;
+&lt;DD&gt;
+ This process lacks permission to make the requested change.
+ &lt;br&gt;&lt;br&gt; 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.
+ &lt;br&gt;&lt;br&gt; , for information about the
+ &lt;CODE&gt;_POSIX_CHOWN_RESTRICTED&lt;/CODE&gt; macro.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EROFS
+ The file is on a read-only file system.
+
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-fchown" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="int filedes"/>
+ <parameter content="int owner"/>
+ <parameter content="int group"/>
+ </prototype>
+ <headers>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ This is like &lt;CODE&gt;chown&lt;/CODE&gt;, except that it changes the owner of the open
+ file with descriptor &lt;VAR&gt;filedes&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; The return value from &lt;CODE&gt;fchown&lt;/CODE&gt; is &lt;CODE&gt;0&lt;/CODE&gt; on success and &lt;CODE&gt;-1&lt;/CODE&gt;
+ on failure. The following &lt;CODE&gt;errno&lt;/CODE&gt; error codes are defined for this
+ function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EBADF&lt;/CODE&gt;
+&lt;DD&gt;
+ The &lt;VAR&gt;filedes&lt;/VAR&gt; argument is not a valid file descriptor.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EINVAL
+ The &lt;VAR&gt;filedes&lt;/VAR&gt; argument corresponds to a pipe or socket, not an ordinary
+ file.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EPERM
+ This process lacks permission to make the requested change. For details
+ see &lt;CODE&gt;chmod&lt;/CODE&gt; above.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EROFS
+ The file resides on a read-only file system.
+
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-umask" type="function">
+ <function returntype="mode_t">
+ <prototype>
+ <parameter content="mode_t mask"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/stat.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;umask&lt;/CODE&gt; function sets the file creation mask of the current
+ process to &lt;VAR&gt;mask&lt;/VAR&gt;, and returns the previous value of the file
+ creation mask.
+ &lt;br&gt;&lt;br&gt; Here is an example showing how to read the mask with &lt;CODE&gt;umask&lt;/CODE&gt;
+ without changing it permanently:
+ &lt;br&gt;&lt;br&gt; &lt;pre&gt;&lt;br&gt;
+ mode_t&lt;br&gt;
+ read_umask (void)&lt;br&gt;
+ {&lt;br&gt;
+ mode_t mask = umask (0);&lt;br&gt;
+ umask (mask);&lt;br&gt;
+ return mask;&lt;br&gt;
+ }&lt;br&gt;
+ &lt;/pre&gt;
+ &lt;br&gt;&lt;br&gt;
+ However, it is better to use &lt;CODE&gt;getumask&lt;/CODE&gt; if you just want to read
+ the mask value, because it is reentrant (at least if you use the GNU
+ operating system).
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-getumask" type="function">
+ <function returntype="mode_t">
+ <prototype>
+ <parameter content="void"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/stat.h"/>
+ </headers>
+ <synopsis>
+ Return the current value of the file creation mask for the current
+ process. This function is a GNU extension.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-chmod" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *filename"/>
+ <parameter content="mode_t mode"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/stat.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;chmod&lt;/CODE&gt; function sets the access permission bits for the file
+ named by &lt;VAR&gt;filename&lt;/VAR&gt; to &lt;VAR&gt;mode&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; If &lt;VAR&gt;filename&lt;/VAR&gt; is a symbolic link, &lt;CODE&gt;chmod&lt;/CODE&gt; changes the
+ permissions of the file pointed to by the link, not those of the link
+ itself.
+ &lt;br&gt;&lt;br&gt; This function returns &lt;CODE&gt;0&lt;/CODE&gt; if successful and &lt;CODE&gt;-1&lt;/CODE&gt; if not. In
+ addition to the usual file name errors , the following &lt;CODE&gt;errno&lt;/CODE&gt; error conditions are defined for
+ this function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;ENOENT&lt;/CODE&gt;
+&lt;DD&gt;
+ The named file doesn't exist.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; 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.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EROFS
+ The file resides on a read-only file system.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EFTYPE
+ &lt;VAR&gt;mode&lt;/VAR&gt; has the &lt;CODE&gt;S_ISVTX&lt;/CODE&gt; 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).
+ &lt;br&gt;&lt;br&gt; You only get &lt;CODE&gt;EFTYPE&lt;/CODE&gt; 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 &lt;VAR&gt;mode&lt;/VAR&gt; and call &lt;CODE&gt;chmod&lt;/CODE&gt; again. ,
+ for full details on the sticky bit.
+
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-fchmod" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="int filedes"/>
+ <parameter content="int mode"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/stat.h"/>
+ </headers>
+ <synopsis>
+ This is like &lt;CODE&gt;chmod&lt;/CODE&gt;, except that it changes the permissions of the
+ currently open file given by &lt;VAR&gt;filedes&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; The return value from &lt;CODE&gt;fchmod&lt;/CODE&gt; is &lt;CODE&gt;0&lt;/CODE&gt; on success and &lt;CODE&gt;-1&lt;/CODE&gt;
+ on failure. The following &lt;CODE&gt;errno&lt;/CODE&gt; error codes are defined for this
+ function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EBADF&lt;/CODE&gt;
+&lt;DD&gt;
+ The &lt;VAR&gt;filedes&lt;/VAR&gt; argument is not a valid file descriptor.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EINVAL
+ The &lt;VAR&gt;filedes&lt;/VAR&gt; argument corresponds to a pipe or socket, or something
+ else that doesn't really have access permissions.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; 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.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EROFS
+ The file resides on a read-only file system.
+
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-access" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *filename"/>
+ <parameter content="int how"/>
+ </prototype>
+ <headers>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;access&lt;/CODE&gt; function checks to see whether the file named by
+ &lt;VAR&gt;filename&lt;/VAR&gt; can be accessed in the way specified by the &lt;VAR&gt;how&lt;/VAR&gt;
+ argument. The &lt;VAR&gt;how&lt;/VAR&gt; argument either can be the bitwise OR of the
+ flags &lt;CODE&gt;R_OK&lt;/CODE&gt;, &lt;CODE&gt;W_OK&lt;/CODE&gt;, &lt;CODE&gt;X_OK&lt;/CODE&gt;, or the existence test
+ &lt;CODE&gt;F_OK&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; This function uses the &lt;EM&gt;real&lt;/EM&gt; user and group IDs of the calling
+ process, rather than the &lt;EM&gt;effective&lt;/EM&gt; IDs, to check for access
+ permission. As a result, if you use the function from a &lt;CODE&gt;setuid&lt;/CODE&gt;
+ or &lt;CODE&gt;setgid&lt;/CODE&gt; program , it gives
+ information relative to the user who actually ran the program.
+ &lt;br&gt;&lt;br&gt; The return value is &lt;CODE&gt;0&lt;/CODE&gt; if the access is permitted, and &lt;CODE&gt;-1&lt;/CODE&gt;
+ otherwise. (In other words, treated as a predicate function,
+ &lt;CODE&gt;access&lt;/CODE&gt; returns true if the requested access is &lt;EM&gt;denied&lt;/EM&gt;.)
+ &lt;br&gt;&lt;br&gt; In addition to the usual file name errors , the following &lt;CODE&gt;errno&lt;/CODE&gt; error conditions are defined for
+ this function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EACCES&lt;/CODE&gt;
+&lt;DD&gt;
+ The access specified by &lt;VAR&gt;how&lt;/VAR&gt; is denied.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ENOENT
+ The file doesn't exist.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EROFS
+ Write permission was requested for a file on a read-only file system.
+
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="struct-utimbuf" type="struct">
+ <structure>
+ <synopsis>
+ The &lt;CODE&gt;utimbuf&lt;/CODE&gt; structure is used with the &lt;CODE&gt;utime&lt;/CODE&gt; function to
+ specify new access and modification times for a file. It contains the
+ following members:
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ <elements>
+ <element content="time_t actime">
+ <synopsis>
+ This is the access time for the file.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ </elements>
+ </structure>
+ </construct>
+ <construct id="function-utime" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *filename"/>
+ <parameter content="const struct utimbuf *times"/>
+ </prototype>
+ <headers>
+ <header filename = "unistd.h"/>
+ <header filename = "time.h"/>
+ </headers>
+ <synopsis>
+ This function is used to modify the file times associated with the file
+ named &lt;VAR&gt;filename&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; If &lt;VAR&gt;times&lt;/VAR&gt; 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 &lt;CODE&gt;actime&lt;/CODE&gt; and &lt;CODE&gt;modtime&lt;/CODE&gt; members (respectively)
+ of the &lt;CODE&gt;utimbuf&lt;/CODE&gt; structure pointed to by &lt;VAR&gt;times&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; 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).
+ &lt;br&gt;&lt;br&gt; The &lt;CODE&gt;utime&lt;/CODE&gt; function returns &lt;CODE&gt;0&lt;/CODE&gt; if successful and &lt;CODE&gt;-1&lt;/CODE&gt;
+ on failure. In addition to the usual file name errors
+ , the following &lt;CODE&gt;errno&lt;/CODE&gt; error conditions
+ are defined for this function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EACCES&lt;/CODE&gt;
+&lt;DD&gt;
+ There is a permission problem in the case where a null pointer was
+ passed as the &lt;VAR&gt;times&lt;/VAR&gt; 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.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ENOENT
+ The file doesn't exist.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EPERM
+ If the &lt;VAR&gt;times&lt;/VAR&gt; argument is not a null pointer, you must either be
+ the owner of the file or be a privileged user.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EROFS
+ The file lives on a read-only file system.
+
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-utimes" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *filename"/>
+ <parameter content="struct timeval tvp[2]"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/time.h"/>
+ </headers>
+ <synopsis>
+ This function sets the file access and modification times of the file
+ &lt;VAR&gt;filename&lt;/VAR&gt;. The new file access time is specified by
+ &lt;CODE&gt;&lt;VAR&gt;tvp&lt;/VAR&gt;[0]&lt;/CODE&gt;, and the new modification time by
+ &lt;CODE&gt;&lt;VAR&gt;tvp&lt;/VAR&gt;[1]&lt;/CODE&gt;. Similar to &lt;CODE&gt;utime&lt;/CODE&gt;, if &lt;VAR&gt;tvp&lt;/VAR&gt; is a null
+ pointer then the access and modification times of the file are set to
+ the current time. This function comes from BSD.
+ &lt;br&gt;&lt;br&gt; The return values and error conditions are the same as for the &lt;CODE&gt;utime&lt;/CODE&gt;
+ function.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-lutimes" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *filename"/>
+ <parameter content="struct timeval tvp[2]"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/time.h"/>
+ </headers>
+ <synopsis>
+ This function is like &lt;CODE&gt;utimes&lt;/CODE&gt;, except that it does not follow
+ symbolic links. If &lt;VAR&gt;filename&lt;/VAR&gt; is the name of a symbolic link,
+ &lt;CODE&gt;lutimes&lt;/CODE&gt; sets the file access and modification times of the
+ symbolic link special file itself (as seen by &lt;CODE&gt;lstat&lt;/CODE&gt;;
+ ) while &lt;CODE&gt;utimes&lt;/CODE&gt; 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 &lt;CODE&gt;ENOSYS&lt;/CODE&gt;).
+ &lt;br&gt;&lt;br&gt; The return values and error conditions are the same as for the &lt;CODE&gt;utime&lt;/CODE&gt;
+ function.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-futimes" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="int fd"/>
+ <parameter content="struct timeval tvp[2]"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/time.h"/>
+ </headers>
+ <synopsis>
+ This function is like &lt;CODE&gt;utimes&lt;/CODE&gt;, 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 &lt;CODE&gt;ENOSYS&lt;/CODE&gt;).
+ &lt;br&gt;&lt;br&gt; Like &lt;CODE&gt;utimes&lt;/CODE&gt;, &lt;CODE&gt;futimes&lt;/CODE&gt; returns &lt;CODE&gt;0&lt;/CODE&gt; on success and &lt;CODE&gt;-1&lt;/CODE&gt;
+ on failure. The following &lt;CODE&gt;errno&lt;/CODE&gt; error conditions are defined for
+ &lt;CODE&gt;futimes&lt;/CODE&gt;:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EACCES&lt;/CODE&gt;
+&lt;DD&gt;
+ There is a permission problem in the case where a null pointer was
+ passed as the &lt;VAR&gt;times&lt;/VAR&gt; 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.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EBADF
+ The &lt;VAR&gt;filedes&lt;/VAR&gt; argument is not a valid file descriptor.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EPERM
+ If the &lt;VAR&gt;times&lt;/VAR&gt; argument is not a null pointer, you must either be
+ the owner of the file or be a privileged user.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EROFS
+ The file lives on a read-only file system.
+
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-truncate" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *filename"/>
+ <parameter content="off_t length"/>
+ </prototype>
+ <headers>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ &lt;br&gt;&lt;br&gt; The &lt;CODE&gt;truncate&lt;/CODE&gt; function changes the size of &lt;VAR&gt;filename&lt;/VAR&gt; to
+ &lt;VAR&gt;length&lt;/VAR&gt;. If &lt;VAR&gt;length&lt;/VAR&gt; 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.
+ &lt;br&gt;&lt;br&gt; If &lt;VAR&gt;length&lt;/VAR&gt; is longer, holes will be added to the end. However, some
+ systems do not support this feature and will leave the file unchanged.
+ &lt;br&gt;&lt;br&gt; When the source file is compiled with &lt;CODE&gt;_FILE_OFFSET_BITS == 64&lt;/CODE&gt; the
+ &lt;CODE&gt;truncate&lt;/CODE&gt; function is in fact &lt;CODE&gt;truncate64&lt;/CODE&gt; and the type
+ &lt;CODE&gt;off_t&lt;/CODE&gt; has 64 bits which makes it possible to handle files up to
+ 2^63 bytes in length.
+ &lt;br&gt;&lt;br&gt; 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:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;br&gt;&lt;br&gt; &lt;DT&gt;&lt;CODE&gt;EACCES&lt;/CODE&gt;
+&lt;DD&gt;
+ The file is a directory or not writable.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EINVAL
+ &lt;VAR&gt;length&lt;/VAR&gt; is negative.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EFBIG
+ The operation would extend the file beyond the limits of the operating system.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EIO
+ A hardware I/O error occurred.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EPERM
+ The file is "append-only" or "immutable".
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EINTR
+ The operation was interrupted by a signal.
+ &lt;br&gt;&lt;br&gt;
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-truncate64" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *name"/>
+ <parameter content="off64_t length"/>
+ </prototype>
+ <headers>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ This function is similar to the &lt;CODE&gt;truncate&lt;/CODE&gt; function. The
+ difference is that the &lt;VAR&gt;length&lt;/VAR&gt; argument is 64 bits wide even on 32
+ bits machines, which allows the handling of files with sizes up to
+ 2^63 bytes.
+ &lt;br&gt;&lt;br&gt; When the source file is compiled with &lt;CODE&gt;_FILE_OFFSET_BITS == 64&lt;/CODE&gt; on a
+ 32 bits machine this function is actually available under the name
+ &lt;CODE&gt;truncate&lt;/CODE&gt; and so transparently replaces the 32 bits interface.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-ftruncate" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="int fd"/>
+ <parameter content="off_t length"/>
+ </prototype>
+ <headers>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ &lt;br&gt;&lt;br&gt; This is like &lt;CODE&gt;truncate&lt;/CODE&gt;, but it works on a file descriptor &lt;VAR&gt;fd&lt;/VAR&gt;
+ 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.
+ &lt;br&gt;&lt;br&gt; The POSIX standard leaves it implementation defined what happens if the
+ specified new &lt;VAR&gt;length&lt;/VAR&gt; of the file is bigger than the original size.
+ The &lt;CODE&gt;ftruncate&lt;/CODE&gt; 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 &lt;CODE&gt;ftruncate&lt;/CODE&gt;
+ 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.
+ &lt;br&gt;&lt;br&gt; &lt;CODE&gt;ftruncate&lt;/CODE&gt; is especially useful in combination with &lt;CODE&gt;mmap&lt;/CODE&gt;.
+ 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.
+ &lt;br&gt;&lt;br&gt; When the source file is compiled with &lt;CODE&gt;_FILE_OFFSET_BITS == 64&lt;/CODE&gt; the
+ &lt;CODE&gt;ftruncate&lt;/CODE&gt; function is in fact &lt;CODE&gt;ftruncate64&lt;/CODE&gt; and the type
+ &lt;CODE&gt;off_t&lt;/CODE&gt; has 64 bits which makes it possible to handle files up to
+ 2^63 bytes in length.
+ &lt;br&gt;&lt;br&gt; The return value is 0 for success, or -1 for an error. The
+ following errors may occur:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;br&gt;&lt;br&gt; &lt;DT&gt;&lt;CODE&gt;EBADF&lt;/CODE&gt;
+&lt;DD&gt;
+ &lt;VAR&gt;fd&lt;/VAR&gt; does not correspond to an open file.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EACCES
+ &lt;VAR&gt;fd&lt;/VAR&gt; is a directory or not open for writing.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EINVAL
+ &lt;VAR&gt;length&lt;/VAR&gt; is negative.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EFBIG
+ The operation would extend the file beyond the limits of the operating system.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EIO
+ A hardware I/O error occurred.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EPERM
+ The file is "append-only" or "immutable".
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EINTR
+ The operation was interrupted by a signal.
+ &lt;br&gt;&lt;br&gt; &lt;br&gt;&lt;br&gt;
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-ftruncate64" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="int id"/>
+ <parameter content="off64_t length"/>
+ </prototype>
+ <headers>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ This function is similar to the &lt;CODE&gt;ftruncate&lt;/CODE&gt; function. The
+ difference is that the &lt;VAR&gt;length&lt;/VAR&gt; argument is 64 bits wide even on 32
+ bits machines which allows the handling of files with sizes up to
+ 2^63 bytes.
+ &lt;br&gt;&lt;br&gt; When the source file is compiled with &lt;CODE&gt;_FILE_OFFSET_BITS == 64&lt;/CODE&gt; on a
+ 32 bits machine this function is actually available under the name
+ &lt;CODE&gt;ftruncate&lt;/CODE&gt; and so transparently replaces the 32 bits interface.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-mknod" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *filename"/>
+ <parameter content="int mode"/>
+ <parameter content="int dev"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/stat.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;mknod&lt;/CODE&gt; function makes a special file with name &lt;VAR&gt;filename&lt;/VAR&gt;.
+ The &lt;VAR&gt;mode&lt;/VAR&gt; specifies the mode of the file, and may include the various
+ special file bits, such as &lt;CODE&gt;S_IFCHR&lt;/CODE&gt; (for a character special file)
+ or &lt;CODE&gt;S_IFBLK&lt;/CODE&gt; (for a block special file). .
+ &lt;br&gt;&lt;br&gt; The &lt;VAR&gt;dev&lt;/VAR&gt; argument specifies which device the special file refers to.
+ Its exact interpretation depends on the kind of special file being created.
+ &lt;br&gt;&lt;br&gt; The return value is &lt;CODE&gt;0&lt;/CODE&gt; on success and &lt;CODE&gt;-1&lt;/CODE&gt; on error. In addition
+ to the usual file name errors , the
+ following &lt;CODE&gt;errno&lt;/CODE&gt; error conditions are defined for this function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EPERM&lt;/CODE&gt;
+&lt;DD&gt;
+ The calling process is not privileged. Only the superuser can create
+ special files.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ENOSPC
+ The directory or file system that would contain the new file is full
+ and cannot be extended.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EROFS
+ The directory containing the new file can't be modified because it's on
+ a read-only file system.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EEXIST
+ There is already a file named &lt;VAR&gt;filename&lt;/VAR&gt;. If you want to replace
+ this file, you must remove the old file explicitly first.
+
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-tmpfile" type="function">
+ <function returntype="FILE *">
+ <prototype>
+ <parameter content="void"/>
+ </prototype>
+ <headers>
+ <header filename = "stdio.h"/>
+ </headers>
+ <synopsis>
+ This function creates a temporary binary file for update mode, as if by
+ calling &lt;CODE&gt;fopen&lt;/CODE&gt; with mode &lt;CODE&gt;"wb+"&lt;/CODE&gt;. 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).
+ &lt;br&gt;&lt;br&gt; This function is reentrant.
+ &lt;br&gt;&lt;br&gt; When the sources are compiled with &lt;CODE&gt;_FILE_OFFSET_BITS == 64&lt;/CODE&gt; on a
+ 32-bit system this function is in fact &lt;CODE&gt;tmpfile64&lt;/CODE&gt;, i.e., the LFS
+ interface transparently replaces the old interface.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-tmpfile64" type="function">
+ <function returntype="FILE *">
+ <prototype>
+ <parameter content="void"/>
+ </prototype>
+ <headers>
+ <header filename = "stdio.h"/>
+ </headers>
+ <synopsis>
+ This function is similar to &lt;CODE&gt;tmpfile&lt;/CODE&gt;, but the stream it returns a
+ pointer to was opened using &lt;CODE&gt;tmpfile64&lt;/CODE&gt;. Therefore this stream can
+ be used for files larger then 2^31 bytes on 32-bit machines.
+ &lt;br&gt;&lt;br&gt; Please note that the return type is still &lt;CODE&gt;FILE *&lt;/CODE&gt;. There is no
+ special &lt;CODE&gt;FILE&lt;/CODE&gt; type for the LFS interface.
+ &lt;br&gt;&lt;br&gt; If the sources are compiled with &lt;CODE&gt;_FILE_OFFSET_BITS == 64&lt;/CODE&gt; on a 32
+ bits machine this function is available under the name &lt;CODE&gt;tmpfile&lt;/CODE&gt;
+ and so transparently replaces the old interface.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-tmpnam" type="function">
+ <function returntype="char *">
+ <prototype>
+ <parameter content="char *result"/>
+ </prototype>
+ <headers>
+ <header filename = "stdio.h"/>
+ </headers>
+ <synopsis>
+ This function constructs and returns a valid file name that does not
+ refer to any existing file. If the &lt;VAR&gt;result&lt;/VAR&gt; 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 &lt;VAR&gt;result&lt;/VAR&gt; argument should be
+ a pointer to an array of at least &lt;CODE&gt;L_tmpnam&lt;/CODE&gt; characters, and the
+ result is written into that array.
+ &lt;br&gt;&lt;br&gt; It is possible for &lt;CODE&gt;tmpnam&lt;/CODE&gt; 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 &lt;CODE&gt;tmpnam&lt;/CODE&gt; fails it returns a null pointer.
+ &lt;br&gt;&lt;br&gt; 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 &lt;CODE&gt;tmpnam&lt;/CODE&gt;, leading to a possible security hole. The
+ implementation generates names which can hardly be predicted, but when
+ opening the file you should use the &lt;CODE&gt;O_EXCL&lt;/CODE&gt; flag. Using
+ &lt;CODE&gt;tmpfile&lt;/CODE&gt; or &lt;CODE&gt;mkstemp&lt;/CODE&gt; is a safe way to avoid this problem.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-tmpnam_r" type="function">
+ <function returntype="char *">
+ <prototype>
+ <parameter content="char *result"/>
+ </prototype>
+ <headers>
+ <header filename = "stdio.h"/>
+ </headers>
+ <synopsis>
+ This function is nearly identical to the &lt;CODE&gt;tmpnam&lt;/CODE&gt; function, except
+ that if &lt;VAR&gt;result&lt;/VAR&gt; is a null pointer it returns a null pointer.
+ &lt;br&gt;&lt;br&gt; This guarantees reentrancy because the non-reentrant situation of
+ &lt;CODE&gt;tmpnam&lt;/CODE&gt; cannot happen here.
+ &lt;br&gt;&lt;br&gt; &lt;h3&gt;Warning&lt;/h3&gt;: This function has the same security problems as
+ &lt;CODE&gt;tmpnam&lt;/CODE&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-tempnam" type="function">
+ <function returntype="char *">
+ <prototype>
+ <parameter content="const char *dir"/>
+ <parameter content="const char *prefix"/>
+ </prototype>
+ <headers>
+ <header filename = "stdio.h"/>
+ </headers>
+ <synopsis>
+ This function generates a unique temporary file name. If &lt;VAR&gt;prefix&lt;/VAR&gt;
+ 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 &lt;CODE&gt;malloc&lt;/CODE&gt;, so you should release its storage with
+ &lt;CODE&gt;free&lt;/CODE&gt; when it is no longer needed.
+ &lt;br&gt;&lt;br&gt; Because the string is dynamically allocated this function is reentrant.
+ &lt;br&gt;&lt;br&gt; 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.
+ &lt;br&gt;&lt;br&gt; &lt;OL&gt;
+ &lt;LI&gt;
+ The environment variable &lt;CODE&gt;TMPDIR&lt;/CODE&gt;, if it is defined. For security
+ reasons this only happens if the program is not SUID or SGID enabled.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt;
+ The &lt;VAR&gt;dir&lt;/VAR&gt; argument, if it is not a null pointer.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt;
+ The value of the &lt;CODE&gt;P_tmpdir&lt;/CODE&gt; macro.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt;
+ The directory &lt;TT&gt;/tmp&lt;/TT&gt;.
+ &lt;/OL&gt;
+ &lt;br&gt;&lt;br&gt; This function is defined for SVID compatibility.
+ &lt;br&gt;&lt;br&gt; 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 &lt;CODE&gt;tempnam&lt;/CODE&gt;, leading to a possible security hole. The
+ implementation generates names which can hardly be predicted, but when
+ opening the file you should use the &lt;CODE&gt;O_EXCL&lt;/CODE&gt; flag. Using
+ &lt;CODE&gt;tmpfile&lt;/CODE&gt; or &lt;CODE&gt;mkstemp&lt;/CODE&gt; is a safe way to avoid this problem.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-mktemp" type="function">
+ <function returntype="char *">
+ <prototype>
+ <parameter content="char *template"/>
+ </prototype>
+ <headers>
+ <header filename = "stdio.h"/>
+ <header filename = "stdlib.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;mktemp&lt;/CODE&gt; function generates a unique file name by modifying
+ &lt;VAR&gt;template&lt;/VAR&gt; as described above. If successful, it returns
+ &lt;VAR&gt;template&lt;/VAR&gt; as modified. If &lt;CODE&gt;mktemp&lt;/CODE&gt; cannot find a unique file
+ name, it makes &lt;VAR&gt;template&lt;/VAR&gt; an empty string and returns that. If
+ &lt;VAR&gt;template&lt;/VAR&gt; does not end with &lt;samp&gt;XXXXXX&lt;/samp&gt;, &lt;CODE&gt;mktemp&lt;/CODE&gt; returns a
+ null pointer.
+ &lt;br&gt;&lt;br&gt; 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 &lt;CODE&gt;mktemp&lt;/CODE&gt;, leading to a possible security hole. The
+ implementation generates names which can hardly be predicted, but when
+ opening the file you should use the &lt;CODE&gt;O_EXCL&lt;/CODE&gt; flag. Using
+ &lt;CODE&gt;mkstemp&lt;/CODE&gt; is a safe way to avoid this problem.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-mkstemp" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="char *template"/>
+ </prototype>
+ <headers>
+ <header filename = "stdlib.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;mkstemp&lt;/CODE&gt; function generates a unique file name just as
+ &lt;CODE&gt;mktemp&lt;/CODE&gt; does, but it also opens the file for you with &lt;CODE&gt;open&lt;/CODE&gt;
+ . If successful, it modifies
+ &lt;VAR&gt;template&lt;/VAR&gt; in place and returns a file descriptor for that file open
+ for reading and writing. If &lt;CODE&gt;mkstemp&lt;/CODE&gt; cannot create a
+ uniquely-named file, it returns &lt;CODE&gt;-1&lt;/CODE&gt;. If &lt;VAR&gt;template&lt;/VAR&gt; does not
+ end with &lt;samp&gt;XXXXXX&lt;/samp&gt;, &lt;CODE&gt;mkstemp&lt;/CODE&gt; returns &lt;CODE&gt;-1&lt;/CODE&gt; and does not
+ modify &lt;VAR&gt;template&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; The file is opened using mode &lt;CODE&gt;0600&lt;/CODE&gt;. If the file is meant to be
+ used by other users this mode must be changed explicitly.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-mkdtemp" type="function">
+ <function returntype="char *">
+ <prototype>
+ <parameter content="char *template"/>
+ </prototype>
+ <headers>
+ <header filename = "stdlib.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;mkdtemp&lt;/CODE&gt; function creates a directory with a unique name. If
+ it succeeds, it overwrites &lt;VAR&gt;template&lt;/VAR&gt; with the name of the
+ directory, and returns &lt;VAR&gt;template&lt;/VAR&gt;. As with &lt;CODE&gt;mktemp&lt;/CODE&gt; and
+ &lt;CODE&gt;mkstemp&lt;/CODE&gt;, &lt;VAR&gt;template&lt;/VAR&gt; should be a string ending with
+ &lt;samp&gt;XXXXXX&lt;/samp&gt;.
+ &lt;br&gt;&lt;br&gt; If &lt;CODE&gt;mkdtemp&lt;/CODE&gt; cannot create an uniquely named directory, it returns
+ &lt;CODE&gt;NULL&lt;/CODE&gt; and sets &lt;VAR&gt;errno&lt;/VAR&gt; appropriately. If &lt;VAR&gt;template&lt;/VAR&gt; does
+ not end with &lt;samp&gt;XXXXXX&lt;/samp&gt;, &lt;CODE&gt;mkdtemp&lt;/CODE&gt; returns &lt;CODE&gt;NULL&lt;/CODE&gt; and does
+ not modify &lt;VAR&gt;template&lt;/VAR&gt;. &lt;VAR&gt;errno&lt;/VAR&gt; will be set to &lt;CODE&gt;EINVAL&lt;/CODE&gt; in
+ this case.
+ &lt;br&gt;&lt;br&gt; The directory is created using mode &lt;CODE&gt;0700&lt;/CODE&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-strsignal" type="function">
+ <function returntype="char *">
+ <prototype>
+ <parameter content="int signum"/>
+ </prototype>
+ <headers>
+ <header filename = "signal.h"/>
+ <header filename = "string.h"/>
+ </headers>
+ <synopsis>
+ This function returns a pointer to a statically-allocated string
+ containing a message describing the signal &lt;VAR&gt;signum&lt;/VAR&gt;. 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.
+ &lt;br&gt;&lt;br&gt; This function is a GNU extension, declared in the header file
+ &lt;TT&gt;string.h&lt;/TT&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-psignal" type="function">
+ <function returntype="void">
+ <prototype>
+ <parameter content="int signum"/>
+ <parameter content="const char *message"/>
+ </prototype>
+ <headers>
+ <header filename = "signal.h"/>
+ </headers>
+ <synopsis>
+ This function prints a message describing the signal &lt;VAR&gt;signum&lt;/VAR&gt; to the
+ standard error output stream &lt;CODE&gt;stderr&lt;/CODE&gt;; see Standard Streams.
+ &lt;br&gt;&lt;br&gt; If you call &lt;CODE&gt;psignal&lt;/CODE&gt; with a &lt;VAR&gt;message&lt;/VAR&gt; that is either a null
+ pointer or an empty string, &lt;CODE&gt;psignal&lt;/CODE&gt; just prints the message
+ corresponding to &lt;VAR&gt;signum&lt;/VAR&gt;, adding a trailing newline.
+ &lt;br&gt;&lt;br&gt; If you supply a non-null &lt;VAR&gt;message&lt;/VAR&gt; argument, then &lt;CODE&gt;psignal&lt;/CODE&gt;
+ prefixes its output with this string. It adds a colon and a space
+ character to separate the &lt;VAR&gt;message&lt;/VAR&gt; from the string corresponding
+ to &lt;VAR&gt;signum&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; This function is a BSD feature, declared in the header file &lt;TT&gt;signal.h&lt;/TT&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="dtype-sighandler_t" type="dtype">
+ <structure>
+ </structure>
+ </construct>
+ <construct id="function-signal" type="function">
+ <function returntype="sighandler_t">
+ <prototype>
+ <parameter content="int signum"/>
+ <parameter content="sighandler_t action"/>
+ </prototype>
+ <headers>
+ <header filename = "signal.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;signal&lt;/CODE&gt; function establishes &lt;VAR&gt;action&lt;/VAR&gt; as the action for
+ the signal &lt;VAR&gt;signum&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; The first argument, &lt;VAR&gt;signum&lt;/VAR&gt;, 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.
+ &lt;br&gt;&lt;br&gt; The second argument, &lt;VAR&gt;action&lt;/VAR&gt;, specifies the action to use for the
+ signal &lt;VAR&gt;signum&lt;/VAR&gt;. This can be one of the following:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;SIG_DFL&lt;/CODE&gt;
+&lt;DD&gt;
+
+ action for a signal
+ &lt;CODE&gt;SIG_DFL&lt;/CODE&gt; specifies the default action for the particular signal.
+ The default actions for various kinds of signals are stated in
+ Standard Signals.
+ &lt;br&gt;&lt;br&gt; &lt;DT&gt;&lt;CODE&gt;SIG_IGN&lt;/CODE&gt;
+&lt;DD&gt;
+
+ action for a signal
+ &lt;CODE&gt;SIG_IGN&lt;/CODE&gt; specifies that the signal should be ignored.
+ &lt;br&gt;&lt;br&gt; Your program generally should not ignore signals that represent serious
+ events or that are normally used to request termination. You cannot
+ ignore the &lt;CODE&gt;SIGKILL&lt;/CODE&gt; or &lt;CODE&gt;SIGSTOP&lt;/CODE&gt; signals at all. You can
+ ignore program error signals like &lt;CODE&gt;SIGSEGV&lt;/CODE&gt;, but ignoring the error
+ won't enable the program to continue executing meaningfully. Ignoring
+ user requests such as &lt;CODE&gt;SIGINT&lt;/CODE&gt;, &lt;CODE&gt;SIGQUIT&lt;/CODE&gt;, and &lt;CODE&gt;SIGTSTP&lt;/CODE&gt;
+ is unfriendly.
+ &lt;br&gt;&lt;br&gt; 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.
+ .
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; &lt;VAR&gt;handler&lt;/VAR&gt;
+ Supply the address of a handler function in your program, to specify
+ running this handler as the way to deliver the signal.
+ &lt;br&gt;&lt;br&gt; For more information about defining signal handler functions,
+ see Defining Handlers.
+
+ &lt;br&gt;&lt;br&gt; If you set the action for a signal to &lt;CODE&gt;SIG_IGN&lt;/CODE&gt;, or if you set it
+ to &lt;CODE&gt;SIG_DFL&lt;/CODE&gt; 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.
+ &lt;br&gt;&lt;br&gt; The &lt;CODE&gt;signal&lt;/CODE&gt; function returns the action that was previously in
+ effect for the specified &lt;VAR&gt;signum&lt;/VAR&gt;. You can save this value and
+ restore it later by calling &lt;CODE&gt;signal&lt;/CODE&gt; again.
+ &lt;br&gt;&lt;br&gt; If &lt;CODE&gt;signal&lt;/CODE&gt; can't honor the request, it returns &lt;CODE&gt;SIG_ERR&lt;/CODE&gt;
+ instead. The following &lt;CODE&gt;errno&lt;/CODE&gt; error conditions are defined for
+ this function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;LI&gt; EINVAL
+ You specified an invalid &lt;VAR&gt;signum&lt;/VAR&gt;; or you tried to ignore or provide
+ a handler for &lt;CODE&gt;SIGKILL&lt;/CODE&gt; or &lt;CODE&gt;SIGSTOP&lt;/CODE&gt;.
+
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-sysv_signal" type="function">
+ <function returntype="sighandler_t">
+ <prototype>
+ <parameter content="int signum"/>
+ <parameter content="sighandler_t action"/>
+ </prototype>
+ <headers>
+ <header filename = "signal.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;sysv_signal&lt;/CODE&gt; implements the behavior of the standard
+ &lt;CODE&gt;signal&lt;/CODE&gt; function as found on SVID systems. The difference to BSD
+ systems is that the handler is deinstalled after a delivery of a signal.
+ &lt;br&gt;&lt;br&gt; Compatibility Note: As said above for &lt;CODE&gt;signal&lt;/CODE&gt;, this
+ function should be avoided when possible. &lt;CODE&gt;sigaction&lt;/CODE&gt; is the
+ preferred method.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-ssignal" type="function">
+ <function returntype="sighandler_t">
+ <prototype>
+ <parameter content="int signum"/>
+ <parameter content="sighandler_t action"/>
+ </prototype>
+ <headers>
+ <header filename = "signal.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;ssignal&lt;/CODE&gt; function does the same thing as &lt;CODE&gt;signal&lt;/CODE&gt;; it is
+ provided only for compatibility with SVID.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="struct-sigaction" type="struct">
+ <structure>
+ <synopsis>
+ Structures of type &lt;CODE&gt;struct sigaction&lt;/CODE&gt; are used in the
+ &lt;CODE&gt;sigaction&lt;/CODE&gt; function to specify all the information about how to
+ handle a particular signal. This structure contains at least the
+ following members:
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ <elements>
+ <element content="sighandler_t sa_handler">
+ <synopsis>
+ This is used in the same way as the &lt;VAR&gt;action&lt;/VAR&gt; argument to the
+ &lt;CODE&gt;signal&lt;/CODE&gt; function. The value can be &lt;CODE&gt;SIG_DFL&lt;/CODE&gt;,
+ &lt;CODE&gt;SIG_IGN&lt;/CODE&gt;, or a function pointer. .
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="sigset_t sa_mask">
+ <synopsis>
+ This specifies a set of signals to be blocked while the handler runs.
+ Blocking is explained in Blocking for Handler. Note that the
+ signal that was delivered is automatically blocked by default before its
+ handler is started; this is true regardless of the value in
+ &lt;CODE&gt;sa_mask&lt;/CODE&gt;. If you want that signal not to be blocked within its
+ handler, you must write code in the handler to unblock it.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ </elements>
+ </structure>
+ </construct>
+ <construct id="function-sigaction" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="int signum"/>
+ <parameter content="const struct sigaction *restrict action"/>
+ <parameter content="struct sigaction *restrict old-action"/>
+ </prototype>
+ <headers>
+ <header filename = "signal.h"/>
+ </headers>
+ <synopsis>
+ The &lt;VAR&gt;action&lt;/VAR&gt; argument is used to set up a new action for the signal
+ &lt;VAR&gt;signum&lt;/VAR&gt;, while the &lt;VAR&gt;old-action&lt;/VAR&gt; argument is used to return
+ information about the action previously associated with this symbol.
+ (In other words, &lt;VAR&gt;old-action&lt;/VAR&gt; has the same purpose as the
+ &lt;CODE&gt;signal&lt;/CODE&gt; 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.)
+ &lt;br&gt;&lt;br&gt; Either &lt;VAR&gt;action&lt;/VAR&gt; or &lt;VAR&gt;old-action&lt;/VAR&gt; can be a null pointer. If
+ &lt;VAR&gt;old-action&lt;/VAR&gt; is a null pointer, this simply suppresses the return
+ of information about the old action. If &lt;VAR&gt;action&lt;/VAR&gt; is a null pointer,
+ the action associated with the signal &lt;VAR&gt;signum&lt;/VAR&gt; is unchanged; this
+ allows you to inquire about how a signal is being handled without changing
+ that handling.
+ &lt;br&gt;&lt;br&gt; The return value from &lt;CODE&gt;sigaction&lt;/CODE&gt; is zero if it succeeds, and
+ &lt;CODE&gt;-1&lt;/CODE&gt; on failure. The following &lt;CODE&gt;errno&lt;/CODE&gt; error conditions are
+ defined for this function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EINVAL&lt;/CODE&gt;
+&lt;DD&gt;
+ The &lt;VAR&gt;signum&lt;/VAR&gt; argument is not valid, or you are trying to
+ trap or ignore &lt;CODE&gt;SIGKILL&lt;/CODE&gt; or &lt;CODE&gt;SIGSTOP&lt;/CODE&gt;.
+
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="dtype-sig_atomic_t" type="dtype">
+ <structure>
+ </structure>
+ </construct>
+ <construct id="function-raise" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="int signum"/>
+ </prototype>
+ <headers>
+ <header filename = "signal.h"/>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;raise&lt;/CODE&gt; function sends the signal &lt;VAR&gt;signum&lt;/VAR&gt; 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 &lt;VAR&gt;signum&lt;/VAR&gt;
+ is invalid.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-gsignal" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="int signum"/>
+ </prototype>
+ <headers>
+ <header filename = "signal.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;gsignal&lt;/CODE&gt; function does the same thing as &lt;CODE&gt;raise&lt;/CODE&gt;; it is
+ provided only for compatibility with SVID.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-kill" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="pid_t pid"/>
+ <parameter content="int signum"/>
+ </prototype>
+ <headers>
+ <header filename = "signal.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;kill&lt;/CODE&gt; function sends the signal &lt;VAR&gt;signum&lt;/VAR&gt; to the process
+ or process group specified by &lt;VAR&gt;pid&lt;/VAR&gt;. Besides the signals listed in
+ Standard Signals, &lt;VAR&gt;signum&lt;/VAR&gt; can also have a value of zero to
+ check the validity of the &lt;VAR&gt;pid&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; The &lt;VAR&gt;pid&lt;/VAR&gt; specifies the process or process group to receive the
+ signal:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;&lt;VAR&gt;pid&lt;/VAR&gt; &gt; 0&lt;/CODE&gt;
+&lt;DD&gt;
+ The process whose identifier is &lt;VAR&gt;pid&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; &lt;DT&gt;&lt;CODE&gt;&lt;VAR&gt;pid&lt;/VAR&gt; == 0&lt;/CODE&gt;
+&lt;DD&gt;
+ All processes in the same process group as the sender.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; &lt;VAR&gt;pid&lt;/VAR&gt; &lt; -1
+ The process group whose identifier is &lt;VAR&gt;pid&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; &lt;VAR&gt;pid&lt;/VAR&gt; == -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.
+
+ &lt;br&gt;&lt;br&gt; A process can send a signal to itself with a call like &lt;CODE&gt;kill
+ (getpid(), &lt;VAR&gt;signum&lt;/VAR&gt;)&lt;/CODE&gt;. If &lt;CODE&gt;kill&lt;/CODE&gt; is used by a process to send
+ a signal to itself, and the signal is not blocked, then &lt;CODE&gt;kill&lt;/CODE&gt;
+ delivers at least one signal (which might be some other pending
+ unblocked signal instead of the signal &lt;VAR&gt;signum&lt;/VAR&gt;) to that process
+ before it returns.
+ &lt;br&gt;&lt;br&gt; The return value from &lt;CODE&gt;kill&lt;/CODE&gt; is zero if the signal can be sent
+ successfully. Otherwise, no signal is sent, and a value of &lt;CODE&gt;-1&lt;/CODE&gt; is
+ returned. If &lt;VAR&gt;pid&lt;/VAR&gt; specifies sending a signal to several processes,
+ &lt;CODE&gt;kill&lt;/CODE&gt; 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.
+ &lt;br&gt;&lt;br&gt; The following &lt;CODE&gt;errno&lt;/CODE&gt; error conditions are defined for this function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;LI&gt; EINVAL
+ The &lt;VAR&gt;signum&lt;/VAR&gt; argument is an invalid or unsupported number.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; 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 &lt;VAR&gt;pid&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ESRCH
+ The &lt;VAR&gt;pid&lt;/VAR&gt; argument does not refer to an existing process or group.
+
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-killpg" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="int pgid"/>
+ <parameter content="int signum"/>
+ </prototype>
+ <headers>
+ <header filename = "signal.h"/>
+ </headers>
+ <synopsis>
+ This is similar to &lt;CODE&gt;kill&lt;/CODE&gt;, but sends signal &lt;VAR&gt;signum&lt;/VAR&gt; to the
+ process group &lt;VAR&gt;pgid&lt;/VAR&gt;. This function is provided for compatibility
+ with BSD; using &lt;CODE&gt;kill&lt;/CODE&gt; to do this is more portable.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="dtype-sigset_t" type="dtype">
+ <structure>
+ </structure>
+ </construct>
+ <construct id="function-sigemptyset" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="sigset_t *set"/>
+ </prototype>
+ <headers>
+ <header filename = "signal.h"/>
+ </headers>
+ <synopsis>
+ This function initializes the signal set &lt;VAR&gt;set&lt;/VAR&gt; to exclude all of the
+ defined signals. It always returns &lt;CODE&gt;0&lt;/CODE&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-sigfillset" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="sigset_t *set"/>
+ </prototype>
+ <headers>
+ <header filename = "signal.h"/>
+ </headers>
+ <synopsis>
+ This function initializes the signal set &lt;VAR&gt;set&lt;/VAR&gt; to include
+ all of the defined signals. Again, the return value is &lt;CODE&gt;0&lt;/CODE&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-sigaddset" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="sigset_t *set"/>
+ <parameter content="int signum"/>
+ </prototype>
+ <headers>
+ <header filename = "signal.h"/>
+ </headers>
+ <synopsis>
+ This function adds the signal &lt;VAR&gt;signum&lt;/VAR&gt; to the signal set &lt;VAR&gt;set&lt;/VAR&gt;.
+ All &lt;CODE&gt;sigaddset&lt;/CODE&gt; does is modify &lt;VAR&gt;set&lt;/VAR&gt;; it does not block or
+ unblock any signals.
+ &lt;br&gt;&lt;br&gt; The return value is &lt;CODE&gt;0&lt;/CODE&gt; on success and &lt;CODE&gt;-1&lt;/CODE&gt; on failure.
+ The following &lt;CODE&gt;errno&lt;/CODE&gt; error condition is defined for this function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EINVAL&lt;/CODE&gt;
+&lt;DD&gt;
+ The &lt;VAR&gt;signum&lt;/VAR&gt; argument doesn't specify a valid signal.
+
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-sigdelset" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="sigset_t *set"/>
+ <parameter content="int signum"/>
+ </prototype>
+ <headers>
+ <header filename = "signal.h"/>
+ </headers>
+ <synopsis>
+ This function removes the signal &lt;VAR&gt;signum&lt;/VAR&gt; from the signal set
+ &lt;VAR&gt;set&lt;/VAR&gt;. All &lt;CODE&gt;sigdelset&lt;/CODE&gt; does is modify &lt;VAR&gt;set&lt;/VAR&gt;; it does not
+ block or unblock any signals. The return value and error conditions are
+ the same as for &lt;CODE&gt;sigaddset&lt;/CODE&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-sigismember" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const sigset_t *set"/>
+ <parameter content="int signum"/>
+ </prototype>
+ <headers>
+ <header filename = "signal.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;sigismember&lt;/CODE&gt; function tests whether the signal &lt;VAR&gt;signum&lt;/VAR&gt; is
+ a member of the signal set &lt;VAR&gt;set&lt;/VAR&gt;. It returns &lt;CODE&gt;1&lt;/CODE&gt; if the signal
+ is in the set, &lt;CODE&gt;0&lt;/CODE&gt; if not, and &lt;CODE&gt;-1&lt;/CODE&gt; if there is an error.
+ &lt;br&gt;&lt;br&gt; The following &lt;CODE&gt;errno&lt;/CODE&gt; error condition is defined for this function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EINVAL&lt;/CODE&gt;
+&lt;DD&gt;
+ The &lt;VAR&gt;signum&lt;/VAR&gt; argument doesn't specify a valid signal.
+
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-sigprocmask" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="int how"/>
+ <parameter content="const sigset_t *restrict set"/>
+ <parameter content="sigset_t *restrict oldset"/>
+ </prototype>
+ <headers>
+ <header filename = "signal.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;sigprocmask&lt;/CODE&gt; function is used to examine or change the calling
+ process's signal mask. The &lt;VAR&gt;how&lt;/VAR&gt; argument determines how the signal
+ mask is changed, and must be one of the following values:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+
+ &lt;DT&gt;&lt;CODE&gt;SIG_BLOCK&lt;/CODE&gt;
+&lt;DD&gt;
+ Block the signals in &lt;CODE&gt;set&lt;/CODE&gt;---add them to the existing mask. In
+ other words, the new mask is the union of the existing mask and
+ &lt;VAR&gt;set&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt;
+ &lt;DT&gt;&lt;CODE&gt;SIG_UNBLOCK&lt;/CODE&gt;
+&lt;DD&gt;
+ Unblock the signals in &lt;VAR&gt;set&lt;/VAR&gt;---remove them from the existing mask.
+ &lt;br&gt;&lt;br&gt;
+ &lt;LI&gt; SIG_SETMASK
+ Use &lt;VAR&gt;set&lt;/VAR&gt; for the mask; ignore the previous value of the mask.
+
+ &lt;br&gt;&lt;br&gt; The last argument, &lt;VAR&gt;oldset&lt;/VAR&gt;, 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 &lt;VAR&gt;oldset&lt;/VAR&gt; argument.
+ Similarly, if you want to know what's in the mask without changing it,
+ pass a null pointer for &lt;VAR&gt;set&lt;/VAR&gt; (in this case the &lt;VAR&gt;how&lt;/VAR&gt; argument
+ is not significant). The &lt;VAR&gt;oldset&lt;/VAR&gt; argument is often used to
+ remember the previous signal mask in order to restore it later. (Since
+ the signal mask is inherited over &lt;CODE&gt;fork&lt;/CODE&gt; and &lt;CODE&gt;exec&lt;/CODE&gt; calls, you
+ can't predict what its contents are when your program starts running.)
+ &lt;br&gt;&lt;br&gt; If invoking &lt;CODE&gt;sigprocmask&lt;/CODE&gt; causes any pending signals to be
+ unblocked, at least one of those signals is delivered to the process
+ before &lt;CODE&gt;sigprocmask&lt;/CODE&gt; returns. The order in which pending signals
+ are delivered is not specified, but you can control the order explicitly
+ by making multiple &lt;CODE&gt;sigprocmask&lt;/CODE&gt; calls to unblock various signals
+ one at a time.
+ &lt;br&gt;&lt;br&gt; The &lt;CODE&gt;sigprocmask&lt;/CODE&gt; function returns &lt;CODE&gt;0&lt;/CODE&gt; if successful, and &lt;CODE&gt;-1&lt;/CODE&gt;
+ to indicate an error. The following &lt;CODE&gt;errno&lt;/CODE&gt; error conditions are
+ defined for this function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;LI&gt; EINVAL
+ The &lt;VAR&gt;how&lt;/VAR&gt; argument is invalid.
+
+ &lt;br&gt;&lt;br&gt; You can't block the &lt;CODE&gt;SIGKILL&lt;/CODE&gt; and &lt;CODE&gt;SIGSTOP&lt;/CODE&gt; signals, but
+ if the signal set includes these, &lt;CODE&gt;sigprocmask&lt;/CODE&gt; just ignores
+ them instead of returning an error status.
+ &lt;br&gt;&lt;br&gt; Remember, too, that blocking program error signals such as &lt;CODE&gt;SIGFPE&lt;/CODE&gt;
+ leads to undesirable results for signals generated by an actual program
+ error (as opposed to signals sent with &lt;CODE&gt;raise&lt;/CODE&gt; or &lt;CODE&gt;kill&lt;/CODE&gt;).
+ This is because your program may be too broken to be able to continue
+ executing to a point where the signal is unblocked again.
+ .
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-sigpending" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="sigset_t *set"/>
+ </prototype>
+ <headers>
+ <header filename = "signal.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;sigpending&lt;/CODE&gt; function stores information about pending signals
+ in &lt;VAR&gt;set&lt;/VAR&gt;. 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
+ &lt;CODE&gt;sigismember&lt;/CODE&gt;; see Signal Sets.)
+ &lt;br&gt;&lt;br&gt; The return value is &lt;CODE&gt;0&lt;/CODE&gt; if successful, and &lt;CODE&gt;-1&lt;/CODE&gt; on failure.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-pause" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content=""/>
+ </prototype>
+ <headers>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;pause&lt;/CODE&gt; function suspends program execution until a signal
+ arrives whose action is either to execute a handler function, or to
+ terminate the process.
+ &lt;br&gt;&lt;br&gt; If the signal causes a handler function to be executed, then
+ &lt;CODE&gt;pause&lt;/CODE&gt; returns. This is considered an unsuccessful return (since
+ ``successful'' behavior would be to suspend the program forever), so the
+ return value is &lt;CODE&gt;-1&lt;/CODE&gt;. Even if you specify that other primitives
+ should resume when a system handler returns , this has no effect on &lt;CODE&gt;pause&lt;/CODE&gt;; it always fails when a
+ signal is handled.
+ &lt;br&gt;&lt;br&gt; The following &lt;CODE&gt;errno&lt;/CODE&gt; error conditions are defined for this function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EINTR&lt;/CODE&gt;
+&lt;DD&gt;
+ The function was interrupted by delivery of a signal.
+
+ &lt;br&gt;&lt;br&gt; If the signal causes program termination, &lt;CODE&gt;pause&lt;/CODE&gt; doesn't return
+ (obviously).
+ &lt;br&gt;&lt;br&gt; 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 &lt;CODE&gt;pause&lt;/CODE&gt; is
+ called. If the thread gets cancelled these resources stay allocated
+ until the program ends. To avoid this calls to &lt;CODE&gt;pause&lt;/CODE&gt; should be
+ protected using cancellation handlers.
+ &lt;br&gt;&lt;br&gt; The &lt;CODE&gt;pause&lt;/CODE&gt; function is declared in &lt;TT&gt;unistd.h&lt;/TT&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-sigsuspend" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const sigset_t *set"/>
+ </prototype>
+ <headers>
+ <header filename = "signal.h"/>
+ </headers>
+ <synopsis>
+ This function replaces the process's signal mask with &lt;VAR&gt;set&lt;/VAR&gt; 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 &lt;VAR&gt;set&lt;/VAR&gt; arrives.
+ &lt;br&gt;&lt;br&gt; If the process is woken up by delivery of a signal that invokes a handler
+ function, and the handler function returns, then &lt;CODE&gt;sigsuspend&lt;/CODE&gt; also
+ returns.
+ &lt;br&gt;&lt;br&gt; The mask remains &lt;VAR&gt;set&lt;/VAR&gt; only as long as &lt;CODE&gt;sigsuspend&lt;/CODE&gt; is waiting.
+ The function &lt;CODE&gt;sigsuspend&lt;/CODE&gt; always restores the previous signal mask
+ when it returns.
+ &lt;br&gt;&lt;br&gt; The return value and error conditions are the same as for &lt;CODE&gt;pause&lt;/CODE&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="dtype-stack_t" type="dtype">
+ <structure>
+ <synopsis>
+ This structure describes a signal stack. It contains the following members:
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ <elements>
+ <element content="void *ss_sp">
+ <synopsis>
+ This points to the base of the signal stack.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="size_t ss_size">
+ <synopsis>
+ This is the size (in bytes) of the signal stack which &lt;samp&gt;ss_sp&lt;/samp&gt; points to.
+ You should set this to however much space you allocated for the stack.
+ &lt;br&gt;&lt;br&gt; There are two macros defined in &lt;TT&gt;signal.h&lt;/TT&gt; that you should use in
+ calculating this size:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ </synopsis>
+ </element>
+ <element content="SIGSTKSZ">
+ <synopsis>
+ This is the canonical size for a signal stack. It is judged to be
+ sufficient for normal uses.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="MINSIGSTKSZ">
+ <synopsis>
+ This is the amount of signal stack space the operating system needs just
+ to implement signal delivery. The size of a signal stack &lt;h3&gt;must&lt;/h3&gt;
+ be greater than this.
+ &lt;br&gt;&lt;br&gt; For most cases, just using &lt;CODE&gt;SIGSTKSZ&lt;/CODE&gt; for &lt;CODE&gt;ss_size&lt;/CODE&gt; is
+ sufficient. But if you know how much stack space your program's signal
+ handlers will need, you may want to use a different size. In this case,
+ you should allocate &lt;CODE&gt;MINSIGSTKSZ&lt;/CODE&gt; additional bytes for the signal
+ stack and increase &lt;CODE&gt;ss_size&lt;/CODE&gt; accordingly.
+ &lt;/DL&gt;
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="int ss_flags">
+ <synopsis>
+ This field contains the bitwise or of these flags:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ </synopsis>
+ </element>
+ <element content="SS_DISABLE">
+ <synopsis>
+ This tells the system that it should not use the signal stack.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ </elements>
+ </structure>
+ </construct>
+ <construct id="function-sigaltstack" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const stack_t *restrict stack"/>
+ <parameter content="stack_t *restrict oldstack"/>
+ </prototype>
+ <headers>
+ <header filename = "signal.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;sigaltstack&lt;/CODE&gt; 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.
+ &lt;br&gt;&lt;br&gt; If &lt;VAR&gt;oldstack&lt;/VAR&gt; is not a null pointer, information about the currently
+ installed signal stack is returned in the location it points to. If
+ &lt;VAR&gt;stack&lt;/VAR&gt; is not a null pointer, then this is installed as the new
+ stack for use by signal handlers.
+ &lt;br&gt;&lt;br&gt; The return value is &lt;CODE&gt;0&lt;/CODE&gt; on success and &lt;CODE&gt;-1&lt;/CODE&gt; on failure. If
+ &lt;CODE&gt;sigaltstack&lt;/CODE&gt; fails, it sets &lt;CODE&gt;errno&lt;/CODE&gt; to one of these values:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EINVAL&lt;/CODE&gt;
+&lt;DD&gt;
+ You tried to disable a stack that was in fact currently in use.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ENOMEM
+ The size of the alternate stack was too small.
+ It must be greater than &lt;CODE&gt;MINSIGSTKSZ&lt;/CODE&gt;.
+
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="struct-sigstack" type="struct">
+ <structure>
+ <synopsis>
+ This structure describes a signal stack. It contains the following members:
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ <elements>
+ <element content="void *ss_sp">
+ <synopsis>
+ This is the stack pointer. If the stack grows downwards on your
+ machine, this should point to the top of the area you allocated. If the
+ stack grows upwards, it should point to the bottom.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ </elements>
+ </structure>
+ </construct>
+ <construct id="function-sigstack" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const struct sigstack *stack"/>
+ <parameter content="struct sigstack *oldstack"/>
+ </prototype>
+ <headers>
+ <header filename = "signal.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;sigstack&lt;/CODE&gt; 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.
+ &lt;br&gt;&lt;br&gt; If &lt;VAR&gt;oldstack&lt;/VAR&gt; is not a null pointer, information about the currently
+ installed signal stack is returned in the location it points to. If
+ &lt;VAR&gt;stack&lt;/VAR&gt; is not a null pointer, then this is installed as the new
+ stack for use by signal handlers.
+ &lt;br&gt;&lt;br&gt; The return value is &lt;CODE&gt;0&lt;/CODE&gt; on success and &lt;CODE&gt;-1&lt;/CODE&gt; on failure.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="struct-sigvec" type="struct">
+ <structure>
+ <synopsis>
+ This data type is the BSD equivalent of &lt;CODE&gt;struct sigaction&lt;/CODE&gt;
+ ; it is used to specify signal actions
+ to the &lt;CODE&gt;sigvec&lt;/CODE&gt; function. It contains the following members:
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ <elements>
+ <element content="sighandler_t sv_handler">
+ <synopsis>
+ This is the handler function.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="int sv_mask">
+ <synopsis>
+ This is the mask of additional signals to be blocked while the handler
+ function is being called.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ </elements>
+ </structure>
+ </construct>
+ <construct id="function-sigvec" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="int signum"/>
+ <parameter content="const struct sigvec *action,struct sigvec *old-action"/>
+ </prototype>
+ <headers>
+ <header filename = "signal.h"/>
+ </headers>
+ <synopsis>
+ This function is the equivalent of &lt;CODE&gt;sigaction&lt;/CODE&gt; ; it installs the action &lt;VAR&gt;action&lt;/VAR&gt; for the signal &lt;VAR&gt;signum&lt;/VAR&gt;,
+ returning information about the previous action in effect for that signal
+ in &lt;VAR&gt;old-action&lt;/VAR&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-siginterrupt" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="int signum"/>
+ <parameter content="int failflag"/>
+ </prototype>
+ <headers>
+ <header filename = "signal.h"/>
+ </headers>
+ <synopsis>
+ This function specifies which approach to use when certain primitives
+ are interrupted by handling signal &lt;VAR&gt;signum&lt;/VAR&gt;. If &lt;VAR&gt;failflag&lt;/VAR&gt; is
+ false, signal &lt;VAR&gt;signum&lt;/VAR&gt; restarts primitives. If &lt;VAR&gt;failflag&lt;/VAR&gt; is
+ true, handling &lt;VAR&gt;signum&lt;/VAR&gt; causes these primitives to fail with error
+ code &lt;CODE&gt;EINTR&lt;/CODE&gt;. .
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-sigblock" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="int mask"/>
+ </prototype>
+ <headers>
+ <header filename = "signal.h"/>
+ </headers>
+ <synopsis>
+ This function is equivalent to &lt;CODE&gt;sigprocmask&lt;/CODE&gt; with a &lt;VAR&gt;how&lt;/VAR&gt; argument of &lt;CODE&gt;SIG_BLOCK&lt;/CODE&gt;: it adds the
+ signals specified by &lt;VAR&gt;mask&lt;/VAR&gt; to the calling process's set of blocked
+ signals. The return value is the previous set of blocked signals.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-sigsetmask" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="int mask"/>
+ </prototype>
+ <headers>
+ <header filename = "signal.h"/>
+ </headers>
+ <synopsis>
+ This function equivalent to &lt;CODE&gt;sigprocmask&lt;/CODE&gt; with a &lt;VAR&gt;how&lt;/VAR&gt; argument of &lt;CODE&gt;SIG_SETMASK&lt;/CODE&gt;: it sets
+ the calling process's signal mask to &lt;VAR&gt;mask&lt;/VAR&gt;. The return value is
+ the previous set of blocked signals.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-sigpause" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="int mask"/>
+ </prototype>
+ <headers>
+ <header filename = "signal.h"/>
+ </headers>
+ <synopsis>
+ This function is the equivalent of &lt;CODE&gt;sigsuspend&lt;/CODE&gt; : it sets the calling process's signal mask to &lt;VAR&gt;mask&lt;/VAR&gt;,
+ and waits for a signal to arrive. On return the previous set of blocked
+ signals is restored.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-pipe" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="int filedes[2]"/>
+ </prototype>
+ <headers>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;pipe&lt;/CODE&gt; function creates a pipe and puts the file descriptors
+ for the reading and writing ends of the pipe (respectively) into
+ &lt;CODE&gt;&lt;VAR&gt;filedes&lt;/VAR&gt;[0]&lt;/CODE&gt; and &lt;CODE&gt;&lt;VAR&gt;filedes&lt;/VAR&gt;[1]&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; An easy way to remember that the input end comes first is that file
+ descriptor &lt;CODE&gt;0&lt;/CODE&gt; is standard input, and file descriptor &lt;CODE&gt;1&lt;/CODE&gt; is
+ standard output.
+ &lt;br&gt;&lt;br&gt; If successful, &lt;CODE&gt;pipe&lt;/CODE&gt; returns a value of &lt;CODE&gt;0&lt;/CODE&gt;. On failure,
+ &lt;CODE&gt;-1&lt;/CODE&gt; is returned. The following &lt;CODE&gt;errno&lt;/CODE&gt; error conditions are
+ defined for this function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EMFILE&lt;/CODE&gt;
+&lt;DD&gt;
+ The process has too many files open.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ENFILE
+ There are too many open files in the entire system. ,
+ for more information about &lt;CODE&gt;ENFILE&lt;/CODE&gt;. This error never occurs in
+ the GNU system.
+
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-popen" type="function">
+ <function returntype="FILE *">
+ <prototype>
+ <parameter content="const char *command"/>
+ <parameter content="const char *mode"/>
+ </prototype>
+ <headers>
+ <header filename = "stdio.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;popen&lt;/CODE&gt; function is closely related to the &lt;CODE&gt;system&lt;/CODE&gt;
+ function; see Running a Command. It executes the shell command
+ &lt;VAR&gt;command&lt;/VAR&gt; 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.
+ &lt;br&gt;&lt;br&gt; If you specify a &lt;VAR&gt;mode&lt;/VAR&gt; argument of &lt;CODE&gt;"r"&lt;/CODE&gt;, 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.
+ &lt;br&gt;&lt;br&gt; Similarly, if you specify a &lt;VAR&gt;mode&lt;/VAR&gt; argument of &lt;CODE&gt;"w"&lt;/CODE&gt;, 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.
+ &lt;br&gt;&lt;br&gt; In the event of an error &lt;CODE&gt;popen&lt;/CODE&gt; 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.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-pclose" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="FILE *stream"/>
+ </prototype>
+ <headers>
+ <header filename = "stdio.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;pclose&lt;/CODE&gt; function is used to close a stream created by &lt;CODE&gt;popen&lt;/CODE&gt;.
+ It waits for the child process to terminate and returns its status value,
+ as for the &lt;CODE&gt;system&lt;/CODE&gt; function.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-mkfifo" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *filename"/>
+ <parameter content="mode_t mode"/>
+ </prototype>
+ <headers>
+ <header filename = "sys/stat.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;mkfifo&lt;/CODE&gt; function makes a FIFO special file with name
+ &lt;VAR&gt;filename&lt;/VAR&gt;. The &lt;VAR&gt;mode&lt;/VAR&gt; argument is used to set the file's
+ permissions; see Setting Permissions.
+ &lt;br&gt;&lt;br&gt; The normal, successful return value from &lt;CODE&gt;mkfifo&lt;/CODE&gt; is &lt;CODE&gt;0&lt;/CODE&gt;. In
+ the case of an error, &lt;CODE&gt;-1&lt;/CODE&gt; is returned. In addition to the usual
+ file name errors , the following
+ &lt;CODE&gt;errno&lt;/CODE&gt; error conditions are defined for this function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EEXIST&lt;/CODE&gt;
+&lt;DD&gt;
+ The named file already exists.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ENOSPC
+ The directory or file system cannot be extended.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EROFS
+ The directory that would contain the file resides on a read-only file
+ system.
+
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-strerror" type="function">
+ <function returntype="char *">
+ <prototype>
+ <parameter content="int errnum"/>
+ </prototype>
+ <headers>
+ <header filename = "errno.h"/>
+ <header filename = "string.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;strerror&lt;/CODE&gt; function maps the error code specified by the &lt;VAR&gt;errnum&lt;/VAR&gt; argument to a descriptive error
+ message string. The return value is a pointer to this string.
+ &lt;br&gt;&lt;br&gt; The value &lt;VAR&gt;errnum&lt;/VAR&gt; normally comes from the variable &lt;CODE&gt;errno&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; You should not modify the string returned by &lt;CODE&gt;strerror&lt;/CODE&gt;. Also, if
+ you make subsequent calls to &lt;CODE&gt;strerror&lt;/CODE&gt;, the string might be
+ overwritten. (But it's guaranteed that no library function ever calls
+ &lt;CODE&gt;strerror&lt;/CODE&gt; behind your back.)
+ &lt;br&gt;&lt;br&gt; The function &lt;CODE&gt;strerror&lt;/CODE&gt; is declared in &lt;TT&gt;string.h&lt;/TT&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-strerror_r" type="function">
+ <function returntype="char *">
+ <prototype>
+ <parameter content="int errnum"/>
+ <parameter content="char *buf"/>
+ <parameter content="size_t n"/>
+ </prototype>
+ <headers>
+ <header filename = "string.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;strerror_r&lt;/CODE&gt; function works like &lt;CODE&gt;strerror&lt;/CODE&gt; 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 &lt;VAR&gt;buf&lt;/VAR&gt; with the
+ length of &lt;VAR&gt;n&lt;/VAR&gt; bytes.
+ &lt;br&gt;&lt;br&gt; At most &lt;VAR&gt;n&lt;/VAR&gt; characters are written (including the NUL byte) so it is
+ up to the user to select the buffer large enough.
+ &lt;br&gt;&lt;br&gt; This function should always be used in multi-threaded programs since
+ there is no way to guarantee the string returned by &lt;CODE&gt;strerror&lt;/CODE&gt;
+ really belongs to the last call of the current thread.
+ &lt;br&gt;&lt;br&gt; This function &lt;CODE&gt;strerror_r&lt;/CODE&gt; is a GNU extension and it is declared in
+ &lt;TT&gt;string.h&lt;/TT&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-perror" type="function">
+ <function returntype="void">
+ <prototype>
+ <parameter content="const char *message"/>
+ </prototype>
+ <headers>
+ <header filename = "stdio.h"/>
+ </headers>
+ <synopsis>
+ This function prints an error message to the stream &lt;CODE&gt;stderr&lt;/CODE&gt;;
+ see Standard Streams. The orientation of &lt;CODE&gt;stderr&lt;/CODE&gt; is not
+ changed.
+ &lt;br&gt;&lt;br&gt; If you call &lt;CODE&gt;perror&lt;/CODE&gt; with a &lt;VAR&gt;message&lt;/VAR&gt; that is either a null
+ pointer or an empty string, &lt;CODE&gt;perror&lt;/CODE&gt; just prints the error message
+ corresponding to &lt;CODE&gt;errno&lt;/CODE&gt;, adding a trailing newline.
+ &lt;br&gt;&lt;br&gt; If you supply a non-null &lt;VAR&gt;message&lt;/VAR&gt; argument, then &lt;CODE&gt;perror&lt;/CODE&gt;
+ prefixes its output with this string. It adds a colon and a space
+ character to separate the &lt;VAR&gt;message&lt;/VAR&gt; from the error string corresponding
+ to &lt;CODE&gt;errno&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; The function &lt;CODE&gt;perror&lt;/CODE&gt; is declared in &lt;TT&gt;stdio.h&lt;/TT&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-error" type="function">
+ <function returntype="void">
+ <prototype>
+ <parameter content="int status"/>
+ <parameter content="int errnum"/>
+ <parameter content="const char *format"/>
+ <parameter content="..."/>
+ </prototype>
+ <headers>
+ <header filename = "errno.h"/>
+ <header filename = "error.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;error&lt;/CODE&gt; function can be used to report general problems during
+ program execution. The &lt;VAR&gt;format&lt;/VAR&gt; argument is a format string just
+ like those given to the &lt;CODE&gt;printf&lt;/CODE&gt; family of functions. The
+ arguments required for the format can follow the &lt;VAR&gt;format&lt;/VAR&gt; parameter.
+ Just like &lt;CODE&gt;perror&lt;/CODE&gt;, &lt;CODE&gt;error&lt;/CODE&gt; also can report an error code in
+ textual form. But unlike &lt;CODE&gt;perror&lt;/CODE&gt; the error value is explicitly
+ passed to the function in the &lt;VAR&gt;errnum&lt;/VAR&gt; parameter. This eliminates
+ the problem mentioned above that the error reporting function must be
+ called immediately after the function causing the error since otherwise
+ &lt;CODE&gt;errno&lt;/CODE&gt; might have a different value.
+ &lt;br&gt;&lt;br&gt; The &lt;CODE&gt;error&lt;/CODE&gt; prints first the program name. If the application
+ defined a global variable &lt;CODE&gt;error_print_progname&lt;/CODE&gt; and points it to a
+ function this function will be called to print the program name.
+ Otherwise the string from the global variable &lt;CODE&gt;program_name&lt;/CODE&gt; 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
+ &lt;VAR&gt;errnum&lt;/VAR&gt; 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
+ &lt;VAR&gt;errnum&lt;/VAR&gt;. In any case is the output terminated with a newline.
+ &lt;br&gt;&lt;br&gt; The output is directed to the &lt;CODE&gt;stderr&lt;/CODE&gt; stream. If the
+ &lt;CODE&gt;stderr&lt;/CODE&gt; wasn't oriented before the call it will be narrow-oriented
+ afterwards.
+ &lt;br&gt;&lt;br&gt; The function will return unless the &lt;VAR&gt;status&lt;/VAR&gt; parameter has a
+ non-zero value. In this case the function will call &lt;CODE&gt;exit&lt;/CODE&gt; with
+ the &lt;VAR&gt;status&lt;/VAR&gt; value for its parameter and therefore never return. If
+ &lt;CODE&gt;error&lt;/CODE&gt; returns the global variable &lt;CODE&gt;error_message_count&lt;/CODE&gt; is
+ incremented by one to keep track of the number of errors reported.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-error_at_line" type="function">
+ <function returntype="void">
+ <prototype>
+ <parameter content="int status"/>
+ <parameter content="int errnum"/>
+ <parameter content="const char *fname"/>
+ <parameter content="unsigned int lineno"/>
+ <parameter content="const char *format"/>
+ <parameter content="..."/>
+ </prototype>
+ <headers>
+ <header filename = "error.h"/>
+ </headers>
+ <synopsis>
+ &lt;br&gt;&lt;br&gt; The &lt;CODE&gt;error_at_line&lt;/CODE&gt; function is very similar to the &lt;CODE&gt;error&lt;/CODE&gt;
+ function. The only difference are the additional parameters &lt;VAR&gt;fname&lt;/VAR&gt;
+ and &lt;VAR&gt;lineno&lt;/VAR&gt;. The handling of the other parameters is identical to
+ that of &lt;CODE&gt;error&lt;/CODE&gt; except that between the program name and the string
+ generated by the format string additional text is inserted.
+ &lt;br&gt;&lt;br&gt; Directly following the program name a colon, followed by the file name
+ pointer to by &lt;VAR&gt;fname&lt;/VAR&gt;, another colon, and a value of &lt;VAR&gt;lineno&lt;/VAR&gt; is
+ printed.
+ &lt;br&gt;&lt;br&gt; 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).
+ &lt;br&gt;&lt;br&gt; If the global variable &lt;CODE&gt;error_one_per_line&lt;/CODE&gt; is set to a non-zero
+ value &lt;CODE&gt;error_at_line&lt;/CODE&gt; will avoid printing consecutive messages for
+ the same file and line. Repetition which are not directly following
+ each other are not caught.
+ &lt;br&gt;&lt;br&gt; Just like &lt;CODE&gt;error&lt;/CODE&gt; this function only returned if &lt;VAR&gt;status&lt;/VAR&gt; is
+ zero. Otherwise &lt;CODE&gt;exit&lt;/CODE&gt; is called with the non-zero value. If
+ &lt;CODE&gt;error&lt;/CODE&gt; returns the global variable &lt;CODE&gt;error_message_count&lt;/CODE&gt; is
+ incremented by one to keep track of the number of errors reported.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-warn" type="function">
+ <function returntype="void">
+ <prototype>
+ <parameter content="const char *format"/>
+ <parameter content="..."/>
+ </prototype>
+ <headers>
+ <header filename = "error.h"/>
+ <header filename = "err.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;warn&lt;/CODE&gt; function is roughly equivalent to a call like
+ &lt;pre&gt;&lt;br&gt;
+ error (0, errno, format, the parameters)&lt;br&gt;
+ &lt;/pre&gt;
+
+ except that the global variables &lt;CODE&gt;error&lt;/CODE&gt; respects and modifies
+ are not used.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-vwarn" type="function">
+ <function returntype="void">
+ <prototype>
+ <parameter content="const char *format"/>
+ <parameter content="va_list"/>
+ </prototype>
+ <headers>
+ <header filename = "err.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;vwarn&lt;/CODE&gt; function is just like &lt;CODE&gt;warn&lt;/CODE&gt; except that the
+ parameters for the handling of the format string &lt;VAR&gt;format&lt;/VAR&gt; are passed
+ in as an value of type &lt;CODE&gt;va_list&lt;/CODE&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-warnx" type="function">
+ <function returntype="void">
+ <prototype>
+ <parameter content="const char *format"/>
+ <parameter content="..."/>
+ </prototype>
+ <headers>
+ <header filename = "err.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;warnx&lt;/CODE&gt; function is roughly equivalent to a call like
+ &lt;pre&gt;&lt;br&gt;
+ error (0, 0, format, the parameters)&lt;br&gt;
+ &lt;/pre&gt;
+
+ except that the global variables &lt;CODE&gt;error&lt;/CODE&gt; respects and modifies
+ are not used. The difference to &lt;CODE&gt;warn&lt;/CODE&gt; is that no error number
+ string is printed.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-vwarnx" type="function">
+ <function returntype="void">
+ <prototype>
+ <parameter content="const char *format"/>
+ <parameter content="va_list"/>
+ </prototype>
+ <headers>
+ <header filename = "err.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;vwarnx&lt;/CODE&gt; function is just like &lt;CODE&gt;warnx&lt;/CODE&gt; except that the
+ parameters for the handling of the format string &lt;VAR&gt;format&lt;/VAR&gt; are passed
+ in as an value of type &lt;CODE&gt;va_list&lt;/CODE&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-err" type="function">
+ <function returntype="void">
+ <prototype>
+ <parameter content="int status"/>
+ <parameter content="const char *format"/>
+ <parameter content="..."/>
+ </prototype>
+ <headers>
+ <header filename = "err.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;err&lt;/CODE&gt; function is roughly equivalent to a call like
+ &lt;pre&gt;&lt;br&gt;
+ error (status, errno, format, the parameters)&lt;br&gt;
+ &lt;/pre&gt;
+
+ except that the global variables &lt;CODE&gt;error&lt;/CODE&gt; respects and modifies
+ are not used and that the program is exited even if &lt;VAR&gt;status&lt;/VAR&gt; is zero.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-verr" type="function">
+ <function returntype="void">
+ <prototype>
+ <parameter content="int status"/>
+ <parameter content="const char *format"/>
+ <parameter content="va_list"/>
+ </prototype>
+ <headers>
+ <header filename = "err.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;verr&lt;/CODE&gt; function is just like &lt;CODE&gt;err&lt;/CODE&gt; except that the
+ parameters for the handling of the format string &lt;VAR&gt;format&lt;/VAR&gt; are passed
+ in as an value of type &lt;CODE&gt;va_list&lt;/CODE&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-errx" type="function">
+ <function returntype="void">
+ <prototype>
+ <parameter content="int status"/>
+ <parameter content="const char *format"/>
+ <parameter content="..."/>
+ </prototype>
+ <headers>
+ <header filename = "err.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;errx&lt;/CODE&gt; function is roughly equivalent to a call like
+ &lt;pre&gt;&lt;br&gt;
+ error (status, 0, format, the parameters)&lt;br&gt;
+ &lt;/pre&gt;
+
+ except that the global variables &lt;CODE&gt;error&lt;/CODE&gt; respects and modifies
+ are not used and that the program is exited even if &lt;VAR&gt;status&lt;/VAR&gt;
+ is zero. The difference to &lt;CODE&gt;err&lt;/CODE&gt; is that no error number
+ string is printed.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-verrx" type="function">
+ <function returntype="void">
+ <prototype>
+ <parameter content="int status"/>
+ <parameter content="const char *format"/>
+ <parameter content="va_list"/>
+ </prototype>
+ <headers>
+ <header filename = "err.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;verrx&lt;/CODE&gt; function is just like &lt;CODE&gt;errx&lt;/CODE&gt; except that the
+ parameters for the handling of the format string &lt;VAR&gt;format&lt;/VAR&gt; are passed
+ in as an value of type &lt;CODE&gt;va_list&lt;/CODE&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-fnmatch" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *pattern"/>
+ <parameter content="const char *string"/>
+ <parameter content="int flags"/>
+ </prototype>
+ <headers>
+ <header filename = "fnmatch.h"/>
+ </headers>
+ <synopsis>
+ This function tests whether the string &lt;VAR&gt;string&lt;/VAR&gt; matches the pattern
+ &lt;VAR&gt;pattern&lt;/VAR&gt;. It returns &lt;CODE&gt;0&lt;/CODE&gt; if they do match; otherwise, it
+ returns the nonzero value &lt;CODE&gt;FNM_NOMATCH&lt;/CODE&gt;. The arguments
+ &lt;VAR&gt;pattern&lt;/VAR&gt; and &lt;VAR&gt;string&lt;/VAR&gt; are both strings.
+ &lt;br&gt;&lt;br&gt; The argument &lt;VAR&gt;flags&lt;/VAR&gt; is a combination of flag bits that alter the
+ details of matching. See below for a list of the defined flags.
+ &lt;br&gt;&lt;br&gt; In the GNU C Library, &lt;CODE&gt;fnmatch&lt;/CODE&gt; cannot experience an ``error''---it
+ always returns an answer for whether the match succeeds. However, other
+ implementations of &lt;CODE&gt;fnmatch&lt;/CODE&gt; might sometimes report ``errors''.
+ They would do so by returning nonzero values that are not equal to
+ &lt;CODE&gt;FNM_NOMATCH&lt;/CODE&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="dtype-glob_t" type="dtype">
+ <structure>
+ <synopsis>
+ This data type holds a pointer to a word vector. More precisely, it
+ records both the address of the word vector and its size. The GNU
+ implementation contains some more fields which are non-standard
+ extensions.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ <elements>
+ <element content="gl_pathc">
+ <synopsis>
+ The number of elements in the vector, excluding the initial null entries
+ if the GLOB_DOOFFS flag is used (see gl_offs below).
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="gl_pathv">
+ <synopsis>
+ The address of the vector. This field has type &lt;CODE&gt;char **&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="gl_offs">
+ <synopsis>
+ The offset of the first real element of the vector, from its nominal
+ address in the &lt;CODE&gt;gl_pathv&lt;/CODE&gt; field. Unlike the other fields, this
+ is always an input to &lt;CODE&gt;glob&lt;/CODE&gt;, rather than an output from it.
+ &lt;br&gt;&lt;br&gt; If you use a nonzero offset, then that many elements at the beginning of
+ the vector are left empty. (The &lt;CODE&gt;glob&lt;/CODE&gt; function fills them with
+ null pointers.)
+ &lt;br&gt;&lt;br&gt; The &lt;CODE&gt;gl_offs&lt;/CODE&gt; field is meaningful only if you use the
+ &lt;CODE&gt;GLOB_DOOFFS&lt;/CODE&gt; flag. Otherwise, the offset is always zero
+ regardless of what is in this field, and the first real element comes at
+ the beginning of the vector.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="gl_closedir">
+ <synopsis>
+ The address of an alternative implementation of the &lt;CODE&gt;closedir&lt;/CODE&gt;
+ function. It is used if the &lt;CODE&gt;GLOB_ALTDIRFUNC&lt;/CODE&gt; bit is set in
+ the flag parameter. The type of this field is
+ &lt;CODE&gt;void (*) (void *)&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; This is a GNU extension.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="gl_readdir">
+ <synopsis>
+ The address of an alternative implementation of the &lt;CODE&gt;readdir&lt;/CODE&gt;
+ function used to read the contents of a directory. It is used if the
+ &lt;CODE&gt;GLOB_ALTDIRFUNC&lt;/CODE&gt; bit is set in the flag parameter. The type of
+ this field is &lt;CODE&gt;struct dirent *(*) (void *)&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; This is a GNU extension.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="gl_opendir">
+ <synopsis>
+ The address of an alternative implementation of the &lt;CODE&gt;opendir&lt;/CODE&gt;
+ function. It is used if the &lt;CODE&gt;GLOB_ALTDIRFUNC&lt;/CODE&gt; bit is set in
+ the flag parameter. The type of this field is
+ &lt;CODE&gt;void *(*) (const char *)&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; This is a GNU extension.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="gl_stat">
+ <synopsis>
+ The address of an alternative implementation of the &lt;CODE&gt;stat&lt;/CODE&gt; function
+ to get information about an object in the filesystem. It is used if the
+ &lt;CODE&gt;GLOB_ALTDIRFUNC&lt;/CODE&gt; bit is set in the flag parameter. The type of
+ this field is &lt;CODE&gt;int (*) (const char *, struct stat *)&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; This is a GNU extension.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ </elements>
+ </structure>
+ </construct>
+ <construct id="dtype-glob64_t" type="dtype">
+ <structure>
+ <synopsis>
+ This data type holds a pointer to a word vector. More precisely, it
+ records both the address of the word vector and its size. The GNU
+ implementation contains some more fields which are non-standard
+ extensions.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ <elements>
+ <element content="gl_pathc">
+ <synopsis>
+ The number of elements in the vector, excluding the initial null entries
+ if the GLOB_DOOFFS flag is used (see gl_offs below).
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="gl_pathv">
+ <synopsis>
+ The address of the vector. This field has type &lt;CODE&gt;char **&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="gl_offs">
+ <synopsis>
+ The offset of the first real element of the vector, from its nominal
+ address in the &lt;CODE&gt;gl_pathv&lt;/CODE&gt; field. Unlike the other fields, this
+ is always an input to &lt;CODE&gt;glob&lt;/CODE&gt;, rather than an output from it.
+ &lt;br&gt;&lt;br&gt; If you use a nonzero offset, then that many elements at the beginning of
+ the vector are left empty. (The &lt;CODE&gt;glob&lt;/CODE&gt; function fills them with
+ null pointers.)
+ &lt;br&gt;&lt;br&gt; The &lt;CODE&gt;gl_offs&lt;/CODE&gt; field is meaningful only if you use the
+ &lt;CODE&gt;GLOB_DOOFFS&lt;/CODE&gt; flag. Otherwise, the offset is always zero
+ regardless of what is in this field, and the first real element comes at
+ the beginning of the vector.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="gl_closedir">
+ <synopsis>
+ The address of an alternative implementation of the &lt;CODE&gt;closedir&lt;/CODE&gt;
+ function. It is used if the &lt;CODE&gt;GLOB_ALTDIRFUNC&lt;/CODE&gt; bit is set in
+ the flag parameter. The type of this field is
+ &lt;CODE&gt;void (*) (void *)&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; This is a GNU extension.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="gl_readdir">
+ <synopsis>
+ The address of an alternative implementation of the &lt;CODE&gt;readdir64&lt;/CODE&gt;
+ function used to read the contents of a directory. It is used if the
+ &lt;CODE&gt;GLOB_ALTDIRFUNC&lt;/CODE&gt; bit is set in the flag parameter. The type of
+ this field is &lt;CODE&gt;struct dirent64 *(*) (void *)&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; This is a GNU extension.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="gl_opendir">
+ <synopsis>
+ The address of an alternative implementation of the &lt;CODE&gt;opendir&lt;/CODE&gt;
+ function. It is used if the &lt;CODE&gt;GLOB_ALTDIRFUNC&lt;/CODE&gt; bit is set in
+ the flag parameter. The type of this field is
+ &lt;CODE&gt;void *(*) (const char *)&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; This is a GNU extension.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="gl_stat">
+ <synopsis>
+ The address of an alternative implementation of the &lt;CODE&gt;stat64&lt;/CODE&gt; function
+ to get information about an object in the filesystem. It is used if the
+ &lt;CODE&gt;GLOB_ALTDIRFUNC&lt;/CODE&gt; bit is set in the flag parameter. The type of
+ this field is &lt;CODE&gt;int (*) (const char *, struct stat64 *)&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; This is a GNU extension.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ </elements>
+ </structure>
+ </construct>
+ <construct id="function-glob" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *pattern"/>
+ <parameter content="int flags"/>
+ <parameter content="int (*errfunc) (const char *filename"/>
+ <parameter content="int error-code)"/>
+ <parameter content="glob_t *vector-ptr"/>
+ </prototype>
+ <headers>
+ <header filename = "fnmatch.h"/>
+ <header filename = "glob.h"/>
+ </headers>
+ <synopsis>
+ The function &lt;CODE&gt;glob&lt;/CODE&gt; does globbing using the pattern &lt;VAR&gt;pattern&lt;/VAR&gt;
+ in the current directory. It puts the result in a newly allocated
+ vector, and stores the size and address of this vector into
+ &lt;CODE&gt;*&lt;VAR&gt;vector-ptr&lt;/VAR&gt;&lt;/CODE&gt;. The argument &lt;VAR&gt;flags&lt;/VAR&gt; is a combination of
+ bit flags; see Flags for Globbing, for details of the flags.
+ &lt;br&gt;&lt;br&gt; The result of globbing is a sequence of file names. The function
+ &lt;CODE&gt;glob&lt;/CODE&gt; allocates a string for each resulting word, then
+ allocates a vector of type &lt;CODE&gt;char **&lt;/CODE&gt; to store the addresses of
+ these strings. The last element of the vector is a null pointer.
+ This vector is called the word vector.
+ &lt;br&gt;&lt;br&gt; To return this vector, &lt;CODE&gt;glob&lt;/CODE&gt; stores both its address and its
+ length (number of elements, not counting the terminating null pointer)
+ into &lt;CODE&gt;*&lt;VAR&gt;vector-ptr&lt;/VAR&gt;&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; Normally, &lt;CODE&gt;glob&lt;/CODE&gt; sorts the file names alphabetically before
+ returning them. You can turn this off with the flag &lt;CODE&gt;GLOB_NOSORT&lt;/CODE&gt;
+ if you want to get the information as fast as possible. Usually it's
+ a good idea to let &lt;CODE&gt;glob&lt;/CODE&gt; 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.
+ &lt;br&gt;&lt;br&gt; If &lt;CODE&gt;glob&lt;/CODE&gt; succeeds, it returns 0. Otherwise, it returns one
+ of these error codes:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;GLOB_ABORTED&lt;/CODE&gt;
+&lt;DD&gt;
+ There was an error opening a directory, and you used the flag
+ &lt;CODE&gt;GLOB_ERR&lt;/CODE&gt; or your specified &lt;VAR&gt;errfunc&lt;/VAR&gt; returned a nonzero
+ value.
+
+
+ ,
+
+ for an explanation of the &lt;CODE&gt;GLOB_ERR&lt;/CODE&gt; flag and &lt;VAR&gt;errfunc&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; &lt;DT&gt;&lt;CODE&gt;GLOB_NOMATCH&lt;/CODE&gt;
+&lt;DD&gt;
+ The pattern didn't match any existing files. If you use the
+ &lt;CODE&gt;GLOB_NOCHECK&lt;/CODE&gt; flag, then you never get this error code, because
+ that flag tells &lt;CODE&gt;glob&lt;/CODE&gt; to &lt;EM&gt;pretend&lt;/EM&gt; that the pattern matched
+ at least one file.
+ &lt;br&gt;&lt;br&gt; &lt;DT&gt;&lt;CODE&gt;GLOB_NOSPACE&lt;/CODE&gt;
+&lt;DD&gt;
+ It was impossible to allocate memory to hold the result.
+ &lt;/DL&gt;
+ &lt;br&gt;&lt;br&gt; In the event of an error, &lt;CODE&gt;glob&lt;/CODE&gt; stores information in
+ &lt;CODE&gt;*&lt;VAR&gt;vector-ptr&lt;/VAR&gt;&lt;/CODE&gt; about all the matches it has found so far.
+ &lt;br&gt;&lt;br&gt; It is important to notice that the &lt;CODE&gt;glob&lt;/CODE&gt; function will not fail if
+ it encounters directories or files which cannot be handled without the
+ LFS interfaces. The implementation of &lt;CODE&gt;glob&lt;/CODE&gt; 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 &lt;CODE&gt;stat&lt;/CODE&gt; functions complicates things a
+ bit. If these callback functions are used and a large file or directory
+ is encountered &lt;CODE&gt;glob&lt;/CODE&gt; &lt;EM&gt;can&lt;/EM&gt; fail.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-glob64" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *pattern"/>
+ <parameter content="int flags"/>
+ <parameter content="int (*errfunc) (const char *filename"/>
+ <parameter content="int error-code)"/>
+ <parameter content="glob64_t *vector-ptr"/>
+ </prototype>
+ <headers>
+ <header filename = "glob.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;glob64&lt;/CODE&gt; 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 &lt;CODE&gt;glob64&lt;/CODE&gt;
+ function is added by the extensions of the GNU &lt;CODE&gt;glob&lt;/CODE&gt;
+ implementation which allows the user to provide own directory handling
+ and &lt;CODE&gt;stat&lt;/CODE&gt; functions. The &lt;CODE&gt;readdir&lt;/CODE&gt; and &lt;CODE&gt;stat&lt;/CODE&gt; functions
+ do depend on the choice of &lt;CODE&gt;_FILE_OFFSET_BITS&lt;/CODE&gt; since the definition
+ of the types &lt;CODE&gt;struct dirent&lt;/CODE&gt; and &lt;CODE&gt;struct stat&lt;/CODE&gt; will change
+ depending on the choice.
+ &lt;br&gt;&lt;br&gt; Beside this difference the &lt;CODE&gt;glob64&lt;/CODE&gt; works just like &lt;CODE&gt;glob&lt;/CODE&gt; in
+ all aspects.
+ &lt;br&gt;&lt;br&gt; This function is a GNU extension.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-globfree" type="function">
+ <function returntype="void">
+ <prototype>
+ <parameter content="glob_t *pglob"/>
+ </prototype>
+ <headers>
+ <header filename = "glob.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;globfree&lt;/CODE&gt; function frees all resources allocated by previous
+ calls to &lt;CODE&gt;glob&lt;/CODE&gt; associated with the object pointed to by
+ &lt;VAR&gt;pglob&lt;/VAR&gt;. This function should be called whenever the currently used
+ &lt;CODE&gt;glob_t&lt;/CODE&gt; typed object isn't used anymore.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-globfree64" type="function">
+ <function returntype="void">
+ <prototype>
+ <parameter content="glob64_t *pglob"/>
+ </prototype>
+ <headers>
+ <header filename = "glob.h"/>
+ </headers>
+ <synopsis>
+ This function is equivalent to &lt;CODE&gt;globfree&lt;/CODE&gt; but it frees records of
+ type &lt;CODE&gt;glob64_t&lt;/CODE&gt; which were allocated by &lt;CODE&gt;glob64&lt;/CODE&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="dtype-regex_t" type="dtype">
+ <structure>
+ <synopsis>
+ This type of object holds a compiled regular expression.
+ It is actually a structure. It has just one field that your programs
+ should look at:
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </structure>
+ </construct>
+ <construct id="function-regcomp" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="regex_t *restrict compiled"/>
+ <parameter content="const char *restrict pattern"/>
+ <parameter content="int cflags"/>
+ </prototype>
+ <headers>
+ <header filename = "regex.h"/>
+ </headers>
+ <synopsis>
+ The function &lt;CODE&gt;regcomp&lt;/CODE&gt; ``compiles'' a regular expression into a
+ data structure that you can use with &lt;CODE&gt;regexec&lt;/CODE&gt; to match against a
+ string. The compiled regular expression format is designed for
+ efficient matching. &lt;CODE&gt;regcomp&lt;/CODE&gt; stores it into &lt;CODE&gt;*&lt;VAR&gt;compiled&lt;/VAR&gt;&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; It's up to you to allocate an object of type &lt;CODE&gt;regex_t&lt;/CODE&gt; and pass its
+ address to &lt;CODE&gt;regcomp&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; The argument &lt;VAR&gt;cflags&lt;/VAR&gt; lets you specify various options that control
+ the syntax and semantics of regular expressions. .
+ &lt;br&gt;&lt;br&gt; If you use the flag &lt;CODE&gt;REG_NOSUB&lt;/CODE&gt;, then &lt;CODE&gt;regcomp&lt;/CODE&gt; omits from
+ the compiled regular expression the information necessary to record
+ how subexpressions actually match. In this case, you might as well
+ pass &lt;CODE&gt;0&lt;/CODE&gt; for the &lt;VAR&gt;matchptr&lt;/VAR&gt; and &lt;VAR&gt;nmatch&lt;/VAR&gt; arguments when
+ you call &lt;CODE&gt;regexec&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; If you don't use &lt;CODE&gt;REG_NOSUB&lt;/CODE&gt;, then the compiled regular expression
+ does have the capacity to record how subexpressions match. Also,
+ &lt;CODE&gt;regcomp&lt;/CODE&gt; tells you how many subexpressions &lt;VAR&gt;pattern&lt;/VAR&gt; has, by
+ storing the number in &lt;CODE&gt;&lt;VAR&gt;compiled&lt;/VAR&gt;-&gt;re_nsub&lt;/CODE&gt;. You can use that
+ value to decide how long an array to allocate to hold information about
+ subexpression matches.
+ &lt;br&gt;&lt;br&gt; &lt;CODE&gt;regcomp&lt;/CODE&gt; returns &lt;CODE&gt;0&lt;/CODE&gt; if it succeeds in compiling the regular
+ expression; otherwise, it returns a nonzero error code (see the table
+ below). You can use &lt;CODE&gt;regerror&lt;/CODE&gt; to produce an error message string
+ describing the reason for a nonzero value; see Regexp Cleanup.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-regexec" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const regex_t *restrict compiled"/>
+ <parameter content="const char *restrict string"/>
+ <parameter content="size_t nmatch"/>
+ <parameter content="regmatch_t matchptr[restrict]"/>
+ <parameter content="int eflags"/>
+ </prototype>
+ <headers>
+ <header filename = "regex.h"/>
+ </headers>
+ <synopsis>
+ This function tries to match the compiled regular expression
+ &lt;CODE&gt;*&lt;VAR&gt;compiled&lt;/VAR&gt;&lt;/CODE&gt; against &lt;VAR&gt;string&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; &lt;CODE&gt;regexec&lt;/CODE&gt; returns &lt;CODE&gt;0&lt;/CODE&gt; if the regular expression matches;
+ otherwise, it returns a nonzero value. See the table below for
+ what nonzero values mean. You can use &lt;CODE&gt;regerror&lt;/CODE&gt; to produce an
+ error message string describing the reason for a nonzero value;
+ see Regexp Cleanup.
+ &lt;br&gt;&lt;br&gt; The argument &lt;VAR&gt;eflags&lt;/VAR&gt; is a word of bit flags that enable various
+ options.
+ &lt;br&gt;&lt;br&gt; If you want to get information about what part of &lt;VAR&gt;string&lt;/VAR&gt; actually
+ matched the regular expression or its subexpressions, use the arguments
+ &lt;VAR&gt;matchptr&lt;/VAR&gt; and &lt;VAR&gt;nmatch&lt;/VAR&gt;. Otherwise, pass &lt;CODE&gt;0&lt;/CODE&gt; for
+ &lt;VAR&gt;nmatch&lt;/VAR&gt;, and &lt;CODE&gt;NULL&lt;/CODE&gt; for &lt;VAR&gt;matchptr&lt;/VAR&gt;. .
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="dtype-regmatch_t" type="dtype">
+ <structure>
+ <synopsis>
+ This is the data type of the &lt;VAR&gt;matcharray&lt;/VAR&gt; array that you pass to
+ &lt;CODE&gt;regexec&lt;/CODE&gt;. It contains two structure fields, as follows:
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ <elements>
+ <element content="rm_so">
+ <synopsis>
+ The offset in &lt;VAR&gt;string&lt;/VAR&gt; of the beginning of a substring. Add this
+ value to &lt;VAR&gt;string&lt;/VAR&gt; to get the address of that part.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ </elements>
+ </structure>
+ </construct>
+ <construct id="dtype-regoff_t" type="dtype">
+ <structure>
+ </structure>
+ </construct>
+ <construct id="function-regfree" type="function">
+ <function returntype="void">
+ <prototype>
+ <parameter content="regex_t *compiled"/>
+ </prototype>
+ <headers>
+ <header filename = "regex.h"/>
+ </headers>
+ <synopsis>
+ Calling &lt;CODE&gt;regfree&lt;/CODE&gt; frees all the storage that &lt;CODE&gt;*&lt;VAR&gt;compiled&lt;/VAR&gt;&lt;/CODE&gt;
+ points to. This includes various internal fields of the &lt;CODE&gt;regex_t&lt;/CODE&gt;
+ structure that aren't documented in this manual.
+ &lt;br&gt;&lt;br&gt; &lt;CODE&gt;regfree&lt;/CODE&gt; does not free the object &lt;CODE&gt;*&lt;VAR&gt;compiled&lt;/VAR&gt;&lt;/CODE&gt; itself.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-regerror" type="function">
+ <function returntype="size_t">
+ <prototype>
+ <parameter content="int errcode"/>
+ <parameter content="const regex_t *restrict compiled"/>
+ <parameter content="char *restrict buffer"/>
+ <parameter content="size_t length"/>
+ </prototype>
+ <headers>
+ <header filename = "regex.h"/>
+ </headers>
+ <synopsis>
+ This function produces an error message string for the error code
+ &lt;VAR&gt;errcode&lt;/VAR&gt;, and stores the string in &lt;VAR&gt;length&lt;/VAR&gt; bytes of memory
+ starting at &lt;VAR&gt;buffer&lt;/VAR&gt;. For the &lt;VAR&gt;compiled&lt;/VAR&gt; argument, supply the
+ same compiled regular expression structure that &lt;CODE&gt;regcomp&lt;/CODE&gt; or
+ &lt;CODE&gt;regexec&lt;/CODE&gt; was working with when it got the error. Alternatively,
+ you can supply &lt;CODE&gt;NULL&lt;/CODE&gt; for &lt;VAR&gt;compiled&lt;/VAR&gt;; you will still get a
+ meaningful error message, but it might not be as detailed.
+ &lt;br&gt;&lt;br&gt; If the error message can't fit in &lt;VAR&gt;length&lt;/VAR&gt; bytes (including a
+ terminating null character), then &lt;CODE&gt;regerror&lt;/CODE&gt; truncates it.
+ The string that &lt;CODE&gt;regerror&lt;/CODE&gt; stores is always null-terminated
+ even if it has been truncated.
+ &lt;br&gt;&lt;br&gt; The return value of &lt;CODE&gt;regerror&lt;/CODE&gt; is the minimum length needed to
+ store the entire error message. If this is less than &lt;VAR&gt;length&lt;/VAR&gt;, then
+ the error message was not truncated, and you can use it. Otherwise, you
+ should call &lt;CODE&gt;regerror&lt;/CODE&gt; again with a larger buffer.
+ &lt;br&gt;&lt;br&gt; Here is a function which uses &lt;CODE&gt;regerror&lt;/CODE&gt;, but always dynamically
+ allocates a buffer for the error message:
+ &lt;br&gt;&lt;br&gt; &lt;pre&gt;&lt;br&gt;
+ char *get_regerror (int errcode, regex_t *compiled)&lt;br&gt;
+ {&lt;br&gt;
+ size_t length = regerror (errcode, compiled, NULL, 0);&lt;br&gt;
+ char *buffer = xmalloc (length);&lt;br&gt;
+ (void) regerror (errcode, compiled, buffer, length);&lt;br&gt;
+ return buffer;&lt;br&gt;
+ }&lt;br&gt;
+ &lt;/pre&gt;
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="type-wordexp_t" type="type">
+ <structure>
+ <synopsis>
+ This data type holds a pointer to a word vector. More precisely, it
+ records both the address of the word vector and its size.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ <elements>
+ <element content="we_wordc">
+ <synopsis>
+ The number of elements in the vector.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ <element content="we_wordv">
+ <synopsis>
+ The address of the vector. This field has type &lt;CODE&gt;char **&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt;
+ </synopsis>
+ </element>
+ </elements>
+ </structure>
+ </construct>
+ <construct id="function-wordexp" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="const char *words"/>
+ <parameter content="wordexp_t *word-vector-ptr"/>
+ <parameter content="int flags"/>
+ </prototype>
+ <headers>
+ <header filename = "wordexp.h"/>
+ </headers>
+ <synopsis>
+ Perform word expansion on the string &lt;VAR&gt;words&lt;/VAR&gt;, putting the result in
+ a newly allocated vector, and store the size and address of this vector
+ into &lt;CODE&gt;*&lt;VAR&gt;word-vector-ptr&lt;/VAR&gt;&lt;/CODE&gt;. The argument &lt;VAR&gt;flags&lt;/VAR&gt; is a
+ combination of bit flags; see Flags for Wordexp, for details of
+ the flags.
+ &lt;br&gt;&lt;br&gt; You shouldn't use any of the characters &lt;samp&gt;|&amp;;&lt;&gt;&lt;/samp&gt; in the string
+ &lt;VAR&gt;words&lt;/VAR&gt; unless they are quoted; likewise for newline. If you use
+ these characters unquoted, you will get the &lt;CODE&gt;WRDE_BADCHAR&lt;/CODE&gt; error
+ code. Don't use parentheses or braces unless they are quoted or part of
+ a word expansion construct. If you use quotation characters &lt;samp&gt;'"`&lt;/samp&gt;,
+ they should come in pairs that balance.
+ &lt;br&gt;&lt;br&gt; The results of word expansion are a sequence of words. The function
+ &lt;CODE&gt;wordexp&lt;/CODE&gt; allocates a string for each resulting word, then
+ allocates a vector of type &lt;CODE&gt;char **&lt;/CODE&gt; to store the addresses of
+ these strings. The last element of the vector is a null pointer.
+ This vector is called the word vector.
+ &lt;br&gt;&lt;br&gt; To return this vector, &lt;CODE&gt;wordexp&lt;/CODE&gt; stores both its address and its
+ length (number of elements, not counting the terminating null pointer)
+ into &lt;CODE&gt;*&lt;VAR&gt;word-vector-ptr&lt;/VAR&gt;&lt;/CODE&gt;.
+ &lt;br&gt;&lt;br&gt; If &lt;CODE&gt;wordexp&lt;/CODE&gt; succeeds, it returns 0. Otherwise, it returns one
+ of these error codes:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;WRDE_BADCHAR&lt;/CODE&gt;
+&lt;DD&gt;
+ The input string &lt;VAR&gt;words&lt;/VAR&gt; contains an unquoted invalid character such
+ as &lt;samp&gt;|&lt;/samp&gt;.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; WRDE_BADVAL
+ The input string refers to an undefined shell variable, and you used the flag
+ &lt;CODE&gt;WRDE_UNDEF&lt;/CODE&gt; to forbid such references.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; WRDE_CMDSUB
+ The input string uses command substitution, and you used the flag
+ &lt;CODE&gt;WRDE_NOCMD&lt;/CODE&gt; to forbid command substitution.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; WRDE_NOSPACE
+ It was impossible to allocate memory to hold the result. In this case,
+ &lt;CODE&gt;wordexp&lt;/CODE&gt; can store part of the results---as much as it could
+ allocate room for.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; WRDE_SYNTAX
+ There was a syntax error in the input string. For example, an unmatched
+ quoting character is a syntax error.
+
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-wordfree" type="function">
+ <function returntype="void">
+ <prototype>
+ <parameter content="wordexp_t *word-vector-ptr"/>
+ </prototype>
+ <headers>
+ <header filename = "wordexp.h"/>
+ </headers>
+ <synopsis>
+ Free the storage used for the word-strings and vector that
+ &lt;CODE&gt;*&lt;VAR&gt;word-vector-ptr&lt;/VAR&gt;&lt;/CODE&gt; points to. This does not free the
+ structure &lt;CODE&gt;*&lt;VAR&gt;word-vector-ptr&lt;/VAR&gt;&lt;/CODE&gt; itself---only the other
+ data it points to.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-backtrace" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="void **buffer"/>
+ <parameter content="int size"/>
+ </prototype>
+ <headers>
+ <header filename = "wordexp.h"/>
+ <header filename = "execinfo.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;backtrace&lt;/CODE&gt; function obtains a backtrace for the current
+ thread, as a list of pointers, and places the information into
+ &lt;VAR&gt;buffer&lt;/VAR&gt;. The argument &lt;VAR&gt;size&lt;/VAR&gt; should be the number of
+ &lt;CODE&gt;void *&lt;/CODE&gt; elements that will fit into &lt;VAR&gt;buffer&lt;/VAR&gt;. The return
+ value is the actual number of entries of &lt;VAR&gt;buffer&lt;/VAR&gt; that are obtained,
+ and is at most &lt;VAR&gt;size&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; The pointers placed in &lt;VAR&gt;buffer&lt;/VAR&gt; are actually return addresses
+ obtained by inspecting the stack, one return address per stack frame.
+ &lt;br&gt;&lt;br&gt; 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 &lt;CODE&gt;backtrace&lt;/CODE&gt; from
+ interpreting the stack contents correctly.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-backtrace_symbols" type="function">
+ <function returntype="char **">
+ <prototype>
+ <parameter content="void *const *buffer"/>
+ <parameter content="int size"/>
+ </prototype>
+ <headers>
+ <header filename = "execinfo.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;backtrace_symbols&lt;/CODE&gt; function translates the information
+ obtained from the &lt;CODE&gt;backtrace&lt;/CODE&gt; function into an array of strings.
+ The argument &lt;VAR&gt;buffer&lt;/VAR&gt; should be a pointer to an array of addresses
+ obtained via the &lt;CODE&gt;backtrace&lt;/CODE&gt; function, and &lt;VAR&gt;size&lt;/VAR&gt; is the number
+ of entries in that array (the return value of &lt;CODE&gt;backtrace&lt;/CODE&gt;).
+ &lt;br&gt;&lt;br&gt; The return value is a pointer to an array of strings, which has
+ &lt;VAR&gt;size&lt;/VAR&gt; entries just like the array &lt;VAR&gt;buffer&lt;/VAR&gt;. Each string
+ contains a printable representation of the corresponding element of
+ &lt;VAR&gt;buffer&lt;/VAR&gt;. It includes the function name (if this can be
+ determined), an offset into the function, and the actual return address
+ (in hexadecimal).
+ &lt;br&gt;&lt;br&gt; 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 (&lt;CODE&gt;-rdynamic&lt;/CODE&gt;.)
+ &lt;br&gt;&lt;br&gt; The return value of &lt;CODE&gt;backtrace_symbols&lt;/CODE&gt; is a pointer obtained via
+ the &lt;CODE&gt;malloc&lt;/CODE&gt; function, and it is the responsibility of the caller
+ to &lt;CODE&gt;free&lt;/CODE&gt; that pointer. Note that only the return value need be
+ freed, not the individual strings.
+ &lt;br&gt;&lt;br&gt; The return value is &lt;CODE&gt;NULL&lt;/CODE&gt; if sufficient memory for the strings
+ cannot be obtained.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-backtrace_symbols_fd" type="function">
+ <function returntype="void">
+ <prototype>
+ <parameter content="void *const *buffer"/>
+ <parameter content="int size"/>
+ <parameter content="int fd"/>
+ </prototype>
+ <headers>
+ <header filename = "execinfo.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;backtrace_symbols_fd&lt;/CODE&gt; function performs the same translation
+ as the function &lt;CODE&gt;backtrace_symbols&lt;/CODE&gt; function. Instead of returning
+ the strings to the caller, it writes the strings to the file descriptor
+ &lt;VAR&gt;fd&lt;/VAR&gt;, one per line. It does not use the &lt;CODE&gt;malloc&lt;/CODE&gt; function, and
+ can therefore be used in situations where that function might fail.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-ctermid" type="function">
+ <function returntype="char *">
+ <prototype>
+ <parameter content="char *string"/>
+ </prototype>
+ <headers>
+ <header filename = "stdio.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;ctermid&lt;/CODE&gt; function returns a string containing the file name of
+ the controlling terminal for the current process. If &lt;VAR&gt;string&lt;/VAR&gt; is
+ not a null pointer, it should be an array that can hold at least
+ &lt;CODE&gt;L_ctermid&lt;/CODE&gt; 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.
+ &lt;br&gt;&lt;br&gt; 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.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-setsid" type="function">
+ <function returntype="pid_t">
+ <prototype>
+ <parameter content="void"/>
+ </prototype>
+ <headers>
+ <header filename = "stdio.h"/>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;setsid&lt;/CODE&gt; 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.
+ &lt;br&gt;&lt;br&gt; This function also makes the calling process have no controlling terminal.
+ &lt;br&gt;&lt;br&gt; The &lt;CODE&gt;setsid&lt;/CODE&gt; function returns the new process group ID of the
+ calling process if successful. A return value of &lt;CODE&gt;-1&lt;/CODE&gt; indicates an
+ error. The following &lt;CODE&gt;errno&lt;/CODE&gt; error conditions are defined for this
+ function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EPERM&lt;/CODE&gt;
+&lt;DD&gt;
+ The calling process is already a process group leader, or there is
+ already another process group around that has the same process group ID.
+
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-getsid" type="function">
+ <function returntype="pid_t">
+ <prototype>
+ <parameter content="pid_t pid"/>
+ </prototype>
+ <headers>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ &lt;br&gt;&lt;br&gt; The &lt;CODE&gt;getsid&lt;/CODE&gt; function returns the process group ID of the session
+ leader of the specified process. If a &lt;VAR&gt;pid&lt;/VAR&gt; is &lt;CODE&gt;0&lt;/CODE&gt;, the
+ process group ID of the session leader of the current process is
+ returned.
+ &lt;br&gt;&lt;br&gt; In case of error &lt;CODE&gt;-1&lt;/CODE&gt; is returned and &lt;CODE&gt;errno&lt;/CODE&gt; is set. The
+ following &lt;CODE&gt;errno&lt;/CODE&gt; error conditions are defined for this function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;ESRCH&lt;/CODE&gt;
+&lt;DD&gt;
+ There is no process with the given process ID &lt;VAR&gt;pid&lt;/VAR&gt;.
+ &lt;LI&gt; EPERM
+ The calling process and the process specified by &lt;VAR&gt;pid&lt;/VAR&gt; 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 &lt;VAR&gt;pid&lt;/VAR&gt;
+ from the calling process.
+
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-setpgid" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="pid_t pid"/>
+ <parameter content="pid_t pgid"/>
+ </prototype>
+ <headers>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ The &lt;CODE&gt;setpgid&lt;/CODE&gt; function puts the process &lt;VAR&gt;pid&lt;/VAR&gt; into the process
+ group &lt;VAR&gt;pgid&lt;/VAR&gt;. As a special case, either &lt;VAR&gt;pid&lt;/VAR&gt; or &lt;VAR&gt;pgid&lt;/VAR&gt; can
+ be zero to indicate the process ID of the calling process.
+ &lt;br&gt;&lt;br&gt; This function fails on a system that does not support job control.
+ , for more information.
+ &lt;br&gt;&lt;br&gt; If the operation is successful, &lt;CODE&gt;setpgid&lt;/CODE&gt; returns zero. Otherwise
+ it returns &lt;CODE&gt;-1&lt;/CODE&gt;. The following &lt;CODE&gt;errno&lt;/CODE&gt; error conditions are
+ defined for this function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EACCES&lt;/CODE&gt;
+&lt;DD&gt;
+ The child process named by &lt;VAR&gt;pid&lt;/VAR&gt; has executed an &lt;CODE&gt;exec&lt;/CODE&gt;
+ function since it was forked.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EINVAL
+ The value of the &lt;VAR&gt;pgid&lt;/VAR&gt; is not valid.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ENOSYS
+ The system doesn't support job control.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EPERM
+ The process indicated by the &lt;VAR&gt;pid&lt;/VAR&gt; argument is a session leader,
+ or is not in the same session as the calling process, or the value of
+ the &lt;VAR&gt;pgid&lt;/VAR&gt; argument doesn't match a process group ID in the same
+ session as the calling process.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ESRCH
+ The process indicated by the &lt;VAR&gt;pid&lt;/VAR&gt; argument is not the calling
+ process or a child of the calling process.
+
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-setpgrp" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="pid_t pid"/>
+ <parameter content="pid_t pgid"/>
+ </prototype>
+ <headers>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ This is the BSD Unix name for &lt;CODE&gt;setpgid&lt;/CODE&gt;. Both functions do exactly
+ the same thing.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-tcgetpgrp" type="function">
+ <function returntype="pid_t">
+ <prototype>
+ <parameter content="int filedes"/>
+ </prototype>
+ <headers>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ This function returns the process group ID of the foreground process
+ group associated with the terminal open on descriptor &lt;VAR&gt;filedes&lt;/VAR&gt;.
+ &lt;br&gt;&lt;br&gt; If there is no foreground process group, the return value is a number
+ greater than &lt;CODE&gt;1&lt;/CODE&gt; 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.
+ &lt;br&gt;&lt;br&gt; In case of an error, a value of &lt;CODE&gt;-1&lt;/CODE&gt; is returned. The
+ following &lt;CODE&gt;errno&lt;/CODE&gt; error conditions are defined for this function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EBADF&lt;/CODE&gt;
+&lt;DD&gt;
+ The &lt;VAR&gt;filedes&lt;/VAR&gt; argument is not a valid file descriptor.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ENOSYS
+ The system doesn't support job control.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ENOTTY
+ The terminal file associated with the &lt;VAR&gt;filedes&lt;/VAR&gt; argument isn't the
+ controlling terminal of the calling process.
+
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-tcsetpgrp" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="int filedes"/>
+ <parameter content="pid_t pgid"/>
+ </prototype>
+ <headers>
+ <header filename = "unistd.h"/>
+ </headers>
+ <synopsis>
+ This function is used to set a terminal's foreground process group ID.
+ The argument &lt;VAR&gt;filedes&lt;/VAR&gt; is a descriptor which specifies the terminal;
+ &lt;VAR&gt;pgid&lt;/VAR&gt; specifies the process group. The calling process must be a
+ member of the same session as &lt;VAR&gt;pgid&lt;/VAR&gt; and must have the same
+ controlling terminal.
+ &lt;br&gt;&lt;br&gt; 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 &lt;CODE&gt;SIGTTOU&lt;/CODE&gt;
+ signal. The exception is if the calling process itself is ignoring or
+ blocking &lt;CODE&gt;SIGTTOU&lt;/CODE&gt; signals, in which case the operation is
+ performed and no signal is sent.
+ &lt;br&gt;&lt;br&gt; If successful, &lt;CODE&gt;tcsetpgrp&lt;/CODE&gt; returns &lt;CODE&gt;0&lt;/CODE&gt;. A return value of
+ &lt;CODE&gt;-1&lt;/CODE&gt; indicates an error. The following &lt;CODE&gt;errno&lt;/CODE&gt; error
+ conditions are defined for this function:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EBADF&lt;/CODE&gt;
+&lt;DD&gt;
+ The &lt;VAR&gt;filedes&lt;/VAR&gt; argument is not a valid file descriptor.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EINVAL
+ The &lt;VAR&gt;pgid&lt;/VAR&gt; argument is not valid.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ENOSYS
+ The system doesn't support job control.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ENOTTY
+ The &lt;VAR&gt;filedes&lt;/VAR&gt; isn't the controlling terminal of the calling process.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; EPERM
+ The &lt;VAR&gt;pgid&lt;/VAR&gt; isn't a process group in the same session as the calling
+ process.
+
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-tcgetsid" type="function">
+ <function returntype="pid_t">
+ <prototype>
+ <parameter content="int fildes"/>
+ </prototype>
+ <headers>
+ <header filename = "termios.h"/>
+ </headers>
+ <synopsis>
+ This function is used to obtain the process group ID of the session
+ for which the terminal specified by &lt;VAR&gt;fildes&lt;/VAR&gt; is the controlling terminal.
+ If the call is successful the group ID is returned. Otherwise the
+ return value is &lt;CODE&gt;(pid_t) -1&lt;/CODE&gt; and the global variable &lt;VAR&gt;errno&lt;/VAR&gt;
+ is set to the following value:
+ &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;EBADF&lt;/CODE&gt;
+&lt;DD&gt;
+ The &lt;VAR&gt;filedes&lt;/VAR&gt; argument is not a valid file descriptor.
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; ENOTTY
+ The calling process does not have a controlling terminal, or the file
+ is not the controlling terminal.
+
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-islower" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="int c"/>
+ </prototype>
+ <headers>
+ <header filename = "ctype.h"/>
+ </headers>
+ <synopsis>
+ Returns true if &lt;VAR&gt;c&lt;/VAR&gt; is a lower-case letter. The letter need not be
+ from the Latin alphabet, any alphabet representable is valid.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-isupper" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="int c"/>
+ </prototype>
+ <headers>
+ <header filename = "ctype.h"/>
+ </headers>
+ <synopsis>
+ Returns true if &lt;VAR&gt;c&lt;/VAR&gt; is an upper-case letter. The letter need not be
+ from the Latin alphabet, any alphabet representable is valid.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-isalpha" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="int c"/>
+ </prototype>
+ <headers>
+ <header filename = "ctype.h"/>
+ </headers>
+ <synopsis>
+ Returns true if &lt;VAR&gt;c&lt;/VAR&gt; is an alphabetic character (a letter). If
+ &lt;CODE&gt;islower&lt;/CODE&gt; or &lt;CODE&gt;isupper&lt;/CODE&gt; is true of a character, then
+ &lt;CODE&gt;isalpha&lt;/CODE&gt; is also true.
+ &lt;br&gt;&lt;br&gt; In some locales, there may be additional characters for which
+ &lt;CODE&gt;isalpha&lt;/CODE&gt; is true---letters which are neither upper case nor lower
+ case. But in the standard &lt;CODE&gt;"C"&lt;/CODE&gt; locale, there are no such
+ additional characters.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-isdigit" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="int c"/>
+ </prototype>
+ <headers>
+ <header filename = "ctype.h"/>
+ </headers>
+ <synopsis>
+ Returns true if &lt;VAR&gt;c&lt;/VAR&gt; is a decimal digit (&lt;samp&gt;0&lt;/samp&gt; through &lt;samp&gt;9&lt;/samp&gt;).
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-isalnum" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="int c"/>
+ </prototype>
+ <headers>
+ <header filename = "ctype.h"/>
+ </headers>
+ <synopsis>
+ Returns true if &lt;VAR&gt;c&lt;/VAR&gt; is an alphanumeric character (a letter or
+ number); in other words, if either &lt;CODE&gt;isalpha&lt;/CODE&gt; or &lt;CODE&gt;isdigit&lt;/CODE&gt; is
+ true of a character, then &lt;CODE&gt;isalnum&lt;/CODE&gt; is also true.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-isxdigit" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="int c"/>
+ </prototype>
+ <headers>
+ <header filename = "ctype.h"/>
+ </headers>
+ <synopsis>
+ Returns true if &lt;VAR&gt;c&lt;/VAR&gt; is a hexadecimal digit.
+ Hexadecimal digits include the normal decimal digits &lt;samp&gt;0&lt;/samp&gt; through
+ &lt;samp&gt;9&lt;/samp&gt; and the letters &lt;samp&gt;A&lt;/samp&gt; through &lt;samp&gt;F&lt;/samp&gt; and
+ &lt;samp&gt;a&lt;/samp&gt; through &lt;samp&gt;f&lt;/samp&gt;.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-ispunct" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="int c"/>
+ </prototype>
+ <headers>
+ <header filename = "ctype.h"/>
+ </headers>
+ <synopsis>
+ Returns true if &lt;VAR&gt;c&lt;/VAR&gt; is a punctuation character.
+ This means any printing character that is not alphanumeric or a space
+ character.
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-isspace" type="function">
+ <function returntype="int">
+ <prototype>
+ <parameter content="int c"/>
+ </prototype>
+ <headers>
+ <header filename = "ctype.h"/>
+ </headers>
+ <synopsis>
+ Returns true if &lt;VAR&gt;c&lt;/VAR&gt; is a whitespace character. In the standard
+ &lt;CODE&gt;"C"&lt;/CODE&gt; locale, &lt;CODE&gt;isspace&lt;/CODE&gt; returns true for only the standard
+ whitespace characters:
+ &lt;br&gt;&lt;br&gt; &lt;DL&gt;
+
+ &lt;DT&gt;&lt;CODE&gt;' '&lt;/CODE&gt;
+&lt;DD&gt;
+ space
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; '\f'
+ formfeed
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; '\n'
+ newline
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; '\r'
+ carriage return
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; '\t'
+ horizontal tab
+ &lt;br&gt;&lt;br&gt; &lt;LI&gt; '\v'
+ vertical tab
+
+ </synopsis>
+ </function>
+ </construct>
+ <construct id="function-isblank" type="function">
+ <function returntype="int">
+ <prototype>