--- eclipse-cdt-3.1.1.orig/debian/changelog +++ eclipse-cdt-3.1.1/debian/changelog @@ -0,0 +1,53 @@ +eclipse-cdt (3.1.1-1) unstable; urgency=medium + + * Merge changes from Ubuntu. + - works with eclipse-3.2.1. Closes: #402003. + + -- Matthias Klose Sat, 13 Jan 2007 22:03:26 +0100 + +eclipse-cdt (3.1.1-0ubuntu2) feisty; urgency=low + + * added bzip2 to build dependencies + + -- Vladimír Lapáček Sat, 6 Jan 2007 08:41:53 +0100 + +eclipse-cdt (3.1.1-0ubuntu1) feisty; urgency=low + + * New upstream release + * Updated to use Eclipse 3.2.1 + + -- Vladimír Lapáček Wed, 6 Dec 2006 22:58:10 +0100 + +eclipse-cdt (3.0.1-3) unstable; urgency=low + + * debian/rules: Adjusted for current eclipse (Closes: #345371). + * Updated Standards-Version to 3.7.2. + + -- Michael Koch Thu, 22 Jun 2006 09:36:48 +0000 + +eclipse-cdt (3.0.1-2) unstable; urgency=low + + * debian/control: Make eclipse-cdt Depends on exuberant-ctags | ctags + and fixed package decription. + * debian/control: Added Build-Depends on java-gcj-compat-dev + (Closes: #345371). + + -- Michael Koch Sun, 1 Jan 2006 12:59:27 +0000 + +eclipse-cdt (3.0.1-1) unstable; urgency=low + + [ Michael Koch ] + * Initial Version (Closes: #195236, #284911). + + [ Stephan Michels ] + * debian/control: Changed the dependency from eclipse-sdk to eclipse. + Updated the description. + * debian/rules: Use variable for the name of the releng plugin. + * debian/rules: Use -DskipFetch=true instead of -DdontFetchAnything=true. + * debian/rules: Define property "config" in rules instead of using + patches to change the properties files. + * debian/copyright: Updated copyright from CPL to EPL + * debian/rules: Add patch for disable the logging to a file + for the javadoc generation. + + -- Stephan Michels Wed, 21 Dec 2005 16:58:32 +0100 --- eclipse-cdt-3.1.1.orig/debian/compat +++ eclipse-cdt-3.1.1/debian/compat @@ -0,0 +1 @@ +4 --- eclipse-cdt-3.1.1.orig/debian/rules +++ eclipse-cdt-3.1.1/debian/rules @@ -0,0 +1,173 @@ +#!/usr/bin/make -f + +# Uncomment this to turn on verbose mode. +#export DH_VERBOSE=1 + +export LC_ALL=C +CURDIR=$(shell pwd) + +SOURCE=$(shell echo upstream/*.tar.bz2) +SOURCE_TREE=source-tree +JAVA_HOME=/usr/lib/jvm/java-gcj +JAVA_RUN=$(JAVA_HOME)/bin/java -Dgnu.gcj.precompiled.db.path=/var/lib/gcj-4.0/classmap.db +ANT_RUN=ant +homedir=$(CURDIR)/home +ECLIPSE_BASE=/usr/lib/eclipse +ECLIPSE_PLATFORM=$(shell dpkg-architecture -qDEB_HOST_ARCH) + +RELENG_PLUGIN=org.eclipse.cdt.releng + +ifeq ($(DEB_HOST_ARCH),i386) + ECLIPSE_PLATFORM=x86 +endif +ifeq ($(DEB_HOST_ARCH),ia64) + ECLIPSE_PLATFORM=ia64 +endif +ifeq ($(DEB_HOST_ARCH),amd64) + ECLIPSE_PLATFORM=x86_64 +endif +ifeq ($(DEB_HOST_ARCH),powerpc) + ECLIPSE_PLATFORM=ppc +endif +ifeq ($(DEB_HOST_ARCH),s390) + ECLIPSE_PLATFORM=s390 +endif + +PATCHES = \ + eclipse-cdt-libhover \ + eclipse-cdt-no-tests \ + eclipse-cdt-disable-filelog + +# eclipse-cdt-no-sdkbuild \ +# eclipse-cdt-build-linux + +# eclipse-cdt-platform-build-linux +# eclipse-cdt-sdk-build-linux \ +# eclipse-cdt-zzz-platform-build-linux-x86-only + +clean: + dh_testdir + + rm -rf $(SOURCE_TREE) $(homedir) debian/tmp debian/eclipse-cdt + rm -f *-stamp + dh_clean + +uncompress: uncompress-stamp +uncompress-stamp: debian/control + dh_testdir + + # The building happens inside the source-tree directory. This makes + # cleanup much easier. + mkdir -p "$(SOURCE_TREE)" + (cd "$(SOURCE_TREE)" && tar xjf ../"$(SOURCE)" > /dev/null) + + touch uncompress-stamp + +patch: patch-stamp +patch-stamp: uncompress-stamp + dh_testdir + + # This patch system was orginally copied off of the one found in cdbs. + @cd $(SOURCE_TREE)/$(RELENG_PLUGIN); \ + test $$(find $(CURDIR)/debian/patches/ -maxdepth 1 -name '*.patch' | wc -l) -eq 0 && exit 0; \ + for patchname in $(PATCHES); do \ + patch=$(CURDIR)/debian/patches/$$patchname.patch; \ + success=""; \ + echo -n "trying patch $$patchname at level "; \ + for level in 0 1 2 3; do \ + if test -z "$$success"; then \ + echo -n "$$level..."; \ + if patch -f -p$$level -E --dry-run < $$patch > /dev/null 2>&1; then \ + if patch -f -p$$level -E -V never < $$patch > /dev/null 2>&1; then \ + success=yes; \ + echo "success."; \ + fi; \ + fi; \ + fi; \ + done; \ + if test -z "$$success"; then \ + echo "failure."; \ + exit 1; \ + fi; \ + done + + sed -e "s/@ARCH@/$(ECLIPSE_PLATFORM)/" -i $(CURDIR)/$(SOURCE_TREE)/$(RELENG_PLUGIN)/platform/build.properties + sed -e "s/@ARCH@/$(ECLIPSE_PLATFORM)/" -i $(CURDIR)/$(SOURCE_TREE)/$(RELENG_PLUGIN)/sdk/build.properties + + touch patch-stamp + + +build: build-stamp +build-stamp: patch-stamp + dh_testdir + + # Create home. + mkdir home + + # build native code. + cd $(SOURCE_TREE)/org.eclipse.cdt.releng/results/plugins/org.eclipse.cdt.core.linux/library && \ + make ARCH=$(ECLIPSE_PLATFORM) CC='gcc -D_GNU_SOURCE' + + # Call eclipse headless to process CDT releng build scripts + cd $(SOURCE_TREE)/$(RELENG_PLUGIN) && \ + $(JAVA_RUN) -cp $(ECLIPSE_BASE)/startup.jar \ + -Duser.home=$(homedir) \ + -Dosgi.install.area=$(ECLIPSE_BASE) \ + org.eclipse.core.launcher.Main \ + -application org.eclipse.ant.core.antRunner \ + -DjavacFailOnError=true \ + -DdontUnzip=true \ + -DbaseLocation=$(ECLIPSE_BASE) \ + -Dpde.build.scripts=$(ECLIPSE_BASE)/plugins/org.eclipse.pde.build_3.2.1.r321_v20060823/scripts \ + -DskipFetch=true \ + -Dconfigs="linux,gtk,$(ECLIPSE_PLATFORM)" \ + -Dbaseos=linux \ + -Dbasews=gtk \ + -Dbasearch=$(ECLIPSE_PLATFORM) + + touch build-stamp + + +install: install-stamp +install-stamp: build + dh_testdir + dh_testroot + + # Install the tar file into our destination directory. + install -d debian/tmp/$(ECLIPSE_BASE) + tar xzf $(SOURCE_TREE)/$(RELENG_PLUGIN)/results/I.*/org.eclipse.cdt.sdk*.$(ECLIPSE_PLATFORM).tar.gz -C debian/tmp/$(ECLIPSE_BASE)/.. + + dh_installdirs + dh_install + + touch install-stamp + + +binary-indep: install + # Nothing to do here. + + +binary-arch: install + dh_testdir -a + dh_testroot -a + + dh_installdocs -a + dh_installexamples -a + dh_installmenu -a + dh_installman -a + dh_installinfo -a + dh_installchangelogs -a + dh_link -a + dh_fixperms -a + + dh_strip -a + dh_compress -a + dh_shlibdeps -a + dh_makeshlibs -a + dh_installdeb -a + dh_gencontrol -a + dh_md5sums -a + dh_builddeb -a + + +binary: binary-indep binary-arch --- eclipse-cdt-3.1.1.orig/debian/control +++ eclipse-cdt-3.1.1/debian/control @@ -0,0 +1,25 @@ +Source: eclipse-cdt +Section: devel +Priority: optional +Maintainer: Debian Java Maintainers +Uploaders: Michael Koch , Stephan Michels +Build-Depends: debhelper (>> 4.2), eclipse (>= 3.2.1), java-gcj-compat-dev, bzip2 +Standards-Version: 3.7.2 + +Package: eclipse-cdt +Architecture: any +Depends: eclipse-pde (>= 3.2.1), exuberant-ctags | ctags +Description: C/C++ Development Tools for Eclipse + The eclipse-cdt package contains Eclipse features and plugins that are + useful for C and C++ development. + . + The current release function includes: + * C/C++ Editor (basic functionality, syntax highlighting, code completion, + etc.) + * C/C++ Debugger (APIs & Default implementation, using GDB) + * C/C++ Launcher (APIs & Default implementation, launches and external + application) + * Parser + * Search Engine + * Content Assist Provider + * Makefile generator --- eclipse-cdt-3.1.1.orig/debian/copyright +++ eclipse-cdt-3.1.1/debian/copyright @@ -0,0 +1,227 @@ +This package was debianized by Michael Koch on +Wed, 07 Jul 2005 06:05:12 +0100. + +It can be downloaded from: +http://download.eclipse.org/tools/cdt/releases/eclipse3.1/ + +This software is copyright (c) 2000, 2005 IBM Corporation and others. + +Copyright: + +Eclipse Public License - v 1.0 + +THE ACCOMPANYING PROGRAM IS PROVIDED UNDER THE TERMS OF THIS ECLIPSE +PUBLIC LICENSE ("AGREEMENT"). ANY USE, REPRODUCTION OR DISTRIBUTION OF THE +PROGRAM CONSTITUTES RECIPIENT'S ACCEPTANCE OF THIS AGREEMENT. + +1. DEFINITIONS + +"Contribution" means: + +a) in the case of the initial Contributor, the initial code and documentation +distributed under this Agreement, and +b) in the case of each subsequent Contributor: + +i) changes to the Program, and + +ii) additions to the Program; + +where such changes and/or additions to the Program originate from and are +distributed by that particular Contributor. A Contribution 'originates' +from a Contributor if it was added to the Program by such Contributor itself +or anyone acting on such Contributor's behalf. Contributions do not include +additions to the Program which: (i) are separate modules of software +distributed in conjunction with the Program under their own license +agreement, and (ii) are not derivative works of the Program. + +"Contributor" means any person or entity that distributes the Program. + +"Licensed Patents " mean patent claims licensable by a Contributor which are +necessarily infringed by the use or sale of its Contribution alone or when +combined with the Program. + +"Program" means the Contributions distributed in accordance with this +Agreement. + +"Recipient" means anyone who receives the Program under this Agreement, +including all Contributors. + +2. GRANT OF RIGHTS + +a) Subject to the terms of this Agreement, each Contributor hereby grants +Recipient a non-exclusive, worldwide, royalty-free copyright license to +reproduce, prepare derivative works of, publicly display, publicly perform, +distribute and sublicense the Contribution of such Contributor, if any, +and such derivative works, in source code and object code form. + +b) Subject to the terms of this Agreement, each Contributor hereby grants +Recipient a non-exclusive, worldwide, royalty-free patent license under +Licensed Patents to make, use, sell, offer to sell, import and otherwise +transfer the Contribution of such Contributor, if any, in source code and +object code form. This patent license shall apply to the combination of +the Contribution and the Program if, at the time the Contribution is added +by the Contributor, such addition of the Contribution causes such +combination to be covered by the Licensed Patents. The patent license shall +not apply to any other combinations which include the Contribution. No +hardware per se is licensed hereunder. + +c) Recipient understands that although each Contributor grants the licenses +to its Contributions set forth herein, no assurances are provided by any +Contributor that the Program does not infringe the patent or other +intellectual property rights of any other entity. Each Contributor disclaims +any liability to Recipient for claims brought by any other entity based on +infringement of intellectual property rights or otherwise. As a condition to +exercising the rights and licenses granted hereunder, each Recipient hereby +assumes sole responsibility to secure any other intellectual property rights +needed, if any. For example, if a third party patent license is required to +allow Recipient to distribute the Program, it is Recipient's responsibility +to acquire that license before distributing the Program. + +d) Each Contributor represents that to its knowledge it has sufficient +copyright rights in its Contribution, if any, to grant the copyright license +set forth in this Agreement. + +3. REQUIREMENTS + +A Contributor may choose to distribute the Program in object code form under +its own license agreement, provided that: + +a) it complies with the terms and conditions of this Agreement; and + +b) its license agreement: + +i) effectively disclaims on behalf of all Contributors all warranties and +conditions, express and implied, including warranties or conditions of title +and non-infringement, and implied warranties or conditions of merchantability +and fitness for a particular purpose; + +ii) effectively excludes on behalf of all Contributors all liability for +damages, including direct, indirect, special, incidental and consequential +damages, such as lost profits; + +iii) states that any provisions which differ from this Agreement are offered +by that Contributor alone and not by any other party; and + +iv) states that source code for the Program is available from such +Contributor, and informs licensees how to obtain it in a reasonable manner on +or through a medium customarily used for software exchange. + +When the Program is made available in source code form: + +a) it must be made available under this Agreement; and + +b) a copy of this Agreement must be included with each copy of the Program. + +Contributors may not remove or alter any copyright notices contained within +the Program. + +Each Contributor must identify itself as the originator of its Contribution, +if any, in a manner that reasonably allows subsequent Recipients to identify +the originator of the Contribution. + +4. COMMERCIAL DISTRIBUTION + +Commercial distributors of software may accept certain responsibilities with +respect to end users, business partners and the like. While this license is +intended to facilitate the commercial use of the Program, the Contributor who +includes the Program in a commercial product offering should do so in a manner +which does not create potential liability for other Contributors. Therefore, +if a Contributor includes the Program in a commercial product offering, such +Contributor ("Commercial Contributor") hereby agrees to defend and indemnify +every other Contributor ("Indemnified Contributor") against any losses, +damages and costs (collectively "Losses") arising from claims, lawsuits and +other legal actions brought by a third party against the Indemnified +Contributor to the extent caused by the acts or omissions of such Commercial +Contributor in connection with its distribution of the Program in a commercial +product offering. The obligations in this section do not apply to any claims +or Losses relating to any actual or alleged intellectual property +infringement. In order to qualify, an Indemnified Contributor must: +a) promptly notify the Commercial Contributor in writing of such claim, and +b) allow the Commercial Contributor to control, and cooperate with the +Commercial Contributor in, the defense and any related settlement +negotiations. The Indemnified Contributor may participate in any such claim +at its own expense. + +For example, a Contributor might include the Program in a commercial product +offering, Product X. That Contributor is then a Commercial Contributor. If +that Commercial Contributor then makes performance claims, or offers +warranties related to Product X, those performance claims and warranties are +such Commercial Contributor's responsibility alone. Under this section, the +Commercial Contributor would have to defend claims against the other +Contributors related to those performance claims and warranties, and if a +court requires any other Contributor to pay any damages as a result, the +Commercial Contributor must pay those damages. + +5. NO WARRANTY + +EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, THE PROGRAM IS PROVIDED ON +AN "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER +EXPRESS OR IMPLIED INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR +CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A +PARTICULAR PURPOSE. Each Recipient is solely responsible for determining the +appropriateness of using and distributing the Program and assumes all +risks associated with its exercise of rights under this Agreement , +including but not limited to the risks and costs of program errors, +compliance with applicable laws, damage to or loss of data, programs or +equipment, and unavailability or interruption of operations. + +6. DISCLAIMER OF LIABILITY + +EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, NEITHER RECIPIENT NOR ANY +CONTRIBUTORS SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, +SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT LIMITATION +LOST PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE PROGRAM OR THE +EXERCISE OF ANY RIGHTS GRANTED HEREUNDER, EVEN IF ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. + +7. GENERAL + +If any provision of this Agreement is invalid or unenforceable under +applicable law, it shall not affect the validity or enforceability of the +remainder of the terms of this Agreement, and without further action by +the parties hereto, such provision shall be reformed to the minimum extent +necessary to make such provision valid and enforceable. + +If Recipient institutes patent litigation against any entity (including a +cross-claim or counterclaim in a lawsuit) alleging that the Program itself +(excluding combinations of the Program with other software or hardware) +infringes such Recipient's patent(s), then such Recipient's rights granted +under Section 2(b) shall terminate as of the date such litigation is filed. + +All Recipient's rights under this Agreement shall terminate if it fails to +comply with any of the material terms or conditions of this Agreement and +does not cure such failure in a reasonable period of time after becoming +aware of such noncompliance. If all Recipient's rights under this Agreement +terminate, Recipient agrees to cease use and distribution of the Program as +soon as reasonably practicable. However, Recipient's obligations under this +Agreement and any licenses granted by Recipient relating to the Program +shall continue and survive. + +Everyone is permitted to copy and distribute copies of this Agreement, but +in order to avoid inconsistency the Agreement is copyrighted and may only +be modified in the following manner. The Agreement Steward reserves the +right to publish new versions (including revisions) of this Agreement from +time to time. No one other than the Agreement Steward has the right to +modify this Agreement. The Eclipse Foundation is the initial Agreement +Steward. The Eclipse Foundation may assign the responsibility to serve as +the Agreement Steward to a suitable separate entity. Each new version of +the Agreement will be given a distinguishing version number. The Program +(including Contributions) may always be distributed subject to the version +of the Agreement under which it was received. In addition, after a new +version of the Agreement is published, Contributor may elect to distribute +the Program (including its Contributions) under the new version. Except as +expressly stated in Sections 2(a) and 2(b) above, Recipient receives no +rights or licenses to the intellectual property of any Contributor under +this Agreement, whether expressly, by implication, estoppel or otherwise. +All rights in the Program not expressly granted under this Agreement are +reserved. + +This Agreement is governed by the laws of the State of New York and the +intellectual property laws of the United States of America. No party to +this Agreement will bring a legal action under this Agreement more than +one year after the cause of action arose. Each party waives its rights to +a jury trial in any resulting litigation. + + --- eclipse-cdt-3.1.1.orig/debian/eclipse-cdt.install +++ eclipse-cdt-3.1.1/debian/eclipse-cdt.install @@ -0,0 +1,2 @@ +debian/tmp/usr/lib/eclipse/features usr/lib/eclipse +debian/tmp/usr/lib/eclipse/plugins usr/lib/eclipse --- eclipse-cdt-3.1.1.orig/debian/patches/eclipse-cdt-build-linux.patch +++ eclipse-cdt-3.1.1/debian/patches/eclipse-cdt-build-linux.patch @@ -0,0 +1,40 @@ +diff -r -u source-tree.orig/org.eclipse.cdt.releng/platform/build.properties source-tree/org.eclipse.cdt.releng/platform/build.properties +--- source-tree.orig/org.eclipse.cdt.releng/platform/build.properties 2005-11-18 02:41:32.000000000 +0100 ++++ source-tree/org.eclipse.cdt.releng/platform/build.properties 2005-11-18 02:45:38.000000000 +0100 +@@ -71,15 +71,7 @@ + # configs=win32,win32,x86 & linux,motif,x86 + # By default the value is *,*,* + configs=\ +- aix,motif,ppc \ +- & linux,gtk,x86 \ +- & linux,gtk,x86_64 \ +- & linux,gtk,ppc \ +- & linux,gtk,ia64 \ +- & macosx,carbon,ppc \ +- & qnx,photon,x86 \ +- & solaris,motif,sparc \ +- & win32,win32,x86 ++ linux,gtk,@ARCH@ + + archivesFormat=\ + aix,motif,ppc-tar \ +diff -r -u source-tree.orig/org.eclipse.cdt.releng/sdk/build.properties source-tree/org.eclipse.cdt.releng/sdk/build.properties +--- source-tree.orig/org.eclipse.cdt.releng/sdk/build.properties 2005-11-18 02:41:29.000000000 +0100 ++++ source-tree/org.eclipse.cdt.releng/sdk/build.properties 2005-11-18 02:44:59.000000000 +0100 +@@ -71,15 +71,7 @@ + # configs=win32,win32,x86 & linux,motif,x86 + # By default the value is *,*,* + configs=\ +- aix,motif,ppc\ +- & linux,gtk,x86 \ +- & linux,gtk,x86_64 \ +- & linux,gtk,ppc \ +- & linux,gtk,ia64 \ +- & macosx,carbon,ppc \ +- & qnx,photon,x86 \ +- & solaris,motif,sparc \ +- & win32,win32,x86 ++ linux,gtk,@ARCH@ + + archivesFormat=\ + aix,motif,ppc-tar \ --- eclipse-cdt-3.1.1.orig/debian/patches/eclipse-cdt-libhover.patch +++ eclipse-cdt-3.1.1/debian/patches/eclipse-cdt-libhover.patch @@ -0,0 +1,30710 @@ +diff -uNr ./eclipse-cdt-2.1.1.orig/org.eclipse.cdt.releng/libhoverdocs/fdl.texi ./eclipse-cdt-2.1.1/org.eclipse.cdt.releng/libhoverdocs/fdl.texi +--- ./eclipse-cdt-2.1.1.orig/org.eclipse.cdt.releng/libhoverdocs/fdl.texi 1969-12-31 18:00:00.000000000 -0600 ++++ ./eclipse-cdt-2.1.1/org.eclipse.cdt.releng/libhoverdocs/fdl.texi 2005-04-19 13:36:29.587735167 -0500 +@@ -0,0 +1,402 @@ ++ ++@appendix GNU Free Documentation License ++ ++@cindex FDL, GNU Free Documentation License ++@center Version 1.1, March 2000 ++ ++@display ++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 ++ ++@enumerate 0 ++@item ++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. ++ ++@item ++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. ++ ++@item ++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. ++ ++@item ++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. ++ ++@item ++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: ++ ++@enumerate A ++@item ++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. ++ ++@item ++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). ++ ++@item ++State on the Title page the name of the publisher of the ++Modified Version, as the publisher. ++ ++@item ++Preserve all the copyright notices of the Document. ++ ++@item ++Add an appropriate copyright notice for your modifications ++adjacent to the other copyright notices. ++ ++@item ++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. ++ ++@item ++Preserve in that license notice the full lists of Invariant Sections ++and required Cover Texts given in the Document's license notice. ++ ++@item ++Include an unaltered copy of this License. ++ ++@item ++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. ++ ++@item ++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. ++ ++@item ++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. ++ ++@item ++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. ++ ++@item ++Delete any section entitled ``Endorsements''. Such a section ++may not be included in the Modified Version. ++ ++@item ++Do not retitle any existing section as ``Endorsements'' ++or to conflict in title with any Invariant Section. ++@end enumerate ++ ++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. ++ ++@item ++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.'' ++ ++@item ++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. ++ ++@item ++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. ++ ++@item ++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. ++ ++@item ++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. ++ ++@item ++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 ++ ++@page ++@appendixsubsec 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: ++ ++@smallexample ++@group ++ Copyright (C) @var{year} @var{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''. ++@end group ++@end smallexample ++ ++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. ++ ++@c Local Variables: ++@c ispell-local-pdict: "ispell-dict" ++@c End: ++ +diff -uNr ./eclipse-cdt-2.1.1.orig/org.eclipse.cdt.releng/libhoverdocs/glibc.xml ./eclipse-cdt-2.1.1/org.eclipse.cdt.releng/libhoverdocs/glibc.xml +--- ./eclipse-cdt-2.1.1.orig/org.eclipse.cdt.releng/libhoverdocs/glibc.xml 1969-12-31 18:00:00.000000000 -0600 ++++ ./eclipse-cdt-2.1.1/org.eclipse.cdt.releng/libhoverdocs/glibc.xml 2005-04-19 13:36:29.665725142 -0500 +@@ -0,0 +1,29885 @@ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++]> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The argp_parse function parses the arguments in argv, of length ++ argc, using the argp parser argp. . <br> A value of zero ++ is the same as a struct argpcontaining all zeros. flags is a ++ set of flag bits that modify the parsing behavior. . input is ++ passed through to the argp parser argp, and has meaning defined ++ by argp. A typical usage is to pass a pointer to a structure ++ which is used for specifying parameters to the parser and ++ passing back the results. <br> Unless the ARGP_NO_EXIT or ++ ARGP_NO_HELP flags are included in flags, calling argp_parse may ++ result in the program exiting. This behavior is true if an ++ error is detected, or when an unknown option is encountered. . ++ <br> If arg_index is non-null, the index of the first ++ unparsed option in argv is returned as a value. <br> The ++ return value is zero for successful parsing, or an error code ++ (Error Codes) if an error is detected. Different argp parsers ++ may return arbitrary error codes, but the standard error codes ++ are: ENOMEM if a memory allocation error occurred, or EINVAL if ++ an unknown option or option argument is encountered. ++ ++ ++ ++ ++ ++ ++ This structure specifies how to parse a given set of options and ++ arguments, perhaps in conjunction with other argp parsers. It ++ has the following fields: <br> ++ ++ ++ ++ ++ A pointer to a vector of argp_option structures specifying which ++ options this argp parser understands; it may be zero if there ++ are no options at all. . <br> ++ ++ ++ ++ ++ A pointer to a function that defines actions for this parser; it ++ is called for each option parsed, and at other well-defined ++ points in the parsing process. A value of zero is the same as a ++ pointer to a function that always returns ARGP_ERR_UNKNOWN. . ++ <br> ++ ++ ++ ++ ++ If non-zero, a string describing what non-option arguments are ++ called by this parser. This is only used to print the Usage: ++ message. If it contains newlines, the strings separated by them ++ are considered alternative usage patterns and printed on ++ separate lines. Lines after the first are prefixed by or: ++ instead of Usage:. <br> ++ ++ ++ ++ ++ If non-zero, a string containing extra text to be printed before ++ and after the options in a long help message, with the two ++ sections separated by a vertical tab ('\v', '\013') character. ++ By convention, the documentation before the options is just a ++ short string explaining what the program does. Documentation ++ printed after the options describe behavior in more detail. ++ <br> ++ ++ ++ ++ ++ A pointer to a vector of argp_children structures. This pointer ++ specifies which additional argp parsers should be combined with ++ this one. . <br> ++ ++ ++ ++ ++ If non-zero, a pointer to a function that filters the output of ++ help messages. . <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ This structure specifies a single option that an argp parser ++ understands, as well as how to parse and document that option. ++ It has the following fields: <br> ++ ++ ++ ++ ++ The long name for this option, corresponding to the long option ++ --name; this field may be zero if this option only has a short ++ name. To specify multiple names for an option, additional ++ entries may follow this one, with the OPTION_ALIAS flag set. . ++ <br> ++ ++ ++ ++ ++ The integer key provided by the current option to the option ++ parser. If key has a value that is a printable ascii character ++ (i.e., isascii (key) is true), it also specifies a short option ++ -char, where char is the ascii character with the code key. ++ <br> ++ ++ ++ ++ ++ If non-zero, this is the name of an argument associated with ++ this option, which must be provided (e.g., with the --name=value ++ or -char value syntaxes), unless the OPTION_ARG_OPTIONAL flag ++ (Argp Option Flags) is set, in which case it may be provided. ++ <br> ++ ++ ++ ++ ++ Flags associated with this option, some of which are referred to ++ above. . <br> ++ ++ ++ ++ ++ A documentation string for this option, for printing in help ++ messages. <br> If both the name and key fields are zero, ++ this string will be printed tabbed left from the normal option ++ column, making it useful as a group header. This will be the ++ first thing printed in its group. In this usage, it's ++ conventional to end the string with a : character. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ Outputs the standard usage message for the argp parser referred ++ to by state to state->err_stream and terminate the program ++ with exit (argp_err_exit_status). . ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ Prints the printf format string fmt and following args, preceded ++ by the program name and :, and followed by a Try --help ++ message, and terminates the program with an exit status of ++ argp_err_exit_status. . ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ Similar to the standard gnu error-reporting function error, this ++ prints the program name and :, the printf format string fmt, and ++ the appropriate following args. If it is non-zero, the standard ++ unix error text for errnum is printed. If status is non-zero, ++ it terminates the program with that value as its exit status. ++ <br> The difference between argp_failure and argp_error is ++ that argp_error is for parsing errors, whereas argp_failure is ++ for other problems that occur during parsing but don't reflect a ++ syntactic problem with the input, such as illegal values for ++ options, bad phase of the moon, etc. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ Outputs a help message for the argp parser referred to by state, ++ to stream. The flags argument determines what sort of help ++ message is produced. . ++ ++ ++ ++ ++ ++ ++ This structure has the following fields, which may be modified ++ as noted: <br> ++ ++ ++ ++ ++ The top level argp parser being parsed. Note that this is often ++ not the same struct argp passed into argp_parse by the invoking ++ program. . It is an internal argp parser that contains options ++ implemented by argp_parse itself, such as --help. <br> ++ ++ ++ ++ ++ ++ ++ The argument vector being parsed. This may be modified. ++ <br> ++ ++ ++ ++ ++ The index in argv of the next argument to be parsed. This may ++ be modified. <br> One way to consume all remaining ++ arguments in the input is to set state->next = ++ state->argc, perhaps after recording the value of the next ++ field to find the consumed arguments. The current option can be ++ re-parsed immediately by decrementing this field, then modifying ++ state->argv[state->next] to reflect the option that should ++ be reexamined. <br> ++ ++ ++ ++ ++ The flags supplied to argp_parse. These may be modified, ++ although some flags may only take effect when argp_parse is ++ first invoked. . <br> ++ ++ ++ ++ ++ While calling a parsing function with the key argument ++ ARGP_KEY_ARG, this represents the number of the current arg, ++ starting at 0. It is incremented after each ARGP_KEY_ARG call ++ returns. At all other times, this is the number of ARGP_KEY_ARG ++ arguments that have been processed. <br> ++ ++ ++ ++ ++ If non-zero, the index in argv of the first argument following a ++ special -- argument. This prevents anything that follows from ++ being interpreted as an option. It is only set after argument ++ parsing has proceeded past this point. <br> ++ ++ ++ ++ ++ An arbitrary pointer passed in from the caller of argp_parse, in ++ the input argument. <br> ++ ++ ++ ++ ++ These are values that will be passed to child parsers. This ++ vector will be the same length as the number of children in the ++ current parser. Each child parser will be given the value of ++ state->child_inputs[i] as its state->input field, where i ++ is the index of the child in the this parser's children field. ++ . <br> ++ ++ ++ ++ ++ For the parser function's use. Initialized to 0, but otherwise ++ ignored by argp. <br> ++ ++ ++ ++ ++ The name used when printing messages. This is initialized to ++ argv[0], or program_invocation_name if argv[0] is unavailable. ++ <br> ++ ++ ++ ++ ++ ++ ++ The stdio streams used when argp prints. Error messages are ++ printed to err_stream, all other output, such as --help output) ++ to out_stream. These are initialized to stderr and stdout ++ respectively. . <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ An entry in the list of subsidiary argp parsers pointed to by ++ the children field in a struct argp. The fields are as follows: ++ <br> ++ ++ ++ ++ ++ The child argp parser, or zero to end of the list. <br> ++ ++ ++ ++ ++ Flags for this child. <br> ++ ++ ++ ++ ++ If non-zero, this is an optional header to be printed within ++ help output before the child options. As a side-effect, a ++ non-zero value forces the child options to be grouped together. ++ To achieve this effect without actually printing a header ++ string, use a value of "". As with header strings specified in ++ an option entry, the conventional value of the last character is ++ :. . <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This outputs a help message for the argp parser argp to stream. ++ The type of messages printed will be determined by flags. ++ <br> Any options such as --help that are implemented ++ automatically by argp itself will not be present in the help ++ output; for this reason it is best to use argp_state_help if ++ calling from within an argp parser function. . ++ ++ ++ ++ ++ ++ ++ This is a structure type used to hold the result returned by the ++ div function. It has the following members: <br> ++ ++ ++ ++ ++ The quotient from the division. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function div computes the quotient and remainder from the ++ division of numerator by denominator, returning the result in a ++ structure of type div_t. <br> If the result cannot be ++ represented (as in a division by zero), the behavior is ++ undefined. <br> Here is an example, albeit not a very ++ useful one. <br> @smallexample div_t result; result = div ++ (20, -6); @end smallexample <br> @noindent Now result.quot ++ is -3 and result.rem is 2. ++ ++ ++ ++ ++ ++ ++ This is a structure type used to hold the result returned by the ++ ldiv function. It has the following members: <br> ++ ++ ++ ++ ++ The quotient from the division. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The ldiv function is similar to div, except that the arguments ++ are of type long int and the result is returned as a structure ++ of type ldiv_t. ++ ++ ++ ++ ++ ++ ++ This is a structure type used to hold the result returned by the ++ lldiv function. It has the following members: <br> ++ ++ ++ ++ ++ The quotient from the division. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The lldiv function is like the div function, but the arguments ++ are of type long long int and the result is returned as a ++ structure of type lldiv_t. <br> The lldiv function was ++ added in ISO C99. ++ ++ ++ ++ ++ ++ ++ This is a structure type used to hold the result returned by the ++ imaxdiv function. It has the following members: <br> ++ ++ ++ ++ ++ The quotient from the division. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The imaxdiv function is like the div function, but the arguments ++ are of type intmax_t and the result is returned as a structure ++ of type imaxdiv_t. <br> See Integers for a description of ++ the intmax_t type. <br> The imaxdiv function was added in ++ ISO C99. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function returns -1 if x represents negative infinity, 1 if ++ x represents positive infinity, and 0 otherwise. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function returns -1 if x represents negative infinity, 1 if ++ x represents positive infinity, and 0 otherwise. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function returns -1 if x represents negative infinity, 1 if ++ x represents positive infinity, and 0 otherwise. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function returns a nonzero value if x is a ``not a number'' ++ value, and zero otherwise. <br> Note: The isnan macro ++ defined by ISO C99 overrides the BSD function. This is normally ++ not a problem, because the two routines behave identically. ++ However, if you really need to get the BSD function for some ++ reason, you can write <br> @smallexample (isnan) (x) @end ++ smallexample ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function returns a nonzero value if x is a ``not a number'' ++ value, and zero otherwise. <br> Note: The isnan macro ++ defined by ISO C99 overrides the BSD function. This is normally ++ not a problem, because the two routines behave identically. ++ However, if you really need to get the BSD function for some ++ reason, you can write <br> @smallexample (isnan) (x) @end ++ smallexample ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function returns a nonzero value if x is a ``not a number'' ++ value, and zero otherwise. <br> Note: The isnan macro ++ defined by ISO C99 overrides the BSD function. This is normally ++ not a problem, because the two routines behave identically. ++ However, if you really need to get the BSD function for some ++ reason, you can write <br> @smallexample (isnan) (x) @end ++ smallexample ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function returns a nonzero value if x is finite or a ``not ++ a number'' value, and zero otherwise. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function returns a nonzero value if x is finite or a ``not ++ a number'' value, and zero otherwise. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function returns a nonzero value if x is finite or a ``not ++ a number'' value, and zero otherwise. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++
++ ++ ++ This function clears all of the supported exception flags ++ indicated by excepts. <br> The function returns zero in ++ case the operation was successful, a non-zero value otherwise. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function raises the supported exceptions indicated by ++ excepts. If more than one exception bit in excepts is set the ++ order in which the exceptions are raised is undefined except ++ that overflow (FE_OVERFLOW) or underflow (FE_UNDERFLOW) are ++ raised before inexact (FE_INEXACT). Whether for overflow or ++ underflow the inexact exception is also raised is also ++ implementation dependent. <br> The function returns zero ++ in case the operation was successful, a non-zero value ++ otherwise. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ Test whether the exception flags indicated by the parameter ++ except are currently set. If any of them are, a nonzero value ++ is returned which specifies which exceptions are set. Otherwise ++ the result is zero. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function stores in the variable pointed to by flagp an ++ implementation-defined value representing the current setting of ++ the exception flags indicated by excepts. <br> The ++ function returns zero in case the operation was successful, a ++ non-zero value otherwise. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function restores the flags for the exceptions indicated by ++ excepts to the values stored in the variable pointed to by ++ flagp. <br> The function returns zero in case the ++ operation was successful, a non-zero value otherwise. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++
++ ++ ++ Returns the currently selected rounding mode, represented by one ++ of the values of the defined rounding mode macros. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ Changes the currently selected rounding mode to round. If round ++ does not correspond to one of the supported rounding modes ++ nothing is changed. fesetround returns zero if it changed the ++ rounding mode, a nonzero value if the mode is not supported. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ Store the floating-point environment in the variable pointed to ++ by envp. <br> The function returns zero in case the ++ operation was successful, a non-zero value otherwise. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ Store the current floating-point environment in the object ++ pointed to by envp. Then clear all exception flags, and set the ++ FPU to trap no exceptions. Not all FPUs support trapping no ++ exceptions; if feholdexcept cannot set this mode, it returns ++ nonzero value. If it succeeds, it returns zero. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ Set the floating-point environment to that described by envp. ++ <br> The function returns zero in case the operation was ++ successful, a non-zero value otherwise. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ Like fesetenv, this function sets the floating-point environment ++ to that described by envp. However, if any exceptions were ++ flagged in the status word before feupdateenv was called, they ++ remain flagged after the call. In other words, after ++ feupdateenv is called, the status word is the bitwise OR of the ++ previous status word and the one saved in envp. <br> The ++ function returns zero in case the operation was successful, a ++ non-zero value otherwise. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This functions enables traps for each of the exceptions as ++ indicated by the parameter except. The individual excepetions ++ are described in Status bit operations. Only the specified ++ exceptions are enabled, the status of the other exceptions is ++ not changed. <br> The function returns the previous ++ enabled exceptions in case the operation was successful, -1 ++ otherwise. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This functions disables traps for each of the exceptions as ++ indicated by the parameter except. The individual excepetions ++ are described in Status bit operations. Only the specified ++ exceptions are disabled, the status of the other exceptions is ++ not changed. <br> The function returns the previous ++ enabled exceptions in case the operation was successful, -1 ++ otherwise. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The function returns a bitmask of all currently enabled ++ exceptions. It returns -1 in case of failure. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the absolute value of number. <br> ++ Most computers use a two's complement integer representation, in ++ which the absolute value of INT_MIN (the smallest possible int) ++ cannot be represented; thus, abs (INT_MIN) is not defined. ++ <br> llabs and imaxdiv are new to ISO C99. <br> See ++ Integers for a description of the intmax_t type. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the absolute value of number. <br> ++ Most computers use a two's complement integer representation, in ++ which the absolute value of INT_MIN (the smallest possible int) ++ cannot be represented; thus, abs (INT_MIN) is not defined. ++ <br> llabs and imaxdiv are new to ISO C99. <br> See ++ Integers for a description of the intmax_t type. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the absolute value of number. <br> ++ Most computers use a two's complement integer representation, in ++ which the absolute value of INT_MIN (the smallest possible int) ++ cannot be represented; thus, abs (INT_MIN) is not defined. ++ <br> llabs and imaxdiv are new to ISO C99. <br> See ++ Integers for a description of the intmax_t type. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the absolute value of number. <br> ++ Most computers use a two's complement integer representation, in ++ which the absolute value of INT_MIN (the smallest possible int) ++ cannot be represented; thus, abs (INT_MIN) is not defined. ++ <br> llabs and imaxdiv are new to ISO C99. <br> See ++ Integers for a description of the intmax_t type. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function returns the absolute value of the floating-point ++ number number. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function returns the absolute value of the floating-point ++ number number. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function returns the absolute value of the floating-point ++ number number. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the absolute value of the complex number ++ z (Complex Numbers). The absolute value of a complex number is: ++ <br> @smallexample sqrt (creal (z) * creal (z) + cimag (z) ++ * cimag (z)) @end smallexample <br> This function should ++ always be used instead of the direct formula because it takes ++ special care to avoid losing precision. It may also take ++ advantage of hardware support for this operation. See hypot in ++ Exponents and Logarithms. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the absolute value of the complex number ++ z (Complex Numbers). The absolute value of a complex number is: ++ <br> @smallexample sqrt (creal (z) * creal (z) + cimag (z) ++ * cimag (z)) @end smallexample <br> This function should ++ always be used instead of the direct formula because it takes ++ special care to avoid losing precision. It may also take ++ advantage of hardware support for this operation. See hypot in ++ Exponents and Logarithms. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the absolute value of the complex number ++ z (Complex Numbers). The absolute value of a complex number is: ++ <br> @smallexample sqrt (creal (z) * creal (z) + cimag (z) ++ * cimag (z)) @end smallexample <br> This function should ++ always be used instead of the direct formula because it takes ++ special care to avoid losing precision. It may also take ++ advantage of hardware support for this operation. See hypot in ++ Exponents and Logarithms. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions are used to split the number value into a ++ normalized fraction and an exponent. <br> If the argument ++ value is not zero, the return value is value times a power of ++ two, and is always in the range 1/2 (inclusive) to 1 ++ (exclusive). The corresponding exponent is stored in *exponent; ++ the return value multiplied by 2 raised to this exponent equals ++ the original number value. <br> For example, frexp (12.8, ++ &exponent) returns 0.8 and stores 4 in exponent. <br> ++ If value is zero, then the return value is zero and zero is ++ stored in *exponent. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions are used to split the number value into a ++ normalized fraction and an exponent. <br> If the argument ++ value is not zero, the return value is value times a power of ++ two, and is always in the range 1/2 (inclusive) to 1 ++ (exclusive). The corresponding exponent is stored in *exponent; ++ the return value multiplied by 2 raised to this exponent equals ++ the original number value. <br> For example, frexp (12.8, ++ &exponent) returns 0.8 and stores 4 in exponent. <br> ++ If value is zero, then the return value is zero and zero is ++ stored in *exponent. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions are used to split the number value into a ++ normalized fraction and an exponent. <br> If the argument ++ value is not zero, the return value is value times a power of ++ two, and is always in the range 1/2 (inclusive) to 1 ++ (exclusive). The corresponding exponent is stored in *exponent; ++ the return value multiplied by 2 raised to this exponent equals ++ the original number value. <br> For example, frexp (12.8, ++ &exponent) returns 0.8 and stores 4 in exponent. <br> ++ If value is zero, then the return value is zero and zero is ++ stored in *exponent. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the result of multiplying the ++ floating-point number value by 2 raised to the power exponent. ++ (It can be used to reassemble floating-point numbers that were ++ taken apart by frexp.) <br> For example, ldexp (0.8, 4) ++ returns 12.8. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the result of multiplying the ++ floating-point number value by 2 raised to the power exponent. ++ (It can be used to reassemble floating-point numbers that were ++ taken apart by frexp.) <br> For example, ldexp (0.8, 4) ++ returns 12.8. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the result of multiplying the ++ floating-point number value by 2 raised to the power exponent. ++ (It can be used to reassemble floating-point numbers that were ++ taken apart by frexp.) <br> For example, ldexp (0.8, 4) ++ returns 12.8. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The scalb function is the BSD name for ldexp. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The scalb function is the BSD name for ldexp. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The scalb function is the BSD name for ldexp. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ scalbn is identical to scalb, except that the exponent n is an ++ int instead of a floating-point number. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ scalbn is identical to scalb, except that the exponent n is an ++ int instead of a floating-point number. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ scalbn is identical to scalb, except that the exponent n is an ++ int instead of a floating-point number. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ scalbln is identical to scalb, except that the exponent n is a ++ long int instead of a floating-point number. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ scalbln is identical to scalb, except that the exponent n is a ++ long int instead of a floating-point number. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ scalbln is identical to scalb, except that the exponent n is a ++ long int instead of a floating-point number. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ significand returns the mantissa of x scaled to the range [1, ++ 2). It is equivalent to scalb (x, (double) -ilogb (x)). ++ <br> This function exists mainly for use in certain ++ standardized tests of IEEE 754 conformance. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ significand returns the mantissa of x scaled to the range [1, ++ 2). It is equivalent to scalb (x, (double) -ilogb (x)). ++ <br> This function exists mainly for use in certain ++ standardized tests of IEEE 754 conformance. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ significand returns the mantissa of x scaled to the range [1, ++ 2). It is equivalent to scalb (x, (double) -ilogb (x)). ++ <br> This function exists mainly for use in certain ++ standardized tests of IEEE 754 conformance. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions round x upwards to the nearest integer, ++ returning that value as a double. Thus, ceil (1.5) is 2.0. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions round x upwards to the nearest integer, ++ returning that value as a double. Thus, ceil (1.5) is 2.0. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions round x upwards to the nearest integer, ++ returning that value as a double. Thus, ceil (1.5) is 2.0. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions round x downwards to the nearest integer, ++ returning that value as a double. Thus, floor (1.5) is 1.0 and ++ floor (-1.5) is -2.0. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions round x downwards to the nearest integer, ++ returning that value as a double. Thus, floor (1.5) is 1.0 and ++ floor (-1.5) is -2.0. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions round x downwards to the nearest integer, ++ returning that value as a double. Thus, floor (1.5) is 1.0 and ++ floor (-1.5) is -2.0. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The trunc functions round x towards zero to the nearest integer ++ (returned in floating-point format). Thus, trunc (1.5) is 1.0 ++ and trunc (-1.5) is -1.0. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The trunc functions round x towards zero to the nearest integer ++ (returned in floating-point format). Thus, trunc (1.5) is 1.0 ++ and trunc (-1.5) is -1.0. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The trunc functions round x towards zero to the nearest integer ++ (returned in floating-point format). Thus, trunc (1.5) is 1.0 ++ and trunc (-1.5) is -1.0. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions round x to an integer value according to the ++ current rounding mode. , for information about the various ++ rounding modes. The default rounding mode is to round to the ++ nearest integer; some machines support other modes, but ++ round-to-nearest is always used unless you explicitly select ++ another. <br> If x was not initially an integer, these ++ functions raise the inexact exception. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions round x to an integer value according to the ++ current rounding mode. , for information about the various ++ rounding modes. The default rounding mode is to round to the ++ nearest integer; some machines support other modes, but ++ round-to-nearest is always used unless you explicitly select ++ another. <br> If x was not initially an integer, these ++ functions raise the inexact exception. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions round x to an integer value according to the ++ current rounding mode. , for information about the various ++ rounding modes. The default rounding mode is to round to the ++ nearest integer; some machines support other modes, but ++ round-to-nearest is always used unless you explicitly select ++ another. <br> If x was not initially an integer, these ++ functions raise the inexact exception. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the same value as the rint functions, but ++ do not raise the inexact exception if x is not an integer. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the same value as the rint functions, but ++ do not raise the inexact exception if x is not an integer. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the same value as the rint functions, but ++ do not raise the inexact exception if x is not an integer. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions are similar to rint, but they round halfway ++ cases away from zero instead of to the nearest even integer. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions are similar to rint, but they round halfway ++ cases away from zero instead of to the nearest even integer. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions are similar to rint, but they round halfway ++ cases away from zero instead of to the nearest even integer. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions are just like rint, but they return a long int ++ instead of a floating-point number. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions are just like rint, but they return a long int ++ instead of a floating-point number. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions are just like rint, but they return a long int ++ instead of a floating-point number. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions are just like rint, but they return a long long ++ int instead of a floating-point number. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions are just like rint, but they return a long long ++ int instead of a floating-point number. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions are just like rint, but they return a long long ++ int instead of a floating-point number. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions are just like round, but they return a long int ++ instead of a floating-point number. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions are just like round, but they return a long int ++ instead of a floating-point number. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions are just like round, but they return a long int ++ instead of a floating-point number. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions are just like round, but they return a long long ++ int instead of a floating-point number. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions are just like round, but they return a long long ++ int instead of a floating-point number. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions are just like round, but they return a long long ++ int instead of a floating-point number. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions break the argument value into an integer part ++ and a fractional part (between -1 and 1, exclusive). Their sum ++ equals value. Each of the parts has the same sign as value, and ++ the integer part is always rounded toward zero. <br> modf ++ stores the integer part in *integer-part, and returns the ++ fractional part. For example, modf (2.5, &intpart) returns ++ 0.5 and stores 2.0 into intpart. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions break the argument value into an integer part ++ and a fractional part (between -1 and 1, exclusive). Their sum ++ equals value. Each of the parts has the same sign as value, and ++ the integer part is always rounded toward zero. <br> modf ++ stores the integer part in *integer-part, and returns the ++ fractional part. For example, modf (2.5, &intpart) returns ++ 0.5 and stores 2.0 into intpart. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions break the argument value into an integer part ++ and a fractional part (between -1 and 1, exclusive). Their sum ++ equals value. Each of the parts has the same sign as value, and ++ the integer part is always rounded toward zero. <br> modf ++ stores the integer part in *integer-part, and returns the ++ fractional part. For example, modf (2.5, &intpart) returns ++ 0.5 and stores 2.0 into intpart. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions compute the remainder from the division of ++ numerator by denominator. Specifically, the return value is ++ numerator - n * denominator, where n is the quotient of ++ numerator divided by denominator, rounded towards zero to an ++ integer. Thus, fmod (6.5, 2.3) returns 1.9, which is 6.5 minus ++ 4.6. <br> The result has the same sign as the numerator ++ and has magnitude less than the magnitude of the denominator. ++ <br> If denominator is zero, fmod signals a domain error. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions compute the remainder from the division of ++ numerator by denominator. Specifically, the return value is ++ numerator - n * denominator, where n is the quotient of ++ numerator divided by denominator, rounded towards zero to an ++ integer. Thus, fmod (6.5, 2.3) returns 1.9, which is 6.5 minus ++ 4.6. <br> The result has the same sign as the numerator ++ and has magnitude less than the magnitude of the denominator. ++ <br> If denominator is zero, fmod signals a domain error. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions compute the remainder from the division of ++ numerator by denominator. Specifically, the return value is ++ numerator - n * denominator, where n is the quotient of ++ numerator divided by denominator, rounded towards zero to an ++ integer. Thus, fmod (6.5, 2.3) returns 1.9, which is 6.5 minus ++ 4.6. <br> The result has the same sign as the numerator ++ and has magnitude less than the magnitude of the denominator. ++ <br> If denominator is zero, fmod signals a domain error. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions are like fmod except that they rounds the ++ internal quotient n to the nearest integer instead of towards ++ zero to an integer. For example, drem (6.5, 2.3) returns -0.4, ++ which is 6.5 minus 6.9. <br> The absolute value of the ++ result is less than or equal to half the absolute value of the ++ denominator. The difference between fmod (numerator, ++ denominator) and drem (numerator, denominator) is always either ++ denominator, minus denominator, or zero. <br> If ++ denominator is zero, drem signals a domain error. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions are like fmod except that they rounds the ++ internal quotient n to the nearest integer instead of towards ++ zero to an integer. For example, drem (6.5, 2.3) returns -0.4, ++ which is 6.5 minus 6.9. <br> The absolute value of the ++ result is less than or equal to half the absolute value of the ++ denominator. The difference between fmod (numerator, ++ denominator) and drem (numerator, denominator) is always either ++ denominator, minus denominator, or zero. <br> If ++ denominator is zero, drem signals a domain error. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions are like fmod except that they rounds the ++ internal quotient n to the nearest integer instead of towards ++ zero to an integer. For example, drem (6.5, 2.3) returns -0.4, ++ which is 6.5 minus 6.9. <br> The absolute value of the ++ result is less than or equal to half the absolute value of the ++ denominator. The difference between fmod (numerator, ++ denominator) and drem (numerator, denominator) is always either ++ denominator, minus denominator, or zero. <br> If ++ denominator is zero, drem signals a domain error. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is another name for drem. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is another name for drem. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is another name for drem. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return x but with the sign of y. They work even ++ if x or y are NaN or zero. Both of these can carry a sign ++ (although not all implementations support it) and this is one of ++ the few operations that can tell the difference. <br> ++ copysign never raises an exception. @c except signalling NaNs ++ <br> This function is defined in IEC 559 (and the appendix ++ with recommended functions in IEEE 754/IEEE 854). ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return x but with the sign of y. They work even ++ if x or y are NaN or zero. Both of these can carry a sign ++ (although not all implementations support it) and this is one of ++ the few operations that can tell the difference. <br> ++ copysign never raises an exception. @c except signalling NaNs ++ <br> This function is defined in IEC 559 (and the appendix ++ with recommended functions in IEEE 754/IEEE 854). ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return x but with the sign of y. They work even ++ if x or y are NaN or zero. Both of these can carry a sign ++ (although not all implementations support it) and this is one of ++ the few operations that can tell the difference. <br> ++ copysign never raises an exception. @c except signalling NaNs ++ <br> This function is defined in IEC 559 (and the appendix ++ with recommended functions in IEEE 754/IEEE 854). ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ signbit is a generic macro which can work on all floating-point ++ types. It returns a nonzero value if the value of x has its ++ sign bit set. <br> This is not the same as x < 0.0, ++ because IEEE 754 floating point allows zero to be signed. The ++ comparison -0.0 < 0.0 is false, but signbit (-0.0) will ++ return a nonzero value. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The nextafter function returns the next representable neighbor ++ of x in the direction towards y. The size of the step between x ++ and the result depends on the type of the result. If x = y the ++ function simply returns y. If either value is NaN, NaN is ++ returned. Otherwise a value corresponding to the value of the ++ least significant bit in the mantissa is added or subtracted, ++ depending on the direction. nextafter will signal overflow or ++ underflow if the result goes outside of the range of normalized ++ numbers. <br> This function is defined in IEC 559 (and the ++ appendix with recommended functions in IEEE 754/IEEE 854). ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The nextafter function returns the next representable neighbor ++ of x in the direction towards y. The size of the step between x ++ and the result depends on the type of the result. If x = y the ++ function simply returns y. If either value is NaN, NaN is ++ returned. Otherwise a value corresponding to the value of the ++ least significant bit in the mantissa is added or subtracted, ++ depending on the direction. nextafter will signal overflow or ++ underflow if the result goes outside of the range of normalized ++ numbers. <br> This function is defined in IEC 559 (and the ++ appendix with recommended functions in IEEE 754/IEEE 854). ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The nextafter function returns the next representable neighbor ++ of x in the direction towards y. The size of the step between x ++ and the result depends on the type of the result. If x = y the ++ function simply returns y. If either value is NaN, NaN is ++ returned. Otherwise a value corresponding to the value of the ++ least significant bit in the mantissa is added or subtracted, ++ depending on the direction. nextafter will signal overflow or ++ underflow if the result goes outside of the range of normalized ++ numbers. <br> This function is defined in IEC 559 (and the ++ appendix with recommended functions in IEEE 754/IEEE 854). ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions are identical to the corresponding versions of ++ nextafter except that their second argument is a long double. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions are identical to the corresponding versions of ++ nextafter except that their second argument is a long double. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions are identical to the corresponding versions of ++ nextafter except that their second argument is a long double. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The nan function returns a representation of NaN, provided that ++ NaN is supported by the target platform. nan ("n-char-sequence") ++ is equivalent to strtod ("NAN(n-char-sequence)"). <br> The ++ argument tagp is used in an unspecified manner. On IEEE 754 ++ systems, there are many representations of NaN, and tagp selects ++ one. On other systems it may do nothing. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The nan function returns a representation of NaN, provided that ++ NaN is supported by the target platform. nan ("n-char-sequence") ++ is equivalent to strtod ("NAN(n-char-sequence)"). <br> The ++ argument tagp is used in an unspecified manner. On IEEE 754 ++ systems, there are many representations of NaN, and tagp selects ++ one. On other systems it may do nothing. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The nan function returns a representation of NaN, provided that ++ NaN is supported by the target platform. nan ("n-char-sequence") ++ is equivalent to strtod ("NAN(n-char-sequence)"). <br> The ++ argument tagp is used in an unspecified manner. On IEEE 754 ++ systems, there are many representations of NaN, and tagp selects ++ one. On other systems it may do nothing. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The fmin function returns the lesser of the two values x and y. ++ It is similar to the expression @smallexample ((x) < (y) ? ++ (x) : (y)) @end smallexample except that x and y are only ++ evaluated once. <br> If an argument is NaN, the other ++ argument is returned. If both arguments are NaN, NaN is ++ returned. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The fmin function returns the lesser of the two values x and y. ++ It is similar to the expression @smallexample ((x) < (y) ? ++ (x) : (y)) @end smallexample except that x and y are only ++ evaluated once. <br> If an argument is NaN, the other ++ argument is returned. If both arguments are NaN, NaN is ++ returned. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The fmin function returns the lesser of the two values x and y. ++ It is similar to the expression @smallexample ((x) < (y) ? ++ (x) : (y)) @end smallexample except that x and y are only ++ evaluated once. <br> If an argument is NaN, the other ++ argument is returned. If both arguments are NaN, NaN is ++ returned. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The fmax function returns the greater of the two values x and y. ++ <br> If an argument is NaN, the other argument is ++ returned. If both arguments are NaN, NaN is returned. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The fmax function returns the greater of the two values x and y. ++ <br> If an argument is NaN, the other argument is ++ returned. If both arguments are NaN, NaN is returned. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The fmax function returns the greater of the two values x and y. ++ <br> If an argument is NaN, the other argument is ++ returned. If both arguments are NaN, NaN is returned. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The fdim function returns the positive difference between x and ++ y. The positive difference is x - y if x is greater than y, and ++ 0 otherwise. <br> If x, y, or both are NaN, NaN is ++ returned. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The fdim function returns the positive difference between x and ++ y. The positive difference is x - y if x is greater than y, and ++ 0 otherwise. <br> If x, y, or both are NaN, NaN is ++ returned. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The fdim function returns the positive difference between x and ++ y. The positive difference is x - y if x is greater than y, and ++ 0 otherwise. <br> If x, y, or both are NaN, NaN is ++ returned. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ @cindex butterfly The fma function performs floating-point ++ multiply-add. This is the operation (x y) + z, but the ++ intermediate result is not rounded to the destination type. ++ This can sometimes improve the precision of a calculation. ++ <br> This function was introduced because some processors ++ have a special instruction to perform multiply-add. The C ++ compiler cannot use it directly, because the expression x*y + z ++ is defined to round the intermediate result. fma lets you ++ choose when you want to round only once. <br> @vindex ++ FP_FAST_FMA On processors which do not implement multiply-add in ++ hardware, fma can be very slow since it must avoid intermediate ++ rounding. math.h defines the symbols FP_FAST_FMA, FP_FAST_FMAF, ++ and FP_FAST_FMAL when the corresponding version of fma is no ++ slower than the expression x*y + z. In the GNU C library, this ++ always means the operation is implemented in hardware. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ @cindex butterfly The fma function performs floating-point ++ multiply-add. This is the operation (x y) + z, but the ++ intermediate result is not rounded to the destination type. ++ This can sometimes improve the precision of a calculation. ++ <br> This function was introduced because some processors ++ have a special instruction to perform multiply-add. The C ++ compiler cannot use it directly, because the expression x*y + z ++ is defined to round the intermediate result. fma lets you ++ choose when you want to round only once. <br> @vindex ++ FP_FAST_FMA On processors which do not implement multiply-add in ++ hardware, fma can be very slow since it must avoid intermediate ++ rounding. math.h defines the symbols FP_FAST_FMA, FP_FAST_FMAF, ++ and FP_FAST_FMAL when the corresponding version of fma is no ++ slower than the expression x*y + z. In the GNU C library, this ++ always means the operation is implemented in hardware. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ @cindex butterfly The fma function performs floating-point ++ multiply-add. This is the operation (x y) + z, but the ++ intermediate result is not rounded to the destination type. ++ This can sometimes improve the precision of a calculation. ++ <br> This function was introduced because some processors ++ have a special instruction to perform multiply-add. The C ++ compiler cannot use it directly, because the expression x*y + z ++ is defined to round the intermediate result. fma lets you ++ choose when you want to round only once. <br> @vindex ++ FP_FAST_FMA On processors which do not implement multiply-add in ++ hardware, fma can be very slow since it must avoid intermediate ++ rounding. math.h defines the symbols FP_FAST_FMA, FP_FAST_FMAF, ++ and FP_FAST_FMAL when the corresponding version of fma is no ++ slower than the expression x*y + z. In the GNU C library, this ++ always means the operation is implemented in hardware. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the real part of the complex number z. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the real part of the complex number z. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the real part of the complex number z. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the imaginary part of the complex number ++ z. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the imaginary part of the complex number ++ z. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the imaginary part of the complex number ++ z. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the conjugate value of the complex number ++ z. The conjugate of a complex number has the same real part and ++ a negated imaginary part. In other words, conj(a + bi) = a + ++ -bi. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the conjugate value of the complex number ++ z. The conjugate of a complex number has the same real part and ++ a negated imaginary part. In other words, conj(a + bi) = a + ++ -bi. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the conjugate value of the complex number ++ z. The conjugate of a complex number has the same real part and ++ a negated imaginary part. In other words, conj(a + bi) = a + ++ -bi. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the argument of the complex number z. The ++ argument of a complex number is the angle in the complex plane ++ between the positive real axis and a line passing through zero ++ and the number. This angle is measured in the usual fashion and ++ ranges from 0 to 2. <br> carg has a branch cut along the ++ positive real axis. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the argument of the complex number z. The ++ argument of a complex number is the angle in the complex plane ++ between the positive real axis and a line passing through zero ++ and the number. This angle is measured in the usual fashion and ++ ranges from 0 to 2. <br> carg has a branch cut along the ++ positive real axis. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the argument of the complex number z. The ++ argument of a complex number is the angle in the complex plane ++ between the positive real axis and a line passing through zero ++ and the number. This angle is measured in the usual fashion and ++ ranges from 0 to 2. <br> carg has a branch cut along the ++ positive real axis. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the projection of the complex value z ++ onto the Riemann sphere. Values with a infinite imaginary part ++ are projected to positive infinity on the real axis, even if the ++ real part is NaN. If the real part is infinite, the result is ++ equivalent to <br> @smallexample INFINITY + I * copysign ++ (0.0, cimag (z)) @end smallexample ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the projection of the complex value z ++ onto the Riemann sphere. Values with a infinite imaginary part ++ are projected to positive infinity on the real axis, even if the ++ real part is NaN. If the real part is infinite, the result is ++ equivalent to <br> @smallexample INFINITY + I * copysign ++ (0.0, cimag (z)) @end smallexample ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the projection of the complex value z ++ onto the Riemann sphere. Values with a infinite imaginary part ++ are projected to positive infinity on the real axis, even if the ++ real part is NaN. If the real part is infinite, the result is ++ equivalent to <br> @smallexample INFINITY + I * copysign ++ (0.0, cimag (z)) @end smallexample ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The strtol (``string-to-long'') function converts the initial ++ part of string to a signed integer, which is returned as a value ++ of type long int. <br> This function attempts to decompose ++ string as follows: <br> @itemize @bullet @item A (possibly ++ empty) sequence of whitespace characters. Which characters are ++ whitespace is determined by the isspace function (Classification ++ of Characters). These are discarded. <br> @item An ++ optional plus or minus sign (+ or -). <br> @item A ++ nonempty sequence of digits in the radix specified by base. ++ <br> If base is zero, decimal radix is assumed unless the ++ series of digits begins with 0 (specifying octal radix), or 0x ++ or 0X (specifying hexadecimal radix); in other words, the same ++ syntax used for integer constants in C. <br> Otherwise ++ base must have a value between 2 and 36. If base is 16, the ++ digits may optionally be preceded by 0x or 0X. If base has no ++ legal value the value returned is 0l and the global variable ++ errno is set to EINVAL. <br> @item Any remaining ++ characters in the string. If tailptr is not a null pointer, ++ strtol stores a pointer to this tail in *tailptr. @end itemize ++ <br> If the string is empty, contains only whitespace, or ++ does not contain an initial substring that has the expected ++ syntax for an integer in the specified base, no conversion is ++ performed. In this case, strtol returns a value of zero and the ++ value stored in *tailptr is the value of string. <br> In a ++ locale other than the standard "C" locale, this function may ++ recognize additional implementation-dependent syntax. <br> ++ If the string has valid syntax for an integer but the value is ++ not representable because of overflow, strtol returns either ++ LONG_MAX or LONG_MIN (Range of Type), as appropriate for the ++ sign of the value. It also sets errno to ERANGE to indicate ++ there was overflow. <br> You should not check for errors ++ by examining the return value of strtol, because the string ++ might be a valid representation of 0l, LONG_MAX, or LONG_MIN. ++ Instead, check whether tailptr points to what you expect after ++ the number (e.g. '\0' if the string should end after the ++ number). You also need to clear errno before the call and check ++ it afterward, in case there was overflow. <br> There is an ++ example at the end of this section. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The wcstol function is equivalent to the strtol function in ++ nearly all aspects but handles wide character strings. ++ <br> The wcstol function was introduced in Amendment 1 of ++ ISO C90. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The strtoul (``string-to-unsigned-long'') function is like ++ strtol except it converts to an unsigned long int value. The ++ syntax is the same as described above for strtol. The value ++ returned on overflow is ULONG_MAX (Range of Type). <br> If ++ string depicts a negative number, strtoul acts the same as ++ strtol but casts the result to an unsigned integer. That means ++ for example that strtoul on "-1" returns ULONG_MAX and an input ++ more negative than LONG_MIN returns (ULONG_MAX + 1) / 2. ++ <br> strtoul sets errno to EINVAL if base is out of range, ++ or ERANGE on overflow. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The wcstoul function is equivalent to the strtoul function in ++ nearly all aspects but handles wide character strings. ++ <br> The wcstoul function was introduced in Amendment 1 of ++ ISO C90. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The strtoll function is like strtol except that it returns a ++ long long int value, and accepts numbers with a correspondingly ++ larger range. <br> If the string has valid syntax for an ++ integer but the value is not representable because of overflow, ++ strtoll returns either LONG_LONG_MAX or LONG_LONG_MIN (Range of ++ Type), as appropriate for the sign of the value. It also sets ++ errno to ERANGE to indicate there was overflow. <br> The ++ strtoll function was introduced in ISO C99. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The wcstoll function is equivalent to the strtoll function in ++ nearly all aspects but handles wide character strings. ++ <br> The wcstoll function was introduced in Amendment 1 of ++ ISO C90. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ strtoq (``string-to-quad-word'') is the BSD name for strtoll. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The wcstoq function is equivalent to the strtoq function in ++ nearly all aspects but handles wide character strings. ++ <br> The wcstoq function is a GNU extension. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The strtoull function is related to strtoll the same way strtoul ++ is related to strtol. <br> The strtoull function was ++ introduced in ISO C99. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The wcstoull function is equivalent to the strtoull function in ++ nearly all aspects but handles wide character strings. ++ <br> The wcstoull function was introduced in Amendment 1 ++ of ISO C90. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ strtouq is the BSD name for strtoull. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The wcstouq function is equivalent to the strtouq function in ++ nearly all aspects but handles wide character strings. ++ <br> The wcstoq function is a GNU extension. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The strtoimax function is like strtol except that it returns a ++ intmax_t value, and accepts numbers of a corresponding range. ++ <br> If the string has valid syntax for an integer but the ++ value is not representable because of overflow, strtoimax ++ returns either INTMAX_MAX or INTMAX_MIN (Integers), as ++ appropriate for the sign of the value. It also sets errno to ++ ERANGE to indicate there was overflow. <br> See Integers ++ for a description of the intmax_t type. The strtoimax function ++ was introduced in ISO C99. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The wcstoimax function is equivalent to the strtoimax function ++ in nearly all aspects but handles wide character strings. ++ <br> The wcstoimax function was introduced in ISO C99. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The strtoumax function is related to strtoimax the same way that ++ strtoul is related to strtol. <br> See Integers for a ++ description of the intmax_t type. The strtoumax function was ++ introduced in ISO C99. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The wcstoumax function is equivalent to the strtoumax function ++ in nearly all aspects but handles wide character strings. ++ <br> The wcstoumax function was introduced in ISO C99. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to the strtol function with a base ++ argument of 10, except that it need not detect overflow errors. ++ The atol function is provided mostly for compatibility with ++ existing code; using strtol is more robust. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is like atol, except that it returns an int. The ++ atoi function is also considered obsolete; use strtol instead. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to atol, except it returns a long long ++ int. <br> The atoll function was introduced in ISO C99. ++ It too is obsolete (despite having just been added); use strtoll ++ instead. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The strtod (``string-to-double'') function converts the initial ++ part of string to a floating-point number, which is returned as ++ a value of type double. <br> This function attempts to ++ decompose string as follows: <br> @itemize @bullet @item A ++ (possibly empty) sequence of whitespace characters. Which ++ characters are whitespace is determined by the isspace function ++ (Classification of Characters). These are discarded. <br> ++ @item An optional plus or minus sign (+ or -). <br> @item ++ A floating point number in decimal or hexadecimal format. The ++ decimal format is: @itemize @minus <br> @item A nonempty ++ sequence of digits optionally containing a decimal-point ++ character---normally ., but it depends on the locale (General ++ Numeric). <br> @item An optional exponent part, consisting ++ of a character e or E, an optional sign, and a sequence of ++ digits. <br> @end itemize <br> The hexadecimal ++ format is as follows: @itemize @minus <br> @item A 0x or ++ 0X followed by a nonempty sequence of hexadecimal digits ++ optionally containing a decimal-point character---normally ., ++ but it depends on the locale (General Numeric). <br> @item ++ An optional binary-exponent part, consisting of a character p or ++ P, an optional sign, and a sequence of digits. <br> @end ++ itemize <br> @item Any remaining characters in the string. ++ If tailptr is not a null pointer, a pointer to this tail of the ++ string is stored in *tailptr. @end itemize <br> If the ++ string is empty, contains only whitespace, or does not contain ++ an initial substring that has the expected syntax for a ++ floating-point number, no conversion is performed. In this ++ case, strtod returns a value of zero and the value returned in ++ *tailptr is the value of string. <br> In a locale other ++ than the standard "C" or "POSIX" locales, this function may ++ recognize additional locale-dependent syntax. <br> If the ++ string has valid syntax for a floating-point number but the ++ value is outside the range of a double, strtod will signal ++ overflow or underflow as described in Math Error Reporting. ++ <br> strtod recognizes four special input strings. The ++ strings "inf" and "infinity" are converted to , or to the ++ largest representable value if the floating-point format doesn't ++ support infinities. You can prepend a "+" or "-" to specify the ++ sign. Case is ignored when scanning these strings. <br> ++ The strings "nan" and "nan(chars)" are converted to NaN. Again, ++ case is ignored. If chars are provided, they are used in some ++ unspecified fashion to select a particular representation of NaN ++ (there can be several). <br> Since zero is a valid result ++ as well as the value returned on error, you should check for ++ errors in the same way as for strtol, by examining errno and ++ tailptr. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions are analogous to strtod, but return float and ++ long double values respectively. They report errors in the same ++ way as strtod. strtof can be substantially faster than strtod, ++ but has less precision; conversely, strtold can be much slower ++ but has more precision (on systems where long double is a ++ separate type). <br> These functions have been GNU ++ extensions and are new to ISO C99. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions are analogous to strtod, but return float and ++ long double values respectively. They report errors in the same ++ way as strtod. strtof can be substantially faster than strtod, ++ but has less precision; conversely, strtold can be much slower ++ but has more precision (on systems where long double is a ++ separate type). <br> These functions have been GNU ++ extensions and are new to ISO C99. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The wcstod, wcstof, and wcstol functions are equivalent in ++ nearly all aspect to the strtod, strtof, and strtold functions ++ but it handles wide character string. <br> The wcstod ++ function was introduced in Amendment 1 of ISO C90. The wcstof ++ and wcstold functions were introduced in ISO C99. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The wcstod, wcstof, and wcstol functions are equivalent in ++ nearly all aspect to the strtod, strtof, and strtold functions ++ but it handles wide character string. <br> The wcstod ++ function was introduced in Amendment 1 of ISO C90. The wcstof ++ and wcstold functions were introduced in ISO C99. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The wcstod, wcstof, and wcstol functions are equivalent in ++ nearly all aspect to the strtod, strtof, and strtold functions ++ but it handles wide character string. <br> The wcstod ++ function was introduced in Amendment 1 of ISO C90. The wcstof ++ and wcstold functions were introduced in ISO C99. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to the strtod function, except that it ++ need not detect overflow and underflow errors. The atof ++ function is provided mostly for compatibility with existing ++ code; using strtod is more robust. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The function ecvt converts the floating-point number value to a ++ string with at most ndigit decimal digits. The returned string ++ contains no decimal point or sign. The first digit of the string ++ is non-zero (unless value is actually zero) and the last digit ++ is rounded to nearest. *decpt is set to the index in the string ++ of the first digit after the decimal point. *neg is set to a ++ nonzero value if value is negative, zero otherwise. <br> ++ If ndigit decimal digits would exceed the precision of a double ++ it is reduced to a system-specific value. <br> The ++ returned string is statically allocated and overwritten by each ++ call to ecvt. <br> If value is zero, it is implementation ++ defined whether *decpt is 0 or 1. <br> For example: ecvt ++ (12.3, 5, &d, &n) returns "12300" and sets d to 2 and n ++ to 0. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The function fcvt is like ecvt, but ndigit specifies the number ++ of digits after the decimal point. If ndigit is less than zero, ++ value is rounded to the ndigit+1'th place to the left of the ++ decimal point. For example, if ndigit is -1, value will be ++ rounded to the nearest 10. If ndigit is negative and larger ++ than the number of digits to the left of the decimal point in ++ value, value will be rounded to one significant digit. ++ <br> If ndigit decimal digits would exceed the precision ++ of a double it is reduced to a system-specific value. <br> ++ The returned string is statically allocated and overwritten by ++ each call to fcvt. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ gcvt is functionally equivalent to sprintf(buf, "%*g", ndigit, ++ value. It is provided only for compatibility's sake. It ++ returns buf. <br> If ndigit decimal digits would exceed ++ the precision of a double it is reduced to a system-specific ++ value. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is equivalent to ecvt except that it takes a long ++ double for the first parameter and that ndigit is restricted by ++ the precision of a long double. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is equivalent to fcvt except that it takes a long ++ double for the first parameter and that ndigit is restricted by ++ the precision of a long double. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is equivalent to gcvt except that it takes a long ++ double for the first parameter and that ndigit is restricted by ++ the precision of a long double. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The ecvt_r function is the same as ecvt, except that it places ++ its result into the user-specified buffer pointed to by buf, ++ with length len. <br> This function is a GNU extension. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The fcvt_r function is the same as fcvt, except that it places ++ its result into the user-specified buffer pointed to by buf, ++ with length len. <br> This function is a GNU extension. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The qecvt_r function is the same as qecvt, except that it places ++ its result into the user-specified buffer pointed to by buf, ++ with length len. <br> This function is a GNU extension. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The qfcvt_r function is the same as qfcvt, except that it places ++ its result into the user-specified buffer pointed to by buf, ++ with length len. <br> This function is a GNU extension. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++
++
++
++ ++ ++ The mbsinit function determines whether the state object pointed ++ to by ps is in the initial state. If ps is a null pointer or ++ the object is in the initial state the return value is nonzero. ++ Otherwise it is zero. <br> @pindex wchar.h mbsinit was ++ introduced in Amendment 1 to ISO C90 and is declared in wchar.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The btowc function (``byte to wide character'') converts a valid ++ single byte character c in the initial shift state into the wide ++ character equivalent using the conversion rules from the ++ currently selected locale of the LC_CTYPE category. <br> ++ If (unsigned char) c is no valid single byte multibyte character ++ or if c is EOF, the function returns WEOF. <br> Please ++ note the restriction of c being tested for validity only in the ++ initial shift state. No mbstate_t object is used from which the ++ state information is taken, and the function also does not use ++ any static state. <br> @pindex wchar.h The btowc function ++ was introduced in Amendment 1 to ISO C90 and is declared in ++ wchar.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The wctob function (``wide character to byte'') takes as the ++ parameter a valid wide character. If the multibyte ++ representation for this character in the initial state is ++ exactly one byte long, the return value of this function is this ++ character. Otherwise the return value is EOF. <br> ++ @pindex wchar.h wctob was introduced in Amendment 1 to ISO C90 ++ and is declared in wchar.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ @cindex stateful The mbrtowc function (``multibyte restartable ++ to wide character'') converts the next multibyte character in ++ the string pointed to by s into a wide character and stores it ++ in the wide character string pointed to by pwc. The conversion ++ is performed according to the locale currently selected for the ++ LC_CTYPE category. If the conversion for the character set used ++ in the locale requires a state, the multibyte string is ++ interpreted in the state represented by the object pointed to by ++ ps. If ps is a null pointer, a static, internal state variable ++ used only by the mbrtowc function is used. <br> If the ++ next multibyte character corresponds to the NUL wide character, ++ the return value of the function is 0 and the state object is ++ afterwards in the initial state. If the next n or fewer bytes ++ form a correct multibyte character, the return value is the ++ number of bytes starting from s that form the multibyte ++ character. The conversion state is updated according to the ++ bytes consumed in the conversion. In both cases the wide ++ character (either the L'\0' or the one found in the conversion) ++ is stored in the string pointed to by pwc if pwc is not null. ++ <br> If the first n bytes of the multibyte string possibly ++ form a valid multibyte character but there are more than n bytes ++ needed to complete it, the return value of the function is ++ (size_t) -2 and no value is stored. Please note that this can ++ happen even if n has a value greater than or equal to MB_CUR_MAX ++ since the input might contain redundant shift sequences. ++ <br> If the first n bytes of the multibyte string cannot ++ possibly form a valid multibyte character, no value is stored, ++ the global variable errno is set to the value EILSEQ, and the ++ function returns (size_t) -1. The conversion state is ++ afterwards undefined. <br> @pindex wchar.h mbrtowc was ++ introduced in Amendment 1 to ISO C90 and is declared in wchar.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The mbrlen function (``multibyte restartable length'') computes ++ the number of at most n bytes starting at s, which form the next ++ valid and complete multibyte character. <br> If the next ++ multibyte character corresponds to the NUL wide character, the ++ return value is 0. If the next n bytes form a valid multibyte ++ character, the number of bytes belonging to this multibyte ++ character byte sequence is returned. <br> If the the first ++ n bytes possibly form a valid multibyte character but the ++ character is incomplete, the return value is (size_t) -2. ++ Otherwise the multibyte character sequence is invalid and the ++ return value is (size_t) -1. <br> The multibyte sequence ++ is interpreted in the state represented by the object pointed to ++ by ps. If ps is a null pointer, a state object local to mbrlen ++ is used. <br> @pindex wchar.h mbrlen was introduced in ++ Amendment 1 to ISO C90 and is declared in wchar.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The wcrtomb function (``wide character restartable to ++ multibyte'') converts a single wide character into a multibyte ++ string corresponding to that wide character. <br> If s is ++ a null pointer, the function resets the state stored in the ++ objects pointed to by ps (or the internal mbstate_t object) to ++ the initial state. This can also be achieved by a call like ++ this: <br> @smallexample wcrtombs (temp_buf, L'\0', ps) ++ @end smallexample <br> @noindent since, if s is a null ++ pointer, wcrtomb performs as if it writes into an internal ++ buffer, which is guaranteed to be large enough. <br> If wc ++ is the NUL wide character, wcrtomb emits, if necessary, a shift ++ sequence to get the state ps into the initial state followed by ++ a single NUL byte, which is stored in the string s. <br> ++ Otherwise a byte sequence (possibly including shift sequences) ++ is written into the string s. This only happens if wc is a ++ valid wide character (i.e., it has a multibyte representation in ++ the character set selected by locale of the LC_CTYPE category). ++ If wc is no valid wide character, nothing is stored in the ++ strings s, errno is set to EILSEQ, the conversion state in ps is ++ undefined and the return value is (size_t) -1. <br> If no ++ error occurred the function returns the number of bytes stored ++ in the string s. This includes all bytes representing shift ++ sequences. <br> One word about the interface of the ++ function: there is no parameter specifying the length of the ++ array s. Instead the function assumes that there are at least ++ MB_CUR_MAX bytes available since this is the maximum length of ++ any byte sequence representing a single character. So the ++ caller has to make sure that there is enough space available, ++ otherwise buffer overruns can occur. <br> @pindex wchar.h ++ wcrtomb was introduced in Amendment 1 to ISO C90 and is declared ++ in wchar.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The mbsrtowcs function (``multibyte string restartable to wide ++ character string'') converts an NUL-terminated multibyte ++ character string at *src into an equivalent wide character ++ string, including the NUL wide character at the end. The ++ conversion is started using the state information from the ++ object pointed to by ps or from an internal object of mbsrtowcs ++ if ps is a null pointer. Before returning, the state object is ++ updated to match the state after the last converted character. ++ The state is the initial state if the terminating NUL byte is ++ reached and converted. <br> If dst is not a null pointer, ++ the result is stored in the array pointed to by dst; otherwise, ++ the conversion result is not available since it is stored in an ++ internal buffer. <br> If len wide characters are stored in ++ the array dst before reaching the end of the input string, the ++ conversion stops and len is returned. If dst is a null pointer, ++ len is never checked. <br> Another reason for a premature ++ return from the function call is if the input string contains an ++ invalid multibyte sequence. In this case the global variable ++ errno is set to EILSEQ and the function returns (size_t) -1. ++ <br> @c XXX The ISO C9x draft seems to have a problem ++ here. It says that PS @c is not updated if DST is NULL. This ++ is not said straightforward and @c none of the other functions ++ is described like this. It would make sense @c to define the ++ function this way but I don't think it is meant like this. ++ <br> In all other cases the function returns the number of ++ wide characters converted during this call. If dst is not null, ++ mbsrtowcs stores in the pointer pointed to by src either a null ++ pointer (if the NUL byte in the input string was reached) or the ++ address of the byte following the last converted multibyte ++ character. <br> @pindex wchar.h mbsrtowcs was introduced ++ in Amendment 1 to ISO C90 and is declared in wchar.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The wcsrtombs function (``wide character string restartable to ++ multibyte string'') converts the NUL-terminated wide character ++ string at *src into an equivalent multibyte character string and ++ stores the result in the array pointed to by dst. The NUL wide ++ character is also converted. The conversion starts in the state ++ described in the object pointed to by ps or by a state object ++ locally to wcsrtombs in case ps is a null pointer. If dst is a ++ null pointer, the conversion is performed as usual but the ++ result is not available. If all characters of the input string ++ were successfully converted and if dst is not a null pointer, ++ the pointer pointed to by src gets assigned a null pointer. ++ <br> If one of the wide characters in the input string has ++ no valid multibyte character equivalent, the conversion stops ++ early, sets the global variable errno to EILSEQ, and returns ++ (size_t) -1. <br> Another reason for a premature stop is ++ if dst is not a null pointer and the next converted character ++ would require more than len bytes in total to the array dst. In ++ this case (and if dest is not a null pointer) the pointer ++ pointed to by src is assigned a value pointing to the wide ++ character right after the last one successfully converted. ++ <br> Except in the case of an encoding error the return ++ value of the wcsrtombs function is the number of bytes in all ++ the multibyte character sequences stored in dst. Before ++ returning the state in the object pointed to by ps (or the ++ internal object in case ps is a null pointer) is updated to ++ reflect the state after the last conversion. The state is the ++ initial shift state in case the terminating NUL wide character ++ was converted. <br> @pindex wchar.h The wcsrtombs function ++ was introduced in Amendment 1 to ISO C90 and is declared in ++ wchar.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The mbsnrtowcs function is very similar to the mbsrtowcs ++ function. All the parameters are the same except for nmc, which ++ is new. The return value is the same as for mbsrtowcs. ++ <br> This new parameter specifies how many bytes at most ++ can be used from the multibyte character string. In other ++ words, the multibyte character string *src need not be ++ NUL-terminated. But if a NUL byte is found within the nmc first ++ bytes of the string, the conversion stops here. <br> This ++ function is a GNU extension. It is meant to work around the ++ problems mentioned above. Now it is possible to convert a ++ buffer with multibyte character text piece for piece without ++ having to care about inserting NUL bytes and the effect of NUL ++ bytes on the conversion state. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The wcsnrtombs function implements the conversion from wide ++ character strings to multibyte character strings. It is similar ++ to wcsrtombs but, just like mbsnrtowcs, it takes an extra ++ parameter, which specifies the length of the input string. ++ <br> No more than nwc wide characters from the input ++ string *src are converted. If the input string contains a NUL ++ wide character in the first nwc characters, the conversion stops ++ at this place. <br> The wcsnrtombs function is a GNU ++ extension and just like mbsnrtowcs helps in situations where no ++ NUL-terminated input strings are available. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The mbtowc (``multibyte to wide character'') function when ++ called with non-null string converts the first multibyte ++ character beginning at string to its corresponding wide ++ character code. It stores the result in *result. <br> ++ mbtowc never examines more than size bytes. (The idea is to ++ supply for size the number of bytes of data you have in hand.) ++ <br> mbtowc with non-null string distinguishes three ++ possibilities: the first size bytes at string start with valid ++ multibyte characters, they start with an invalid byte sequence ++ or just part of a character, or string points to an empty string ++ (a null character). <br> For a valid multibyte character, ++ mbtowc converts it to a wide character and stores that in ++ *result, and returns the number of bytes in that character ++ (always at least 1 and never more than size). <br> For an ++ invalid byte sequence, mbtowc returns -1. For an empty string, ++ it returns 0, also storing '\0' in *result. <br> If the ++ multibyte character code uses shift characters, then mbtowc ++ maintains and updates a shift state as it scans. If you call ++ mbtowc with a null pointer for string, that initializes the ++ shift state to its standard initial value. It also returns ++ nonzero if the multibyte character code in use actually has a ++ shift state. . ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The wctomb (``wide character to multibyte'') function converts ++ the wide character code wchar to its corresponding multibyte ++ character sequence, and stores the result in bytes starting at ++ string. At most MB_CUR_MAX characters are stored. <br> ++ wctomb with non-null string distinguishes three possibilities ++ for wchar: a valid wide character code (one that can be ++ translated to a multibyte character), an invalid code, and ++ L'\0'. <br> Given a valid code, wctomb converts it to a ++ multibyte character, storing the bytes starting at string. Then ++ it returns the number of bytes in that character (always at ++ least 1 and never more than MB_CUR_MAX). <br> If wchar is ++ an invalid wide character code, wctomb returns -1. If wchar is ++ L'\0', it returns 0, also storing '\0' in *string. <br> If ++ the multibyte character code uses shift characters, then wctomb ++ maintains and updates a shift state as it scans. If you call ++ wctomb with a null pointer for string, that initializes the ++ shift state to its standard initial value. It also returns ++ nonzero if the multibyte character code in use actually has a ++ shift state. . <br> Calling this function with a wchar ++ argument of zero when string is not null has the side-effect of ++ reinitializing the stored shift state as well as storing the ++ multibyte character '\0' and returning 0. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The mblen function with a non-null string argument returns the ++ number of bytes that make up the multibyte character beginning ++ at string, never examining more than size bytes. (The idea is ++ to supply for size the number of bytes of data you have in ++ hand.) <br> The return value of mblen distinguishes three ++ possibilities: the first size bytes at string start with valid ++ multibyte characters, they start with an invalid byte sequence ++ or just part of a character, or string points to an empty string ++ (a null character). <br> For a valid multibyte character, ++ mblen returns the number of bytes in that character (always at ++ least 1 and never more than size). For an invalid byte ++ sequence, mblen returns -1. For an empty string, it returns 0. ++ <br> If the multibyte character code uses shift ++ characters, then mblen maintains and updates a shift state as it ++ scans. If you call mblen with a null pointer for string, that ++ initializes the shift state to its standard initial value. It ++ also returns a nonzero value if the multibyte character code in ++ use actually has a shift state. . <br> @pindex stdlib.h ++ The function mblen is declared in stdlib.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The mbstowcs (``multibyte string to wide character string'') ++ function converts the null-terminated string of multibyte ++ characters string to an array of wide character codes, storing ++ not more than size wide characters into the array beginning at ++ wstring. The terminating null character counts towards the size, ++ so if size is less than the actual number of wide characters ++ resulting from string, no terminating null character is stored. ++ <br> The conversion of characters from string begins in ++ the initial shift state. <br> If an invalid multibyte ++ character sequence is found, the mbstowcs function returns a ++ value of -1. Otherwise, it returns the number of wide ++ characters stored in the array wstring. This number does not ++ include the terminating null character, which is present if the ++ number is less than size. <br> Here is an example showing ++ how to convert a string of multibyte characters, allocating ++ enough space for the result. <br> @smallexample wchar_t * ++ mbstowcs_alloc (const char *string) size_t size = strlen ++ (string) + 1; wchar_t *buf = xmalloc (size * sizeof ++ (wchar_t)); <br> size = mbstowcs (buf, string, size); ++ if (size == (size_t) -1) return NULL; buf = xrealloc (buf, ++ (size + 1) * sizeof (wchar_t)); return buf; @ @end ++ smallexample <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The wcstombs (``wide character string to multibyte string'') ++ function converts the null-terminated wide character array ++ wstring into a string containing multibyte characters, storing ++ not more than size bytes starting at string, followed by a ++ terminating null character if there is room. The conversion of ++ characters begins in the initial shift state. <br> The ++ terminating null character counts towards the size, so if size ++ is less than or equal to the number of bytes needed in wstring, ++ no terminating null character is stored. <br> If a code ++ that does not correspond to a valid multibyte character is ++ found, the wcstombs function returns a value of -1. Otherwise, ++ the return value is the number of bytes stored in the array ++ string. This number does not include the terminating null ++ character, which is present if the number is less than size. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The iconv_open function has to be used before starting a ++ conversion. The two parameters this function takes determine ++ the source and destination character set for the conversion, and ++ if the implementation has the possibility to perform such a ++ conversion, the function returns a handle. <br> If the ++ wanted conversion is not available, the iconv_open function ++ returns (iconv_t) -1. In this case the global variable errno can ++ have the following values: <br> @table @code @item EMFILE ++ The process already has OPEN_MAX file descriptors open. @item ++ ENFILE The system limit of open file is reached. @item ENOMEM ++ Not enough memory to carry out the operation. @item EINVAL The ++ conversion from fromcode to tocode is not supported. @end table ++ <br> It is not possible to use the same descriptor in ++ different threads to perform independent conversions. The data ++ structures associated with the descriptor include information ++ about the conversion state. This must not be messed up by using ++ it in different conversions. <br> An iconv descriptor is ++ like a file descriptor as for every use a new descriptor must be ++ created. The descriptor does not stand for all of the ++ conversions from fromset to toset. <br> The GNU C library ++ implementation of iconv_open has one significant extension to ++ other implementations. To ease the extension of the set of ++ available conversions, the implementation allows storing the ++ necessary files with data and code in an arbitrary number of ++ directories. How this extension must be written will be ++ explained below (glibc iconv Implementation). Here it is only ++ important to say that all directories mentioned in the ++ GCONV_PATH environment variable are considered only if they ++ contain a file gconv-modules. These directories need not ++ necessarily be created by the system administrator. In fact, ++ this extension is introduced to help users writing and using ++ their own, new conversions. Of course, this does not work for ++ security reasons in SUID binaries; in this case only the system ++ directory is considered and this normally is prefix/lib/gconv. ++ The GCONV_PATH environment variable is examined exactly once at ++ the first call of the iconv_open function. Later modifications ++ of the variable have no effect. <br> @pindex iconv.h The ++ iconv_open function was introduced early in the X/Open ++ Portability Guide, version 2. It is supported by all commercial ++ Unices as it is required for the Unix branding. However, the ++ quality and completeness of the implementation varies widely. ++ The iconv_open function is declared in iconv.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The iconv_close function frees all resources associated with the ++ handle cd, which must have been returned by a successful call to ++ the iconv_open function. <br> If the function call was ++ successful the return value is 0. Otherwise it is -1 and errno ++ is set appropriately. Defined error are: <br> @table @code ++ @item EBADF The conversion descriptor is invalid. @end table ++ <br> @pindex iconv.h The iconv_close function was ++ introduced together with the rest of the iconv functions in XPG2 ++ and is declared in iconv.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ @cindex stateful The iconv function converts the text in the ++ input buffer according to the rules associated with the ++ descriptor cd and stores the result in the output buffer. It is ++ possible to call the function for the same text several times in ++ a row since for stateful character sets the necessary state ++ information is kept in the data structures associated with the ++ descriptor. <br> The input buffer is specified by *inbuf ++ and it contains *inbytesleft bytes. The extra indirection is ++ necessary for communicating the used input back to the caller ++ (see below). It is important to note that the buffer pointer is ++ of type char and the length is measured in bytes even if the ++ input text is encoded in wide characters. <br> The output ++ buffer is specified in a similar way. *outbuf points to the ++ beginning of the buffer with at least *outbytesleft bytes room ++ for the result. The buffer pointer again is of type char and ++ the length is measured in bytes. If outbuf or *outbuf is a null ++ pointer, the conversion is performed but no output is available. ++ <br> If inbuf is a null pointer, the iconv function ++ performs the necessary action to put the state of the conversion ++ into the initial state. This is obviously a no-op for ++ non-stateful encodings, but if the encoding has a state, such a ++ function call might put some byte sequences in the output ++ buffer, which perform the necessary state changes. The next ++ call with inbuf not being a null pointer then simply goes on ++ from the initial state. It is important that the programmer ++ never makes any assumption as to whether the conversion has to ++ deal with states. Even if the input and output character sets ++ are not stateful, the implementation might still have to keep ++ states. This is due to the implementation chosen for the GNU C ++ library as it is described below. Therefore an iconv call to ++ reset the state should always be performed if some protocol ++ requires this for the output text. <br> The conversion ++ stops for one of three reasons. The first is that all characters ++ from the input buffer are converted. This actually can mean two ++ things: either all bytes from the input buffer are consumed or ++ there are some bytes at the end of the buffer that possibly can ++ form a complete character but the input is incomplete. The ++ second reason for a stop is that the output buffer is full. And ++ the third reason is that the input contains invalid characters. ++ <br> In all of these cases the buffer pointers after the ++ last successful conversion, for input and output buffer, are ++ stored in inbuf and outbuf, and the available room in each ++ buffer is stored in inbytesleft and outbytesleft. <br> ++ Since the character sets selected in the iconv_open call can be ++ almost arbitrary, there can be situations where the input buffer ++ contains valid characters, which have no identical ++ representation in the output character set. The behavior in ++ this situation is undefined. The current behavior of the GNU C ++ library in this situation is to return with an error ++ immediately. This certainly is not the most desirable solution; ++ therefore, future versions will provide better ones, but they ++ are not yet finished. <br> If all input from the input ++ buffer is successfully converted and stored in the output ++ buffer, the function returns the number of non-reversible ++ conversions performed. In all other cases the return value is ++ (size_t) -1 and errno is set appropriately. In such cases the ++ value pointed to by inbytesleft is nonzero. <br> @table ++ @code @item EILSEQ The conversion stopped because of an invalid ++ byte sequence in the input. After the call, *inbuf points at the ++ first byte of the invalid byte sequence. <br> @item E2BIG ++ The conversion stopped because it ran out of space in the output ++ buffer. <br> @item EINVAL The conversion stopped because ++ of an incomplete byte sequence at the end of the input buffer. ++ <br> @item EBADF The cd argument is invalid. @end table ++ <br> @pindex iconv.h The iconv function was introduced in ++ the XPG2 standard and is declared in the iconv.h header. ++ ++ ++ ++ ++ ++ ++ This data structure describes one conversion a module can ++ perform. For each function in a loaded module with conversion ++ functions there is exactly one object of this type. This object ++ is shared by all users of the conversion (i.e., this object does ++ not contain any information corresponding to an actual ++ conversion; it only describes the conversion itself). <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ All these elements of the structure are used internally in the C ++ library to coordinate loading and unloading the shared. One ++ must not expect any of the other elements to be available or ++ initialized. <br> ++ ++ ++ ++ ++ ++ ++ __from_name and __to_name contain the names of the source and ++ destination character sets. They can be used to identify the ++ actual conversion to be carried out since one module might ++ implement conversions for more than one character set and/or ++ direction. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ These elements contain pointers to the functions in the loadable ++ module. The interface will be explained below. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ These values have to be supplied in the init function of the ++ module. The __min_needed_from value specifies how many bytes a ++ character of the source character set at least needs. The ++ __max_needed_from specifies the maximum value that also includes ++ possible shift sequences. <br> The __min_needed_to and ++ __max_needed_to values serve the same purpose as ++ __min_needed_from and __max_needed_from but this time for the ++ destination character set. <br> It is crucial that these ++ values be accurate since otherwise the conversion functions will ++ have problems or not work at all. <br> ++ ++ ++ ++ ++ This element must also be initialized by the init function. int ++ __stateful is nonzero if the source character set is stateful. ++ Otherwise it is zero. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ This is the data structure that contains the information ++ specific to each use of the conversion functions. <br> ++ <br> ++ ++ ++ ++ ++ ++ ++ These elements specify the output buffer for the conversion ++ step. The __outbuf element points to the beginning of the ++ buffer, and __outbufend points to the byte following the last ++ byte in the buffer. The conversion function must not assume ++ anything about the size of the buffer but it can be safely ++ assumed the there is room for at least one complete character in ++ the output buffer. <br> Once the conversion is finished, ++ if the conversion is the last step, the __outbuf element must be ++ modified to point after the last byte written into the buffer to ++ signal how much output is available. If this conversion step is ++ not the last one, the element must not be modified. The ++ __outbufend element must not be modified. <br> ++ ++ ++ ++ ++ This element is nonzero if this conversion step is the last one. ++ This information is necessary for the recursion. See the ++ description of the conversion function internals below. This ++ element must never be modified. <br> ++ ++ ++ ++ ++ The conversion function can use this element to see how many ++ calls of the conversion function already happened. Some ++ character sets require a certain prolog when generating output, ++ and by comparing this value with zero, one can find out whether ++ it is the first call and whether, therefore, the prolog should ++ be emitted. This element must never be modified. <br> ++ ++ ++ ++ ++ This element is another one rarely used but needed in certain ++ situations. It is assigned a nonzero value in case the ++ conversion functions are used to implement mbsrtowcs et.al.@: ++ (i.e., the function is not used directly through the iconv ++ interface). <br> This sometimes makes a difference as it ++ is expected that the iconv functions are used to translate ++ entire texts while the mbsrtowcs functions are normally used ++ only to convert single strings and might be used multiple times ++ to convert entire texts. <br> But in this situation we ++ would have problem complying with some rules of the character ++ set specification. Some character sets require a prolog, which ++ must appear exactly once for an entire text. If a number of ++ mbsrtowcs calls are used to convert the text, only the first ++ call must add the prolog. However, because there is no ++ communication between the different calls of mbsrtowcs, the ++ conversion functions have no possibility to find this out. The ++ situation is different for sequences of iconv calls since the ++ handle allows access to the needed information. <br> The ++ int __internal_use element is mostly used together with ++ __invocation_counter as follows: <br> @smallexample if ++ (!data->__internal_use && ++ data->__invocation_counter == 0) /* Emit prolog. */ ++ @end smallexample <br> This element must never be ++ modified. <br> ++ ++ ++ ++ ++ The __statep element points to an object of type mbstate_t ++ (Keeping the state). The conversion of a stateful character set ++ must use the object pointed to by __statep to store information ++ about the conversion state. The __statep element itself must ++ never be modified. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++
++
++ ++ ++ This function is used to inquire about runtime system ++ parameters. The parameter argument should be one of the _SC_ ++ symbols listed below. <br> The normal return value from ++ sysconf is the value you requested. A value of -1 is returned ++ both if the implementation does not impose a limit, and in case ++ of an error. <br> The following errno error conditions are ++ defined for this function: <br> @table @code @item EINVAL ++ The value of the parameter is invalid. @end table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++
++
++
++
++ ++ ++ This function is used to inquire about the limits that apply to ++ the file named filename. <br> The parameter argument ++ should be one of the _PC_ constants listed below. <br> The ++ normal return value from pathconf is the value you requested. A ++ value of -1 is returned both if the implementation does not ++ impose a limit, and in case of an error. In the former case, ++ errno is not set, while in the latter case, errno is set to ++ indicate the cause of the problem. So the only way to use this ++ function robustly is to store 0 into errno just before calling ++ it. <br> Besides the usual file name errors (File Name ++ Errors), the following error condition is defined for this ++ function: <br> @table @code @item EINVAL The value of ++ parameter is invalid, or the implementation doesn't support the ++ parameter for the specific file. @end table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This is just like pathconf except that an open file descriptor ++ is used to specify the file for which information is requested, ++ instead of a file name. <br> The following errno error ++ conditions are defined for this function: <br> @table ++ @code @item EBADF The filedes argument is not a valid file ++ descriptor. <br> @item EINVAL The value of parameter is ++ invalid, or the implementation doesn't support the parameter for ++ the specific file. @end table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++
++ ++ ++ This function reads the value of a string-valued system ++ parameter, storing the string into len bytes of memory space ++ starting at buf. The parameter argument should be one of the ++ _CS_ symbols listed below. <br> The normal return value ++ from confstr is the length of the string value that you asked ++ for. If you supply a null pointer for buf, then confstr does ++ not try to store the string; it just returns its length. A ++ value of 0 indicates an error. <br> If the string you ++ asked for is too long for the buffer (that is, longer than len - ++ 1), then confstr stores just that much (leaving room for the ++ terminating null character). You can tell that this has ++ happened because confstr returns a value greater than or equal ++ to len. <br> The following errno error conditions are ++ defined for this function: <br> @table @code @item EINVAL ++ The value of the parameter is invalid. @end table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> getpass outputs prompt, then reads a string in from ++ the terminal without echoing it. It tries to connect to the ++ real terminal, /dev/tty, if possible, to encourage users not to ++ put plaintext passwords in files; otherwise, it uses stdin and ++ stderr. getpass also disables the INTR, QUIT, and SUSP ++ characters on the terminal using the ISIG terminal attribute ++ (Local Modes). The terminal is flushed before and after getpass, ++ so that characters of a mistyped password are not accidentally ++ visible. <br> In other C libraries, getpass may only ++ return the first PASS_MAX bytes of a password. The GNU C ++ library has no limit, so PASS_MAX is undefined. <br> The ++ prototype for this function is in unistd.h. PASS_MAX would be ++ defined in limits.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> The crypt function takes a password, key, as a ++ string, and a salt 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 key that will produce that output is to guess ++ values of key until the original value of key is found. ++ <br> The salt 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 salt, an intruder can make a guess, run ++ crypt on it once, and compare the result with all the passwords. ++ With a salt, the intruder must run crypt once for each ++ different salt. <br> For the MD5-based algorithm, the salt ++ should consist of the string $1$, followed by up to 8 ++ characters, terminated by either another $ or the end of the ++ string. The result of crypt will be the salt, followed by a $ ++ if the salt didn't end with one, followed by 22 characters from ++ the alphabet ./0-9A-Za-z, up to 34 characters total. Every ++ character in the key is significant. <br> For the ++ DES-based algorithm, the salt should consist of two characters ++ from the alphabet ./0-9A-Za-z, and the result of crypt will be ++ those two characters followed by 11 more from the same alphabet, ++ 13 in total. Only the first 8 characters in the key are ++ significant. <br> The MD5-based algorithm has no limit on ++ the useful length of the password used, and is slightly more ++ secure. It is therefore preferred over the DES-based algorithm. ++ <br> When the user enters their password for the first ++ time, the salt should be set to a new string which is reasonably ++ random. To verify a password against the result of a previous ++ call to crypt, pass the result of the previous call as the salt. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> The crypt_r function does the same thing as crypt, ++ but takes an extra parameter which includes space for its result ++ (among other things), so it can be reentrant. ++ data->initialized must be cleared to zero before the first ++ time crypt_r is called. <br> The crypt_r function is a GNU ++ extension. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> The setkey function sets an internal data structure ++ to be an expanded form of key. key is specified as an array of ++ 64 bits each stored in a char, the first bit is key[0] and the ++ 64th bit is key[63]. The key should have the correct parity. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> The encrypt function encrypts block if edflag is 0, ++ otherwise it decrypts block, using a key previously set by ++ setkey. The result is placed in block. <br> Like setkey, ++ block is specified as an array of 64 bits each stored in a char, ++ but there are no parity bits in block. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> These are reentrant versions of setkey and encrypt. ++ The only difference is the extra parameter, which stores the ++ expanded version of key. Before calling setkey_r the first ++ time, data->initialized must be cleared to zero. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> These are reentrant versions of setkey and encrypt. ++ The only difference is the extra parameter, which stores the ++ expanded version of key. Before calling setkey_r the first ++ time, data->initialized must be cleared to zero. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> The function ecb_crypt encrypts or decrypts one or ++ more blocks using DES. Each block is encrypted independently. ++ <br> The blocks and the key are stored packed in 8-bit ++ bytes, so that the first bit of the key is the most-significant ++ bit of key[0] and the 63rd bit of the key is stored as the ++ least-significant bit of key[7]. The key should have the ++ correct parity. <br> len is the number of bytes in blocks. ++ It should be a multiple of 8 (so that there is a whole number ++ of blocks to encrypt). len is limited to a maximum of ++ DES_MAXDATA bytes. <br> The result of the encryption ++ replaces the input in blocks. <br> The mode parameter is ++ the bitwise OR of two of the following: <br> @vtable @code ++ @item DES_ENCRYPT This constant, used in the mode parameter, ++ specifies that blocks is to be encrypted. <br> @item ++ DES_DECRYPT This constant, used in the mode parameter, specifies ++ that blocks is to be decrypted. <br> @item DES_HW This ++ constant, used in the mode parameter, asks to use a hardware ++ device. If no hardware device is available, encryption happens ++ anyway, but in software. <br> @item DES_SW This constant, ++ used in the mode parameter, specifies that no hardware device is ++ to be used. @end vtable <br> The result of the function ++ will be one of these values: <br> @vtable @code @item ++ DESERR_NONE The encryption succeeded. <br> @item ++ DESERR_NOHWDEVICE The encryption succeeded, but there was no ++ hardware device available. <br> @item DESERR_HWERROR The ++ encryption failed because of a hardware problem. <br> ++ @item DESERR_BADPARAM The encryption failed because of a bad ++ parameter, for instance len is not a multiple of 8 or len is ++ larger than DES_MAXDATA. @end vtable ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This macro returns 1 if err is a `success' result code from ++ ecb_crypt or cbc_crypt, and 0 otherwise. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> The function cbc_crypt encrypts or decrypts one or ++ more blocks using DES in Cipher Block Chaining mode. <br> ++ For encryption in CBC mode, each block is exclusive-ored with ++ ivec before being encrypted, then ivec is replaced with the ++ result of the encryption, then the next block is processed. ++ Decryption is the reverse of this process. <br> This has ++ the advantage that blocks which are the same before being ++ encrypted are very unlikely to be the same after being ++ encrypted, making it much harder to detect patterns in the data. ++ <br> Usually, ivec 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 ivec for decryption. Another possibility ++ is to set ivec to 8 zeroes initially, and have the first the ++ block encrypted consist of 8 random bytes. <br> Otherwise, ++ all the parameters are similar to those for ecb_crypt. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> The function des_setparity changes the 64-bit key, ++ stored packed in 8-bit bytes, to have odd parity by altering the ++ low bits of each byte. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ Returns true if c is a lower-case letter. The letter need not ++ be from the Latin alphabet, any alphabet representable is valid. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ Returns true if c is an upper-case letter. The letter need not ++ be from the Latin alphabet, any alphabet representable is valid. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ Returns true if c is an alphabetic character (a letter). If ++ islower or isupper is true of a character, then isalpha is also ++ true. <br> In some locales, there may be additional ++ characters for which isalpha is true---letters which are neither ++ upper case nor lower case. But in the standard "C" locale, ++ there are no such additional characters. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ Returns true if c is a decimal digit (0 through 9). ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ Returns true if c is an alphanumeric character (a letter or ++ number); in other words, if either isalpha or isdigit is true of ++ a character, then isalnum is also true. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ Returns true if c is a hexadecimal digit. Hexadecimal digits ++ include the normal decimal digits 0 through 9 and the letters A ++ through F and a through f. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ Returns true if c is a punctuation character. This means any ++ printing character that is not alphanumeric or a space ++ character. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ Returns true if c is a whitespace character. In the standard ++ "C" locale, isspace returns true for only the standard ++ whitespace characters: <br> @table @code @item ' ' space ++ <br> @item '\f' formfeed <br> @item '\n' newline ++ <br> @item '\r' carriage return <br> @item '\t' ++ horizontal tab <br> @item '\v' vertical tab @end table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ Returns true if c is a blank character; that is, a space or a ++ tab. This function is a GNU extension. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ Returns true if c is a graphic character; that is, a character ++ that has a glyph associated with it. The whitespace characters ++ are not considered graphic. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ Returns true if c is a printing character. Printing characters ++ include all the graphic characters, plus the space ( ) ++ character. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ Returns true if c is a control character (that is, a character ++ that is not a printing character). ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ Returns true if c is a 7-bit unsigned char value that fits into ++ the US/UK ASCII character set. This function is a BSD extension ++ and is also an SVID extension. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ If c is an upper-case letter, tolower returns the corresponding ++ lower-case letter. If c is not an upper-case letter, c is ++ returned unchanged. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ If c is a lower-case letter, toupper returns the corresponding ++ upper-case letter. Otherwise c is returned unchanged. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function converts c to a 7-bit unsigned char value that ++ fits into the US/UK ASCII character set, by clearing the ++ high-order bits. This function is a BSD extension and is also ++ an SVID extension. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This is identical to tolower, and is provided for compatibility ++ with the SVID. .@refill ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This is identical to toupper, and is provided for compatibility ++ with the SVID. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The wctype returns a value representing a class of wide ++ characters which is identified by the string property. Beside ++ some standard properties each locale can define its own ones. ++ In case no property with the given name is known for the current ++ locale selected for the LC_CTYPE category, the function returns ++ zero. <br> @noindent The properties known in every locale ++ are: <br> @multitable @columnfractions .25 .25 .25 .25 ++ @item "alnum" @tab "alpha" @tab "cntrl" @tab "digit" @item ++ "graph" @tab "lower" @tab "print" @tab "punct" @item "space" ++ @tab "upper" @tab "xdigit" @end multitable <br> @pindex ++ wctype.h This function is declared in wctype.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function returns a nonzero value if wc is in the character ++ class specified by desc. desc must previously be returned by a ++ successful call to wctype. <br> @pindex wctype.h This ++ function is declared in wctype.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function returns a nonzero value if wc is an alphanumeric ++ character (a letter or number); in other words, if either ++ iswalpha or iswdigit is true of a character, then iswalnum is ++ also true. <br> @noindent This function can be implemented ++ using <br> @smallexample iswctype (wc, wctype ("alnum")) ++ @end smallexample <br> @pindex wctype.h It is declared in ++ wctype.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ Returns true if wc is an alphabetic character (a letter). If ++ iswlower or iswupper is true of a character, then iswalpha is ++ also true. <br> In some locales, there may be additional ++ characters for which iswalpha is true---letters which are ++ neither upper case nor lower case. But in the standard "C" ++ locale, there are no such additional characters. <br> ++ @noindent This function can be implemented using <br> ++ @smallexample iswctype (wc, wctype ("alpha")) @end smallexample ++ <br> @pindex wctype.h It is declared in wctype.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ Returns true if wc is a control character (that is, a character ++ that is not a printing character). <br> @noindent This ++ function can be implemented using <br> @smallexample ++ iswctype (wc, wctype ("cntrl")) @end smallexample <br> ++ @pindex wctype.h It is declared in wctype.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ Returns true if wc is a digit (e.g., 0 through 9). Please note ++ that this function does not only return a nonzero value for ++ decimal digits, but for all kinds of digits. A consequence is ++ that code like the following will not work unconditionally for ++ wide characters: <br> @smallexample n = 0; while (iswdigit ++ (*wc)) n *= 10; n += *wc++ - L'0'; @ @end ++ smallexample <br> @noindent This function can be ++ implemented using <br> @smallexample iswctype (wc, wctype ++ ("digit")) @end smallexample <br> @pindex wctype.h It is ++ declared in wctype.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ Returns true if wc is a graphic character; that is, a character ++ that has a glyph associated with it. The whitespace characters ++ are not considered graphic. <br> @noindent This function ++ can be implemented using <br> @smallexample iswctype (wc, ++ wctype ("graph")) @end smallexample <br> @pindex wctype.h ++ It is declared in wctype.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ Returns true if wc is a lower-case letter. The letter need not ++ be from the Latin alphabet, any alphabet representable is valid. ++ <br> @noindent This function can be implemented using ++ <br> @smallexample iswctype (wc, wctype ("lower")) @end ++ smallexample <br> @pindex wctype.h It is declared in ++ wctype.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ Returns true if wc is a printing character. Printing characters ++ include all the graphic characters, plus the space ( ) ++ character. <br> @noindent This function can be implemented ++ using <br> @smallexample iswctype (wc, wctype ("print")) ++ @end smallexample <br> @pindex wctype.h It is declared in ++ wctype.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ Returns true if wc is a punctuation character. This means any ++ printing character that is not alphanumeric or a space ++ character. <br> @noindent This function can be implemented ++ using <br> @smallexample iswctype (wc, wctype ("punct")) ++ @end smallexample <br> @pindex wctype.h It is declared in ++ wctype.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ Returns true if wc is a whitespace character. In the standard ++ "C" locale, iswspace returns true for only the standard ++ whitespace characters: <br> @table @code @item L' ' space ++ <br> @item L'\f' formfeed <br> @item L'\n' newline ++ <br> @item L'\r' carriage return <br> @item L'\t' ++ horizontal tab <br> @item L'\v' vertical tab @end table ++ <br> @noindent This function can be implemented using ++ <br> @smallexample iswctype (wc, wctype ("space")) @end ++ smallexample <br> @pindex wctype.h It is declared in ++ wctype.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ Returns true if wc is an upper-case letter. The letter need not ++ be from the Latin alphabet, any alphabet representable is valid. ++ <br> @noindent This function can be implemented using ++ <br> @smallexample iswctype (wc, wctype ("upper")) @end ++ smallexample <br> @pindex wctype.h It is declared in ++ wctype.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ Returns true if wc is a hexadecimal digit. Hexadecimal digits ++ include the normal decimal digits 0 through 9 and the letters A ++ through F and a through f. <br> @noindent This function ++ can be implemented using <br> @smallexample iswctype (wc, ++ wctype ("xdigit")) @end smallexample <br> @pindex wctype.h ++ It is declared in wctype.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ Returns true if wc is a blank character; that is, a space or a ++ tab. This function is a GNU extension. It is declared in ++ wchar.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The wctrans function has to be used to find out whether a named ++ mapping is defined in the current locale selected for the ++ LC_CTYPE category. If the returned value is non-zero, you can ++ use it afterwards in calls to towctrans. If the return value is ++ zero no such mapping is known in the current locale. <br> ++ Beside locale-specific mappings there are two mappings which are ++ guaranteed to be available in every locale: <br> ++ @multitable @columnfractions .5 .5 @item "tolower" @tab ++ "toupper" @end multitable <br> @pindex wctype.h @noindent ++ These functions are declared in wctype.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ towctrans maps the input character wc according to the rules of ++ the mapping for which desc is a descriptor, and returns the ++ value it finds. desc must be obtained by a successful call to ++ wctrans. <br> @pindex wctype.h @noindent This function is ++ declared in wctype.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ If wc is an upper-case letter, towlower returns the ++ corresponding lower-case letter. If wc is not an upper-case ++ letter, wc is returned unchanged. <br> @noindent towlower ++ can be implemented using <br> @smallexample towctrans (wc, ++ wctrans ("tolower")) @end smallexample <br> @pindex ++ wctype.h @noindent This function is declared in wctype.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ If wc is a lower-case letter, towupper returns the corresponding ++ upper-case letter. Otherwise wc is returned unchanged. ++ <br> @noindent towupper can be implemented using ++ <br> @smallexample towctrans (wc, wctrans ("toupper")) ++ @end smallexample <br> @pindex wctype.h @noindent This ++ function is declared in wctype.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The backtrace function obtains a backtrace for the current ++ thread, as a list of pointers, and places the information into ++ buffer. The argument size should be the number of void * ++ elements that will fit into buffer. The return value is the ++ actual number of entries of buffer that are obtained, and is at ++ most size. <br> The pointers placed in buffer are actually ++ return addresses obtained by inspecting the stack, one return ++ address per stack frame. <br> Note that certain compiler ++ optimizations may interfere with obtaining a valid backtrace. ++ Function inlining causes the inlined function to not have a ++ stack frame; tail call optimization replaces one stack frame ++ with another; frame pointer elimination will stop backtrace from ++ interpreting the stack contents correctly. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The backtrace_symbols function translates the information ++ obtained from the backtrace function into an array of strings. ++ The argument buffer should be a pointer to an array of addresses ++ obtained via the backtrace function, and size is the number of ++ entries in that array (the return value of backtrace). ++ <br> The return value is a pointer to an array of strings, ++ which has size entries just like the array buffer. Each string ++ contains a printable representation of the corresponding element ++ of buffer. It includes the function name (if this can be ++ determined), an offset into the function, and the actual return ++ address (in hexadecimal). <br> Currently, the function ++ name and offset only be obtained on systems that use the ELF ++ binary format for programs and libraries. On other systems, ++ only the hexadecimal return address will be present. Also, you ++ may need to pass additional flags to the linker to make the ++ function names available to the program. (For example, on ++ systems using GNU ld, you must pass (-rdynamic.) <br> The ++ return value of backtrace_symbols is a pointer obtained via the ++ malloc function, and it is the responsibility of the caller to ++ free that pointer. Note that only the return value need be ++ freed, not the individual strings. <br> The return value ++ is NULL if sufficient memory for the strings cannot be obtained. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The backtrace_symbols_fd function performs the same translation ++ as the function backtrace_symbols function. Instead of ++ returning the strings to the caller, it writes the strings to ++ the file descriptor fd, one per line. It does not use the ++ malloc function, and can therefore be used in situations where ++ that function might fail. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++
++ ++ ++ The strerror function maps the error code (Checking for Errors) ++ specified by the errnum argument to a descriptive error message ++ string. The return value is a pointer to this string. ++ <br> The value errnum normally comes from the variable ++ errno. <br> You should not modify the string returned by ++ strerror. Also, if you make subsequent calls to strerror, the ++ string might be overwritten. (But it's guaranteed that no ++ library function ever calls strerror behind your back.) ++ <br> The function strerror is declared in string.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The strerror_r function works like strerror 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 buf ++ with the length of n bytes. <br> At most n characters are ++ written (including the NUL byte) so it is up to the user to ++ select the buffer large enough. <br> This function should ++ always be used in multi-threaded programs since there is no way ++ to guarantee the string returned by strerror really belongs to ++ the last call of the current thread. <br> This function ++ strerror_r is a GNU extension and it is declared in string.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function prints an error message to the stream stderr; see ++ Standard Streams. The orientation of stderr is not changed. ++ <br> If you call perror with a message that is either a ++ null pointer or an empty string, perror just prints the error ++ message corresponding to errno, adding a trailing newline. ++ <br> If you supply a non-null message argument, then ++ perror prefixes its output with this string. It adds a colon ++ and a space character to separate the message from the error ++ string corresponding to errno. <br> The function perror is ++ declared in stdio.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++
++ ++ ++ The error function can be used to report general problems during ++ program execution. The format argument is a format string just ++ like those given to the printf family of functions. The ++ arguments required for the format can follow the format ++ parameter. Just like perror, error also can report an error code ++ in textual form. But unlike perror the error value is ++ explicitly passed to the function in the errnum parameter. This ++ elimintates the problem mentioned above that the error reporting ++ function must be called immediately after the function causing ++ the error since otherwise errno might have a different value. ++ <br> The error prints first the program name. If the ++ application defined a global variable error_print_progname and ++ points it to a function this function will be called to print ++ the program name. Otherwise the string from the global variable ++ program_name 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 errnum 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 errnum. In any ++ case is the output terminated with a newline. <br> The ++ output is directed to the stderr stream. If the stderr wasn't ++ oriented before the call it will be narrow-oriented afterwards. ++ <br> The function will return unless the status parameter ++ has a non-zero value. In this case the function will call exit ++ with the status value for its parameter and therefore never ++ return. If error returns the global variable ++ error_message_count is incremented by one to keep track of the ++ number of errors reported. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> The error_at_line function is very similar to the ++ error function. The only difference are the additional ++ parameters fname and lineno. The handling of the other ++ parameters is identical to that of error except that between the ++ program name and the string generated by the format string ++ additional text is inserted. <br> Directly following the ++ program name a colon, followed by the file name pointer to by ++ fname, another colon, and a value of lineno is printed. ++ <br> This additional output of course is meant to be used ++ to locate an error in an input file (like a programming language ++ source code file etc). <br> If the global variable ++ error_one_per_line is set to a non-zero value error_at_line will ++ avoid printing consecutive messages for the same file anem line. ++ Repetition which are not directly following each other are not ++ caught. <br> Just like error this function only returned ++ if status is zero. Otherwise exit is called with the non-zero ++ value. If error returns the global variable error_message_count ++ is incremented by one to keep track of the number of errors ++ reported. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++
++ ++ ++ The warn function is roughly equivalent to a call like ++ @smallexample error (0, errno, format, the parameters) @end ++ smallexample @noindent except that the global variables error ++ respects and modifies are not used. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The vwarn function is just like warn except that the parameters ++ for the handling of the format string format are passed in as an ++ value of type va_list. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The warnx function is roughly equivalent to a call like ++ @smallexample error (0, 0, format, the parameters) @end ++ smallexample @noindent except that the global variables error ++ respects and modifies are not used. The difference to warn is ++ that no error number string is printed. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The vwarnx function is just like warnx except that the ++ parameters for the handling of the format string format are ++ passed in as an value of type va_list. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The err function is roughly equivalent to a call like ++ @smallexample error (status, errno, format, the parameters) ++ @end smallexample @noindent except that the global variables ++ error respects and modifies are not used and that the program is ++ exited even if status is zero. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The verr function is just like err except that the parameters ++ for the handling of the format string format are passed in as an ++ value of type va_list. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The errx function is roughly equivalent to a call like ++ @smallexample error (status, 0, format, the parameters) @end ++ smallexample @noindent except that the global variables error ++ respects and modifies are not used and that the program is ++ exited even if status is zero. The difference to err is that no ++ error number string is printed. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The verrx function is just like errx except that the parameters ++ for the handling of the format string format are passed in as an ++ value of type va_list. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The getcwd function returns an absolute file name representing ++ the current working directory, storing it in the character array ++ buffer that you provide. The size argument is how you tell the ++ system the allocation size of buffer. <br> The GNU library ++ version of this function also permits you to specify a null ++ pointer for the buffer argument. Then getcwd allocates a buffer ++ automatically, as with malloc (Unconstrained Allocation). If ++ the size is greater than zero, then the buffer is that large; ++ otherwise, the buffer is as large as necessary to hold the ++ result. <br> The return value is buffer on success and a ++ null pointer on failure. The following errno error conditions ++ are defined for this function: <br> @table @code @item ++ EINVAL The size argument is zero and buffer is not a null ++ pointer. <br> @item ERANGE The size argument is less than ++ the length of the working directory name. You need to allocate ++ a bigger array and try again. <br> @item EACCES Permission ++ to read or search a component of the file name was denied. @end ++ table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ @vindex PWD This get_current_dir_name function is bascially ++ equivalent to getcwd (NULL, 0). The only difference is that the ++ value of the PWD variable is returned if this value is correct. ++ This is a subtle difference which is visible if the path ++ described by the PWD value is using one or more symbol links in ++ which case the value returned by getcwd can resolve the symbol ++ links and therefore yield a different result. <br> This ++ function is a GNU extension. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is used to set the process's working directory to ++ filename. <br> The normal, successful return value from ++ chdir is 0. A value of -1 is returned to indicate an error. ++ The errno error conditions defined for this function are the ++ usual file name syntax errors (File Name Errors), plus ENOTDIR ++ if the file filename is not a directory. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is used to set the process's working directory to ++ directory associated with the file descriptor filedes. ++ <br> The normal, successful return value from fchdir is 0. ++ A value of -1 is returned to indicate an error. The following ++ errno error conditions are defined for this function: <br> ++ @table @code @item EACCES Read permission is denied for the ++ directory named by dirname. <br> @item EBADF The filedes ++ argument is not a valid file descriptor. <br> @item ++ ENOTDIR The file descriptor filedes is not associated with a ++ directory. <br> @item EINTR The function call was ++ interrupt by a signal. <br> @item EIO An I/O error ++ occurred. @end table ++ ++ ++ ++ ++ ++ ++ This is a structure type used to return information about ++ directory entries. It contains the following fields: <br> ++ ++ ++ ++ ++ This is the null-terminated file name component. This is the ++ only field you can count on in all POSIX systems. <br> ++ ++ ++ ++ ++ This is the file serial number. For BSD compatibility, you can ++ also refer to this member as d_ino. In the GNU system and most ++ POSIX systems, for most files this the same as the st_ino member ++ that stat will return for the file. . <br> ++ ++ ++ ++ ++ This is the length of the file name, not including the ++ terminating null character. Its type is unsigned char because ++ that is the integer type of the appropriate size <br> ++ ++ ++ ++ ++ This is the type of the file, possibly unknown. The following ++ constants are defined for its value: <br> @vtable @code ++ ++ ++ ++ ++ The type is unknown. On some systems this is the only value ++ returned. <br> ++ ++ ++ ++ ++ A regular file. <br> ++ ++ ++ ++ ++ A directory. <br> ++ ++ ++ ++ ++ A named pipe, or FIFO. . <br> ++ ++ ++ ++ ++ A local-domain socket. @c !!! . <br> ++ ++ ++ ++ ++ A character device. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The opendir function opens and returns a directory stream for ++ reading the directory whose file name is dirname. The stream ++ has type DIR *. <br> If unsuccessful, opendir returns a ++ null pointer. In addition to the usual file name errors (File ++ Name Errors), the following errno error conditions are defined ++ for this function: <br> @table @code @item EACCES Read ++ permission is denied for the directory named by dirname. ++ <br> @item EMFILE The process has too many files open. ++ <br> @item 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.) @end table <br> The DIR type is ++ typically implemented using a file descriptor, and the opendir ++ function in terms of the open function. . Directory streams and ++ the underlying file descriptors are closed on exec (Executing a ++ File). ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The function dirfd returns the file descriptor associated with ++ the directory stream dirstream. This descriptor can be used ++ until the directory is closed with closedir. If the directory ++ stream implementation is not using file descriptors the return ++ value is -1. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function reads the next entry from the directory. It ++ normally returns a pointer to a structure containing information ++ about the file. This structure is statically allocated and can ++ be rewritten by a subsequent call. <br> Portability Note: ++ On some systems readdir may not return entries for . and .., ++ even though these are always valid file names in any directory. ++ . <br> If there are no more entries in the directory or an ++ error is detected, readdir returns a null pointer. The ++ following errno error conditions are defined for this function: ++ <br> @table @code @item EBADF The dirstream argument is ++ not valid. @end table <br> readdir is not thread safe. ++ Multiple threads using readdir on the same dirstream may ++ overwrite the return value. Use readdir_r when this is ++ critical. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is the reentrant version of readdir. Like readdir ++ 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 ++ entry points to a place to store the result. <br> Normally ++ readdir_r returns zero and sets *result to entry. If there are ++ no more entries in the directory or an error is detected, ++ readdir_r sets *result to a null pointer and returns a nonzero ++ error code, also stored in errno, as described for readdir. ++ <br> Portability Note: On some systems readdir_r may not ++ return a NUL terminated string for the file name, even when ++ there is no d_reclen field in struct dirent and the file name is ++ the maximum allowed size. Modern systems all have the d_reclen ++ field, and on old systems multi-threading is not critical. In ++ any case there is no such problem with the readdir function, so ++ that even on systems without the d_reclen member one could use ++ multiple threads by using external locking. <br> It is ++ also important to look at the definition of the struct dirent ++ type. Simply passing a pointer to an object of this type for ++ the second parameter of readdir_r might not be enough. Some ++ systems don't define the d_name element sufficiently long. In ++ this case the user has to provide additional space. There must ++ be room for at least NAME_MAX + 1 characters in the d_name ++ array. Code to call readdir_r could look like this: <br> ++ @smallexample union struct dirent d; char ++ b[offsetof (struct dirent, d_name) + NAME_MAX + 1]; @ u; ++ <br> if (readdir_r (dir, &u.d, &res) == 0) ++ @end smallexample ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The readdir64 function is just like the readdir function except ++ that it returns a pointer to a record of type struct dirent64. ++ Some of the members of this data type (notably d_ino) might have ++ a different size to allow large filesystems. <br> In all ++ other aspects this function is equivalent to readdir. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The readdir64_r function is equivalent to the readdir_r function ++ except that it takes parameters of base type struct dirent64 ++ instead of struct dirent in the second and third position. The ++ same precautions mentioned in the documentation of readdir_r ++ also apply here. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function closes the directory stream dirstream. It returns ++ 0 on success and -1 on failure. <br> The following errno ++ error conditions are defined for this function: <br> ++ @table @code @item EBADF The dirstream argument is not valid. ++ @end table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The rewinddir function is used to reinitialize the directory ++ stream dirstream, so that if you call readdir 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 opendir. (Entries for these ++ files might or might not be returned by readdir if they were ++ added or removed since you last called opendir or rewinddir.) ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The telldir function returns the file position of the directory ++ stream dirstream. You can use this value with seekdir to ++ restore the directory stream to that position. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The seekdir function sets the file position of the directory ++ stream dirstream to pos. The value pos must be the result of a ++ previous call to telldir on this particular stream; closing and ++ reopening the directory can invalidate values returned by ++ telldir. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> The scandir function scans the contents of the ++ directory selected by dir. The result in *namelist is an array ++ of pointers to structure of type struct dirent which describe ++ all selected directory entries and which is allocated using ++ malloc. Instead of always getting all directory entries ++ returned, the user supplied function selector can be used to ++ decide which entries are in the result. Only the entries for ++ which selector returns a non-zero value are selected. <br> ++ Finally the entries in *namelist are sorted using the ++ user-supplied function cmp. The arguments passed to the cmp ++ function are of type struct dirent **, therefore one cannot ++ directly use the strcmp or strcoll functions; instead see the ++ functions alphasort and versionsort below. <br> The return ++ value of the function is the number of entries placed in ++ *namelist. If it is -1 an error occurred (either the directory ++ could not be opened for reading or the malloc call failed) and ++ the global variable errno contains more information on the ++ error. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The alphasort function behaves like the strcoll function ++ (String/Array Comparison). The difference is that the arguments ++ are not string pointers but instead they are of type struct ++ dirent **. <br> The return value of alphasort is less ++ than, equal to, or greater than zero depending on the order of ++ the two entries a and b. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The versionsort function is like alphasort except that it uses ++ the strverscmp function internally. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The scandir64 function works like the scandir function except ++ that the directory entries it returns are described by elements ++ of type struct dirent64. The function pointed to by selector is ++ again used to select the desired entries, except that selector ++ now must point to a function which takes a struct dirent64 * ++ parameter. <br> Similarly the cmp function should expect ++ its two arguments to be of type struct dirent64 **. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The alphasort64 function behaves like the strcoll function ++ (String/Array Comparison). The difference is that the arguments ++ are not string pointers but instead they are of type struct ++ dirent64 **. <br> Return value of alphasort64 is less ++ than, equal to, or greater than zero depending on the order of ++ the two entries a and b. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The versionsort64 function is like alphasort64, excepted that it ++ uses the strverscmp function internally. ++ ++ ++ ++ ++ ++ ++ <br> @smallexample int (*) (const char *, const struct ++ stat *, int) @end smallexample <br> The type of callback ++ functions given to the ftw function. The first parameter points ++ to the file name, the second parameter to an object of type ++ struct stat which is filled in for the file named in the first ++ parameter. <br> @noindent The last parameter is a flag ++ giving more information about the current file. It can have the ++ following values: <br> @vtable @code ++ ++ ++ ++ ++ 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. ++ ++ ++ ++ ++ The item is a directory. ++ ++ ++ ++ ++ The stat call failed and so the information pointed to by the ++ second paramater is invalid. ++ ++ ++ ++ ++ The item is a directory which cannot be read. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ <br> @smallexample int (*) (const char *, const struct ++ stat *, int, struct FTW *) @end smallexample <br> @vindex ++ FTW_DP @vindex FTW_SLN The first three arguments are the same as ++ for the __ftw_func_t type. However for the third argument some ++ additional values are defined to allow finer differentiation: ++ ++ ++ ++ ++ The current item is a directory and all subdirectories have ++ already been visited and reported. This flag is returned ++ instead of FTW_D if the FTW_DEPTH flag is passed to nftw (see ++ below). ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ 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. ++ <br> ++ ++ ++ ++ ++ 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 FTW_CHDIR flag was ++ set in calling nftw since then the current directory is the one ++ the current item is found in. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The ftw function calls the callback function given in the ++ parameter func for every item which is found in the directory ++ specified by filename and all directories below. The function ++ follows symbolic links if necessary but does not process an item ++ twice. If filename is not a directory then it itself is the only ++ object returned to the callback function. <br> The file ++ name passed to the callback function is constructed by taking ++ the filename 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. ftw also ++ calls stat for the file and passes that information on to the ++ callback function. If this stat call was not successful the ++ failure is indicated by setting the third argument of the ++ callback function to FTW_NS. Otherwise it is set according to ++ the description given in the account of __ftw_func_t above. ++ <br> The callback function is expected to return 0 to ++ indicate that no error occurred and that processing should ++ continue. If an error occurred in the callback function or it ++ wants ftw 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 setjmp or similar ++ techniques to continue from another place. This would leave ++ resources allocated by the ftw function unfreed. <br> The ++ descriptors parameter to ftw specifies how many file descriptors ++ it is allowed to consume. The function runs faster the more ++ descriptors it can use. For each level in the directory ++ hierarchy at most one descriptor is used, but for very deep ones ++ any limit on open file descriptors for the process or the system ++ may be exceeded. Moreover, file descriptor limits in a ++ multi-threaded program apply to all the threads as a group, and ++ therefore it is a good idea to supply a reasonable limit to the ++ number of open descriptors. <br> The return value of the ++ ftw function is 0 if all callback function calls returned 0 and ++ all actions performed by the ftw succeeded. If a function call ++ failed (other than calling stat 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 ftw. <br> When ++ the sources are compiled with _FILE_OFFSET_BITS == 64 on a ++ 32-bit system this function is in fact ftw64, i.e. the LFS ++ interface transparently replaces the old interface. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to ftw but it can work on filesystems ++ with large files. File information is reported using a variable ++ of type struct stat64 which is passed by reference to the ++ callback function. <br> When the sources are compiled with ++ _FILE_OFFSET_BITS == 64 on a 32-bit system this function is ++ available under the name ftw and transparently replaces the old ++ implementation. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The nftw function works like the ftw functions. They call the ++ callback function func for all items found in the directory ++ filename and below. At most descriptors file descriptors are ++ consumed during the nftw call. <br> One difference is that ++ the callback function is of a different type. It is of type ++ struct FTW * and provides the callback function with the extra ++ information described above. <br> A second difference is ++ that nftw takes a fourth argument, which is 0 or a bitwise-OR ++ combination of any of the following values. <br> @vtable ++ @code @item FTW_PHYS While traversing the directory symbolic ++ links are not followed. Instead symbolic links are reported ++ using the FTW_SL value for the type parameter to the callback ++ function. If the file referenced by a symbolic link does not ++ exist FTW_SLN is returned instead. @item FTW_MOUNT The callback ++ function is only called for items which are on the same mounted ++ filesystem as the directory given by the filename parameter to ++ nftw. @item FTW_CHDIR 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 ntfw finally ++ returns the current directory is restored to its original value. ++ @item FTW_DEPTH 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 ++ FTW_DP and not FTW_D. @end vtable <br> The return value is ++ computed in the same way as for ftw. nftw 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 errno is set accordingly. If the return value ++ of a callback invocation was non-zero then that value is ++ returned. <br> When the sources are compiled with ++ _FILE_OFFSET_BITS == 64 on a 32-bit system this function is in ++ fact nftw64, i.e. the LFS interface transparently replaces the ++ old interface. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to nftw but it can work on filesystems ++ with large files. File information is reported using a variable ++ of type struct stat64 which is passed by reference to the ++ callback function. <br> When the sources are compiled with ++ _FILE_OFFSET_BITS == 64 on a 32-bit system this function is ++ available under the name nftw and transparently replaces the old ++ implementation. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The link function makes a new link to the existing file named by ++ oldname, under the new name newname. <br> This function ++ returns a value of 0 if it is successful and -1 on failure. In ++ addition to the usual file name errors (File Name Errors) for ++ both oldname and newname, the following errno error conditions ++ are defined for this function: <br> @table @code @item ++ EACCES You are not allowed to write to the directory in which ++ the new link is to be written. @ignore Some implementations also ++ require that the existing file be accessible by the caller, and ++ use this error to report failure for that reason. @end ignore ++ <br> @item EEXIST There is already a file named newname. ++ If you want to replace this link with a new link, you must ++ remove the old link explicitly first. <br> @item EMLINK ++ There are already too many links to the file named by oldname. ++ (The maximum number of links to a file is LINK_MAX; see Limits ++ for Files.) <br> @item ENOENT The file named by oldname ++ doesn't exist. You can't make a link to a file that doesn't ++ exist. <br> @item ENOSPC The directory or file system that ++ would contain the new link is full and cannot be extended. ++ <br> @item EPERM In the GNU system and some others, you ++ cannot make links to directories. Many systems allow only ++ privileged users to do so. This error is used to report the ++ problem. <br> @item EROFS The directory containing the new ++ link can't be modified because it's on a read-only file system. ++ <br> @item EXDEV The directory specified in newname is on ++ a different file system than the existing file. <br> @item ++ EIO A hardware error occurred while trying to read or write the ++ to filesystem. @end table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++
++ ++ ++ The symlink function makes a symbolic link to oldname named ++ newname. <br> The normal return value from symlink is 0. ++ A return value of -1 indicates an error. In addition to the ++ usual file name syntax errors (File Name Errors), the following ++ errno error conditions are defined for this function: <br> ++ @table @code @item EEXIST There is already an existing file ++ named newname. <br> @item EROFS The file newname would ++ exist on a read-only file system. <br> @item ENOSPC The ++ directory or file system cannot be extended to make the new ++ link. <br> @item EIO A hardware error occurred while ++ reading or writing data on the disk. <br> @ignore @item ++ ELOOP There are too many levels of indirection. This can be the ++ result of circular symbolic links to directories. <br> ++ @item EDQUOT The new link can't be created because the user's ++ disk quota has been exceeded. @end ignore @end table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The readlink function gets the value of the symbolic link ++ filename. The file name that the link points to is copied into ++ buffer. This file name string is not null-terminated; readlink ++ normally returns the number of characters copied. The size ++ argument specifies the maximum number of characters to copy, ++ usually the allocation size of buffer. <br> If the return ++ value equals size, you cannot tell whether or not there was room ++ to return the entire name. So make a bigger buffer and call ++ readlink again. Here is an example: <br> @smallexample ++ char * readlink_malloc (const char *filename) int size = 100; ++ char *buffer = NULL; <br> while (1) buffer ++ = (char *) xrealloc (buffer, size); int nchars = readlink ++ (filename, buffer, size); if (nchars < 0) ++ free (buffer); return NULL; @ if ++ (nchars < size) return buffer; size *= 2; @ ++ @ @end smallexample <br> @c @group Invalid outside ++ example. A value of -1 is returned in case of error. In ++ addition to the usual file name errors (File Name Errors), the ++ following errno error conditions are defined for this function: ++ <br> @table @code @item EINVAL The named file is not a ++ symbolic link. <br> @item EIO A hardware error occurred ++ while reading or writing data on the disk. @end table @c @end ++ group ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> The canonicalize_file_name function returns the ++ absolute name of the file named by name which contains no ., .. ++ components nor any repeated path separators (/) or symlinks. ++ The result is passed back as the return value of the function in ++ a block of memory allocated with malloc. If the result is not ++ used anymore the memory should be freed with a call to free. ++ <br> In any of the path components except the last one is ++ missing the function returns a NULL pointer. This is also what ++ is returned if the length of the path reaches or exceeds ++ PATH_MAX characters. In any case errno is set accordingly. ++ <br> @table @code @item ENAMETOOLONG The resulting path is ++ too long. This error only occurs on systems which have a limit ++ on the file name length. <br> @item EACCES At least one of ++ the path components is not readable. <br> @item ENOENT The ++ input file name is empty. <br> @item ENOENT At least one ++ of the path components does not exist. <br> @item ELOOP ++ More than MAXSYMLINKS many symlinks have been followed. @end ++ table <br> This function is a GNU extension and is ++ declared in stdlib.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> A call to realpath where the resolved parameter is ++ NULL behaves exactly like canonicalize_file_name. The function ++ allocates a buffer for the file name and returns a pointer to ++ it. If resolved is not NULL 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 PATH_MAX 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 realpath with anything but NULL for the second ++ parameter. <br> One other difference is that the buffer ++ resolved (if nonzero) will contain the part of the path ++ component which does not exist or is not readable if the ++ function returns NULL and errno is set to EACCES or ENOENT. ++ <br> This function is declared in stdlib.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The unlink function deletes the file name filename. If this is ++ a file's sole name, the file itself is also deleted. (Actually, ++ if any process has the file open when this happens, deletion is ++ postponed until all processes have closed the file.) <br> ++ @pindex unistd.h The function unlink is declared in the header ++ file unistd.h. <br> This function returns 0 on successful ++ completion, and -1 on error. In addition to the usual file name ++ errors (File Name Errors), the following errno error conditions ++ are defined for this function: <br> @table @code @item ++ EACCES Write permission is denied for the directory from which ++ the file is to be removed, or the directory has the sticky bit ++ set and you do not own the file. <br> @item EBUSY This ++ error indicates that the file is being used by the system in ++ such a way that it can't be unlinked. For example, you might ++ see this error if the file name specifies the root directory or ++ a mount point for a file system. <br> @item ENOENT The ++ file name to be deleted doesn't exist. <br> @item EPERM On ++ some systems unlink 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 rmdir to delete directories. ++ (In the GNU system unlink can never delete the name of a ++ directory.) <br> @item EROFS The directory containing the ++ file name to be deleted is on a read-only file system and can't ++ be modified. @end table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ @cindex directories, deleting @cindex deleting a directory The ++ rmdir function deletes a directory. The directory must be empty ++ before it can be removed; in other words, it can only contain ++ entries for . and ... <br> In most other respects, rmdir ++ behaves like unlink. There are two additional errno error ++ conditions defined for rmdir: <br> @table @code @item ++ ENOTEMPTY @itemx EEXIST The directory to be deleted is not ++ empty. @end table <br> These two error codes are ++ synonymous; some systems use one, and some use the other. The ++ GNU system always uses ENOTEMPTY. <br> The prototype for ++ this function is declared in the header file unistd.h. @pindex ++ unistd.h ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This is the ISO C function to remove a file. It works like ++ unlink for files and like rmdir for directories. remove is ++ declared in stdio.h. @pindex stdio.h ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The rename function renames the file oldname to newname. The ++ file formerly accessible under the name oldname is afterwards ++ accessible as newname instead. (If the file had any other names ++ aside from oldname, it continues to have those names.) ++ <br> The directory containing the name newname must be on ++ the same file system as the directory containing the name ++ oldname. <br> One special case for rename is when oldname ++ and newname are two names for the same file. The consistent way ++ to handle this case is to delete oldname. However, in this case ++ POSIX requires that rename do nothing and report success---which ++ is inconsistent. We don't know what your operating system will ++ do. <br> If oldname is not a directory, then any existing ++ file named newname is removed during the renaming operation. ++ However, if newname is the name of a directory, rename fails in ++ this case. <br> If oldname is a directory, then either ++ newname must not exist or it must name a directory that is ++ empty. In the latter case, the existing directory named newname ++ is deleted first. The name newname must not specify a ++ subdirectory of the directory oldname which is being renamed. ++ <br> One useful feature of rename is that the meaning of ++ newname changes ``atomically'' from any previously existing file ++ by that name to its new meaning (i.e. the file that was called ++ oldname). There is no instant at which newname 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 newname will always be intact if it ++ exists at all. <br> If rename fails, it returns -1. In ++ addition to the usual file name errors (File Name Errors), the ++ following errno error conditions are defined for this function: ++ <br> @table @code @item EACCES One of the directories ++ containing newname or oldname refuses write permission; or ++ newname and oldname are directories and write permission is ++ refused for one of them. <br> @item EBUSY A directory ++ named by oldname or newname is being used by the system in a way ++ that prevents the renaming from working. This includes ++ directories that are mount points for filesystems, and ++ directories that are the current working directories of ++ processes. <br> @item ENOTEMPTY @itemx EEXIST The ++ directory newname isn't empty. The GNU system always returns ++ ENOTEMPTY for this, but some other systems return EEXIST. ++ <br> @item EINVAL oldname is a directory that contains ++ newname. <br> @item EISDIR newname is a directory but the ++ oldname isn't. <br> @item EMLINK The parent directory of ++ newname would have too many links (entries). <br> @item ++ ENOENT The file oldname doesn't exist. <br> @item ENOSPC ++ The directory that would contain newname has no room for another ++ entry, and there is no space left in the file system to expand ++ it. <br> @item EROFS The operation would involve writing ++ to a directory on a read-only file system. <br> @item ++ EXDEV The two file names newname and oldname are on different ++ file systems. @end table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The mkdir function creates a new, empty directory with name ++ filename. <br> The argument mode specifies the file ++ permissions for the new directory file. , for more information ++ about this. <br> A return value of 0 indicates successful ++ completion, and -1 indicates failure. In addition to the usual ++ file name syntax errors (File Name Errors), the following errno ++ error conditions are defined for this function: <br> ++ @table @code @item EACCES Write permission is denied for the ++ parent directory in which the new directory is to be added. ++ <br> @item EEXIST A file named filename already exists. ++ <br> @item EMLINK The parent directory has too many links ++ (entries). <br> Well-designed file systems never report ++ this error, because they permit more links than your disk could ++ possibly hold. However, you must still take account of the ++ possibility of this error, as it could result from network ++ access to a file system on another machine. <br> @item ++ ENOSPC The file system doesn't have enough room to create the ++ new directory. <br> @item EROFS The parent directory of ++ the directory being created is on a read-only file system and ++ cannot be modified. @end table <br> To use this function, ++ your program should include the header file sys/stat.h. @pindex ++ sys/stat.h ++ ++ ++ ++ ++ ++ ++ The stat structure type is used to return information about the ++ attributes of a file. It contains at least the following ++ members: <br> ++ ++ ++ ++ ++ Specifies the mode of the file. This includes file type ++ information (Testing File Type) and the file permission bits ++ (Permission Bits). <br> ++ ++ ++ ++ ++ The file serial number, which distinguishes this file from all ++ other files on the same device. <br> ++ ++ ++ ++ ++ Identifies the device containing the file. The st_ino and ++ st_dev, taken together, uniquely identify the file. The st_dev ++ value is not necessarily consistent across reboots or system ++ crashes, however. <br> ++ ++ ++ ++ ++ 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. <br> ++ ++ ++ ++ ++ The user ID of the file's owner. . <br> ++ ++ ++ ++ ++ The group ID of the file. . <br> ++ ++ ++ ++ ++ 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. <br> ++ ++ ++ ++ ++ This is the last access time for the file. . <br> ++ ++ ++ ++ ++ This is the fractional part of the last access time for the ++ file. . <br> ++ ++ ++ ++ ++ This is the time of the last modification to the contents of the ++ file. . <br> ++ ++ ++ ++ ++ This is the fractional part of the time of the last modification ++ to the contents of the file. . <br> ++ ++ ++ ++ ++ This is the time of the last modification to the attributes of ++ the file. . <br> ++ ++ ++ ++ ++ This is the fractional part of the time of the last modification ++ to the attributes of the file. . <br> @c !!! st_rdev ++ ++ ++ ++ ++ This is the amount of disk space that the file occupies, ++ measured in units of 512-byte blocks. <br> 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. <br> You can tell (approximately) ++ whether a file is sparse by comparing this value with st_size, ++ like this: <br> @smallexample (st.st_blocks * 512 < ++ st.st_size) @end smallexample <br> 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. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ The members of this type are the same and have the same names as ++ those in struct stat. The only difference is that the members ++ st_ino, st_size, and st_blocks have a different type to support ++ larger values. <br> ++ ++ ++ ++ ++ Specifies the mode of the file. This includes file type ++ information (Testing File Type) and the file permission bits ++ (Permission Bits). <br> ++ ++ ++ ++ ++ The file serial number, which distinguishes this file from all ++ other files on the same device. <br> ++ ++ ++ ++ ++ Identifies the device containing the file. The st_ino and ++ st_dev, taken together, uniquely identify the file. The st_dev ++ value is not necessarily consistent across reboots or system ++ crashes, however. <br> ++ ++ ++ ++ ++ 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. <br> ++ ++ ++ ++ ++ The user ID of the file's owner. . <br> ++ ++ ++ ++ ++ The group ID of the file. . <br> ++ ++ ++ ++ ++ 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. <br> ++ ++ ++ ++ ++ This is the last access time for the file. . <br> ++ ++ ++ ++ ++ This is the fractional part of the last access time for the ++ file. . <br> ++ ++ ++ ++ ++ This is the time of the last modification to the contents of the ++ file. . <br> ++ ++ ++ ++ ++ This is the fractional part of the time of the last modification ++ to the contents of the file. . <br> ++ ++ ++ ++ ++ This is the time of the last modification to the attributes of ++ the file. . <br> ++ ++ ++ ++ ++ This is the fractional part of the time of the last modification ++ to the attributes of the file. . <br> @c !!! st_rdev ++ ++ ++ ++ ++ This is the amount of disk space that the file occupies, ++ measured in units of 512-byte blocks. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++
++ ++ ++ The stat function returns information about the attributes of ++ the file named by filename in the structure pointed to by buf. ++ <br> If filename 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 stat fails ++ reporting a nonexistent file. <br> The return value is 0 ++ if the operation is successful, or -1 on failure. In addition ++ to the usual file name errors (File Name Errors, the following ++ errno error conditions are defined for this function: <br> ++ @table @code @item ENOENT The file named by filename doesn't ++ exist. @end table <br> When the sources are compiled with ++ _FILE_OFFSET_BITS == 64 this function is in fact stat64 since ++ the LFS interface transparently replaces the normal ++ implementation. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to stat 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 struct stat64 ++ to which buf must point. <br> When the sources are ++ compiled with _FILE_OFFSET_BITS == 64 this function is available ++ under the name stat and so transparently replaces the interface ++ for small files on 32-bit machines. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The fstat function is like stat, except that it takes an open ++ file descriptor as an argument instead of a file name. . ++ <br> Like stat, fstat returns 0 on success and -1 on ++ failure. The following errno error conditions are defined for ++ fstat: <br> @table @code @item EBADF The filedes argument ++ is not a valid file descriptor. @end table <br> When the ++ sources are compiled with _FILE_OFFSET_BITS == 64 this function ++ is in fact fstat64 since the LFS interface transparently ++ replaces the normal implementation. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to fstat but is able to work on large ++ files on 32-bit platforms. For large files the file descriptor ++ filedes should be obtained by open64 or creat64. The buf pointer ++ points to a variable of type struct stat64 which is able to ++ represent the larger values. <br> When the sources are ++ compiled with _FILE_OFFSET_BITS == 64 this function is available ++ under the name fstat and so transparently replaces the interface ++ for small files on 32-bit machines. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The lstat function is like stat, except that it does not follow ++ symbolic links. If filename is the name of a symbolic link, ++ lstat returns information about the link itself; otherwise lstat ++ works like stat. . <br> When the sources are compiled ++ with _FILE_OFFSET_BITS == 64 this function is in fact lstat64 ++ since the LFS interface transparently replaces the normal ++ implementation. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to lstat 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 struct stat64 ++ to which buf must point. <br> When the sources are ++ compiled with _FILE_OFFSET_BITS == 64 this function is available ++ under the name lstat and so transparently replaces the interface ++ for small files on 32-bit machines. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++
++ ++ ++ The chown function changes the owner of the file filename to ++ owner, and its group owner to group. <br> Changing the ++ owner of the file on certain systems clears the set-user-ID and ++ set-group-ID permission bits. (This is because those bits may ++ not be appropriate for the new owner.) Other file permission ++ bits are not changed. <br> The return value is 0 on ++ success and -1 on failure. In addition to the usual file name ++ errors (File Name Errors), the following errno error conditions ++ are defined for this function: <br> @table @code @item ++ EPERM This process lacks permission to make the requested ++ change. <br> Only privileged users or the file's owner can ++ change the file's group. On most file systems, only privileged ++ users can change the file owner; some file systems allow you to ++ change the owner if you are currently the owner. When you ++ access a remote file system, the behavior you encounter is ++ determined by the system that actually holds the file, not by ++ the system your program is running on. <br> , for ++ information about the _POSIX_CHOWN_RESTRICTED macro. <br> ++ @item EROFS The file is on a read-only file system. @end table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This is like chown, except that it changes the owner of the open ++ file with descriptor filedes. <br> The return value from ++ fchown is 0 on success and -1 on failure. The following errno ++ error codes are defined for this function: <br> @table ++ @code @item EBADF The filedes argument is not a valid file ++ descriptor. <br> @item EINVAL The filedes argument ++ corresponds to a pipe or socket, not an ordinary file. ++ <br> @item EPERM This process lacks permission to make the ++ requested change. For details see chmod above. <br> @item ++ EROFS The file resides on a read-only file system. @end table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The umask function sets the file creation mask of the current ++ process to mask, and returns the previous value of the file ++ creation mask. <br> Here is an example showing how to read ++ the mask with umask without changing it permanently: <br> ++ @smallexample mode_t read_umask (void) mode_t mask = umask ++ (0); umask (mask); return mask; @ @end smallexample ++ <br> @noindent However, it is better to use getumask if ++ you just want to read the mask value, because it is reentrant ++ (at least if you use the GNU operating system). ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ Return the current value of the file creation mask for the ++ current process. This function is a GNU extension. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The chmod function sets the access permission bits for the file ++ named by filename to mode. <br> If filename is a symbolic ++ link, chmod changes the permissions of the file pointed to by ++ the link, not those of the link itself. <br> This function ++ returns 0 if successful and -1 if not. In addition to the usual ++ file name errors (File Name Errors), the following errno error ++ conditions are defined for this function: <br> @table ++ @code @item ENOENT The named file doesn't exist. <br> ++ @item EPERM This process does not have permission to change the ++ access permissions of this file. Only the file's owner (as ++ judged by the effective user ID of the process) or a privileged ++ user can change them. <br> @item EROFS The file resides on ++ a read-only file system. <br> @item EFTYPE mode has the ++ S_ISVTX bit (the ``sticky bit'') set, and the named file is not ++ a directory. Some systems do not allow setting the sticky bit ++ on non-directory files, and some do (and only some of those ++ assign a useful meaning to the bit for non-directory files). ++ <br> You only get EFTYPE 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 mode and call chmod again. , for ++ full details on the sticky bit. @end table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This is like chmod, except that it changes the permissions of ++ the currently open file given by filedes. <br> The return ++ value from fchmod is 0 on success and -1 on failure. The ++ following errno error codes are defined for this function: ++ <br> @table @code @item EBADF The filedes argument is not ++ a valid file descriptor. <br> @item EINVAL The filedes ++ argument corresponds to a pipe or socket, or something else that ++ doesn't really have access permissions. <br> @item EPERM ++ This process does not have permission to change the access ++ permissions of this file. Only the file's owner (as judged by ++ the effective user ID of the process) or a privileged user can ++ change them. <br> @item EROFS The file resides on a ++ read-only file system. @end table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The access function checks to see whether the file named by ++ filename can be accessed in the way specified by the how ++ argument. The how argument either can be the bitwise OR of the ++ flags R_OK, W_OK, X_OK, or the existence test F_OK. <br> ++ This function uses the real user and group IDs of the calling ++ process, rather than the effective IDs, to check for access ++ permission. As a result, if you use the function from a setuid ++ or setgid program (How Change Persona), it gives information ++ relative to the user who actually ran the program. <br> ++ The return value is 0 if the access is permitted, and -1 ++ otherwise. (In other words, treated as a predicate function, ++ access returns true if the requested access is denied.) ++ <br> In addition to the usual file name errors (File Name ++ Errors), the following errno error conditions are defined for ++ this function: <br> @table @code @item EACCES The access ++ specified by how is denied. <br> @item ENOENT The file ++ doesn't exist. <br> @item EROFS Write permission was ++ requested for a file on a read-only file system. @end table ++ ++ ++ ++ ++ ++ ++ The utimbuf structure is used with the utime function to specify ++ new access and modification times for a file. It contains the ++ following members: <br> ++ ++ ++ ++ ++ This is the access time for the file. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++
++ ++ ++ This function is used to modify the file times associated with ++ the file named filename. <br> If times 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 actime and modtime members (respectively) of the utimbuf ++ structure pointed to by times. <br> The attribute ++ modification time for the file is set to the current time in ++ either case (since changing the time stamps is itself a ++ modification of the file attributes). <br> The utime ++ function returns 0 if successful and -1 on failure. In addition ++ to the usual file name errors (File Name Errors), the following ++ errno error conditions are defined for this function: <br> ++ @table @code @item EACCES There is a permission problem in the ++ case where a null pointer was passed as the times argument. In ++ order to update the time stamp on the file, you must either be ++ the owner of the file, have write permission for the file, or be ++ a privileged user. <br> @item ENOENT The file doesn't ++ exist. <br> @item EPERM If the times argument is not a ++ null pointer, you must either be the owner of the file or be a ++ privileged user. <br> @item EROFS The file lives on a ++ read-only file system. @end table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function sets the file access and modification times of the ++ file filename. The new file access time is specified by tvp[0], ++ and the new modification time by tvp[1]. Similar to utime, if ++ tvp is a null pointer then the access and modification times of ++ the file are set to the current time. This function comes from ++ BSD. <br> The return values and error conditions are the ++ same as for the utime function. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is like utimes, except that it does not follow ++ symbolic links. If filename is the name of a symbolic link, ++ lutimes sets the file access and modification times of the ++ symbolic link special file itself (as seen by lstat; Symbolic ++ Links) while utimes 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 ENOSYS). <br> The return ++ values and error conditions are the same as for the utime ++ function. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is like utimes, 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 ENOSYS). ++ <br> Like utimes, futimes returns 0 on success and -1 on ++ failure. The following errno error conditions are defined for ++ futimes: <br> @table @code @item EACCES There is a ++ permission problem in the case where a null pointer was passed ++ as the times argument. In order to update the time stamp on the ++ file, you must either be the owner of the file, have write ++ permission for the file, or be a privileged user. <br> ++ @item EBADF The filedes argument is not a valid file descriptor. ++ <br> @item EPERM If the times argument is not a null ++ pointer, you must either be the owner of the file or be a ++ privileged user. <br> @item EROFS The file lives on a ++ read-only file system. @end table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> The truncate function changes the size of filename to ++ length. If length is shorter than the previous length, data at ++ the end will be lost. The file must be writable by the user to ++ perform this operation. <br> If length is longer, holes ++ will be added to the end. However, some systems do not support ++ this feature and will leave the file unchanged. <br> When ++ the source file is compiled with _FILE_OFFSET_BITS == 64 the ++ truncate function is in fact truncate64 and the type off_t has ++ 64 bits which makes it possible to handle files up to 2^63 bytes ++ in length. <br> The return value is 0 for success, or -1 ++ for an error. In addition to the usual file name errors, the ++ following errors may occur: <br> @table @code <br> ++ @item EACCES The file is a directory or not writable. <br> ++ @item EINVAL length is negative. <br> @item EFBIG The ++ operation would extend the file beyond the limits of the ++ operating system. <br> @item EIO A hardware I/O error ++ occurred. <br> @item EPERM The file is "append-only" or ++ "immutable". <br> @item EINTR The operation was ++ interrupted by a signal. <br> @end table <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to the truncate function. The ++ difference is that the length argument is 64 bits wide even on ++ 32 bits machines, which allows the handling of files with sizes ++ up to 2^63 bytes. <br> When the source file is compiled ++ with _FILE_OFFSET_BITS == 64 on a 32 bits machine this function ++ is actually available under the name truncate and so ++ transparently replaces the 32 bits interface. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> This is like truncate, but it works on a file ++ descriptor fd for an opened file instead of a file name to ++ identify the object. The file must be opened for writing to ++ successfully carry out the operation. <br> The POSIX ++ standard leaves it implementation defined what happens if the ++ specified new length of the file is bigger than the original ++ size. The ftruncate 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 ftruncate is no reliable way to increase the file size but ++ if it is possible it is probably the fastest way. The function ++ also operates on POSIX shared memory segments if these are ++ implemented by the system. <br> ftruncate is especially ++ useful in combination with mmap. Since the mapped region must ++ have a fixed size one cannot enlarge the file by writing ++ something beyond the last mapped page. Instead one has to ++ enlarge the file itself and then remap the file with the new ++ size. The example below shows how this works. <br> When ++ the source file is compiled with _FILE_OFFSET_BITS == 64 the ++ ftruncate function is in fact ftruncate64 and the type off_t has ++ 64 bits which makes it possible to handle files up to 2^63 bytes ++ in length. <br> The return value is 0 for success, or -1 ++ for an error. The following errors may occur: <br> @table ++ @code <br> @item EBADF fd does not correspond to an open ++ file. <br> @item EACCES fd is a directory or not open for ++ writing. <br> @item EINVAL length is negative. <br> ++ @item EFBIG The operation would extend the file beyond the ++ limits of the operating system. @c or the open() call -- with ++ the not-yet-discussed feature of opening @c files with ++ extra-large offsets. <br> @item EIO A hardware I/O error ++ occurred. <br> @item EPERM The file is "append-only" or ++ "immutable". <br> @item EINTR The operation was ++ interrupted by a signal. <br> @c ENOENT is also possible ++ on Linux --- however it only occurs if the file @c descriptor ++ has a `file' structure but no `inode' structure. I'm not @c ++ sure how such an fd could be created. Perhaps it's a bug. ++ <br> @end table <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to the ftruncate function. The ++ difference is that the length argument is 64 bits wide even on ++ 32 bits machines which allows the handling of files with sizes ++ up to 2^63 bytes. <br> When the source file is compiled ++ with _FILE_OFFSET_BITS == 64 on a 32 bits machine this function ++ is actually available under the name ftruncate and so ++ transparently replaces the 32 bits interface. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The mknod function makes a special file with name filename. The ++ mode specifies the mode of the file, and may include the various ++ special file bits, such as S_IFCHR (for a character special ++ file) or S_IFBLK (for a block special file). . <br> The ++ dev argument specifies which device the special file refers to. ++ Its exact interpretation depends on the kind of special file ++ being created. <br> The return value is 0 on success and ++ -1 on error. In addition to the usual file name errors (File ++ Name Errors), the following errno error conditions are defined ++ for this function: <br> @table @code @item EPERM The ++ calling process is not privileged. Only the superuser can ++ create special files. <br> @item ENOSPC The directory or ++ file system that would contain the new file is full and cannot ++ be extended. <br> @item EROFS The directory containing the ++ new file can't be modified because it's on a read-only file ++ system. <br> @item EEXIST There is already a file named ++ filename. If you want to replace this file, you must remove the ++ old file explicitly first. @end table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function creates a temporary binary file for update mode, ++ as if by calling fopen with mode "wb+". The file is deleted ++ automatically when it is closed or when the program terminates. ++ (On some other ISO C systems the file may fail to be deleted if ++ the program terminates abnormally). <br> This function is ++ reentrant. <br> When the sources are compiled with ++ _FILE_OFFSET_BITS == 64 on a 32-bit system this function is in ++ fact tmpfile64, i.e. the LFS interface transparently replaces ++ the old interface. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to tmpfile, but the stream it returns a ++ pointer to was opened using tmpfile64. Therefore this stream ++ can be used for files larger then 2^31 bytes on 32-bit machines. ++ <br> Please note that the return type is still FILE *. ++ There is no special FILE type for the LFS interface. <br> ++ If the sources are compiled with _FILE_OFFSET_BITS == 64 on a 32 ++ bits machine this function is available under the name tmpfile ++ and so transparently replaces the old interface. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function constructs and returns a valid file name that does ++ not refer to any existing file. If the result 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 ++ result argument should be a pointer to an array of at least ++ L_tmpnam characters, and the result is written into that array. ++ <br> It is possible for tmpnam 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 tmpnam ++ fails it returns a null pointer. <br> Warning: Between the ++ time the pathname is constructed and the file is created another ++ process might have created a file with the same name using ++ tmpnam, leading to a possible security hole. The implementation ++ generates names which can hardly be predicted, but when opening ++ the file you should use the O_EXCL flag. Using tmpfile or ++ mkstemp is a safe way to avoid this problem. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is nearly identical to the tmpnam function, except ++ that if result is a null pointer it returns a null pointer. ++ <br> This guarantees reentrancy because the non-reentrant ++ situation of tmpnam cannot happen here. <br> Warning: This ++ function has the same security problems as tmpnam. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function generates a unique temporary file name. If prefix ++ 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 malloc, so you should release its ++ storage with free when it is no longer needed. <br> ++ Because the string is dynamically allocated this function is ++ reentrant. <br> The directory prefix for the temporary ++ file name is determined by testing each of the following in ++ sequence. The directory must exist and be writable. <br> ++ @itemize @bullet @item The environment variable TMPDIR, if it is ++ defined. For security reasons this only happens if the program ++ is not SUID or SGID enabled. <br> @item The dir argument, ++ if it is not a null pointer. <br> @item The value of the ++ P_tmpdir macro. <br> @item The directory /tmp. @end ++ itemize <br> This function is defined for SVID ++ compatibility. <br> Warning: Between the time the pathname ++ is constructed and the file is created another process might ++ have created a file with the same name using tempnam, leading to ++ a possible security hole. The implementation generates names ++ which can hardly be predicted, but when opening the file you ++ should use the O_EXCL flag. Using tmpfile or mkstemp is a safe ++ way to avoid this problem. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++
++ ++ ++ The mktemp function generates a unique file name by modifying ++ template as described above. If successful, it returns template ++ as modified. If mktemp cannot find a unique file name, it makes ++ template an empty string and returns that. If template does not ++ end with XXXXXX, mktemp returns a null pointer. <br> ++ Warning: Between the time the pathname is constructed and the ++ file is created another process might have created a file with ++ the same name using mktemp, leading to a possible security hole. ++ The implementation generates names which can hardly be ++ predicted, but when opening the file you should use the O_EXCL ++ flag. Using mkstemp is a safe way to avoid this problem. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The mkstemp function generates a unique file name just as mktemp ++ does, but it also opens the file for you with open (Opening and ++ Closing Files). If successful, it modifies template in place ++ and returns a file descriptor for that file open for reading and ++ writing. If mkstemp cannot create a uniquely-named file, it ++ returns -1. If template does not end with XXXXXX, mkstemp ++ returns -1 and does not modify template. <br> The file is ++ opened using mode 0600. If the file is meant to be used by ++ other users this mode must be changed explicitly. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The mkdtemp function creates a directory with a unique name. If ++ it succeeds, it overwrites template with the name of the ++ directory, and returns template. As with mktemp and mkstemp, ++ template should be a string ending with XXXXXX. <br> If ++ mkdtemp cannot create an uniquely named directory, it returns ++ NULL and sets errno appropriately. If template does not end ++ with XXXXXX, mkdtemp returns NULL and does not modify template. ++ errno will be set to EINVAL in this case. <br> The ++ directory is created using mode 0700. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The getopt function gets the next option argument from the ++ argument list specified by the argv and argc arguments. Normally ++ these values come directly from the arguments received by main. ++ <br> The options argument is a string that specifies the ++ option characters that are valid for this program. An option ++ character in this string can be followed by a colon (:) to ++ indicate that it takes a required argument. If an option ++ character is followed by two colons (::), its argument is ++ optional; this is a GNU extension. <br> getopt has three ++ ways to deal with options that follow non-options argv elements. ++ The special argument -- forces in all cases the end of option ++ scanning. <br> @itemize @bullet @item The default is to ++ permute the contents of argv while scanning it so that ++ eventually all the non-options are at the end. This allows ++ options to be given in any order, even with programs that were ++ not written to expect this. <br> @item If the options ++ argument string begins with a hyphen (-), this is treated ++ specially. It permits arguments that are not options to be ++ returned as if they were associated with option character \1. ++ <br> @item POSIX demands the following behavior: The first ++ non-option stops option processing. This mode is selected by ++ either setting the environment variable POSIXLY_CORRECT or ++ beginning the options argument string with a plus sign (+). @end ++ itemize <br> The getopt function returns the option ++ character for the next command line option. When no more option ++ arguments are available, it returns -1. There may still be more ++ non-option arguments; you must compare the external variable ++ optind against the argc parameter to check this. <br> If ++ the option has an argument, getopt returns the argument by ++ storing it in the variable optarg. You don't ordinarily need to ++ copy the optarg string, since it is a pointer into the original ++ argv array, not into a static area that might be overwritten. ++ <br> If getopt finds an option character in argv that was ++ not included in options, or a missing option argument, it ++ returns ? and sets the external variable optopt to the actual ++ option character. If the first character of options is a colon ++ (:), then getopt returns : instead of ? to indicate a missing ++ option argument. In addition, if the external variable opterr ++ is nonzero (which is the default), getopt prints an error ++ message. ++ ++ ++ ++ ++ ++ ++ This structure describes a single long option name for the sake ++ of getopt_long. The argument longopts must be an array of these ++ structures, one for each long option. Terminate the array with ++ an element containing all zeros. <br> The struct option ++ structure has these fields: <br> ++ ++ ++ ++ ++ This field is the name of the option. It is a string. ++ <br> ++ ++ ++ ++ ++ This field says whether the option takes an argument. It is an ++ integer, and there are three legitimate values: no_argument, ++ required_argument and optional_argument. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ Decode options from the vector argv (whose length is argc). The ++ argument shortopts describes the short options to accept, just ++ as it does in getopt. The argument longopts describes the long ++ options to accept (see above). <br> When getopt_long ++ encounters a short option, it does the same thing that getopt ++ would do: it returns the character code for the option, and ++ stores the options argument (if it has one) in optarg. ++ <br> When getopt_long encounters a long option, it takes ++ actions based on the flag and val fields of the definition of ++ that option. <br> If flag is a null pointer, then ++ getopt_long returns the contents of val to indicate which option ++ it found. You should arrange distinct values in the val field ++ for options with different meanings, so you can decode these ++ values after getopt_long returns. If the long option is ++ equivalent to a short option, you can use the short option's ++ character code in val. <br> If flag is not a null pointer, ++ that means this option should just set a flag in the program. ++ The flag is a variable of type int that you define. Put the ++ address of the flag in the flag field. Put in the val field the ++ value you would like this option to store in the flag. In this ++ case, getopt_long returns 0. <br> For any long option, ++ getopt_long tells you the index in the array longopts of the ++ options definition, by storing it into *indexptr. You can get ++ the name of the option with longopts[*indexptr].name. So you ++ can distinguish among long options either by the values in their ++ val fields or by their indices. You can also distinguish in ++ this way among long options that set flags. <br> When a ++ long option has an argument, getopt_long puts the argument value ++ in the variable optarg before returning. When the option has no ++ argument, the value in optarg is a null pointer. This is how ++ you can tell whether an optional argument was supplied. ++ <br> When getopt_long has no more options to handle, it ++ returns -1, and leaves in the variable optind the index in argv ++ of the next remaining argument. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> The getopt_long_only function is equivalent to the ++ getopt_long function but it allows to specify the user of the ++ application to pass long options with only - instead of --. The ++ -- prefix is still recognized but instead of looking through the ++ short options if a - is seen it is first tried whether this ++ parameter names a long option. If not, it is parsed as a short ++ option. <br> Assuming getopt_long_only is used starting an ++ application with <br> @smallexample app -foo @end ++ smallexample <br> @noindent the getopt_long_only will ++ first look for a long option named foo. If this is not found, ++ the short options f, o, and again o are recognized. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The ctermid function returns a string containing the file name ++ of the controlling terminal for the current process. If string ++ is not a null pointer, it should be an array that can hold at ++ least L_ctermid characters; the string is returned in this ++ array. Otherwise, a pointer to a string in a static area is ++ returned, which might get overwritten on subsequent calls to ++ this function. <br> 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. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++
++ ++ ++ The setsid function creates a new session. The calling process ++ becomes the session leader, and is put in a new process group ++ whose process group ID is the same as the process ID of that ++ process. There are initially no other processes in the new ++ process group, and no other process groups in the new session. ++ <br> This function also makes the calling process have no ++ controlling terminal. <br> The setsid function returns the ++ new process group ID of the calling process if successful. A ++ return value of -1 indicates an error. The following errno ++ error conditions are defined for this function: <br> ++ @table @code @item EPERM The calling process is already a ++ process group leader, or there is already another process group ++ around that has the same process group ID. @end table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> The getsid function returns the process group ID of ++ the session leader of the specified process. If a pid is 0, the ++ process group ID of the session leader of the current process is ++ returned. <br> In case of error -1 is returned and errno ++ is set. The following errno error conditions are defined for ++ this function: <br> @table @code @item ESRCH There is no ++ process with the given process ID pid. @item EPERM The calling ++ process and the process specified by pid 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 ++ pid from the calling process. @end table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The setpgid function puts the process pid into the process group ++ pgid. As a special case, either pid or pgid can be zero to ++ indicate the process ID of the calling process. <br> This ++ function fails on a system that does not support job control. , ++ for more information. <br> If the operation is successful, ++ setpgid returns zero. Otherwise it returns -1. The following ++ errno error conditions are defined for this function: <br> ++ @table @code @item EACCES The child process named by pid has ++ executed an exec function since it was forked. <br> @item ++ EINVAL The value of the pgid is not valid. <br> @item ++ ENOSYS The system doesn't support job control. <br> @item ++ EPERM The process indicated by the pid argument is a session ++ leader, or is not in the same session as the calling process, or ++ the value of the pgid argument doesn't match a process group ID ++ in the same session as the calling process. <br> @item ++ ESRCH The process indicated by the pid argument is not the ++ calling process or a child of the calling process. @end table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This is the BSD Unix name for setpgid. Both functions do ++ exactly the same thing. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function returns the process group ID of the foreground ++ process group associated with the terminal open on descriptor ++ filedes. <br> If there is no foreground process group, the ++ return value is a number greater than 1 that does not match the ++ process group ID of any existing process group. This can happen ++ if all of the processes in the job that was formerly the ++ foreground job have terminated, and no other job has yet been ++ moved into the foreground. <br> In case of an error, a ++ value of -1 is returned. The following errno error conditions ++ are defined for this function: <br> @table @code @item ++ EBADF The filedes argument is not a valid file descriptor. ++ <br> @item ENOSYS The system doesn't support job control. ++ <br> @item ENOTTY The terminal file associated with the ++ filedes argument isn't the controlling terminal of the calling ++ process. @end table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is used to set a terminal's foreground process ++ group ID. The argument filedes is a descriptor which specifies ++ the terminal; pgid specifies the process group. The calling ++ process must be a member of the same session as pgid and must ++ have the same controlling terminal. <br> For terminal ++ access purposes, this function is treated as output. If it is ++ called from a background process on its controlling terminal, ++ normally all processes in the process group are sent a SIGTTOU ++ signal. The exception is if the calling process itself is ++ ignoring or blocking SIGTTOU signals, in which case the ++ operation is performed and no signal is sent. <br> If ++ successful, tcsetpgrp returns 0. A return value of -1 indicates ++ an error. The following errno error conditions are defined for ++ this function: <br> @table @code @item EBADF The filedes ++ argument is not a valid file descriptor. <br> @item EINVAL ++ The pgid argument is not valid. <br> @item ENOSYS The ++ system doesn't support job control. <br> @item ENOTTY The ++ filedes isn't the controlling terminal of the calling process. ++ <br> @item EPERM The pgid isn't a process group in the ++ same session as the calling process. @end table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is used to obtain the process group ID of the ++ session for which the terminal specified by fildes is the ++ controlling terminal. If the call is successful the group ID is ++ returned. Otherwise the return value is (pid_t) -1 and the ++ global variable errno is set to the following value: @table ++ @code @item EBADF The filedes argument is not a valid file ++ descriptor. <br> @item ENOTTY The calling process does not ++ have a controlling terminal, or the file is not the controlling ++ terminal. @end table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++
++
++
++
++
++
++ ++ ++ The open function creates and returns a new file descriptor for ++ the file named by filename. Initially, the file position ++ indicator for the file is at the beginning of the file. The ++ argument mode is used only when a file is created, but it ++ doesn't hurt to supply the argument in any case. <br> The ++ flags argument controls how the file is to be opened. This is a ++ bit mask; you create the value by the bitwise OR of the ++ appropriate parameters (using the | operator in C). , for the ++ parameters available. <br> The normal return value from ++ open is a non-negative integer file descriptor. In the case of ++ an error, a value of -1 is returned instead. In addition to the ++ usual file name errors (File Name Errors), the following errno ++ error conditions are defined for this function: <br> ++ @table @code @item EACCES The file exists but is not ++ readable/writable as requested by the flags argument, the file ++ does not exist and the directory is unwritable so it cannot be ++ created. <br> @item EEXIST Both O_CREAT and O_EXCL are ++ set, and the named file already exists. <br> @item EINTR ++ The open operation was interrupted by a signal. . <br> ++ @item EISDIR The flags argument specified write access, and the ++ file is a directory. <br> @item EMFILE The process has too ++ many files open. The maximum number of file descriptors is ++ controlled by the RLIMIT_NOFILE resource limit; Limits on ++ Resources. <br> @item ENFILE The entire system, or perhaps ++ the file system which contains the directory, cannot support any ++ additional open files at the moment. (This problem cannot happen ++ on the GNU system.) <br> @item ENOENT The named file does ++ not exist, and O_CREAT is not specified. <br> @item ENOSPC ++ The directory or file system that would contain the new file ++ cannot be extended, because there is no disk space left. ++ <br> @item ENXIO O_NONBLOCK and O_WRONLY are both set in ++ the flags argument, the file named by filename is a FIFO (Pipes ++ and FIFOs), and no process has the file open for reading. ++ <br> @item EROFS The file resides on a read-only file ++ system and any of O_WRONLY, O_RDWR, and O_TRUNC are set in the ++ flags argument, or O_CREAT is set and the file does not already ++ exist. @end table <br> @c !!! umask <br> If on a 32 ++ bit machine the sources are translated with _FILE_OFFSET_BITS == ++ 64 the function open returns a file descriptor opened in the ++ large file mode which enables the file handling functions to use ++ files up to 2^63 bytes in size and offset from -2^63 to 2^63. ++ This happens transparently for the user since all of the ++ lowlevel file handling functions are equally replaced. ++ <br> 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 open is called. If the ++ thread gets canceled these resources stay allocated until the ++ program ends. To avoid this calls to open should be protected ++ using cancellation handlers. @c ref pthread_cleanup_push / ++ pthread_cleanup_pop <br> The open function is the ++ underlying primitive for the fopen and freopen functions, that ++ create streams. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to open. It returns a file descriptor ++ which can be used to access the file named by filename. The ++ only difference is that on 32 bit systems the file is opened in ++ the large file mode. I.e., file length and file offsets can ++ exceed 31 bits. <br> When the sources are translated with ++ _FILE_OFFSET_BITS == 64 this function is actually available ++ under the name open. I.e., the new, extended API using 64 bit ++ file sizes and offsets transparently replaces the old API. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++
++ ++ ++ The function close closes the file descriptor filedes. Closing a ++ file has the following consequences: <br> @itemize @bullet ++ @item The file descriptor is deallocated. <br> @item Any ++ record locks owned by the process on the file are unlocked. ++ <br> @item When all file descriptors associated with a ++ pipe or FIFO have been closed, any unread data is discarded. ++ @end itemize <br> This function is a cancellation point in ++ multi-threaded programs. This is a problem if the thread ++ allocates some resources (like memory, file descriptors, ++ semaphores or whatever) at the time close is called. If the ++ thread gets canceled these resources stay allocated until the ++ program ends. To avoid this, calls to close should be protected ++ using cancellation handlers. @c ref pthread_cleanup_push / ++ pthread_cleanup_pop <br> The normal return value from ++ close is 0; a value of -1 is returned in case of failure. The ++ following errno error conditions are defined for this function: ++ <br> @table @code @item EBADF The filedes argument is not ++ a valid file descriptor. <br> @item EINTR The close call ++ was interrupted by a signal. . Here is an example of how to ++ handle EINTR properly: <br> @smallexample ++ TEMP_FAILURE_RETRY (close (desc)); @end smallexample <br> ++ @item ENOSPC @itemx EIO @itemx EDQUOT When the file is accessed ++ by NFS, these errors from write can sometimes not be detected ++ until close. , for details on their meaning. @end table ++ <br> Please note that there is no separate close64 ++ function. This is not necessary since this function does not ++ determine nor depend on the mode of the file. The kernel which ++ performs the close operation knows which mode the descriptor is ++ used for and can handle this situation. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The read function reads up to size bytes from the file with ++ descriptor filedes, storing the results in the buffer. (This is ++ not necessarily a character string, and no terminating null ++ character is added.) <br> @cindex end-of-file, on a file ++ descriptor The return value is the number of bytes actually ++ read. This might be less than size; for example, if there ++ aren't that many bytes left in the file or if there aren't that ++ many bytes immediately available. The exact behavior depends on ++ what kind of file it is. Note that reading less than size bytes ++ is not an error. <br> A value of zero indicates ++ end-of-file (except if the value of the size argument is also ++ zero). This is not considered an error. If you keep calling ++ read while at end-of-file, it will keep returning zero and doing ++ nothing else. <br> If read returns at least one character, ++ there is no way you can tell whether end-of-file was reached. ++ But if you did reach the end, the next read will return zero. ++ <br> In case of an error, read returns -1. The following ++ errno error conditions are defined for this function: <br> ++ @table @code @item EAGAIN Normally, when no input is immediately ++ available, read waits for some input. But if the O_NONBLOCK ++ flag is set for the file (File Status Flags), read returns ++ immediately without reading any data, and reports this error. ++ <br> Compatibility Note: Most versions of BSD Unix use a ++ different error code for this: EWOULDBLOCK. In the GNU library, ++ EWOULDBLOCK is an alias for EAGAIN, so it doesn't matter which ++ name you use. <br> On some systems, reading a large amount ++ of data from a character special file can also fail with EAGAIN ++ if the kernel cannot find enough physical memory to lock down ++ the user's pages. This is limited to devices that transfer with ++ direct memory access into the user's memory, which means it does ++ not include terminals, since they always use separate buffers ++ inside the kernel. This problem never happens in the GNU ++ system. <br> Any condition that could result in EAGAIN can ++ instead result in a successful read which returns fewer bytes ++ than requested. Calling read again immediately would result in ++ EAGAIN. <br> @item EBADF The filedes argument is not a ++ valid file descriptor, or is not open for reading. <br> ++ @item EINTR read was interrupted by a signal while it was ++ waiting for input. . A signal will not necessary cause read to ++ return EINTR; it may instead result in a successful read which ++ returns fewer bytes than requested. <br> @item EIO For ++ many devices, and for disk files, this error code indicates a ++ hardware error. <br> EIO also occurs when a background ++ process tries to read from the controlling terminal, and the ++ normal action of stopping the process by sending it a SIGTTIN ++ signal isn't working. This might happen if the signal is being ++ blocked or ignored, or because the process group is orphaned. , ++ for more information about job control, and Signal Handling, for ++ information about signals. @end table <br> Please note ++ that there is no function named read64. This is not necessary ++ since this function does not directly modify or handle the ++ possibly wide file offset. Since the kernel handles this state ++ internally, the read function can be used for all cases. ++ <br> This function is a cancellation point in ++ multi-threaded programs. This is a problem if the thread ++ allocates some resources (like memory, file descriptors, ++ semaphores or whatever) at the time read is called. If the ++ thread gets canceled these resources stay allocated until the ++ program ends. To avoid this, calls to read should be protected ++ using cancellation handlers. @c ref pthread_cleanup_push / ++ pthread_cleanup_pop <br> The read function is the ++ underlying primitive for all of the functions that read from ++ streams, such as fgetc. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The pread function is similar to the read function. The first ++ three arguments are identical, and the return values and error ++ codes also correspond. <br> The difference is the fourth ++ argument and its handling. The data block is not read from the ++ current position of the file descriptor filedes. Instead the ++ data is read from the file starting at position offset. The ++ position of the file descriptor itself is not affected by the ++ operation. The value is the same as before the call. <br> ++ When the source file is compiled with _FILE_OFFSET_BITS == 64 ++ the pread function is in fact pread64 and the type off_t has 64 ++ bits, which makes it possible to handle files up to 2^63 bytes ++ in length. <br> The return value of pread describes the ++ number of bytes read. In the error case it returns -1 like read ++ does and the error codes are also the same, with these ++ additions: <br> @table @code @item EINVAL The value given ++ for offset is negative and therefore illegal. <br> @item ++ ESPIPE The file descriptor filedes is associate with a pipe or a ++ FIFO and this device does not allow positioning of the file ++ pointer. @end table <br> The function is an extension ++ defined in the Unix Single Specification version 2. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to the pread function. The difference ++ is that the offset parameter is of type off64_t instead of off_t ++ which makes it possible on 32 bit machines to address files ++ larger than 2^31 bytes and up to 2^63 bytes. The file ++ descriptor filedes must be opened using open64 since otherwise ++ the large offsets possible with off64_t will lead to errors with ++ a descriptor in small file mode. <br> When the source file ++ is compiled with _FILE_OFFSET_BITS == 64 on a 32 bit machine ++ this function is actually available under the name pread and so ++ transparently replaces the 32 bit interface. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The write function writes up to size bytes from buffer to the ++ file with descriptor filedes. The data in buffer is not ++ necessarily a character string and a null character is output ++ like any other character. <br> The return value is the ++ number of bytes actually written. This may be size, but can ++ always be smaller. Your program should always call write in a ++ loop, iterating until all the data is written. <br> Once ++ write returns, the data is enqueued to be written and can be ++ read back right away, but it is not necessarily written out to ++ permanent storage immediately. You can use fsync when you need ++ to be sure your data has been permanently stored before ++ continuing. (It is more efficient for the system to batch up ++ consecutive writes and do them all at once when convenient. ++ Normally they will always be written to disk within a minute or ++ less.) Modern systems provide another function fdatasync which ++ guarantees integrity only for the file data and is therefore ++ faster. @c !!! xref fsync, fdatasync You can use the O_FSYNC ++ open mode to make write always store the data to disk before ++ returning; Operating Modes. <br> In the case of an error, ++ write returns -1. The following errno error conditions are ++ defined for this function: <br> @table @code @item EAGAIN ++ Normally, write blocks until the write operation is complete. ++ But if the O_NONBLOCK flag is set for the file (Control ++ Operations), it returns immediately without writing any data and ++ reports this error. An example of a situation that might cause ++ the process to block on output is writing to a terminal device ++ that supports flow control, where output has been suspended by ++ receipt of a STOP character. <br> Compatibility Note: Most ++ versions of BSD Unix use a different error code for this: ++ EWOULDBLOCK. In the GNU library, EWOULDBLOCK is an alias for ++ EAGAIN, so it doesn't matter which name you use. <br> On ++ some systems, writing a large amount of data from a character ++ special file can also fail with EAGAIN if the kernel cannot find ++ enough physical memory to lock down the user's pages. This is ++ limited to devices that transfer with direct memory access into ++ the user's memory, which means it does not include terminals, ++ since they always use separate buffers inside the kernel. This ++ problem does not arise in the GNU system. <br> @item EBADF ++ The filedes argument is not a valid file descriptor, or is not ++ open for writing. <br> @item EFBIG The size of the file ++ would become larger than the implementation can support. ++ <br> @item EINTR The write operation was interrupted by a ++ signal while it was blocked waiting for completion. A signal ++ will not necessarily cause write to return EINTR; it may instead ++ result in a successful write which writes fewer bytes than ++ requested. . <br> @item EIO For many devices, and for disk ++ files, this error code indicates a hardware error. <br> ++ @item ENOSPC The device containing the file is full. <br> ++ @item EPIPE This error is returned when you try to write to a ++ pipe or FIFO that isn't open for reading by any process. When ++ this happens, a SIGPIPE signal is also sent to the process; see ++ Signal Handling. @end table <br> Unless you have arranged ++ to prevent EINTR failures, you should check errno after each ++ failing call to write, and if the error was EINTR, you should ++ simply repeat the call. . The easy way to do this is with the ++ macro TEMP_FAILURE_RETRY, as follows: <br> @smallexample ++ nbytes = TEMP_FAILURE_RETRY (write (desc, buffer, count)); @end ++ smallexample <br> Please note that there is no function ++ named write64. This is not necessary since this function does ++ not directly modify or handle the possibly wide file offset. ++ Since the kernel handles this state internally the write ++ function can be used for all cases. <br> This function is ++ a cancellation point in multi-threaded programs. This is a ++ problem if the thread allocates some resources (like memory, ++ file descriptors, semaphores or whatever) at the time write is ++ called. If the thread gets canceled these resources stay ++ allocated until the program ends. To avoid this, calls to write ++ should be protected using cancellation handlers. @c ref ++ pthread_cleanup_push / pthread_cleanup_pop <br> The write ++ function is the underlying primitive for all of the functions ++ that write to streams, such as fputc. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The pwrite function is similar to the write function. The first ++ three arguments are identical, and the return values and error ++ codes also correspond. <br> The difference is the fourth ++ argument and its handling. The data block is not written to the ++ current position of the file descriptor filedes. Instead the ++ data is written to the file starting at position offset. The ++ position of the file descriptor itself is not affected by the ++ operation. The value is the same as before the call. <br> ++ When the source file is compiled with _FILE_OFFSET_BITS == 64 ++ the pwrite function is in fact pwrite64 and the type off_t has ++ 64 bits, which makes it possible to handle files up to 2^63 ++ bytes in length. <br> The return value of pwrite describes ++ the number of written bytes. In the error case it returns -1 ++ like write does and the error codes are also the same, with ++ these additions: <br> @table @code @item EINVAL The value ++ given for offset is negative and therefore illegal. <br> ++ @item ESPIPE The file descriptor filedes is associated with a ++ pipe or a FIFO and this device does not allow positioning of the ++ file pointer. @end table <br> The function is an extension ++ defined in the Unix Single Specification version 2. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to the pwrite function. The difference ++ is that the offset parameter is of type off64_t instead of off_t ++ which makes it possible on 32 bit machines to address files ++ larger than 2^31 bytes and up to 2^63 bytes. The file ++ descriptor filedes must be opened using open64 since otherwise ++ the large offsets possible with off64_t will lead to errors with ++ a descriptor in small file mode. <br> When the source file ++ is compiled using _FILE_OFFSET_BITS == 64 on a 32 bit machine ++ this function is actually available under the name pwrite and so ++ transparently replaces the 32 bit interface. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The lseek function is used to change the file position of the ++ file with descriptor filedes. <br> The whence argument ++ specifies how the offset should be interpreted, in the same way ++ as for the fseek function, and it must be one of the symbolic ++ constants SEEK_SET, SEEK_CUR, or SEEK_END. <br> @table ++ @code @item SEEK_SET Specifies that whence is a count of ++ characters from the beginning of the file. <br> @item ++ SEEK_CUR Specifies that whence is a count of characters from the ++ current file position. This count may be positive or negative. ++ <br> @item SEEK_END Specifies that whence is a count of ++ characters from the end of the file. A negative count specifies ++ a position within the current extent of the file; a positive ++ count specifies a position past the current end. If you set the ++ position past the current end, and actually write data, you will ++ extend the file with zeros up to that position. @end table ++ <br> The return value from lseek is normally the resulting ++ file position, measured in bytes from the beginning of the file. ++ You can use this feature together with SEEK_CUR to read the ++ current file position. <br> If you want to append to the ++ file, setting the file position to the current end of file with ++ SEEK_END is not sufficient. Another process may write more data ++ after you seek but before you write, extending the file so the ++ position you write onto clobbers their data. Instead, use the ++ O_APPEND operating mode; Operating Modes. <br> You can set ++ the file position past the current end of the file. This does ++ not by itself make the file longer; lseek never changes the ++ file. But subsequent output at that position will extend the ++ file. Characters between the previous end of file and the new ++ position are filled with zeros. Extending the file in this way ++ can create a ``hole'': the blocks of zeros are not actually ++ allocated on disk, so the file takes up less space than it ++ appears to; it is then called a ``sparse file''. @cindex sparse ++ files @cindex holes in files <br> If the file position ++ cannot be changed, or the operation is in some way invalid, ++ lseek returns a value of -1. The following errno error ++ conditions are defined for this function: <br> @table ++ @code @item EBADF The filedes is not a valid file descriptor. ++ <br> @item EINVAL The whence argument value is not valid, ++ or the resulting file offset is not valid. A file offset is ++ invalid. <br> @item ESPIPE The filedes corresponds to an ++ object that cannot be positioned, such as a pipe, FIFO or ++ terminal device. (POSIX.1 specifies this error only for pipes ++ and FIFOs, but in the GNU system, you always get ESPIPE if the ++ object is not seekable.) @end table <br> When the source ++ file is compiled with _FILE_OFFSET_BITS == 64 the lseek function ++ is in fact lseek64 and the type off_t has 64 bits which makes it ++ possible to handle files up to 2^63 bytes in length. <br> ++ This function is a cancellation point in multi-threaded ++ programs. This is a problem if the thread allocates some ++ resources (like memory, file descriptors, semaphores or ++ whatever) at the time lseek is called. If the thread gets ++ canceled these resources stay allocated until the program ends. ++ To avoid this calls to lseek should be protected using ++ cancellation handlers. @c ref pthread_cleanup_push / ++ pthread_cleanup_pop <br> The lseek function is the ++ underlying primitive for the fseek, fseeko, ftell, ftello and ++ rewind functions, which operate on streams instead of file ++ descriptors. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to the lseek function. The difference ++ is that the offset parameter is of type off64_t instead of off_t ++ which makes it possible on 32 bit machines to address files ++ larger than 2^31 bytes and up to 2^63 bytes. The file ++ descriptor filedes must be opened using open64 since otherwise ++ the large offsets possible with off64_t will lead to errors with ++ a descriptor in small file mode. <br> When the source file ++ is compiled with _FILE_OFFSET_BITS == 64 on a 32 bits machine ++ this function is actually available under the name lseek and so ++ transparently replaces the 32 bit interface. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++
++ ++ ++ The fdopen function returns a new stream for the file descriptor ++ filedes. <br> The opentype argument is interpreted in the ++ same way as for the fopen function (Opening Streams), except ++ that the b option is not permitted; this is because GNU makes no ++ distinction between text and binary files. Also, "w" and "w+" ++ do not cause truncation of the file; these have an effect only ++ when opening a file, and in this case the file has already been ++ opened. You must make sure that the opentype argument matches ++ the actual mode of the open file descriptor. <br> The ++ return value is the new stream. If the stream cannot be created ++ (for example, if the modes for the file indicated by the file ++ descriptor do not permit the access specified by the opentype ++ argument), a null pointer is returned instead. <br> In ++ some other systems, fdopen may fail to detect that the modes for ++ file descriptor do not permit the access specified by opentype. ++ The GNU C library always checks for this. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function returns the file descriptor associated with the ++ stream stream. If an error is detected (for example, if the ++ stream is not valid) or if stream does not do I/O to a file, ++ fileno returns -1. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The fileno_unlocked function is equivalent to the fileno ++ function except that it does not implicitly lock the stream if ++ the state is FSETLOCKING_INTERNAL. <br> This function is a ++ GNU extension. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++
++ ++ ++ Clean up the stream stream so that its buffer is empty. If ++ stream is doing output, force it out. If stream is doing input, ++ give the data in the buffer back to the system, arranging to ++ reread it. ++ ++ ++ ++ ++ ++ ++ <br> The iovec structure describes a buffer. It contains ++ two fields: <br> <br> ++ ++ ++ ++ ++ Contains the address of a buffer. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> The readv function reads data from filedes and ++ scatters it into the buffers described in vector, which is taken ++ to be count structures long. As each buffer is filled, data is ++ sent to the next. <br> Note that readv is not guaranteed ++ to fill all the buffers. It may stop at any point, for the same ++ reasons read would. <br> The return value is a count of ++ bytes (not buffers) read, 0 indicating end-of-file, or -1 ++ indicating an error. The possible errors are the same as in ++ read. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> The writev function gathers data from the buffers ++ described in vector, which is taken to be count structures long, ++ and writes them to filedes. As each buffer is written, it moves ++ on to the next. <br> Like readv, writev may stop midstream ++ under the same conditions write would. <br> The return ++ value is a count of bytes written, or -1 indicating an error. ++ The possible errors are the same as in write. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> The mmap function creates a new mapping, connected to ++ bytes (offset) to (offset + length - 1) in the file open on ++ filedes. A new reference for the file specified by filedes is ++ created, which is not removed by closing the file. <br> ++ address gives a preferred starting address for the mapping. NULL ++ expresses no preference. Any previous mapping at that address is ++ automatically removed. The address you give may still be ++ changed, unless you use the MAP_FIXED flag. <br> @vindex ++ PROT_READ @vindex PROT_WRITE @vindex PROT_EXEC protect contains ++ flags that control what kind of access is permitted. They ++ include PROT_READ, PROT_WRITE, and PROT_EXEC, which permit ++ reading, writing, and execution, respectively. Inappropriate ++ access will cause a segfault (Program Error Signals). <br> ++ Note that most hardware designs cannot support write permission ++ without read permission, and many do not distinguish read and ++ execute permission. Thus, you may receive wider permissions than ++ you ask for, and mappings of write-only files may be denied even ++ if you do not use PROT_READ. <br> flags contains flags ++ that control the nature of the map. One of MAP_SHARED or ++ MAP_PRIVATE must be specified. <br> They include: ++ <br> @vtable @code @item MAP_PRIVATE This specifies that ++ writes to the region should never be written back to the ++ attached file. Instead, a copy is made for the process, and the ++ region will be swapped normally if memory runs low. No other ++ process will see the changes. <br> Since private mappings ++ effectively revert to ordinary memory when written to, you must ++ have enough virtual memory for a copy of the entire mmapped ++ region if you use this mode with PROT_WRITE. <br> @item ++ MAP_SHARED This specifies that writes to the region will be ++ written back to the file. Changes made will be shared ++ immediately with other processes mmaping the same file. ++ <br> Note that actual writing may take place at any time. ++ You need to use msync, described below, if it is important that ++ other processes using conventional I/O get a consistent view of ++ the file. <br> @item MAP_FIXED This forces the system to ++ use the exact mapping address specified in address and fail if ++ it can't. <br> @c One of these is official - the other is ++ obviously an obsolete synonym @c Which is which? @item ++ MAP_ANONYMOUS @itemx MAP_ANON This flag tells the system to ++ create an anonymous mapping, not connected to a file. filedes ++ and off are ignored, and the region is initialized with zeros. ++ <br> Anonymous maps are used as the basic primitive to ++ extend the heap on some systems. They are also useful to share ++ data between multiple tasks without creating a file. <br> ++ On some systems using private anonymous mmaps is more efficient ++ than using malloc for large blocks. This is not an issue with ++ the GNU C library, as the included malloc automatically uses ++ mmap where appropriate. <br> @c Linux has some other MAP_ ++ options, which I have not discussed here. @c MAP_DENYWRITE, ++ MAP_EXECUTABLE and MAP_GROWSDOWN don't seem applicable to @c ++ user programs (and I don't understand the last two). MAP_LOCKED ++ does @c not appear to be implemented. <br> @end vtable ++ <br> mmap returns the address of the new mapping, or -1 ++ for an error. <br> Possible errors include: <br> ++ @table @code <br> @item EINVAL <br> Either address ++ was unusable, or inconsistent flags were given. <br> @item ++ EACCES <br> filedes was not open for the type of access ++ specified in protect. <br> @item ENOMEM <br> Either ++ there is not enough memory for the operation, or the process is ++ out of address space. <br> @item ENODEV <br> This ++ file is of a type that doesn't support mapping. <br> @item ++ ENOEXEC <br> The file is on a filesystem that doesn't ++ support mapping. <br> @c On Linux, EAGAIN will appear if ++ the file has a conflicting mandatory lock. @c However mandatory ++ locks are not discussed in this manual. @c @c Similarly, ETXTBSY ++ will occur if the MAP_DENYWRITE flag (not documented @c here) is ++ used and the file is already open for writing. <br> @end ++ table <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The mmap64 function is equivalent to the mmap function but the ++ offset parameter is of type off64_t. On 32-bit systems this ++ allows the file associated with the filedes descriptor to be ++ larger than 2GB. filedes must be a descriptor returned from a ++ call to open64 or fopen64 and freopen64 where the descriptor is ++ retrieved with fileno. <br> When the sources are ++ translated with _FILE_OFFSET_BITS == 64 this function is ++ actually available under the name mmap. I.e., the new, extended ++ API using 64 bit file sizes and offsets transparently replaces ++ the old API. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> munmap removes any memory maps from (addr) to (addr + ++ length). length should be the length of the mapping. <br> ++ It is safe to unmap multiple mappings in one command, or include ++ unmapped space in the range. It is also possible to unmap only ++ part of an existing mapping. However, only entire pages can be ++ removed. If length is not an even number of pages, it will be ++ rounded up. <br> It returns 0 for success and -1 for an ++ error. <br> One error is possible: <br> @table @code ++ <br> @item EINVAL The memory range given was outside the ++ user mmap range or wasn't page aligned. <br> @end table ++ <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> When using shared mappings, the kernel can write the ++ file at any time before the mapping is removed. To be certain ++ data has actually been written to the file and will be ++ accessible to non-memory-mapped I/O, it is necessary to use this ++ function. <br> It operates on the region address to ++ (address + length). It may be used on part of a mapping or ++ multiple mappings, however the region given should not contain ++ any unmapped space. <br> flags can contain some options: ++ <br> @vtable @code <br> @item MS_SYNC <br> ++ This flag makes sure the data is actually written to disk. ++ Normally msync only makes sure that accesses to a file with ++ conventional I/O reflect the recent changes. <br> @item ++ MS_ASYNC <br> This tells msync to begin the ++ synchronization, but not to wait for it to complete. <br> ++ @c Linux also has MS_INVALIDATE, which I don't understand. ++ <br> @end vtable <br> msync returns 0 for success ++ and -1 for error. Errors include: <br> @table @code ++ <br> @item EINVAL An invalid region was given, or the ++ flags were invalid. <br> @item EFAULT There is no existing ++ mapping in at least part of the given region. <br> @end ++ table <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> This function can be used to change the size of an ++ existing memory area. address and length must cover a region ++ entirely mapped in the same mmap statement. A new mapping with ++ the same characteristics will be returned with the length ++ new_length. <br> One option is possible, MREMAP_MAYMOVE. ++ If it is given in flags, the system may remove the existing ++ mapping and create a new one of the desired length in another ++ location. <br> The address of the resulting mapping is ++ returned, or -1. Possible error codes include: <br> @table ++ @code <br> @item EFAULT There is no existing mapping in at ++ least part of the original region, or the region covers two or ++ more distinct mappings. <br> @item EINVAL The address ++ given is misaligned or inappropriate. <br> @item EAGAIN ++ The region has pages locked, and if extended it would exceed the ++ process's resource limit for locked pages. . <br> @item ++ ENOMEM The region is private writable, and insufficient virtual ++ memory is available to extend it. Also, this error will occur ++ if MREMAP_MAYMOVE is not given and the extension would collide ++ with another mapped region. <br> @end table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> This function can be used to provide the system with ++ advice about the intended usage patterns of the memory region ++ starting at addr and extending length bytes. <br> The ++ valid BSD values for advice are: <br> @table @code ++ <br> @item MADV_NORMAL The region should receive no ++ further special treatment. <br> @item MADV_RANDOM The ++ region will be accessed via random page references. The kernel ++ should page-in the minimal number of pages for each page fault. ++ <br> @item MADV_SEQUENTIAL The region will be accessed via ++ sequential page references. This may cause the kernel to ++ aggressively read-ahead, expecting further sequential references ++ after any page fault within this region. <br> @item ++ MADV_WILLNEED The region will be needed. The pages within this ++ region may be pre-faulted in by the kernel. <br> @item ++ MADV_DONTNEED The region is no longer needed. The kernel may ++ free these pages, causing any changes to the pages to be lost, ++ as well as swapped out pages to be discarded. <br> @end ++ table <br> The POSIX names are slightly different, but ++ with the same meanings: <br> @table @code <br> @item ++ POSIX_MADV_NORMAL This corresponds with BSD's MADV_NORMAL. ++ <br> @item POSIX_MADV_RANDOM This corresponds with BSD's ++ MADV_RANDOM. <br> @item POSIX_MADV_SEQUENTIAL This ++ corresponds with BSD's MADV_SEQUENTIAL. <br> @item ++ POSIX_MADV_WILLNEED This corresponds with BSD's MADV_WILLNEED. ++ <br> @item POSIX_MADV_DONTNEED This corresponds with BSD's ++ MADV_DONTNEED. <br> @end table <br> msync returns 0 ++ for success and -1 for error. Errors include: @table @code ++ <br> @item EINVAL An invalid region was given, or the ++ advice was invalid. <br> @item EFAULT There is no existing ++ mapping in at least part of the given region. <br> @end ++ table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The select function blocks the calling process until there is ++ activity on any of the specified sets of file descriptors, or ++ until the timeout period has expired. <br> The file ++ descriptors specified by the read-fds argument are checked to ++ see if they are ready for reading; the write-fds file ++ descriptors are checked to see if they are ready for writing; ++ and the except-fds file descriptors are checked for exceptional ++ conditions. You can pass a null pointer for any of these ++ arguments if you are not interested in checking for that kind of ++ condition. <br> A file descriptor is considered ready for ++ reading if it is not at end of file. A server socket is ++ considered ready for reading if there is a pending connection ++ which can be accepted with accept; Accepting Connections. A ++ client socket is ready for writing when its connection is fully ++ established; Connecting. <br> ``Exceptional conditions'' ++ does not mean errors---errors are reported immediately when an ++ erroneous system call is executed, and do not constitute a state ++ of the descriptor. Rather, they include conditions such as the ++ presence of an urgent message on a socket. (, for information ++ on urgent messages.) <br> The select function checks only ++ the first nfds file descriptors. The usual thing is to pass ++ FD_SETSIZE as the value of this argument. <br> The timeout ++ specifies the maximum time to wait. If you pass a null pointer ++ for this argument, it means to block indefinitely until one of ++ the file descriptors is ready. Otherwise, you should provide ++ the time in struct timeval format; see High-Resolution Calendar. ++ Specify zero as the time (a struct timeval containing all ++ zeros) if you want to find out which descriptors are ready ++ without waiting if none are ready. <br> The normal return ++ value from select is the total number of ready file descriptors ++ in all of the sets. Each of the argument sets is overwritten ++ with information about the descriptors that are ready for the ++ corresponding operation. Thus, to see if a particular ++ descriptor desc has input, use FD_ISSET (desc, read-fds) after ++ select returns. <br> If select returns because the timeout ++ period expires, it returns a value of zero. <br> Any ++ signal will cause select to return immediately. So if your ++ program uses signals, you can't rely on select to keep waiting ++ for the full time specified. If you want to be sure of waiting ++ for a particular amount of time, you must check for EINTR and ++ repeat the select with a newly calculated timeout based on the ++ current time. See the example below. See also Interrupted ++ Primitives. <br> If an error occurs, select returns -1 and ++ does not modify the argument file descriptor sets. The ++ following errno error conditions are defined for this function: ++ <br> @table @code @item EBADF One of the file descriptor ++ sets specified an invalid file descriptor. <br> @item ++ EINTR The operation was interrupted by a signal. . <br> ++ @item EINVAL The timeout argument is invalid; one of the ++ components is negative or too large. @end table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ A call to this function will not return as long as there is data ++ which has not been written to the device. All dirty buffers in ++ the kernel will be written and so an overall consistent system ++ can be achieved (if no other process in parallel writes data). ++ <br> A prototype for sync can be found in unistd.h. ++ <br> The return value is zero to indicate no error. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The fsync function can be used to make sure all data associated ++ with the open file fildes is written to the device associated ++ with the descriptor. The function call does not return unless ++ all actions have finished. <br> A prototype for fsync can ++ be found in unistd.h. <br> This function is a cancellation ++ point in multi-threaded programs. This is a problem if the ++ thread allocates some resources (like memory, file descriptors, ++ semaphores or whatever) at the time fsync is called. If the ++ thread gets canceled these resources stay allocated until the ++ program ends. To avoid this, calls to fsync should be protected ++ using cancellation handlers. @c ref pthread_cleanup_push / ++ pthread_cleanup_pop <br> The return value of the function ++ is zero if no error occurred. Otherwise it is -1 and the global ++ variable errno is set to the following values: @table @code ++ @item EBADF The descriptor fildes is not valid. <br> @item ++ EINVAL No synchronization is possible since the system does not ++ implement this. @end table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ When a call to the fdatasync function returns, it is ensured ++ that all of the file data is written to the device. For all ++ pending I/O operations, the parts guaranteeing data integrity ++ finished. <br> Not all systems implement the fdatasync ++ operation. On systems missing this functionality fdatasync is ++ emulated by a call to fsync since the performed actions are a ++ superset of those required by fdatasync. <br> The ++ prototype for fdatasync is in unistd.h. <br> The return ++ value of the function is zero if no error occurred. Otherwise ++ it is -1 and the global variable errno is set to the following ++ values: @table @code @item EBADF The descriptor fildes is not ++ valid. <br> @item EINVAL No synchronization is possible ++ since the system does not implement this. @end table ++ ++ ++ ++ ++ ++ ++ The POSIX.1b standard mandates that the struct aiocb structure ++ contains at least the members described in the following table. ++ There might be more elements which are used by the ++ implementation, but depending upon these elements is not ++ portable and is highly deprecated. <br> ++ ++ ++ ++ ++ This element specifies the file descriptor to be used for the ++ operation. It must be a legal descriptor, otherwise the ++ operation will fail. <br> The device on which the file is ++ opened must allow the seek operation. I.e., it is not possible ++ to use any of the AIO operations on devices like terminals where ++ an lseek call would lead to an error. <br> ++ ++ ++ ++ ++ This element specifies the offset in the file at which the ++ operation (input or output) is performed. Since the operations ++ are carried out in arbitrary order and more than one operation ++ for one file descriptor can be started, one cannot expect a ++ current read/write position of the file descriptor. <br> ++ ++ ++ ++ ++ This is a pointer to the buffer with the data to be written or ++ the place where the read data is stored. <br> ++ ++ ++ ++ ++ This element specifies the length of the buffer pointed to by ++ aio_buf. <br> ++ ++ ++ ++ ++ If the platform has defined _POSIX_PRIORITIZED_IO and ++ _POSIX_PRIORITY_SCHEDULING, the AIO requests are processed based ++ on the current scheduling priority. The aio_reqprio element can ++ then be used to lower the priority of the AIO operation. ++ <br> ++ ++ ++ ++ ++ This element specifies how the calling process is notified once ++ the operation terminates. If the sigev_notify element is ++ SIGEV_NONE, no notification is sent. If it is SIGEV_SIGNAL, the ++ signal determined by sigev_signo is sent. Otherwise, ++ sigev_notify must be SIGEV_THREAD. In this case, a thread is ++ created which starts executing the function pointed to by ++ sigev_notify_function. <br> ++ ++ ++ ++ ++ This element is only used by the lio_listio and lio_listio64 ++ functions. Since these functions allow an arbitrary number of ++ operations to start at once, and each operation can be input or ++ output (or nothing), the information must be stored in the ++ control block. The possible values are: <br> @vtable ++ @code ++ ++ ++ ++ ++ Start a read operation. Read from the file at position ++ aio_offset and store the next aio_nbytes bytes in the buffer ++ pointed to by aio_buf. <br> ++ ++ ++ ++ ++ Start a write operation. Write aio_nbytes bytes starting at ++ aio_buf into the file starting at position aio_offset. ++ <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ This element specifies the file descriptor which is used for the ++ operation. It must be a legal descriptor since otherwise the ++ operation fails for obvious reasons. <br> The device on ++ which the file is opened must allow the seek operation. I.e., it ++ is not possible to use any of the AIO operations on devices like ++ terminals where an lseek call would lead to an error. <br> ++ ++ ++ ++ ++ This element specifies at which offset in the file the operation ++ (input or output) is performed. Since the operation are carried ++ in arbitrary order and more than one operation for one file ++ descriptor can be started, one cannot expect a current ++ read/write position of the file descriptor. <br> ++ ++ ++ ++ ++ This is a pointer to the buffer with the data to be written or ++ the place where the read data is stored. <br> ++ ++ ++ ++ ++ This element specifies the length of the buffer pointed to by ++ aio_buf. <br> ++ ++ ++ ++ ++ If for the platform _POSIX_PRIORITIZED_IO and ++ _POSIX_PRIORITY_SCHEDULING are defined the AIO requests are ++ processed based on the current scheduling priority. The ++ aio_reqprio element can then be used to lower the priority of ++ the AIO operation. <br> ++ ++ ++ ++ ++ This element specifies how the calling process is notified once ++ the operation terminates. If the sigev_notify, element is ++ SIGEV_NONE no notification is sent. If it is SIGEV_SIGNAL, the ++ signal determined by sigev_signo is sent. Otherwise, ++ sigev_notify must be SIGEV_THREAD in which case a thread which ++ starts executing the function pointed to by ++ sigev_notify_function. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function initiates an asynchronous read operation. It ++ immediately returns after the operation was enqueued or when an ++ error was encountered. <br> The first ++ aiocbp->aio_nbytes bytes of the file for which ++ aiocbp->aio_fildes is a descriptor are written to the buffer ++ starting at aiocbp->aio_buf. Reading starts at the absolute ++ position aiocbp->aio_offset in the file. <br> If ++ prioritized I/O is supported by the platform the ++ aiocbp->aio_reqprio value is used to adjust the priority ++ before the request is actually enqueued. <br> The calling ++ process is notified about the termination of the read request ++ according to the aiocbp->aio_sigevent value. <br> When ++ aio_read returns, the return value is zero if no error occurred ++ that can be found before the process is enqueued. If such an ++ early error is found, the function returns -1 and sets errno to ++ one of the following values: <br> @table @code @item ++ EAGAIN The request was not enqueued due to (temporarily) ++ exceeded resource limitations. @item ENOSYS The aio_read ++ function is not implemented. @item EBADF The ++ aiocbp->aio_fildes descriptor is not valid. This condition ++ need not be recognized before enqueueing the request and so this ++ error might also be signaled asynchronously. @item EINVAL The ++ aiocbp->aio_offset or aiocbp->aio_reqpiro value is ++ invalid. This condition need not be recognized before ++ enqueueing the request and so this error might also be signaled ++ asynchronously. @end table <br> If aio_read returns zero, ++ the current status of the request can be queried using aio_error ++ and aio_return functions. As long as the value returned by ++ aio_error is EINPROGRESS the operation has not yet completed. ++ If aio_error returns zero, the operation successfully ++ terminated, otherwise the value is to be interpreted as an error ++ code. If the function terminated, the result of the operation ++ can be obtained using a call to aio_return. The returned value ++ is the same as an equivalent call to read would have returned. ++ Possible error codes returned by aio_error are: <br> ++ @table @code @item EBADF The aiocbp->aio_fildes descriptor is ++ not valid. @item ECANCELED The operation was canceled before the ++ operation was finished (Cancel AIO Operations) @item EINVAL The ++ aiocbp->aio_offset value is invalid. @end table <br> ++ When the sources are compiled with _FILE_OFFSET_BITS == 64 this ++ function is in fact aio_read64 since the LFS interface ++ transparently replaces the normal implementation. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to the aio_read function. The only ++ difference is that on 32 bit machines, the file descriptor ++ should be opened in the large file mode. Internally, aio_read64 ++ uses functionality equivalent to lseek64 (File Position ++ Primitive) to position the file descriptor correctly for the ++ reading, as opposed to lseek functionality used in aio_read. ++ <br> When the sources are compiled with _FILE_OFFSET_BITS ++ == 64, this function is available under the name aio_read and so ++ transparently replaces the interface for small files on 32 bit ++ machines. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function initiates an asynchronous write operation. The ++ function call immediately returns after the operation was ++ enqueued or if before this happens an error was encountered. ++ <br> The first aiocbp->aio_nbytes bytes from the buffer ++ starting at aiocbp->aio_buf are written to the file for which ++ aiocbp->aio_fildes is an descriptor, starting at the absolute ++ position aiocbp->aio_offset in the file. <br> If ++ prioritized I/O is supported by the platform, the ++ aiocbp->aio_reqprio value is used to adjust the priority ++ before the request is actually enqueued. <br> The calling ++ process is notified about the termination of the read request ++ according to the aiocbp->aio_sigevent value. <br> When ++ aio_write returns, the return value is zero if no error occurred ++ that can be found before the process is enqueued. If such an ++ early error is found the function returns -1 and sets errno to ++ one of the following values. <br> @table @code @item ++ EAGAIN The request was not enqueued due to (temporarily) ++ exceeded resource limitations. @item ENOSYS The aio_write ++ function is not implemented. @item EBADF The ++ aiocbp->aio_fildes descriptor is not valid. This condition ++ may not be recognized before enqueueing the request, and so this ++ error might also be signaled asynchronously. @item EINVAL The ++ aiocbp->aio_offset or aiocbp->aio_reqprio value is ++ invalid. This condition may not be recognized before enqueueing ++ the request and so this error might also be signaled ++ asynchronously. @end table <br> In the case aio_write ++ returns zero, the current status of the request can be queried ++ using aio_error and aio_return functions. As long as the value ++ returned by aio_error is EINPROGRESS the operation has not yet ++ completed. If aio_error returns zero, the operation ++ successfully terminated, otherwise the value is to be ++ interpreted as an error code. If the function terminated, the ++ result of the operation can be get using a call to aio_return. ++ The returned value is the same as an equivalent call to read ++ would have returned. Possible error codes returned by aio_error ++ are: <br> @table @code @item EBADF The ++ aiocbp->aio_fildes descriptor is not valid. @item ECANCELED ++ The operation was canceled before the operation was finished. ++ (Cancel AIO Operations) @item EINVAL The aiocbp->aio_offset ++ value is invalid. @end table <br> When the sources are ++ compiled with _FILE_OFFSET_BITS == 64, this function is in fact ++ aio_write64 since the LFS interface transparently replaces the ++ normal implementation. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to the aio_write function. The only ++ difference is that on 32 bit machines the file descriptor should ++ be opened in the large file mode. Internally aio_write64 uses ++ functionality equivalent to lseek64 (File Position Primitive) to ++ position the file descriptor correctly for the writing, as ++ opposed to lseek functionality used in aio_write. <br> ++ When the sources are compiled with _FILE_OFFSET_BITS == 64, this ++ function is available under the name aio_write and so ++ transparently replaces the interface for small files on 32 bit ++ machines. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The lio_listio function can be used to enqueue an arbitrary ++ number of read and write requests at one time. The requests can ++ all be meant for the same file, all for different files or every ++ solution in between. <br> lio_listio gets the nent ++ requests from the array pointed to by list. The operation to be ++ performed is determined by the aio_lio_opcode member in each ++ element of list. If this field is LIO_READ a read operation is ++ enqueued, similar to a call of aio_read for this element of the ++ array (except that the way the termination is signalled is ++ different, as we will see below). If the aio_lio_opcode member ++ is LIO_WRITE a write operation is enqueued. Otherwise the ++ aio_lio_opcode must be LIO_NOP in which case this element of ++ list is simply ignored. This ``operation'' is useful in ++ situations where one has a fixed array of struct aiocb elements ++ from which only a few need to be handled at a time. Another ++ situation is where the lio_listio call was canceled before all ++ requests are processed (Cancel AIO Operations) and the remaining ++ requests have to be reissued. <br> The other members of ++ each element of the array pointed to by list must have values ++ suitable for the operation as described in the documentation for ++ aio_read and aio_write above. <br> The mode argument ++ determines how lio_listio behaves after having enqueued all the ++ requests. If mode is LIO_WAIT it waits until all requests ++ terminated. Otherwise mode must be LIO_NOWAIT and in this case ++ the function returns immediately after having enqueued all the ++ requests. In this case the caller gets a notification of the ++ termination of all requests according to the sig parameter. If ++ sig is NULL no notification is send. Otherwise a signal is sent ++ or a thread is started, just as described in the description for ++ aio_read or aio_write. <br> If mode is LIO_WAIT, the ++ return value of lio_listio is 0 when all requests completed ++ successfully. Otherwise the function return -1 and errno is set ++ accordingly. To find out which request or requests failed one ++ has to use the aio_error function on all the elements of the ++ array list. <br> In case mode is LIO_NOWAIT, the function ++ returns 0 if all requests were enqueued correctly. The current ++ state of the requests can be found using aio_error and ++ aio_return as described above. If lio_listio returns -1 in this ++ mode, the global variable errno is set accordingly. If a ++ request did not yet terminate, a call to aio_error returns ++ EINPROGRESS. If the value is different, the request is finished ++ and the error value (or 0) is returned and the result of the ++ operation can be retrieved using aio_return. <br> Possible ++ values for errno are: <br> @table @code @item EAGAIN The ++ resources necessary to queue all the requests are not available ++ at the moment. The error status for each element of list must ++ be checked to determine which request failed. <br> Another ++ reason could be that the system wide limit of AIO requests is ++ exceeded. This cannot be the case for the implementation on GNU ++ systems since no arbitrary limits exist. @item EINVAL The mode ++ parameter is invalid or nent is larger than AIO_LISTIO_MAX. ++ @item EIO One or more of the request's I/O operations failed. ++ The error status of each request should be checked to determine ++ which one failed. @item ENOSYS The lio_listio function is not ++ supported. @end table <br> If the mode parameter is ++ LIO_NOWAIT and the caller cancels a request, the error status ++ for this request returned by aio_error is ECANCELED. <br> ++ When the sources are compiled with _FILE_OFFSET_BITS == 64, this ++ function is in fact lio_listio64 since the LFS interface ++ transparently replaces the normal implementation. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to the lio_listio function. The only ++ difference is that on 32 bit machines, the file descriptor ++ should be opened in the large file mode. Internally, ++ lio_listio64 uses functionality equivalent to lseek64 (File ++ Position Primitive) to position the file descriptor correctly ++ for the reading or writing, as opposed to lseek functionality ++ used in lio_listio. <br> When the sources are compiled ++ with _FILE_OFFSET_BITS == 64, this function is available under ++ the name lio_listio and so transparently replaces the interface ++ for small files on 32 bit machines. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function determines the error state of the request ++ described by the struct aiocb variable pointed to by aiocbp. If ++ the request has not yet terminated the value returned is always ++ EINPROGRESS. Once the request has terminated the value ++ aio_error returns is either 0 if the request completed ++ successfully or it returns the value which would be stored in ++ the errno variable if the request would have been done using ++ read, write, or fsync. <br> The function can return ENOSYS ++ if it is not implemented. It could also return EINVAL if the ++ aiocbp parameter does not refer to an asynchronous operation ++ whose return status is not yet known. <br> When the ++ sources are compiled with _FILE_OFFSET_BITS == 64 this function ++ is in fact aio_error64 since the LFS interface transparently ++ replaces the normal implementation. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to aio_error with the only difference ++ that the argument is a reference to a variable of type struct ++ aiocb64. <br> When the sources are compiled with ++ _FILE_OFFSET_BITS == 64 this function is available under the ++ name aio_error and so transparently replaces the interface for ++ small files on 32 bit machines. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function can be used to retrieve the return status of the ++ operation carried out by the request described in the variable ++ pointed to by aiocbp. As long as the error status of this ++ request as returned by aio_error is EINPROGRESS the return of ++ this function is undefined. <br> Once the request is ++ finished this function can be used exactly once to retrieve the ++ return value. Following calls might lead to undefined behavior. ++ The return value itself is the value which would have been ++ returned by the read, write, or fsync call. <br> The ++ function can return ENOSYS if it is not implemented. It could ++ also return EINVAL if the aiocbp parameter does not refer to an ++ asynchronous operation whose return status is not yet known. ++ <br> When the sources are compiled with _FILE_OFFSET_BITS ++ == 64 this function is in fact aio_return64 since the LFS ++ interface transparently replaces the normal implementation. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to aio_return with the only difference ++ that the argument is a reference to a variable of type struct ++ aiocb64. <br> When the sources are compiled with ++ _FILE_OFFSET_BITS == 64 this function is available under the ++ name aio_return and so transparently replaces the interface for ++ small files on 32 bit machines. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ Calling this function forces all I/O operations operating queued ++ at the time of the function call operating on the file ++ descriptor aiocbp->aio_fildes into the synchronized I/O ++ completion state (Synchronizing I/O). The aio_fsync function ++ returns immediately but the notification through the method ++ described in aiocbp->aio_sigevent will happen only after all ++ requests for this file descriptor have terminated and the file ++ is synchronized. This also means that requests for this very ++ same file descriptor which are queued after the synchronization ++ request are not affected. <br> If op is O_DSYNC the ++ synchronization happens as with a call to fdatasync. Otherwise ++ op should be O_SYNC and the synchronization happens as with ++ fsync. <br> As long as the synchronization has not ++ happened, a call to aio_error with the reference to the object ++ pointed to by aiocbp returns EINPROGRESS. Once the ++ synchronization is done aio_error return 0 if the ++ synchronization was not successful. Otherwise the value ++ returned is the value to which the fsync or fdatasync function ++ would have set the errno variable. In this case nothing can be ++ assumed about the consistency for the data written to this file ++ descriptor. <br> The return value of this function is 0 if ++ the request was successfully enqueued. Otherwise the return ++ value is -1 and errno is set to one of the following values: ++ <br> @table @code @item EAGAIN The request could not be ++ enqueued due to temporary lack of resources. @item EBADF The ++ file descriptor aiocbp->aio_fildes is not valid or not open ++ for writing. @item EINVAL The implementation does not support ++ I/O synchronization or the op parameter is other than O_DSYNC ++ and O_SYNC. @item ENOSYS This function is not implemented. @end ++ table <br> When the sources are compiled with ++ _FILE_OFFSET_BITS == 64 this function is in fact aio_fsync64 ++ since the LFS interface transparently replaces the normal ++ implementation. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to aio_fsync with the only difference ++ that the argument is a reference to a variable of type struct ++ aiocb64. <br> When the sources are compiled with ++ _FILE_OFFSET_BITS == 64 this function is available under the ++ name aio_fsync and so transparently replaces the interface for ++ small files on 32 bit machines. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ When calling this function, the calling thread is suspended ++ until at least one of the requests pointed to by the nent ++ elements of the array list has completed. If any of the ++ requests has already completed at the time aio_suspend is ++ called, the function returns immediately. Whether a request has ++ terminated or not is determined by comparing the error status of ++ the request with EINPROGRESS. If an element of list is NULL, ++ the entry is simply ignored. <br> If no request has ++ finished, the calling process is suspended. If timeout is NULL, ++ the process is not woken until a request has finished. If ++ timeout is not NULL, the process remains suspended at least as ++ long as specified in timeout. In this case, aio_suspend returns ++ with an error. <br> The return value of the function is 0 ++ if one or more requests from the list have terminated. ++ Otherwise the function returns -1 and errno is set to one of the ++ following values: <br> @table @code @item EAGAIN None of ++ the requests from the list completed in the time specified by ++ timeout. @item EINTR A signal interrupted the aio_suspend ++ function. This signal might also be sent by the AIO ++ implementation while signalling the termination of one of the ++ requests. @item ENOSYS The aio_suspend function is not ++ implemented. @end table <br> When the sources are compiled ++ with _FILE_OFFSET_BITS == 64 this function is in fact ++ aio_suspend64 since the LFS interface transparently replaces the ++ normal implementation. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to aio_suspend with the only difference ++ that the argument is a reference to a variable of type struct ++ aiocb64. <br> When the sources are compiled with ++ _FILE_OFFSET_BITS == 64 this function is available under the ++ name aio_suspend and so transparently replaces the interface for ++ small files on 32 bit machines. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The aio_cancel function can be used to cancel one or more ++ outstanding requests. If the aiocbp parameter is NULL, the ++ function tries to cancel all of the outstanding requests which ++ would process the file descriptor fildes (i.e., whose aio_fildes ++ member is fildes). If aiocbp is not NULL, aio_cancel attempts ++ to cancel the specific request pointed to by aiocbp. <br> ++ For requests which were successfully canceled, the normal ++ notification about the termination of the request should take ++ place. I.e., depending on the struct sigevent object which ++ controls this, nothing happens, a signal is sent or a thread is ++ started. If the request cannot be canceled, it terminates the ++ usual way after performing the operation. <br> After a ++ request is successfully canceled, a call to aio_error with a ++ reference to this request as the parameter will return ECANCELED ++ and a call to aio_return will return -1. If the request wasn't ++ canceled and is still running the error status is still ++ EINPROGRESS. <br> The return value of the function is ++ AIO_CANCELED if there were requests which haven't terminated and ++ which were successfully canceled. If there is one or more ++ requests left which couldn't be canceled, the return value is ++ AIO_NOTCANCELED. In this case aio_error must be used to find ++ out which of the, perhaps multiple, requests (in aiocbp is NULL) ++ weren't successfully canceled. If all requests already ++ terminated at the time aio_cancel is called the return value is ++ AIO_ALLDONE. <br> If an error occurred during the ++ execution of aio_cancel the function returns -1 and sets errno ++ to one of the following values. <br> @table @code @item ++ EBADF The file descriptor fildes is not valid. @item ENOSYS ++ aio_cancel is not implemented. @end table <br> When the ++ sources are compiled with _FILE_OFFSET_BITS == 64, this function ++ is in fact aio_cancel64 since the LFS interface transparently ++ replaces the normal implementation. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to aio_cancel with the only difference ++ that the argument is a reference to a variable of type struct ++ aiocb64. <br> When the sources are compiled with ++ _FILE_OFFSET_BITS == 64, this function is available under the ++ name aio_cancel and so transparently replaces the interface for ++ small files on 32 bit machines. ++ ++ ++ ++ ++ ++ ++ This data type is used to pass the configuration or tunable ++ parameters to the implementation. The program has to initialize ++ the members of this struct and pass it to the implementation ++ using the aio_init function. <br> ++ ++ ++ ++ ++ This member specifies the maximal number of threads which may be ++ used at any one time. ++ ++ ++ ++ ++ This number provides an estimate on the maximal number of ++ simultaneously enqueued requests. ++ ++ ++ ++ ++ Unused. ++ ++ ++ ++ ++ Unused. ++ ++ ++ ++ ++ Unused. ++ ++ ++ ++ ++ Unused. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function must be called before any other AIO function. ++ Calling it is completely voluntary, as it is only meant to help ++ the AIO implementation perform better. <br> Before calling ++ the aio_init, function the members of a variable of type struct ++ aioinit must be initialized. Then a reference to this variable ++ is passed as the parameter to aio_init which itself may or may ++ not pay attention to the hints. <br> The function has no ++ return value and no error cases are defined. It is a extension ++ which follows a proposal from the SGI implementation in Irix 6. ++ It is not covered by POSIX.1b or Unix98. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The fcntl function performs the operation specified by command ++ on the file descriptor filedes. Some commands require ++ additional arguments to be supplied. These additional arguments ++ and the return value and error conditions are given in the ++ detailed descriptions of the individual commands. <br> ++ Briefly, here is a list of what the various commands are. ++ <br> @table @code @item F_DUPFD Duplicate the file ++ descriptor (return another file descriptor pointing to the same ++ open file). . <br> @item F_GETFD Get flags associated ++ with the file descriptor. . <br> @item F_SETFD Set flags ++ associated with the file descriptor. . <br> @item F_GETFL ++ Get flags associated with the open file. . <br> @item ++ F_SETFL Set flags associated with the open file. . <br> ++ @item F_GETLK Get a file lock. . <br> @item F_SETLK Set ++ or clear a file lock. . <br> @item F_SETLKW Like F_SETLK, ++ but wait for completion. . <br> @item F_GETOWN Get ++ process or process group ID to receive SIGIO signals. . ++ <br> @item F_SETOWN Set process or process group ID to ++ receive SIGIO signals. . @end table <br> This function is ++ a cancellation point in multi-threaded programs. This is a ++ problem if the thread allocates some resources (like memory, ++ file descriptors, semaphores or whatever) at the time fcntl is ++ called. If the thread gets canceled these resources stay ++ allocated until the program ends. To avoid this calls to fcntl ++ should be protected using cancellation handlers. @c ref ++ pthread_cleanup_push / pthread_cleanup_pop ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function copies descriptor old to the first available ++ descriptor number (the first number not currently open). It is ++ equivalent to fcntl (old, F_DUPFD, 0). ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function copies the descriptor old to descriptor number ++ new. <br> If old is an invalid descriptor, then dup2 does ++ nothing; it does not close new. Otherwise, the new duplicate of ++ old replaces any previous meaning of descriptor new, as if new ++ were closed first. <br> If old and new are different ++ numbers, and old is a valid descriptor number, then dup2 is ++ equivalent to: <br> @smallexample close (new); fcntl (old, ++ F_DUPFD, new) @end smallexample <br> However, dup2 does ++ this atomically; there is no instant in the middle of calling ++ dup2 at which new is closed and not yet a duplicate of old. ++ ++ ++ ++ ++ ++ ++ This structure is used with the fcntl function to describe a ++ file lock. It has these members: <br> ++ ++ ++ ++ ++ Specifies the type of the lock; one of F_RDLCK, F_WRLCK, or ++ F_UNLCK. <br> ++ ++ ++ ++ ++ This corresponds to the whence argument to fseek or lseek, and ++ specifies what the offset is relative to. Its value can be one ++ of SEEK_SET, SEEK_CUR, or SEEK_END. <br> ++ ++ ++ ++ ++ This specifies the offset of the start of the region to which ++ the lock applies, and is given in bytes relative to the point ++ specified by l_whence member. <br> ++ ++ ++ ++ ++ This specifies the length of the region to be locked. A value ++ of 0 is treated specially; it means the region extends to the ++ end of the file. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++
++ ++ ++ <br> The ioctl function performs the generic I/O operation ++ command on filedes. <br> A third argument is usually ++ present, either a single number or a pointer to a structure. ++ The meaning of this argument, the returned value, and any error ++ codes depends upon the command used. Often -1 is returned for a ++ failure. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The function setlocale sets the current locale for category ++ category to locale. A list of all the locales the system ++ provides can be created by running <br> @pindex locale ++ @smallexample locale -a @end smallexample <br> If ++ category is LC_ALL, this specifies the locale for all purposes. ++ The other possible values of category specify an single purpose ++ (Locale Categories). <br> You can also use this function ++ to find out the current locale by passing a null pointer as the ++ locale argument. In this case, setlocale returns a string that ++ is the name of the locale currently selected for category ++ category. <br> The string returned by setlocale can be ++ overwritten by subsequent calls, so you should make a copy of ++ the string (Copying and Concatenation) if you want to save it ++ past any further calls to setlocale. (The standard library is ++ guaranteed never to call setlocale itself.) <br> You ++ should not modify the string returned by setlocale. It might be ++ the same string that was passed as an argument in a previous ++ call to setlocale. One requirement is that the category must be ++ the same in the call the string was returned and the one when ++ the string is passed in as locale parameter. <br> When you ++ read the current locale for category LC_ALL, the value encodes ++ the entire combination of selected locales for all categories. ++ In this case, the value is not just a single locale name. In ++ fact, we don't make any promises about what it looks like. But ++ if you specify the same ``locale name'' with LC_ALL in a ++ subsequent call to setlocale, it restores the same combination ++ of locale selections. <br> To be sure you can use the ++ returned string encoding the currently selected locale at a ++ later time, you must make a copy of the string. It is not ++ guaranteed that the returned pointer remains valid over time. ++ <br> When the locale argument is not a null pointer, the ++ string returned by setlocale reflects the newly-modified locale. ++ <br> If you specify an empty string for locale, this means ++ to read the appropriate environment variable and use its value ++ to select the locale for category. <br> If a nonempty ++ string is given for locale, then the locale of that name is used ++ if possible. <br> If you specify an invalid locale name, ++ setlocale returns a null pointer and leaves the current locale ++ unchanged. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The localeconv function returns a pointer to a structure whose ++ components contain information about how numeric and monetary ++ values should be formatted in the current locale. <br> You ++ should not modify the structure or its contents. The structure ++ might be overwritten by subsequent calls to localeconv, or by ++ calls to setlocale, but no other function in the library ++ overwrites this value. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++
++ ++ ++ The nl_langinfo function can be used to access individual ++ elements of the locale categories. Unlike the localeconv ++ function, which returns all the information, nl_langinfo lets ++ the caller select what information it requires. This is very ++ fast and it is not a problem to call this function multiple ++ times. <br> A second advantage is that in addition to the ++ numeric and monetary formatting information, information from ++ the LC_TIME and LC_MESSAGES categories is available. <br> ++ @pindex langinfo.h The type nl_type is defined in nl_types.h. ++ The argument item is a numeric value defined in the header ++ langinfo.h. The X/Open standard defines the following values: ++ <br> @vtable @code @item CODESET nl_langinfo returns a ++ string with the name of the coded character set used in the ++ selected locale. <br> @item ABDAY_1 @itemx ABDAY_2 @itemx ++ ABDAY_3 @itemx ABDAY_4 @itemx ABDAY_5 @itemx ABDAY_6 @itemx ++ ABDAY_7 nl_langinfo returns the abbreviated weekday name. ++ ABDAY_1 corresponds to Sunday. @item DAY_1 @itemx DAY_2 @itemx ++ DAY_3 @itemx DAY_4 @itemx DAY_5 @itemx DAY_6 @itemx DAY_7 ++ Similar to ABDAY_1 etc., but here the return value is the ++ unabbreviated weekday name. @item ABMON_1 @itemx ABMON_2 @itemx ++ ABMON_3 @itemx ABMON_4 @itemx ABMON_5 @itemx ABMON_6 @itemx ++ ABMON_7 @itemx ABMON_8 @itemx ABMON_9 @itemx ABMON_10 @itemx ++ ABMON_11 @itemx ABMON_12 The return value is abbreviated name of ++ the month. ABMON_1 corresponds to January. @item MON_1 @itemx ++ MON_2 @itemx MON_3 @itemx MON_4 @itemx MON_5 @itemx MON_6 @itemx ++ MON_7 @itemx MON_8 @itemx MON_9 @itemx MON_10 @itemx MON_11 ++ @itemx MON_12 Similar to ABMON_1 etc., but here the month names ++ are not abbreviated. Here the first value MON_1 also corresponds ++ to January. @item AM_STR @itemx PM_STR The return values are ++ strings which can be used in the representation of time as an ++ hour from 1 to 12 plus an am/pm specifier. <br> Note that ++ in locales which do not use this time representation these ++ strings might be empty, in which case the am/pm format cannot be ++ used at all. @item D_T_FMT The return value can be used as a ++ format string for strftime to represent time and date in a ++ locale-specific way. @item D_FMT The return value can be used as ++ a format string for strftime to represent a date in a ++ locale-specific way. @item T_FMT The return value can be used as ++ a format string for strftime to represent time in a ++ locale-specific way. @item T_FMT_AMPM The return value can be ++ used as a format string for strftime to represent time in the ++ am/pm format. <br> Note that if the am/pm format does not ++ make any sense for the selected locale, the return value might ++ be the same as the one for T_FMT. @item ERA The return value ++ represents the era used in the current locale. <br> Most ++ locales do not define this value. An example of a locale which ++ does define this value is the Japanese one. In Japan, the ++ traditional representation of dates includes the name of the era ++ corresponding to the then-emperor's reign. <br> Normally ++ it should not be necessary to use this value directly. ++ Specifying the E modifier in their format strings causes the ++ strftime functions to use this information. The format of the ++ returned string is not specified, and therefore you should not ++ assume knowledge of it on different systems. @item ERA_YEAR The ++ return value gives the year in the relevant era of the locale. ++ As for ERA it should not be necessary to use this value ++ directly. @item ERA_D_T_FMT This return value can be used as a ++ format string for strftime to represent dates and times in a ++ locale-specific era-based way. @item ERA_D_FMT This return value ++ can be used as a format string for strftime to represent a date ++ in a locale-specific era-based way. @item ERA_T_FMT This return ++ value can be used as a format string for strftime to represent ++ time in a locale-specific era-based way. @item ALT_DIGITS The ++ return value is a representation of up to 100 values used to ++ represent the values 0 to 99. As for ERA this value is not ++ intended to be used directly, but instead indirectly through the ++ strftime function. When the modifier O is used in a format ++ which would otherwise use numerals to represent hours, minutes, ++ seconds, weekdays, months, or weeks, the appropriate value for ++ the locale is used instead. @item INT_CURR_SYMBOL The same as ++ the value returned by localeconv in the int_curr_symbol element ++ of the struct lconv. @item CURRENCY_SYMBOL @itemx CRNCYSTR The ++ same as the value returned by localeconv in the currency_symbol ++ element of the struct lconv. <br> CRNCYSTR is a deprecated ++ alias still required by Unix98. @item MON_DECIMAL_POINT The same ++ as the value returned by localeconv in the mon_decimal_point ++ element of the struct lconv. @item MON_THOUSANDS_SEP The same as ++ the value returned by localeconv in the mon_thousands_sep ++ element of the struct lconv. @item MON_GROUPING The same as the ++ value returned by localeconv in the mon_grouping element of the ++ struct lconv. @item POSITIVE_SIGN The same as the value returned ++ by localeconv in the positive_sign element of the struct lconv. ++ @item NEGATIVE_SIGN The same as the value returned by localeconv ++ in the negative_sign element of the struct lconv. @item ++ INT_FRAC_DIGITS The same as the value returned by localeconv in ++ the int_frac_digits element of the struct lconv. @item ++ FRAC_DIGITS The same as the value returned by localeconv in the ++ frac_digits element of the struct lconv. @item P_CS_PRECEDES The ++ same as the value returned by localeconv in the p_cs_precedes ++ element of the struct lconv. @item P_SEP_BY_SPACE The same as ++ the value returned by localeconv in the p_sep_by_space element ++ of the struct lconv. @item N_CS_PRECEDES The same as the value ++ returned by localeconv in the n_cs_precedes element of the ++ struct lconv. @item N_SEP_BY_SPACE The same as the value ++ returned by localeconv in the n_sep_by_space element of the ++ struct lconv. @item P_SIGN_POSN The same as the value returned ++ by localeconv in the p_sign_posn element of the struct lconv. ++ @item N_SIGN_POSN The same as the value returned by localeconv ++ in the n_sign_posn element of the struct lconv. <br> @item ++ INT_P_CS_PRECEDES The same as the value returned by localeconv ++ in the int_p_cs_precedes element of the struct lconv. @item ++ INT_P_SEP_BY_SPACE The same as the value returned by localeconv ++ in the int_p_sep_by_space element of the struct lconv. @item ++ INT_N_CS_PRECEDES The same as the value returned by localeconv ++ in the int_n_cs_precedes element of the struct lconv. @item ++ INT_N_SEP_BY_SPACE The same as the value returned by localeconv ++ in the int_n_sep_by_space element of the struct lconv. @item ++ INT_P_SIGN_POSN The same as the value returned by localeconv in ++ the int_p_sign_posn element of the struct lconv. @item ++ INT_N_SIGN_POSN The same as the value returned by localeconv in ++ the int_n_sign_posn element of the struct lconv. <br> ++ @item DECIMAL_POINT @itemx RADIXCHAR The same as the value ++ returned by localeconv in the decimal_point element of the ++ struct lconv. <br> The name RADIXCHAR is a deprecated ++ alias still used in Unix98. @item THOUSANDS_SEP @itemx THOUSEP ++ The same as the value returned by localeconv in the ++ thousands_sep element of the struct lconv. <br> The name ++ THOUSEP is a deprecated alias still used in Unix98. @item ++ GROUPING The same as the value returned by localeconv in the ++ grouping element of the struct lconv. @item YESEXPR The return ++ value is a regular expression which can be used with the regex ++ function to recognize a positive response to a yes/no question. ++ The GNU C library provides the rpmatch function for easier ++ handling in applications. @item NOEXPR The return value is a ++ regular expression which can be used with the regex function to ++ recognize a negative response to a yes/no question. @item YESSTR ++ The return value is a locale-specific translation of the ++ positive response to a yes/no question. <br> Using this ++ value is deprecated since it is a very special case of message ++ translation, and is better handled by the message translation ++ functions (Message Translation). <br> The use of this ++ symbol is deprecated. Instead message translation should be ++ used. @item NOSTR The return value is a locale-specific ++ translation of the negative response to a yes/no question. What ++ is said for YESSTR is also true here. <br> The use of this ++ symbol is deprecated. Instead message translation should be ++ used. @end vtable <br> The file langinfo.h defines a lot ++ more symbols but none of them is official. Using them is not ++ portable, and the format of the return values might change. ++ Therefore we recommended you not use them. <br> Note that ++ the return value for any valid argument can be used for in all ++ situations (with the possible exception of the am/pm time ++ formatting codes). If the user has not selected any locale for ++ the appropriate category, nl_langinfo returns the information ++ from the "C" locale. It is therefore possible to use this ++ function as shown in the example below. <br> If the ++ argument item is not valid, a pointer to an empty string is ++ returned. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ The strfmon function is similar to the strftime function in that ++ it takes a buffer, its size, a format string, and values to ++ write into the buffer as text in a form specified by the format ++ string. Like strftime, the function also returns the number of ++ bytes written into the buffer. <br> There are two ++ differences: strfmon can take more than one argument, and, of ++ course, the format specification is different. Like strftime, ++ the format string consists of normal text, which is output as ++ is, and format specifiers, which are indicated by a %. ++ Immediately after the %, you can optionally specify various ++ flags and formatting information before the main formatting ++ character, in a similar way to printf: <br> @itemize ++ @bullet @item Immediately following the % there can be one or ++ more of the following flags: @table @asis @item =f The single ++ byte character f is used for this field as the numeric fill ++ character. By default this character is a space character. ++ Filling with this character is only performed if a left ++ precision is specified. It is not just to fill to the given ++ field width. @item ^ The number is printed without grouping the ++ digits according to the rules of the current locale. By default ++ grouping is enabled. @item +, ( At most one of these flags can ++ be used. They select which format to represent the sign of a ++ currency amount. By default, and if + is given, the locale ++ equivalent of +/- is used. If ( is given, negative amounts are ++ enclosed in parentheses. The exact format is determined by the ++ values of the LC_MONETARY category of the locale selected at ++ program runtime. @item ! The output will not contain the ++ currency symbol. @item - The output will be formatted ++ left-justified instead of right-justified if it does not fill ++ the entire field width. @end table @end itemize <br> The ++ next part of a specification is an optional field width. If no ++ width is specified 0 is taken. During output, the function ++ first determines how much space is required. If it requires at ++ least as many characters as given by the field width, it is ++ output using as much space as necessary. Otherwise, it is ++ extended to use the full width by filling with the space ++ character. The presence or absence of the - flag determines the ++ side at which such padding occurs. If present, the spaces are ++ added at the right making the output left-justified, and vice ++ versa. <br> So far the format looks familiar, being ++ similar to the printf and strftime formats. However, the next ++ two optional fields introduce something new. The first one is a ++ # character followed by a decimal digit string. The value of ++ the digit string specifies the number of digit positions to the ++ left of the decimal point (or equivalent). This does not ++ include the grouping character when the ^ flag is not given. If ++ the space needed to print the number does not fill the whole ++ width, the field is padded at the left side with the fill ++ character, which can be selected using the = flag and by default ++ is a space. For example, if the field width is selected as 6 ++ and the number is 123, the fill character is * the result will ++ be ***123. <br> The second optional field starts with a . ++ (period) and consists of another decimal digit string. Its ++ value describes the number of characters printed after the ++ decimal point. The default is selected from the current locale ++ (frac_digits, int_frac_digits, see General Numeric). If the ++ exact representation needs more digits than given by the field ++ width, the displayed value is rounded. If the number of ++ fractional digits is selected to be zero, no decimal point is ++ printed. <br> As a GNU extension, the strfmon ++ implementation in the GNU libc allows an optional L next as a ++ format modifier. If this modifier is given, the argument is ++ expected to be a long double instead of a double value. ++ <br> Finally, the last component is a format specifier. ++ There are three specifiers defined: <br> @table @asis ++ @item i Use the locale's rules for formatting an international ++ currency value. @item n Use the locale's rules for formatting a ++ national currency value. @item % Place a % in the output. There ++ must be no flag, width specifier or modifier given, only %% is ++ allowed. @end table <br> As for printf, the function reads ++ the format string from left to right and uses the values passed ++ to the function following the format string. The values are ++ expected to be either of type double or long double, depending ++ on the presence of the modifier L. The result is stored in the ++ buffer pointed to by s. At most maxsize characters are stored. ++ <br> The return value of the function is the number of ++ characters stored in s, including the terminating NULL byte. If ++ the number of characters stored would exceed maxsize, the ++ function returns -1 and the content of the buffer s is ++ unspecified. In this case errno is set to E2BIG. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The function rpmatch checks the string in response whether or ++ not it is a correct yes-or-no answer and if yes, which one. The ++ check uses the YESEXPR and NOEXPR data in the LC_MESSAGES ++ category of the currently selected locale. The return value is ++ as follows: <br> @table @code @item 1 The user entered an ++ affirmative answer. <br> @item 0 The user entered a ++ negative answer. <br> @item -1 The answer matched neither ++ the YESEXPR nor the NOEXPR regular expression. @end table ++ <br> This function is not standardized but available ++ beside in GNU libc at least also in the IBM AIX library. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the sine of x, where x is given in ++ radians. The return value is in the range -1 to 1. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the sine of x, where x is given in ++ radians. The return value is in the range -1 to 1. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the sine of x, where x is given in ++ radians. The return value is in the range -1 to 1. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the cosine of x, where x is given in ++ radians. The return value is in the range -1 to 1. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the cosine of x, where x is given in ++ radians. The return value is in the range -1 to 1. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the cosine of x, where x is given in ++ radians. The return value is in the range -1 to 1. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the tangent of x, where x is given in ++ radians. <br> Mathematically, the tangent function has ++ singularities at odd multiples of pi/2. If the argument x is ++ too close to one of these singularities, tan will signal ++ overflow. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the tangent of x, where x is given in ++ radians. <br> Mathematically, the tangent function has ++ singularities at odd multiples of pi/2. If the argument x is ++ too close to one of these singularities, tan will signal ++ overflow. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the tangent of x, where x is given in ++ radians. <br> Mathematically, the tangent function has ++ singularities at odd multiples of pi/2. If the argument x is ++ too close to one of these singularities, tan will signal ++ overflow. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the sine of x in *sinx and the cosine of ++ x in *cos, where x is given in radians. Both values, *sinx and ++ *cosx, are in the range of -1 to 1. <br> This function is ++ a GNU extension. Portable programs should be prepared to cope ++ with its absence. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the sine of x in *sinx and the cosine of ++ x in *cos, where x is given in radians. Both values, *sinx and ++ *cosx, are in the range of -1 to 1. <br> This function is ++ a GNU extension. Portable programs should be prepared to cope ++ with its absence. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the sine of x in *sinx and the cosine of ++ x in *cos, where x is given in radians. Both values, *sinx and ++ *cosx, are in the range of -1 to 1. <br> This function is ++ a GNU extension. Portable programs should be prepared to cope ++ with its absence. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the complex sine of z. The mathematical ++ definition of the complex sine is <br> @ifnottex sin (z) = ++ 1/(2*i) * (exp (z*i) - exp (-z*i)). @end ifnottex @tex $$\sin(z) ++ = {1\over 2i} (e^{zi} - e^{-zi})$$ @end tex ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the complex sine of z. The mathematical ++ definition of the complex sine is <br> @ifnottex sin (z) = ++ 1/(2*i) * (exp (z*i) - exp (-z*i)). @end ifnottex @tex $$\sin(z) ++ = {1\over 2i} (e^{zi} - e^{-zi})$$ @end tex ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the complex sine of z. The mathematical ++ definition of the complex sine is <br> @ifnottex sin (z) = ++ 1/(2*i) * (exp (z*i) - exp (-z*i)). @end ifnottex @tex $$\sin(z) ++ = {1\over 2i} (e^{zi} - e^{-zi})$$ @end tex ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the complex cosine of z. The mathematical ++ definition of the complex cosine is <br> @ifnottex cos (z) ++ = 1/2 * (exp (z*i) + exp (-z*i)) @end ifnottex @tex $$\cos(z) = ++ {1\over 2} (e^{zi} + e^{-zi})$$ @end tex ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the complex cosine of z. The mathematical ++ definition of the complex cosine is <br> @ifnottex cos (z) ++ = 1/2 * (exp (z*i) + exp (-z*i)) @end ifnottex @tex $$\cos(z) = ++ {1\over 2} (e^{zi} + e^{-zi})$$ @end tex ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the complex cosine of z. The mathematical ++ definition of the complex cosine is <br> @ifnottex cos (z) ++ = 1/2 * (exp (z*i) + exp (-z*i)) @end ifnottex @tex $$\cos(z) = ++ {1\over 2} (e^{zi} + e^{-zi})$$ @end tex ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the complex tangent of z. The ++ mathematical definition of the complex tangent is <br> ++ @ifnottex tan (z) = -i * (exp (z*i) - exp (-z*i)) / (exp (z*i) + ++ exp (-z*i)) @end ifnottex @tex $$\tan(z) = -i \cdot {e^{zi} - ++ e^{-zi}\over e^{zi} + e^{-zi}}$$ @end tex <br> @noindent ++ The complex tangent has poles at pi/2 + 2n, where n is an ++ integer. ctan may signal overflow if z is too close to a pole. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the complex tangent of z. The ++ mathematical definition of the complex tangent is <br> ++ @ifnottex tan (z) = -i * (exp (z*i) - exp (-z*i)) / (exp (z*i) + ++ exp (-z*i)) @end ifnottex @tex $$\tan(z) = -i \cdot {e^{zi} - ++ e^{-zi}\over e^{zi} + e^{-zi}}$$ @end tex <br> @noindent ++ The complex tangent has poles at pi/2 + 2n, where n is an ++ integer. ctan may signal overflow if z is too close to a pole. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the complex tangent of z. The ++ mathematical definition of the complex tangent is <br> ++ @ifnottex tan (z) = -i * (exp (z*i) - exp (-z*i)) / (exp (z*i) + ++ exp (-z*i)) @end ifnottex @tex $$\tan(z) = -i \cdot {e^{zi} - ++ e^{-zi}\over e^{zi} + e^{-zi}}$$ @end tex <br> @noindent ++ The complex tangent has poles at pi/2 + 2n, where n is an ++ integer. ctan may signal overflow if z is too close to a pole. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions compute the arc sine of x---that is, the value ++ whose sine is x. The value is in units of radians. ++ Mathematically, there are infinitely many such values; the one ++ actually returned is the one between -pi/2 and pi/2 (inclusive). ++ <br> The arc sine function is defined mathematically only ++ over the domain -1 to 1. If x is outside the domain, asin ++ signals a domain error. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions compute the arc sine of x---that is, the value ++ whose sine is x. The value is in units of radians. ++ Mathematically, there are infinitely many such values; the one ++ actually returned is the one between -pi/2 and pi/2 (inclusive). ++ <br> The arc sine function is defined mathematically only ++ over the domain -1 to 1. If x is outside the domain, asin ++ signals a domain error. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions compute the arc sine of x---that is, the value ++ whose sine is x. The value is in units of radians. ++ Mathematically, there are infinitely many such values; the one ++ actually returned is the one between -pi/2 and pi/2 (inclusive). ++ <br> The arc sine function is defined mathematically only ++ over the domain -1 to 1. If x is outside the domain, asin ++ signals a domain error. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions compute the arc cosine of x---that is, the value ++ whose cosine is x. The value is in units of radians. ++ Mathematically, there are infinitely many such values; the one ++ actually returned is the one between 0 and pi (inclusive). ++ <br> The arc cosine function is defined mathematically ++ only over the domain -1 to 1. If x is outside the domain, acos ++ signals a domain error. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions compute the arc cosine of x---that is, the value ++ whose cosine is x. The value is in units of radians. ++ Mathematically, there are infinitely many such values; the one ++ actually returned is the one between 0 and pi (inclusive). ++ <br> The arc cosine function is defined mathematically ++ only over the domain -1 to 1. If x is outside the domain, acos ++ signals a domain error. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions compute the arc cosine of x---that is, the value ++ whose cosine is x. The value is in units of radians. ++ Mathematically, there are infinitely many such values; the one ++ actually returned is the one between 0 and pi (inclusive). ++ <br> The arc cosine function is defined mathematically ++ only over the domain -1 to 1. If x is outside the domain, acos ++ signals a domain error. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions compute the arc tangent of x---that is, the ++ value whose tangent is x. The value is in units of radians. ++ Mathematically, there are infinitely many such values; the one ++ actually returned is the one between -pi/2 and pi/2 (inclusive). ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions compute the arc tangent of x---that is, the ++ value whose tangent is x. The value is in units of radians. ++ Mathematically, there are infinitely many such values; the one ++ actually returned is the one between -pi/2 and pi/2 (inclusive). ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions compute the arc tangent of x---that is, the ++ value whose tangent is x. The value is in units of radians. ++ Mathematically, there are infinitely many such values; the one ++ actually returned is the one between -pi/2 and pi/2 (inclusive). ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function computes the arc tangent of y/x, but the signs of ++ both arguments are used to determine the quadrant of the result, ++ and x is permitted to be zero. The return value is given in ++ radians and is in the range -pi to pi, inclusive. <br> If ++ x and y are coordinates of a point in the plane, atan2 returns ++ the signed angle between the line from the origin to that point ++ and the x-axis. Thus, atan2 is useful for converting Cartesian ++ coordinates to polar coordinates. (To compute the radial ++ coordinate, use hypot; see Exponents and Logarithms.) <br> ++ @c This is experimentally true. Should it be so? -zw If both x ++ and y are zero, atan2 returns zero. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function computes the arc tangent of y/x, but the signs of ++ both arguments are used to determine the quadrant of the result, ++ and x is permitted to be zero. The return value is given in ++ radians and is in the range -pi to pi, inclusive. <br> If ++ x and y are coordinates of a point in the plane, atan2 returns ++ the signed angle between the line from the origin to that point ++ and the x-axis. Thus, atan2 is useful for converting Cartesian ++ coordinates to polar coordinates. (To compute the radial ++ coordinate, use hypot; see Exponents and Logarithms.) <br> ++ @c This is experimentally true. Should it be so? -zw If both x ++ and y are zero, atan2 returns zero. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function computes the arc tangent of y/x, but the signs of ++ both arguments are used to determine the quadrant of the result, ++ and x is permitted to be zero. The return value is given in ++ radians and is in the range -pi to pi, inclusive. <br> If ++ x and y are coordinates of a point in the plane, atan2 returns ++ the signed angle between the line from the origin to that point ++ and the x-axis. Thus, atan2 is useful for converting Cartesian ++ coordinates to polar coordinates. (To compute the radial ++ coordinate, use hypot; see Exponents and Logarithms.) <br> ++ @c This is experimentally true. Should it be so? -zw If both x ++ and y are zero, atan2 returns zero. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions compute the complex arc sine of z---that is, the ++ value whose sine is z. The value returned is in radians. ++ <br> Unlike the real-valued functions, casin is defined ++ for all values of z. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions compute the complex arc sine of z---that is, the ++ value whose sine is z. The value returned is in radians. ++ <br> Unlike the real-valued functions, casin is defined ++ for all values of z. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions compute the complex arc sine of z---that is, the ++ value whose sine is z. The value returned is in radians. ++ <br> Unlike the real-valued functions, casin is defined ++ for all values of z. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions compute the complex arc cosine of z---that is, ++ the value whose cosine is z. The value returned is in radians. ++ <br> Unlike the real-valued functions, cacos is defined ++ for all values of z. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions compute the complex arc cosine of z---that is, ++ the value whose cosine is z. The value returned is in radians. ++ <br> Unlike the real-valued functions, cacos is defined ++ for all values of z. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions compute the complex arc cosine of z---that is, ++ the value whose cosine is z. The value returned is in radians. ++ <br> Unlike the real-valued functions, cacos is defined ++ for all values of z. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions compute the complex arc tangent of z---that is, ++ the value whose tangent is z. The value is in units of radians. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions compute the complex arc tangent of z---that is, ++ the value whose tangent is z. The value is in units of radians. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions compute the complex arc tangent of z---that is, ++ the value whose tangent is z. The value is in units of radians. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions compute e (the base of natural logarithms) ++ raised to the power x. <br> If the magnitude of the result ++ is too large to be representable, exp signals overflow. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions compute e (the base of natural logarithms) ++ raised to the power x. <br> If the magnitude of the result ++ is too large to be representable, exp signals overflow. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions compute e (the base of natural logarithms) ++ raised to the power x. <br> If the magnitude of the result ++ is too large to be representable, exp signals overflow. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions compute 2 raised to the power x. Mathematically, ++ exp2 (x) is the same as exp (x * log (2)). ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions compute 2 raised to the power x. Mathematically, ++ exp2 (x) is the same as exp (x * log (2)). ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions compute 2 raised to the power x. Mathematically, ++ exp2 (x) is the same as exp (x * log (2)). ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions compute 10 raised to the power x. ++ Mathematically, exp10 (x) is the same as exp (x * log (10)). ++ <br> These functions are GNU extensions. The name exp10 ++ is preferred, since it is analogous to exp and exp2. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions compute 10 raised to the power x. ++ Mathematically, exp10 (x) is the same as exp (x * log (10)). ++ <br> These functions are GNU extensions. The name exp10 ++ is preferred, since it is analogous to exp and exp2. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions compute 10 raised to the power x. ++ Mathematically, exp10 (x) is the same as exp (x * log (10)). ++ <br> These functions are GNU extensions. The name exp10 ++ is preferred, since it is analogous to exp and exp2. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions compute 10 raised to the power x. ++ Mathematically, exp10 (x) is the same as exp (x * log (10)). ++ <br> These functions are GNU extensions. The name exp10 ++ is preferred, since it is analogous to exp and exp2. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions compute 10 raised to the power x. ++ Mathematically, exp10 (x) is the same as exp (x * log (10)). ++ <br> These functions are GNU extensions. The name exp10 ++ is preferred, since it is analogous to exp and exp2. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions compute 10 raised to the power x. ++ Mathematically, exp10 (x) is the same as exp (x * log (10)). ++ <br> These functions are GNU extensions. The name exp10 ++ is preferred, since it is analogous to exp and exp2. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions compute the natural logarithm of x. exp (log ++ (x)) equals x, exactly in mathematics and approximately in C. ++ <br> If x is negative, log signals a domain error. If x ++ is zero, it returns negative infinity; if x is too close to ++ zero, it may signal overflow. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions compute the natural logarithm of x. exp (log ++ (x)) equals x, exactly in mathematics and approximately in C. ++ <br> If x is negative, log signals a domain error. If x ++ is zero, it returns negative infinity; if x is too close to ++ zero, it may signal overflow. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions compute the natural logarithm of x. exp (log ++ (x)) equals x, exactly in mathematics and approximately in C. ++ <br> If x is negative, log signals a domain error. If x ++ is zero, it returns negative infinity; if x is too close to ++ zero, it may signal overflow. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the base-10 logarithm of x. log10 (x) ++ equals log (x) / log (10). <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the base-10 logarithm of x. log10 (x) ++ equals log (x) / log (10). <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the base-10 logarithm of x. log10 (x) ++ equals log (x) / log (10). <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the base-2 logarithm of x. log2 (x) ++ equals log (x) / log (2). ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the base-2 logarithm of x. log2 (x) ++ equals log (x) / log (2). ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the base-2 logarithm of x. log2 (x) ++ equals log (x) / log (2). ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions extract the exponent of x and return it as a ++ floating-point value. If FLT_RADIX is two, logb is equal to ++ floor (log2 (x)), except it's probably faster. <br> If x ++ is de-normalized, logb returns the exponent x would have if it ++ were normalized. If x is infinity (positive or negative), logb ++ returns . If x is zero, logb returns . It does not signal. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions extract the exponent of x and return it as a ++ floating-point value. If FLT_RADIX is two, logb is equal to ++ floor (log2 (x)), except it's probably faster. <br> If x ++ is de-normalized, logb returns the exponent x would have if it ++ were normalized. If x is infinity (positive or negative), logb ++ returns . If x is zero, logb returns . It does not signal. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions extract the exponent of x and return it as a ++ floating-point value. If FLT_RADIX is two, logb is equal to ++ floor (log2 (x)), except it's probably faster. <br> If x ++ is de-normalized, logb returns the exponent x would have if it ++ were normalized. If x is infinity (positive or negative), logb ++ returns . If x is zero, logb returns . It does not signal. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions are equivalent to the corresponding logb ++ functions except that they return signed integer values. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions are equivalent to the corresponding logb ++ functions except that they return signed integer values. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions are equivalent to the corresponding logb ++ functions except that they return signed integer values. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These are general exponentiation functions, returning base ++ raised to power. <br> Mathematically, pow would return a ++ complex number when base is negative and power is not an ++ integral value. pow can't do that, so instead it signals a ++ domain error. pow may also underflow or overflow the destination ++ type. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These are general exponentiation functions, returning base ++ raised to power. <br> Mathematically, pow would return a ++ complex number when base is negative and power is not an ++ integral value. pow can't do that, so instead it signals a ++ domain error. pow may also underflow or overflow the destination ++ type. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These are general exponentiation functions, returning base ++ raised to power. <br> Mathematically, pow would return a ++ complex number when base is negative and power is not an ++ integral value. pow can't do that, so instead it signals a ++ domain error. pow may also underflow or overflow the destination ++ type. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the nonnegative square root of x. ++ <br> If x is negative, sqrt signals a domain error. ++ Mathematically, it should return a complex number. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the nonnegative square root of x. ++ <br> If x is negative, sqrt signals a domain error. ++ Mathematically, it should return a complex number. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the nonnegative square root of x. ++ <br> If x is negative, sqrt signals a domain error. ++ Mathematically, it should return a complex number. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the cube root of x. They cannot fail; ++ every representable real value has a representable real cube ++ root. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the cube root of x. They cannot fail; ++ every representable real value has a representable real cube ++ root. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the cube root of x. They cannot fail; ++ every representable real value has a representable real cube ++ root. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return sqrt (x*x + y*y). This is the length of ++ the hypotenuse of a right triangle with sides of length x and y, ++ or the distance of the point (x, y) from the origin. Using this ++ function instead of the direct formula is wise, since the error ++ is much smaller. See also the function cabs in Absolute Value. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return sqrt (x*x + y*y). This is the length of ++ the hypotenuse of a right triangle with sides of length x and y, ++ or the distance of the point (x, y) from the origin. Using this ++ function instead of the direct formula is wise, since the error ++ is much smaller. See also the function cabs in Absolute Value. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return sqrt (x*x + y*y). This is the length of ++ the hypotenuse of a right triangle with sides of length x and y, ++ or the distance of the point (x, y) from the origin. Using this ++ function instead of the direct formula is wise, since the error ++ is much smaller. See also the function cabs in Absolute Value. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return a value equivalent to exp (x) - 1. They ++ are computed in a way that is accurate even if x is near ++ zero---a case where exp (x) - 1 would be inaccurate owing to ++ subtraction of two numbers that are nearly equal. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return a value equivalent to exp (x) - 1. They ++ are computed in a way that is accurate even if x is near ++ zero---a case where exp (x) - 1 would be inaccurate owing to ++ subtraction of two numbers that are nearly equal. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return a value equivalent to exp (x) - 1. They ++ are computed in a way that is accurate even if x is near ++ zero---a case where exp (x) - 1 would be inaccurate owing to ++ subtraction of two numbers that are nearly equal. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions returns a value equivalent to log (1 + x). They ++ are computed in a way that is accurate even if x is near zero. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions returns a value equivalent to log (1 + x). They ++ are computed in a way that is accurate even if x is near zero. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions returns a value equivalent to log (1 + x). They ++ are computed in a way that is accurate even if x is near zero. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return e (the base of natural logarithms) raised ++ to the power of z. Mathematically, this corresponds to the value ++ <br> @ifnottex exp (z) = exp (creal (z)) * (cos (cimag ++ (z)) + I * sin (cimag (z))) @end ifnottex @tex $$\exp(z) = e^z = ++ e^{{\rm Re}\,z} (\cos ({\rm Im}\,z) + i \sin ({\rm Im}\,z))$$ ++ @end tex ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return e (the base of natural logarithms) raised ++ to the power of z. Mathematically, this corresponds to the value ++ <br> @ifnottex exp (z) = exp (creal (z)) * (cos (cimag ++ (z)) + I * sin (cimag (z))) @end ifnottex @tex $$\exp(z) = e^z = ++ e^{{\rm Re}\,z} (\cos ({\rm Im}\,z) + i \sin ({\rm Im}\,z))$$ ++ @end tex ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return e (the base of natural logarithms) raised ++ to the power of z. Mathematically, this corresponds to the value ++ <br> @ifnottex exp (z) = exp (creal (z)) * (cos (cimag ++ (z)) + I * sin (cimag (z))) @end ifnottex @tex $$\exp(z) = e^z = ++ e^{{\rm Re}\,z} (\cos ({\rm Im}\,z) + i \sin ({\rm Im}\,z))$$ ++ @end tex ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the natural logarithm of z. ++ Mathematically, this corresponds to the value <br> ++ @ifnottex log (z) = log (cabs (z)) + I * carg (z) @end ifnottex ++ @tex $$\log(z) = \log |z| + i \arg z$$ @end tex <br> ++ @noindent clog has a pole at 0, and will signal overflow if z ++ equals or is very close to 0. It is well-defined for all other ++ values of z. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the natural logarithm of z. ++ Mathematically, this corresponds to the value <br> ++ @ifnottex log (z) = log (cabs (z)) + I * carg (z) @end ifnottex ++ @tex $$\log(z) = \log |z| + i \arg z$$ @end tex <br> ++ @noindent clog has a pole at 0, and will signal overflow if z ++ equals or is very close to 0. It is well-defined for all other ++ values of z. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the natural logarithm of z. ++ Mathematically, this corresponds to the value <br> ++ @ifnottex log (z) = log (cabs (z)) + I * carg (z) @end ifnottex ++ @tex $$\log(z) = \log |z| + i \arg z$$ @end tex <br> ++ @noindent clog has a pole at 0, and will signal overflow if z ++ equals or is very close to 0. It is well-defined for all other ++ values of z. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the base 10 logarithm of the complex ++ value z. Mathematically, this corresponds to the value ++ <br> @ifnottex log (z) = log10 (cabs (z)) + I * carg (z) ++ @end ifnottex @tex $$\log_{10}(z) = \log_{10}|z| + i \arg z$$ ++ @end tex <br> These functions are GNU extensions. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the base 10 logarithm of the complex ++ value z. Mathematically, this corresponds to the value ++ <br> @ifnottex log (z) = log10 (cabs (z)) + I * carg (z) ++ @end ifnottex @tex $$\log_{10}(z) = \log_{10}|z| + i \arg z$$ ++ @end tex <br> These functions are GNU extensions. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the base 10 logarithm of the complex ++ value z. Mathematically, this corresponds to the value ++ <br> @ifnottex log (z) = log10 (cabs (z)) + I * carg (z) ++ @end ifnottex @tex $$\log_{10}(z) = \log_{10}|z| + i \arg z$$ ++ @end tex <br> These functions are GNU extensions. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the complex square root of the argument ++ z. Unlike the real-valued functions, they are defined for all ++ values of z. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the complex square root of the argument ++ z. Unlike the real-valued functions, they are defined for all ++ values of z. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the complex square root of the argument ++ z. Unlike the real-valued functions, they are defined for all ++ values of z. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return base raised to the power of power. This ++ is equivalent to cexp (y * clog (x)) ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return base raised to the power of power. This ++ is equivalent to cexp (y * clog (x)) ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return base raised to the power of power. This ++ is equivalent to cexp (y * clog (x)) ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the hyperbolic sine of x, defined ++ mathematically as (exp (x) - exp (-x)) / 2. They may signal ++ overflow if x is too large. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the hyperbolic sine of x, defined ++ mathematically as (exp (x) - exp (-x)) / 2. They may signal ++ overflow if x is too large. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the hyperbolic sine of x, defined ++ mathematically as (exp (x) - exp (-x)) / 2. They may signal ++ overflow if x is too large. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These function return the hyperbolic cosine of x, defined ++ mathematically as (exp (x) + exp (-x)) / 2. They may signal ++ overflow if x is too large. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These function return the hyperbolic cosine of x, defined ++ mathematically as (exp (x) + exp (-x)) / 2. They may signal ++ overflow if x is too large. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These function return the hyperbolic cosine of x, defined ++ mathematically as (exp (x) + exp (-x)) / 2. They may signal ++ overflow if x is too large. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the hyperbolic tangent of x, defined ++ mathematically as sinh (x) / cosh (x). They may signal overflow ++ if x is too large. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the hyperbolic tangent of x, defined ++ mathematically as sinh (x) / cosh (x). They may signal overflow ++ if x is too large. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the hyperbolic tangent of x, defined ++ mathematically as sinh (x) / cosh (x). They may signal overflow ++ if x is too large. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the complex hyperbolic sine of z, defined ++ mathematically as (exp (z) - exp (-z)) / 2. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the complex hyperbolic sine of z, defined ++ mathematically as (exp (z) - exp (-z)) / 2. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the complex hyperbolic sine of z, defined ++ mathematically as (exp (z) - exp (-z)) / 2. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the complex hyperbolic cosine of z, ++ defined mathematically as (exp (z) + exp (-z)) / 2. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the complex hyperbolic cosine of z, ++ defined mathematically as (exp (z) + exp (-z)) / 2. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the complex hyperbolic cosine of z, ++ defined mathematically as (exp (z) + exp (-z)) / 2. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the complex hyperbolic tangent of z, ++ defined mathematically as csinh (z) / ccosh (z). ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the complex hyperbolic tangent of z, ++ defined mathematically as csinh (z) / ccosh (z). ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the complex hyperbolic tangent of z, ++ defined mathematically as csinh (z) / ccosh (z). ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the inverse hyperbolic sine of x---the ++ value whose hyperbolic sine is x. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the inverse hyperbolic sine of x---the ++ value whose hyperbolic sine is x. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the inverse hyperbolic sine of x---the ++ value whose hyperbolic sine is x. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the inverse hyperbolic cosine of x---the ++ value whose hyperbolic cosine is x. If x is less than 1, acosh ++ signals a domain error. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the inverse hyperbolic cosine of x---the ++ value whose hyperbolic cosine is x. If x is less than 1, acosh ++ signals a domain error. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the inverse hyperbolic cosine of x---the ++ value whose hyperbolic cosine is x. If x is less than 1, acosh ++ signals a domain error. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the inverse hyperbolic tangent of x---the ++ value whose hyperbolic tangent is x. If the absolute value of x ++ is greater than 1, atanh signals a domain error; if it is equal ++ to 1, atanh returns infinity. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the inverse hyperbolic tangent of x---the ++ value whose hyperbolic tangent is x. If the absolute value of x ++ is greater than 1, atanh signals a domain error; if it is equal ++ to 1, atanh returns infinity. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the inverse hyperbolic tangent of x---the ++ value whose hyperbolic tangent is x. If the absolute value of x ++ is greater than 1, atanh signals a domain error; if it is equal ++ to 1, atanh returns infinity. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the inverse complex hyperbolic sine of ++ z---the value whose complex hyperbolic sine is z. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the inverse complex hyperbolic sine of ++ z---the value whose complex hyperbolic sine is z. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the inverse complex hyperbolic sine of ++ z---the value whose complex hyperbolic sine is z. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the inverse complex hyperbolic cosine of ++ z---the value whose complex hyperbolic cosine is z. Unlike the ++ real-valued functions, there are no restrictions on the value of ++ z. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the inverse complex hyperbolic cosine of ++ z---the value whose complex hyperbolic cosine is z. Unlike the ++ real-valued functions, there are no restrictions on the value of ++ z. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the inverse complex hyperbolic cosine of ++ z---the value whose complex hyperbolic cosine is z. Unlike the ++ real-valued functions, there are no restrictions on the value of ++ z. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the inverse complex hyperbolic tangent of ++ z---the value whose complex hyperbolic tangent is z. Unlike the ++ real-valued functions, there are no restrictions on the value of ++ z. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the inverse complex hyperbolic tangent of ++ z---the value whose complex hyperbolic tangent is z. Unlike the ++ real-valued functions, there are no restrictions on the value of ++ z. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions return the inverse complex hyperbolic tangent of ++ z---the value whose complex hyperbolic tangent is z. Unlike the ++ real-valued functions, there are no restrictions on the value of ++ z. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ erf returns the error function of x. The error function is ++ defined as @tex $$\hbox{erf}(x) = ++ {2\over\sqrt{\pi}}\cdot\int_0^x e^{-t^2} \hbox{d}t$$ @end tex ++ @ifnottex @smallexample erf (x) = 2/sqrt(pi) * integral from 0 ++ to x of exp(-t^2) dt @end smallexample @end ifnottex ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ erf returns the error function of x. The error function is ++ defined as @tex $$\hbox{erf}(x) = ++ {2\over\sqrt{\pi}}\cdot\int_0^x e^{-t^2} \hbox{d}t$$ @end tex ++ @ifnottex @smallexample erf (x) = 2/sqrt(pi) * integral from 0 ++ to x of exp(-t^2) dt @end smallexample @end ifnottex ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ erf returns the error function of x. The error function is ++ defined as @tex $$\hbox{erf}(x) = ++ {2\over\sqrt{\pi}}\cdot\int_0^x e^{-t^2} \hbox{d}t$$ @end tex ++ @ifnottex @smallexample erf (x) = 2/sqrt(pi) * integral from 0 ++ to x of exp(-t^2) dt @end smallexample @end ifnottex ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ erfc returns 1.0 - erf(x), but computed in a fashion that avoids ++ round-off error when x is large. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ erfc returns 1.0 - erf(x), but computed in a fashion that avoids ++ round-off error when x is large. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ erfc returns 1.0 - erf(x), but computed in a fashion that avoids ++ round-off error when x is large. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ lgamma returns the natural logarithm of the absolute value of ++ the gamma function of x. The gamma function is defined as @tex ++ $$\Gamma(x) = \int_0^\infty t^{x-1} e^{-t} \hbox{d}t$$ @end tex ++ @ifnottex @smallexample gamma (x) = integral from 0 to of ++ t^(x-1) e^-t dt @end smallexample @end ifnottex <br> ++ @vindex signgam The sign of the gamma function is stored in the ++ global variable signgam, which is declared in math.h. It is 1 ++ if the intermediate result was positive or zero, or -1 if it was ++ negative. <br> To compute the real gamma function you can ++ use the tgamma function or you can compute the values as ++ follows: @smallexample lgam = lgamma(x); gam = ++ signgam*exp(lgam); @end smallexample <br> The gamma ++ function has singularities at the non-positive integers. lgamma ++ will raise the zero divide exception if evaluated at a ++ singularity. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ lgamma returns the natural logarithm of the absolute value of ++ the gamma function of x. The gamma function is defined as @tex ++ $$\Gamma(x) = \int_0^\infty t^{x-1} e^{-t} \hbox{d}t$$ @end tex ++ @ifnottex @smallexample gamma (x) = integral from 0 to of ++ t^(x-1) e^-t dt @end smallexample @end ifnottex <br> ++ @vindex signgam The sign of the gamma function is stored in the ++ global variable signgam, which is declared in math.h. It is 1 ++ if the intermediate result was positive or zero, or -1 if it was ++ negative. <br> To compute the real gamma function you can ++ use the tgamma function or you can compute the values as ++ follows: @smallexample lgam = lgamma(x); gam = ++ signgam*exp(lgam); @end smallexample <br> The gamma ++ function has singularities at the non-positive integers. lgamma ++ will raise the zero divide exception if evaluated at a ++ singularity. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ lgamma returns the natural logarithm of the absolute value of ++ the gamma function of x. The gamma function is defined as @tex ++ $$\Gamma(x) = \int_0^\infty t^{x-1} e^{-t} \hbox{d}t$$ @end tex ++ @ifnottex @smallexample gamma (x) = integral from 0 to of ++ t^(x-1) e^-t dt @end smallexample @end ifnottex <br> ++ @vindex signgam The sign of the gamma function is stored in the ++ global variable signgam, which is declared in math.h. It is 1 ++ if the intermediate result was positive or zero, or -1 if it was ++ negative. <br> To compute the real gamma function you can ++ use the tgamma function or you can compute the values as ++ follows: @smallexample lgam = lgamma(x); gam = ++ signgam*exp(lgam); @end smallexample <br> The gamma ++ function has singularities at the non-positive integers. lgamma ++ will raise the zero divide exception if evaluated at a ++ singularity. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ lgamma_r is just like lgamma, but it stores the sign of the ++ intermediate result in the variable pointed to by signp instead ++ of in the signgam global. This means it is reentrant. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ lgamma_r is just like lgamma, but it stores the sign of the ++ intermediate result in the variable pointed to by signp instead ++ of in the signgam global. This means it is reentrant. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ lgamma_r is just like lgamma, but it stores the sign of the ++ intermediate result in the variable pointed to by signp instead ++ of in the signgam global. This means it is reentrant. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions exist for compatibility reasons. They are ++ equivalent to lgamma etc. It is better to use lgamma since for ++ one the name reflects better the actual computation, moreover ++ lgamma is standardized in ISO C99 while gamma is not. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions exist for compatibility reasons. They are ++ equivalent to lgamma etc. It is better to use lgamma since for ++ one the name reflects better the actual computation, moreover ++ lgamma is standardized in ISO C99 while gamma is not. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ These functions exist for compatibility reasons. They are ++ equivalent to lgamma etc. It is better to use lgamma since for ++ one the name reflects better the actual computation, moreover ++ lgamma is standardized in ISO C99 while gamma is not. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ tgamma applies the gamma function to x. The gamma function is ++ defined as @tex $$\Gamma(x) = \int_0^\infty t^{x-1} e^{-t} ++ \hbox{d}t$$ @end tex @ifnottex @smallexample gamma (x) = ++ integral from 0 to of t^(x-1) e^-t dt @end smallexample @end ++ ifnottex <br> This function was introduced in ISO C99. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ tgamma applies the gamma function to x. The gamma function is ++ defined as @tex $$\Gamma(x) = \int_0^\infty t^{x-1} e^{-t} ++ \hbox{d}t$$ @end tex @ifnottex @smallexample gamma (x) = ++ integral from 0 to of t^(x-1) e^-t dt @end smallexample @end ++ ifnottex <br> This function was introduced in ISO C99. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ tgamma applies the gamma function to x. The gamma function is ++ defined as @tex $$\Gamma(x) = \int_0^\infty t^{x-1} e^{-t} ++ \hbox{d}t$$ @end tex @ifnottex @smallexample gamma (x) = ++ integral from 0 to of t^(x-1) e^-t dt @end smallexample @end ++ ifnottex <br> This function was introduced in ISO C99. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ j0 returns the Bessel function of the first kind of order 0 of ++ x. It may signal underflow if x is too large. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ j0 returns the Bessel function of the first kind of order 0 of ++ x. It may signal underflow if x is too large. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ j0 returns the Bessel function of the first kind of order 0 of ++ x. It may signal underflow if x is too large. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ j1 returns the Bessel function of the first kind of order 1 of ++ x. It may signal underflow if x is too large. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ j1 returns the Bessel function of the first kind of order 1 of ++ x. It may signal underflow if x is too large. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ j1 returns the Bessel function of the first kind of order 1 of ++ x. It may signal underflow if x is too large. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ jn returns the Bessel function of the first kind of order n of ++ x. It may signal underflow if x is too large. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ jn returns the Bessel function of the first kind of order n of ++ x. It may signal underflow if x is too large. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ jn returns the Bessel function of the first kind of order n of ++ x. It may signal underflow if x is too large. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ y0 returns the Bessel function of the second kind of order 0 of ++ x. It may signal underflow if x is too large. If x is ++ negative, y0 signals a domain error; if it is zero, y0 signals ++ overflow and returns -@infinity. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ y0 returns the Bessel function of the second kind of order 0 of ++ x. It may signal underflow if x is too large. If x is ++ negative, y0 signals a domain error; if it is zero, y0 signals ++ overflow and returns -@infinity. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ y0 returns the Bessel function of the second kind of order 0 of ++ x. It may signal underflow if x is too large. If x is ++ negative, y0 signals a domain error; if it is zero, y0 signals ++ overflow and returns -@infinity. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ y1 returns the Bessel function of the second kind of order 1 of ++ x. It may signal underflow if x is too large. If x is ++ negative, y1 signals a domain error; if it is zero, y1 signals ++ overflow and returns -@infinity. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ y1 returns the Bessel function of the second kind of order 1 of ++ x. It may signal underflow if x is too large. If x is ++ negative, y1 signals a domain error; if it is zero, y1 signals ++ overflow and returns -@infinity. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ y1 returns the Bessel function of the second kind of order 1 of ++ x. It may signal underflow if x is too large. If x is ++ negative, y1 signals a domain error; if it is zero, y1 signals ++ overflow and returns -@infinity. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ yn returns the Bessel function of the second kind of order n of ++ x. It may signal underflow if x is too large. If x is ++ negative, yn signals a domain error; if it is zero, yn signals ++ overflow and returns -@infinity. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ yn returns the Bessel function of the second kind of order n of ++ x. It may signal underflow if x is too large. If x is ++ negative, yn signals a domain error; if it is zero, yn signals ++ overflow and returns -@infinity. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ yn returns the Bessel function of the second kind of order n of ++ x. It may signal underflow if x is too large. If x is ++ negative, yn signals a domain error; if it is zero, yn signals ++ overflow and returns -@infinity. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The rand function returns the next pseudo-random number in the ++ series. The value ranges from 0 to RAND_MAX. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function establishes seed as the seed for a new series of ++ pseudo-random numbers. If you call rand before a seed has been ++ established with srand, it uses the value 1 as a default seed. ++ <br> To produce a different pseudo-random series each time ++ your program is run, do srand (time (0)). ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function returns a random number in the range 0 to RAND_MAX ++ just as rand does. However, all its state is stored in the seed ++ argument. This means the RNG's state can only have as many bits ++ as the type unsigned int has. This is far too few to provide a ++ good RNG. <br> If your program requires a reentrant RNG, ++ we recommend you use the reentrant GNU extensions to the SVID ++ random number generator. The POSIX.1 interface should only be ++ used when the GNU extensions are not available. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function returns the next pseudo-random number in the ++ sequence. The value returned ranges from 0 to RAND_MAX. ++ <br> Note: Temporarily this function was defined to return ++ a int32_t value to indicate that the return value always ++ contains 32 bits even if long int is wider. The standard ++ demands it differently. Users must always be aware of the ++ 32-bit limitation, though. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The srandom function sets the state of the random number ++ generator based on the integer seed. If you supply a seed value ++ of 1, this will cause random to reproduce the default set of ++ random numbers. <br> To produce a different set of ++ pseudo-random numbers each time your program runs, do srandom ++ (time (0)). ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The initstate function is used to initialize the random number ++ generator state. The argument state is an array of size bytes, ++ used to hold the state information. It is initialized based on ++ seed. The size must be between 8 and 256 bytes, and should be a ++ power of two. The bigger the state array, the better. ++ <br> The return value is the previous value of the state ++ information array. You can use this value later as an argument ++ to setstate to restore that state. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The setstate function restores the random number state ++ information state. The argument must have been the result of a ++ previous call to initstate or setstate. <br> The return ++ value is the previous value of the state information array. You ++ can use this value later as an argument to setstate to restore ++ that state. <br> If the function fails the return value is ++ NULL. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The random_r function behaves exactly like the random function ++ except that it uses and modifies the state in the object pointed ++ to by the first parameter instead of the global state. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The srandom_r function behaves exactly like the srandom function ++ except that it uses and modifies the state in the object pointed ++ to by the second parameter instead of the global state. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The initstate_r function behaves exactly like the initstate ++ function except that it uses and modifies the state in the ++ object pointed to by the fourth parameter instead of the global ++ state. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The setstate_r function behaves exactly like the setstate ++ function except that it uses and modifies the state in the ++ object pointed to by the first parameter instead of the global ++ state. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function returns a double value in the range of 0.0 to 1.0 ++ (exclusive). The random bits are determined by the global state ++ of the random number generator in the C library. <br> ++ Since the double type according to IEEE 754 has a 52-bit ++ mantissa this means 4 bits are not initialized by the random ++ number generator. These are (of course) chosen to be the least ++ significant bits and they are initialized to 0. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function returns a double value in the range of 0.0 to 1.0 ++ (exclusive), similarly to drand48. The argument is an array ++ describing the state of the random number generator. <br> ++ This function can be called subsequently since it updates the ++ array to guarantee random numbers. The array should have been ++ initialized before initial use to obtain reproducible results. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The lrand48 function returns an integer value in the range of 0 ++ to 2^31 (exclusive). Even if the size of the long int type can ++ take more than 32 bits, no higher numbers are returned. The ++ random bits are determined by the global state of the random ++ number generator in the C library. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to the lrand48 function in that it ++ returns a number in the range of 0 to 2^31 (exclusive) but the ++ state of the random number generator used to produce the random ++ bits is determined by the array provided as the parameter to the ++ function. <br> The numbers in the array are updated ++ afterwards so that subsequent calls to this function yield ++ different results (as is expected of a random number generator). ++ The array should have been initialized before the first call to ++ obtain reproducible results. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The mrand48 function is similar to lrand48. The only difference ++ is that the numbers returned are in the range -2^31 to 2^31 ++ (exclusive). ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The jrand48 function is similar to nrand48. The only difference ++ is that the numbers returned are in the range -2^31 to 2^31 ++ (exclusive). For the xsubi parameter the same requirements are ++ necessary. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The srand48 function sets the most significant 32 bits of the ++ internal state of the random number generator to the least ++ significant 32 bits of the seedval parameter. The lower 16 bits ++ are initialized to the value 0x330E. Even if the long int type ++ contains more than 32 bits only the lower 32 bits are used. ++ <br> Owing to this limitation, initialization of the state ++ of this function is not very useful. But it makes it easy to ++ use a construct like srand48 (time (0)). <br> A ++ side-effect of this function is that the values a and c from the ++ internal state, which are used in the congruential formula, are ++ reset to the default values given above. This is of importance ++ once the user has called the lcong48 function (see below). ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The seed48 function initializes all 48 bits of the state of the ++ internal random number generator from the contents of the ++ parameter seed16v. Here the lower 16 bits of the first element ++ of see16v initialize the least significant 16 bits of the ++ internal state, the lower 16 bits of seed16v[1] initialize the ++ mid-order 16 bits of the state and the 16 lower bits of ++ seed16v[2] initialize the most significant 16 bits of the state. ++ <br> Unlike srand48 this function lets the user initialize ++ all 48 bits of the state. <br> The value returned by ++ seed48 is a pointer to an array containing the values of the ++ internal state before the change. This might be useful to ++ restart the random number generator at a certain state. ++ Otherwise the value can simply be ignored. <br> As for ++ srand48, the values a and c from the congruential formula are ++ reset to the default values. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The lcong48 function allows the user to change the complete ++ state of the random number generator. Unlike srand48 and ++ seed48, this function also changes the constants in the ++ congruential formula. <br> From the seven elements in the ++ array param the least significant 16 bits of the entries ++ param[0] to param[2] determine the initial state, the least ++ significant 16 bits of param[3] to param[5] determine the 48 bit ++ constant a and param[6] determines the 16-bit value c. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is equivalent to the drand48 function with the ++ difference that it does not modify the global random number ++ generator parameters but instead the parameters in the buffer ++ supplied through the pointer buffer. The random number is ++ returned in the variable pointed to by result. <br> The ++ return value of the function indicates whether the call ++ succeeded. If the value is less than 0 an error occurred and ++ errno is set to indicate the problem. <br> This function ++ is a GNU extension and should not be used in portable programs. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The erand48_r function works like erand48, but in addition it ++ takes an argument buffer which describes the random number ++ generator. The state of the random number generator is taken ++ from the xsubi array, the parameters for the congruential ++ formula from the global random number generator data. The ++ random number is returned in the variable pointed to by result. ++ <br> The return value is non-negative if the call ++ succeeded. <br> This function is a GNU extension and ++ should not be used in portable programs. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to lrand48, but in addition it takes a ++ pointer to a buffer describing the state of the random number ++ generator just like drand48. <br> If the return value of ++ the function is non-negative the variable pointed to by result ++ contains the result. Otherwise an error occurred. <br> ++ This function is a GNU extension and should not be used in ++ portable programs. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The nrand48_r function works like nrand48 in that it produces a ++ random number in the range 0 to 2^31. But instead of using the ++ global parameters for the congruential formula it uses the ++ information from the buffer pointed to by buffer. The state is ++ described by the values in xsubi. <br> If the return value ++ is non-negative the variable pointed to by result contains the ++ result. <br> This function is a GNU extension and should ++ not be used in portable programs. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to mrand48 but like the other reentrant ++ functions it uses the random number generator described by the ++ value in the buffer pointed to by buffer. <br> If the ++ return value is non-negative the variable pointed to by result ++ contains the result. <br> This function is a GNU extension ++ and should not be used in portable programs. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The jrand48_r function is similar to jrand48. Like the other ++ reentrant functions of this function family it uses the ++ congruential formula parameters from the buffer pointed to by ++ buffer. <br> If the return value is non-negative the ++ variable pointed to by result contains the result. <br> ++ This function is a GNU extension and should not be used in ++ portable programs. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The description of the random number generator represented by ++ the information in buffer is initialized similarly to what the ++ function srand48 does. The state is initialized from the ++ parameter seedval and the parameters for the congruential ++ formula are initialized to their default values. <br> If ++ the return value is non-negative the function call succeeded. ++ <br> This function is a GNU extension and should not be ++ used in portable programs. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to srand48_r but like seed48 it ++ initializes all 48 bits of the state from the parameter seed16v. ++ <br> If the return value is non-negative the function call ++ succeeded. It does not return a pointer to the previous state ++ of the random number generator like the seed48 function does. ++ If the user wants to preserve the state for a later re-run s/he ++ can copy the whole buffer pointed to by buffer. <br> This ++ function is a GNU extension and should not be used in portable ++ programs. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function initializes all aspects of the random number ++ generator described in buffer with the data in param. Here it ++ is especially true that the function does more than just copying ++ the contents of param and buffer. More work is required and ++ therefore it is important to use this function rather than ++ initializing the random number generator directly. <br> If ++ the return value is non-negative the function call succeeded. ++ <br> This function is a GNU extension and should not be ++ used in portable programs. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ This function returns a pointer to a newly allocated block size ++ bytes long, or a null pointer if the block could not be ++ allocated. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ The free function deallocates the block of memory pointed at by ++ ptr. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function does the same thing as free. It's provided for ++ backward compatibility with SunOS; you should use free instead. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ The realloc function changes the size of the block whose address ++ is ptr to be newsize. <br> Since the space after the end ++ of the block may be in use, realloc may find it necessary to ++ copy the block to a new address where more free space is ++ available. The value of realloc is the new address of the ++ block. If the block needs to be moved, realloc copies the old ++ contents. <br> If you pass a null pointer for ptr, realloc ++ behaves just like malloc (newsize). This can be convenient, but ++ beware that older implementations (before ISO C) may not support ++ this behavior, and will probably crash when realloc is passed a ++ null pointer. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ This function allocates a block long enough to contain a vector ++ of count elements, each of size eltsize. Its contents are ++ cleared to zero before calloc returns. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The memalign function allocates a block of size bytes whose ++ address is a multiple of boundary. The boundary must be a power ++ of two! The function memalign works by allocating a somewhat ++ larger block, and then returning an address within the block ++ that is on the specified boundary. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The posix_memalign function is similar to the memalign function ++ in that it returns a buffer of size bytes aligned to a multiple ++ of alignment. But it adds one requirement to the parameter ++ alignment: the value must be a power of two multiple of sizeof ++ (void *). <br> If the function succeeds in allocation ++ memory a pointer to the allocated memory is returned in *memptr ++ and the return value is zero. Otherwise the function returns an ++ error value indicating the problem. <br> This function was ++ introduced in POSIX 1003.1d. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ Using valloc is like using memalign and passing the page size as ++ the value of the second argument. It is implemented like this: ++ <br> @smallexample void * valloc (size_t size) return ++ memalign (getpagesize (), size); @ @end smallexample <br> ++ Query Memory Parameters for more information about the memory ++ subsystem. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ When calling mallopt, the param argument specifies the parameter ++ to be set, and value the new value to be set. Possible choices ++ for param, as defined in malloc.h, are: <br> @table @code ++ @item M_TRIM_THRESHOLD This is the minimum size (in bytes) of ++ the top-most, releasable chunk that will cause sbrk to be called ++ with a negative argument in order to return memory to the ++ system. @item M_TOP_PAD This parameter determines the amount of ++ extra memory to obtain from the system when a call to sbrk is ++ required. It also specifies the number of bytes to retain when ++ shrinking the heap by calling sbrk with a negative argument. ++ This provides the necessary hysteresis in heap size such that ++ excessive amounts of system calls can be avoided. @item ++ M_MMAP_THRESHOLD All chunks larger than this value are allocated ++ outside the normal heap, using the mmap system call. This way ++ it is guaranteed that the memory for these chunks can be ++ returned to the system on free. Note that requests smaller than ++ this threshold might still be allocated via mmap. @item ++ M_MMAP_MAX The maximum number of chunks to allocate with mmap. ++ Setting this to zero disables all use of mmap. @end table ++ <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ Calling mcheck tells malloc to perform occasional consistency ++ checks. These will catch things such as writing past the end of ++ a block that was allocated with malloc. <br> The abortfn ++ argument is the function to call when an inconsistency is found. ++ If you supply a null pointer, then mcheck uses a default ++ function which prints a message and calls abort (Aborting a ++ Program). The function you supply is called with one argument, ++ which says what sort of inconsistency was detected; its type is ++ described below. <br> It is too late to begin allocation ++ checking once you have allocated anything with malloc. So ++ mcheck does nothing in that case. The function returns -1 if ++ you call it too late, and 0 otherwise (when it is successful). ++ <br> The easiest way to arrange to call mcheck early ++ enough is to use the option -lmcheck when you link your program; ++ then you don't need to modify your program source at all. ++ Alternatively you might use a debugger to insert a call to ++ mcheck whenever the program is started, for example these gdb ++ commands will automatically call mcheck whenever the program ++ starts: <br> @smallexample (gdb) break main Breakpoint 1, ++ main (argc=2, argv=0xbffff964) at whatever.c:10 (gdb) command 1 ++ Type commands for when breakpoint 1 is hit, one per line. End ++ with a line saying just "end". >call mcheck(0) >continue ++ >end (gdb) @end smallexample <br> This will however ++ only work if no initialization function of any object involved ++ calls any of the malloc functions since mcheck must be called ++ before the first such function. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ The mprobe function lets you explicitly check for ++ inconsistencies in a particular allocated block. You must have ++ already called mcheck at the beginning of the program, to do its ++ occasional checks; calling mprobe requests an additional ++ consistency check to be done at the time of the call. <br> ++ The argument pointer must be a pointer returned by malloc or ++ realloc. mprobe returns a value that says what inconsistency, ++ if any, was found. The values are described below. ++ ++ ++ ++ ++ ++ ++ This enumerated type describes what kind of inconsistency was ++ detected in an allocated block, if any. Here are the possible ++ values: <br> ++ ++ ++ ++ ++ mcheck was not called before the first allocation. No ++ consistency checking can be done. ++ ++ ++ ++ ++ No inconsistency detected. ++ ++ ++ ++ ++ The data immediately before the block was modified. This ++ commonly happens when an array index or pointer is decremented ++ too far. ++ ++ ++ ++ ++ The data immediately after the block was modified. This commonly ++ happens when an array index or pointer is incremented too far. ++ ++ ++ ++ ++ ++ ++ ++ ++ This structure type is used to return information about the ++ dynamic memory allocator. It contains the following members: ++ <br> ++ ++ ++ ++ ++ This is the total size of memory allocated with sbrk by malloc, ++ in bytes. <br> ++ ++ ++ ++ ++ This is the number of chunks not in use. (The memory allocator ++ internally gets chunks of memory from the operating system, and ++ then carves them up to satisfy individual malloc requests; see ++ Efficiency and Malloc.) <br> ++ ++ ++ ++ ++ This field is unused. <br> ++ ++ ++ ++ ++ This is the total number of chunks allocated with mmap. ++ <br> ++ ++ ++ ++ ++ This is the total size of memory allocated with mmap, in bytes. ++ <br> ++ ++ ++ ++ ++ This field is unused. <br> ++ ++ ++ ++ ++ This field is unused. <br> ++ ++ ++ ++ ++ This is the total size of memory occupied by chunks handed out ++ by malloc. <br> ++ ++ ++ ++ ++ This is the total size of memory occupied by free (not in use) ++ chunks. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function returns information about the current dynamic ++ memory usage in a structure of type struct mallinfo. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ When the mtrace function is called it looks for an environment ++ variable named MALLOC_TRACE. This variable is supposed to ++ contain a valid file name. The user must have write access. If ++ the file already exists it is truncated. If the environment ++ variable is not set or it does not name a valid file which can ++ be opened for writing nothing is done. The behavior of malloc ++ etc. is not changed. For obvious reasons this also happens if ++ the application is installed with the SUID or SGID bit set. ++ <br> If the named file is successfully opened, mtrace ++ installs special handlers for the functions malloc, realloc, and ++ free (Hooks for Malloc). From then on, all uses of these ++ functions are traced and protocolled into the file. There is ++ now of course a speed penalty for all calls to the traced ++ functions so tracing should not be enabled during normal use. ++ <br> This function is a GNU extension and generally not ++ available on other systems. The prototype can be found in ++ mcheck.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The muntrace function can be called after mtrace was used to ++ enable tracing the malloc calls. If no (successful) call of ++ mtrace was made muntrace does nothing. <br> Otherwise it ++ deinstalls the handlers for malloc, realloc, and free and then ++ closes the protocol file. No calls are protocolled anymore and ++ the program runs again at full speed. <br> This function ++ is a GNU extension and generally not available on other systems. ++ The prototype can be found in mcheck.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ Initialize obstack obstack-ptr for allocation of objects. This ++ function calls the obstack's obstack_chunk_alloc function. If ++ allocation of memory fails, the function pointed to by ++ obstack_alloc_failed_handler is called. The obstack_init ++ function always returns 1 (Compatibility notice: Former versions ++ of obstack returned 0 if allocation failed). ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This allocates an uninitialized block of size bytes in an ++ obstack and returns its address. Here obstack-ptr specifies ++ which obstack to allocate the block in; it is the address of the ++ struct obstack object which represents the obstack. Each ++ obstack function or macro requires you to specify an obstack-ptr ++ as the first argument. <br> This function calls the ++ obstack's obstack_chunk_alloc function if it needs to allocate a ++ new chunk of memory; it calls obstack_alloc_failed_handler if ++ allocation of memory by obstack_chunk_alloc failed. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This allocates a block and initializes it by copying size bytes ++ of data starting at address. It calls ++ obstack_alloc_failed_handler if allocation of memory by ++ obstack_chunk_alloc failed. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ Like obstack_copy, but appends an extra byte containing a null ++ character. This extra byte is not counted in the argument size. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ If object is a null pointer, everything allocated in the obstack ++ is freed. Otherwise, object must be the address of an object ++ allocated in the obstack. Then object is freed, along with ++ everything allocated in obstack since object. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The most basic function for adding to a growing object is ++ obstack_blank, which adds space without initializing it. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ To add a block of initialized space, use obstack_grow, which is ++ the growing-object analogue of obstack_copy. It adds size bytes ++ of data to the growing object, copying the contents from data. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This is the growing-object analogue of obstack_copy0. It adds ++ size bytes copied from data, followed by an additional null ++ character. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ To add one character at a time, use the function obstack_1grow. ++ It adds a single byte containing c to the growing object. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ Adding the value of a pointer one can use the function ++ obstack_ptr_grow. It adds sizeof (void *) bytes containing the ++ value of data. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ A single value of type int can be added by using the ++ obstack_int_grow function. It adds sizeof (int) bytes to the ++ growing object and initializes them with the value of data. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ When you are finished growing the object, use the function ++ obstack_finish to close it off and return its final address. ++ <br> Once you have finished the object, the obstack is ++ available for ordinary allocation or for growing another object. ++ <br> This function can return a null pointer under the ++ same conditions as obstack_alloc (Allocation in an Obstack). ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function returns the current size of the growing object, in ++ bytes. Remember to call this function before finishing the ++ object. After it is finished, obstack_object_size will return ++ zero. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This returns the number of bytes that can be added safely to the ++ current growing object (or to an object about to be started) in ++ obstack obstack using the fast growth functions. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The function obstack_1grow_fast adds one byte containing the ++ character c to the growing object in obstack obstack-ptr. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The function obstack_ptr_grow_fast adds sizeof (void *) bytes ++ containing the value of data to the growing object in obstack ++ obstack-ptr. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The function obstack_int_grow_fast adds sizeof (int) bytes ++ containing the value of data to the growing object in obstack ++ obstack-ptr. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The function obstack_blank_fast adds size bytes to the growing ++ object in obstack obstack-ptr without initializing them. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function returns the tentative address of the beginning of ++ the currently growing object in obstack-ptr. If you finish the ++ object immediately, it will have that address. If you make it ++ larger first, it may outgrow the current chunk---then its ++ address will change! <br> If no object is growing, this ++ value says where the next object you allocate will start (once ++ again assuming it fits in the current chunk). ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function returns the address of the first free byte in the ++ current chunk of obstack obstack-ptr. This is the end of the ++ currently growing object. If no object is growing, ++ obstack_next_free returns the same value as obstack_base. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++
++ ++ ++ The return value of alloca is the address of a block of size ++ bytes of memory, allocated in the stack frame of the calling ++ function. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> brk sets the high end of the calling process' data ++ segment to addr. <br> The address of the end of a segment ++ is defined to be the address of the last byte in the segment ++ plus 1. <br> The function has no effect if addr is lower ++ than the low end of the data segment. (This is considered ++ success, by the way). <br> The function fails if it would ++ cause the data segment to overlap another segment or exceed the ++ process' data storage limit (Limits on Resources). <br> ++ The function is named for a common historical case where data ++ storage and the stack are in the same segment. Data storage ++ allocation grows upward from the bottom of the segment while the ++ stack grows downward toward it from the top of the segment and ++ the curtain between them is called the break. <br> The ++ return value is zero on success. On failure, the return value ++ is -1 and errno is set accordingly. The following errno values ++ are specific to this function: <br> @table @code @item ++ ENOMEM The request would cause the data segment to overlap ++ another segment or exceed the process' data storage limit. @end ++ table <br> @c The Brk system call in Linux (as opposed to ++ the GNU C Library function) @c is considerably different. It ++ always returns the new end of the data @c segment, whether it ++ succeeds or fails. The GNU C library Brk determines @c it's a ++ failure if and only if if the system call returns an address ++ less @c than the address requested. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is the same as brk except that you specify the new ++ end of the data segment as an offset delta from the current end ++ and on success the return value is the address of the resulting ++ end of the data segment instead of zero. <br> This means ++ you can use sbrk(0) to find out what the current end of the data ++ segment is. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> mlock locks a range of the calling process' virtual ++ pages. <br> The range of memory starts at address addr and ++ is len bytes long. Actually, since you must lock whole pages, ++ it is the range of pages that include any part of the specified ++ range. <br> When the function returns successfully, each ++ of those pages is backed by (connected to) a real frame (is ++ resident) and is marked to stay that way. This means the ++ function may cause page-ins and have to wait for them. ++ <br> When the function fails, it does not affect the lock ++ status of any pages. <br> The return value is zero if the ++ function succeeds. Otherwise, it is -1 and errno is set ++ accordingly. errno values specific to this function are: ++ <br> @table @code @item ENOMEM @itemize @bullet @item At ++ least some of the specified address range does not exist in the ++ calling process' virtual address space. @item The locking would ++ cause the process to exceed its locked page limit. @end itemize ++ <br> @item EPERM The calling process is not superuser. ++ <br> @item EINVAL len is not positive. <br> @item ++ ENOSYS The kernel does not provide mlock capability. <br> ++ @end table <br> You can lock all a process' memory with ++ mlockall. You unlock memory with munlock or munlockall. ++ <br> To avoid all page faults in a C program, you have to ++ use mlockall, because some of the memory a program uses is ++ hidden from the C code, e.g. the stack and automatic variables, ++ and you wouldn't know what address to tell mlock. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> mlock unlocks a range of the calling process' virtual ++ pages. <br> munlock is the inverse of mlock and functions ++ completely analogously to mlock, except that there is no EPERM ++ failure. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> mlockall locks all the pages in a process' virtual ++ memory address space, and/or any that are added to it in the ++ future. This includes the pages of the code, data and stack ++ segment, as well as shared libraries, user space kernel data, ++ shared memory, and memory mapped files. <br> flags is a ++ string of single bit flags represented by the following macros. ++ They tell mlockall which of its functions you want. All other ++ bits must be zero. <br> @table @code <br> @item ++ MCL_CURRENT Lock all pages which currently exist in the calling ++ process' virtual address space. <br> @item MCL_FUTURE Set ++ a mode such that any pages added to the process' virtual address ++ space in the future will be locked from birth. This mode does ++ not affect future address spaces owned by the same process so ++ exec, which replaces a process' address space, wipes out ++ MCL_FUTURE. . <br> @end table <br> When the function ++ returns successfully, and you specified MCL_CURRENT, all of the ++ process' pages are backed by (connected to) real frames (they ++ are resident) and are marked to stay that way. This means the ++ function may cause page-ins and have to wait for them. ++ <br> When the process is in MCL_FUTURE mode because it ++ successfully executed this function and specified MCL_CURRENT, ++ any system call by the process that requires space be added to ++ its virtual address space fails with errno = ENOMEM if locking ++ the additional space would cause the process to exceed its ++ locked page limit. In the case that the address space addition ++ that can't be accommodated is stack expansion, the stack ++ expansion fails and the kernel sends a SIGSEGV signal to the ++ process. <br> When the function fails, it does not affect ++ the lock status of any pages or the future locking mode. ++ <br> The return value is zero if the function succeeds. ++ Otherwise, it is -1 and errno is set accordingly. errno values ++ specific to this function are: <br> @table @code @item ++ ENOMEM @itemize @bullet @item At least some of the specified ++ address range does not exist in the calling process' virtual ++ address space. @item The locking would cause the process to ++ exceed its locked page limit. @end itemize <br> @item ++ EPERM The calling process is not superuser. <br> @item ++ EINVAL Undefined bits in flags are not zero. <br> @item ++ ENOSYS The kernel does not provide mlockall capability. ++ <br> @end table <br> You can lock just specific ++ pages with mlock. You unlock pages with munlockall and munlock. ++ <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> munlockall unlocks every page in the calling process' ++ virtual address space and turn off MCL_FUTURE future locking ++ mode. <br> The return value is zero if the function ++ succeeds. Otherwise, it is -1 and errno is set accordingly. ++ The only way this function can fail is for generic reasons that ++ all functions and system calls can fail, so there are no ++ specific errno values. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++
++ ++ ++ The catgets function tries to locate the message data file names ++ cat_name and loads it when found. The return value is of an ++ opaque type and can be used in calls to the other functions to ++ refer to this loaded catalog. <br> The return value is ++ (nl_catd) -1 in case the function failed and no catalog was ++ loaded. The global variable errno contains a code for the error ++ causing the failure. But even if the function call succeeded ++ this does not mean that all messages can be translated. ++ <br> Locating the catalog file must happen in a way which ++ lets the user of the program influence the decision. It is up ++ to the user to decide about the language to use and sometimes it ++ is useful to use alternate catalog files. All this can be ++ specified by the user by setting some environment variables. ++ <br> The first problem is to find out where all the ++ message catalogs are stored. Every program could have its own ++ place to keep all the different files but usually the catalog ++ files are grouped by languages and the catalogs for all programs ++ are kept in the same place. <br> @cindex NLSPATH ++ environment variable To tell the catopen function where the ++ catalog for the program can be found the user can set the ++ environment variable NLSPATH to a value which describes her/his ++ choice. Since this value must be usable for different languages ++ and locales it cannot be a simple string. Instead it is a format ++ string (similar to printf's). An example is <br> ++ @smallexample ++ /usr/share/locale/%L/%N:/usr/share/locale/%L/LC_MESSAGES/%N @end ++ smallexample <br> First one can see that more than one ++ directory can be specified (with the usual syntax of separating ++ them by colons). The next things to observe are the format ++ string, %L and %N in this case. The catopen function knows about ++ several of them and the replacement for all of them is of course ++ different. <br> @table @code @item %N This format element ++ is substituted with the name of the catalog file. This is the ++ value of the cat_name argument given to catgets. <br> ++ @item %L This format element is substituted with the name of the ++ currently selected locale for translating messages. How this is ++ determined is explained below. <br> @item %l (This is the ++ lowercase ell.) This format element is substituted with the ++ language element of the locale name. The string describing the ++ selected locale is expected to have the form ++ lang[_terr[.codeset]] and this format uses the first part lang. ++ <br> @item %t This format element is substituted by the ++ territory part terr of the name of the currently selected ++ locale. See the explanation of the format above. <br> ++ @item %c This format element is substituted by the codeset part ++ codeset of the name of the currently selected locale. See the ++ explanation of the format above. <br> @item %% Since % is ++ used in a meta character there must be a way to express the % ++ character in the result itself. Using %% does this just like it ++ works for printf. @end table <br> <br> Using NLSPATH ++ allows arbitrary directories to be searched for message catalogs ++ while still allowing different languages to be used. If the ++ NLSPATH environment variable is not set, the default value is ++ <br> @smallexample ++ prefix/share/locale/%L/%N:prefix/share/locale/%L/LC_MESSAGES/%N ++ @end smallexample <br> @noindent where prefix is given to ++ configure while installing the GNU C Library (this value is in ++ many cases /usr or the empty string). <br> The remaining ++ problem is to decide which must be used. The value decides ++ about the substitution of the format elements mentioned above. ++ First of all the user can specify a path in the message catalog ++ name (i.e., the name contains a slash character). In this ++ situation the NLSPATH environment variable is not used. The ++ catalog must exist as specified in the program, perhaps relative ++ to the current working directory. This situation in not ++ desirable and catalogs names never should be written this way. ++ Beside this, this behavior is not portable to all other ++ platforms providing the catgets interface. <br> @cindex ++ LC_ALL environment variable @cindex LC_MESSAGES environment ++ variable @cindex LANG environment variable Otherwise the values ++ of environment variables from the standard environment are ++ examined (Standard Environment). Which variables are examined ++ is decided by the flag parameter of catopen. If the value is ++ NL_CAT_LOCALE (which is defined in nl_types.h) then the catopen ++ function use the name of the locale currently selected for the ++ LC_MESSAGES category. <br> If flag is zero the LANG ++ environment variable is examined. This is a left-over from the ++ early days where the concept of the locales had not even reached ++ the level of POSIX locales. <br> The environment variable ++ and the locale name should have a value of the form ++ lang[_terr[.codeset]] as explained above. If no environment ++ variable is set the "C" locale is used which prevents any ++ translation. <br> The return value of the function is in ++ any case a valid string. Either it is a translation from a ++ message catalog or it is the same as the string parameter. So a ++ piece of code to decide whether a translation actually happened ++ must look like this: <br> @smallexample char *trans = ++ catgets (desc, set, msg, input_string); if (trans == ++ input_string) /* Something went wrong. */ @ @ ++ @end smallexample <br> @noindent When an error occurred ++ the global variable errno is set to <br> @table @var @item ++ EBADF The catalog does not exist. @item ENOMSG The set/message ++ tuple does not name an existing element in the message catalog. ++ @end table <br> While it sometimes can be useful to test ++ for errors programs normally will avoid any test. If the ++ translation is not available it is no big problem if the ++ original, untranslated message is printed. Either the user ++ understands this as well or s/he will look for the reason why ++ the messages are not translated. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ The function catgets has to be used to access the massage ++ catalog previously opened using the catopen function. The ++ catalog_desc parameter must be a value previously returned by ++ catopen. <br> The next two parameters, set and message, ++ reflect the internal organization of the message catalog files. ++ This will be explained in detail below. For now it is ++ interesting to know that a catalog can consists of several set ++ and the messages in each thread are individually numbered using ++ numbers. Neither the set number nor the message number must be ++ consecutive. They can be arbitrarily chosen. But each message ++ (unless equal to another one) must have its own unique pair of ++ set and message number. <br> Since it is not guaranteed ++ that the message catalog for the language selected by the user ++ exists the last parameter string helps to handle this case ++ gracefully. If no matching string can be found string is ++ returned. This means for the programmer that <br> ++ @itemize @bullet @item the string parameters should contain ++ reasonable text (this also helps to understand the program seems ++ otherwise there would be no hint on the string which is expected ++ to be returned. @item all string arguments should be written in ++ the same language. @end itemize ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ The catclose function can be used to free the resources ++ associated with a message catalog which previously was opened by ++ a call to catopen. If the resources can be successfully freed ++ the function returns 0. Otherwise it return 1 and the global ++ variable errno is set. Errors can occur if the catalog ++ descriptor catalog_desc is not valid in which case errno is set ++ to EBADF. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The gettext function searches the currently selected message ++ catalogs for a string which is equal to msgid. If there is such ++ a string available it is returned. Otherwise the argument ++ string msgid is returned. <br> Please note that all though ++ the return value is char * the returned string must not be ++ changed. This broken type results from the history of the ++ function and does not reflect the way the function should be ++ used. <br> Please note that above we wrote ``message ++ catalogs'' (plural). This is a specialty of the GNU ++ implementation of these functions and we will say more about ++ this when we talk about the ways message catalogs are selected ++ (Locating gettext catalog). <br> The gettext function does ++ not modify the value of the global errno variable. This is ++ necessary to make it possible to write something like <br> ++ @smallexample printf (gettext ("Operation failed: %m\n")); ++ @end smallexample <br> Here the errno value is used in the ++ printf function while processing the %m format element and if ++ the gettext function would change this value (it is called ++ before printf is called) we would get a wrong message. ++ <br> So there is no easy way to detect a missing message ++ catalog beside comparing the argument string with the result. ++ But it is normally the task of the user to react on missing ++ catalogs. The program cannot guess when a message catalog is ++ really necessary since for a user who speaks the language the ++ program was developed in does not need any translation. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The dgettext functions acts just like the gettext function. It ++ only takes an additional first argument domainname which guides ++ the selection of the message catalogs which are searched for the ++ translation. If the domainname parameter is the null pointer ++ the dgettext function is exactly equivalent to gettext since the ++ default value for the domain name is used. <br> As for ++ gettext the return value type is char * which is an anachronism. ++ The returned string must never be modified. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The dcgettext adds another argument to those which dgettext ++ takes. This argument category specifies the last piece of ++ information needed to localize the message catalog. I.e., the ++ domain name and the locale category exactly specify which ++ message catalog has to be used (relative to a given directory, ++ see below). <br> The dgettext function can be expressed in ++ terms of dcgettext by using <br> @smallexample dcgettext ++ (domain, string, LC_MESSAGES) @end smallexample <br> ++ @noindent instead of <br> @smallexample dgettext (domain, ++ string) @end smallexample <br> This also shows which ++ values are expected for the third parameter. One has to use the ++ available selectors for the categories available in locale.h. ++ Normally the available values are LC_CTYPE, LC_COLLATE, ++ LC_MESSAGES, LC_MONETARY, LC_NUMERIC, and LC_TIME. Please note ++ that LC_ALL must not be used and even though the names might ++ suggest this, there is no relation to the environments variables ++ of this name. <br> The dcgettext function is only ++ implemented for compatibility with other systems which have ++ gettext functions. There is not really any situation where it ++ is necessary (or useful) to use a different value but ++ LC_MESSAGES in for the category parameter. We are dealing with ++ messages here and any other choice can only be irritating. ++ <br> As for gettext the return value type is char * which ++ is an anachronism. The returned string must never be modified. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The textdomain function sets the default domain, which is used ++ in all future gettext calls, to domainname. Please note that ++ dgettext and dcgettext calls are not influenced if the ++ domainname parameter of these functions is not the null pointer. ++ <br> Before the first call to textdomain the default ++ domain is messages. This is the name specified in the ++ specification of the gettext API. This name is as good as any ++ other name. No program should ever really use a domain with ++ this name since this can only lead to problems. <br> The ++ function returns the value which is from now on taken as the ++ default domain. If the system went out of memory the returned ++ value is NULL and the global variable errno is set to ENOMEM. ++ Despite the return value type being char * the return string ++ must not be changed. It is allocated internally by the ++ textdomain function. <br> If the domainname parameter is ++ the null pointer no new default domain is set. Instead the ++ currently selected default domain is returned. <br> If the ++ domainname parameter is the empty string the default domain is ++ reset to its initial value, the domain with the name messages. ++ This possibility is questionable to use since the domain ++ messages really never should be used. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The bindtextdomain function can be used to specify the directory ++ which contains the message catalogs for domain domainname for ++ the different languages. To be correct, this is the directory ++ where the hierarchy of directories is expected. Details are ++ explained below. <br> For the programmer it is important ++ to note that the translations which come with the program have ++ be placed in a directory hierarchy starting at, say, /foo/bar. ++ Then the program should make a bindtextdomain call to bind the ++ domain for the current program to this directory. So it is made ++ sure the catalogs are found. A correctly running program does ++ not depend on the user setting an environment variable. ++ <br> The bindtextdomain function can be used several times ++ and if the domainname argument is different the previously bound ++ domains will not be overwritten. <br> If the program which ++ wish to use bindtextdomain at some point of time use the chdir ++ function to change the current working directory it is important ++ that the dirname strings ought to be an absolute pathname. ++ Otherwise the addressed directory might vary with the time. ++ <br> If the dirname parameter is the null pointer ++ bindtextdomain returns the currently selected directory for the ++ domain with the name domainname. <br> The bindtextdomain ++ function returns a pointer to a string containing the name of ++ the selected directory name. The string is allocated internally ++ in the function and must not be changed by the user. If the ++ system went out of core during the execution of bindtextdomain ++ the return value is NULL and the global variable errno is set ++ accordingly. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The ngettext function is similar to the gettext function as it ++ finds the message catalogs in the same way. But it takes two ++ extra arguments. The msgid1 parameter must contain the singular ++ form of the string to be converted. It is also used as the key ++ for the search in the catalog. The msgid2 parameter is the ++ plural form. The parameter n is used to determine the plural ++ form. If no message catalog is found msgid1 is returned if n == ++ 1, otherwise msgid2. <br> An example for the us of this ++ function is: <br> @smallexample printf (ngettext ("%d ++ file removed", "%d files removed", n), n); @end smallexample ++ <br> Please note that the numeric value n has to be passed ++ to the printf function as well. It is not sufficient to pass it ++ only to ngettext. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The dngettext is similar to the dgettext function in the way the ++ message catalog is selected. The difference is that it takes ++ two extra parameter to provide the correct plural form. These ++ two parameters are handled in the same way ngettext handles ++ them. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The dcngettext is similar to the dcgettext function in the way ++ the message catalog is selected. The difference is that it ++ takes two extra parameter to provide the correct plural form. ++ These two parameters are handled in the same way ngettext ++ handles them. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function tests whether the string string matches the ++ pattern pattern. It returns 0 if they do match; otherwise, it ++ returns the nonzero value FNM_NOMATCH. The arguments pattern ++ and string are both strings. <br> The argument flags is a ++ combination of flag bits that alter the details of matching. ++ See below for a list of the defined flags. <br> In the GNU ++ C Library, fnmatch cannot experience an ``error''---it always ++ returns an answer for whether the match succeeds. However, ++ other implementations of fnmatch might sometimes report ++ ``errors''. They would do so by returning nonzero values that ++ are not equal to FNM_NOMATCH. ++ ++ ++ ++ ++ ++ ++ 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. <br> ++ ++ ++ ++ ++ The number of elements in the vector, excluding the initial null ++ entries if the GLOB_DOOFFS flag is used (see gl_offs below). ++ <br> ++ ++ ++ ++ ++ The address of the vector. This field has type char **. ++ <br> ++ ++ ++ ++ ++ The offset of the first real element of the vector, from its ++ nominal address in the gl_pathv field. Unlike the other fields, ++ this is always an input to glob, rather than an output from it. ++ <br> If you use a nonzero offset, then that many elements ++ at the beginning of the vector are left empty. (The glob ++ function fills them with null pointers.) <br> The gl_offs ++ field is meaningful only if you use the GLOB_DOOFFS 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. <br> ++ ++ ++ ++ ++ The address of an alternative implementation of the closedir ++ function. It is used if the GLOB_ALTDIRFUNC bit is set in the ++ flag parameter. The type of this field is void (*) (void *). ++ <br> This is a GNU extension. <br> ++ ++ ++ ++ ++ The address of an alternative implementation of the readdir ++ function used to read the contents of a directory. It is used ++ if the GLOB_ALTDIRFUNC bit is set in the flag parameter. The ++ type of this field is struct dirent *(*) (void *). <br> ++ This is a GNU extension. <br> ++ ++ ++ ++ ++ The address of an alternative implementation of the opendir ++ function. It is used if the GLOB_ALTDIRFUNC bit is set in the ++ flag parameter. The type of this field is void *(*) (const char ++ *). <br> This is a GNU extension. <br> ++ ++ ++ ++ ++ The address of an alternative implementation of the stat ++ function to get information about an object in the filesystem. ++ It is used if the GLOB_ALTDIRFUNC bit is set in the flag ++ parameter. The type of this field is int (*) (const char *, ++ struct stat *). <br> This is a GNU extension. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ 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. <br> ++ ++ ++ ++ ++ The number of elements in the vector, excluding the initial null ++ entries if the GLOB_DOOFFS flag is used (see gl_offs below). ++ <br> ++ ++ ++ ++ ++ The address of the vector. This field has type char **. ++ <br> ++ ++ ++ ++ ++ The offset of the first real element of the vector, from its ++ nominal address in the gl_pathv field. Unlike the other fields, ++ this is always an input to glob, rather than an output from it. ++ <br> If you use a nonzero offset, then that many elements ++ at the beginning of the vector are left empty. (The glob ++ function fills them with null pointers.) <br> The gl_offs ++ field is meaningful only if you use the GLOB_DOOFFS 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. <br> ++ ++ ++ ++ ++ The address of an alternative implementation of the closedir ++ function. It is used if the GLOB_ALTDIRFUNC bit is set in the ++ flag parameter. The type of this field is void (*) (void *). ++ <br> This is a GNU extension. <br> ++ ++ ++ ++ ++ The address of an alternative implementation of the readdir64 ++ function used to read the contents of a directory. It is used ++ if the GLOB_ALTDIRFUNC bit is set in the flag parameter. The ++ type of this field is struct dirent64 *(*) (void *). <br> ++ This is a GNU extension. <br> ++ ++ ++ ++ ++ The address of an alternative implementation of the opendir ++ function. It is used if the GLOB_ALTDIRFUNC bit is set in the ++ flag parameter. The type of this field is void *(*) (const char ++ *). <br> This is a GNU extension. <br> ++ ++ ++ ++ ++ The address of an alternative implementation of the stat64 ++ function to get information about an object in the filesystem. ++ It is used if the GLOB_ALTDIRFUNC bit is set in the flag ++ parameter. The type of this field is int (*) (const char *, ++ struct stat64 *). <br> This is a GNU extension. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++
++ ++ ++ The function glob does globbing using the pattern pattern in the ++ current directory. It puts the result in a newly allocated ++ vector, and stores the size and address of this vector into ++ *vector-ptr. The argument flags is a combination of bit flags; ++ see Flags for Globbing, for details of the flags. <br> The ++ result of globbing is a sequence of file names. The function ++ glob allocates a string for each resulting word, then allocates ++ a vector of type char ** to store the addresses of these ++ strings. The last element of the vector is a null pointer. This ++ vector is called the word vector. <br> To return this ++ vector, glob stores both its address and its length (number of ++ elements, not counting the terminating null pointer) into ++ *vector-ptr. <br> Normally, glob sorts the file names ++ alphabetically before returning them. You can turn this off ++ with the flag GLOB_NOSORT if you want to get the information as ++ fast as possible. Usually it's a good idea to let glob sort ++ them---if you process the files in alphabetical order, the users ++ will have a feel for the rate of progress that your application ++ is making. <br> If glob succeeds, it returns 0. ++ Otherwise, it returns one of these error codes: <br> ++ @vtable @code @item GLOB_ABORTED There was an error opening a ++ directory, and you used the flag GLOB_ERR or your specified ++ errfunc returned a nonzero value. @iftex See below @end iftex ++ @ifinfo , @end ifinfo for an explanation of the GLOB_ERR flag ++ and errfunc. <br> @item GLOB_NOMATCH The pattern didn't ++ match any existing files. If you use the GLOB_NOCHECK flag, ++ then you never get this error code, because that flag tells glob ++ to pretend that the pattern matched at least one file. ++ <br> @item GLOB_NOSPACE It was impossible to allocate ++ memory to hold the result. @end vtable <br> In the event ++ of an error, glob stores information in *vector-ptr about all ++ the matches it has found so far. <br> It is important to ++ notice that the glob function will not fail if it encounters ++ directories or files which cannot be handled without the LFS ++ interfaces. The implementation of glob 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 stat functions complicates ++ things a bit. If these callback functions are used and a large ++ file or directory is encountered glob can fail. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The glob64 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 glob64 function is added by the extensions of the GNU glob ++ implementation which allows the user to provide own directory ++ handling and stat functions. The readdir and stat functions do ++ depend on the choice of _FILE_OFFSET_BITS since the definition ++ of the types struct dirent and struct stat will change depending ++ on the choice. <br> Beside this difference the glob64 ++ works just like glob in all aspects. <br> This function is ++ a GNU extension. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The globfree function frees all resources allocated by previous ++ calls to glob associated with the object pointed to by pglob. ++ This function should be called whenever the currently used ++ glob_t typed object isn't used anymore. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is equivalent to globfree but it frees records of ++ type glob64_t which were allocated by glob64. ++ ++ ++ ++ ++ ++ ++ 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: <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The function regcomp ``compiles'' a regular expression into a ++ data structure that you can use with regexec to match against a ++ string. The compiled regular expression format is designed for ++ efficient matching. regcomp stores it into *compiled. ++ <br> It's up to you to allocate an object of type regex_t ++ and pass its address to regcomp. <br> The argument cflags ++ lets you specify various options that control the syntax and ++ semantics of regular expressions. . <br> If you use the ++ flag REG_NOSUB, then regcomp omits from the compiled regular ++ expression the information necessary to record how ++ subexpressions actually match. In this case, you might as well ++ pass 0 for the matchptr and nmatch arguments when you call ++ regexec. <br> If you don't use REG_NOSUB, then the ++ compiled regular expression does have the capacity to record how ++ subexpressions match. Also, regcomp tells you how many ++ subexpressions pattern has, by storing the number in ++ compiled->re_nsub. You can use that value to decide how long ++ an array to allocate to hold information about subexpression ++ matches. <br> regcomp returns 0 if it succeeds in ++ compiling the regular expression; otherwise, it returns a ++ nonzero error code (see the table below). You can use regerror ++ to produce an error message string describing the reason for a ++ nonzero value; see Regexp Cleanup. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function tries to match the compiled regular expression ++ *compiled against string. <br> regexec returns 0 if the ++ regular expression matches; otherwise, it returns a nonzero ++ value. See the table below for what nonzero values mean. You ++ can use regerror to produce an error message string describing ++ the reason for a nonzero value; see Regexp Cleanup. <br> ++ The argument eflags is a word of bit flags that enable various ++ options. <br> If you want to get information about what ++ part of string actually matched the regular expression or its ++ subexpressions, use the arguments matchptr and nmatch. ++ Otherwise, pass 0 for nmatch, and NULL for matchptr. . ++ ++ ++ ++ ++ ++ ++ This is the data type of the matcharray array that you pass to ++ regexec. It contains two structure fields, as follows: ++ <br> ++ ++ ++ ++ ++ The offset in string of the beginning of a substring. Add this ++ value to string to get the address of that part. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ Calling regfree frees all the storage that *compiled points to. ++ This includes various internal fields of the regex_t structure ++ that aren't documented in this manual. <br> regfree does ++ not free the object *compiled itself. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function produces an error message string for the error ++ code errcode, and stores the string in length bytes of memory ++ starting at buffer. For the compiled argument, supply the same ++ compiled regular expression structure that regcomp or regexec ++ was working with when it got the error. Alternatively, you can ++ supply NULL for compiled; you will still get a meaningful error ++ message, but it might not be as detailed. <br> If the ++ error message can't fit in length bytes (including a terminating ++ null character), then regerror truncates it. The string that ++ regerror stores is always null-terminated even if it has been ++ truncated. <br> The return value of regerror is the ++ minimum length needed to store the entire error message. If ++ this is less than length, then the error message was not ++ truncated, and you can use it. Otherwise, you should call ++ regerror again with a larger buffer. <br> Here is a ++ function which uses regerror, but always dynamically allocates a ++ buffer for the error message: <br> @smallexample char ++ *get_regerror (int errcode, regex_t *compiled) size_t length ++ = regerror (errcode, compiled, NULL, 0); char *buffer = ++ xmalloc (length); (void) regerror (errcode, compiled, buffer, ++ length); return buffer; @ @end smallexample ++ ++ ++ ++ ++ ++ ++ This data type holds a pointer to a word vector. More ++ precisely, it records both the address of the word vector and ++ its size. <br> ++ ++ ++ ++ ++ The number of elements in the vector. <br> ++ ++ ++ ++ ++ The address of the vector. This field has type char **. ++ <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ Perform word expansion on the string words, putting the result ++ in a newly allocated vector, and store the size and address of ++ this vector into *word-vector-ptr. The argument flags is a ++ combination of bit flags; see Flags for Wordexp, for details of ++ the flags. <br> You shouldn't use any of the characters ++ |&;<> in the string words unless they are quoted; ++ likewise for newline. If you use these characters unquoted, you ++ will get the WRDE_BADCHAR error code. Don't use parentheses or ++ braces unless they are quoted or part of a word expansion ++ construct. If you use quotation characters '"`, they should ++ come in pairs that balance. <br> The results of word ++ expansion are a sequence of words. The function wordexp ++ allocates a string for each resulting word, then allocates a ++ vector of type char ** to store the addresses of these strings. ++ The last element of the vector is a null pointer. This vector is ++ called the word vector. <br> To return this vector, ++ wordexp stores both its address and its length (number of ++ elements, not counting the terminating null pointer) into ++ *word-vector-ptr. <br> If wordexp succeeds, it returns 0. ++ Otherwise, it returns one of these error codes: <br> ++ @table @code @item WRDE_BADCHAR The input string words contains ++ an unquoted invalid character such as |. <br> @item ++ WRDE_BADVAL The input string refers to an undefined shell ++ variable, and you used the flag WRDE_UNDEF to forbid such ++ references. <br> @item WRDE_CMDSUB The input string uses ++ command substitution, and you used the flag WRDE_NOCMD to forbid ++ command substitution. <br> @item WRDE_NOSPACE It was ++ impossible to allocate memory to hold the result. In this case, ++ wordexp can store part of the results---as much as it could ++ allocate room for. <br> @item WRDE_SYNTAX There was a ++ syntax error in the input string. For example, an unmatched ++ quoting character is a syntax error. @end table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ Free the storage used for the word-strings and vector that ++ *word-vector-ptr points to. This does not free the structure ++ *word-vector-ptr itself---only the other data it points to. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++
++ ++ ++ The pipe function creates a pipe and puts the file descriptors ++ for the reading and writing ends of the pipe (respectively) into ++ filedes[0] and filedes[1]. <br> An easy way to remember ++ that the input end comes first is that file descriptor 0 is ++ standard input, and file descriptor 1 is standard output. ++ <br> If successful, pipe returns a value of 0. On ++ failure, -1 is returned. The following errno error conditions ++ are defined for this function: <br> @table @code @item ++ EMFILE The process has too many files open. <br> @item ++ ENFILE There are too many open files in the entire system. , ++ for more information about ENFILE. This error never occurs in ++ the GNU system. @end table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The popen function is closely related to the system function; ++ see Running a Command. It executes the shell command command as ++ a subprocess. However, instead of waiting for the command to ++ complete, it creates a pipe to the subprocess and returns a ++ stream that corresponds to that pipe. <br> If you specify ++ a mode argument of "r", you can read from the stream to retrieve ++ data from the standard output channel of the subprocess. The ++ subprocess inherits its standard input channel from the parent ++ process. <br> Similarly, if you specify a mode argument of ++ "w", you can write to the stream to send data to the standard ++ input channel of the subprocess. The subprocess inherits its ++ standard output channel from the parent process. <br> In ++ the event of an error popen 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. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The pclose function is used to close a stream created by popen. ++ It waits for the child process to terminate and returns its ++ status value, as for the system function. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The mkfifo function makes a FIFO special file with name ++ filename. The mode argument is used to set the file's ++ permissions; see Setting Permissions. <br> The normal, ++ successful return value from mkfifo is 0. In the case of an ++ error, -1 is returned. In addition to the usual file name ++ errors (File Name Errors), the following errno error conditions ++ are defined for this function: <br> @table @code @item ++ EEXIST The named file already exists. <br> @item ENOSPC ++ The directory or file system cannot be extended. <br> ++ @item EROFS The directory that would contain the file resides on ++ a read-only file system. @end table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ @pindex sh This function executes command as a shell command. ++ In the GNU C library, it always uses the default shell sh to run ++ the command. In particular, it searches the directories in PATH ++ to find programs to execute. The return value is -1 if it ++ wasn't possible to create the shell process, and otherwise is ++ the status of the shell process. , for details on how this ++ status code can be interpreted. <br> If the command ++ argument is a null pointer, a return value of zero indicates ++ that no command processor is available. <br> This function ++ is a cancellation point in multi-threaded programs. This is a ++ problem if the thread allocates some resources (like memory, ++ file descriptors, semaphores or whatever) at the time system is ++ called. If the thread gets canceled these resources stay ++ allocated until the program ends. To avoid this calls to system ++ should be protected using cancellation handlers. @c ref ++ pthread_cleanup_push / pthread_cleanup_pop <br> @pindex ++ stdlib.h The system function is declared in the header file ++ stdlib.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++
++ ++ ++ The getpid function returns the process ID of the current ++ process. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The getppid function returns the process ID of the parent of the ++ current process. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The fork function creates a new process. <br> If the ++ operation is successful, there are then both parent and child ++ processes and both see fork return, but with different values: ++ it returns a value of 0 in the child process and returns the ++ child's process ID in the parent process. <br> If process ++ creation failed, fork returns a value of -1 in the parent ++ process. The following errno error conditions are defined for ++ fork: <br> @table @code @item EAGAIN There aren't enough ++ system resources to create another process, or the user already ++ has too many processes running. This means exceeding the ++ RLIMIT_NPROC resource limit, which can usually be increased; ++ Limits on Resources. <br> @item ENOMEM The process ++ requires more space than the system can supply. @end table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The vfork function is similar to fork but on some systems it is ++ more efficient; however, there are restrictions you must follow ++ to use it safely. <br> While fork makes a complete copy of ++ the calling process's address space and allows both the parent ++ and child to execute independently, vfork does not make this ++ copy. Instead, the child process created with vfork shares its ++ parent's address space until it calls _exit or one of the exec ++ functions. In the meantime, the parent process suspends ++ execution. <br> You must be very careful not to allow the ++ child process created with vfork 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 vfork! This would leave the parent ++ process's control information very confused. If in doubt, use ++ fork instead. <br> Some operating systems don't really ++ implement vfork. The GNU C library permits you to use vfork on ++ all systems, but actually executes fork if vfork isn't ++ available. If you follow the proper precautions for using ++ vfork, your program will still work even if the system uses fork ++ instead. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The execv function executes the file named by filename as a new ++ process image. <br> The argv argument is an array of ++ null-terminated strings that is used to provide a value for the ++ argv argument to the main function of the program to be ++ executed. The last element of this array must be a null ++ pointer. By convention, the first element of this array is the ++ file name of the program sans directory names. , for full ++ details on how programs can access these arguments. <br> ++ The environment for the new process image is taken from the ++ environ variable of the current process image; see Environment ++ Variables, for information about environments. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This is similar to execv, but the argv strings are specified ++ individually instead of as an array. A null pointer must be ++ passed as the last such argument. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This is similar to execv, but permits you to specify the ++ environment for the new program explicitly as the env argument. ++ This should be an array of strings in the same format as for the ++ environ variable; see Environment Access. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This is similar to execl, 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 argv argument, and should be an array of strings in the ++ same format as for the environ variable. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The execvp function is similar to execv, except that it searches ++ the directories listed in the PATH environment variable ++ (Standard Environment) to find the full file name of a file from ++ filename if filename does not contain a slash. <br> This ++ function is useful for executing system utility programs, ++ because it looks for them in the places that the user has ++ chosen. Shells use it to run the commands that users type. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is like execl, except that it performs the same ++ file name searching as the execvp function. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The waitpid function is used to request status information from ++ a child process whose process ID is pid. Normally, the calling ++ process is suspended until the child process makes status ++ information available by terminating. <br> Other values ++ for the pid argument have special interpretations. A value of ++ -1 or WAIT_ANY requests status information for any child ++ process; a value of 0 or WAIT_MYPGRP requests information for ++ any child process in the same process group as the calling ++ process; and any other negative value pgid requests information ++ for any child process whose process group ID is pgid. <br> ++ If status information for a child process is available ++ immediately, this function returns immediately without waiting. ++ If more than one eligible child process has status information ++ available, one of them is chosen randomly, and its status is ++ returned immediately. To get the status from the other eligible ++ child processes, you need to call waitpid again. <br> The ++ options argument is a bit mask. Its value should be the bitwise ++ OR (that is, the | operator) of zero or more of the WNOHANG and ++ WUNTRACED flags. You can use the WNOHANG flag to indicate that ++ the parent process shouldn't wait; and the WUNTRACED flag to ++ request status information from stopped processes as well as ++ processes that have terminated. <br> The status ++ information from the child process is stored in the object that ++ status-ptr points to, unless status-ptr is a null pointer. ++ <br> This function is a cancellation point in ++ multi-threaded programs. This is a problem if the thread ++ allocates some resources (like memory, file descriptors, ++ semaphores or whatever) at the time waitpid is called. If the ++ thread gets canceled these resources stay allocated until the ++ program ends. To avoid this calls to waitpid should be ++ protected using cancellation handlers. @c ref ++ pthread_cleanup_push / pthread_cleanup_pop <br> The return ++ value is normally the process ID of the child process whose ++ status is reported. If there are child processes but none of ++ them is waiting to be noticed, waitpid will block until one is. ++ However, if the WNOHANG option was specified, waitpid will ++ return zero instead of blocking. <br> If a specific PID to ++ wait for was given to waitpid, 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, ++ waitpid will block or return zero as described above. <br> ++ A value of -1 is returned in case of error. The following errno ++ error conditions are defined for this function: <br> ++ @table @code @item EINTR The function was interrupted by ++ delivery of a signal to the calling process. . <br> @item ++ ECHILD There are no child processes to wait for, or the ++ specified pid is not a child of the calling process. <br> ++ @item EINVAL An invalid value was provided for the options ++ argument. @end table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This is a simplified version of waitpid, and is used to wait ++ until any one child process terminates. The call: <br> ++ @smallexample wait (&status) @end smallexample <br> ++ @noindent is exactly equivalent to: <br> @smallexample ++ waitpid (-1, &status, 0) @end smallexample <br> This ++ function is a cancellation point in multi-threaded programs. ++ This is a problem if the thread allocates some resources (like ++ memory, file descriptors, semaphores or whatever) at the time ++ wait is called. If the thread gets canceled these resources ++ stay allocated until the program ends. To avoid this calls to ++ wait should be protected using cancellation handlers. @c ref ++ pthread_cleanup_push / pthread_cleanup_pop ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ If usage is a null pointer, wait4 is equivalent to waitpid (pid, ++ status-ptr, options). <br> If usage is not null, wait4 ++ stores usage figures for the child process in *rusage (but only ++ if the child has terminated, not if it has stopped). . ++ <br> This function is a BSD extension. ++ ++ ++ ++ ++ ++ ++ This data type represents program termination status values. It ++ has the following members: <br> ++ ++ ++ ++ ++ The value of this member is the same as that of the WTERMSIG ++ macro. <br> ++ ++ ++ ++ ++ The value of this member is the same as that of the WCOREDUMP ++ macro. <br> ++ ++ ++ ++ ++ The value of this member is the same as that of the WEXITSTATUS ++ macro. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ If usage is a null pointer, wait3 is equivalent to waitpid (-1, ++ status-ptr, options). <br> If usage is not null, wait3 ++ stores usage figures for the child process in *rusage (but only ++ if the child has terminated, not if it has stopped). . ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function reports resource usage totals for processes ++ specified by processes, storing the information in *rusage. ++ <br> In most systems, processes has only two valid values: ++ <br> @table @code @item RUSAGE_SELF Just the current ++ process. <br> @item RUSAGE_CHILDREN All child processes ++ (direct and indirect) that have already terminated. @end table ++ <br> In the GNU system, you can also inquire about a ++ particular child process by specifying its process ID. ++ <br> The return value of getrusage is zero for success, ++ and -1 for failure. <br> @table @code @item EINVAL The ++ argument processes is not valid. @end table ++ ++ ++ ++ ++ ++ ++ This data type stores various resource usage statistics. It has ++ the following members, and possibly others: <br> ++ ++ ++ ++ ++ Time spent executing user instructions. <br> ++ ++ ++ ++ ++ Time spent in operating system code on behalf of processes. ++ <br> ++ ++ ++ ++ ++ The maximum resident set size used, in kilobytes. That is, the ++ maximum number of kilobytes of physical memory that processes ++ used simultaneously. <br> ++ ++ ++ ++ ++ An integral value expressed in kilobytes times ticks of ++ execution, which indicates the amount of memory used by text ++ that was shared with other processes. <br> ++ ++ ++ ++ ++ An integral value expressed the same way, which is the amount of ++ unshared memory used for data. <br> ++ ++ ++ ++ ++ An integral value expressed the same way, which is the amount of ++ unshared memory used for stack space. <br> ++ ++ ++ ++ ++ The number of page faults which were serviced without requiring ++ any I/O. <br> ++ ++ ++ ++ ++ The number of page faults which were serviced by doing I/O. ++ <br> ++ ++ ++ ++ ++ The number of times processes was swapped entirely out of main ++ memory. <br> ++ ++ ++ ++ ++ The number of times the file system had to read from the disk on ++ behalf of processes. <br> ++ ++ ++ ++ ++ The number of times the file system had to write to the disk on ++ behalf of processes. <br> ++ ++ ++ ++ ++ Number of IPC messages sent. <br> ++ ++ ++ ++ ++ Number of IPC messages received. <br> ++ ++ ++ ++ ++ Number of signals received. <br> ++ ++ ++ ++ ++ The number of times processes voluntarily invoked a context ++ switch (usually to wait for some service). <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++
++ ++ ++ <br> vtimes reports resource usage totals for a process. ++ <br> If current is non-null, vtimes stores resource usage ++ totals for the invoking process alone in the structure to which ++ it points. If child is non-null, vtimes stores resource usage ++ totals for all past children (which have terminated) of the ++ invoking process in the structure to which it points. <br> ++ @deftp {Data Type} {struct vtimes} This data type contains ++ information about the resource usage of a process. Each member ++ corresponds to a member of the struct rusage data type described ++ above. <br> @table @code @item vm_utime User CPU time. ++ Analogous to ru_utime in struct rusage @item vm_stime System CPU ++ time. Analogous to ru_stime in struct rusage @item vm_idsrss ++ Data and stack memory. The sum of the values that would be ++ reported as ru_idrss and ru_isrss in struct rusage @item ++ vm_ixrss Shared memory. Analogous to ru_ixrss in struct rusage ++ @item vm_maxrss Maximent resident set size. Analogous to ++ ru_maxrss in struct rusage @item vm_majflt Major page faults. ++ Analogous to ru_majflt in struct rusage @item vm_minflt Minor ++ page faults. Analogous to ru_minflt in struct rusage @item ++ vm_nswap Swap count. Analogous to ru_nswap in struct rusage ++ @item vm_inblk Disk reads. Analogous to ru_inblk in struct ++ rusage @item vm_oublk Disk writes. Analogous to ru_oublk in ++ struct rusage @end table @end deftp <br> <br> The ++ return value is zero if the function succeeds; -1 otherwise. ++ <br> <br> <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ Read the current and maximum limits for the resource resource ++ and store them in *rlp. <br> The return value is 0 on ++ success and -1 on failure. The only possible errno error ++ condition is EFAULT. <br> When the sources are compiled ++ with _FILE_OFFSET_BITS == 64 on a 32-bit system this function is ++ in fact getrlimit64. Thus, the LFS interface transparently ++ replaces the old interface. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to getrlimit but its second parameter ++ is a pointer to a variable of type struct rlimit64, which allows ++ it to read values which wouldn't fit in the member of a struct ++ rlimit. <br> If the sources are compiled with ++ _FILE_OFFSET_BITS == 64 on a 32-bit machine, this function is ++ available under the name getrlimit and so transparently replaces ++ the old interface. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ Store the current and maximum limits for the resource resource ++ in *rlp. <br> The return value is 0 on success and -1 on ++ failure. The following errno error condition is possible: ++ <br> @table @code @item EPERM @itemize @bullet @item The ++ process tried to raise a current limit beyond the maximum limit. ++ <br> @item The process tried to raise a maximum limit, but ++ is not superuser. @end itemize @end table <br> When the ++ sources are compiled with _FILE_OFFSET_BITS == 64 on a 32-bit ++ system this function is in fact setrlimit64. Thus, the LFS ++ interface transparently replaces the old interface. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to setrlimit but its second parameter ++ is a pointer to a variable of type struct rlimit64 which allows ++ it to set values which wouldn't fit in the member of a struct ++ rlimit. <br> If the sources are compiled with ++ _FILE_OFFSET_BITS == 64 on a 32-bit machine this function is ++ available under the name setrlimit and so transparently replaces ++ the old interface. ++ ++ ++ ++ ++ ++ ++ This structure is used with getrlimit to receive limit values, ++ and with setrlimit to specify limit values for a particular ++ process and resource. It has two fields: <br> ++ ++ ++ ++ ++ The current limit <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ This structure is analogous to the rlimit structure above, but ++ its components have wider ranges. It has two fields: <br> ++ ++ ++ ++ ++ This is analogous to rlimit.rlim_cur, but with a different type. ++ <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++
++ ++ ++ <br> ulimit gets the current limit or sets the current and ++ maximum limit for a particular resource for the calling process ++ according to the command cmd.a <br> If you are getting a ++ limit, the command argument is the only argument. If you are ++ setting a limit, there is a second argument: long int limit ++ which is the value to which you are setting the limit. ++ <br> The cmd values and the operations they specify are: ++ @table @code <br> @item GETFSIZE Get the current limit on ++ the size of a file, in units of 512 bytes. <br> @item ++ SETFSIZE Set the current and maximum limit on the size of a file ++ to limit * 512 bytes. <br> @end table <br> There are ++ also some other cmd values that may do things on some systems, ++ but they are not supported. <br> Only the superuser may ++ increase a maximum limit. <br> When you successfully get a ++ limit, the return value of ulimit is that limit, which is never ++ negative. When you successfully set a limit, the return value ++ is zero. When the function fails, the return value is -1 and ++ errno is set according to the reason: <br> @table @code ++ @item EPERM A process tried to increase a maximum limit, but is ++ not superuser. @end table <br> <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> vlimit sets the current limit for a resource for a ++ process. <br> resource identifies the resource: <br> ++ @table @code @item LIM_CPU Maximum CPU time. Same as RLIMIT_CPU ++ for setrlimit. @item LIM_FSIZE Maximum file size. Same as ++ RLIMIT_FSIZE for setrlimit. @item LIM_DATA Maximum data memory. ++ Same as RLIMIT_DATA for setrlimit. @item LIM_STACK Maximum stack ++ size. Same as RLIMIT_STACK for setrlimit. @item LIM_CORE ++ Maximum core file size. Same as RLIMIT_COR for setrlimit. @item ++ LIM_MAXRSS Maximum physical memory. Same as RLIMIT_RSS for ++ setrlimit. @end table <br> The return value is zero for ++ success, and -1 with errno set accordingly for failure: ++ <br> @table @code @item EPERM The process tried to set its ++ current limit beyond its maximum limit. @end table <br> ++ ++ ++ ++ ++ ++ ++ This structure describes an absolute priority. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> This function sets both the absolute priority and the ++ scheduling policy for a process. <br> It assigns the ++ absolute priority value given by param and the scheduling policy ++ policy to the process with Process ID pid, or the calling ++ process if pid is zero. If policy is negative, ++ sched_setscheduler keeps the existing scheduling policy. ++ <br> The following macros represent the valid values for ++ policy: <br> @table @code @item SCHED_OTHER Traditional ++ Scheduling @item SCHED_FIFO First In First Out @item SCHED_RR ++ Round Robin @end table <br> @c The Linux kernel code (in ++ sched.c) actually reschedules the process, @c but it puts it at ++ the head of the run queue, so I'm not sure just what @c the ++ effect is, but it must be subtle. <br> On success, the ++ return value is 0. Otherwise, it is -1 and ERRNO is set ++ accordingly. The errno values specific to this function are: ++ <br> @table @code @item EPERM @itemize @bullet @item The ++ calling process does not have CAP_SYS_NICE permission and policy ++ is not SCHED_OTHER (or it's negative and the existing policy is ++ not SCHED_OTHER. <br> @item The calling process does not ++ have CAP_SYS_NICE permission and its owner is not the target ++ process' owner. I.e. the effective uid of the calling process ++ is neither the effective nor the real uid of process pid. @c We ++ need a cross reference to the capabilities section, when ++ written. @end itemize <br> @item ESRCH There is no process ++ with pid pid and pid is not zero. <br> @item EINVAL ++ @itemize @bullet @item policy does not identify an existing ++ scheduling policy. <br> @item The absolute priority value ++ identified by *param is outside the valid range for the ++ scheduling policy policy (or the existing scheduling policy if ++ policy is negative) or param is null. sched_get_priority_max ++ and sched_get_priority_min tell you what the valid range is. ++ <br> @item pid is negative. @end itemize @end table ++ <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> This function returns the scheduling policy assigned ++ to the process with Process ID (pid) pid, or the calling process ++ if pid is zero. <br> The return value is the scheduling ++ policy. See sched_setscheduler for the possible values. ++ <br> If the function fails, the return value is instead -1 ++ and errno is set accordingly. <br> The errno values ++ specific to this function are: <br> @table @code ++ <br> @item ESRCH There is no process with pid pid and it ++ is not zero. <br> @item EINVAL pid is negative. <br> ++ @end table <br> Note that this function is not an exact ++ mate to sched_setscheduler because while that function sets the ++ scheduling policy and the absolute priority, this function gets ++ only the scheduling policy. To get the absolute priority, use ++ sched_getparam. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> This function sets a process' absolute priority. ++ <br> It is functionally identical to sched_setscheduler ++ with policy = -1. <br> @c in fact, that's how it's ++ implemented in Linux. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> This function returns a process' absolute priority. ++ <br> pid is the Process ID (pid) of the process whose ++ absolute priority you want to know. <br> param is a ++ pointer to a structure in which the function stores the absolute ++ priority of the process. <br> On success, the return value ++ is 0. Otherwise, it is -1 and ERRNO is set accordingly. The ++ errno values specific to this function are: <br> @table ++ @code <br> @item ESRCH There is no process with pid pid ++ and it is not zero. <br> @item EINVAL pid is negative. ++ <br> @end table <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> This function returns the lowest absolute priority ++ value that is allowable for a process with scheduling policy ++ policy. <br> On Linux, it is 0 for SCHED_OTHER and 1 for ++ everything else. <br> On success, the return value is 0. ++ Otherwise, it is -1 and ERRNO is set accordingly. The errno ++ values specific to this function are: <br> @table @code ++ @item EINVAL policy does not identify an existing scheduling ++ policy. @end table <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> This function returns the highest absolute priority ++ value that is allowable for a process that with scheduling ++ policy policy. <br> On Linux, it is 0 for SCHED_OTHER and ++ 99 for everything else. <br> On success, the return value ++ is 0. Otherwise, it is -1 and ERRNO is set accordingly. The ++ errno values specific to this function are: <br> @table ++ @code @item EINVAL policy does not identify an existing ++ scheduling policy. @end table <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> This function returns the length of the quantum (time ++ slice) used with the Round Robin scheduling policy, if it is ++ used, for the process with Process ID pid. <br> It returns ++ the length of time as interval. @c We need a cross-reference to ++ where timespec is explained. But that @c section doesn't exist ++ yet, and the time chapter needs to be slightly @c reorganized so ++ there is a place to put it (which will be right next @c to ++ timeval, which is presently misplaced). 2000.05.07. <br> ++ With a Linux kernel, the round robin time slice is always 150 ++ microseconds, and pid need not even be a real pid. <br> ++ The return value is 0 on success and in the pathological case ++ that it fails, the return value is -1 and errno is set ++ accordingly. There is nothing specific that can go wrong with ++ this function, so there are no specific errno values. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> This function voluntarily gives up the process' claim ++ on the CPU. <br> Technically, sched_yield causes the ++ calling process to be made immediately ready to run (as opposed ++ to running, which is what it was before). This means that if it ++ has absolute priority higher than 0, it gets pushed onto the ++ tail of the queue of processes that share its absolute priority ++ and are ready to run, and it will run again when its turn next ++ arrives. If its absolute priority is 0, it is more complicated, ++ but still has the effect of yielding the CPU to other processes. ++ <br> If there are no other processes that share the ++ calling process' absolute priority, this function doesn't have ++ any effect. <br> To the extent that the containing program ++ is oblivious to what other processes in the system are doing and ++ how fast it executes, this function appears as a no-op. ++ <br> The return value is 0 on success and in the ++ pathological case that it fails, the return value is -1 and ++ errno is set accordingly. There is nothing specific that can go ++ wrong with this function, so there are no specific errno values. ++ <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ Return the nice value of a set of processes; class and id ++ specify which ones (see below). If the processes specified do ++ not all have the same nice value, this returns the lowest value ++ that any of them has. <br> On success, the return value is ++ 0. Otherwise, it is -1 and ERRNO is set accordingly. The errno ++ values specific to this function are: <br> @table @code ++ @item ESRCH The combination of class and id does not match any ++ existing process. <br> @item EINVAL The value of class is ++ not valid. @end table <br> If the return value is -1, it ++ could indicate failure, or it could be the nice value. The only ++ way to make certain is to set errno = 0 before calling ++ getpriority, then use errno != 0 afterward as the criterion for ++ failure. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ Set the nice value of a set of processes to niceval; class and ++ id specify which ones (see below). <br> The return value ++ is 0 on success, and -1 on failure. The following errno error ++ condition are possible for this function: <br> @table ++ @code @item ESRCH The combination of class and id does not match ++ any existing process. <br> @item EINVAL The value of class ++ is not valid. <br> @item EPERM The call would set the nice ++ value of a process which is owned by a different user than the ++ calling process (i.e. the target process' real or effective uid ++ does not match the calling process' effective uid) and the ++ calling process does not have CAP_SYS_NICE permission. ++ <br> @item EACCES The call would lower the process' nice ++ value and the process does not have CAP_SYS_NICE permission. ++ @end table <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++
++ ++ ++ Increment the nice value of the calling process by increment. ++ The return value is the new nice value on success, and -1 on ++ failure. In the case of failure, errno will be set to the same ++ values as for setpriority. <br> <br> Here is an ++ equivalent definition of nice: <br> @smallexample int nice ++ (int increment) int result, old = getpriority (PRIO_PROCESS, ++ 0); result = setpriority (PRIO_PROCESS, 0, old + increment); ++ if (result != -1) return old + increment; else ++ return -1; @ @end smallexample ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The getpagesize function returns the page size of the process. ++ This value is fixed for the runtime of the process but can vary ++ in different runs of the application. <br> The function is ++ declared in unistd.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The get_phys_pages function returns the total number of pages of ++ physical the system has. To get the amount of memory this ++ number has to be multiplied by the page size. <br> This ++ function is a GNU extension. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The get_phys_pages function returns the number of available ++ pages of physical the system has. To get the amount of memory ++ this number has to be multiplied by the page size. <br> ++ This function is a GNU extension. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The get_nprocs_conf function returns the number of processors ++ the operating system configured. <br> This function is a ++ GNU extension. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The get_nprocs function returns the number of available ++ processors. <br> This function is a GNU extension. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function gets the 1, 5 and 15 minute load averages of the ++ system. The values are placed in loadavg. getloadavg will place ++ at most nelem elements into the array but never more than three ++ elements. The return value is the number of elements written to ++ loadavg, or -1 on error. <br> This function is declared in ++ stdlib.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++
++ ++ ++ The lfind function searches in the array with *nmemb elements of ++ size bytes pointed to by base for an element which matches the ++ one pointed to by key. The function pointed to by compar is ++ used decide whether two elements match. <br> The return ++ value is a pointer to the matching element in the array starting ++ at base if it is found. If no matching element is available ++ NULL is returned. <br> The mean runtime of this function ++ is *nmemb/2. This function should only be used elements often ++ get added to or deleted from the array in which case it might ++ not be useful to sort the array before searching. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The lsearch function is similar to the lfind function. It ++ searches the given array for an element and returns it if found. ++ The difference is that if no matching element is found the ++ lsearch function adds the object pointed to by key (with a size ++ of size bytes) at the end of the array and it increments the ++ value of *nmemb to reflect this addition. <br> This means ++ for the caller that if it is not sure that the array contains ++ the element one is searching for the memory allocated for the ++ array starting at base must have room for at least size more ++ bytes. If one is sure the element is in the array it is better ++ to use lfind so having more room in the array is always ++ necessary when calling lsearch. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The bsearch function searches the sorted array array for an ++ object that is equivalent to key. The array contains count ++ elements, each of which is of size size bytes. <br> The ++ compare function is used to perform the comparison. This ++ function is called with two pointer arguments and should return ++ an integer less than, equal to, or greater than zero ++ corresponding to whether its first argument is considered less ++ than, equal to, or greater than its second argument. The ++ elements of the array must already be sorted in ascending order ++ according to this comparison function. <br> The return ++ value is a pointer to the matching array element, or a null ++ pointer if no match is found. If the array contains more than ++ one element that matches, the one that is returned is ++ unspecified. <br> This function derives its name from the ++ fact that it is implemented using the binary search algorithm. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The qsort function sorts the array array. The array contains ++ count elements, each of which is of size size. <br> The ++ compare function is used to perform the comparison on the array ++ elements. This function is called with two pointer arguments ++ and should return an integer less than, equal to, or greater ++ than zero corresponding to whether its first argument is ++ considered less than, equal to, or greater than its second ++ argument. <br> @cindex stable sorting Warning: If two ++ objects compare as equal, their order after sorting is ++ unpredictable. That is to say, the sorting is not stable. This ++ can make a difference when the comparison considers only part of ++ the elements. Two elements with the same sort key may differ in ++ other respects. <br> If you want the effect of a stable ++ sort, you can get this result by writing the comparison function ++ so that, lacking other reason distinguish between two elements, ++ it compares them by their addresses. Note that doing this may ++ make the sorting algorithm less efficient, so do it only if ++ necessary. <br> Here is a simple example of sorting an ++ array of doubles in numerical order, using the comparison ++ function defined above (Comparison Functions): <br> ++ @smallexample double *array; int size; qsort (array, ++ size, sizeof (double), compare_doubles); @ @end smallexample ++ <br> The qsort function derives its name from the fact ++ that it was originally implemented using the ``quick sort'' ++ algorithm. <br> The implementation of qsort in this ++ library might not be an in-place sort and might thereby use an ++ extra amount of memory to store the array. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The hcreate function creates a hashing table which can contain ++ at least nel elements. There is no possibility to grow this ++ table so it is necessary to choose the value for nel wisely. ++ The used methods to implement this function might make it ++ necessary to make the number of elements in the hashing table ++ larger than the expected maximal number of elements. Hashing ++ tables usually work inefficient if they are filled 80% or more. ++ The constant access time guaranteed by hashing can only be ++ achieved if few collisions exist. See Knuth's ``The Art of ++ Computer Programming, Part 3: Searching and Sorting'' for more ++ information. <br> The weakest aspect of this function is ++ that there can be at most one hashing table used through the ++ whole program. The table is allocated in local memory out of ++ control of the programmer. As an extension the GNU C library ++ provides an additional set of functions with an reentrant ++ interface which provide a similar interface but which allow to ++ keep arbitrarily many hashing tables. <br> It is possible ++ to use more than one hashing table in the program run if the ++ former table is first destroyed by a call to hdestroy. ++ <br> The function returns a non-zero value if successful. ++ If it return zero something went wrong. This could either mean ++ there is already a hashing table in use or the program runs out ++ of memory. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The hdestroy function can be used to free all the resources ++ allocated in a previous call of hcreate. After a call to this ++ function it is again possible to call hcreate and allocate a new ++ table with possibly different size. <br> It is important ++ to remember that the elements contained in the hashing table at ++ the time hdestroy is called are not freed by this function. It ++ is the responsibility of the program code to free those strings ++ (if necessary at all). Freeing all the element memory is not ++ possible without extra, separately kept information since there ++ is no function to iterate through all available elements in the ++ hashing table. If it is really necessary to free a table and all ++ elements the programmer has to keep a list of all table elements ++ and before calling hdestroy s/he has to free all element's data ++ using this list. This is a very unpleasant mechanism and it also ++ shows that this kind of hashing tables is mainly meant for ++ tables which are created once and used until the end of the ++ program run. ++ ++ ++ ++ ++ ++ ++ Both elements of this structure are pointers to zero-terminated ++ strings. This is a limiting restriction of the functionality of ++ the hsearch functions. They can only be used for data sets ++ which use the NUL character always and solely to terminate the ++ records. It is not possible to handle general binary data. ++ <br> ++ ++ ++ ++ ++ Pointer to a zero-terminated string of characters describing the ++ key for the search or the element in the hashing table. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ To search in a hashing table created using hcreate the hsearch ++ function must be used. This function can perform simple search ++ for an element (if action has the FIND) or it can alternatively ++ insert the key element into the hashing table. Entries are ++ never replaced. <br> The key is denoted by a pointer to an ++ object of type ENTRY. For locating the corresponding position ++ in the hashing table only the key element of the structure is ++ used. <br> If an entry with matching key is found the ++ action parameter is irrelevant. The found entry is returned. ++ If no matching entry is found and the action parameter has the ++ value FIND the function returns a NULL pointer. If no entry is ++ found and the action parameter has the value ENTER a new entry ++ is added to the hashing table which is initialized with the ++ parameter item. A pointer to the newly added entry is returned. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The hcreate_r function initializes the object pointed to by htab ++ to contain a hashing table with at least nel elements. So this ++ function is equivalent to the hcreate function except that the ++ initialized data structure is controlled by the user. <br> ++ This allows having more than one hashing table at one time. The ++ memory necessary for the struct hsearch_data object can be ++ allocated dynamically. It must be initialized with zero before ++ calling this function. <br> The return value is non-zero ++ if the operation were successful. if the return value is zero ++ something went wrong which probably means the programs runs out ++ of memory. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The hdestroy_r function frees all resources allocated by the ++ hcreate_r function for this very same object htab. As for ++ hdestroy it is the programs responsibility to free the strings ++ for the elements of the table. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The hsearch_r function is equivalent to hsearch. The meaning of ++ the first two arguments is identical. But instead of operating ++ on a single global hashing table the function works on the table ++ described by the object pointed to by htab (which is initialized ++ by a call to hcreate_r). <br> Another difference to ++ hcreate is that the pointer to the found entry in the table is ++ not the return value of the functions. It is returned by ++ storing it in a pointer variables pointed to by the retval ++ parameter. The return value of the function is an integer value ++ indicating success if it is non-zero and failure if it is zero. ++ In the latter case the global variable errno signals the reason ++ for the failure. <br> @table @code @item ENOMEM The table ++ is filled and hsearch_r was called with an so far unknown key ++ and action set to ENTER. @item ESRCH The action parameter is ++ FIND and no corresponding element is found in the table. @end ++ table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The tsearch function searches in the tree pointed to by *rootp ++ for an element matching key. The function pointed to by compar ++ is used to determine whether two elements match. , for a ++ specification of the functions which can be used for the compar ++ parameter. <br> If the tree does not contain a matching ++ entry the key value will be added to the tree. tsearch does not ++ make a copy of the object pointed to by key (how could it since ++ the size is unknown). Instead it adds a reference to this object ++ which means the object must be available as long as the tree ++ data structure is used. <br> The tree is represented by a ++ pointer to a pointer since it is sometimes necessary to change ++ the root node of the tree. So it must not be assumed that the ++ variable pointed to by rootp has the same value after the call. ++ This also shows that it is not safe to call the tsearch function ++ more than once at the same time using the same tree. It is no ++ problem to run it more than once at a time on different trees. ++ <br> The return value is a pointer to the matching element ++ in the tree. If a new element was created the pointer points to ++ the new data (which is in fact key). If an entry had to be ++ created and the program ran out of space NULL is returned. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The tfind function is similar to the tsearch function. It ++ locates an element matching the one pointed to by key and ++ returns a pointer to this element. But if no matching element ++ is available no new element is entered (note that the rootp ++ parameter points to a constant pointer). Instead the function ++ returns NULL. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ To remove a specific element matching key from the tree tdelete ++ can be used. It locates the matching element using the same ++ method as tfind. The corresponding element is then removed and ++ a pointer to the parent of the deleted node is returned by the ++ function. If there is no matching entry in the tree nothing can ++ be deleted and the function returns NULL. If the root of the ++ tree is deleted tdelete returns some unspecified value not equal ++ to NULL. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ If the complete search tree has to be removed one can use ++ tdestroy. It frees all resources allocated by the tsearch ++ function to generate the tree pointed to by vroot. <br> ++ For the data in each tree node the function freefct is called. ++ The pointer to the data is passed as the argument to the ++ function. If no such work is necessary freefct must point to a ++ function doing nothing. It is called in any case. <br> ++ This function is a GNU extension and not covered by the System V ++ or X/Open specifications. ++ ++ ++ ++ ++ ++ ++ The VISIT value indicates the status of the current node in the ++ tree and how the function is called. The status of a node is ++ either `leaf' or `internal node'. For each leaf node the ++ function is called exactly once, for each internal node it is ++ called three times: before the first child is processed, after ++ the first child is processed and after both children are ++ processed. This makes it possible to handle all three methods ++ of tree traversal (or even a combination of them). <br> ++ ++ ++ ++ ++ The current node is an internal node and the function is called ++ before the first child was processed. ++ ++ ++ ++ ++ The current node is an internal node and the function is called ++ after the first child was processed. ++ ++ ++ ++ ++ The current node is an internal node and the function is called ++ after the second child was processed. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ For each node in the tree with a node pointed to by root, the ++ twalk function calls the function provided by the parameter ++ action. For leaf nodes the function is called exactly once with ++ value set to leaf. For internal nodes the function is called ++ three times, setting the value parameter or action to the ++ appropriate value. The level argument for the action function ++ is computed while descending the tree with increasing the value ++ by one for the descend to a child, starting with the value 0 for ++ the root node. <br> Since the functions used for the ++ action parameter to twalk must not modify the tree data, it is ++ safe to run twalk in more than one thread at the same time, ++ working on the same tree. It is also safe to call tfind in ++ parallel. Functions which modify the tree must not be used, ++ otherwise the behavior is undefined. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function restores current execution to the state saved in ++ state, and continues execution from the call to setjmp that ++ established that return point. Returning from setjmp by means ++ of longjmp returns the value argument that was passed to ++ longjmp, rather than 0. (But if value is given as 0, setjmp ++ returns 1).@refill ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This is similar to setjmp. If savesigs is nonzero, the set of ++ blocked signals is saved in state and will be restored if a ++ siglongjmp is later performed with this state. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This is similar to longjmp except for the type of its state ++ argument. If the sigsetjmp call that set this state used a ++ nonzero savesigs flag, siglongjmp also restores the set of ++ blocked signals. ++ ++ ++ ++ ++ ++ ++ <br> The ucontext_t type is defined as a structure with as ++ least the following elements: <br> ++ ++ ++ ++ ++ This is a pointer to the next context structure which is used if ++ the context described in the current structure returns. ++ <br> ++ ++ ++ ++ ++ Set of signals which are blocked when this context is used. ++ <br> ++ ++ ++ ++ ++ Stack used for this context. The value need not be (and ++ normally is not) the stack pointer. . <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The getcontext function initializes the variable pointed to by ++ ucp with the context of the calling thread. The context ++ contains the content of the registers, the signal mask, and the ++ current stack. Executing the contents would start at the point ++ where the getcontext call just returned. <br> The function ++ returns 0 if successful. Otherwise it returns -1 and sets errno ++ accordingly. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> The ucp parameter passed to the makecontext shall be ++ initialized by a call to getcontext. The context will be ++ modified to in a way so that if the context is resumed it will ++ start by calling the function func which gets argc integer ++ arguments passed. The integer arguments which are to be passed ++ should follow the argc parameter in the call to makecontext. ++ <br> Before the call to this function the uc_stack and ++ uc_link element of the ucp structure should be initialized. The ++ uc_stack element describes the stack which is used for this ++ context. No two contexts which are used at the same time should ++ use the same memory region for a stack. <br> The uc_link ++ element of the object pointed to by ucp should be a pointer to ++ the context to be executed when the function func returns or it ++ should be a null pointer. See setcontext for more information ++ about the exact use. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> The setcontext function restores the context ++ described by ucp. The context is not modified and can be reused ++ as often as wanted. <br> If the context was created by ++ getcontext execution resumes with the registers filled with the ++ same values and the same stack as if the getcontext call just ++ returned. <br> If the context was modified with a call to ++ makecontext execution continues with the function passed to ++ makecontext which gets the specified parameters passed. If this ++ function returns execution is resumed in the context which was ++ referenced by the uc_link element of the context structure ++ passed to makecontext at the time of the call. If uc_link was a ++ null pointer the application terminates in this case. <br> ++ Since the context contains information about the stack no two ++ threads should use the same context at the same time. The ++ result in most cases would be disastrous. <br> The ++ setcontext function does not return unless an error occurred in ++ which case it returns -1. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> The swapcontext function is similar to setcontext but ++ instead of just replacing the current context the latter is ++ first saved in the object pointed to by oucp as if this was a ++ call to getcontext. The saved context would resume after the ++ call to swapcontext. <br> Once the current context is ++ saved the context described in ucp is installed and execution ++ continues as described in this context. <br> If ++ swapcontext succeeds the function does not return unless the ++ context oucp is used without prior modification by makecontext. ++ The return value in this case is 0. If the function fails it ++ returns -1 and set errno accordingly. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++
++ ++ ++ This function returns a pointer to a statically-allocated string ++ containing a message describing the signal signum. You should ++ not modify the contents of this string; and, since it can be ++ rewritten on subsequent calls, you should save a copy of it if ++ you need to reference it later. <br> @pindex string.h This ++ function is a GNU extension, declared in the header file ++ string.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function prints a message describing the signal signum to ++ the standard error output stream stderr; see Standard Streams. ++ <br> If you call psignal with a message that is either a ++ null pointer or an empty string, psignal just prints the message ++ corresponding to signum, adding a trailing newline. <br> ++ If you supply a non-null message argument, then psignal prefixes ++ its output with this string. It adds a colon and a space ++ character to separate the message from the string corresponding ++ to signum. <br> @pindex stdio.h This function is a BSD ++ feature, declared in the header file signal.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The signal function establishes action as the action for the ++ signal signum. <br> The first argument, signum, 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 (Standard Signals)---don't ++ use an explicit number, because the numerical code for a given ++ kind of signal may vary from operating system to operating ++ system. <br> The second argument, action, specifies the ++ action to use for the signal signum. This can be one of the ++ following: <br> @table @code @item SIG_DFL @vindex SIG_DFL ++ @cindex default action for a signal SIG_DFL specifies the ++ default action for the particular signal. The default actions ++ for various kinds of signals are stated in Standard Signals. ++ <br> @item SIG_IGN @vindex SIG_IGN @cindex ignore action ++ for a signal SIG_IGN specifies that the signal should be ++ ignored. <br> Your program generally should not ignore ++ signals that represent serious events or that are normally used ++ to request termination. You cannot ignore the SIGKILL or ++ SIGSTOP signals at all. You can ignore program error signals ++ like SIGSEGV, but ignoring the error won't enable the program to ++ continue executing meaningfully. Ignoring user requests such as ++ SIGINT, SIGQUIT, and SIGTSTP is unfriendly. <br> When you ++ do not wish signals to be delivered during a certain part of the ++ program, the thing to do is to block them, not ignore them. . ++ <br> @item handler Supply the address of a handler ++ function in your program, to specify running this handler as the ++ way to deliver the signal. <br> For more information about ++ defining signal handler functions, see Defining Handlers. @end ++ table <br> If you set the action for a signal to SIG_IGN, ++ or if you set it to SIG_DFL and the default action is to ignore ++ that signal, then any pending signals of that type are discarded ++ (even if they are blocked). Discarding the pending signals ++ means that they will never be delivered, not even if you ++ subsequently specify another action and unblock this kind of ++ signal. <br> The signal function returns the action that ++ was previously in effect for the specified signum. You can save ++ this value and restore it later by calling signal again. ++ <br> If signal can't honor the request, it returns SIG_ERR ++ instead. The following errno error conditions are defined for ++ this function: <br> @table @code @item EINVAL You ++ specified an invalid signum; or you tried to ignore or provide a ++ handler for SIGKILL or SIGSTOP. @end table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The sysv_signal implements the behavior of the standard signal ++ function as found on SVID systems. The difference to BSD ++ systems is that the handler is deinstalled after a delivery of a ++ signal. <br> Compatibility Note: As said above for signal, ++ this function should be avoided when possible. sigaction is the ++ preferred method. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The ssignal function does the same thing as signal; it is ++ provided only for compatibility with SVID. ++ ++ ++ ++ ++ ++ ++ Structures of type struct sigaction are used in the sigaction ++ function to specify all the information about how to handle a ++ particular signal. This structure contains at least the ++ following members: <br> ++ ++ ++ ++ ++ This is used in the same way as the action argument to the ++ signal function. The value can be SIG_DFL, SIG_IGN, or a ++ function pointer. . <br> ++ ++ ++ ++ ++ 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 sa_mask. If you want that signal not to be ++ blocked within its handler, you must write code in the handler ++ to unblock it. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The action argument is used to set up a new action for the ++ signal signum, while the old-action argument is used to return ++ information about the action previously associated with this ++ symbol. (In other words, old-action has the same purpose as the ++ signal function's return value---you can check to see what the ++ old action in effect for the signal was, and restore it later if ++ you want.) <br> Either action or old-action can be a null ++ pointer. If old-action is a null pointer, this simply ++ suppresses the return of information about the old action. If ++ action is a null pointer, the action associated with the signal ++ signum is unchanged; this allows you to inquire about how a ++ signal is being handled without changing that handling. ++ <br> The return value from sigaction is zero if it ++ succeeds, and -1 on failure. The following errno error ++ conditions are defined for this function: <br> @table ++ @code @item EINVAL The signum argument is not valid, or you are ++ trying to trap or ignore SIGKILL or SIGSTOP. @end table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++
++ ++ ++ The raise function sends the signal signum 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 signum is invalid. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The gsignal function does the same thing as raise; it is ++ provided only for compatibility with SVID. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The kill function sends the signal signum to the process or ++ process group specified by pid. Besides the signals listed in ++ Standard Signals, signum can also have a value of zero to check ++ the validity of the pid. <br> The pid specifies the ++ process or process group to receive the signal: <br> ++ @table @code @item pid > 0 The process whose identifier is ++ pid. <br> @item pid == 0 All processes in the same process ++ group as the sender. <br> @item pid < -1 The process ++ group whose identifier is pid. <br> @item pid == -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. @end table ++ <br> A process can send a signal to itself with a call ++ like kill (getpid(), signum). If kill is used by a process to ++ send a signal to itself, and the signal is not blocked, then ++ kill delivers at least one signal (which might be some other ++ pending unblocked signal instead of the signal signum) to that ++ process before it returns. <br> The return value from kill ++ is zero if the signal can be sent successfully. Otherwise, no ++ signal is sent, and a value of -1 is returned. If pid specifies ++ sending a signal to several processes, kill succeeds if it can ++ send the signal to at least one of them. There's no way you can ++ tell which of the processes got the signal or whether all of ++ them did. <br> The following errno error conditions are ++ defined for this function: <br> @table @code @item EINVAL ++ The signum argument is an invalid or unsupported number. ++ <br> @item 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 pid. <br> @item ESCRH The pid argument does ++ not refer to an existing process or group. @end table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This is similar to kill, but sends signal signum to the process ++ group pgid. This function is provided for compatibility with ++ BSD; using kill to do this is more portable. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function initializes the signal set set to exclude all of ++ the defined signals. It always returns 0. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function initializes the signal set set to include all of ++ the defined signals. Again, the return value is 0. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function adds the signal signum to the signal set set. All ++ sigaddset does is modify set; it does not block or unblock any ++ signals. <br> The return value is 0 on success and -1 on ++ failure. The following errno error condition is defined for this ++ function: <br> @table @code @item EINVAL The signum ++ argument doesn't specify a valid signal. @end table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function removes the signal signum from the signal set set. ++ All sigdelset does is modify set; it does not block or unblock ++ any signals. The return value and error conditions are the same ++ as for sigaddset. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The sigismember function tests whether the signal signum is a ++ member of the signal set set. It returns 1 if the signal is in ++ the set, 0 if not, and -1 if there is an error. <br> The ++ following errno error condition is defined for this function: ++ <br> @table @code @item EINVAL The signum argument doesn't ++ specify a valid signal. @end table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The sigprocmask function is used to examine or change the ++ calling process's signal mask. The how argument determines how ++ the signal mask is changed, and must be one of the following ++ values: <br> @table @code @vindex SIG_BLOCK @item ++ SIG_BLOCK Block the signals in set---add them to the existing ++ mask. In other words, the new mask is the union of the existing ++ mask and set. <br> @vindex SIG_UNBLOCK @item SIG_UNBLOCK ++ Unblock the signals in set---remove them from the existing mask. ++ <br> @vindex SIG_SETMASK @item SIG_SETMASK Use set for the ++ mask; ignore the previous value of the mask. @end table ++ <br> The last argument, oldset, 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 oldset argument. Similarly, if you want to know what's in ++ the mask without changing it, pass a null pointer for set (in ++ this case the how argument is not significant). The oldset ++ argument is often used to remember the previous signal mask in ++ order to restore it later. (Since the signal mask is inherited ++ over fork and exec calls, you can't predict what its contents ++ are when your program starts running.) <br> If invoking ++ sigprocmask causes any pending signals to be unblocked, at least ++ one of those signals is delivered to the process before ++ sigprocmask returns. The order in which pending signals are ++ delivered is not specified, but you can control the order ++ explicitly by making multiple sigprocmask calls to unblock ++ various signals one at a time. <br> The sigprocmask ++ function returns 0 if successful, and -1 to indicate an error. ++ The following errno error conditions are defined for this ++ function: <br> @table @code @item EINVAL The how argument ++ is invalid. @end table <br> You can't block the SIGKILL ++ and SIGSTOP signals, but if the signal set includes these, ++ sigprocmask just ignores them instead of returning an error ++ status. <br> Remember, too, that blocking program error ++ signals such as SIGFPE leads to undesirable results for signals ++ generated by an actual program error (as opposed to signals sent ++ with raise or kill). This is because your program may be too ++ broken to be able to continue executing to a point where the ++ signal is unblocked again. . ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The sigpending function stores information about pending signals ++ in set. 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 sigismember; see Signal Sets.) <br> The return ++ value is 0 if successful, and -1 on failure. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The pause function suspends program execution until a signal ++ arrives whose action is either to execute a handler function, or ++ to terminate the process. <br> If the signal causes a ++ handler function to be executed, then pause returns. This is ++ considered an unsuccessful return (since ``successful'' behavior ++ would be to suspend the program forever), so the return value is ++ -1. Even if you specify that other primitives should resume ++ when a system handler returns (Interrupted Primitives), this has ++ no effect on pause; it always fails when a signal is handled. ++ <br> The following errno error conditions are defined for ++ this function: <br> @table @code @item EINTR The function ++ was interrupted by delivery of a signal. @end table <br> ++ If the signal causes program termination, pause doesn't return ++ (obviously). <br> This function is a cancellation point in ++ multithreaded programs. This is a problem if the thread ++ allocates some resources (like memory, file descriptors, ++ semaphores or whatever) at the time pause is called. If the ++ thread gets cancelled these resources stay allocated until the ++ program ends. To avoid this calls to pause should be protected ++ using cancellation handlers. @c ref pthread_cleanup_push / ++ pthread_cleanup_pop <br> The pause function is declared in ++ unistd.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function replaces the process's signal mask with set 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 set ++ arrives. <br> If the process is woken up by delivery of a ++ signal that invokes a handler function, and the handler function ++ returns, then sigsuspend also returns. <br> The mask ++ remains set only as long as sigsuspend is waiting. The function ++ sigsuspend always restores the previous signal mask when it ++ returns. <br> The return value and error conditions are ++ the same as for pause. ++ ++ ++ ++ ++ ++ ++ This structure describes a signal stack. It contains the ++ following members: <br> ++ ++ ++ ++ ++ This points to the base of the signal stack. <br> ++ ++ ++ ++ ++ This is the size (in bytes) of the signal stack which ss_sp ++ points to. You should set this to however much space you ++ allocated for the stack. <br> There are two macros defined ++ in signal.h that you should use in calculating this size: ++ <br> @vtable @code ++ ++ ++ ++ ++ This is the canonical size for a signal stack. It is judged to ++ be sufficient for normal uses. <br> ++ ++ ++ ++ ++ This is the amount of signal stack space the operating system ++ needs just to implement signal delivery. The size of a signal ++ stack must be greater than this. <br> For most cases, just ++ using SIGSTKSZ for ss_size 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 MINSIGSTKSZ additional bytes for the signal stack and ++ increase ss_size accordingly. @end vtable <br> ++ ++ ++ ++ ++ This field contains the bitwise or of these flags: <br> ++ @vtable @code ++ ++ ++ ++ ++ This tells the system that it should not use the signal stack. ++ <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The sigaltstack function specifies an alternate stack for use ++ during signal handling. When a signal is received by the ++ process and its action indicates that the signal stack is used, ++ the system arranges a switch to the currently installed signal ++ stack while the handler for that signal is executed. <br> ++ If oldstack is not a null pointer, information about the ++ currently installed signal stack is returned in the location it ++ points to. If stack is not a null pointer, then this is ++ installed as the new stack for use by signal handlers. ++ <br> The return value is 0 on success and -1 on failure. ++ If sigaltstack fails, it sets errno to one of these values: ++ <br> @table @code @item EINVAL You tried to disable a ++ stack that was in fact currently in use. <br> @item ENOMEM ++ The size of the alternate stack was too small. It must be ++ greater than MINSIGSTKSZ. @end table ++ ++ ++ ++ ++ ++ ++ This structure describes a signal stack. It contains the ++ following members: <br> ++ ++ ++ ++ ++ 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. ++ <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The sigstack function specifies an alternate stack for use ++ during signal handling. When a signal is received by the ++ process and its action indicates that the signal stack is used, ++ the system arranges a switch to the currently installed signal ++ stack while the handler for that signal is executed. <br> ++ If oldstack is not a null pointer, information about the ++ currently installed signal stack is returned in the location it ++ points to. If stack is not a null pointer, then this is ++ installed as the new stack for use by signal handlers. ++ <br> The return value is 0 on success and -1 on failure. ++ ++ ++ ++ ++ ++ ++ This data type is the BSD equivalent of struct sigaction ++ (Advanced Signal Handling); it is used to specify signal actions ++ to the sigvec function. It contains the following members: ++ <br> ++ ++ ++ ++ ++ This is the handler function. <br> ++ ++ ++ ++ ++ This is the mask of additional signals to be blocked while the ++ handler function is being called. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is the equivalent of sigaction (Advanced Signal ++ Handling); it installs the action action for the signal signum, ++ returning information about the previous action in effect for ++ that signal in old-action. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function specifies which approach to use when certain ++ primitives are interrupted by handling signal signum. If ++ failflag is false, signal signum restarts primitives. If ++ failflag is true, handling signum causes these primitives to ++ fail with error code EINTR. . ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is equivalent to sigprocmask (Process Signal Mask) ++ with a how argument of SIG_BLOCK: it adds the signals specified ++ by mask to the calling process's set of blocked signals. The ++ return value is the previous set of blocked signals. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function equivalent to sigprocmask (Process Signal Mask) ++ with a how argument of SIG_SETMASK: it sets the calling ++ process's signal mask to mask. The return value is the previous ++ set of blocked signals. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is the equivalent of sigsuspend (Waiting for a ++ Signal): it sets the calling process's signal mask to mask, and ++ waits for a signal to arrive. On return the previous set of ++ blocked signals is restored. ++ ++ ++ ++ ++ ++ ++ The struct sockaddr type itself has the following members: ++ <br> ++ ++ ++ ++ ++ This is the code for the address format of this address. It ++ identifies the format of the data which follows. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The bind function assigns an address to the socket socket. The ++ addr and length arguments specify the address; the detailed ++ format of the address depends on the namespace. The first part ++ of the address is always the format designator, which specifies ++ a namespace, and says that the address is in the format of that ++ namespace. <br> The return value is 0 on success and -1 on ++ failure. The following errno error conditions are defined for ++ this function: <br> @table @code @item EBADF The socket ++ argument is not a valid file descriptor. <br> @item ++ ENOTSOCK The descriptor socket is not a socket. <br> @item ++ EADDRNOTAVAIL The specified address is not available on this ++ machine. <br> @item EADDRINUSE Some other socket is ++ already using the specified address. <br> @item EINVAL The ++ socket socket already has an address. <br> @item 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 IPPORT_RESERVED minus one; ++ see Ports.) @end table <br> Additional conditions may be ++ possible depending on the particular namespace of the socket. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The getsockname function returns information about the address ++ of the socket socket in the locations specified by the addr and ++ length-ptr arguments. Note that the length-ptr is a pointer; ++ you should initialize it to be the allocation size of addr, and ++ on return it contains the actual size of the address data. ++ <br> The format of the address data depends on the socket ++ namespace. The length of the information is usually fixed for a ++ given namespace, so normally you can know exactly how much space ++ is needed and can provide that much. The usual practice is to ++ allocate a place for the value using the proper data type for ++ the socket's namespace, then cast its address to struct sockaddr ++ * to pass it to getsockname. <br> The return value is 0 on ++ success and -1 on error. The following errno error conditions ++ are defined for this function: <br> @table @code @item ++ EBADF The socket argument is not a valid file descriptor. ++ <br> @item ENOTSOCK The descriptor socket is not a socket. ++ <br> @item ENOBUFS There are not enough internal buffers ++ available for the operation. @end table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function yields the interface index corresponding to a ++ particular name. If no interface exists with the name given, it ++ returns 0. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function maps an interface index to its corresponding name. ++ The returned name is placed in the buffer pointed to by ifname, ++ which must be at least IFNAMSIZ bytes in length. If the index ++ was invalid, the function's return value is a null pointer, ++ otherwise it is ifname. ++ ++ ++ ++ ++ ++ ++ This data type is used to hold the information about a single ++ interface. It has the following members: <br> ++ ++ ++ ++ ++ This is the interface index. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function returns an array of if_nameindex structures, one ++ for every interface that is present. The end of the list is ++ indicated by a structure with an interface of 0 and a null name ++ pointer. If an error occurs, this function returns a null ++ pointer. <br> The returned structure must be freed with ++ if_freenameindex after use. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function frees the structure returned by an earlier call to ++ if_nameindex. ++ ++ ++ ++ ++ ++ ++ This structure is used to specify local namespace socket ++ addresses. It has the following members: <br> ++ ++ ++ ++ ++ This identifies the address family or format of the socket ++ address. You should store the value AF_LOCAL to designate the ++ local namespace. . <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ This is the data type used to represent socket addresses in the ++ Internet namespace. It has the following members: <br> ++ ++ ++ ++ ++ This identifies the address family or format of the socket ++ address. You should store the value AF_INET in this member. . ++ <br> ++ ++ ++ ++ ++ This is the Internet address of the host machine. , and Host ++ Names, for how to get a value to store here. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ This is the data type used to represent socket addresses in the ++ IPv6 namespace. It has the following members: <br> ++ ++ ++ ++ ++ This identifies the address family or format of the socket ++ address. You should store the value of AF_INET6 in this member. ++ . <br> ++ ++ ++ ++ ++ This is the IPv6 address of the host machine. , and Host Names, ++ for how to get a value to store here. <br> ++ ++ ++ ++ ++ This is a currently unimplemented field. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++
++
++
++ ++ ++ This function converts the IPv4 Internet host address name from ++ the standard numbers-and-dots notation into binary data and ++ stores it in the struct in_addr that addr points to. inet_aton ++ returns nonzero if the address is valid, zero if not. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function converts the IPv4 Internet host address name from ++ the standard numbers-and-dots notation into binary data. If the ++ input is not valid, inet_addr returns INADDR_NONE. This is an ++ obsolete interface to inet_aton, described immediately above. It ++ is obsolete because INADDR_NONE is a valid address ++ (255.255.255.255), and inet_aton provides a cleaner way to ++ indicate error return. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function extracts the network number from the address name, ++ given in the standard numbers-and-dots notation. The returned ++ address is in host order. If the input is not valid, ++ inet_network returns -1. <br> The function works only with ++ traditional IPv4 class A, B and C network types. It doesn't ++ work with classless addresses and shouldn't be used anymore. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function converts the IPv4 Internet host address addr to a ++ string in the standard numbers-and-dots notation. The return ++ value is a pointer into a statically-allocated buffer. ++ Subsequent calls will overwrite the same buffer, so you should ++ copy the string if you need to save it. <br> In ++ multi-threaded programs each thread has an own ++ statically-allocated buffer. But still subsequent calls of ++ inet_ntoa in the same thread will overwrite the result of the ++ last call. <br> Instead of inet_ntoa the newer function ++ inet_ntop which is described below should be used since it ++ handles both IPv4 and IPv6 addresses. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function makes an IPv4 Internet host address by combining ++ the network number net with the local-address-within-network ++ number local. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function returns the local-address-within-network part of ++ the Internet host address addr. <br> The function works ++ only with traditional IPv4 class A, B and C network types. It ++ doesn't work with classless addresses and shouldn't be used ++ anymore. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function returns the network number part of the Internet ++ host address addr. <br> The function works only with ++ traditional IPv4 class A, B and C network types. It doesn't ++ work with classless addresses and shouldn't be used anymore. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function converts an Internet address (either IPv4 or IPv6) ++ from presentation (textual) to network (binary) format. af ++ should be either AF_INET or AF_INET6, as appropriate for the ++ type of address being converted. cp is a pointer to the input ++ string, and buf is a pointer to a buffer for the result. It is ++ the caller's responsibility to make sure the buffer is large ++ enough. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function converts an Internet address (either IPv4 or IPv6) ++ from network (binary) to presentation (textual) form. af should ++ be either AF_INET or AF_INET6, as appropriate. cp is a pointer ++ to the address to be converted. buf should be a pointer to a ++ buffer to hold the result, and len is the length of this buffer. ++ The return value from the function will be this buffer address. ++ ++ ++ ++ ++ ++ ++ This data type is used to represent an entry in the hosts ++ database. It has the following members: <br> ++ ++ ++ ++ ++ This is the ``official'' name of the host. <br> ++ ++ ++ ++ ++ These are alternative names for the host, represented as a ++ null-terminated vector of strings. <br> ++ ++ ++ ++ ++ This is the host address type; in practice, its value is always ++ either AF_INET or AF_INET6, 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 ++ AF_INET or AF_INET6. . <br> ++ ++ ++ ++ ++ This is the length, in bytes, of each address. <br> ++ ++ ++ ++ ++ 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. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The gethostbyname function returns information about the host ++ named name. If the lookup fails, it returns a null pointer. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The gethostbyname2 function is like gethostbyname, but allows ++ the caller to specify the desired address family (e.g.@: AF_INET ++ or AF_INET6) of the result. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The gethostbyaddr function returns information about the host ++ with Internet address addr. The parameter addr is not really a ++ pointer to char - it can be a pointer to an IPv4 or an IPv6 ++ address. The length argument is the size (in bytes) of the ++ address at addr. format specifies the address format; for an ++ IPv4 Internet address, specify a value of AF_INET; for an IPv6 ++ Internet address, use AF_INET6. <br> If the lookup fails, ++ gethostbyaddr returns a null pointer. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The gethostbyname_r function returns information about the host ++ named name. The caller must pass a pointer to an object of type ++ struct hostent in the result_buf 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 buf and buflen ++ parameters. <br> A pointer to the buffer, in which the ++ result is stored, is available in *result after the function ++ call successfully returned. If an error occurs or if no entry ++ is found, the pointer *result 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 gethostbyname it can also be ERANGE. In this case ++ the call should be repeated with a larger buffer. Additional ++ error information is not stored in the global variable h_errno ++ but instead in the object pointed to by h_errnop. <br> ++ Here's a small example: @smallexample struct hostent * ++ gethostname (char *host) struct hostent hostbuf, *hp; ++ size_t hstbuflen; char *tmphstbuf; int res; int herr; ++ <br> hstbuflen = 1024; /* Allocate buffer, remember to ++ free it to avoid memory leakage. */ tmphstbuf = malloc ++ (hstbuflen); <br> while ((res = gethostbyname_r (host, ++ &hostbuf, tmphstbuf, hstbuflen, ++ &hp, &herr)) == ERANGE) /* Enlarge the ++ buffer. */ hstbuflen *= 2; tmphstbuf = realloc ++ (tmphstbuf, hstbuflen); @ /* Check for errors. */ if ++ (res || hp == NULL) return NULL; return hp; @ @end ++ smallexample ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The gethostbyname2_r function is like gethostbyname_r, but ++ allows the caller to specify the desired address family (e.g.@: ++ AF_INET or AF_INET6) for the result. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The gethostbyaddr_r function returns information about the host ++ with Internet address addr. The parameter addr is not really a ++ pointer to char - it can be a pointer to an IPv4 or an IPv6 ++ address. The length argument is the size (in bytes) of the ++ address at addr. format specifies the address format; for an ++ IPv4 Internet address, specify a value of AF_INET; for an IPv6 ++ Internet address, use AF_INET6. <br> Similar to the ++ gethostbyname_r 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 ERANGE has the special meaning that the caller-provided ++ buffer is too small. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function opens the hosts database to begin scanning it. ++ You can then call gethostent to read the entries. <br> @c ++ There was a rumor that this flag has different meaning if using ++ the DNS, @c but it appears this description is accurate in that ++ case also. If the stayopen argument is nonzero, this sets a flag ++ so that subsequent calls to gethostbyname or gethostbyaddr 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. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function returns the next entry in the hosts database. It ++ returns a null pointer if there are no more entries. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function closes the hosts database. ++ ++ ++ ++ ++ ++ ++ This data type holds information about entries from the services ++ database. It has the following members: <br> ++ ++ ++ ++ ++ This is the ``official'' name of the service. <br> ++ ++ ++ ++ ++ These are alternate names for the service, represented as an ++ array of strings. A null pointer terminates the array. ++ <br> ++ ++ ++ ++ ++ This is the port number for the service. Port numbers are given ++ in network byte order; see Byte Order. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++
++ ++ ++ The getservbyname function returns information about the service ++ named name using protocol proto. If it can't find such a ++ service, it returns a null pointer. <br> This function is ++ useful for servers as well as for clients; servers use it to ++ determine which port they should listen on (Listening). ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The getservbyport function returns information about the service ++ at port port using protocol proto. If it can't find such a ++ service, it returns a null pointer. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function opens the services database to begin scanning it. ++ <br> If the stayopen argument is nonzero, this sets a flag ++ so that subsequent calls to getservbyname or getservbyport 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. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function returns the next entry in the services database. ++ If there are no more entries, it returns a null pointer. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function closes the services database. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function converts the uint16_t integer hostshort from host ++ byte order to network byte order. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function converts the uint16_t integer netshort from ++ network byte order to host byte order. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function converts the uint32_t integer hostlong from host ++ byte order to network byte order. <br> This is used for ++ IPv4 Internet addresses. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function converts the uint32_t integer netlong from network ++ byte order to host byte order. <br> This is used for IPv4 ++ Internet addresses. ++ ++ ++ ++ ++ ++ ++ This data type is used to represent entries in the network ++ protocols database. It has the following members: <br> ++ ++ ++ ++ ++ This is the official name of the protocol. <br> ++ ++ ++ ++ ++ These are alternate names for the protocol, specified as an ++ array of strings. The last element of the array is a null ++ pointer. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The getprotobyname function returns information about the ++ network protocol named name. If there is no such protocol, it ++ returns a null pointer. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The getprotobynumber function returns information about the ++ network protocol with number protocol. If there is no such ++ protocol, it returns a null pointer. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function opens the protocols database to begin scanning it. ++ <br> If the stayopen argument is nonzero, this sets a flag ++ so that subsequent calls to getprotobyname or getprotobynumber ++ 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. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function returns the next entry in the protocols database. ++ It returns a null pointer if there are no more entries. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function closes the protocols database. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function creates a socket and specifies communication style ++ style, which should be one of the socket styles listed in ++ Communication Styles. The namespace argument specifies the ++ namespace; it must be PF_LOCAL (Local Namespace) or PF_INET ++ (Internet Namespace). protocol designates the specific protocol ++ (Socket Concepts); zero is usually right for protocol. ++ <br> The return value from socket is the file descriptor ++ for the new socket, or -1 in case of error. The following errno ++ error conditions are defined for this function: <br> ++ @table @code @item EPROTONOSUPPORT The protocol or style is not ++ supported by the namespace specified. <br> @item EMFILE ++ The process already has too many file descriptors open. ++ <br> @item ENFILE The system already has too many file ++ descriptors open. <br> @item EACCES The process does not ++ have the privilege to create a socket of the specified style or ++ protocol. <br> @item ENOBUFS The system ran out of ++ internal buffer space. @end table <br> The file descriptor ++ returned by the socket function supports both read and write ++ operations. However, like pipes, sockets do not support file ++ positioning operations. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The shutdown function shuts down the connection of socket ++ socket. The argument how specifies what action to perform: ++ <br> @table @code @item 0 Stop receiving data for this ++ socket. If further data arrives, reject it. <br> @item 1 ++ Stop trying to transmit data from this socket. Discard any data ++ waiting to be sent. Stop looking for acknowledgement of data ++ already sent; don't retransmit it if it is lost. <br> ++ @item 2 Stop both reception and transmission. @end table ++ <br> The return value is 0 on success and -1 on failure. ++ The following errno error conditions are defined for this ++ function: <br> @table @code @item EBADF socket is not a ++ valid file descriptor. <br> @item ENOTSOCK socket is not a ++ socket. <br> @item ENOTCONN socket is not connected. @end ++ table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function creates a socket pair, returning the file ++ descriptors in filedes[0] and filedes[1]. The socket pair is a ++ full-duplex communications channel, so that both reading and ++ writing may be performed at either end. <br> The ++ namespace, style and protocol arguments are interpreted as for ++ the socket function. style should be one of the communication ++ styles listed in Communication Styles. The namespace argument ++ specifies the namespace, which must be AF_LOCAL (Local ++ Namespace); protocol specifies the communications protocol, but ++ zero is the only meaningful value. <br> If style specifies ++ a connectionless communication style, then the two sockets you ++ get are not connected, strictly speaking, but each of them knows ++ the other as the default destination address, so they can send ++ packets to each other. <br> The socketpair function ++ returns 0 on success and -1 on failure. The following errno ++ error conditions are defined for this function: <br> ++ @table @code @item EMFILE The process has too many file ++ descriptors open. <br> @item EAFNOSUPPORT The specified ++ namespace is not supported. <br> @item EPROTONOSUPPORT The ++ specified protocol is not supported. <br> @item EOPNOTSUPP ++ The specified protocol does not support the creation of socket ++ pairs. @end table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The connect function initiates a connection from the socket with ++ file descriptor socket to the socket whose address is specified ++ by the addr and length arguments. (This socket is typically on ++ another machine, and it must be already set up as a server.) , ++ for information about how these arguments are interpreted. ++ <br> Normally, connect waits until the server responds to ++ the request before it returns. You can set nonblocking mode on ++ the socket socket to make connect return immediately without ++ waiting for the response. , for information about nonblocking ++ mode. @c !!! how do you tell when it has finished connecting? I ++ suspect the @c way you do it is select for writing. <br> ++ The normal return value from connect is 0. If an error occurs, ++ connect returns -1. The following errno error conditions are ++ defined for this function: <br> @table @code @item EBADF ++ The socket socket is not a valid file descriptor. <br> ++ @item ENOTSOCK File descriptor socket is not a socket. ++ <br> @item EADDRNOTAVAIL The specified address is not ++ available on the remote machine. <br> @item EAFNOSUPPORT ++ The namespace of the addr is not supported by this socket. ++ <br> @item EISCONN The socket socket is already connected. ++ <br> @item ETIMEDOUT The attempt to establish the ++ connection timed out. <br> @item ECONNREFUSED The server ++ has actively refused to establish the connection. <br> ++ @item ENETUNREACH The network of the given addr isn't reachable ++ from this host. <br> @item EADDRINUSE The socket address ++ of the given addr is already in use. <br> @item ++ EINPROGRESS The socket socket is non-blocking and the connection ++ could not be established immediately. You can determine when ++ the connection is completely established with select; Waiting ++ for I/O. Another connect call on the same socket, before the ++ connection is completely established, will fail with EALREADY. ++ <br> @item EALREADY The socket socket is non-blocking and ++ already has a pending connection in progress (see EINPROGRESS ++ above). @end table <br> This function is defined as a ++ cancellation point in multi-threaded programs, so one has to be ++ prepared for this and make sure that allocated resources (like ++ memory, files descriptors, semaphores or whatever) are freed ++ even if the thread is canceled. @c , for a method how to do ++ this. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The listen function enables the socket socket to accept ++ connections, thus making it a server socket. <br> The ++ argument n specifies the length of the queue for pending ++ connections. When the queue fills, new clients attempting to ++ connect fail with ECONNREFUSED until the server calls accept to ++ accept a connection from the queue. <br> The listen ++ function returns 0 on success and -1 on failure. The following ++ errno error conditions are defined for this function: <br> ++ @table @code @item EBADF The argument socket is not a valid file ++ descriptor. <br> @item ENOTSOCK The argument socket is not ++ a socket. <br> @item EOPNOTSUPP The socket socket does not ++ support this operation. @end table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is used to accept a connection request on the ++ server socket socket. <br> The accept function waits if ++ there are no connections pending, unless the socket socket has ++ nonblocking mode set. (You can use select to wait for a pending ++ connection, with a nonblocking socket.) , for information about ++ nonblocking mode. <br> The addr and length-ptr arguments ++ are used to return information about the name of the client ++ socket that initiated the connection. , for information about ++ the format of the information. <br> Accepting a connection ++ does not make socket part of the connection. Instead, it ++ creates a new socket which becomes connected. The normal return ++ value of accept is the file descriptor for the new socket. ++ <br> After accept, the original socket socket remains open ++ and unconnected, and continues listening until you close it. ++ You can accept further connections with socket by calling accept ++ again. <br> If an error occurs, accept returns -1. The ++ following errno error conditions are defined for this function: ++ <br> @table @code @item EBADF The socket argument is not a ++ valid file descriptor. <br> @item ENOTSOCK The descriptor ++ socket argument is not a socket. <br> @item EOPNOTSUPP The ++ descriptor socket does not support this operation. <br> ++ @item EWOULDBLOCK socket has nonblocking mode set, and there are ++ no pending connections immediately available. @end table ++ <br> This function is defined as a cancellation point in ++ multi-threaded programs, so one has to be prepared for this and ++ make sure that allocated resources (like memory, files ++ descriptors, semaphores or whatever) are freed even if the ++ thread is canceled. @c , for a method how to do this. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The getpeername function returns the address of the socket that ++ socket is connected to; it stores the address in the memory ++ space specified by addr and length-ptr. It stores the length of ++ the address in *length-ptr. <br> , for information about ++ the format of the address. In some operating systems, ++ getpeername works only for sockets in the Internet domain. ++ <br> The return value is 0 on success and -1 on error. ++ The following errno error conditions are defined for this ++ function: <br> @table @code @item EBADF The argument ++ socket is not a valid file descriptor. <br> @item ENOTSOCK ++ The descriptor socket is not a socket. <br> @item ENOTCONN ++ The socket socket is not connected. <br> @item ENOBUFS ++ There are not enough internal buffers available. @end table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The send function is like write, but with the additional flags ++ flags. The possible values of flags are described in Socket ++ Data Options. <br> This function returns the number of ++ bytes transmitted, or -1 on failure. If the socket is ++ nonblocking, then send (like write) can return after sending ++ just part of the data. , for information about nonblocking mode. ++ <br> Note, however, that a successful return value merely ++ indicates that the message has been sent without error, not ++ necessarily that it has been received without error. <br> ++ The following errno error conditions are defined for this ++ function: <br> @table @code @item EBADF The socket ++ argument is not a valid file descriptor. <br> @item EINTR ++ The operation was interrupted by a signal before any data was ++ sent. . <br> @item ENOTSOCK The descriptor socket is not a ++ socket. <br> @item EMSGSIZE The socket type requires that ++ the message be sent atomically, but the message is too large for ++ this to be possible. <br> @item EWOULDBLOCK Nonblocking ++ mode has been set on the socket, and the write operation would ++ block. (Normally send blocks until the operation can be ++ completed.) <br> @item ENOBUFS There is not enough ++ internal buffer space available. <br> @item ENOTCONN You ++ never connected this socket. <br> @item EPIPE This socket ++ was connected but the connection is now broken. In this case, ++ send generates a SIGPIPE signal first; if that signal is ignored ++ or blocked, or if its handler returns, then send fails with ++ EPIPE. @end table <br> This function is defined as a ++ cancellation point in multi-threaded programs, so one has to be ++ prepared for this and make sure that allocated resources (like ++ memory, files descriptors, semaphores or whatever) are freed ++ even if the thread is canceled. @c , for a method how to do ++ this. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The recv function is like read, but with the additional flags ++ flags. The possible values of flags are described in Socket ++ Data Options. <br> If nonblocking mode is set for socket, ++ and no data are available to be read, recv fails immediately ++ rather than waiting. , for information about nonblocking mode. ++ <br> This function returns the number of bytes received, ++ or -1 on failure. The following errno error conditions are ++ defined for this function: <br> @table @code @item EBADF ++ The socket argument is not a valid file descriptor. <br> ++ @item ENOTSOCK The descriptor socket is not a socket. <br> ++ @item EWOULDBLOCK Nonblocking mode has been set on the socket, ++ and the read operation would block. (Normally, recv blocks ++ until there is input available to be read.) <br> @item ++ EINTR The operation was interrupted by a signal before any data ++ was read. . <br> @item ENOTCONN You never connected this ++ socket. @end table <br> This function is defined as a ++ cancellation point in multi-threaded programs, so one has to be ++ prepared for this and make sure that allocated resources (like ++ memory, files descriptors, semaphores or whatever) are freed ++ even if the thread is canceled. @c , for a method how to do ++ this. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The sendto function transmits the data in the buffer through the ++ socket socket to the destination address specified by the addr ++ and length arguments. The size argument specifies the number of ++ bytes to be transmitted. <br> The flags are interpreted ++ the same way as for send; see Socket Data Options. <br> ++ The return value and error conditions are also the same as for ++ send, but you cannot rely on the system to detect errors and ++ report them; the most common error is that the packet is lost or ++ there is no-one at the specified address to receive it, and the ++ operating system on your machine usually does not know this. ++ <br> It is also possible for one call to sendto to report ++ an error owing to a problem related to a previous call. ++ <br> This function is defined as a cancellation point in ++ multi-threaded programs, so one has to be prepared for this and ++ make sure that allocated resources (like memory, files ++ descriptors, semaphores or whatever) are freed even if the ++ thread is canceled. @c , for a method how to do this. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The recvfrom function reads one packet from the socket socket ++ into the buffer buffer. The size argument specifies the maximum ++ number of bytes to be read. <br> If the packet is longer ++ than size bytes, then you get the first size bytes of the packet ++ and the rest of the packet is lost. There's no way to read the ++ rest of the packet. Thus, when you use a packet protocol, you ++ must always know how long a packet to expect. <br> The ++ addr and length-ptr 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 (Local Namespace). You can ++ specify a null pointer as the addr argument if you are not ++ interested in this information. <br> The flags are ++ interpreted the same way as for recv (Socket Data Options). The ++ return value and error conditions are also the same as for recv. ++ <br> This function is defined as a cancellation point in ++ multi-threaded programs, so one has to be prepared for this and ++ make sure that allocated resources (like memory, files ++ descriptors, semaphores or whatever) are freed even if the ++ thread is canceled. @c , for a method how to do this. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> This function is defined as a cancellation point in ++ multi-threaded programs, so one has to be prepared for this and ++ make sure that allocated resources (like memory, files ++ descriptors, semaphores or whatever) are freed even if the ++ thread is cancel. @c , for a method how to do this. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> This function is defined as a cancellation point in ++ multi-threaded programs, so one has to be prepared for this and ++ make sure that allocated resources (like memory, files ++ descriptors, semaphores or whatever) are freed even if the ++ thread is canceled. @c , for a method how to do this. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The getsockopt function gets information about the value of ++ option optname at level level for socket socket. <br> The ++ option value is stored in a buffer that optval points to. Before ++ the call, you should supply in *optlen-ptr the size of this ++ buffer; on return, it contains the number of bytes of ++ information actually stored in the buffer. <br> Most ++ options interpret the optval buffer as a single int value. ++ <br> The actual return value of getsockopt is 0 on success ++ and -1 on failure. The following errno error conditions are ++ defined: <br> @table @code @item EBADF The socket argument ++ is not a valid file descriptor. <br> @item ENOTSOCK The ++ descriptor socket is not a socket. <br> @item ENOPROTOOPT ++ The optname doesn't make sense for the given level. @end table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is used to set the socket option optname at level ++ level for socket socket. The value of the option is passed in ++ the buffer optval of size optlen. <br> @c Argh. -zw @iftex ++ @hfuzz 6pt The return value and error codes for setsockopt are ++ the same as for getsockopt. @end iftex @ifinfo The return value ++ and error codes for setsockopt are the same as for getsockopt. ++ @end ifinfo <br> ++ ++ ++ ++ ++ ++ ++ This structure type has the following members: <br> ++ ++ ++ ++ ++ This field is interpreted as a boolean. If nonzero, close ++ blocks until the data are transmitted or the timeout period has ++ expired. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ This data type is used to represent information about entries in ++ the networks database. It has the following members: <br> ++ ++ ++ ++ ++ This is the ``official'' name of the network. <br> ++ ++ ++ ++ ++ These are alternative names for the network, represented as a ++ vector of strings. A null pointer terminates the array. ++ <br> ++ ++ ++ ++ ++ This is the type of the network number; this is always equal to ++ AF_INET for Internet networks. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++
++ ++ ++ The getnetbyname function returns information about the network ++ named name. It returns a null pointer if there is no such ++ network. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The getnetbyaddr function returns information about the network ++ of type type with number net. You should specify a value of ++ AF_INET for the type argument for Internet networks. <br> ++ getnetbyaddr returns a null pointer if there is no such network. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function opens and rewinds the networks database. ++ <br> If the stayopen argument is nonzero, this sets a flag ++ so that subsequent calls to getnetbyname or getnetbyaddr 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. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function returns the next entry in the networks database. ++ It returns a null pointer if there are no more entries. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function closes the networks database. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> The optionp parameter must be a pointer to a variable ++ containing the address of the string to process. When the ++ function returns the reference is updated to point to the next ++ suboption or to the terminating \0 character if there is no more ++ suboption available. <br> The tokens parameter references ++ an array of strings containing the known suboptions. All ++ strings must be \0 terminated and to mark the end a null pointer ++ must be stored. When getsubopt finds a possible legal suboption ++ it compares it with all strings available in the tokens array ++ and returns the index in the string as the indicator. <br> ++ In case the suboption has an associated value introduced by a = ++ character, a pointer to the value is returned in valuep. The ++ string is \0 terminated. If no argument is available valuep is ++ set to the null pointer. By doing this the caller can check ++ whether a necessary value is given or whether no unexpected ++ value is present. <br> In case the next suboption in the ++ string is not mentioned in the tokens array the starting address ++ of the suboption including a possible value is returned in ++ valuep and the return value of the function is -1. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function returns a string that is the value of the ++ environment variable name. You must not modify this string. In ++ some non-Unix systems not using the GNU library, it might be ++ overwritten by subsequent calls to getenv (but not by any other ++ library function). If the environment variable name is not ++ defined, the value is a null pointer. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The putenv function adds or removes definitions from the ++ environment. If the string is of the form name=value, the ++ definition is added to the environment. Otherwise, the string ++ is interpreted as the name of an environment variable, and any ++ definition for this variable in the environment is removed. ++ <br> The difference to the setenv function is that the ++ exact string given as the parameter string is put into the ++ environment. If the user should change the string after the ++ putenv call this will reflect in automatically in the ++ environment. This also requires that string is no automatic ++ variable which scope is left before the variable is removed from ++ the environment. The same applies of course to dynamically ++ allocated variables which are freed later. <br> This ++ function is part of the extended Unix interface. Since it was ++ also available in old SVID libraries you should define either ++ _XOPEN_SOURCE or _SVID_SOURCE before including any header. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The setenv function can be used to add a new definition to the ++ environment. The entry with the name name is replaced by the ++ value name=value. Please note that this is also true if value ++ is the empty string. To do this a new string is created and the ++ strings name and value are copied. A null pointer for the value ++ parameter is illegal. If the environment already contains an ++ entry with key name the replace parameter controls the action. ++ If replace is zero, nothing happens. Otherwise the old entry is ++ replaced by the new one. <br> Please note that you cannot ++ remove an entry completely using this function. <br> This ++ function was originally part of the BSD library but is now part ++ of the Unix standard. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ Using this function one can remove an entry completely from the ++ environment. If the environment contains an entry with the key ++ name this whole entry is removed. A call to this function is ++ equivalent to a call to putenv when the value part of the string ++ is empty. <br> The function return -1 if name is a null ++ pointer, points to an empty string, or points to a string ++ containing a = character. It returns 0 if the call succeeded. ++ <br> This function was originally part of the BSD library ++ but is now part of the Unix standard. The BSD version had no ++ return value, though. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The clearenv function removes all entries from the environment. ++ Using putenv and setenv new entries can be added again later. ++ <br> If the function is successful it returns 0. ++ Otherwise the return value is nonzero. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> syscall performs a generic system call. <br> ++ @cindex system call number sysno is the system call number. ++ Each kind of system call is identified by a number. Macros for ++ all the possible system call numbers are defined in ++ sys/syscall.h <br> The remaining arguments are the ++ arguments for the system call, in order, and their meanings ++ depend on the kind of system call. Each kind of system call has ++ a definite number of arguments, from zero to five. If you code ++ more arguments than the system call takes, the extra ones to the ++ right are ignored. <br> The return value is the return ++ value from the system call, unless the system call failed. In ++ that case, syscall returns -1 and sets errno to an error code ++ that the system call returned. Note that system calls do not ++ return -1 when they succeed. @cindex errno <br> If you ++ specify an invalid sysno, syscall returns -1 with errno = ++ ENOSYS. <br> Example: <br> @smallexample <br> ++ #include <unistd.h> #include <sys/syscall.h> ++ #include <errno.h> <br> <br> int rc; ++ <br> rc = syscall(SYS_chmod, "/etc/passwd", 0444); ++ <br> if (rc == -1) fprintf(stderr, "chmod failed, errno ++ = %d\n", errno); <br> @end smallexample <br> This, ++ if all the compatibility stars are aligned, is equivalent to the ++ following preferable code: <br> @smallexample <br> ++ #include <sys/types.h> #include <sys/stat.h> ++ #include <errno.h> <br> <br> int rc; ++ <br> rc = chmod("/etc/passwd", 0444); if (rc == -1) ++ fprintf(stderr, "chmod failed, errno = %d\n", errno); <br> ++ @end smallexample <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The exit function tells the system that the program is done, ++ which causes it to terminate the process. <br> status is ++ the program's exit status, which becomes part of the process' ++ termination status. This function does not return. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The atexit function registers the function function to be called ++ at normal program termination. The function is called with no ++ arguments. <br> The return value from atexit is zero on ++ success and nonzero if the function cannot be registered. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is a somewhat more powerful variant of atexit. It ++ accepts two arguments, a function function and an arbitrary ++ pointer arg. At normal program termination, the function is ++ called with two arguments: the status value passed to exit, and ++ the arg. <br> This function is included in the GNU C ++ library only for compatibility for SunOS, and may not be ++ supported by other implementations. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The abort function causes abnormal program termination. This ++ does not execute cleanup functions registered with atexit or ++ on_exit. <br> This function actually terminates the ++ process by raising a SIGABRT signal, and your program can ++ include a handler to intercept this signal; see Signal Handling. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The _exit function is the primitive for causing a process to ++ terminate with status status. Calling this function does not ++ execute cleanup functions registered with atexit or on_exit. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The _Exit function is the ISO C equivalent to _exit. The ISO C ++ committee members were not sure whether the definitions of _exit ++ and _Exit were compatible so they have not used the POSIX name. ++ <br> This function was introduced in ISO C99 and is ++ declared in stdlib.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The fopen function opens a stream for I/O to the file filename, ++ and returns a pointer to the stream. <br> The opentype ++ argument is a string that controls how the file is opened and ++ specifies attributes of the resulting stream. It must begin ++ with one of the following sequences of characters: <br> ++ @table @samp @item r Open an existing file for reading only. ++ <br> @item w Open the file for writing only. If the file ++ already exists, it is truncated to zero length. Otherwise a new ++ file is created. <br> @item a Open a file for append ++ access; that is, writing at the end of file only. If the file ++ already exists, its initial contents are unchanged and output to ++ the stream is appended to the end of the file. Otherwise, a new, ++ empty file is created. <br> @item r+ Open an existing file ++ for both reading and writing. The initial contents of the file ++ are unchanged and the initial file position is at the beginning ++ of the file. <br> @item w+ Open a file for both reading ++ and writing. If the file already exists, it is truncated to ++ zero length. Otherwise, a new file is created. <br> @item ++ a+ Open or create file for both reading and appending. If the ++ file exists, its initial contents are unchanged. Otherwise, a ++ new file is created. The initial file position for reading is at ++ the beginning of the file, but output is always appended to the ++ end of the file. @end table <br> As you can see, + ++ requests a stream that can do both input and output. The ISO ++ standard says that when using such a stream, you must call ++ fflush (Stream Buffering) or a file positioning function such as ++ fseek (File Positioning) when switching from reading to writing ++ or vice versa. Otherwise, internal buffers might not be emptied ++ properly. The GNU C library does not have this limitation; you ++ can do arbitrary reading and writing operations on a stream in ++ whatever order. <br> Additional characters may appear ++ after these to specify flags for the call. Always put the mode ++ (r, w+, etc.) first; that is the only part you are guaranteed ++ will be understood by all systems. <br> The GNU C library ++ defines one additional character for use in opentype: the ++ character x insists on creating a new file---if a file filename ++ already exists, fopen fails rather than opening it. If you use ++ x you are guaranteed that you will not clobber an existing file. ++ This is equivalent to the O_EXCL option to the open function ++ (Opening and Closing Files). <br> The character b in ++ opentype has a standard meaning; it requests a binary stream ++ rather than a text stream. But this makes no difference in ++ POSIX systems (including the GNU system). If both + and b are ++ specified, they can appear in either order. . <br> @cindex ++ stream orientation @cindex orientation, stream If the opentype ++ string contains the sequence ,ccs=STRING then STRING is taken as ++ the name of a coded character set and fopen will mark the stream ++ as wide-oriented which appropriate conversion functions in place ++ to convert from and to the character set STRING is place. Any ++ other stream is opened initially unoriented and the orientation ++ is decided with the first file operation. If the first ++ operation is a wide character operation, the stream is not only ++ marked as wide-oriented, also the conversion functions to ++ convert to the coded character set used for the current locale ++ are loaded. This will not change anymore from this point on ++ even if the locale selected for the LC_CTYPE category is ++ changed. <br> Any other characters in opentype are simply ++ ignored. They may be meaningful in other systems. <br> If ++ the open fails, fopen returns a null pointer. <br> When ++ the sources are compiling with _FILE_OFFSET_BITS == 64 on a 32 ++ bit machine this function is in fact fopen64 since the LFS ++ interface replaces transparently the old interface. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to fopen but the stream it returns a ++ pointer for is opened using open64. Therefore this stream can ++ be used even on files larger then 2^31 bytes on 32 bit machines. ++ <br> Please note that the return type is still FILE *. ++ There is no special FILE type for the LFS interface. <br> ++ If the sources are compiled with _FILE_OFFSET_BITS == 64 on a 32 ++ bits machine this function is available under the name fopen and ++ so transparently replaces the old interface. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is like a combination of fclose and fopen. It ++ first closes the stream referred to by stream, ignoring any ++ errors that are detected in the process. (Because errors are ++ ignored, you should not use freopen on an output stream if you ++ have actually done any output using the stream.) Then the file ++ named by filename is opened with mode opentype as for fopen, and ++ associated with the same stream object stream. <br> If the ++ operation fails, a null pointer is returned; otherwise, freopen ++ returns stream. <br> freopen has traditionally been used ++ to connect a standard stream such as stdin with a file of your ++ own choice. This is useful in programs in which use of a ++ standard stream for certain purposes is hard-coded. In the GNU ++ C library, you can simply close the standard streams and open ++ new ones with fopen. But other systems lack this ability, so ++ using freopen is more portable. <br> When the sources are ++ compiling with _FILE_OFFSET_BITS == 64 on a 32 bit machine this ++ function is in fact freopen64 since the LFS interface replaces ++ transparently the old interface. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to freopen. The only difference is ++ that on 32 bit machine the stream returned is able to read ++ beyond the 2^31 bytes limits imposed by the normal interface. ++ It should be noted that the stream pointed to by stream need not ++ be opened using fopen64 or freopen64 since its mode is not ++ important for this function. <br> If the sources are ++ compiled with _FILE_OFFSET_BITS == 64 on a 32 bits machine this ++ function is available under the name freopen and so ++ transparently replaces the old interface. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The __freadable function determines whether the stream stream ++ was opened to allow reading. In this case the return value is ++ nonzero. For write-only streams the function returns zero. ++ <br> This function is declared in stdio_ext.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The __fwritable function determines whether the stream stream ++ was opened to allow writing. In this case the return value is ++ nonzero. For read-only streams the function returns zero. ++ <br> This function is declared in stdio_ext.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The __freading function determines whether the stream stream was ++ last read from or whether it is opened read-only. In this case ++ the return value is nonzero, otherwise it is zero. Determining ++ whether a stream opened for reading and writing was last used ++ for writing allows to draw conclusions about the content about ++ the buffer, among other things. <br> This function is ++ declared in stdio_ext.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The __fwriting function determines whether the stream stream was ++ last written to or whether it is opened write-only. In this ++ case the return value is nonzero, otherwise it is zero. ++ <br> This function is declared in stdio_ext.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function causes stream to be closed and the connection to ++ the corresponding file to be broken. Any buffered output is ++ written and any buffered input is discarded. The fclose ++ function returns a value of 0 if the file was closed ++ successfully, and EOF if an error was detected. <br> It is ++ important to check for errors when you call fclose to close an ++ output stream, because real, everyday errors can be detected at ++ this time. For example, when fclose writes the remaining ++ buffered output, it might get an error because the disk is full. ++ Even if you know the buffer is empty, errors can still occur ++ when closing a file if you are using NFS. <br> The ++ function fclose is declared in stdio.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function causes all open streams of the process to be ++ closed and the connection to corresponding files to be broken. ++ All buffered data is written and any buffered input is ++ discarded. The fcloseall function returns a value of 0 if all ++ the files were closed successfully, and EOF if an error was ++ detected. <br> This function should be used only in ++ special situations, e.g., when an error occurred and the program ++ must be aborted. Normally each single stream should be closed ++ separately so that problems with individual streams can be ++ identified. It is also problematic since the standard streams ++ (Standard Streams) will also be closed. <br> The function ++ fcloseall is declared in stdio.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The flockfile function acquires the internal locking object ++ associated with the stream stream. This ensures that no other ++ thread can explicitly through flockfile/ftrylockfile or implicit ++ through a call of a stream function lock the stream. The thread ++ will block until the lock is acquired. An explicit call to ++ funlockfile has to be used to release the lock. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The ftrylockfile function tries to acquire the internal locking ++ object associated with the stream stream just like flockfile. ++ But unlike flockfile this function does not block if the lock is ++ not available. ftrylockfile returns zero if the lock was ++ successfully acquired. Otherwise the stream is locked by ++ another thread. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The funlockfile function releases the internal locking object of ++ the stream stream. The stream must have been locked before by a ++ call to flockfile or a successful call of ftrylockfile. The ++ implicit locking performed by the stream operations do not ++ count. The funlockfile function does not return an error status ++ and the behavior of a call for a stream which is not locked by ++ the current thread is undefined. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> The __fsetlocking function can be used to select ++ whether the stream operations will implicitly acquire the ++ locking object of the stream stream. By default this is done ++ but it can be disabled and reinstated using this function. ++ There are three values defined for the type parameter. ++ <br> @vtable @code @item FSETLOCKING_INTERNAL The stream ++ stream will from now on use the default internal locking. Every ++ stream operation with exception of the _unlocked variants will ++ implicitly lock the stream. <br> @item ++ FSETLOCKING_BYCALLER After the __fsetlocking function returns ++ the user is responsible for locking the stream. None of the ++ stream operations will implicitly do this anymore until the ++ state is set back to FSETLOCKING_INTERNAL. <br> @item ++ FSETLOCKING_QUERY __fsetlocking only queries the current locking ++ state of the stream. The return value will be ++ FSETLOCKING_INTERNAL or FSETLOCKING_BYCALLER depending on the ++ state. @end vtable <br> The return value of __fsetlocking ++ is either FSETLOCKING_INTERNAL or FSETLOCKING_BYCALLER depending ++ on the state of the stream before the call. <br> This ++ function and the values for the type parameter are declared in ++ stdio_ext.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> The fwide function can be used to set and query the ++ state of the orientation of the stream stream. If the mode ++ parameter has a positive value the streams get wide oriented, ++ for negative values narrow oriented. It is not possible to ++ overwrite previous orientations with fwide. I.e., if the stream ++ stream was already oriented before the call nothing is done. ++ <br> If mode is zero the current orientation state is ++ queried and nothing is changed. <br> The fwide function ++ returns a negative value, zero, or a positive value if the ++ stream is narrow, not at all, or wide oriented respectively. ++ <br> This function was introduced in Amendment 1 to ISO ++ C90 and is declared in wchar.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The fputc function converts the character c to type unsigned ++ char, and writes it to the stream stream. EOF is returned if a ++ write error occurs; otherwise the character c is returned. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The fputwc function writes the wide character wc to the stream ++ stream. WEOF is returned if a write error occurs; otherwise the ++ character wc is returned. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The fputc_unlocked function is equivalent to the fputc function ++ except that it does not implicitly lock the stream. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The fputwc_unlocked function is equivalent to the fputwc ++ function except that it does not implicitly lock the stream. ++ <br> This function is a GNU extension. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This is just like fputc, except that most systems implement it ++ as a macro, making it faster. One consequence is that it may ++ evaluate the stream argument more than once, which is an ++ exception to the general rule for macros. putc is usually the ++ best function to use for writing a single character. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This is just like fputwc, except that it can be implement as a ++ macro, making it faster. One consequence is that it may ++ evaluate the stream argument more than once, which is an ++ exception to the general rule for macros. putwc is usually the ++ best function to use for writing a single wide character. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The putc_unlocked function is equivalent to the putc function ++ except that it does not implicitly lock the stream. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The putwc_unlocked function is equivalent to the putwc function ++ except that it does not implicitly lock the stream. <br> ++ This function is a GNU extension. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The putchar function is equivalent to putc with stdout as the ++ value of the stream argument. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The putwchar function is equivalent to putwc with stdout as the ++ value of the stream argument. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The putchar_unlocked function is equivalent to the putchar ++ function except that it does not implicitly lock the stream. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The putwchar_unlocked function is equivalent to the putwchar ++ function except that it does not implicitly lock the stream. ++ <br> This function is a GNU extension. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The function fputs writes the string s to the stream stream. ++ The terminating null character is not written. This function ++ does not add a newline character, either. It outputs only the ++ characters in the string. <br> This function returns EOF ++ if a write error occurs, and otherwise a non-negative value. ++ <br> For example: <br> @smallexample fputs ("Are ", ++ stdout); fputs ("you ", stdout); fputs ("hungry?\n", stdout); ++ @end smallexample <br> @noindent outputs the text Are you ++ hungry? followed by a newline. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The function fputws writes the wide character string ws to the ++ stream stream. The terminating null character is not written. ++ This function does not add a newline character, either. It ++ outputs only the characters in the string. <br> This ++ function returns WEOF if a write error occurs, and otherwise a ++ non-negative value. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The fputs_unlocked function is equivalent to the fputs function ++ except that it does not implicitly lock the stream. <br> ++ This function is a GNU extension. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The fputws_unlocked function is equivalent to the fputws ++ function except that it does not implicitly lock the stream. ++ <br> This function is a GNU extension. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The puts function writes the string s to the stream stdout ++ followed by a newline. The terminating null character of the ++ string is not written. (Note that fputs does not write a ++ newline as this function does.) <br> puts is the most ++ convenient function for printing simple messages. For example: ++ <br> @smallexample puts ("This is a message."); @end ++ smallexample <br> @noindent outputs the text This is a ++ message. followed by a newline. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function writes the word w (that is, an int) to stream. It ++ is provided for compatibility with SVID, but we recommend you ++ use fwrite instead (Block Input/Output). ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function reads the next character as an unsigned char from ++ the stream stream and returns its value, converted to an int. ++ If an end-of-file condition or read error occurs, EOF is ++ returned instead. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function reads the next wide character from the stream ++ stream and returns its value. If an end-of-file condition or ++ read error occurs, WEOF is returned instead. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The fgetc_unlocked function is equivalent to the fgetc function ++ except that it does not implicitly lock the stream. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The fgetwc_unlocked function is equivalent to the fgetwc ++ function except that it does not implicitly lock the stream. ++ <br> This function is a GNU extension. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This is just like fgetc, except that it is permissible (and ++ typical) for it to be implemented as a macro that evaluates the ++ stream argument more than once. getc is often highly optimized, ++ so it is usually the best function to use to read a single ++ character. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This is just like fgetwc, except that it is permissible for it ++ to be implemented as a macro that evaluates the stream argument ++ more than once. getwc can be highly optimized, so it is usually ++ the best function to use to read a single wide character. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The getc_unlocked function is equivalent to the getc function ++ except that it does not implicitly lock the stream. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The getwc_unlocked function is equivalent to the getwc function ++ except that it does not implicitly lock the stream. <br> ++ This function is a GNU extension. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The getchar function is equivalent to getc with stdin as the ++ value of the stream argument. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The getwchar function is equivalent to getwc with stdin as the ++ value of the stream argument. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The getchar_unlocked function is equivalent to the getchar ++ function except that it does not implicitly lock the stream. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The getwchar_unlocked function is equivalent to the getwchar ++ function except that it does not implicitly lock the stream. ++ <br> This function is a GNU extension. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function reads a word (that is, an int) from stream. It's ++ provided for compatibility with SVID. We recommend you use ++ fread instead (Block Input/Output). Unlike getc, any int value ++ could be a valid result. getw returns EOF when it encounters ++ end-of-file or an error, but there is no way to distinguish this ++ from an input word with value -1. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function reads an entire line from stream, storing the text ++ (including the newline and a terminating null character) in a ++ buffer and storing the buffer address in *lineptr. <br> ++ Before calling getline, you should place in *lineptr the address ++ of a buffer *n bytes long, allocated with malloc. If this ++ buffer is long enough to hold the line, getline stores the line ++ in this buffer. Otherwise, getline makes the buffer bigger ++ using realloc, storing the new buffer address back in *lineptr ++ and the increased size back in *n. . <br> If you set ++ *lineptr to a null pointer, and *n to zero, before the call, ++ then getline allocates the initial buffer for you by calling ++ malloc. <br> In either case, when getline returns, ++ *lineptr is a char * which points to the text of the line. ++ <br> When getline is successful, it returns the number of ++ characters read (including the newline, but not including the ++ terminating null). This value enables you to distinguish null ++ characters that are part of the line from the null character ++ inserted as a terminator. <br> This function is a GNU ++ extension, but it is the recommended way to read lines from a ++ stream. The alternative standard functions are unreliable. ++ <br> If an error occurs or end of file is reached without ++ any bytes read, getline returns -1. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is like getline except that the character which ++ tells it to stop reading is not necessarily newline. The ++ argument delimiter specifies the delimiter character; getdelim ++ keeps reading until it sees that character (or end of file). ++ <br> The text is stored in lineptr, including the ++ delimiter character and a terminating null. Like getline, ++ getdelim makes lineptr bigger if it isn't big enough. <br> ++ getline is in fact implemented in terms of getdelim, just like ++ this: <br> @smallexample ssize_t getline (char **lineptr, ++ size_t *n, FILE *stream) return getdelim (lineptr, n, '\n', ++ stream); @ @end smallexample ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The fgets function reads characters from the stream stream up to ++ and including a newline character and stores them in the string ++ s, adding a null character to mark the end of the string. You ++ must supply count characters worth of space in s, but the number ++ of characters read is at most count 1. The extra character ++ space is used to hold the null character at the end of the ++ string. <br> If the system is already at end of file when ++ you call fgets, then the contents of the array s are unchanged ++ and a null pointer is returned. A null pointer is also returned ++ if a read error occurs. Otherwise, the return value is the ++ pointer s. <br> Warning: If the input data has a null ++ character, you can't tell. So don't use fgets unless you know ++ the data cannot contain a null. Don't use it to read files ++ edited by the user because, if the user inserts a null ++ character, you should either handle it properly or print a clear ++ error message. We recommend using getline instead of fgets. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The fgetws function reads wide characters from the stream stream ++ up to and including a newline character and stores them in the ++ string ws, adding a null wide character to mark the end of the ++ string. You must supply count wide characters worth of space in ++ ws, but the number of characters read is at most count 1. The ++ extra character space is used to hold the null wide character at ++ the end of the string. <br> If the system is already at ++ end of file when you call fgetws, then the contents of the array ++ ws are unchanged and a null pointer is returned. A null pointer ++ is also returned if a read error occurs. Otherwise, the return ++ value is the pointer ws. <br> Warning: If the input data ++ has a null wide character (which are null bytes in the input ++ stream), you can't tell. So don't use fgetws unless you know ++ the data cannot contain a null. Don't use it to read files ++ edited by the user because, if the user inserts a null ++ character, you should either handle it properly or print a clear ++ error message. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The fgets_unlocked function is equivalent to the fgets function ++ except that it does not implicitly lock the stream. <br> ++ This function is a GNU extension. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The fgetws_unlocked function is equivalent to the fgetws ++ function except that it does not implicitly lock the stream. ++ <br> This function is a GNU extension. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The ungetc function pushes back the character c onto the input ++ stream stream. So the next input from stream will read c before ++ anything else. <br> If c is EOF, ungetc does nothing and ++ just returns EOF. This lets you call ungetc with the return ++ value of getc without needing to check for an error from getc. ++ <br> The character that you push back doesn't have to be ++ the same as the last character that was actually read from the ++ stream. In fact, it isn't necessary to actually read any ++ characters from the stream before unreading them with ungetc! ++ But that is a strange way to write a program; usually ungetc is ++ used only to unread a character that was just read from the same ++ stream. The GNU C library supports this even on files opened in ++ binary mode, but other systems might not. <br> The GNU C ++ library only supports one character of pushback---in other ++ words, it does not work to call ungetc twice without doing input ++ in between. Other systems might let you push back multiple ++ characters; then reading from the stream retrieves the ++ characters in the reverse order that they were pushed. ++ <br> Pushing back characters doesn't alter the file; only ++ the internal buffering for the stream is affected. If a file ++ positioning function (such as fseek, fseeko or rewind; File ++ Positioning) is called, any pending pushed-back characters are ++ discarded. <br> Unreading a character on a stream that is ++ at end of file clears the end-of-file indicator for the stream, ++ because it makes the character of input available. After you ++ read that character, trying to read again will encounter end of ++ file. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The ungetwc function behaves just like ungetc just that it ++ pushes back a wide character. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function reads up to count objects of size size into the ++ array data, from the stream stream. It returns the number of ++ objects actually read, which might be less than count if a read ++ error occurs or the end of the file is reached. This function ++ returns a value of zero (and doesn't read anything) if either ++ size or count is zero. <br> If fread encounters end of ++ file in the middle of an object, it returns the number of ++ complete objects read, and discards the partial object. ++ Therefore, the stream remains at the actual end of the file. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The fread_unlocked function is equivalent to the fread function ++ except that it does not implicitly lock the stream. <br> ++ This function is a GNU extension. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function writes up to count objects of size size from the ++ array data, to the stream stream. The return value is normally ++ count, if the call succeeds. Any other value indicates some ++ sort of error, such as running out of space. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The fwrite_unlocked function is equivalent to the fwrite ++ function except that it does not implicitly lock the stream. ++ <br> This function is a GNU extension. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The printf function prints the optional arguments under the ++ control of the template string template to the stream stdout. ++ It returns the number of characters printed, or a negative value ++ if there was an output error. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The wprintf function prints the optional arguments under the ++ control of the wide template string template to the stream ++ stdout. It returns the number of wide characters printed, or a ++ negative value if there was an output error. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is just like printf, except that the output is ++ written to the stream stream instead of stdout. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is just like wprintf, except that the output is ++ written to the stream stream instead of stdout. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This is like printf, except that the output is stored in the ++ character array s instead of written to a stream. A null ++ character is written to mark the end of the string. <br> ++ The sprintf function returns the number of characters stored in ++ the array s, not including the terminating null character. ++ <br> The behavior of this function is undefined if copying ++ takes place between objects that overlap---for example, if s is ++ also given as an argument to be printed under control of the %s ++ conversion. . <br> Warning: The sprintf function can be ++ dangerous because it can potentially output more characters than ++ can fit in the allocation size of the string s. Remember that ++ the field width given in a conversion specification is only a ++ minimum value. <br> To avoid this problem, you can use ++ snprintf or asprintf, described below. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This is like wprintf, except that the output is stored in the ++ wide character array ws instead of written to a stream. A null ++ wide character is written to mark the end of the string. The ++ size argument specifies the maximum number of characters to ++ produce. The trailing null character is counted towards this ++ limit, so you should allocate at least size wide characters for ++ the string ws. <br> The return value is the number of ++ characters generated for the given input, excluding the trailing ++ null. If not all output fits into the provided buffer a ++ negative value is returned. You should try again with a bigger ++ output string. Note: this is different from how snprintf ++ handles this situation. <br> Note that the corresponding ++ narrow stream function takes fewer parameters. swprintf in fact ++ corresponds to the snprintf function. Since the sprintf ++ function can be dangerous and should be avoided the ISO C ++ committee refused to make the same mistake again and decided to ++ not define an function exactly corresponding to sprintf. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The snprintf function is similar to sprintf, except that the ++ size argument specifies the maximum number of characters to ++ produce. The trailing null character is counted towards this ++ limit, so you should allocate at least size characters for the ++ string s. <br> The return value is the number of ++ characters which would be generated for the given input, ++ excluding the trailing null. If this value is greater or equal ++ to size, not all characters from the result have been stored in ++ s. You should try again with a bigger output string. Here is ++ an example of doing this: <br> @smallexample @group /* ++ Construct a message describing the value of a variable whose ++ name is name and whose value is value. */ char * make_message ++ (char *name, char *value) /* Guess we need no more than 100 ++ chars of space. */ int size = 100; char *buffer = (char *) ++ xmalloc (size); int nchars; @end group @group if (buffer == ++ NULL) return NULL; <br> /* Try to print in the ++ allocated space. */ nchars = snprintf (buffer, size, "value of ++ %s is %s", name, value); @end group @group ++ if (nchars >= size) /* Reallocate buffer now that ++ we know how much space is needed. */ buffer = ++ (char *) xrealloc (buffer, nchars + 1); <br> if ++ (buffer != NULL) /* Try again. */ snprintf ++ (buffer, size, "value of %s is %s", name, ++ value); @ /* The last call worked, return the string. */ ++ return buffer; @ @end group @end smallexample <br> In ++ practice, it is often easier just to use asprintf, below. ++ <br> Attention: In versions of the GNU C library prior to ++ 2.1 the return value is the number of characters stored, not ++ including the terminating null; unless there was not enough ++ space in s to store the result in which case -1 is returned. ++ This was changed in order to comply with the ISO C99 standard. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to sprintf, except that it dynamically ++ allocates a string (as with malloc; Unconstrained Allocation) to ++ hold the output, instead of putting the output in a buffer you ++ allocate in advance. The ptr argument should be the address of ++ a char * object, and asprintf stores a pointer to the newly ++ allocated string at that location. <br> The return value ++ is the number of characters allocated for the buffer, or less ++ than zero if an error occurred. Usually this means that the ++ buffer could not be allocated. <br> Here is how to use ++ asprintf to get the same result as the snprintf example, but ++ more easily: <br> @smallexample /* Construct a message ++ describing the value of a variable whose name is name and ++ whose value is value. */ char * make_message (char *name, char ++ *value) char *result; if (asprintf (&result, "value of ++ %s is %s", name, value) < 0) return NULL; return ++ result; @ @end smallexample ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to asprintf, except that it uses the ++ obstack obstack to allocate the space. . <br> The ++ characters are written onto the end of the current object. To ++ get at them, you must finish the object with obstack_finish ++ (Growing Objects).@refill ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to printf except that, instead of ++ taking a variable number of arguments directly, it takes an ++ argument list pointer ap. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to wprintf except that, instead of ++ taking a variable number of arguments directly, it takes an ++ argument list pointer ap. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This is the equivalent of fprintf with the variable argument ++ list specified directly as for vprintf. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This is the equivalent of fwprintf with the variable argument ++ list specified directly as for vwprintf. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This is the equivalent of sprintf with the variable argument ++ list specified directly as for vprintf. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This is the equivalent of swprintf with the variable argument ++ list specified directly as for vwprintf. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This is the equivalent of snprintf with the variable argument ++ list specified directly as for vprintf. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The vasprintf function is the equivalent of asprintf with the ++ variable argument list specified directly as for vprintf. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The obstack_vprintf function is the equivalent of obstack_printf ++ with the variable argument list specified directly as for ++ vprintf.@refill ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function returns information about the number and types of ++ arguments expected by the printf template string template. The ++ information is stored in the array argtypes; each element of ++ this array describes one argument. This information is encoded ++ using the various PA_ macros, listed below. <br> The ++ argument n specifies the number of elements in the array ++ argtypes. This is the maximum number of elements that ++ parse_printf_format will try to write. <br> ++ parse_printf_format returns the total number of arguments ++ required by template. If this number is greater than n, then ++ the information returned describes only the first n arguments. ++ If you want information about additional arguments, allocate a ++ bigger array and call parse_printf_format again. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function defines the conversion specifier character spec. ++ Thus, if spec is 'Y', it defines the conversion %Y. You can ++ redefine the built-in conversions like %s, but flag characters ++ like # and type modifiers like l can never be used as ++ conversions; calling register_printf_function for those ++ characters has no effect. It is advisable not to use lowercase ++ letters, since the ISO C standard warns that additional ++ lowercase letters may be standardized in future editions of the ++ standard. <br> The handler-function is the function called ++ by printf and friends when this conversion appears in a template ++ string. , for information about how to define a function to pass ++ as this argument. If you specify a null pointer, any existing ++ handler function for spec is removed. <br> The ++ arginfo-function is the function called by parse_printf_format ++ when this conversion appears in a template string. , for ++ information about this. <br> @c The following is not true ++ anymore. The `parse_printf_format' function @c is now also ++ called from `vfprintf' via `parse_one_spec'. @c --drepper@gnu, ++ 1996/11/14 @c @c Normally, you install both functions for a ++ conversion at the same time, @c but if you are never going to ++ call parse_printf_format, you do @c not need to define an ++ arginfo function. <br> Attention: In the GNU C library ++ versions before 2.0 the arginfo-function function did not need ++ to be installed unless the user used the parse_printf_format ++ function. This has changed. Now a call to any of the printf ++ functions will call this function when this format specifier ++ appears in the format string. <br> The return value is 0 ++ on success, and -1 on failure (which occurs if spec is out of ++ range). <br> You can redefine the standard output ++ conversions, but this is probably not a good idea because of the ++ potential for confusion. Library routines written by other ++ people could break if you do this. ++ ++ ++ ++ ++ ++ ++ This structure is used to pass information about the options ++ appearing in an instance of a conversion specifier in a printf ++ template string to the handler and arginfo functions for that ++ specifier. It contains the following members: <br> ++ ++ ++ ++ ++ This is the precision specified. The value is -1 if no ++ precision was specified. If the precision was given as *, the ++ printf_info structure passed to the handler function contains ++ the actual value retrieved from the argument list. But the ++ structure passed to the arginfo function contains a value of ++ INT_MIN, since the actual value is not known. <br> ++ ++ ++ ++ ++ This is the minimum field width specified. The value is 0 if no ++ width was specified. If the field width was given as *, the ++ printf_info structure passed to the handler function contains ++ the actual value retrieved from the argument list. But the ++ structure passed to the arginfo function contains a value of ++ INT_MIN, since the actual value is not known. <br> ++ ++ ++ ++ ++ This is the conversion specifier character specified. It's ++ stored in the structure so that you can register the same ++ handler function for multiple characters, but still have a way ++ to tell them apart when the handler function is called. ++ <br> ++ ++ ++ ++ ++ This is a boolean that is true if the L, ll, or q type modifier ++ was specified. For integer conversions, this indicates long ++ long int, as opposed to long double for floating point ++ conversions. <br> ++ ++ ++ ++ ++ This is a boolean that is true if the hh type modifier was ++ specified. <br> ++ ++ ++ ++ ++ This is a boolean that is true if the h type modifier was ++ specified. <br> ++ ++ ++ ++ ++ This is a boolean that is true if the l type modifier was ++ specified. <br> ++ ++ ++ ++ ++ This is a boolean that is true if the # flag was specified. ++ <br> ++ ++ ++ ++ ++ This is a boolean that is true if the flag was specified. ++ <br> ++ ++ ++ ++ ++ This is a boolean that is true if the - flag was specified. ++ <br> ++ ++ ++ ++ ++ This is a boolean that is true if the + flag was specified. ++ <br> ++ ++ ++ ++ ++ This is a boolean that is true if the ' flag was specified. ++ <br> ++ ++ ++ ++ ++ This flag has a special meaning depending on the context. It ++ could be used freely by the user-defined handlers but when ++ called from the printf function this variable always contains ++ the value 0. <br> ++ ++ ++ ++ ++ This flag is set if the stream is wide oriented. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ Print a given floating point number as for the format %f except ++ that there is a postfix character indicating the divisor for the ++ number to make this less than 1000. There are two possible ++ divisors: powers of 1024 or powers of 1000. Which one is used ++ depends on the format character specified while registered this ++ handler. If the character is of lower case, 1024 is used. For ++ upper case characters, 1000 is used. <br> The postfix tag ++ corresponds to bytes, kilobytes, megabytes, gigabytes, etc. The ++ full table is: <br> @ifinfo @multitable @hsep @vsep {' '} ++ {2^10 (1024)} {zetta} {Upper} {10^24 (1000)} @item low @tab ++ Multiplier @tab From @tab Upper @tab Multiplier @item ' ' @tab ++ 1 @tab @tab ' ' @tab 1 @item k @tab 2^10 ++ (1024) @tab kilo @tab K @tab 10^3 (1000) @item m @tab ++ 2^20 @tab mega @tab M @tab 10^6 @item g @tab 2^30 ++ @tab giga @tab G @tab 10^9 @item t @tab 2^40 ++ @tab tera @tab T @tab 10^12 @item p @tab 2^50 @tab ++ peta @tab P @tab 10^15 @item e @tab 2^60 @tab exa ++ @tab E @tab 10^18 @item z @tab 2^70 @tab zetta ++ @tab Z @tab 10^21 @item y @tab 2^80 @tab yotta @tab ++ Y @tab 10^24 @end multitable @end ifinfo @iftex @tex \hbox ++ to\hsize{\hfil\vbox{\offinterlineskip \hrule ++ \halign{\strut#& \vrule#\tabskip=1em plus2em& ++ {\tt#}\hfil& \vrule#& #\hfil& \vrule#& ++ #\hfil& \vrule#& {\tt#}\hfil& \vrule#& ++ #\hfil& \vrule#\tabskip=0pt\cr \noalign{\hrule} ++ \omit&height2pt&\omit&&\omit&&\omit&&\omit&&\omit&\cr ++ && \omit low && Multiplier && From ++ && \omit Upper && Multiplier &\cr ++ \omit&height2pt&\omit&&\omit&&\omit&&\omit&&\omit&\cr ++ \noalign{\hrule} && {\tt\char32} && 1 ++ && && {\tt\char32} && 1 &\cr ++ && k && $2^{10} = 1024$ && kilo ++ && K && $10^3 = 1000$ &\cr && m ++ && $2^{20}$ && mega && M && ++ $10^6$ &\cr && g && $2^{30}$ && giga ++ && G && $10^9$ &\cr && t && ++ $2^{40}$ && tera && T && $10^{12}$ ++ &\cr && p && $2^{50}$ && peta ++ && P && $10^{15}$ &\cr && e ++ && $2^{60}$ && exa && E && ++ $10^{18}$ &\cr && z && $2^{70}$ && ++ zetta && Z && $10^{21}$ &\cr && y ++ && $2^{80}$ && yotta && Y && ++ $10^{24}$ &\cr \noalign{\hrule}}}\hfil} @end tex @end iftex ++ <br> The default precision is 3, i.e., 1024 is printed ++ with a lower-case format character as if it were %.3fk and will ++ yield 1.000k. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function will return in argtypes the information about the ++ used parameters in the way the vfprintf implementation expects ++ it. The format always takes one argument. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The scanf function reads formatted input from the stream stdin ++ under the control of the template string template. The optional ++ arguments are pointers to the places which receive the resulting ++ values. <br> The return value is normally the number of ++ successful assignments. If an end-of-file condition is detected ++ before any matches are performed, including matches against ++ whitespace and literal characters in the template, then EOF is ++ returned. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The wscanf function reads formatted input from the stream stdin ++ under the control of the template string template. The optional ++ arguments are pointers to the places which receive the resulting ++ values. <br> The return value is normally the number of ++ successful assignments. If an end-of-file condition is detected ++ before any matches are performed, including matches against ++ whitespace and literal characters in the template, then WEOF is ++ returned. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is just like scanf, except that the input is read ++ from the stream stream instead of stdin. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is just like wscanf, except that the input is read ++ from the stream stream instead of stdin. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This is like scanf, except that the characters are taken from ++ the null-terminated string s instead of from a stream. Reaching ++ the end of the string is treated as an end-of-file condition. ++ <br> The behavior of this function is undefined if copying ++ takes place between objects that overlap---for example, if s is ++ also given as an argument to receive a string read under control ++ of the %s, %S, or %[ conversion. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This is like wscanf, except that the characters are taken from ++ the null-terminated string ws instead of from a stream. ++ Reaching the end of the string is treated as an end-of-file ++ condition. <br> The behavior of this function is undefined ++ if copying takes place between objects that overlap---for ++ example, if ws is also given as an argument to receive a string ++ read under control of the %s, %S, or %[ conversion. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to scanf, but instead of taking a ++ variable number of arguments directly, it takes an argument list ++ pointer ap of type va_list (Variadic Functions). ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to wscanf, but instead of taking a ++ variable number of arguments directly, it takes an argument list ++ pointer ap of type va_list (Variadic Functions). ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This is the equivalent of fscanf with the variable argument list ++ specified directly as for vscanf. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This is the equivalent of fwscanf with the variable argument ++ list specified directly as for vwscanf. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This is the equivalent of sscanf with the variable argument list ++ specified directly as for vscanf. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This is the equivalent of swscanf with the variable argument ++ list specified directly as for vwscanf. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++
++ ++ ++ The feof function returns nonzero if and only if the end-of-file ++ indicator for the stream stream is set. <br> This symbol ++ is declared in stdio.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The feof_unlocked function is equivalent to the feof function ++ except that it does not implicitly lock the stream. <br> ++ This function is a GNU extension. <br> This symbol is ++ declared in stdio.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The ferror function returns nonzero if and only if the error ++ indicator for the stream stream is set, indicating that an error ++ has occurred on a previous operation on the stream. <br> ++ This symbol is declared in stdio.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The ferror_unlocked function is equivalent to the ferror ++ function except that it does not implicitly lock the stream. ++ <br> This function is a GNU extension. <br> This ++ symbol is declared in stdio.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function clears the end-of-file and error indicators for ++ the stream stream. <br> The file positioning functions ++ (File Positioning) also clear the end-of-file indicator for the ++ stream. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The clearerr_unlocked function is equivalent to the clearerr ++ function except that it does not implicitly lock the stream. ++ <br> This function is a GNU extension. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function returns the current file position of the stream ++ stream. <br> This function can fail if the stream doesn't ++ support file positioning, or if the file position can't be ++ represented in a long int, and possibly for other reasons as ++ well. If a failure occurs, a value of -1 is returned. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The ftello function is similar to ftell, except that it returns ++ a value of type off_t. Systems which support this type use it ++ to describe all file positions, unlike the POSIX specification ++ which uses a long int. The two are not necessarily the same ++ size. Therefore, using ftell can lead to problems if the ++ implementation is written on top of a POSIX compliant low-level ++ I/O implementation, and using ftello is preferable whenever it ++ is available. <br> If this function fails it returns ++ (off_t) -1. This can happen due to missing support for file ++ positioning or internal errors. Otherwise the return value is ++ the current file position. <br> The function is an ++ extension defined in the Unix Single Specification version 2. ++ <br> When the sources are compiled with _FILE_OFFSET_BITS ++ == 64 on a 32 bit system this function is in fact ftello64. ++ I.e., the LFS interface transparently replaces the old ++ interface. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to ftello with the only difference that ++ the return value is of type off64_t. This also requires that ++ the stream stream was opened using either fopen64, freopen64, or ++ tmpfile64 since otherwise the underlying file operations to ++ position the file pointer beyond the 2^31 bytes limit might ++ fail. <br> If the sources are compiled with ++ _FILE_OFFSET_BITS == 64 on a 32 bits machine this function is ++ available under the name ftello and so transparently replaces ++ the old interface. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The fseek function is used to change the file position of the ++ stream stream. The value of whence must be one of the constants ++ SEEK_SET, SEEK_CUR, or SEEK_END, to indicate whether the offset ++ is relative to the beginning of the file, the current file ++ position, or the end of the file, respectively. <br> This ++ function returns a value of zero if the operation was ++ successful, and a nonzero value to indicate failure. A ++ successful call also clears the end-of-file indicator of stream ++ and discards any characters that were ``pushed back'' by the use ++ of ungetc. <br> fseek either flushes any buffered output ++ before setting the file position or else remembers it so it will ++ be written later in its proper place in the file. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to fseek but it corrects a problem with ++ fseek in a system with POSIX types. Using a value of type long ++ int for the offset is not compatible with POSIX. fseeko uses the ++ correct type off_t for the offset parameter. <br> For this ++ reason it is a good idea to prefer ftello whenever it is ++ available since its functionality is (if different at all) ++ closer the underlying definition. <br> The functionality ++ and return value is the same as for fseek. <br> The ++ function is an extension defined in the Unix Single ++ Specification version 2. <br> When the sources are ++ compiled with _FILE_OFFSET_BITS == 64 on a 32 bit system this ++ function is in fact fseeko64. I.e., the LFS interface ++ transparently replaces the old interface. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to fseeko with the only difference that ++ the offset parameter is of type off64_t. This also requires ++ that the stream stream was opened using either fopen64, ++ freopen64, or tmpfile64 since otherwise the underlying file ++ operations to position the file pointer beyond the 2^31 bytes ++ limit might fail. <br> If the sources are compiled with ++ _FILE_OFFSET_BITS == 64 on a 32 bits machine this function is ++ available under the name fseeko and so transparently replaces ++ the old interface. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The rewind function positions the stream stream at the beginning ++ of the file. It is equivalent to calling fseek or fseeko on the ++ stream with an offset argument of 0L and a whence argument of ++ SEEK_SET, except that the return value is discarded and the ++ error indicator for the stream is reset. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++
++ ++ ++ This function stores the value of the file position indicator ++ for the stream stream in the fpos_t object pointed to by ++ position. If successful, fgetpos returns zero; otherwise it ++ returns a nonzero value and stores an implementation-defined ++ positive value in errno. <br> When the sources are ++ compiled with _FILE_OFFSET_BITS == 64 on a 32 bit system the ++ function is in fact fgetpos64. I.e., the LFS interface ++ transparently replaces the old interface. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to fgetpos but the file position is ++ returned in a variable of type fpos64_t to which position ++ points. <br> If the sources are compiled with ++ _FILE_OFFSET_BITS == 64 on a 32 bits machine this function is ++ available under the name fgetpos and so transparently replaces ++ the old interface. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function sets the file position indicator for the stream ++ stream to the position position, which must have been set by a ++ previous call to fgetpos on the same stream. If successful, ++ fsetpos clears the end-of-file indicator on the stream, discards ++ any characters that were ``pushed back'' by the use of ungetc, ++ and returns a value of zero. Otherwise, fsetpos returns a ++ nonzero value and stores an implementation-defined positive ++ value in errno. <br> When the sources are compiled with ++ _FILE_OFFSET_BITS == 64 on a 32 bit system the function is in ++ fact fsetpos64. I.e., the LFS interface transparently replaces ++ the old interface. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to fsetpos but the file position used ++ for positioning is provided in a variable of type fpos64_t to ++ which position points. <br> If the sources are compiled ++ with _FILE_OFFSET_BITS == 64 on a 32 bits machine this function ++ is available under the name fsetpos and so transparently ++ replaces the old interface. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function causes any buffered output on stream to be ++ delivered to the file. If stream is a null pointer, then fflush ++ causes buffered output on all open output streams to be flushed. ++ <br> This function returns EOF if a write error occurs, or ++ zero otherwise. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The fflush_unlocked function is equivalent to the fflush ++ function except that it does not implicitly lock the stream. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The _flushlbf function flushes all line buffered streams ++ currently opened. <br> This function is declared in the ++ stdio_ext.h header. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The __fpurge function causes the buffer of the stream stream to ++ be emptied. If the stream is currently in read mode all input ++ in the buffer is lost. If the stream is in output mode the ++ buffered output is not written to the device (or whatever other ++ underlying storage) and the buffer the cleared. <br> This ++ function is declared in stdio_ext.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is used to specify that the stream stream should ++ have the buffering mode mode, which can be either _IOFBF (for ++ full buffering), _IOLBF (for line buffering), or _IONBF (for ++ unbuffered input/output). <br> If you specify a null ++ pointer as the buf argument, then setvbuf allocates a buffer ++ itself using malloc. This buffer will be freed when you close ++ the stream. <br> Otherwise, buf should be a character ++ array that can hold at least size characters. You should not ++ free the space for this array as long as the stream remains open ++ and this array remains its buffer. You should usually either ++ allocate it statically, or malloc (Unconstrained Allocation) the ++ buffer. Using an automatic array is not a good idea unless you ++ close the file before exiting the block that declares the array. ++ <br> While the array remains a stream buffer, the stream ++ I/O functions will use the buffer for their internal purposes. ++ You shouldn't try to access the values in the array directly ++ while the stream is using it for buffering. <br> The ++ setvbuf function returns zero on success, or a nonzero value if ++ the value of mode is not valid or if the request could not be ++ honored. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ If buf is a null pointer, the effect of this function is ++ equivalent to calling setvbuf with a mode argument of _IONBF. ++ Otherwise, it is equivalent to calling setvbuf with buf, and a ++ mode of _IOFBF and a size argument of BUFSIZ. <br> The ++ setbuf function is provided for compatibility with old code; use ++ setvbuf in all new programs. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ If buf is a null pointer, this function makes stream unbuffered. ++ Otherwise, it makes stream fully buffered using buf as the ++ buffer. The size argument specifies the length of buf. ++ <br> This function is provided for compatibility with old ++ BSD code. Use setvbuf instead. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function makes stream be line buffered, and allocates the ++ buffer for you. <br> This function is provided for ++ compatibility with old BSD code. Use setvbuf instead. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The __flbf function will return a nonzero value in case the ++ stream stream is line buffered. Otherwise the return value is ++ zero. <br> This function is declared in the stdio_ext.h ++ header. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The __fbufsize function return the size of the buffer in the ++ stream stream. This value can be used to optimize the use of ++ the stream. <br> This function is declared in the ++ stdio_ext.h header. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ function returns the number of bytes currently in the output ++ buffer. For wide-oriented stream the measuring unit is wide ++ characters. This function should not be used on buffers in read ++ mode or opened read-only. <br> This function is declared ++ in the stdio_ext.h header. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function opens a stream that allows the access specified by ++ the opentype argument, that reads from or writes to the buffer ++ specified by the argument buf. This array must be at least size ++ bytes long. <br> If you specify a null pointer as the buf ++ argument, fmemopen dynamically allocates an array size bytes ++ long (as with malloc; Unconstrained Allocation). This is really ++ only useful if you are going to write things to the buffer and ++ then read them back in again, because you have no way of ++ actually getting a pointer to the buffer (for this, try ++ open_memstream, below). The buffer is freed when the stream is ++ closed. <br> The argument opentype is the same as in fopen ++ (Opening Streams). If the opentype specifies append mode, then ++ the initial file position is set to the first null character in ++ the buffer. Otherwise the initial file position is at the ++ beginning of the buffer. <br> When a stream open for ++ writing is flushed or closed, a null character (zero byte) is ++ written at the end of the buffer if it fits. You should add an ++ extra byte to the size argument to account for this. Attempts to ++ write more than size bytes to the buffer result in an error. ++ <br> For a stream open for reading, null characters (zero ++ bytes) in the buffer do not count as ``end of file''. Read ++ operations indicate end of file only when the file position ++ advances past size bytes. So, if you want to read characters ++ from a null-terminated string, you should supply the length of ++ the string as the size argument. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function opens a stream for writing to a buffer. The ++ buffer is allocated dynamically (as with malloc; Unconstrained ++ Allocation) and grown as necessary. <br> When the stream ++ is closed with fclose or flushed with fflush, the locations ptr ++ and sizeloc are updated to contain the pointer to the buffer and ++ its size. The values thus stored remain valid only as long as ++ no further output on the stream takes place. If you do more ++ output, you must flush the stream again to store new values ++ before you use them again. <br> A null character is ++ written at the end of the buffer. This null character is not ++ included in the size value stored at sizeloc. <br> You can ++ move the stream's file position with fseek or fseeko (File ++ Positioning). Moving the file position past the end of the data ++ already written fills the intervening space with zeroes. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function opens a stream for writing data into the obstack ++ obstack. This starts an object in the obstack and makes it grow ++ as data is written (Growing Objects). @c @end group Doubly ++ invalid because not nested right. <br> Calling fflush on ++ this stream updates the current size of the object to match the ++ amount of data that has been written. After a call to fflush, ++ you can examine the object temporarily. <br> You can move ++ the file position of an obstack stream with fseek or fseeko ++ (File Positioning). Moving the file position past the end of ++ the data written fills the intervening space with zeros. ++ <br> To make the object permanent, update the obstack with ++ fflush, and then use obstack_finish to finalize the object and ++ get its address. The following write to the stream starts a new ++ object in the obstack, and later writes add to that object until ++ you do another fflush and obstack_finish. <br> But how do ++ you find out how long the object is? You can get the length in ++ bytes by calling obstack_object_size (Status of an Obstack), or ++ you can null-terminate the object like this: <br> ++ @smallexample obstack_1grow (obstack, 0); @end smallexample ++ <br> Whichever one you do, you must do it before calling ++ obstack_finish. (You can do both if you wish.) ++ ++ ++ ++ ++ ++ ++ This is a structure type that holds the functions that define ++ the communications protocol between the stream and its cookie. ++ It has the following members: <br> ++ ++ ++ ++ ++ This is the function that reads data from the cookie. If the ++ value is a null pointer instead of a function, then read ++ operations on this stream always return EOF. <br> ++ ++ ++ ++ ++ This is the function that writes data to the cookie. If the ++ value is a null pointer instead of a function, then data written ++ to the stream is discarded. <br> ++ ++ ++ ++ ++ This is the function that performs the equivalent of file ++ positioning on the cookie. If the value is a null pointer ++ instead of a function, calls to fseek or fseeko on this stream ++ can only seek to locations within the buffer; any attempt to ++ seek outside the buffer will return an ESPIPE error. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function actually creates the stream for communicating with ++ the cookie using the functions in the io-functions argument. The ++ opentype argument is interpreted as for fopen; see Opening ++ Streams. (But note that the ``truncate on open'' option is ++ ignored.) The new stream is fully buffered. <br> The ++ fopencookie function returns the newly created stream, or a null ++ pointer in case of an error. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++
++ ++ ++ Display a message described by its parameters on the device(s) ++ specified in the classification parameter. The label parameter ++ identifies the source of the message. The string should consist ++ of two colon separated parts where the first part has not more ++ than 10 and the second part not more than 14 characters. The ++ text parameter describes the condition of the error, the action ++ parameter possible steps to recover from the error and the tag ++ parameter is a reference to the online documentation where more ++ information can be found. It should contain the label value and ++ a unique identification number. <br> Each of the ++ parameters can be a special value which means this value is to ++ be omitted. The symbolic names for these values are: <br> ++ @vtable @code @item MM_NULLLBL Ignore label parameter. @item ++ MM_NULLSEV Ignore severity parameter. @item MM_NULLMC Ignore ++ classification parameter. This implies that nothing is actually ++ printed. @item MM_NULLTXT Ignore text parameter. @item ++ MM_NULLACT Ignore action parameter. @item MM_NULLTAG Ignore tag ++ parameter. @end vtable <br> There is another way certain ++ fields can be omitted from the output to standard error. This ++ is described below in the description of environment variables ++ influencing the behavior. <br> The severity parameter can ++ have one of the values in the following table: @cindex severity ++ class <br> @vtable @code @item MM_NOSEV Nothing is ++ printed, this value is the same as MM_NULLSEV. @item MM_HALT ++ This value is printed as HALT. @item MM_ERROR This value is ++ printed as ERROR. @item MM_WARNING This value is printed as ++ WARNING. @item MM_INFO This value is printed as INFO. @end ++ vtable <br> The numeric value of these five macros are ++ between 0 and 4. Using the environment variable SEV_LEVEL or ++ using the addseverity function one can add more severity levels ++ with their corresponding string to print. This is described ++ below (Adding Severity Classes). <br> @noindent If no ++ parameter is ignored the output looks like this: <br> ++ @smallexample label: severity-string: text TO FIX: action tag ++ @end smallexample <br> The colons, new line characters and ++ the TO FIX string are inserted if necessary, i.e., if the ++ corresponding parameter is not ignored. <br> This function ++ is specified in the X/Open Portability Guide. It is also ++ available on all systems derived from System V. <br> The ++ function returns the value MM_OK if no error occurred. If only ++ the printing to standard error failed, it returns MM_NOMSG. If ++ printing to the console fails, it returns MM_NOCON. If nothing ++ is printed MM_NOTOK is returned. Among situations where all ++ outputs fail this last value is also returned if a parameter ++ value is incorrect. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ This function allows the introduction of new severity classes ++ which can be addressed by the severity parameter of the fmtmsg ++ function. The severity parameter of addseverity must match the ++ value for the parameter with the same name of fmtmsg, and string ++ is the string printed in the actual messages instead of the ++ numeric value. <br> If string is NULL the severity class ++ with the numeric value according to severity is removed. ++ <br> It is not possible to overwrite or remove one of the ++ default severity classes. All calls to addseverity with ++ severity set to one of the values for the default classes will ++ fail. <br> The return value is MM_OK if the task was ++ successfully performed. If the return value is MM_NOTOK ++ something went wrong. This could mean that no more memory is ++ available or a class is not available when it has to be removed. ++ <br> This function is not specified in the X/Open ++ Portability Guide although the fmtsmg function is. It is ++ available on System V systems. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The strlen function returns the length of the null-terminated ++ string s in bytes. (In other words, it returns the offset of ++ the terminating null character within the array.) <br> For ++ example, @smallexample strlen ("hello, world") 12 @end ++ smallexample <br> When applied to a character array, the ++ strlen function returns the length of the string stored there, ++ not its allocated size. You can get the allocated size of the ++ character array that holds a string using the sizeof operator: ++ <br> @smallexample char string[32] = "hello, world"; ++ sizeof (string) 32 strlen (string) 12 @end ++ smallexample <br> But beware, this will not work unless ++ string is the character array itself, not a pointer to it. For ++ example: <br> @smallexample char string[32] = "hello, ++ world"; char *ptr = string; sizeof (string) 32 sizeof (ptr) ++ 4 /* (on a machine with 4 byte pointers) */ @end ++ smallexample <br> This is an easy mistake to make when you ++ are working with functions that take string arguments; those ++ arguments are always pointers, not arrays. <br> It must ++ also be noted that for multibyte encoded strings the return ++ value does not have to correspond to the number of characters in ++ the string. To get this value the string can be converted to ++ wide characters and wcslen can be used or something like the ++ following code can be used: <br> @smallexample /* The ++ input is in string. The length is expected in n. */ ++ mbstate_t t; char *scopy = string; /* In initial state. */ ++ memset (&t, '\0', sizeof (t)); /* Determine number of ++ characters. */ n = mbsrtowcs (NULL, &scopy, strlen ++ (scopy), &t); @ @end smallexample <br> This is ++ cumbersome to do so if the number of characters (as opposed to ++ bytes) is needed often it is better to work with wide ++ characters. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The wcslen function is the wide character equivalent to strlen. ++ The return value is the number of wide characters in the wide ++ character string pointed to by ws (this is also the offset of ++ the terminating null wide character of ws). <br> Since ++ there are no multi wide character sequences making up one ++ character the return value is not only the offset in the array, ++ it is also the number of wide characters. <br> This ++ function was introduced in Amendment 1 to ISO C90. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The strnlen function returns the length of the string s in bytes ++ if this length is smaller than maxlen bytes. Otherwise it ++ returns maxlen. Therefore this function is equivalent to ++ (strlen (s) < n ? strlen (s) : maxlen) but it is more ++ efficient and works even if the string s is not null-terminated. ++ <br> @smallexample char string[32] = "hello, world"; ++ strnlen (string, 32) 12 strnlen (string, 5) 5 @end ++ smallexample <br> This function is a GNU extension and is ++ declared in string.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ wcsnlen is the wide character equivalent to strnlen. The maxlen ++ parameter specifies the maximum number of wide characters. ++ <br> This function is a GNU extension and is declared in ++ wchar.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The memcpy function copies size bytes from the object beginning ++ at from into the object beginning at to. The behavior of this ++ function is undefined if the two arrays to and from overlap; use ++ memmove instead if overlapping is possible. <br> The value ++ returned by memcpy is the value of to. <br> Here is an ++ example of how you might use memcpy to copy the contents of an ++ array: <br> @smallexample struct foo *oldarray, *newarray; ++ int arraysize; memcpy (new, old, arraysize * sizeof (struct ++ foo)); @end smallexample ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The wmemcpy function copies size wide characters from the object ++ beginning at wfrom into the object beginning at wto. The ++ behavior of this function is undefined if the two arrays wto and ++ wfrom overlap; use wmemmove instead if overlapping is possible. ++ <br> The following is a possible implementation of wmemcpy ++ but there are more optimizations possible. <br> ++ @smallexample wchar_t * wmemcpy (wchar_t *restrict wto, const ++ wchar_t *restrict wfrom, size_t size) return ++ (wchar_t *) memcpy (wto, wfrom, size * sizeof (wchar_t)); @ @end ++ smallexample <br> The value returned by wmemcpy is the ++ value of wto. <br> This function was introduced in ++ Amendment 1 to ISO C90. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The mempcpy function is nearly identical to the memcpy function. ++ It copies size bytes from the object beginning at from into the ++ object pointed to by to. But instead of returning the value of ++ to it returns a pointer to the byte following the last written ++ byte in the object beginning at to. I.e., the value is ((void *) ++ ((char *) to + size)). <br> This function is useful in ++ situations where a number of objects shall be copied to ++ consecutive memory positions. <br> @smallexample void * ++ combine (void *o1, size_t s1, void *o2, size_t s2) void ++ *result = malloc (s1 + s2); if (result != NULL) mempcpy ++ (mempcpy (result, o1, s1), o2, s2); return result; @ @end ++ smallexample <br> This function is a GNU extension. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The wmempcpy function is nearly identical to the wmemcpy ++ function. It copies size wide characters from the object ++ beginning at wfrom into the object pointed to by wto. But ++ instead of returning the value of wto it returns a pointer to ++ the wide character following the last written wide character in ++ the object beginning at wto. I.e., the value is wto + size. ++ <br> This function is useful in situations where a number ++ of objects shall be copied to consecutive memory positions. ++ <br> The following is a possible implementation of wmemcpy ++ but there are more optimizations possible. <br> ++ @smallexample wchar_t * wmempcpy (wchar_t *restrict wto, const ++ wchar_t *restrict wfrom, size_t size) return ++ (wchar_t *) mempcpy (wto, wfrom, size * sizeof (wchar_t)); @ ++ @end smallexample <br> This function is a GNU extension. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ memmove copies the size bytes at from into the size bytes at to, ++ even if those two blocks of space overlap. In the case of ++ overlap, memmove is careful to copy the original values of the ++ bytes in the block at from, including those bytes which also ++ belong to the block at to. <br> The value returned by ++ memmove is the value of to. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ wmemmove copies the size wide characters at wfrom into the size ++ wide characters at wto, even if those two blocks of space ++ overlap. In the case of overlap, memmove is careful to copy the ++ original values of the wide characters in the block at wfrom, ++ including those wide characters which also belong to the block ++ at wto. <br> The following is a possible implementation of ++ wmemcpy but there are more optimizations possible. <br> ++ @smallexample wchar_t * wmempcpy (wchar_t *restrict wto, const ++ wchar_t *restrict wfrom, size_t size) return ++ (wchar_t *) mempcpy (wto, wfrom, size * sizeof (wchar_t)); @ ++ @end smallexample <br> The value returned by wmemmove is ++ the value of wto. <br> This function is a GNU extension. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function copies no more than size bytes from from to to, ++ stopping if a byte matching c is found. The return value is a ++ pointer into to one byte past where c was copied, or a null ++ pointer if no byte matching c appeared in the first size bytes ++ of from. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function copies the value of c (converted to an unsigned ++ char) into each of the first size bytes of the object beginning ++ at block. It returns the value of block. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function copies the value of wc into each of the first size ++ wide characters of the object beginning at block. It returns ++ the value of block. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This copies characters from the string from (up to and including ++ the terminating null character) into the string to. Like ++ memcpy, this function has undefined results if the strings ++ overlap. The return value is the value of to. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This copies wide characters from the string wfrom (up to and ++ including the terminating null wide character) into the string ++ wto. Like wmemcpy, this function has undefined results if the ++ strings overlap. The return value is the value of wto. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to strcpy but always copies exactly ++ size characters into to. <br> If the length of from is ++ more than size, then strncpy copies just the first size ++ characters. Note that in this case there is no null terminator ++ written into to. <br> If the length of from is less than ++ size, then strncpy copies all of from, followed by enough null ++ characters to add up to size characters in all. This behavior ++ is rarely useful, but it is specified by the ISO C standard. ++ <br> The behavior of strncpy is undefined if the strings ++ overlap. <br> Using strncpy as opposed to strcpy is a way ++ to avoid bugs relating to writing past the end of the allocated ++ space for to. However, it can also make your program much slower ++ in one common case: copying a string which is probably small ++ into a potentially large buffer. In this case, size may be ++ large, and when it is, strncpy will waste a considerable amount ++ of time copying null characters. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to wcscpy but always copies exactly ++ size wide characters into wto. <br> If the length of wfrom ++ is more than size, then wcsncpy copies just the first size wide ++ characters. Note that in this case there is no null terminator ++ written into wto. <br> If the length of wfrom is less than ++ size, then wcsncpy copies all of wfrom, followed by enough null ++ wide characters to add up to size wide characters in all. This ++ behavior is rarely useful, but it is specified by the ISO C ++ standard. <br> The behavior of wcsncpy is undefined if the ++ strings overlap. <br> Using wcsncpy as opposed to wcscpy ++ is a way to avoid bugs relating to writing past the end of the ++ allocated space for wto. However, it can also make your program ++ much slower in one common case: copying a string which is ++ probably small into a potentially large buffer. In this case, ++ size may be large, and when it is, wcsncpy will waste a ++ considerable amount of time copying null wide characters. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function copies the null-terminated string s into a newly ++ allocated string. The string is allocated using malloc; see ++ Unconstrained Allocation. If malloc cannot allocate space for ++ the new string, strdup returns a null pointer. Otherwise it ++ returns a pointer to the new string. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function copies the null-terminated wide character string ++ ws into a newly allocated string. The string is allocated using ++ malloc; see Unconstrained Allocation. If malloc cannot allocate ++ space for the new string, wcsdup returns a null pointer. ++ Otherwise it returns a pointer to the new wide character string. ++ <br> This function is a GNU extension. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to strdup but always copies at most ++ size characters into the newly allocated string. <br> If ++ the length of s is more than size, then strndup copies just the ++ first size characters and adds a closing null terminator. ++ Otherwise all characters are copied and the string is ++ terminated. <br> This function is different to strncpy in ++ that it always terminates the destination string. <br> ++ strndup is a GNU extension. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is like strcpy, except that it returns a pointer ++ to the end of the string to (that is, the address of the ++ terminating null character to + strlen (from)) rather than the ++ beginning. <br> For example, this program uses stpcpy to ++ concatenate foo and bar to produce foobar, which it then prints. ++ <br> @smallexample @include stpcpy.c.texi @end ++ smallexample <br> This function is not part of the ISO or ++ POSIX standards, and is not customary on Unix systems, but we ++ did not invent it either. Perhaps it comes from MS-DOG. ++ <br> Its behavior is undefined if the strings overlap. ++ The function is declared in string.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is like wcscpy, except that it returns a pointer ++ to the end of the string wto (that is, the address of the ++ terminating null character wto + strlen (wfrom)) rather than the ++ beginning. <br> This function is not part of ISO or POSIX ++ but was found useful while developing the GNU C Library itself. ++ <br> The behavior of wcpcpy is undefined if the strings ++ overlap. <br> wcpcpy is a GNU extension and is declared in ++ wchar.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to stpcpy but copies always exactly ++ size characters into to. <br> If the length of from is ++ more then size, then stpncpy copies just the first size ++ characters and returns a pointer to the character directly ++ following the one which was copied last. Note that in this case ++ there is no null terminator written into to. <br> If the ++ length of from is less than size, then stpncpy copies all of ++ from, followed by enough null characters to add up to size ++ characters in all. This behavior is rarely useful, but it is ++ implemented to be useful in contexts where this behavior of the ++ strncpy is used. stpncpy returns a pointer to the first written ++ null character. <br> This function is not part of ISO or ++ POSIX but was found useful while developing the GNU C Library ++ itself. <br> Its behavior is undefined if the strings ++ overlap. The function is declared in string.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to wcpcpy but copies always exactly ++ wsize characters into wto. <br> If the length of wfrom is ++ more then size, then wcpncpy copies just the first size wide ++ characters and returns a pointer to the wide character directly ++ following the one which was copied last. Note that in this case ++ there is no null terminator written into wto. <br> If the ++ length of wfrom is less than size, then wcpncpy copies all of ++ wfrom, followed by enough null characters to add up to size ++ characters in all. This behavior is rarely useful, but it is ++ implemented to be useful in contexts where this behavior of the ++ wcsncpy is used. wcpncpy returns a pointer to the first written ++ null character. <br> This function is not part of ISO or ++ POSIX but was found useful while developing the GNU C Library ++ itself. <br> Its behavior is undefined if the strings ++ overlap. <br> wcpncpy is a GNU extension and is declared ++ in wchar.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The strcat function is similar to strcpy, except that the ++ characters from from are concatenated or appended to the end of ++ to, instead of overwriting it. That is, the first character ++ from from overwrites the null character marking the end of to. ++ <br> An equivalent definition for strcat would be: ++ <br> @smallexample char * strcat (char *restrict to, const ++ char *restrict from) strcpy (to + strlen (to), from); ++ return to; @ @end smallexample <br> This function has ++ undefined results if the strings overlap. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The wcscat function is similar to wcscpy, except that the ++ characters from wfrom are concatenated or appended to the end of ++ wto, instead of overwriting it. That is, the first character ++ from wfrom overwrites the null character marking the end of wto. ++ <br> An equivalent definition for wcscat would be: ++ <br> @smallexample wchar_t * wcscat (wchar_t *wto, const ++ wchar_t *wfrom) wcscpy (wto + wcslen (wto), wfrom); return ++ wto; @ @end smallexample <br> This function has undefined ++ results if the strings overlap. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is like strcat except that not more than size ++ characters from from are appended to the end of to. A single ++ null character is also always appended to to, so the total ++ allocated size of to must be at least size + 1 bytes longer than ++ its initial length. <br> The strncat function could be ++ implemented like this: <br> @smallexample @group char * ++ strncat (char *to, const char *from, size_t size) to[strlen ++ (to) + size] = '\0'; strncpy (to + strlen (to), from, size); ++ return to; @ @end group @end smallexample <br> The ++ behavior of strncat is undefined if the strings overlap. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is like wcscat except that not more than size ++ characters from from are appended to the end of to. A single ++ null character is also always appended to to, so the total ++ allocated size of to must be at least size + 1 bytes longer than ++ its initial length. <br> The wcsncat function could be ++ implemented like this: <br> @smallexample @group wchar_t * ++ wcsncat (wchar_t *restrict wto, const wchar_t *restrict wfrom, ++ size_t size) wto[wcslen (to) + size] = L'\0'; ++ wcsncpy (wto + wcslen (wto), wfrom, size); return wto; @ @end ++ group @end smallexample <br> The behavior of wcsncat is ++ undefined if the strings overlap. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This is a partially obsolete alternative for memmove, derived ++ from BSD. Note that it is not quite equivalent to memmove, ++ because the arguments are not in the same order and there is no ++ return value. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This is a partially obsolete alternative for memset, derived ++ from BSD. Note that it is not as general as memset, because the ++ only value it can store is zero. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The function memcmp compares the size bytes of memory beginning ++ at a1 against the size bytes of memory beginning at a2. The ++ value returned has the same sign as the difference between the ++ first differing pair of bytes (interpreted as unsigned char ++ objects, then promoted to int). <br> If the contents of ++ the two blocks are equal, memcmp returns 0. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The function wmemcmp compares the size wide characters beginning ++ at a1 against the size wide characters beginning at a2. The ++ value returned is smaller than or larger than zero depending on ++ whether the first differing wide character is a1 is smaller or ++ larger than the corresponding character in a2. <br> If the ++ contents of the two blocks are equal, wmemcmp returns 0. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The strcmp function compares the string s1 against s2, returning ++ a value that has the same sign as the difference between the ++ first differing pair of characters (interpreted as unsigned char ++ objects, then promoted to int). <br> If the two strings ++ are equal, strcmp returns 0. <br> A consequence of the ++ ordering used by strcmp is that if s1 is an initial substring of ++ s2, then s1 is considered to be ``less than'' s2. <br> ++ strcmp does not take sorting conventions of the language the ++ strings are written in into account. To get that one has to use ++ strcoll. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> The wcscmp function compares the wide character ++ string ws1 against ws2. The value returned is smaller than or ++ larger than zero depending on whether the first differing wide ++ character is ws1 is smaller or larger than the corresponding ++ character in ws2. <br> If the two strings are equal, ++ wcscmp returns 0. <br> A consequence of the ordering used ++ by wcscmp is that if ws1 is an initial substring of ws2, then ++ ws1 is considered to be ``less than'' ws2. <br> wcscmp ++ does not take sorting conventions of the language the strings ++ are written in into account. To get that one has to use ++ wcscoll. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is like strcmp, except that differences in case ++ are ignored. How uppercase and lowercase characters are related ++ is determined by the currently selected locale. In the standard ++ "C" locale the characters @"A and @"a do not match but in a ++ locale which regards these characters as parts of the alphabet ++ they do match. <br> @noindent strcasecmp is derived from ++ BSD. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is like wcscmp, except that differences in case ++ are ignored. How uppercase and lowercase characters are related ++ is determined by the currently selected locale. In the standard ++ "C" locale the characters @"A and @"a do not match but in a ++ locale which regards these characters as parts of the alphabet ++ they do match. <br> @noindent wcscasecmp is a GNU ++ extension. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is the similar to strcmp, except that no more than ++ size wide characters are compared. In other words, if the two ++ strings are the same in their first size wide characters, the ++ return value is zero. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is the similar to wcscmp, except that no more than ++ size wide characters are compared. In other words, if the two ++ strings are the same in their first size wide characters, the ++ return value is zero. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is like strncmp, except that differences in case ++ are ignored. Like strcasecmp, it is locale dependent how ++ uppercase and lowercase characters are related. <br> ++ @noindent strncasecmp is a GNU extension. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is like wcsncmp, except that differences in case ++ are ignored. Like wcscasecmp, it is locale dependent how ++ uppercase and lowercase characters are related. <br> ++ @noindent wcsncasecmp is a GNU extension. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The strverscmp function compares the string s1 against s2, ++ considering them as holding indices/version numbers. Return ++ value follows the same conventions as found in the strverscmp ++ function. In fact, if s1 and s2 contain no digits, strverscmp ++ behaves like strcmp. <br> Basically, we compare strings ++ normally (character by character), until we find a digit in each ++ string - then we enter a special comparison mode, where each ++ sequence of digits is taken as a whole. If we reach the end of ++ these two parts without noticing a difference, we return to the ++ standard comparison mode. There are two types of numeric parts: ++ "integral" and "fractional" (those begin with a '0'). The types ++ of the numeric parts affect the way we sort them: <br> ++ @itemize @bullet @item integral/integral: we compare values as ++ you would expect. <br> @item fractional/integral: the ++ fractional part is less than the integral one. Again, no ++ surprise. <br> @item fractional/fractional: the things ++ become a bit more complex. If the common prefix contains only ++ leading zeroes, the longest part is less than the other one; ++ else the comparison behaves normally. @end itemize <br> ++ @smallexample strverscmp ("no digit", "no digit") 0 /* ++ same behavior as strcmp. */ strverscmp ("item#99", "item#100") ++ <0 /* same prefix, but 99 < 100. */ strverscmp ++ ("alpha1", "alpha001") >0 /* fractional part inferior ++ to integral one. */ strverscmp ("part1_f012", "part1_f01") ++ >0 /* two fractional parts. */ strverscmp ("foo.009", ++ "foo.0") <0 /* idem, but with leading zeroes only. */ ++ @end smallexample <br> This function is especially useful ++ when dealing with filename sorting, because filenames frequently ++ hold indices/version numbers. <br> strverscmp is a GNU ++ extension. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This is an obsolete alias for memcmp, derived from BSD. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The strcoll function is similar to strcmp but uses the collating ++ sequence of the current locale for collation (the LC_COLLATE ++ locale). ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The wcscoll function is similar to wcscmp but uses the collating ++ sequence of the current locale for collation (the LC_COLLATE ++ locale). ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The function strxfrm transforms the string from using the ++ collation transformation determined by the locale currently ++ selected for collation, and stores the transformed string in the ++ array to. Up to size characters (including a terminating null ++ character) are stored. <br> The behavior is undefined if ++ the strings to and from overlap; see Copying and Concatenation. ++ <br> The return value is the length of the entire ++ transformed string. This value is not affected by the value of ++ size, but if it is greater or equal than size, it means that the ++ transformed string did not entirely fit in the array to. In ++ this case, only as much of the string as actually fits was ++ stored. To get the whole transformed string, call strxfrm again ++ with a bigger output array. <br> The transformed string ++ may be longer than the original string, and it may also be ++ shorter. <br> If size is zero, no characters are stored in ++ to. In this case, strxfrm simply returns the number of ++ characters that would be the length of the transformed string. ++ This is useful for determining what size the allocated array ++ should be. It does not matter what to is if size is zero; to ++ may even be a null pointer. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The function wcsxfrm transforms wide character string wfrom ++ using the collation transformation determined by the locale ++ currently selected for collation, and stores the transformed ++ string in the array wto. Up to size wide characters (including ++ a terminating null character) are stored. <br> The ++ behavior is undefined if the strings wto and wfrom overlap; see ++ Copying and Concatenation. <br> The return value is the ++ length of the entire transformed wide character string. This ++ value is not affected by the value of size, but if it is greater ++ or equal than size, it means that the transformed wide character ++ string did not entirely fit in the array wto. In this case, ++ only as much of the wide character string as actually fits was ++ stored. To get the whole transformed wide character string, ++ call wcsxfrm again with a bigger output array. <br> The ++ transformed wide character string may be longer than the ++ original wide character string, and it may also be shorter. ++ <br> If size is zero, no characters are stored in to. In ++ this case, wcsxfrm simply returns the number of wide characters ++ that would be the length of the transformed wide character ++ string. This is useful for determining what size the allocated ++ array should be (remember to multiply with sizeof (wchar_t)). ++ It does not matter what wto is if size is zero; wto may even be ++ a null pointer. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function finds the first occurrence of the byte c ++ (converted to an unsigned char) in the initial size bytes of the ++ object beginning at block. The return value is a pointer to the ++ located byte, or a null pointer if no match was found. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function finds the first occurrence of the wide character ++ wc in the initial size wide characters of the object beginning ++ at block. The return value is a pointer to the located wide ++ character, or a null pointer if no match was found. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ Often the memchr function is used with the knowledge that the ++ byte c is available in the memory block specified by the ++ parameters. But this means that the size parameter is not ++ really needed and that the tests performed with it at runtime ++ (to check whether the end of the block is reached) are not ++ needed. <br> The rawmemchr function exists for just this ++ situation which is surprisingly frequent. The interface is ++ similar to memchr except that the size parameter is missing. ++ The function will look beyond the end of the block pointed to by ++ block in case the programmer made an error in assuming that the ++ byte c is present in the block. In this case the result is ++ unspecified. Otherwise the return value is a pointer to the ++ located byte. <br> This function is of special interest ++ when looking for the end of a string. Since all strings are ++ terminated by a null byte a call like <br> @smallexample ++ rawmemchr (str, '\0') @end smallexample <br> @noindent ++ will never go beyond the end of the string. <br> This ++ function is a GNU extension. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The function memrchr is like memchr, except that it searches ++ backwards from the end of the block defined by block and size ++ (instead of forwards from the front). ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The strchr function finds the first occurrence of the character ++ c (converted to a char) in the null-terminated string beginning ++ at string. The return value is a pointer to the located ++ character, or a null pointer if no match was found. <br> ++ For example, @smallexample strchr ("hello, world", 'l') ++ "llo, world" strchr ("hello, world", '?') NULL @end ++ smallexample <br> The terminating null character is ++ considered to be part of the string, so you can use this ++ function get a pointer to the end of a string by specifying a ++ null character as the value of the c argument. It would be ++ better (but less portable) to use strchrnul in this case, ++ though. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The wcschr function finds the first occurrence of the wide ++ character wc in the null-terminated wide character string ++ beginning at wstring. The return value is a pointer to the ++ located wide character, or a null pointer if no match was found. ++ <br> The terminating null character is considered to be ++ part of the wide character string, so you can use this function ++ get a pointer to the end of a wide character string by ++ specifying a null wude character as the value of the wc ++ argument. It would be better (but less portable) to use ++ wcschrnul in this case, though. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ strchrnul is the same as strchr except that if it does not find ++ the character, it returns a pointer to string's terminating null ++ character rather than a null pointer. <br> This function ++ is a GNU extension. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ wcschrnul is the same as wcschr except that if it does not find ++ the wide character, it returns a pointer to wide character ++ string's terminating null wide character rather than a null ++ pointer. <br> This function is a GNU extension. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The function strrchr is like strchr, except that it searches ++ backwards from the end of the string string (instead of forwards ++ from the front). <br> For example, @smallexample strrchr ++ ("hello, world", 'l') "ld" @end smallexample ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The function wcsrchr is like wcschr, except that it searches ++ backwards from the end of the string wstring (instead of ++ forwards from the front). ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This is like strchr, except that it searches haystack for a ++ substring needle rather than just a single character. It ++ returns a pointer into the string haystack that is the first ++ character of the substring, or a null pointer if no match was ++ found. If needle is an empty string, the function returns ++ haystack. <br> For example, @smallexample strstr ("hello, ++ world", "l") "llo, world" strstr ("hello, world", "wo") ++ "world" @end smallexample ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This is like wcschr, except that it searches haystack for a ++ substring needle rather than just a single wide character. It ++ returns a pointer into the string haystack that is the first ++ wide character of the substring, or a null pointer if no match ++ was found. If needle is an empty string, the function returns ++ haystack. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ wcsstr is an depricated alias for wcsstr. This is the name ++ originally used in the X/Open Portability Guide before the ++ Amendment 1 to ISO C90 was published. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This is like strstr, except that it ignores case in searching ++ for the substring. Like strcasecmp, it is locale dependent how ++ uppercase and lowercase characters are related. <br> ++ <br> For example, @smallexample strstr ("hello, world", ++ "L") "llo, world" strstr ("hello, World", "wo") ++ "World" @end smallexample ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This is like strstr, but needle and haystack are byte arrays ++ rather than null-terminated strings. needle-len is the length ++ of needle and haystack-len is the length of haystack.@refill ++ <br> This function is a GNU extension. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The strspn (``string span'') function returns the length of the ++ initial substring of string that consists entirely of characters ++ that are members of the set specified by the string skipset. ++ The order of the characters in skipset is not important. ++ <br> For example, @smallexample strspn ("hello, world", ++ "abcdefghijklmnopqrstuvwxyz") 5 @end smallexample ++ <br> Note that ``character'' is here used in the sense of ++ byte. In a string using a multibyte character encoding ++ (abstract) character consisting of more than one byte are not ++ treated as an entity. Each byte is treated separately. The ++ function is not locale-dependent. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The wcsspn (``wide character string span'') function returns the ++ length of the initial substring of wstring that consists ++ entirely of wide characters that are members of the set ++ specified by the string skipset. The order of the wide ++ characters in skipset is not important. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The strcspn (``string complement span'') function returns the ++ length of the initial substring of string that consists entirely ++ of characters that are not members of the set specified by the ++ string stopset. (In other words, it returns the offset of the ++ first character in string that is a member of the set stopset.) ++ <br> For example, @smallexample strcspn ("hello, world", " ++ \t\n,.;!?") 5 @end smallexample <br> Note that ++ ``character'' is here used in the sense of byte. In a string ++ using a multibyte character encoding (abstract) character ++ consisting of more than one byte are not treated as an entity. ++ Each byte is treated separately. The function is not ++ locale-dependent. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The wcscspn (``wide character string complement span'') function ++ returns the length of the initial substring of wstring that ++ consists entirely of wide characters that are not members of the ++ set specified by the string stopset. (In other words, it ++ returns the offset of the first character in string that is a ++ member of the set stopset.) ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The strpbrk (``string pointer break'') function is related to ++ strcspn, except that it returns a pointer to the first character ++ in string that is a member of the set stopset instead of the ++ length of the initial substring. It returns a null pointer if ++ no such character from stopset is found. <br> @c @group ++ Invalid outside the example. For example, <br> ++ @smallexample strpbrk ("hello, world", " \t\n,.;!?") ", ++ world" @end smallexample @c @end group <br> Note that ++ ``character'' is here used in the sense of byte. In a string ++ using a multibyte character encoding (abstract) character ++ consisting of more than one byte are not treated as an entity. ++ Each byte is treated separately. The function is not ++ locale-dependent. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The wcspbrk (``wide character string pointer break'') function ++ is related to wcscspn, except that it returns a pointer to the ++ first wide character in wstring that is a member of the set ++ stopset instead of the length of the initial substring. It ++ returns a null pointer if no such character from stopset is ++ found. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ index is another name for strchr; they are exactly the same. New ++ code should always use strchr since this name is defined in ISO ++ C while index is a BSD invention which never was available on ++ System V derived systems. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ rindex is another name for strrchr; they are exactly the same. ++ New code should always use strrchr since this name is defined in ++ ISO C while rindex is a BSD invention which never was available ++ on System V derived systems. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ A string can be split into tokens by making a series of calls to ++ the function strtok. <br> The string to be split up is ++ passed as the newstring argument on the first call only. The ++ strtok function uses this to set up some internal state ++ information. Subsequent calls to get additional tokens from the ++ same string are indicated by passing a null pointer as the ++ newstring argument. Calling strtok with another non-null ++ newstring argument reinitializes the state information. It is ++ guaranteed that no other library function ever calls strtok ++ behind your back (which would mess up this internal state ++ information). <br> The delimiters argument is a string ++ that specifies a set of delimiters that may surround the token ++ being extracted. All the initial characters that are members of ++ this set are discarded. The first character that is not a ++ member of this set of delimiters marks the beginning of the next ++ token. The end of the token is found by looking for the next ++ character that is a member of the delimiter set. This character ++ in the original string newstring is overwritten by a null ++ character, and the pointer to the beginning of the token in ++ newstring is returned. <br> On the next call to strtok, ++ the searching begins at the next character beyond the one that ++ marked the end of the previous token. Note that the set of ++ delimiters delimiters do not have to be the same on every call ++ in a series of calls to strtok. <br> If the end of the ++ string newstring is reached, or if the remainder of string ++ consists only of delimiter characters, strtok returns a null ++ pointer. <br> Note that ``character'' is here used in the ++ sense of byte. In a string using a multibyte character encoding ++ (abstract) character consisting of more than one byte are not ++ treated as an entity. Each byte is treated separately. The ++ function is not locale-dependent. <br> Note that ++ ``character'' is here used in the sense of byte. In a string ++ using a multibyte character encoding (abstract) character ++ consisting of more than one byte are not treated as an entity. ++ Each byte is treated separately. The function is not ++ locale-dependent. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ A string can be split into tokens by making a series of calls to ++ the function wcstok. <br> The string to be split up is ++ passed as the newstring argument on the first call only. The ++ wcstok function uses this to set up some internal state ++ information. Subsequent calls to get additional tokens from the ++ same wide character string are indicated by passing a null ++ pointer as the newstring argument. Calling wcstok with another ++ non-null newstring argument reinitializes the state information. ++ It is guaranteed that no other library function ever calls ++ wcstok behind your back (which would mess up this internal state ++ information). <br> The delimiters argument is a wide ++ character string that specifies a set of delimiters that may ++ surround the token being extracted. All the initial wide ++ characters that are members of this set are discarded. The first ++ wide character that is not a member of this set of delimiters ++ marks the beginning of the next token. The end of the token is ++ found by looking for the next wide character that is a member of ++ the delimiter set. This wide character in the original wide ++ character string newstring is overwritten by a null wide ++ character, and the pointer to the beginning of the token in ++ newstring is returned. <br> On the next call to wcstok, ++ the searching begins at the next wide character beyond the one ++ that marked the end of the previous token. Note that the set of ++ delimiters delimiters do not have to be the same on every call ++ in a series of calls to wcstok. <br> If the end of the ++ wide character string newstring is reached, or if the remainder ++ of string consists only of delimiter wide characters, wcstok ++ returns a null pointer. <br> Note that ``character'' is ++ here used in the sense of byte. In a string using a multibyte ++ character encoding (abstract) character consisting of more than ++ one byte are not treated as an entity. Each byte is treated ++ separately. The function is not locale-dependent. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ Just like strtok, this function splits the string into several ++ tokens which can be accessed by successive calls to strtok_r. ++ The difference is that the information about the next token is ++ stored in the space pointed to by the third argument, save_ptr, ++ which is a pointer to a string pointer. Calling strtok_r with a ++ null pointer for newstring and leaving save_ptr between the ++ calls unchanged does the job without hindering reentrancy. ++ <br> This function is defined in POSIX.1 and can be found ++ on many systems which support multi-threading. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function has a similar functionality as strtok_r with the ++ newstring argument replaced by the save_ptr argument. The ++ initialization of the moving pointer has to be done by the user. ++ Successive calls to strsep move the pointer along the tokens ++ separated by delimiter, returning the address of the next token ++ and updating string_ptr to point to the beginning of the next ++ token. <br> One difference between strsep and strtok_r is ++ that if the input string contains more than one character from ++ delimiter in a row strsep returns an empty string for each pair ++ of characters from delimiter. This means that a program ++ normally should test for strsep returning an empty string before ++ processing it. <br> This function was introduced in 4.3BSD ++ and therefore is widely available. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The GNU version of the basename function returns the last ++ component of the path in filename. This function is the ++ preferred usage, since it does not modify the argument, ++ filename, and respects trailing slashes. The prototype for ++ basename can be found in string.h. Note, this function is ++ overriden by the XPG version, if libgen.h is included. ++ <br> Example of using GNU basename: <br> ++ @smallexample #include <string.h> <br> int main (int ++ argc, char *argv[]) char *prog = basename (argv[0]); ++ <br> if (argc < 2) fprintf (stderr, "Usage ++ %s <arg>\n", prog); exit (1); @ <br> @ ++ @end smallexample <br> Portability Note: This function may ++ produce different results on different systems. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The dirname function is the compliment to the XPG version of ++ basename. It returns the parent directory of the file specified ++ by path. If path is NULL, an empty string, or contains no '/' ++ characters, then "." is returned. The prototype for this ++ function can be found in libgen.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> strfry creates a pseudorandom anagram of a string, ++ replacing the input with the anagram in place. For each ++ position in the string, strfry swaps it with a position in the ++ string selected at random (from a uniform distribution). The ++ two positions may be the same. <br> The return value of ++ strfry is always string. <br> Portability Note: This ++ function is unique to the GNU C library. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> memfrob transforms (frobnicates) each byte of the ++ data structure at mem, which is length bytes long, by bitwise ++ exclusive oring it with binary 00101010. It does the ++ transformation in place and its return value is always mem. ++ <br> Note that memfrob a second time on the same data ++ structure returns it to its original state. <br> This is a ++ good function for hiding information from someone who doesn't ++ want to see it or doesn't want to see it very much. To really ++ prevent people from retrieving the information, use stronger ++ encryption such as that described in . <br> Portability ++ Note: This function is unique to the GNU C library. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function encodes a 32-bit input value using characters from ++ the basic character set. It returns a pointer to a 6 character ++ buffer which contains an encoded version of n. To encode a ++ series of bytes the user must copy the returned string to a ++ destination buffer. It returns the empty string if n is zero, ++ which is somewhat bizarre but mandated by the standard.@* ++ Warning: Since a static buffer is used this function should not ++ be used in multi-threaded programs. There is no thread-safe ++ alternative to this function in the C library.@* Compatibility ++ Note: The XPG standard states that the return value of l64a is ++ undefined if n is negative. In the GNU implementation, l64a ++ treats its argument as unsigned, so it will return a sensible ++ encoding for any nonzero n; however, portable programs should ++ not rely on this. <br> To encode a large buffer l64a must ++ be called in a loop, once for each 32-bit word of the buffer. ++ For example, one could do something like this: <br> ++ @smallexample char * encode (const void *buf, size_t len) /* ++ We know in advance how long the buffer has to be. */ unsigned ++ char *in = (unsigned char *) buf; char *out = malloc (6 + ++ ((len + 3) / 4) * 6 + 1); char *cp = out; <br> /* ++ Encode the length. */ /* Using `htonl' is necessary so that ++ the data can be decoded even on machines with different ++ byte order. */ <br> cp = mempcpy (cp, l64a (htonl ++ (len)), 6); <br> while (len > 3) unsigned ++ long int n = *in++; n = (n << 8) | *in++; n = ++ (n << 8) | *in++; n = (n << 8) | *in++; ++ len -= 4; if (n) cp = mempcpy (cp, l64a (htonl ++ (n)), 6); else /* `l64a' returns the empty ++ string for n==0, so we must generate its ++ encoding ("......") by hand. */ cp = stpcpy (cp, ++ "......"); @ if (len > 0) unsigned long int ++ n = *in++; if (--len > 0) n = (n ++ << 8) | *in++; if (--len > 0) n = ++ (n << 8) | *in; @ memcpy (cp, l64a (htonl ++ (n)), 6); cp += 6; @ *cp = '\0'; return out; @ ++ @end smallexample <br> It is strange that the library does ++ not provide the complete functionality needed but so be it. ++ <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The parameter string should contain a string which was produced ++ by a call to l64a. The function processes at least 6 characters ++ of this string, and decodes the characters it finds according to ++ the table below. It stops decoding when it finds a character ++ not in the table, rather like atoi; if you have a buffer which ++ has been broken into lines, you must be careful to skip over the ++ end-of-line characters. <br> The decoded number is ++ returned as a long int value. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The argz_create function converts the Unix-style argument vector ++ argv (a vector of pointers to normal C strings, terminated by ++ (char *)0; Program Arguments) into an argz vector with the same ++ elements, which is returned in argz and argz_len. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The argz_create_sep function converts the null-terminated string ++ string into an argz vector (returned in argz and argz_len) by ++ splitting it into elements at every occurrence of the character ++ sep. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ Returns the number of elements in the argz vector argz and ++ argz_len. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The argz_extract function converts the argz vector argz and ++ argz_len into a Unix-style argument vector stored in argv, by ++ putting pointers to every element in argz into successive ++ positions in argv, followed by a terminator of 0. Argv must be ++ pre-allocated with enough space to hold all the elements in argz ++ plus the terminating (char *)0 ((argz_count (argz, argz_len) + ++ 1) * sizeof (char *) bytes should be enough). Note that the ++ string pointers stored into argv point into argz---they are not ++ copies---and so argz must be copied if it will be changed while ++ argv is still active. This function is useful for passing the ++ elements in argz to an exec function (Executing a File). ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The argz_stringify converts argz into a normal string with the ++ elements separated by the character sep, by replacing each '\0' ++ inside argz (except the last one, which terminates the string) ++ with sep. This is handy for printing argz in a readable manner. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The argz_add function adds the string str to the end of the argz ++ vector *argz, and updates *argz and *argz_len accordingly. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The argz_add_sep function is similar to argz_add, but str is ++ split into separate elements in the result at occurrences of the ++ character delim. This is useful, for instance, for adding the ++ components of a Unix search path to an argz vector, by using a ++ value of ':' for delim. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The argz_append function appends buf_len bytes starting at buf ++ to the argz vector *argz, reallocating *argz to accommodate it, ++ and adding buf_len to *argz_len. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ If entry points to the beginning of one of the elements in the ++ argz vector *argz, the argz_delete function will remove this ++ entry and reallocate *argz, modifying *argz and *argz_len ++ accordingly. Note that as destructive argz functions usually ++ reallocate their argz argument, pointers into argz vectors such ++ as entry will then become invalid. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The argz_insert function inserts the string entry into the argz ++ vector *argz at a point just before the existing element pointed ++ to by before, reallocating *argz and updating *argz and ++ *argz_len. If before is 0, entry is added to the end instead ++ (as if by argz_add). Since the first element is in fact the ++ same as *argz, passing in *argz as the value of before will ++ result in entry being inserted at the beginning. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The argz_next function provides a convenient way of iterating ++ over the elements in the argz vector argz. It returns a pointer ++ to the next element in argz after the element entry, or 0 if ++ there are no elements following entry. If entry is 0, the first ++ element of argz is returned. <br> This behavior suggests ++ two styles of iteration: <br> @smallexample char ++ *entry = 0; while ((entry = argz_next (argz, argz_len, ++ entry))) action; @end smallexample <br> (the double ++ parentheses are necessary to make some C compilers shut up about ++ what they consider a questionable while-test) and: <br> ++ @smallexample char *entry; for (entry = argz; ++ entry; entry = argz_next (argz, argz_len, entry)) ++ action; @end smallexample <br> Note that the latter ++ depends on argz having a value of 0 if it is empty (rather than ++ a pointer to an empty block of memory); this invariant is ++ maintained for argz vectors created by the functions here. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ Replace any occurrences of the string str in argz with with, ++ reallocating argz as necessary. If replace_count is non-zero, ++ *replace_count will be incremented by number of replacements ++ performed. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The envz_entry function finds the entry in envz with the name ++ name, and returns a pointer to the whole entry---that is, the ++ argz element which begins with name followed by a '=' character. ++ If there is no entry with that name, 0 is returned. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The envz_get function finds the entry in envz with the name name ++ (like envz_entry), and returns a pointer to the value portion of ++ that entry (following the '='). If there is no entry with that ++ name (or only a null entry), 0 is returned. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The envz_add function adds an entry to *envz (updating *envz and ++ *envz_len) with the name name, and value value. If an entry ++ with the same name already exists in envz, it is removed first. ++ If value is 0, then the new entry will the special null type of ++ entry (mentioned above). ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The envz_merge function adds each entry in envz2 to envz, as if ++ with envz_add, updating *envz and *envz_len. If override is ++ true, then values in envz2 will supersede those with the same ++ name in envz, otherwise not. <br> Null entries are treated ++ just like other entries in this respect, so a null entry in envz ++ can prevent an entry of the same name in envz2 from being added ++ to envz, if override is false. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The envz_strip function removes any null entries from envz, ++ updating *envz and *envz_len. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function returns the host name of the system on which it is ++ called, in the array name. The size argument specifies the size ++ of this array, in bytes. Note that this is not the DNS ++ hostname. If the system participates in DNS, this is the FQDN ++ (see above). <br> The return value is 0 on success and -1 ++ on failure. In the GNU C library, gethostname fails if size is ++ not large enough; then you can try again with a larger array. ++ The following errno error condition is defined for this ++ function: <br> @table @code @item ENAMETOOLONG The size ++ argument is less than the size of the host name plus one. @end ++ table <br> @pindex sys/param.h On some systems, there is a ++ symbol for the maximum possible host name length: ++ MAXHOSTNAMELEN. It is defined in sys/param.h. But you can't ++ count on this to exist, so it is cleaner to handle failure and ++ try again. <br> gethostname stores the beginning of the ++ host name in name 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. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The sethostname function sets the host name of the system that ++ calls it to name, a string with length length. Only privileged ++ processes are permitted to do this. <br> Usually ++ sethostname gets called just once, at system boot time. Often, ++ the program that calls it sets it to the value it finds in the ++ file /etc/hostname. @cindex /etc/hostname <br> Be sure to ++ set the host name to the full host name, not just the DNS ++ hostname (see above). <br> The return value is 0 on ++ success and -1 on failure. The following errno error condition ++ is defined for this function: <br> @table @code @item ++ EPERM This process cannot set the host name because it is not ++ privileged. @end table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ @cindex NIS domain name @cindex YP domain name <br> ++ getdomainname 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 gethostname. <br> The ++ specifics of this function are analogous to gethostname, above. ++ <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ @cindex NIS domain name @cindex YP domain name <br> ++ getdomainname 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 sethostname. <br> The ++ specifics of this function are analogous to sethostname, above. ++ <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ 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 long int. ++ However, on some systems it is a meaningless but unique number ++ which is hard-coded for each machine. <br> This is not ++ widely used. It arose in BSD 4.2, but was dropped in BSD 4.4. ++ It is not required by POSIX. <br> The proper way to query ++ the IP address is to use gethostbyname on the results of ++ gethostname. For more information on IP addresses, . ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The sethostid function sets the ``host ID'' of the host machine ++ to id. Only privileged processes are permitted to do this. ++ Usually it happens just once, at system boot time. <br> ++ The proper way to establish the primary IP address of a system ++ is to configure the IP address resolver to associate that IP ++ address with the system's host name as returned by gethostname. ++ For example, put a record for the system in /etc/hosts. ++ <br> See gethostid above for more information on host ids. ++ <br> The return value is 0 on success and -1 on failure. ++ The following errno error conditions are defined for this ++ function: <br> @table @code @item EPERM This process ++ cannot set the host name because it is not privileged. ++ <br> @item 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. @end ++ table ++ ++ ++ ++ ++ ++ ++ The utsname structure is used to hold information returned by ++ the uname function. It has the following members: <br> ++ ++ ++ ++ ++ This is the name of the operating system in use. <br> ++ ++ ++ ++ ++ This is the current release level of the operating system ++ implementation. <br> ++ ++ ++ ++ ++ This is the current version level within the release of the ++ operating system. <br> ++ ++ ++ ++ ++ This is a description of the type of hardware that is in use. ++ <br> 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. <br> GNU uses a three-part name to ++ describe a system configuration; the three parts are cpu, ++ manufacturer and system-type, 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. <br> Since the ++ value in machine is supposed to describe just the hardware, it ++ consists of the first two parts of the configuration name: ++ cpu-manufacturer. For example, it might be one of these: ++ <br> @quotation "sparc-sun", "i386-anything", "m68k-hp", ++ "m68k-sony", "m68k-sun", "mips-dec" @end quotation <br> ++ ++ ++ ++ ++ This is the host name of this particular computer. In the GNU C ++ library, the value is the same as that returned by gethostname; ++ see Host Identification. <br> @ gethostname() is ++ implemented with a call to uname(). <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The uname function fills in the structure pointed to by info ++ with information about the operating system and host machine. A ++ non-negative value indicates that the data was successfully ++ stored. <br> -1 as the value indicates an error. The only ++ error possible is EFAULT, which we normally don't mention as it ++ is always a possibility. ++ ++ ++ ++ ++ ++ ++ This structure is used with the getfsent, getfsspec, and ++ getfsfile functions. <br> ++ ++ ++ ++ ++ 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. <br> Even though the element is not ++ declared const it shouldn't be modified. The missing const has ++ historic reasons, since this function predates ISO C. The same ++ is true for the other string elements of this structure. ++ <br> ++ ++ ++ ++ ++ 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. <br> ++ ++ ++ ++ ++ This is the type of the filesystem. Depending on what the ++ underlying kernel understands it can be any string. <br> ++ ++ ++ ++ ++ This is a string containing options passed to the kernel with ++ the mount 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 = character. <br> If the value of this ++ element must be processed it should ideally be done using the ++ getsubopt function; see Suboptions. <br> ++ ++ ++ ++ ++ This name is poorly chosen. This element points to a string ++ (possibly in the fs_mntops string) which describes the modes ++ with which the filesystem is mounted. fstab defines five macros ++ to describe the possible values: <br> @vtable @code ++ ++ ++ ++ ++ The filesystems gets mounted with read and write enabled. ++ ++ ++ ++ ++ The filesystems gets mounted with read and write enabled. Write ++ access is restricted by quotas. ++ ++ ++ ++ ++ The filesystem gets mounted read-only. ++ ++ ++ ++ ++ This is not a real filesystem, it is a swap device. ++ ++ ++ ++ ++ This entry from the fstab file is totally ignored. @end vtable ++ <br> Testing for equality with these value must happen ++ using strcmp since these are all strings. Comparing the pointer ++ will probably always fail. <br> ++ ++ ++ ++ ++ This element describes the dump frequency in days. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function makes sure that the internal read pointer for the ++ fstab file is at the beginning of the file. This is done by ++ either opening the file or resetting the read pointer. ++ <br> Since the file handle is internal to the libc this ++ function is not thread-safe. <br> This function returns a ++ non-zero value if the operation was successful and the getfs* ++ functions can be used to read the entries of the file. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function makes sure that all resources acquired by a prior ++ call to setfsent (explicitly or implicitly by calling getfsent) ++ are freed. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function returns the next entry of the fstab file. If this ++ is the first call to any of the functions handling fstab since ++ program start or the last call of endfsent, the file will be ++ opened. <br> The function returns a pointer to a variable ++ of type struct fstab. This variable is shared by all threads ++ and therefore this function is not thread-safe. If an error ++ occurred getfsent returns a NULL pointer. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function returns the next entry of the fstab file which has ++ a string equal to name pointed to by the fs_spec 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 fstab since program start or the last call of endfsent, ++ the file will be opened. <br> The function returns a ++ pointer to a variable of type struct fstab. This variable is ++ shared by all threads and therefore this function is not ++ thread-safe. If an error occurred getfsent returns a NULL ++ pointer. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function returns the next entry of the fstab file which has ++ a string equal to name pointed to by the fs_file 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 fstab since program start or the last call of endfsent, ++ the file will be opened. <br> The function returns a ++ pointer to a variable of type struct fstab. This variable is ++ shared by all threads and therefore this function is not ++ thread-safe. If an error occurred getfsent returns a NULL ++ pointer. ++ ++ ++ ++ ++ ++ ++ This structure is used with the getmntent, getmntent_t, ++ addmntent, and hasmntopt functions. <br> ++ ++ ++ ++ ++ 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 fs_spec element in struct fstab. <br> ++ ++ ++ ++ ++ This element points to a string describing the mount point of ++ the filesystem. It corresponds to the fs_file element in struct ++ fstab. <br> ++ ++ ++ ++ ++ mnt_type describes the filesystem type and is therefore ++ equivalent to fs_vfstype in struct fstab. mntent.h 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 ++ mntent.h. <br> @vtable @code ++ ++ ++ ++ ++ This symbol expands to "ignore". The value is sometime used in ++ fstab files to make sure entries are not used without removing ++ them. ++ ++ ++ ++ ++ Expands to "nfs". Using this macro sometimes could make sense ++ since it names the default NFS implementation, in case both ++ version 2 and 3 are supported. ++ ++ ++ ++ ++ This symbol expands to "swap". It names the special fstab entry ++ which names one of the possibly multiple swap partitions. @end ++ vtable <br> ++ ++ ++ ++ ++ The element contains a string describing the options used while ++ mounting the filesystem. As for the equivalent element ++ fs_mntops of struct fstab it is best to use the function ++ getsubopt (Suboptions) to access the parts of this string. ++ <br> The mntent.h 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: <br> @vtable @code ++ ++ ++ ++ ++ Expands to "defaults". This option should be used alone since ++ it indicates all values for the customizable values are chosen ++ to be the default. ++ ++ ++ ++ ++ Expands to "ro". See the FSTAB_RO value, it means the ++ filesystem is mounted read-only. ++ ++ ++ ++ ++ Expand to "rw". See the FSTAB_RW value, it means the filesystem ++ is mounted with read and write permissions. ++ ++ ++ ++ ++ Expands to "suid". This means that the SUID bit (How Change ++ Persona) is respected when a program from the filesystem is ++ started. ++ ++ ++ ++ ++ Expands to "nosuid". This is the opposite of MNTOPT_SUID, the ++ SUID bit for all files from the filesystem is ignored. ++ ++ ++ ++ ++ Expands to "noauto". At startup time the mount program will ++ ignore this entry if it is started with the -a option to mount ++ all filesystems mentioned in the fstab file. @end vtable ++ <br> As for the FSTAB_* entries introduced above it is ++ important to use strcmp to check for equality. <br> ++ ++ ++ ++ ++ This elements corresponds to fs_freq and also specifies the ++ frequency in days in which dumps are made. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The setmntent function prepares the file named FILE which must ++ be in the format of a fstab and mtab file for the upcoming ++ processing through the other functions of the family. The mode ++ parameter can be chosen in the way the opentype parameter for ++ fopen (Opening Streams) can be chosen. If the file is opened ++ for writing the file is also allowed to be empty. <br> If ++ the file was successfully opened setmntent returns a file ++ descriptor for future use. Otherwise the return value is NULL ++ and errno is set accordingly. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function takes for the stream parameter a file handle which ++ previously was returned from the setmntent call. endmntent ++ closes the stream and frees all resources. <br> The return ++ value is 1 unless an error occurred in which case it is 0. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The getmntent function takes as the parameter a file handle ++ previously returned by successful call to setmntent. It returns ++ a pointer to a static variable of type struct mntent which is ++ filled with the information from the next entry from the file ++ currently read. <br> The file format used prescribes the ++ use of spaces or tab characters to separate the fields. This ++ makes it harder to use name containing one of these characters ++ (e.g., mount points using spaces). Therefore these characters ++ are encoded in the files and the getmntent function takes care ++ of the decoding while reading the entries back in. '\040' is ++ used to encode a space character, '\012' to encode a tab ++ character and '\\' to encode a backslash. <br> If there ++ was an error or the end of the file is reached the return value ++ is NULL. <br> This function is not thread-safe since all ++ calls to this function return a pointer to the same static ++ variable. getmntent_r should be used in situations where ++ multiple threads access the file. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The getmntent_r function is the reentrant variant of getmntent. ++ 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 result parameter. Additional ++ information (e.g., the strings pointed to by the elements of the ++ result) are kept in the buffer of size bufsize pointed to by ++ buffer. <br> Escaped characters (space, tab, backslash) ++ are converted back in the same way as it happens for getmentent. ++ <br> The function returns a NULL pointer in error cases. ++ Errors could be: @itemize @bullet @item error while reading the ++ file, @item end of file reached, @item bufsize is too small for ++ reading a complete new entry. @end itemize ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The addmntent function allows adding a new entry to the file ++ previously opened with setmntent. The new entries are always ++ appended. I.e., even if the position of the file descriptor is ++ not at the end of the file this function does not overwrite an ++ existing entry following the current position. <br> The ++ implication of this is that to remove an entry from a file one ++ has to create a new file while leaving out the entry to be ++ removed and after closing the file remove the old one and rename ++ the new file to the chosen name. <br> 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 getmntent description above. <br> ++ This function returns 0 in case the operation was successful. ++ Otherwise the return value is 1 and errno is set appropriately. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function can be used to check whether the string pointed to ++ by the mnt_opts element of the variable pointed to by mnt ++ contains the option opt. If this is true a pointer to the ++ beginning of the option in the mnt_opts element is returned. If ++ no such option exists the function returns NULL. <br> This ++ function is useful to test whether a specific option is present ++ but when all options have to be processed one is better off with ++ using the getsubopt function to iterate over all options in the ++ string. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> mount mounts or remounts a filesystem. The two ++ operations are quite different and are merged rather unnaturally ++ into this one function. The MS_REMOUNT option, explained below, ++ determines whether mount mounts or remounts. <br> For a ++ mount, the filesystem on the block device represented by the ++ device special file named special_file gets mounted over the ++ mount point dir. This means that the directory dir (along with ++ any files in it) is no longer visible; in its place (and still ++ with the name dir) is the root directory of the filesystem on ++ the device. <br> As an exception, if the filesystem type ++ (see below) is one which is not based on a device (e.g. ++ ``proc''), mount instantiates a filesystem and mounts it over ++ dir and ignores special_file. <br> For a remount, dir ++ specifies the mount point where the filesystem to be remounted ++ is (and remains) mounted and special_file is ignored. ++ Remounting a filesystem means changing the options that control ++ operations on the filesystem while it is mounted. It does not ++ mean unmounting and mounting again. <br> For a mount, you ++ must identify the type of the filesystem as fstype. 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 ++ proc filesystem, the list of possible values is in the file ++ filesystems in the proc filesystem (e.g. type cat ++ /proc/filesystems to see the list). With a Linux kernel, the ++ types of filesystems that mount 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 fstype is ext2. <br> For a remount, mount ++ ignores fstype. <br> @c This is traditionally called ++ "rwflag" for historical reasons. @c No point in confusing people ++ today, though. options 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 ++ MS_RDONLY) can be overridden for individual file accesses via ++ ioctl. <br> options is a bit string with bit fields ++ defined using the following mask and masked value macros: ++ <br> @table @code @item MS_MGC_MASK This multibit field ++ contains a magic number. If it does not have the value ++ MS_MGC_VAL, mount assumes all the following bits are zero and ++ the data argument is a null string, regardless of their actual ++ values. <br> @item MS_REMOUNT This bit on means to remount ++ the filesystem. Off means to mount it. @c There is a mask ++ MS_RMT_MASK in mount.h that says only two of the options @c can ++ be reset by remount. But the Linux kernel has its own version ++ of @c MS_RMT_MASK that says they all can be reset. As far as I ++ can tell, @c libc just passes the arguments straight through to ++ the kernel. <br> @item MS_RDONLY This bit on specifies ++ that no writing to the filesystem shall be allowed while it is ++ mounted. This cannot be overridden by ioctl. This option is ++ available on nearly all filesystems. <br> @item ++ 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 ioctl. This option is a relatively new ++ invention and is not available on many filesystems. <br> ++ @item 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 ioctl. This ++ is a relatively new invention and is not available on many ++ filesystems. <br> @item MS_NOSUID This bit on specifies ++ that Setuid and Setgid permissions on files in the filesystem ++ shall be ignored while it is mounted. <br> @item MS_NOEXEC ++ This bit on specifies that no files in the filesystem shall be ++ executed while the filesystem is mounted. <br> @item ++ MS_NODEV This bit on specifies that no device special files in ++ the filesystem shall be accessible while the filesystem is ++ mounted. <br> @item MS_SYNCHRONOUS This bit on specifies ++ that all writes to the filesystem while it is mounted shall be ++ synchronous; i.e. data shall be synced before each write ++ completes rather than held in the buffer cache. <br> @item ++ MS_MANDLOCK This bit on specifies that mandatory locks on files ++ shall be permitted while the filesystem is mounted. <br> ++ @item MS_NOATIME This bit on specifies that access times of ++ files shall not be updated when the files are accessed while the ++ filesystem is mounted. <br> @item MS_NODIRATIME This bit ++ on specifies that access times of directories shall not be ++ updated when the directories are accessed while the filesystem ++ in mounted. <br> @c there is also S_QUOTA Linux fs.h ++ (mount.h still uses its former name @c S_WRITE), but I can't see ++ what it does. Turns on quotas, I guess. <br> @end table ++ <br> Any bits not covered by the above masks should be set ++ off; otherwise, results are undefined. <br> The meaning of ++ data depends on the filesystem type and is controlled entirely ++ by the filesystem driver in the kernel. <br> Example: ++ <br> @smallexample @group #include <sys/mount.h> ++ <br> mount("/dev/hdb", "/cdrom", MS_MGC_VAL | MS_RDONLY | ++ MS_NOSUID, ""); <br> mount("/dev/hda2", "/mnt", MS_MGC_VAL ++ | MS_REMOUNT, ""); <br> @end group @end smallexample ++ <br> Appropriate arguments for mount are conventionally ++ recorded in the fstab table. . <br> The return value is ++ zero if the mount or remount is successful. Otherwise, it is -1 ++ and errno is set appropriately. The values of errno are ++ filesystem dependent, but here is a general list: <br> ++ @table @code @item EPERM The process is not superuser. @item ++ ENODEV The file system type fstype is not known to the kernel. ++ @item ENOTBLK The file dev is not a block device special file. ++ @item EBUSY <br> @itemize @bullet <br> @item The ++ device is already mounted. <br> @item The mount point is ++ busy. (E.g. it is some process' working directory or has a ++ filesystem mounted on it already). <br> @item The request ++ is to remount read-only, but there are files open for write. ++ @end itemize <br> @item EINVAL @itemize @bullet <br> ++ @item A remount was attempted, but there is no filesystem ++ mounted over the specified mount point. <br> @item The ++ supposed filesystem has an invalid superblock. <br> @end ++ itemize <br> @item EACCES @itemize @bullet <br> ++ @item 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 MS_RDONLY bit off). <br> @item ++ special_file or dir is not accessible due to file permissions. ++ <br> @item special_file is not accessible because it is in ++ a filesystem that is mounted with the MS_NODEV option. ++ <br> @end itemize <br> @item EM_FILE The table of ++ dummy devices is full. mount needs to create a dummy device ++ (aka ``unnamed'' device) if the filesystem being mounted is not ++ one that uses a device. <br> @end table <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> umount2 unmounts a filesystem. <br> You can ++ identify the filesystem to unmount either by the device special ++ file that contains the filesystem or by the mount point. The ++ effect is the same. Specify either as the string file. ++ <br> flags contains the one-bit field identified by the ++ following mask macro: <br> @table @code <br> @item ++ MNT_FORCE 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, umount2 fails with errno = ++ EBUSY. Depending on the filesystem, this may override all, ++ some, or no busy conditions. <br> @end table <br> ++ All other bits in flags should be set to zero; otherwise, the ++ result is undefined. <br> Example: <br> ++ @smallexample @group #include <sys/mount.h> <br> ++ umount2("/mnt", MNT_FORCE); <br> umount2("/dev/hdd1", 0); ++ <br> @end group @end smallexample <br> After the ++ filesystem is unmounted, the directory that was the mount point ++ is visible, as are any files in it. <br> As part of ++ unmounting, umount2 syncs the filesystem. <br> If the ++ unmounting is successful, the return value is zero. Otherwise, ++ it is -1 and errno is set accordingly: <br> @table @code ++ @item EPERM The process is not superuser. @item 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 MNT_FORCE ++ option. <br> @item EINVAL file validly refers to a file, ++ but that file is neither a mount point nor a device special file ++ of a currently mounted filesystem. <br> @end table ++ <br> This function is not available on all systems. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> umount does the same thing as umount2 with flags set ++ to zeroes. It is more widely available than umount2 but since ++ it lacks the possibility to forcefully unmount a filesystem is ++ deprecated when umount2 is also available. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> sysctl gets or sets a specified system parameter. ++ There are so many of these parameters that it is not practical ++ to list them all here, but here are some examples: <br> ++ @itemize @bullet @item network domain name @item paging ++ parameters @item network Address Resolution Protocol timeout ++ time @item maximum number of files that may be open @item root ++ filesystem device @item when kernel was built @end itemize ++ <br> The set of available parameters depends on the kernel ++ configuration and can change while the system is running, ++ particularly when you load and unload loadable kernel modules. ++ <br> The system parameters with which syslog 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 sysctl.h. names is the path, in the form of an array of ++ integers. Each component of the path is one element of the ++ array, in order. nlen is the number of components in the path. ++ <br> For example, the first component of the path for all ++ the paging parameters is the value CTL_VM. For the free page ++ thresholds, the second component of the path is VM_FREEPG. So ++ to get the free page threshold values, make names an array ++ containing the two elements CTL_VM and VM_FREEPG and make nlen = ++ 2. <br> <br> The format of the value of a parameter ++ depends on the parameter. Sometimes it is an integer; sometimes ++ it is an ASCII string; sometimes it is an elaborate structure. ++ In the case of the free page thresholds used in the example ++ above, the parameter value is a structure containing several ++ integers. <br> In any case, you identify a place to return ++ the parameter's value with oldval and specify the amount of ++ storage available at that location as *oldlenp. *oldlenp does ++ double duty because it is also the output location that contains ++ the actual length of the returned value. <br> If you don't ++ want the parameter value returned, specify a null pointer for ++ oldval. <br> To set the parameter, specify the address and ++ length of the new value as newval and newlen. If you don't want ++ to set the parameter, specify a null pointer as newval. ++ <br> If you get and set a parameter in the same sysctl ++ call, the value returned is the value of the parameter before it ++ was set. <br> Each system parameter has a set of ++ permissions similar to the permissions for a file (including the ++ permissions on directories in its path) that determine whether ++ you may get or set it. For the purposes of these permissions, ++ every parameter is considered to be owned by the superuser and ++ Group 0 so processes with that effective uid or gid may have ++ more access to system parameters. Unlike with files, the ++ superuser does not invariably have full permission to all system ++ parameters, because some of them are designed not to be changed ++ ever. <br> <br> sysctl returns a zero return value ++ if it succeeds. Otherwise, it returns -1 and sets errno ++ appropriately. Besides the failures that apply to all system ++ calls, the following are the errno codes for all possible ++ failures: <br> @table @code @item EPERM 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. ++ @c There is some indication in the Linux 2.2 code that the code ++ is trying to @c return EACCES here, but the EACCES value never ++ actually makes it to the @c user. @item ENOTDIR There is no ++ system parameter corresponding to name. @item EFAULT oldval is ++ not null, which means the process wanted to read the parameter, ++ but *oldlenp is zero, so there is no place to return it. @item ++ EINVAL @itemize @bullet @item The process attempted to set a ++ system parameter to a value that is not valid for that ++ parameter. @item The space provided for the return of the system ++ parameter is not the right size for that parameter. @end itemize ++ @item ENOMEM This value may be returned instead of the more ++ correct EINVAL in some cases where the space provided for the ++ return of the system parameter is too small. <br> @end ++ table <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> openlog opens or reopens a connection to Syslog in ++ preparation for submitting messages. <br> ident is an ++ arbitrary identification string which future syslog invocations ++ will prefix to each message. This is intended to identify the ++ source of the message, and people conventionally set it to the ++ name of the program that will submit the messages. <br> If ++ ident is NULL, or if openlog is not called, the default ++ identification string used in Syslog messages will be the ++ program name, taken from argv[0]. <br> Please note that ++ the string pointer ident will be retained internally by the ++ Syslog routines. You must not free the memory that ident points ++ to. It is also dangerous to pass a reference to an automatic ++ variable since leaving the scope would mean ending the lifetime ++ of the variable. If you want to change the ident string, you ++ must call openlog again; overwriting the string pointed to by ++ ident is not thread-safe. <br> You can cause the Syslog ++ routines to drop the reference to ident and go back to the ++ default string (the program name taken from argv[0]), by calling ++ closelog: . <br> In particular, if you are writing code ++ for a shared library that might get loaded and then unloaded ++ (e.g. a PAM module), and you use openlog, you must call closelog ++ before any point where your library might get unloaded, as in ++ this example: <br> @smallexample #include <syslog.h> ++ <br> void shared_library_function (void) openlog ++ ("mylibrary", option, priority); <br> syslog (LOG_INFO, ++ "shared library has been invoked"); <br> closelog (); @ ++ @end smallexample <br> Without the call to closelog, ++ future invocations of syslog by the program using the shared ++ library may crash, if the library gets unloaded and the memory ++ containing the string "mylibrary" becomes unmapped. This is a ++ limitation of the BSD syslog interface. <br> openlog may ++ or may not open the /dev/log socket, depending on option. If it ++ does, it tries to open it and connect it as a stream socket. If ++ that doesn't work, it tries to open it and connect it as a ++ datagram socket. The socket has the ``Close on Exec'' ++ attribute, so the kernel will close it if the process performs ++ an exec. <br> You don't have to use openlog. If you call ++ syslog without having called openlog, syslog just opens the ++ connection implicitly and uses defaults for the information in ++ ident and options. <br> options is a bit string, with the ++ bits as defined by the following single bit masks: <br> ++ @table @code @item LOG_PERROR If on, openlog sets up the ++ connection so that any syslog on this connection writes its ++ message to the calling process' Standard Error stream in ++ addition to submitting it to Syslog. If off, syslog does not ++ write the message to Standard Error. <br> @item LOG_CONS ++ If on, openlog sets up the connection so that a syslog on this ++ connection that fails to submit a message to Syslog writes the ++ message instead to system console. If off, syslog does not ++ write to the system console (but of course Syslog may write ++ messages it receives to the console). <br> @item LOG_PID ++ When on, openlog sets up the connection so that a syslog on this ++ connection inserts the calling process' Process ID (PID) into ++ the message. When off, openlog does not insert the PID. ++ <br> @item LOG_NDELAY When on, openlog opens and connects ++ the /dev/log socket. When off, a future syslog call must open ++ and connect the socket. <br> Portability note: In early ++ systems, the sense of this bit was exactly the opposite. ++ <br> @item LOG_ODELAY This bit does nothing. It exists ++ for backward compatibility. <br> @end table <br> If ++ any other bit in options is on, the result is undefined. ++ <br> facility is the default facility code for this ++ connection. A syslog on this connection that specifies default ++ facility causes this facility to be associated with the message. ++ See syslog for possible values. A value of zero means the ++ default default, which is LOG_USER. <br> If a Syslog ++ connection is already open when you call openlog, openlog ++ ``reopens'' the connection. Reopening is like opening except ++ that if you specify zero for the default facility code, the ++ default facility code simply remains unchanged and if you ++ specify LOG_NDELAY and the socket is already open and connected, ++ openlog just leaves it that way. <br> @c There is a bug in ++ closelog() (glibc 2.1.3) wherein it does not reset the @c ++ default log facility to LOG_USER, which means the default ++ default log @c facility could be whatever the default log ++ facility was for a previous @c Syslog connection. I have ++ documented what the function should be rather @c than what it is ++ because I think if anyone ever gets concerned, the code @c will ++ change. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> syslog submits a message to the Syslog facility. It ++ does this by writing to the Unix domain socket /dev/log. ++ <br> syslog submits the message with the facility and ++ priority indicated by facility_priority. The macro LOG_MAKEPRI ++ generates a facility/priority from a facility and a priority, as ++ in the following example: <br> @smallexample ++ LOG_MAKEPRI(LOG_USER, LOG_WARNING) @end smallexample <br> ++ The possible values for the facility code are (macros): ++ <br> @c Internally, there is also LOG_KERN, but LOG_KERN ++ == 0, which means @c if you try to use it here, just selects ++ default. <br> @vtable @code @item LOG_USER A miscellaneous ++ user process @item LOG_MAIL Mail @item LOG_DAEMON A ++ miscellaneous system daemon @item LOG_AUTH Security ++ (authorization) @item LOG_SYSLOG Syslog @item LOG_LPR Central ++ printer @item LOG_NEWS Network news (e.g. Usenet) @item LOG_UUCP ++ UUCP @item LOG_CRON Cron and At @item LOG_AUTHPRIV Private ++ security (authorization) @item LOG_FTP Ftp server @item ++ LOG_LOCAL0 Locally defined @item LOG_LOCAL1 Locally defined ++ @item LOG_LOCAL2 Locally defined @item LOG_LOCAL3 Locally ++ defined @item LOG_LOCAL4 Locally defined @item LOG_LOCAL5 ++ Locally defined @item LOG_LOCAL6 Locally defined @item ++ LOG_LOCAL7 Locally defined @end vtable <br> Results are ++ undefined if the facility code is anything else. <br> ++ note: syslog recognizes one other facility code: that of the ++ kernel. But you can't specify that facility code with these ++ functions. If you try, it looks the same to syslog as if you ++ are requesting the default facility. But you wouldn't want to ++ anyway, because any program that uses the GNU C library is not ++ the kernel. <br> You can use just a priority code as ++ facility_priority. In that case, syslog assumes the default ++ facility established when the Syslog connection was opened. . ++ <br> The possible values for the priority code are ++ (macros): <br> @vtable @code @item LOG_EMERG The message ++ says the system is unusable. @item LOG_ALERT Action on the ++ message must be taken immediately. @item LOG_CRIT The message ++ states a critical condition. @item LOG_ERR The message describes ++ an error. @item LOG_WARNING The message is a warning. @item ++ LOG_NOTICE The message describes a normal but important event. ++ @item LOG_INFO The message is purely informational. @item ++ LOG_DEBUG The message is only for debugging purposes. @end ++ vtable <br> Results are undefined if the priority code is ++ anything else. <br> If the process does not presently have ++ a Syslog connection open (i.e. it did not call openlog), syslog ++ implicitly opens the connection the same as openlog would, with ++ the following defaults for information that would otherwise be ++ included in an openlog call: The default identification string ++ is the program name. The default default facility is LOG_USER. ++ The default for all the connection options in options is as if ++ those bits were off. syslog leaves the Syslog connection open. ++ <br> If the dev/log socket is not open and connected, ++ syslog opens and connects it, the same as openlog with the ++ LOG_NDELAY option would. <br> syslog leaves /dev/log open ++ and connected unless its attempt to send the message failed, in ++ which case syslog closes it (with the hope that a future ++ implicit open will restore the Syslog connection to a usable ++ state). <br> Example: <br> @smallexample <br> ++ #include <syslog.h> syslog (LOG_MAKEPRI(LOG_LOCAL1, ++ LOG_ERROR), "Unable to make network connection to %s. ++ Error=%m", host); <br> @end smallexample <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> This is functionally identical to syslog, with the ++ BSD style variable length argument. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> closelog closes the current Syslog connection, if ++ there is one. This includes closing the dev/log socket, if it is ++ open. closelog also sets the identification string for Syslog ++ messages back to the default, if openlog was called with a ++ non-NULL argument to ident. The default identification string ++ is the program name taken from argv[0]. <br> If you are ++ writing shared library code that uses openlog to generate custom ++ syslog output, you should use closelog to drop the GNU C ++ library's internal reference to the ident pointer when you are ++ done. Please read the section on openlog for more information: ++ . <br> closelog does not flush any buffers. You do not ++ have to call closelog before re-opening a Syslog connection with ++ initlog. Syslog connections are automatically closed on exec or ++ exit. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> setlogmask sets a mask (the ``logmask'') that ++ determines which future syslog calls shall be ignored. If a ++ program has not called setlogmask, syslog doesn't ignore any ++ calls. You can use setlogmask to specify that messages of ++ particular priorities shall be ignored in the future. <br> ++ A setlogmask call overrides any previous setlogmask call. ++ <br> Note that the logmask exists entirely independently ++ of opening and closing of Syslog connections. <br> Setting ++ the logmask has a similar effect to, but is not the same as, ++ configuring Syslog. The Syslog configuration may cause Syslog ++ to discard certain messages it receives, but the logmask causes ++ certain messages never to get submitted to Syslog in the first ++ place. <br> mask is a bit string with one bit ++ corresponding to each of the possible message priorities. If ++ the bit is on, syslog handles messages of that priority ++ normally. If it is off, syslog discards messages of that ++ priority. Use the message priority macros described in syslog; ++ vsyslog and the LOG_MASK to construct an appropriate mask value, ++ as in this example: <br> @smallexample LOG_MASK(LOG_EMERG) ++ | LOG_MASK(LOG_ERROR) @end smallexample <br> or <br> ++ @smallexample ~(LOG_MASK(LOG_INFO)) @end smallexample <br> ++ There is also a LOG_UPTO macro, which generates a mask with the ++ bits on for a certain priority and all priorities above it: ++ <br> @smallexample LOG_UPTO(LOG_ERROR) @end smallexample ++ <br> The unfortunate naming of the macro is due to the ++ fact that internally, higher numbers are used for lower message ++ priorities. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function returns 1 if filedes is a file descriptor ++ associated with an open terminal device, and 0 otherwise. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ If the file descriptor filedes is associated with a terminal ++ device, the ttyname function returns a pointer to a ++ statically-allocated, null-terminated string containing the file ++ name of the terminal file. The value is a null pointer if the ++ file descriptor isn't associated with a terminal, or the file ++ name cannot be determined. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The ttyname_r function is similar to the ttyname function except ++ that it places its result into the user-specified buffer ++ starting at buf with length len. <br> The normal return ++ value from ttyname_r is 0. Otherwise an error number is ++ returned to indicate the error. The following errno error ++ conditions are defined for this function: <br> @table ++ @code @item EBADF The filedes argument is not a valid file ++ descriptor. <br> @item ENOTTY The filedes is not ++ associated with a terminal. <br> @item ERANGE The buffer ++ length len is too small to store the string to be returned. @end ++ table ++ ++ ++ ++ ++ ++ ++ Structure that records all the I/O attributes of a terminal. ++ The structure includes at least the following members: ++ <br> ++ ++ ++ ++ ++ A bit mask specifying flags for input modes; see Input Modes. ++ <br> ++ ++ ++ ++ ++ A bit mask specifying flags for output modes; see Output Modes. ++ <br> ++ ++ ++ ++ ++ A bit mask specifying flags for control modes; see Control ++ Modes. <br> ++ ++ ++ ++ ++ A bit mask specifying flags for local modes; see Local Modes. ++ <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is used to examine the attributes of the terminal ++ device with file descriptor filedes. The attributes are ++ returned in the structure that termios-p points to. <br> ++ If successful, tcgetattr returns 0. A return value of -1 ++ indicates an error. The following errno error conditions are ++ defined for this function: <br> @table @code @item EBADF ++ The filedes argument is not a valid file descriptor. <br> ++ @item ENOTTY The filedes is not associated with a terminal. @end ++ table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function sets the attributes of the terminal device with ++ file descriptor filedes. The new attributes are taken from the ++ structure that termios-p points to. <br> The when argument ++ specifies how to deal with input and output already queued. It ++ can be one of the following values: <br> @table @code ++ @item TCSANOW @vindex TCSANOW Make the change immediately. ++ <br> @item TCSADRAIN @vindex TCSADRAIN Make the change ++ after waiting until all queued output has been written. You ++ should usually use this option when changing parameters that ++ affect output. <br> @item TCSAFLUSH @vindex TCSAFLUSH This ++ is like TCSADRAIN, but also discards any queued input. ++ <br> @item TCSASOFT @vindex TCSASOFT This is a flag bit ++ that you can add to any of the above alternatives. Its meaning ++ is to inhibit alteration of the state of the terminal hardware. ++ It is a BSD extension; it is only supported on BSD systems and ++ the GNU system. <br> Using TCSASOFT is exactly the same as ++ setting the CIGNORE bit in the c_cflag member of the structure ++ termios-p points to. , for a description of CIGNORE. @end table ++ <br> If this function is called from a background process ++ on its controlling terminal, normally all processes in the ++ process group are sent a SIGTTOU signal, in the same way as if ++ the process were trying to write to the terminal. The exception ++ is if the calling process itself is ignoring or blocking SIGTTOU ++ signals, in which case the operation is performed and no signal ++ is sent. . <br> If successful, tcsetattr returns 0. A ++ return value of -1 indicates an error. The following errno ++ error conditions are defined for this function: <br> ++ @table @code @item EBADF The filedes argument is not a valid ++ file descriptor. <br> @item ENOTTY The filedes is not ++ associated with a terminal. <br> @item EINVAL Either the ++ value of the when argument is not valid, or there is something ++ wrong with the data in the termios-p argument. @end table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function returns the output line speed stored in the ++ structure *termios-p. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function returns the input line speed stored in the ++ structure *termios-p. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function stores speed in *termios-p as the output speed. ++ The normal return value is 0; a value of -1 indicates an error. ++ If speed is not a speed, cfsetospeed returns -1. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function stores speed in *termios-p as the input speed. ++ The normal return value is 0; a value of -1 indicates an error. ++ If speed is not a speed, cfsetospeed returns -1. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function stores speed in *termios-p as both the input and ++ output speeds. The normal return value is 0; a value of -1 ++ indicates an error. If speed is not a speed, cfsetspeed returns ++ -1. This function is an extension in 4.4 BSD. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function provides an easy way to set up *termios-p for what ++ has traditionally been called ``raw mode'' in BSD. This uses ++ noncanonical input, and turns off most processing to give an ++ unmodified channel to the terminal. <br> It does exactly ++ this: @smallexample termios-p->c_iflag &= ++ ~(IGNBRK|BRKINT|PARMRK|ISTRIP ++ |INLCR|IGNCR|ICRNL|IXON); termios-p->c_oflag &= ~OPOST; ++ termios-p->c_lflag &= ++ ~(ECHO|ECHONL|ICANON|ISIG|IEXTEN); termios-p->c_cflag ++ &= ~(CSIZE|PARENB); termios-p->c_cflag |= CS8; @end ++ smallexample ++ ++ ++ ++ ++ ++ ++ This structure is an input or output parameter list for gtty and ++ stty. <br> ++ ++ ++ ++ ++ Line speed for input ++ ++ ++ ++ ++ Line speed for output ++ ++ ++ ++ ++ Erase character ++ ++ ++ ++ ++ Kill character ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++
++ ++ ++ This function gets the attributes of a terminal. <br> gtty ++ sets *attributes to describe the terminal attributes of the ++ terminal which is open with file descriptor filedes. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> This function sets the attributes of a terminal. ++ <br> stty sets the terminal attributes of the terminal ++ which is open with file descriptor filedes to those described by ++ *filedes. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function generates a break condition by transmitting a ++ stream of zero bits on the terminal associated with the file ++ descriptor filedes. The duration of the break is controlled by ++ the duration argument. If zero, the duration is between 0.25 ++ and 0.5 seconds. The meaning of a nonzero value depends on the ++ operating system. <br> This function does nothing if the ++ terminal is not an asynchronous serial data port. <br> The ++ return value is normally zero. In the event of an error, a ++ value of -1 is returned. The following errno error conditions ++ are defined for this function: <br> @table @code @item ++ EBADF The filedes is not a valid file descriptor. <br> ++ @item ENOTTY The filedes is not associated with a terminal ++ device. @end table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The tcdrain function waits until all queued output to the ++ terminal filedes has been transmitted. <br> This function ++ is a cancellation point in multi-threaded programs. This is a ++ problem if the thread allocates some resources (like memory, ++ file descriptors, semaphores or whatever) at the time tcdrain is ++ called. If the thread gets canceled these resources stay ++ allocated until the program ends. To avoid this calls to ++ tcdrain should be protected using cancellation handlers. @c ref ++ pthread_cleanup_push / pthread_cleanup_pop <br> The return ++ value is normally zero. In the event of an error, a value of -1 ++ is returned. The following errno error conditions are defined ++ for this function: <br> @table @code @item EBADF The ++ filedes is not a valid file descriptor. <br> @item ENOTTY ++ The filedes is not associated with a terminal device. <br> ++ @item EINTR The operation was interrupted by delivery of a ++ signal. . @end table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The tcflush function is used to clear the input and/or output ++ queues associated with the terminal file filedes. The queue ++ argument specifies which queue(s) to clear, and can be one of ++ the following values: <br> @c Extra blank lines here make ++ it look better. @table @code @vindex TCIFLUSH @item TCIFLUSH ++ <br> Clear any input data received, but not yet read. ++ <br> @vindex TCOFLUSH @item TCOFLUSH <br> Clear any ++ output data written, but not yet transmitted. <br> @vindex ++ TCIOFLUSH @item TCIOFLUSH <br> Clear both queued input and ++ output. @end table <br> The return value is normally zero. ++ In the event of an error, a value of -1 is returned. The ++ following errno error conditions are defined for this function: ++ <br> @table @code @item EBADF The filedes is not a valid ++ file descriptor. <br> @item ENOTTY The filedes is not ++ associated with a terminal device. <br> @item EINVAL A bad ++ value was supplied as the queue argument. @end table <br> ++ It is unfortunate that this function is named tcflush, because ++ the term ``flush'' is normally used for quite another ++ operation---waiting until all output is transmitted---and using ++ it for discarding input or output would be confusing. ++ Unfortunately, the name tcflush comes from POSIX and we cannot ++ change it. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The tcflow function is used to perform operations relating to ++ XON/XOFF flow control on the terminal file specified by filedes. ++ <br> The action argument specifies what operation to ++ perform, and can be one of the following values: <br> ++ @table @code @vindex TCOOFF @item TCOOFF Suspend transmission of ++ output. <br> @vindex TCOON @item TCOON Restart ++ transmission of output. <br> @vindex TCIOFF @item TCIOFF ++ Transmit a STOP character. <br> @vindex TCION @item TCION ++ Transmit a START character. @end table <br> For more ++ information about the STOP and START characters, see Special ++ Characters. <br> The return value is normally zero. In ++ the event of an error, a value of -1 is returned. The following ++ errno error conditions are defined for this function: <br> ++ @table @code @vindex EBADF @item EBADF The filedes is not a ++ valid file descriptor. <br> @vindex ENOTTY @item ENOTTY ++ The filedes is not associated with a terminal device. <br> ++ @vindex EINVAL @item EINVAL A bad value was supplied as the ++ action argument. @end table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The getpt function returns a new file descriptor for the next ++ available master pseudo-terminal. The normal return value from ++ getpt is a non-negative integer file descriptor. In the case of ++ an error, a value of -1 is returned instead. The following ++ errno conditions are defined for this function: <br> ++ @table @code @item ENOENT There are no free master ++ pseudo-terminals available. @end table <br> This function ++ is a GNU extension. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The grantpt function changes the ownership and access permission ++ of the slave pseudo-terminal device corresponding to the master ++ pseudo-terminal device associated with the file descriptor ++ filedes. The owner is set from the real user ID of the calling ++ process (Process Persona), and the group is set to a special ++ group (typically tty) or from the real group ID of the calling ++ process. The access permission is set such that the file is ++ both readable and writable by the owner and only writable by the ++ group. <br> On some systems this function is implemented ++ by invoking a special setuid root program (How Change Persona). ++ As a consequence, installing a signal handler for the SIGCHLD ++ signal (Job Control Signals) may interfere with a call to ++ grantpt. <br> The normal return value from grantpt is 0; a ++ value of -1 is returned in case of failure. The following errno ++ error conditions are defined for this function: <br> ++ @table @code @item EBADF The filedes argument is not a valid ++ file descriptor. <br> @item EINVAL The filedes argument is ++ not associated with a master pseudo-terminal device. <br> ++ @item EACCES The slave pseudo-terminal device corresponding to ++ the master associated with filedes could not be accessed. @end ++ table <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The unlockpt function unlocks the slave pseudo-terminal device ++ corresponding to the master pseudo-terminal device associated ++ with the file descriptor filedes. On many systems, the slave ++ can only be opened after unlocking, so portable applications ++ should always call unlockpt before trying to open the slave. ++ <br> The normal return value from unlockpt is 0; a value ++ of -1 is returned in case of failure. The following errno error ++ conditions are defined for this function: <br> @table ++ @code @item EBADF The filedes argument is not a valid file ++ descriptor. <br> @item EINVAL The filedes argument is not ++ associated with a master pseudo-terminal device. @end table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ If the file descriptor filedes is associated with a master ++ pseudo-terminal device, the ptsname function returns a pointer ++ to a statically-allocated, null-terminated string containing the ++ file name of the associated slave pseudo-terminal file. This ++ string might be overwritten by subsequent calls to ptsname. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The ptsname_r function is similar to the ptsname function except ++ that it places its result into the user-specified buffer ++ starting at buf with length len. <br> This function is a ++ GNU extension. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function allocates and opens a pseudo-terminal pair, ++ returning the file descriptor for the master in *amaster, and ++ the file descriptor for the slave in *aslave. If the argument ++ name is not a null pointer, the file name of the slave ++ pseudo-terminal device is stored in *name. If termp is not a ++ null pointer, the terminal attributes of the slave are set to ++ the ones specified in the structure that termp points to ++ (Terminal Modes). Likewise, if the winp is not a null pointer, ++ the screen size of the slave is set to the values specified in ++ the structure that winp points to. <br> The normal return ++ value from openpty is 0; a value of -1 is returned in case of ++ failure. The following errno conditions are defined for this ++ function: <br> @table @code @item ENOENT There are no free ++ pseudo-terminal pairs available. @end table <br> Warning: ++ Using the openpty function with name not set to NULL is very ++ dangerous because it provides no protection against overflowing ++ the string name. You should use the ttyname function on the ++ file descriptor returned in *slave to find out the file name of ++ the slave pseudo-terminal device instead. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to the openpty function, but in ++ addition, forks a new process (Creating a Process) and makes the ++ newly opened slave pseudo-terminal device the controlling ++ terminal (Controlling Terminal) for the child process. ++ <br> If the operation is successful, there are then both ++ parent and child processes and both see forkpty return, but with ++ different values: it returns a value of 0 in the child process ++ and returns the child's process ID in the parent process. ++ <br> If the allocation of a pseudo-terminal pair or the ++ process creation failed, forkpty returns a value of -1 in the ++ parent process. <br> Warning: The forkpty function has the ++ same problems with respect to the name argument as openpty. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The difftime function returns the number of seconds of elapsed ++ time between calendar time time1 and calendar time time0, as a ++ value of type double. The difference ignores leap seconds ++ unless leap second support is enabled. <br> In the GNU ++ system, you can simply subtract time_t values. But on other ++ systems, the time_t data type might use some other encoding ++ where subtraction doesn't work directly. ++ ++ ++ ++ ++ ++ ++ @cindex timeval The struct timeval structure represents an ++ elapsed time. It is declared in sys/time.h and has the ++ following members: <br> ++ ++ ++ ++ ++ This represents the number of whole seconds of elapsed time. ++ <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ @cindex timespec The struct timespec structure represents an ++ elapsed time. It is declared in time.h and has the following ++ members: <br> ++ ++ ++ ++ ++ This represents the number of whole seconds of elapsed time. ++ <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++
++ ++ ++ This function returns the calling process' current CPU time. If ++ the CPU time is not available or cannot be represented, clock ++ returns the value (clock_t)(-1). ++ ++ ++ ++ ++ ++ ++ The tms structure is used to return information about process ++ times. It contains at least the following members: <br> ++ ++ ++ ++ ++ This is the total processor time the calling process has used in ++ executing the instructions of its program. <br> ++ ++ ++ ++ ++ This is the processor time the system has used on behalf of the ++ calling process. <br> ++ ++ ++ ++ ++ This is the sum of the tms_utime values and the tms_cutime ++ values of all terminated child processes of the calling process, ++ whose status has been reported to the parent process by wait or ++ waitpid; 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 ++ wait or waitpid. @cindex child process <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The times function stores the processor time information for the ++ calling process in buffer. <br> The return value is the ++ calling process' CPU time (the same value you get from clock(). ++ times returns (clock_t)(-1) to indicate failure. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The time function returns the current calendar time as a value ++ of type time_t. If the argument result is not a null pointer, ++ the calendar time value is also stored in *result. If the ++ current calendar time is not available, the value (time_t)(-1) ++ is returned. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ stime sets the system clock, i.e. it tells the system that the ++ current calendar time is newtime, where newtime is interpreted ++ as described in the above definition of time_t. <br> ++ settimeofday is a newer function which sets the system clock to ++ better than one second precision. settimeofday is generally a ++ better choice than stime. . <br> Only the superuser can ++ set the system clock. <br> If the function succeeds, the ++ return value is zero. Otherwise, it is -1 and errno is set ++ accordingly: <br> @table @code @item EPERM The process is ++ not superuser. @end table ++ ++ ++ ++ ++ ++ ++ The struct timezone structure is used to hold minimal ++ information about the local time zone. It has the following ++ members: <br> ++ ++ ++ ++ ++ This is the number of minutes west of UTC. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The gettimeofday function returns the current calendar time as ++ the elapsed time since the epoch in the struct timeval structure ++ indicated by tp. (Elapsed Time for a description of struct ++ timespec). Information about the time zone is returned in the ++ structure pointed at tzp. If the tzp argument is a null ++ pointer, time zone information is ignored. <br> The return ++ value is 0 on success and -1 on failure. The following errno ++ error condition is defined for this function: <br> @table ++ @code @item ENOSYS The operating system does not support getting ++ time zone information, and tzp is not a null pointer. The GNU ++ operating system does not support using struct timezone to ++ represent time zone information; that is an obsolete feature of ++ 4.3 BSD. Instead, use the facilities described in Time Zone ++ Functions. @end table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The settimeofday function sets the current calendar time in the ++ system clock according to the arguments. As for gettimeofday, ++ the calendar time is represented as the elapsed time since the ++ epoch. As for gettimeofday, time zone information is ignored if ++ tzp is a null pointer. <br> You must be a privileged user ++ in order to use settimeofday. <br> Some kernels ++ automatically set the system clock from some source such as a ++ hardware clock when they start up. Others, including Linux, ++ place the system clock in an ``invalid'' state (in which ++ attempts to read the clock fail). A call of stime removes the ++ system clock from an invalid state, and system startup scripts ++ typically run a program that calls stime. <br> ++ settimeofday causes a sudden jump forwards or backwards, which ++ can cause a variety of problems in a system. Use adjtime ++ (below) to make a smooth transition from one time to another by ++ temporarily speeding up or slowing down the clock. <br> ++ With a Linux kernel, adjtimex does the same thing and can also ++ make permanent changes to the speed of the system clock so it ++ doesn't need to be corrected as often. <br> The return ++ value is 0 on success and -1 on failure. The following errno ++ error conditions are defined for this function: <br> ++ @table @code @item EPERM This process cannot set the clock ++ because it is not privileged. <br> @item ENOSYS The ++ operating system does not support setting time zone information, ++ and tzp is not a null pointer. @end table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function speeds up or slows down the system clock in order ++ to make a gradual adjustment. This ensures that the calendar ++ time reported by the system clock is always monotonically ++ increasing, which might not happen if you simply set the clock. ++ <br> The delta argument specifies a relative adjustment to ++ be made to the clock time. If negative, the system clock is ++ slowed down for a while until it has lost this much elapsed ++ time. If positive, the system clock is speeded up for a while. ++ <br> If the olddelta argument is not a null pointer, the ++ adjtime function returns information about any previous time ++ adjustment that has not yet completed. <br> This function ++ is typically used to synchronize the clocks of computers in a ++ local network. You must be a privileged user to use it. ++ <br> With a Linux kernel, you can use the adjtimex ++ function to permanently change the clock speed. <br> The ++ return value is 0 on success and -1 on failure. The following ++ errno error condition is defined for this function: <br> ++ @table @code @item EPERM You do not have privilege to set the ++ time. @end table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> adjtimex is functionally identical to ntp_adjtime. . ++ <br> This function is present only with a Linux kernel. ++ <br> ++ ++ ++ ++ ++ ++ ++ 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. <br> ++ ++ ++ ++ ++ This is the number of full seconds since the top of the minute ++ (normally in the range 0 through 59, but the actual upper limit ++ is 60, to allow for leap seconds if leap second support is ++ available). @cindex leap second <br> ++ ++ ++ ++ ++ This is the number of full minutes since the top of the hour (in ++ the range 0 through 59). <br> ++ ++ ++ ++ ++ This is the number of full hours past midnight (in the range 0 ++ through 23). <br> ++ ++ ++ ++ ++ This is the ordinal day of the month (in the range 1 through ++ 31). Watch out for this one! As the only ordinal number in the ++ structure, it is inconsistent with the rest of the structure. ++ <br> ++ ++ ++ ++ ++ This is the number of full calendar months since the beginning ++ of the year (in the range 0 through 11). Watch out for this ++ one! People usually use ordinal numbers for month-of-year (where ++ January = 1). <br> ++ ++ ++ ++ ++ This is the number of full calendar years since 1900. <br> ++ ++ ++ ++ ++ This is the number of full days since Sunday (in the range 0 ++ through 6). <br> ++ ++ ++ ++ ++ This is the number of full days since the beginning of the year ++ (in the range 0 through 365). <br> ++ ++ ++ ++ ++ @cindex Daylight Saving Time @cindex summer 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. <br> ++ ++ ++ ++ ++ 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 -5*60*60. The tm_gmtoff field is derived from ++ BSD and is a GNU library extension; it is not visible in a ++ strict ISO C environment. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The localtime function converts the simple time pointed to by ++ time to broken-down time representation, expressed relative to ++ the user's specified time zone. <br> The return value is a ++ pointer to a static broken-down time structure, which might be ++ overwritten by subsequent calls to ctime, gmtime, or localtime. ++ (But no other library function overwrites the contents of this ++ object.) <br> The return value is the null pointer if time ++ cannot be represented as a broken-down time; typically this is ++ because the year cannot fit into an int. <br> Calling ++ localtime has one other effect: it sets the variable tzname with ++ information about the current time zone. . ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The localtime_r function works just like the localtime function. ++ It takes a pointer to a variable containing a simple time and ++ converts it to the broken-down time format. <br> But the ++ result is not placed in a static buffer. Instead it is placed ++ in the object of type struct tm to which the parameter resultp ++ points. <br> If the conversion is successful the function ++ returns a pointer to the object the result was written into, ++ i.e., it returns resultp. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to localtime, except that the ++ broken-down time is expressed as Coordinated Universal Time ++ (UTC) (formerly called Greenwich Mean Time (GMT)) rather than ++ relative to a local time zone. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to localtime_r, except that it converts ++ just like gmtime the given time as Coordinated Universal Time. ++ <br> If the conversion is successful the function returns ++ a pointer to the object the result was written into, i.e., it ++ returns resultp. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The mktime function is used to convert a broken-down time ++ structure to a simple time representation. It also ++ ``normalizes'' the contents of the broken-down time structure, ++ by filling in the day of week and day of year based on the other ++ date and time components. <br> The mktime function ignores ++ the specified contents of the tm_wday and tm_yday 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 mktime does is adjust the ++ components of the brokentime structure (including the tm_wday ++ and tm_yday). <br> If the specified broken-down time ++ cannot be represented as a simple time, mktime returns a value ++ of (time_t)(-1) and does not modify the contents of brokentime. ++ <br> Calling mktime also sets the variable tzname with ++ information about the current time zone. . ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> timelocal is functionally identical to mktime, but ++ more mnemonically named. Note that it is the inverse of the ++ localtime function. <br> Portability note: mktime is ++ essentially universally available. timelocal is rather rare. ++ <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ <br> timegm is functionally identical to mktime except it ++ always takes the input values to be Coordinated Universal Time ++ (UTC) regardless of any local time zone setting. <br> Note ++ that timegm is the inverse of gmtime. <br> Portability ++ note: mktime is essentially universally available. timegm is ++ rather rare. For the most portable conversion from a UTC ++ broken-down time to a simple time, set the TZ environment ++ variable to UTC, call mktime, then set TZ back. <br> ++ ++ ++ ++ ++ ++ ++ This structure is used for information about the system clock. ++ It contains the following members: ++ ++ ++ ++ ++ This is the current calendar time, expressed as the elapsed time ++ since the epoch. The struct timeval data type is described in ++ Elapsed Time. <br> ++ ++ ++ ++ ++ This is the maximum error, measured in microseconds. Unless ++ updated via ntp_adjtime periodically, this value will reach some ++ platform-specific maximum value. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The ntp_gettime function sets the structure pointed to by tptr ++ 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 ++ ntp_adjtime call is necessary. <br> The return value is 0 ++ on success and other values on failure. The following errno ++ error conditions are defined for this function: <br> ++ @table @code @item TIME_ERROR 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. @end ++ table ++ ++ ++ ++ ++ ++ ++ This structure is used to control and monitor the system clock. ++ It contains the following members: ++ ++ ++ ++ ++ This variable controls whether and which values are set. ++ Several symbolic constants have to be combined with binary or to ++ specify the effective mode. These constants start with MOD_. ++ <br> ++ ++ ++ ++ ++ This value indicates the current offset of the system clock from ++ the true calendar time. The value is given in microseconds. If ++ bit MOD_OFFSET is set in modes, the offset (and possibly other ++ dependent values) can be set. The offset's absolute value must ++ not exceed MAXPHASE. <br> <br> ++ ++ ++ ++ ++ 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 1 ++ << SHIFT_USEC. The value can be set with bit ++ MOD_FREQUENCY, but the absolute value must not exceed MAXFREQ. ++ <br> ++ ++ ++ ++ ++ This is the maximum error, measured in microseconds. A new ++ value can be set using bit MOD_MAXERROR. Unless updated via ++ ntp_adjtime periodically, this value will increase steadily and ++ reach some platform-specific maximum value. <br> ++ ++ ++ ++ ++ This is the estimated error, measured in microseconds. This ++ value can be set using bit MOD_ESTERROR. <br> ++ ++ ++ ++ ++ This variable reflects the various states of the clock ++ machinery. There are symbolic constants for the significant ++ bits, starting with STA_. Some of these flags can be updated ++ using the MOD_STATUS bit. <br> ++ ++ ++ ++ ++ This value represents the bandwidth or stiffness of the PLL ++ (phase locked loop) implemented in the kernel. The value can be ++ changed using bit MOD_TIMECONST. <br> ++ ++ ++ ++ ++ This value represents the accuracy or the maximum error when ++ reading the system clock. The value is expressed in ++ microseconds. <br> ++ ++ ++ ++ ++ This value represents the maximum frequency error of the system ++ clock in scaled PPM. This value is used to increase the ++ maxerror every second. <br> ++ ++ ++ ++ ++ The current calendar time. <br> ++ ++ ++ ++ ++ The elapsed time between clock ticks in microseconds. A clock ++ tick is a periodic timer interrupt on which the system clock is ++ based. <br> ++ ++ ++ ++ ++ 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. <br> ++ ++ ++ ++ ++ This value expresses a median filtered average of the PPS ++ signal's dispersion in microseconds. <br> ++ ++ ++ ++ ++ This value is a binary exponent for the duration of the PPS ++ calibration interval, ranging from PPS_SHIFT to PPS_SHIFTMAX. ++ <br> ++ ++ ++ ++ ++ This value represents the median filtered dispersion of the PPS ++ frequency in scaled PPM. <br> ++ ++ ++ ++ ++ This counter represents the number of pulses where the jitter ++ exceeded the allowed maximum MAXTIME. <br> ++ ++ ++ ++ ++ This counter reflects the number of successful calibration ++ intervals. <br> ++ ++ ++ ++ ++ This counter represents the number of calibration errors (caused ++ by large offsets or jitter). <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The ntp_adjtime function sets the structure specified by tptr to ++ current values. <br> In addition, ntp_adjtime updates some ++ settings to match what you pass to it in *tptr. Use the modes ++ element of *tptr to select what settings to update. You can set ++ offset, freq, maxerror, esterror, status, constant, and tick. ++ <br> modes = zero means set nothing. <br> Only the ++ superuser can update settings. <br> @c On Linux, ++ ntp_adjtime() also does the adjtime() function if you set @c ++ modes = ADJ_OFFSET_SINGLESHOT (in fact, that is how GNU libc ++ implements @c adjtime()). But this should be considered an ++ internal function because @c it's so inconsistent with the rest ++ of what ntp_adjtime() does and is @c forced in an ugly way into ++ the struct timex. So we don't document it @c and instead ++ document adjtime() as the way to achieve the function. ++ <br> The return value is 0 on success and other values on ++ failure. The following errno error conditions are defined for ++ this function: <br> @table @code @item TIME_ERROR The high ++ accuracy clock model is not properly set up at the moment, thus ++ the clock must be considered unsynchronized, and the values ++ should be treated with care. Another reason could be that the ++ specified new values are not allowed. <br> @item EPERM The ++ process specified a settings update, but is not superuser. ++ <br> @end table <br> For more details see RFC1305 ++ (Network Time Protocol, Version 3) and related documents. ++ <br> Portability note: Early versions of the GNU C library ++ did not have this function but did have the synonymous adjtimex. ++ <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The asctime function converts the broken-down time value that ++ brokentime points to into a string in a standard format: ++ <br> @smallexample "Tue May 21 13:46:22 1991\n" @end ++ smallexample <br> The abbreviations for the days of week ++ are: Sun, Mon, Tue, Wed, Thu, Fri, and Sat. <br> The ++ abbreviations for the months are: Jan, Feb, Mar, Apr, May, Jun, ++ Jul, Aug, Sep, Oct, Nov, and Dec. <br> The return value ++ points to a statically allocated string, which might be ++ overwritten by subsequent calls to asctime or ctime. (But no ++ other library function overwrites the contents of this string.) ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to asctime but instead of placing the ++ result in a static buffer it writes the string in the buffer ++ pointed to by the parameter buffer. This buffer should have ++ room for at least 26 bytes, including the terminating null. ++ <br> If no error occurred the function returns a pointer ++ to the string the result was written into, i.e., it returns ++ buffer. Otherwise return NULL. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The ctime function is similar to asctime, except that you ++ specify the calendar time argument as a time_t simple time value ++ rather than in broken-down local time format. It is equivalent ++ to <br> @smallexample asctime (localtime (time)) @end ++ smallexample <br> ctime sets the variable tzname, because ++ localtime does so. . ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to ctime, but places the result in the ++ string pointed to by buffer. It is equivalent to (written using ++ gcc extensions, Statement Exprs,,,gcc,Porting and Using gcc): ++ <br> @smallexample ( struct tm tm; asctime_r (localtime_r ++ (time, &tm), buf); @) @end smallexample <br> If no ++ error occurred the function returns a pointer to the string the ++ result was written into, i.e., it returns buffer. Otherwise ++ return NULL. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to the sprintf function (Formatted ++ Input), but the conversion specifications that can appear in the ++ format template template are specialized for printing components ++ of the date and time brokentime according to the locale ++ currently specified for time conversion (Locales). <br> ++ Ordinary characters appearing in the template are copied to the ++ output string s; this can include multibyte character sequences. ++ Conversion specifiers are introduced by a % character, followed ++ by an optional flag which can be one of the following. These ++ flags are all GNU extensions. The first three affect only the ++ output of numbers: <br> @table @code @item _ The number is ++ padded with spaces. <br> @item - The number is not padded ++ at all. <br> @item 0 The number is padded with zeros even ++ if the format specifies padding with spaces. <br> @item ^ ++ The output uses uppercase characters, but only if this is ++ possible (Case Conversion). @end table <br> The default ++ action is to pad the number with zeros to keep it a constant ++ width. Numbers that do not have a range indicated below are ++ never padded, since there is no natural width for them. ++ <br> Following the flag an optional specification of the ++ width is possible. This is specified in decimal notation. If ++ the natural size of the output is of the field has less than the ++ specified number of characters, the result is written right ++ adjusted and space padded to the given size. <br> An ++ optional modifier can follow the optional flag and width ++ specification. The modifiers, which were first standardized by ++ POSIX.2-1992 and by ISO C99, are: <br> @table @code @item ++ E Use the locale's alternate representation for date and time. ++ This modifier applies to the %c, %C, %x, %X, %y and %Y format ++ specifiers. In a Japanese locale, for example, %Ex might yield ++ a date format based on the Japanese Emperors' reigns. <br> ++ @item O Use the locale's alternate numeric symbols for numbers. ++ This modifier applies only to numeric format specifiers. @end ++ table <br> If the format supports the modifier but no ++ alternate representation is available, it is ignored. <br> ++ The conversion specifier ends with a format specifier taken from ++ the following list. The whole % sequence is replaced in the ++ output string as follows: <br> @table @code @item %a The ++ abbreviated weekday name according to the current locale. ++ <br> @item %A The full weekday name according to the ++ current locale. <br> @item %b The abbreviated month name ++ according to the current locale. <br> @item %B The full ++ month name according to the current locale. <br> @item %c ++ The preferred calendar time representation for the current ++ locale. <br> @item %C The century of the year. This is ++ equivalent to the greatest integer not greater than the year ++ divided by 100. <br> This format was first standardized by ++ POSIX.2-1992 and by ISO C99. <br> @item %d The day of the ++ month as a decimal number (range 01 through 31). <br> ++ @item %D The date using the format %m/%d/%y. <br> This ++ format was first standardized by POSIX.2-1992 and by ISO C99. ++ <br> @item %e The day of the month like with %d, but ++ padded with blank (range 1 through 31). <br> This format ++ was first standardized by POSIX.2-1992 and by ISO C99. ++ <br> @item %F The date using the format %Y-%m-%d. This is ++ the form specified in the ISO 8601 standard and is the preferred ++ form for all uses. <br> This format was first standardized ++ by ISO C99 and by POSIX.1-2001. <br> @item %g The year ++ corresponding to the ISO week number, but without the century ++ (range 00 through 99). This has the same format and value as ++ %y, except that if the ISO week number (see %V) belongs to the ++ previous or next year, that year is used instead. <br> ++ This format was first standardized by ISO C99 and by ++ POSIX.1-2001. <br> @item %G The year corresponding to the ++ ISO week number. This has the same format and value as %Y, ++ except that if the ISO week number (see %V) belongs to the ++ previous or next year, that year is used instead. <br> ++ This format was first standardized by ISO C99 and by ++ POSIX.1-2001 but was previously available as a GNU extension. ++ <br> @item %h The abbreviated month name according to the ++ current locale. The action is the same as for %b. <br> ++ This format was first standardized by POSIX.2-1992 and by ISO ++ C99. <br> @item %H The hour as a decimal number, using a ++ 24-hour clock (range 00 through 23). <br> @item %I The ++ hour as a decimal number, using a 12-hour clock (range 01 ++ through 12). <br> @item %j The day of the year as a ++ decimal number (range 001 through 366). <br> @item %k The ++ hour as a decimal number, using a 24-hour clock like %H, but ++ padded with blank (range 0 through 23). <br> This format ++ is a GNU extension. <br> @item %l The hour as a decimal ++ number, using a 12-hour clock like %I, but padded with blank ++ (range 1 through 12). <br> This format is a GNU ++ extension. <br> @item %m The month as a decimal number ++ (range 01 through 12). <br> @item %M The minute as a ++ decimal number (range 00 through 59). <br> @item %n A ++ single \n (newline) character. <br> This format was first ++ standardized by POSIX.2-1992 and by ISO C99. <br> @item %p ++ Either AM or PM, according to the given time value; or the ++ corresponding strings for the current locale. Noon is treated ++ as PM and midnight as AM. In most locales AM/PM format is not ++ supported, in such cases "%p" yields an empty string. <br> ++ @ignore We currently have a problem with makeinfo. Write AM and ++ am both results in `am'. I.e., the difference in case is not ++ visible anymore. @end ignore @item %P Either am or pm, according ++ to the given time value; or the corresponding strings for the ++ current locale, printed in lowercase characters. Noon is ++ treated as pm and midnight as am. In most locales AM/PM format ++ is not supported, in such cases "%P" yields an empty string. ++ <br> This format is a GNU extension. <br> @item %r ++ The complete calendar time using the AM/PM format of the current ++ locale. <br> This format was first standardized by ++ POSIX.2-1992 and by ISO C99. In the POSIX locale, this format is ++ equivalent to %I:%M:%S %p. <br> @item %R The hour and ++ minute in decimal numbers using the format %H:%M. <br> ++ This format was first standardized by ISO C99 and by ++ POSIX.1-2001 but was previously available as a GNU extension. ++ <br> @item %s The number of seconds since the epoch, i.e., ++ since 1970-01-01 00:00:00 UTC. Leap seconds are not counted ++ unless leap second support is available. <br> This format ++ is a GNU extension. <br> @item %S The seconds as a decimal ++ number (range 00 through 60). <br> @item %t A single \t ++ (tabulator) character. <br> This format was first ++ standardized by POSIX.2-1992 and by ISO C99. <br> @item %T ++ The time of day using decimal numbers using the format %H:%M:%S. ++ <br> This format was first standardized by POSIX.2-1992 ++ and by ISO C99. <br> @item %u The day of the week as a ++ decimal number (range 1 through 7), Monday being 1. <br> ++ This format was first standardized by POSIX.2-1992 and by ISO ++ C99. <br> @item %U The week number of the current year as ++ a decimal number (range 00 through 53), 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 00. ++ <br> @item %V The ISO 8601:1988 week number as a decimal ++ number (range 01 through 53). ISO weeks start with Monday and ++ end with Sunday. Week 01 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 01 of a year ++ can contain days from the previous year. The week before week 01 ++ of a year is the last week (52 or 53) of the previous year even ++ if it contains days from the new year. <br> This format ++ was first standardized by POSIX.2-1992 and by ISO C99. ++ <br> @item %w The day of the week as a decimal number ++ (range 0 through 6), Sunday being 0. <br> @item %W The ++ week number of the current year as a decimal number (range 00 ++ through 53), 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 00. <br> @item %x The ++ preferred date representation for the current locale. <br> ++ @item %X The preferred time of day representation for the ++ current locale. <br> @item %y The year without a century ++ as a decimal number (range 00 through 99). This is equivalent ++ to the year modulo 100. <br> @item %Y The year as a ++ decimal number, using the Gregorian calendar. Years before the ++ year 1 are numbered 0, -1, and so on. <br> @item %z RFC ++ 822/ISO 8601:1988 style numeric time zone (e.g., -0600 or ++ +0100), or nothing if no time zone is determinable. <br> ++ This format was first standardized by ISO C99 and by ++ POSIX.1-2001 but was previously available as a GNU extension. ++ <br> In the POSIX locale, a full RFC 822 timestamp is ++ generated by the format "%a, %d %b %Y %H:%M:%S %z" (or the ++ equivalent "%a, %d %b %Y %T %z"). <br> @item %Z The time ++ zone abbreviation (empty if the time zone can't be determined). ++ <br> @item %% A literal % character. @end table <br> ++ The size parameter can be used to specify the maximum number of ++ characters to be stored in the array s, including the ++ terminating null character. If the formatted time requires more ++ than size characters, strftime returns zero and the contents of ++ the array s are undefined. Otherwise the return value indicates ++ the number of characters placed in the array s, not including ++ the terminating null character. <br> Warning: 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 "%p" will return the empty string, i.e., the return ++ value is zero. To detect situations like this something similar ++ to the following code should be used: <br> @smallexample ++ buf[0] = '\1'; len = strftime (buf, bufsize, format, tp); if ++ (len == 0 && buf[0] != '\0') /* Something went ++ wrong in the strftime call. */ @ @end smallexample ++ <br> If s is a null pointer, strftime does not actually ++ write anything, but instead returns the number of characters it ++ would have written. <br> According to POSIX.1 every call ++ to strftime implies a call to tzset. So the contents of the ++ environment variable TZ is examined before any output is ++ produced. <br> For an example of strftime, see Time ++ Functions Example. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The wcsftime function is equivalent to the strftime function ++ with the difference that it operates on wide character strings. ++ The buffer where the result is stored, pointed to by s, must be ++ an array of wide characters. The parameter size which specifies ++ the size of the output buffer gives the number of wide ++ character, not the number of bytes. <br> Also the format ++ string template 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 L"" notation. The parameter ++ brokentime has the same meaning as in the strftime call. ++ <br> The wcsftime function supports the same flags, ++ modifiers, and format specifiers as the strftime function. ++ <br> The return value of wcsftime is the number of wide ++ characters stored in s. When more characters would have to be ++ written than can be placed in the buffer s the return value is ++ zero, with the same problems indicated in the strftime ++ documentation. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The strptime function parses the input string s according to the ++ format string fmt and stores its results in the structure tp. ++ <br> The input string could be generated by a strftime ++ call or obtained any other way. It does not need to be in a ++ human-recognizable format; e.g. a date passed as "02:1999:9" is ++ acceptable, even though it is ambiguous without context. As ++ long as the format string fmt matches the input string the ++ function will succeed. <br> The user has to make sure, ++ though, that the input can be parsed in a unambiguous way. The ++ string "1999112" can be parsed using the format "%Y%m%d" as ++ 1999-1-12, 1999-11-2, or even 19991-1-2. It is necessary to add ++ appropriate separators to reliably get results. <br> The ++ format string consists of the same components as the format ++ string of the strftime function. The only difference is that ++ the flags _, -, 0, and ^ are not allowed. Several of the ++ distinct formats of strftime do the same work in strptime since ++ differences like case of the input do not matter. For reasons of ++ symmetry all formats are supported, though. <br> The ++ modifiers E and O are also allowed everywhere the strftime ++ function allows them. <br> The formats are: <br> ++ @table @code @item %a @itemx %A The weekday name according to ++ the current locale, in abbreviated form or the full name. ++ <br> @item %b @itemx %B @itemx %h The month name according ++ to the current locale, in abbreviated form or the full name. ++ <br> @item %c The date and time representation for the ++ current locale. <br> @item %Ec Like %c but the locale's ++ alternative date and time format is used. <br> @item %C ++ The century of the year. <br> It makes sense to use this ++ format only if the format string also contains the %y format. ++ <br> @item %EC The locale's representation of the period. ++ <br> Unlike %C it sometimes makes sense to use this format ++ since some cultures represent years relative to the beginning of ++ eras instead of using the Gregorian years. <br> @item %d ++ @item %e The day of the month as a decimal number (range 1 ++ through 31). Leading zeroes are permitted but not required. ++ <br> @item %Od @itemx %Oe Same as %d but using the ++ locale's alternative numeric symbols. <br> Leading zeroes ++ are permitted but not required. <br> @item %D Equivalent ++ to %m/%d/%y. <br> @item %F Equivalent to %Y-%m-%d, which ++ is the ISO 8601 date format. <br> This is a GNU extension ++ following an ISO C99 extension to strftime. <br> @item %g ++ The year corresponding to the ISO week number, but without the ++ century (range 00 through 99). <br> Note: Currently, this ++ is not fully implemented. The format is recognized, input is ++ consumed but no field in tm is set. <br> This format is a ++ GNU extension following a GNU extension of strftime. <br> ++ @item %G The year corresponding to the ISO week number. ++ <br> Note: Currently, this is not fully implemented. The ++ format is recognized, input is consumed but no field in tm is ++ set. <br> This format is a GNU extension following a GNU ++ extension of strftime. <br> @item %H @itemx %k The hour as ++ a decimal number, using a 24-hour clock (range 00 through 23). ++ <br> %k is a GNU extension following a GNU extension of ++ strftime. <br> @item %OH Same as %H but using the locale's ++ alternative numeric symbols. <br> @item %I @itemx %l The ++ hour as a decimal number, using a 12-hour clock (range 01 ++ through 12). <br> %l is a GNU extension following a GNU ++ extension of strftime. <br> @item %OI Same as %I but using ++ the locale's alternative numeric symbols. <br> @item %j ++ The day of the year as a decimal number (range 1 through 366). ++ <br> Leading zeroes are permitted but not required. ++ <br> @item %m The month as a decimal number (range 1 ++ through 12). <br> Leading zeroes are permitted but not ++ required. <br> @item %Om Same as %m but using the locale's ++ alternative numeric symbols. <br> @item %M The minute as a ++ decimal number (range 0 through 59). <br> Leading zeroes ++ are permitted but not required. <br> @item %OM Same as %M ++ but using the locale's alternative numeric symbols. <br> ++ @item %n @itemx %t Matches any white space. <br> @item %p ++ @item %P The locale-dependent equivalent to AM or PM. <br> ++ This format is not useful unless %I or %l is also used. Another ++ complication is that the locale might not define these values at ++ all and therefore the conversion fails. <br> %P is a GNU ++ extension following a GNU extension to strftime. <br> ++ @item %r The complete time using the AM/PM format of the current ++ locale. <br> A complication is that the locale might not ++ define this format at all and therefore the conversion fails. ++ <br> @item %R The hour and minute in decimal numbers using ++ the format %H:%M. <br> %R is a GNU extension following a ++ GNU extension to strftime. <br> @item %s The number of ++ seconds since the epoch, i.e., since 1970-01-01 00:00:00 UTC. ++ Leap seconds are not counted unless leap second support is ++ available. <br> %s is a GNU extension following a GNU ++ extension to strftime. <br> @item %S The seconds as a ++ decimal number (range 0 through 60). <br> Leading zeroes ++ are permitted but not required. <br> Note: The Unix ++ specification says the upper bound on this value is 61, a result ++ of a decision to allow double leap seconds. You will not see ++ the value 61 because no minute has more than one leap second, ++ but the myth persists. <br> @item %OS Same as %S but using ++ the locale's alternative numeric symbols. <br> @item %T ++ Equivalent to the use of %H:%M:%S in this place. <br> ++ @item %u The day of the week as a decimal number (range 1 ++ through 7), Monday being 1. <br> Leading zeroes are ++ permitted but not required. <br> Note: Currently, this is ++ not fully implemented. The format is recognized, input is ++ consumed but no field in tm is set. <br> @item %U The week ++ number of the current year as a decimal number (range 0 through ++ 53). <br> Leading zeroes are permitted but not required. ++ <br> @item %OU Same as %U but using the locale's ++ alternative numeric symbols. <br> @item %V The ISO ++ 8601:1988 week number as a decimal number (range 1 through 53). ++ <br> Leading zeroes are permitted but not required. ++ <br> Note: Currently, this is not fully implemented. The ++ format is recognized, input is consumed but no field in tm is ++ set. <br> @item %w The day of the week as a decimal number ++ (range 0 through 6), Sunday being 0. <br> Leading zeroes ++ are permitted but not required. <br> Note: Currently, this ++ is not fully implemented. The format is recognized, input is ++ consumed but no field in tm is set. <br> @item %Ow Same as ++ %w but using the locale's alternative numeric symbols. ++ <br> @item %W The week number of the current year as a ++ decimal number (range 0 through 53). <br> Leading zeroes ++ are permitted but not required. <br> Note: Currently, this ++ is not fully implemented. The format is recognized, input is ++ consumed but no field in tm is set. <br> @item %OW Same as ++ %W but using the locale's alternative numeric symbols. ++ <br> @item %x The date using the locale's date format. ++ <br> @item %Ex Like %x but the locale's alternative data ++ representation is used. <br> @item %X The time using the ++ locale's time format. <br> @item %EX Like %X but the ++ locale's alternative time representation is used. <br> ++ @item %y The year without a century as a decimal number (range 0 ++ through 99). <br> Leading zeroes are permitted but not ++ required. <br> Note that it is questionable to use this ++ format without the %C format. The strptime function does regard ++ input values in the range 68 to 99 as the years 1969 to 1999 and ++ the values 0 to 68 as the years 2000 to 2068. But maybe this ++ heuristic fails for some input data. <br> Therefore it is ++ best to avoid %y completely and use %Y instead. <br> @item ++ %Ey The offset from %EC in the locale's alternative ++ representation. <br> @item %Oy The offset of the year ++ (from %C) using the locale's alternative numeric symbols. ++ <br> @item %Y The year as a decimal number, using the ++ Gregorian calendar. <br> @item %EY The full alternative ++ year representation. <br> @item %z The offset from GMT in ++ ISO 8601/RFC822 format. <br> @item %Z The timezone name. ++ <br> Note: Currently, this is not fully implemented. The ++ format is recognized, input is consumed but no field in tm is ++ set. <br> @item %% A literal % character. @end table ++ <br> All other characters in the format string must have a ++ matching character in the input string. Exceptions are white ++ spaces in the input string which can match zero or more ++ whitespace characters in the format string. <br> ++ Portability Note: The XPG standard advises applications to use ++ at least one whitespace character (as specified by isspace) 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 ++ "%d%m%Y%H%M%S". <br> The strptime function processes the ++ input string from right to left. Each of the three possible ++ input elements (white space, literal, or format) are handled one ++ after the other. If the input cannot be matched to the format ++ string the function stops. The remainder of the format and ++ input strings are not processed. <br> 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 NULL byte at the end of the ++ string. If an error occurs, i.e. strptime fails to match all of ++ the format string, the function returns NULL. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The interface to getdate is the simplest possible for a function ++ to parse a string and return the value. string is the input ++ string and the result is returned in a statically-allocated ++ variable. <br> The details about how the string is ++ processed are hidden from the user. In fact, they can be outside ++ the control of the program. Which formats are recognized is ++ controlled by the file named by the environment variable ++ DATEMSK. This file should contain lines of valid format strings ++ which could be passed to strptime. <br> The getdate ++ function reads these format strings one after the other and ++ tries to match the input string. The first line which ++ completely matches the input string is used. <br> Elements ++ not initialized through the format string retain the values ++ present at the time of the getdate function call. <br> The ++ formats recognized by getdate are the same as for strptime. See ++ above for an explanation. There are only a few extensions to ++ the strptime behavior: <br> @itemize @bullet @item If the ++ %Z format is given the broken-down time is based on the current ++ time of the timezone matched, not of the current timezone of the ++ runtime environment. <br> Note: 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 EST ++ meaning US East Coast time), then uses for countries other than ++ the USA will fail. So far we have found no good solution to ++ this. <br> @item If only the weekday is specified the ++ selected day depends on the current date. If the current ++ weekday is greater or equal to the tm_wday value the current ++ week's day is chosen, otherwise the day next week is chosen. ++ <br> @item A similar heuristic is used when only the month ++ is given and not the year. If the month is greater than or ++ equal to the current month, then the current year is used. ++ Otherwise it wraps to next year. The first day of the month is ++ assumed if one is not explicitly specified. <br> @item The ++ current hour, minute, and second are used if the appropriate ++ value is not set through the format. <br> @item 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. @end itemize ++ <br> It should be noted that the format in the template ++ file need not only contain format elements. The following is a ++ list of possible format strings (taken from the Unix standard): ++ <br> @smallexample %m %A %B %d, %Y %H:%M:%S %A %B %m/%d/%y ++ %I %p %d,%m,%Y %H:%M at %A the %dst of %B in %Y run job at %I ++ %p,%B %dnd %A den %d. %B %Y %H.%M Uhr @end smallexample ++ <br> As you can see, the template list can contain very ++ specific strings like run job at %I %p,%B %dnd. Using the above ++ list of templates and assuming the current time is Mon Sep 22 ++ 12:19:47 EDT 1986 we can obtain the following results for the ++ given input. <br> @multitable {xxxxxxxxxxxx} {xxxxxxxxxx} ++ {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} @item Input ++ @tab Match @tab Result @item Mon @tab %a @tab ++ Mon Sep 22 12:19:47 EDT 1986 @item Sun @tab %a ++ @tab Sun Sep 28 12:19:47 EDT 1986 @item Fri @tab ++ %a @tab Fri Sep 26 12:19:47 EDT 1986 @item September ++ @tab %B @tab Mon Sep 1 12:19:47 EDT 1986 @item January ++ @tab %B @tab Thu Jan 1 12:19:47 EST 1987 @item ++ December @tab %B @tab Mon Dec 1 12:19:47 EST 1986 @item ++ Sep Mon @tab %b %a @tab Mon Sep 1 12:19:47 EDT 1986 @item ++ Jan Fri @tab %b %a @tab Fri Jan 2 12:19:47 EST 1987 @item ++ Dec Mon @tab %b %a @tab Mon Dec 1 12:19:47 EST 1986 ++ @item Jan Wed 1989 @tab %b %a %Y @tab Wed Jan 4 12:19:47 ++ EST 1989 @item Fri 9 @tab %a %H @tab Fri Sep 26 ++ 09:00:00 EDT 1986 @item Feb 10:30 @tab %b %H:%S @tab Sun ++ Feb 1 10:00:30 EST 1987 @item 10:30 @tab %H:%M @tab ++ Tue Sep 23 10:30:00 EDT 1986 @item 13:30 @tab %H:%M ++ @tab Mon Sep 22 13:30:00 EDT 1986 @end multitable <br> The ++ return value of the function is a pointer to a static variable ++ of type struct tm, or a null pointer if an error occurred. The ++ result is only valid until the next getdate call, making this ++ function unusable in multi-threaded applications. <br> The ++ errno variable is not changed. Error conditions are stored in ++ the global variable getdate_err. See the description above for ++ a list of the possible error values. <br> Warning: The ++ getdate function should never be used in SUID-programs. The ++ reason is obvious: using the DATEMSK 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. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The getdate_r function is the reentrant counterpart of getdate. ++ It does not use the global variable getdate_err to signal an ++ error, but instead returns an error code. The same error codes ++ as described in the getdate_err documentation above are used, ++ with 0 meaning success. <br> Moreover, getdate_r stores ++ the broken-down time in the variable of type struct tm pointed ++ to by the second argument, rather than in a static variable. ++ <br> This function is not defined in the Unix standard. ++ Nevertheless it is available on some other Unix systems as well. ++ <br> The warning against using getdate in SUID-programs ++ applies to getdate_r as well. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The tzset function initializes the tzname variable from the ++ value of the TZ 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. ++ ++ ++ ++ ++ ++ ++ This structure is used to specify when a timer should expire. ++ It contains the following members: ++ ++ ++ ++ ++ This is the period between successive timer interrupts. If ++ zero, the alarm will only be sent once. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++
++ ++ ++ The setitimer function sets the timer specified by which ++ according to new. The which argument can have a value of ++ ITIMER_REAL, ITIMER_VIRTUAL, or ITIMER_PROF. <br> If old ++ is not a null pointer, setitimer returns information about any ++ previous unexpired timer of the same kind in the structure it ++ points to. <br> The return value is 0 on success and -1 on ++ failure. The following errno error conditions are defined for ++ this function: <br> @table @code @item EINVAL The timer ++ period is too large. @end table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The getitimer function stores information about the timer ++ specified by which in the structure pointed at by old. ++ <br> The return value and error conditions are the same as ++ for setitimer. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++
++ ++ ++ The alarm function sets the real-time timer to expire in seconds ++ seconds. If you want to cancel any existing alarm, you can do ++ this by calling alarm with a seconds argument of zero. ++ <br> The return value indicates how many seconds remain ++ before the previous alarm would have been sent. If there is no ++ previous alarm, alarm returns zero. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The sleep function waits for seconds or until a signal is ++ delivered, whichever happens first. <br> If sleep function ++ returns because the requested interval is over, it returns a ++ value of zero. If it returns because of delivery of a signal, ++ its return value is the remaining time in the sleep interval. ++ <br> The sleep function is declared in unistd.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ If resolution to seconds is not enough the nanosleep function ++ can be used. As the name suggests the sleep interval can be ++ specified in nanoseconds. The actual elapsed time of the sleep ++ interval might be longer since the system rounds the elapsed ++ time you request up to the next integer multiple of the actual ++ resolution the system can deliver. <br> *requested_time is ++ the elapsed time of the interval you want to sleep. <br> ++ The function returns as *remaining the elapsed time left in the ++ interval for which you requested to sleep. If the interval ++ completed without getting interrupted by a signal, this is zero. ++ <br> struct timespec is described in . <br> If the ++ function returns because the interval is over the return value ++ is zero. If the function returns -1 the global variable errno ++ is set to the following values: <br> @table @code @item ++ EINTR The call was interrupted because a signal was delivered to ++ the thread. If the remaining parameter is not the null pointer ++ the structure pointed to by remaining is updated to contain the ++ remaining elapsed time. <br> @item EINVAL The nanosecond ++ value in the requested_time parameter contains an illegal value. ++ Either the value is negative or greater than or equal to 1000 ++ million. @end table <br> This function is a cancellation ++ point in multi-threaded programs. This is a problem if the ++ thread allocates some resources (like memory, file descriptors, ++ semaphores or whatever) at the time nanosleep is called. If the ++ thread gets canceled these resources stay allocated until the ++ program ends. To avoid this calls to nanosleep should be ++ protected using cancellation handlers. @c ref ++ pthread_cleanup_push / pthread_cleanup_pop <br> The ++ nanosleep function is declared in time.h. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++
++ ++ ++ The getuid function returns the real user ID of the process. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The getgid function returns the real group ID of the process. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The geteuid function returns the effective user ID of the ++ process. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The getegid function returns the effective group ID of the ++ process. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The getgroups function is used to inquire about the ++ supplementary group IDs of the process. Up to count of these ++ group IDs are stored in the array groups; the return value from ++ the function is the number of group IDs actually stored. If ++ count is smaller than the total number of supplementary group ++ IDs, then getgroups returns a value of -1 and errno is set to ++ EINVAL. <br> If count is zero, then getgroups just returns ++ the total number of supplementary group IDs. On systems that do ++ not support supplementary groups, this will always be zero. ++ <br> Here's how to use getgroups to read all the ++ supplementary group IDs: <br> @smallexample @group gid_t * ++ read_all_groups (void) int ngroups = getgroups (0, NULL); ++ gid_t *groups = (gid_t *) xmalloc (ngroups * sizeof ++ (gid_t)); int val = getgroups (ngroups, groups); if (val ++ < 0) free (groups); return NULL; @ ++ return groups; @ @end group @end smallexample ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function sets the effective user ID of a process to newuid, ++ provided that the process is allowed to change its effective ++ user ID. A privileged process (effective user ID zero) can ++ change its effective user ID to any legal value. An ++ unprivileged process with a file user ID can change its ++ effective user ID to its real user ID or to its file user ID. ++ Otherwise, a process may not change its effective user ID at ++ all. <br> The seteuid function returns a value of 0 to ++ indicate successful completion, and a value of -1 to indicate an ++ error. The following errno error conditions are defined for this ++ function: <br> @table @code @item EINVAL The value of the ++ newuid argument is invalid. <br> @item EPERM The process ++ may not change to the specified ID. @end table <br> Older ++ systems (those without the _POSIX_SAVED_IDS feature) do not have ++ this function. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ If the calling process is privileged, this function sets both ++ the real and effective user ID of the process to newuid. It ++ also deletes the file user ID of the process, if any. newuid ++ may be any legal value. (Once this has been done, there is no ++ way to recover the old effective user ID.) <br> If the ++ process is not privileged, and the system supports the ++ _POSIX_SAVED_IDS feature, then this function behaves like ++ seteuid. <br> The return values and error conditions are ++ the same as for seteuid. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function sets the real user ID of the process to ruid and ++ the effective user ID to euid. If ruid is -1, it means not to ++ change the real user ID; likewise if euid is -1, it means not to ++ change the effective user ID. <br> The setreuid function ++ exists for compatibility with 4.3 BSD Unix, which does not ++ support file IDs. You can use this function to swap the ++ effective and real user IDs of the process. (Privileged ++ processes are not limited to this particular usage.) If file ++ IDs are supported, you should use that feature instead of this ++ function. . <br> The return value is 0 on success and -1 ++ on failure. The following errno error conditions are defined for ++ this function: <br> @table @code @item EPERM The process ++ does not have the appropriate privileges; you do not have ++ permission to change to the specified ID. @end table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function sets the effective group ID of the process to ++ newgid, provided that the process is allowed to change its group ++ ID. Just as with seteuid, if the process is privileged it may ++ change its effective group ID to any value; if it isn't, but it ++ has a file group ID, then it may change to its real group ID or ++ file group ID; otherwise it may not change its effective group ++ ID. <br> Note that a process is only privileged if its ++ effective user ID is zero. The effective group ID only affects ++ access permissions. <br> The return values and error ++ conditions for setegid are the same as those for seteuid. ++ <br> This function is only present if _POSIX_SAVED_IDS is ++ defined. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function sets both the real and effective group ID of the ++ process to newgid, provided that the process is privileged. It ++ also deletes the file group ID, if any. <br> If the ++ process is not privileged, then setgid behaves like setegid. ++ <br> The return values and error conditions for setgid are ++ the same as those for seteuid. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function sets the real group ID of the process to rgid and ++ the effective group ID to egid. If rgid is -1, it means not to ++ change the real group ID; likewise if egid is -1, it means not ++ to change the effective group ID. <br> The setregid ++ function is provided for compatibility with 4.3 BSD Unix, which ++ does not support file IDs. You can use this function to swap ++ the effective and real group IDs of the process. (Privileged ++ processes are not limited to this usage.) If file IDs are ++ supported, you should use that feature instead of using this ++ function. . <br> The return values and error conditions ++ for setregid are the same as those for setreuid. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function sets the process's supplementary group IDs. It ++ can only be called from privileged processes. The count ++ argument specifies the number of group IDs in the array groups. ++ <br> This function returns 0 if successful and -1 on ++ error. The following errno error conditions are defined for this ++ function: <br> @table @code @item EPERM The calling ++ process is not privileged. @end table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The initgroups function sets the process's supplementary group ++ IDs to be the normal default for the user name user. The group ++ group is automatically included. <br> This function works ++ by scanning the group database for all the groups user belongs ++ to. It then calls setgroups with the list it has constructed. ++ <br> The return values and error conditions are the same ++ as for setgroups. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The getgrouplist function scans the group database for all the ++ groups user belongs to. Up to *ngroups group IDs corresponding ++ to these groups are stored in the array groups; the return value ++ from the function is the number of group IDs actually stored. ++ If *ngroups is smaller than the total number of groups found, ++ then getgrouplist returns a value of -1 and stores the actual ++ number of groups in *ngroups. The group group is automatically ++ included in the list of groups returned by getgrouplist. ++ <br> Here's how to use getgrouplist to read all ++ supplementary groups for user: <br> @smallexample @group ++ gid_t * supplementary_groups (char *user) int ngroups = 16; ++ gid_t *groups = (gid_t *) xmalloc (ngroups * sizeof ++ (gid_t)); struct passwd *pw = getpwnam (user); <br> if ++ (pw == NULL) return NULL; <br> if (getgrouplist ++ (pw->pw_name, pw->pw_gid, groups, &ngroups) < 0) ++ groups = xrealloc (ngroups * sizeof (gid_t)); ++ getgrouplist (pw->pw_name, pw->pw_gid, groups, ++ &ngroups); @ return groups; @ @end group @end ++ smallexample ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The getlogin 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 cuserid. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The cuserid function returns a pointer to a string containing a ++ user name associated with the effective ID of the process. If ++ string is not a null pointer, it should be an array that can ++ hold at least L_cuserid characters; the string is returned in ++ this array. Otherwise, a pointer to a string in a static area ++ is returned. This string is statically allocated and might be ++ overwritten on subsequent calls to this function or to getlogin. ++ <br> The use of this function is deprecated since it is ++ marked to be withdrawn in XPG4.2 and has already been removed ++ from newer revisions of POSIX.1. ++ ++ ++ ++ ++ ++ ++ The exit_status data structure is used to hold information about ++ the exit status of processes marked as DEAD_PROCESS in the user ++ accounting database. <br> ++ ++ ++ ++ ++ The exit status of the process. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ The utmp data structure is used to hold information about ++ entries in the user accounting database. On the GNU system it ++ has the following members: <br> ++ ++ ++ ++ ++ Specifies the type of login; one of EMPTY, RUN_LVL, BOOT_TIME, ++ OLD_TIME, NEW_TIME, INIT_PROCESS, LOGIN_PROCESS, USER_PROCESS, ++ DEAD_PROCESS or ACCOUNTING. <br> ++ ++ ++ ++ ++ The process ID number of the login process. <br> ++ ++ ++ ++ ++ The device name of the tty (without /dev/). <br> ++ ++ ++ ++ ++ The inittab ID of the process. <br> ++ ++ ++ ++ ++ The user's login name. <br> ++ ++ ++ ++ ++ The name of the host from which the user logged in. <br> ++ ++ ++ ++ ++ The exit status of a process marked as DEAD_PROCESS. <br> ++ ++ ++ ++ ++ The Session ID, used for windowing. <br> ++ ++ ++ ++ ++ Time the entry was made. For entries of type OLD_TIME this is ++ the time when the system clock changed, and for entries of type ++ NEW_TIME this is the time the system clock was set to. ++ <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++
++ ++ ++ This function opens the user accounting database to begin ++ scanning it. You can then call getutent, getutid or getutline to ++ read entries and pututline to write entries. <br> If the ++ database is already open, it resets the input to the beginning ++ of the database. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The getutent 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 getutent. You must copy the contents of the structure ++ if you wish to save the information or you can use the ++ getutent_r function which stores the data in a user-provided ++ buffer. <br> A null pointer is returned in case no further ++ entry is available. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function closes the user accounting database. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function searches forward from the current point in the ++ database for an entry that matches id. If the ut_type member of ++ the id structure is one of RUN_LVL, BOOT_TIME, OLD_TIME or ++ NEW_TIME the entries match if the ut_type members are identical. ++ If the ut_type member of the id structure is INIT_PROCESS, ++ LOGIN_PROCESS, USER_PROCESS or DEAD_PROCESS, the entries match ++ if the ut_type member of the entry read from the database is one ++ of these four, and the ut_id members match. However if the ++ ut_id member of either the id structure or the entry read from ++ the database is empty it checks if the ut_line members match ++ instead. If a matching entry is found, getutid returns a ++ pointer to the entry, which is statically allocated, and may be ++ overwritten by a subsequent call to getutent, getutid or ++ getutline. You must copy the contents of the structure if you ++ wish to save the information. <br> A null pointer is ++ returned in case the end of the database is reached without a ++ match. <br> The getutid function may cache the last read ++ entry. Therefore, if you are using getutid to search for ++ multiple occurrences, it is necessary to zero out the static ++ data after each call. Otherwise getutid could just return a ++ pointer to the same entry over and over again. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function searches forward from the current point in the ++ database until it finds an entry whose ut_type value is ++ LOGIN_PROCESS or USER_PROCESS, and whose ut_line member matches ++ the ut_line member of the line 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 ++ getutent, getutid or getutline. You must copy the contents of ++ the structure if you wish to save the information. <br> A ++ null pointer is returned in case the end of the database is ++ reached without a match. <br> The getutline function may ++ cache the last read entry. Therefore if you are using getutline ++ to search for multiple occurrences, it is necessary to zero out ++ the static data after each call. Otherwise getutline could just ++ return a pointer to the same entry over and over again. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The pututline function inserts the entry *utmp 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 getutid to search for the position to insert the entry, ++ however this will not modify the static structure returned by ++ getutent, getutid and getutline. If this search fails, the ++ entry is appended to the database. <br> The pututline ++ 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 errno error conditions are ++ defined for this function: <br> @table @code @item EPERM ++ The process does not have the appropriate privileges; you cannot ++ modify the user accounting database. @end table ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The getutent_r is equivalent to the getutent 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 buffer. <br> If the ++ call was successful, the function returns 0 and the pointer ++ variable pointed to by the parameter result contains a pointer ++ to the buffer which contains the result (this is most probably ++ the same value as buffer). If something went wrong during the ++ execution of getutent_r the function returns -1. <br> This ++ function is a GNU extension. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function retrieves just like getutid the next entry ++ matching the information stored in id. But the result is stored ++ in the buffer pointed to by the parameter buffer. <br> If ++ successful the function returns 0 and the pointer variable ++ pointed to by the parameter result contains a pointer to the ++ buffer with the result (probably the same as result. If not ++ successful the function return -1. <br> This function is a ++ GNU extension. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function retrieves just like getutline the next entry ++ matching the information stored in line. But the result is ++ stored in the buffer pointed to by the parameter buffer. ++ <br> If successful the function returns 0 and the pointer ++ variable pointed to by the parameter result contains a pointer ++ to the buffer with the result (probably the same as result. If ++ not successful the function return -1. <br> This function ++ is a GNU extension. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The utmpname function changes the name of the database to be ++ examined to file, and closes any previously opened database. By ++ default getutent, getutid, getutline and pututline read from and ++ write to the user accounting database. <br> The following ++ macros are defined for use as the file argument: <br> ++ @deftypevr Macro {char *} _PATH_UTMP This macro is used to ++ specify the user accounting database. @end deftypevr <br> ++ @deftypevr Macro {char *} _PATH_WTMP This macro is used to ++ specify the user accounting log file. @end deftypevr <br> ++ The utmpname function returns a value of 0 if the new name was ++ successfully stored, and a value of -1 to indicate an error. ++ Note that utmpname 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. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The updwtmp function appends the entry *utmp to the database ++ specified by wtmp_file. For possible values for the wtmp_file ++ argument see the utmpname function. ++ ++ ++ ++ ++ ++ ++ The utmpx data structure contains at least the following ++ members: <br> ++ ++ ++ ++ ++ Specifies the type of login; one of EMPTY, RUN_LVL, BOOT_TIME, ++ OLD_TIME, NEW_TIME, INIT_PROCESS, LOGIN_PROCESS, USER_PROCESS or ++ DEAD_PROCESS. <br> ++ ++ ++ ++ ++ The process ID number of the login process. <br> ++ ++ ++ ++ ++ The device name of the tty (without /dev/). <br> ++ ++ ++ ++ ++ The inittab ID of the process. <br> ++ ++ ++ ++ ++ The user's login name. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to setutent. On the GNU system it is ++ simply an alias for setutent. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The getutxent function is similar to getutent, but returns a ++ pointer to a struct utmpx instead of struct utmp. On the GNU ++ system it simply is an alias for getutent. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to endutent. On the GNU system it is ++ simply an alias for endutent. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to getutid, but uses struct utmpx ++ instead of struct utmp. On the GNU system it is simply an alias ++ for getutid. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to getutid, but uses struct utmpx ++ instead of struct utmp. On the GNU system it is simply an alias ++ for getutline. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The pututxline function is functionally identical to pututline, ++ but uses struct utmpx instead of struct utmp. On the GNU ++ system, pututxline is simply an alias for pututline. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The utmpxname function is functionally identical to utmpname. ++ On the GNU system, utmpxname is simply an alias for utmpname. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++
++ ++ ++ getutmp copies the information, insofar as the structures are ++ compatible, from utmpx to utmp. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++
++ ++ ++ getutmpx copies the information, insofar as the structures are ++ compatible, from utmp to utmpx. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function makes filedes the controlling terminal of the ++ current process, redirects standard input, standard output and ++ standard error output to this terminal, and closes filedes. ++ <br> This function returns 0 on successful completion, and ++ -1 on error. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The login functions inserts an entry into the user accounting ++ database. The ut_line member is set to the name of the terminal ++ on standard input. If standard input is not a terminal login ++ uses standard output or standard error output to determine the ++ name of the terminal. If struct utmp has a ut_type member, ++ login sets it to USER_PROCESS, and if there is an ut_pid member, ++ it will be set to the process ID of the current process. The ++ remaining entries are copied from entry. <br> A copy of ++ the entry is written to the user accounting log file. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function modifies the user accounting database to indicate ++ that the user on ut_line has logged out. <br> The logout ++ function returns 1 if the entry was successfully written to the ++ database, or 0 on error. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The logwtmp function appends an entry to the user accounting log ++ file, for the current time and the information provided in the ++ ut_line, ut_name and ut_host arguments. ++ ++ ++ ++ ++ ++ ++ The passwd data structure is used to hold information about ++ entries in the system user data base. It has at least the ++ following members: <br> ++ ++ ++ ++ ++ The user's login name. <br> ++ ++ ++ ++ ++ The encrypted password string. <br> ++ ++ ++ ++ ++ The user ID number. <br> ++ ++ ++ ++ ++ The user's default group ID number. <br> ++ ++ ++ ++ ++ A string typically containing the user's real name, and possibly ++ other information such as a phone number. <br> ++ ++ ++ ++ ++ The user's home directory, or initial working directory. This ++ might be a null pointer, in which case the interpretation is ++ system-dependent. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function returns a pointer to a statically-allocated ++ structure containing information about the user whose user ID is ++ uid. This structure may be overwritten on subsequent calls to ++ getpwuid. <br> A null pointer value indicates there is no ++ user in the data base with user ID uid. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to getpwuid in that it returns ++ information about the user whose user ID is uid. However, it ++ fills the user supplied structure pointed to by result_buf with ++ the information instead of using a static buffer. The first ++ buflen bytes of the additional buffer pointed to by buffer are ++ used to contain additional information, normally strings which ++ are pointed to by the elements of the result structure. ++ <br> If a user with ID uid is found, the pointer returned ++ in result points to the record which contains the wanted data ++ (i.e., result contains the value result_buf). If no user is ++ found or if an error occurred, the pointer returned in result is ++ a null pointer. The function returns zero or an error code. If ++ the buffer buffer is too small to contain all the needed ++ information, the error code ERANGE is returned and errno is set ++ to ERANGE. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function returns a pointer to a statically-allocated ++ structure containing information about the user whose user name ++ is name. This structure may be overwritten on subsequent calls ++ to getpwnam. <br> A null pointer return indicates there is ++ no user named name. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to getpwnam in that is returns ++ information about the user whose user name is name. However, ++ like getpwuid_r, it fills the user supplied buffers in ++ result_buf and buffer with the information instead of using a ++ static buffer. <br> The return values are the same as for ++ getpwuid_r. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function reads the next user entry from stream and returns ++ a pointer to the entry. The structure is statically allocated ++ and is rewritten on subsequent calls to fgetpwent. You must ++ copy the contents of the structure if you wish to save the ++ information. <br> The stream must correspond to a file in ++ the same format as the standard password database file. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to fgetpwent in that it reads the next ++ user entry from stream. But the result is returned in the ++ structure pointed to by result_buf. The first buflen bytes of ++ the additional buffer pointed to by buffer are used to contain ++ additional information, normally strings which are pointed to by ++ the elements of the result structure. <br> The stream must ++ correspond to a file in the same format as the standard password ++ database file. <br> If the function returns zero result ++ points to the structure with the wanted data (normally this is ++ in result_buf). If errors occurred the return value is nonzero ++ and result contains a null pointer. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function initializes a stream which getpwent and getpwent_r ++ use to read the user database. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The getpwent function reads the next entry from the stream ++ initialized by setpwent. It returns a pointer to the entry. ++ The structure is statically allocated and is rewritten on ++ subsequent calls to getpwent. You must copy the contents of the ++ structure if you wish to save the information. <br> A null ++ pointer is returned when no more entries are available. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to getpwent in that it returns the next ++ entry from the stream initialized by setpwent. Like ++ fgetpwent_r, it uses the user-supplied buffers in result_buf and ++ buffer to return the information requested. <br> The ++ return values are the same as for fgetpwent_r. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function closes the internal stream used by getpwent or ++ getpwent_r. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function writes the user entry *p to the stream stream, in ++ the format used for the standard user database file. The return ++ value is zero on success and nonzero on failure. <br> This ++ function exists for compatibility with SVID. We recommend that ++ you avoid using it, because it makes sense only on the ++ assumption that the struct passwd 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. @c Then how are ++ programmers to modify the password file? -zw <br> The ++ function putpwent is declared in pwd.h. ++ ++ ++ ++ ++ ++ ++ The group structure is used to hold information about an entry ++ in the system group database. It has at least the following ++ members: <br> ++ ++ ++ ++ ++ The name of the group. <br> ++ ++ ++ ++ ++ The group ID of the group. <br> ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function returns a pointer to a statically-allocated ++ structure containing information about the group whose group ID ++ is gid. This structure may be overwritten by subsequent calls to ++ getgrgid. <br> A null pointer indicates there is no group ++ with ID gid. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to getgrgid in that it returns ++ information about the group whose group ID is gid. However, it ++ fills the user supplied structure pointed to by result_buf with ++ the information instead of using a static buffer. The first ++ buflen bytes of the additional buffer pointed to by buffer are ++ used to contain additional information, normally strings which ++ are pointed to by the elements of the result structure. ++ <br> If a group with ID gid is found, the pointer returned ++ in result points to the record which contains the wanted data ++ (i.e., result contains the value result_buf). If no group is ++ found or if an error occurred, the pointer returned in result is ++ a null pointer. The function returns zero or an error code. If ++ the buffer buffer is too small to contain all the needed ++ information, the error code ERANGE is returned and errno is set ++ to ERANGE. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function returns a pointer to a statically-allocated ++ structure containing information about the group whose group ++ name is name. This structure may be overwritten by subsequent ++ calls to getgrnam. <br> A null pointer indicates there is ++ no group named name. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to getgrnam in that is returns ++ information about the group whose group name is name. Like ++ getgrgid_r, it uses the user supplied buffers in result_buf and ++ buffer, not a static buffer. <br> The return values are ++ the same as for getgrgid_r ERANGE. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The fgetgrent function reads the next entry from stream. It ++ returns a pointer to the entry. The structure is statically ++ allocated and is overwritten on subsequent calls to fgetgrent. ++ You must copy the contents of the structure if you wish to save ++ the information. <br> The stream must correspond to a file ++ in the same format as the standard group database file. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to fgetgrent in that it reads the next ++ user entry from stream. But the result is returned in the ++ structure pointed to by result_buf. The first buflen bytes of ++ the additional buffer pointed to by buffer are used to contain ++ additional information, normally strings which are pointed to by ++ the elements of the result structure. <br> This stream ++ must correspond to a file in the same format as the standard ++ group database file. <br> If the function returns zero ++ result points to the structure with the wanted data (normally ++ this is in result_buf). If errors occurred the return value is ++ non-zero and result contains a null pointer. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function initializes a stream for reading from the group ++ data base. You use this stream by calling getgrent or ++ getgrent_r. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ The getgrent function reads the next entry from the stream ++ initialized by setgrent. It returns a pointer to the entry. ++ The structure is statically allocated and is overwritten on ++ subsequent calls to getgrent. You must copy the contents of the ++ structure if you wish to save the information. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to getgrent in that it returns the next ++ entry from the stream initialized by setgrent. Like ++ fgetgrent_r, it places the result in user-supplied buffers ++ pointed to result_buf and buffer. <br> If the function ++ returns zero result contains a pointer to the data (normally ++ equal to result_buf). If errors occurred the return value is ++ non-zero and result contains a null pointer. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function closes the internal stream used by getgrent or ++ getgrent_r. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ A call to this function initializes the internal state of the ++ library to allow following calls of the getnetgrent to iterate ++ over all entries in the netgroup with name netgroup. <br> ++ When the call is successful (i.e., when a netgroup with this ++ name exists) the return value is 1. When the return value is 0 ++ no netgroup of this name is known or some other error occurred. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function returns the next unprocessed entry of the ++ currently selected netgroup. The string pointers, in which ++ addresses are passed in the arguments hostp, userp, and domainp, ++ will contain after a successful call pointers to appropriate ++ strings. If the string in the next entry is empty the pointer ++ has the value NULL. The returned string pointers are only valid ++ if none of the netgroup related functions are called. <br> ++ The return value is 1 if the next entry was successfully read. ++ A value of 0 means no further entries exist or internal errors ++ occurred. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function is similar to getnetgrent with only one exception: ++ the strings the three string pointers hostp, userp, and domainp ++ point to, are placed in the buffer of buflen bytes starting at ++ buffer. This means the returned values are valid even after ++ other netgroup related functions are called. <br> The ++ return value is 1 if the next entry was successfully read and ++ the buffer contains enough room to place the strings in it. 0 ++ is returned in case no more entries are found, the buffer is too ++ small, or internal errors occurred. <br> This function is ++ a GNU extension. The original implementation in the SunOS libc ++ does not provide this function. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function frees all buffers which were allocated to process ++ the last selected netgroup. As a result all string pointers ++ returned by calls to getnetgrent are invalid afterwards. ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
++ ++ ++ This function tests whether the triple specified by the ++ parameters hostp, userp, and domainp is part of the netgroup ++ netgroup. Using this function has the advantage that <br> ++ @enumerate @item no other netgroup function can use the global ++ netgroup state since internal locking is used and @item the ++ function is implemented more efficiently than successive calls ++ to the other set/get/endnetgrent functions. @end enumerate ++ <br> Any of the pointers hostp, userp, and domainp can be ++ NULL which means any value is accepted in this position. This ++ is also true for the name - which should not match any other ++ string otherwise. <br> The return value is 1 if an entry ++ matching the given triple is found in the netgroup. The return ++ value is 0 if the netgroup itself is not found, the netgroup ++ does not contain the triple or internal errors occurred. ++ ++ ++ ++ +diff -uNr ./eclipse-cdt-2.1.1.orig/org.eclipse.cdt.releng/results/plugins/org.eclipse.cdt.ui/plugin.properties ./eclipse-cdt-2.1.1/org.eclipse.cdt.releng/results/plugins/org.eclipse.cdt.ui/plugin.properties +--- ./results/plugins/org.eclipse.cdt.ui/plugin.properties 2004-12-03 15:57:38.000000000 -0600 ++++ ./results/plugins/org.eclipse.cdt.ui/plugin.properties 2005-04-19 13:38:34.858629590 -0500 +@@ -268,6 +268,8 @@ + annotationHoverDescription= Shows the description of the selected annotation. + problemHover= Problem Description + problemHoverDescription= Shows the description of the selected problem. ++clibHover= Library Documentation ++clibHoverDescription= Shows the library documentation of the selected element. + + # + appearancePrefName= Appearance +diff -uNr ./eclipse-cdt-2.1.1.orig/org.eclipse.cdt.releng/results/plugins/org.eclipse.cdt.ui/plugin.xml ./eclipse-cdt-2.1.1/org.eclipse.cdt.releng/results/plugins/org.eclipse.cdt.ui/plugin.xml +--- ./results/plugins/org.eclipse.cdt.ui/plugin.xml 2005-02-03 09:45:34.000000000 -0600 ++++ ./results/plugins/org.eclipse.cdt.ui/plugin.xml 2005-04-19 13:39:19.419899554 -0500 +@@ -157,6 +157,12 @@ + id="org.eclipse.cdt.ui.CDocHover"> + + ++ ++ 0) { ++ HTMLPrinter.insertPageProlog(buffer, 0); ++ HTMLPrinter.addPageEpilog(buffer); ++ return buffer.toString(); ++ } ++ } catch(Exception ex) { ++ /* Ignore */ ++ } ++ ++ return null; ++ } ++ ++ /* (non-Javadoc) ++ * @see org.eclipse.jface.text.ITextHover#getHoverRegion(org.eclipse.jface.text.ITextViewer, int) ++ */ ++ public IRegion getHoverRegion(ITextViewer viewer, int offset) { ++ Point selectedRange = viewer.getSelectedRange(); ++ if (selectedRange.x >= 0 && ++ selectedRange.y > 0 && ++ offset >= selectedRange.x && ++ offset <= selectedRange.x + selectedRange.y) ++ return new Region( selectedRange.x, selectedRange.y ); ++ if (viewer != null) ++ return CWordFinder.findWord(viewer.getDocument(), offset); ++ return null; ++ } ++ ++} --- eclipse-cdt-3.1.1.orig/debian/patches/eclipse-cdt-no-sdkbuild.patch +++ eclipse-cdt-3.1.1/debian/patches/eclipse-cdt-no-sdkbuild.patch @@ -0,0 +1,28 @@ +--- build.xml 2005-02-24 14:10:52.000000000 -0600 ++++ build.xml.new 2005-04-04 12:51:46.117849336 -0500 +@@ -37,15 +37,9 @@ + + + +- +- +- + + + +- +- +- + + + +@@ -57,9 +51,6 @@ + + + +- +- +- + + + --- eclipse-cdt-3.1.1.orig/debian/patches/eclipse-cdt-no-tests.patch +++ eclipse-cdt-3.1.1/debian/patches/eclipse-cdt-no-tests.patch @@ -0,0 +1,11 @@ +--- build.xml.orig 2005-04-11 09:01:15.241527048 -0500 ++++ build.xml 2005-04-11 09:01:30.151743318 -0500 +@@ -4,7 +4,7 @@ + + + +- ++ + + + --- eclipse-cdt-3.1.1.orig/debian/patches/eclipse-cdt-platform-build-linux.patch +++ eclipse-cdt-3.1.1/debian/patches/eclipse-cdt-platform-build-linux.patch @@ -0,0 +1,20 @@ +--- platform/build.properties.orig 2005-04-11 08:43:20.392950997 -0500 ++++ platform/build.properties 2005-04-11 08:43:29.807826270 -0500 +@@ -60,15 +60,10 @@ + # configs=win32,win32,x86 & linux,motif,x86 + # By default the value is *,*,* + configs=\ +- aix,motif,ppc \ +- & linux,gtk,x86 \ ++ linux,gtk,x86 \ + & linux,gtk,x86_64 \ + & linux,gtk,ppc \ +- & linux,gtk,ia64 \ +- & macosx,carbon,ppc \ +- & qnx,photon,x86 \ +- & solaris,motif,sparc \ +- & win32,win32,x86 ++ & linux,gtk,ia64 + + archivesFormat=\ + aix,motif,ppc-tar \ --- eclipse-cdt-3.1.1.orig/debian/patches/eclipse-cdt-sdk-build-linux.patch +++ eclipse-cdt-3.1.1/debian/patches/eclipse-cdt-sdk-build-linux.patch @@ -0,0 +1,20 @@ +--- sdk/build.properties.orig 2005-04-11 08:53:54.294261362 -0500 ++++ sdk/build.properties 2005-04-11 08:54:10.457332110 -0500 +@@ -60,15 +60,10 @@ + # configs=win32,win32,x86 & linux,motif,x86 + # By default the value is *,*,* + configs=\ +- aix,motif,ppc\ +- & linux,gtk,x86 \ ++ linux,gtk,x86 \ + & linux,gtk,x86_64 \ + & linux,gtk,ppc \ +- & linux,gtk,ia64 \ +- & macosx,carbon,ppc \ +- & qnx,photon,x86 \ +- & solaris,motif,sparc \ +- & win32,win32,x86 ++ & linux,gtk,ia64 + + archivesFormat=\ + aix,motif,ppc-tar \ --- eclipse-cdt-3.1.1.orig/debian/patches/eclipse-cdt-zzz-platform-build-linux-x86-only.patch +++ eclipse-cdt-3.1.1/debian/patches/eclipse-cdt-zzz-platform-build-linux-x86-only.patch @@ -0,0 +1,14 @@ +--- source-tree/org.eclipse.cdt.releng/platform/build.properties.orig 2005-11-14 07:55:20.000000000 +0000 ++++ source-tree/org.eclipse.cdt.releng/platform/build.properties 2005-11-14 07:55:43.000000000 +0000 +@@ -71,10 +71,7 @@ + # configs=win32,win32,x86 & linux,motif,x86 + # By default the value is *,*,* + configs=\ +- linux,gtk,x86 \ +- & linux,gtk,x86_64 \ +- & linux,gtk,ppc \ +- & linux,gtk,ia64 ++ linux,gtk,@ARCH@ + + archivesFormat=\ + aix,motif,ppc-tar \ --- eclipse-cdt-3.1.1.orig/debian/patches/eclipse-cdt-disable-filelog.patch +++ eclipse-cdt-3.1.1/debian/patches/eclipse-cdt-disable-filelog.patch @@ -0,0 +1,11 @@ +--- source-tree/org.eclipse.cdt.releng/results/plugins/org.eclipse.cdt.doc.isv/buildDoc.xml.orig 2005-12-21 15:26:32.000000000 +0100 ++++ source-tree/org.eclipse.cdt.releng/results/plugins/org.eclipse.cdt.doc.isv/buildDoc.xml 2005-12-21 15:27:08.000000000 +0100 +@@ -49,7 +49,7 @@ + + + +- ++ + + +