| <!-- This file automatically generated by an Eclipse utility --> |
| <!DOCTYPE descriptions [ |
| |
| <!ELEMENT descriptions (construct)*> |
| |
| <!ELEMENT construct (structure|function)*> |
| <!ATTLIST construct |
| id ID #REQUIRED |
| type CDATA #REQUIRED |
| > |
| |
| <!ELEMENT structure (synopsis?, elements?)?> |
| |
| <!ELEMENT elements (element*)> |
| |
| <!ELEMENT element (synopsis*)> |
| <!ATTLIST element |
| content CDATA #REQUIRED |
| > |
| |
| <!ELEMENT synopsis (#PCDATA)*> |
| |
| <!ELEMENT function (prototype,headers?,synopsis)> |
| <!ATTLIST function |
| returntype CDATA #REQUIRED |
| > |
| |
| <!ELEMENT prototype (parameter+)?> |
| |
| <!ELEMENT parameter (#PCDATA)*> |
| <!ATTLIST parameter |
| content CDATA #REQUIRED |
| > |
| |
| <!ELEMENT headers (header+)?> |
| |
| <!ELEMENT header (#PCDATA)*> |
| <!ATTLIST header |
| filename CDATA #REQUIRED |
| > |
| |
| ]> |
| |
| <descriptions> |
| <!-- Following is needed to comply with the GFDL regarding modification and invariant sections. --> |
| <construct id="function-0-REQUIRED-SECTIONS" type="function"> |
| <function returntype="void"> |
| <prototype> |
| </prototype> |
| <synopsis> |
| The GNU C Library (Eclipse Libhover Version) |
| |
| Based on The GNU C Library |
| EDITION 0.12 |
| VERSION 2.8 |
| UPDATED 2007-10-27 |
| ISBN 1-882114-55-8 |
| |
| This file documents the GNU C library. |
| |
| This is based on Edition 0.12, last updated 2007-10-27 |
| of The GNU C Library Reference Manual, for version 2.8. |
| |
| Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2001, 2002, |
| 2003, 2007, 2008, 2010 Free Software Foundation, Inc. |
| |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version 1.3 or |
| any later version published by the Free Software Foundation; with the |
| Invariant Sections being ``Free Software Needs Free Documentation'' |
| and ``GNU Lesser General Public License'', the Front-Cover texts being |
| ``A GNU Manual'', and with the Back-Cover Texts as in (a) below. A |
| copy of the license is included in the section entitled "GNU Free |
| Documentation License". |
| |
| (a) The FSF's Back-Cover Text is: ``You have the freedom to |
| copy and modify this GNU manual. Buying copies from the FSF |
| supports it in developing GNU and promoting software freedom.'' |
| |
| Authors |
| Sandra Loosemore |
| with |
| Richard M. Stallman, Roland McGrath, Andrew Oram, and Ulrich Drepper |
| Edition 0.12 |
| last updated 2007-10-27 |
| for version 2.8 |
| |
| Modified for use with Eclipse libhover plug-in by Jeff Johnston. |
| |
| Modified documentation published by Eclipse Linux Tools project |
| |
| Cover art for the Free Software Foundation's printed edition |
| by Etienne Suvasa. |
| |
| ================================================================================================== |
| |
| Free Software Needs Free Documentation |
| |
| The biggest deficiency in the free software community today is not in |
| the software---it is the lack of good free documentation that we can |
| include with the free software. Many of our most important |
| programs do not come with free reference manuals and free introductory |
| texts. Documentation is an essential part of any software package; |
| when an important free software package does not come with a free |
| manual and a free tutorial, that is a major gap. We have many such |
| gaps today. |
| |
| Consider Perl, for instance. The tutorial manuals that people |
| normally use are non-free. How did this come about? Because the |
| authors of those manuals published them with restrictive terms---no |
| copying, no modification, source files not available---which exclude |
| them from the free software world. |
| |
| That wasn't the first time this sort of thing happened, and it was far |
| from the last. Many times we have heard a GNU user eagerly describe a |
| manual that he is writing, his intended contribution to the community, |
| only to learn that he had ruined everything by signing a publication |
| contract to make it non-free. |
| |
| Free documentation, like free software, is a matter of freedom, not |
| price. The problem with the non-free manual is not that publishers |
| charge a price for printed copies---that in itself is fine. (The Free |
| Software Foundation sells printed copies of manuals, too.) The |
| problem is the restrictions on the use of the manual. Free manuals |
| are available in source code form, and give you permission to copy and |
| modify. Non-free manuals do not allow this. |
| |
| The criteria of freedom for a free manual are roughly the same as for |
| free software. Redistribution (including the normal kinds of |
| commercial redistribution) must be permitted, so that the manual can |
| accompany every copy of the program, both on-line and on paper. |
| |
| Permission for modification of the technical content is crucial too. |
| When people modify the software, adding or changing features, if they |
| are conscientious they will change the manual too---so they can |
| provide accurate and clear documentation for the modified program. A |
| manual that leaves you no choice but to write a new manual to document |
| a changed version of the program is not really available to our |
| community. |
| |
| Some kinds of limits on the way modification is handled are |
| acceptable. For example, requirements to preserve the original |
| author's copyright notice, the distribution terms, or the list of |
| authors, are ok. It is also no problem to require modified versions |
| to include notice that they were modified. Even entire sections that |
| may not be deleted or changed are acceptable, as long as they deal |
| with nontechnical topics (like this one). These kinds of restrictions |
| are acceptable because they don't obstruct the community's normal use |
| of the manual. |
| |
| However, it must be possible to modify all the @emph{technical} |
| content of the manual, and then distribute the result in all the usual |
| media, through all the usual channels. Otherwise, the restrictions |
| obstruct the use of the manual, it is not free, and we need another |
| manual to replace it. |
| |
| Please spread the word about this issue. Our community continues to |
| lose manuals to proprietary publishing. If we spread the word that |
| free software needs free reference manuals and free tutorials, perhaps |
| the next person who wants to contribute by writing documentation will |
| realize, before it is too late, that only free manuals contribute to |
| the free software community. |
| |
| If you are writing documentation, please insist on publishing it under |
| the GNU Free Documentation License or another free documentation |
| license. Remember that this decision requires your approval---you |
| don't have to let the publisher decide. Some commercial publishers |
| will use a free license if you insist, but they will not propose the |
| option; it is up to you to raise the issue and say firmly that this is |
| what you want. If the publisher you are dealing with refuses, please |
| try other publishers. If you're not sure whether a proposed license |
| is free, write to @email{licensing@@gnu.org}. |
| |
| You can encourage commercial publishers to sell more free, copylefted |
| manuals and tutorials by buying them, and particularly by buying |
| copies from the publishers that paid for their writing or for major |
| improvements. Meanwhile, try to avoid buying non-free documentation |
| at all. Check the distribution terms of a manual before you buy it, |
| and insist that whoever seeks your business must respect your freedom. |
| Check the history of the book, and try reward the publishers that have |
| paid or pay the authors to work on it. |
| |
| The Free Software Foundation maintains a list of free documentation |
| published by other publishers, at |
| http://www.fsf.org/doc/other-free-books.html. |
| |
| ==================================================================================================== |
| |
| GNU Lesser General Public License |
| |
| Version 2.1, February 1999 |
| |
| Copyright @copyright{} 1991, 1999 Free Software Foundation, Inc. |
| 59 Temple Place -- Suite 330, Boston, MA 02111-1307, USA |
| |
| Everyone is permitted to copy and distribute verbatim copies |
| of this license document, but changing it is not allowed. |
| |
| [This is the first released version of the Lesser GPL. It also counts |
| as the successor of the GNU Library Public License, version 2, hence the |
| version number 2.1.] |
| |
| Preamble |
| |
| The licenses for most software are designed to take away your |
| freedom to share and change it. By contrast, the GNU General Public |
| Licenses are intended to guarantee your freedom to share and change |
| free software---to make sure the software is free for all its users. |
| |
| This license, the Lesser General Public License, applies to some |
| specially designated software---typically libraries---of the Free |
| Software Foundation and other authors who decide to use it. You can use |
| it too, but we suggest you first think carefully about whether this |
| license or the ordinary General Public License is the better strategy to |
| use in any particular case, based on the explanations below. |
| |
| When we speak of free software, we are referring to freedom of use, |
| not price. Our General Public Licenses are designed to make sure that |
| you have the freedom to distribute copies of free software (and charge |
| for this service if you wish); that you receive source code or can get |
| it if you want it; that you can change the software and use pieces of it |
| in new free programs; and that you are informed that you can do these |
| things. |
| |
| To protect your rights, we need to make restrictions that forbid |
| distributors to deny you these rights or to ask you to surrender these |
| rights. These restrictions translate to certain responsibilities for |
| you if you distribute copies of the library or if you modify it. |
| |
| For example, if you distribute copies of the library, whether gratis |
| or for a fee, you must give the recipients all the rights that we gave |
| you. You must make sure that they, too, receive or can get the source |
| code. If you link other code with the library, you must provide |
| complete object files to the recipients, so that they can relink them |
| with the library after making changes to the library and recompiling |
| it. And you must show them these terms so they know their rights. |
| |
| We protect your rights with a two-step method: (1) we copyright the |
| library, and (2) we offer you this license, which gives you legal |
| permission to copy, distribute and/or modify the library. |
| |
| To protect each distributor, we want to make it very clear that |
| there is no warranty for the free library. Also, if the library is |
| modified by someone else and passed on, the recipients should know |
| that what they have is not the original version, so that the original |
| author's reputation will not be affected by problems that might be |
| introduced by others. |
| |
| Finally, software patents pose a constant threat to the existence of |
| any free program. We wish to make sure that a company cannot |
| effectively restrict the users of a free program by obtaining a |
| restrictive license from a patent holder. Therefore, we insist that |
| any patent license obtained for a version of the library must be |
| consistent with the full freedom of use specified in this license. |
| |
| Most GNU software, including some libraries, is covered by the |
| ordinary GNU General Public License. This license, the GNU Lesser |
| General Public License, applies to certain designated libraries, and |
| is quite different from the ordinary General Public License. We use |
| this license for certain libraries in order to permit linking those |
| libraries into non-free programs. |
| |
| When a program is linked with a library, whether statically or using |
| a shared library, the combination of the two is legally speaking a |
| combined work, a derivative of the original library. The ordinary |
| General Public License therefore permits such linking only if the |
| entire combination fits its criteria of freedom. The Lesser General |
| Public License permits more lax criteria for linking other code with |
| the library. |
| |
| We call this license the @dfn{Lesser} General Public License because it |
| does @emph{Less} to protect the user's freedom than the ordinary General |
| Public License. It also provides other free software developers Less |
| of an advantage over competing non-free programs. These disadvantages |
| are the reason we use the ordinary General Public License for many |
| libraries. However, the Lesser license provides advantages in certain |
| special circumstances. |
| |
| For example, on rare occasions, there may be a special need to |
| encourage the widest possible use of a certain library, so that it becomes |
| a de-facto standard. To achieve this, non-free programs must be |
| allowed to use the library. A more frequent case is that a free |
| library does the same job as widely used non-free libraries. In this |
| case, there is little to gain by limiting the free library to free |
| software only, so we use the Lesser General Public License. |
| |
| In other cases, permission to use a particular library in non-free |
| programs enables a greater number of people to use a large body of |
| free software. For example, permission to use the GNU C Library in |
| non-free programs enables many more people to use the whole GNU |
| operating system, as well as its variant, the GNU/Linux operating |
| system. |
| |
| Although the Lesser General Public License is Less protective of the |
| users' freedom, it does ensure that the user of a program that is |
| linked with the Library has the freedom and the wherewithal to run |
| that program using a modified version of the Library. |
| |
| The precise terms and conditions for copying, distribution and |
| modification follow. Pay close attention to the difference between a |
| ``work based on the library'' and a ``work that uses the library''. The |
| former contains code derived from the library, whereas the latter must |
| be combined with the library in order to run. |
| |
| TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION |
| |
| 0. |
| This License Agreement applies to any software library or other program |
| which contains a notice placed by the copyright holder or other |
| authorized party saying it may be distributed under the terms of this |
| Lesser General Public License (also called ``this License''). Each |
| licensee is addressed as ``you''. |
| |
| A ``library'' means a collection of software functions and/or data |
| prepared so as to be conveniently linked with application programs |
| (which use some of those functions and data) to form executables. |
| |
| The ``Library'', below, refers to any such software library or work |
| which has been distributed under these terms. A ``work based on the |
| Library'' means either the Library or any derivative work under |
| copyright law: that is to say, a work containing the Library or a |
| portion of it, either verbatim or with modifications and/or translated |
| straightforwardly into another language. (Hereinafter, translation is |
| included without limitation in the term ``modification''.) |
| |
| ``Source code'' for a work means the preferred form of the work for |
| making modifications to it. For a library, complete source code means |
| all the source code for all modules it contains, plus any associated |
| interface definition files, plus the scripts used to control compilation |
| and installation of the library. |
| |
| Activities other than copying, distribution and modification are not |
| covered by this License; they are outside its scope. The act of |
| running a program using the Library is not restricted, and output from |
| such a program is covered only if its contents constitute a work based |
| on the Library (independent of the use of the Library in a tool for |
| writing it). Whether that is true depends on what the Library does |
| and what the program that uses the Library does. |
| |
| 1. |
| You may copy and distribute verbatim copies of the Library's |
| complete source code as you receive it, in any medium, provided that |
| you conspicuously and appropriately publish on each copy an |
| appropriate copyright notice and disclaimer of warranty; keep intact |
| all the notices that refer to this License and to the absence of any |
| warranty; and distribute a copy of this License along with the |
| Library. |
| |
| You may charge a fee for the physical act of transferring a copy, |
| and you may at your option offer warranty protection in exchange for a |
| fee. |
| |
| 2. |
| You may modify your copy or copies of the Library or any portion |
| of it, thus forming a work based on the Library, and copy and |
| distribute such modifications or work under the terms of Section 1 |
| above, provided that you also meet all of these conditions: |
| |
| a. The modified work must itself be a software library. |
| |
| b. You must cause the files modified to carry prominent notices |
| stating that you changed the files and the date of any change. |
| |
| c. You must cause the whole of the work to be licensed at no |
| charge to all third parties under the terms of this License. |
| |
| d. If a facility in the modified Library refers to a function or a |
| table of data to be supplied by an application program that uses |
| the facility, other than as an argument passed when the facility |
| is invoked, then you must make a good faith effort to ensure that, |
| in the event an application does not supply such function or |
| table, the facility still operates, and performs whatever part of |
| its purpose remains meaningful. |
| |
| (For example, a function in a library to compute square roots has |
| a purpose that is entirely well-defined independent of the |
| application. Therefore, Subsection 2d requires that any |
| application-supplied function or table used by this function must |
| be optional: if the application does not supply it, the square |
| root function must still compute square roots.) |
| @end enumerate |
| |
| These requirements apply to the modified work as a whole. If |
| identifiable sections of that work are not derived from the Library, |
| and can be reasonably considered independent and separate works in |
| themselves, then this License, and its terms, do not apply to those |
| sections when you distribute them as separate works. But when you |
| distribute the same sections as part of a whole which is a work based |
| on the Library, the distribution of the whole must be on the terms of |
| this License, whose permissions for other licensees extend to the |
| entire whole, and thus to each and every part regardless of who wrote |
| it. |
| |
| Thus, it is not the intent of this section to claim rights or contest |
| your rights to work written entirely by you; rather, the intent is to |
| exercise the right to control the distribution of derivative or |
| collective works based on the Library. |
| |
| In addition, mere aggregation of another work not based on the Library |
| with the Library (or with a work based on the Library) on a volume of |
| a storage or distribution medium does not bring the other work under |
| the scope of this License. |
| |
| 3. |
| You may opt to apply the terms of the ordinary GNU General Public |
| License instead of this License to a given copy of the Library. To do |
| this, you must alter all the notices that refer to this License, so |
| that they refer to the ordinary GNU General Public License, version 2, |
| instead of to this License. (If a newer version than version 2 of the |
| ordinary GNU General Public License has appeared, then you can specify |
| that version instead if you wish.) Do not make any other change in |
| these notices. |
| |
| Once this change is made in a given copy, it is irreversible for |
| that copy, so the ordinary GNU General Public License applies to all |
| subsequent copies and derivative works made from that copy. |
| |
| This option is useful when you wish to copy part of the code of |
| the Library into a program that is not a library. |
| |
| 4. |
| You may copy and distribute the Library (or a portion or |
| derivative of it, under Section 2) in object code or executable form |
| under the terms of Sections 1 and 2 above provided that you accompany |
| it with the complete corresponding machine-readable source code, which |
| must be distributed under the terms of Sections 1 and 2 above on a |
| medium customarily used for software interchange. |
| |
| If distribution of object code is made by offering access to copy |
| from a designated place, then offering equivalent access to copy the |
| source code from the same place satisfies the requirement to |
| distribute the source code, even though third parties are not |
| compelled to copy the source along with the object code. |
| |
| 5. |
| A program that contains no derivative of any portion of the |
| Library, but is designed to work with the Library by being compiled or |
| linked with it, is called a ``work that uses the Library''. Such a |
| work, in isolation, is not a derivative work of the Library, and |
| therefore falls outside the scope of this License. |
| |
| However, linking a ``work that uses the Library'' with the Library |
| creates an executable that is a derivative of the Library (because it |
| contains portions of the Library), rather than a ``work that uses the |
| library''. The executable is therefore covered by this License. |
| Section 6 states terms for distribution of such executables. |
| |
| When a ``work that uses the Library'' uses material from a header file |
| that is part of the Library, the object code for the work may be a |
| derivative work of the Library even though the source code is not. |
| Whether this is true is especially significant if the work can be |
| linked without the Library, or if the work is itself a library. The |
| threshold for this to be true is not precisely defined by law. |
| |
| If such an object file uses only numerical parameters, data |
| structure layouts and accessors, and small macros and small inline |
| functions (ten lines or less in length), then the use of the object |
| file is unrestricted, regardless of whether it is legally a derivative |
| work. (Executables containing this object code plus portions of the |
| Library will still fall under Section 6.) |
| |
| Otherwise, if the work is a derivative of the Library, you may |
| distribute the object code for the work under the terms of Section 6. |
| Any executables containing that work also fall under Section 6, |
| whether or not they are linked directly with the Library itself. |
| |
| 6. |
| As an exception to the Sections above, you may also combine or |
| link a ``work that uses the Library'' with the Library to produce a |
| work containing portions of the Library, and distribute that work |
| under terms of your choice, provided that the terms permit |
| modification of the work for the customer's own use and reverse |
| engineering for debugging such modifications. |
| |
| You must give prominent notice with each copy of the work that the |
| Library is used in it and that the Library and its use are covered by |
| this License. You must supply a copy of this License. If the work |
| during execution displays copyright notices, you must include the |
| copyright notice for the Library among them, as well as a reference |
| directing the user to the copy of this License. Also, you must do one |
| of these things: |
| |
| a. Accompany the work with the complete corresponding |
| machine-readable source code for the Library including whatever |
| changes were used in the work (which must be distributed under |
| Sections 1 and 2 above); and, if the work is an executable linked |
| with the Library, with the complete machine-readable ``work that |
| uses the Library'', as object code and/or source code, so that the |
| user can modify the Library and then relink to produce a modified |
| executable containing the modified Library. (It is understood |
| that the user who changes the contents of definitions files in the |
| Library will not necessarily be able to recompile the application |
| to use the modified definitions.) |
| |
| b. Use a suitable shared library mechanism for linking with the Library. A |
| suitable mechanism is one that (1) uses at run time a copy of the |
| library already present on the user's computer system, rather than |
| copying library functions into the executable, and (2) will operate |
| properly with a modified version of the library, if the user installs |
| one, as long as the modified version is interface-compatible with the |
| version that the work was made with. |
| |
| c. Accompany the work with a written offer, valid for at |
| least three years, to give the same user the materials |
| specified in Subsection 6a, above, for a charge no more |
| than the cost of performing this distribution. |
| |
| d. If distribution of the work is made by offering access to copy |
| from a designated place, offer equivalent access to copy the above |
| specified materials from the same place. |
| |
| e. Verify that the user has already received a copy of these |
| materials or that you have already sent this user a copy. |
| @end enumerate |
| |
| For an executable, the required form of the ``work that uses the |
| Library'' must include any data and utility programs needed for |
| reproducing the executable from it. However, as a special exception, |
| the materials to be distributed need not include anything that is |
| normally distributed (in either source or binary form) with the major |
| components (compiler, kernel, and so on) of the operating system on |
| which the executable runs, unless that component itself accompanies the |
| executable. |
| |
| It may happen that this requirement contradicts the license |
| restrictions of other proprietary libraries that do not normally |
| accompany the operating system. Such a contradiction means you cannot |
| use both them and the Library together in an executable that you |
| distribute. |
| |
| 7. |
| You may place library facilities that are a work based on the |
| Library side-by-side in a single library together with other library |
| facilities not covered by this License, and distribute such a combined |
| library, provided that the separate distribution of the work based on |
| the Library and of the other library facilities is otherwise |
| permitted, and provided that you do these two things: |
| |
| a. Accompany the combined library with a copy of the same work |
| based on the Library, uncombined with any other library |
| facilities. This must be distributed under the terms of the |
| Sections above. |
| |
| b. Give prominent notice with the combined library of the fact |
| that part of it is a work based on the Library, and explaining |
| where to find the accompanying uncombined form of the same work. |
| |
| 8. |
| You may not copy, modify, sublicense, link with, or distribute |
| the Library except as expressly provided under this License. Any |
| attempt otherwise to copy, modify, sublicense, link with, or |
| distribute the Library is void, and will automatically terminate your |
| rights under this License. However, parties who have received copies, |
| or rights, from you under this License will not have their licenses |
| terminated so long as such parties remain in full compliance. |
| |
| 9. |
| You are not required to accept this License, since you have not |
| signed it. However, nothing else grants you permission to modify or |
| distribute the Library or its derivative works. These actions are |
| prohibited by law if you do not accept this License. Therefore, by |
| modifying or distributing the Library (or any work based on the |
| Library), you indicate your acceptance of this License to do so, and |
| all its terms and conditions for copying, distributing or modifying |
| the Library or works based on it. |
| |
| 10. |
| Each time you redistribute the Library (or any work based on the |
| Library), the recipient automatically receives a license from the |
| original licensor to copy, distribute, link with or modify the Library |
| subject to these terms and conditions. You may not impose any further |
| restrictions on the recipients' exercise of the rights granted herein. |
| You are not responsible for enforcing compliance by third parties with |
| this License. |
| |
| 11. |
| If, as a consequence of a court judgment or allegation of patent |
| infringement or for any other reason (not limited to patent issues), |
| conditions are imposed on you (whether by court order, agreement or |
| otherwise) that contradict the conditions of this License, they do not |
| excuse you from the conditions of this License. If you cannot |
| distribute so as to satisfy simultaneously your obligations under this |
| License and any other pertinent obligations, then as a consequence you |
| may not distribute the Library at all. For example, if a patent |
| license would not permit royalty-free redistribution of the Library by |
| all those who receive copies directly or indirectly through you, then |
| the only way you could satisfy both it and this License would be to |
| refrain entirely from distribution of the Library. |
| |
| If any portion of this section is held invalid or unenforceable under any |
| particular circumstance, the balance of the section is intended to apply, |
| and the section as a whole is intended to apply in other circumstances. |
| |
| It is not the purpose of this section to induce you to infringe any |
| patents or other property right claims or to contest validity of any |
| such claims; this section has the sole purpose of protecting the |
| integrity of the free software distribution system which is |
| implemented by public license practices. Many people have made |
| generous contributions to the wide range of software distributed |
| through that system in reliance on consistent application of that |
| system; it is up to the author/donor to decide if he or she is willing |
| to distribute software through any other system and a licensee cannot |
| impose that choice. |
| |
| This section is intended to make thoroughly clear what is believed to |
| be a consequence of the rest of this License. |
| |
| 12. |
| If the distribution and/or use of the Library is restricted in |
| certain countries either by patents or by copyrighted interfaces, the |
| original copyright holder who places the Library under this License may add |
| an explicit geographical distribution limitation excluding those countries, |
| so that distribution is permitted only in or among countries not thus |
| excluded. In such case, this License incorporates the limitation as if |
| written in the body of this License. |
| |
| 13. |
| The Free Software Foundation may publish revised and/or new |
| versions of the Lesser General Public License from time to time. |
| Such new versions will be similar in spirit to the present version, |
| but may differ in detail to address new problems or concerns. |
| |
| Each version is given a distinguishing version number. If the Library |
| specifies a version number of this License which applies to it and |
| ``any later version'', you have the option of following the terms and |
| conditions either of that version or of any later version published by |
| the Free Software Foundation. If the Library does not specify a |
| license version number, you may choose any version ever published by |
| the Free Software Foundation. |
| |
| 14. |
| If you wish to incorporate parts of the Library into other free |
| programs whose distribution conditions are incompatible with these, |
| write to the author to ask for permission. For software which is |
| copyrighted by the Free Software Foundation, write to the Free |
| Software Foundation; we sometimes make exceptions for this. Our |
| decision will be guided by the two goals of preserving the free status |
| of all derivatives of our free software and of promoting the sharing |
| and reuse of software generally. |
| |
| NO WARRANTY |
| |
| 15. |
| BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO |
| WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. |
| EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR |
| OTHER PARTIES PROVIDE THE LIBRARY ``AS IS'' WITHOUT WARRANTY OF ANY |
| KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE |
| IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR |
| PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE |
| LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME |
| THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. |
| |
| 16. |
| IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN |
| WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY |
| AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU |
| FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR |
| CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE |
| LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING |
| RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A |
| FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF |
| SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH |
| DAMAGES. |
| |
| END OF TERMS AND CONDITIONS |
| |
| How to Apply These Terms to Your New Libraries |
| |
| If you develop a new library, and you want it to be of the greatest |
| possible use to the public, we recommend making it free software that |
| everyone can redistribute and change. You can do so by permitting |
| redistribution under these terms (or, alternatively, under the terms of the |
| ordinary General Public License). |
| |
| To apply these terms, attach the following notices to the library. It is |
| safest to attach them to the start of each source file to most effectively |
| convey the exclusion of warranty; and each file should have at least the |
| ``copyright'' line and a pointer to where the full notice is found. |
| |
| one line to give the library's name and an idea of what it does. |
| Copyright (C) year name of author |
| |
| This library is free software; you can redistribute it and/or modify it |
| under the terms of the GNU Lesser General Public License as published by |
| the Free Software Foundation; either version 2.1 of the License, or (at |
| your option) any later version. |
| |
| This library is distributed in the hope that it will be useful, but |
| WITHOUT ANY WARRANTY; without even the implied warranty of |
| MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
| Lesser General Public License for more details. |
| |
| You should have received a copy of the GNU Lesser General Public |
| License along with this library; if not, write to the Free Software |
| Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, |
| USA. |
| |
| Also add information on how to contact you by electronic and paper mail. |
| |
| You should also get your employer (if you work as a programmer) or your |
| school, if any, to sign a ``copyright disclaimer'' for the library, if |
| necessary. Here is a sample; alter the names: |
| |
| Yoyodyne, Inc., hereby disclaims all copyright interest in the library |
| `Frob' (a library for tweaking knobs) written by James Random Hacker. |
| |
| signature of Ty Coon, 1 April 1990 |
| Ty Coon, President of Vice |
| |
| That's all there is to it! |
| |
| ==================================================================================================== |
| |
| GNU Free Documentation License |
| |
| Version 1.1, March 2000 |
| |
| Copyright @copyright{} 2000 Free Software Foundation, Inc. |
| 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA |
| |
| Everyone is permitted to copy and distribute verbatim copies |
| of this license document, but changing it is not allowed. |
| @end display |
| |
| 0. |
| PREAMBLE |
| |
| The purpose of this License is to make a manual, textbook, or other |
| written document @dfn{free} in the sense of freedom: to assure everyone |
| the effective freedom to copy and redistribute it, with or without |
| modifying it, either commercially or noncommercially. Secondarily, |
| this License preserves for the author and publisher a way to get |
| credit for their work, while not being considered responsible for |
| modifications made by others. |
| |
| This License is a kind of ``copyleft'', which means that derivative |
| works of the document must themselves be free in the same sense. It |
| complements the GNU General Public License, which is a copyleft |
| license designed for free software. |
| |
| We have designed this License in order to use it for manuals for free |
| software, because free software needs free documentation: a free |
| program should come with manuals providing the same freedoms that the |
| software does. But this License is not limited to software manuals; |
| it can be used for any textual work, regardless of subject matter or |
| whether it is published as a printed book. We recommend this License |
| principally for works whose purpose is instruction or reference. |
| |
| 1. |
| APPLICABILITY AND DEFINITIONS |
| |
| This License applies to any manual or other work that contains a |
| notice placed by the copyright holder saying it can be distributed |
| under the terms of this License. The ``Document'', below, refers to any |
| such manual or work. Any member of the public is a licensee, and is |
| addressed as ``you''. |
| |
| A ``Modified Version'' of the Document means any work containing the |
| Document or a portion of it, either copied verbatim, or with |
| modifications and/or translated into another language. |
| |
| A ``Secondary Section'' is a named appendix or a front-matter section of |
| the Document that deals exclusively with the relationship of the |
| publishers or authors of the Document to the Document's overall subject |
| (or to related matters) and contains nothing that could fall directly |
| within that overall subject. (For example, if the Document is in part a |
| textbook of mathematics, a Secondary Section may not explain any |
| mathematics.) The relationship could be a matter of historical |
| connection with the subject or with related matters, or of legal, |
| commercial, philosophical, ethical or political position regarding |
| them. |
| |
| The ``Invariant Sections'' are certain Secondary Sections whose titles |
| are designated, as being those of Invariant Sections, in the notice |
| that says that the Document is released under this License. |
| |
| The ``Cover Texts'' are certain short passages of text that are listed, |
| as Front-Cover Texts or Back-Cover Texts, in the notice that says that |
| the Document is released under this License. |
| |
| A ``Transparent'' copy of the Document means a machine-readable copy, |
| represented in a format whose specification is available to the |
| general public, whose contents can be viewed and edited directly and |
| straightforwardly with generic text editors or (for images composed of |
| pixels) generic paint programs or (for drawings) some widely available |
| drawing editor, and that is suitable for input to text formatters or |
| for automatic translation to a variety of formats suitable for input |
| to text formatters. A copy made in an otherwise Transparent file |
| format whose markup has been designed to thwart or discourage |
| subsequent modification by readers is not Transparent. A copy that is |
| not ``Transparent'' is called ``Opaque''. |
| |
| Examples of suitable formats for Transparent copies include plain |
| @sc{ascii} without markup, Texinfo input format, La@TeX{} input format, |
| @acronym{SGML} or @acronym{XML} using a publicly available |
| @acronym{DTD}, and standard-conforming simple @acronym{HTML} designed |
| for human modification. Opaque formats include PostScript, |
| @acronym{PDF}, proprietary formats that can be read and edited only by |
| proprietary word processors, @acronym{SGML} or @acronym{XML} for which |
| the @acronym{DTD} and/or processing tools are not generally available, |
| and the machine-generated @acronym{HTML} produced by some word |
| processors for output purposes only. |
| |
| The ``Title Page'' means, for a printed book, the title page itself, |
| plus such following pages as are needed to hold, legibly, the material |
| this License requires to appear in the title page. For works in |
| formats which do not have any title page as such, ``Title Page'' means |
| the text near the most prominent appearance of the work's title, |
| preceding the beginning of the body of the text. |
| |
| 2. |
| VERBATIM COPYING |
| |
| You may copy and distribute the Document in any medium, either |
| commercially or noncommercially, provided that this License, the |
| copyright notices, and the license notice saying this License applies |
| to the Document are reproduced in all copies, and that you add no other |
| conditions whatsoever to those of this License. You may not use |
| technical measures to obstruct or control the reading or further |
| copying of the copies you make or distribute. However, you may accept |
| compensation in exchange for copies. If you distribute a large enough |
| number of copies you must also follow the conditions in section 3. |
| |
| You may also lend copies, under the same conditions stated above, and |
| you may publicly display copies. |
| |
| 3. |
| COPYING IN QUANTITY |
| |
| If you publish printed copies of the Document numbering more than 100, |
| and the Document's license notice requires Cover Texts, you must enclose |
| the copies in covers that carry, clearly and legibly, all these Cover |
| Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on |
| the back cover. Both covers must also clearly and legibly identify |
| you as the publisher of these copies. The front cover must present |
| the full title with all words of the title equally prominent and |
| visible. You may add other material on the covers in addition. |
| Copying with changes limited to the covers, as long as they preserve |
| the title of the Document and satisfy these conditions, can be treated |
| as verbatim copying in other respects. |
| |
| If the required texts for either cover are too voluminous to fit |
| legibly, you should put the first ones listed (as many as fit |
| reasonably) on the actual cover, and continue the rest onto adjacent |
| pages. |
| |
| If you publish or distribute Opaque copies of the Document numbering |
| more than 100, you must either include a machine-readable Transparent |
| copy along with each Opaque copy, or state in or with each Opaque copy |
| a publicly-accessible computer-network location containing a complete |
| Transparent copy of the Document, free of added material, which the |
| general network-using public has access to download anonymously at no |
| charge using public-standard network protocols. If you use the latter |
| option, you must take reasonably prudent steps, when you begin |
| distribution of Opaque copies in quantity, to ensure that this |
| Transparent copy will remain thus accessible at the stated location |
| until at least one year after the last time you distribute an Opaque |
| copy (directly or through your agents or retailers) of that edition to |
| the public. |
| |
| It is requested, but not required, that you contact the authors of the |
| Document well before redistributing any large number of copies, to give |
| them a chance to provide you with an updated version of the Document. |
| |
| 4. |
| MODIFICATIONS |
| |
| You may copy and distribute a Modified Version of the Document under |
| the conditions of sections 2 and 3 above, provided that you release |
| the Modified Version under precisely this License, with the Modified |
| Version filling the role of the Document, thus licensing distribution |
| and modification of the Modified Version to whoever possesses a copy |
| of it. In addition, you must do these things in the Modified Version: |
| |
| A. |
| Use in the Title Page (and on the covers, if any) a title distinct |
| from that of the Document, and from those of previous versions |
| (which should, if there were any, be listed in the History section |
| of the Document). You may use the same title as a previous version |
| if the original publisher of that version gives permission. |
| |
| B. |
| List on the Title Page, as authors, one or more persons or entities |
| responsible for authorship of the modifications in the Modified |
| Version, together with at least five of the principal authors of the |
| Document (all of its principal authors, if it has less than five). |
| |
| C. |
| State on the Title page the name of the publisher of the |
| Modified Version, as the publisher. |
| |
| D. |
| Preserve all the copyright notices of the Document. |
| |
| E. |
| Add an appropriate copyright notice for your modifications |
| adjacent to the other copyright notices. |
| |
| F. |
| Include, immediately after the copyright notices, a license notice |
| giving the public permission to use the Modified Version under the |
| terms of this License, in the form shown in the Addendum below. |
| |
| G. |
| Preserve in that license notice the full lists of Invariant Sections |
| and required Cover Texts given in the Document's license notice. |
| |
| H. |
| Include an unaltered copy of this License. |
| |
| I. |
| Preserve the section entitled ``History'', and its title, and add to |
| it an item stating at least the title, year, new authors, and |
| publisher of the Modified Version as given on the Title Page. If |
| there is no section entitled ``History'' in the Document, create one |
| stating the title, year, authors, and publisher of the Document as |
| given on its Title Page, then add an item describing the Modified |
| Version as stated in the previous sentence. |
| |
| J. |
| Preserve the network location, if any, given in the Document for |
| public access to a Transparent copy of the Document, and likewise |
| the network locations given in the Document for previous versions |
| it was based on. These may be placed in the ``History'' section. |
| You may omit a network location for a work that was published at |
| least four years before the Document itself, or if the original |
| publisher of the version it refers to gives permission. |
| |
| K. |
| In any section entitled ``Acknowledgments'' or ``Dedications'', |
| preserve the section's title, and preserve in the section all the |
| substance and tone of each of the contributor acknowledgments |
| and/or dedications given therein. |
| |
| L. |
| Preserve all the Invariant Sections of the Document, |
| unaltered in their text and in their titles. Section numbers |
| or the equivalent are not considered part of the section titles. |
| |
| M. |
| Delete any section entitled ``Endorsements''. Such a section |
| may not be included in the Modified Version. |
| |
| N. |
| Do not retitle any existing section as ``Endorsements'' |
| or to conflict in title with any Invariant Section. |
| |
| If the Modified Version includes new front-matter sections or |
| appendices that qualify as Secondary Sections and contain no material |
| copied from the Document, you may at your option designate some or all |
| of these sections as invariant. To do this, add their titles to the |
| list of Invariant Sections in the Modified Version's license notice. |
| These titles must be distinct from any other section titles. |
| |
| You may add a section entitled ``Endorsements'', provided it contains |
| nothing but endorsements of your Modified Version by various |
| parties---for example, statements of peer review or that the text has |
| been approved by an organization as the authoritative definition of a |
| standard. |
| |
| You may add a passage of up to five words as a Front-Cover Text, and a |
| passage of up to 25 words as a Back-Cover Text, to the end of the list |
| of Cover Texts in the Modified Version. Only one passage of |
| Front-Cover Text and one of Back-Cover Text may be added by (or |
| through arrangements made by) any one entity. If the Document already |
| includes a cover text for the same cover, previously added by you or |
| by arrangement made by the same entity you are acting on behalf of, |
| you may not add another; but you may replace the old one, on explicit |
| permission from the previous publisher that added the old one. |
| |
| The author(s) and publisher(s) of the Document do not by this License |
| give permission to use their names for publicity for or to assert or |
| imply endorsement of any Modified Version. |
| |
| 5. |
| COMBINING DOCUMENTS |
| |
| You may combine the Document with other documents released under this |
| License, under the terms defined in section 4 above for modified |
| versions, provided that you include in the combination all of the |
| Invariant Sections of all of the original documents, unmodified, and |
| list them all as Invariant Sections of your combined work in its |
| license notice. |
| |
| The combined work need only contain one copy of this License, and |
| multiple identical Invariant Sections may be replaced with a single |
| copy. If there are multiple Invariant Sections with the same name but |
| different contents, make the title of each such section unique by |
| adding at the end of it, in parentheses, the name of the original |
| author or publisher of that section if known, or else a unique number. |
| Make the same adjustment to the section titles in the list of |
| Invariant Sections in the license notice of the combined work. |
| |
| In the combination, you must combine any sections entitled ``History'' |
| in the various original documents, forming one section entitled |
| ``History''; likewise combine any sections entitled ``Acknowledgments'', |
| and any sections entitled ``Dedications''. You must delete all sections |
| entitled ``Endorsements.'' |
| |
| 6. |
| COLLECTIONS OF DOCUMENTS |
| |
| You may make a collection consisting of the Document and other documents |
| released under this License, and replace the individual copies of this |
| License in the various documents with a single copy that is included in |
| the collection, provided that you follow the rules of this License for |
| verbatim copying of each of the documents in all other respects. |
| |
| You may extract a single document from such a collection, and distribute |
| it individually under this License, provided you insert a copy of this |
| License into the extracted document, and follow this License in all |
| other respects regarding verbatim copying of that document. |
| |
| 7. |
| AGGREGATION WITH INDEPENDENT WORKS |
| |
| A compilation of the Document or its derivatives with other separate |
| and independent documents or works, in or on a volume of a storage or |
| distribution medium, does not as a whole count as a Modified Version |
| of the Document, provided no compilation copyright is claimed for the |
| compilation. Such a compilation is called an ``aggregate'', and this |
| License does not apply to the other self-contained works thus compiled |
| with the Document, on account of their being thus compiled, if they |
| are not themselves derivative works of the Document. |
| |
| If the Cover Text requirement of section 3 is applicable to these |
| copies of the Document, then if the Document is less than one quarter |
| of the entire aggregate, the Document's Cover Texts may be placed on |
| covers that surround only the Document within the aggregate. |
| Otherwise they must appear on covers around the whole aggregate. |
| |
| 8. |
| TRANSLATION |
| |
| Translation is considered a kind of modification, so you may |
| distribute translations of the Document under the terms of section 4. |
| Replacing Invariant Sections with translations requires special |
| permission from their copyright holders, but you may include |
| translations of some or all Invariant Sections in addition to the |
| original versions of these Invariant Sections. You may include a |
| translation of this License provided that you also include the |
| original English version of this License. In case of a disagreement |
| between the translation and the original English version of this |
| License, the original English version will prevail. |
| |
| 9. |
| TERMINATION |
| |
| You may not copy, modify, sublicense, or distribute the Document except |
| as expressly provided for under this License. Any other attempt to |
| copy, modify, sublicense or distribute the Document is void, and will |
| automatically terminate your rights under this License. However, |
| parties who have received copies, or rights, from you under this |
| License will not have their licenses terminated so long as such |
| parties remain in full compliance. |
| |
| 10. |
| FUTURE REVISIONS OF THIS LICENSE |
| |
| The Free Software Foundation may publish new, revised versions |
| of the GNU Free Documentation License from time to time. Such new |
| versions will be similar in spirit to the present version, but may |
| differ in detail to address new problems or concerns. See |
| @uref{http://www.gnu.org/copyleft/}. |
| |
| Each version of the License is given a distinguishing version number. |
| If the Document specifies that a particular numbered version of this |
| License ``or any later version'' applies to it, you have the option of |
| following the terms and conditions either of that specified version or |
| of any later version that has been published (not as a draft) by the |
| Free Software Foundation. If the Document does not specify a version |
| number of this License, you may choose any version ever published (not |
| as a draft) by the Free Software Foundation. |
| @end enumerate |
| |
| ADDENDUM: How to use this License for your documents |
| |
| To use this License in a document you have written, include a copy of |
| the License in the document and put the following copyright and |
| license notices just after the title page: |
| |
| Copyright (C) year your name. |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version 1.1 |
| or any later version published by the Free Software Foundation; |
| with the Invariant Sections being @var{list their titles}, with the |
| Front-Cover Texts being @var{list}, and with the Back-Cover Texts being @var{list}. |
| A copy of the license is included in the section entitled ``GNU |
| Free Documentation License''. |
| |
| If you have no Invariant Sections, write ``with no Invariant Sections'' |
| instead of saying which ones are invariant. If you have no |
| Front-Cover Texts, write ``no Front-Cover Texts'' instead of |
| ``Front-Cover Texts being @var{list}''; likewise for Back-Cover Texts. |
| |
| If your document contains nontrivial examples of program code, we |
| recommend releasing these examples in parallel under your choice of |
| free software license, such as the GNU General Public License, |
| to permit their use in free software. |
| |
| ======================================================================================== |
| |
| A transparent copy of this modified document can be found along-side the binary .libhover file |
| in the org.eclipse.cdt.libhover.glibc plug-in jar under the data directory. The plug-in can be |
| unzipped via "unzip". The original un-modified document can be generated from the sources which |
| can be found at: http://ftp.gnu.org/gnu/glibc/glibc-2.14.tar.gz |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getpass" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="const char *prompt"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| <br><br> <CODE>getpass</CODE> outputs <VAR>prompt</VAR>, then reads a string in from the |
| terminal without echoing it. It tries to connect to the real terminal, |
| <TT>/dev/tty</TT>, if possible, to encourage users not to put plaintext |
| passwords in files; otherwise, it uses <CODE>stdin</CODE> and <CODE>stderr</CODE>. |
| <CODE>getpass</CODE> also disables the INTR, QUIT, and SUSP characters on the |
| terminal using the <CODE>ISIG</CODE> terminal attribute . |
| The terminal is flushed before and after <CODE>getpass</CODE>, so that |
| characters of a mistyped password are not accidentally visible. |
| <br><br> In other C libraries, <CODE>getpass</CODE> may only return the first |
| <CODE>PASS_MAX</CODE> bytes of a password. The GNU C library has no limit, so |
| <CODE>PASS_MAX</CODE> is undefined. |
| <br><br> The prototype for this function is in <TT>unistd.h</TT>. <CODE>PASS_MAX</CODE> |
| would be defined in <TT>limits.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-crypt" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="const char *key"/> |
| <parameter content="const char *salt"/> |
| </prototype> |
| <headers> |
| <header filename = "crypt.h"/> |
| </headers> |
| <synopsis> |
| <br><br> The <CODE>crypt</CODE> function takes a password, <VAR>key</VAR>, as a string, and |
| a <VAR>salt</VAR> character array which is described below, and returns a |
| printable ASCII string which starts with another salt. It is believed |
| that, given the output of the function, the best way to find a <VAR>key</VAR> |
| that will produce that output is to guess values of <VAR>key</VAR> until the |
| original value of <VAR>key</VAR> is found. |
| <br><br> The <VAR>salt</VAR> parameter does two things. Firstly, it selects which |
| algorithm is used, the MD5-based one or the DES-based one. Secondly, it |
| makes life harder for someone trying to guess passwords against a file |
| containing many passwords; without a <VAR>salt</VAR>, an intruder can make a |
| guess, run <CODE>crypt</CODE> on it once, and compare the result with all the |
| passwords. With a <VAR>salt</VAR>, the intruder must run <CODE>crypt</CODE> once |
| for each different salt. |
| <br><br> For the MD5-based algorithm, the <VAR>salt</VAR> should consist of the string |
| <CODE>$1$</CODE>, followed by up to 8 characters, terminated by either |
| another <CODE>$</CODE> or the end of the string. The result of <CODE>crypt</CODE> |
| will be the <VAR>salt</VAR>, followed by a <CODE>$</CODE> if the salt didn't end |
| with one, followed by 22 characters from the alphabet |
| <CODE>./0-9A-Za-z</CODE>, up to 34 characters total. Every character in the |
| <VAR>key</VAR> is significant. |
| <br><br> For the DES-based algorithm, the <VAR>salt</VAR> should consist of two |
| characters from the alphabet <CODE>./0-9A-Za-z</CODE>, and the result of |
| <CODE>crypt</CODE> will be those two characters followed by 11 more from the |
| same alphabet, 13 in total. Only the first 8 characters in the |
| <VAR>key</VAR> are significant. |
| <br><br> The MD5-based algorithm has no limit on the useful length of the |
| password used, and is slightly more secure. It is therefore preferred |
| over the DES-based algorithm. |
| <br><br> When the user enters their password for the first time, the <VAR>salt</VAR> |
| should be set to a new string which is reasonably random. To verify a |
| password against the result of a previous call to <CODE>crypt</CODE>, pass |
| the result of the previous call as the <VAR>salt</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-crypt_r" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="const char *key"/> |
| <parameter content="const char *salt"/> |
| <parameter content="{struct crypt_data *} data"/> |
| </prototype> |
| <headers> |
| <header filename = "crypt.h"/> |
| </headers> |
| <synopsis> |
| <br><br> The <CODE>crypt_r</CODE> function does the same thing as <CODE>crypt</CODE>, but |
| takes an extra parameter which includes space for its result (among |
| other things), so it can be reentrant. <CODE>data-></CODE>initialized must be |
| cleared to zero before the first time <CODE>crypt_r</CODE> is called. |
| <br><br> The <CODE>crypt_r</CODE> function is a GNU extension. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-setkey" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="const char *key"/> |
| </prototype> |
| <headers> |
| <header filename = "crypt.h"/> |
| </headers> |
| <synopsis> |
| <br><br> The <CODE>setkey</CODE> function sets an internal data structure to be an |
| expanded form of <VAR>key</VAR>. <VAR>key</VAR> is specified as an array of 64 |
| bits each stored in a <CODE>char</CODE>, the first bit is <CODE>key[0]</CODE> and |
| the 64th bit is <CODE>key[63]</CODE>. The <VAR>key</VAR> should have the correct |
| parity. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-encrypt" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="char *block"/> |
| <parameter content="int edflag"/> |
| </prototype> |
| <headers> |
| <header filename = "crypt.h"/> |
| </headers> |
| <synopsis> |
| <br><br> The <CODE>encrypt</CODE> function encrypts <VAR>block</VAR> if |
| <VAR>edflag</VAR> is 0, otherwise it decrypts <VAR>block</VAR>, using a key |
| previously set by <CODE>setkey</CODE>. The result is |
| placed in <VAR>block</VAR>. |
| <br><br> Like <CODE>setkey</CODE>, <VAR>block</VAR> is specified as an array of 64 bits each |
| stored in a <CODE>char</CODE>, but there are no parity bits in <VAR>block</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-setkey_r" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="const char *key"/> |
| <parameter content="{struct crypt_data *} data"/> |
| </prototype> |
| <headers> |
| <header filename = "crypt.h"/> |
| </headers> |
| <synopsis> |
| <br><br> These are reentrant versions of <CODE>setkey</CODE> and <CODE>encrypt</CODE>. The |
| only difference is the extra parameter, which stores the expanded |
| version of <VAR>key</VAR>. Before calling <CODE>setkey_r</CODE> the first time, |
| <CODE>data->initialized</CODE> must be cleared to zero. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-encrypt_r" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="char *block"/> |
| <parameter content="int edflag"/> |
| <parameter content="{struct crypt_data *} data"/> |
| </prototype> |
| <headers> |
| <header filename = "crypt.h"/> |
| </headers> |
| <synopsis> |
| <br><br> These are reentrant versions of <CODE>setkey</CODE> and <CODE>encrypt</CODE>. The |
| only difference is the extra parameter, which stores the expanded |
| version of <VAR>key</VAR>. Before calling <CODE>setkey_r</CODE> the first time, |
| <CODE>data->initialized</CODE> must be cleared to zero. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-ecb_crypt" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="char *key"/> |
| <parameter content="char *blocks"/> |
| <parameter content="unsigned len"/> |
| <parameter content="unsigned mode"/> |
| </prototype> |
| <headers> |
| <header filename = "rpc/des_crypt.h"/> |
| </headers> |
| <synopsis> |
| <br><br> The function <CODE>ecb_crypt</CODE> encrypts or decrypts one or more blocks |
| using DES. Each block is encrypted independently. |
| <br><br> The <VAR>blocks</VAR> and the <VAR>key</VAR> are stored packed in 8-bit bytes, so |
| that the first bit of the key is the most-significant bit of |
| <CODE>key[0]</CODE> and the 63rd bit of the key is stored as the |
| least-significant bit of <CODE>key[7]</CODE>. The <VAR>key</VAR> should have the |
| correct parity. |
| <br><br> <VAR>len</VAR> is the number of bytes in <VAR>blocks</VAR>. It should be a |
| multiple of 8 (so that there is a whole number of blocks to encrypt). |
| <VAR>len</VAR> is limited to a maximum of <CODE>DES_MAXDATA</CODE> bytes. |
| <br><br> The result of the encryption replaces the input in <VAR>blocks</VAR>. |
| <br><br> The <VAR>mode</VAR> parameter is the bitwise OR of two of the following: |
| <br><br> <DL> |
| |
| <DT><CODE>DES_ENCRYPT</CODE> |
| <DD> |
| This constant, used in the <VAR>mode</VAR> parameter, specifies that |
| <VAR>blocks</VAR> is to be encrypted. |
| <br><br> <DT><CODE>DES_DECRYPT</CODE> |
| <DD> |
| This constant, used in the <VAR>mode</VAR> parameter, specifies that |
| <VAR>blocks</VAR> is to be decrypted. |
| <br><br> <DT><CODE>DES_HW</CODE> |
| <DD> |
| This constant, used in the <VAR>mode</VAR> parameter, asks to use a hardware |
| device. If no hardware device is available, encryption happens anyway, |
| but in software. |
| <br><br> <DT><CODE>DES_SW</CODE> |
| <DD> |
| This constant, used in the <VAR>mode</VAR> parameter, specifies that no |
| hardware device is to be used. |
| </DL> |
| <br><br> The result of the function will be one of these values: |
| <br><br> <DL> |
| |
| <DT><CODE>DESERR_NONE</CODE> |
| <DD> |
| The encryption succeeded. |
| <br><br> <DT><CODE>DESERR_NOHWDEVICE</CODE> |
| <DD> |
| The encryption succeeded, but there was no hardware device available. |
| <br><br> <DT><CODE>DESERR_HWERROR</CODE> |
| <DD> |
| The encryption failed because of a hardware problem. |
| <br><br> <DT><CODE>DESERR_BADPARAM</CODE> |
| <DD> |
| The encryption failed because of a bad parameter, for instance <VAR>len</VAR> |
| is not a multiple of 8 or <VAR>len</VAR> is larger than <CODE>DES_MAXDATA</CODE>. |
| </DL> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-DES_FAILED" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int err"/> |
| </prototype> |
| <headers> |
| <header filename = "rpc/des_crypt.h"/> |
| </headers> |
| <synopsis> |
| This macro returns 1 if <VAR>err</VAR> is a `success' result code from |
| <CODE>ecb_crypt</CODE> or <CODE>cbc_crypt</CODE>, and 0 otherwise. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-cbc_crypt" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="char *key"/> |
| <parameter content="char *blocks"/> |
| <parameter content="unsigned len"/> |
| <parameter content="unsigned mode"/> |
| <parameter content="char *ivec"/> |
| </prototype> |
| <headers> |
| <header filename = "rpc/des_crypt.h"/> |
| </headers> |
| <synopsis> |
| <br><br> The function <CODE>cbc_crypt</CODE> encrypts or decrypts one or more blocks |
| using DES in Cipher Block Chaining mode. |
| <br><br> For encryption in CBC mode, each block is exclusive-ored with <VAR>ivec</VAR> |
| before being encrypted, then <VAR>ivec</VAR> is replaced with the result of |
| the encryption, then the next block is processed. Decryption is the |
| reverse of this process. |
| <br><br> This has the advantage that blocks which are the same before being |
| encrypted are very unlikely to be the same after being encrypted, making |
| it much harder to detect patterns in the data. |
| <br><br> Usually, <VAR>ivec</VAR> is set to 8 random bytes before encryption starts. |
| Then the 8 random bytes are transmitted along with the encrypted data |
| (without themselves being encrypted), and passed back in as <VAR>ivec</VAR> |
| for decryption. Another possibility is to set <VAR>ivec</VAR> to 8 zeroes |
| initially, and have the first the block encrypted consist of 8 random |
| bytes. |
| <br><br> Otherwise, all the parameters are similar to those for <CODE>ecb_crypt</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-des_setparity" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="char *key"/> |
| </prototype> |
| <headers> |
| <header filename = "rpc/des_crypt.h"/> |
| </headers> |
| <synopsis> |
| <br><br> The function <CODE>des_setparity</CODE> changes the 64-bit <VAR>key</VAR>, stored |
| packed in 8-bit bytes, to have odd parity by altering the low bits of |
| each byte. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-gethostname" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="char *name"/> |
| <parameter content="size_t size"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| This function returns the host name of the system on which it is called, |
| in the array <VAR>name</VAR>. The <VAR>size</VAR> argument specifies the size of |
| this array, in bytes. Note that this is <EM>not</EM> the DNS hostname. |
| If the system participates in DNS, this is the FQDN (see above). |
| <br><br> The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on failure. In |
| the GNU C library, <CODE>gethostname</CODE> fails if <VAR>size</VAR> is not large |
| enough; then you can try again with a larger array. The following |
| <CODE>errno</CODE> error condition is defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>ENAMETOOLONG</CODE> |
| <DD> |
| The <VAR>size</VAR> argument is less than the size of the host name plus one. |
| |
| <br><br> On some systems, there is a symbol for the maximum possible host name |
| length: <CODE>MAXHOSTNAMELEN</CODE>. It is defined in <TT>sys/param.h</TT>. |
| But you can't count on this to exist, so it is cleaner to handle |
| failure and try again. |
| <br><br> <CODE>gethostname</CODE> stores the beginning of the host name in <VAR>name</VAR> |
| even if the host name won't entirely fit. For some purposes, a |
| truncated host name is good enough. If it is, you can ignore the |
| error code. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-sethostname" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *name"/> |
| <parameter content="size_t length"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>sethostname</CODE> function sets the host name of the system that |
| calls it to <VAR>name</VAR>, a string with length <VAR>length</VAR>. Only |
| privileged processes are permitted to do this. |
| <br><br> Usually <CODE>sethostname</CODE> gets called just once, at system boot time. |
| Often, the program that calls it sets it to the value it finds in the |
| file <CODE>/etc/hostname</CODE>. |
| /etc/hostname |
| <br><br> Be sure to set the host name to the full host name, not just the DNS |
| hostname (see above). |
| <br><br> The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on failure. |
| The following <CODE>errno</CODE> error condition is defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EPERM</CODE> |
| <DD> |
| This process cannot set the host name because it is not privileged. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getdomainnname" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="char *name"/> |
| <parameter content="size_t length"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| domain name |
| domain name |
| <br><br> <CODE>getdomainname</CODE> returns the NIS (aka YP) domain name of the system |
| on which it is called. Note that this is not the more popular DNS |
| domain name. Get that with <CODE>gethostname</CODE>. |
| <br><br> The specifics of this function are analogous to <CODE>gethostname</CODE>, above. |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-setdomainname" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *name"/> |
| <parameter content="size_t length"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| domain name |
| domain name |
| <br><br> <CODE>getdomainname</CODE> sets the NIS (aka YP) domain name of the system |
| on which it is called. Note that this is not the more popular DNS |
| domain name. Set that with <CODE>sethostname</CODE>. |
| <br><br> The specifics of this function are analogous to <CODE>sethostname</CODE>, above. |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-gethostid" type="function"> |
| <function returntype="long int"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| This function returns the ``host ID'' of the machine the program is |
| running on. By convention, this is usually the primary Internet IP address |
| of that machine, converted to a <CODE>long int</CODE>. However, on some |
| systems it is a meaningless but unique number which is hard-coded for |
| each machine. |
| <br><br> This is not widely used. It arose in BSD 4.2, but was dropped in BSD 4.4. |
| It is not required by POSIX. |
| <br><br> The proper way to query the IP address is to use <CODE>gethostbyname</CODE> |
| on the results of <CODE>gethostname</CODE>. For more information on IP addresses, |
| . |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-sethostid" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="long int id"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>sethostid</CODE> function sets the ``host ID'' of the host machine |
| to <VAR>id</VAR>. Only privileged processes are permitted to do this. Usually |
| it happens just once, at system boot time. |
| <br><br> The proper way to establish the primary IP address of a system |
| is to configure the IP address resolver to associate that IP address with |
| the system's host name as returned by <CODE>gethostname</CODE>. For example, |
| put a record for the system in <TT>/etc/hosts</TT>. |
| <br><br> See <CODE>gethostid</CODE> above for more information on host ids. |
| <br><br> The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on failure. |
| The following <CODE>errno</CODE> error conditions are defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EPERM</CODE> |
| <DD> |
| This process cannot set the host name because it is not privileged. |
| <br><br> <LI> ENOSYS |
| The operating system does not support setting the host ID. On some |
| systems, the host ID is a meaningless but unique number hard-coded for |
| each machine. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="struct-utsname" type="struct"> |
| <structure> |
| <synopsis> |
| The <CODE>utsname</CODE> structure is used to hold information returned |
| by the <CODE>uname</CODE> function. It has the following members: |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="char sysname[]"> |
| <synopsis> |
| This is the name of the operating system in use. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="char release[]"> |
| <synopsis> |
| This is the current release level of the operating system implementation. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="char version[]"> |
| <synopsis> |
| This is the current version level within the release of the operating |
| system. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="char machine[]"> |
| <synopsis> |
| This is a description of the type of hardware that is in use. |
| <br><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><br> GNU uses a three-part name to describe a system configuration; the three |
| parts are <VAR>cpu</VAR>, <VAR>manufacturer</VAR> and <VAR>system-type</VAR>, 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><br> Since the value in <CODE>machine</CODE> is supposed to describe just the |
| hardware, it consists of the first two parts of the configuration name: |
| <samp><VAR>cpu</VAR>-<VAR>manufacturer</VAR></samp>. For example, it might be one of these: |
| <br><br> |
| <CODE>"sparc-sun"</CODE>, |
| <CODE>"i386-<VAR>anything</VAR>"</CODE>, |
| <CODE>"m68k-hp"</CODE>, |
| <CODE>"m68k-sony"</CODE>, |
| <CODE>"m68k-sun"</CODE>, |
| <CODE>"mips-dec"</CODE> |
| |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="char nodename[]"> |
| <synopsis> |
| This is the host name of this particular computer. In the GNU C |
| library, the value is the same as that returned by <CODE>gethostname</CODE>; |
| see Host Identification. |
| <br><br> @ gethostname() is implemented with a call to uname(). |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="function-uname" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="struct utsname *info"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/utsname.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>uname</CODE> function fills in the structure pointed to by |
| <VAR>info</VAR> with information about the operating system and host machine. |
| A non-negative value indicates that the data was successfully stored. |
| <br><br> <CODE>-1</CODE> as the value indicates an error. The only error possible is |
| <CODE>EFAULT</CODE>, which we normally don't mention as it is always a |
| possibility. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="struct-fstab" type="struct"> |
| <structure> |
| <synopsis> |
| This structure is used with the <CODE>getfsent</CODE>, <CODE>getfsspec</CODE>, and |
| <CODE>getfsfile</CODE> functions. |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="char *fs_spec"> |
| <synopsis> |
| This element describes the device from which the filesystem is mounted. |
| Normally this is the name of a special device, such as a hard disk |
| partition, but it could also be a more or less generic string. For |
| NFS it would be a hostname and directory name combination. |
| <br><br> Even though the element is not declared <CODE>const</CODE> it shouldn't be |
| modified. The missing <CODE>const</CODE> has historic reasons, since this |
| function predates ISO C. The same is true for the other string |
| elements of this structure. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="char *fs_file"> |
| <synopsis> |
| This describes the mount point on the local system. I.e., accessing any |
| file in this filesystem has implicitly or explicitly this string as a |
| prefix. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="char *fs_vfstype"> |
| <synopsis> |
| This is the type of the filesystem. Depending on what the underlying |
| kernel understands it can be any string. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="char *fs_mntops"> |
| <synopsis> |
| This is a string containing options passed to the kernel with the |
| <CODE>mount</CODE> 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 <CODE>=</CODE> |
| character. |
| <br><br> If the value of this element must be processed it should ideally be done |
| using the <CODE>getsubopt</CODE> function; see Suboptions. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="const char *fs_type"> |
| <synopsis> |
| This name is poorly chosen. This element points to a string (possibly |
| in the <CODE>fs_mntops</CODE> string) which describes the modes with which the |
| filesystem is mounted. <TT>fstab</TT> defines five macros to describe the |
| possible values: |
| <br><br> <DL> |
| |
| </synopsis> |
| </element> |
| <element content="FSTAB_RW"> |
| <synopsis> |
| The filesystems gets mounted with read and write enabled. |
| </synopsis> |
| </element> |
| <element content="FSTAB_RQ"> |
| <synopsis> |
| The filesystems gets mounted with read and write enabled. Write access |
| is restricted by quotas. |
| </synopsis> |
| </element> |
| <element content="FSTAB_RO"> |
| <synopsis> |
| The filesystem gets mounted read-only. |
| </synopsis> |
| </element> |
| <element content="FSTAB_SW"> |
| <synopsis> |
| This is not a real filesystem, it is a swap device. |
| </synopsis> |
| </element> |
| <element content="FSTAB_XX"> |
| <synopsis> |
| This entry from the <TT>fstab</TT> file is totally ignored. |
| </DL> |
| <br><br> Testing for equality with these value must happen using <CODE>strcmp</CODE> |
| since these are all strings. Comparing the pointer will probably always |
| fail. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="int fs_freq"> |
| <synopsis> |
| This element describes the dump frequency in days. |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="function-setfsent" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "fstab.h"/> |
| </headers> |
| <synopsis> |
| This function makes sure that the internal read pointer for the |
| <TT>fstab</TT> file is at the beginning of the file. This is done by |
| either opening the file or resetting the read pointer. |
| <br><br> Since the file handle is internal to the libc this function is not |
| thread-safe. |
| <br><br> This function returns a non-zero value if the operation was successful |
| and the <CODE>getfs*</CODE> functions can be used to read the entries of the |
| file. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-endfsent" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "fstab.h"/> |
| </headers> |
| <synopsis> |
| This function makes sure that all resources acquired by a prior call to |
| <CODE>setfsent</CODE> (explicitly or implicitly by calling <CODE>getfsent</CODE>) are |
| freed. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getfsent" type="function"> |
| <function returntype="struct fstab *"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "fstab.h"/> |
| </headers> |
| <synopsis> |
| This function returns the next entry of the <TT>fstab</TT> file. If this |
| is the first call to any of the functions handling <TT>fstab</TT> since |
| program start or the last call of <CODE>endfsent</CODE>, the file will be |
| opened. |
| <br><br> The function returns a pointer to a variable of type <CODE>struct |
| fstab</CODE>. This variable is shared by all threads and therefore this |
| function is not thread-safe. If an error occurred <CODE>getfsent</CODE> |
| returns a <CODE>NULL</CODE> pointer. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getfsspec" type="function"> |
| <function returntype="struct fstab *"> |
| <prototype> |
| <parameter content="const char *name"/> |
| </prototype> |
| <headers> |
| <header filename = "fstab.h"/> |
| </headers> |
| <synopsis> |
| This function returns the next entry of the <TT>fstab</TT> file which has |
| a string equal to <VAR>name</VAR> pointed to by the <CODE>fs_spec</CODE> element. |
| Since there is normally exactly one entry for each special device it |
| makes no sense to call this function more than once for the same |
| argument. If this is the first call to any of the functions handling |
| <TT>fstab</TT> since program start or the last call of <CODE>endfsent</CODE>, |
| the file will be opened. |
| <br><br> The function returns a pointer to a variable of type <CODE>struct |
| fstab</CODE>. This variable is shared by all threads and therefore this |
| function is not thread-safe. If an error occurred <CODE>getfsent</CODE> |
| returns a <CODE>NULL</CODE> pointer. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getfsfile" type="function"> |
| <function returntype="struct fstab *"> |
| <prototype> |
| <parameter content="const char *name"/> |
| </prototype> |
| <headers> |
| <header filename = "fstab.h"/> |
| </headers> |
| <synopsis> |
| This function returns the next entry of the <TT>fstab</TT> file which has |
| a string equal to <VAR>name</VAR> pointed to by the <CODE>fs_file</CODE> element. |
| Since there is normally exactly one entry for each mount point it |
| makes no sense to call this function more than once for the same |
| argument. If this is the first call to any of the functions handling |
| <TT>fstab</TT> since program start or the last call of <CODE>endfsent</CODE>, |
| the file will be opened. |
| <br><br> The function returns a pointer to a variable of type <CODE>struct |
| fstab</CODE>. This variable is shared by all threads and therefore this |
| function is not thread-safe. If an error occurred <CODE>getfsent</CODE> |
| returns a <CODE>NULL</CODE> pointer. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="struct-mntent" type="struct"> |
| <structure> |
| <synopsis> |
| This structure is used with the <CODE>getmntent</CODE>, <CODE>getmntent_t</CODE>, |
| <CODE>addmntent</CODE>, and <CODE>hasmntopt</CODE> functions. |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="char *mnt_fsname"> |
| <synopsis> |
| This element contains a pointer to a string describing the name of the |
| special device from which the filesystem is mounted. It corresponds to |
| the <CODE>fs_spec</CODE> element in <CODE>struct fstab</CODE>. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="char *mnt_dir"> |
| <synopsis> |
| This element points to a string describing the mount point of the |
| filesystem. It corresponds to the <CODE>fs_file</CODE> element in |
| <CODE>struct fstab</CODE>. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="char *mnt_type"> |
| <synopsis> |
| <CODE>mnt_type</CODE> describes the filesystem type and is therefore |
| equivalent to <CODE>fs_vfstype</CODE> in <CODE>struct fstab</CODE>. <TT>mntent.h</TT> |
| 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 <TT>mntent.h</TT>. |
| <br><br> <DL> |
| |
| </synopsis> |
| </element> |
| <element content="MNTTYPE_IGNORE"> |
| <synopsis> |
| This symbol expands to <CODE>"ignore"</CODE>. The value is sometime used in |
| <TT>fstab</TT> files to make sure entries are not used without removing them. |
| </synopsis> |
| </element> |
| <element content="MNTTYPE_NFS"> |
| <synopsis> |
| Expands to <CODE>"nfs"</CODE>. Using this macro sometimes could make sense |
| since it names the default NFS implementation, in case both version 2 |
| and 3 are supported. |
| </synopsis> |
| </element> |
| <element content="MNTTYPE_SWAP"> |
| <synopsis> |
| This symbol expands to <CODE>"swap"</CODE>. It names the special <TT>fstab</TT> |
| entry which names one of the possibly multiple swap partitions. |
| </DL> |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="char *mnt_opts"> |
| <synopsis> |
| The element contains a string describing the options used while mounting |
| the filesystem. As for the equivalent element <CODE>fs_mntops</CODE> of |
| <CODE>struct fstab</CODE> it is best to use the function <CODE>getsubopt</CODE> |
| to access the parts of this string. |
| <br><br> The <TT>mntent.h</TT> 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><br> <DL> |
| |
| </synopsis> |
| </element> |
| <element content="MNTOPT_DEFAULTS"> |
| <synopsis> |
| Expands to <CODE>"defaults"</CODE>. This option should be used alone since it |
| indicates all values for the customizable values are chosen to be the |
| default. |
| </synopsis> |
| </element> |
| <element content="MNTOPT_RO"> |
| <synopsis> |
| Expands to <CODE>"ro"</CODE>. See the <CODE>FSTAB_RO</CODE> value, it means the |
| filesystem is mounted read-only. |
| </synopsis> |
| </element> |
| <element content="MNTOPT_RW"> |
| <synopsis> |
| Expand to <CODE>"rw"</CODE>. See the <CODE>FSTAB_RW</CODE> value, it means the |
| filesystem is mounted with read and write permissions. |
| </synopsis> |
| </element> |
| <element content="MNTOPT_SUID"> |
| <synopsis> |
| Expands to <CODE>"suid"</CODE>. This means that the SUID bit is respected when a program from the filesystem is |
| started. |
| </synopsis> |
| </element> |
| <element content="MNTOPT_NOSUID"> |
| <synopsis> |
| Expands to <CODE>"nosuid"</CODE>. This is the opposite of <CODE>MNTOPT_SUID</CODE>, |
| the SUID bit for all files from the filesystem is ignored. |
| </synopsis> |
| </element> |
| <element content="MNTOPT_NOAUTO"> |
| <synopsis> |
| Expands to <CODE>"noauto"</CODE>. At startup time the <CODE>mount</CODE> program |
| will ignore this entry if it is started with the <CODE>-a</CODE> option to |
| mount all filesystems mentioned in the <TT>fstab</TT> file. |
| </DL> |
| <br><br> As for the <CODE>FSTAB_*</CODE> entries introduced above it is important to |
| use <CODE>strcmp</CODE> to check for equality. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="mnt_freq"> |
| <synopsis> |
| This elements corresponds to <CODE>fs_freq</CODE> and also specifies the |
| frequency in days in which dumps are made. |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="function-setmntent" type="function"> |
| <function returntype="FILE *"> |
| <prototype> |
| <parameter content="const char *file"/> |
| <parameter content="const char *mode"/> |
| </prototype> |
| <headers> |
| <header filename = "mntent.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>setmntent</CODE> function prepares the file named <VAR>FILE</VAR> which |
| must be in the format of a <TT>fstab</TT> and <TT>mtab</TT> file for the |
| upcoming processing through the other functions of the family. The |
| <VAR>mode</VAR> parameter can be chosen in the way the <VAR>opentype</VAR> |
| parameter for <CODE>fopen</CODE> can be chosen. If |
| the file is opened for writing the file is also allowed to be empty. |
| <br><br> If the file was successfully opened <CODE>setmntent</CODE> returns a file |
| descriptor for future use. Otherwise the return value is <CODE>NULL</CODE> |
| and <CODE>errno</CODE> is set accordingly. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-endmntent" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "mntent.h"/> |
| </headers> |
| <synopsis> |
| This function takes for the <VAR>stream</VAR> parameter a file handle which |
| previously was returned from the <CODE>setmntent</CODE> call. |
| <CODE>endmntent</CODE> closes the stream and frees all resources. |
| <br><br> The return value is 1 unless an error occurred in which case it |
| is 0. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getmntent" type="function"> |
| <function returntype="struct mntent *"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "mntent.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>getmntent</CODE> function takes as the parameter a file handle |
| previously returned by successful call to <CODE>setmntent</CODE>. It returns |
| a pointer to a static variable of type <CODE>struct mntent</CODE> which is |
| filled with the information from the next entry from the file currently |
| read. |
| <br><br> The file format used prescribes the use of spaces or tab characters to |
| separate the fields. This makes it harder to use name containing one |
| of these characters (e.g., mount points using spaces). Therefore |
| these characters are encoded in the files and the <CODE>getmntent</CODE> |
| function takes care of the decoding while reading the entries back in. |
| <CODE>'\040'</CODE> is used to encode a space character, <CODE>'\011'</CODE> to |
| encode a tab character, <CODE>'\012'</CODE> to encode a newline character, |
| and <CODE>'\\'</CODE> to encode a backslash. |
| <br><br> If there was an error or the end of the file is reached the return value |
| is <CODE>NULL</CODE>. |
| <br><br> This function is not thread-safe since all calls to this function return |
| a pointer to the same static variable. <CODE>getmntent_r</CODE> should be |
| used in situations where multiple threads access the file. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getmntent_r" type="function"> |
| <function returntype="struct mntent *"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| <parameter content="struct mentent *result"/> |
| <parameter content="char *buffer"/> |
| <parameter content="int bufsize"/> |
| </prototype> |
| <headers> |
| <header filename = "mntent.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>getmntent_r</CODE> function is the reentrant variant of |
| <CODE>getmntent</CODE>. It also returns the next entry from the file and |
| returns a pointer. The actual variable the values are stored in is not |
| static, though. Instead the function stores the values in the variable |
| pointed to by the <VAR>result</VAR> parameter. Additional information (e.g., |
| the strings pointed to by the elements of the result) are kept in the |
| buffer of size <VAR>bufsize</VAR> pointed to by <VAR>buffer</VAR>. |
| <br><br> Escaped characters (space, tab, backslash) are converted back in the |
| same way as it happens for <CODE>getmentent</CODE>. |
| <br><br> The function returns a <CODE>NULL</CODE> pointer in error cases. Errors could be: |
| <OL> |
| <LI> |
| error while reading the file, |
| <LI> |
| end of file reached, |
| <LI> |
| <VAR>bufsize</VAR> is too small for reading a complete new entry. |
| </OL> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-addmntent" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| <parameter content="const struct mntent *mnt"/> |
| </prototype> |
| <headers> |
| <header filename = "mntent.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>addmntent</CODE> function allows adding a new entry to the file |
| previously opened with <CODE>setmntent</CODE>. The new entries are always |
| appended. I.e., even if the position of the file descriptor is not at |
| the end of the file this function does not overwrite an existing entry |
| following the current position. |
| <br><br> The implication of this is that to remove an entry from a file one has |
| to create a new file while leaving out the entry to be removed and after |
| closing the file remove the old one and rename the new file to the |
| chosen name. |
| <br><br> This function takes care of spaces and tab characters in the names to be |
| written to the file. It converts them and the backslash character into |
| the format describe in the <CODE>getmntent</CODE> description above. |
| <br><br> This function returns 0 in case the operation was successful. |
| Otherwise the return value is 1 and <CODE>errno</CODE> is set |
| appropriately. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-hasmntopt" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="const struct mntent *mnt"/> |
| <parameter content="const char *opt"/> |
| </prototype> |
| <headers> |
| <header filename = "mntent.h"/> |
| </headers> |
| <synopsis> |
| This function can be used to check whether the string pointed to by the |
| <CODE>mnt_opts</CODE> element of the variable pointed to by <VAR>mnt</VAR> contains |
| the option <VAR>opt</VAR>. If this is true a pointer to the beginning of the |
| option in the <CODE>mnt_opts</CODE> element is returned. If no such option |
| exists the function returns <CODE>NULL</CODE>. |
| <br><br> This function is useful to test whether a specific option is present but |
| when all options have to be processed one is better off with using the |
| <CODE>getsubopt</CODE> function to iterate over all options in the string. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-mount" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *special_file"/> |
| <parameter content="const char *dir"/> |
| <parameter content="const char *fstype"/> |
| <parameter content="unsigned long int options"/> |
| <parameter content="const void *data"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/mount.h"/> |
| </headers> |
| <synopsis> |
| <br><br> <CODE>mount</CODE> mounts or remounts a filesystem. The two operations are |
| quite different and are merged rather unnaturally into this one function. |
| The <CODE>MS_REMOUNT</CODE> option, explained below, determines whether |
| <CODE>mount</CODE> mounts or remounts. |
| <br><br> For a mount, the filesystem on the block device represented by the |
| device special file named <VAR>special_file</VAR> gets mounted over the mount |
| point <VAR>dir</VAR>. This means that the directory <VAR>dir</VAR> (along with any |
| files in it) is no longer visible; in its place (and still with the name |
| <VAR>dir</VAR>) is the root directory of the filesystem on the device. |
| <br><br> As an exception, if the filesystem type (see below) is one which is not |
| based on a device (e.g. ``proc''), <CODE>mount</CODE> instantiates a |
| filesystem and mounts it over <VAR>dir</VAR> and ignores <VAR>special_file</VAR>. |
| <br><br> For a remount, <VAR>dir</VAR> specifies the mount point where the filesystem |
| to be remounted is (and remains) mounted and <VAR>special_file</VAR> is |
| ignored. Remounting a filesystem means changing the options that control |
| operations on the filesystem while it is mounted. It does not mean |
| unmounting and mounting again. |
| <br><br> For a mount, you must identify the type of the filesystem as |
| <VAR>fstype</VAR>. This type tells the kernel how to access the filesystem |
| and can be thought of as the name of a filesystem driver. The |
| acceptable values are system dependent. On a system with a Linux kernel |
| and the <CODE>proc</CODE> filesystem, the list of possible values is in the |
| file <TT>filesystems</TT> in the <CODE>proc</CODE> filesystem (e.g. type |
| <KBD>cat /proc/filesystems</KBD> to see the list). With a Linux kernel, the |
| types of filesystems that <CODE>mount</CODE> can mount, and their type names, |
| depends on what filesystem drivers are configured into the kernel or |
| loaded as loadable kernel modules. An example of a common value for |
| <VAR>fstype</VAR> is <CODE>ext2</CODE>. |
| <br><br> For a remount, <CODE>mount</CODE> ignores <VAR>fstype</VAR>. |
| <br><br> <VAR>options</VAR> specifies a variety of options that apply until the |
| filesystem is unmounted or remounted. The precise meaning of an option |
| depends on the filesystem and with some filesystems, an option may have |
| no effect at all. Furthermore, for some filesystems, some of these |
| options (but never <CODE>MS_RDONLY</CODE>) can be overridden for individual |
| file accesses via <CODE>ioctl</CODE>. |
| <br><br> <VAR>options</VAR> is a bit string with bit fields defined using the |
| following mask and masked value macros: |
| <br><br> <DL> |
| |
| <DT><CODE>MS_MGC_MASK</CODE> |
| <DD> |
| This multibit field contains a magic number. If it does not have the value |
| <CODE>MS_MGC_VAL</CODE>, <CODE>mount</CODE> assumes all the following bits are zero and |
| the <VAR>data</VAR> argument is a null string, regardless of their actual values. |
| <br><br> <DT><CODE>MS_REMOUNT</CODE> |
| <DD> |
| This bit on means to remount the filesystem. Off means to mount it. |
| <br><br> <LI> MS_RDONLY |
| This bit on specifies that no writing to the filesystem shall be allowed |
| while it is mounted. This cannot be overridden by <CODE>ioctl</CODE>. This |
| option is available on nearly all filesystems. |
| <br><br> <LI> S_IMMUTABLE |
| This bit on specifies that no writing to the files in the filesystem |
| shall be allowed while it is mounted. This can be overridden for a |
| particular file access by a properly privileged call to <CODE>ioctl</CODE>. |
| This option is a relatively new invention and is not available on many |
| filesystems. |
| <br><br> <LI> S_APPEND |
| This bit on specifies that the only file writing that shall be allowed |
| while the filesystem is mounted is appending. Some filesystems allow |
| this to be overridden for a particular process by a properly privileged |
| call to <CODE>ioctl</CODE>. This is a relatively new invention and is not |
| available on many filesystems. |
| <br><br> <LI> MS_NOSUID |
| This bit on specifies that Setuid and Setgid permissions on files in the |
| filesystem shall be ignored while it is mounted. |
| <br><br> <LI> MS_NOEXEC |
| This bit on specifies that no files in the filesystem shall be executed |
| while the filesystem is mounted. |
| <br><br> <LI> MS_NODEV |
| This bit on specifies that no device special files in the filesystem |
| shall be accessible while the filesystem is mounted. |
| <br><br> <LI> MS_SYNCHRONOUS |
| This bit on specifies that all writes to the filesystem while it is |
| mounted shall be synchronous; i.e., data shall be synced before each |
| write completes rather than held in the buffer cache. |
| <br><br> <LI> MS_MANDLOCK |
| This bit on specifies that mandatory locks on files shall be permitted while |
| the filesystem is mounted. |
| <br><br> <LI> MS_NOATIME |
| This bit on specifies that access times of files shall not be updated when |
| the files are accessed while the filesystem is mounted. |
| <br><br> <LI> MS_NODIRATIME |
| This bit on specifies that access times of directories shall not be updated |
| when the directories are accessed while the filesystem in mounted. |
| <br><br> <br><br> |
| <br><br> Any bits not covered by the above masks should be set off; otherwise, |
| results are undefined. |
| <br><br> The meaning of <VAR>data</VAR> depends on the filesystem type and is controlled |
| entirely by the filesystem driver in the kernel. |
| <br><br> Example: |
| <br><br> <pre><br> |
| <br> |
| #include <sys/mount.h><br> |
| <br><br> mount("/dev/hdb", "/cdrom", MS_MGC_VAL | MS_RDONLY | MS_NOSUID, "");<br> |
| <br><br> mount("/dev/hda2", "/mnt", MS_MGC_VAL | MS_REMOUNT, "");<br> |
| <br><br> <br> |
| </pre> |
| <br><br> Appropriate arguments for <CODE>mount</CODE> are conventionally recorded in |
| the <TT>fstab</TT> table. . |
| <br><br> The return value is zero if the mount or remount is successful. Otherwise, |
| it is <CODE>-1</CODE> and <CODE>errno</CODE> is set appropriately. The values of |
| <CODE>errno</CODE> are filesystem dependent, but here is a general list: |
| <br><br> <DL> |
| |
| <LI> EPERM |
| The process is not superuser. |
| <LI> ENODEV |
| The file system type <VAR>fstype</VAR> is not known to the kernel. |
| <LI> ENOTBLK |
| The file <VAR>dev</VAR> is not a block device special file. |
| <LI> EBUSY |
| <br><br> <OL> |
| <br><br> <LI> |
| The device is already mounted. |
| <br><br> <LI> |
| The mount point is busy. (E.g. it is some process' working directory or |
| has a filesystem mounted on it already). |
| <br><br> <LI> |
| The request is to remount read-only, but there are files open for write. |
| </OL> |
| <br><br> <LI> EINVAL |
| <OL> |
| <br><br> <LI> |
| A remount was attempted, but there is no filesystem mounted over the |
| specified mount point. |
| <br><br> <LI> |
| The supposed filesystem has an invalid superblock. |
| <br><br> </OL> |
| <br><br> <LI> EACCES |
| <OL> |
| <br><br> <LI> |
| The filesystem is inherently read-only (possibly due to a switch on the |
| device) and the process attempted to mount it read/write (by setting the |
| <CODE>MS_RDONLY</CODE> bit off). |
| <br><br> <LI> |
| <VAR>special_file</VAR> or <VAR>dir</VAR> is not accessible due to file permissions. |
| <br><br> <LI> |
| <VAR>special_file</VAR> is not accessible because it is in a filesystem that is |
| mounted with the <CODE>MS_NODEV</CODE> option. |
| <br><br> </OL> |
| <br><br> <LI> EM_FILE |
| The table of dummy devices is full. <CODE>mount</CODE> needs to create a |
| dummy device (aka ``unnamed'' device) if the filesystem being mounted is |
| not one that uses a device. |
| <br><br> |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-umount2" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *file"/> |
| <parameter content="int flags"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/mount.h"/> |
| </headers> |
| <synopsis> |
| <br><br> <CODE>umount2</CODE> unmounts a filesystem. |
| <br><br> You can identify the filesystem to unmount either by the device special |
| file that contains the filesystem or by the mount point. The effect is |
| the same. Specify either as the string <VAR>file</VAR>. |
| <br><br> <VAR>flags</VAR> contains the one-bit field identified by the following |
| mask macro: |
| <br><br> <DL> |
| |
| <br><br> <DT><CODE>MNT_FORCE</CODE> |
| <DD> |
| This bit on means to force the unmounting even if the filesystem is |
| busy, by making it unbusy first. If the bit is off and the filesystem is |
| busy, <CODE>umount2</CODE> fails with <CODE>errno</CODE> = <CODE>EBUSY</CODE>. Depending |
| on the filesystem, this may override all, some, or no busy conditions. |
| <br><br> |
| <br><br> All other bits in <VAR>flags</VAR> should be set to zero; otherwise, the result |
| is undefined. |
| <br><br> Example: |
| <br><br> <pre><br> |
| <br> |
| #include <sys/mount.h><br> |
| <br><br> umount2("/mnt", MNT_FORCE);<br> |
| <br><br> umount2("/dev/hdd1", 0);<br> |
| <br><br> <br> |
| </pre> |
| <br><br> After the filesystem is unmounted, the directory that was the mount point |
| is visible, as are any files in it. |
| <br><br> As part of unmounting, <CODE>umount2</CODE> syncs the filesystem. |
| <br><br> If the unmounting is successful, the return value is zero. Otherwise, it |
| is <CODE>-1</CODE> and <CODE>errno</CODE> is set accordingly: |
| <br><br> <DL> |
| |
| <LI> EPERM |
| The process is not superuser. |
| <LI> EBUSY |
| The filesystem cannot be unmounted because it is busy. E.g. it contains |
| a directory that is some process's working directory or a file that some |
| process has open. With some filesystems in some cases, you can avoid |
| this failure with the <CODE>MNT_FORCE</CODE> option. |
| <br><br> <LI> EINVAL |
| <VAR>file</VAR> validly refers to a file, but that file is neither a mount |
| point nor a device special file of a currently mounted filesystem. |
| <br><br> |
| </DL> |
| <br><br> This function is not available on all systems. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-umount" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *file"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/mount.h"/> |
| </headers> |
| <synopsis> |
| <br><br> <CODE>umount</CODE> does the same thing as <CODE>umount2</CODE> with <VAR>flags</VAR> set |
| to zeroes. It is more widely available than <CODE>umount2</CODE> but since it |
| lacks the possibility to forcefully unmount a filesystem is deprecated |
| when <CODE>umount2</CODE> is also available. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-sysctl" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int *names"/> |
| <parameter content="int nlen"/> |
| <parameter content="void *oldval"/> |
| <parameter content="size_t *oldlenp"/> |
| <parameter content="void *newval"/> |
| <parameter content="size_t newlen"/> |
| </prototype> |
| <headers> |
| <header filename = "sysctl.h"/> |
| </headers> |
| <synopsis> |
| <br><br> <CODE>sysctl</CODE> gets or sets a specified system parameter. There are so |
| many of these parameters that it is not practical to list them all here, |
| but here are some examples: |
| <br><br> <OL> |
| <LI> network domain name |
| <LI> paging parameters |
| <LI> network Address Resolution Protocol timeout time |
| <LI> maximum number of files that may be open |
| <LI> root filesystem device |
| <LI> when kernel was built |
| </OL> |
| <br><br> The set of available parameters depends on the kernel configuration and |
| can change while the system is running, particularly when you load and |
| unload loadable kernel modules. |
| <br><br> The system parameters with which <CODE>syslog</CODE> is concerned are arranged |
| in a hierarchical structure like a hierarchical filesystem. To identify |
| a particular parameter, you specify a path through the structure in a |
| way analogous to specifying the pathname of a file. Each component of |
| the path is specified by an integer and each of these integers has a |
| macro defined for it by <TT>sysctl.h</TT>. <VAR>names</VAR> is the path, in |
| the form of an array of integers. Each component of the path is one |
| element of the array, in order. <VAR>nlen</VAR> is the number of components |
| in the path. |
| <br><br> For example, the first component of the path for all the paging |
| parameters is the value <CODE>CTL_VM</CODE>. For the free page thresholds, the |
| second component of the path is <CODE>VM_FREEPG</CODE>. So to get the free |
| page threshold values, make <VAR>names</VAR> an array containing the two |
| elements <CODE>CTL_VM</CODE> and <CODE>VM_FREEPG</CODE> and make <VAR>nlen</VAR> = 2. |
| <br><br> <br><br> The format of the value of a parameter depends on the parameter. |
| Sometimes it is an integer; sometimes it is an ASCII string; sometimes |
| it is an elaborate structure. In the case of the free page thresholds |
| used in the example above, the parameter value is a structure containing |
| several integers. |
| <br><br> In any case, you identify a place to return the parameter's value with |
| <VAR>oldval</VAR> and specify the amount of storage available at that |
| location as *<VAR>oldlenp</VAR>. *<VAR>oldlenp</VAR> does double duty because it |
| is also the output location that contains the actual length of the |
| returned value. |
| <br><br> If you don't want the parameter value returned, specify a null pointer |
| for <VAR>oldval</VAR>. |
| <br><br> To set the parameter, specify the address and length of the new value |
| as <VAR>newval</VAR> and <VAR>newlen</VAR>. If you don't want to set the parameter, |
| specify a null pointer as <VAR>newval</VAR>. |
| <br><br> If you get and set a parameter in the same <CODE>sysctl</CODE> call, the value |
| returned is the value of the parameter before it was set. |
| <br><br> Each system parameter has a set of permissions similar to the |
| permissions for a file (including the permissions on directories in its |
| path) that determine whether you may get or set it. For the purposes of |
| these permissions, every parameter is considered to be owned by the |
| superuser and Group 0 so processes with that effective uid or gid may |
| have more access to system parameters. Unlike with files, the superuser |
| does not invariably have full permission to all system parameters, because |
| some of them are designed not to be changed ever. |
| <br><br> <br><br> <CODE>sysctl</CODE> returns a zero return value if it succeeds. Otherwise, it |
| returns <CODE>-1</CODE> and sets <CODE>errno</CODE> appropriately. Besides the |
| failures that apply to all system calls, the following are the |
| <CODE>errno</CODE> codes for all possible failures: |
| <br><br> <DL> |
| |
| <DT><CODE>EPERM</CODE> |
| <DD> |
| The process is not permitted to access one of the components of the |
| path of the system parameter or is not permitted to access the system parameter |
| itself in the way (read or write) that it requested. |
| <LI> ENOTDIR |
| There is no system parameter corresponding to <VAR>name</VAR>. |
| <LI> EFAULT |
| <VAR>oldval</VAR> is not null, which means the process wanted to read the parameter, |
| but *<VAR>oldlenp</VAR> is zero, so there is no place to return it. |
| <LI> EINVAL |
| <OL> |
| <LI> |
| The process attempted to set a system parameter to a value that is not valid |
| for that parameter. |
| <LI> |
| The space provided for the return of the system parameter is not the right |
| size for that parameter. |
| </OL> |
| <LI> ENOMEM |
| This value may be returned instead of the more correct <CODE>EINVAL</CODE> in some |
| cases where the space provided for the return of the system parameter is too |
| small. |
| <br><br> |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="dtype-uid_t" type="dtype"> |
| <structure> |
| </structure> |
| </construct> |
| <construct id="dtype-gid_t" type="dtype"> |
| <structure> |
| </structure> |
| </construct> |
| <construct id="function-getuid" type="function"> |
| <function returntype="uid_t"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/types.h"/> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>getuid</CODE> function returns the real user ID of the process. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getgid" type="function"> |
| <function returntype="gid_t"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>getgid</CODE> function returns the real group ID of the process. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-geteuid" type="function"> |
| <function returntype="uid_t"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>geteuid</CODE> function returns the effective user ID of the process. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getegid" type="function"> |
| <function returntype="gid_t"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>getegid</CODE> function returns the effective group ID of the process. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getgroups" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int count"/> |
| <parameter content="gid_t *groups"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>getgroups</CODE> function is used to inquire about the supplementary |
| group IDs of the process. Up to <VAR>count</VAR> of these group IDs are |
| stored in the array <VAR>groups</VAR>; the return value from the function is |
| the number of group IDs actually stored. If <VAR>count</VAR> is smaller than |
| the total number of supplementary group IDs, then <CODE>getgroups</CODE> |
| returns a value of <CODE>-1</CODE> and <CODE>errno</CODE> is set to <CODE>EINVAL</CODE>. |
| <br><br> If <VAR>count</VAR> is zero, then <CODE>getgroups</CODE> just returns the total |
| number of supplementary group IDs. On systems that do not support |
| supplementary groups, this will always be zero. |
| <br><br> Here's how to use <CODE>getgroups</CODE> to read all the supplementary group |
| IDs: |
| <br><br> <pre><br> |
| <br> |
| gid_t *<br> |
| read_all_groups (void)<br> |
| {<br> |
| int ngroups = getgroups (0, NULL);<br> |
| gid_t *groups<br> |
| = (gid_t *) xmalloc (ngroups * sizeof (gid_t));<br> |
| int val = getgroups (ngroups, groups);<br> |
| if (val < 0)<br> |
| {<br> |
| free (groups);<br> |
| return NULL;<br> |
| }<br> |
| return groups;<br> |
| }<br> |
| <br> |
| </pre> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-seteuid" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="uid_t neweuid"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| This function sets the effective user ID of a process to <VAR>newuid</VAR>, |
| provided that the process is allowed to change its effective user ID. A |
| privileged process (effective user ID zero) can change its effective |
| user ID to any legal value. An unprivileged process with a file user ID |
| can change its effective user ID to its real user ID or to its file user |
| ID. Otherwise, a process may not change its effective user ID at all. |
| <br><br> The <CODE>seteuid</CODE> function returns a value of <CODE>0</CODE> to indicate |
| successful completion, and a value of <CODE>-1</CODE> to indicate an error. |
| The following <CODE>errno</CODE> error conditions are defined for this |
| function: |
| <br><br> <DL> |
| |
| <DT><CODE>EINVAL</CODE> |
| <DD> |
| The value of the <VAR>newuid</VAR> argument is invalid. |
| <br><br> <LI> EPERM |
| The process may not change to the specified ID. |
| |
| <br><br> Older systems (those without the <CODE>_POSIX_SAVED_IDS</CODE> feature) do not |
| have this function. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-setuid" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="uid_t newuid"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| If the calling process is privileged, this function sets both the real |
| and effective user ID of the process to <VAR>newuid</VAR>. It also deletes |
| the file user ID of the process, if any. <VAR>newuid</VAR> may be any |
| legal value. (Once this has been done, there is no way to recover the |
| old effective user ID.) |
| <br><br> If the process is not privileged, and the system supports the |
| <CODE>_POSIX_SAVED_IDS</CODE> feature, then this function behaves like |
| <CODE>seteuid</CODE>. |
| <br><br> The return values and error conditions are the same as for <CODE>seteuid</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-setreuid" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="uid_t ruid"/> |
| <parameter content="uid_t euid"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| This function sets the real user ID of the process to <VAR>ruid</VAR> and the |
| effective user ID to <VAR>euid</VAR>. If <VAR>ruid</VAR> is <CODE>-1</CODE>, it means |
| not to change the real user ID; likewise if <VAR>euid</VAR> is <CODE>-1</CODE>, it |
| means not to change the effective user ID. |
| <br><br> The <CODE>setreuid</CODE> function exists for compatibility with 4.3 BSD Unix, |
| which does not support file IDs. You can use this function to swap the |
| effective and real user IDs of the process. (Privileged processes are |
| not limited to this particular usage.) If file IDs are supported, you |
| should use that feature instead of this function. . |
| <br><br> The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on failure. |
| The following <CODE>errno</CODE> error conditions are defined for this |
| function: |
| <br><br> <DL> |
| |
| <DT><CODE>EPERM</CODE> |
| <DD> |
| The process does not have the appropriate privileges; you do not |
| have permission to change to the specified ID. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-setegid" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="gid_t newgid"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| This function sets the effective group ID of the process to |
| <VAR>newgid</VAR>, provided that the process is allowed to change its group |
| ID. Just as with <CODE>seteuid</CODE>, if the process is privileged it may |
| change its effective group ID to any value; if it isn't, but it has a |
| file group ID, then it may change to its real group ID or file group ID; |
| otherwise it may not change its effective group ID. |
| <br><br> Note that a process is only privileged if its effective <EM>user</EM> ID |
| is zero. The effective group ID only affects access permissions. |
| <br><br> The return values and error conditions for <CODE>setegid</CODE> are the same |
| as those for <CODE>seteuid</CODE>. |
| <br><br> This function is only present if <CODE>_POSIX_SAVED_IDS</CODE> is defined. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-setgid" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="gid_t newgid"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| This function sets both the real and effective group ID of the process |
| to <VAR>newgid</VAR>, provided that the process is privileged. It also |
| deletes the file group ID, if any. |
| <br><br> If the process is not privileged, then <CODE>setgid</CODE> behaves like |
| <CODE>setegid</CODE>. |
| <br><br> The return values and error conditions for <CODE>setgid</CODE> are the same |
| as those for <CODE>seteuid</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-setregid" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="gid_t rgid"/> |
| <parameter content="gid_t egid"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| This function sets the real group ID of the process to <VAR>rgid</VAR> and |
| the effective group ID to <VAR>egid</VAR>. If <VAR>rgid</VAR> is <CODE>-1</CODE>, it |
| means not to change the real group ID; likewise if <VAR>egid</VAR> is |
| <CODE>-1</CODE>, it means not to change the effective group ID. |
| <br><br> The <CODE>setregid</CODE> function is provided for compatibility with 4.3 BSD |
| Unix, which does not support file IDs. You can use this function to |
| swap the effective and real group IDs of the process. (Privileged |
| processes are not limited to this usage.) If file IDs are supported, |
| you should use that feature instead of using this function. |
| . |
| <br><br> The return values and error conditions for <CODE>setregid</CODE> are the same |
| as those for <CODE>setreuid</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-setgroups" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="size_t count"/> |
| <parameter content="gid_t *groups"/> |
| </prototype> |
| <headers> |
| <header filename = "grp.h"/> |
| </headers> |
| <synopsis> |
| This function sets the process's supplementary group IDs. It can only |
| be called from privileged processes. The <VAR>count</VAR> argument specifies |
| the number of group IDs in the array <VAR>groups</VAR>. |
| <br><br> This function returns <CODE>0</CODE> if successful and <CODE>-1</CODE> on error. |
| The following <CODE>errno</CODE> error conditions are defined for this |
| function: |
| <br><br> <DL> |
| |
| <DT><CODE>EPERM</CODE> |
| <DD> |
| The calling process is not privileged. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-initgroups" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *user"/> |
| <parameter content="gid_t group"/> |
| </prototype> |
| <headers> |
| <header filename = "grp.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>initgroups</CODE> function sets the process's supplementary group |
| IDs to be the normal default for the user name <VAR>user</VAR>. The group |
| <VAR>group</VAR> is automatically included. |
| <br><br> This function works by scanning the group database for all the groups |
| <VAR>user</VAR> belongs to. It then calls <CODE>setgroups</CODE> with the list it |
| has constructed. |
| <br><br> The return values and error conditions are the same as for |
| <CODE>setgroups</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getgrouplist" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *user"/> |
| <parameter content="gid_t group"/> |
| <parameter content="gid_t *groups"/> |
| <parameter content="int *ngroups"/> |
| </prototype> |
| <headers> |
| <header filename = "grp.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>getgrouplist</CODE> function scans the group database for all the |
| groups <VAR>user</VAR> belongs to. Up to *<VAR>ngroups</VAR> group IDs |
| corresponding to these groups are stored in the array <VAR>groups</VAR>; the |
| return value from the function is the number of group IDs actually |
| stored. If *<VAR>ngroups</VAR> is smaller than the total number of groups |
| found, then <CODE>getgrouplist</CODE> returns a value of <CODE>-1</CODE> and stores |
| the actual number of groups in *<VAR>ngroups</VAR>. The group <VAR>group</VAR> is |
| automatically included in the list of groups returned by |
| <CODE>getgrouplist</CODE>. |
| <br><br> Here's how to use <CODE>getgrouplist</CODE> to read all supplementary groups |
| for <VAR>user</VAR>: |
| <br><br> <pre><br> |
| <br> |
| gid_t *<br> |
| supplementary_groups (char *user)<br> |
| {<br> |
| int ngroups = 16;<br> |
| gid_t *groups<br> |
| = (gid_t *) xmalloc (ngroups * sizeof (gid_t));<br> |
| struct passwd *pw = getpwnam (user);<br> |
| <br><br> if (pw == NULL)<br> |
| return NULL;<br> |
| <br><br> if (getgrouplist (pw->pw_name, pw->pw_gid, groups, &ngroups) < 0)<br> |
| {<br> |
| groups = xrealloc (ngroups * sizeof (gid_t));<br> |
| getgrouplist (pw->pw_name, pw->pw_gid, groups, &ngroups);<br> |
| }<br> |
| return groups;<br> |
| }<br> |
| <br> |
| </pre> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getlogin" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>getlogin</CODE> function returns a pointer to a string containing the |
| name of the user logged in on the controlling terminal of the process, |
| or a null pointer if this information cannot be determined. The string |
| is statically allocated and might be overwritten on subsequent calls to |
| this function or to <CODE>cuserid</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-cuserid" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="char *string"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>cuserid</CODE> function returns a pointer to a string containing a |
| user name associated with the effective ID of the process. If |
| <VAR>string</VAR> is not a null pointer, it should be an array that can hold |
| at least <CODE>L_cuserid</CODE> characters; the string is returned in this |
| array. Otherwise, a pointer to a string in a static area is returned. |
| This string is statically allocated and might be overwritten on |
| subsequent calls to this function or to <CODE>getlogin</CODE>. |
| <br><br> The use of this function is deprecated since it is marked to be |
| withdrawn in XPG4.2 and has already been removed from newer revisions of |
| POSIX.1. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="struct-exit_status" type="struct"> |
| <structure> |
| <synopsis> |
| The <CODE>exit_status</CODE> data structure is used to hold information about |
| the exit status of processes marked as <CODE>DEAD_PROCESS</CODE> in the user |
| accounting database. |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="short int e_termination"> |
| <synopsis> |
| The exit status of the process. |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="struct-utmp" type="struct"> |
| <structure> |
| <synopsis> |
| The <CODE>utmp</CODE> data structure is used to hold information about entries |
| in the user accounting database. On the GNU system it has the following |
| members: |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="short int ut_type"> |
| <synopsis> |
| Specifies the type of login; one of <CODE>EMPTY</CODE>, <CODE>RUN_LVL</CODE>, |
| <CODE>BOOT_TIME</CODE>, <CODE>OLD_TIME</CODE>, <CODE>NEW_TIME</CODE>, <CODE>INIT_PROCESS</CODE>, |
| <CODE>LOGIN_PROCESS</CODE>, <CODE>USER_PROCESS</CODE>, <CODE>DEAD_PROCESS</CODE> or |
| <CODE>ACCOUNTING</CODE>. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="pid_t ut_pid"> |
| <synopsis> |
| The process ID number of the login process. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="char ut_line[]"> |
| <synopsis> |
| The device name of the tty (without <TT>/dev/</TT>). |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="char ut_id[]"> |
| <synopsis> |
| The inittab ID of the process. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="char ut_user[]"> |
| <synopsis> |
| The user's login name. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="char ut_host[]"> |
| <synopsis> |
| The name of the host from which the user logged in. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="struct exit_status ut_exit"> |
| <synopsis> |
| The exit status of a process marked as <CODE>DEAD_PROCESS</CODE>. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="long ut_session"> |
| <synopsis> |
| The Session ID, used for windowing. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="struct timeval ut_tv"> |
| <synopsis> |
| Time the entry was made. For entries of type <CODE>OLD_TIME</CODE> this is |
| the time when the system clock changed, and for entries of type |
| <CODE>NEW_TIME</CODE> this is the time the system clock was set to. |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="function-setutent" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| <header filename = "utmp.h"/> |
| </headers> |
| <synopsis> |
| This function opens the user accounting database to begin scanning it. |
| You can then call <CODE>getutent</CODE>, <CODE>getutid</CODE> or <CODE>getutline</CODE> to |
| read entries and <CODE>pututline</CODE> to write entries. |
| <br><br> If the database is already open, it resets the input to the beginning of |
| the database. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getutent" type="function"> |
| <function returntype="struct utmp *"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "utmp.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>getutent</CODE> function reads the next entry from the user |
| accounting database. It returns a pointer to the entry, which is |
| statically allocated and may be overwritten by subsequent calls to |
| <CODE>getutent</CODE>. You must copy the contents of the structure if you |
| wish to save the information or you can use the <CODE>getutent_r</CODE> |
| function which stores the data in a user-provided buffer. |
| <br><br> A null pointer is returned in case no further entry is available. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-endutent" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "utmp.h"/> |
| </headers> |
| <synopsis> |
| This function closes the user accounting database. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getutid" type="function"> |
| <function returntype="struct utmp *"> |
| <prototype> |
| <parameter content="const struct utmp *id"/> |
| </prototype> |
| <headers> |
| <header filename = "utmp.h"/> |
| </headers> |
| <synopsis> |
| This function searches forward from the current point in the database |
| for an entry that matches <VAR>id</VAR>. If the <CODE>ut_type</CODE> member of the |
| <VAR>id</VAR> structure is one of <CODE>RUN_LVL</CODE>, <CODE>BOOT_TIME</CODE>, |
| <CODE>OLD_TIME</CODE> or <CODE>NEW_TIME</CODE> the entries match if the |
| <CODE>ut_type</CODE> members are identical. If the <CODE>ut_type</CODE> member of |
| the <VAR>id</VAR> structure is <CODE>INIT_PROCESS</CODE>, <CODE>LOGIN_PROCESS</CODE>, |
| <CODE>USER_PROCESS</CODE> or <CODE>DEAD_PROCESS</CODE>, the entries match if the |
| <CODE>ut_type</CODE> member of the entry read from the database is one of |
| these four, and the <CODE>ut_id</CODE> members match. However if the |
| <CODE>ut_id</CODE> member of either the <VAR>id</VAR> structure or the entry read |
| from the database is empty it checks if the <CODE>ut_line</CODE> members match |
| instead. If a matching entry is found, <CODE>getutid</CODE> returns a pointer |
| to the entry, which is statically allocated, and may be overwritten by a |
| subsequent call to <CODE>getutent</CODE>, <CODE>getutid</CODE> or <CODE>getutline</CODE>. |
| You must copy the contents of the structure if you wish to save the |
| information. |
| <br><br> A null pointer is returned in case the end of the database is reached |
| without a match. |
| <br><br> The <CODE>getutid</CODE> function may cache the last read entry. Therefore, |
| if you are using <CODE>getutid</CODE> to search for multiple occurrences, it |
| is necessary to zero out the static data after each call. Otherwise |
| <CODE>getutid</CODE> could just return a pointer to the same entry over and |
| over again. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getutline" type="function"> |
| <function returntype="struct utmp *"> |
| <prototype> |
| <parameter content="const struct utmp *line"/> |
| </prototype> |
| <headers> |
| <header filename = "utmp.h"/> |
| </headers> |
| <synopsis> |
| This function searches forward from the current point in the database |
| until it finds an entry whose <CODE>ut_type</CODE> value is |
| <CODE>LOGIN_PROCESS</CODE> or <CODE>USER_PROCESS</CODE>, and whose <CODE>ut_line</CODE> |
| member matches the <CODE>ut_line</CODE> member of the <VAR>line</VAR> structure. |
| If it finds such an entry, it returns a pointer to the entry which is |
| statically allocated, and may be overwritten by a subsequent call to |
| <CODE>getutent</CODE>, <CODE>getutid</CODE> or <CODE>getutline</CODE>. You must copy the |
| contents of the structure if you wish to save the information. |
| <br><br> A null pointer is returned in case the end of the database is reached |
| without a match. |
| <br><br> The <CODE>getutline</CODE> function may cache the last read entry. Therefore |
| if you are using <CODE>getutline</CODE> to search for multiple occurrences, it |
| is necessary to zero out the static data after each call. Otherwise |
| <CODE>getutline</CODE> could just return a pointer to the same entry over and |
| over again. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-pututline" type="function"> |
| <function returntype="struct utmp *"> |
| <prototype> |
| <parameter content="const struct utmp *utmp"/> |
| </prototype> |
| <headers> |
| <header filename = "utmp.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>pututline</CODE> function inserts the entry <CODE>*<VAR>utmp</VAR></CODE> at |
| the appropriate place in the user accounting database. If it finds that |
| it is not already at the correct place in the database, it uses |
| <CODE>getutid</CODE> to search for the position to insert the entry, however |
| this will not modify the static structure returned by <CODE>getutent</CODE>, |
| <CODE>getutid</CODE> and <CODE>getutline</CODE>. If this search fails, the entry |
| is appended to the database. |
| <br><br> The <CODE>pututline</CODE> function returns a pointer to a copy of the entry |
| inserted in the user accounting database, or a null pointer if the entry |
| could not be added. The following <CODE>errno</CODE> error conditions are |
| defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EPERM</CODE> |
| <DD> |
| The process does not have the appropriate privileges; you cannot modify |
| the user accounting database. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getutent_r" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="struct utmp *buffer"/> |
| <parameter content="struct utmp **result"/> |
| </prototype> |
| <headers> |
| <header filename = "utmp.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>getutent_r</CODE> is equivalent to the <CODE>getutent</CODE> function. It |
| returns the next entry from the database. But instead of storing the |
| information in a static buffer it stores it in the buffer pointed to by |
| the parameter <VAR>buffer</VAR>. |
| <br><br> If the call was successful, the function returns <CODE>0</CODE> and the |
| pointer variable pointed to by the parameter <VAR>result</VAR> contains a |
| pointer to the buffer which contains the result (this is most probably |
| the same value as <VAR>buffer</VAR>). If something went wrong during the |
| execution of <CODE>getutent_r</CODE> the function returns <CODE>-1</CODE>. |
| <br><br> This function is a GNU extension. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getutid_r" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const struct utmp *id"/> |
| <parameter content="struct utmp *buffer"/> |
| <parameter content="struct utmp **result"/> |
| </prototype> |
| <headers> |
| <header filename = "utmp.h"/> |
| </headers> |
| <synopsis> |
| This function retrieves just like <CODE>getutid</CODE> the next entry matching |
| the information stored in <VAR>id</VAR>. But the result is stored in the |
| buffer pointed to by the parameter <VAR>buffer</VAR>. |
| <br><br> If successful the function returns <CODE>0</CODE> and the pointer variable |
| pointed to by the parameter <VAR>result</VAR> contains a pointer to the |
| buffer with the result (probably the same as <VAR>result</VAR>. If not |
| successful the function return <CODE>-1</CODE>. |
| <br><br> This function is a GNU extension. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getutline_r" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const struct utmp *line"/> |
| <parameter content="struct utmp *buffer"/> |
| <parameter content="struct utmp **result"/> |
| </prototype> |
| <headers> |
| <header filename = "utmp.h"/> |
| </headers> |
| <synopsis> |
| This function retrieves just like <CODE>getutline</CODE> the next entry |
| matching the information stored in <VAR>line</VAR>. But the result is stored |
| in the buffer pointed to by the parameter <VAR>buffer</VAR>. |
| <br><br> If successful the function returns <CODE>0</CODE> and the pointer variable |
| pointed to by the parameter <VAR>result</VAR> contains a pointer to the |
| buffer with the result (probably the same as <VAR>result</VAR>. If not |
| successful the function return <CODE>-1</CODE>. |
| <br><br> This function is a GNU extension. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-utmpname" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *file"/> |
| </prototype> |
| <headers> |
| <header filename = "utmp.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>utmpname</CODE> function changes the name of the database to be |
| examined to <VAR>file</VAR>, and closes any previously opened database. By |
| default <CODE>getutent</CODE>, <CODE>getutid</CODE>, <CODE>getutline</CODE> and |
| <CODE>pututline</CODE> read from and write to the user accounting database. |
| <br><br> The following macros are defined for use as the <VAR>file</VAR> argument: |
| <br><br> Macro {char *} _PATH_UTMP |
| This macro is used to specify the user accounting database. |
| |
| <br><br> Macro {char *} _PATH_WTMP |
| This macro is used to specify the user accounting log file. |
| |
| <br><br> The <CODE>utmpname</CODE> function returns a value of <CODE>0</CODE> if the new name |
| was successfully stored, and a value of <CODE>-1</CODE> to indicate an error. |
| Note that <CODE>utmpname</CODE> does not try to open the database, and that |
| therefore the return value does not say anything about whether the |
| database can be successfully opened. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-updwtmp" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="const char *wtmp_file"/> |
| <parameter content="const struct utmp *utmp"/> |
| </prototype> |
| <headers> |
| <header filename = "utmp.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>updwtmp</CODE> function appends the entry *<VAR>utmp</VAR> to the |
| database specified by <VAR>wtmp_file</VAR>. For possible values for the |
| <VAR>wtmp_file</VAR> argument see the <CODE>utmpname</CODE> function. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="struct-utmpx" type="struct"> |
| <structure> |
| <synopsis> |
| The <CODE>utmpx</CODE> data structure contains at least the following members: |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="short int ut_type"> |
| <synopsis> |
| Specifies the type of login; one of <CODE>EMPTY</CODE>, <CODE>RUN_LVL</CODE>, |
| <CODE>BOOT_TIME</CODE>, <CODE>OLD_TIME</CODE>, <CODE>NEW_TIME</CODE>, <CODE>INIT_PROCESS</CODE>, |
| <CODE>LOGIN_PROCESS</CODE>, <CODE>USER_PROCESS</CODE> or <CODE>DEAD_PROCESS</CODE>. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="pid_t ut_pid"> |
| <synopsis> |
| The process ID number of the login process. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="char ut_line[]"> |
| <synopsis> |
| The device name of the tty (without <TT>/dev/</TT>). |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="char ut_id[]"> |
| <synopsis> |
| The inittab ID of the process. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="char ut_user[]"> |
| <synopsis> |
| The user's login name. |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="function-setutxent" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "utmpx.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to <CODE>setutent</CODE>. On the GNU system it is |
| simply an alias for <CODE>setutent</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getutxent" type="function"> |
| <function returntype="struct utmpx *"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "utmpx.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>getutxent</CODE> function is similar to <CODE>getutent</CODE>, but returns |
| a pointer to a <CODE>struct utmpx</CODE> instead of <CODE>struct utmp</CODE>. On |
| the GNU system it simply is an alias for <CODE>getutent</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-endutxent" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "utmpx.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to <CODE>endutent</CODE>. On the GNU system it is |
| simply an alias for <CODE>endutent</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getutxid" type="function"> |
| <function returntype="struct utmpx *"> |
| <prototype> |
| <parameter content="const struct utmpx *id"/> |
| </prototype> |
| <headers> |
| <header filename = "utmpx.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to <CODE>getutid</CODE>, but uses <CODE>struct utmpx</CODE> |
| instead of <CODE>struct utmp</CODE>. On the GNU system it is simply an alias |
| for <CODE>getutid</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getutxline" type="function"> |
| <function returntype="struct utmpx *"> |
| <prototype> |
| <parameter content="const struct utmpx *line"/> |
| </prototype> |
| <headers> |
| <header filename = "utmpx.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to <CODE>getutid</CODE>, but uses <CODE>struct utmpx</CODE> |
| instead of <CODE>struct utmp</CODE>. On the GNU system it is simply an alias |
| for <CODE>getutline</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-pututxline" type="function"> |
| <function returntype="struct utmpx *"> |
| <prototype> |
| <parameter content="const struct utmpx *utmp"/> |
| </prototype> |
| <headers> |
| <header filename = "utmpx.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>pututxline</CODE> function is functionally identical to |
| <CODE>pututline</CODE>, but uses <CODE>struct utmpx</CODE> instead of <CODE>struct |
| utmp</CODE>. On the GNU system, <CODE>pututxline</CODE> is simply an alias for |
| <CODE>pututline</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-utmpxname" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *file"/> |
| </prototype> |
| <headers> |
| <header filename = "utmpx.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>utmpxname</CODE> function is functionally identical to |
| <CODE>utmpname</CODE>. On the GNU system, <CODE>utmpxname</CODE> is simply an |
| alias for <CODE>utmpname</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getutmp" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const struct utmpx *utmpx"/> |
| <parameter content="struct utmp *utmp"/> |
| </prototype> |
| <headers> |
| <header filename = "utmpx.h"/> |
| <header filename = "utmp.h"/> |
| </headers> |
| <synopsis> |
| <CODE>getutmp</CODE> copies the information, insofar as the structures are |
| compatible, from <VAR>utmpx</VAR> to <VAR>utmp</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getutmpx" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const struct utmp *utmp"/> |
| <parameter content="struct utmpx *utmpx"/> |
| </prototype> |
| <headers> |
| <header filename = "utmpx.h"/> |
| <header filename = "utmp.h"/> |
| </headers> |
| <synopsis> |
| <CODE>getutmpx</CODE> copies the information, insofar as the structures are |
| compatible, from <VAR>utmp</VAR> to <VAR>utmpx</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-login_tty" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int filedes"/> |
| </prototype> |
| <headers> |
| <header filename = "utmp.h"/> |
| </headers> |
| <synopsis> |
| This function makes <VAR>filedes</VAR> the controlling terminal of the |
| current process, redirects standard input, standard output and |
| standard error output to this terminal, and closes <VAR>filedes</VAR>. |
| <br><br> This function returns <CODE>0</CODE> on successful completion, and <CODE>-1</CODE> |
| on error. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-login" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="const struct utmp *entry"/> |
| </prototype> |
| <headers> |
| <header filename = "utmp.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>login</CODE> functions inserts an entry into the user accounting |
| database. The <CODE>ut_line</CODE> member is set to the name of the terminal |
| on standard input. If standard input is not a terminal <CODE>login</CODE> |
| uses standard output or standard error output to determine the name of |
| the terminal. If <CODE>struct utmp</CODE> has a <CODE>ut_type</CODE> member, |
| <CODE>login</CODE> sets it to <CODE>USER_PROCESS</CODE>, and if there is an |
| <CODE>ut_pid</CODE> member, it will be set to the process ID of the current |
| process. The remaining entries are copied from <VAR>entry</VAR>. |
| <br><br> A copy of the entry is written to the user accounting log file. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-logout" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *ut_line"/> |
| </prototype> |
| <headers> |
| <header filename = "utmp.h"/> |
| </headers> |
| <synopsis> |
| This function modifies the user accounting database to indicate that the |
| user on <VAR>ut_line</VAR> has logged out. |
| <br><br> The <CODE>logout</CODE> function returns <CODE>1</CODE> if the entry was successfully |
| written to the database, or <CODE>0</CODE> on error. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-logwtmp" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="const char *ut_line"/> |
| <parameter content="const char *ut_name"/> |
| <parameter content="const char *ut_host"/> |
| </prototype> |
| <headers> |
| <header filename = "utmp.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>logwtmp</CODE> function appends an entry to the user accounting log |
| file, for the current time and the information provided in the |
| <VAR>ut_line</VAR>, <VAR>ut_name</VAR> and <VAR>ut_host</VAR> arguments. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="struct-passwd" type="struct"> |
| <structure> |
| <synopsis> |
| The <CODE>passwd</CODE> data structure is used to hold information about |
| entries in the system user data base. It has at least the following members: |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="char *pw_name"> |
| <synopsis> |
| The user's login name. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="char *pw_passwd."> |
| <synopsis> |
| The encrypted password string. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="uid_t pw_uid"> |
| <synopsis> |
| The user ID number. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="gid_t pw_gid"> |
| <synopsis> |
| The user's default group ID number. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="char *pw_gecos"> |
| <synopsis> |
| A string typically containing the user's real name, and possibly other |
| information such as a phone number. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="char *pw_dir"> |
| <synopsis> |
| The user's home directory, or initial working directory. This might be |
| a null pointer, in which case the interpretation is system-dependent. |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="function-getpwuid" type="function"> |
| <function returntype="struct passwd *"> |
| <prototype> |
| <parameter content="uid_t uid"/> |
| </prototype> |
| <headers> |
| <header filename = "pwd.h"/> |
| </headers> |
| <synopsis> |
| This function returns a pointer to a statically-allocated structure |
| containing information about the user whose user ID is <VAR>uid</VAR>. This |
| structure may be overwritten on subsequent calls to <CODE>getpwuid</CODE>. |
| <br><br> A null pointer value indicates there is no user in the data base with |
| user ID <VAR>uid</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getpwuid_r" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="uid_t uid"/> |
| <parameter content="struct passwd *result_buf"/> |
| <parameter content="char *buffer"/> |
| <parameter content="size_t buflen"/> |
| <parameter content="struct passwd **result"/> |
| </prototype> |
| <headers> |
| <header filename = "pwd.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to <CODE>getpwuid</CODE> in that it returns |
| information about the user whose user ID is <VAR>uid</VAR>. However, it |
| fills the user supplied structure pointed to by <VAR>result_buf</VAR> with |
| the information instead of using a static buffer. The first |
| <VAR>buflen</VAR> bytes of the additional buffer pointed to by <VAR>buffer</VAR> |
| are used to contain additional information, normally strings which are |
| pointed to by the elements of the result structure. |
| <br><br> If a user with ID <VAR>uid</VAR> is found, the pointer returned in |
| <VAR>result</VAR> points to the record which contains the wanted data (i.e., |
| <VAR>result</VAR> contains the value <VAR>result_buf</VAR>). If no user is found |
| or if an error occurred, the pointer returned in <VAR>result</VAR> is a null |
| pointer. The function returns zero or an error code. If the buffer |
| <VAR>buffer</VAR> is too small to contain all the needed information, the |
| error code <CODE>ERANGE</CODE> is returned and <VAR>errno</VAR> is set to |
| <CODE>ERANGE</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getpwnam" type="function"> |
| <function returntype="struct passwd *"> |
| <prototype> |
| <parameter content="const char *name"/> |
| </prototype> |
| <headers> |
| <header filename = "pwd.h"/> |
| </headers> |
| <synopsis> |
| This function returns a pointer to a statically-allocated structure |
| containing information about the user whose user name is <VAR>name</VAR>. |
| This structure may be overwritten on subsequent calls to |
| <CODE>getpwnam</CODE>. |
| <br><br> A null pointer return indicates there is no user named <VAR>name</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getpwnam_r" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *name"/> |
| <parameter content="struct passwd *result_buf"/> |
| <parameter content="char *buffer"/> |
| <parameter content="size_t buflen"/> |
| <parameter content="struct passwd **result"/> |
| </prototype> |
| <headers> |
| <header filename = "pwd.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to <CODE>getpwnam</CODE> in that is returns |
| information about the user whose user name is <VAR>name</VAR>. However, like |
| <CODE>getpwuid_r</CODE>, it fills the user supplied buffers in |
| <VAR>result_buf</VAR> and <VAR>buffer</VAR> with the information instead of using |
| a static buffer. |
| <br><br> The return values are the same as for <CODE>getpwuid_r</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fgetpwent" type="function"> |
| <function returntype="struct passwd *"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "pwd.h"/> |
| </headers> |
| <synopsis> |
| This function reads the next user entry from <VAR>stream</VAR> and returns a |
| pointer to the entry. The structure is statically allocated and is |
| rewritten on subsequent calls to <CODE>fgetpwent</CODE>. You must copy the |
| contents of the structure if you wish to save the information. |
| <br><br> The stream must correspond to a file in the same format as the standard |
| password database file. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fgetpwent_r" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| <parameter content="struct passwd *result_buf"/> |
| <parameter content="char *buffer"/> |
| <parameter content="size_t buflen"/> |
| <parameter content="struct passwd **result"/> |
| </prototype> |
| <headers> |
| <header filename = "pwd.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to <CODE>fgetpwent</CODE> in that it reads the next |
| user entry from <VAR>stream</VAR>. But the result is returned in the |
| structure pointed to by <VAR>result_buf</VAR>. The |
| first <VAR>buflen</VAR> bytes of the additional buffer pointed to by |
| <VAR>buffer</VAR> are used to contain additional information, normally |
| strings which are pointed to by the elements of the result structure. |
| <br><br> The stream must correspond to a file in the same format as the standard |
| password database file. |
| <br><br> If the function returns zero <VAR>result</VAR> points to the structure with |
| the wanted data (normally this is in <VAR>result_buf</VAR>). If errors |
| occurred the return value is nonzero and <VAR>result</VAR> contains a null |
| pointer. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-setpwent" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "pwd.h"/> |
| </headers> |
| <synopsis> |
| This function initializes a stream which <CODE>getpwent</CODE> and |
| <CODE>getpwent_r</CODE> use to read the user database. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getpwent" type="function"> |
| <function returntype="struct passwd *"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "pwd.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>getpwent</CODE> function reads the next entry from the stream |
| initialized by <CODE>setpwent</CODE>. It returns a pointer to the entry. The |
| structure is statically allocated and is rewritten on subsequent calls |
| to <CODE>getpwent</CODE>. You must copy the contents of the structure if you |
| wish to save the information. |
| <br><br> A null pointer is returned when no more entries are available. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getpwent_r" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="struct passwd *result_buf"/> |
| <parameter content="char *buffer"/> |
| <parameter content="int buflen"/> |
| <parameter content="struct passwd **result"/> |
| </prototype> |
| <headers> |
| <header filename = "pwd.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to <CODE>getpwent</CODE> in that it returns the next |
| entry from the stream initialized by <CODE>setpwent</CODE>. Like |
| <CODE>fgetpwent_r</CODE>, it uses the user-supplied buffers in |
| <VAR>result_buf</VAR> and <VAR>buffer</VAR> to return the information requested. |
| <br><br> The return values are the same as for <CODE>fgetpwent_r</CODE>. |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-endpwent" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "pwd.h"/> |
| </headers> |
| <synopsis> |
| This function closes the internal stream used by <CODE>getpwent</CODE> or |
| <CODE>getpwent_r</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-putpwent" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const struct passwd *p"/> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "pwd.h"/> |
| </headers> |
| <synopsis> |
| This function writes the user entry <CODE>*<VAR>p</VAR></CODE> to the stream |
| <VAR>stream</VAR>, in the format used for the standard user database |
| file. The return value is zero on success and nonzero on failure. |
| <br><br> This function exists for compatibility with SVID. We recommend that you |
| avoid using it, because it makes sense only on the assumption that the |
| <CODE>struct passwd</CODE> structure has no members except the standard ones; |
| on a system which merges the traditional Unix data base with other |
| extended information about users, adding an entry using this function |
| would inevitably leave out much of the important information. |
| <br><br> The group and user ID fields are left empty if the group or user name |
| starts with a - or +. |
| <br><br> The function <CODE>putpwent</CODE> is declared in <TT>pwd.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="struct-group" type="struct"> |
| <structure> |
| <synopsis> |
| The <CODE>group</CODE> structure is used to hold information about an entry in |
| the system group database. It has at least the following members: |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="char *gr_name"> |
| <synopsis> |
| The name of the group. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="gid_t gr_gid"> |
| <synopsis> |
| The group ID of the group. |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="function-getgrgid" type="function"> |
| <function returntype="struct group *"> |
| <prototype> |
| <parameter content="gid_t gid"/> |
| </prototype> |
| <headers> |
| <header filename = "grp.h"/> |
| </headers> |
| <synopsis> |
| This function returns a pointer to a statically-allocated structure |
| containing information about the group whose group ID is <VAR>gid</VAR>. |
| This structure may be overwritten by subsequent calls to |
| <CODE>getgrgid</CODE>. |
| <br><br> A null pointer indicates there is no group with ID <VAR>gid</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getgrgid_r" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="gid_t gid"/> |
| <parameter content="struct group *result_buf"/> |
| <parameter content="char *buffer"/> |
| <parameter content="size_t buflen"/> |
| <parameter content="struct group **result"/> |
| </prototype> |
| <headers> |
| <header filename = "grp.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to <CODE>getgrgid</CODE> in that it returns |
| information about the group whose group ID is <VAR>gid</VAR>. However, it |
| fills the user supplied structure pointed to by <VAR>result_buf</VAR> with |
| the information instead of using a static buffer. The first |
| <VAR>buflen</VAR> bytes of the additional buffer pointed to by <VAR>buffer</VAR> |
| are used to contain additional information, normally strings which are |
| pointed to by the elements of the result structure. |
| <br><br> If a group with ID <VAR>gid</VAR> is found, the pointer returned in |
| <VAR>result</VAR> points to the record which contains the wanted data (i.e., |
| <VAR>result</VAR> contains the value <VAR>result_buf</VAR>). If no group is found |
| or if an error occurred, the pointer returned in <VAR>result</VAR> is a null |
| pointer. The function returns zero or an error code. If the buffer |
| <VAR>buffer</VAR> is too small to contain all the needed information, the |
| error code <CODE>ERANGE</CODE> is returned and <VAR>errno</VAR> is set to |
| <CODE>ERANGE</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getgrnam" type="function"> |
| <function returntype="struct group *"> |
| <prototype> |
| <parameter content="const char *name"/> |
| </prototype> |
| <headers> |
| <header filename = "grp.h"/> |
| </headers> |
| <synopsis> |
| This function returns a pointer to a statically-allocated structure |
| containing information about the group whose group name is <VAR>name</VAR>. |
| This structure may be overwritten by subsequent calls to |
| <CODE>getgrnam</CODE>. |
| <br><br> A null pointer indicates there is no group named <VAR>name</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getgrnam_r" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *name"/> |
| <parameter content="struct group *result_buf"/> |
| <parameter content="char *buffer"/> |
| <parameter content="size_t buflen"/> |
| <parameter content="struct group **result"/> |
| </prototype> |
| <headers> |
| <header filename = "grp.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to <CODE>getgrnam</CODE> in that is returns |
| information about the group whose group name is <VAR>name</VAR>. Like |
| <CODE>getgrgid_r</CODE>, it uses the user supplied buffers in |
| <VAR>result_buf</VAR> and <VAR>buffer</VAR>, not a static buffer. |
| <br><br> The return values are the same as for <CODE>getgrgid_r</CODE> |
| <CODE>ERANGE</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fgetgrent" type="function"> |
| <function returntype="struct group *"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "grp.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>fgetgrent</CODE> function reads the next entry from <VAR>stream</VAR>. |
| It returns a pointer to the entry. The structure is statically |
| allocated and is overwritten on subsequent calls to <CODE>fgetgrent</CODE>. You |
| must copy the contents of the structure if you wish to save the |
| information. |
| <br><br> The stream must correspond to a file in the same format as the standard |
| group database file. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fgetgrent_r" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| <parameter content="struct group *result_buf"/> |
| <parameter content="char *buffer"/> |
| <parameter content="size_t buflen"/> |
| <parameter content="struct group **result"/> |
| </prototype> |
| <headers> |
| <header filename = "grp.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to <CODE>fgetgrent</CODE> in that it reads the next |
| user entry from <VAR>stream</VAR>. But the result is returned in the |
| structure pointed to by <VAR>result_buf</VAR>. The first <VAR>buflen</VAR> bytes |
| of the additional buffer pointed to by <VAR>buffer</VAR> are used to contain |
| additional information, normally strings which are pointed to by the |
| elements of the result structure. |
| <br><br> This stream must correspond to a file in the same format as the standard |
| group database file. |
| <br><br> If the function returns zero <VAR>result</VAR> points to the structure with |
| the wanted data (normally this is in <VAR>result_buf</VAR>). If errors |
| occurred the return value is non-zero and <VAR>result</VAR> contains a null |
| pointer. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-setgrent" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "grp.h"/> |
| </headers> |
| <synopsis> |
| This function initializes a stream for reading from the group data base. |
| You use this stream by calling <CODE>getgrent</CODE> or <CODE>getgrent_r</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getgrent" type="function"> |
| <function returntype="struct group *"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "grp.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>getgrent</CODE> function reads the next entry from the stream |
| initialized by <CODE>setgrent</CODE>. It returns a pointer to the entry. The |
| structure is statically allocated and is overwritten on subsequent calls |
| to <CODE>getgrent</CODE>. You must copy the contents of the structure if you |
| wish to save the information. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getgrent_r" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="struct group *result_buf"/> |
| <parameter content="char *buffer"/> |
| <parameter content="size_t buflen"/> |
| <parameter content="struct group **result"/> |
| </prototype> |
| <headers> |
| <header filename = "grp.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to <CODE>getgrent</CODE> in that it returns the next |
| entry from the stream initialized by <CODE>setgrent</CODE>. Like |
| <CODE>fgetgrent_r</CODE>, it places the result in user-supplied buffers |
| pointed to <VAR>result_buf</VAR> and <VAR>buffer</VAR>. |
| <br><br> If the function returns zero <VAR>result</VAR> contains a pointer to the data |
| (normally equal to <VAR>result_buf</VAR>). If errors occurred the return |
| value is non-zero and <VAR>result</VAR> contains a null pointer. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-endgrent" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "grp.h"/> |
| </headers> |
| <synopsis> |
| This function closes the internal stream used by <CODE>getgrent</CODE> or |
| <CODE>getgrent_r</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-setnetgrent" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *netgroup"/> |
| </prototype> |
| <headers> |
| <header filename = "netdb.h"/> |
| </headers> |
| <synopsis> |
| A call to this function initializes the internal state of the library to |
| allow following calls of the <CODE>getnetgrent</CODE> to iterate over all entries |
| in the netgroup with name <VAR>netgroup</VAR>. |
| <br><br> When the call is successful (i.e., when a netgroup with this name exists) |
| the return value is <CODE>1</CODE>. When the return value is <CODE>0</CODE> no |
| netgroup of this name is known or some other error occurred. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getnetgrent" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="char **hostp"/> |
| <parameter content="char **userp"/> |
| <parameter content="char **domainp"/> |
| </prototype> |
| <headers> |
| <header filename = "netdb.h"/> |
| </headers> |
| <synopsis> |
| This function returns the next unprocessed entry of the currently |
| selected netgroup. The string pointers, in which addresses are passed in |
| the arguments <VAR>hostp</VAR>, <VAR>userp</VAR>, and <VAR>domainp</VAR>, will contain |
| after a successful call pointers to appropriate strings. If the string |
| in the next entry is empty the pointer has the value <CODE>NULL</CODE>. |
| The returned string pointers are only valid if none of the netgroup |
| related functions are called. |
| <br><br> The return value is <CODE>1</CODE> if the next entry was successfully read. A |
| value of <CODE>0</CODE> means no further entries exist or internal errors occurred. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getnetgrent_r" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="char **hostp"/> |
| <parameter content="char **userp"/> |
| <parameter content="char **domainp"/> |
| <parameter content="char *buffer"/> |
| <parameter content="int buflen"/> |
| </prototype> |
| <headers> |
| <header filename = "netdb.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to <CODE>getnetgrent</CODE> with only one exception: |
| the strings the three string pointers <VAR>hostp</VAR>, <VAR>userp</VAR>, and |
| <VAR>domainp</VAR> point to, are placed in the buffer of <VAR>buflen</VAR> bytes |
| starting at <VAR>buffer</VAR>. This means the returned values are valid |
| even after other netgroup related functions are called. |
| <br><br> The return value is <CODE>1</CODE> if the next entry was successfully read and |
| the buffer contains enough room to place the strings in it. <CODE>0</CODE> is |
| returned in case no more entries are found, the buffer is too small, or |
| internal errors occurred. |
| <br><br> This function is a GNU extension. The original implementation in the |
| SunOS libc does not provide this function. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-endnetgrent" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "netdb.h"/> |
| </headers> |
| <synopsis> |
| This function frees all buffers which were allocated to process the last |
| selected netgroup. As a result all string pointers returned by calls |
| to <CODE>getnetgrent</CODE> are invalid afterwards. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-innetgr" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *netgroup"/> |
| <parameter content="const char *host"/> |
| <parameter content="const char *user"/> |
| <parameter content="const char *domain"/> |
| </prototype> |
| <headers> |
| <header filename = "netdb.h"/> |
| </headers> |
| <synopsis> |
| This function tests whether the triple specified by the parameters |
| <VAR>hostp</VAR>, <VAR>userp</VAR>, and <VAR>domainp</VAR> is part of the netgroup |
| <VAR>netgroup</VAR>. Using this function has the advantage that |
| <br><br> <OL> |
| <LI> |
| no other netgroup function can use the global netgroup state since |
| internal locking is used and |
| <LI> |
| the function is implemented more efficiently than successive calls |
| to the other <CODE>set</CODE>/<CODE>get</CODE>/<CODE>endnetgrent</CODE> functions. |
| </OL> |
| <br><br> Any of the pointers <VAR>hostp</VAR>, <VAR>userp</VAR>, and <VAR>domainp</VAR> can be |
| <CODE>NULL</CODE> which means any value is accepted in this position. This is |
| also true for the name <CODE>-</CODE> which should not match any other string |
| otherwise. |
| <br><br> The return value is <CODE>1</CODE> if an entry matching the given triple is |
| found in the netgroup. The return value is <CODE>0</CODE> if the netgroup |
| itself is not found, the netgroup does not contain the triple or |
| internal errors occurred. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="struct-sockaddr" type="struct"> |
| <structure> |
| <synopsis> |
| The <CODE>struct sockaddr</CODE> type itself has the following members: |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="short int sa_family"> |
| <synopsis> |
| This is the code for the address format of this address. It |
| identifies the format of the data which follows. |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="function-bind" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int socket"/> |
| <parameter content="struct sockaddr *addr"/> |
| <parameter content="socklen_t length"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/socket.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>bind</CODE> function assigns an address to the socket |
| <VAR>socket</VAR>. The <VAR>addr</VAR> and <VAR>length</VAR> arguments specify the |
| address; the detailed format of the address depends on the namespace. |
| The first part of the address is always the format designator, which |
| specifies a namespace, and says that the address is in the format of |
| that namespace. |
| <br><br> The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on failure. The |
| following <CODE>errno</CODE> error conditions are defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EBADF</CODE> |
| <DD> |
| The <VAR>socket</VAR> argument is not a valid file descriptor. |
| <br><br> <LI> ENOTSOCK |
| The descriptor <VAR>socket</VAR> is not a socket. |
| <br><br> <LI> EADDRNOTAVAIL |
| The specified address is not available on this machine. |
| <br><br> <LI> EADDRINUSE |
| Some other socket is already using the specified address. |
| <br><br> <LI> EINVAL |
| The socket <VAR>socket</VAR> already has an address. |
| <br><br> <LI> EACCES |
| You do not have permission to access the requested address. (In the |
| Internet domain, only the super-user is allowed to specify a port number |
| in the range 0 through <CODE>IPPORT_RESERVED</CODE> minus one; see |
| Ports.) |
| |
| <br><br> Additional conditions may be possible depending on the particular namespace |
| of the socket. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getsockname" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int socket"/> |
| <parameter content="struct sockaddr *addr"/> |
| <parameter content="socklen_t *length-ptr"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/socket.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>getsockname</CODE> function returns information about the |
| address of the socket <VAR>socket</VAR> in the locations specified by the |
| <VAR>addr</VAR> and <VAR>length-ptr</VAR> arguments. Note that the |
| <VAR>length-ptr</VAR> is a pointer; you should initialize it to be the |
| allocation size of <VAR>addr</VAR>, and on return it contains the actual |
| size of the address data. |
| <br><br> The format of the address data depends on the socket namespace. The |
| length of the information is usually fixed for a given namespace, so |
| normally you can know exactly how much space is needed and can provide |
| that much. The usual practice is to allocate a place for the value |
| using the proper data type for the socket's namespace, then cast its |
| address to <CODE>struct sockaddr *</CODE> to pass it to <CODE>getsockname</CODE>. |
| <br><br> The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on error. The |
| following <CODE>errno</CODE> error conditions are defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EBADF</CODE> |
| <DD> |
| The <VAR>socket</VAR> argument is not a valid file descriptor. |
| <br><br> <LI> ENOTSOCK |
| The descriptor <VAR>socket</VAR> is not a socket. |
| <br><br> <LI> ENOBUFS |
| There are not enough internal buffers available for the operation. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-if_nametoindex" type="function"> |
| <function returntype="unsigned int"> |
| <prototype> |
| <parameter content="const char *ifname"/> |
| </prototype> |
| <headers> |
| <header filename = "net/if.h"/> |
| </headers> |
| <synopsis> |
| This function yields the interface index corresponding to a particular |
| name. If no interface exists with the name given, it returns 0. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-if_indextoname" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="unsigned int ifindex"/> |
| <parameter content="char *ifname"/> |
| </prototype> |
| <headers> |
| <header filename = "net/if.h"/> |
| </headers> |
| <synopsis> |
| This function maps an interface index to its corresponding name. The |
| returned name is placed in the buffer pointed to by <CODE>ifname</CODE>, which |
| must be at least <CODE>IFNAMSIZ</CODE> bytes in length. If the index was |
| invalid, the function's return value is a null pointer, otherwise it is |
| <CODE>ifname</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="struct-if_nameindex" type="struct"> |
| <structure> |
| <synopsis> |
| This data type is used to hold the information about a single |
| interface. It has the following members: |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="unsigned int if_index;"> |
| <synopsis> |
| This is the interface index. |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="function-if_nameindex" type="function"> |
| <function returntype="struct if_nameindex *"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "net/if.h"/> |
| </headers> |
| <synopsis> |
| This function returns an array of <CODE>if_nameindex</CODE> structures, one |
| for every interface that is present. The end of the list is indicated |
| by a structure with an interface of 0 and a null name pointer. If an |
| error occurs, this function returns a null pointer. |
| <br><br> The returned structure must be freed with <CODE>if_freenameindex</CODE> after |
| use. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-if_freenameindex" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="struct if_nameindex *ptr"/> |
| </prototype> |
| <headers> |
| <header filename = "net/if.h"/> |
| </headers> |
| <synopsis> |
| This function frees the structure returned by an earlier call to |
| <CODE>if_nameindex</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="struct-sockaddr_un" type="struct"> |
| <structure> |
| <synopsis> |
| This structure is used to specify local namespace socket addresses. It has |
| the following members: |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="short int sun_family"> |
| <synopsis> |
| This identifies the address family or format of the socket address. |
| You should store the value <CODE>AF_LOCAL</CODE> to designate the local |
| namespace. . |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="struct-sockaddr_in" type="struct"> |
| <structure> |
| <synopsis> |
| This is the data type used to represent socket addresses in the |
| Internet namespace. It has the following members: |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="sa_family_t sin_family"> |
| <synopsis> |
| This identifies the address family or format of the socket address. |
| You should store the value <CODE>AF_INET</CODE> in this member. |
| . |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="struct in_addr sin_addr"> |
| <synopsis> |
| This is the Internet address of the host machine. , and Host Names, for how to get a value to store |
| here. |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="struct-sockaddr_in6" type="struct"> |
| <structure> |
| <synopsis> |
| This is the data type used to represent socket addresses in the IPv6 |
| namespace. It has the following members: |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="sa_family_t sin6_family"> |
| <synopsis> |
| This identifies the address family or format of the socket address. |
| You should store the value of <CODE>AF_INET6</CODE> in this member. |
| . |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="struct in6_addr sin6_addr"> |
| <synopsis> |
| This is the IPv6 address of the host machine. , and Host Names, for how to get a value to store |
| here. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="uint32_t sin6_flowinfo"> |
| <synopsis> |
| This is a currently unimplemented field. |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="struct-in_addr" type="struct"> |
| <structure> |
| </structure> |
| </construct> |
| <construct id="struct-in6_addr" type="struct"> |
| <structure> |
| </structure> |
| </construct> |
| <construct id="function-inet_aton" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *name"/> |
| <parameter content="struct in_addr *addr"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/socket.h"/> |
| <header filename = "netinet/in.h"/> |
| <header filename = "arpa/inet.h"/> |
| </headers> |
| <synopsis> |
| This function converts the IPv4 Internet host address <VAR>name</VAR> |
| from the standard numbers-and-dots notation into binary data and stores |
| it in the <CODE>struct in_addr</CODE> that <VAR>addr</VAR> points to. |
| <CODE>inet_aton</CODE> returns nonzero if the address is valid, zero if not. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-inet_addr" type="function"> |
| <function returntype="uint32_t"> |
| <prototype> |
| <parameter content="const char *name"/> |
| </prototype> |
| <headers> |
| <header filename = "arpa/inet.h"/> |
| </headers> |
| <synopsis> |
| This function converts the IPv4 Internet host address <VAR>name</VAR> from the |
| standard numbers-and-dots notation into binary data. If the input is |
| not valid, <CODE>inet_addr</CODE> returns <CODE>INADDR_NONE</CODE>. This is an |
| obsolete interface to <CODE>inet_aton</CODE>, described immediately above. It |
| is obsolete because <CODE>INADDR_NONE</CODE> is a valid address |
| (255.255.255.255), and <CODE>inet_aton</CODE> provides a cleaner way to |
| indicate error return. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-inet_network" type="function"> |
| <function returntype="uint32_t"> |
| <prototype> |
| <parameter content="const char *name"/> |
| </prototype> |
| <headers> |
| <header filename = "arpa/inet.h"/> |
| </headers> |
| <synopsis> |
| This function extracts the network number from the address <VAR>name</VAR>, |
| given in the standard numbers-and-dots notation. The returned address is |
| in host order. If the input is not valid, <CODE>inet_network</CODE> returns |
| <CODE>-1</CODE>. |
| <br><br> The function works only with traditional IPv4 class A, B and C network |
| types. It doesn't work with classless addresses and shouldn't be used |
| anymore. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-inet_ntoa" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="struct in_addr addr"/> |
| </prototype> |
| <headers> |
| <header filename = "arpa/inet.h"/> |
| </headers> |
| <synopsis> |
| This function converts the IPv4 Internet host address <VAR>addr</VAR> to a |
| string in the standard numbers-and-dots notation. The return value is |
| a pointer into a statically-allocated buffer. Subsequent calls will |
| overwrite the same buffer, so you should copy the string if you need |
| to save it. |
| <br><br> In multi-threaded programs each thread has an own statically-allocated |
| buffer. But still subsequent calls of <CODE>inet_ntoa</CODE> in the same |
| thread will overwrite the result of the last call. |
| <br><br> Instead of <CODE>inet_ntoa</CODE> the newer function <CODE>inet_ntop</CODE> which is |
| described below should be used since it handles both IPv4 and IPv6 |
| addresses. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-inet_makeaddr" type="function"> |
| <function returntype="struct in_addr"> |
| <prototype> |
| <parameter content="uint32_t net"/> |
| <parameter content="uint32_t local"/> |
| </prototype> |
| <headers> |
| <header filename = "arpa/inet.h"/> |
| </headers> |
| <synopsis> |
| This function makes an IPv4 Internet host address by combining the network |
| number <VAR>net</VAR> with the local-address-within-network number |
| <VAR>local</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-inet_lnaof" type="function"> |
| <function returntype="uint32_t"> |
| <prototype> |
| <parameter content="struct in_addr addr"/> |
| </prototype> |
| <headers> |
| <header filename = "arpa/inet.h"/> |
| </headers> |
| <synopsis> |
| This function returns the local-address-within-network part of the |
| Internet host address <VAR>addr</VAR>. |
| <br><br> The function works only with traditional IPv4 class A, B and C network |
| types. It doesn't work with classless addresses and shouldn't be used |
| anymore. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-inet_netof" type="function"> |
| <function returntype="uint32_t"> |
| <prototype> |
| <parameter content="struct in_addr addr"/> |
| </prototype> |
| <headers> |
| <header filename = "arpa/inet.h"/> |
| </headers> |
| <synopsis> |
| This function returns the network number part of the Internet host |
| address <VAR>addr</VAR>. |
| <br><br> The function works only with traditional IPv4 class A, B and C network |
| types. It doesn't work with classless addresses and shouldn't be used |
| anymore. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-inet_pton" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int af"/> |
| <parameter content="const char *cp"/> |
| <parameter content="void *buf"/> |
| </prototype> |
| <headers> |
| <header filename = "arpa/inet.h"/> |
| </headers> |
| <synopsis> |
| This function converts an Internet address (either IPv4 or IPv6) from |
| presentation (textual) to network (binary) format. <VAR>af</VAR> should be |
| either <CODE>AF_INET</CODE> or <CODE>AF_INET6</CODE>, as appropriate for the type of |
| address being converted. <VAR>cp</VAR> is a pointer to the input string, and |
| <VAR>buf</VAR> is a pointer to a buffer for the result. It is the caller's |
| responsibility to make sure the buffer is large enough. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-inet_ntop" type="function"> |
| <function returntype="const char *"> |
| <prototype> |
| <parameter content="int af"/> |
| <parameter content="const void *cp"/> |
| <parameter content="char *buf"/> |
| <parameter content="size_t len"/> |
| </prototype> |
| <headers> |
| <header filename = "arpa/inet.h"/> |
| </headers> |
| <synopsis> |
| This function converts an Internet address (either IPv4 or IPv6) from |
| network (binary) to presentation (textual) form. <VAR>af</VAR> should be |
| either <CODE>AF_INET</CODE> or <CODE>AF_INET6</CODE>, as appropriate. <VAR>cp</VAR> is a |
| pointer to the address to be converted. <VAR>buf</VAR> should be a pointer |
| to a buffer to hold the result, and <VAR>len</VAR> is the length of this |
| buffer. The return value from the function will be this buffer address. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="struct-hostent" type="struct"> |
| <structure> |
| <synopsis> |
| This data type is used to represent an entry in the hosts database. It |
| has the following members: |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="char *h_name"> |
| <synopsis> |
| This is the ``official'' name of the host. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="char **h_aliases"> |
| <synopsis> |
| These are alternative names for the host, represented as a null-terminated |
| vector of strings. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="int h_addrtype"> |
| <synopsis> |
| This is the host address type; in practice, its value is always either |
| <CODE>AF_INET</CODE> or <CODE>AF_INET6</CODE>, 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 <CODE>AF_INET</CODE> or |
| <CODE>AF_INET6</CODE>. . |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="int h_length"> |
| <synopsis> |
| This is the length, in bytes, of each address. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="char **h_addr_list"> |
| <synopsis> |
| This is the vector of addresses for the host. (Recall that the host |
| might be connected to multiple networks and have different addresses on |
| each one.) The vector is terminated by a null pointer. |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="function-gethostbyname" type="function"> |
| <function returntype="struct hostent *"> |
| <prototype> |
| <parameter content="const char *name"/> |
| </prototype> |
| <headers> |
| <header filename = "netdb.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>gethostbyname</CODE> function returns information about the host |
| named <VAR>name</VAR>. If the lookup fails, it returns a null pointer. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-gethostbyname2" type="function"> |
| <function returntype="struct hostent *"> |
| <prototype> |
| <parameter content="const char *name"/> |
| <parameter content="int af"/> |
| </prototype> |
| <headers> |
| <header filename = "netdb.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>gethostbyname2</CODE> function is like <CODE>gethostbyname</CODE>, but |
| allows the caller to specify the desired address family (e.g.: |
| <CODE>AF_INET</CODE> or <CODE>AF_INET6</CODE>) of the result. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-gethostbyaddr" type="function"> |
| <function returntype="struct hostent *"> |
| <prototype> |
| <parameter content="const char *addr"/> |
| <parameter content="size_t length"/> |
| <parameter content="int format"/> |
| </prototype> |
| <headers> |
| <header filename = "netdb.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>gethostbyaddr</CODE> function returns information about the host |
| with Internet address <VAR>addr</VAR>. The parameter <VAR>addr</VAR> is not |
| really a pointer to char - it can be a pointer to an IPv4 or an IPv6 |
| address. The <VAR>length</VAR> argument is the size (in bytes) of the address |
| at <VAR>addr</VAR>. <VAR>format</VAR> specifies the address format; for an IPv4 |
| Internet address, specify a value of <CODE>AF_INET</CODE>; for an IPv6 |
| Internet address, use <CODE>AF_INET6</CODE>. |
| <br><br> If the lookup fails, <CODE>gethostbyaddr</CODE> returns a null pointer. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-gethostbyname_r" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *restrict name"/> |
| <parameter content="struct hostent *restrict result_buf"/> |
| <parameter content="char *restrict buf"/> |
| <parameter content="size_t buflen"/> |
| <parameter content="struct hostent **restrict result"/> |
| <parameter content="int *restrict h_errnop"/> |
| </prototype> |
| <headers> |
| <header filename = "netdb.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>gethostbyname_r</CODE> function returns information about the host |
| named <VAR>name</VAR>. The caller must pass a pointer to an object of type |
| <CODE>struct hostent</CODE> in the <VAR>result_buf</VAR> parameter. In addition |
| the function may need extra buffer space and the caller must pass an |
| pointer and the size of the buffer in the <VAR>buf</VAR> and <VAR>buflen</VAR> |
| parameters. |
| <br><br> A pointer to the buffer, in which the result is stored, is available in |
| <CODE>*<VAR>result</VAR></CODE> after the function call successfully returned. If |
| an error occurs or if no entry is found, the pointer <CODE>*<VAR>result</VAR></CODE> |
| is a null pointer. Success is signalled by a zero return value. If the |
| function failed the return value is an error number. In addition to the |
| errors defined for <CODE>gethostbyname</CODE> it can also be <CODE>ERANGE</CODE>. |
| In this case the call should be repeated with a larger buffer. |
| Additional error information is not stored in the global variable |
| <CODE>h_errno</CODE> but instead in the object pointed to by <VAR>h_errnop</VAR>. |
| <br><br> Here's a small example: |
| <pre><br> |
| struct hostent *<br> |
| gethostname (char *host)<br> |
| {<br> |
| struct hostent hostbuf, *hp;<br> |
| size_t hstbuflen;<br> |
| char *tmphstbuf;<br> |
| int res;<br> |
| int herr;<br> |
| <br><br> hstbuflen = 1024;<br> |
| /* Allocate buffer, remember to free it to avoid memory leakage. */<br> |
| tmphstbuf = malloc (hstbuflen);<br> |
| <br><br> while ((res = gethostbyname_r (host, &hostbuf, tmphstbuf, hstbuflen,<br> |
| &hp, &herr)) == ERANGE)<br> |
| {<br> |
| /* Enlarge the buffer. */<br> |
| hstbuflen *= 2;<br> |
| tmphstbuf = realloc (tmphstbuf, hstbuflen);<br> |
| }<br> |
| /* Check for errors. */<br> |
| if (res || hp == NULL)<br> |
| return NULL;<br> |
| return hp;<br> |
| }<br> |
| </pre> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-gethostbyname2_r" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *name"/> |
| <parameter content="int af"/> |
| <parameter content="struct hostent *restrict result_buf"/> |
| <parameter content="char *restrict buf"/> |
| <parameter content="size_t buflen"/> |
| <parameter content="struct hostent **restrict result"/> |
| <parameter content="int *restrict h_errnop"/> |
| </prototype> |
| <headers> |
| <header filename = "netdb.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>gethostbyname2_r</CODE> function is like <CODE>gethostbyname_r</CODE>, but |
| allows the caller to specify the desired address family (e.g.: |
| <CODE>AF_INET</CODE> or <CODE>AF_INET6</CODE>) for the result. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-gethostbyaddr_r" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *addr"/> |
| <parameter content="size_t length"/> |
| <parameter content="int format"/> |
| <parameter content="struct hostent *restrict result_buf"/> |
| <parameter content="char *restrict buf"/> |
| <parameter content="size_t buflen"/> |
| <parameter content="struct hostent **restrict result"/> |
| <parameter content="int *restrict h_errnop"/> |
| </prototype> |
| <headers> |
| <header filename = "netdb.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>gethostbyaddr_r</CODE> function returns information about the host |
| with Internet address <VAR>addr</VAR>. The parameter <VAR>addr</VAR> is not |
| really a pointer to char - it can be a pointer to an IPv4 or an IPv6 |
| address. The <VAR>length</VAR> argument is the size (in bytes) of the address |
| at <VAR>addr</VAR>. <VAR>format</VAR> specifies the address format; for an IPv4 |
| Internet address, specify a value of <CODE>AF_INET</CODE>; for an IPv6 |
| Internet address, use <CODE>AF_INET6</CODE>. |
| <br><br> Similar to the <CODE>gethostbyname_r</CODE> function, the caller must provide |
| buffers for the result and memory used internally. In case of success |
| the function returns zero. Otherwise the value is an error number where |
| <CODE>ERANGE</CODE> has the special meaning that the caller-provided buffer is |
| too small. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-sethostent" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="int stayopen"/> |
| </prototype> |
| <headers> |
| <header filename = "netdb.h"/> |
| </headers> |
| <synopsis> |
| This function opens the hosts database to begin scanning it. You can |
| then call <CODE>gethostent</CODE> to read the entries. |
| <br><br> If the <VAR>stayopen</VAR> argument is nonzero, this sets a flag so that |
| subsequent calls to <CODE>gethostbyname</CODE> or <CODE>gethostbyaddr</CODE> will |
| not close the database (as they usually would). This makes for more |
| efficiency if you call those functions several times, by avoiding |
| reopening the database for each call. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-gethostent" type="function"> |
| <function returntype="struct hostent *"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "netdb.h"/> |
| </headers> |
| <synopsis> |
| This function returns the next entry in the hosts database. It |
| returns a null pointer if there are no more entries. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-endhostent" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "netdb.h"/> |
| </headers> |
| <synopsis> |
| This function closes the hosts database. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="struct-servent" type="struct"> |
| <structure> |
| <synopsis> |
| This data type holds information about entries from the services database. |
| It has the following members: |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="char *s_name"> |
| <synopsis> |
| This is the ``official'' name of the service. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="char **s_aliases"> |
| <synopsis> |
| These are alternate names for the service, represented as an array of |
| strings. A null pointer terminates the array. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="int s_port"> |
| <synopsis> |
| This is the port number for the service. Port numbers are given in |
| network byte order; see Byte Order. |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="function-getservbyname" type="function"> |
| <function returntype="struct servent *"> |
| <prototype> |
| <parameter content="const char *name"/> |
| <parameter content="const char *proto"/> |
| </prototype> |
| <headers> |
| <header filename = "netinet/in.h"/> |
| <header filename = "netdb.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>getservbyname</CODE> function returns information about the |
| service named <VAR>name</VAR> using protocol <VAR>proto</VAR>. If it can't find |
| such a service, it returns a null pointer. |
| <br><br> This function is useful for servers as well as for clients; servers |
| use it to determine which port they should listen on . |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getservbyport" type="function"> |
| <function returntype="struct servent *"> |
| <prototype> |
| <parameter content="int port"/> |
| <parameter content="const char *proto"/> |
| </prototype> |
| <headers> |
| <header filename = "netdb.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>getservbyport</CODE> function returns information about the |
| service at port <VAR>port</VAR> using protocol <VAR>proto</VAR>. If it can't |
| find such a service, it returns a null pointer. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-setservent" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="int stayopen"/> |
| </prototype> |
| <headers> |
| <header filename = "netdb.h"/> |
| </headers> |
| <synopsis> |
| This function opens the services database to begin scanning it. |
| <br><br> If the <VAR>stayopen</VAR> argument is nonzero, this sets a flag so that |
| subsequent calls to <CODE>getservbyname</CODE> or <CODE>getservbyport</CODE> will |
| not close the database (as they usually would). This makes for more |
| efficiency if you call those functions several times, by avoiding |
| reopening the database for each call. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getservent" type="function"> |
| <function returntype="struct servent *"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "netdb.h"/> |
| </headers> |
| <synopsis> |
| This function returns the next entry in the services database. If |
| there are no more entries, it returns a null pointer. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-endservent" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "netdb.h"/> |
| </headers> |
| <synopsis> |
| This function closes the services database. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-htons" type="function"> |
| <function returntype="uint16_t"> |
| <prototype> |
| <parameter content="uint16_t hostshort"/> |
| </prototype> |
| <headers> |
| <header filename = "netinet/in.h"/> |
| </headers> |
| <synopsis> |
| This function converts the <CODE>uint16_t</CODE> integer <VAR>hostshort</VAR> from |
| host byte order to network byte order. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-ntohs" type="function"> |
| <function returntype="uint16_t"> |
| <prototype> |
| <parameter content="uint16_t netshort"/> |
| </prototype> |
| <headers> |
| <header filename = "netinet/in.h"/> |
| </headers> |
| <synopsis> |
| This function converts the <CODE>uint16_t</CODE> integer <VAR>netshort</VAR> from |
| network byte order to host byte order. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-htonl" type="function"> |
| <function returntype="uint32_t"> |
| <prototype> |
| <parameter content="uint32_t hostlong"/> |
| </prototype> |
| <headers> |
| <header filename = "netinet/in.h"/> |
| </headers> |
| <synopsis> |
| This function converts the <CODE>uint32_t</CODE> integer <VAR>hostlong</VAR> from |
| host byte order to network byte order. |
| <br><br> This is used for IPv4 Internet addresses. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-ntohl" type="function"> |
| <function returntype="uint32_t"> |
| <prototype> |
| <parameter content="uint32_t netlong"/> |
| </prototype> |
| <headers> |
| <header filename = "netinet/in.h"/> |
| </headers> |
| <synopsis> |
| This function converts the <CODE>uint32_t</CODE> integer <VAR>netlong</VAR> from |
| network byte order to host byte order. |
| <br><br> This is used for IPv4 Internet addresses. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="struct-protoent" type="struct"> |
| <structure> |
| <synopsis> |
| This data type is used to represent entries in the network protocols |
| database. It has the following members: |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="char *p_name"> |
| <synopsis> |
| This is the official name of the protocol. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="char **p_aliases"> |
| <synopsis> |
| These are alternate names for the protocol, specified as an array of |
| strings. The last element of the array is a null pointer. |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="function-getprotobyname" type="function"> |
| <function returntype="struct protoent *"> |
| <prototype> |
| <parameter content="const char *name"/> |
| </prototype> |
| <headers> |
| <header filename = "netdb.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>getprotobyname</CODE> function returns information about the |
| network protocol named <VAR>name</VAR>. If there is no such protocol, it |
| returns a null pointer. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getprotobynumber" type="function"> |
| <function returntype="struct protoent *"> |
| <prototype> |
| <parameter content="int protocol"/> |
| </prototype> |
| <headers> |
| <header filename = "netdb.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>getprotobynumber</CODE> function returns information about the |
| network protocol with number <VAR>protocol</VAR>. If there is no such |
| protocol, it returns a null pointer. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-setprotoent" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="int stayopen"/> |
| </prototype> |
| <headers> |
| <header filename = "netdb.h"/> |
| </headers> |
| <synopsis> |
| This function opens the protocols database to begin scanning it. |
| <br><br> If the <VAR>stayopen</VAR> argument is nonzero, this sets a flag so that |
| subsequent calls to <CODE>getprotobyname</CODE> or <CODE>getprotobynumber</CODE> will |
| not close the database (as they usually would). This makes for more |
| efficiency if you call those functions several times, by avoiding |
| reopening the database for each call. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getprotoent" type="function"> |
| <function returntype="struct protoent *"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "netdb.h"/> |
| </headers> |
| <synopsis> |
| This function returns the next entry in the protocols database. It |
| returns a null pointer if there are no more entries. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-endprotoent" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "netdb.h"/> |
| </headers> |
| <synopsis> |
| This function closes the protocols database. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-socket" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int namespace"/> |
| <parameter content="int style"/> |
| <parameter content="int protocol"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/socket.h"/> |
| </headers> |
| <synopsis> |
| This function creates a socket and specifies communication style |
| <VAR>style</VAR>, which should be one of the socket styles listed in |
| Communication Styles. The <VAR>namespace</VAR> argument specifies |
| the namespace; it must be <CODE>PF_LOCAL</CODE> or |
| <CODE>PF_INET</CODE> . <VAR>protocol</VAR> |
| designates the specific protocol ; zero is |
| usually right for <VAR>protocol</VAR>. |
| <br><br> The return value from <CODE>socket</CODE> is the file descriptor for the new |
| socket, or <CODE>-1</CODE> in case of error. The following <CODE>errno</CODE> error |
| conditions are defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EPROTONOSUPPORT</CODE> |
| <DD> |
| The <VAR>protocol</VAR> or <VAR>style</VAR> is not supported by the |
| <VAR>namespace</VAR> specified. |
| <br><br> <LI> EMFILE |
| The process already has too many file descriptors open. |
| <br><br> <LI> ENFILE |
| The system already has too many file descriptors open. |
| <br><br> <LI> EACCES |
| The process does not have the privilege to create a socket of the specified |
| <VAR>style</VAR> or <VAR>protocol</VAR>. |
| <br><br> <LI> ENOBUFS |
| The system ran out of internal buffer space. |
| |
| <br><br> The file descriptor returned by the <CODE>socket</CODE> function supports both |
| read and write operations. However, like pipes, sockets do not support file |
| positioning operations. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-shutdown" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int socket"/> |
| <parameter content="int how"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/socket.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>shutdown</CODE> function shuts down the connection of socket |
| <VAR>socket</VAR>. The argument <VAR>how</VAR> specifies what action to |
| perform: |
| <br><br> <DL> |
| |
| <DT><CODE>0</CODE> |
| <DD> |
| Stop receiving data for this socket. If further data arrives, |
| reject it. |
| <br><br> <DT><CODE>1</CODE> |
| <DD> |
| Stop trying to transmit data from this socket. Discard any data |
| waiting to be sent. Stop looking for acknowledgement of data already |
| sent; don't retransmit it if it is lost. |
| <br><br> <LI> 2 |
| Stop both reception and transmission. |
| |
| <br><br> The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on failure. The |
| following <CODE>errno</CODE> error conditions are defined for this function: |
| <br><br> <DL> |
| |
| <LI> EBADF |
| <VAR>socket</VAR> is not a valid file descriptor. |
| <br><br> <LI> ENOTSOCK |
| <VAR>socket</VAR> is not a socket. |
| <br><br> <LI> ENOTCONN |
| <VAR>socket</VAR> is not connected. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-socketpair" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int namespace"/> |
| <parameter content="int style"/> |
| <parameter content="int protocol"/> |
| <parameter content="int filedes[2]"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/socket.h"/> |
| </headers> |
| <synopsis> |
| This function creates a socket pair, returning the file descriptors in |
| <CODE><VAR>filedes</VAR>[0]</CODE> and <CODE><VAR>filedes</VAR>[1]</CODE>. The socket pair |
| is a full-duplex communications channel, so that both reading and writing |
| may be performed at either end. |
| <br><br> The <VAR>namespace</VAR>, <VAR>style</VAR> and <VAR>protocol</VAR> arguments are |
| interpreted as for the <CODE>socket</CODE> function. <VAR>style</VAR> should be |
| one of the communication styles listed in Communication Styles. |
| The <VAR>namespace</VAR> argument specifies the namespace, which must be |
| <CODE>AF_LOCAL</CODE> ; <VAR>protocol</VAR> specifies the |
| communications protocol, but zero is the only meaningful value. |
| <br><br> If <VAR>style</VAR> specifies a connectionless communication style, then |
| the two sockets you get are not <EM>connected</EM>, strictly speaking, |
| but each of them knows the other as the default destination address, |
| so they can send packets to each other. |
| <br><br> The <CODE>socketpair</CODE> function returns <CODE>0</CODE> on success and <CODE>-1</CODE> |
| on failure. The following <CODE>errno</CODE> error conditions are defined |
| for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EMFILE</CODE> |
| <DD> |
| The process has too many file descriptors open. |
| <br><br> <LI> EAFNOSUPPORT |
| The specified namespace is not supported. |
| <br><br> <LI> EPROTONOSUPPORT |
| The specified protocol is not supported. |
| <br><br> <LI> EOPNOTSUPP |
| The specified protocol does not support the creation of socket pairs. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-connect" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int socket"/> |
| <parameter content="struct sockaddr *addr"/> |
| <parameter content="socklen_t length"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/socket.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>connect</CODE> function initiates a connection from the socket |
| with file descriptor <VAR>socket</VAR> to the socket whose address is |
| specified by the <VAR>addr</VAR> and <VAR>length</VAR> arguments. (This socket |
| is typically on another machine, and it must be already set up as a |
| server.) , for information about how these |
| arguments are interpreted. |
| <br><br> Normally, <CODE>connect</CODE> waits until the server responds to the request |
| before it returns. You can set nonblocking mode on the socket |
| <VAR>socket</VAR> to make <CODE>connect</CODE> return immediately without waiting |
| for the response. , for information about |
| nonblocking mode. |
| <br><br> The normal return value from <CODE>connect</CODE> is <CODE>0</CODE>. If an error |
| occurs, <CODE>connect</CODE> returns <CODE>-1</CODE>. The following <CODE>errno</CODE> |
| error conditions are defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EBADF</CODE> |
| <DD> |
| The socket <VAR>socket</VAR> is not a valid file descriptor. |
| <br><br> <LI> ENOTSOCK |
| File descriptor <VAR>socket</VAR> is not a socket. |
| <br><br> <LI> EADDRNOTAVAIL |
| The specified address is not available on the remote machine. |
| <br><br> <LI> EAFNOSUPPORT |
| The namespace of the <VAR>addr</VAR> is not supported by this socket. |
| <br><br> <LI> EISCONN |
| The socket <VAR>socket</VAR> is already connected. |
| <br><br> <LI> ETIMEDOUT |
| The attempt to establish the connection timed out. |
| <br><br> <LI> ECONNREFUSED |
| The server has actively refused to establish the connection. |
| <br><br> <LI> ENETUNREACH |
| The network of the given <VAR>addr</VAR> isn't reachable from this host. |
| <br><br> <LI> EADDRINUSE |
| The socket address of the given <VAR>addr</VAR> is already in use. |
| <br><br> <LI> EINPROGRESS |
| The socket <VAR>socket</VAR> is non-blocking and the connection could not be |
| established immediately. You can determine when the connection is |
| completely established with <CODE>select</CODE>; . |
| Another <CODE>connect</CODE> call on the same socket, before the connection is |
| completely established, will fail with <CODE>EALREADY</CODE>. |
| <br><br> <LI> EALREADY |
| The socket <VAR>socket</VAR> is non-blocking and already has a pending |
| connection in progress (see <CODE>EINPROGRESS</CODE> above). |
| |
| <br><br> This function is defined as a cancellation point in multi-threaded |
| programs, so one has to be prepared for this and make sure that |
| allocated resources (like memory, files descriptors, semaphores or |
| whatever) are freed even if the thread is canceled. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-listen" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int socket"/> |
| <parameter content="int n"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/socket.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>listen</CODE> function enables the socket <VAR>socket</VAR> to accept |
| connections, thus making it a server socket. |
| <br><br> The argument <VAR>n</VAR> specifies the length of the queue for pending |
| connections. When the queue fills, new clients attempting to connect |
| fail with <CODE>ECONNREFUSED</CODE> until the server calls <CODE>accept</CODE> to |
| accept a connection from the queue. |
| <br><br> The <CODE>listen</CODE> function returns <CODE>0</CODE> on success and <CODE>-1</CODE> |
| on failure. The following <CODE>errno</CODE> error conditions are defined |
| for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EBADF</CODE> |
| <DD> |
| The argument <VAR>socket</VAR> is not a valid file descriptor. |
| <br><br> <LI> ENOTSOCK |
| The argument <VAR>socket</VAR> is not a socket. |
| <br><br> <LI> EOPNOTSUPP |
| The socket <VAR>socket</VAR> does not support this operation. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-accept" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int socket"/> |
| <parameter content="struct sockaddr *addr"/> |
| <parameter content="socklen_t *length_ptr"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/socket.h"/> |
| </headers> |
| <synopsis> |
| This function is used to accept a connection request on the server |
| socket <VAR>socket</VAR>. |
| <br><br> The <CODE>accept</CODE> function waits if there are no connections pending, |
| unless the socket <VAR>socket</VAR> has nonblocking mode set. (You can use |
| <CODE>select</CODE> to wait for a pending connection, with a nonblocking |
| socket.) , for information about nonblocking |
| mode. |
| <br><br> The <VAR>addr</VAR> and <VAR>length-ptr</VAR> arguments are used to return |
| information about the name of the client socket that initiated the |
| connection. , for information about the format |
| of the information. |
| <br><br> Accepting a connection does not make <VAR>socket</VAR> part of the |
| connection. Instead, it creates a new socket which becomes |
| connected. The normal return value of <CODE>accept</CODE> is the file |
| descriptor for the new socket. |
| <br><br> After <CODE>accept</CODE>, the original socket <VAR>socket</VAR> remains open and |
| unconnected, and continues listening until you close it. You can |
| accept further connections with <VAR>socket</VAR> by calling <CODE>accept</CODE> |
| again. |
| <br><br> If an error occurs, <CODE>accept</CODE> returns <CODE>-1</CODE>. The following |
| <CODE>errno</CODE> error conditions are defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EBADF</CODE> |
| <DD> |
| The <VAR>socket</VAR> argument is not a valid file descriptor. |
| <br><br> <LI> ENOTSOCK |
| The descriptor <VAR>socket</VAR> argument is not a socket. |
| <br><br> <LI> EOPNOTSUPP |
| The descriptor <VAR>socket</VAR> does not support this operation. |
| <br><br> <LI> EWOULDBLOCK |
| <VAR>socket</VAR> has nonblocking mode set, and there are no pending |
| connections immediately available. |
| |
| <br><br> This function is defined as a cancellation point in multi-threaded |
| programs, so one has to be prepared for this and make sure that |
| allocated resources (like memory, files descriptors, semaphores or |
| whatever) are freed even if the thread is canceled. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getpeername" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int socket"/> |
| <parameter content="struct sockaddr *addr"/> |
| <parameter content="socklen_t *length-ptr"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/socket.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>getpeername</CODE> function returns the address of the socket that |
| <VAR>socket</VAR> is connected to; it stores the address in the memory space |
| specified by <VAR>addr</VAR> and <VAR>length-ptr</VAR>. It stores the length of |
| the address in <CODE>*<VAR>length-ptr</VAR></CODE>. |
| <br><br> , for information about the format of the |
| address. In some operating systems, <CODE>getpeername</CODE> works only for |
| sockets in the Internet domain. |
| <br><br> The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on error. The |
| following <CODE>errno</CODE> error conditions are defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EBADF</CODE> |
| <DD> |
| The argument <VAR>socket</VAR> is not a valid file descriptor. |
| <br><br> <LI> ENOTSOCK |
| The descriptor <VAR>socket</VAR> is not a socket. |
| <br><br> <LI> ENOTCONN |
| The socket <VAR>socket</VAR> is not connected. |
| <br><br> <LI> ENOBUFS |
| There are not enough internal buffers available. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-send" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int socket"/> |
| <parameter content="void *buffer"/> |
| <parameter content="size_t size"/> |
| <parameter content="int flags"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/socket.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>send</CODE> function is like <CODE>write</CODE>, but with the additional |
| flags <VAR>flags</VAR>. The possible values of <VAR>flags</VAR> are described |
| in Socket Data Options. |
| <br><br> This function returns the number of bytes transmitted, or <CODE>-1</CODE> on |
| failure. If the socket is nonblocking, then <CODE>send</CODE> (like |
| <CODE>write</CODE>) can return after sending just part of the data. |
| , for information about nonblocking mode. |
| <br><br> Note, however, that a successful return value merely indicates that |
| the message has been sent without error, not necessarily that it has |
| been received without error. |
| <br><br> The following <CODE>errno</CODE> error conditions are defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EBADF</CODE> |
| <DD> |
| The <VAR>socket</VAR> argument is not a valid file descriptor. |
| <br><br> <LI> EINTR |
| The operation was interrupted by a signal before any data was sent. |
| . |
| <br><br> <LI> ENOTSOCK |
| The descriptor <VAR>socket</VAR> is not a socket. |
| <br><br> <LI> EMSGSIZE |
| The socket type requires that the message be sent atomically, but the |
| message is too large for this to be possible. |
| <br><br> <LI> EWOULDBLOCK |
| Nonblocking mode has been set on the socket, and the write operation |
| would block. (Normally <CODE>send</CODE> blocks until the operation can be |
| completed.) |
| <br><br> <LI> ENOBUFS |
| There is not enough internal buffer space available. |
| <br><br> <LI> ENOTCONN |
| You never connected this socket. |
| <br><br> <LI> EPIPE |
| This socket was connected but the connection is now broken. In this |
| case, <CODE>send</CODE> generates a <CODE>SIGPIPE</CODE> signal first; if that |
| signal is ignored or blocked, or if its handler returns, then |
| <CODE>send</CODE> fails with <CODE>EPIPE</CODE>. |
| |
| <br><br> This function is defined as a cancellation point in multi-threaded |
| programs, so one has to be prepared for this and make sure that |
| allocated resources (like memory, files descriptors, semaphores or |
| whatever) are freed even if the thread is canceled. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-recv" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int socket"/> |
| <parameter content="void *buffer"/> |
| <parameter content="size_t size"/> |
| <parameter content="int flags"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/socket.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>recv</CODE> function is like <CODE>read</CODE>, but with the additional |
| flags <VAR>flags</VAR>. The possible values of <VAR>flags</VAR> are described |
| in Socket Data Options. |
| <br><br> If nonblocking mode is set for <VAR>socket</VAR>, and no data are available to |
| be read, <CODE>recv</CODE> fails immediately rather than waiting. , for information about nonblocking mode. |
| <br><br> This function returns the number of bytes received, or <CODE>-1</CODE> on failure. |
| The following <CODE>errno</CODE> error conditions are defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EBADF</CODE> |
| <DD> |
| The <VAR>socket</VAR> argument is not a valid file descriptor. |
| <br><br> <LI> ENOTSOCK |
| The descriptor <VAR>socket</VAR> is not a socket. |
| <br><br> <LI> EWOULDBLOCK |
| Nonblocking mode has been set on the socket, and the read operation |
| would block. (Normally, <CODE>recv</CODE> blocks until there is input |
| available to be read.) |
| <br><br> <LI> EINTR |
| The operation was interrupted by a signal before any data was read. |
| . |
| <br><br> <LI> ENOTCONN |
| You never connected this socket. |
| |
| <br><br> This function is defined as a cancellation point in multi-threaded |
| programs, so one has to be prepared for this and make sure that |
| allocated resources (like memory, files descriptors, semaphores or |
| whatever) are freed even if the thread is canceled. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-sendto" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int socket"/> |
| <parameter content="void *buffer"/> |
| <parameter content="size_t size"/> |
| <parameter content="int flags"/> |
| <parameter content="struct sockaddr *addr"/> |
| <parameter content="socklen_t length"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/socket.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>sendto</CODE> function transmits the data in the <VAR>buffer</VAR> |
| through the socket <VAR>socket</VAR> to the destination address specified |
| by the <VAR>addr</VAR> and <VAR>length</VAR> arguments. The <VAR>size</VAR> argument |
| specifies the number of bytes to be transmitted. |
| <br><br> The <VAR>flags</VAR> are interpreted the same way as for <CODE>send</CODE>; see |
| Socket Data Options. |
| <br><br> The return value and error conditions are also the same as for |
| <CODE>send</CODE>, but you cannot rely on the system to detect errors and |
| report them; the most common error is that the packet is lost or there |
| is no-one at the specified address to receive it, and the operating |
| system on your machine usually does not know this. |
| <br><br> It is also possible for one call to <CODE>sendto</CODE> to report an error |
| owing to a problem related to a previous call. |
| <br><br> This function is defined as a cancellation point in multi-threaded |
| programs, so one has to be prepared for this and make sure that |
| allocated resources (like memory, files descriptors, semaphores or |
| whatever) are freed even if the thread is canceled. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-recvfrom" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int socket"/> |
| <parameter content="void *buffer"/> |
| <parameter content="size_t size"/> |
| <parameter content="int flags"/> |
| <parameter content="struct sockaddr *addr"/> |
| <parameter content="socklen_t *length-ptr"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/socket.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>recvfrom</CODE> function reads one packet from the socket |
| <VAR>socket</VAR> into the buffer <VAR>buffer</VAR>. The <VAR>size</VAR> argument |
| specifies the maximum number of bytes to be read. |
| <br><br> If the packet is longer than <VAR>size</VAR> bytes, then you get the first |
| <VAR>size</VAR> bytes of the packet and the rest of the packet is lost. |
| There's no way to read the rest of the packet. Thus, when you use a |
| packet protocol, you must always know how long a packet to expect. |
| <br><br> The <VAR>addr</VAR> and <VAR>length-ptr</VAR> arguments are used to return the |
| address where the packet came from. . For a |
| socket in the local domain the address information won't be meaningful, |
| since you can't read the address of such a socket. You can specify a null pointer as the <VAR>addr</VAR> argument |
| if you are not interested in this information. |
| <br><br> The <VAR>flags</VAR> are interpreted the same way as for <CODE>recv</CODE> |
| . The return value and error conditions |
| are also the same as for <CODE>recv</CODE>. |
| <br><br> This function is defined as a cancellation point in multi-threaded |
| programs, so one has to be prepared for this and make sure that |
| allocated resources (like memory, files descriptors, semaphores or |
| whatever) are freed even if the thread is canceled. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="struct-msghdr" type="struct"> |
| <structure> |
| </structure> |
| </construct> |
| <construct id="function-sendmsg" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int socket"/> |
| <parameter content="const struct msghdr *message"/> |
| <parameter content="int flags"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/socket.h"/> |
| </headers> |
| <synopsis> |
| <br><br> This function is defined as a cancellation point in multi-threaded |
| programs, so one has to be prepared for this and make sure that |
| allocated resources (like memory, files descriptors, semaphores or |
| whatever) are freed even if the thread is cancel. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-recvmsg" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int socket"/> |
| <parameter content="struct msghdr *message"/> |
| <parameter content="int flags"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/socket.h"/> |
| </headers> |
| <synopsis> |
| <br><br> This function is defined as a cancellation point in multi-threaded |
| programs, so one has to be prepared for this and make sure that |
| allocated resources (like memory, files descriptors, semaphores or |
| whatever) are freed even if the thread is canceled. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getsockopt" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int socket"/> |
| <parameter content="int level"/> |
| <parameter content="int optname"/> |
| <parameter content="void *optval"/> |
| <parameter content="socklen_t *optlen-ptr"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/socket.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>getsockopt</CODE> function gets information about the value of |
| option <VAR>optname</VAR> at level <VAR>level</VAR> for socket <VAR>socket</VAR>. |
| <br><br> The option value is stored in a buffer that <VAR>optval</VAR> points to. |
| Before the call, you should supply in <CODE>*<VAR>optlen-ptr</VAR></CODE> the |
| size of this buffer; on return, it contains the number of bytes of |
| information actually stored in the buffer. |
| <br><br> Most options interpret the <VAR>optval</VAR> buffer as a single <CODE>int</CODE> |
| value. |
| <br><br> The actual return value of <CODE>getsockopt</CODE> is <CODE>0</CODE> on success |
| and <CODE>-1</CODE> on failure. The following <CODE>errno</CODE> error conditions |
| are defined: |
| <br><br> <DL> |
| |
| <DT><CODE>EBADF</CODE> |
| <DD> |
| The <VAR>socket</VAR> argument is not a valid file descriptor. |
| <br><br> <LI> ENOTSOCK |
| The descriptor <VAR>socket</VAR> is not a socket. |
| <br><br> <LI> ENOPROTOOPT |
| The <VAR>optname</VAR> doesn't make sense for the given <VAR>level</VAR>. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-setsockopt" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int socket"/> |
| <parameter content="int level"/> |
| <parameter content="int optname"/> |
| <parameter content="void *optval"/> |
| <parameter content="socklen_t optlen"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/socket.h"/> |
| </headers> |
| <synopsis> |
| This function is used to set the socket option <VAR>optname</VAR> at level |
| <VAR>level</VAR> for socket <VAR>socket</VAR>. The value of the option is passed |
| in the buffer <VAR>optval</VAR> of size <VAR>optlen</VAR>. |
| <br><br> |
| |
| The return value and error codes for <CODE>setsockopt</CODE> are the same as |
| for <CODE>getsockopt</CODE>. |
| |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="struct-linger" type="struct"> |
| <structure> |
| <synopsis> |
| This structure type has the following members: |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="int l_onoff"> |
| <synopsis> |
| This field is interpreted as a boolean. If nonzero, <CODE>close</CODE> |
| blocks until the data are transmitted or the timeout period has expired. |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="struct-netent" type="struct"> |
| <structure> |
| <synopsis> |
| This data type is used to represent information about entries in the |
| networks database. It has the following members: |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="char *n_name"> |
| <synopsis> |
| This is the ``official'' name of the network. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="char **n_aliases"> |
| <synopsis> |
| These are alternative names for the network, represented as a vector |
| of strings. A null pointer terminates the array. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="int n_addrtype"> |
| <synopsis> |
| This is the type of the network number; this is always equal to |
| <CODE>AF_INET</CODE> for Internet networks. |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="function-getnetbyname" type="function"> |
| <function returntype="struct netent *"> |
| <prototype> |
| <parameter content="const char *name"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/socket.h"/> |
| <header filename = "netdb.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>getnetbyname</CODE> function returns information about the network |
| named <VAR>name</VAR>. It returns a null pointer if there is no such |
| network. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getnetbyaddr" type="function"> |
| <function returntype="struct netent *"> |
| <prototype> |
| <parameter content="unsigned long int net"/> |
| <parameter content="int type"/> |
| </prototype> |
| <headers> |
| <header filename = "netdb.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>getnetbyaddr</CODE> function returns information about the network |
| of type <VAR>type</VAR> with number <VAR>net</VAR>. You should specify a value of |
| <CODE>AF_INET</CODE> for the <VAR>type</VAR> argument for Internet networks. |
| <br><br> <CODE>getnetbyaddr</CODE> returns a null pointer if there is no such |
| network. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-setnetent" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="int stayopen"/> |
| </prototype> |
| <headers> |
| <header filename = "netdb.h"/> |
| </headers> |
| <synopsis> |
| This function opens and rewinds the networks database. |
| <br><br> If the <VAR>stayopen</VAR> argument is nonzero, this sets a flag so that |
| subsequent calls to <CODE>getnetbyname</CODE> or <CODE>getnetbyaddr</CODE> will |
| not close the database (as they usually would). This makes for more |
| efficiency if you call those functions several times, by avoiding |
| reopening the database for each call. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getnetent" type="function"> |
| <function returntype="struct netent *"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "netdb.h"/> |
| </headers> |
| <synopsis> |
| This function returns the next entry in the networks database. It |
| returns a null pointer if there are no more entries. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-endnetent" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "netdb.h"/> |
| </headers> |
| <synopsis> |
| This function closes the networks database. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-difftime" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="time_t time1"/> |
| <parameter content="time_t time0"/> |
| </prototype> |
| <headers> |
| <header filename = "time.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>difftime</CODE> function returns the number of seconds of elapsed |
| time between calendar time <VAR>time1</VAR> and calendar time <VAR>time0</VAR>, as |
| a value of type <CODE>double</CODE>. The difference ignores leap seconds |
| unless leap second support is enabled. |
| <br><br> In the GNU system, you can simply subtract <CODE>time_t</CODE> values. But on |
| other systems, the <CODE>time_t</CODE> data type might use some other encoding |
| where subtraction doesn't work directly. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="struct-timeval" type="struct"> |
| <structure> |
| <synopsis> |
| |
| The <CODE>struct timeval</CODE> structure represents an elapsed time. It is |
| declared in <TT>sys/time.h</TT> and has the following members: |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="long int tv_sec"> |
| <synopsis> |
| This represents the number of whole seconds of elapsed time. |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="struct-timespec" type="struct"> |
| <structure> |
| <synopsis> |
| |
| The <CODE>struct timespec</CODE> structure represents an elapsed time. It is |
| declared in <TT>time.h</TT> and has the following members: |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="long int tv_sec"> |
| <synopsis> |
| This represents the number of whole seconds of elapsed time. |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="dtype-clock_t" type="dtype"> |
| <structure> |
| </structure> |
| </construct> |
| <construct id="function-clock" type="function"> |
| <function returntype="clock_t"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/time.h"/> |
| <header filename = "time.h"/> |
| </headers> |
| <synopsis> |
| This function returns the calling process' current CPU time. If the CPU |
| time is not available or cannot be represented, <CODE>clock</CODE> returns the |
| value <CODE>(clock_t)(-1)</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="struct-tms" type="struct"> |
| <structure> |
| <synopsis> |
| The <CODE>tms</CODE> structure is used to return information about process |
| times. It contains at least the following members: |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="clock_t tms_utime"> |
| <synopsis> |
| This is the total processor time the calling process has used in |
| executing the instructions of its program. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="clock_t tms_stime"> |
| <synopsis> |
| This is the processor time the system has used on behalf of the calling |
| process. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="clock_t tms_cutime"> |
| <synopsis> |
| This is the sum of the <CODE>tms_utime</CODE> values and the <CODE>tms_cutime</CODE> |
| values of all terminated child processes of the calling process, whose |
| status has been reported to the parent process by <CODE>wait</CODE> or |
| <CODE>waitpid</CODE>; 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 <CODE>wait</CODE> or |
| <CODE>waitpid</CODE>. |
| process |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="function-times" type="function"> |
| <function returntype="clock_t"> |
| <prototype> |
| <parameter content="struct tms *buffer"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/times.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>times</CODE> function stores the processor time information for |
| the calling process in <VAR>buffer</VAR>. |
| <br><br> The return value is the calling process' CPU time (the same value you |
| get from <CODE>clock()</CODE>. <CODE>times</CODE> returns <CODE>(clock_t)(-1)</CODE> to |
| indicate failure. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="dtype-time_t" type="dtype"> |
| <structure> |
| </structure> |
| </construct> |
| <construct id="function-time" type="function"> |
| <function returntype="time_t"> |
| <prototype> |
| <parameter content="time_t *result"/> |
| </prototype> |
| <headers> |
| <header filename = "time.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>time</CODE> function returns the current calendar time as a value of |
| type <CODE>time_t</CODE>. If the argument <VAR>result</VAR> is not a null pointer, |
| the calendar time value is also stored in <CODE>*<VAR>result</VAR></CODE>. If the |
| current calendar time is not available, the value |
| <CODE>(time_t)(-1)</CODE> is returned. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-stime" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="time_t *newtime"/> |
| </prototype> |
| <headers> |
| <header filename = "time.h"/> |
| </headers> |
| <synopsis> |
| <CODE>stime</CODE> sets the system clock, i.e., it tells the system that the |
| current calendar time is <VAR>newtime</VAR>, where <CODE>newtime</CODE> is |
| interpreted as described in the above definition of <CODE>time_t</CODE>. |
| <br><br> <CODE>settimeofday</CODE> is a newer function which sets the system clock to |
| better than one second precision. <CODE>settimeofday</CODE> is generally a |
| better choice than <CODE>stime</CODE>. . |
| <br><br> Only the superuser can set the system clock. |
| <br><br> If the function succeeds, the return value is zero. Otherwise, it is |
| <CODE>-1</CODE> and <CODE>errno</CODE> is set accordingly: |
| <br><br> <DL> |
| |
| <DT><CODE>EPERM</CODE> |
| <DD> |
| The process is not superuser. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="struct-timezone" type="struct"> |
| <structure> |
| <synopsis> |
| The <CODE>struct timezone</CODE> structure is used to hold minimal information |
| about the local time zone. It has the following members: |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="int tz_minuteswest"> |
| <synopsis> |
| This is the number of minutes west of UTC. |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="function-gettimeofday" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="struct timeval *tp"/> |
| <parameter content="struct timezone *tzp"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/time.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>gettimeofday</CODE> function returns the current calendar time as |
| the elapsed time since the epoch in the <CODE>struct timeval</CODE> structure |
| indicated by <VAR>tp</VAR>. ( for a description of |
| <CODE>struct timeval</CODE>). Information about the time zone is returned in |
| the structure pointed at <VAR>tzp</VAR>. If the <VAR>tzp</VAR> argument is a null |
| pointer, time zone information is ignored. |
| <br><br> The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on failure. The |
| following <CODE>errno</CODE> error condition is defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>ENOSYS</CODE> |
| <DD> |
| The operating system does not support getting time zone information, and |
| <VAR>tzp</VAR> is not a null pointer. The GNU operating system does not |
| support using <CODE>struct timezone</CODE> to represent time zone |
| information; that is an obsolete feature of 4.3 BSD. |
| Instead, use the facilities described in Time Zone Functions. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-settimeofday" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const struct timeval *tp"/> |
| <parameter content="const struct timezone *tzp"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/time.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>settimeofday</CODE> function sets the current calendar time in the |
| system clock according to the arguments. As for <CODE>gettimeofday</CODE>, |
| the calendar time is represented as the elapsed time since the epoch. |
| As for <CODE>gettimeofday</CODE>, time zone information is ignored if |
| <VAR>tzp</VAR> is a null pointer. |
| <br><br> You must be a privileged user in order to use <CODE>settimeofday</CODE>. |
| <br><br> Some kernels automatically set the system clock from some source such as |
| a hardware clock when they start up. Others, including Linux, place the |
| system clock in an ``invalid'' state (in which attempts to read the clock |
| fail). A call of <CODE>stime</CODE> removes the system clock from an invalid |
| state, and system startup scripts typically run a program that calls |
| <CODE>stime</CODE>. |
| <br><br> <CODE>settimeofday</CODE> causes a sudden jump forwards or backwards, which |
| can cause a variety of problems in a system. Use <CODE>adjtime</CODE> (below) |
| to make a smooth transition from one time to another by temporarily |
| speeding up or slowing down the clock. |
| <br><br> With a Linux kernel, <CODE>adjtimex</CODE> does the same thing and can also |
| make permanent changes to the speed of the system clock so it doesn't |
| need to be corrected as often. |
| <br><br> The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on failure. The |
| following <CODE>errno</CODE> error conditions are defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EPERM</CODE> |
| <DD> |
| This process cannot set the clock because it is not privileged. |
| <br><br> <LI> ENOSYS |
| The operating system does not support setting time zone information, and |
| <VAR>tzp</VAR> is not a null pointer. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-adjtime" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const struct timeval *delta"/> |
| <parameter content="struct timeval *olddelta"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/time.h"/> |
| </headers> |
| <synopsis> |
| This function speeds up or slows down the system clock in order to make |
| a gradual adjustment. This ensures that the calendar time reported by |
| the system clock is always monotonically increasing, which might not |
| happen if you simply set the clock. |
| <br><br> The <VAR>delta</VAR> argument specifies a relative adjustment to be made to |
| the clock time. If negative, the system clock is slowed down for a |
| while until it has lost this much elapsed time. If positive, the system |
| clock is speeded up for a while. |
| <br><br> If the <VAR>olddelta</VAR> argument is not a null pointer, the <CODE>adjtime</CODE> |
| function returns information about any previous time adjustment that |
| has not yet completed. |
| <br><br> This function is typically used to synchronize the clocks of computers |
| in a local network. You must be a privileged user to use it. |
| <br><br> With a Linux kernel, you can use the <CODE>adjtimex</CODE> function to |
| permanently change the clock speed. |
| <br><br> The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on failure. The |
| following <CODE>errno</CODE> error condition is defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EPERM</CODE> |
| <DD> |
| You do not have privilege to set the time. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-adjtimex" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="struct timex *timex"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/timex.h"/> |
| </headers> |
| <synopsis> |
| <br><br> <CODE>adjtimex</CODE> is functionally identical to <CODE>ntp_adjtime</CODE>. |
| . |
| <br><br> This function is present only with a Linux kernel. |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="struct-tm" type="struct"> |
| <structure> |
| <synopsis> |
| This is the data type used to represent a broken-down time. The structure |
| contains at least the following members, which can appear in any order. |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="int tm_sec"> |
| <synopsis> |
| This is the number of full seconds since the top of the minute (normally |
| in the range <CODE>0</CODE> through <CODE>59</CODE>, but the actual upper limit is |
| <CODE>60</CODE>, to allow for leap seconds if leap second support is |
| available). |
| second |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="int tm_min"> |
| <synopsis> |
| This is the number of full minutes since the top of the hour (in the |
| range <CODE>0</CODE> through <CODE>59</CODE>). |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="int tm_hour"> |
| <synopsis> |
| This is the number of full hours past midnight (in the range <CODE>0</CODE> through |
| <CODE>23</CODE>). |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="int tm_mday"> |
| <synopsis> |
| This is the ordinal day of the month (in the range <CODE>1</CODE> through <CODE>31</CODE>). |
| Watch out for this one! As the only ordinal number in the structure, it is |
| inconsistent with the rest of the structure. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="int tm_mon"> |
| <synopsis> |
| This is the number of full calendar months since the beginning of the |
| year (in the range <CODE>0</CODE> through <CODE>11</CODE>). Watch out for this one! |
| People usually use ordinal numbers for month-of-year (where January = 1). |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="int tm_year"> |
| <synopsis> |
| This is the number of full calendar years since 1900. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="int tm_wday"> |
| <synopsis> |
| This is the number of full days since Sunday (in the range <CODE>0</CODE> through |
| <CODE>6</CODE>). |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="int tm_yday"> |
| <synopsis> |
| This is the number of full days since the beginning of the year (in the |
| range <CODE>0</CODE> through <CODE>365</CODE>). |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="int tm_isdst"> |
| <synopsis> |
| Saving Time |
| time |
| This is a flag that indicates whether Daylight Saving Time is (or was, or |
| will be) in effect at the time described. The value is positive if |
| Daylight Saving Time is in effect, zero if it is not, and negative if the |
| information is not available. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="long int tm_gmtoff"> |
| <synopsis> |
| This field describes the time zone that was used to compute this |
| broken-down time value, including any adjustment for daylight saving; it |
| is the number of seconds that you must add to UTC to get local time. |
| You can also think of this as the number of seconds east of UTC. For |
| example, for U.S. Eastern Standard Time, the value is <CODE>-5*60*60</CODE>. |
| The <CODE>tm_gmtoff</CODE> field is derived from BSD and is a GNU library |
| extension; it is not visible in a strict ISO C environment. |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="function-localtime" type="function"> |
| <function returntype="struct tm *"> |
| <prototype> |
| <parameter content="const time_t *time"/> |
| </prototype> |
| <headers> |
| <header filename = "time.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>localtime</CODE> function converts the simple time pointed to by |
| <VAR>time</VAR> to broken-down time representation, expressed relative to the |
| user's specified time zone. |
| <br><br> The return value is a pointer to a static broken-down time structure, which |
| might be overwritten by subsequent calls to <CODE>ctime</CODE>, <CODE>gmtime</CODE>, |
| or <CODE>localtime</CODE>. (But no other library function overwrites the contents |
| of this object.) |
| <br><br> The return value is the null pointer if <VAR>time</VAR> cannot be represented |
| as a broken-down time; typically this is because the year cannot fit into |
| an <CODE>int</CODE>. |
| <br><br> Calling <CODE>localtime</CODE> has one other effect: it sets the variable |
| <CODE>tzname</CODE> with information about the current time zone. . |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-localtime_r" type="function"> |
| <function returntype="struct tm *"> |
| <prototype> |
| <parameter content="const time_t *time"/> |
| <parameter content="struct tm *resultp"/> |
| </prototype> |
| <headers> |
| <header filename = "time.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>localtime_r</CODE> function works just like the <CODE>localtime</CODE> |
| function. It takes a pointer to a variable containing a simple time |
| and converts it to the broken-down time format. |
| <br><br> But the result is not placed in a static buffer. Instead it is placed |
| in the object of type <CODE>struct tm</CODE> to which the parameter |
| <VAR>resultp</VAR> points. |
| <br><br> If the conversion is successful the function returns a pointer to the |
| object the result was written into, i.e., it returns <VAR>resultp</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-gmtime" type="function"> |
| <function returntype="struct tm *"> |
| <prototype> |
| <parameter content="const time_t *time"/> |
| </prototype> |
| <headers> |
| <header filename = "time.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to <CODE>localtime</CODE>, except that the broken-down |
| time is expressed as Coordinated Universal Time (UTC) (formerly called |
| Greenwich Mean Time (GMT)) rather than relative to a local time zone. |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-gmtime_r" type="function"> |
| <function returntype="struct tm *"> |
| <prototype> |
| <parameter content="const time_t *time"/> |
| <parameter content="struct tm *resultp"/> |
| </prototype> |
| <headers> |
| <header filename = "time.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to <CODE>localtime_r</CODE>, except that it converts |
| just like <CODE>gmtime</CODE> the given time as Coordinated Universal Time. |
| <br><br> If the conversion is successful the function returns a pointer to the |
| object the result was written into, i.e., it returns <VAR>resultp</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-mktime" type="function"> |
| <function returntype="time_t"> |
| <prototype> |
| <parameter content="struct tm *brokentime"/> |
| </prototype> |
| <headers> |
| <header filename = "time.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>mktime</CODE> function is used to convert a broken-down time structure |
| to a simple time representation. It also ``normalizes'' the contents of |
| the broken-down time structure, by filling in the day of week and day of |
| year based on the other date and time components. |
| <br><br> The <CODE>mktime</CODE> function ignores the specified contents of the |
| <CODE>tm_wday</CODE> and <CODE>tm_yday</CODE> members of the broken-down time |
| structure. It uses the values of the other components to determine the |
| calendar time; it's permissible for these components to have |
| unnormalized values outside their normal ranges. The last thing that |
| <CODE>mktime</CODE> does is adjust the components of the <VAR>brokentime</VAR> |
| structure (including the <CODE>tm_wday</CODE> and <CODE>tm_yday</CODE>). |
| <br><br> If the specified broken-down time cannot be represented as a simple time, |
| <CODE>mktime</CODE> returns a value of <CODE>(time_t)(-1)</CODE> and does not modify |
| the contents of <VAR>brokentime</VAR>. |
| <br><br> Calling <CODE>mktime</CODE> also sets the variable <CODE>tzname</CODE> with |
| information about the current time zone. . |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-timelocal" type="function"> |
| <function returntype="time_t"> |
| <prototype> |
| <parameter content="struct tm *brokentime"/> |
| </prototype> |
| <headers> |
| <header filename = "time.h"/> |
| </headers> |
| <synopsis> |
| <br><br> <CODE>timelocal</CODE> is functionally identical to <CODE>mktime</CODE>, but more |
| mnemonically named. Note that it is the inverse of the <CODE>localtime</CODE> |
| function. |
| <br><br> Portability note: <CODE>mktime</CODE> is essentially universally |
| available. <CODE>timelocal</CODE> is rather rare. |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-timegm" type="function"> |
| <function returntype="time_t"> |
| <prototype> |
| <parameter content="struct tm *brokentime"/> |
| </prototype> |
| <headers> |
| <header filename = "time.h"/> |
| </headers> |
| <synopsis> |
| <br><br> <CODE>timegm</CODE> is functionally identical to <CODE>mktime</CODE> except it |
| always takes the input values to be Coordinated Universal Time (UTC) |
| regardless of any local time zone setting. |
| <br><br> Note that <CODE>timegm</CODE> is the inverse of <CODE>gmtime</CODE>. |
| <br><br> Portability note: <CODE>mktime</CODE> is essentially universally |
| available. <CODE>timegm</CODE> is rather rare. For the most portable |
| conversion from a UTC broken-down time to a simple time, set |
| the <CODE>TZ</CODE> environment variable to UTC, call <CODE>mktime</CODE>, then set |
| <CODE>TZ</CODE> back. |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="struct-ntptimeval" type="struct"> |
| <structure> |
| <synopsis> |
| This structure is used for information about the system clock. It |
| contains the following members: |
| </synopsis> |
| <elements> |
| <element content="struct timeval time"> |
| <synopsis> |
| This is the current calendar time, expressed as the elapsed time since |
| the epoch. The <CODE>struct timeval</CODE> data type is described in |
| Elapsed Time. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="long int maxerror"> |
| <synopsis> |
| This is the maximum error, measured in microseconds. Unless updated |
| via <CODE>ntp_adjtime</CODE> periodically, this value will reach some |
| platform-specific maximum value. |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="function-ntp_gettime" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="struct ntptimeval *tptr"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/timex.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>ntp_gettime</CODE> function sets the structure pointed to by |
| <VAR>tptr</VAR> to current values. The elements of the structure afterwards |
| contain the values the timer implementation in the kernel assumes. They |
| might or might not be correct. If they are not a <CODE>ntp_adjtime</CODE> |
| call is necessary. |
| <br><br> The return value is <CODE>0</CODE> on success and other values on failure. The |
| following <CODE>errno</CODE> error conditions are defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>TIME_ERROR</CODE> |
| <DD> |
| The precision clock model is not properly set up at the moment, thus the |
| clock must be considered unsynchronized, and the values should be |
| treated with care. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="struct-timex" type="struct"> |
| <structure> |
| <synopsis> |
| This structure is used to control and monitor the system clock. It |
| contains the following members: |
| </synopsis> |
| <elements> |
| <element content="unsigned int modes"> |
| <synopsis> |
| This variable controls whether and which values are set. Several |
| symbolic constants have to be combined with <EM>binary or</EM> to specify |
| the effective mode. These constants start with <CODE>MOD_</CODE>. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="long int offset"> |
| <synopsis> |
| This value indicates the current offset of the system clock from the true |
| calendar time. The value is given in microseconds. If bit |
| <CODE>MOD_OFFSET</CODE> is set in <CODE>modes</CODE>, the offset (and possibly other |
| dependent values) can be set. The offset's absolute value must not |
| exceed <CODE>MAXPHASE</CODE>. |
| <br><br> <br><br> |
| </synopsis> |
| </element> |
| <element content="long int frequency"> |
| <synopsis> |
| This value indicates the difference in frequency between the true |
| calendar time and the system clock. The value is expressed as scaled |
| PPM (parts per million, 0.0001%). The scaling is <CODE>1 << |
| SHIFT_USEC</CODE>. The value can be set with bit <CODE>MOD_FREQUENCY</CODE>, but |
| the absolute value must not exceed <CODE>MAXFREQ</CODE>. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="long int maxerror"> |
| <synopsis> |
| This is the maximum error, measured in microseconds. A new value can be |
| set using bit <CODE>MOD_MAXERROR</CODE>. Unless updated via |
| <CODE>ntp_adjtime</CODE> periodically, this value will increase steadily |
| and reach some platform-specific maximum value. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="long int esterror"> |
| <synopsis> |
| This is the estimated error, measured in microseconds. This value can |
| be set using bit <CODE>MOD_ESTERROR</CODE>. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="int status"> |
| <synopsis> |
| This variable reflects the various states of the clock machinery. There |
| are symbolic constants for the significant bits, starting with |
| <CODE>STA_</CODE>. Some of these flags can be updated using the |
| <CODE>MOD_STATUS</CODE> bit. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="long int constant"> |
| <synopsis> |
| This value represents the bandwidth or stiffness of the PLL (phase |
| locked loop) implemented in the kernel. The value can be changed using |
| bit <CODE>MOD_TIMECONST</CODE>. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="long int precision"> |
| <synopsis> |
| This value represents the accuracy or the maximum error when reading the |
| system clock. The value is expressed in microseconds. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="long int tolerance"> |
| <synopsis> |
| This value represents the maximum frequency error of the system clock in |
| scaled PPM. This value is used to increase the <CODE>maxerror</CODE> every |
| second. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="struct timeval time"> |
| <synopsis> |
| The current calendar time. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="long int tick"> |
| <synopsis> |
| The elapsed time between clock ticks in microseconds. A clock tick is a |
| periodic timer interrupt on which the system clock is based. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="long int ppsfreq"> |
| <synopsis> |
| This is the first of a few optional variables that are present only if |
| the system clock can use a PPS (pulse per second) signal to discipline |
| the system clock. The value is expressed in scaled PPM and it denotes |
| the difference in frequency between the system clock and the PPS signal. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="long int jitter"> |
| <synopsis> |
| This value expresses a median filtered average of the PPS signal's |
| dispersion in microseconds. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="int shift"> |
| <synopsis> |
| This value is a binary exponent for the duration of the PPS calibration |
| interval, ranging from <CODE>PPS_SHIFT</CODE> to <CODE>PPS_SHIFTMAX</CODE>. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="long int stabil"> |
| <synopsis> |
| This value represents the median filtered dispersion of the PPS |
| frequency in scaled PPM. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="long int jitcnt"> |
| <synopsis> |
| This counter represents the number of pulses where the jitter exceeded |
| the allowed maximum <CODE>MAXTIME</CODE>. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="long int calcnt"> |
| <synopsis> |
| This counter reflects the number of successful calibration intervals. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="long int errcnt"> |
| <synopsis> |
| This counter represents the number of calibration errors (caused by |
| large offsets or jitter). |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="function-ntp_adjtime" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="struct timex *tptr"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/timex.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>ntp_adjtime</CODE> function sets the structure specified by |
| <VAR>tptr</VAR> to current values. |
| <br><br> In addition, <CODE>ntp_adjtime</CODE> updates some settings to match what you |
| pass to it in *<VAR>tptr</VAR>. Use the <CODE>modes</CODE> element of *<VAR>tptr</VAR> |
| to select what settings to update. You can set <CODE>offset</CODE>, |
| <CODE>freq</CODE>, <CODE>maxerror</CODE>, <CODE>esterror</CODE>, <CODE>status</CODE>, |
| <CODE>constant</CODE>, and <CODE>tick</CODE>. |
| <br><br> <CODE>modes</CODE> = zero means set nothing. |
| <br><br> Only the superuser can update settings. |
| <br><br> <br><br> The return value is <CODE>0</CODE> on success and other values on failure. The |
| following <CODE>errno</CODE> error conditions are defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>TIME_ERROR</CODE> |
| <DD> |
| The high accuracy clock model is not properly set up at the moment, thus the |
| clock must be considered unsynchronized, and the values should be |
| treated with care. Another reason could be that the specified new values |
| are not allowed. |
| <br><br> <LI> EPERM |
| The process specified a settings update, but is not superuser. |
| <br><br> |
| <br><br> For more details see RFC1305 (Network Time Protocol, Version 3) and |
| related documents. |
| <br><br> Portability note: Early versions of the GNU C library did not |
| have this function but did have the synonymous <CODE>adjtimex</CODE>. |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-asctime" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="const struct tm *brokentime"/> |
| </prototype> |
| <headers> |
| <header filename = "time.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>asctime</CODE> function converts the broken-down time value that |
| <VAR>brokentime</VAR> points to into a string in a standard format: |
| <br><br> <pre><br> |
| "Tue May 21 13:46:22 1991\n"<br> |
| </pre> |
| <br><br> The abbreviations for the days of week are: <samp>Sun</samp>, <samp>Mon</samp>, |
| <samp>Tue</samp>, <samp>Wed</samp>, <samp>Thu</samp>, <samp>Fri</samp>, and <samp>Sat</samp>. |
| <br><br> The abbreviations for the months are: <samp>Jan</samp>, <samp>Feb</samp>, |
| <samp>Mar</samp>, <samp>Apr</samp>, <samp>May</samp>, <samp>Jun</samp>, <samp>Jul</samp>, <samp>Aug</samp>, |
| <samp>Sep</samp>, <samp>Oct</samp>, <samp>Nov</samp>, and <samp>Dec</samp>. |
| <br><br> The return value points to a statically allocated string, which might be |
| overwritten by subsequent calls to <CODE>asctime</CODE> or <CODE>ctime</CODE>. |
| (But no other library function overwrites the contents of this |
| string.) |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-asctime_r" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="const struct tm *brokentime"/> |
| <parameter content="char *buffer"/> |
| </prototype> |
| <headers> |
| <header filename = "time.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to <CODE>asctime</CODE> but instead of placing the |
| result in a static buffer it writes the string in the buffer pointed to |
| by the parameter <VAR>buffer</VAR>. This buffer should have room |
| for at least 26 bytes, including the terminating null. |
| <br><br> If no error occurred the function returns a pointer to the string the |
| result was written into, i.e., it returns <VAR>buffer</VAR>. Otherwise |
| return <CODE>NULL</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-ctime" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="const time_t *time"/> |
| </prototype> |
| <headers> |
| <header filename = "time.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>ctime</CODE> function is similar to <CODE>asctime</CODE>, except that you |
| specify the calendar time argument as a <CODE>time_t</CODE> simple time value |
| rather than in broken-down local time format. It is equivalent to |
| <br><br> <pre><br> |
| asctime (localtime (<VAR>time</VAR>))<br> |
| </pre> |
| <br><br> <CODE>ctime</CODE> sets the variable <CODE>tzname</CODE>, because <CODE>localtime</CODE> |
| does so. . |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-ctime_r" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="const time_t *time"/> |
| <parameter content="char *buffer"/> |
| </prototype> |
| <headers> |
| <header filename = "time.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to <CODE>ctime</CODE>, but places the result in the |
| string pointed to by <VAR>buffer</VAR>. It is equivalent to (written using |
| gcc extensions, ): |
| <br><br> <pre><br> |
| ({ struct tm tm; asctime_r (localtime_r (time, &tm), buf); })<br> |
| </pre> |
| <br><br> If no error occurred the function returns a pointer to the string the |
| result was written into, i.e., it returns <VAR>buffer</VAR>. Otherwise |
| return <CODE>NULL</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-strftime" type="function"> |
| <function returntype="size_t"> |
| <prototype> |
| <parameter content="char *s"/> |
| <parameter content="size_t size"/> |
| <parameter content="const char *template"/> |
| <parameter content="const struct tm *brokentime"/> |
| </prototype> |
| <headers> |
| <header filename = "time.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to the <CODE>sprintf</CODE> function , but the conversion specifications that can appear in the format |
| template <VAR>template</VAR> are specialized for printing components of the date |
| and time <VAR>brokentime</VAR> according to the locale currently specified for |
| time conversion . |
| <br><br> Ordinary characters appearing in the <VAR>template</VAR> are copied to the |
| output string <VAR>s</VAR>; this can include multibyte character sequences. |
| Conversion specifiers are introduced by a <samp>%</samp> character, followed |
| by an optional flag which can be one of the following. These flags |
| are all GNU extensions. The first three affect only the output of |
| numbers: |
| <br><br> <DL> |
| |
| <DT><CODE>_</CODE> |
| <DD> |
| The number is padded with spaces. |
| <br><br> <DT><CODE>-</CODE> |
| <DD> |
| The number is not padded at all. |
| <br><br> <DT><CODE>0</CODE> |
| <DD> |
| The number is padded with zeros even if the format specifies padding |
| with spaces. |
| <br><br> <LI> ^ |
| The output uses uppercase characters, but only if this is possible |
| . |
| |
| <br><br> The default action is to pad the number with zeros to keep it a constant |
| width. Numbers that do not have a range indicated below are never |
| padded, since there is no natural width for them. |
| <br><br> Following the flag an optional specification of the width is possible. |
| This is specified in decimal notation. If the natural size of the |
| output is of the field has less than the specified number of characters, |
| the result is written right adjusted and space padded to the given |
| size. |
| <br><br> An optional modifier can follow the optional flag and width |
| specification. The modifiers, which were first standardized by |
| POSIX.2-1992 and by ISO C99, are: |
| <br><br> <DL> |
| |
| <LI> E |
| Use the locale's alternate representation for date and time. This |
| modifier applies to the <CODE>%c</CODE>, <CODE>%C</CODE>, <CODE>%x</CODE>, <CODE>%X</CODE>, |
| <CODE>%y</CODE> and <CODE>%Y</CODE> format specifiers. In a Japanese locale, for |
| example, <CODE>%Ex</CODE> might yield a date format based on the Japanese |
| Emperors' reigns. |
| <br><br> <LI> O |
| Use the locale's alternate numeric symbols for numbers. This modifier |
| applies only to numeric format specifiers. |
| |
| <br><br> If the format supports the modifier but no alternate representation |
| is available, it is ignored. |
| <br><br> The conversion specifier ends with a format specifier taken from the |
| following list. The whole <samp>%</samp> sequence is replaced in the output |
| string as follows: |
| <br><br> <DL> |
| |
| <LI> %a |
| The abbreviated weekday name according to the current locale. |
| <br><br> <LI> %A |
| The full weekday name according to the current locale. |
| <br><br> <LI> %b |
| The abbreviated month name according to the current locale. |
| <br><br> <LI> %B |
| The full month name according to the current locale. |
| <br><br> Using <CODE>%B</CODE> together with <CODE>%d</CODE> produces grammatically |
| incorrect results for some locales. |
| <br><br> <LI> %c |
| The preferred calendar time representation for the current locale. |
| <br><br> <LI> %C |
| The century of the year. This is equivalent to the greatest integer not |
| greater than the year divided by 100. |
| <br><br> This format was first standardized by POSIX.2-1992 and by ISO C99. |
| <br><br> <LI> %d |
| The day of the month as a decimal number (range <CODE>01</CODE> through <CODE>31</CODE>). |
| <br><br> <LI> %D |
| The date using the format <CODE>%m/%d/%y</CODE>. |
| <br><br> This format was first standardized by POSIX.2-1992 and by ISO C99. |
| <br><br> <LI> %e |
| The day of the month like with <CODE>%d</CODE>, but padded with blank (range |
| <CODE> 1</CODE> through <CODE>31</CODE>). |
| <br><br> This format was first standardized by POSIX.2-1992 and by ISO C99. |
| <br><br> <LI> %F |
| The date using the format <CODE>%Y-%m-%d</CODE>. This is the form specified |
| in the ISO 8601 standard and is the preferred form for all uses. |
| <br><br> This format was first standardized by ISO C99 and by POSIX.1-2001. |
| <br><br> <LI> %g |
| The year corresponding to the ISO week number, but without the century |
| (range <CODE>00</CODE> through <CODE>99</CODE>). This has the same format and value |
| as <CODE>%y</CODE>, except that if the ISO week number (see <CODE>%V</CODE>) belongs |
| to the previous or next year, that year is used instead. |
| <br><br> This format was first standardized by ISO C99 and by POSIX.1-2001. |
| <br><br> <LI> %G |
| The year corresponding to the ISO week number. This has the same format |
| and value as <CODE>%Y</CODE>, except that if the ISO week number (see |
| <CODE>%V</CODE>) belongs to the previous or next year, that year is used |
| instead. |
| <br><br> This format was first standardized by ISO C99 and by POSIX.1-2001 |
| but was previously available as a GNU extension. |
| <br><br> <LI> %h |
| The abbreviated month name according to the current locale. The action |
| is the same as for <CODE>%b</CODE>. |
| <br><br> This format was first standardized by POSIX.2-1992 and by ISO C99. |
| <br><br> <LI> %H |
| The hour as a decimal number, using a 24-hour clock (range <CODE>00</CODE> through |
| <CODE>23</CODE>). |
| <br><br> <LI> %I |
| The hour as a decimal number, using a 12-hour clock (range <CODE>01</CODE> through |
| <CODE>12</CODE>). |
| <br><br> <LI> %j |
| The day of the year as a decimal number (range <CODE>001</CODE> through <CODE>366</CODE>). |
| <br><br> <LI> %k |
| The hour as a decimal number, using a 24-hour clock like <CODE>%H</CODE>, but |
| padded with blank (range <CODE> 0</CODE> through <CODE>23</CODE>). |
| <br><br> This format is a GNU extension. |
| <br><br> <LI> %l |
| The hour as a decimal number, using a 12-hour clock like <CODE>%I</CODE>, but |
| padded with blank (range <CODE> 1</CODE> through <CODE>12</CODE>). |
| <br><br> This format is a GNU extension. |
| <br><br> <LI> %m |
| The month as a decimal number (range <CODE>01</CODE> through <CODE>12</CODE>). |
| <br><br> <LI> %M |
| The minute as a decimal number (range <CODE>00</CODE> through <CODE>59</CODE>). |
| <br><br> <LI> %n |
| A single <samp>\n</samp> (newline) character. |
| <br><br> This format was first standardized by POSIX.2-1992 and by ISO C99. |
| <br><br> <LI> %p |
| Either <samp>AM</samp> or <samp>PM</samp>, according to the given time value; or the |
| corresponding strings for the current locale. Noon is treated as |
| <samp>PM</samp> and midnight as <samp>AM</samp>. In most locales |
| <samp>AM</samp>/<samp>PM</samp> format is not supported, in such cases <CODE>"%p"</CODE> |
| yields an empty string. |
| <br><br> |
| <LI> %P |
| Either <samp>am</samp> or <samp>pm</samp>, according to the given time value; or the |
| corresponding strings for the current locale, printed in lowercase |
| characters. Noon is treated as <samp>pm</samp> and midnight as <samp>am</samp>. In |
| most locales <samp>AM</samp>/<samp>PM</samp> format is not supported, in such cases |
| <CODE>"%P"</CODE> yields an empty string. |
| <br><br> This format is a GNU extension. |
| <br><br> <LI> %r |
| The complete calendar time using the AM/PM format of the current locale. |
| <br><br> This format was first standardized by POSIX.2-1992 and by ISO C99. |
| In the POSIX locale, this format is equivalent to <CODE>%I:%M:%S %p</CODE>. |
| <br><br> <LI> %R |
| The hour and minute in decimal numbers using the format <CODE>%H:%M</CODE>. |
| <br><br> This format was first standardized by ISO C99 and by POSIX.1-2001 |
| but was previously available as a GNU extension. |
| <br><br> <LI> %s |
| The number of seconds since the epoch, i.e., since 1970-01-01 00:00:00 UTC. |
| Leap seconds are not counted unless leap second support is available. |
| <br><br> This format is a GNU extension. |
| <br><br> <LI> %S |
| The seconds as a decimal number (range <CODE>00</CODE> through <CODE>60</CODE>). |
| <br><br> <LI> %t |
| A single <samp>\t</samp> (tabulator) character. |
| <br><br> This format was first standardized by POSIX.2-1992 and by ISO C99. |
| <br><br> <LI> %T |
| The time of day using decimal numbers using the format <CODE>%H:%M:%S</CODE>. |
| <br><br> This format was first standardized by POSIX.2-1992 and by ISO C99. |
| <br><br> <LI> %u |
| The day of the week as a decimal number (range <CODE>1</CODE> through |
| <CODE>7</CODE>), Monday being <CODE>1</CODE>. |
| <br><br> This format was first standardized by POSIX.2-1992 and by ISO C99. |
| <br><br> <LI> %U |
| The week number of the current year as a decimal number (range <CODE>00</CODE> |
| through <CODE>53</CODE>), starting with the first Sunday as the first day of |
| the first week. Days preceding the first Sunday in the year are |
| considered to be in week <CODE>00</CODE>. |
| <br><br> <LI> %V |
| The ISO 8601:1988 week number as a decimal number (range <CODE>01</CODE> |
| through <CODE>53</CODE>). ISO weeks start with Monday and end with Sunday. |
| Week <CODE>01</CODE> of a year is the first week which has the majority of its |
| days in that year; this is equivalent to the week containing the year's |
| first Thursday, and it is also equivalent to the week containing January |
| 4. Week <CODE>01</CODE> of a year can contain days from the previous year. |
| The week before week <CODE>01</CODE> of a year is the last week (<CODE>52</CODE> or |
| <CODE>53</CODE>) of the previous year even if it contains days from the new |
| year. |
| <br><br> This format was first standardized by POSIX.2-1992 and by ISO C99. |
| <br><br> <LI> %w |
| The day of the week as a decimal number (range <CODE>0</CODE> through |
| <CODE>6</CODE>), Sunday being <CODE>0</CODE>. |
| <br><br> <LI> %W |
| The week number of the current year as a decimal number (range <CODE>00</CODE> |
| through <CODE>53</CODE>), starting with the first Monday as the first day of |
| the first week. All days preceding the first Monday in the year are |
| considered to be in week <CODE>00</CODE>. |
| <br><br> <LI> %x |
| The preferred date representation for the current locale. |
| <br><br> <LI> %X |
| The preferred time of day representation for the current locale. |
| <br><br> <LI> %y |
| The year without a century as a decimal number (range <CODE>00</CODE> through |
| <CODE>99</CODE>). This is equivalent to the year modulo 100. |
| <br><br> <LI> %Y |
| The year as a decimal number, using the Gregorian calendar. Years |
| before the year <CODE>1</CODE> are numbered <CODE>0</CODE>, <CODE>-1</CODE>, and so on. |
| <br><br> <LI> %z |
| RFC 822/ISO 8601:1988 style numeric time zone (e.g., |
| <CODE>-0600</CODE> or <CODE>+0100</CODE>), or nothing if no time zone is |
| determinable. |
| <br><br> This format was first standardized by ISO C99 and by POSIX.1-2001 |
| but was previously available as a GNU extension. |
| <br><br> In the POSIX locale, a full RFC 822 timestamp is generated by the format |
| <samp>"%a, %d %b %Y %H:%M:%S %z"</samp> (or the equivalent |
| <samp>"%a, %d %b %Y %T %z"</samp>). |
| <br><br> <LI> %Z |
| The time zone abbreviation (empty if the time zone can't be determined). |
| <br><br> <LI> %% |
| A literal <samp>%</samp> character. |
| |
| <br><br> The <VAR>size</VAR> parameter can be used to specify the maximum number of |
| characters to be stored in the array <VAR>s</VAR>, including the terminating |
| null character. If the formatted time requires more than <VAR>size</VAR> |
| characters, <CODE>strftime</CODE> returns zero and the contents of the array |
| <VAR>s</VAR> are undefined. Otherwise the return value indicates the |
| number of characters placed in the array <VAR>s</VAR>, not including the |
| terminating null character. |
| <br><br> <EM>Warning:</EM> This convention for the return value which is prescribed |
| in ISO C can lead to problems in some situations. For certain |
| format strings and certain locales the output really can be the empty |
| string and this cannot be discovered by testing the return value only. |
| E.g., in most locales the AM/PM time format is not supported (most of |
| the world uses the 24 hour time representation). In such locales |
| <CODE>"%p"</CODE> will return the empty string, i.e., the return value is |
| zero. To detect situations like this something similar to the following |
| code should be used: |
| <br><br> <pre><br> |
| buf[0] = '\1';<br> |
| len = strftime (buf, bufsize, format, tp);<br> |
| if (len == 0 && buf[0] != '\0')<br> |
| {<br> |
| /* Something went wrong in the strftime call. */<br> |
| <small>...</small><br> |
| }<br> |
| </pre> |
| <br><br> If <VAR>s</VAR> is a null pointer, <CODE>strftime</CODE> does not actually write |
| anything, but instead returns the number of characters it would have written. |
| <br><br> According to POSIX.1 every call to <CODE>strftime</CODE> implies a call to |
| <CODE>tzset</CODE>. So the contents of the environment variable <CODE>TZ</CODE> |
| is examined before any output is produced. |
| <br><br> For an example of <CODE>strftime</CODE>, see Time Functions Example. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-wcsftime" type="function"> |
| <function returntype="size_t"> |
| <prototype> |
| <parameter content="wchar_t *s"/> |
| <parameter content="size_t size"/> |
| <parameter content="const wchar_t *template"/> |
| <parameter content="const struct tm *brokentime"/> |
| </prototype> |
| <headers> |
| <header filename = "time.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>wcsftime</CODE> function is equivalent to the <CODE>strftime</CODE> |
| function with the difference that it operates on wide character |
| strings. The buffer where the result is stored, pointed to by <VAR>s</VAR>, |
| must be an array of wide characters. The parameter <VAR>size</VAR> which |
| specifies the size of the output buffer gives the number of wide |
| character, not the number of bytes. |
| <br><br> Also the format string <VAR>template</VAR> is a wide character string. Since |
| all characters needed to specify the format string are in the basic |
| character set it is portably possible to write format strings in the C |
| source code using the <CODE>L"<small>...</small>"</CODE> notation. The parameter |
| <VAR>brokentime</VAR> has the same meaning as in the <CODE>strftime</CODE> call. |
| <br><br> The <CODE>wcsftime</CODE> function supports the same flags, modifiers, and |
| format specifiers as the <CODE>strftime</CODE> function. |
| <br><br> The return value of <CODE>wcsftime</CODE> is the number of wide characters |
| stored in <CODE>s</CODE>. When more characters would have to be written than |
| can be placed in the buffer <VAR>s</VAR> the return value is zero, with the |
| same problems indicated in the <CODE>strftime</CODE> documentation. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-strptime" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="const char *s"/> |
| <parameter content="const char *fmt"/> |
| <parameter content="struct tm *tp"/> |
| </prototype> |
| <headers> |
| <header filename = "time.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>strptime</CODE> function parses the input string <VAR>s</VAR> according |
| to the format string <VAR>fmt</VAR> and stores its results in the |
| structure <VAR>tp</VAR>. |
| <br><br> The input string could be generated by a <CODE>strftime</CODE> call or |
| obtained any other way. It does not need to be in a human-recognizable |
| format; e.g. a date passed as <CODE>"02:1999:9"</CODE> is acceptable, even |
| though it is ambiguous without context. As long as the format string |
| <VAR>fmt</VAR> matches the input string the function will succeed. |
| <br><br> The user has to make sure, though, that the input can be parsed in a |
| unambiguous way. The string <CODE>"1999112"</CODE> can be parsed using the |
| format <CODE>"%Y%m%d"</CODE> as 1999-1-12, 1999-11-2, or even 19991-1-2. It |
| is necessary to add appropriate separators to reliably get results. |
| <br><br> The format string consists of the same components as the format string |
| of the <CODE>strftime</CODE> function. The only difference is that the flags |
| <CODE>_</CODE>, <CODE>-</CODE>, <CODE>0</CODE>, and <CODE>^</CODE> are not allowed. |
| Several of the distinct formats of <CODE>strftime</CODE> do the same work in |
| <CODE>strptime</CODE> since differences like case of the input do not matter. |
| For reasons of symmetry all formats are supported, though. |
| <br><br> The modifiers <CODE>E</CODE> and <CODE>O</CODE> are also allowed everywhere the |
| <CODE>strftime</CODE> function allows them. |
| <br><br> The formats are: |
| <br><br> <DL> |
| |
| <DT><CODE>%a</CODE> |
| <DD> |
| <LI>x %A |
| The weekday name according to the current locale, in abbreviated form or |
| the full name. |
| <br><br> <LI> %b |
| <LI>x %B |
| <LI>x %h |
| The month name according to the current locale, in abbreviated form or |
| the full name. |
| <br><br> <LI> %c |
| The date and time representation for the current locale. |
| <br><br> <LI> %Ec |
| Like <CODE>%c</CODE> but the locale's alternative date and time format is used. |
| <br><br> <LI> %C |
| The century of the year. |
| <br><br> It makes sense to use this format only if the format string also |
| contains the <CODE>%y</CODE> format. |
| <br><br> <LI> %EC |
| The locale's representation of the period. |
| <br><br> Unlike <CODE>%C</CODE> it sometimes makes sense to use this format since some |
| cultures represent years relative to the beginning of eras instead of |
| using the Gregorian years. |
| <br><br> <LI> %d |
| <LI> %e |
| The day of the month as a decimal number (range <CODE>1</CODE> through <CODE>31</CODE>). |
| Leading zeroes are permitted but not required. |
| <br><br> <LI> %Od |
| <LI>x %Oe |
| Same as <CODE>%d</CODE> but using the locale's alternative numeric symbols. |
| <br><br> Leading zeroes are permitted but not required. |
| <br><br> <LI> %D |
| Equivalent to <CODE>%m/%d/%y</CODE>. |
| <br><br> <LI> %F |
| Equivalent to <CODE>%Y-%m-%d</CODE>, which is the ISO 8601 date |
| format. |
| <br><br> This is a GNU extension following an ISO C99 extension to |
| <CODE>strftime</CODE>. |
| <br><br> <LI> %g |
| The year corresponding to the ISO week number, but without the century |
| (range <CODE>00</CODE> through <CODE>99</CODE>). |
| <br><br> <EM>Note:</EM> Currently, this is not fully implemented. The format is |
| recognized, input is consumed but no field in <VAR>tm</VAR> is set. |
| <br><br> This format is a GNU extension following a GNU extension of <CODE>strftime</CODE>. |
| <br><br> <LI> %G |
| The year corresponding to the ISO week number. |
| <br><br> <EM>Note:</EM> Currently, this is not fully implemented. The format is |
| recognized, input is consumed but no field in <VAR>tm</VAR> is set. |
| <br><br> This format is a GNU extension following a GNU extension of <CODE>strftime</CODE>. |
| <br><br> <LI> %H |
| <LI>x %k |
| The hour as a decimal number, using a 24-hour clock (range <CODE>00</CODE> through |
| <CODE>23</CODE>). |
| <br><br> <CODE>%k</CODE> is a GNU extension following a GNU extension of <CODE>strftime</CODE>. |
| <br><br> <LI> %OH |
| Same as <CODE>%H</CODE> but using the locale's alternative numeric symbols. |
| <br><br> <LI> %I |
| <LI>x %l |
| The hour as a decimal number, using a 12-hour clock (range <CODE>01</CODE> through |
| <CODE>12</CODE>). |
| <br><br> <CODE>%l</CODE> is a GNU extension following a GNU extension of <CODE>strftime</CODE>. |
| <br><br> <LI> %OI |
| Same as <CODE>%I</CODE> but using the locale's alternative numeric symbols. |
| <br><br> <LI> %j |
| The day of the year as a decimal number (range <CODE>1</CODE> through <CODE>366</CODE>). |
| <br><br> Leading zeroes are permitted but not required. |
| <br><br> <LI> %m |
| The month as a decimal number (range <CODE>1</CODE> through <CODE>12</CODE>). |
| <br><br> Leading zeroes are permitted but not required. |
| <br><br> <LI> %Om |
| Same as <CODE>%m</CODE> but using the locale's alternative numeric symbols. |
| <br><br> <LI> %M |
| The minute as a decimal number (range <CODE>0</CODE> through <CODE>59</CODE>). |
| <br><br> Leading zeroes are permitted but not required. |
| <br><br> <LI> %OM |
| Same as <CODE>%M</CODE> but using the locale's alternative numeric symbols. |
| <br><br> <LI> %n |
| <LI>x %t |
| Matches any white space. |
| <br><br> <LI> %p |
| <LI> %P |
| The locale-dependent equivalent to <samp>AM</samp> or <samp>PM</samp>. |
| <br><br> This format is not useful unless <CODE>%I</CODE> or <CODE>%l</CODE> is also used. |
| Another complication is that the locale might not define these values at |
| all and therefore the conversion fails. |
| <br><br> <CODE>%P</CODE> is a GNU extension following a GNU extension to <CODE>strftime</CODE>. |
| <br><br> <LI> %r |
| The complete time using the AM/PM format of the current locale. |
| <br><br> A complication is that the locale might not define this format at all |
| and therefore the conversion fails. |
| <br><br> <LI> %R |
| The hour and minute in decimal numbers using the format <CODE>%H:%M</CODE>. |
| <br><br> <CODE>%R</CODE> is a GNU extension following a GNU extension to <CODE>strftime</CODE>. |
| <br><br> <LI> %s |
| The number of seconds since the epoch, i.e., since 1970-01-01 00:00:00 UTC. |
| Leap seconds are not counted unless leap second support is available. |
| <br><br> <CODE>%s</CODE> is a GNU extension following a GNU extension to <CODE>strftime</CODE>. |
| <br><br> <LI> %S |
| The seconds as a decimal number (range <CODE>0</CODE> through <CODE>60</CODE>). |
| <br><br> Leading zeroes are permitted but not required. |
| <br><br> NB: The Unix specification says the upper bound on this value |
| is <CODE>61</CODE>, a result of a decision to allow double leap seconds. You |
| will not see the value <CODE>61</CODE> because no minute has more than one |
| leap second, but the myth persists. |
| <br><br> <LI> %OS |
| Same as <CODE>%S</CODE> but using the locale's alternative numeric symbols. |
| <br><br> <LI> %T |
| Equivalent to the use of <CODE>%H:%M:%S</CODE> in this place. |
| <br><br> <LI> %u |
| The day of the week as a decimal number (range <CODE>1</CODE> through |
| <CODE>7</CODE>), Monday being <CODE>1</CODE>. |
| <br><br> Leading zeroes are permitted but not required. |
| <br><br> <EM>Note:</EM> Currently, this is not fully implemented. The format is |
| recognized, input is consumed but no field in <VAR>tm</VAR> is set. |
| <br><br> <LI> %U |
| The week number of the current year as a decimal number (range <CODE>0</CODE> |
| through <CODE>53</CODE>). |
| <br><br> Leading zeroes are permitted but not required. |
| <br><br> <LI> %OU |
| Same as <CODE>%U</CODE> but using the locale's alternative numeric symbols. |
| <br><br> <LI> %V |
| The ISO 8601:1988 week number as a decimal number (range <CODE>1</CODE> |
| through <CODE>53</CODE>). |
| <br><br> Leading zeroes are permitted but not required. |
| <br><br> <EM>Note:</EM> Currently, this is not fully implemented. The format is |
| recognized, input is consumed but no field in <VAR>tm</VAR> is set. |
| <br><br> <LI> %w |
| The day of the week as a decimal number (range <CODE>0</CODE> through |
| <CODE>6</CODE>), Sunday being <CODE>0</CODE>. |
| <br><br> Leading zeroes are permitted but not required. |
| <br><br> <EM>Note:</EM> Currently, this is not fully implemented. The format is |
| recognized, input is consumed but no field in <VAR>tm</VAR> is set. |
| <br><br> <LI> %Ow |
| Same as <CODE>%w</CODE> but using the locale's alternative numeric symbols. |
| <br><br> <LI> %W |
| The week number of the current year as a decimal number (range <CODE>0</CODE> |
| through <CODE>53</CODE>). |
| <br><br> Leading zeroes are permitted but not required. |
| <br><br> <EM>Note:</EM> Currently, this is not fully implemented. The format is |
| recognized, input is consumed but no field in <VAR>tm</VAR> is set. |
| <br><br> <LI> %OW |
| Same as <CODE>%W</CODE> but using the locale's alternative numeric symbols. |
| <br><br> <LI> %x |
| The date using the locale's date format. |
| <br><br> <LI> %Ex |
| Like <CODE>%x</CODE> but the locale's alternative data representation is used. |
| <br><br> <LI> %X |
| The time using the locale's time format. |
| <br><br> <LI> %EX |
| Like <CODE>%X</CODE> but the locale's alternative time representation is used. |
| <br><br> <LI> %y |
| The year without a century as a decimal number (range <CODE>0</CODE> through |
| <CODE>99</CODE>). |
| <br><br> Leading zeroes are permitted but not required. |
| <br><br> Note that it is questionable to use this format without |
| the <CODE>%C</CODE> format. The <CODE>strptime</CODE> function does regard input |
| values in the range 68 to 99 as the years 1969 to |
| 1999 and the values 0 to 68 as the years |
| 2000 to 2068. But maybe this heuristic fails for some |
| input data. |
| <br><br> Therefore it is best to avoid <CODE>%y</CODE> completely and use <CODE>%Y</CODE> |
| instead. |
| <br><br> <LI> %Ey |
| The offset from <CODE>%EC</CODE> in the locale's alternative representation. |
| <br><br> <LI> %Oy |
| The offset of the year (from <CODE>%C</CODE>) using the locale's alternative |
| numeric symbols. |
| <br><br> <LI> %Y |
| The year as a decimal number, using the Gregorian calendar. |
| <br><br> <LI> %EY |
| The full alternative year representation. |
| <br><br> <LI> %z |
| The offset from GMT in ISO 8601/RFC822 format. |
| <br><br> <LI> %Z |
| The timezone name. |
| <br><br> <EM>Note:</EM> Currently, this is not fully implemented. The format is |
| recognized, input is consumed but no field in <VAR>tm</VAR> is set. |
| <br><br> <LI> %% |
| A literal <samp>%</samp> character. |
| |
| <br><br> All other characters in the format string must have a matching character |
| in the input string. Exceptions are white spaces in the input string |
| which can match zero or more whitespace characters in the format string. |
| <br><br> Portability Note: The XPG standard advises applications to use |
| at least one whitespace character (as specified by <CODE>isspace</CODE>) or |
| other non-alphanumeric characters between any two conversion |
| specifications. The GNU C Library does not have this limitation but |
| other libraries might have trouble parsing formats like |
| <CODE>"%d%m%Y%H%M%S"</CODE>. |
| <br><br> The <CODE>strptime</CODE> function processes the input string from right to |
| left. Each of the three possible input elements (white space, literal, |
| or format) are handled one after the other. If the input cannot be |
| matched to the format string the function stops. The remainder of the |
| format and input strings are not processed. |
| <br><br> The function returns a pointer to the first character it was unable to |
| process. If the input string contains more characters than required by |
| the format string the return value points right after the last consumed |
| input character. If the whole input string is consumed the return value |
| points to the <CODE>NULL</CODE> byte at the end of the string. If an error |
| occurs, i.e., <CODE>strptime</CODE> fails to match all of the format string, |
| the function returns <CODE>NULL</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getdate" type="function"> |
| <function returntype="struct tm *"> |
| <prototype> |
| <parameter content="const char *string"/> |
| </prototype> |
| <headers> |
| <header filename = "time.h"/> |
| </headers> |
| <synopsis> |
| The interface to <CODE>getdate</CODE> is the simplest possible for a function |
| to parse a string and return the value. <VAR>string</VAR> is the input |
| string and the result is returned in a statically-allocated variable. |
| <br><br> The details about how the string is processed are hidden from the user. |
| In fact, they can be outside the control of the program. Which formats |
| are recognized is controlled by the file named by the environment |
| variable <CODE>DATEMSK</CODE>. This file should contain |
| lines of valid format strings which could be passed to <CODE>strptime</CODE>. |
| <br><br> The <CODE>getdate</CODE> function reads these format strings one after the |
| other and tries to match the input string. The first line which |
| completely matches the input string is used. |
| <br><br> Elements not initialized through the format string retain the values |
| present at the time of the <CODE>getdate</CODE> function call. |
| <br><br> The formats recognized by <CODE>getdate</CODE> are the same as for |
| <CODE>strptime</CODE>. See above for an explanation. There are only a few |
| extensions to the <CODE>strptime</CODE> behavior: |
| <br><br> <OL> |
| <LI> |
| If the <CODE>%Z</CODE> format is given the broken-down time is based on the |
| current time of the timezone matched, not of the current timezone of the |
| runtime environment. |
| <br><br> <EM>Note</EM>: This is not implemented (currently). The problem is that |
| timezone names are not unique. If a fixed timezone is assumed for a |
| given string (say <CODE>EST</CODE> meaning US East Coast time), then uses for |
| countries other than the USA will fail. So far we have found no good |
| solution to this. |
| <br><br> <LI> |
| If only the weekday is specified the selected day depends on the current |
| date. If the current weekday is greater or equal to the <CODE>tm_wday</CODE> |
| value the current week's day is chosen, otherwise the day next week is chosen. |
| <br><br> <LI> |
| A similar heuristic is used when only the month is given and not the |
| year. If the month is greater than or equal to the current month, then |
| the current year is used. Otherwise it wraps to next year. The first |
| day of the month is assumed if one is not explicitly specified. |
| <br><br> <LI> |
| The current hour, minute, and second are used if the appropriate value is |
| not set through the format. |
| <br><br> <LI> |
| If no date is given tomorrow's date is used if the time is |
| smaller than the current time. Otherwise today's date is taken. |
| </OL> |
| <br><br> It should be noted that the format in the template file need not only |
| contain format elements. The following is a list of possible format |
| strings (taken from the Unix standard): |
| <br><br> <pre><br> |
| %m<br> |
| %A %B %d, %Y %H:%M:%S<br> |
| %A<br> |
| %B<br> |
| %m/%d/%y %I %p<br> |
| %d,%m,%Y %H:%M<br> |
| at %A the %dst of %B in %Y<br> |
| run job at %I %p,%B %dnd<br> |
| %A den %d. %B %Y %H.%M Uhr<br> |
| </pre> |
| <br><br> As you can see, the template list can contain very specific strings like |
| <CODE>run job at %I %p,%B %dnd</CODE>. Using the above list of templates and |
| assuming the current time is Mon Sep 22 12:19:47 EDT 1986 we can obtain the |
| following results for the given input. |
| <br><br> <DL> |
| <DT><pre>Input Match Result</pre> |
| <DD><br> <DT><pre>Mon %a Mon Sep 22 12:19:47 EDT 1986</pre> |
| <DD><br> <DT><pre>Sun %a Sun Sep 28 12:19:47 EDT 1986</pre> |
| <DD><br> <DT><pre>Fri %a Fri Sep 26 12:19:47 EDT 1986</pre> |
| <DD><br> <DT><pre>September %B Mon Sep 1 12:19:47 EDT 1986</pre> |
| <DD><br> <DT><pre>January %B Thu Jan 1 12:19:47 EST 1987</pre> |
| <DD><br> <DT><pre>December %B Mon Dec 1 12:19:47 EST 1986</pre> |
| <DD><br> <DT><pre>Sep Mon %b %a Mon Sep 1 12:19:47 EDT 1986</pre> |
| <DD><br> <DT><pre>Jan Fri %b %a Fri Jan 2 12:19:47 EST 1987</pre> |
| <DD><br> <DT><pre>Dec Mon %b %a Mon Dec 1 12:19:47 EST 1986</pre> |
| <DD><br> <DT><pre>Jan Wed 1989 %b %a %Y Wed Jan 4 12:19:47 EST 1989</pre> |
| <DD><br> <DT><pre>Fri 9 %a %H Fri Sep 26 09:00:00 EDT 1986</pre> |
| <DD><br> <DT><pre>Feb 10:30 %b %H:%S Sun Feb 1 10:00:30 EST 1987</pre> |
| <DD><br> <DT><pre>10:30 %H:%M Tue Sep 23 10:30:00 EDT 1986</pre> |
| <DD><br> <DT><pre>13:30 %H:%M Mon Sep 22 13:30:00 EDT 1986</pre> |
| <DD><br> </DL> |
| <br><br> The return value of the function is a pointer to a static variable of |
| type <CODE>struct tm</CODE>, or a null pointer if an error occurred. The |
| result is only valid until the next <CODE>getdate</CODE> call, making this |
| function unusable in multi-threaded applications. |
| <br><br> The <CODE>errno</CODE> variable is <EM>not</EM> changed. Error conditions are |
| stored in the global variable <CODE>getdate_err</CODE>. See the |
| description above for a list of the possible error values. |
| <br><br> <EM>Warning:</EM> The <CODE>getdate</CODE> function should <EM>never</EM> be |
| used in SUID-programs. The reason is obvious: using the |
| <CODE>DATEMSK</CODE> environment variable you can get the function to open |
| any arbitrary file and chances are high that with some bogus input |
| (such as a binary file) the program will crash. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getdate_r" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *string"/> |
| <parameter content="struct tm *tp"/> |
| </prototype> |
| <headers> |
| <header filename = "time.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>getdate_r</CODE> function is the reentrant counterpart of |
| <CODE>getdate</CODE>. It does not use the global variable <CODE>getdate_err</CODE> |
| to signal an error, but instead returns an error code. The same error |
| codes as described in the <CODE>getdate_err</CODE> documentation above are |
| used, with 0 meaning success. |
| <br><br> Moreover, <CODE>getdate_r</CODE> stores the broken-down time in the variable |
| of type <CODE>struct tm</CODE> pointed to by the second argument, rather than |
| in a static variable. |
| <br><br> This function is not defined in the Unix standard. Nevertheless it is |
| available on some other Unix systems as well. |
| <br><br> The warning against using <CODE>getdate</CODE> in SUID-programs applies to |
| <CODE>getdate_r</CODE> as well. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-tzset" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "time.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>tzset</CODE> function initializes the <CODE>tzname</CODE> variable from |
| the value of the <CODE>TZ</CODE> environment variable. It is not usually |
| necessary for your program to call this function, because it is called |
| automatically when you use the other time conversion functions that |
| depend on the time zone. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="struct-itimerval" type="struct"> |
| <structure> |
| <synopsis> |
| This structure is used to specify when a timer should expire. It contains |
| the following members: |
| </synopsis> |
| <elements> |
| <element content="struct timeval it_interval"> |
| <synopsis> |
| This is the period between successive timer interrupts. If zero, the |
| alarm will only be sent once. |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="function-setitimer" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int which"/> |
| <parameter content="struct itimerval *new"/> |
| <parameter content="struct itimerval *old"/> |
| </prototype> |
| <headers> |
| <header filename = "time.h"/> |
| <header filename = "sys/time.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>setitimer</CODE> function sets the timer specified by <VAR>which</VAR> |
| according to <VAR>new</VAR>. The <VAR>which</VAR> argument can have a value of |
| <CODE>ITIMER_REAL</CODE>, <CODE>ITIMER_VIRTUAL</CODE>, or <CODE>ITIMER_PROF</CODE>. |
| <br><br> If <VAR>old</VAR> is not a null pointer, <CODE>setitimer</CODE> returns information |
| about any previous unexpired timer of the same kind in the structure it |
| points to. |
| <br><br> The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on failure. The |
| following <CODE>errno</CODE> error conditions are defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EINVAL</CODE> |
| <DD> |
| The timer period is too large. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getitimer" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int which"/> |
| <parameter content="struct itimerval *old"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/time.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>getitimer</CODE> function stores information about the timer specified |
| by <VAR>which</VAR> in the structure pointed at by <VAR>old</VAR>. |
| <br><br> The return value and error conditions are the same as for <CODE>setitimer</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-alarm" type="function"> |
| <function returntype="unsigned int"> |
| <prototype> |
| <parameter content="unsigned int seconds"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/time.h"/> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>alarm</CODE> function sets the real-time timer to expire in |
| <VAR>seconds</VAR> seconds. If you want to cancel any existing alarm, you |
| can do this by calling <CODE>alarm</CODE> with a <VAR>seconds</VAR> argument of |
| zero. |
| <br><br> The return value indicates how many seconds remain before the previous |
| alarm would have been sent. If there is no previous alarm, <CODE>alarm</CODE> |
| returns zero. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-sleep" type="function"> |
| <function returntype="unsigned int"> |
| <prototype> |
| <parameter content="unsigned int seconds"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>sleep</CODE> function waits for <VAR>seconds</VAR> or until a signal |
| is delivered, whichever happens first. |
| <br><br> If <CODE>sleep</CODE> function returns because the requested interval is over, |
| it returns a value of zero. If it returns because of delivery of a |
| signal, its return value is the remaining time in the sleep interval. |
| <br><br> The <CODE>sleep</CODE> function is declared in <TT>unistd.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-nanosleep" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const struct timespec *requested_time"/> |
| <parameter content="struct timespec *remaining"/> |
| </prototype> |
| <headers> |
| <header filename = "time.h"/> |
| </headers> |
| <synopsis> |
| If resolution to seconds is not enough the <CODE>nanosleep</CODE> function can |
| be used. As the name suggests the sleep interval can be specified in |
| nanoseconds. The actual elapsed time of the sleep interval might be |
| longer since the system rounds the elapsed time you request up to the |
| next integer multiple of the actual resolution the system can deliver. |
| <br><br> *<CODE>requested_time</CODE> is the elapsed time of the interval you want to |
| sleep. |
| <br><br> The function returns as *<CODE>remaining</CODE> the elapsed time left in the |
| interval for which you requested to sleep. If the interval completed |
| without getting interrupted by a signal, this is zero. |
| <br><br> <CODE>struct timespec</CODE> is described in . |
| <br><br> If the function returns because the interval is over the return value is |
| zero. If the function returns -1 the global variable <VAR>errno</VAR> |
| is set to the following values: |
| <br><br> <DL> |
| |
| <DT><CODE>EINTR</CODE> |
| <DD> |
| The call was interrupted because a signal was delivered to the thread. |
| If the <VAR>remaining</VAR> parameter is not the null pointer the structure |
| pointed to by <VAR>remaining</VAR> is updated to contain the remaining |
| elapsed time. |
| <br><br> <LI> EINVAL |
| The nanosecond value in the <VAR>requested_time</VAR> parameter contains an |
| illegal value. Either the value is negative or greater than or equal to |
| 1000 million. |
| |
| <br><br> This function is a cancellation point in multi-threaded programs. This |
| is a problem if the thread allocates some resources (like memory, file |
| descriptors, semaphores or whatever) at the time <CODE>nanosleep</CODE> is |
| called. If the thread gets canceled these resources stay allocated |
| until the program ends. To avoid this calls to <CODE>nanosleep</CODE> should |
| be protected using cancellation handlers. |
| <br><br> The <CODE>nanosleep</CODE> function is declared in <TT>time.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="dtype-va_list" type="dtype"> |
| <structure> |
| </structure> |
| </construct> |
| <construct id="dtype-ptrdiff_t" type="dtype"> |
| <structure> |
| </structure> |
| </construct> |
| <construct id="dtype-size_t" type="dtype"> |
| <structure> |
| </structure> |
| </construct> |
| <construct id="function-system" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *command"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| This function executes <VAR>command</VAR> as a shell command. In the GNU C |
| library, it always uses the default shell <CODE>sh</CODE> to run the command. |
| In particular, it searches the directories in <CODE>PATH</CODE> to find |
| programs to execute. The return value is <CODE>-1</CODE> if it wasn't |
| possible to create the shell process, and otherwise is the status of the |
| shell process. , for details on how this |
| status code can be interpreted. |
| <br><br> If the <VAR>command</VAR> argument is a null pointer, a return value of zero |
| indicates that no command processor is available. |
| <br><br> This function is a cancellation point in multi-threaded programs. This |
| is a problem if the thread allocates some resources (like memory, file |
| descriptors, semaphores or whatever) at the time <CODE>system</CODE> is |
| called. If the thread gets canceled these resources stay allocated |
| until the program ends. To avoid this calls to <CODE>system</CODE> should be |
| protected using cancellation handlers. |
| <br><br> The <CODE>system</CODE> function is declared in the header file |
| <TT>stdlib.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="dtype-pid_t" type="dtype"> |
| <structure> |
| </structure> |
| </construct> |
| <construct id="function-getpid" type="function"> |
| <function returntype="pid_t"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/types.h"/> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>getpid</CODE> function returns the process ID of the current process. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getppid" type="function"> |
| <function returntype="pid_t"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>getppid</CODE> function returns the process ID of the parent of the |
| current process. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fork" type="function"> |
| <function returntype="pid_t"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>fork</CODE> function creates a new process. |
| <br><br> If the operation is successful, there are then both parent and child |
| processes and both see <CODE>fork</CODE> return, but with different values: it |
| returns a value of <CODE>0</CODE> in the child process and returns the child's |
| process ID in the parent process. |
| <br><br> If process creation failed, <CODE>fork</CODE> returns a value of <CODE>-1</CODE> in |
| the parent process. The following <CODE>errno</CODE> error conditions are |
| defined for <CODE>fork</CODE>: |
| <br><br> <DL> |
| |
| <DT><CODE>EAGAIN</CODE> |
| <DD> |
| There aren't enough system resources to create another process, or the |
| user already has too many processes running. This means exceeding the |
| <CODE>RLIMIT_NPROC</CODE> resource limit, which can usually be increased; |
| . |
| <br><br> <LI> ENOMEM |
| The process requires more space than the system can supply. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-vfork" type="function"> |
| <function returntype="pid_t"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>vfork</CODE> function is similar to <CODE>fork</CODE> but on some systems |
| it is more efficient; however, there are restrictions you must follow to |
| use it safely. |
| <br><br> While <CODE>fork</CODE> makes a complete copy of the calling process's address |
| space and allows both the parent and child to execute independently, |
| <CODE>vfork</CODE> does not make this copy. Instead, the child process |
| created with <CODE>vfork</CODE> shares its parent's address space until it |
| calls <CODE>_exit</CODE> or one of the <CODE>exec</CODE> functions. In the |
| meantime, the parent process suspends execution. |
| <br><br> You must be very careful not to allow the child process created with |
| <CODE>vfork</CODE> to modify any global data or even local variables shared |
| with the parent. Furthermore, the child process cannot return from (or |
| do a long jump out of) the function that called <CODE>vfork</CODE>! This |
| would leave the parent process's control information very confused. If |
| in doubt, use <CODE>fork</CODE> instead. |
| <br><br> Some operating systems don't really implement <CODE>vfork</CODE>. The GNU C |
| library permits you to use <CODE>vfork</CODE> on all systems, but actually |
| executes <CODE>fork</CODE> if <CODE>vfork</CODE> isn't available. If you follow |
| the proper precautions for using <CODE>vfork</CODE>, your program will still |
| work even if the system uses <CODE>fork</CODE> instead. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-execv" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *filename"/> |
| <parameter content="char *const argv[]"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>execv</CODE> function executes the file named by <VAR>filename</VAR> as a |
| new process image. |
| <br><br> The <VAR>argv</VAR> argument is an array of null-terminated strings that is |
| used to provide a value for the <CODE>argv</CODE> argument to the <CODE>main</CODE> |
| function of the program to be executed. The last element of this array |
| must be a null pointer. By convention, the first element of this array |
| is the file name of the program sans directory names. , for full details on how programs can access these arguments. |
| <br><br> The environment for the new process image is taken from the |
| <CODE>environ</CODE> variable of the current process image; see |
| Environment Variables, for information about environments. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-execl" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *filename"/> |
| <parameter content="const char *arg0"/> |
| <parameter content="..."/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| This is similar to <CODE>execv</CODE>, but the <VAR>argv</VAR> strings are |
| specified individually instead of as an array. A null pointer must be |
| passed as the last such argument. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-execve" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *filename"/> |
| <parameter content="char *const argv[]"/> |
| <parameter content="char *const env[]"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| This is similar to <CODE>execv</CODE>, but permits you to specify the environment |
| for the new program explicitly as the <VAR>env</VAR> argument. This should |
| be an array of strings in the same format as for the <CODE>environ</CODE> |
| variable; see Environment Access. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-execle" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *filename"/> |
| <parameter content="const char *arg0"/> |
| <parameter content="char *const env[]"/> |
| <parameter content="..."/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| This is similar to <CODE>execl</CODE>, but permits you to specify the |
| environment for the new program explicitly. The environment argument is |
| passed following the null pointer that marks the last <VAR>argv</VAR> |
| argument, and should be an array of strings in the same format as for |
| the <CODE>environ</CODE> variable. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-execvp" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *filename"/> |
| <parameter content="char *const argv[]"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>execvp</CODE> function is similar to <CODE>execv</CODE>, except that it |
| searches the directories listed in the <CODE>PATH</CODE> environment variable |
| to find the full file name of a |
| file from <VAR>filename</VAR> if <VAR>filename</VAR> does not contain a slash. |
| <br><br> This function is useful for executing system utility programs, because |
| it looks for them in the places that the user has chosen. Shells use it |
| to run the commands that users type. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-execlp" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *filename"/> |
| <parameter content="const char *arg0"/> |
| <parameter content="..."/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| This function is like <CODE>execl</CODE>, except that it performs the same |
| file name searching as the <CODE>execvp</CODE> function. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-waitpid" type="function"> |
| <function returntype="pid_t"> |
| <prototype> |
| <parameter content="pid_t pid"/> |
| <parameter content="int *status-ptr"/> |
| <parameter content="int options"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/wait.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>waitpid</CODE> function is used to request status information from a |
| child process whose process ID is <VAR>pid</VAR>. Normally, the calling |
| process is suspended until the child process makes status information |
| available by terminating. |
| <br><br> Other values for the <VAR>pid</VAR> argument have special interpretations. A |
| value of <CODE>-1</CODE> or <CODE>WAIT_ANY</CODE> requests status information for |
| any child process; a value of <CODE>0</CODE> or <CODE>WAIT_MYPGRP</CODE> requests |
| information for any child process in the same process group as the |
| calling process; and any other negative value <VAR>pgid</VAR> |
| requests information for any child process whose process group ID is |
| <VAR>pgid</VAR>. |
| <br><br> If status information for a child process is available immediately, this |
| function returns immediately without waiting. If more than one eligible |
| child process has status information available, one of them is chosen |
| randomly, and its status is returned immediately. To get the status |
| from the other eligible child processes, you need to call <CODE>waitpid</CODE> |
| again. |
| <br><br> The <VAR>options</VAR> argument is a bit mask. Its value should be the |
| bitwise OR (that is, the <samp>|</samp> operator) of zero or more of the |
| <CODE>WNOHANG</CODE> and <CODE>WUNTRACED</CODE> flags. You can use the |
| <CODE>WNOHANG</CODE> flag to indicate that the parent process shouldn't wait; |
| and the <CODE>WUNTRACED</CODE> flag to request status information from stopped |
| processes as well as processes that have terminated. |
| <br><br> The status information from the child process is stored in the object |
| that <VAR>status-ptr</VAR> points to, unless <VAR>status-ptr</VAR> is a null pointer. |
| <br><br> This function is a cancellation point in multi-threaded programs. This |
| is a problem if the thread allocates some resources (like memory, file |
| descriptors, semaphores or whatever) at the time <CODE>waitpid</CODE> is |
| called. If the thread gets canceled these resources stay allocated |
| until the program ends. To avoid this calls to <CODE>waitpid</CODE> should be |
| protected using cancellation handlers. |
| <br><br> The return value is normally the process ID of the child process whose |
| status is reported. If there are child processes but none of them is |
| waiting to be noticed, <CODE>waitpid</CODE> will block until one is. However, |
| if the <CODE>WNOHANG</CODE> option was specified, <CODE>waitpid</CODE> will return |
| zero instead of blocking. |
| <br><br> If a specific PID to wait for was given to <CODE>waitpid</CODE>, it will |
| ignore all other children (if any). Therefore if there are children |
| waiting to be noticed but the child whose PID was specified is not one |
| of them, <CODE>waitpid</CODE> will block or return zero as described above. |
| <br><br> A value of <CODE>-1</CODE> is returned in case of error. The following |
| <CODE>errno</CODE> error conditions are defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EINTR</CODE> |
| <DD> |
| The function was interrupted by delivery of a signal to the calling |
| process. . |
| <br><br> <LI> ECHILD |
| There are no child processes to wait for, or the specified <VAR>pid</VAR> |
| is not a child of the calling process. |
| <br><br> <LI> EINVAL |
| An invalid value was provided for the <VAR>options</VAR> argument. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-wait" type="function"> |
| <function returntype="pid_t"> |
| <prototype> |
| <parameter content="int *status-ptr"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/wait.h"/> |
| </headers> |
| <synopsis> |
| This is a simplified version of <CODE>waitpid</CODE>, and is used to wait |
| until any one child process terminates. The call: |
| <br><br> <pre><br> |
| wait (&status)<br> |
| </pre><br> |
| <br><br> <br> |
| is exactly equivalent to:<br> |
| <br><br> <pre><br> |
| waitpid (-1, &status, 0)<br> |
| </pre> |
| <br><br> This function is a cancellation point in multi-threaded programs. This |
| is a problem if the thread allocates some resources (like memory, file |
| descriptors, semaphores or whatever) at the time <CODE>wait</CODE> is |
| called. If the thread gets canceled these resources stay allocated |
| until the program ends. To avoid this calls to <CODE>wait</CODE> should be |
| protected using cancellation handlers. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-wait4" type="function"> |
| <function returntype="pid_t"> |
| <prototype> |
| <parameter content="pid_t pid"/> |
| <parameter content="int *status-ptr"/> |
| <parameter content="int options"/> |
| <parameter content="struct rusage *usage"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/wait.h"/> |
| </headers> |
| <synopsis> |
| If <VAR>usage</VAR> is a null pointer, <CODE>wait4</CODE> is equivalent to |
| <CODE>waitpid (<VAR>pid</VAR>, <VAR>status-ptr</VAR>, <VAR>options</VAR>)</CODE>. |
| <br><br> If <VAR>usage</VAR> is not null, <CODE>wait4</CODE> stores usage figures for the |
| child process in <CODE>*<VAR>rusage</VAR></CODE> (but only if the child has |
| terminated, not if it has stopped). . |
| <br><br> This function is a BSD extension. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="union-wait" type="union"> |
| <structure> |
| <synopsis> |
| This data type represents program termination status values. It has |
| the following members: |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="int w_termsig"> |
| <synopsis> |
| The value of this member is the same as that of the |
| <CODE>WTERMSIG</CODE> macro. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="int w_coredump"> |
| <synopsis> |
| The value of this member is the same as that of the |
| <CODE>WCOREDUMP</CODE> macro. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="int w_retcode"> |
| <synopsis> |
| The value of this member is the same as that of the |
| <CODE>WEXITSTATUS</CODE> macro. |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="function-wait3" type="function"> |
| <function returntype="pid_t"> |
| <prototype> |
| <parameter content="union wait *status-ptr"/> |
| <parameter content="int options"/> |
| <parameter content="struct rusage *usage"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/wait.h"/> |
| </headers> |
| <synopsis> |
| If <VAR>usage</VAR> is a null pointer, <CODE>wait3</CODE> is equivalent to |
| <CODE>waitpid (-1, <VAR>status-ptr</VAR>, <VAR>options</VAR>)</CODE>. |
| <br><br> If <VAR>usage</VAR> is not null, <CODE>wait3</CODE> stores usage figures for the |
| child process in <CODE>*<VAR>rusage</VAR></CODE> (but only if the child has |
| terminated, not if it has stopped). . |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getcwd" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="char *buffer"/> |
| <parameter content="size_t size"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>getcwd</CODE> function returns an absolute file name representing |
| the current working directory, storing it in the character array |
| <VAR>buffer</VAR> that you provide. The <VAR>size</VAR> argument is how you tell |
| the system the allocation size of <VAR>buffer</VAR>. |
| <br><br> The GNU library version of this function also permits you to specify a |
| null pointer for the <VAR>buffer</VAR> argument. Then <CODE>getcwd</CODE> |
| allocates a buffer automatically, as with <CODE>malloc</CODE> |
| . If the <VAR>size</VAR> is greater than |
| zero, then the buffer is that large; otherwise, the buffer is as large |
| as necessary to hold the result. |
| <br><br> The return value is <VAR>buffer</VAR> on success and a null pointer on failure. |
| The following <CODE>errno</CODE> error conditions are defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EINVAL</CODE> |
| <DD> |
| The <VAR>size</VAR> argument is zero and <VAR>buffer</VAR> is not a null pointer. |
| <br><br> <LI> ERANGE |
| The <VAR>size</VAR> argument is less than the length of the working directory |
| name. You need to allocate a bigger array and try again. |
| <br><br> <LI> EACCES |
| Permission to read or search a component of the file name was denied. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-get_current_dir_name" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| |
| This <CODE>get_current_dir_name</CODE> function is basically equivalent to |
| <CODE>getcwd (NULL, 0)</CODE>. The only difference is that the value of |
| the <CODE>PWD</CODE> variable is returned if this value is correct. This is a |
| subtle difference which is visible if the path described by the |
| <CODE>PWD</CODE> value is using one or more symbol links in which case the |
| value returned by <CODE>getcwd</CODE> can resolve the symbol links and |
| therefore yield a different result. |
| <br><br> This function is a GNU extension. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-chdir" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *filename"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| This function is used to set the process's working directory to |
| <VAR>filename</VAR>. |
| <br><br> The normal, successful return value from <CODE>chdir</CODE> is <CODE>0</CODE>. A |
| value of <CODE>-1</CODE> is returned to indicate an error. The <CODE>errno</CODE> |
| error conditions defined for this function are the usual file name |
| syntax errors , plus <CODE>ENOTDIR</CODE> if the |
| file <VAR>filename</VAR> is not a directory. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fchdir" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int filedes"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| This function is used to set the process's working directory to |
| directory associated with the file descriptor <VAR>filedes</VAR>. |
| <br><br> The normal, successful return value from <CODE>fchdir</CODE> is <CODE>0</CODE>. A |
| value of <CODE>-1</CODE> is returned to indicate an error. The following |
| <CODE>errno</CODE> error conditions are defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EACCES</CODE> |
| <DD> |
| Read permission is denied for the directory named by <CODE>dirname</CODE>. |
| <br><br> <LI> EBADF |
| The <VAR>filedes</VAR> argument is not a valid file descriptor. |
| <br><br> <LI> ENOTDIR |
| The file descriptor <VAR>filedes</VAR> is not associated with a directory. |
| <br><br> <LI> EINTR |
| The function call was interrupt by a signal. |
| <br><br> <LI> EIO |
| An I/O error occurred. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="struct-dirent" type="struct"> |
| <structure> |
| <synopsis> |
| This is a structure type used to return information about directory |
| entries. It contains the following fields: |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="char d_name[]"> |
| <synopsis> |
| This is the null-terminated file name component. This is the only |
| field you can count on in all POSIX systems. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="ino_t d_fileno"> |
| <synopsis> |
| This is the file serial number. For BSD compatibility, you can also |
| refer to this member as <CODE>d_ino</CODE>. In the GNU system and most POSIX |
| systems, for most files this the same as the <CODE>st_ino</CODE> member that |
| <CODE>stat</CODE> will return for the file. . |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="unsigned char d_namlen"> |
| <synopsis> |
| This is the length of the file name, not including the terminating null |
| character. Its type is <CODE>unsigned char</CODE> because that is the integer |
| type of the appropriate size |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="unsigned char d_type"> |
| <synopsis> |
| This is the type of the file, possibly unknown. The following constants |
| are defined for its value: |
| <br><br> <DL> |
| |
| </synopsis> |
| </element> |
| <element content="DT_UNKNOWN"> |
| <synopsis> |
| The type is unknown. On some systems this is the only value returned. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="DT_REG"> |
| <synopsis> |
| A regular file. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="DT_DIR"> |
| <synopsis> |
| A directory. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="DT_FIFO"> |
| <synopsis> |
| A named pipe, or FIFO. . |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="DT_SOCK"> |
| <synopsis> |
| A local-domain socket. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="DT_CHR"> |
| <synopsis> |
| A character device. |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="dtype-DIR" type="dtype"> |
| <structure> |
| </structure> |
| </construct> |
| <construct id="function-opendir" type="function"> |
| <function returntype="DIR *"> |
| <prototype> |
| <parameter content="const char *dirname"/> |
| </prototype> |
| <headers> |
| <header filename = "dirent.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>opendir</CODE> function opens and returns a directory stream for |
| reading the directory whose file name is <VAR>dirname</VAR>. The stream has |
| type <CODE>DIR *</CODE>. |
| <br><br> If unsuccessful, <CODE>opendir</CODE> returns a null pointer. In addition to |
| the usual file name errors , the |
| following <CODE>errno</CODE> error conditions are defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EACCES</CODE> |
| <DD> |
| Read permission is denied for the directory named by <CODE>dirname</CODE>. |
| <br><br> <LI> EMFILE |
| The process has too many files open. |
| <br><br> <LI> ENFILE |
| The entire system, or perhaps the file system which contains the |
| directory, cannot support any additional open files at the moment. |
| (This problem cannot happen on the GNU system.) |
| <br><br> <LI> ENOMEM |
| Not enough memory available. |
| |
| <br><br> The <CODE>DIR</CODE> type is typically implemented using a file descriptor, |
| and the <CODE>opendir</CODE> function in terms of the <CODE>open</CODE> function. |
| . Directory streams and the underlying |
| file descriptors are closed on <CODE>exec</CODE> . |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fdopendir" type="function"> |
| <function returntype="DIR *"> |
| <prototype> |
| <parameter content="int fd"/> |
| </prototype> |
| <headers> |
| <header filename = "dirent.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>fdopendir</CODE> function works just like <CODE>opendir</CODE> but |
| instead of taking a file name and opening a file descriptor for the |
| directory the caller is required to provide a file descriptor. This |
| file descriptor is then used in subsequent uses of the returned |
| directory stream object. |
| <br><br> The caller must make sure the file descriptor is associated with a |
| directory and it allows reading. |
| <br><br> If the <CODE>fdopendir</CODE> call returns successfully the file descriptor |
| is now under the control of the system. It can be used in the same |
| way the descriptor implicitly created by <CODE>opendir</CODE> can be used |
| but the program must not close the descriptor. |
| <br><br> In case the function is unsuccessful it returns a null pointer and the |
| file descriptor remains to be usable by the program. The following |
| <CODE>errno</CODE> error conditions are defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EBADF</CODE> |
| <DD> |
| The file descriptor is not valid. |
| <br><br> <LI> ENOTDIR |
| The file descriptor is not associated with a directory. |
| <br><br> <LI> EINVAL |
| The descriptor does not allow reading the directory content. |
| <br><br> <LI> ENOMEM |
| Not enough memory available. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-dirfd" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="DIR *dirstream"/> |
| </prototype> |
| <headers> |
| <header filename = "dirent.h"/> |
| </headers> |
| <synopsis> |
| The function <CODE>dirfd</CODE> returns the file descriptor associated with |
| the directory stream <VAR>dirstream</VAR>. This descriptor can be used until |
| the directory is closed with <CODE>closedir</CODE>. If the directory stream |
| implementation is not using file descriptors the return value is |
| <CODE>-1</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-readdir" type="function"> |
| <function returntype="struct dirent *"> |
| <prototype> |
| <parameter content="DIR *dirstream"/> |
| </prototype> |
| <headers> |
| <header filename = "dirent.h"/> |
| </headers> |
| <synopsis> |
| This function reads the next entry from the directory. It normally |
| returns a pointer to a structure containing information about the file. |
| This structure is statically allocated and can be rewritten by a |
| subsequent call. |
| <br><br> Portability Note: On some systems <CODE>readdir</CODE> may not |
| return entries for <TT>.</TT> and <TT>..</TT>, even though these are always |
| valid file names in any directory. . |
| <br><br> If there are no more entries in the directory or an error is detected, |
| <CODE>readdir</CODE> returns a null pointer. The following <CODE>errno</CODE> error |
| conditions are defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EBADF</CODE> |
| <DD> |
| The <VAR>dirstream</VAR> argument is not valid. |
| |
| <br><br> <CODE>readdir</CODE> is not thread safe. Multiple threads using |
| <CODE>readdir</CODE> on the same <VAR>dirstream</VAR> may overwrite the return |
| value. Use <CODE>readdir_r</CODE> when this is critical. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-readdir_r" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="DIR *dirstream"/> |
| <parameter content="struct dirent *entry"/> |
| <parameter content="struct dirent **result"/> |
| </prototype> |
| <headers> |
| <header filename = "dirent.h"/> |
| </headers> |
| <synopsis> |
| This function is the reentrant version of <CODE>readdir</CODE>. Like |
| <CODE>readdir</CODE> it returns the next entry from the directory. But to |
| prevent conflicts between simultaneously running threads the result is |
| not stored in statically allocated memory. Instead the argument |
| <VAR>entry</VAR> points to a place to store the result. |
| <br><br> Normally <CODE>readdir_r</CODE> returns zero and sets <CODE>*<VAR>result</VAR></CODE> |
| to <VAR>entry</VAR>. If there are no more entries in the directory or an |
| error is detected, <CODE>readdir_r</CODE> sets <CODE>*<VAR>result</VAR></CODE> to a |
| null pointer and returns a nonzero error code, also stored in |
| <CODE>errno</CODE>, as described for <CODE>readdir</CODE>. |
| <br><br> Portability Note: On some systems <CODE>readdir_r</CODE> may not |
| return a NUL terminated string for the file name, even when there is no |
| <CODE>d_reclen</CODE> field in <CODE>struct dirent</CODE> and the file |
| name is the maximum allowed size. Modern systems all have the |
| <CODE>d_reclen</CODE> field, and on old systems multi-threading is not |
| critical. In any case there is no such problem with the <CODE>readdir</CODE> |
| function, so that even on systems without the <CODE>d_reclen</CODE> member one |
| could use multiple threads by using external locking. |
| <br><br> It is also important to look at the definition of the <CODE>struct |
| dirent</CODE> type. Simply passing a pointer to an object of this type for |
| the second parameter of <CODE>readdir_r</CODE> might not be enough. Some |
| systems don't define the <CODE>d_name</CODE> element sufficiently long. In |
| this case the user has to provide additional space. There must be room |
| for at least <CODE>NAME_MAX + 1</CODE> characters in the <CODE>d_name</CODE> array. |
| Code to call <CODE>readdir_r</CODE> could look like this: |
| <br><br> <pre><br> |
| union<br> |
| {<br> |
| struct dirent d;<br> |
| char b[offsetof (struct dirent, d_name) + NAME_MAX + 1];<br> |
| } u;<br> |
| <br><br> if (readdir_r (dir, &u.d, &res) == 0)<br> |
| <small>...</small><br> |
| </pre> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-readdir64" type="function"> |
| <function returntype="struct dirent64 *"> |
| <prototype> |
| <parameter content="DIR *dirstream"/> |
| </prototype> |
| <headers> |
| <header filename = "dirent.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>readdir64</CODE> function is just like the <CODE>readdir</CODE> function |
| except that it returns a pointer to a record of type <CODE>struct |
| dirent64</CODE>. Some of the members of this data type (notably <CODE>d_ino</CODE>) |
| might have a different size to allow large filesystems. |
| <br><br> In all other aspects this function is equivalent to <CODE>readdir</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-readdir64_r" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="DIR *dirstream"/> |
| <parameter content="struct dirent64 *entry"/> |
| <parameter content="struct dirent64 **result"/> |
| </prototype> |
| <headers> |
| <header filename = "dirent.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>readdir64_r</CODE> function is equivalent to the <CODE>readdir_r</CODE> |
| function except that it takes parameters of base type <CODE>struct |
| dirent64</CODE> instead of <CODE>struct dirent</CODE> in the second and third |
| position. The same precautions mentioned in the documentation of |
| <CODE>readdir_r</CODE> also apply here. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-closedir" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="DIR *dirstream"/> |
| </prototype> |
| <headers> |
| <header filename = "dirent.h"/> |
| </headers> |
| <synopsis> |
| This function closes the directory stream <VAR>dirstream</VAR>. It returns |
| <CODE>0</CODE> on success and <CODE>-1</CODE> on failure. |
| <br><br> The following <CODE>errno</CODE> error conditions are defined for this |
| function: |
| <br><br> <DL> |
| |
| <DT><CODE>EBADF</CODE> |
| <DD> |
| The <VAR>dirstream</VAR> argument is not valid. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-rewinddir" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="DIR *dirstream"/> |
| </prototype> |
| <headers> |
| <header filename = "dirent.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>rewinddir</CODE> function is used to reinitialize the directory |
| stream <VAR>dirstream</VAR>, so that if you call <CODE>readdir</CODE> it |
| returns information about the first entry in the directory again. This |
| function also notices if files have been added or removed to the |
| directory since it was opened with <CODE>opendir</CODE>. (Entries for these |
| files might or might not be returned by <CODE>readdir</CODE> if they were |
| added or removed since you last called <CODE>opendir</CODE> or |
| <CODE>rewinddir</CODE>.) |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-seekdir" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="DIR *dirstream"/> |
| <parameter content="long int pos"/> |
| </prototype> |
| <headers> |
| <header filename = "dirent.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>seekdir</CODE> function sets the file position of the directory |
| stream <VAR>dirstream</VAR> to <VAR>pos</VAR>. The value <VAR>pos</VAR> must be the |
| result of a previous call to <CODE>telldir</CODE> on this particular stream; |
| closing and reopening the directory can invalidate values returned by |
| <CODE>telldir</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-scandir" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *dir"/> |
| <parameter content="struct dirent ***namelist"/> |
| <parameter content="int (*selector) (const struct dirent *)"/> |
| <parameter content="int (*cmp) (const void *"/> |
| <parameter content="const void *)"/> |
| </prototype> |
| <headers> |
| <header filename = "dirent.h"/> |
| </headers> |
| <synopsis> |
| <br><br> The <CODE>scandir</CODE> function scans the contents of the directory selected |
| by <VAR>dir</VAR>. The result in *<VAR>namelist</VAR> is an array of pointers to |
| structure of type <CODE>struct dirent</CODE> which describe all selected |
| directory entries and which is allocated using <CODE>malloc</CODE>. Instead |
| of always getting all directory entries returned, the user supplied |
| function <VAR>selector</VAR> can be used to decide which entries are in the |
| result. Only the entries for which <VAR>selector</VAR> returns a non-zero |
| value are selected. |
| <br><br> Finally the entries in *<VAR>namelist</VAR> are sorted using the |
| user-supplied function <VAR>cmp</VAR>. The arguments passed to the <VAR>cmp</VAR> |
| function are of type <CODE>struct dirent **</CODE>, therefore one cannot |
| directly use the <CODE>strcmp</CODE> or <CODE>strcoll</CODE> functions; instead see |
| the functions <CODE>alphasort</CODE> and <CODE>versionsort</CODE> below. |
| <br><br> The return value of the function is the number of entries placed in |
| *<VAR>namelist</VAR>. If it is <CODE>-1</CODE> an error occurred (either the |
| directory could not be opened for reading or the malloc call failed) and |
| the global variable <CODE>errno</CODE> contains more information on the error. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-alphasort" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const void *a"/> |
| <parameter content="const void *b"/> |
| </prototype> |
| <headers> |
| <header filename = "dirent.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>alphasort</CODE> function behaves like the <CODE>strcoll</CODE> function |
| . The difference is that the arguments |
| are not string pointers but instead they are of type |
| <CODE>struct dirent **</CODE>. |
| <br><br> The return value of <CODE>alphasort</CODE> is less than, equal to, or greater |
| than zero depending on the order of the two entries <VAR>a</VAR> and <VAR>b</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-versionsort" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const void *a"/> |
| <parameter content="const void *b"/> |
| </prototype> |
| <headers> |
| <header filename = "dirent.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>versionsort</CODE> function is like <CODE>alphasort</CODE> except that it |
| uses the <CODE>strverscmp</CODE> function internally. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-scandir64" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *dir"/> |
| <parameter content="struct dirent64 ***namelist"/> |
| <parameter content="int (*selector) (const struct dirent64 *)"/> |
| <parameter content="int (*cmp) (const void *"/> |
| <parameter content="const void *)"/> |
| </prototype> |
| <headers> |
| <header filename = "dirent.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>scandir64</CODE> function works like the <CODE>scandir</CODE> function |
| except that the directory entries it returns are described by elements |
| of type <CODE>struct dirent64</CODE>. The function pointed to by |
| <VAR>selector</VAR> is again used to select the desired entries, except that |
| <VAR>selector</VAR> now must point to a function which takes a |
| <CODE>struct dirent64 *</CODE> parameter. |
| <br><br> Similarly the <VAR>cmp</VAR> function should expect its two arguments to be |
| of type <CODE>struct dirent64 **</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-alphasort64" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const void *a"/> |
| <parameter content="const void *b"/> |
| </prototype> |
| <headers> |
| <header filename = "dirent.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>alphasort64</CODE> function behaves like the <CODE>strcoll</CODE> function |
| . The difference is that the arguments |
| are not string pointers but instead they are of type |
| <CODE>struct dirent64 **</CODE>. |
| <br><br> Return value of <CODE>alphasort64</CODE> is less than, equal to, or greater |
| than zero depending on the order of the two entries <VAR>a</VAR> and <VAR>b</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-versionsort64" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const void *a"/> |
| <parameter content="const void *b"/> |
| </prototype> |
| <headers> |
| <header filename = "dirent.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>versionsort64</CODE> function is like <CODE>alphasort64</CODE>, excepted that it |
| uses the <CODE>strverscmp</CODE> function internally. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="dtype-__ftw_func_t" type="dtype"> |
| <structure> |
| <synopsis> |
| <br><br> <pre><br> |
| int (*) (const char *, const struct stat *, int)<br> |
| </pre> |
| <br><br> The type of callback functions given to the <CODE>ftw</CODE> function. The |
| first parameter points to the file name, the second parameter to an |
| object of type <CODE>struct stat</CODE> which is filled in for the file named |
| in the first parameter. |
| <br><br> |
| The last parameter is a flag giving more information about the current |
| file. It can have the following values: |
| <br><br> <DL> |
| |
| </synopsis> |
| <elements> |
| <element content="FTW_F"> |
| <synopsis> |
| The item is either a normal file or a file which does not fit into one |
| of the following categories. This could be special files, sockets etc. |
| </synopsis> |
| </element> |
| <element content="FTW_D"> |
| <synopsis> |
| The item is a directory. |
| </synopsis> |
| </element> |
| <element content="FTW_NS"> |
| <synopsis> |
| The <CODE>stat</CODE> call failed and so the information pointed to by the |
| second paramater is invalid. |
| </synopsis> |
| </element> |
| <element content="FTW_DNR"> |
| <synopsis> |
| The item is a directory which cannot be read. |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="dtype-__ftw64_func_t" type="dtype"> |
| <structure> |
| </structure> |
| </construct> |
| <construct id="dtype-__nftw_func_t" type="dtype"> |
| <structure> |
| <synopsis> |
| <br><br> <pre><br> |
| int (*) (const char *, const struct stat *, int, struct FTW *)<br> |
| </pre> |
| <br><br> |
| |
| The first three arguments are the same as for the <CODE>__ftw_func_t</CODE> |
| type. However for the third argument some additional values are defined |
| to allow finer differentiation: |
| </synopsis> |
| <elements> |
| <element content="FTW_DP"> |
| <synopsis> |
| The current item is a directory and all subdirectories have already been |
| visited and reported. This flag is returned instead of <CODE>FTW_D</CODE> if |
| the <CODE>FTW_DEPTH</CODE> flag is passed to <CODE>nftw</CODE> (see below). |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="dtype-__nftw64_func_t" type="dtype"> |
| <structure> |
| </structure> |
| </construct> |
| <construct id="struct-FTW" type="struct"> |
| <structure> |
| <synopsis> |
| The information contained in this structure helps in interpreting the |
| name parameter and gives some information about the current state of the |
| traversal of the directory hierarchy. |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="int base"> |
| <synopsis> |
| The value is the offset into the string passed in the first parameter to |
| the callback function of the beginning of the file name. The rest of |
| the string is the path of the file. This information is especially |
| important if the <CODE>FTW_CHDIR</CODE> flag was set in calling <CODE>nftw</CODE> |
| since then the current directory is the one the current item is found |
| in. |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="function-ftw" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *filename"/> |
| <parameter content="__ftw_func_t func"/> |
| <parameter content="int descriptors"/> |
| </prototype> |
| <headers> |
| <header filename = "ftw.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>ftw</CODE> function calls the callback function given in the |
| parameter <VAR>func</VAR> for every item which is found in the directory |
| specified by <VAR>filename</VAR> and all directories below. The function |
| follows symbolic links if necessary but does not process an item twice. |
| If <VAR>filename</VAR> is not a directory then it itself is the only object |
| returned to the callback function. |
| <br><br> The file name passed to the callback function is constructed by taking |
| the <VAR>filename</VAR> parameter and appending the names of all passed |
| directories and then the local file name. So the callback function can |
| use this parameter to access the file. <CODE>ftw</CODE> also calls |
| <CODE>stat</CODE> for the file and passes that information on to the callback |
| function. If this <CODE>stat</CODE> call was not successful the failure is |
| indicated by setting the third argument of the callback function to |
| <CODE>FTW_NS</CODE>. Otherwise it is set according to the description given |
| in the account of <CODE>__ftw_func_t</CODE> above. |
| <br><br> The callback function is expected to return 0 to indicate that no |
| error occurred and that processing should continue. If an error |
| occurred in the callback function or it wants <CODE>ftw</CODE> to return |
| immediately, the callback function can return a value other than |
| 0. This is the only correct way to stop the function. The |
| program must not use <CODE>setjmp</CODE> or similar techniques to continue |
| from another place. This would leave resources allocated by the |
| <CODE>ftw</CODE> function unfreed. |
| <br><br> The <VAR>descriptors</VAR> parameter to <CODE>ftw</CODE> specifies how many file |
| descriptors it is allowed to consume. The function runs faster the more |
| descriptors it can use. For each level in the directory hierarchy at |
| most one descriptor is used, but for very deep ones any limit on open |
| file descriptors for the process or the system may be exceeded. |
| Moreover, file descriptor limits in a multi-threaded program apply to |
| all the threads as a group, and therefore it is a good idea to supply a |
| reasonable limit to the number of open descriptors. |
| <br><br> The return value of the <CODE>ftw</CODE> function is 0 if all callback |
| function calls returned 0 and all actions performed by the |
| <CODE>ftw</CODE> succeeded. If a function call failed (other than calling |
| <CODE>stat</CODE> on an item) the function returns -1. If a callback |
| function returns a value other than 0 this value is returned as |
| the return value of <CODE>ftw</CODE>. |
| <br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> on a |
| 32-bit system this function is in fact <CODE>ftw64</CODE>, i.e., the LFS |
| interface transparently replaces the old interface. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-ftw64" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *filename"/> |
| <parameter content="__ftw64_func_t func"/> |
| <parameter content="int descriptors"/> |
| </prototype> |
| <headers> |
| <header filename = "ftw.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to <CODE>ftw</CODE> but it can work on filesystems |
| with large files. File information is reported using a variable of type |
| <CODE>struct stat64</CODE> which is passed by reference to the callback |
| function. |
| <br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> on a |
| 32-bit system this function is available under the name <CODE>ftw</CODE> and |
| transparently replaces the old implementation. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-nftw" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *filename"/> |
| <parameter content="__nftw_func_t func"/> |
| <parameter content="int descriptors"/> |
| <parameter content="int flag"/> |
| </prototype> |
| <headers> |
| <header filename = "ftw.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>nftw</CODE> function works like the <CODE>ftw</CODE> functions. They call |
| the callback function <VAR>func</VAR> for all items found in the directory |
| <VAR>filename</VAR> and below. At most <VAR>descriptors</VAR> file descriptors |
| are consumed during the <CODE>nftw</CODE> call. |
| <br><br> One difference is that the callback function is of a different type. It |
| is of type <CODE>struct FTW *</CODE> and provides the callback function |
| with the extra information described above. |
| <br><br> A second difference is that <CODE>nftw</CODE> takes a fourth argument, which |
| is 0 or a bitwise-OR combination of any of the following values. |
| <br><br> <DL> |
| |
| <DT><CODE>FTW_PHYS</CODE> |
| <DD> |
| While traversing the directory symbolic links are not followed. Instead |
| symbolic links are reported using the <CODE>FTW_SL</CODE> value for the type |
| parameter to the callback function. If the file referenced by a |
| symbolic link does not exist <CODE>FTW_SLN</CODE> is returned instead. |
| <DT><CODE>FTW_MOUNT</CODE> |
| <DD> |
| The callback function is only called for items which are on the same |
| mounted filesystem as the directory given by the <VAR>filename</VAR> |
| parameter to <CODE>nftw</CODE>. |
| <DT><CODE>FTW_CHDIR</CODE> |
| <DD> |
| If this flag is given the current working directory is changed to the |
| directory of the reported object before the callback function is called. |
| When <CODE>ntfw</CODE> finally returns the current directory is restored to |
| its original value. |
| <DT><CODE>FTW_DEPTH</CODE> |
| <DD> |
| If this option is specified then all subdirectories and files within |
| them are processed before processing the top directory itself |
| (depth-first processing). This also means the type flag given to the |
| callback function is <CODE>FTW_DP</CODE> and not <CODE>FTW_D</CODE>. |
| <DT><CODE>FTW_ACTIONRETVAL</CODE> |
| <DD> |
| If this option is specified then return values from callbacks |
| are handled differently. If the callback returns <CODE>FTW_CONTINUE</CODE>, |
| walking continues normally. <CODE>FTW_STOP</CODE> means walking stops |
| and <CODE>FTW_STOP</CODE> is returned to the caller. If <CODE>FTW_SKIP_SUBTREE</CODE> |
| is returned by the callback with <CODE>FTW_D</CODE> argument, the subtree |
| is skipped and walking continues with next sibling of the directory. |
| If <CODE>FTW_SKIP_SIBLINGS</CODE> is returned by the callback, all siblings |
| of the current entry are skipped and walking continues in its parent. |
| No other return values should be returned from the callbacks if |
| this option is set. This option is a GNU extension. |
| </DL> |
| <br><br> The return value is computed in the same way as for <CODE>ftw</CODE>. |
| <CODE>nftw</CODE> returns 0 if no failures occurred and all callback |
| functions returned 0. In case of internal errors, such as memory |
| problems, the return value is -1 and <VAR>errno</VAR> is set |
| accordingly. If the return value of a callback invocation was non-zero |
| then that value is returned. |
| <br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> on a |
| 32-bit system this function is in fact <CODE>nftw64</CODE>, i.e., the LFS |
| interface transparently replaces the old interface. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-nftw64" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *filename"/> |
| <parameter content="__nftw64_func_t func"/> |
| <parameter content="int descriptors"/> |
| <parameter content="int flag"/> |
| </prototype> |
| <headers> |
| <header filename = "ftw.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to <CODE>nftw</CODE> but it can work on filesystems |
| with large files. File information is reported using a variable of type |
| <CODE>struct stat64</CODE> which is passed by reference to the callback |
| function. |
| <br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> on a |
| 32-bit system this function is available under the name <CODE>nftw</CODE> and |
| transparently replaces the old implementation. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-link" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *oldname"/> |
| <parameter content="const char *newname"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>link</CODE> function makes a new link to the existing file named by |
| <VAR>oldname</VAR>, under the new name <VAR>newname</VAR>. |
| <br><br> This function returns a value of <CODE>0</CODE> if it is successful and |
| <CODE>-1</CODE> on failure. In addition to the usual file name errors |
| for both <VAR>oldname</VAR> and <VAR>newname</VAR>, the |
| following <CODE>errno</CODE> error conditions are defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EACCES</CODE> |
| <DD> |
| You are not allowed to write to the directory in which the new link is |
| to be written. |
| |
| <br><br> <LI> EEXIST |
| There is already a file named <VAR>newname</VAR>. If you want to replace |
| this link with a new link, you must remove the old link explicitly first. |
| <br><br> <LI> EMLINK |
| There are already too many links to the file named by <VAR>oldname</VAR>. |
| (The maximum number of links to a file is <CODE>LINK_MAX</CODE>; see |
| Limits for Files.) |
| <br><br> <LI> ENOENT |
| The file named by <VAR>oldname</VAR> doesn't exist. You can't make a link to |
| a file that doesn't exist. |
| <br><br> <LI> ENOSPC |
| The directory or file system that would contain the new link is full |
| and cannot be extended. |
| <br><br> <LI> EPERM |
| In the GNU system and some others, you cannot make links to directories. |
| Many systems allow only privileged users to do so. This error |
| is used to report the problem. |
| <br><br> <LI> EROFS |
| The directory containing the new link can't be modified because it's on |
| a read-only file system. |
| <br><br> <LI> EXDEV |
| The directory specified in <VAR>newname</VAR> is on a different file system |
| than the existing file. |
| <br><br> <LI> EIO |
| A hardware error occurred while trying to read or write the to filesystem. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-symlink" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *oldname"/> |
| <parameter content="const char *newname"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/param.h"/> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>symlink</CODE> function makes a symbolic link to <VAR>oldname</VAR> named |
| <VAR>newname</VAR>. |
| <br><br> The normal return value from <CODE>symlink</CODE> is <CODE>0</CODE>. A return value |
| of <CODE>-1</CODE> indicates an error. In addition to the usual file name |
| syntax errors , the following <CODE>errno</CODE> |
| error conditions are defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EEXIST</CODE> |
| <DD> |
| There is already an existing file named <VAR>newname</VAR>. |
| <br><br> <LI> EROFS |
| The file <VAR>newname</VAR> would exist on a read-only file system. |
| <br><br> <LI> ENOSPC |
| The directory or file system cannot be extended to make the new link. |
| <br><br> <LI> EIO |
| A hardware error occurred while reading or writing data on the disk. |
| <br><br> |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-readlink" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *filename"/> |
| <parameter content="char *buffer"/> |
| <parameter content="size_t size"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>readlink</CODE> function gets the value of the symbolic link |
| <VAR>filename</VAR>. The file name that the link points to is copied into |
| <VAR>buffer</VAR>. This file name string is <EM>not</EM> null-terminated; |
| <CODE>readlink</CODE> normally returns the number of characters copied. The |
| <VAR>size</VAR> argument specifies the maximum number of characters to copy, |
| usually the allocation size of <VAR>buffer</VAR>. |
| <br><br> If the return value equals <VAR>size</VAR>, you cannot tell whether or not |
| there was room to return the entire name. So make a bigger buffer and |
| call <CODE>readlink</CODE> again. Here is an example: |
| <br><br> <pre><br> |
| char *<br> |
| readlink_malloc (const char *filename)<br> |
| {<br> |
| int size = 100;<br> |
| char *buffer = NULL;<br> |
| <br><br> while (1)<br> |
| {<br> |
| buffer = (char *) xrealloc (buffer, size);<br> |
| int nchars = readlink (filename, buffer, size);<br> |
| if (nchars < 0)<br> |
| {<br> |
| free (buffer);<br> |
| return NULL;<br> |
| }<br> |
| if (nchars < size)<br> |
| return buffer;<br> |
| size *= 2;<br> |
| }<br> |
| }<br> |
| </pre> |
| <br><br> A value of <CODE>-1</CODE> is returned in case of error. In addition to the |
| usual file name errors , the following |
| <CODE>errno</CODE> error conditions are defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EINVAL</CODE> |
| <DD> |
| The named file is not a symbolic link. |
| <br><br> <LI> EIO |
| A hardware error occurred while reading or writing data on the disk. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-canonicalize_file_name" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="const char *name"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| <br><br> The <CODE>canonicalize_file_name</CODE> function returns the absolute name of |
| the file named by <VAR>name</VAR> which contains no <CODE>.</CODE>, <CODE>..</CODE> |
| components nor any repeated path separators (<CODE>/</CODE>) or symlinks. The |
| result is passed back as the return value of the function in a block of |
| memory allocated with <CODE>malloc</CODE>. If the result is not used anymore |
| the memory should be freed with a call to <CODE>free</CODE>. |
| <br><br> If any of the path components is missing the function returns a NULL |
| pointer. This is also what is returned if the length of the path |
| reaches or exceeds <CODE>PATH_MAX</CODE> characters. In any case |
| <CODE>errno</CODE> is set accordingly. |
| <br><br> <DL> |
| |
| <DT><CODE>ENAMETOOLONG</CODE> |
| <DD> |
| The resulting path is too long. This error only occurs on systems which |
| have a limit on the file name length. |
| <br><br> <LI> EACCES |
| At least one of the path components is not readable. |
| <br><br> <LI> ENOENT |
| The input file name is empty. |
| <br><br> <LI> ENOENT |
| At least one of the path components does not exist. |
| <br><br> <LI> ELOOP |
| More than <CODE>MAXSYMLINKS</CODE> many symlinks have been followed. |
| |
| <br><br> This function is a GNU extension and is declared in <TT>stdlib.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-realpath" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="const char *restrict name"/> |
| <parameter content="char *restrict resolved"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| <br><br> A call to <CODE>realpath</CODE> where the <VAR>resolved</VAR> parameter is |
| <CODE>NULL</CODE> behaves exactly like <CODE>canonicalize_file_name</CODE>. The |
| function allocates a buffer for the file name and returns a pointer to |
| it. If <VAR>resolved</VAR> is not <CODE>NULL</CODE> it points to a buffer into |
| which the result is copied. It is the callers responsibility to |
| allocate a buffer which is large enough. On systems which define |
| <CODE>PATH_MAX</CODE> this means the buffer must be large enough for a |
| pathname of this size. For systems without limitations on the pathname |
| length the requirement cannot be met and programs should not call |
| <CODE>realpath</CODE> with anything but <CODE>NULL</CODE> for the second parameter. |
| <br><br> One other difference is that the buffer <VAR>resolved</VAR> (if nonzero) will |
| contain the part of the path component which does not exist or is not |
| readable if the function returns <CODE>NULL</CODE> and <CODE>errno</CODE> is set to |
| <CODE>EACCES</CODE> or <CODE>ENOENT</CODE>. |
| <br><br> This function is declared in <TT>stdlib.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-unlink" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *filename"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>unlink</CODE> function deletes the file name <VAR>filename</VAR>. If |
| this is a file's sole name, the file itself is also deleted. (Actually, |
| if any process has the file open when this happens, deletion is |
| postponed until all processes have closed the file.) |
| <br><br> The function <CODE>unlink</CODE> is declared in the header file <TT>unistd.h</TT>. |
| <br><br> This function returns <CODE>0</CODE> on successful completion, and <CODE>-1</CODE> |
| on error. In addition to the usual file name errors |
| , the following <CODE>errno</CODE> error conditions are |
| defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EACCES</CODE> |
| <DD> |
| Write permission is denied for the directory from which the file is to be |
| removed, or the directory has the sticky bit set and you do not own the file. |
| <br><br> <LI> EBUSY |
| This error indicates that the file is being used by the system in such a |
| way that it can't be unlinked. For example, you might see this error if |
| the file name specifies the root directory or a mount point for a file |
| system. |
| <br><br> <LI> ENOENT |
| The file name to be deleted doesn't exist. |
| <br><br> <LI> EPERM |
| On some systems <CODE>unlink</CODE> cannot be used to delete the name of a |
| directory, or at least can only be used this way by a privileged user. |
| To avoid such problems, use <CODE>rmdir</CODE> to delete directories. (In the |
| GNU system <CODE>unlink</CODE> can never delete the name of a directory.) |
| <br><br> <LI> EROFS |
| The directory containing the file name to be deleted is on a read-only |
| file system and can't be modified. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-rmdir" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *filename"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| , deleting |
| a directory |
| The <CODE>rmdir</CODE> function deletes a directory. The directory must be |
| empty before it can be removed; in other words, it can only contain |
| entries for <TT>.</TT> and <TT>..</TT>. |
| <br><br> In most other respects, <CODE>rmdir</CODE> behaves like <CODE>unlink</CODE>. There |
| are two additional <CODE>errno</CODE> error conditions defined for |
| <CODE>rmdir</CODE>: |
| <br><br> <DL> |
| |
| <DT><CODE>ENOTEMPTY</CODE> |
| <DD> |
| <LI>x EEXIST |
| The directory to be deleted is not empty. |
| |
| <br><br> These two error codes are synonymous; some systems use one, and some use |
| the other. The GNU system always uses <CODE>ENOTEMPTY</CODE>. |
| <br><br> The prototype for this function is declared in the header file |
| <TT>unistd.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-remove" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *filename"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| This is the ISO C function to remove a file. It works like |
| <CODE>unlink</CODE> for files and like <CODE>rmdir</CODE> for directories. |
| <CODE>remove</CODE> is declared in <TT>stdio.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-rename" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *oldname"/> |
| <parameter content="const char *newname"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>rename</CODE> function renames the file <VAR>oldname</VAR> to |
| <VAR>newname</VAR>. The file formerly accessible under the name |
| <VAR>oldname</VAR> is afterwards accessible as <VAR>newname</VAR> instead. (If |
| the file had any other names aside from <VAR>oldname</VAR>, it continues to |
| have those names.) |
| <br><br> The directory containing the name <VAR>newname</VAR> must be on the same file |
| system as the directory containing the name <VAR>oldname</VAR>. |
| <br><br> One special case for <CODE>rename</CODE> is when <VAR>oldname</VAR> and |
| <VAR>newname</VAR> are two names for the same file. The consistent way to |
| handle this case is to delete <VAR>oldname</VAR>. However, in this case |
| POSIX requires that <CODE>rename</CODE> do nothing and report success---which |
| is inconsistent. We don't know what your operating system will do. |
| <br><br> If <VAR>oldname</VAR> is not a directory, then any existing file named |
| <VAR>newname</VAR> is removed during the renaming operation. However, if |
| <VAR>newname</VAR> is the name of a directory, <CODE>rename</CODE> fails in this |
| case. |
| <br><br> If <VAR>oldname</VAR> is a directory, then either <VAR>newname</VAR> must not |
| exist or it must name a directory that is empty. In the latter case, |
| the existing directory named <VAR>newname</VAR> is deleted first. The name |
| <VAR>newname</VAR> must not specify a subdirectory of the directory |
| <CODE>oldname</CODE> which is being renamed. |
| <br><br> One useful feature of <CODE>rename</CODE> is that the meaning of <VAR>newname</VAR> |
| changes ``atomically'' from any previously existing file by that name to |
| its new meaning (i.e., the file that was called <VAR>oldname</VAR>). There is |
| no instant at which <VAR>newname</VAR> is non-existent ``in between'' the old |
| meaning and the new meaning. If there is a system crash during the |
| operation, it is possible for both names to still exist; but |
| <VAR>newname</VAR> will always be intact if it exists at all. |
| <br><br> If <CODE>rename</CODE> fails, it returns <CODE>-1</CODE>. In addition to the usual |
| file name errors , the following |
| <CODE>errno</CODE> error conditions are defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EACCES</CODE> |
| <DD> |
| One of the directories containing <VAR>newname</VAR> or <VAR>oldname</VAR> |
| refuses write permission; or <VAR>newname</VAR> and <VAR>oldname</VAR> are |
| directories and write permission is refused for one of them. |
| <br><br> <LI> EBUSY |
| A directory named by <VAR>oldname</VAR> or <VAR>newname</VAR> is being used by |
| the system in a way that prevents the renaming from working. This includes |
| directories that are mount points for filesystems, and directories |
| that are the current working directories of processes. |
| <br><br> <LI> ENOTEMPTY |
| <LI>x EEXIST |
| The directory <VAR>newname</VAR> isn't empty. The GNU system always returns |
| <CODE>ENOTEMPTY</CODE> for this, but some other systems return <CODE>EEXIST</CODE>. |
| <br><br> <LI> EINVAL |
| <VAR>oldname</VAR> is a directory that contains <VAR>newname</VAR>. |
| <br><br> <LI> EISDIR |
| <VAR>newname</VAR> is a directory but the <VAR>oldname</VAR> isn't. |
| <br><br> <LI> EMLINK |
| The parent directory of <VAR>newname</VAR> would have too many links |
| (entries). |
| <br><br> <LI> ENOENT |
| The file <VAR>oldname</VAR> doesn't exist. |
| <br><br> <LI> ENOSPC |
| The directory that would contain <VAR>newname</VAR> has no room for another |
| entry, and there is no space left in the file system to expand it. |
| <br><br> <LI> EROFS |
| The operation would involve writing to a directory on a read-only file |
| system. |
| <br><br> <LI> EXDEV |
| The two file names <VAR>newname</VAR> and <VAR>oldname</VAR> are on different |
| file systems. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-mkdir" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *filename"/> |
| <parameter content="mode_t mode"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/stat.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>mkdir</CODE> function creates a new, empty directory with name |
| <VAR>filename</VAR>. |
| <br><br> The argument <VAR>mode</VAR> specifies the file permissions for the new |
| directory file. , for more information about |
| this. |
| <br><br> A return value of <CODE>0</CODE> indicates successful completion, and |
| <CODE>-1</CODE> indicates failure. In addition to the usual file name syntax |
| errors , the following <CODE>errno</CODE> error |
| conditions are defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EACCES</CODE> |
| <DD> |
| Write permission is denied for the parent directory in which the new |
| directory is to be added. |
| <br><br> <LI> EEXIST |
| A file named <VAR>filename</VAR> already exists. |
| <br><br> <LI> EMLINK |
| The parent directory has too many links (entries). |
| <br><br> Well-designed file systems never report this error, because they permit |
| more links than your disk could possibly hold. However, you must still |
| take account of the possibility of this error, as it could result from |
| network access to a file system on another machine. |
| <br><br> <LI> ENOSPC |
| The file system doesn't have enough room to create the new directory. |
| <br><br> <LI> EROFS |
| The parent directory of the directory being created is on a read-only |
| file system and cannot be modified. |
| |
| <br><br> To use this function, your program should include the header file |
| <TT>sys/stat.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="struct-stat" type="struct"> |
| <structure> |
| <synopsis> |
| The <CODE>stat</CODE> structure type is used to return information about the |
| attributes of a file. It contains at least the following members: |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="mode_t st_mode"> |
| <synopsis> |
| Specifies the mode of the file. This includes file type information |
| and the file permission bits |
| . |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="ino_t st_ino"> |
| <synopsis> |
| The file serial number, which distinguishes this file from all other |
| files on the same device. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="dev_t st_dev"> |
| <synopsis> |
| Identifies the device containing the file. The <CODE>st_ino</CODE> and |
| <CODE>st_dev</CODE>, taken together, uniquely identify the file. The |
| <CODE>st_dev</CODE> value is not necessarily consistent across reboots or |
| system crashes, however. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="nlink_t st_nlink"> |
| <synopsis> |
| The number of hard links to the file. This count keeps track of how |
| many directories have entries for this file. If the count is ever |
| decremented to zero, then the file itself is discarded as soon as no |
| process still holds it open. Symbolic links are not counted in the |
| total. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="uid_t st_uid"> |
| <synopsis> |
| The user ID of the file's owner. . |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="gid_t st_gid"> |
| <synopsis> |
| The group ID of the file. . |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="off_t st_size"> |
| <synopsis> |
| This specifies the size of a regular file in bytes. For files that are |
| really devices this field isn't usually meaningful. For symbolic links |
| this specifies the length of the file name the link refers to. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="time_t st_atime"> |
| <synopsis> |
| This is the last access time for the file. . |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="unsigned long int st_atime_usec"> |
| <synopsis> |
| This is the fractional part of the last access time for the file. |
| . |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="time_t st_mtime"> |
| <synopsis> |
| This is the time of the last modification to the contents of the file. |
| . |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="unsigned long int st_mtime_usec"> |
| <synopsis> |
| This is the fractional part of the time of the last modification to the |
| contents of the file. . |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="time_t st_ctime"> |
| <synopsis> |
| This is the time of the last modification to the attributes of the file. |
| . |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="unsigned long int st_ctime_usec"> |
| <synopsis> |
| This is the fractional part of the time of the last modification to the |
| attributes of the file. . |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="blkcnt_t st_blocks"> |
| <synopsis> |
| This is the amount of disk space that the file occupies, measured in |
| units of 512-byte blocks. |
| <br><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><br> You can tell (approximately) whether a file is sparse by comparing this |
| value with <CODE>st_size</CODE>, like this: |
| <br><br> <pre><br> |
| (st.st_blocks * 512 < st.st_size)<br> |
| </pre> |
| <br><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><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="struct-stat64" type="struct"> |
| <structure> |
| <synopsis> |
| The members of this type are the same and have the same names as those |
| in <CODE>struct stat</CODE>. The only difference is that the members |
| <CODE>st_ino</CODE>, <CODE>st_size</CODE>, and <CODE>st_blocks</CODE> have a different |
| type to support larger values. |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="mode_t st_mode"> |
| <synopsis> |
| Specifies the mode of the file. This includes file type information |
| and the file permission bits |
| . |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="ino64_t st_ino"> |
| <synopsis> |
| The file serial number, which distinguishes this file from all other |
| files on the same device. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="dev_t st_dev"> |
| <synopsis> |
| Identifies the device containing the file. The <CODE>st_ino</CODE> and |
| <CODE>st_dev</CODE>, taken together, uniquely identify the file. The |
| <CODE>st_dev</CODE> value is not necessarily consistent across reboots or |
| system crashes, however. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="nlink_t st_nlink"> |
| <synopsis> |
| The number of hard links to the file. This count keeps track of how |
| many directories have entries for this file. If the count is ever |
| decremented to zero, then the file itself is discarded as soon as no |
| process still holds it open. Symbolic links are not counted in the |
| total. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="uid_t st_uid"> |
| <synopsis> |
| The user ID of the file's owner. . |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="gid_t st_gid"> |
| <synopsis> |
| The group ID of the file. . |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="off64_t st_size"> |
| <synopsis> |
| This specifies the size of a regular file in bytes. For files that are |
| really devices this field isn't usually meaningful. For symbolic links |
| this specifies the length of the file name the link refers to. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="time_t st_atime"> |
| <synopsis> |
| This is the last access time for the file. . |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="unsigned long int st_atime_usec"> |
| <synopsis> |
| This is the fractional part of the last access time for the file. |
| . |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="time_t st_mtime"> |
| <synopsis> |
| This is the time of the last modification to the contents of the file. |
| . |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="unsigned long int st_mtime_usec"> |
| <synopsis> |
| This is the fractional part of the time of the last modification to the |
| contents of the file. . |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="time_t st_ctime"> |
| <synopsis> |
| This is the time of the last modification to the attributes of the file. |
| . |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="unsigned long int st_ctime_usec"> |
| <synopsis> |
| This is the fractional part of the time of the last modification to the |
| attributes of the file. . |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="blkcnt64_t st_blocks"> |
| <synopsis> |
| This is the amount of disk space that the file occupies, measured in |
| units of 512-byte blocks. |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="dtype-mode_t" type="dtype"> |
| <structure> |
| </structure> |
| </construct> |
| <construct id="dtype-ino_t" type="dtype"> |
| <structure> |
| </structure> |
| </construct> |
| <construct id="dtype-ino64_t" type="dtype"> |
| <structure> |
| </structure> |
| </construct> |
| <construct id="dtype-dev_t" type="dtype"> |
| <structure> |
| </structure> |
| </construct> |
| <construct id="dtype-nlink_t" type="dtype"> |
| <structure> |
| </structure> |
| </construct> |
| <construct id="dtype-blkcnt_t" type="dtype"> |
| <structure> |
| </structure> |
| </construct> |
| <construct id="dtype-blkcnt64_t" type="dtype"> |
| <structure> |
| </structure> |
| </construct> |
| <construct id="function-stat" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *filename"/> |
| <parameter content="struct stat *buf"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/stat.h"/> |
| <header filename = "sys/types.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>stat</CODE> function returns information about the attributes of the |
| file named by <VAR>filename</VAR> in the structure pointed to by <VAR>buf</VAR>. |
| <br><br> If <VAR>filename</VAR> is the name of a symbolic link, the attributes you get |
| describe the file that the link points to. If the link points to a |
| nonexistent file name, then <CODE>stat</CODE> fails reporting a nonexistent |
| file. |
| <br><br> The return value is <CODE>0</CODE> if the operation is successful, or |
| <CODE>-1</CODE> on failure. In addition to the usual file name errors |
| (, the following <CODE>errno</CODE> error conditions |
| are defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>ENOENT</CODE> |
| <DD> |
| The file named by <VAR>filename</VAR> doesn't exist. |
| |
| <br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> this |
| function is in fact <CODE>stat64</CODE> since the LFS interface transparently |
| replaces the normal implementation. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-stat64" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *filename"/> |
| <parameter content="struct stat64 *buf"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/stat.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to <CODE>stat</CODE> but it is also able to work on |
| files larger then 2^31 bytes on 32-bit systems. To be able to do |
| this the result is stored in a variable of type <CODE>struct stat64</CODE> to |
| which <VAR>buf</VAR> must point. |
| <br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> this |
| function is available under the name <CODE>stat</CODE> and so transparently |
| replaces the interface for small files on 32-bit machines. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fstat" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int filedes"/> |
| <parameter content="struct stat *buf"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/stat.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>fstat</CODE> function is like <CODE>stat</CODE>, except that it takes an |
| open file descriptor as an argument instead of a file name. |
| . |
| <br><br> Like <CODE>stat</CODE>, <CODE>fstat</CODE> returns <CODE>0</CODE> on success and <CODE>-1</CODE> |
| on failure. The following <CODE>errno</CODE> error conditions are defined for |
| <CODE>fstat</CODE>: |
| <br><br> <DL> |
| |
| <DT><CODE>EBADF</CODE> |
| <DD> |
| The <VAR>filedes</VAR> argument is not a valid file descriptor. |
| |
| <br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> this |
| function is in fact <CODE>fstat64</CODE> since the LFS interface transparently |
| replaces the normal implementation. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fstat64" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int filedes"/> |
| <parameter content="struct stat64 *buf"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/stat.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to <CODE>fstat</CODE> but is able to work on large |
| files on 32-bit platforms. For large files the file descriptor |
| <VAR>filedes</VAR> should be obtained by <CODE>open64</CODE> or <CODE>creat64</CODE>. |
| The <VAR>buf</VAR> pointer points to a variable of type <CODE>struct stat64</CODE> |
| which is able to represent the larger values. |
| <br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> this |
| function is available under the name <CODE>fstat</CODE> and so transparently |
| replaces the interface for small files on 32-bit machines. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-lstat" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *filename"/> |
| <parameter content="struct stat *buf"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/stat.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>lstat</CODE> function is like <CODE>stat</CODE>, except that it does not |
| follow symbolic links. If <VAR>filename</VAR> is the name of a symbolic |
| link, <CODE>lstat</CODE> returns information about the link itself; otherwise |
| <CODE>lstat</CODE> works like <CODE>stat</CODE>. . |
| <br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> this |
| function is in fact <CODE>lstat64</CODE> since the LFS interface transparently |
| replaces the normal implementation. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-lstat64" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *filename"/> |
| <parameter content="struct stat64 *buf"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/stat.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to <CODE>lstat</CODE> but it is also able to work on |
| files larger then 2^31 bytes on 32-bit systems. To be able to do |
| this the result is stored in a variable of type <CODE>struct stat64</CODE> to |
| which <VAR>buf</VAR> must point. |
| <br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> this |
| function is available under the name <CODE>lstat</CODE> and so transparently |
| replaces the interface for small files on 32-bit machines. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-chown" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *filename"/> |
| <parameter content="uid_t owner"/> |
| <parameter content="gid_t group"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>chown</CODE> function changes the owner of the file <VAR>filename</VAR> to |
| <VAR>owner</VAR>, and its group owner to <VAR>group</VAR>. |
| <br><br> Changing the owner of the file on certain systems clears the set-user-ID |
| and set-group-ID permission bits. (This is because those bits may not |
| be appropriate for the new owner.) Other file permission bits are not |
| changed. |
| <br><br> The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on failure. |
| In addition to the usual file name errors , |
| the following <CODE>errno</CODE> error conditions are defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EPERM</CODE> |
| <DD> |
| This process lacks permission to make the requested change. |
| <br><br> Only privileged users or the file's owner can change the file's group. |
| On most file systems, only privileged users can change the file owner; |
| some file systems allow you to change the owner if you are currently the |
| owner. When you access a remote file system, the behavior you encounter |
| is determined by the system that actually holds the file, not by the |
| system your program is running on. |
| <br><br> , for information about the |
| <CODE>_POSIX_CHOWN_RESTRICTED</CODE> macro. |
| <br><br> <LI> EROFS |
| The file is on a read-only file system. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fchown" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int filedes"/> |
| <parameter content="int owner"/> |
| <parameter content="int group"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| This is like <CODE>chown</CODE>, except that it changes the owner of the open |
| file with descriptor <VAR>filedes</VAR>. |
| <br><br> The return value from <CODE>fchown</CODE> is <CODE>0</CODE> on success and <CODE>-1</CODE> |
| on failure. The following <CODE>errno</CODE> error codes are defined for this |
| function: |
| <br><br> <DL> |
| |
| <DT><CODE>EBADF</CODE> |
| <DD> |
| The <VAR>filedes</VAR> argument is not a valid file descriptor. |
| <br><br> <LI> EINVAL |
| The <VAR>filedes</VAR> argument corresponds to a pipe or socket, not an ordinary |
| file. |
| <br><br> <LI> EPERM |
| This process lacks permission to make the requested change. For details |
| see <CODE>chmod</CODE> above. |
| <br><br> <LI> EROFS |
| The file resides on a read-only file system. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-umask" type="function"> |
| <function returntype="mode_t"> |
| <prototype> |
| <parameter content="mode_t mask"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/stat.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>umask</CODE> function sets the file creation mask of the current |
| process to <VAR>mask</VAR>, and returns the previous value of the file |
| creation mask. |
| <br><br> Here is an example showing how to read the mask with <CODE>umask</CODE> |
| without changing it permanently: |
| <br><br> <pre><br> |
| mode_t<br> |
| read_umask (void)<br> |
| {<br> |
| mode_t mask = umask (0);<br> |
| umask (mask);<br> |
| return mask;<br> |
| }<br> |
| </pre> |
| <br><br> |
| However, it is better to use <CODE>getumask</CODE> if you just want to read |
| the mask value, because it is reentrant (at least if you use the GNU |
| operating system). |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getumask" type="function"> |
| <function returntype="mode_t"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/stat.h"/> |
| </headers> |
| <synopsis> |
| Return the current value of the file creation mask for the current |
| process. This function is a GNU extension. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-chmod" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *filename"/> |
| <parameter content="mode_t mode"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/stat.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>chmod</CODE> function sets the access permission bits for the file |
| named by <VAR>filename</VAR> to <VAR>mode</VAR>. |
| <br><br> If <VAR>filename</VAR> is a symbolic link, <CODE>chmod</CODE> changes the |
| permissions of the file pointed to by the link, not those of the link |
| itself. |
| <br><br> This function returns <CODE>0</CODE> if successful and <CODE>-1</CODE> if not. In |
| addition to the usual file name errors , the following <CODE>errno</CODE> error conditions are defined for |
| this function: |
| <br><br> <DL> |
| |
| <DT><CODE>ENOENT</CODE> |
| <DD> |
| The named file doesn't exist. |
| <br><br> <LI> EPERM |
| This process does not have permission to change the access permissions |
| of this file. Only the file's owner (as judged by the effective user ID |
| of the process) or a privileged user can change them. |
| <br><br> <LI> EROFS |
| The file resides on a read-only file system. |
| <br><br> <LI> EFTYPE |
| <VAR>mode</VAR> has the <CODE>S_ISVTX</CODE> bit (the ``sticky bit'') set, |
| and the named file is not a directory. Some systems do not allow setting the |
| sticky bit on non-directory files, and some do (and only some of those |
| assign a useful meaning to the bit for non-directory files). |
| <br><br> You only get <CODE>EFTYPE</CODE> on systems where the sticky bit has no useful |
| meaning for non-directory files, so it is always safe to just clear the |
| bit in <VAR>mode</VAR> and call <CODE>chmod</CODE> again. , |
| for full details on the sticky bit. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fchmod" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int filedes"/> |
| <parameter content="int mode"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/stat.h"/> |
| </headers> |
| <synopsis> |
| This is like <CODE>chmod</CODE>, except that it changes the permissions of the |
| currently open file given by <VAR>filedes</VAR>. |
| <br><br> The return value from <CODE>fchmod</CODE> is <CODE>0</CODE> on success and <CODE>-1</CODE> |
| on failure. The following <CODE>errno</CODE> error codes are defined for this |
| function: |
| <br><br> <DL> |
| |
| <DT><CODE>EBADF</CODE> |
| <DD> |
| The <VAR>filedes</VAR> argument is not a valid file descriptor. |
| <br><br> <LI> EINVAL |
| The <VAR>filedes</VAR> argument corresponds to a pipe or socket, or something |
| else that doesn't really have access permissions. |
| <br><br> <LI> EPERM |
| This process does not have permission to change the access permissions |
| of this file. Only the file's owner (as judged by the effective user ID |
| of the process) or a privileged user can change them. |
| <br><br> <LI> EROFS |
| The file resides on a read-only file system. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-access" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *filename"/> |
| <parameter content="int how"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>access</CODE> function checks to see whether the file named by |
| <VAR>filename</VAR> can be accessed in the way specified by the <VAR>how</VAR> |
| argument. The <VAR>how</VAR> argument either can be the bitwise OR of the |
| flags <CODE>R_OK</CODE>, <CODE>W_OK</CODE>, <CODE>X_OK</CODE>, or the existence test |
| <CODE>F_OK</CODE>. |
| <br><br> This function uses the <EM>real</EM> user and group IDs of the calling |
| process, rather than the <EM>effective</EM> IDs, to check for access |
| permission. As a result, if you use the function from a <CODE>setuid</CODE> |
| or <CODE>setgid</CODE> program , it gives |
| information relative to the user who actually ran the program. |
| <br><br> The return value is <CODE>0</CODE> if the access is permitted, and <CODE>-1</CODE> |
| otherwise. (In other words, treated as a predicate function, |
| <CODE>access</CODE> returns true if the requested access is <EM>denied</EM>.) |
| <br><br> In addition to the usual file name errors , the following <CODE>errno</CODE> error conditions are defined for |
| this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EACCES</CODE> |
| <DD> |
| The access specified by <VAR>how</VAR> is denied. |
| <br><br> <LI> ENOENT |
| The file doesn't exist. |
| <br><br> <LI> EROFS |
| Write permission was requested for a file on a read-only file system. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="struct-utimbuf" type="struct"> |
| <structure> |
| <synopsis> |
| The <CODE>utimbuf</CODE> structure is used with the <CODE>utime</CODE> function to |
| specify new access and modification times for a file. It contains the |
| following members: |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="time_t actime"> |
| <synopsis> |
| This is the access time for the file. |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="function-utime" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *filename"/> |
| <parameter content="const struct utimbuf *times"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| <header filename = "time.h"/> |
| </headers> |
| <synopsis> |
| This function is used to modify the file times associated with the file |
| named <VAR>filename</VAR>. |
| <br><br> If <VAR>times</VAR> is a null pointer, then the access and modification times |
| of the file are set to the current time. Otherwise, they are set to the |
| values from the <CODE>actime</CODE> and <CODE>modtime</CODE> members (respectively) |
| of the <CODE>utimbuf</CODE> structure pointed to by <VAR>times</VAR>. |
| <br><br> The attribute modification time for the file is set to the current time |
| in either case (since changing the time stamps is itself a modification |
| of the file attributes). |
| <br><br> The <CODE>utime</CODE> function returns <CODE>0</CODE> if successful and <CODE>-1</CODE> |
| on failure. In addition to the usual file name errors |
| , the following <CODE>errno</CODE> error conditions |
| are defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EACCES</CODE> |
| <DD> |
| There is a permission problem in the case where a null pointer was |
| passed as the <VAR>times</VAR> argument. In order to update the time stamp on |
| the file, you must either be the owner of the file, have write |
| permission for the file, or be a privileged user. |
| <br><br> <LI> ENOENT |
| The file doesn't exist. |
| <br><br> <LI> EPERM |
| If the <VAR>times</VAR> argument is not a null pointer, you must either be |
| the owner of the file or be a privileged user. |
| <br><br> <LI> EROFS |
| The file lives on a read-only file system. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-utimes" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *filename"/> |
| <parameter content="struct timeval tvp[2]"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/time.h"/> |
| </headers> |
| <synopsis> |
| This function sets the file access and modification times of the file |
| <VAR>filename</VAR>. The new file access time is specified by |
| <CODE><VAR>tvp</VAR>[0]</CODE>, and the new modification time by |
| <CODE><VAR>tvp</VAR>[1]</CODE>. Similar to <CODE>utime</CODE>, if <VAR>tvp</VAR> is a null |
| pointer then the access and modification times of the file are set to |
| the current time. This function comes from BSD. |
| <br><br> The return values and error conditions are the same as for the <CODE>utime</CODE> |
| function. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-lutimes" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *filename"/> |
| <parameter content="struct timeval tvp[2]"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/time.h"/> |
| </headers> |
| <synopsis> |
| This function is like <CODE>utimes</CODE>, except that it does not follow |
| symbolic links. If <VAR>filename</VAR> is the name of a symbolic link, |
| <CODE>lutimes</CODE> sets the file access and modification times of the |
| symbolic link special file itself (as seen by <CODE>lstat</CODE>; |
| ) while <CODE>utimes</CODE> sets the file access and |
| modification times of the file the symbolic link refers to. This |
| function comes from FreeBSD, and is not available on all platforms (if |
| not available, it will fail with <CODE>ENOSYS</CODE>). |
| <br><br> The return values and error conditions are the same as for the <CODE>utime</CODE> |
| function. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-futimes" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int fd"/> |
| <parameter content="struct timeval tvp[2]"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/time.h"/> |
| </headers> |
| <synopsis> |
| This function is like <CODE>utimes</CODE>, except that it takes an open file |
| descriptor as an argument instead of a file name. . This function comes from FreeBSD, and is not available on all |
| platforms (if not available, it will fail with <CODE>ENOSYS</CODE>). |
| <br><br> Like <CODE>utimes</CODE>, <CODE>futimes</CODE> returns <CODE>0</CODE> on success and <CODE>-1</CODE> |
| on failure. The following <CODE>errno</CODE> error conditions are defined for |
| <CODE>futimes</CODE>: |
| <br><br> <DL> |
| |
| <DT><CODE>EACCES</CODE> |
| <DD> |
| There is a permission problem in the case where a null pointer was |
| passed as the <VAR>times</VAR> argument. In order to update the time stamp on |
| the file, you must either be the owner of the file, have write |
| permission for the file, or be a privileged user. |
| <br><br> <LI> EBADF |
| The <VAR>filedes</VAR> argument is not a valid file descriptor. |
| <br><br> <LI> EPERM |
| If the <VAR>times</VAR> argument is not a null pointer, you must either be |
| the owner of the file or be a privileged user. |
| <br><br> <LI> EROFS |
| The file lives on a read-only file system. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-truncate" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *filename"/> |
| <parameter content="off_t length"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| <br><br> The <CODE>truncate</CODE> function changes the size of <VAR>filename</VAR> to |
| <VAR>length</VAR>. If <VAR>length</VAR> is shorter than the previous length, data |
| at the end will be lost. The file must be writable by the user to |
| perform this operation. |
| <br><br> If <VAR>length</VAR> is longer, holes will be added to the end. However, some |
| systems do not support this feature and will leave the file unchanged. |
| <br><br> When the source file is compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> the |
| <CODE>truncate</CODE> function is in fact <CODE>truncate64</CODE> and the type |
| <CODE>off_t</CODE> has 64 bits which makes it possible to handle files up to |
| 2^63 bytes in length. |
| <br><br> The return value is 0 for success, or -1 for an error. In |
| addition to the usual file name errors, the following errors may occur: |
| <br><br> <DL> |
| |
| <br><br> <DT><CODE>EACCES</CODE> |
| <DD> |
| The file is a directory or not writable. |
| <br><br> <LI> EINVAL |
| <VAR>length</VAR> is negative. |
| <br><br> <LI> EFBIG |
| The operation would extend the file beyond the limits of the operating system. |
| <br><br> <LI> EIO |
| A hardware I/O error occurred. |
| <br><br> <LI> EPERM |
| The file is "append-only" or "immutable". |
| <br><br> <LI> EINTR |
| The operation was interrupted by a signal. |
| <br><br> |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-truncate64" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *name"/> |
| <parameter content="off64_t length"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to the <CODE>truncate</CODE> function. The |
| difference is that the <VAR>length</VAR> argument is 64 bits wide even on 32 |
| bits machines, which allows the handling of files with sizes up to |
| 2^63 bytes. |
| <br><br> When the source file is compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> on a |
| 32 bits machine this function is actually available under the name |
| <CODE>truncate</CODE> and so transparently replaces the 32 bits interface. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-ftruncate" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int fd"/> |
| <parameter content="off_t length"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| <br><br> This is like <CODE>truncate</CODE>, but it works on a file descriptor <VAR>fd</VAR> |
| for an opened file instead of a file name to identify the object. The |
| file must be opened for writing to successfully carry out the operation. |
| <br><br> The POSIX standard leaves it implementation defined what happens if the |
| specified new <VAR>length</VAR> of the file is bigger than the original size. |
| The <CODE>ftruncate</CODE> function might simply leave the file alone and do |
| nothing or it can increase the size to the desired size. In this later |
| case the extended area should be zero-filled. So using <CODE>ftruncate</CODE> |
| is no reliable way to increase the file size but if it is possible it is |
| probably the fastest way. The function also operates on POSIX shared |
| memory segments if these are implemented by the system. |
| <br><br> <CODE>ftruncate</CODE> is especially useful in combination with <CODE>mmap</CODE>. |
| Since the mapped region must have a fixed size one cannot enlarge the |
| file by writing something beyond the last mapped page. Instead one has |
| to enlarge the file itself and then remap the file with the new size. |
| The example below shows how this works. |
| <br><br> When the source file is compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> the |
| <CODE>ftruncate</CODE> function is in fact <CODE>ftruncate64</CODE> and the type |
| <CODE>off_t</CODE> has 64 bits which makes it possible to handle files up to |
| 2^63 bytes in length. |
| <br><br> The return value is 0 for success, or -1 for an error. The |
| following errors may occur: |
| <br><br> <DL> |
| |
| <br><br> <DT><CODE>EBADF</CODE> |
| <DD> |
| <VAR>fd</VAR> does not correspond to an open file. |
| <br><br> <LI> EACCES |
| <VAR>fd</VAR> is a directory or not open for writing. |
| <br><br> <LI> EINVAL |
| <VAR>length</VAR> is negative. |
| <br><br> <LI> EFBIG |
| The operation would extend the file beyond the limits of the operating system. |
| <br><br> <LI> EIO |
| A hardware I/O error occurred. |
| <br><br> <LI> EPERM |
| The file is "append-only" or "immutable". |
| <br><br> <LI> EINTR |
| The operation was interrupted by a signal. |
| <br><br> <br><br> |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-ftruncate64" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int id"/> |
| <parameter content="off64_t length"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to the <CODE>ftruncate</CODE> function. The |
| difference is that the <VAR>length</VAR> argument is 64 bits wide even on 32 |
| bits machines which allows the handling of files with sizes up to |
| 2^63 bytes. |
| <br><br> When the source file is compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> on a |
| 32 bits machine this function is actually available under the name |
| <CODE>ftruncate</CODE> and so transparently replaces the 32 bits interface. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-mknod" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *filename"/> |
| <parameter content="int mode"/> |
| <parameter content="int dev"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/stat.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>mknod</CODE> function makes a special file with name <VAR>filename</VAR>. |
| The <VAR>mode</VAR> specifies the mode of the file, and may include the various |
| special file bits, such as <CODE>S_IFCHR</CODE> (for a character special file) |
| or <CODE>S_IFBLK</CODE> (for a block special file). . |
| <br><br> The <VAR>dev</VAR> argument specifies which device the special file refers to. |
| Its exact interpretation depends on the kind of special file being created. |
| <br><br> The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on error. In addition |
| to the usual file name errors , the |
| following <CODE>errno</CODE> error conditions are defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EPERM</CODE> |
| <DD> |
| The calling process is not privileged. Only the superuser can create |
| special files. |
| <br><br> <LI> ENOSPC |
| The directory or file system that would contain the new file is full |
| and cannot be extended. |
| <br><br> <LI> EROFS |
| The directory containing the new file can't be modified because it's on |
| a read-only file system. |
| <br><br> <LI> EEXIST |
| There is already a file named <VAR>filename</VAR>. If you want to replace |
| this file, you must remove the old file explicitly first. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-tmpfile" type="function"> |
| <function returntype="FILE *"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| This function creates a temporary binary file for update mode, as if by |
| calling <CODE>fopen</CODE> with mode <CODE>"wb+"</CODE>. The file is deleted |
| automatically when it is closed or when the program terminates. (On |
| some other ISO C systems the file may fail to be deleted if the program |
| terminates abnormally). |
| <br><br> This function is reentrant. |
| <br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> on a |
| 32-bit system this function is in fact <CODE>tmpfile64</CODE>, i.e., the LFS |
| interface transparently replaces the old interface. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-tmpfile64" type="function"> |
| <function returntype="FILE *"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to <CODE>tmpfile</CODE>, but the stream it returns a |
| pointer to was opened using <CODE>tmpfile64</CODE>. Therefore this stream can |
| be used for files larger then 2^31 bytes on 32-bit machines. |
| <br><br> Please note that the return type is still <CODE>FILE *</CODE>. There is no |
| special <CODE>FILE</CODE> type for the LFS interface. |
| <br><br> If the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> on a 32 |
| bits machine this function is available under the name <CODE>tmpfile</CODE> |
| and so transparently replaces the old interface. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-tmpnam" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="char *result"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| This function constructs and returns a valid file name that does not |
| refer to any existing file. If the <VAR>result</VAR> argument is a null |
| pointer, the return value is a pointer to an internal static string, |
| which might be modified by subsequent calls and therefore makes this |
| function non-reentrant. Otherwise, the <VAR>result</VAR> argument should be |
| a pointer to an array of at least <CODE>L_tmpnam</CODE> characters, and the |
| result is written into that array. |
| <br><br> It is possible for <CODE>tmpnam</CODE> to fail if you call it too many times |
| without removing previously-created files. This is because the limited |
| length of the temporary file names gives room for only a finite number |
| of different names. If <CODE>tmpnam</CODE> fails it returns a null pointer. |
| <br><br> Warning: Between the time the pathname is constructed and the |
| file is created another process might have created a file with the same |
| name using <CODE>tmpnam</CODE>, leading to a possible security hole. The |
| implementation generates names which can hardly be predicted, but when |
| opening the file you should use the <CODE>O_EXCL</CODE> flag. Using |
| <CODE>tmpfile</CODE> or <CODE>mkstemp</CODE> is a safe way to avoid this problem. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-tmpnam_r" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="char *result"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| This function is nearly identical to the <CODE>tmpnam</CODE> function, except |
| that if <VAR>result</VAR> is a null pointer it returns a null pointer. |
| <br><br> This guarantees reentrancy because the non-reentrant situation of |
| <CODE>tmpnam</CODE> cannot happen here. |
| <br><br> <h3>Warning</h3>: This function has the same security problems as |
| <CODE>tmpnam</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-tempnam" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="const char *dir"/> |
| <parameter content="const char *prefix"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| This function generates a unique temporary file name. If <VAR>prefix</VAR> |
| is not a null pointer, up to five characters of this string are used as |
| a prefix for the file name. The return value is a string newly |
| allocated with <CODE>malloc</CODE>, so you should release its storage with |
| <CODE>free</CODE> when it is no longer needed. |
| <br><br> Because the string is dynamically allocated this function is reentrant. |
| <br><br> The directory prefix for the temporary file name is determined by |
| testing each of the following in sequence. The directory must exist and |
| be writable. |
| <br><br> <OL> |
| <LI> |
| The environment variable <CODE>TMPDIR</CODE>, if it is defined. For security |
| reasons this only happens if the program is not SUID or SGID enabled. |
| <br><br> <LI> |
| The <VAR>dir</VAR> argument, if it is not a null pointer. |
| <br><br> <LI> |
| The value of the <CODE>P_tmpdir</CODE> macro. |
| <br><br> <LI> |
| The directory <TT>/tmp</TT>. |
| </OL> |
| <br><br> This function is defined for SVID compatibility. |
| <br><br> Warning: Between the time the pathname is constructed and the |
| file is created another process might have created a file with the same |
| name using <CODE>tempnam</CODE>, leading to a possible security hole. The |
| implementation generates names which can hardly be predicted, but when |
| opening the file you should use the <CODE>O_EXCL</CODE> flag. Using |
| <CODE>tmpfile</CODE> or <CODE>mkstemp</CODE> is a safe way to avoid this problem. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-mktemp" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="char *template"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>mktemp</CODE> function generates a unique file name by modifying |
| <VAR>template</VAR> as described above. If successful, it returns |
| <VAR>template</VAR> as modified. If <CODE>mktemp</CODE> cannot find a unique file |
| name, it makes <VAR>template</VAR> an empty string and returns that. If |
| <VAR>template</VAR> does not end with <samp>XXXXXX</samp>, <CODE>mktemp</CODE> returns a |
| null pointer. |
| <br><br> Warning: Between the time the pathname is constructed and the |
| file is created another process might have created a file with the same |
| name using <CODE>mktemp</CODE>, leading to a possible security hole. The |
| implementation generates names which can hardly be predicted, but when |
| opening the file you should use the <CODE>O_EXCL</CODE> flag. Using |
| <CODE>mkstemp</CODE> is a safe way to avoid this problem. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-mkstemp" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="char *template"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>mkstemp</CODE> function generates a unique file name just as |
| <CODE>mktemp</CODE> does, but it also opens the file for you with <CODE>open</CODE> |
| . If successful, it modifies |
| <VAR>template</VAR> in place and returns a file descriptor for that file open |
| for reading and writing. If <CODE>mkstemp</CODE> cannot create a |
| uniquely-named file, it returns <CODE>-1</CODE>. If <VAR>template</VAR> does not |
| end with <samp>XXXXXX</samp>, <CODE>mkstemp</CODE> returns <CODE>-1</CODE> and does not |
| modify <VAR>template</VAR>. |
| <br><br> The file is opened using mode <CODE>0600</CODE>. If the file is meant to be |
| used by other users this mode must be changed explicitly. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-mkdtemp" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="char *template"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>mkdtemp</CODE> function creates a directory with a unique name. If |
| it succeeds, it overwrites <VAR>template</VAR> with the name of the |
| directory, and returns <VAR>template</VAR>. As with <CODE>mktemp</CODE> and |
| <CODE>mkstemp</CODE>, <VAR>template</VAR> should be a string ending with |
| <samp>XXXXXX</samp>. |
| <br><br> If <CODE>mkdtemp</CODE> cannot create an uniquely named directory, it returns |
| <CODE>NULL</CODE> and sets <VAR>errno</VAR> appropriately. If <VAR>template</VAR> does |
| not end with <samp>XXXXXX</samp>, <CODE>mkdtemp</CODE> returns <CODE>NULL</CODE> and does |
| not modify <VAR>template</VAR>. <VAR>errno</VAR> will be set to <CODE>EINVAL</CODE> in |
| this case. |
| <br><br> The directory is created using mode <CODE>0700</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-strsignal" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="int signum"/> |
| </prototype> |
| <headers> |
| <header filename = "signal.h"/> |
| <header filename = "string.h"/> |
| </headers> |
| <synopsis> |
| This function returns a pointer to a statically-allocated string |
| containing a message describing the signal <VAR>signum</VAR>. You |
| should not modify the contents of this string; and, since it can be |
| rewritten on subsequent calls, you should save a copy of it if you need |
| to reference it later. |
| <br><br> This function is a GNU extension, declared in the header file |
| <TT>string.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-psignal" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="int signum"/> |
| <parameter content="const char *message"/> |
| </prototype> |
| <headers> |
| <header filename = "signal.h"/> |
| </headers> |
| <synopsis> |
| This function prints a message describing the signal <VAR>signum</VAR> to the |
| standard error output stream <CODE>stderr</CODE>; see Standard Streams. |
| <br><br> If you call <CODE>psignal</CODE> with a <VAR>message</VAR> that is either a null |
| pointer or an empty string, <CODE>psignal</CODE> just prints the message |
| corresponding to <VAR>signum</VAR>, adding a trailing newline. |
| <br><br> If you supply a non-null <VAR>message</VAR> argument, then <CODE>psignal</CODE> |
| prefixes its output with this string. It adds a colon and a space |
| character to separate the <VAR>message</VAR> from the string corresponding |
| to <VAR>signum</VAR>. |
| <br><br> This function is a BSD feature, declared in the header file <TT>signal.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="dtype-sighandler_t" type="dtype"> |
| <structure> |
| </structure> |
| </construct> |
| <construct id="function-signal" type="function"> |
| <function returntype="sighandler_t"> |
| <prototype> |
| <parameter content="int signum"/> |
| <parameter content="sighandler_t action"/> |
| </prototype> |
| <headers> |
| <header filename = "signal.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>signal</CODE> function establishes <VAR>action</VAR> as the action for |
| the signal <VAR>signum</VAR>. |
| <br><br> The first argument, <VAR>signum</VAR>, identifies the signal whose behavior |
| you want to control, and should be a signal number. The proper way to |
| specify a signal number is with one of the symbolic signal names |
| ---don't use an explicit number, because |
| the numerical code for a given kind of signal may vary from operating |
| system to operating system. |
| <br><br> The second argument, <VAR>action</VAR>, specifies the action to use for the |
| signal <VAR>signum</VAR>. This can be one of the following: |
| <br><br> <DL> |
| |
| <DT><CODE>SIG_DFL</CODE> |
| <DD> |
| |
| action for a signal |
| <CODE>SIG_DFL</CODE> specifies the default action for the particular signal. |
| The default actions for various kinds of signals are stated in |
| Standard Signals. |
| <br><br> <DT><CODE>SIG_IGN</CODE> |
| <DD> |
| |
| action for a signal |
| <CODE>SIG_IGN</CODE> specifies that the signal should be ignored. |
| <br><br> Your program generally should not ignore signals that represent serious |
| events or that are normally used to request termination. You cannot |
| ignore the <CODE>SIGKILL</CODE> or <CODE>SIGSTOP</CODE> signals at all. You can |
| ignore program error signals like <CODE>SIGSEGV</CODE>, but ignoring the error |
| won't enable the program to continue executing meaningfully. Ignoring |
| user requests such as <CODE>SIGINT</CODE>, <CODE>SIGQUIT</CODE>, and <CODE>SIGTSTP</CODE> |
| is unfriendly. |
| <br><br> When you do not wish signals to be delivered during a certain part of |
| the program, the thing to do is to block them, not ignore them. |
| . |
| <br><br> <LI> <VAR>handler</VAR> |
| Supply the address of a handler function in your program, to specify |
| running this handler as the way to deliver the signal. |
| <br><br> For more information about defining signal handler functions, |
| see Defining Handlers. |
| |
| <br><br> If you set the action for a signal to <CODE>SIG_IGN</CODE>, or if you set it |
| to <CODE>SIG_DFL</CODE> and the default action is to ignore that signal, then |
| any pending signals of that type are discarded (even if they are |
| blocked). Discarding the pending signals means that they will never be |
| delivered, not even if you subsequently specify another action and |
| unblock this kind of signal. |
| <br><br> The <CODE>signal</CODE> function returns the action that was previously in |
| effect for the specified <VAR>signum</VAR>. You can save this value and |
| restore it later by calling <CODE>signal</CODE> again. |
| <br><br> If <CODE>signal</CODE> can't honor the request, it returns <CODE>SIG_ERR</CODE> |
| instead. The following <CODE>errno</CODE> error conditions are defined for |
| this function: |
| <br><br> <DL> |
| |
| <LI> EINVAL |
| You specified an invalid <VAR>signum</VAR>; or you tried to ignore or provide |
| a handler for <CODE>SIGKILL</CODE> or <CODE>SIGSTOP</CODE>. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-sysv_signal" type="function"> |
| <function returntype="sighandler_t"> |
| <prototype> |
| <parameter content="int signum"/> |
| <parameter content="sighandler_t action"/> |
| </prototype> |
| <headers> |
| <header filename = "signal.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>sysv_signal</CODE> implements the behavior of the standard |
| <CODE>signal</CODE> function as found on SVID systems. The difference to BSD |
| systems is that the handler is deinstalled after a delivery of a signal. |
| <br><br> Compatibility Note: As said above for <CODE>signal</CODE>, this |
| function should be avoided when possible. <CODE>sigaction</CODE> is the |
| preferred method. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-ssignal" type="function"> |
| <function returntype="sighandler_t"> |
| <prototype> |
| <parameter content="int signum"/> |
| <parameter content="sighandler_t action"/> |
| </prototype> |
| <headers> |
| <header filename = "signal.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>ssignal</CODE> function does the same thing as <CODE>signal</CODE>; it is |
| provided only for compatibility with SVID. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="struct-sigaction" type="struct"> |
| <structure> |
| <synopsis> |
| Structures of type <CODE>struct sigaction</CODE> are used in the |
| <CODE>sigaction</CODE> function to specify all the information about how to |
| handle a particular signal. This structure contains at least the |
| following members: |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="sighandler_t sa_handler"> |
| <synopsis> |
| This is used in the same way as the <VAR>action</VAR> argument to the |
| <CODE>signal</CODE> function. The value can be <CODE>SIG_DFL</CODE>, |
| <CODE>SIG_IGN</CODE>, or a function pointer. . |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="sigset_t sa_mask"> |
| <synopsis> |
| This specifies a set of signals to be blocked while the handler runs. |
| Blocking is explained in Blocking for Handler. Note that the |
| signal that was delivered is automatically blocked by default before its |
| handler is started; this is true regardless of the value in |
| <CODE>sa_mask</CODE>. If you want that signal not to be blocked within its |
| handler, you must write code in the handler to unblock it. |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="function-sigaction" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int signum"/> |
| <parameter content="const struct sigaction *restrict action"/> |
| <parameter content="struct sigaction *restrict old-action"/> |
| </prototype> |
| <headers> |
| <header filename = "signal.h"/> |
| </headers> |
| <synopsis> |
| The <VAR>action</VAR> argument is used to set up a new action for the signal |
| <VAR>signum</VAR>, while the <VAR>old-action</VAR> argument is used to return |
| information about the action previously associated with this symbol. |
| (In other words, <VAR>old-action</VAR> has the same purpose as the |
| <CODE>signal</CODE> function's return value---you can check to see what the |
| old action in effect for the signal was, and restore it later if you |
| want.) |
| <br><br> Either <VAR>action</VAR> or <VAR>old-action</VAR> can be a null pointer. If |
| <VAR>old-action</VAR> is a null pointer, this simply suppresses the return |
| of information about the old action. If <VAR>action</VAR> is a null pointer, |
| the action associated with the signal <VAR>signum</VAR> is unchanged; this |
| allows you to inquire about how a signal is being handled without changing |
| that handling. |
| <br><br> The return value from <CODE>sigaction</CODE> is zero if it succeeds, and |
| <CODE>-1</CODE> on failure. The following <CODE>errno</CODE> error conditions are |
| defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EINVAL</CODE> |
| <DD> |
| The <VAR>signum</VAR> argument is not valid, or you are trying to |
| trap or ignore <CODE>SIGKILL</CODE> or <CODE>SIGSTOP</CODE>. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="dtype-sig_atomic_t" type="dtype"> |
| <structure> |
| </structure> |
| </construct> |
| <construct id="function-raise" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int signum"/> |
| </prototype> |
| <headers> |
| <header filename = "signal.h"/> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>raise</CODE> function sends the signal <VAR>signum</VAR> to the calling |
| process. It returns zero if successful and a nonzero value if it fails. |
| About the only reason for failure would be if the value of <VAR>signum</VAR> |
| is invalid. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-gsignal" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int signum"/> |
| </prototype> |
| <headers> |
| <header filename = "signal.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>gsignal</CODE> function does the same thing as <CODE>raise</CODE>; it is |
| provided only for compatibility with SVID. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-kill" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="pid_t pid"/> |
| <parameter content="int signum"/> |
| </prototype> |
| <headers> |
| <header filename = "signal.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>kill</CODE> function sends the signal <VAR>signum</VAR> to the process |
| or process group specified by <VAR>pid</VAR>. Besides the signals listed in |
| Standard Signals, <VAR>signum</VAR> can also have a value of zero to |
| check the validity of the <VAR>pid</VAR>. |
| <br><br> The <VAR>pid</VAR> specifies the process or process group to receive the |
| signal: |
| <br><br> <DL> |
| |
| <DT><CODE><VAR>pid</VAR> > 0</CODE> |
| <DD> |
| The process whose identifier is <VAR>pid</VAR>. |
| <br><br> <DT><CODE><VAR>pid</VAR> == 0</CODE> |
| <DD> |
| All processes in the same process group as the sender. |
| <br><br> <LI> <VAR>pid</VAR> < -1 |
| The process group whose identifier is <VAR>pid</VAR>. |
| <br><br> <LI> <VAR>pid</VAR> == -1 |
| If the process is privileged, send the signal to all processes except |
| for some special system processes. Otherwise, send the signal to all |
| processes with the same effective user ID. |
| |
| <br><br> A process can send a signal to itself with a call like <CODE>kill |
| (getpid(), <VAR>signum</VAR>)</CODE>. If <CODE>kill</CODE> is used by a process to send |
| a signal to itself, and the signal is not blocked, then <CODE>kill</CODE> |
| delivers at least one signal (which might be some other pending |
| unblocked signal instead of the signal <VAR>signum</VAR>) to that process |
| before it returns. |
| <br><br> The return value from <CODE>kill</CODE> is zero if the signal can be sent |
| successfully. Otherwise, no signal is sent, and a value of <CODE>-1</CODE> is |
| returned. If <VAR>pid</VAR> specifies sending a signal to several processes, |
| <CODE>kill</CODE> succeeds if it can send the signal to at least one of them. |
| There's no way you can tell which of the processes got the signal |
| or whether all of them did. |
| <br><br> The following <CODE>errno</CODE> error conditions are defined for this function: |
| <br><br> <DL> |
| |
| <LI> EINVAL |
| The <VAR>signum</VAR> argument is an invalid or unsupported number. |
| <br><br> <LI> EPERM |
| You do not have the privilege to send a signal to the process or any of |
| the processes in the process group named by <VAR>pid</VAR>. |
| <br><br> <LI> ESRCH |
| The <VAR>pid</VAR> argument does not refer to an existing process or group. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-killpg" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int pgid"/> |
| <parameter content="int signum"/> |
| </prototype> |
| <headers> |
| <header filename = "signal.h"/> |
| </headers> |
| <synopsis> |
| This is similar to <CODE>kill</CODE>, but sends signal <VAR>signum</VAR> to the |
| process group <VAR>pgid</VAR>. This function is provided for compatibility |
| with BSD; using <CODE>kill</CODE> to do this is more portable. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="dtype-sigset_t" type="dtype"> |
| <structure> |
| </structure> |
| </construct> |
| <construct id="function-sigemptyset" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="sigset_t *set"/> |
| </prototype> |
| <headers> |
| <header filename = "signal.h"/> |
| </headers> |
| <synopsis> |
| This function initializes the signal set <VAR>set</VAR> to exclude all of the |
| defined signals. It always returns <CODE>0</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-sigfillset" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="sigset_t *set"/> |
| </prototype> |
| <headers> |
| <header filename = "signal.h"/> |
| </headers> |
| <synopsis> |
| This function initializes the signal set <VAR>set</VAR> to include |
| all of the defined signals. Again, the return value is <CODE>0</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-sigaddset" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="sigset_t *set"/> |
| <parameter content="int signum"/> |
| </prototype> |
| <headers> |
| <header filename = "signal.h"/> |
| </headers> |
| <synopsis> |
| This function adds the signal <VAR>signum</VAR> to the signal set <VAR>set</VAR>. |
| All <CODE>sigaddset</CODE> does is modify <VAR>set</VAR>; it does not block or |
| unblock any signals. |
| <br><br> The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on failure. |
| The following <CODE>errno</CODE> error condition is defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EINVAL</CODE> |
| <DD> |
| The <VAR>signum</VAR> argument doesn't specify a valid signal. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-sigdelset" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="sigset_t *set"/> |
| <parameter content="int signum"/> |
| </prototype> |
| <headers> |
| <header filename = "signal.h"/> |
| </headers> |
| <synopsis> |
| This function removes the signal <VAR>signum</VAR> from the signal set |
| <VAR>set</VAR>. All <CODE>sigdelset</CODE> does is modify <VAR>set</VAR>; it does not |
| block or unblock any signals. The return value and error conditions are |
| the same as for <CODE>sigaddset</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-sigismember" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const sigset_t *set"/> |
| <parameter content="int signum"/> |
| </prototype> |
| <headers> |
| <header filename = "signal.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>sigismember</CODE> function tests whether the signal <VAR>signum</VAR> is |
| a member of the signal set <VAR>set</VAR>. It returns <CODE>1</CODE> if the signal |
| is in the set, <CODE>0</CODE> if not, and <CODE>-1</CODE> if there is an error. |
| <br><br> The following <CODE>errno</CODE> error condition is defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EINVAL</CODE> |
| <DD> |
| The <VAR>signum</VAR> argument doesn't specify a valid signal. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-sigprocmask" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int how"/> |
| <parameter content="const sigset_t *restrict set"/> |
| <parameter content="sigset_t *restrict oldset"/> |
| </prototype> |
| <headers> |
| <header filename = "signal.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>sigprocmask</CODE> function is used to examine or change the calling |
| process's signal mask. The <VAR>how</VAR> argument determines how the signal |
| mask is changed, and must be one of the following values: |
| <br><br> <DL> |
| |
| |
| <DT><CODE>SIG_BLOCK</CODE> |
| <DD> |
| Block the signals in <CODE>set</CODE>---add them to the existing mask. In |
| other words, the new mask is the union of the existing mask and |
| <VAR>set</VAR>. |
| <br><br> |
| <DT><CODE>SIG_UNBLOCK</CODE> |
| <DD> |
| Unblock the signals in <VAR>set</VAR>---remove them from the existing mask. |
| <br><br> |
| <LI> SIG_SETMASK |
| Use <VAR>set</VAR> for the mask; ignore the previous value of the mask. |
| |
| <br><br> The last argument, <VAR>oldset</VAR>, is used to return information about the |
| old process signal mask. If you just want to change the mask without |
| looking at it, pass a null pointer as the <VAR>oldset</VAR> argument. |
| Similarly, if you want to know what's in the mask without changing it, |
| pass a null pointer for <VAR>set</VAR> (in this case the <VAR>how</VAR> argument |
| is not significant). The <VAR>oldset</VAR> argument is often used to |
| remember the previous signal mask in order to restore it later. (Since |
| the signal mask is inherited over <CODE>fork</CODE> and <CODE>exec</CODE> calls, you |
| can't predict what its contents are when your program starts running.) |
| <br><br> If invoking <CODE>sigprocmask</CODE> causes any pending signals to be |
| unblocked, at least one of those signals is delivered to the process |
| before <CODE>sigprocmask</CODE> returns. The order in which pending signals |
| are delivered is not specified, but you can control the order explicitly |
| by making multiple <CODE>sigprocmask</CODE> calls to unblock various signals |
| one at a time. |
| <br><br> The <CODE>sigprocmask</CODE> function returns <CODE>0</CODE> if successful, and <CODE>-1</CODE> |
| to indicate an error. The following <CODE>errno</CODE> error conditions are |
| defined for this function: |
| <br><br> <DL> |
| |
| <LI> EINVAL |
| The <VAR>how</VAR> argument is invalid. |
| |
| <br><br> You can't block the <CODE>SIGKILL</CODE> and <CODE>SIGSTOP</CODE> signals, but |
| if the signal set includes these, <CODE>sigprocmask</CODE> just ignores |
| them instead of returning an error status. |
| <br><br> Remember, too, that blocking program error signals such as <CODE>SIGFPE</CODE> |
| leads to undesirable results for signals generated by an actual program |
| error (as opposed to signals sent with <CODE>raise</CODE> or <CODE>kill</CODE>). |
| This is because your program may be too broken to be able to continue |
| executing to a point where the signal is unblocked again. |
| . |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-sigpending" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="sigset_t *set"/> |
| </prototype> |
| <headers> |
| <header filename = "signal.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>sigpending</CODE> function stores information about pending signals |
| in <VAR>set</VAR>. If there is a pending signal that is blocked from |
| delivery, then that signal is a member of the returned set. (You can |
| test whether a particular signal is a member of this set using |
| <CODE>sigismember</CODE>; see Signal Sets.) |
| <br><br> The return value is <CODE>0</CODE> if successful, and <CODE>-1</CODE> on failure. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-pause" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content=""/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>pause</CODE> function suspends program execution until a signal |
| arrives whose action is either to execute a handler function, or to |
| terminate the process. |
| <br><br> If the signal causes a handler function to be executed, then |
| <CODE>pause</CODE> returns. This is considered an unsuccessful return (since |
| ``successful'' behavior would be to suspend the program forever), so the |
| return value is <CODE>-1</CODE>. Even if you specify that other primitives |
| should resume when a system handler returns , this has no effect on <CODE>pause</CODE>; it always fails when a |
| signal is handled. |
| <br><br> The following <CODE>errno</CODE> error conditions are defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EINTR</CODE> |
| <DD> |
| The function was interrupted by delivery of a signal. |
| |
| <br><br> If the signal causes program termination, <CODE>pause</CODE> doesn't return |
| (obviously). |
| <br><br> This function is a cancellation point in multithreaded programs. This |
| is a problem if the thread allocates some resources (like memory, file |
| descriptors, semaphores or whatever) at the time <CODE>pause</CODE> is |
| called. If the thread gets cancelled these resources stay allocated |
| until the program ends. To avoid this calls to <CODE>pause</CODE> should be |
| protected using cancellation handlers. |
| <br><br> The <CODE>pause</CODE> function is declared in <TT>unistd.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-sigsuspend" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const sigset_t *set"/> |
| </prototype> |
| <headers> |
| <header filename = "signal.h"/> |
| </headers> |
| <synopsis> |
| This function replaces the process's signal mask with <VAR>set</VAR> and then |
| suspends the process until a signal is delivered whose action is either |
| to terminate the process or invoke a signal handling function. In other |
| words, the program is effectively suspended until one of the signals that |
| is not a member of <VAR>set</VAR> arrives. |
| <br><br> If the process is woken up by delivery of a signal that invokes a handler |
| function, and the handler function returns, then <CODE>sigsuspend</CODE> also |
| returns. |
| <br><br> The mask remains <VAR>set</VAR> only as long as <CODE>sigsuspend</CODE> is waiting. |
| The function <CODE>sigsuspend</CODE> always restores the previous signal mask |
| when it returns. |
| <br><br> The return value and error conditions are the same as for <CODE>pause</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="dtype-stack_t" type="dtype"> |
| <structure> |
| <synopsis> |
| This structure describes a signal stack. It contains the following members: |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="void *ss_sp"> |
| <synopsis> |
| This points to the base of the signal stack. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="size_t ss_size"> |
| <synopsis> |
| This is the size (in bytes) of the signal stack which <samp>ss_sp</samp> points to. |
| You should set this to however much space you allocated for the stack. |
| <br><br> There are two macros defined in <TT>signal.h</TT> that you should use in |
| calculating this size: |
| <br><br> <DL> |
| |
| </synopsis> |
| </element> |
| <element content="SIGSTKSZ"> |
| <synopsis> |
| This is the canonical size for a signal stack. It is judged to be |
| sufficient for normal uses. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="MINSIGSTKSZ"> |
| <synopsis> |
| This is the amount of signal stack space the operating system needs just |
| to implement signal delivery. The size of a signal stack <h3>must</h3> |
| be greater than this. |
| <br><br> For most cases, just using <CODE>SIGSTKSZ</CODE> for <CODE>ss_size</CODE> 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 <CODE>MINSIGSTKSZ</CODE> additional bytes for the signal |
| stack and increase <CODE>ss_size</CODE> accordingly. |
| </DL> |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="int ss_flags"> |
| <synopsis> |
| This field contains the bitwise or of these flags: |
| <br><br> <DL> |
| |
| </synopsis> |
| </element> |
| <element content="SS_DISABLE"> |
| <synopsis> |
| This tells the system that it should not use the signal stack. |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="function-sigaltstack" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const stack_t *restrict stack"/> |
| <parameter content="stack_t *restrict oldstack"/> |
| </prototype> |
| <headers> |
| <header filename = "signal.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>sigaltstack</CODE> function specifies an alternate stack for use |
| during signal handling. When a signal is received by the process and |
| its action indicates that the signal stack is used, the system arranges |
| a switch to the currently installed signal stack while the handler for |
| that signal is executed. |
| <br><br> If <VAR>oldstack</VAR> is not a null pointer, information about the currently |
| installed signal stack is returned in the location it points to. If |
| <VAR>stack</VAR> is not a null pointer, then this is installed as the new |
| stack for use by signal handlers. |
| <br><br> The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on failure. If |
| <CODE>sigaltstack</CODE> fails, it sets <CODE>errno</CODE> to one of these values: |
| <br><br> <DL> |
| |
| <DT><CODE>EINVAL</CODE> |
| <DD> |
| You tried to disable a stack that was in fact currently in use. |
| <br><br> <LI> ENOMEM |
| The size of the alternate stack was too small. |
| It must be greater than <CODE>MINSIGSTKSZ</CODE>. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="struct-sigstack" type="struct"> |
| <structure> |
| <synopsis> |
| This structure describes a signal stack. It contains the following members: |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="void *ss_sp"> |
| <synopsis> |
| This is the stack pointer. If the stack grows downwards on your |
| machine, this should point to the top of the area you allocated. If the |
| stack grows upwards, it should point to the bottom. |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="function-sigstack" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const struct sigstack *stack"/> |
| <parameter content="struct sigstack *oldstack"/> |
| </prototype> |
| <headers> |
| <header filename = "signal.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>sigstack</CODE> function specifies an alternate stack for use during |
| signal handling. When a signal is received by the process and its |
| action indicates that the signal stack is used, the system arranges a |
| switch to the currently installed signal stack while the handler for |
| that signal is executed. |
| <br><br> If <VAR>oldstack</VAR> is not a null pointer, information about the currently |
| installed signal stack is returned in the location it points to. If |
| <VAR>stack</VAR> is not a null pointer, then this is installed as the new |
| stack for use by signal handlers. |
| <br><br> The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on failure. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="struct-sigvec" type="struct"> |
| <structure> |
| <synopsis> |
| This data type is the BSD equivalent of <CODE>struct sigaction</CODE> |
| ; it is used to specify signal actions |
| to the <CODE>sigvec</CODE> function. It contains the following members: |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="sighandler_t sv_handler"> |
| <synopsis> |
| This is the handler function. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="int sv_mask"> |
| <synopsis> |
| This is the mask of additional signals to be blocked while the handler |
| function is being called. |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="function-sigvec" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int signum"/> |
| <parameter content="const struct sigvec *action,struct sigvec *old-action"/> |
| </prototype> |
| <headers> |
| <header filename = "signal.h"/> |
| </headers> |
| <synopsis> |
| This function is the equivalent of <CODE>sigaction</CODE> ; it installs the action <VAR>action</VAR> for the signal <VAR>signum</VAR>, |
| returning information about the previous action in effect for that signal |
| in <VAR>old-action</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-siginterrupt" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int signum"/> |
| <parameter content="int failflag"/> |
| </prototype> |
| <headers> |
| <header filename = "signal.h"/> |
| </headers> |
| <synopsis> |
| This function specifies which approach to use when certain primitives |
| are interrupted by handling signal <VAR>signum</VAR>. If <VAR>failflag</VAR> is |
| false, signal <VAR>signum</VAR> restarts primitives. If <VAR>failflag</VAR> is |
| true, handling <VAR>signum</VAR> causes these primitives to fail with error |
| code <CODE>EINTR</CODE>. . |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-sigblock" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int mask"/> |
| </prototype> |
| <headers> |
| <header filename = "signal.h"/> |
| </headers> |
| <synopsis> |
| This function is equivalent to <CODE>sigprocmask</CODE> with a <VAR>how</VAR> argument of <CODE>SIG_BLOCK</CODE>: it adds the |
| signals specified by <VAR>mask</VAR> to the calling process's set of blocked |
| signals. The return value is the previous set of blocked signals. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-sigsetmask" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int mask"/> |
| </prototype> |
| <headers> |
| <header filename = "signal.h"/> |
| </headers> |
| <synopsis> |
| This function equivalent to <CODE>sigprocmask</CODE> with a <VAR>how</VAR> argument of <CODE>SIG_SETMASK</CODE>: it sets |
| the calling process's signal mask to <VAR>mask</VAR>. The return value is |
| the previous set of blocked signals. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-sigpause" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int mask"/> |
| </prototype> |
| <headers> |
| <header filename = "signal.h"/> |
| </headers> |
| <synopsis> |
| This function is the equivalent of <CODE>sigsuspend</CODE> : it sets the calling process's signal mask to <VAR>mask</VAR>, |
| and waits for a signal to arrive. On return the previous set of blocked |
| signals is restored. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-pipe" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int filedes[2]"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>pipe</CODE> function creates a pipe and puts the file descriptors |
| for the reading and writing ends of the pipe (respectively) into |
| <CODE><VAR>filedes</VAR>[0]</CODE> and <CODE><VAR>filedes</VAR>[1]</CODE>. |
| <br><br> An easy way to remember that the input end comes first is that file |
| descriptor <CODE>0</CODE> is standard input, and file descriptor <CODE>1</CODE> is |
| standard output. |
| <br><br> If successful, <CODE>pipe</CODE> returns a value of <CODE>0</CODE>. On failure, |
| <CODE>-1</CODE> is returned. The following <CODE>errno</CODE> error conditions are |
| defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EMFILE</CODE> |
| <DD> |
| The process has too many files open. |
| <br><br> <LI> ENFILE |
| There are too many open files in the entire system. , |
| for more information about <CODE>ENFILE</CODE>. This error never occurs in |
| the GNU system. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-popen" type="function"> |
| <function returntype="FILE *"> |
| <prototype> |
| <parameter content="const char *command"/> |
| <parameter content="const char *mode"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>popen</CODE> function is closely related to the <CODE>system</CODE> |
| function; see Running a Command. It executes the shell command |
| <VAR>command</VAR> as a subprocess. However, instead of waiting for the |
| command to complete, it creates a pipe to the subprocess and returns a |
| stream that corresponds to that pipe. |
| <br><br> If you specify a <VAR>mode</VAR> argument of <CODE>"r"</CODE>, you can read from the |
| stream to retrieve data from the standard output channel of the subprocess. |
| The subprocess inherits its standard input channel from the parent process. |
| <br><br> Similarly, if you specify a <VAR>mode</VAR> argument of <CODE>"w"</CODE>, you can |
| write to the stream to send data to the standard input channel of the |
| subprocess. The subprocess inherits its standard output channel from |
| the parent process. |
| <br><br> In the event of an error <CODE>popen</CODE> returns a null pointer. This |
| might happen if the pipe or stream cannot be created, if the subprocess |
| cannot be forked, or if the program cannot be executed. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-pclose" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>pclose</CODE> function is used to close a stream created by <CODE>popen</CODE>. |
| It waits for the child process to terminate and returns its status value, |
| as for the <CODE>system</CODE> function. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-mkfifo" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *filename"/> |
| <parameter content="mode_t mode"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/stat.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>mkfifo</CODE> function makes a FIFO special file with name |
| <VAR>filename</VAR>. The <VAR>mode</VAR> argument is used to set the file's |
| permissions; see Setting Permissions. |
| <br><br> The normal, successful return value from <CODE>mkfifo</CODE> is <CODE>0</CODE>. In |
| the case of an error, <CODE>-1</CODE> is returned. In addition to the usual |
| file name errors , the following |
| <CODE>errno</CODE> error conditions are defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EEXIST</CODE> |
| <DD> |
| The named file already exists. |
| <br><br> <LI> ENOSPC |
| The directory or file system cannot be extended. |
| <br><br> <LI> EROFS |
| The directory that would contain the file resides on a read-only file |
| system. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-strerror" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="int errnum"/> |
| </prototype> |
| <headers> |
| <header filename = "errno.h"/> |
| <header filename = "string.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>strerror</CODE> function maps the error code specified by the <VAR>errnum</VAR> argument to a descriptive error |
| message string. The return value is a pointer to this string. |
| <br><br> The value <VAR>errnum</VAR> normally comes from the variable <CODE>errno</CODE>. |
| <br><br> You should not modify the string returned by <CODE>strerror</CODE>. Also, if |
| you make subsequent calls to <CODE>strerror</CODE>, the string might be |
| overwritten. (But it's guaranteed that no library function ever calls |
| <CODE>strerror</CODE> behind your back.) |
| <br><br> The function <CODE>strerror</CODE> is declared in <TT>string.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-strerror_r" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="int errnum"/> |
| <parameter content="char *buf"/> |
| <parameter content="size_t n"/> |
| </prototype> |
| <headers> |
| <header filename = "string.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>strerror_r</CODE> function works like <CODE>strerror</CODE> but instead of |
| returning the error message in a statically allocated buffer shared by |
| all threads in the process, it returns a private copy for the |
| thread. This might be either some permanent global data or a message |
| string in the user supplied buffer starting at <VAR>buf</VAR> with the |
| length of <VAR>n</VAR> bytes. |
| <br><br> At most <VAR>n</VAR> characters are written (including the NUL byte) so it is |
| up to the user to select the buffer large enough. |
| <br><br> This function should always be used in multi-threaded programs since |
| there is no way to guarantee the string returned by <CODE>strerror</CODE> |
| really belongs to the last call of the current thread. |
| <br><br> This function <CODE>strerror_r</CODE> is a GNU extension and it is declared in |
| <TT>string.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-perror" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="const char *message"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| This function prints an error message to the stream <CODE>stderr</CODE>; |
| see Standard Streams. The orientation of <CODE>stderr</CODE> is not |
| changed. |
| <br><br> If you call <CODE>perror</CODE> with a <VAR>message</VAR> that is either a null |
| pointer or an empty string, <CODE>perror</CODE> just prints the error message |
| corresponding to <CODE>errno</CODE>, adding a trailing newline. |
| <br><br> If you supply a non-null <VAR>message</VAR> argument, then <CODE>perror</CODE> |
| prefixes its output with this string. It adds a colon and a space |
| character to separate the <VAR>message</VAR> from the error string corresponding |
| to <CODE>errno</CODE>. |
| <br><br> The function <CODE>perror</CODE> is declared in <TT>stdio.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-error" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="int status"/> |
| <parameter content="int errnum"/> |
| <parameter content="const char *format"/> |
| <parameter content="..."/> |
| </prototype> |
| <headers> |
| <header filename = "errno.h"/> |
| <header filename = "error.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>error</CODE> function can be used to report general problems during |
| program execution. The <VAR>format</VAR> argument is a format string just |
| like those given to the <CODE>printf</CODE> family of functions. The |
| arguments required for the format can follow the <VAR>format</VAR> parameter. |
| Just like <CODE>perror</CODE>, <CODE>error</CODE> also can report an error code in |
| textual form. But unlike <CODE>perror</CODE> the error value is explicitly |
| passed to the function in the <VAR>errnum</VAR> parameter. This eliminates |
| the problem mentioned above that the error reporting function must be |
| called immediately after the function causing the error since otherwise |
| <CODE>errno</CODE> might have a different value. |
| <br><br> The <CODE>error</CODE> prints first the program name. If the application |
| defined a global variable <CODE>error_print_progname</CODE> and points it to a |
| function this function will be called to print the program name. |
| Otherwise the string from the global variable <CODE>program_name</CODE> is |
| used. The program name is followed by a colon and a space which in turn |
| is followed by the output produced by the format string. If the |
| <VAR>errnum</VAR> parameter is non-zero the format string output is followed |
| by a colon and a space, followed by the error message for the error code |
| <VAR>errnum</VAR>. In any case is the output terminated with a newline. |
| <br><br> The output is directed to the <CODE>stderr</CODE> stream. If the |
| <CODE>stderr</CODE> wasn't oriented before the call it will be narrow-oriented |
| afterwards. |
| <br><br> The function will return unless the <VAR>status</VAR> parameter has a |
| non-zero value. In this case the function will call <CODE>exit</CODE> with |
| the <VAR>status</VAR> value for its parameter and therefore never return. If |
| <CODE>error</CODE> returns the global variable <CODE>error_message_count</CODE> is |
| incremented by one to keep track of the number of errors reported. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-error_at_line" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="int status"/> |
| <parameter content="int errnum"/> |
| <parameter content="const char *fname"/> |
| <parameter content="unsigned int lineno"/> |
| <parameter content="const char *format"/> |
| <parameter content="..."/> |
| </prototype> |
| <headers> |
| <header filename = "error.h"/> |
| </headers> |
| <synopsis> |
| <br><br> The <CODE>error_at_line</CODE> function is very similar to the <CODE>error</CODE> |
| function. The only difference are the additional parameters <VAR>fname</VAR> |
| and <VAR>lineno</VAR>. The handling of the other parameters is identical to |
| that of <CODE>error</CODE> except that between the program name and the string |
| generated by the format string additional text is inserted. |
| <br><br> Directly following the program name a colon, followed by the file name |
| pointer to by <VAR>fname</VAR>, another colon, and a value of <VAR>lineno</VAR> is |
| printed. |
| <br><br> This additional output of course is meant to be used to locate an error |
| in an input file (like a programming language source code file etc). |
| <br><br> If the global variable <CODE>error_one_per_line</CODE> is set to a non-zero |
| value <CODE>error_at_line</CODE> will avoid printing consecutive messages for |
| the same file and line. Repetition which are not directly following |
| each other are not caught. |
| <br><br> Just like <CODE>error</CODE> this function only returned if <VAR>status</VAR> is |
| zero. Otherwise <CODE>exit</CODE> is called with the non-zero value. If |
| <CODE>error</CODE> returns the global variable <CODE>error_message_count</CODE> is |
| incremented by one to keep track of the number of errors reported. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-warn" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="const char *format"/> |
| <parameter content="..."/> |
| </prototype> |
| <headers> |
| <header filename = "error.h"/> |
| <header filename = "err.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>warn</CODE> function is roughly equivalent to a call like |
| <pre><br> |
| error (0, errno, format, the parameters)<br> |
| </pre> |
| |
| except that the global variables <CODE>error</CODE> respects and modifies |
| are not used. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-vwarn" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="const char *format"/> |
| <parameter content="va_list"/> |
| </prototype> |
| <headers> |
| <header filename = "err.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>vwarn</CODE> function is just like <CODE>warn</CODE> except that the |
| parameters for the handling of the format string <VAR>format</VAR> are passed |
| in as an value of type <CODE>va_list</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-warnx" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="const char *format"/> |
| <parameter content="..."/> |
| </prototype> |
| <headers> |
| <header filename = "err.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>warnx</CODE> function is roughly equivalent to a call like |
| <pre><br> |
| error (0, 0, format, the parameters)<br> |
| </pre> |
| |
| except that the global variables <CODE>error</CODE> respects and modifies |
| are not used. The difference to <CODE>warn</CODE> is that no error number |
| string is printed. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-vwarnx" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="const char *format"/> |
| <parameter content="va_list"/> |
| </prototype> |
| <headers> |
| <header filename = "err.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>vwarnx</CODE> function is just like <CODE>warnx</CODE> except that the |
| parameters for the handling of the format string <VAR>format</VAR> are passed |
| in as an value of type <CODE>va_list</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-err" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="int status"/> |
| <parameter content="const char *format"/> |
| <parameter content="..."/> |
| </prototype> |
| <headers> |
| <header filename = "err.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>err</CODE> function is roughly equivalent to a call like |
| <pre><br> |
| error (status, errno, format, the parameters)<br> |
| </pre> |
| |
| except that the global variables <CODE>error</CODE> respects and modifies |
| are not used and that the program is exited even if <VAR>status</VAR> is zero. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-verr" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="int status"/> |
| <parameter content="const char *format"/> |
| <parameter content="va_list"/> |
| </prototype> |
| <headers> |
| <header filename = "err.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>verr</CODE> function is just like <CODE>err</CODE> except that the |
| parameters for the handling of the format string <VAR>format</VAR> are passed |
| in as an value of type <CODE>va_list</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-errx" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="int status"/> |
| <parameter content="const char *format"/> |
| <parameter content="..."/> |
| </prototype> |
| <headers> |
| <header filename = "err.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>errx</CODE> function is roughly equivalent to a call like |
| <pre><br> |
| error (status, 0, format, the parameters)<br> |
| </pre> |
| |
| except that the global variables <CODE>error</CODE> respects and modifies |
| are not used and that the program is exited even if <VAR>status</VAR> |
| is zero. The difference to <CODE>err</CODE> is that no error number |
| string is printed. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-verrx" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="int status"/> |
| <parameter content="const char *format"/> |
| <parameter content="va_list"/> |
| </prototype> |
| <headers> |
| <header filename = "err.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>verrx</CODE> function is just like <CODE>errx</CODE> except that the |
| parameters for the handling of the format string <VAR>format</VAR> are passed |
| in as an value of type <CODE>va_list</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fnmatch" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *pattern"/> |
| <parameter content="const char *string"/> |
| <parameter content="int flags"/> |
| </prototype> |
| <headers> |
| <header filename = "fnmatch.h"/> |
| </headers> |
| <synopsis> |
| This function tests whether the string <VAR>string</VAR> matches the pattern |
| <VAR>pattern</VAR>. It returns <CODE>0</CODE> if they do match; otherwise, it |
| returns the nonzero value <CODE>FNM_NOMATCH</CODE>. The arguments |
| <VAR>pattern</VAR> and <VAR>string</VAR> are both strings. |
| <br><br> The argument <VAR>flags</VAR> is a combination of flag bits that alter the |
| details of matching. See below for a list of the defined flags. |
| <br><br> In the GNU C Library, <CODE>fnmatch</CODE> cannot experience an ``error''---it |
| always returns an answer for whether the match succeeds. However, other |
| implementations of <CODE>fnmatch</CODE> might sometimes report ``errors''. |
| They would do so by returning nonzero values that are not equal to |
| <CODE>FNM_NOMATCH</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="dtype-glob_t" type="dtype"> |
| <structure> |
| <synopsis> |
| This data type holds a pointer to a word vector. More precisely, it |
| records both the address of the word vector and its size. The GNU |
| implementation contains some more fields which are non-standard |
| extensions. |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="gl_pathc"> |
| <synopsis> |
| The number of elements in the vector, excluding the initial null entries |
| if the GLOB_DOOFFS flag is used (see gl_offs below). |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="gl_pathv"> |
| <synopsis> |
| The address of the vector. This field has type <CODE>char **</CODE>. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="gl_offs"> |
| <synopsis> |
| The offset of the first real element of the vector, from its nominal |
| address in the <CODE>gl_pathv</CODE> field. Unlike the other fields, this |
| is always an input to <CODE>glob</CODE>, rather than an output from it. |
| <br><br> If you use a nonzero offset, then that many elements at the beginning of |
| the vector are left empty. (The <CODE>glob</CODE> function fills them with |
| null pointers.) |
| <br><br> The <CODE>gl_offs</CODE> field is meaningful only if you use the |
| <CODE>GLOB_DOOFFS</CODE> 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><br> |
| </synopsis> |
| </element> |
| <element content="gl_closedir"> |
| <synopsis> |
| The address of an alternative implementation of the <CODE>closedir</CODE> |
| function. It is used if the <CODE>GLOB_ALTDIRFUNC</CODE> bit is set in |
| the flag parameter. The type of this field is |
| <CODE>void (*) (void *)</CODE>. |
| <br><br> This is a GNU extension. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="gl_readdir"> |
| <synopsis> |
| The address of an alternative implementation of the <CODE>readdir</CODE> |
| function used to read the contents of a directory. It is used if the |
| <CODE>GLOB_ALTDIRFUNC</CODE> bit is set in the flag parameter. The type of |
| this field is <CODE>struct dirent *(*) (void *)</CODE>. |
| <br><br> This is a GNU extension. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="gl_opendir"> |
| <synopsis> |
| The address of an alternative implementation of the <CODE>opendir</CODE> |
| function. It is used if the <CODE>GLOB_ALTDIRFUNC</CODE> bit is set in |
| the flag parameter. The type of this field is |
| <CODE>void *(*) (const char *)</CODE>. |
| <br><br> This is a GNU extension. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="gl_stat"> |
| <synopsis> |
| The address of an alternative implementation of the <CODE>stat</CODE> function |
| to get information about an object in the filesystem. It is used if the |
| <CODE>GLOB_ALTDIRFUNC</CODE> bit is set in the flag parameter. The type of |
| this field is <CODE>int (*) (const char *, struct stat *)</CODE>. |
| <br><br> This is a GNU extension. |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="dtype-glob64_t" type="dtype"> |
| <structure> |
| <synopsis> |
| This data type holds a pointer to a word vector. More precisely, it |
| records both the address of the word vector and its size. The GNU |
| implementation contains some more fields which are non-standard |
| extensions. |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="gl_pathc"> |
| <synopsis> |
| The number of elements in the vector, excluding the initial null entries |
| if the GLOB_DOOFFS flag is used (see gl_offs below). |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="gl_pathv"> |
| <synopsis> |
| The address of the vector. This field has type <CODE>char **</CODE>. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="gl_offs"> |
| <synopsis> |
| The offset of the first real element of the vector, from its nominal |
| address in the <CODE>gl_pathv</CODE> field. Unlike the other fields, this |
| is always an input to <CODE>glob</CODE>, rather than an output from it. |
| <br><br> If you use a nonzero offset, then that many elements at the beginning of |
| the vector are left empty. (The <CODE>glob</CODE> function fills them with |
| null pointers.) |
| <br><br> The <CODE>gl_offs</CODE> field is meaningful only if you use the |
| <CODE>GLOB_DOOFFS</CODE> 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><br> |
| </synopsis> |
| </element> |
| <element content="gl_closedir"> |
| <synopsis> |
| The address of an alternative implementation of the <CODE>closedir</CODE> |
| function. It is used if the <CODE>GLOB_ALTDIRFUNC</CODE> bit is set in |
| the flag parameter. The type of this field is |
| <CODE>void (*) (void *)</CODE>. |
| <br><br> This is a GNU extension. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="gl_readdir"> |
| <synopsis> |
| The address of an alternative implementation of the <CODE>readdir64</CODE> |
| function used to read the contents of a directory. It is used if the |
| <CODE>GLOB_ALTDIRFUNC</CODE> bit is set in the flag parameter. The type of |
| this field is <CODE>struct dirent64 *(*) (void *)</CODE>. |
| <br><br> This is a GNU extension. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="gl_opendir"> |
| <synopsis> |
| The address of an alternative implementation of the <CODE>opendir</CODE> |
| function. It is used if the <CODE>GLOB_ALTDIRFUNC</CODE> bit is set in |
| the flag parameter. The type of this field is |
| <CODE>void *(*) (const char *)</CODE>. |
| <br><br> This is a GNU extension. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="gl_stat"> |
| <synopsis> |
| The address of an alternative implementation of the <CODE>stat64</CODE> function |
| to get information about an object in the filesystem. It is used if the |
| <CODE>GLOB_ALTDIRFUNC</CODE> bit is set in the flag parameter. The type of |
| this field is <CODE>int (*) (const char *, struct stat64 *)</CODE>. |
| <br><br> This is a GNU extension. |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="function-glob" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *pattern"/> |
| <parameter content="int flags"/> |
| <parameter content="int (*errfunc) (const char *filename"/> |
| <parameter content="int error-code)"/> |
| <parameter content="glob_t *vector-ptr"/> |
| </prototype> |
| <headers> |
| <header filename = "fnmatch.h"/> |
| <header filename = "glob.h"/> |
| </headers> |
| <synopsis> |
| The function <CODE>glob</CODE> does globbing using the pattern <VAR>pattern</VAR> |
| in the current directory. It puts the result in a newly allocated |
| vector, and stores the size and address of this vector into |
| <CODE>*<VAR>vector-ptr</VAR></CODE>. The argument <VAR>flags</VAR> is a combination of |
| bit flags; see Flags for Globbing, for details of the flags. |
| <br><br> The result of globbing is a sequence of file names. The function |
| <CODE>glob</CODE> allocates a string for each resulting word, then |
| allocates a vector of type <CODE>char **</CODE> to store the addresses of |
| these strings. The last element of the vector is a null pointer. |
| This vector is called the word vector. |
| <br><br> To return this vector, <CODE>glob</CODE> stores both its address and its |
| length (number of elements, not counting the terminating null pointer) |
| into <CODE>*<VAR>vector-ptr</VAR></CODE>. |
| <br><br> Normally, <CODE>glob</CODE> sorts the file names alphabetically before |
| returning them. You can turn this off with the flag <CODE>GLOB_NOSORT</CODE> |
| if you want to get the information as fast as possible. Usually it's |
| a good idea to let <CODE>glob</CODE> sort them---if you process the files in |
| alphabetical order, the users will have a feel for the rate of progress |
| that your application is making. |
| <br><br> If <CODE>glob</CODE> succeeds, it returns 0. Otherwise, it returns one |
| of these error codes: |
| <br><br> <DL> |
| |
| <DT><CODE>GLOB_ABORTED</CODE> |
| <DD> |
| There was an error opening a directory, and you used the flag |
| <CODE>GLOB_ERR</CODE> or your specified <VAR>errfunc</VAR> returned a nonzero |
| value. |
| |
| |
| , |
| |
| for an explanation of the <CODE>GLOB_ERR</CODE> flag and <VAR>errfunc</VAR>. |
| <br><br> <DT><CODE>GLOB_NOMATCH</CODE> |
| <DD> |
| The pattern didn't match any existing files. If you use the |
| <CODE>GLOB_NOCHECK</CODE> flag, then you never get this error code, because |
| that flag tells <CODE>glob</CODE> to <EM>pretend</EM> that the pattern matched |
| at least one file. |
| <br><br> <DT><CODE>GLOB_NOSPACE</CODE> |
| <DD> |
| It was impossible to allocate memory to hold the result. |
| </DL> |
| <br><br> In the event of an error, <CODE>glob</CODE> stores information in |
| <CODE>*<VAR>vector-ptr</VAR></CODE> about all the matches it has found so far. |
| <br><br> It is important to notice that the <CODE>glob</CODE> function will not fail if |
| it encounters directories or files which cannot be handled without the |
| LFS interfaces. The implementation of <CODE>glob</CODE> is supposed to use |
| these functions internally. This at least is the assumptions made by |
| the Unix standard. The GNU extension of allowing the user to provide |
| own directory handling and <CODE>stat</CODE> functions complicates things a |
| bit. If these callback functions are used and a large file or directory |
| is encountered <CODE>glob</CODE> <EM>can</EM> fail. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-glob64" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *pattern"/> |
| <parameter content="int flags"/> |
| <parameter content="int (*errfunc) (const char *filename"/> |
| <parameter content="int error-code)"/> |
| <parameter content="glob64_t *vector-ptr"/> |
| </prototype> |
| <headers> |
| <header filename = "glob.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>glob64</CODE> function was added as part of the Large File Summit |
| extensions but is not part of the original LFS proposal. The reason for |
| this is simple: it is not necessary. The necessity for a <CODE>glob64</CODE> |
| function is added by the extensions of the GNU <CODE>glob</CODE> |
| implementation which allows the user to provide own directory handling |
| and <CODE>stat</CODE> functions. The <CODE>readdir</CODE> and <CODE>stat</CODE> functions |
| do depend on the choice of <CODE>_FILE_OFFSET_BITS</CODE> since the definition |
| of the types <CODE>struct dirent</CODE> and <CODE>struct stat</CODE> will change |
| depending on the choice. |
| <br><br> Beside this difference the <CODE>glob64</CODE> works just like <CODE>glob</CODE> in |
| all aspects. |
| <br><br> This function is a GNU extension. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-globfree" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="glob_t *pglob"/> |
| </prototype> |
| <headers> |
| <header filename = "glob.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>globfree</CODE> function frees all resources allocated by previous |
| calls to <CODE>glob</CODE> associated with the object pointed to by |
| <VAR>pglob</VAR>. This function should be called whenever the currently used |
| <CODE>glob_t</CODE> typed object isn't used anymore. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-globfree64" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="glob64_t *pglob"/> |
| </prototype> |
| <headers> |
| <header filename = "glob.h"/> |
| </headers> |
| <synopsis> |
| This function is equivalent to <CODE>globfree</CODE> but it frees records of |
| type <CODE>glob64_t</CODE> which were allocated by <CODE>glob64</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="dtype-regex_t" type="dtype"> |
| <structure> |
| <synopsis> |
| This type of object holds a compiled regular expression. |
| It is actually a structure. It has just one field that your programs |
| should look at: |
| <br><br> |
| </synopsis> |
| </structure> |
| </construct> |
| <construct id="function-regcomp" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="regex_t *restrict compiled"/> |
| <parameter content="const char *restrict pattern"/> |
| <parameter content="int cflags"/> |
| </prototype> |
| <headers> |
| <header filename = "regex.h"/> |
| </headers> |
| <synopsis> |
| The function <CODE>regcomp</CODE> ``compiles'' a regular expression into a |
| data structure that you can use with <CODE>regexec</CODE> to match against a |
| string. The compiled regular expression format is designed for |
| efficient matching. <CODE>regcomp</CODE> stores it into <CODE>*<VAR>compiled</VAR></CODE>. |
| <br><br> It's up to you to allocate an object of type <CODE>regex_t</CODE> and pass its |
| address to <CODE>regcomp</CODE>. |
| <br><br> The argument <VAR>cflags</VAR> lets you specify various options that control |
| the syntax and semantics of regular expressions. . |
| <br><br> If you use the flag <CODE>REG_NOSUB</CODE>, then <CODE>regcomp</CODE> omits from |
| the compiled regular expression the information necessary to record |
| how subexpressions actually match. In this case, you might as well |
| pass <CODE>0</CODE> for the <VAR>matchptr</VAR> and <VAR>nmatch</VAR> arguments when |
| you call <CODE>regexec</CODE>. |
| <br><br> If you don't use <CODE>REG_NOSUB</CODE>, then the compiled regular expression |
| does have the capacity to record how subexpressions match. Also, |
| <CODE>regcomp</CODE> tells you how many subexpressions <VAR>pattern</VAR> has, by |
| storing the number in <CODE><VAR>compiled</VAR>->re_nsub</CODE>. You can use that |
| value to decide how long an array to allocate to hold information about |
| subexpression matches. |
| <br><br> <CODE>regcomp</CODE> returns <CODE>0</CODE> if it succeeds in compiling the regular |
| expression; otherwise, it returns a nonzero error code (see the table |
| below). You can use <CODE>regerror</CODE> to produce an error message string |
| describing the reason for a nonzero value; see Regexp Cleanup. |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-regexec" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const regex_t *restrict compiled"/> |
| <parameter content="const char *restrict string"/> |
| <parameter content="size_t nmatch"/> |
| <parameter content="regmatch_t matchptr[restrict]"/> |
| <parameter content="int eflags"/> |
| </prototype> |
| <headers> |
| <header filename = "regex.h"/> |
| </headers> |
| <synopsis> |
| This function tries to match the compiled regular expression |
| <CODE>*<VAR>compiled</VAR></CODE> against <VAR>string</VAR>. |
| <br><br> <CODE>regexec</CODE> returns <CODE>0</CODE> if the regular expression matches; |
| otherwise, it returns a nonzero value. See the table below for |
| what nonzero values mean. You can use <CODE>regerror</CODE> to produce an |
| error message string describing the reason for a nonzero value; |
| see Regexp Cleanup. |
| <br><br> The argument <VAR>eflags</VAR> is a word of bit flags that enable various |
| options. |
| <br><br> If you want to get information about what part of <VAR>string</VAR> actually |
| matched the regular expression or its subexpressions, use the arguments |
| <VAR>matchptr</VAR> and <VAR>nmatch</VAR>. Otherwise, pass <CODE>0</CODE> for |
| <VAR>nmatch</VAR>, and <CODE>NULL</CODE> for <VAR>matchptr</VAR>. . |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="dtype-regmatch_t" type="dtype"> |
| <structure> |
| <synopsis> |
| This is the data type of the <VAR>matcharray</VAR> array that you pass to |
| <CODE>regexec</CODE>. It contains two structure fields, as follows: |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="rm_so"> |
| <synopsis> |
| The offset in <VAR>string</VAR> of the beginning of a substring. Add this |
| value to <VAR>string</VAR> to get the address of that part. |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="dtype-regoff_t" type="dtype"> |
| <structure> |
| </structure> |
| </construct> |
| <construct id="function-regfree" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="regex_t *compiled"/> |
| </prototype> |
| <headers> |
| <header filename = "regex.h"/> |
| </headers> |
| <synopsis> |
| Calling <CODE>regfree</CODE> frees all the storage that <CODE>*<VAR>compiled</VAR></CODE> |
| points to. This includes various internal fields of the <CODE>regex_t</CODE> |
| structure that aren't documented in this manual. |
| <br><br> <CODE>regfree</CODE> does not free the object <CODE>*<VAR>compiled</VAR></CODE> itself. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-regerror" type="function"> |
| <function returntype="size_t"> |
| <prototype> |
| <parameter content="int errcode"/> |
| <parameter content="const regex_t *restrict compiled"/> |
| <parameter content="char *restrict buffer"/> |
| <parameter content="size_t length"/> |
| </prototype> |
| <headers> |
| <header filename = "regex.h"/> |
| </headers> |
| <synopsis> |
| This function produces an error message string for the error code |
| <VAR>errcode</VAR>, and stores the string in <VAR>length</VAR> bytes of memory |
| starting at <VAR>buffer</VAR>. For the <VAR>compiled</VAR> argument, supply the |
| same compiled regular expression structure that <CODE>regcomp</CODE> or |
| <CODE>regexec</CODE> was working with when it got the error. Alternatively, |
| you can supply <CODE>NULL</CODE> for <VAR>compiled</VAR>; you will still get a |
| meaningful error message, but it might not be as detailed. |
| <br><br> If the error message can't fit in <VAR>length</VAR> bytes (including a |
| terminating null character), then <CODE>regerror</CODE> truncates it. |
| The string that <CODE>regerror</CODE> stores is always null-terminated |
| even if it has been truncated. |
| <br><br> The return value of <CODE>regerror</CODE> is the minimum length needed to |
| store the entire error message. If this is less than <VAR>length</VAR>, then |
| the error message was not truncated, and you can use it. Otherwise, you |
| should call <CODE>regerror</CODE> again with a larger buffer. |
| <br><br> Here is a function which uses <CODE>regerror</CODE>, but always dynamically |
| allocates a buffer for the error message: |
| <br><br> <pre><br> |
| char *get_regerror (int errcode, regex_t *compiled)<br> |
| {<br> |
| size_t length = regerror (errcode, compiled, NULL, 0);<br> |
| char *buffer = xmalloc (length);<br> |
| (void) regerror (errcode, compiled, buffer, length);<br> |
| return buffer;<br> |
| }<br> |
| </pre> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="type-wordexp_t" type="type"> |
| <structure> |
| <synopsis> |
| This data type holds a pointer to a word vector. More precisely, it |
| records both the address of the word vector and its size. |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="we_wordc"> |
| <synopsis> |
| The number of elements in the vector. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="we_wordv"> |
| <synopsis> |
| The address of the vector. This field has type <CODE>char **</CODE>. |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="function-wordexp" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *words"/> |
| <parameter content="wordexp_t *word-vector-ptr"/> |
| <parameter content="int flags"/> |
| </prototype> |
| <headers> |
| <header filename = "wordexp.h"/> |
| </headers> |
| <synopsis> |
| Perform word expansion on the string <VAR>words</VAR>, putting the result in |
| a newly allocated vector, and store the size and address of this vector |
| into <CODE>*<VAR>word-vector-ptr</VAR></CODE>. The argument <VAR>flags</VAR> is a |
| combination of bit flags; see Flags for Wordexp, for details of |
| the flags. |
| <br><br> You shouldn't use any of the characters <samp>|&;<></samp> in the string |
| <VAR>words</VAR> unless they are quoted; likewise for newline. If you use |
| these characters unquoted, you will get the <CODE>WRDE_BADCHAR</CODE> error |
| code. Don't use parentheses or braces unless they are quoted or part of |
| a word expansion construct. If you use quotation characters <samp>'"`</samp>, |
| they should come in pairs that balance. |
| <br><br> The results of word expansion are a sequence of words. The function |
| <CODE>wordexp</CODE> allocates a string for each resulting word, then |
| allocates a vector of type <CODE>char **</CODE> to store the addresses of |
| these strings. The last element of the vector is a null pointer. |
| This vector is called the word vector. |
| <br><br> To return this vector, <CODE>wordexp</CODE> stores both its address and its |
| length (number of elements, not counting the terminating null pointer) |
| into <CODE>*<VAR>word-vector-ptr</VAR></CODE>. |
| <br><br> If <CODE>wordexp</CODE> succeeds, it returns 0. Otherwise, it returns one |
| of these error codes: |
| <br><br> <DL> |
| |
| <DT><CODE>WRDE_BADCHAR</CODE> |
| <DD> |
| The input string <VAR>words</VAR> contains an unquoted invalid character such |
| as <samp>|</samp>. |
| <br><br> <LI> WRDE_BADVAL |
| The input string refers to an undefined shell variable, and you used the flag |
| <CODE>WRDE_UNDEF</CODE> to forbid such references. |
| <br><br> <LI> WRDE_CMDSUB |
| The input string uses command substitution, and you used the flag |
| <CODE>WRDE_NOCMD</CODE> to forbid command substitution. |
| <br><br> <LI> WRDE_NOSPACE |
| It was impossible to allocate memory to hold the result. In this case, |
| <CODE>wordexp</CODE> can store part of the results---as much as it could |
| allocate room for. |
| <br><br> <LI> WRDE_SYNTAX |
| There was a syntax error in the input string. For example, an unmatched |
| quoting character is a syntax error. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-wordfree" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="wordexp_t *word-vector-ptr"/> |
| </prototype> |
| <headers> |
| <header filename = "wordexp.h"/> |
| </headers> |
| <synopsis> |
| Free the storage used for the word-strings and vector that |
| <CODE>*<VAR>word-vector-ptr</VAR></CODE> points to. This does not free the |
| structure <CODE>*<VAR>word-vector-ptr</VAR></CODE> itself---only the other |
| data it points to. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-backtrace" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="void **buffer"/> |
| <parameter content="int size"/> |
| </prototype> |
| <headers> |
| <header filename = "wordexp.h"/> |
| <header filename = "execinfo.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>backtrace</CODE> function obtains a backtrace for the current |
| thread, as a list of pointers, and places the information into |
| <VAR>buffer</VAR>. The argument <VAR>size</VAR> should be the number of |
| <CODE>void *</CODE> elements that will fit into <VAR>buffer</VAR>. The return |
| value is the actual number of entries of <VAR>buffer</VAR> that are obtained, |
| and is at most <VAR>size</VAR>. |
| <br><br> The pointers placed in <VAR>buffer</VAR> are actually return addresses |
| obtained by inspecting the stack, one return address per stack frame. |
| <br><br> Note that certain compiler optimizations may interfere with obtaining a |
| valid backtrace. Function inlining causes the inlined function to not |
| have a stack frame; tail call optimization replaces one stack frame with |
| another; frame pointer elimination will stop <CODE>backtrace</CODE> from |
| interpreting the stack contents correctly. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-backtrace_symbols" type="function"> |
| <function returntype="char **"> |
| <prototype> |
| <parameter content="void *const *buffer"/> |
| <parameter content="int size"/> |
| </prototype> |
| <headers> |
| <header filename = "execinfo.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>backtrace_symbols</CODE> function translates the information |
| obtained from the <CODE>backtrace</CODE> function into an array of strings. |
| The argument <VAR>buffer</VAR> should be a pointer to an array of addresses |
| obtained via the <CODE>backtrace</CODE> function, and <VAR>size</VAR> is the number |
| of entries in that array (the return value of <CODE>backtrace</CODE>). |
| <br><br> The return value is a pointer to an array of strings, which has |
| <VAR>size</VAR> entries just like the array <VAR>buffer</VAR>. Each string |
| contains a printable representation of the corresponding element of |
| <VAR>buffer</VAR>. It includes the function name (if this can be |
| determined), an offset into the function, and the actual return address |
| (in hexadecimal). |
| <br><br> Currently, the function name and offset only be obtained on systems that |
| use the ELF binary format for programs and libraries. On other systems, |
| only the hexadecimal return address will be present. Also, you may need |
| to pass additional flags to the linker to make the function names |
| available to the program. (For example, on systems using GNU ld, you |
| must pass (<CODE>-rdynamic</CODE>.) |
| <br><br> The return value of <CODE>backtrace_symbols</CODE> is a pointer obtained via |
| the <CODE>malloc</CODE> function, and it is the responsibility of the caller |
| to <CODE>free</CODE> that pointer. Note that only the return value need be |
| freed, not the individual strings. |
| <br><br> The return value is <CODE>NULL</CODE> if sufficient memory for the strings |
| cannot be obtained. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-backtrace_symbols_fd" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="void *const *buffer"/> |
| <parameter content="int size"/> |
| <parameter content="int fd"/> |
| </prototype> |
| <headers> |
| <header filename = "execinfo.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>backtrace_symbols_fd</CODE> function performs the same translation |
| as the function <CODE>backtrace_symbols</CODE> function. Instead of returning |
| the strings to the caller, it writes the strings to the file descriptor |
| <VAR>fd</VAR>, one per line. It does not use the <CODE>malloc</CODE> function, and |
| can therefore be used in situations where that function might fail. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-ctermid" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="char *string"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>ctermid</CODE> function returns a string containing the file name of |
| the controlling terminal for the current process. If <VAR>string</VAR> is |
| not a null pointer, it should be an array that can hold at least |
| <CODE>L_ctermid</CODE> characters; the string is returned in this array. |
| Otherwise, a pointer to a string in a static area is returned, which |
| might get overwritten on subsequent calls to this function. |
| <br><br> An empty string is returned if the file name cannot be determined for |
| any reason. Even if a file name is returned, access to the file it |
| represents is not guaranteed. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-setsid" type="function"> |
| <function returntype="pid_t"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>setsid</CODE> function creates a new session. The calling process |
| becomes the session leader, and is put in a new process group whose |
| process group ID is the same as the process ID of that process. There |
| are initially no other processes in the new process group, and no other |
| process groups in the new session. |
| <br><br> This function also makes the calling process have no controlling terminal. |
| <br><br> The <CODE>setsid</CODE> function returns the new process group ID of the |
| calling process if successful. A return value of <CODE>-1</CODE> indicates an |
| error. The following <CODE>errno</CODE> error conditions are defined for this |
| function: |
| <br><br> <DL> |
| |
| <DT><CODE>EPERM</CODE> |
| <DD> |
| The calling process is already a process group leader, or there is |
| already another process group around that has the same process group ID. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getsid" type="function"> |
| <function returntype="pid_t"> |
| <prototype> |
| <parameter content="pid_t pid"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| <br><br> The <CODE>getsid</CODE> function returns the process group ID of the session |
| leader of the specified process. If a <VAR>pid</VAR> is <CODE>0</CODE>, the |
| process group ID of the session leader of the current process is |
| returned. |
| <br><br> In case of error <CODE>-1</CODE> is returned and <CODE>errno</CODE> is set. The |
| following <CODE>errno</CODE> error conditions are defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>ESRCH</CODE> |
| <DD> |
| There is no process with the given process ID <VAR>pid</VAR>. |
| <LI> EPERM |
| The calling process and the process specified by <VAR>pid</VAR> are in |
| different sessions, and the implementation doesn't allow to access the |
| process group ID of the session leader of the process with ID <VAR>pid</VAR> |
| from the calling process. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-setpgid" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="pid_t pid"/> |
| <parameter content="pid_t pgid"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>setpgid</CODE> function puts the process <VAR>pid</VAR> into the process |
| group <VAR>pgid</VAR>. As a special case, either <VAR>pid</VAR> or <VAR>pgid</VAR> can |
| be zero to indicate the process ID of the calling process. |
| <br><br> This function fails on a system that does not support job control. |
| , for more information. |
| <br><br> If the operation is successful, <CODE>setpgid</CODE> returns zero. Otherwise |
| it returns <CODE>-1</CODE>. The following <CODE>errno</CODE> error conditions are |
| defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EACCES</CODE> |
| <DD> |
| The child process named by <VAR>pid</VAR> has executed an <CODE>exec</CODE> |
| function since it was forked. |
| <br><br> <LI> EINVAL |
| The value of the <VAR>pgid</VAR> is not valid. |
| <br><br> <LI> ENOSYS |
| The system doesn't support job control. |
| <br><br> <LI> EPERM |
| The process indicated by the <VAR>pid</VAR> argument is a session leader, |
| or is not in the same session as the calling process, or the value of |
| the <VAR>pgid</VAR> argument doesn't match a process group ID in the same |
| session as the calling process. |
| <br><br> <LI> ESRCH |
| The process indicated by the <VAR>pid</VAR> argument is not the calling |
| process or a child of the calling process. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-setpgrp" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="pid_t pid"/> |
| <parameter content="pid_t pgid"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| This is the BSD Unix name for <CODE>setpgid</CODE>. Both functions do exactly |
| the same thing. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-tcgetpgrp" type="function"> |
| <function returntype="pid_t"> |
| <prototype> |
| <parameter content="int filedes"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| This function returns the process group ID of the foreground process |
| group associated with the terminal open on descriptor <VAR>filedes</VAR>. |
| <br><br> If there is no foreground process group, the return value is a number |
| greater than <CODE>1</CODE> that does not match the process group ID of any |
| existing process group. This can happen if all of the processes in the |
| job that was formerly the foreground job have terminated, and no other |
| job has yet been moved into the foreground. |
| <br><br> In case of an error, a value of <CODE>-1</CODE> is returned. The |
| following <CODE>errno</CODE> error conditions are defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EBADF</CODE> |
| <DD> |
| The <VAR>filedes</VAR> argument is not a valid file descriptor. |
| <br><br> <LI> ENOSYS |
| The system doesn't support job control. |
| <br><br> <LI> ENOTTY |
| The terminal file associated with the <VAR>filedes</VAR> argument isn't the |
| controlling terminal of the calling process. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-tcsetpgrp" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int filedes"/> |
| <parameter content="pid_t pgid"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| This function is used to set a terminal's foreground process group ID. |
| The argument <VAR>filedes</VAR> is a descriptor which specifies the terminal; |
| <VAR>pgid</VAR> specifies the process group. The calling process must be a |
| member of the same session as <VAR>pgid</VAR> and must have the same |
| controlling terminal. |
| <br><br> For terminal access purposes, this function is treated as output. If it |
| is called from a background process on its controlling terminal, |
| normally all processes in the process group are sent a <CODE>SIGTTOU</CODE> |
| signal. The exception is if the calling process itself is ignoring or |
| blocking <CODE>SIGTTOU</CODE> signals, in which case the operation is |
| performed and no signal is sent. |
| <br><br> If successful, <CODE>tcsetpgrp</CODE> returns <CODE>0</CODE>. A return value of |
| <CODE>-1</CODE> indicates an error. The following <CODE>errno</CODE> error |
| conditions are defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EBADF</CODE> |
| <DD> |
| The <VAR>filedes</VAR> argument is not a valid file descriptor. |
| <br><br> <LI> EINVAL |
| The <VAR>pgid</VAR> argument is not valid. |
| <br><br> <LI> ENOSYS |
| The system doesn't support job control. |
| <br><br> <LI> ENOTTY |
| The <VAR>filedes</VAR> isn't the controlling terminal of the calling process. |
| <br><br> <LI> EPERM |
| The <VAR>pgid</VAR> isn't a process group in the same session as the calling |
| process. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-tcgetsid" type="function"> |
| <function returntype="pid_t"> |
| <prototype> |
| <parameter content="int fildes"/> |
| </prototype> |
| <headers> |
| <header filename = "termios.h"/> |
| </headers> |
| <synopsis> |
| This function is used to obtain the process group ID of the session |
| for which the terminal specified by <VAR>fildes</VAR> is the controlling terminal. |
| If the call is successful the group ID is returned. Otherwise the |
| return value is <CODE>(pid_t) -1</CODE> and the global variable <VAR>errno</VAR> |
| is set to the following value: |
| <DL> |
| |
| <DT><CODE>EBADF</CODE> |
| <DD> |
| The <VAR>filedes</VAR> argument is not a valid file descriptor. |
| <br><br> <LI> ENOTTY |
| The calling process does not have a controlling terminal, or the file |
| is not the controlling terminal. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-islower" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int c"/> |
| </prototype> |
| <headers> |
| <header filename = "ctype.h"/> |
| </headers> |
| <synopsis> |
| Returns true if <VAR>c</VAR> is a lower-case letter. The letter need not be |
| from the Latin alphabet, any alphabet representable is valid. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-isupper" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int c"/> |
| </prototype> |
| <headers> |
| <header filename = "ctype.h"/> |
| </headers> |
| <synopsis> |
| Returns true if <VAR>c</VAR> is an upper-case letter. The letter need not be |
| from the Latin alphabet, any alphabet representable is valid. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-isalpha" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int c"/> |
| </prototype> |
| <headers> |
| <header filename = "ctype.h"/> |
| </headers> |
| <synopsis> |
| Returns true if <VAR>c</VAR> is an alphabetic character (a letter). If |
| <CODE>islower</CODE> or <CODE>isupper</CODE> is true of a character, then |
| <CODE>isalpha</CODE> is also true. |
| <br><br> In some locales, there may be additional characters for which |
| <CODE>isalpha</CODE> is true---letters which are neither upper case nor lower |
| case. But in the standard <CODE>"C"</CODE> locale, there are no such |
| additional characters. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-isdigit" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int c"/> |
| </prototype> |
| <headers> |
| <header filename = "ctype.h"/> |
| </headers> |
| <synopsis> |
| Returns true if <VAR>c</VAR> is a decimal digit (<samp>0</samp> through <samp>9</samp>). |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-isalnum" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int c"/> |
| </prototype> |
| <headers> |
| <header filename = "ctype.h"/> |
| </headers> |
| <synopsis> |
| Returns true if <VAR>c</VAR> is an alphanumeric character (a letter or |
| number); in other words, if either <CODE>isalpha</CODE> or <CODE>isdigit</CODE> is |
| true of a character, then <CODE>isalnum</CODE> is also true. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-isxdigit" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int c"/> |
| </prototype> |
| <headers> |
| <header filename = "ctype.h"/> |
| </headers> |
| <synopsis> |
| Returns true if <VAR>c</VAR> is a hexadecimal digit. |
| Hexadecimal digits include the normal decimal digits <samp>0</samp> through |
| <samp>9</samp> and the letters <samp>A</samp> through <samp>F</samp> and |
| <samp>a</samp> through <samp>f</samp>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-ispunct" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int c"/> |
| </prototype> |
| <headers> |
| <header filename = "ctype.h"/> |
| </headers> |
| <synopsis> |
| Returns true if <VAR>c</VAR> is a punctuation character. |
| This means any printing character that is not alphanumeric or a space |
| character. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-isspace" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int c"/> |
| </prototype> |
| <headers> |
| <header filename = "ctype.h"/> |
| </headers> |
| <synopsis> |
| Returns true if <VAR>c</VAR> is a whitespace character. In the standard |
| <CODE>"C"</CODE> locale, <CODE>isspace</CODE> returns true for only the standard |
| whitespace characters: |
| <br><br> <DL> |
| |
| <DT><CODE>' '</CODE> |
| <DD> |
| space |
| <br><br> <LI> '\f' |
| formfeed |
| <br><br> <LI> '\n' |
| newline |
| <br><br> <LI> '\r' |
| carriage return |
| <br><br> <LI> '\t' |
| horizontal tab |
| <br><br> <LI> '\v' |
| vertical tab |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-isblank" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int c"/> |
| </prototype> |
| <headers> |
| <header filename = "ctype.h"/> |
| </headers> |
| <synopsis> |
| Returns true if <VAR>c</VAR> is a blank character; that is, a space or a tab. |
| This function was originally a GNU extension, but was added in ISO C99. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-isgraph" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int c"/> |
| </prototype> |
| <headers> |
| <header filename = "ctype.h"/> |
| </headers> |
| <synopsis> |
| Returns true if <VAR>c</VAR> is a graphic character; that is, a character |
| that has a glyph associated with it. The whitespace characters are not |
| considered graphic. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-isprint" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int c"/> |
| </prototype> |
| <headers> |
| <header filename = "ctype.h"/> |
| </headers> |
| <synopsis> |
| Returns true if <VAR>c</VAR> is a printing character. Printing characters |
| include all the graphic characters, plus the space (<samp> </samp>) character. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-iscntrl" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int c"/> |
| </prototype> |
| <headers> |
| <header filename = "ctype.h"/> |
| </headers> |
| <synopsis> |
| Returns true if <VAR>c</VAR> is a control character (that is, a character that |
| is not a printing character). |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-isascii" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int c"/> |
| </prototype> |
| <headers> |
| <header filename = "ctype.h"/> |
| </headers> |
| <synopsis> |
| Returns true if <VAR>c</VAR> is a 7-bit <CODE>unsigned char</CODE> value that fits |
| into the US/UK ASCII character set. This function is a BSD extension |
| and is also an SVID extension. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-tolower" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int c"/> |
| </prototype> |
| <headers> |
| <header filename = "ctype.h"/> |
| </headers> |
| <synopsis> |
| If <VAR>c</VAR> is an upper-case letter, <CODE>tolower</CODE> returns the corresponding |
| lower-case letter. If <VAR>c</VAR> is not an upper-case letter, |
| <VAR>c</VAR> is returned unchanged. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-toupper" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int c"/> |
| </prototype> |
| <headers> |
| <header filename = "ctype.h"/> |
| </headers> |
| <synopsis> |
| If <VAR>c</VAR> is a lower-case letter, <CODE>toupper</CODE> returns the corresponding |
| upper-case letter. Otherwise <VAR>c</VAR> is returned unchanged. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-toascii" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int c"/> |
| </prototype> |
| <headers> |
| <header filename = "ctype.h"/> |
| </headers> |
| <synopsis> |
| This function converts <VAR>c</VAR> to a 7-bit <CODE>unsigned char</CODE> value |
| that fits into the US/UK ASCII character set, by clearing the high-order |
| bits. This function is a BSD extension and is also an SVID extension. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-_tolower" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int c"/> |
| </prototype> |
| <headers> |
| <header filename = "ctype.h"/> |
| </headers> |
| <synopsis> |
| This is identical to <CODE>tolower</CODE>, and is provided for compatibility |
| with the SVID. . |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-_toupper" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int c"/> |
| </prototype> |
| <headers> |
| <header filename = "ctype.h"/> |
| </headers> |
| <synopsis> |
| This is identical to <CODE>toupper</CODE>, and is provided for compatibility |
| with the SVID. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="dtype-wctype_t" type="dtype"> |
| <structure> |
| </structure> |
| </construct> |
| <construct id="function-wctype" type="function"> |
| <function returntype="wctype_t"> |
| <prototype> |
| <parameter content="const char *property"/> |
| </prototype> |
| <headers> |
| <header filename = "wctype.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>wctype</CODE> returns a value representing a class of wide |
| characters which is identified by the string <VAR>property</VAR>. Beside |
| some standard properties each locale can define its own ones. In case |
| no property with the given name is known for the current locale |
| selected for the <CODE>LC_CTYPE</CODE> category, the function returns zero. |
| <br><br> |
| The properties known in every locale are: |
| <br><br> <DT><pre></pre> |
| <DD><br> |
| <br><br> This function is declared in <TT>wctype.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-iswctype" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="wint_t wc"/> |
| <parameter content="wctype_t desc"/> |
| </prototype> |
| <headers> |
| <header filename = "wctype.h"/> |
| </headers> |
| <synopsis> |
| This function returns a nonzero value if <VAR>wc</VAR> is in the character |
| class specified by <VAR>desc</VAR>. <VAR>desc</VAR> must previously be returned |
| by a successful call to <CODE>wctype</CODE>. |
| <br><br> This function is declared in <TT>wctype.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-iswalnum" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="wint_t wc"/> |
| </prototype> |
| <headers> |
| <header filename = "wctype.h"/> |
| </headers> |
| <synopsis> |
| This function returns a nonzero value if <VAR>wc</VAR> is an alphanumeric |
| character (a letter or number); in other words, if either <CODE>iswalpha</CODE> |
| or <CODE>iswdigit</CODE> is true of a character, then <CODE>iswalnum</CODE> is also |
| true. |
| <br><br> |
| This function can be implemented using |
| <br><br> <pre><br> |
| iswctype (wc, wctype ("alnum"))<br> |
| </pre> |
| <br><br> It is declared in <TT>wctype.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-iswalpha" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="wint_t wc"/> |
| </prototype> |
| <headers> |
| <header filename = "wctype.h"/> |
| </headers> |
| <synopsis> |
| Returns true if <VAR>wc</VAR> is an alphabetic character (a letter). If |
| <CODE>iswlower</CODE> or <CODE>iswupper</CODE> is true of a character, then |
| <CODE>iswalpha</CODE> is also true. |
| <br><br> In some locales, there may be additional characters for which |
| <CODE>iswalpha</CODE> is true---letters which are neither upper case nor lower |
| case. But in the standard <CODE>"C"</CODE> locale, there are no such |
| additional characters. |
| <br><br> |
| This function can be implemented using |
| <br><br> <pre><br> |
| iswctype (wc, wctype ("alpha"))<br> |
| </pre> |
| <br><br> It is declared in <TT>wctype.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-iswcntrl" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="wint_t wc"/> |
| </prototype> |
| <headers> |
| <header filename = "wctype.h"/> |
| </headers> |
| <synopsis> |
| Returns true if <VAR>wc</VAR> is a control character (that is, a character that |
| is not a printing character). |
| <br><br> |
| This function can be implemented using |
| <br><br> <pre><br> |
| iswctype (wc, wctype ("cntrl"))<br> |
| </pre> |
| <br><br> It is declared in <TT>wctype.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-iswdigit" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="wint_t wc"/> |
| </prototype> |
| <headers> |
| <header filename = "wctype.h"/> |
| </headers> |
| <synopsis> |
| Returns true if <VAR>wc</VAR> is a digit (e.g., <samp>0</samp> through <samp>9</samp>). |
| Please note that this function does not only return a nonzero value for |
| <EM>decimal</EM> digits, but for all kinds of digits. A consequence is |
| that code like the following will <h3>not</h3> work unconditionally for |
| wide characters: |
| <br><br> <pre><br> |
| n = 0;<br> |
| while (iswdigit (*wc))<br> |
| {<br> |
| n *= 10;<br> |
| n += *wc++ - L'0';<br> |
| }<br> |
| </pre><br> |
| <br><br> <br> |
| This function can be implemented using<br> |
| <br><br> <pre><br> |
| iswctype (wc, wctype ("digit"))<br> |
| </pre> |
| <br><br> It is declared in <TT>wctype.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-iswgraph" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="wint_t wc"/> |
| </prototype> |
| <headers> |
| <header filename = "wctype.h"/> |
| </headers> |
| <synopsis> |
| Returns true if <VAR>wc</VAR> is a graphic character; that is, a character |
| that has a glyph associated with it. The whitespace characters are not |
| considered graphic. |
| <br><br> |
| This function can be implemented using |
| <br><br> <pre><br> |
| iswctype (wc, wctype ("graph"))<br> |
| </pre> |
| <br><br> It is declared in <TT>wctype.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-iswlower" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="wint_t wc"/> |
| </prototype> |
| <headers> |
| <header filename = "ctype.h"/> |
| </headers> |
| <synopsis> |
| Returns true if <VAR>wc</VAR> is a lower-case letter. The letter need not be |
| from the Latin alphabet, any alphabet representable is valid. |
| <br><br> |
| This function can be implemented using |
| <br><br> <pre><br> |
| iswctype (wc, wctype ("lower"))<br> |
| </pre> |
| <br><br> It is declared in <TT>wctype.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-iswprint" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="wint_t wc"/> |
| </prototype> |
| <headers> |
| <header filename = "wctype.h"/> |
| </headers> |
| <synopsis> |
| Returns true if <VAR>wc</VAR> is a printing character. Printing characters |
| include all the graphic characters, plus the space (<samp> </samp>) character. |
| <br><br> |
| This function can be implemented using |
| <br><br> <pre><br> |
| iswctype (wc, wctype ("print"))<br> |
| </pre> |
| <br><br> It is declared in <TT>wctype.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-iswpunct" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="wint_t wc"/> |
| </prototype> |
| <headers> |
| <header filename = "wctype.h"/> |
| </headers> |
| <synopsis> |
| Returns true if <VAR>wc</VAR> is a punctuation character. |
| This means any printing character that is not alphanumeric or a space |
| character. |
| <br><br> |
| This function can be implemented using |
| <br><br> <pre><br> |
| iswctype (wc, wctype ("punct"))<br> |
| </pre> |
| <br><br> It is declared in <TT>wctype.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-iswspace" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="wint_t wc"/> |
| </prototype> |
| <headers> |
| <header filename = "wctype.h"/> |
| </headers> |
| <synopsis> |
| Returns true if <VAR>wc</VAR> is a whitespace character. In the standard |
| <CODE>"C"</CODE> locale, <CODE>iswspace</CODE> returns true for only the standard |
| whitespace characters: |
| <br><br> <DL> |
| |
| <DT><CODE>L' '</CODE> |
| <DD> |
| space |
| <br><br> <LI> L'\f' |
| formfeed |
| <br><br> <LI> L'\n' |
| newline |
| <br><br> <LI> L'\r' |
| carriage return |
| <br><br> <LI> L'\t' |
| horizontal tab |
| <br><br> <LI> L'\v' |
| vertical tab |
| |
| <br><br> |
| This function can be implemented using |
| <br><br> <pre><br> |
| iswctype (wc, wctype ("space"))<br> |
| </pre> |
| <br><br> It is declared in <TT>wctype.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-iswupper" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="wint_t wc"/> |
| </prototype> |
| <headers> |
| <header filename = "wctype.h"/> |
| </headers> |
| <synopsis> |
| Returns true if <VAR>wc</VAR> is an upper-case letter. The letter need not be |
| from the Latin alphabet, any alphabet representable is valid. |
| <br><br> |
| This function can be implemented using |
| <br><br> <pre><br> |
| iswctype (wc, wctype ("upper"))<br> |
| </pre> |
| <br><br> It is declared in <TT>wctype.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-iswxdigit" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="wint_t wc"/> |
| </prototype> |
| <headers> |
| <header filename = "wctype.h"/> |
| </headers> |
| <synopsis> |
| Returns true if <VAR>wc</VAR> is a hexadecimal digit. |
| Hexadecimal digits include the normal decimal digits <samp>0</samp> through |
| <samp>9</samp> and the letters <samp>A</samp> through <samp>F</samp> and |
| <samp>a</samp> through <samp>f</samp>. |
| <br><br> |
| This function can be implemented using |
| <br><br> <pre><br> |
| iswctype (wc, wctype ("xdigit"))<br> |
| </pre> |
| <br><br> It is declared in <TT>wctype.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-iswblank" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="wint_t wc"/> |
| </prototype> |
| <headers> |
| <header filename = "wctype.h"/> |
| </headers> |
| <synopsis> |
| Returns true if <VAR>wc</VAR> is a blank character; that is, a space or a tab. |
| This function was originally a GNU extension, but was added in ISO C99. |
| It is declared in <TT>wchar.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="dtype-wctrans_t" type="dtype"> |
| <structure> |
| </structure> |
| </construct> |
| <construct id="function-wctrans" type="function"> |
| <function returntype="wctrans_t"> |
| <prototype> |
| <parameter content="const char *property"/> |
| </prototype> |
| <headers> |
| <header filename = "wctype.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>wctrans</CODE> function has to be used to find out whether a named |
| mapping is defined in the current locale selected for the |
| <CODE>LC_CTYPE</CODE> category. If the returned value is non-zero, you can use |
| it afterwards in calls to <CODE>towctrans</CODE>. If the return value is |
| zero no such mapping is known in the current locale. |
| <br><br> Beside locale-specific mappings there are two mappings which are |
| guaranteed to be available in every locale: |
| <br><br> <DT><pre></pre> |
| <DD><br> |
| <br><br> |
| These functions are declared in <TT>wctype.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-towctrans" type="function"> |
| <function returntype="wint_t"> |
| <prototype> |
| <parameter content="wint_t wc"/> |
| <parameter content="wctrans_t desc"/> |
| </prototype> |
| <headers> |
| <header filename = "wctype.h"/> |
| </headers> |
| <synopsis> |
| <CODE>towctrans</CODE> maps the input character <VAR>wc</VAR> |
| according to the rules of the mapping for which <VAR>desc</VAR> is a |
| descriptor, and returns the value it finds. <VAR>desc</VAR> must be |
| obtained by a successful call to <CODE>wctrans</CODE>. |
| <br><br> |
| This function is declared in <TT>wctype.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-towlower" type="function"> |
| <function returntype="wint_t"> |
| <prototype> |
| <parameter content="wint_t wc"/> |
| </prototype> |
| <headers> |
| <header filename = "wctype.h"/> |
| </headers> |
| <synopsis> |
| If <VAR>wc</VAR> is an upper-case letter, <CODE>towlower</CODE> returns the corresponding |
| lower-case letter. If <VAR>wc</VAR> is not an upper-case letter, |
| <VAR>wc</VAR> is returned unchanged. |
| <br><br> |
| <CODE>towlower</CODE> can be implemented using |
| <br><br> <pre><br> |
| towctrans (wc, wctrans ("tolower"))<br> |
| </pre> |
| <br><br> |
| This function is declared in <TT>wctype.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-towupper" type="function"> |
| <function returntype="wint_t"> |
| <prototype> |
| <parameter content="wint_t wc"/> |
| </prototype> |
| <headers> |
| <header filename = "wctype.h"/> |
| </headers> |
| <synopsis> |
| If <VAR>wc</VAR> is a lower-case letter, <CODE>towupper</CODE> returns the corresponding |
| upper-case letter. Otherwise <VAR>wc</VAR> is returned unchanged. |
| <br><br> |
| <CODE>towupper</CODE> can be implemented using |
| <br><br> <pre><br> |
| towctrans (wc, wctrans ("toupper"))<br> |
| </pre> |
| <br><br> |
| This function is declared in <TT>wctype.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-catopen" type="function"> |
| <function returntype="nl_catd"> |
| <prototype> |
| <parameter content="const char *cat_name"/> |
| <parameter content="int flag"/> |
| </prototype> |
| <headers> |
| <header filename = "nl_types.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>catgets</CODE> function tries to locate the message data file names |
| <VAR>cat_name</VAR> and loads it when found. The return value is of an |
| opaque type and can be used in calls to the other functions to refer to |
| this loaded catalog. |
| <br><br> The return value is <CODE>(nl_catd) -1</CODE> in case the function failed and |
| no catalog was loaded. The global variable <VAR>errno</VAR> contains a code |
| for the error causing the failure. But even if the function call |
| succeeded this does not mean that all messages can be translated. |
| <br><br> Locating the catalog file must happen in a way which lets the user of |
| the program influence the decision. It is up to the user to decide |
| about the language to use and sometimes it is useful to use alternate |
| catalog files. All this can be specified by the user by setting some |
| environment variables. |
| <br><br> The first problem is to find out where all the message catalogs are |
| stored. Every program could have its own place to keep all the |
| different files but usually the catalog files are grouped by languages |
| and the catalogs for all programs are kept in the same place. |
| <br><br> environment variable |
| To tell the <CODE>catopen</CODE> function where the catalog for the program |
| can be found the user can set the environment variable <CODE>NLSPATH</CODE> to |
| a value which describes her/his choice. Since this value must be usable |
| for different languages and locales it cannot be a simple string. |
| Instead it is a format string (similar to <CODE>printf</CODE>'s). An example |
| is |
| <br><br> <pre><br> |
| /usr/share/locale/%L/%N:/usr/share/locale/%L/LC_MESSAGES/%N<br> |
| </pre><br> |
| <br><br> First one can see that more than one directory can be specified (with<br> |
| the usual syntax of separating them by colons). The next things to<br> |
| observe are the format string, <CODE>%L</CODE> and <CODE>%N</CODE> in this case.<br> |
| The <CODE>catopen</CODE> function knows about several of them and the<br> |
| replacement for all of them is of course different.<br> |
| <br><br> <DL> |
| <br> |
| <DT><CODE>%N<br></CODE> |
| <DD> |
| This format element is substituted with the name of the catalog file.<br> |
| This is the value of the <VAR>cat_name</VAR> argument given to<br> |
| <CODE>catgets</CODE>.<br> |
| <br><br> <DT><CODE>%L<br></CODE> |
| <DD> |
| This format element is substituted with the name of the currently<br> |
| selected locale for translating messages. How this is determined is<br> |
| explained below.<br> |
| <br><br> <LI> %l<br> |
| (This is the lowercase ell.) This format element is substituted with the<br> |
| language element of the locale name. The string describing the selected<br> |
| locale is expected to have the form<br> |
| <CODE><VAR>lang</VAR>[_<VAR>terr</VAR>[.<VAR>codeset</VAR>]]</CODE> and this format uses the<br> |
| first part <VAR>lang</VAR>.<br> |
| <br><br> <LI> %t<br> |
| This format element is substituted by the territory part <VAR>terr</VAR> of<br> |
| the name of the currently selected locale. See the explanation of the<br> |
| format above.<br> |
| <br><br> <LI> %c<br> |
| This format element is substituted by the codeset part <VAR>codeset</VAR> of<br> |
| the name of the currently selected locale. See the explanation of the<br> |
| format above.<br> |
| <br><br> <LI> %%<br> |
| Since <CODE>%</CODE> is used in a meta character there must be a way to<br> |
| express the <CODE>%</CODE> character in the result itself. Using <CODE>%%</CODE><br> |
| does this just like it works for <CODE>printf</CODE>.<br> |
| <br> |
| <br><br> <br><br> Using <CODE>NLSPATH</CODE> allows arbitrary directories to be searched for<br> |
| message catalogs while still allowing different languages to be used.<br> |
| If the <CODE>NLSPATH</CODE> environment variable is not set, the default value<br> |
| is<br> |
| <br><br> <pre><br> |
| <VAR>prefix</VAR>/share/locale/%L/%N:<VAR>prefix</VAR>/share/locale/%L/LC_MESSAGES/%N<br> |
| </pre><br> |
| <br><br> <br> |
| where <VAR>prefix</VAR> is given to <CODE>configure</CODE> while installing the GNU<br> |
| C Library (this value is in many cases <CODE>/usr</CODE> or the empty string).<br> |
| <br><br> The remaining problem is to decide which must be used. The value<br> |
| decides about the substitution of the format elements mentioned above.<br> |
| First of all the user can specify a path in the message catalog name<br> |
| (i.e., the name contains a slash character). In this situation the<br> |
| <CODE>NLSPATH</CODE> environment variable is not used. The catalog must exist<br> |
| as specified in the program, perhaps relative to the current working<br> |
| directory. This situation in not desirable and catalogs names never<br> |
| should be written this way. Beside this, this behavior is not portable<br> |
| to all other platforms providing the <CODE>catgets</CODE> interface.<br> |
| <br><br> environment variable<br> |
| environment variable<br> |
| environment variable<br> |
| Otherwise the values of environment variables from the standard<br> |
| environment are examined. Which<br> |
| variables are examined is decided by the <VAR>flag</VAR> parameter of<br> |
| <CODE>catopen</CODE>. If the value is <CODE>NL_CAT_LOCALE</CODE> (which is defined<br> |
| in <TT>nl_types.h</TT>) then the <CODE>catopen</CODE> function use the name of<br> |
| the locale currently selected for the <CODE>LC_MESSAGES</CODE> category.<br> |
| <br><br> If <VAR>flag</VAR> is zero the <CODE>LANG</CODE> environment variable is examined.<br> |
| This is a left-over from the early days where the concept of the locales<br> |
| had not even reached the level of POSIX locales.<br> |
| <br><br> The environment variable and the locale name should have a value of the<br> |
| form <CODE><VAR>lang</VAR>[_<VAR>terr</VAR>[.<VAR>codeset</VAR>]]</CODE> as explained above.<br> |
| If no environment variable is set the <CODE>"C"</CODE> locale is used which<br> |
| prevents any translation.<br> |
| <br><br> The return value of the function is in any case a valid string. Either<br> |
| it is a translation from a message catalog or it is the same as the<br> |
| <VAR>string</VAR> parameter. So a piece of code to decide whether a<br> |
| translation actually happened must look like this:<br> |
| <br><br> <pre><br> |
| {<br> |
| char *trans = catgets (desc, set, msg, input_string);<br> |
| if (trans == input_string)<br> |
| {<br> |
| /* Something went wrong. */<br> |
| }<br> |
| }<br> |
| </pre> |
| <br><br> |
| When an error occurred the global variable <VAR>errno</VAR> is set to |
| <br><br> <DL> |
| |
| <LI> EBADF |
| The catalog does not exist. |
| <LI> ENOMSG |
| The set/message tuple does not name an existing element in the |
| message catalog. |
| |
| <br><br> While it sometimes can be useful to test for errors programs normally |
| will avoid any test. If the translation is not available it is no big |
| problem if the original, untranslated message is printed. Either the |
| user understands this as well or s/he will look for the reason why the |
| messages are not translated. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-catgets" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="nl_catd catalog_desc"/> |
| <parameter content="int set"/> |
| <parameter content="int message"/> |
| <parameter content="const char *string"/> |
| </prototype> |
| <synopsis> |
| The function <CODE>catgets</CODE> has to be used to access the massage catalog |
| previously opened using the <CODE>catopen</CODE> function. The |
| <VAR>catalog_desc</VAR> parameter must be a value previously returned by |
| <CODE>catopen</CODE>. |
| <br><br> The next two parameters, <VAR>set</VAR> and <VAR>message</VAR>, reflect the |
| internal organization of the message catalog files. This will be |
| explained in detail below. For now it is interesting to know that a |
| catalog can consists of several set and the messages in each thread are |
| individually numbered using numbers. Neither the set number nor the |
| message number must be consecutive. They can be arbitrarily chosen. |
| But each message (unless equal to another one) must have its own unique |
| pair of set and message number. |
| <br><br> Since it is not guaranteed that the message catalog for the language |
| selected by the user exists the last parameter <VAR>string</VAR> helps to |
| handle this case gracefully. If no matching string can be found |
| <VAR>string</VAR> is returned. This means for the programmer that |
| <br><br> <OL> |
| <LI> |
| the <VAR>string</VAR> parameters should contain reasonable text (this also |
| helps to understand the program seems otherwise there would be no hint |
| on the string which is expected to be returned. |
| <LI> |
| all <VAR>string</VAR> arguments should be written in the same language. |
| </OL> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-catclose" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="nl_catd catalog_desc"/> |
| </prototype> |
| <synopsis> |
| The <CODE>catclose</CODE> function can be used to free the resources |
| associated with a message catalog which previously was opened by a call |
| to <CODE>catopen</CODE>. If the resources can be successfully freed the |
| function returns <CODE>0</CODE>. Otherwise it return <CODE></CODE>1 and the |
| global variable <VAR>errno</VAR> is set. Errors can occur if the catalog |
| descriptor <VAR>catalog_desc</VAR> is not valid in which case <VAR>errno</VAR> is |
| set to <CODE>EBADF</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-gettext" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="const char *msgid"/> |
| </prototype> |
| <headers> |
| <header filename = "libintl.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>gettext</CODE> function searches the currently selected message |
| catalogs for a string which is equal to <VAR>msgid</VAR>. If there is such a |
| string available it is returned. Otherwise the argument string |
| <VAR>msgid</VAR> is returned. |
| <br><br> Please note that all though the return value is <CODE>char *</CODE> the |
| returned string must not be changed. This broken type results from the |
| history of the function and does not reflect the way the function should |
| be used. |
| <br><br> Please note that above we wrote ``message catalogs'' (plural). This is |
| a specialty of the GNU implementation of these functions and we will |
| say more about this when we talk about the ways message catalogs are |
| selected . |
| <br><br> The <CODE>gettext</CODE> function does not modify the value of the global |
| <VAR>errno</VAR> variable. This is necessary to make it possible to write |
| something like |
| <br><br> <pre><br> |
| printf (gettext ("Operation failed: %m\n"));<br> |
| </pre> |
| <br><br> Here the <VAR>errno</VAR> value is used in the <CODE>printf</CODE> function while |
| processing the <CODE>%m</CODE> format element and if the <CODE>gettext</CODE> |
| function would change this value (it is called before <CODE>printf</CODE> is |
| called) we would get a wrong message. |
| <br><br> So there is no easy way to detect a missing message catalog beside |
| comparing the argument string with the result. But it is normally the |
| task of the user to react on missing catalogs. The program cannot guess |
| when a message catalog is really necessary since for a user who speaks |
| the language the program was developed in does not need any translation. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-dgettext" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="const char *domainname"/> |
| <parameter content="const char *msgid"/> |
| </prototype> |
| <headers> |
| <header filename = "libintl.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>dgettext</CODE> functions acts just like the <CODE>gettext</CODE> |
| function. It only takes an additional first argument <VAR>domainname</VAR> |
| which guides the selection of the message catalogs which are searched |
| for the translation. If the <VAR>domainname</VAR> parameter is the null |
| pointer the <CODE>dgettext</CODE> function is exactly equivalent to |
| <CODE>gettext</CODE> since the default value for the domain name is used. |
| <br><br> As for <CODE>gettext</CODE> the return value type is <CODE>char *</CODE> which is an |
| anachronism. The returned string must never be modified. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-dcgettext" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="const char *domainname"/> |
| <parameter content="const char *msgid"/> |
| <parameter content="int category"/> |
| </prototype> |
| <headers> |
| <header filename = "libintl.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>dcgettext</CODE> adds another argument to those which |
| <CODE>dgettext</CODE> takes. This argument <VAR>category</VAR> specifies the last |
| piece of information needed to localize the message catalog. I.e., the |
| domain name and the locale category exactly specify which message |
| catalog has to be used (relative to a given directory, see below). |
| <br><br> The <CODE>dgettext</CODE> function can be expressed in terms of |
| <CODE>dcgettext</CODE> by using |
| <br><br> <pre><br> |
| dcgettext (domain, string, LC_MESSAGES)<br> |
| </pre><br> |
| <br><br> <br> |
| instead of<br> |
| <br><br> <pre><br> |
| dgettext (domain, string)<br> |
| </pre> |
| <br><br> This also shows which values are expected for the third parameter. One |
| has to use the available selectors for the categories available in |
| <TT>locale.h</TT>. Normally the available values are <CODE>LC_CTYPE</CODE>, |
| <CODE>LC_COLLATE</CODE>, <CODE>LC_MESSAGES</CODE>, <CODE>LC_MONETARY</CODE>, |
| <CODE>LC_NUMERIC</CODE>, and <CODE>LC_TIME</CODE>. Please note that <CODE>LC_ALL</CODE> |
| must not be used and even though the names might suggest this, there is |
| no relation to the environments variables of this name. |
| <br><br> The <CODE>dcgettext</CODE> function is only implemented for compatibility with |
| other systems which have <CODE>gettext</CODE> functions. There is not really |
| any situation where it is necessary (or useful) to use a different value |
| but <CODE>LC_MESSAGES</CODE> in for the <VAR>category</VAR> parameter. We are |
| dealing with messages here and any other choice can only be irritating. |
| <br><br> As for <CODE>gettext</CODE> the return value type is <CODE>char *</CODE> which is an |
| anachronism. The returned string must never be modified. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-textdomain" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="const char *domainname"/> |
| </prototype> |
| <headers> |
| <header filename = "libintl.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>textdomain</CODE> function sets the default domain, which is used in |
| all future <CODE>gettext</CODE> calls, to <VAR>domainname</VAR>. Please note that |
| <CODE>dgettext</CODE> and <CODE>dcgettext</CODE> calls are not influenced if the |
| <VAR>domainname</VAR> parameter of these functions is not the null pointer. |
| <br><br> Before the first call to <CODE>textdomain</CODE> the default domain is |
| <CODE>messages</CODE>. This is the name specified in the specification of |
| the <CODE>gettext</CODE> API. This name is as good as any other name. No |
| program should ever really use a domain with this name since this can |
| only lead to problems. |
| <br><br> The function returns the value which is from now on taken as the default |
| domain. If the system went out of memory the returned value is |
| <CODE>NULL</CODE> and the global variable <VAR>errno</VAR> is set to <CODE>ENOMEM</CODE>. |
| Despite the return value type being <CODE>char *</CODE> the return string must |
| not be changed. It is allocated internally by the <CODE>textdomain</CODE> |
| function. |
| <br><br> If the <VAR>domainname</VAR> parameter is the null pointer no new default |
| domain is set. Instead the currently selected default domain is |
| returned. |
| <br><br> If the <VAR>domainname</VAR> parameter is the empty string the default domain |
| is reset to its initial value, the domain with the name <CODE>messages</CODE>. |
| This possibility is questionable to use since the domain <CODE>messages</CODE> |
| really never should be used. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-bindtextdomain" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="const char *domainname"/> |
| <parameter content="const char *dirname"/> |
| </prototype> |
| <headers> |
| <header filename = "libintl.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>bindtextdomain</CODE> function can be used to specify the directory |
| which contains the message catalogs for domain <VAR>domainname</VAR> for the |
| different languages. To be correct, this is the directory where the |
| hierarchy of directories is expected. Details are explained below. |
| <br><br> For the programmer it is important to note that the translations which |
| come with the program have be placed in a directory hierarchy starting |
| at, say, <TT>/foo/bar</TT>. Then the program should make a |
| <CODE>bindtextdomain</CODE> call to bind the domain for the current program to |
| this directory. So it is made sure the catalogs are found. A correctly |
| running program does not depend on the user setting an environment |
| variable. |
| <br><br> The <CODE>bindtextdomain</CODE> function can be used several times and if the |
| <VAR>domainname</VAR> argument is different the previously bound domains |
| will not be overwritten. |
| <br><br> If the program which wish to use <CODE>bindtextdomain</CODE> at some point of |
| time use the <CODE>chdir</CODE> function to change the current working |
| directory it is important that the <VAR>dirname</VAR> strings ought to be an |
| absolute pathname. Otherwise the addressed directory might vary with |
| the time. |
| <br><br> If the <VAR>dirname</VAR> parameter is the null pointer <CODE>bindtextdomain</CODE> |
| returns the currently selected directory for the domain with the name |
| <VAR>domainname</VAR>. |
| <br><br> The <CODE>bindtextdomain</CODE> function returns a pointer to a string |
| containing the name of the selected directory name. The string is |
| allocated internally in the function and must not be changed by the |
| user. If the system went out of core during the execution of |
| <CODE>bindtextdomain</CODE> the return value is <CODE>NULL</CODE> and the global |
| variable <VAR>errno</VAR> is set accordingly. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-ngettext" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="const char *msgid1"/> |
| <parameter content="const char *msgid2"/> |
| <parameter content="unsigned long int n"/> |
| </prototype> |
| <headers> |
| <header filename = "libintl.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>ngettext</CODE> function is similar to the <CODE>gettext</CODE> function |
| as it finds the message catalogs in the same way. But it takes two |
| extra arguments. The <VAR>msgid1</VAR> parameter must contain the singular |
| form of the string to be converted. It is also used as the key for the |
| search in the catalog. The <VAR>msgid2</VAR> parameter is the plural form. |
| The parameter <VAR>n</VAR> is used to determine the plural form. If no |
| message catalog is found <VAR>msgid1</VAR> is returned if <CODE>n == 1</CODE>, |
| otherwise <CODE>msgid2</CODE>. |
| <br><br> An example for the us of this function is: |
| <br><br> <pre><br> |
| printf (ngettext ("%d file removed", "%d files removed", n), n);<br> |
| </pre> |
| <br><br> Please note that the numeric value <VAR>n</VAR> has to be passed to the |
| <CODE>printf</CODE> function as well. It is not sufficient to pass it only to |
| <CODE>ngettext</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-dngettext" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="const char *domain"/> |
| <parameter content="const char *msgid1"/> |
| <parameter content="const char *msgid2"/> |
| <parameter content="unsigned long int n"/> |
| </prototype> |
| <headers> |
| <header filename = "libintl.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>dngettext</CODE> is similar to the <CODE>dgettext</CODE> function in the |
| way the message catalog is selected. The difference is that it takes |
| two extra parameter to provide the correct plural form. These two |
| parameters are handled in the same way <CODE>ngettext</CODE> handles them. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-dcngettext" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="const char *domain"/> |
| <parameter content="const char *msgid1"/> |
| <parameter content="const char *msgid2"/> |
| <parameter content="unsigned long int n"/> |
| <parameter content="int category"/> |
| </prototype> |
| <headers> |
| <header filename = "libintl.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>dcngettext</CODE> is similar to the <CODE>dcgettext</CODE> function in the |
| way the message catalog is selected. The difference is that it takes |
| two extra parameter to provide the correct plural form. These two |
| parameters are handled in the same way <CODE>ngettext</CODE> handles them. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="dtype-jmp_buf" type="dtype"> |
| <structure> |
| </structure> |
| </construct> |
| <construct id="function-longjmp" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="jmp_buf state"/> |
| <parameter content="int value"/> |
| </prototype> |
| <headers> |
| <header filename = "setjmp.h"/> |
| </headers> |
| <synopsis> |
| This function restores current execution to the state saved in |
| <VAR>state</VAR>, and continues execution from the call to <CODE>setjmp</CODE> that |
| established that return point. Returning from <CODE>setjmp</CODE> by means of |
| <CODE>longjmp</CODE> returns the <VAR>value</VAR> argument that was passed to |
| <CODE>longjmp</CODE>, rather than <CODE>0</CODE>. (But if <VAR>value</VAR> is given as |
| <CODE>0</CODE>, <CODE>setjmp</CODE> returns <CODE>1</CODE>). |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="dtype-sigjmp_buf" type="dtype"> |
| <structure> |
| </structure> |
| </construct> |
| <construct id="function-sigsetjmp" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="sigjmp_buf state"/> |
| <parameter content="int savesigs"/> |
| </prototype> |
| <headers> |
| <header filename = "setjmp.h"/> |
| </headers> |
| <synopsis> |
| This is similar to <CODE>setjmp</CODE>. If <VAR>savesigs</VAR> is nonzero, the set |
| of blocked signals is saved in <VAR>state</VAR> and will be restored if a |
| <CODE>siglongjmp</CODE> is later performed with this <VAR>state</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-siglongjmp" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="sigjmp_buf state"/> |
| <parameter content="int value"/> |
| </prototype> |
| <headers> |
| <header filename = "setjmp.h"/> |
| </headers> |
| <synopsis> |
| This is similar to <CODE>longjmp</CODE> except for the type of its <VAR>state</VAR> |
| argument. If the <CODE>sigsetjmp</CODE> call that set this <VAR>state</VAR> used a |
| nonzero <VAR>savesigs</VAR> flag, <CODE>siglongjmp</CODE> also restores the set of |
| blocked signals. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="dtype-ucontext_t" type="dtype"> |
| <structure> |
| <synopsis> |
| <br><br> The <CODE>ucontext_t</CODE> type is defined as a structure with as least the |
| following elements: |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="ucontext_t *uc_link"> |
| <synopsis> |
| This is a pointer to the next context structure which is used if the |
| context described in the current structure returns. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="sigset_t uc_sigmask"> |
| <synopsis> |
| Set of signals which are blocked when this context is used. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="stack_t uc_stack"> |
| <synopsis> |
| Stack used for this context. The value need not be (and normally is |
| not) the stack pointer. . |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="function-getcontext" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="ucontext_t *ucp"/> |
| </prototype> |
| <headers> |
| <header filename = "ucontext.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>getcontext</CODE> function initializes the variable pointed to by |
| <VAR>ucp</VAR> with the context of the calling thread. The context contains |
| the content of the registers, the signal mask, and the current stack. |
| Executing the contents would start at the point where the |
| <CODE>getcontext</CODE> call just returned. |
| <br><br> The function returns <CODE>0</CODE> if successful. Otherwise it returns |
| <CODE>-1</CODE> and sets <VAR>errno</VAR> accordingly. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-makecontext" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="ucontext_t *ucp"/> |
| <parameter content="void (*func) (void)"/> |
| <parameter content="int argc"/> |
| <parameter content="..."/> |
| </prototype> |
| <headers> |
| <header filename = "ucontext.h"/> |
| </headers> |
| <synopsis> |
| <br><br> The <VAR>ucp</VAR> parameter passed to the <CODE>makecontext</CODE> shall be |
| initialized by a call to <CODE>getcontext</CODE>. The context will be |
| modified to in a way so that if the context is resumed it will start by |
| calling the function <CODE>func</CODE> which gets <VAR>argc</VAR> integer arguments |
| passed. The integer arguments which are to be passed should follow the |
| <VAR>argc</VAR> parameter in the call to <CODE>makecontext</CODE>. |
| <br><br> Before the call to this function the <CODE>uc_stack</CODE> and <CODE>uc_link</CODE> |
| element of the <VAR>ucp</VAR> structure should be initialized. The |
| <CODE>uc_stack</CODE> element describes the stack which is used for this |
| context. No two contexts which are used at the same time should use the |
| same memory region for a stack. |
| <br><br> The <CODE>uc_link</CODE> element of the object pointed to by <VAR>ucp</VAR> should |
| be a pointer to the context to be executed when the function <VAR>func</VAR> |
| returns or it should be a null pointer. See <CODE>setcontext</CODE> for more |
| information about the exact use. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-setcontext" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const ucontext_t *ucp"/> |
| </prototype> |
| <headers> |
| <header filename = "ucontext.h"/> |
| </headers> |
| <synopsis> |
| <br><br> The <CODE>setcontext</CODE> function restores the context described by |
| <VAR>ucp</VAR>. The context is not modified and can be reused as often as |
| wanted. |
| <br><br> If the context was created by <CODE>getcontext</CODE> execution resumes with |
| the registers filled with the same values and the same stack as if the |
| <CODE>getcontext</CODE> call just returned. |
| <br><br> If the context was modified with a call to <CODE>makecontext</CODE> execution |
| continues with the function passed to <CODE>makecontext</CODE> which gets the |
| specified parameters passed. If this function returns execution is |
| resumed in the context which was referenced by the <CODE>uc_link</CODE> |
| element of the context structure passed to <CODE>makecontext</CODE> at the |
| time of the call. If <CODE>uc_link</CODE> was a null pointer the application |
| terminates in this case. |
| <br><br> Since the context contains information about the stack no two threads |
| should use the same context at the same time. The result in most cases |
| would be disastrous. |
| <br><br> The <CODE>setcontext</CODE> function does not return unless an error occurred |
| in which case it returns <CODE>-1</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-swapcontext" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="ucontext_t *restrict oucp"/> |
| <parameter content="const ucontext_t *restrict ucp"/> |
| </prototype> |
| <headers> |
| <header filename = "ucontext.h"/> |
| </headers> |
| <synopsis> |
| <br><br> The <CODE>swapcontext</CODE> function is similar to <CODE>setcontext</CODE> but |
| instead of just replacing the current context the latter is first saved |
| in the object pointed to by <VAR>oucp</VAR> as if this was a call to |
| <CODE>getcontext</CODE>. The saved context would resume after the call to |
| <CODE>swapcontext</CODE>. |
| <br><br> Once the current context is saved the context described in <VAR>ucp</VAR> is |
| installed and execution continues as described in this context. |
| <br><br> If <CODE>swapcontext</CODE> succeeds the function does not return unless the |
| context <VAR>oucp</VAR> is used without prior modification by |
| <CODE>makecontext</CODE>. The return value in this case is <CODE>0</CODE>. If the |
| function fails it returns <CODE>-1</CODE> and set <VAR>errno</VAR> accordingly. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-open" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *filename"/> |
| <parameter content="int flags["/> |
| <parameter content="mode_t mode]"/> |
| </prototype> |
| <headers> |
| <header filename = "fcntl.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>open</CODE> function creates and returns a new file descriptor |
| for the file named by <VAR>filename</VAR>. Initially, the file position |
| indicator for the file is at the beginning of the file. The argument |
| <VAR>mode</VAR> is used only when a file is created, but it doesn't hurt |
| to supply the argument in any case. |
| <br><br> The <VAR>flags</VAR> argument controls how the file is to be opened. This is |
| a bit mask; you create the value by the bitwise OR of the appropriate |
| parameters (using the <samp>|</samp> operator in C). |
| , for the parameters available. |
| <br><br> The normal return value from <CODE>open</CODE> is a non-negative integer file |
| descriptor. In the case of an error, a value of -1 is returned |
| instead. In addition to the usual file name errors , the following <CODE>errno</CODE> error conditions are defined |
| for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EACCES</CODE> |
| <DD> |
| The file exists but is not readable/writable as requested by the <VAR>flags</VAR> |
| argument, the file does not exist and the directory is unwritable so |
| it cannot be created. |
| <br><br> <LI> EEXIST |
| Both <CODE>O_CREAT</CODE> and <CODE>O_EXCL</CODE> are set, and the named file already |
| exists. |
| <br><br> <LI> EINTR |
| The <CODE>open</CODE> operation was interrupted by a signal. |
| . |
| <br><br> <LI> EISDIR |
| The <VAR>flags</VAR> argument specified write access, and the file is a directory. |
| <br><br> <LI> EMFILE |
| The process has too many files open. |
| The maximum number of file descriptors is controlled by the |
| <CODE>RLIMIT_NOFILE</CODE> resource limit; . |
| <br><br> <LI> ENFILE |
| The entire system, or perhaps the file system which contains the |
| directory, cannot support any additional open files at the moment. |
| (This problem cannot happen on the GNU system.) |
| <br><br> <LI> ENOENT |
| The named file does not exist, and <CODE>O_CREAT</CODE> is not specified. |
| <br><br> <LI> ENOSPC |
| The directory or file system that would contain the new file cannot be |
| extended, because there is no disk space left. |
| <br><br> <LI> ENXIO |
| <CODE>O_NONBLOCK</CODE> and <CODE>O_WRONLY</CODE> are both set in the <VAR>flags</VAR> |
| argument, the file named by <VAR>filename</VAR> is a FIFO , and no process has the file open for reading. |
| <br><br> <LI> EROFS |
| The file resides on a read-only file system and any of <CODE>O_WRONLY</CODE>, |
| <CODE>O_RDWR</CODE>, and <CODE>O_TRUNC</CODE> are set in the <VAR>flags</VAR> argument, |
| or <CODE>O_CREAT</CODE> is set and the file does not already exist. |
| |
| <br><br> <br><br> If on a 32 bit machine the sources are translated with |
| <CODE>_FILE_OFFSET_BITS == 64</CODE> the function <CODE>open</CODE> returns a file |
| descriptor opened in the large file mode which enables the file handling |
| functions to use files up to 2^63 bytes in size and offset from |
| -2^63 to 2^63. This happens transparently for the user |
| since all of the lowlevel file handling functions are equally replaced. |
| <br><br> This function is a cancellation point in multi-threaded programs. This |
| is a problem if the thread allocates some resources (like memory, file |
| descriptors, semaphores or whatever) at the time <CODE>open</CODE> is |
| called. If the thread gets canceled these resources stay allocated |
| until the program ends. To avoid this calls to <CODE>open</CODE> should be |
| protected using cancellation handlers. |
| <br><br> The <CODE>open</CODE> function is the underlying primitive for the <CODE>fopen</CODE> |
| and <CODE>freopen</CODE> functions, that create streams. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-open64" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *filename"/> |
| <parameter content="int flags["/> |
| <parameter content="mode_t mode]"/> |
| </prototype> |
| <headers> |
| <header filename = "fcntl.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to <CODE>open</CODE>. It returns a file descriptor |
| which can be used to access the file named by <VAR>filename</VAR>. The only |
| difference is that on 32 bit systems the file is opened in the |
| large file mode. I.e., file length and file offsets can exceed 31 bits. |
| <br><br> When the sources are translated with <CODE>_FILE_OFFSET_BITS == 64</CODE> this |
| function is actually available under the name <CODE>open</CODE>. I.e., the |
| new, extended API using 64 bit file sizes and offsets transparently |
| replaces the old API. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-close" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int filedes"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| The function <CODE>close</CODE> closes the file descriptor <VAR>filedes</VAR>. |
| Closing a file has the following consequences: |
| <br><br> <OL> |
| <LI> |
| The file descriptor is deallocated. |
| <br><br> <LI> |
| Any record locks owned by the process on the file are unlocked. |
| <br><br> <LI> |
| When all file descriptors associated with a pipe or FIFO have been closed, |
| any unread data is discarded. |
| </OL> |
| <br><br> This function is a cancellation point in multi-threaded programs. This |
| is a problem if the thread allocates some resources (like memory, file |
| descriptors, semaphores or whatever) at the time <CODE>close</CODE> is |
| called. If the thread gets canceled these resources stay allocated |
| until the program ends. To avoid this, calls to <CODE>close</CODE> should be |
| protected using cancellation handlers. |
| <br><br> The normal return value from <CODE>close</CODE> is 0; a value of -1 |
| is returned in case of failure. The following <CODE>errno</CODE> error |
| conditions are defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EBADF</CODE> |
| <DD> |
| The <VAR>filedes</VAR> argument is not a valid file descriptor. |
| <br><br> <LI> EINTR |
| The <CODE>close</CODE> call was interrupted by a signal. |
| . |
| Here is an example of how to handle <CODE>EINTR</CODE> properly: |
| <br><br> <pre><br> |
| TEMP_FAILURE_RETRY (close (desc));<br> |
| </pre> |
| <br><br> <LI> ENOSPC |
| <LI>x EIO |
| <LI>x EDQUOT |
| When the file is accessed by NFS, these errors from <CODE>write</CODE> can sometimes |
| not be detected until <CODE>close</CODE>. , for details |
| on their meaning. |
| |
| <br><br> Please note that there is <EM>no</EM> separate <CODE>close64</CODE> function. |
| This is not necessary since this function does not determine nor depend |
| on the mode of the file. The kernel which performs the <CODE>close</CODE> |
| operation knows which mode the descriptor is used for and can handle |
| this situation. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="dtype-ssize_t" type="dtype"> |
| <structure> |
| </structure> |
| </construct> |
| <construct id="function-read" type="function"> |
| <function returntype="ssize_t"> |
| <prototype> |
| <parameter content="int filedes"/> |
| <parameter content="void *buffer"/> |
| <parameter content="size_t size"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>read</CODE> function reads up to <VAR>size</VAR> bytes from the file |
| with descriptor <VAR>filedes</VAR>, storing the results in the <VAR>buffer</VAR>. |
| (This is not necessarily a character string, and no terminating null |
| character is added.) |
| <br><br> -of-file, on a file descriptor |
| The return value is the number of bytes actually read. This might be |
| less than <VAR>size</VAR>; for example, if there aren't that many bytes left |
| in the file or if there aren't that many bytes immediately available. |
| The exact behavior depends on what kind of file it is. Note that |
| reading less than <VAR>size</VAR> bytes is not an error. |
| <br><br> A value of zero indicates end-of-file (except if the value of the |
| <VAR>size</VAR> argument is also zero). This is not considered an error. |
| If you keep calling <CODE>read</CODE> while at end-of-file, it will keep |
| returning zero and doing nothing else. |
| <br><br> If <CODE>read</CODE> returns at least one character, there is no way you can |
| tell whether end-of-file was reached. But if you did reach the end, the |
| next read will return zero. |
| <br><br> In case of an error, <CODE>read</CODE> returns -1. The following |
| <CODE>errno</CODE> error conditions are defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EAGAIN</CODE> |
| <DD> |
| Normally, when no input is immediately available, <CODE>read</CODE> waits for |
| some input. But if the <CODE>O_NONBLOCK</CODE> flag is set for the file |
| , <CODE>read</CODE> returns immediately without |
| reading any data, and reports this error. |
| <br><br> Compatibility Note: Most versions of BSD Unix use a different |
| error code for this: <CODE>EWOULDBLOCK</CODE>. In the GNU library, |
| <CODE>EWOULDBLOCK</CODE> is an alias for <CODE>EAGAIN</CODE>, so it doesn't matter |
| which name you use. |
| <br><br> On some systems, reading a large amount of data from a character special |
| file can also fail with <CODE>EAGAIN</CODE> if the kernel cannot find enough |
| physical memory to lock down the user's pages. This is limited to |
| devices that transfer with direct memory access into the user's memory, |
| which means it does not include terminals, since they always use |
| separate buffers inside the kernel. This problem never happens in the |
| GNU system. |
| <br><br> Any condition that could result in <CODE>EAGAIN</CODE> can instead result in a |
| successful <CODE>read</CODE> which returns fewer bytes than requested. |
| Calling <CODE>read</CODE> again immediately would result in <CODE>EAGAIN</CODE>. |
| <br><br> <LI> EBADF |
| The <VAR>filedes</VAR> argument is not a valid file descriptor, |
| or is not open for reading. |
| <br><br> <LI> EINTR |
| <CODE>read</CODE> was interrupted by a signal while it was waiting for input. |
| . A signal will not necessary cause |
| <CODE>read</CODE> to return <CODE>EINTR</CODE>; it may instead result in a |
| successful <CODE>read</CODE> which returns fewer bytes than requested. |
| <br><br> <LI> EIO |
| For many devices, and for disk files, this error code indicates |
| a hardware error. |
| <br><br> <CODE>EIO</CODE> also occurs when a background process tries to read from the |
| controlling terminal, and the normal action of stopping the process by |
| sending it a <CODE>SIGTTIN</CODE> signal isn't working. This might happen if |
| the signal is being blocked or ignored, or because the process group is |
| orphaned. , for more information about job control, |
| and Signal Handling, for information about signals. |
| <br><br> <LI> EINVAL |
| In some systems, when reading from a character or block device, position |
| and size offsets must be aligned to a particular block size. This error |
| indicates that the offsets were not properly aligned. |
| |
| <br><br> Please note that there is no function named <CODE>read64</CODE>. This is not |
| necessary since this function does not directly modify or handle the |
| possibly wide file offset. Since the kernel handles this state |
| internally, the <CODE>read</CODE> function can be used for all cases. |
| <br><br> This function is a cancellation point in multi-threaded programs. This |
| is a problem if the thread allocates some resources (like memory, file |
| descriptors, semaphores or whatever) at the time <CODE>read</CODE> is |
| called. If the thread gets canceled these resources stay allocated |
| until the program ends. To avoid this, calls to <CODE>read</CODE> should be |
| protected using cancellation handlers. |
| <br><br> The <CODE>read</CODE> function is the underlying primitive for all of the |
| functions that read from streams, such as <CODE>fgetc</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-pread" type="function"> |
| <function returntype="ssize_t"> |
| <prototype> |
| <parameter content="int filedes"/> |
| <parameter content="void *buffer"/> |
| <parameter content="size_t size"/> |
| <parameter content="off_t offset"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>pread</CODE> function is similar to the <CODE>read</CODE> function. The |
| first three arguments are identical, and the return values and error |
| codes also correspond. |
| <br><br> The difference is the fourth argument and its handling. The data block |
| is not read from the current position of the file descriptor |
| <CODE>filedes</CODE>. Instead the data is read from the file starting at |
| position <VAR>offset</VAR>. The position of the file descriptor itself is |
| not affected by the operation. The value is the same as before the call. |
| <br><br> When the source file is compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> the |
| <CODE>pread</CODE> function is in fact <CODE>pread64</CODE> and the type |
| <CODE>off_t</CODE> has 64 bits, which makes it possible to handle files up to |
| 2^63 bytes in length. |
| <br><br> The return value of <CODE>pread</CODE> describes the number of bytes read. |
| In the error case it returns -1 like <CODE>read</CODE> does and the |
| error codes are also the same, with these additions: |
| <br><br> <DL> |
| |
| <DT><CODE>EINVAL</CODE> |
| <DD> |
| The value given for <VAR>offset</VAR> is negative and therefore illegal. |
| <br><br> <LI> ESPIPE |
| The file descriptor <VAR>filedes</VAR> is associate with a pipe or a FIFO and |
| this device does not allow positioning of the file pointer. |
| |
| <br><br> The function is an extension defined in the Unix Single Specification |
| version 2. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-pread64" type="function"> |
| <function returntype="ssize_t"> |
| <prototype> |
| <parameter content="int filedes"/> |
| <parameter content="void *buffer"/> |
| <parameter content="size_t size"/> |
| <parameter content="off64_t offset"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to the <CODE>pread</CODE> function. The difference |
| is that the <VAR>offset</VAR> parameter is of type <CODE>off64_t</CODE> instead of |
| <CODE>off_t</CODE> which makes it possible on 32 bit machines to address |
| files larger than 2^31 bytes and up to 2^63 bytes. The |
| file descriptor <CODE>filedes</CODE> must be opened using <CODE>open64</CODE> since |
| otherwise the large offsets possible with <CODE>off64_t</CODE> will lead to |
| errors with a descriptor in small file mode. |
| <br><br> When the source file is compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> on a |
| 32 bit machine this function is actually available under the name |
| <CODE>pread</CODE> and so transparently replaces the 32 bit interface. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-write" type="function"> |
| <function returntype="ssize_t"> |
| <prototype> |
| <parameter content="int filedes"/> |
| <parameter content="const void *buffer"/> |
| <parameter content="size_t size"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>write</CODE> function writes up to <VAR>size</VAR> bytes from |
| <VAR>buffer</VAR> to the file with descriptor <VAR>filedes</VAR>. The data in |
| <VAR>buffer</VAR> is not necessarily a character string and a null character is |
| output like any other character. |
| <br><br> The return value is the number of bytes actually written. This may be |
| <VAR>size</VAR>, but can always be smaller. Your program should always call |
| <CODE>write</CODE> in a loop, iterating until all the data is written. |
| <br><br> Once <CODE>write</CODE> 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 <CODE>fsync</CODE> 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 |
| <CODE>fdatasync</CODE> which guarantees integrity only for the file data and |
| is therefore faster. |
| You can use the <CODE>O_FSYNC</CODE> open mode to make <CODE>write</CODE> always |
| store the data to disk before returning; . |
| <br><br> In the case of an error, <CODE>write</CODE> returns -1. The following |
| <CODE>errno</CODE> error conditions are defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EAGAIN</CODE> |
| <DD> |
| Normally, <CODE>write</CODE> blocks until the write operation is complete. |
| But if the <CODE>O_NONBLOCK</CODE> flag is set for the file , 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><br> Compatibility Note: Most versions of BSD Unix use a different |
| error code for this: <CODE>EWOULDBLOCK</CODE>. In the GNU library, |
| <CODE>EWOULDBLOCK</CODE> is an alias for <CODE>EAGAIN</CODE>, so it doesn't matter |
| which name you use. |
| <br><br> On some systems, writing a large amount of data from a character special |
| file can also fail with <CODE>EAGAIN</CODE> if the kernel cannot find enough |
| physical memory to lock down the user's pages. This is limited to |
| devices that transfer with direct memory access into the user's memory, |
| which means it does not include terminals, since they always use |
| separate buffers inside the kernel. This problem does not arise in the |
| GNU system. |
| <br><br> <LI> EBADF |
| The <VAR>filedes</VAR> argument is not a valid file descriptor, |
| or is not open for writing. |
| <br><br> <LI> EFBIG |
| The size of the file would become larger than the implementation can support. |
| <br><br> <LI> EINTR |
| The <CODE>write</CODE> operation was interrupted by a signal while it was |
| blocked waiting for completion. A signal will not necessarily cause |
| <CODE>write</CODE> to return <CODE>EINTR</CODE>; it may instead result in a |
| successful <CODE>write</CODE> which writes fewer bytes than requested. |
| . |
| <br><br> <LI> EIO |
| For many devices, and for disk files, this error code indicates |
| a hardware error. |
| <br><br> <LI> ENOSPC |
| The device containing the file is full. |
| <br><br> <LI> 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 <CODE>SIGPIPE</CODE> |
| signal is also sent to the process; see Signal Handling. |
| <br><br> <LI> EINVAL |
| In some systems, when writing to a character or block device, position |
| and size offsets must be aligned to a particular block size. This error |
| indicates that the offsets were not properly aligned. |
| |
| <br><br> Unless you have arranged to prevent <CODE>EINTR</CODE> failures, you should |
| check <CODE>errno</CODE> after each failing call to <CODE>write</CODE>, and if the |
| error was <CODE>EINTR</CODE>, you should simply repeat the call. |
| . The easy way to do this is with the |
| macro <CODE>TEMP_FAILURE_RETRY</CODE>, as follows: |
| <br><br> <pre><br> |
| nbytes = TEMP_FAILURE_RETRY (write (desc, buffer, count));<br> |
| </pre> |
| <br><br> Please note that there is no function named <CODE>write64</CODE>. This is not |
| necessary since this function does not directly modify or handle the |
| possibly wide file offset. Since the kernel handles this state |
| internally the <CODE>write</CODE> function can be used for all cases. |
| <br><br> This function is a cancellation point in multi-threaded programs. This |
| is a problem if the thread allocates some resources (like memory, file |
| descriptors, semaphores or whatever) at the time <CODE>write</CODE> is |
| called. If the thread gets canceled these resources stay allocated |
| until the program ends. To avoid this, calls to <CODE>write</CODE> should be |
| protected using cancellation handlers. |
| <br><br> The <CODE>write</CODE> function is the underlying primitive for all of the |
| functions that write to streams, such as <CODE>fputc</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-pwrite" type="function"> |
| <function returntype="ssize_t"> |
| <prototype> |
| <parameter content="int filedes"/> |
| <parameter content="const void *buffer"/> |
| <parameter content="size_t size"/> |
| <parameter content="off_t offset"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>pwrite</CODE> function is similar to the <CODE>write</CODE> function. The |
| first three arguments are identical, and the return values and error codes |
| also correspond. |
| <br><br> The difference is the fourth argument and its handling. The data block |
| is not written to the current position of the file descriptor |
| <CODE>filedes</CODE>. Instead the data is written to the file starting at |
| position <VAR>offset</VAR>. The position of the file descriptor itself is |
| not affected by the operation. The value is the same as before the call. |
| <br><br> When the source file is compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> the |
| <CODE>pwrite</CODE> function is in fact <CODE>pwrite64</CODE> and the type |
| <CODE>off_t</CODE> has 64 bits, which makes it possible to handle files up to |
| 2^63 bytes in length. |
| <br><br> The return value of <CODE>pwrite</CODE> describes the number of written bytes. |
| In the error case it returns -1 like <CODE>write</CODE> does and the |
| error codes are also the same, with these additions: |
| <br><br> <DL> |
| |
| <DT><CODE>EINVAL</CODE> |
| <DD> |
| The value given for <VAR>offset</VAR> is negative and therefore illegal. |
| <br><br> <LI> ESPIPE |
| The file descriptor <VAR>filedes</VAR> is associated with a pipe or a FIFO and |
| this device does not allow positioning of the file pointer. |
| |
| <br><br> The function is an extension defined in the Unix Single Specification |
| version 2. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-pwrite64" type="function"> |
| <function returntype="ssize_t"> |
| <prototype> |
| <parameter content="int filedes"/> |
| <parameter content="const void *buffer"/> |
| <parameter content="size_t size"/> |
| <parameter content="off64_t offset"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to the <CODE>pwrite</CODE> function. The difference |
| is that the <VAR>offset</VAR> parameter is of type <CODE>off64_t</CODE> instead of |
| <CODE>off_t</CODE> which makes it possible on 32 bit machines to address |
| files larger than 2^31 bytes and up to 2^63 bytes. The |
| file descriptor <CODE>filedes</CODE> must be opened using <CODE>open64</CODE> since |
| otherwise the large offsets possible with <CODE>off64_t</CODE> will lead to |
| errors with a descriptor in small file mode. |
| <br><br> When the source file is compiled using <CODE>_FILE_OFFSET_BITS == 64</CODE> on a |
| 32 bit machine this function is actually available under the name |
| <CODE>pwrite</CODE> and so transparently replaces the 32 bit interface. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-lseek" type="function"> |
| <function returntype="off_t"> |
| <prototype> |
| <parameter content="int filedes"/> |
| <parameter content="off_t offset"/> |
| <parameter content="int whence"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>lseek</CODE> function is used to change the file position of the |
| file with descriptor <VAR>filedes</VAR>. |
| <br><br> The <VAR>whence</VAR> argument specifies how the <VAR>offset</VAR> should be |
| interpreted, in the same way as for the <CODE>fseek</CODE> function, and it must |
| be one of the symbolic constants <CODE>SEEK_SET</CODE>, <CODE>SEEK_CUR</CODE>, or |
| <CODE>SEEK_END</CODE>. |
| <br><br> <DL> |
| |
| <DT><CODE>SEEK_SET</CODE> |
| <DD> |
| Specifies that <VAR>whence</VAR> is a count of characters from the beginning |
| of the file. |
| <br><br> <DT><CODE>SEEK_CUR</CODE> |
| <DD> |
| Specifies that <VAR>whence</VAR> is a count of characters from the current |
| file position. This count may be positive or negative. |
| <br><br> <LI> SEEK_END |
| Specifies that <VAR>whence</VAR> is a count of characters from the end of |
| the file. A negative count specifies a position within the current |
| extent of the file; a positive count specifies a position past the |
| current end. If you set the position past the current end, and |
| actually write data, you will extend the file with zeros up to that |
| position. |
| |
| <br><br> The return value from <CODE>lseek</CODE> is normally the resulting file |
| position, measured in bytes from the beginning of the file. |
| You can use this feature together with <CODE>SEEK_CUR</CODE> to read the |
| current file position. |
| <br><br> If you want to append to the file, setting the file position to the |
| current end of file with <CODE>SEEK_END</CODE> is not sufficient. Another |
| process may write more data after you seek but before you write, |
| extending the file so the position you write onto clobbers their data. |
| Instead, use the <CODE>O_APPEND</CODE> operating mode; . |
| <br><br> You can set the file position past the current end of the file. This |
| does not by itself make the file longer; <CODE>lseek</CODE> never changes the |
| file. But subsequent output at that position will extend the file. |
| Characters between the previous end of file and the new position are |
| filled with zeros. Extending the file in this way can create a |
| ``hole'': the blocks of zeros are not actually allocated on disk, so the |
| file takes up less space than it appears to; it is then called a |
| ``sparse file''. |
| files |
| in files |
| <br><br> If the file position cannot be changed, or the operation is in some way |
| invalid, <CODE>lseek</CODE> returns a value of -1. The following |
| <CODE>errno</CODE> error conditions are defined for this function: |
| <br><br> <DL> |
| |
| <LI> EBADF |
| The <VAR>filedes</VAR> is not a valid file descriptor. |
| <br><br> <LI> EINVAL |
| The <VAR>whence</VAR> argument value is not valid, or the resulting |
| file offset is not valid. A file offset is invalid. |
| <br><br> <LI> ESPIPE |
| The <VAR>filedes</VAR> corresponds to an object that cannot be positioned, |
| such as a pipe, FIFO or terminal device. (POSIX.1 specifies this error |
| only for pipes and FIFOs, but in the GNU system, you always get |
| <CODE>ESPIPE</CODE> if the object is not seekable.) |
| |
| <br><br> When the source file is compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> the |
| <CODE>lseek</CODE> function is in fact <CODE>lseek64</CODE> and the type |
| <CODE>off_t</CODE> has 64 bits which makes it possible to handle files up to |
| 2^63 bytes in length. |
| <br><br> This function is a cancellation point in multi-threaded programs. This |
| is a problem if the thread allocates some resources (like memory, file |
| descriptors, semaphores or whatever) at the time <CODE>lseek</CODE> is |
| called. If the thread gets canceled these resources stay allocated |
| until the program ends. To avoid this calls to <CODE>lseek</CODE> should be |
| protected using cancellation handlers. |
| <br><br> The <CODE>lseek</CODE> function is the underlying primitive for the |
| <CODE>fseek</CODE>, <CODE>fseeko</CODE>, <CODE>ftell</CODE>, <CODE>ftello</CODE> and |
| <CODE>rewind</CODE> functions, which operate on streams instead of file |
| descriptors. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-lseek64" type="function"> |
| <function returntype="off64_t"> |
| <prototype> |
| <parameter content="int filedes"/> |
| <parameter content="off64_t offset"/> |
| <parameter content="int whence"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to the <CODE>lseek</CODE> function. The difference |
| is that the <VAR>offset</VAR> parameter is of type <CODE>off64_t</CODE> instead of |
| <CODE>off_t</CODE> which makes it possible on 32 bit machines to address |
| files larger than 2^31 bytes and up to 2^63 bytes. The |
| file descriptor <CODE>filedes</CODE> must be opened using <CODE>open64</CODE> since |
| otherwise the large offsets possible with <CODE>off64_t</CODE> will lead to |
| errors with a descriptor in small file mode. |
| <br><br> When the source file is compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> on a |
| 32 bits machine this function is actually available under the name |
| <CODE>lseek</CODE> and so transparently replaces the 32 bit interface. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="dtype-off_t" type="dtype"> |
| <structure> |
| </structure> |
| </construct> |
| <construct id="dtype-off64_t" type="dtype"> |
| <structure> |
| </structure> |
| </construct> |
| <construct id="function-fdopen" type="function"> |
| <function returntype="FILE *"> |
| <prototype> |
| <parameter content="int filedes"/> |
| <parameter content="const char *opentype"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/types.h"/> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>fdopen</CODE> function returns a new stream for the file descriptor |
| <VAR>filedes</VAR>. |
| <br><br> The <VAR>opentype</VAR> argument is interpreted in the same way as for the |
| <CODE>fopen</CODE> function , except that |
| the <samp>b</samp> option is not permitted; this is because GNU makes no |
| distinction between text and binary files. Also, <CODE>"w"</CODE> and |
| <CODE>"w+"</CODE> do not cause truncation of the file; these have an effect only |
| when opening a file, and in this case the file has already been opened. |
| You must make sure that the <VAR>opentype</VAR> argument matches the actual |
| mode of the open file descriptor. |
| <br><br> The return value is the new stream. If the stream cannot be created |
| (for example, if the modes for the file indicated by the file descriptor |
| do not permit the access specified by the <VAR>opentype</VAR> argument), a |
| null pointer is returned instead. |
| <br><br> In some other systems, <CODE>fdopen</CODE> may fail to detect that the modes |
| for file descriptor do not permit the access specified by |
| <CODE>opentype</CODE>. The GNU C library always checks for this. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fileno" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| This function returns the file descriptor associated with the stream |
| <VAR>stream</VAR>. If an error is detected (for example, if the <VAR>stream</VAR> |
| is not valid) or if <VAR>stream</VAR> does not do I/O to a file, |
| <CODE>fileno</CODE> returns -1. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fileno_unlocked" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>fileno_unlocked</CODE> function is equivalent to the <CODE>fileno</CODE> |
| function except that it does not implicitly lock the stream if the state |
| is <CODE>FSETLOCKING_INTERNAL</CODE>. |
| <br><br> This function is a GNU extension. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fclean" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| Clean up the stream <VAR>stream</VAR> so that its buffer is empty. If |
| <VAR>stream</VAR> is doing output, force it out. If <VAR>stream</VAR> is doing |
| input, give the data in the buffer back to the system, arranging to |
| reread it. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="struct-iovec" type="struct"> |
| <structure> |
| <synopsis> |
| <br><br> The <CODE>iovec</CODE> structure describes a buffer. It contains two fields: |
| <br><br> <br><br> |
| </synopsis> |
| <elements> |
| <element content="void *iov_base"> |
| <synopsis> |
| Contains the address of a buffer. |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="function-readv" type="function"> |
| <function returntype="ssize_t"> |
| <prototype> |
| <parameter content="int filedes"/> |
| <parameter content="const struct iovec *vector"/> |
| <parameter content="int count"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/uio.h"/> |
| </headers> |
| <synopsis> |
| <br><br> The <CODE>readv</CODE> function reads data from <VAR>filedes</VAR> and scatters it |
| into the buffers described in <VAR>vector</VAR>, which is taken to be |
| <VAR>count</VAR> structures long. As each buffer is filled, data is sent to the |
| next. |
| <br><br> Note that <CODE>readv</CODE> is not guaranteed to fill all the buffers. |
| It may stop at any point, for the same reasons <CODE>read</CODE> would. |
| <br><br> The return value is a count of bytes (<EM>not</EM> buffers) read, 0 |
| indicating end-of-file, or -1 indicating an error. The possible |
| errors are the same as in <CODE>read</CODE>. |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-writev" type="function"> |
| <function returntype="ssize_t"> |
| <prototype> |
| <parameter content="int filedes"/> |
| <parameter content="const struct iovec *vector"/> |
| <parameter content="int count"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/uio.h"/> |
| </headers> |
| <synopsis> |
| <br><br> The <CODE>writev</CODE> function gathers data from the buffers described in |
| <VAR>vector</VAR>, which is taken to be <VAR>count</VAR> structures long, and writes |
| them to <CODE>filedes</CODE>. As each buffer is written, it moves on to the |
| next. |
| <br><br> Like <CODE>readv</CODE>, <CODE>writev</CODE> may stop midstream under the same |
| conditions <CODE>write</CODE> would. |
| <br><br> The return value is a count of bytes written, or -1 indicating an |
| error. The possible errors are the same as in <CODE>write</CODE>. |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-mmap" type="function"> |
| <function returntype="void *"> |
| <prototype> |
| <parameter content="void *address"/> |
| <parameter content="size_t length,int protect"/> |
| <parameter content="int flags"/> |
| <parameter content="int filedes"/> |
| <parameter content="off_t offset"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/mman.h"/> |
| </headers> |
| <synopsis> |
| <br><br> The <CODE>mmap</CODE> function creates a new mapping, connected to bytes |
| (<VAR>offset</VAR>) to (<VAR>offset</VAR> + <VAR>length</VAR> - 1) in the file open on |
| <VAR>filedes</VAR>. A new reference for the file specified by <VAR>filedes</VAR> |
| is created, which is not removed by closing the file. |
| <br><br> <VAR>address</VAR> gives a preferred starting address for the mapping. |
| <CODE>NULL</CODE> expresses no preference. Any previous mapping at that |
| address is automatically removed. The address you give may still be |
| changed, unless you use the <CODE>MAP_FIXED</CODE> flag. |
| <br><br> |
| |
| |
| <VAR>protect</VAR> contains flags that control what kind of access is |
| permitted. They include <CODE>PROT_READ</CODE>, <CODE>PROT_WRITE</CODE>, and |
| <CODE>PROT_EXEC</CODE>, which permit reading, writing, and execution, |
| respectively. Inappropriate access will cause a segfault . |
| <br><br> Note that most hardware designs cannot support write permission without |
| read permission, and many do not distinguish read and execute permission. |
| Thus, you may receive wider permissions than you ask for, and mappings of |
| write-only files may be denied even if you do not use <CODE>PROT_READ</CODE>. |
| <br><br> <VAR>flags</VAR> contains flags that control the nature of the map. |
| One of <CODE>MAP_SHARED</CODE> or <CODE>MAP_PRIVATE</CODE> must be specified. |
| <br><br> They include: |
| <br><br> <DL> |
| |
| <DT><CODE>MAP_PRIVATE</CODE> |
| <DD> |
| This specifies that writes to the region should never be written back |
| to the attached file. Instead, a copy is made for the process, and the |
| region will be swapped normally if memory runs low. No other process will |
| see the changes. |
| <br><br> Since private mappings effectively revert to ordinary memory |
| when written to, you must have enough virtual memory for a copy of |
| the entire mmapped region if you use this mode with <CODE>PROT_WRITE</CODE>. |
| <br><br> <DT><CODE>MAP_SHARED</CODE> |
| <DD> |
| This specifies that writes to the region will be written back to the |
| file. Changes made will be shared immediately with other processes |
| mmaping the same file. |
| <br><br> Note that actual writing may take place at any time. You need to use |
| <CODE>msync</CODE>, described below, if it is important that other processes |
| using conventional I/O get a consistent view of the file. |
| <br><br> <DT><CODE>MAP_FIXED</CODE> |
| <DD> |
| This forces the system to use the exact mapping address specified in |
| <VAR>address</VAR> and fail if it can't. |
| <br><br> <DT><CODE>MAP_ANONYMOUS</CODE> |
| <DD> |
| <LI>x MAP_ANON |
| This flag tells the system to create an anonymous mapping, not connected |
| to a file. <VAR>filedes</VAR> and <VAR>off</VAR> are ignored, and the region is |
| initialized with zeros. |
| <br><br> Anonymous maps are used as the basic primitive to extend the heap on some |
| systems. They are also useful to share data between multiple tasks |
| without creating a file. |
| <br><br> On some systems using private anonymous mmaps is more efficient than using |
| <CODE>malloc</CODE> for large blocks. This is not an issue with the GNU C library, |
| as the included <CODE>malloc</CODE> automatically uses <CODE>mmap</CODE> where appropriate. |
| <br><br> <br><br> </DL> |
| <br><br> <CODE>mmap</CODE> returns the address of the new mapping, or -1 for an |
| error. |
| <br><br> Possible errors include: |
| <br><br> <DL> |
| |
| <br><br> <DT><CODE>EINVAL</CODE> |
| <DD> |
| <br><br> Either <VAR>address</VAR> was unusable, or inconsistent <VAR>flags</VAR> were |
| given. |
| <br><br> <LI> EACCES |
| <br><br> <VAR>filedes</VAR> was not open for the type of access specified in <VAR>protect</VAR>. |
| <br><br> <LI> ENOMEM |
| <br><br> Either there is not enough memory for the operation, or the process is |
| out of address space. |
| <br><br> <LI> ENODEV |
| <br><br> This file is of a type that doesn't support mapping. |
| <br><br> <LI> ENOEXEC |
| <br><br> The file is on a filesystem that doesn't support mapping. |
| <br><br> |
| <br><br> |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-mmap64" type="function"> |
| <function returntype="void *"> |
| <prototype> |
| <parameter content="void *address"/> |
| <parameter content="size_t length,int protect"/> |
| <parameter content="int flags"/> |
| <parameter content="int filedes"/> |
| <parameter content="off64_t offset"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/mman.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>mmap64</CODE> function is equivalent to the <CODE>mmap</CODE> function but |
| the <VAR>offset</VAR> parameter is of type <CODE>off64_t</CODE>. On 32-bit systems |
| this allows the file associated with the <VAR>filedes</VAR> descriptor to be |
| larger than 2GB. <VAR>filedes</VAR> must be a descriptor returned from a |
| call to <CODE>open64</CODE> or <CODE>fopen64</CODE> and <CODE>freopen64</CODE> where the |
| descriptor is retrieved with <CODE>fileno</CODE>. |
| <br><br> When the sources are translated with <CODE>_FILE_OFFSET_BITS == 64</CODE> this |
| function is actually available under the name <CODE>mmap</CODE>. I.e., the |
| new, extended API using 64 bit file sizes and offsets transparently |
| replaces the old API. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-munmap" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="void *addr"/> |
| <parameter content="size_t length"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/mman.h"/> |
| </headers> |
| <synopsis> |
| <br><br> <CODE>munmap</CODE> removes any memory maps from (<VAR>addr</VAR>) to (<VAR>addr</VAR> + |
| <VAR>length</VAR>). <VAR>length</VAR> should be the length of the mapping. |
| <br><br> It is safe to unmap multiple mappings in one command, or include unmapped |
| space in the range. It is also possible to unmap only part of an existing |
| mapping. However, only entire pages can be removed. If <VAR>length</VAR> is not |
| an even number of pages, it will be rounded up. |
| <br><br> It returns 0 for success and -1 for an error. |
| <br><br> One error is possible: |
| <br><br> <DL> |
| |
| <br><br> <DT><CODE>EINVAL</CODE> |
| <DD> |
| The memory range given was outside the user mmap range or wasn't page |
| aligned. |
| <br><br> |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-msync" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="void *address"/> |
| <parameter content="size_t length"/> |
| <parameter content="int flags"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/mman.h"/> |
| </headers> |
| <synopsis> |
| <br><br> When using shared mappings, the kernel can write the file at any time |
| before the mapping is removed. To be certain data has actually been |
| written to the file and will be accessible to non-memory-mapped I/O, it |
| is necessary to use this function. |
| <br><br> It operates on the region <VAR>address</VAR> to (<VAR>address</VAR> + <VAR>length</VAR>). |
| It may be used on part of a mapping or multiple mappings, however the |
| region given should not contain any unmapped space. |
| <br><br> <VAR>flags</VAR> can contain some options: |
| <br><br> <DL> |
| |
| <br><br> <DT><CODE>MS_SYNC</CODE> |
| <DD> |
| <br><br> This flag makes sure the data is actually written <EM>to disk</EM>. |
| Normally <CODE>msync</CODE> only makes sure that accesses to a file with |
| conventional I/O reflect the recent changes. |
| <br><br> <DT><CODE>MS_ASYNC</CODE> |
| <DD> |
| <br><br> This tells <CODE>msync</CODE> to begin the synchronization, but not to wait for |
| it to complete. |
| <br><br> <br><br> </DL> |
| <br><br> <CODE>msync</CODE> returns 0 for success and -1 for |
| error. Errors include: |
| <br><br> <DL> |
| |
| <br><br> <DT><CODE>EINVAL</CODE> |
| <DD> |
| An invalid region was given, or the <VAR>flags</VAR> were invalid. |
| <br><br> <LI> EFAULT |
| There is no existing mapping in at least part of the given region. |
| <br><br> |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-mremap" type="function"> |
| <function returntype="void *"> |
| <prototype> |
| <parameter content="void *address"/> |
| <parameter content="size_t length"/> |
| <parameter content="size_t new_length"/> |
| <parameter content="int flag"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/mman.h"/> |
| </headers> |
| <synopsis> |
| <br><br> This function can be used to change the size of an existing memory |
| area. <VAR>address</VAR> and <VAR>length</VAR> must cover a region entirely mapped |
| in the same <CODE>mmap</CODE> statement. A new mapping with the same |
| characteristics will be returned with the length <VAR>new_length</VAR>. |
| <br><br> One option is possible, <CODE>MREMAP_MAYMOVE</CODE>. If it is given in |
| <VAR>flags</VAR>, the system may remove the existing mapping and create a new |
| one of the desired length in another location. |
| <br><br> The address of the resulting mapping is returned, or -1. Possible |
| error codes include: |
| <br><br> <DL> |
| |
| <br><br> <DT><CODE>EFAULT</CODE> |
| <DD> |
| There is no existing mapping in at least part of the original region, or |
| the region covers two or more distinct mappings. |
| <br><br> <LI> EINVAL |
| The address given is misaligned or inappropriate. |
| <br><br> <LI> EAGAIN |
| The region has pages locked, and if extended it would exceed the |
| process's resource limit for locked pages. . |
| <br><br> <LI> ENOMEM |
| The region is private writable, and insufficient virtual memory is |
| available to extend it. Also, this error will occur if |
| <CODE>MREMAP_MAYMOVE</CODE> is not given and the extension would collide with |
| another mapped region. |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-madvise" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="void *addr"/> |
| <parameter content="size_t length"/> |
| <parameter content="int advice"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/mman.h"/> |
| </headers> |
| <synopsis> |
| <br><br> This function can be used to provide the system with <VAR>advice</VAR> about |
| the intended usage patterns of the memory region starting at <VAR>addr</VAR> |
| and extending <VAR>length</VAR> bytes. |
| <br><br> The valid BSD values for <VAR>advice</VAR> are: |
| <br><br> <DL> |
| |
| <br><br> <DT><CODE>MADV_NORMAL</CODE> |
| <DD> |
| The region should receive no further special treatment. |
| <br><br> <DT><CODE>MADV_RANDOM</CODE> |
| <DD> |
| The region will be accessed via random page references. The kernel |
| should page-in the minimal number of pages for each page fault. |
| <br><br> <DT><CODE>MADV_SEQUENTIAL</CODE> |
| <DD> |
| The region will be accessed via sequential page references. This |
| may cause the kernel to aggressively read-ahead, expecting further |
| sequential references after any page fault within this region. |
| <br><br> <LI> MADV_WILLNEED |
| The region will be needed. The pages within this region may |
| be pre-faulted in by the kernel. |
| <br><br> <LI> MADV_DONTNEED |
| The region is no longer needed. The kernel may free these pages, |
| causing any changes to the pages to be lost, as well as swapped |
| out pages to be discarded. |
| <br><br> |
| <br><br> The POSIX names are slightly different, but with the same meanings: |
| <br><br> <DL> |
| |
| <br><br> <LI> POSIX_MADV_NORMAL |
| This corresponds with BSD's <CODE>MADV_NORMAL</CODE>. |
| <br><br> <LI> POSIX_MADV_RANDOM |
| This corresponds with BSD's <CODE>MADV_RANDOM</CODE>. |
| <br><br> <LI> POSIX_MADV_SEQUENTIAL |
| This corresponds with BSD's <CODE>MADV_SEQUENTIAL</CODE>. |
| <br><br> <LI> POSIX_MADV_WILLNEED |
| This corresponds with BSD's <CODE>MADV_WILLNEED</CODE>. |
| <br><br> <LI> POSIX_MADV_DONTNEED |
| This corresponds with BSD's <CODE>MADV_DONTNEED</CODE>. |
| <br><br> |
| <br><br> <CODE>msync</CODE> returns 0 for success and -1 for |
| error. Errors include: |
| <DL> |
| |
| <br><br> <LI> EINVAL |
| An invalid region was given, or the <VAR>advice</VAR> was invalid. |
| <br><br> <LI> EFAULT |
| There is no existing mapping in at least part of the given region. |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="dtype-fd_set" type="dtype"> |
| <structure> |
| </structure> |
| </construct> |
| <construct id="function-select" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int nfds"/> |
| <parameter content="fd_set *read-fds"/> |
| <parameter content="fd_set *write-fds"/> |
| <parameter content="fd_set *except-fds"/> |
| <parameter content="struct timeval *timeout"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/types.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>select</CODE> function blocks the calling process until there is |
| activity on any of the specified sets of file descriptors, or until the |
| timeout period has expired. |
| <br><br> The file descriptors specified by the <VAR>read-fds</VAR> argument are |
| checked to see if they are ready for reading; the <VAR>write-fds</VAR> file |
| descriptors are checked to see if they are ready for writing; and the |
| <VAR>except-fds</VAR> file descriptors are checked for exceptional |
| conditions. You can pass a null pointer for any of these arguments if |
| you are not interested in checking for that kind of condition. |
| <br><br> A file descriptor is considered ready for reading if a <CODE>read</CODE> |
| call will not block. This usually includes the read offset being at |
| the end of the file or there is an error to report. A server socket |
| is considered ready for reading if there is a pending connection which |
| can be accepted with <CODE>accept</CODE>; . A |
| client socket is ready for writing when its connection is fully |
| established; . |
| <br><br> ``Exceptional conditions'' does not mean errors---errors are reported |
| immediately when an erroneous system call is executed, and do not |
| constitute a state of the descriptor. Rather, they include conditions |
| such as the presence of an urgent message on a socket. (, |
| for information on urgent messages.) |
| <br><br> The <CODE>select</CODE> function checks only the first <VAR>nfds</VAR> file |
| descriptors. The usual thing is to pass <CODE>FD_SETSIZE</CODE> as the value |
| of this argument. |
| <br><br> The <VAR>timeout</VAR> specifies the maximum time to wait. If you pass a |
| null pointer for this argument, it means to block indefinitely until one |
| of the file descriptors is ready. Otherwise, you should provide the |
| time in <CODE>struct timeval</CODE> format; see High-Resolution |
| Calendar. Specify zero as the time (a <CODE>struct timeval</CODE> containing |
| all zeros) if you want to find out which descriptors are ready without |
| waiting if none are ready. |
| <br><br> The normal return value from <CODE>select</CODE> is the total number of ready file |
| descriptors in all of the sets. Each of the argument sets is overwritten |
| with information about the descriptors that are ready for the corresponding |
| operation. Thus, to see if a particular descriptor <VAR>desc</VAR> has input, |
| use <CODE>FD_ISSET (<VAR>desc</VAR>, <VAR>read-fds</VAR>)</CODE> after <CODE>select</CODE> returns. |
| <br><br> If <CODE>select</CODE> returns because the timeout period expires, it returns |
| a value of zero. |
| <br><br> Any signal will cause <CODE>select</CODE> to return immediately. So if your |
| program uses signals, you can't rely on <CODE>select</CODE> to keep waiting |
| for the full time specified. If you want to be sure of waiting for a |
| particular amount of time, you must check for <CODE>EINTR</CODE> and repeat |
| the <CODE>select</CODE> with a newly calculated timeout based on the current |
| time. See the example below. See also Interrupted Primitives. |
| <br><br> If an error occurs, <CODE>select</CODE> returns <CODE>-1</CODE> and does not modify |
| the argument file descriptor sets. The following <CODE>errno</CODE> error |
| conditions are defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EBADF</CODE> |
| <DD> |
| One of the file descriptor sets specified an invalid file descriptor. |
| <br><br> <LI> EINTR |
| The operation was interrupted by a signal. . |
| <br><br> <LI> EINVAL |
| The <VAR>timeout</VAR> argument is invalid; one of the components is negative |
| or too large. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-sync" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| A call to this function will not return as long as there is data which |
| has not been written to the device. All dirty buffers in the kernel will |
| be written and so an overall consistent system can be achieved (if no |
| other process in parallel writes data). |
| <br><br> A prototype for <CODE>sync</CODE> can be found in <TT>unistd.h</TT>. |
| <br><br> The return value is zero to indicate no error. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fsync" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int fildes"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>fsync</CODE> function can be used to make sure all data associated with |
| the open file <VAR>fildes</VAR> is written to the device associated with the |
| descriptor. The function call does not return unless all actions have |
| finished. |
| <br><br> A prototype for <CODE>fsync</CODE> can be found in <TT>unistd.h</TT>. |
| <br><br> This function is a cancellation point in multi-threaded programs. This |
| is a problem if the thread allocates some resources (like memory, file |
| descriptors, semaphores or whatever) at the time <CODE>fsync</CODE> is |
| called. If the thread gets canceled these resources stay allocated |
| until the program ends. To avoid this, calls to <CODE>fsync</CODE> should be |
| protected using cancellation handlers. |
| <br><br> The return value of the function is zero if no error occurred. Otherwise |
| it is -1 and the global variable <VAR>errno</VAR> is set to the |
| following values: |
| <DL> |
| |
| <DT><CODE>EBADF</CODE> |
| <DD> |
| The descriptor <VAR>fildes</VAR> is not valid. |
| <br><br> <LI> EINVAL |
| No synchronization is possible since the system does not implement this. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fdatasync" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int fildes"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| When a call to the <CODE>fdatasync</CODE> function returns, it is ensured |
| that all of the file data is written to the device. For all pending I/O |
| operations, the parts guaranteeing data integrity finished. |
| <br><br> Not all systems implement the <CODE>fdatasync</CODE> operation. On systems |
| missing this functionality <CODE>fdatasync</CODE> is emulated by a call to |
| <CODE>fsync</CODE> since the performed actions are a superset of those |
| required by <CODE>fdatasync</CODE>. |
| <br><br> The prototype for <CODE>fdatasync</CODE> is in <TT>unistd.h</TT>. |
| <br><br> The return value of the function is zero if no error occurred. Otherwise |
| it is -1 and the global variable <VAR>errno</VAR> is set to the |
| following values: |
| <DL> |
| |
| <DT><CODE>EBADF</CODE> |
| <DD> |
| The descriptor <VAR>fildes</VAR> is not valid. |
| <br><br> <LI> EINVAL |
| No synchronization is possible since the system does not implement this. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="struct-aiocb" type="struct"> |
| <structure> |
| <synopsis> |
| The POSIX.1b standard mandates that the <CODE>struct aiocb</CODE> 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><br> |
| </synopsis> |
| <elements> |
| <element content="int aio_fildes"> |
| <synopsis> |
| This element specifies the file descriptor to be used for the |
| operation. It must be a legal descriptor, otherwise the operation will |
| fail. |
| <br><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 <CODE>lseek</CODE> call would lead to an error. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="off_t aio_offset"> |
| <synopsis> |
| 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><br> |
| </synopsis> |
| </element> |
| <element content="volatile void *aio_buf"> |
| <synopsis> |
| This is a pointer to the buffer with the data to be written or the place |
| where the read data is stored. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="size_t aio_nbytes"> |
| <synopsis> |
| This element specifies the length of the buffer pointed to by <CODE>aio_buf</CODE>. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="int aio_reqprio"> |
| <synopsis> |
| If the platform has defined <CODE>_POSIX_PRIORITIZED_IO</CODE> and |
| <CODE>_POSIX_PRIORITY_SCHEDULING</CODE>, the AIO requests are |
| processed based on the current scheduling priority. The |
| <CODE>aio_reqprio</CODE> element can then be used to lower the priority of the |
| AIO operation. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="struct sigevent aio_sigevent"> |
| <synopsis> |
| This element specifies how the calling process is notified once the |
| operation terminates. If the <CODE>sigev_notify</CODE> element is |
| <CODE>SIGEV_NONE</CODE>, no notification is sent. If it is <CODE>SIGEV_SIGNAL</CODE>, |
| the signal determined by <CODE>sigev_signo</CODE> is sent. Otherwise, |
| <CODE>sigev_notify</CODE> must be <CODE>SIGEV_THREAD</CODE>. In this case, a thread |
| is created which starts executing the function pointed to by |
| <CODE>sigev_notify_function</CODE>. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="int aio_lio_opcode"> |
| <synopsis> |
| This element is only used by the <CODE>lio_listio</CODE> and |
| <CODE>lio_listio64</CODE> 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><br> <DL> |
| |
| </synopsis> |
| </element> |
| <element content="LIO_READ"> |
| <synopsis> |
| Start a read operation. Read from the file at position |
| <CODE>aio_offset</CODE> and store the next <CODE>aio_nbytes</CODE> bytes in the |
| buffer pointed to by <CODE>aio_buf</CODE>. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="LIO_WRITE"> |
| <synopsis> |
| Start a write operation. Write <CODE>aio_nbytes</CODE> bytes starting at |
| <CODE>aio_buf</CODE> into the file starting at position <CODE>aio_offset</CODE>. |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="struct-aiocb64" type="struct"> |
| <structure> |
| <elements> |
| <element content="int aio_fildes"> |
| <synopsis> |
| 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><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 <CODE>lseek</CODE> call would lead to an error. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="off64_t aio_offset"> |
| <synopsis> |
| 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><br> |
| </synopsis> |
| </element> |
| <element content="volatile void *aio_buf"> |
| <synopsis> |
| This is a pointer to the buffer with the data to be written or the place |
| where the read data is stored. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="size_t aio_nbytes"> |
| <synopsis> |
| This element specifies the length of the buffer pointed to by <CODE>aio_buf</CODE>. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="int aio_reqprio"> |
| <synopsis> |
| If for the platform <CODE>_POSIX_PRIORITIZED_IO</CODE> and |
| <CODE>_POSIX_PRIORITY_SCHEDULING</CODE> are defined the AIO requests are |
| processed based on the current scheduling priority. The |
| <CODE>aio_reqprio</CODE> element can then be used to lower the priority of the |
| AIO operation. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="struct sigevent aio_sigevent"> |
| <synopsis> |
| This element specifies how the calling process is notified once the |
| operation terminates. If the <CODE>sigev_notify</CODE>, element is |
| <CODE>SIGEV_NONE</CODE> no notification is sent. If it is <CODE>SIGEV_SIGNAL</CODE>, |
| the signal determined by <CODE>sigev_signo</CODE> is sent. Otherwise, |
| <CODE>sigev_notify</CODE> must be <CODE>SIGEV_THREAD</CODE> in which case a thread |
| which starts executing the function pointed to by |
| <CODE>sigev_notify_function</CODE>. |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="function-aio_read" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="struct aiocb *aiocbp"/> |
| </prototype> |
| <headers> |
| <header filename = "aio.h"/> |
| </headers> |
| <synopsis> |
| This function initiates an asynchronous read operation. It |
| immediately returns after the operation was enqueued or when an |
| error was encountered. |
| <br><br> The first <CODE>aiocbp->aio_nbytes</CODE> bytes of the file for which |
| <CODE>aiocbp->aio_fildes</CODE> is a descriptor are written to the buffer |
| starting at <CODE>aiocbp->aio_buf</CODE>. Reading starts at the absolute |
| position <CODE>aiocbp->aio_offset</CODE> in the file. |
| <br><br> If prioritized I/O is supported by the platform the |
| <CODE>aiocbp->aio_reqprio</CODE> value is used to adjust the priority before |
| the request is actually enqueued. |
| <br><br> The calling process is notified about the termination of the read |
| request according to the <CODE>aiocbp->aio_sigevent</CODE> value. |
| <br><br> When <CODE>aio_read</CODE> returns, the return value is zero if no error |
| occurred that can be found before the process is enqueued. If such an |
| early error is found, the function returns -1 and sets |
| <CODE>errno</CODE> to one of the following values: |
| <br><br> <DL> |
| |
| <DT><CODE>EAGAIN</CODE> |
| <DD> |
| The request was not enqueued due to (temporarily) exceeded resource |
| limitations. |
| <DT><CODE>ENOSYS</CODE> |
| <DD> |
| The <CODE>aio_read</CODE> function is not implemented. |
| <LI> EBADF |
| The <CODE>aiocbp->aio_fildes</CODE> descriptor is not valid. This condition |
| need not be recognized before enqueueing the request and so this error |
| might also be signaled asynchronously. |
| <LI> EINVAL |
| The <CODE>aiocbp->aio_offset</CODE> or <CODE>aiocbp->aio_reqpiro</CODE> value is |
| invalid. This condition need not be recognized before enqueueing the |
| request and so this error might also be signaled asynchronously. |
| |
| <br><br> If <CODE>aio_read</CODE> returns zero, the current status of the request |
| can be queried using <CODE>aio_error</CODE> and <CODE>aio_return</CODE> functions. |
| As long as the value returned by <CODE>aio_error</CODE> is <CODE>EINPROGRESS</CODE> |
| the operation has not yet completed. If <CODE>aio_error</CODE> returns zero, |
| the operation successfully terminated, otherwise the value is to be |
| interpreted as an error code. If the function terminated, the result of |
| the operation can be obtained using a call to <CODE>aio_return</CODE>. The |
| returned value is the same as an equivalent call to <CODE>read</CODE> would |
| have returned. Possible error codes returned by <CODE>aio_error</CODE> are: |
| <br><br> <DL> |
| |
| <LI> EBADF |
| The <CODE>aiocbp->aio_fildes</CODE> descriptor is not valid. |
| <LI> ECANCELED |
| The operation was canceled before the operation was finished |
| |
| <LI> EINVAL |
| The <CODE>aiocbp->aio_offset</CODE> value is invalid. |
| |
| <br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> this |
| function is in fact <CODE>aio_read64</CODE> since the LFS interface transparently |
| replaces the normal implementation. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-aio_read64" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="struct aiocb *aiocbp"/> |
| </prototype> |
| <headers> |
| <header filename = "aio.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to the <CODE>aio_read</CODE> function. The only |
| difference is that on 32 bit machines, the file descriptor should |
| be opened in the large file mode. Internally, <CODE>aio_read64</CODE> uses |
| functionality equivalent to <CODE>lseek64</CODE> to position the file descriptor correctly for the reading, |
| as opposed to <CODE>lseek</CODE> functionality used in <CODE>aio_read</CODE>. |
| <br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE>, this |
| function is available under the name <CODE>aio_read</CODE> and so transparently |
| replaces the interface for small files on 32 bit machines. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-aio_write" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="struct aiocb *aiocbp"/> |
| </prototype> |
| <headers> |
| <header filename = "aio.h"/> |
| </headers> |
| <synopsis> |
| This function initiates an asynchronous write operation. The function |
| call immediately returns after the operation was enqueued or if before |
| this happens an error was encountered. |
| <br><br> The first <CODE>aiocbp->aio_nbytes</CODE> bytes from the buffer starting at |
| <CODE>aiocbp->aio_buf</CODE> are written to the file for which |
| <CODE>aiocbp->aio_fildes</CODE> is an descriptor, starting at the absolute |
| position <CODE>aiocbp->aio_offset</CODE> in the file. |
| <br><br> If prioritized I/O is supported by the platform, the |
| <CODE>aiocbp->aio_reqprio</CODE> value is used to adjust the priority before |
| the request is actually enqueued. |
| <br><br> The calling process is notified about the termination of the read |
| request according to the <CODE>aiocbp->aio_sigevent</CODE> value. |
| <br><br> When <CODE>aio_write</CODE> returns, the return value is zero if no error |
| occurred that can be found before the process is enqueued. If such an |
| early error is found the function returns -1 and sets |
| <CODE>errno</CODE> to one of the following values. |
| <br><br> <DL> |
| |
| <DT><CODE>EAGAIN</CODE> |
| <DD> |
| The request was not enqueued due to (temporarily) exceeded resource |
| limitations. |
| <DT><CODE>ENOSYS</CODE> |
| <DD> |
| The <CODE>aio_write</CODE> function is not implemented. |
| <LI> EBADF |
| The <CODE>aiocbp->aio_fildes</CODE> descriptor is not valid. This condition |
| may not be recognized before enqueueing the request, and so this error |
| might also be signaled asynchronously. |
| <LI> EINVAL |
| The <CODE>aiocbp->aio_offset</CODE> or <CODE>aiocbp->aio_reqprio</CODE> value is |
| invalid. This condition may not be recognized before enqueueing the |
| request and so this error might also be signaled asynchronously. |
| |
| <br><br> In the case <CODE>aio_write</CODE> returns zero, the current status of the |
| request can be queried using <CODE>aio_error</CODE> and <CODE>aio_return</CODE> |
| functions. As long as the value returned by <CODE>aio_error</CODE> is |
| <CODE>EINPROGRESS</CODE> the operation has not yet completed. If |
| <CODE>aio_error</CODE> returns zero, the operation successfully terminated, |
| otherwise the value is to be interpreted as an error code. If the |
| function terminated, the result of the operation can be get using a call |
| to <CODE>aio_return</CODE>. The returned value is the same as an equivalent |
| call to <CODE>read</CODE> would have returned. Possible error codes returned |
| by <CODE>aio_error</CODE> are: |
| <br><br> <DL> |
| |
| <LI> EBADF |
| The <CODE>aiocbp->aio_fildes</CODE> descriptor is not valid. |
| <LI> ECANCELED |
| The operation was canceled before the operation was finished. |
| |
| <LI> EINVAL |
| The <CODE>aiocbp->aio_offset</CODE> value is invalid. |
| |
| <br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE>, this |
| function is in fact <CODE>aio_write64</CODE> since the LFS interface transparently |
| replaces the normal implementation. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-aio_write64" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="struct aiocb *aiocbp"/> |
| </prototype> |
| <headers> |
| <header filename = "aio.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to the <CODE>aio_write</CODE> function. The only |
| difference is that on 32 bit machines the file descriptor should |
| be opened in the large file mode. Internally <CODE>aio_write64</CODE> uses |
| functionality equivalent to <CODE>lseek64</CODE> to position the file descriptor correctly for the writing, |
| as opposed to <CODE>lseek</CODE> functionality used in <CODE>aio_write</CODE>. |
| <br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE>, this |
| function is available under the name <CODE>aio_write</CODE> and so transparently |
| replaces the interface for small files on 32 bit machines. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-lio_listio" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int mode"/> |
| <parameter content="struct aiocb *const list[]"/> |
| <parameter content="int nent"/> |
| <parameter content="struct sigevent *sig"/> |
| </prototype> |
| <headers> |
| <header filename = "aio.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>lio_listio</CODE> function can be used to enqueue an arbitrary |
| number of read and write requests at one time. The requests can all be |
| meant for the same file, all for different files or every solution in |
| between. |
| <br><br> <CODE>lio_listio</CODE> gets the <VAR>nent</VAR> requests from the array pointed to |
| by <VAR>list</VAR>. The operation to be performed is determined by the |
| <CODE>aio_lio_opcode</CODE> member in each element of <VAR>list</VAR>. If this |
| field is <CODE>LIO_READ</CODE> a read operation is enqueued, similar to a call |
| of <CODE>aio_read</CODE> for this element of the array (except that the way |
| the termination is signalled is different, as we will see below). If |
| the <CODE>aio_lio_opcode</CODE> member is <CODE>LIO_WRITE</CODE> a write operation |
| is enqueued. Otherwise the <CODE>aio_lio_opcode</CODE> must be <CODE>LIO_NOP</CODE> |
| in which case this element of <VAR>list</VAR> is simply ignored. This |
| ``operation'' is useful in situations where one has a fixed array of |
| <CODE>struct aiocb</CODE> elements from which only a few need to be handled at |
| a time. Another situation is where the <CODE>lio_listio</CODE> call was |
| canceled before all requests are processed and the remaining requests have to be reissued. |
| <br><br> The other members of each element of the array pointed to by |
| <CODE>list</CODE> must have values suitable for the operation as described in |
| the documentation for <CODE>aio_read</CODE> and <CODE>aio_write</CODE> above. |
| <br><br> The <VAR>mode</VAR> argument determines how <CODE>lio_listio</CODE> behaves after |
| having enqueued all the requests. If <VAR>mode</VAR> is <CODE>LIO_WAIT</CODE> it |
| waits until all requests terminated. Otherwise <VAR>mode</VAR> must be |
| <CODE>LIO_NOWAIT</CODE> and in this case the function returns immediately after |
| having enqueued all the requests. In this case the caller gets a |
| notification of the termination of all requests according to the |
| <VAR>sig</VAR> parameter. If <VAR>sig</VAR> is <CODE>NULL</CODE> no notification is |
| send. Otherwise a signal is sent or a thread is started, just as |
| described in the description for <CODE>aio_read</CODE> or <CODE>aio_write</CODE>. |
| <br><br> If <VAR>mode</VAR> is <CODE>LIO_WAIT</CODE>, the return value of <CODE>lio_listio</CODE> |
| is 0 when all requests completed successfully. Otherwise the |
| function return -1 and <CODE>errno</CODE> is set accordingly. To find |
| out which request or requests failed one has to use the <CODE>aio_error</CODE> |
| function on all the elements of the array <VAR>list</VAR>. |
| <br><br> In case <VAR>mode</VAR> is <CODE>LIO_NOWAIT</CODE>, the function returns 0 if |
| all requests were enqueued correctly. The current state of the requests |
| can be found using <CODE>aio_error</CODE> and <CODE>aio_return</CODE> as described |
| above. If <CODE>lio_listio</CODE> returns -1 in this mode, the |
| global variable <CODE>errno</CODE> is set accordingly. If a request did not |
| yet terminate, a call to <CODE>aio_error</CODE> returns <CODE>EINPROGRESS</CODE>. If |
| the value is different, the request is finished and the error value (or |
| 0) is returned and the result of the operation can be retrieved |
| using <CODE>aio_return</CODE>. |
| <br><br> Possible values for <CODE>errno</CODE> are: |
| <br><br> <DL> |
| |
| <DT><CODE>EAGAIN</CODE> |
| <DD> |
| The resources necessary to queue all the requests are not available at |
| the moment. The error status for each element of <VAR>list</VAR> must be |
| checked to determine which request failed. |
| <br><br> Another reason could be that the system wide limit of AIO requests is |
| exceeded. This cannot be the case for the implementation on GNU systems |
| since no arbitrary limits exist. |
| <LI> EINVAL |
| The <VAR>mode</VAR> parameter is invalid or <VAR>nent</VAR> is larger than |
| <CODE>AIO_LISTIO_MAX</CODE>. |
| <LI> EIO |
| One or more of the request's I/O operations failed. The error status of |
| each request should be checked to determine which one failed. |
| <LI> ENOSYS |
| The <CODE>lio_listio</CODE> function is not supported. |
| |
| <br><br> If the <VAR>mode</VAR> parameter is <CODE>LIO_NOWAIT</CODE> and the caller cancels |
| a request, the error status for this request returned by |
| <CODE>aio_error</CODE> is <CODE>ECANCELED</CODE>. |
| <br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE>, this |
| function is in fact <CODE>lio_listio64</CODE> since the LFS interface |
| transparently replaces the normal implementation. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-lio_listio64" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int mode"/> |
| <parameter content="struct aiocb *const list"/> |
| <parameter content="int nent"/> |
| <parameter content="struct sigevent *sig"/> |
| </prototype> |
| <headers> |
| <header filename = "aio.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to the <CODE>lio_listio</CODE> function. The only |
| difference is that on 32 bit machines, the file descriptor should |
| be opened in the large file mode. Internally, <CODE>lio_listio64</CODE> uses |
| functionality equivalent to <CODE>lseek64</CODE> to position the file descriptor correctly for the reading or |
| writing, as opposed to <CODE>lseek</CODE> functionality used in |
| <CODE>lio_listio</CODE>. |
| <br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE>, this |
| function is available under the name <CODE>lio_listio</CODE> and so |
| transparently replaces the interface for small files on 32 bit |
| machines. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-aio_error" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const struct aiocb *aiocbp"/> |
| </prototype> |
| <headers> |
| <header filename = "aio.h"/> |
| </headers> |
| <synopsis> |
| This function determines the error state of the request described by the |
| <CODE>struct aiocb</CODE> variable pointed to by <VAR>aiocbp</VAR>. If the |
| request has not yet terminated the value returned is always |
| <CODE>EINPROGRESS</CODE>. Once the request has terminated the value |
| <CODE>aio_error</CODE> returns is either 0 if the request completed |
| successfully or it returns the value which would be stored in the |
| <CODE>errno</CODE> variable if the request would have been done using |
| <CODE>read</CODE>, <CODE>write</CODE>, or <CODE>fsync</CODE>. |
| <br><br> The function can return <CODE>ENOSYS</CODE> if it is not implemented. It |
| could also return <CODE>EINVAL</CODE> if the <VAR>aiocbp</VAR> parameter does not |
| refer to an asynchronous operation whose return status is not yet known. |
| <br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> this |
| function is in fact <CODE>aio_error64</CODE> since the LFS interface |
| transparently replaces the normal implementation. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-aio_error64" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const struct aiocb64 *aiocbp"/> |
| </prototype> |
| <headers> |
| <header filename = "aio.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to <CODE>aio_error</CODE> with the only difference |
| that the argument is a reference to a variable of type <CODE>struct |
| aiocb64</CODE>. |
| <br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> this |
| function is available under the name <CODE>aio_error</CODE> and so |
| transparently replaces the interface for small files on 32 bit |
| machines. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-aio_return" type="function"> |
| <function returntype="ssize_t"> |
| <prototype> |
| <parameter content="const struct aiocb *aiocbp"/> |
| </prototype> |
| <headers> |
| <header filename = "aio.h"/> |
| </headers> |
| <synopsis> |
| This function can be used to retrieve the return status of the operation |
| carried out by the request described in the variable pointed to by |
| <VAR>aiocbp</VAR>. As long as the error status of this request as returned |
| by <CODE>aio_error</CODE> is <CODE>EINPROGRESS</CODE> the return of this function is |
| undefined. |
| <br><br> Once the request is finished this function can be used exactly once to |
| retrieve the return value. Following calls might lead to undefined |
| behavior. The return value itself is the value which would have been |
| returned by the <CODE>read</CODE>, <CODE>write</CODE>, or <CODE>fsync</CODE> call. |
| <br><br> The function can return <CODE>ENOSYS</CODE> if it is not implemented. It |
| could also return <CODE>EINVAL</CODE> if the <VAR>aiocbp</VAR> parameter does not |
| refer to an asynchronous operation whose return status is not yet known. |
| <br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> this |
| function is in fact <CODE>aio_return64</CODE> since the LFS interface |
| transparently replaces the normal implementation. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-aio_return64" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const struct aiocb64 *aiocbp"/> |
| </prototype> |
| <headers> |
| <header filename = "aio.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to <CODE>aio_return</CODE> with the only difference |
| that the argument is a reference to a variable of type <CODE>struct |
| aiocb64</CODE>. |
| <br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> this |
| function is available under the name <CODE>aio_return</CODE> and so |
| transparently replaces the interface for small files on 32 bit |
| machines. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-aio_fsync" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int op"/> |
| <parameter content="struct aiocb *aiocbp"/> |
| </prototype> |
| <headers> |
| <header filename = "aio.h"/> |
| </headers> |
| <synopsis> |
| Calling this function forces all I/O operations operating queued at the |
| time of the function call operating on the file descriptor |
| <CODE>aiocbp->aio_fildes</CODE> into the synchronized I/O completion state |
| . The <CODE>aio_fsync</CODE> function returns |
| immediately but the notification through the method described in |
| <CODE>aiocbp->aio_sigevent</CODE> will happen only after all requests for this |
| file descriptor have terminated and the file is synchronized. This also |
| means that requests for this very same file descriptor which are queued |
| after the synchronization request are not affected. |
| <br><br> If <VAR>op</VAR> is <CODE>O_DSYNC</CODE> the synchronization happens as with a call |
| to <CODE>fdatasync</CODE>. Otherwise <VAR>op</VAR> should be <CODE>O_SYNC</CODE> and |
| the synchronization happens as with <CODE>fsync</CODE>. |
| <br><br> As long as the synchronization has not happened, a call to |
| <CODE>aio_error</CODE> with the reference to the object pointed to by |
| <VAR>aiocbp</VAR> returns <CODE>EINPROGRESS</CODE>. Once the synchronization is |
| done <CODE>aio_error</CODE> return 0 if the synchronization was not |
| successful. Otherwise the value returned is the value to which the |
| <CODE>fsync</CODE> or <CODE>fdatasync</CODE> function would have set the |
| <CODE>errno</CODE> variable. In this case nothing can be assumed about the |
| consistency for the data written to this file descriptor. |
| <br><br> The return value of this function is 0 if the request was |
| successfully enqueued. Otherwise the return value is -1 and |
| <CODE>errno</CODE> is set to one of the following values: |
| <br><br> <DL> |
| |
| <DT><CODE>EAGAIN</CODE> |
| <DD> |
| The request could not be enqueued due to temporary lack of resources. |
| <LI> EBADF |
| The file descriptor <CODE>aiocbp->aio_fildes</CODE> is not valid or not open |
| for writing. |
| <LI> EINVAL |
| The implementation does not support I/O synchronization or the <VAR>op</VAR> |
| parameter is other than <CODE>O_DSYNC</CODE> and <CODE>O_SYNC</CODE>. |
| <LI> ENOSYS |
| This function is not implemented. |
| |
| <br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> this |
| function is in fact <CODE>aio_fsync64</CODE> since the LFS interface |
| transparently replaces the normal implementation. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-aio_fsync64" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int op"/> |
| <parameter content="struct aiocb64 *aiocbp"/> |
| </prototype> |
| <headers> |
| <header filename = "aio.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to <CODE>aio_fsync</CODE> with the only difference |
| that the argument is a reference to a variable of type <CODE>struct |
| aiocb64</CODE>. |
| <br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> this |
| function is available under the name <CODE>aio_fsync</CODE> and so |
| transparently replaces the interface for small files on 32 bit |
| machines. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-aio_suspend" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const struct aiocb *const list[]"/> |
| <parameter content="int nent"/> |
| <parameter content="const struct timespec *timeout"/> |
| </prototype> |
| <headers> |
| <header filename = "aio.h"/> |
| </headers> |
| <synopsis> |
| When calling this function, the calling thread is suspended until at |
| least one of the requests pointed to by the <VAR>nent</VAR> elements of the |
| array <VAR>list</VAR> has completed. If any of the requests has already |
| completed at the time <CODE>aio_suspend</CODE> is called, the function returns |
| immediately. Whether a request has terminated or not is determined by |
| comparing the error status of the request with <CODE>EINPROGRESS</CODE>. If |
| an element of <VAR>list</VAR> is <CODE>NULL</CODE>, the entry is simply ignored. |
| <br><br> If no request has finished, the calling process is suspended. If |
| <VAR>timeout</VAR> is <CODE>NULL</CODE>, the process is not woken until a request |
| has finished. If <VAR>timeout</VAR> is not <CODE>NULL</CODE>, the process remains |
| suspended at least as long as specified in <VAR>timeout</VAR>. In this case, |
| <CODE>aio_suspend</CODE> returns with an error. |
| <br><br> The return value of the function is 0 if one or more requests |
| from the <VAR>list</VAR> have terminated. Otherwise the function returns |
| -1 and <CODE>errno</CODE> is set to one of the following values: |
| <br><br> <DL> |
| |
| <DT><CODE>EAGAIN</CODE> |
| <DD> |
| None of the requests from the <VAR>list</VAR> completed in the time specified |
| by <VAR>timeout</VAR>. |
| <LI> EINTR |
| A signal interrupted the <CODE>aio_suspend</CODE> function. This signal might |
| also be sent by the AIO implementation while signalling the termination |
| of one of the requests. |
| <LI> ENOSYS |
| The <CODE>aio_suspend</CODE> function is not implemented. |
| |
| <br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> this |
| function is in fact <CODE>aio_suspend64</CODE> since the LFS interface |
| transparently replaces the normal implementation. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-aio_suspend64" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const struct aiocb64 *const list[]"/> |
| <parameter content="int nent"/> |
| <parameter content="const struct timespec *timeout"/> |
| </prototype> |
| <headers> |
| <header filename = "aio.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to <CODE>aio_suspend</CODE> with the only difference |
| that the argument is a reference to a variable of type <CODE>struct |
| aiocb64</CODE>. |
| <br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> this |
| function is available under the name <CODE>aio_suspend</CODE> and so |
| transparently replaces the interface for small files on 32 bit |
| machines. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-aio_cancel" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int fildes"/> |
| <parameter content="struct aiocb *aiocbp"/> |
| </prototype> |
| <headers> |
| <header filename = "aio.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>aio_cancel</CODE> function can be used to cancel one or more |
| outstanding requests. If the <VAR>aiocbp</VAR> parameter is <CODE>NULL</CODE>, the |
| function tries to cancel all of the outstanding requests which would process |
| the file descriptor <VAR>fildes</VAR> (i.e., whose <CODE>aio_fildes</CODE> member |
| is <VAR>fildes</VAR>). If <VAR>aiocbp</VAR> is not <CODE>NULL</CODE>, <CODE>aio_cancel</CODE> |
| attempts to cancel the specific request pointed to by <VAR>aiocbp</VAR>. |
| <br><br> For requests which were successfully canceled, the normal notification |
| about the termination of the request should take place. I.e., depending |
| on the <CODE>struct sigevent</CODE> object which controls this, nothing |
| happens, a signal is sent or a thread is started. If the request cannot |
| be canceled, it terminates the usual way after performing the operation. |
| <br><br> After a request is successfully canceled, a call to <CODE>aio_error</CODE> with |
| a reference to this request as the parameter will return |
| <CODE>ECANCELED</CODE> and a call to <CODE>aio_return</CODE> will return -1. |
| If the request wasn't canceled and is still running the error status is |
| still <CODE>EINPROGRESS</CODE>. |
| <br><br> The return value of the function is <CODE>AIO_CANCELED</CODE> if there were |
| requests which haven't terminated and which were successfully canceled. |
| If there is one or more requests left which couldn't be canceled, the |
| return value is <CODE>AIO_NOTCANCELED</CODE>. In this case <CODE>aio_error</CODE> |
| must be used to find out which of the, perhaps multiple, requests (in |
| <VAR>aiocbp</VAR> is <CODE>NULL</CODE>) weren't successfully canceled. If all |
| requests already terminated at the time <CODE>aio_cancel</CODE> is called the |
| return value is <CODE>AIO_ALLDONE</CODE>. |
| <br><br> If an error occurred during the execution of <CODE>aio_cancel</CODE> the |
| function returns -1 and sets <CODE>errno</CODE> to one of the following |
| values. |
| <br><br> <DL> |
| |
| <DT><CODE>EBADF</CODE> |
| <DD> |
| The file descriptor <VAR>fildes</VAR> is not valid. |
| <LI> ENOSYS |
| <CODE>aio_cancel</CODE> is not implemented. |
| |
| <br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE>, this |
| function is in fact <CODE>aio_cancel64</CODE> since the LFS interface |
| transparently replaces the normal implementation. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-aio_cancel64" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int fildes"/> |
| <parameter content="struct aiocb64 *aiocbp"/> |
| </prototype> |
| <headers> |
| <header filename = "aio.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to <CODE>aio_cancel</CODE> with the only difference |
| that the argument is a reference to a variable of type <CODE>struct |
| aiocb64</CODE>. |
| <br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE>, this |
| function is available under the name <CODE>aio_cancel</CODE> and so |
| transparently replaces the interface for small files on 32 bit |
| machines. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="struct-aioinit" type="struct"> |
| <structure> |
| <synopsis> |
| 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 <CODE>aio_init</CODE> |
| function. |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="int aio_threads"> |
| <synopsis> |
| This member specifies the maximal number of threads which may be used |
| at any one time. |
| </synopsis> |
| </element> |
| <element content="int aio_num"> |
| <synopsis> |
| This number provides an estimate on the maximal number of simultaneously |
| enqueued requests. |
| </synopsis> |
| </element> |
| <element content="int aio_locks"> |
| <synopsis> |
| Unused. |
| </synopsis> |
| </element> |
| <element content="int aio_usedba"> |
| <synopsis> |
| Unused. |
| </synopsis> |
| </element> |
| <element content="int aio_debug"> |
| <synopsis> |
| Unused. |
| </synopsis> |
| </element> |
| <element content="int aio_numusers"> |
| <synopsis> |
| Unused. |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="function-aio_init" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="const struct aioinit *init"/> |
| </prototype> |
| <headers> |
| <header filename = "aio.h"/> |
| </headers> |
| <synopsis> |
| This function must be called before any other AIO function. Calling it |
| is completely voluntary, as it is only meant to help the AIO |
| implementation perform better. |
| <br><br> Before calling the <CODE>aio_init</CODE>, function the members of a variable of |
| type <CODE>struct aioinit</CODE> must be initialized. Then a reference to |
| this variable is passed as the parameter to <CODE>aio_init</CODE> which itself |
| may or may not pay attention to the hints. |
| <br><br> The function has no return value and no error cases are defined. It is |
| a extension which follows a proposal from the SGI implementation in |
| Irix 6. It is not covered by POSIX.1b or Unix98. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fcntl" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int filedes"/> |
| <parameter content="int command"/> |
| <parameter content="..."/> |
| </prototype> |
| <headers> |
| <header filename = "fcntl.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>fcntl</CODE> function performs the operation specified by |
| <VAR>command</VAR> on the file descriptor <VAR>filedes</VAR>. Some commands |
| require additional arguments to be supplied. These additional arguments |
| and the return value and error conditions are given in the detailed |
| descriptions of the individual commands. |
| <br><br> Briefly, here is a list of what the various commands are. |
| <br><br> <DL> |
| |
| <DT><CODE>F_DUPFD</CODE> |
| <DD> |
| Duplicate the file descriptor (return another file descriptor pointing |
| to the same open file). . |
| <br><br> <LI> F_GETFD |
| Get flags associated with the file descriptor. . |
| <br><br> <LI> F_SETFD |
| Set flags associated with the file descriptor. . |
| <br><br> <LI> F_GETFL |
| Get flags associated with the open file. . |
| <br><br> <LI> F_SETFL |
| Set flags associated with the open file. . |
| <br><br> <LI> F_GETLK |
| Get a file lock. . |
| <br><br> <LI> F_SETLK |
| Set or clear a file lock. . |
| <br><br> <LI> F_SETLKW |
| Like <CODE>F_SETLK</CODE>, but wait for completion. . |
| <br><br> <LI> F_GETOWN |
| Get process or process group ID to receive <CODE>SIGIO</CODE> signals. |
| . |
| <br><br> <LI> F_SETOWN |
| Set process or process group ID to receive <CODE>SIGIO</CODE> signals. |
| . |
| |
| <br><br> This function is a cancellation point in multi-threaded programs. This |
| is a problem if the thread allocates some resources (like memory, file |
| descriptors, semaphores or whatever) at the time <CODE>fcntl</CODE> is |
| called. If the thread gets canceled these resources stay allocated |
| until the program ends. To avoid this calls to <CODE>fcntl</CODE> should be |
| protected using cancellation handlers. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-dup" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int old"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| This function copies descriptor <VAR>old</VAR> to the first available |
| descriptor number (the first number not currently open). It is |
| equivalent to <CODE>fcntl (<VAR>old</VAR>, F_DUPFD, 0)</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-dup2" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int old"/> |
| <parameter content="int new"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| This function copies the descriptor <VAR>old</VAR> to descriptor number |
| <VAR>new</VAR>. |
| <br><br> If <VAR>old</VAR> is an invalid descriptor, then <CODE>dup2</CODE> does nothing; it |
| does not close <VAR>new</VAR>. Otherwise, the new duplicate of <VAR>old</VAR> |
| replaces any previous meaning of descriptor <VAR>new</VAR>, as if <VAR>new</VAR> |
| were closed first. |
| <br><br> If <VAR>old</VAR> and <VAR>new</VAR> are different numbers, and <VAR>old</VAR> is a |
| valid descriptor number, then <CODE>dup2</CODE> is equivalent to: |
| <br><br> <pre><br> |
| close (<VAR>new</VAR>);<br> |
| fcntl (<VAR>old</VAR>, F_DUPFD, <VAR>new</VAR>)<br> |
| </pre> |
| <br><br> However, <CODE>dup2</CODE> does this atomically; there is no instant in the |
| middle of calling <CODE>dup2</CODE> at which <VAR>new</VAR> is closed and not yet a |
| duplicate of <VAR>old</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="struct-flock" type="struct"> |
| <structure> |
| <synopsis> |
| This structure is used with the <CODE>fcntl</CODE> function to describe a file |
| lock. It has these members: |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="short int l_type"> |
| <synopsis> |
| Specifies the type of the lock; one of <CODE>F_RDLCK</CODE>, <CODE>F_WRLCK</CODE>, or |
| <CODE>F_UNLCK</CODE>. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="short int l_whence"> |
| <synopsis> |
| This corresponds to the <VAR>whence</VAR> argument to <CODE>fseek</CODE> or |
| <CODE>lseek</CODE>, and specifies what the offset is relative to. Its value |
| can be one of <CODE>SEEK_SET</CODE>, <CODE>SEEK_CUR</CODE>, or <CODE>SEEK_END</CODE>. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="off_t l_start"> |
| <synopsis> |
| 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 |
| <CODE>l_whence</CODE> member. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="off_t l_len"> |
| <synopsis> |
| This specifies the length of the region to be locked. A value of |
| <CODE>0</CODE> is treated specially; it means the region extends to the end of |
| the file. |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="function-ioctl" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int filedes"/> |
| <parameter content="int command"/> |
| <parameter content="..."/> |
| </prototype> |
| <headers> |
| <header filename = "fcntl.h"/> |
| <header filename = "sys/ioctl.h"/> |
| </headers> |
| <synopsis> |
| <br><br> The <CODE>ioctl</CODE> function performs the generic I/O operation |
| <VAR>command</VAR> on <VAR>filedes</VAR>. |
| <br><br> A third argument is usually present, either a single number or a pointer |
| to a structure. The meaning of this argument, the returned value, and |
| any error codes depends upon the command used. Often -1 is |
| returned for a failure. |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-strlen" type="function"> |
| <function returntype="size_t"> |
| <prototype> |
| <parameter content="const char *s"/> |
| </prototype> |
| <headers> |
| <header filename = "string.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>strlen</CODE> function returns the length of the null-terminated |
| string <VAR>s</VAR> in bytes. (In other words, it returns the offset of the |
| terminating null character within the array.) |
| <br><br> For example, |
| <pre><br> |
| strlen ("hello, world")<br> |
| 12<br> |
| </pre><br> |
| <br><br> When applied to a character array, the <CODE>strlen</CODE> function returns<br> |
| the length of the string stored there, not its allocated size. You can<br> |
| get the allocated size of the character array that holds a string using<br> |
| the <CODE>sizeof</CODE> operator:<br> |
| <br><br> <pre><br> |
| char string[32] = "hello, world";<br> |
| sizeof (string)<br> |
| 32<br> |
| strlen (string)<br> |
| 12<br> |
| </pre><br> |
| <br><br> But beware, this will not work unless <VAR>string</VAR> is the character<br> |
| array itself, not a pointer to it. For example:<br> |
| <br><br> <pre><br> |
| char string[32] = "hello, world";<br> |
| char *ptr = string;<br> |
| sizeof (string)<br> |
| 32<br> |
| sizeof (ptr)<br> |
| 4 /* (on a machine with 4 byte pointers) */<br> |
| </pre><br> |
| <br><br> This is an easy mistake to make when you are working with functions that<br> |
| take string arguments; those arguments are always pointers, not arrays.<br> |
| <br><br> It must also be noted that for multibyte encoded strings the return<br> |
| value does not have to correspond to the number of characters in the<br> |
| string. To get this value the string can be converted to wide<br> |
| characters and <CODE>wcslen</CODE> can be used or something like the following<br> |
| code can be used:<br> |
| <br><br> <pre><br> |
| /* The input is in <CODE>string</CODE>.<br> |
| The length is expected in <CODE>n</CODE>. */<br> |
| {<br> |
| mbstate_t t;<br> |
| char *scopy = string;<br> |
| /* In initial state. */<br> |
| memset (&t, '\0', sizeof (t));<br> |
| /* Determine number of characters. */<br> |
| n = mbsrtowcs (NULL, &scopy, strlen (scopy), &t);<br> |
| }<br> |
| </pre> |
| <br><br> This is cumbersome to do so if the number of characters (as opposed to |
| bytes) is needed often it is better to work with wide characters. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-wcslen" type="function"> |
| <function returntype="size_t"> |
| <prototype> |
| <parameter content="const wchar_t *ws"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>wcslen</CODE> function is the wide character equivalent to |
| <CODE>strlen</CODE>. The return value is the number of wide characters in the |
| wide character string pointed to by <VAR>ws</VAR> (this is also the offset of |
| the terminating null wide character of <VAR>ws</VAR>). |
| <br><br> Since there are no multi wide character sequences making up one |
| character the return value is not only the offset in the array, it is |
| also the number of wide characters. |
| <br><br> This function was introduced in Amendment 1 to ISO C90. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-strnlen" type="function"> |
| <function returntype="size_t"> |
| <prototype> |
| <parameter content="const char *s"/> |
| <parameter content="size_t maxlen"/> |
| </prototype> |
| <headers> |
| <header filename = "string.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>strnlen</CODE> function returns the length of the string <VAR>s</VAR> in |
| bytes if this length is smaller than <VAR>maxlen</VAR> bytes. Otherwise it |
| returns <VAR>maxlen</VAR>. Therefore this function is equivalent to |
| <CODE>(strlen (<VAR>s</VAR>) < n ? strlen (<VAR>s</VAR>) : <VAR>maxlen</VAR>)</CODE> but it |
| is more efficient and works even if the string <VAR>s</VAR> is not |
| null-terminated. |
| <br><br> <pre><br> |
| char string[32] = "hello, world";<br> |
| strnlen (string, 32)<br> |
| 12<br> |
| strnlen (string, 5)<br> |
| 5<br> |
| </pre> |
| <br><br> This function is a GNU extension and is declared in <TT>string.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-wcsnlen" type="function"> |
| <function returntype="size_t"> |
| <prototype> |
| <parameter content="const wchar_t *ws"/> |
| <parameter content="size_t maxlen"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| <CODE>wcsnlen</CODE> is the wide character equivalent to <CODE>strnlen</CODE>. The |
| <VAR>maxlen</VAR> parameter specifies the maximum number of wide characters. |
| <br><br> This function is a GNU extension and is declared in <TT>wchar.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-memcpy" type="function"> |
| <function returntype="void *"> |
| <prototype> |
| <parameter content="void *restrict to"/> |
| <parameter content="const void *restrict from"/> |
| <parameter content="size_t size"/> |
| </prototype> |
| <headers> |
| <header filename = "string.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>memcpy</CODE> function copies <VAR>size</VAR> bytes from the object |
| beginning at <VAR>from</VAR> into the object beginning at <VAR>to</VAR>. The |
| behavior of this function is undefined if the two arrays <VAR>to</VAR> and |
| <VAR>from</VAR> overlap; use <CODE>memmove</CODE> instead if overlapping is possible. |
| <br><br> The value returned by <CODE>memcpy</CODE> is the value of <VAR>to</VAR>. |
| <br><br> Here is an example of how you might use <CODE>memcpy</CODE> to copy the |
| contents of an array: |
| <br><br> <pre><br> |
| struct foo *oldarray, *newarray;<br> |
| int arraysize;<br> |
| <small>...</small><br> |
| memcpy (new, old, arraysize * sizeof (struct foo));<br> |
| </pre> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-wmemcpy" type="function"> |
| <function returntype="wchar_t *"> |
| <prototype> |
| <parameter content="wchar_t *restrict wto"/> |
| <parameter content="const wchar_t *restrict wfrom"/> |
| <parameter content="size_t size"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>wmemcpy</CODE> function copies <VAR>size</VAR> wide characters from the object |
| beginning at <VAR>wfrom</VAR> into the object beginning at <VAR>wto</VAR>. The |
| behavior of this function is undefined if the two arrays <VAR>wto</VAR> and |
| <VAR>wfrom</VAR> overlap; use <CODE>wmemmove</CODE> instead if overlapping is possible. |
| <br><br> The following is a possible implementation of <CODE>wmemcpy</CODE> but there |
| are more optimizations possible. |
| <br><br> <pre><br> |
| wchar_t *<br> |
| wmemcpy (wchar_t *restrict wto, const wchar_t *restrict wfrom,<br> |
| size_t size)<br> |
| {<br> |
| return (wchar_t *) memcpy (wto, wfrom, size * sizeof (wchar_t));<br> |
| }<br> |
| </pre> |
| <br><br> The value returned by <CODE>wmemcpy</CODE> is the value of <VAR>wto</VAR>. |
| <br><br> This function was introduced in Amendment 1 to ISO C90. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-mempcpy" type="function"> |
| <function returntype="void *"> |
| <prototype> |
| <parameter content="void *restrict to"/> |
| <parameter content="const void *restrict from"/> |
| <parameter content="size_t size"/> |
| </prototype> |
| <headers> |
| <header filename = "string.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>mempcpy</CODE> function is nearly identical to the <CODE>memcpy</CODE> |
| function. It copies <VAR>size</VAR> bytes from the object beginning at |
| <CODE>from</CODE> into the object pointed to by <VAR>to</VAR>. But instead of |
| returning the value of <VAR>to</VAR> it returns a pointer to the byte |
| following the last written byte in the object beginning at <VAR>to</VAR>. |
| I.e., the value is <CODE>((void *) ((char *) <VAR>to</VAR> + <VAR>size</VAR>))</CODE>. |
| <br><br> This function is useful in situations where a number of objects shall be |
| copied to consecutive memory positions. |
| <br><br> <pre><br> |
| void *<br> |
| combine (void *o1, size_t s1, void *o2, size_t s2)<br> |
| {<br> |
| void *result = malloc (s1 + s2);<br> |
| if (result != NULL)<br> |
| mempcpy (mempcpy (result, o1, s1), o2, s2);<br> |
| return result;<br> |
| }<br> |
| </pre> |
| <br><br> This function is a GNU extension. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-wmempcpy" type="function"> |
| <function returntype="wchar_t *"> |
| <prototype> |
| <parameter content="wchar_t *restrict wto"/> |
| <parameter content="const wchar_t *restrict wfrom"/> |
| <parameter content="size_t size"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>wmempcpy</CODE> function is nearly identical to the <CODE>wmemcpy</CODE> |
| function. It copies <VAR>size</VAR> wide characters from the object |
| beginning at <CODE>wfrom</CODE> into the object pointed to by <VAR>wto</VAR>. But |
| instead of returning the value of <VAR>wto</VAR> it returns a pointer to the |
| wide character following the last written wide character in the object |
| beginning at <VAR>wto</VAR>. I.e., the value is <CODE><VAR>wto</VAR> + <VAR>size</VAR></CODE>. |
| <br><br> This function is useful in situations where a number of objects shall be |
| copied to consecutive memory positions. |
| <br><br> The following is a possible implementation of <CODE>wmemcpy</CODE> but there |
| are more optimizations possible. |
| <br><br> <pre><br> |
| wchar_t *<br> |
| wmempcpy (wchar_t *restrict wto, const wchar_t *restrict wfrom,<br> |
| size_t size)<br> |
| {<br> |
| return (wchar_t *) mempcpy (wto, wfrom, size * sizeof (wchar_t));<br> |
| }<br> |
| </pre> |
| <br><br> This function is a GNU extension. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-memmove" type="function"> |
| <function returntype="void *"> |
| <prototype> |
| <parameter content="void *to"/> |
| <parameter content="const void *from"/> |
| <parameter content="size_t size"/> |
| </prototype> |
| <headers> |
| <header filename = "string.h"/> |
| </headers> |
| <synopsis> |
| <CODE>memmove</CODE> copies the <VAR>size</VAR> bytes at <VAR>from</VAR> into the |
| <VAR>size</VAR> bytes at <VAR>to</VAR>, even if those two blocks of space |
| overlap. In the case of overlap, <CODE>memmove</CODE> is careful to copy the |
| original values of the bytes in the block at <VAR>from</VAR>, including those |
| bytes which also belong to the block at <VAR>to</VAR>. |
| <br><br> The value returned by <CODE>memmove</CODE> is the value of <VAR>to</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-wmemmove" type="function"> |
| <function returntype="wchar_t *"> |
| <prototype> |
| <parameter content="wchar *wto"/> |
| <parameter content="const wchar_t *wfrom"/> |
| <parameter content="size_t size"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| <CODE>wmemmove</CODE> copies the <VAR>size</VAR> wide characters at <VAR>wfrom</VAR> |
| into the <VAR>size</VAR> wide characters at <VAR>wto</VAR>, even if those two |
| blocks of space overlap. In the case of overlap, <CODE>memmove</CODE> is |
| careful to copy the original values of the wide characters in the block |
| at <VAR>wfrom</VAR>, including those wide characters which also belong to the |
| block at <VAR>wto</VAR>. |
| <br><br> The following is a possible implementation of <CODE>wmemcpy</CODE> but there |
| are more optimizations possible. |
| <br><br> <pre><br> |
| wchar_t *<br> |
| wmempcpy (wchar_t *restrict wto, const wchar_t *restrict wfrom,<br> |
| size_t size)<br> |
| {<br> |
| return (wchar_t *) mempcpy (wto, wfrom, size * sizeof (wchar_t));<br> |
| }<br> |
| </pre> |
| <br><br> The value returned by <CODE>wmemmove</CODE> is the value of <VAR>wto</VAR>. |
| <br><br> This function is a GNU extension. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-memccpy" type="function"> |
| <function returntype="void *"> |
| <prototype> |
| <parameter content="void *restrict to"/> |
| <parameter content="const void *restrict from"/> |
| <parameter content="int c"/> |
| <parameter content="size_t size"/> |
| </prototype> |
| <headers> |
| <header filename = "string.h"/> |
| </headers> |
| <synopsis> |
| This function copies no more than <VAR>size</VAR> bytes from <VAR>from</VAR> to |
| <VAR>to</VAR>, stopping if a byte matching <VAR>c</VAR> is found. The return |
| value is a pointer into <VAR>to</VAR> one byte past where <VAR>c</VAR> was copied, |
| or a null pointer if no byte matching <VAR>c</VAR> appeared in the first |
| <VAR>size</VAR> bytes of <VAR>from</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-memset" type="function"> |
| <function returntype="void *"> |
| <prototype> |
| <parameter content="void *block"/> |
| <parameter content="int c"/> |
| <parameter content="size_t size"/> |
| </prototype> |
| <headers> |
| <header filename = "string.h"/> |
| </headers> |
| <synopsis> |
| This function copies the value of <VAR>c</VAR> (converted to an |
| <CODE>unsigned char</CODE>) into each of the first <VAR>size</VAR> bytes of the |
| object beginning at <VAR>block</VAR>. It returns the value of <VAR>block</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-wmemset" type="function"> |
| <function returntype="wchar_t *"> |
| <prototype> |
| <parameter content="wchar_t *block"/> |
| <parameter content="wchar_t wc"/> |
| <parameter content="size_t size"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| This function copies the value of <VAR>wc</VAR> into each of the first |
| <VAR>size</VAR> wide characters of the object beginning at <VAR>block</VAR>. It |
| returns the value of <VAR>block</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-strcpy" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="char *restrict to"/> |
| <parameter content="const char *restrict from"/> |
| </prototype> |
| <headers> |
| <header filename = "string.h"/> |
| </headers> |
| <synopsis> |
| This copies characters from the string <VAR>from</VAR> (up to and including |
| the terminating null character) into the string <VAR>to</VAR>. Like |
| <CODE>memcpy</CODE>, this function has undefined results if the strings |
| overlap. The return value is the value of <VAR>to</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-wcscpy" type="function"> |
| <function returntype="wchar_t *"> |
| <prototype> |
| <parameter content="wchar_t *restrict wto"/> |
| <parameter content="const wchar_t *restrict wfrom"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| This copies wide characters from the string <VAR>wfrom</VAR> (up to and |
| including the terminating null wide character) into the string |
| <VAR>wto</VAR>. Like <CODE>wmemcpy</CODE>, this function has undefined results if |
| the strings overlap. The return value is the value of <VAR>wto</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-strncpy" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="char *restrict to"/> |
| <parameter content="const char *restrict from"/> |
| <parameter content="size_t size"/> |
| </prototype> |
| <headers> |
| <header filename = "string.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to <CODE>strcpy</CODE> but always copies exactly |
| <VAR>size</VAR> characters into <VAR>to</VAR>. |
| <br><br> If the length of <VAR>from</VAR> is more than <VAR>size</VAR>, then <CODE>strncpy</CODE> |
| copies just the first <VAR>size</VAR> characters. Note that in this case |
| there is no null terminator written into <VAR>to</VAR>. |
| <br><br> If the length of <VAR>from</VAR> is less than <VAR>size</VAR>, then <CODE>strncpy</CODE> |
| copies all of <VAR>from</VAR>, followed by enough null characters to add up |
| to <VAR>size</VAR> characters in all. This behavior is rarely useful, but it |
| is specified by the ISO C standard. |
| <br><br> The behavior of <CODE>strncpy</CODE> is undefined if the strings overlap. |
| <br><br> Using <CODE>strncpy</CODE> as opposed to <CODE>strcpy</CODE> is a way to avoid bugs |
| relating to writing past the end of the allocated space for <VAR>to</VAR>. |
| However, it can also make your program much slower in one common case: |
| copying a string which is probably small into a potentially large buffer. |
| In this case, <VAR>size</VAR> may be large, and when it is, <CODE>strncpy</CODE> will |
| waste a considerable amount of time copying null characters. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-wcsncpy" type="function"> |
| <function returntype="wchar_t *"> |
| <prototype> |
| <parameter content="wchar_t *restrict wto"/> |
| <parameter content="const wchar_t *restrict wfrom"/> |
| <parameter content="size_t size"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to <CODE>wcscpy</CODE> but always copies exactly |
| <VAR>size</VAR> wide characters into <VAR>wto</VAR>. |
| <br><br> If the length of <VAR>wfrom</VAR> is more than <VAR>size</VAR>, then |
| <CODE>wcsncpy</CODE> copies just the first <VAR>size</VAR> wide characters. Note |
| that in this case there is no null terminator written into <VAR>wto</VAR>. |
| <br><br> If the length of <VAR>wfrom</VAR> is less than <VAR>size</VAR>, then |
| <CODE>wcsncpy</CODE> copies all of <VAR>wfrom</VAR>, followed by enough null wide |
| characters to add up to <VAR>size</VAR> wide characters in all. This |
| behavior is rarely useful, but it is specified by the ISO C |
| standard. |
| <br><br> The behavior of <CODE>wcsncpy</CODE> is undefined if the strings overlap. |
| <br><br> Using <CODE>wcsncpy</CODE> as opposed to <CODE>wcscpy</CODE> is a way to avoid bugs |
| relating to writing past the end of the allocated space for <VAR>wto</VAR>. |
| However, it can also make your program much slower in one common case: |
| copying a string which is probably small into a potentially large buffer. |
| In this case, <VAR>size</VAR> may be large, and when it is, <CODE>wcsncpy</CODE> will |
| waste a considerable amount of time copying null wide characters. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-strdup" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="const char *s"/> |
| </prototype> |
| <headers> |
| <header filename = "string.h"/> |
| </headers> |
| <synopsis> |
| This function copies the null-terminated string <VAR>s</VAR> into a newly |
| allocated string. The string is allocated using <CODE>malloc</CODE>; see |
| Unconstrained Allocation. If <CODE>malloc</CODE> cannot allocate space |
| for the new string, <CODE>strdup</CODE> returns a null pointer. Otherwise it |
| returns a pointer to the new string. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-wcsdup" type="function"> |
| <function returntype="wchar_t *"> |
| <prototype> |
| <parameter content="const wchar_t *ws"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| This function copies the null-terminated wide character string <VAR>ws</VAR> |
| into a newly allocated string. The string is allocated using |
| <CODE>malloc</CODE>; see Unconstrained Allocation. If <CODE>malloc</CODE> |
| cannot allocate space for the new string, <CODE>wcsdup</CODE> returns a null |
| pointer. Otherwise it returns a pointer to the new wide character |
| string. |
| <br><br> This function is a GNU extension. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-strndup" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="const char *s"/> |
| <parameter content="size_t size"/> |
| </prototype> |
| <headers> |
| <header filename = "string.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to <CODE>strdup</CODE> but always copies at most |
| <VAR>size</VAR> characters into the newly allocated string. |
| <br><br> If the length of <VAR>s</VAR> is more than <VAR>size</VAR>, then <CODE>strndup</CODE> |
| copies just the first <VAR>size</VAR> characters and adds a closing null |
| terminator. Otherwise all characters are copied and the string is |
| terminated. |
| <br><br> This function is different to <CODE>strncpy</CODE> in that it always |
| terminates the destination string. |
| <br><br> <CODE>strndup</CODE> is a GNU extension. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-stpcpy" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="char *restrict to"/> |
| <parameter content="const char *restrict from"/> |
| </prototype> |
| <headers> |
| <header filename = "string.h"/> |
| </headers> |
| <synopsis> |
| This function is like <CODE>strcpy</CODE>, except that it returns a pointer to |
| the end of the string <VAR>to</VAR> (that is, the address of the terminating |
| null character <CODE>to + strlen (from)</CODE>) rather than the beginning. |
| <br><br> For example, this program uses <CODE>stpcpy</CODE> to concatenate <samp>foo</samp> |
| and <samp>bar</samp> to produce <samp>foobar</samp>, which it then prints. |
| <br><br> <pre><br> |
| #include &lt;string.h&gt;<br> |
| #include &lt;stdio.h&gt;<br> |
| <br><br> int<br> |
| main (void)<br> |
| {<br> |
| char buffer[10];<br> |
| char *to = buffer;<br> |
| to = stpcpy (to, "foo");<br> |
| to = stpcpy (to, "bar");<br> |
| puts (buffer);<br> |
| return 0;<br> |
| }<br> |
| </pre> |
| <br><br> This function is not part of the ISO or POSIX standards, and is not |
| customary on Unix systems, but we did not invent it either. Perhaps it |
| comes from MS-DOG. |
| <br><br> Its behavior is undefined if the strings overlap. The function is |
| declared in <TT>string.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-wcpcpy" type="function"> |
| <function returntype="wchar_t *"> |
| <prototype> |
| <parameter content="wchar_t *restrict wto"/> |
| <parameter content="const wchar_t *restrict wfrom"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| This function is like <CODE>wcscpy</CODE>, except that it returns a pointer to |
| the end of the string <VAR>wto</VAR> (that is, the address of the terminating |
| null character <CODE>wto + strlen (wfrom)</CODE>) rather than the beginning. |
| <br><br> This function is not part of ISO or POSIX but was found useful while |
| developing the GNU C Library itself. |
| <br><br> The behavior of <CODE>wcpcpy</CODE> is undefined if the strings overlap. |
| <br><br> <CODE>wcpcpy</CODE> is a GNU extension and is declared in <TT>wchar.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-stpncpy" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="char *restrict to"/> |
| <parameter content="const char *restrict from"/> |
| <parameter content="size_t size"/> |
| </prototype> |
| <headers> |
| <header filename = "string.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to <CODE>stpcpy</CODE> but copies always exactly |
| <VAR>size</VAR> characters into <VAR>to</VAR>. |
| <br><br> If the length of <VAR>from</VAR> is more then <VAR>size</VAR>, then <CODE>stpncpy</CODE> |
| copies just the first <VAR>size</VAR> characters and returns a pointer to the |
| character directly following the one which was copied last. Note that in |
| this case there is no null terminator written into <VAR>to</VAR>. |
| <br><br> If the length of <VAR>from</VAR> is less than <VAR>size</VAR>, then <CODE>stpncpy</CODE> |
| copies all of <VAR>from</VAR>, followed by enough null characters to add up |
| to <VAR>size</VAR> characters in all. This behavior is rarely useful, but it |
| is implemented to be useful in contexts where this behavior of the |
| <CODE>strncpy</CODE> is used. <CODE>stpncpy</CODE> returns a pointer to the |
| <EM>first</EM> written null character. |
| <br><br> This function is not part of ISO or POSIX but was found useful while |
| developing the GNU C Library itself. |
| <br><br> Its behavior is undefined if the strings overlap. The function is |
| declared in <TT>string.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-wcpncpy" type="function"> |
| <function returntype="wchar_t *"> |
| <prototype> |
| <parameter content="wchar_t *restrict wto"/> |
| <parameter content="const wchar_t *restrict wfrom"/> |
| <parameter content="size_t size"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to <CODE>wcpcpy</CODE> but copies always exactly |
| <VAR>wsize</VAR> characters into <VAR>wto</VAR>. |
| <br><br> If the length of <VAR>wfrom</VAR> is more then <VAR>size</VAR>, then |
| <CODE>wcpncpy</CODE> copies just the first <VAR>size</VAR> wide characters and |
| returns a pointer to the wide character directly following the last |
| non-null wide character which was copied last. Note that in this case |
| there is no null terminator written into <VAR>wto</VAR>. |
| <br><br> If the length of <VAR>wfrom</VAR> is less than <VAR>size</VAR>, then <CODE>wcpncpy</CODE> |
| copies all of <VAR>wfrom</VAR>, followed by enough null characters to add up |
| to <VAR>size</VAR> characters in all. This behavior is rarely useful, but it |
| is implemented to be useful in contexts where this behavior of the |
| <CODE>wcsncpy</CODE> is used. <CODE>wcpncpy</CODE> returns a pointer to the |
| <EM>first</EM> written null character. |
| <br><br> This function is not part of ISO or POSIX but was found useful while |
| developing the GNU C Library itself. |
| <br><br> Its behavior is undefined if the strings overlap. |
| <br><br> <CODE>wcpncpy</CODE> is a GNU extension and is declared in <TT>wchar.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-strcat" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="char *restrict to"/> |
| <parameter content="const char *restrict from"/> |
| </prototype> |
| <headers> |
| <header filename = "string.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>strcat</CODE> function is similar to <CODE>strcpy</CODE>, except that the |
| characters from <VAR>from</VAR> are concatenated or appended to the end of |
| <VAR>to</VAR>, instead of overwriting it. That is, the first character from |
| <VAR>from</VAR> overwrites the null character marking the end of <VAR>to</VAR>. |
| <br><br> An equivalent definition for <CODE>strcat</CODE> would be: |
| <br><br> <pre><br> |
| char *<br> |
| strcat (char *restrict to, const char *restrict from)<br> |
| {<br> |
| strcpy (to + strlen (to), from);<br> |
| return to;<br> |
| }<br> |
| </pre> |
| <br><br> This function has undefined results if the strings overlap. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-wcscat" type="function"> |
| <function returntype="wchar_t *"> |
| <prototype> |
| <parameter content="wchar_t *restrict wto"/> |
| <parameter content="const wchar_t *restrict wfrom"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>wcscat</CODE> function is similar to <CODE>wcscpy</CODE>, except that the |
| characters from <VAR>wfrom</VAR> are concatenated or appended to the end of |
| <VAR>wto</VAR>, instead of overwriting it. That is, the first character from |
| <VAR>wfrom</VAR> overwrites the null character marking the end of <VAR>wto</VAR>. |
| <br><br> An equivalent definition for <CODE>wcscat</CODE> would be: |
| <br><br> <pre><br> |
| wchar_t *<br> |
| wcscat (wchar_t *wto, const wchar_t *wfrom)<br> |
| {<br> |
| wcscpy (wto + wcslen (wto), wfrom);<br> |
| return wto;<br> |
| }<br> |
| </pre> |
| <br><br> This function has undefined results if the strings overlap. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-strncat" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="char *restrict to"/> |
| <parameter content="const char *restrict from"/> |
| <parameter content="size_t size"/> |
| </prototype> |
| <headers> |
| <header filename = "string.h"/> |
| </headers> |
| <synopsis> |
| This function is like <CODE>strcat</CODE> except that not more than <VAR>size</VAR> |
| characters from <VAR>from</VAR> are appended to the end of <VAR>to</VAR>. A |
| single null character is also always appended to <VAR>to</VAR>, so the total |
| allocated size of <VAR>to</VAR> must be at least <CODE><VAR>size</VAR> + 1</CODE> bytes |
| longer than its initial length. |
| <br><br> The <CODE>strncat</CODE> function could be implemented like this: |
| <br><br> <pre><br> |
| <br> |
| char *<br> |
| strncat (char *to, const char *from, size_t size)<br> |
| {<br> |
| to[strlen (to) + size] = '\0';<br> |
| strncpy (to + strlen (to), from, size);<br> |
| return to;<br> |
| }<br> |
| <br> |
| </pre> |
| <br><br> The behavior of <CODE>strncat</CODE> is undefined if the strings overlap. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-wcsncat" type="function"> |
| <function returntype="wchar_t *"> |
| <prototype> |
| <parameter content="wchar_t *restrict wto"/> |
| <parameter content="const wchar_t *restrict wfrom"/> |
| <parameter content="size_t size"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| This function is like <CODE>wcscat</CODE> except that not more than <VAR>size</VAR> |
| characters from <VAR>from</VAR> are appended to the end of <VAR>to</VAR>. A |
| single null character is also always appended to <VAR>to</VAR>, so the total |
| allocated size of <VAR>to</VAR> must be at least <CODE><VAR>size</VAR> + 1</CODE> bytes |
| longer than its initial length. |
| <br><br> The <CODE>wcsncat</CODE> function could be implemented like this: |
| <br><br> <pre><br> |
| <br> |
| wchar_t *<br> |
| wcsncat (wchar_t *restrict wto, const wchar_t *restrict wfrom,<br> |
| size_t size)<br> |
| {<br> |
| wto[wcslen (to) + size] = L'\0';<br> |
| wcsncpy (wto + wcslen (wto), wfrom, size);<br> |
| return wto;<br> |
| }<br> |
| <br> |
| </pre> |
| <br><br> The behavior of <CODE>wcsncat</CODE> is undefined if the strings overlap. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-bcopy" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="const void *from"/> |
| <parameter content="void *to"/> |
| <parameter content="size_t size"/> |
| </prototype> |
| <headers> |
| <header filename = "string.h"/> |
| </headers> |
| <synopsis> |
| This is a partially obsolete alternative for <CODE>memmove</CODE>, derived from |
| BSD. Note that it is not quite equivalent to <CODE>memmove</CODE>, because the |
| arguments are not in the same order and there is no return value. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-bzero" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="void *block"/> |
| <parameter content="size_t size"/> |
| </prototype> |
| <headers> |
| <header filename = "string.h"/> |
| </headers> |
| <synopsis> |
| This is a partially obsolete alternative for <CODE>memset</CODE>, derived from |
| BSD. Note that it is not as general as <CODE>memset</CODE>, because the only |
| value it can store is zero. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-memcmp" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const void *a1"/> |
| <parameter content="const void *a2"/> |
| <parameter content="size_t size"/> |
| </prototype> |
| <headers> |
| <header filename = "string.h"/> |
| </headers> |
| <synopsis> |
| The function <CODE>memcmp</CODE> compares the <VAR>size</VAR> bytes of memory |
| beginning at <VAR>a1</VAR> against the <VAR>size</VAR> bytes of memory beginning |
| at <VAR>a2</VAR>. The value returned has the same sign as the difference |
| between the first differing pair of bytes (interpreted as <CODE>unsigned |
| char</CODE> objects, then promoted to <CODE>int</CODE>). |
| <br><br> If the contents of the two blocks are equal, <CODE>memcmp</CODE> returns |
| <CODE>0</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-wmemcmp" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const wchar_t *a1"/> |
| <parameter content="const wchar_t *a2"/> |
| <parameter content="size_t size"/> |
| </prototype> |
| <headers> |
| <header filename = "wcjar.h"/> |
| </headers> |
| <synopsis> |
| The function <CODE>wmemcmp</CODE> compares the <VAR>size</VAR> wide characters |
| beginning at <VAR>a1</VAR> against the <VAR>size</VAR> wide characters beginning |
| at <VAR>a2</VAR>. The value returned is smaller than or larger than zero |
| depending on whether the first differing wide character is <VAR>a1</VAR> is |
| smaller or larger than the corresponding character in <VAR>a2</VAR>. |
| <br><br> If the contents of the two blocks are equal, <CODE>wmemcmp</CODE> returns |
| <CODE>0</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-strcmp" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *s1"/> |
| <parameter content="const char *s2"/> |
| </prototype> |
| <headers> |
| <header filename = "string.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>strcmp</CODE> function compares the string <VAR>s1</VAR> against |
| <VAR>s2</VAR>, returning a value that has the same sign as the difference |
| between the first differing pair of characters (interpreted as |
| <CODE>unsigned char</CODE> objects, then promoted to <CODE>int</CODE>). |
| <br><br> If the two strings are equal, <CODE>strcmp</CODE> returns <CODE>0</CODE>. |
| <br><br> A consequence of the ordering used by <CODE>strcmp</CODE> is that if <VAR>s1</VAR> |
| is an initial substring of <VAR>s2</VAR>, then <VAR>s1</VAR> is considered to be |
| ``less than'' <VAR>s2</VAR>. |
| <br><br> <CODE>strcmp</CODE> does not take sorting conventions of the language the |
| strings are written in into account. To get that one has to use |
| <CODE>strcoll</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-wcscmp" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const wchar_t *ws1"/> |
| <parameter content="const wchar_t *ws2"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| <br><br> The <CODE>wcscmp</CODE> function compares the wide character string <VAR>ws1</VAR> |
| against <VAR>ws2</VAR>. The value returned is smaller than or larger than zero |
| depending on whether the first differing wide character is <VAR>ws1</VAR> is |
| smaller or larger than the corresponding character in <VAR>ws2</VAR>. |
| <br><br> If the two strings are equal, <CODE>wcscmp</CODE> returns <CODE>0</CODE>. |
| <br><br> A consequence of the ordering used by <CODE>wcscmp</CODE> is that if <VAR>ws1</VAR> |
| is an initial substring of <VAR>ws2</VAR>, then <VAR>ws1</VAR> is considered to be |
| ``less than'' <VAR>ws2</VAR>. |
| <br><br> <CODE>wcscmp</CODE> does not take sorting conventions of the language the |
| strings are written in into account. To get that one has to use |
| <CODE>wcscoll</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-strcasecmp" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *s1"/> |
| <parameter content="const char *s2"/> |
| </prototype> |
| <headers> |
| <header filename = "string.h"/> |
| </headers> |
| <synopsis> |
| This function is like <CODE>strcmp</CODE>, except that differences in case are |
| ignored. How uppercase and lowercase characters are related is |
| determined by the currently selected locale. In the standard <CODE>"C"</CODE> |
| locale the characters "A and "a do not match but in a locale which |
| regards these characters as parts of the alphabet they do match. |
| <br><br> |
| <CODE>strcasecmp</CODE> is derived from BSD. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-wcscasecmp" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const wchar_t *ws1"/> |
| <parameter content="const wchar_T *ws2"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| This function is like <CODE>wcscmp</CODE>, except that differences in case are |
| ignored. How uppercase and lowercase characters are related is |
| determined by the currently selected locale. In the standard <CODE>"C"</CODE> |
| locale the characters "A and "a do not match but in a locale which |
| regards these characters as parts of the alphabet they do match. |
| <br><br> |
| <CODE>wcscasecmp</CODE> is a GNU extension. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-strncmp" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *s1"/> |
| <parameter content="const char *s2"/> |
| <parameter content="size_t size"/> |
| </prototype> |
| <headers> |
| <header filename = "string.h"/> |
| </headers> |
| <synopsis> |
| This function is the similar to <CODE>strcmp</CODE>, except that no more than |
| <VAR>size</VAR> characters are compared. In other words, if the two |
| strings are the same in their first <VAR>size</VAR> characters, the |
| return value is zero. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-wcsncmp" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const wchar_t *ws1"/> |
| <parameter content="const wchar_t *ws2"/> |
| <parameter content="size_t size"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| This function is the similar to <CODE>wcscmp</CODE>, except that no more than |
| <VAR>size</VAR> wide characters are compared. In other words, if the two |
| strings are the same in their first <VAR>size</VAR> wide characters, the |
| return value is zero. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-strncasecmp" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *s1"/> |
| <parameter content="const char *s2"/> |
| <parameter content="size_t n"/> |
| </prototype> |
| <headers> |
| <header filename = "string.h"/> |
| </headers> |
| <synopsis> |
| This function is like <CODE>strncmp</CODE>, except that differences in case |
| are ignored. Like <CODE>strcasecmp</CODE>, it is locale dependent how |
| uppercase and lowercase characters are related. |
| <br><br> |
| <CODE>strncasecmp</CODE> is a GNU extension. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-wcsncasecmp" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const wchar_t *ws1"/> |
| <parameter content="const wchar_t *s2"/> |
| <parameter content="size_t n"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| This function is like <CODE>wcsncmp</CODE>, except that differences in case |
| are ignored. Like <CODE>wcscasecmp</CODE>, it is locale dependent how |
| uppercase and lowercase characters are related. |
| <br><br> |
| <CODE>wcsncasecmp</CODE> is a GNU extension. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-strverscmp" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *s1"/> |
| <parameter content="const char *s2"/> |
| </prototype> |
| <headers> |
| <header filename = "string.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>strverscmp</CODE> function compares the string <VAR>s1</VAR> against |
| <VAR>s2</VAR>, considering them as holding indices/version numbers. Return |
| value follows the same conventions as found in the <CODE>strverscmp</CODE> |
| function. In fact, if <VAR>s1</VAR> and <VAR>s2</VAR> contain no digits, |
| <CODE>strverscmp</CODE> behaves like <CODE>strcmp</CODE>. |
| <br><br> Basically, we compare strings normally (character by character), until |
| we find a digit in each string - then we enter a special comparison |
| mode, where each sequence of digits is taken as a whole. If we reach the |
| end of these two parts without noticing a difference, we return to the |
| standard comparison mode. There are two types of numeric parts: |
| "integral" and "fractional" (those begin with a '0'). The types |
| of the numeric parts affect the way we sort them: |
| <br><br> <OL> |
| <LI> |
| integral/integral: we compare values as you would expect. |
| <br><br> <LI> |
| fractional/integral: the fractional part is less than the integral one. |
| Again, no surprise. |
| <br><br> <LI> |
| fractional/fractional: the things become a bit more complex. |
| If the common prefix contains only leading zeroes, the longest part is less |
| than the other one; else the comparison behaves normally. |
| </OL> |
| <br><br> <pre><br> |
| strverscmp ("no digit", "no digit")<br> |
| 0 /* same behavior as strcmp. */<br> |
| strverscmp ("item#99", "item#100")<br> |
| <0 /* same prefix, but 99 < 100. */<br> |
| strverscmp ("alpha1", "alpha001")<br> |
| >0 /* fractional part inferior to integral one. */<br> |
| strverscmp ("part1_f012", "part1_f01")<br> |
| >0 /* two fractional parts. */<br> |
| strverscmp ("foo.009", "foo.0")<br> |
| <0 /* idem, but with leading zeroes only. */<br> |
| </pre> |
| <br><br> This function is especially useful when dealing with filename sorting, |
| because filenames frequently hold indices/version numbers. |
| <br><br> <CODE>strverscmp</CODE> is a GNU extension. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-bcmp" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const void *a1"/> |
| <parameter content="const void *a2"/> |
| <parameter content="size_t size"/> |
| </prototype> |
| <headers> |
| <header filename = "string.h"/> |
| </headers> |
| <synopsis> |
| This is an obsolete alias for <CODE>memcmp</CODE>, derived from BSD. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-strcoll" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *s1"/> |
| <parameter content="const char *s2"/> |
| </prototype> |
| <headers> |
| <header filename = "string.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>strcoll</CODE> function is similar to <CODE>strcmp</CODE> but uses the |
| collating sequence of the current locale for collation (the |
| <CODE>LC_COLLATE</CODE> locale). |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-wcscoll" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const wchar_t *ws1"/> |
| <parameter content="const wchar_t *ws2"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>wcscoll</CODE> function is similar to <CODE>wcscmp</CODE> but uses the |
| collating sequence of the current locale for collation (the |
| <CODE>LC_COLLATE</CODE> locale). |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-strxfrm" type="function"> |
| <function returntype="size_t"> |
| <prototype> |
| <parameter content="char *restrict to"/> |
| <parameter content="const char *restrict from"/> |
| <parameter content="size_t size"/> |
| </prototype> |
| <headers> |
| <header filename = "string.h"/> |
| </headers> |
| <synopsis> |
| The function <CODE>strxfrm</CODE> transforms the string <VAR>from</VAR> using the |
| collation transformation determined by the locale currently selected for |
| collation, and stores the transformed string in the array <VAR>to</VAR>. Up |
| to <VAR>size</VAR> characters (including a terminating null character) are |
| stored. |
| <br><br> The behavior is undefined if the strings <VAR>to</VAR> and <VAR>from</VAR> |
| overlap; see Copying and Concatenation. |
| <br><br> The return value is the length of the entire transformed string. This |
| value is not affected by the value of <VAR>size</VAR>, but if it is greater |
| or equal than <VAR>size</VAR>, it means that the transformed string did not |
| entirely fit in the array <VAR>to</VAR>. In this case, only as much of the |
| string as actually fits was stored. To get the whole transformed |
| string, call <CODE>strxfrm</CODE> again with a bigger output array. |
| <br><br> The transformed string may be longer than the original string, and it |
| may also be shorter. |
| <br><br> If <VAR>size</VAR> is zero, no characters are stored in <VAR>to</VAR>. In this |
| case, <CODE>strxfrm</CODE> simply returns the number of characters that would |
| be the length of the transformed string. This is useful for determining |
| what size the allocated array should be. It does not matter what |
| <VAR>to</VAR> is if <VAR>size</VAR> is zero; <VAR>to</VAR> may even be a null pointer. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-wcsxfrm" type="function"> |
| <function returntype="size_t"> |
| <prototype> |
| <parameter content="wchar_t *restrict wto"/> |
| <parameter content="const wchar_t *wfrom"/> |
| <parameter content="size_t size"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| The function <CODE>wcsxfrm</CODE> transforms wide character string <VAR>wfrom</VAR> |
| using the collation transformation determined by the locale currently |
| selected for collation, and stores the transformed string in the array |
| <VAR>wto</VAR>. Up to <VAR>size</VAR> wide characters (including a terminating null |
| character) are stored. |
| <br><br> The behavior is undefined if the strings <VAR>wto</VAR> and <VAR>wfrom</VAR> |
| overlap; see Copying and Concatenation. |
| <br><br> The return value is the length of the entire transformed wide character |
| string. This value is not affected by the value of <VAR>size</VAR>, but if |
| it is greater or equal than <VAR>size</VAR>, it means that the transformed |
| wide character string did not entirely fit in the array <VAR>wto</VAR>. In |
| this case, only as much of the wide character string as actually fits |
| was stored. To get the whole transformed wide character string, call |
| <CODE>wcsxfrm</CODE> again with a bigger output array. |
| <br><br> The transformed wide character string may be longer than the original |
| wide character string, and it may also be shorter. |
| <br><br> If <VAR>size</VAR> is zero, no characters are stored in <VAR>to</VAR>. In this |
| case, <CODE>wcsxfrm</CODE> simply returns the number of wide characters that |
| would be the length of the transformed wide character string. This is |
| useful for determining what size the allocated array should be (remember |
| to multiply with <CODE>sizeof (wchar_t)</CODE>). It does not matter what |
| <VAR>wto</VAR> is if <VAR>size</VAR> is zero; <VAR>wto</VAR> may even be a null pointer. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-memchr" type="function"> |
| <function returntype="void *"> |
| <prototype> |
| <parameter content="const void *block"/> |
| <parameter content="int c"/> |
| <parameter content="size_t size"/> |
| </prototype> |
| <headers> |
| <header filename = "string.h"/> |
| </headers> |
| <synopsis> |
| This function finds the first occurrence of the byte <VAR>c</VAR> (converted |
| to an <CODE>unsigned char</CODE>) in the initial <VAR>size</VAR> bytes of the |
| object beginning at <VAR>block</VAR>. The return value is a pointer to the |
| located byte, or a null pointer if no match was found. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-wmemchr" type="function"> |
| <function returntype="wchar_t *"> |
| <prototype> |
| <parameter content="const wchar_t *block"/> |
| <parameter content="wchar_t wc"/> |
| <parameter content="size_t size"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| This function finds the first occurrence of the wide character <VAR>wc</VAR> |
| in the initial <VAR>size</VAR> wide characters of the object beginning at |
| <VAR>block</VAR>. The return value is a pointer to the located wide |
| character, or a null pointer if no match was found. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-rawmemchr" type="function"> |
| <function returntype="void *"> |
| <prototype> |
| <parameter content="const void *block"/> |
| <parameter content="int c"/> |
| </prototype> |
| <headers> |
| <header filename = "string.h"/> |
| </headers> |
| <synopsis> |
| Often the <CODE>memchr</CODE> function is used with the knowledge that the |
| byte <VAR>c</VAR> is available in the memory block specified by the |
| parameters. But this means that the <VAR>size</VAR> parameter is not really |
| needed and that the tests performed with it at runtime (to check whether |
| the end of the block is reached) are not needed. |
| <br><br> The <CODE>rawmemchr</CODE> function exists for just this situation which is |
| surprisingly frequent. The interface is similar to <CODE>memchr</CODE> except |
| that the <VAR>size</VAR> parameter is missing. The function will look beyond |
| the end of the block pointed to by <VAR>block</VAR> in case the programmer |
| made an error in assuming that the byte <VAR>c</VAR> is present in the block. |
| In this case the result is unspecified. Otherwise the return value is a |
| pointer to the located byte. |
| <br><br> This function is of special interest when looking for the end of a |
| string. Since all strings are terminated by a null byte a call like |
| <br><br> <pre><br> |
| rawmemchr (str, '\0')<br> |
| </pre> |
| <br><br> |
| will never go beyond the end of the string. |
| <br><br> This function is a GNU extension. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-memrchr" type="function"> |
| <function returntype="void *"> |
| <prototype> |
| <parameter content="const void *block"/> |
| <parameter content="int c"/> |
| <parameter content="size_t size"/> |
| </prototype> |
| <headers> |
| <header filename = "string.h"/> |
| </headers> |
| <synopsis> |
| The function <CODE>memrchr</CODE> is like <CODE>memchr</CODE>, except that it searches |
| backwards from the end of the block defined by <VAR>block</VAR> and <VAR>size</VAR> |
| (instead of forwards from the front). |
| <br><br> This function is a GNU extension. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-strchr" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="const char *string"/> |
| <parameter content="int c"/> |
| </prototype> |
| <headers> |
| <header filename = "string.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>strchr</CODE> function finds the first occurrence of the character |
| <VAR>c</VAR> (converted to a <CODE>char</CODE>) in the null-terminated string |
| beginning at <VAR>string</VAR>. The return value is a pointer to the located |
| character, or a null pointer if no match was found. |
| <br><br> For example, |
| <pre><br> |
| strchr ("hello, world", 'l')<br> |
| "llo, world"<br> |
| strchr ("hello, world", '?')<br> |
| NULL<br> |
| </pre> |
| <br><br> The terminating null character is considered to be part of the string, |
| so you can use this function get a pointer to the end of a string by |
| specifying a null character as the value of the <VAR>c</VAR> argument. It |
| would be better (but less portable) to use <CODE>strchrnul</CODE> in this |
| case, though. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-wcschr" type="function"> |
| <function returntype="wchar_t *"> |
| <prototype> |
| <parameter content="const wchar_t *wstring"/> |
| <parameter content="int wc"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>wcschr</CODE> function finds the first occurrence of the wide |
| character <VAR>wc</VAR> in the null-terminated wide character string |
| beginning at <VAR>wstring</VAR>. The return value is a pointer to the |
| located wide character, or a null pointer if no match was found. |
| <br><br> The terminating null character is considered to be part of the wide |
| character string, so you can use this function get a pointer to the end |
| of a wide character string by specifying a null wude character as the |
| value of the <VAR>wc</VAR> argument. It would be better (but less portable) |
| to use <CODE>wcschrnul</CODE> in this case, though. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-strchrnul" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="const char *string"/> |
| <parameter content="int c"/> |
| </prototype> |
| <headers> |
| <header filename = "string.h"/> |
| </headers> |
| <synopsis> |
| <CODE>strchrnul</CODE> is the same as <CODE>strchr</CODE> except that if it does |
| not find the character, it returns a pointer to string's terminating |
| null character rather than a null pointer. |
| <br><br> This function is a GNU extension. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-wcschrnul" type="function"> |
| <function returntype="wchar_t *"> |
| <prototype> |
| <parameter content="const wchar_t *wstring"/> |
| <parameter content="wchar_t wc"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| <CODE>wcschrnul</CODE> is the same as <CODE>wcschr</CODE> except that if it does not |
| find the wide character, it returns a pointer to wide character string's |
| terminating null wide character rather than a null pointer. |
| <br><br> This function is a GNU extension. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-strrchr" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="const char *string"/> |
| <parameter content="int c"/> |
| </prototype> |
| <headers> |
| <header filename = "string.h"/> |
| </headers> |
| <synopsis> |
| The function <CODE>strrchr</CODE> is like <CODE>strchr</CODE>, except that it searches |
| backwards from the end of the string <VAR>string</VAR> (instead of forwards |
| from the front). |
| <br><br> For example, |
| <pre><br> |
| strrchr ("hello, world", 'l')<br> |
| "ld"<br> |
| </pre> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-wcsrchr" type="function"> |
| <function returntype="wchar_t *"> |
| <prototype> |
| <parameter content="const wchar_t *wstring"/> |
| <parameter content="wchar_t c"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| The function <CODE>wcsrchr</CODE> is like <CODE>wcschr</CODE>, except that it searches |
| backwards from the end of the string <VAR>wstring</VAR> (instead of forwards |
| from the front). |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-strstr" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="const char *haystack"/> |
| <parameter content="const char *needle"/> |
| </prototype> |
| <headers> |
| <header filename = "string.h"/> |
| </headers> |
| <synopsis> |
| This is like <CODE>strchr</CODE>, except that it searches <VAR>haystack</VAR> for a |
| substring <VAR>needle</VAR> rather than just a single character. It |
| returns a pointer into the string <VAR>haystack</VAR> that is the first |
| character of the substring, or a null pointer if no match was found. If |
| <VAR>needle</VAR> is an empty string, the function returns <VAR>haystack</VAR>. |
| <br><br> For example, |
| <pre><br> |
| strstr ("hello, world", "l")<br> |
| "llo, world"<br> |
| strstr ("hello, world", "wo")<br> |
| "world"<br> |
| </pre> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-wcsstr" type="function"> |
| <function returntype="wchar_t *"> |
| <prototype> |
| <parameter content="const wchar_t *haystack"/> |
| <parameter content="const wchar_t *needle"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| This is like <CODE>wcschr</CODE>, except that it searches <VAR>haystack</VAR> for a |
| substring <VAR>needle</VAR> rather than just a single wide character. It |
| returns a pointer into the string <VAR>haystack</VAR> that is the first wide |
| character of the substring, or a null pointer if no match was found. If |
| <VAR>needle</VAR> is an empty string, the function returns <VAR>haystack</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-wcswcs" type="function"> |
| <function returntype="wchar_t *"> |
| <prototype> |
| <parameter content="const wchar_t *haystack"/> |
| <parameter content="const wchar_t *needle"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| <CODE>wcswcs</CODE> is an deprecated alias for <CODE>wcsstr</CODE>. This is the |
| name originally used in the X/Open Portability Guide before the |
| Amendment 1 to ISO C90 was published. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-strcasestr" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="const char *haystack"/> |
| <parameter content="const char *needle"/> |
| </prototype> |
| <headers> |
| <header filename = "string.h"/> |
| </headers> |
| <synopsis> |
| This is like <CODE>strstr</CODE>, except that it ignores case in searching for |
| the substring. Like <CODE>strcasecmp</CODE>, it is locale dependent how |
| uppercase and lowercase characters are related. |
| <br><br> <br><br> For example, |
| <pre><br> |
| strcasestr ("hello, world", "L")<br> |
| "llo, world"<br> |
| strcasestr ("hello, World", "wo")<br> |
| "World"<br> |
| </pre> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-memmem" type="function"> |
| <function returntype="void *"> |
| <prototype> |
| <parameter content="const void *haystack"/> |
| <parameter content="size_t haystack-len,const void *needle"/> |
| <parameter content="size_t needle-len"/> |
| </prototype> |
| <headers> |
| <header filename = "string.h"/> |
| </headers> |
| <synopsis> |
| This is like <CODE>strstr</CODE>, but <VAR>needle</VAR> and <VAR>haystack</VAR> are byte |
| arrays rather than null-terminated strings. <VAR>needle-len</VAR> is the |
| length of <VAR>needle</VAR> and <VAR>haystack-len</VAR> is the length of |
| <VAR>haystack</VAR>. |
| <br><br> This function is a GNU extension. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-strspn" type="function"> |
| <function returntype="size_t"> |
| <prototype> |
| <parameter content="const char *string"/> |
| <parameter content="const char *skipset"/> |
| </prototype> |
| <headers> |
| <header filename = "string.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>strspn</CODE> (``string span'') function returns the length of the |
| initial substring of <VAR>string</VAR> that consists entirely of characters that |
| are members of the set specified by the string <VAR>skipset</VAR>. The order |
| of the characters in <VAR>skipset</VAR> is not important. |
| <br><br> For example, |
| <pre><br> |
| strspn ("hello, world", "abcdefghijklmnopqrstuvwxyz")<br> |
| 5<br> |
| </pre> |
| <br><br> Note that ``character'' is here used in the sense of byte. In a string |
| using a multibyte character encoding (abstract) character consisting of |
| more than one byte are not treated as an entity. Each byte is treated |
| separately. The function is not locale-dependent. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-wcsspn" type="function"> |
| <function returntype="size_t"> |
| <prototype> |
| <parameter content="const wchar_t *wstring"/> |
| <parameter content="const wchar_t *skipset"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>wcsspn</CODE> (``wide character string span'') function returns the |
| length of the initial substring of <VAR>wstring</VAR> that consists entirely |
| of wide characters that are members of the set specified by the string |
| <VAR>skipset</VAR>. The order of the wide characters in <VAR>skipset</VAR> is not |
| important. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-strcspn" type="function"> |
| <function returntype="size_t"> |
| <prototype> |
| <parameter content="const char *string"/> |
| <parameter content="const char *stopset"/> |
| </prototype> |
| <headers> |
| <header filename = "string.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>strcspn</CODE> (``string complement span'') function returns the length |
| of the initial substring of <VAR>string</VAR> that consists entirely of characters |
| that are <EM>not</EM> members of the set specified by the string <VAR>stopset</VAR>. |
| (In other words, it returns the offset of the first character in <VAR>string</VAR> |
| that is a member of the set <VAR>stopset</VAR>.) |
| <br><br> For example, |
| <pre><br> |
| strcspn ("hello, world", " \t\n,.;!?")<br> |
| 5<br> |
| </pre> |
| <br><br> Note that ``character'' is here used in the sense of byte. In a string |
| using a multibyte character encoding (abstract) character consisting of |
| more than one byte are not treated as an entity. Each byte is treated |
| separately. The function is not locale-dependent. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-wcscspn" type="function"> |
| <function returntype="size_t"> |
| <prototype> |
| <parameter content="const wchar_t *wstring"/> |
| <parameter content="const wchar_t *stopset"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>wcscspn</CODE> (``wide character string complement span'') function |
| returns the length of the initial substring of <VAR>wstring</VAR> that |
| consists entirely of wide characters that are <EM>not</EM> members of the |
| set specified by the string <VAR>stopset</VAR>. (In other words, it returns |
| the offset of the first character in <VAR>string</VAR> that is a member of |
| the set <VAR>stopset</VAR>.) |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-strpbrk" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="const char *string"/> |
| <parameter content="const char *stopset"/> |
| </prototype> |
| <headers> |
| <header filename = "string.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>strpbrk</CODE> (``string pointer break'') function is related to |
| <CODE>strcspn</CODE>, except that it returns a pointer to the first character |
| in <VAR>string</VAR> that is a member of the set <VAR>stopset</VAR> instead of the |
| length of the initial substring. It returns a null pointer if no such |
| character from <VAR>stopset</VAR> is found. |
| <br><br> For example, |
| <br><br> <pre><br> |
| strpbrk ("hello, world", " \t\n,.;!?")<br> |
| ", world"<br> |
| </pre> |
| <br><br> Note that ``character'' is here used in the sense of byte. In a string |
| using a multibyte character encoding (abstract) character consisting of |
| more than one byte are not treated as an entity. Each byte is treated |
| separately. The function is not locale-dependent. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-wcspbrk" type="function"> |
| <function returntype="wchar_t *"> |
| <prototype> |
| <parameter content="const wchar_t *wstring"/> |
| <parameter content="const wchar_t *stopset"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>wcspbrk</CODE> (``wide character string pointer break'') function is |
| related to <CODE>wcscspn</CODE>, except that it returns a pointer to the first |
| wide character in <VAR>wstring</VAR> that is a member of the set |
| <VAR>stopset</VAR> instead of the length of the initial substring. It |
| returns a null pointer if no such character from <VAR>stopset</VAR> is found. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-index" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="const char *string"/> |
| <parameter content="int c"/> |
| </prototype> |
| <headers> |
| <header filename = "string.h"/> |
| </headers> |
| <synopsis> |
| <CODE>index</CODE> is another name for <CODE>strchr</CODE>; they are exactly the same. |
| New code should always use <CODE>strchr</CODE> since this name is defined in |
| ISO C while <CODE>index</CODE> is a BSD invention which never was available |
| on System V derived systems. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-rindex" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="const char *string"/> |
| <parameter content="int c"/> |
| </prototype> |
| <headers> |
| <header filename = "string.h"/> |
| </headers> |
| <synopsis> |
| <CODE>rindex</CODE> is another name for <CODE>strrchr</CODE>; they are exactly the same. |
| New code should always use <CODE>strrchr</CODE> since this name is defined in |
| ISO C while <CODE>rindex</CODE> is a BSD invention which never was available |
| on System V derived systems. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-strtok" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="char *restrict newstring"/> |
| <parameter content="const char *restrict delimiters"/> |
| </prototype> |
| <headers> |
| <header filename = "string.h"/> |
| </headers> |
| <synopsis> |
| A string can be split into tokens by making a series of calls to the |
| function <CODE>strtok</CODE>. |
| <br><br> The string to be split up is passed as the <VAR>newstring</VAR> argument on |
| the first call only. The <CODE>strtok</CODE> function uses this to set up |
| some internal state information. Subsequent calls to get additional |
| tokens from the same string are indicated by passing a null pointer as |
| the <VAR>newstring</VAR> argument. Calling <CODE>strtok</CODE> with another |
| non-null <VAR>newstring</VAR> argument reinitializes the state information. |
| It is guaranteed that no other library function ever calls <CODE>strtok</CODE> |
| behind your back (which would mess up this internal state information). |
| <br><br> The <VAR>delimiters</VAR> argument is a string that specifies a set of delimiters |
| that may surround the token being extracted. All the initial characters |
| that are members of this set are discarded. The first character that is |
| <EM>not</EM> a member of this set of delimiters marks the beginning of the |
| next token. The end of the token is found by looking for the next |
| character that is a member of the delimiter set. This character in the |
| original string <VAR>newstring</VAR> is overwritten by a null character, and the |
| pointer to the beginning of the token in <VAR>newstring</VAR> is returned. |
| <br><br> On the next call to <CODE>strtok</CODE>, the searching begins at the next |
| character beyond the one that marked the end of the previous token. |
| Note that the set of delimiters <VAR>delimiters</VAR> do not have to be the |
| same on every call in a series of calls to <CODE>strtok</CODE>. |
| <br><br> If the end of the string <VAR>newstring</VAR> is reached, or if the remainder of |
| string consists only of delimiter characters, <CODE>strtok</CODE> returns |
| a null pointer. |
| <br><br> Note that ``character'' is here used in the sense of byte. In a string |
| using a multibyte character encoding (abstract) character consisting of |
| more than one byte are not treated as an entity. Each byte is treated |
| separately. The function is not locale-dependent. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-wcstok" type="function"> |
| <function returntype="wchar_t *"> |
| <prototype> |
| <parameter content="wchar_t *newstring"/> |
| <parameter content="const char *delimiters"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| A string can be split into tokens by making a series of calls to the |
| function <CODE>wcstok</CODE>. |
| <br><br> The string to be split up is passed as the <VAR>newstring</VAR> argument on |
| the first call only. The <CODE>wcstok</CODE> function uses this to set up |
| some internal state information. Subsequent calls to get additional |
| tokens from the same wide character string are indicated by passing a |
| null pointer as the <VAR>newstring</VAR> argument. Calling <CODE>wcstok</CODE> |
| with another non-null <VAR>newstring</VAR> argument reinitializes the state |
| information. It is guaranteed that no other library function ever calls |
| <CODE>wcstok</CODE> behind your back (which would mess up this internal state |
| information). |
| <br><br> The <VAR>delimiters</VAR> argument is a wide character string that specifies |
| a set of delimiters that may surround the token being extracted. All |
| the initial wide characters that are members of this set are discarded. |
| The first wide character that is <EM>not</EM> a member of this set of |
| delimiters marks the beginning of the next token. The end of the token |
| is found by looking for the next wide character that is a member of the |
| delimiter set. This wide character in the original wide character |
| string <VAR>newstring</VAR> is overwritten by a null wide character, and the |
| pointer to the beginning of the token in <VAR>newstring</VAR> is returned. |
| <br><br> On the next call to <CODE>wcstok</CODE>, the searching begins at the next |
| wide character beyond the one that marked the end of the previous token. |
| Note that the set of delimiters <VAR>delimiters</VAR> do not have to be the |
| same on every call in a series of calls to <CODE>wcstok</CODE>. |
| <br><br> If the end of the wide character string <VAR>newstring</VAR> is reached, or |
| if the remainder of string consists only of delimiter wide characters, |
| <CODE>wcstok</CODE> returns a null pointer. |
| <br><br> Note that ``character'' is here used in the sense of byte. In a string |
| using a multibyte character encoding (abstract) character consisting of |
| more than one byte are not treated as an entity. Each byte is treated |
| separately. The function is not locale-dependent. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-strtok_r" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="char *newstring"/> |
| <parameter content="const char *delimiters"/> |
| <parameter content="char **save_ptr"/> |
| </prototype> |
| <headers> |
| <header filename = "string.h"/> |
| </headers> |
| <synopsis> |
| Just like <CODE>strtok</CODE>, this function splits the string into several |
| tokens which can be accessed by successive calls to <CODE>strtok_r</CODE>. |
| The difference is that the information about the next token is stored in |
| the space pointed to by the third argument, <VAR>save_ptr</VAR>, which is a |
| pointer to a string pointer. Calling <CODE>strtok_r</CODE> with a null |
| pointer for <VAR>newstring</VAR> and leaving <VAR>save_ptr</VAR> between the calls |
| unchanged does the job without hindering reentrancy. |
| <br><br> This function is defined in POSIX.1 and can be found on many systems |
| which support multi-threading. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-strsep" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="char **string_ptr"/> |
| <parameter content="const char *delimiter"/> |
| </prototype> |
| <headers> |
| <header filename = "string.h"/> |
| </headers> |
| <synopsis> |
| This function has a similar functionality as <CODE>strtok_r</CODE> with the |
| <VAR>newstring</VAR> argument replaced by the <VAR>save_ptr</VAR> argument. The |
| initialization of the moving pointer has to be done by the user. |
| Successive calls to <CODE>strsep</CODE> move the pointer along the tokens |
| separated by <VAR>delimiter</VAR>, returning the address of the next token |
| and updating <VAR>string_ptr</VAR> to point to the beginning of the next |
| token. |
| <br><br> One difference between <CODE>strsep</CODE> and <CODE>strtok_r</CODE> is that if the |
| input string contains more than one character from <VAR>delimiter</VAR> in a |
| row <CODE>strsep</CODE> returns an empty string for each pair of characters |
| from <VAR>delimiter</VAR>. This means that a program normally should test |
| for <CODE>strsep</CODE> returning an empty string before processing it. |
| <br><br> This function was introduced in 4.3BSD and therefore is widely available. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-basename" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="const char *filename"/> |
| </prototype> |
| <headers> |
| <header filename = "string.h"/> |
| </headers> |
| <synopsis> |
| The GNU version of the <CODE>basename</CODE> function returns the last |
| component of the path in <VAR>filename</VAR>. This function is the preferred |
| usage, since it does not modify the argument, <VAR>filename</VAR>, and |
| respects trailing slashes. The prototype for <CODE>basename</CODE> can be |
| found in <TT>string.h</TT>. Note, this function is overriden by the XPG |
| version, if <TT>libgen.h</TT> is included. |
| <br><br> Example of using GNU <CODE>basename</CODE>: |
| <br><br> <pre><br> |
| #include <string.h><br> |
| <br><br> int<br> |
| main (int argc, char *argv[])<br> |
| {<br> |
| char *prog = basename (argv[0]);<br> |
| <br><br> if (argc < 2)<br> |
| {<br> |
| fprintf (stderr, "Usage %s <arg>\n", prog);<br> |
| exit (1);<br> |
| }<br> |
| <br><br> <small>...</small><br> |
| }<br> |
| </pre> |
| <br><br> Portability Note: This function may produce different results |
| on different systems. |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-basename" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="char *path"/> |
| </prototype> |
| <headers> |
| <header filename = "libgen.h"/> |
| </headers> |
| <synopsis> |
| This is the standard XPG defined <CODE>basename</CODE>. It is similar in |
| spirit to the GNU version, but may modify the <VAR>path</VAR> by removing |
| trailing '/' characters. If the <VAR>path</VAR> is made up entirely of '/' |
| characters, then "/" will be returned. Also, if <VAR>path</VAR> is |
| <CODE>NULL</CODE> or an empty string, then "." is returned. The prototype for |
| the XPG version can be found in <TT>libgen.h</TT>. |
| <br><br> Example of using XPG <CODE>basename</CODE>: |
| <br><br> <pre><br> |
| #include <libgen.h><br> |
| <br><br> int<br> |
| main (int argc, char *argv[])<br> |
| {<br> |
| char *prog;<br> |
| char *path = strdupa (argv[0]);<br> |
| <br><br> prog = basename (path);<br> |
| <br><br> if (argc < 2)<br> |
| {<br> |
| fprintf (stderr, "Usage %s <arg>\n", prog);<br> |
| exit (1);<br> |
| }<br> |
| <br><br> <small>...</small><br> |
| <br><br> }<br> |
| </pre> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-dirname" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="char *path"/> |
| </prototype> |
| <headers> |
| <header filename = "libgen.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>dirname</CODE> function is the compliment to the XPG version of |
| <CODE>basename</CODE>. It returns the parent directory of the file specified |
| by <VAR>path</VAR>. If <VAR>path</VAR> is <CODE>NULL</CODE>, an empty string, or |
| contains no '/' characters, then "." is returned. The prototype for this |
| function can be found in <TT>libgen.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-strfry" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="char *string"/> |
| </prototype> |
| <headers> |
| <header filename = "string.h"/> |
| </headers> |
| <synopsis> |
| <br><br> <CODE>strfry</CODE> creates a pseudorandom anagram of a string, replacing the |
| input with the anagram in place. For each position in the string, |
| <CODE>strfry</CODE> swaps it with a position in the string selected at random |
| (from a uniform distribution). The two positions may be the same. |
| <br><br> The return value of <CODE>strfry</CODE> is always <VAR>string</VAR>. |
| <br><br> Portability Note: This function is unique to the GNU C library. |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-memfrob" type="function"> |
| <function returntype="void *"> |
| <prototype> |
| <parameter content="void *mem"/> |
| <parameter content="size_t length"/> |
| </prototype> |
| <headers> |
| <header filename = "string.h"/> |
| </headers> |
| <synopsis> |
| <br><br> <CODE>memfrob</CODE> transforms (frobnicates) each byte of the data structure |
| at <VAR>mem</VAR>, which is <VAR>length</VAR> bytes long, by bitwise exclusive |
| oring it with binary 00101010. It does the transformation in place and |
| its return value is always <VAR>mem</VAR>. |
| <br><br> Note that <CODE>memfrob</CODE> a second time on the same data structure |
| returns it to its original state. |
| <br><br> This is a good function for hiding information from someone who doesn't |
| want to see it or doesn't want to see it very much. To really prevent |
| people from retrieving the information, use stronger encryption such as |
| that described in . |
| <br><br> Portability Note: This function is unique to the GNU C library. |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-l64a" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="long int n"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| This function encodes a 32-bit input value using characters from the |
| basic character set. It returns a pointer to a 7 character buffer which |
| contains an encoded version of <VAR>n</VAR>. To encode a series of bytes the |
| user must copy the returned string to a destination buffer. It returns |
| the empty string if <VAR>n</VAR> is zero, which is somewhat bizarre but |
| mandated by the standard.* |
| Warning: Since a static buffer is used this function should not |
| be used in multi-threaded programs. There is no thread-safe alternative |
| to this function in the C library.* |
| Compatibility Note: The XPG standard states that the return |
| value of <CODE>l64a</CODE> is undefined if <VAR>n</VAR> is negative. In the GNU |
| implementation, <CODE>l64a</CODE> treats its argument as unsigned, so it will |
| return a sensible encoding for any nonzero <VAR>n</VAR>; however, portable |
| programs should not rely on this. |
| <br><br> To encode a large buffer <CODE>l64a</CODE> must be called in a loop, once for |
| each 32-bit word of the buffer. For example, one could do something |
| like this: |
| <br><br> <pre><br> |
| char *<br> |
| encode (const void *buf, size_t len)<br> |
| {<br> |
| /* We know in advance how long the buffer has to be. */<br> |
| unsigned char *in = (unsigned char *) buf;<br> |
| char *out = malloc (6 + ((len + 3) / 4) * 6 + 1);<br> |
| char *cp = out, *p;<br> |
| <br><br> /* Encode the length. */<br> |
| /* Using `htonl' is necessary so that the data can be<br> |
| decoded even on machines with different byte order.<br> |
| `l64a' can return a string shorter than 6 bytes, so <br> |
| we pad it with encoding of 0 ('.') at the end by <br> |
| hand. */<br> |
| <br><br> p = stpcpy (cp, l64a (htonl (len)));<br> |
| cp = mempcpy (p, "......", 6 - (p - cp));<br> |
| <br><br> while (len > 3)<br> |
| {<br> |
| unsigned long int n = *in++;<br> |
| n = (n << 8) | *in++;<br> |
| n = (n << 8) | *in++;<br> |
| n = (n << 8) | *in++;<br> |
| len -= 4;<br> |
| p = stpcpy (cp, l64a (htonl (n)));<br> |
| cp = mempcpy (p, "......", 6 - (p - cp));<br> |
| }<br> |
| if (len > 0)<br> |
| {<br> |
| unsigned long int n = *in++;<br> |
| if (--len > 0)<br> |
| {<br> |
| n = (n << 8) | *in++;<br> |
| if (--len > 0)<br> |
| n = (n << 8) | *in;<br> |
| }<br> |
| cp = stpcpy (cp, l64a (htonl (n)));<br> |
| }<br> |
| *cp = '\0';<br> |
| return out;<br> |
| }<br> |
| </pre> |
| <br><br> It is strange that the library does not provide the complete |
| functionality needed but so be it. |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-a64l" type="function"> |
| <function returntype="long int"> |
| <prototype> |
| <parameter content="const char *string"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The parameter <VAR>string</VAR> should contain a string which was produced by |
| a call to <CODE>l64a</CODE>. The function processes at least 6 characters of |
| this string, and decodes the characters it finds according to the table |
| below. It stops decoding when it finds a character not in the table, |
| rather like <CODE>atoi</CODE>; if you have a buffer which has been broken into |
| lines, you must be careful to skip over the end-of-line characters. |
| <br><br> The decoded number is returned as a <CODE>long int</CODE> value. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-argz_create" type="function"> |
| <function returntype="error_t"> |
| <prototype> |
| <parameter content="char *const argv[]"/> |
| <parameter content="char **argz"/> |
| <parameter content="size_t *argz_len"/> |
| </prototype> |
| <headers> |
| <header filename = "argz.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>argz_create</CODE> function converts the Unix-style argument vector |
| <VAR>argv</VAR> (a vector of pointers to normal C strings, terminated by |
| <CODE>(char *)0</CODE>; ) into an argz vector with |
| the same elements, which is returned in <VAR>argz</VAR> and <VAR>argz_len</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-argz_create_sep" type="function"> |
| <function returntype="error_t"> |
| <prototype> |
| <parameter content="const char *string"/> |
| <parameter content="int sep"/> |
| <parameter content="char **argz"/> |
| <parameter content="size_t *argz_len"/> |
| </prototype> |
| <headers> |
| <header filename = "argz.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>argz_create_sep</CODE> function converts the null-terminated string |
| <VAR>string</VAR> into an argz vector (returned in <VAR>argz</VAR> and |
| <VAR>argz_len</VAR>) by splitting it into elements at every occurrence of the |
| character <VAR>sep</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-argz_count" type="function"> |
| <function returntype="size_t"> |
| <prototype> |
| <parameter content="const char *argz"/> |
| <parameter content="size_t arg_len"/> |
| </prototype> |
| <headers> |
| <header filename = "argz.h"/> |
| </headers> |
| <synopsis> |
| Returns the number of elements in the argz vector <VAR>argz</VAR> and |
| <VAR>argz_len</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-argz_extract" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="char *argz"/> |
| <parameter content="size_t argz_len"/> |
| <parameter content="char **argv"/> |
| </prototype> |
| <headers> |
| <header filename = "argz.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>argz_extract</CODE> function converts the argz vector <VAR>argz</VAR> and |
| <VAR>argz_len</VAR> into a Unix-style argument vector stored in <VAR>argv</VAR>, |
| by putting pointers to every element in <VAR>argz</VAR> into successive |
| positions in <VAR>argv</VAR>, followed by a terminator of <CODE>0</CODE>. |
| <VAR>Argv</VAR> must be pre-allocated with enough space to hold all the |
| elements in <VAR>argz</VAR> plus the terminating <CODE>(char *)0</CODE> |
| (<CODE>(argz_count (<VAR>argz</VAR>, <VAR>argz_len</VAR>) + 1) * sizeof (char *)</CODE> |
| bytes should be enough). Note that the string pointers stored into |
| <VAR>argv</VAR> point into <VAR>argz</VAR>---they are not copies---and so |
| <VAR>argz</VAR> must be copied if it will be changed while <VAR>argv</VAR> is |
| still active. This function is useful for passing the elements in |
| <VAR>argz</VAR> to an exec function . |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-argz_stringify" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="char *argz"/> |
| <parameter content="size_t len"/> |
| <parameter content="int sep"/> |
| </prototype> |
| <headers> |
| <header filename = "argz.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>argz_stringify</CODE> converts <VAR>argz</VAR> into a normal string with |
| the elements separated by the character <VAR>sep</VAR>, by replacing each |
| <CODE>'\0'</CODE> inside <VAR>argz</VAR> (except the last one, which terminates the |
| string) with <VAR>sep</VAR>. This is handy for printing <VAR>argz</VAR> in a |
| readable manner. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-argz_add" type="function"> |
| <function returntype="error_t"> |
| <prototype> |
| <parameter content="char **argz"/> |
| <parameter content="size_t *argz_len"/> |
| <parameter content="const char *str"/> |
| </prototype> |
| <headers> |
| <header filename = "argz.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>argz_add</CODE> function adds the string <VAR>str</VAR> to the end of the |
| argz vector <CODE>*<VAR>argz</VAR></CODE>, and updates <CODE>*<VAR>argz</VAR></CODE> and |
| <CODE>*<VAR>argz_len</VAR></CODE> accordingly. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-argz_add_sep" type="function"> |
| <function returntype="error_t"> |
| <prototype> |
| <parameter content="char **argz"/> |
| <parameter content="size_t *argz_len"/> |
| <parameter content="const char *str"/> |
| <parameter content="int delim"/> |
| </prototype> |
| <headers> |
| <header filename = "argz.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>argz_add_sep</CODE> function is similar to <CODE>argz_add</CODE>, but |
| <VAR>str</VAR> is split into separate elements in the result at occurrences of |
| the character <VAR>delim</VAR>. This is useful, for instance, for |
| adding the components of a Unix search path to an argz vector, by using |
| a value of <CODE>':'</CODE> for <VAR>delim</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-argz_append" type="function"> |
| <function returntype="error_t"> |
| <prototype> |
| <parameter content="char **argz"/> |
| <parameter content="size_t *argz_len"/> |
| <parameter content="const char *buf"/> |
| <parameter content="size_t buf_len"/> |
| </prototype> |
| <headers> |
| <header filename = "argz.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>argz_append</CODE> function appends <VAR>buf_len</VAR> bytes starting at |
| <VAR>buf</VAR> to the argz vector <CODE>*<VAR>argz</VAR></CODE>, reallocating |
| <CODE>*<VAR>argz</VAR></CODE> to accommodate it, and adding <VAR>buf_len</VAR> to |
| <CODE>*<VAR>argz_len</VAR></CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-argz_delete" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="char **argz"/> |
| <parameter content="size_t *argz_len"/> |
| <parameter content="char *entry"/> |
| </prototype> |
| <headers> |
| <header filename = "argz.h"/> |
| </headers> |
| <synopsis> |
| If <VAR>entry</VAR> points to the beginning of one of the elements in the |
| argz vector <CODE>*<VAR>argz</VAR></CODE>, the <CODE>argz_delete</CODE> function will |
| remove this entry and reallocate <CODE>*<VAR>argz</VAR></CODE>, modifying |
| <CODE>*<VAR>argz</VAR></CODE> and <CODE>*<VAR>argz_len</VAR></CODE> accordingly. Note that as |
| destructive argz functions usually reallocate their argz argument, |
| pointers into argz vectors such as <VAR>entry</VAR> will then become invalid. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-argz_insert" type="function"> |
| <function returntype="error_t"> |
| <prototype> |
| <parameter content="char **argz"/> |
| <parameter content="size_t *argz_len"/> |
| <parameter content="char *before"/> |
| <parameter content="const char *entry"/> |
| </prototype> |
| <headers> |
| <header filename = "argz.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>argz_insert</CODE> function inserts the string <VAR>entry</VAR> into the |
| argz vector <CODE>*<VAR>argz</VAR></CODE> at a point just before the existing |
| element pointed to by <VAR>before</VAR>, reallocating <CODE>*<VAR>argz</VAR></CODE> and |
| updating <CODE>*<VAR>argz</VAR></CODE> and <CODE>*<VAR>argz_len</VAR></CODE>. If <VAR>before</VAR> |
| is <CODE>0</CODE>, <VAR>entry</VAR> is added to the end instead (as if by |
| <CODE>argz_add</CODE>). Since the first element is in fact the same as |
| <CODE>*<VAR>argz</VAR></CODE>, passing in <CODE>*<VAR>argz</VAR></CODE> as the value of |
| <VAR>before</VAR> will result in <VAR>entry</VAR> being inserted at the beginning. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-argz_next" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="char *argz"/> |
| <parameter content="size_t argz_len"/> |
| <parameter content="const char *entry"/> |
| </prototype> |
| <headers> |
| <header filename = "argz.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>argz_next</CODE> function provides a convenient way of iterating |
| over the elements in the argz vector <VAR>argz</VAR>. It returns a pointer |
| to the next element in <VAR>argz</VAR> after the element <VAR>entry</VAR>, or |
| <CODE>0</CODE> if there are no elements following <VAR>entry</VAR>. If <VAR>entry</VAR> |
| is <CODE>0</CODE>, the first element of <VAR>argz</VAR> is returned. |
| <br><br> This behavior suggests two styles of iteration: |
| <br><br> <pre><br> |
| char *entry = 0;<br> |
| while ((entry = argz_next (<VAR>argz</VAR>, <VAR>argz_len</VAR>, entry)))<br> |
| <VAR>action</VAR>;<br> |
| </pre><br> |
| <br><br> (the double parentheses are necessary to make some C compilers shut up<br> |
| about what they consider a questionable <CODE>while</CODE>-test) and:<br> |
| <br><br> <pre><br> |
| char *entry;<br> |
| for (entry = <VAR>argz</VAR>;<br> |
| entry;<br> |
| entry = argz_next (<VAR>argz</VAR>, <VAR>argz_len</VAR>, entry))<br> |
| <VAR>action</VAR>;<br> |
| </pre> |
| <br><br> Note that the latter depends on <VAR>argz</VAR> having a value of <CODE>0</CODE> if |
| it is empty (rather than a pointer to an empty block of memory); this |
| invariant is maintained for argz vectors created by the functions here. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-argz_replace" type="function"> |
| <function returntype="error_t"> |
| <prototype> |
| </prototype> |
| <headers> |
| <header filename = "argz.h"/> |
| </headers> |
| <synopsis> |
| Replace any occurrences of the string <VAR>str</VAR> in <VAR>argz</VAR> with |
| <VAR>with</VAR>, reallocating <VAR>argz</VAR> as necessary. If |
| <VAR>replace_count</VAR> is non-zero, <CODE>*<VAR>replace_count</VAR></CODE> will be |
| incremented by number of replacements performed. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-envz_entry" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="const char *envz"/> |
| <parameter content="size_t envz_len"/> |
| <parameter content="const char *name"/> |
| </prototype> |
| <headers> |
| <header filename = "envz.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>envz_entry</CODE> function finds the entry in <VAR>envz</VAR> with the name |
| <VAR>name</VAR>, and returns a pointer to the whole entry---that is, the argz |
| element which begins with <VAR>name</VAR> followed by a <CODE>'='</CODE> character. If |
| there is no entry with that name, <CODE>0</CODE> is returned. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-envz_get" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="const char *envz"/> |
| <parameter content="size_t envz_len"/> |
| <parameter content="const char *name"/> |
| </prototype> |
| <headers> |
| <header filename = "envz.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>envz_get</CODE> function finds the entry in <VAR>envz</VAR> with the name |
| <VAR>name</VAR> (like <CODE>envz_entry</CODE>), and returns a pointer to the value |
| portion of that entry (following the <CODE>'='</CODE>). If there is no entry with |
| that name (or only a null entry), <CODE>0</CODE> is returned. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-envz_add" type="function"> |
| <function returntype="error_t"> |
| <prototype> |
| <parameter content="char **envz"/> |
| <parameter content="size_t *envz_len"/> |
| <parameter content="const char *name"/> |
| <parameter content="const char *value"/> |
| </prototype> |
| <headers> |
| <header filename = "envz.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>envz_add</CODE> function adds an entry to <CODE>*<VAR>envz</VAR></CODE> |
| (updating <CODE>*<VAR>envz</VAR></CODE> and <CODE>*<VAR>envz_len</VAR></CODE>) with the name |
| <VAR>name</VAR>, and value <VAR>value</VAR>. If an entry with the same name |
| already exists in <VAR>envz</VAR>, it is removed first. If <VAR>value</VAR> is |
| <CODE>0</CODE>, then the new entry will the special null type of entry |
| (mentioned above). |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-envz_merge" type="function"> |
| <function returntype="error_t"> |
| <prototype> |
| <parameter content="char **envz"/> |
| <parameter content="size_t *envz_len"/> |
| <parameter content="const char *envz2"/> |
| <parameter content="size_t envz2_len"/> |
| <parameter content="int override"/> |
| </prototype> |
| <headers> |
| <header filename = "envz.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>envz_merge</CODE> function adds each entry in <VAR>envz2</VAR> to <VAR>envz</VAR>, |
| as if with <CODE>envz_add</CODE>, updating <CODE>*<VAR>envz</VAR></CODE> and |
| <CODE>*<VAR>envz_len</VAR></CODE>. If <VAR>override</VAR> is true, then values in <VAR>envz2</VAR> |
| will supersede those with the same name in <VAR>envz</VAR>, otherwise not. |
| <br><br> Null entries are treated just like other entries in this respect, so a null |
| entry in <VAR>envz</VAR> can prevent an entry of the same name in <VAR>envz2</VAR> from |
| being added to <VAR>envz</VAR>, if <VAR>override</VAR> is false. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-envz_strip" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="char **envz"/> |
| <parameter content="size_t *envz_len"/> |
| </prototype> |
| <headers> |
| <header filename = "envz.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>envz_strip</CODE> function removes any null entries from <VAR>envz</VAR>, |
| updating <CODE>*<VAR>envz</VAR></CODE> and <CODE>*<VAR>envz_len</VAR></CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getopt" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int argc"/> |
| <parameter content="char **argv"/> |
| <parameter content="const char *options"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>getopt</CODE> function gets the next option argument from the |
| argument list specified by the <VAR>argv</VAR> and <VAR>argc</VAR> arguments. |
| Normally these values come directly from the arguments received by |
| <CODE>main</CODE>. |
| <br><br> The <VAR>options</VAR> argument is a string that specifies the option |
| characters that are valid for this program. An option character in this |
| string can be followed by a colon (<samp>:</samp>) to indicate that it takes a |
| required argument. If an option character is followed by two colons |
| (<samp>::</samp>), its argument is optional; this is a GNU extension. |
| <br><br> <CODE>getopt</CODE> has three ways to deal with options that follow |
| non-options <VAR>argv</VAR> elements. The special argument <samp>--</samp> forces |
| in all cases the end of option scanning. |
| <br><br> <OL> |
| <LI> |
| The default is to permute the contents of <VAR>argv</VAR> while scanning it |
| so that eventually all the non-options are at the end. This allows |
| options to be given in any order, even with programs that were not |
| written to expect this. |
| <br><br> <LI> |
| If the <VAR>options</VAR> argument string begins with a hyphen (<samp>-</samp>), this |
| is treated specially. It permits arguments that are not options to be |
| returned as if they were associated with option character <samp>\1</samp>. |
| <br><br> <LI> |
| POSIX demands the following behavior: The first non-option stops option |
| processing. This mode is selected by either setting the environment |
| variable <CODE>POSIXLY_CORRECT</CODE> or beginning the <VAR>options</VAR> argument |
| string with a plus sign (<samp>+</samp>). |
| </OL> |
| <br><br> The <CODE>getopt</CODE> function returns the option character for the next |
| command line option. When no more option arguments are available, it |
| returns <CODE>-1</CODE>. There may still be more non-option arguments; you |
| must compare the external variable <CODE>optind</CODE> against the <VAR>argc</VAR> |
| parameter to check this. |
| <br><br> If the option has an argument, <CODE>getopt</CODE> returns the argument by |
| storing it in the variable <VAR>optarg</VAR>. You don't ordinarily need to |
| copy the <CODE>optarg</CODE> string, since it is a pointer into the original |
| <VAR>argv</VAR> array, not into a static area that might be overwritten. |
| <br><br> If <CODE>getopt</CODE> finds an option character in <VAR>argv</VAR> that was not |
| included in <VAR>options</VAR>, or a missing option argument, it returns |
| <samp>?</samp> and sets the external variable <CODE>optopt</CODE> to the actual |
| option character. If the first character of <VAR>options</VAR> is a colon |
| (<samp>:</samp>), then <CODE>getopt</CODE> returns <samp>:</samp> instead of <samp>?</samp> to |
| indicate a missing option argument. In addition, if the external |
| variable <CODE>opterr</CODE> is nonzero (which is the default), <CODE>getopt</CODE> |
| prints an error message. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="struct-option" type="struct"> |
| <structure> |
| <synopsis> |
| This structure describes a single long option name for the sake of |
| <CODE>getopt_long</CODE>. The argument <VAR>longopts</VAR> must be an array of |
| these structures, one for each long option. Terminate the array with an |
| element containing all zeros. |
| <br><br> The <CODE>struct option</CODE> structure has these fields: |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="const char *name"> |
| <synopsis> |
| This field is the name of the option. It is a string. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="int has_arg"> |
| <synopsis> |
| This field says whether the option takes an argument. It is an integer, |
| and there are three legitimate values: <CODE>no_argument</CODE>, |
| <CODE>required_argument</CODE> and <CODE>optional_argument</CODE>. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="int *flag"> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="function-getopt_long" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int argc"/> |
| <parameter content="char *const *argv"/> |
| <parameter content="const char *shortopts"/> |
| <parameter content="const struct option *longopts"/> |
| <parameter content="int *indexptr"/> |
| </prototype> |
| <headers> |
| <header filename = "getopt.h"/> |
| </headers> |
| <synopsis> |
| Decode options from the vector <VAR>argv</VAR> (whose length is <VAR>argc</VAR>). |
| The argument <VAR>shortopts</VAR> describes the short options to accept, just as |
| it does in <CODE>getopt</CODE>. The argument <VAR>longopts</VAR> describes the long |
| options to accept (see above). |
| <br><br> When <CODE>getopt_long</CODE> encounters a short option, it does the same |
| thing that <CODE>getopt</CODE> would do: it returns the character code for the |
| option, and stores the options argument (if it has one) in <CODE>optarg</CODE>. |
| <br><br> When <CODE>getopt_long</CODE> encounters a long option, it takes actions based |
| on the <CODE>flag</CODE> and <CODE>val</CODE> fields of the definition of that |
| option. |
| <br><br> If <CODE>flag</CODE> is a null pointer, then <CODE>getopt_long</CODE> returns the |
| contents of <CODE>val</CODE> to indicate which option it found. You should |
| arrange distinct values in the <CODE>val</CODE> field for options with |
| different meanings, so you can decode these values after |
| <CODE>getopt_long</CODE> returns. If the long option is equivalent to a short |
| option, you can use the short option's character code in <CODE>val</CODE>. |
| <br><br> If <CODE>flag</CODE> is not a null pointer, that means this option should just |
| set a flag in the program. The flag is a variable of type <CODE>int</CODE> |
| that you define. Put the address of the flag in the <CODE>flag</CODE> field. |
| Put in the <CODE>val</CODE> field the value you would like this option to |
| store in the flag. In this case, <CODE>getopt_long</CODE> returns <CODE>0</CODE>. |
| <br><br> For any long option, <CODE>getopt_long</CODE> tells you the index in the array |
| <VAR>longopts</VAR> of the options definition, by storing it into |
| <CODE>*<VAR>indexptr</VAR></CODE>. You can get the name of the option with |
| <CODE><VAR>longopts</VAR>[*<VAR>indexptr</VAR>].name</CODE>. So you can distinguish among |
| long options either by the values in their <CODE>val</CODE> fields or by their |
| indices. You can also distinguish in this way among long options that |
| set flags. |
| <br><br> When a long option has an argument, <CODE>getopt_long</CODE> puts the argument |
| value in the variable <CODE>optarg</CODE> before returning. When the option |
| has no argument, the value in <CODE>optarg</CODE> is a null pointer. This is |
| how you can tell whether an optional argument was supplied. |
| <br><br> When <CODE>getopt_long</CODE> has no more options to handle, it returns |
| <CODE>-1</CODE>, and leaves in the variable <CODE>optind</CODE> the index in |
| <VAR>argv</VAR> of the next remaining argument. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getopt_long_only" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int argc"/> |
| <parameter content="char *const *argv"/> |
| <parameter content="const char *shortopts"/> |
| <parameter content="const struct option *longopts"/> |
| <parameter content="int *indexptr"/> |
| </prototype> |
| <headers> |
| <header filename = "getopt.h"/> |
| </headers> |
| <synopsis> |
| <br><br> The <CODE>getopt_long_only</CODE> function is equivalent to the |
| <CODE>getopt_long</CODE> function but it allows to specify the user of the |
| application to pass long options with only <samp>-</samp> instead of |
| <samp>--</samp>. The <samp>--</samp> prefix is still recognized but instead of |
| looking through the short options if a <samp>-</samp> is seen it is first |
| tried whether this parameter names a long option. If not, it is parsed |
| as a short option. |
| <br><br> Assuming <CODE>getopt_long_only</CODE> is used starting an application with |
| <br><br> <pre><br> |
| app -foo<br> |
| </pre> |
| <br><br> |
| the <CODE>getopt_long_only</CODE> will first look for a long option named |
| <samp>foo</samp>. If this is not found, the short options <samp>f</samp>, <samp>o</samp>, |
| and again <samp>o</samp> are recognized. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="dtype-div_t" type="dtype"> |
| <structure> |
| <synopsis> |
| This is a structure type used to hold the result returned by the <CODE>div</CODE> |
| function. It has the following members: |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="int quot"> |
| <synopsis> |
| The quotient from the division. |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="function-div" type="function"> |
| <function returntype="div_t"> |
| <prototype> |
| <parameter content="int numerator"/> |
| <parameter content="int denominator"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| This function <CODE>div</CODE> computes the quotient and remainder from |
| the division of <VAR>numerator</VAR> by <VAR>denominator</VAR>, returning the |
| result in a structure of type <CODE>div_t</CODE>. |
| <br><br> If the result cannot be represented (as in a division by zero), the |
| behavior is undefined. |
| <br><br> Here is an example, albeit not a very useful one. |
| <br><br> <pre><br> |
| div_t result;<br> |
| result = div (20, -6);<br> |
| </pre> |
| <br><br> |
| Now <CODE>result.quot</CODE> is <CODE>-3</CODE> and <CODE>result.rem</CODE> is <CODE>2</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="dtype-ldiv_t" type="dtype"> |
| <structure> |
| <synopsis> |
| This is a structure type used to hold the result returned by the <CODE>ldiv</CODE> |
| function. It has the following members: |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="long int quot"> |
| <synopsis> |
| The quotient from the division. |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="function-ldiv" type="function"> |
| <function returntype="ldiv_t"> |
| <prototype> |
| <parameter content="long int numerator"/> |
| <parameter content="long int denominator"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>ldiv</CODE> function is similar to <CODE>div</CODE>, except that the |
| arguments are of type <CODE>long int</CODE> and the result is returned as a |
| structure of type <CODE>ldiv_t</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="dtype-lldiv_t" type="dtype"> |
| <structure> |
| <synopsis> |
| This is a structure type used to hold the result returned by the <CODE>lldiv</CODE> |
| function. It has the following members: |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="long long int quot"> |
| <synopsis> |
| The quotient from the division. |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="function-lldiv" type="function"> |
| <function returntype="lldiv_t"> |
| <prototype> |
| <parameter content="long long int numerator"/> |
| <parameter content="long long int denominator"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>lldiv</CODE> function is like the <CODE>div</CODE> function, but the |
| arguments are of type <CODE>long long int</CODE> and the result is returned as |
| a structure of type <CODE>lldiv_t</CODE>. |
| <br><br> The <CODE>lldiv</CODE> function was added in ISO C99. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="dtype-imaxdiv_t" type="dtype"> |
| <structure> |
| <synopsis> |
| This is a structure type used to hold the result returned by the <CODE>imaxdiv</CODE> |
| function. It has the following members: |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="intmax_t quot"> |
| <synopsis> |
| The quotient from the division. |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="function-imaxdiv" type="function"> |
| <function returntype="imaxdiv_t"> |
| <prototype> |
| <parameter content="intmax_t numerator"/> |
| <parameter content="intmax_t denominator"/> |
| </prototype> |
| <headers> |
| <header filename = "inttypes.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>imaxdiv</CODE> function is like the <CODE>div</CODE> function, but the |
| arguments are of type <CODE>intmax_t</CODE> and the result is returned as |
| a structure of type <CODE>imaxdiv_t</CODE>. |
| <br><br> See Integers for a description of the <CODE>intmax_t</CODE> type. |
| <br><br> The <CODE>imaxdiv</CODE> function was added in ISO C99. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-isinf" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| This function returns <CODE>-1</CODE> if <VAR>x</VAR> represents negative infinity, |
| <CODE>1</CODE> if <VAR>x</VAR> represents positive infinity, and <CODE>0</CODE> otherwise. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-isinff" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="float x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| This function returns <CODE>-1</CODE> if <VAR>x</VAR> represents negative infinity, |
| <CODE>1</CODE> if <VAR>x</VAR> represents positive infinity, and <CODE>0</CODE> otherwise. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-isinfl" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="long double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| This function returns <CODE>-1</CODE> if <VAR>x</VAR> represents negative infinity, |
| <CODE>1</CODE> if <VAR>x</VAR> represents positive infinity, and <CODE>0</CODE> otherwise. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-isnan" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| This function returns a nonzero value if <VAR>x</VAR> is a ``not a number'' |
| value, and zero otherwise. |
| <br><br> NB: The <CODE>isnan</CODE> macro defined by ISO C99 overrides |
| the BSD function. This is normally not a problem, because the two |
| routines behave identically. However, if you really need to get the BSD |
| function for some reason, you can write |
| <br><br> <pre><br> |
| (isnan) (x)<br> |
| </pre> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-isnanf" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="float x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| This function returns a nonzero value if <VAR>x</VAR> is a ``not a number'' |
| value, and zero otherwise. |
| <br><br> NB: The <CODE>isnan</CODE> macro defined by ISO C99 overrides |
| the BSD function. This is normally not a problem, because the two |
| routines behave identically. However, if you really need to get the BSD |
| function for some reason, you can write |
| <br><br> <pre><br> |
| (isnan) (x)<br> |
| </pre> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-isnanl" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="long double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| This function returns a nonzero value if <VAR>x</VAR> is a ``not a number'' |
| value, and zero otherwise. |
| <br><br> NB: The <CODE>isnan</CODE> macro defined by ISO C99 overrides |
| the BSD function. This is normally not a problem, because the two |
| routines behave identically. However, if you really need to get the BSD |
| function for some reason, you can write |
| <br><br> <pre><br> |
| (isnan) (x)<br> |
| </pre> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-finite" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| This function returns a nonzero value if <VAR>x</VAR> is finite or a ``not a |
| number'' value, and zero otherwise. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-finitef" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="float x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| This function returns a nonzero value if <VAR>x</VAR> is finite or a ``not a |
| number'' value, and zero otherwise. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-finitel" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="long double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| This function returns a nonzero value if <VAR>x</VAR> is finite or a ``not a |
| number'' value, and zero otherwise. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-feclearexcept" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int excepts"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| <header filename = "fenv.h"/> |
| </headers> |
| <synopsis> |
| This function clears all of the supported exception flags indicated by |
| <VAR>excepts</VAR>. |
| <br><br> The function returns zero in case the operation was successful, a |
| non-zero value otherwise. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-feraiseexcept" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int excepts"/> |
| </prototype> |
| <headers> |
| <header filename = "fenv.h"/> |
| </headers> |
| <synopsis> |
| This function raises the supported exceptions indicated by |
| <VAR>excepts</VAR>. If more than one exception bit in <VAR>excepts</VAR> is set |
| the order in which the exceptions are raised is undefined except that |
| overflow (<CODE>FE_OVERFLOW</CODE>) or underflow (<CODE>FE_UNDERFLOW</CODE>) are |
| raised before inexact (<CODE>FE_INEXACT</CODE>). Whether for overflow or |
| underflow the inexact exception is also raised is also implementation |
| dependent. |
| <br><br> The function returns zero in case the operation was successful, a |
| non-zero value otherwise. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fetestexcept" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int excepts"/> |
| </prototype> |
| <headers> |
| <header filename = "fenv.h"/> |
| </headers> |
| <synopsis> |
| Test whether the exception flags indicated by the parameter <VAR>except</VAR> |
| are currently set. If any of them are, a nonzero value is returned |
| which specifies which exceptions are set. Otherwise the result is zero. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fegetexceptflag" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="fexcept_t *flagp"/> |
| <parameter content="int excepts"/> |
| </prototype> |
| <headers> |
| <header filename = "fenv.h"/> |
| </headers> |
| <synopsis> |
| This function stores in the variable pointed to by <VAR>flagp</VAR> an |
| implementation-defined value representing the current setting of the |
| exception flags indicated by <VAR>excepts</VAR>. |
| <br><br> The function returns zero in case the operation was successful, a |
| non-zero value otherwise. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fesetexceptflag" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const fexcept_t *flagp"/> |
| <parameter content="int excepts"/> |
| </prototype> |
| <headers> |
| <header filename = "fenv.h"/> |
| </headers> |
| <synopsis> |
| This function restores the flags for the exceptions indicated by |
| <VAR>excepts</VAR> to the values stored in the variable pointed to by |
| <VAR>flagp</VAR>. |
| <br><br> The function returns zero in case the operation was successful, a |
| non-zero value otherwise. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fegetround" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| <header filename = "fenv.h"/> |
| </headers> |
| <synopsis> |
| Returns the currently selected rounding mode, represented by one of the |
| values of the defined rounding mode macros. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fesetround" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int round"/> |
| </prototype> |
| <headers> |
| <header filename = "fenv.h"/> |
| </headers> |
| <synopsis> |
| Changes the currently selected rounding mode to <VAR>round</VAR>. If |
| <VAR>round</VAR> does not correspond to one of the supported rounding modes |
| nothing is changed. <CODE>fesetround</CODE> returns zero if it changed the |
| rounding mode, a nonzero value if the mode is not supported. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fegetenv" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="fenv_t *envp"/> |
| </prototype> |
| <headers> |
| <header filename = "fenv.h"/> |
| </headers> |
| <synopsis> |
| Store the floating-point environment in the variable pointed to by |
| <VAR>envp</VAR>. |
| <br><br> The function returns zero in case the operation was successful, a |
| non-zero value otherwise. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-feholdexcept" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="fenv_t *envp"/> |
| </prototype> |
| <headers> |
| <header filename = "fenv.h"/> |
| </headers> |
| <synopsis> |
| Store the current floating-point environment in the object pointed to by |
| <VAR>envp</VAR>. Then clear all exception flags, and set the FPU to trap no |
| exceptions. Not all FPUs support trapping no exceptions; if |
| <CODE>feholdexcept</CODE> cannot set this mode, it returns nonzero value. If it |
| succeeds, it returns zero. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fesetenv" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const fenv_t *envp"/> |
| </prototype> |
| <headers> |
| <header filename = "fenv.h"/> |
| </headers> |
| <synopsis> |
| Set the floating-point environment to that described by <VAR>envp</VAR>. |
| <br><br> The function returns zero in case the operation was successful, a |
| non-zero value otherwise. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-feupdateenv" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const fenv_t *envp"/> |
| </prototype> |
| <headers> |
| <header filename = "fenv.h"/> |
| </headers> |
| <synopsis> |
| Like <CODE>fesetenv</CODE>, this function sets the floating-point environment |
| to that described by <VAR>envp</VAR>. However, if any exceptions were |
| flagged in the status word before <CODE>feupdateenv</CODE> was called, they |
| remain flagged after the call. In other words, after <CODE>feupdateenv</CODE> |
| is called, the status word is the bitwise OR of the previous status word |
| and the one saved in <VAR>envp</VAR>. |
| <br><br> The function returns zero in case the operation was successful, a |
| non-zero value otherwise. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-feenableexcept" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int excepts"/> |
| </prototype> |
| <headers> |
| <header filename = "fenv.h"/> |
| </headers> |
| <synopsis> |
| This functions enables traps for each of the exceptions as indicated by |
| the parameter <VAR>except</VAR>. The individual excepetions are described in |
| Status bit operations. Only the specified exceptions are |
| enabled, the status of the other exceptions is not changed. |
| <br><br> The function returns the previous enabled exceptions in case the |
| operation was successful, <CODE>-1</CODE> otherwise. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fedisableexcept" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int excepts"/> |
| </prototype> |
| <headers> |
| <header filename = "fenv.h"/> |
| </headers> |
| <synopsis> |
| This functions disables traps for each of the exceptions as indicated by |
| the parameter <VAR>except</VAR>. The individual excepetions are described in |
| Status bit operations. Only the specified exceptions are |
| disabled, the status of the other exceptions is not changed. |
| <br><br> The function returns the previous enabled exceptions in case the |
| operation was successful, <CODE>-1</CODE> otherwise. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fegetexcept" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int excepts"/> |
| </prototype> |
| <headers> |
| <header filename = "fenv.h"/> |
| </headers> |
| <synopsis> |
| The function returns a bitmask of all currently enabled exceptions. It |
| returns <CODE>-1</CODE> in case of failure. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-abs" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int number"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| These functions return the absolute value of <VAR>number</VAR>. |
| <br><br> Most computers use a two's complement integer representation, in which |
| the absolute value of <CODE>INT_MIN</CODE> (the smallest possible <CODE>int</CODE>) |
| cannot be represented; thus, <CODE>abs (INT_MIN)</CODE> is not defined. |
| <br><br> <CODE>llabs</CODE> and <CODE>imaxdiv</CODE> are new to ISO C99. |
| <br><br> See Integers for a description of the <CODE>intmax_t</CODE> type. |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-labs" type="function"> |
| <function returntype="long int"> |
| <prototype> |
| <parameter content="long int number"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| These functions return the absolute value of <VAR>number</VAR>. |
| <br><br> Most computers use a two's complement integer representation, in which |
| the absolute value of <CODE>INT_MIN</CODE> (the smallest possible <CODE>int</CODE>) |
| cannot be represented; thus, <CODE>abs (INT_MIN)</CODE> is not defined. |
| <br><br> <CODE>llabs</CODE> and <CODE>imaxdiv</CODE> are new to ISO C99. |
| <br><br> See Integers for a description of the <CODE>intmax_t</CODE> type. |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-llabs" type="function"> |
| <function returntype="long long int"> |
| <prototype> |
| <parameter content="long long int number"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| These functions return the absolute value of <VAR>number</VAR>. |
| <br><br> Most computers use a two's complement integer representation, in which |
| the absolute value of <CODE>INT_MIN</CODE> (the smallest possible <CODE>int</CODE>) |
| cannot be represented; thus, <CODE>abs (INT_MIN)</CODE> is not defined. |
| <br><br> <CODE>llabs</CODE> and <CODE>imaxdiv</CODE> are new to ISO C99. |
| <br><br> See Integers for a description of the <CODE>intmax_t</CODE> type. |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-imaxabs" type="function"> |
| <function returntype="intmax_t"> |
| <prototype> |
| <parameter content="intmax_t number"/> |
| </prototype> |
| <headers> |
| <header filename = "inttypes.h"/> |
| </headers> |
| <synopsis> |
| These functions return the absolute value of <VAR>number</VAR>. |
| <br><br> Most computers use a two's complement integer representation, in which |
| the absolute value of <CODE>INT_MIN</CODE> (the smallest possible <CODE>int</CODE>) |
| cannot be represented; thus, <CODE>abs (INT_MIN)</CODE> is not defined. |
| <br><br> <CODE>llabs</CODE> and <CODE>imaxdiv</CODE> are new to ISO C99. |
| <br><br> See Integers for a description of the <CODE>intmax_t</CODE> type. |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fabs" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double number"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| This function returns the absolute value of the floating-point number |
| <VAR>number</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fabsf" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float number"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| This function returns the absolute value of the floating-point number |
| <VAR>number</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fabsl" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double number"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| This function returns the absolute value of the floating-point number |
| <VAR>number</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-cabs" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="complex double z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return the absolute value of the complex number <VAR>z</VAR> |
| . The absolute value of a complex number is: |
| <br><br> <pre><br> |
| sqrt (creal (<VAR>z</VAR>) * creal (<VAR>z</VAR>) + cimag (<VAR>z</VAR>) * cimag (<VAR>z</VAR>))<br> |
| </pre> |
| <br><br> This function should always be used instead of the direct formula |
| because it takes special care to avoid losing precision. It may also |
| take advantage of hardware support for this operation. See <CODE>hypot</CODE> |
| in Exponents and Logarithms. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-cabsf" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="complex float z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return the absolute value of the complex number <VAR>z</VAR> |
| . The absolute value of a complex number is: |
| <br><br> <pre><br> |
| sqrt (creal (<VAR>z</VAR>) * creal (<VAR>z</VAR>) + cimag (<VAR>z</VAR>) * cimag (<VAR>z</VAR>))<br> |
| </pre> |
| <br><br> This function should always be used instead of the direct formula |
| because it takes special care to avoid losing precision. It may also |
| take advantage of hardware support for this operation. See <CODE>hypot</CODE> |
| in Exponents and Logarithms. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-cabsl" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="complex long double z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return the absolute value of the complex number <VAR>z</VAR> |
| . The absolute value of a complex number is: |
| <br><br> <pre><br> |
| sqrt (creal (<VAR>z</VAR>) * creal (<VAR>z</VAR>) + cimag (<VAR>z</VAR>) * cimag (<VAR>z</VAR>))<br> |
| </pre> |
| <br><br> This function should always be used instead of the direct formula |
| because it takes special care to avoid losing precision. It may also |
| take advantage of hardware support for this operation. See <CODE>hypot</CODE> |
| in Exponents and Logarithms. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-frexp" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double value"/> |
| <parameter content="int *exponent"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions are used to split the number <VAR>value</VAR> |
| into a normalized fraction and an exponent. |
| <br><br> If the argument <VAR>value</VAR> is not zero, the return value is <VAR>value</VAR> |
| times a power of two, and is always in the range 1/2 (inclusive) to 1 |
| (exclusive). The corresponding exponent is stored in |
| <CODE>*<VAR>exponent</VAR></CODE>; the return value multiplied by 2 raised to this |
| exponent equals the original number <VAR>value</VAR>. |
| <br><br> For example, <CODE>frexp (12.8, &exponent)</CODE> returns <CODE>0.8</CODE> and |
| stores <CODE>4</CODE> in <CODE>exponent</CODE>. |
| <br><br> If <VAR>value</VAR> is zero, then the return value is zero and |
| zero is stored in <CODE>*<VAR>exponent</VAR></CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-frexpf" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float value"/> |
| <parameter content="int *exponent"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions are used to split the number <VAR>value</VAR> |
| into a normalized fraction and an exponent. |
| <br><br> If the argument <VAR>value</VAR> is not zero, the return value is <VAR>value</VAR> |
| times a power of two, and is always in the range 1/2 (inclusive) to 1 |
| (exclusive). The corresponding exponent is stored in |
| <CODE>*<VAR>exponent</VAR></CODE>; the return value multiplied by 2 raised to this |
| exponent equals the original number <VAR>value</VAR>. |
| <br><br> For example, <CODE>frexp (12.8, &exponent)</CODE> returns <CODE>0.8</CODE> and |
| stores <CODE>4</CODE> in <CODE>exponent</CODE>. |
| <br><br> If <VAR>value</VAR> is zero, then the return value is zero and |
| zero is stored in <CODE>*<VAR>exponent</VAR></CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-frexpl" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double value"/> |
| <parameter content="int *exponent"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions are used to split the number <VAR>value</VAR> |
| into a normalized fraction and an exponent. |
| <br><br> If the argument <VAR>value</VAR> is not zero, the return value is <VAR>value</VAR> |
| times a power of two, and is always in the range 1/2 (inclusive) to 1 |
| (exclusive). The corresponding exponent is stored in |
| <CODE>*<VAR>exponent</VAR></CODE>; the return value multiplied by 2 raised to this |
| exponent equals the original number <VAR>value</VAR>. |
| <br><br> For example, <CODE>frexp (12.8, &exponent)</CODE> returns <CODE>0.8</CODE> and |
| stores <CODE>4</CODE> in <CODE>exponent</CODE>. |
| <br><br> If <VAR>value</VAR> is zero, then the return value is zero and |
| zero is stored in <CODE>*<VAR>exponent</VAR></CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-ldexp" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double value"/> |
| <parameter content="int exponent"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions return the result of multiplying the floating-point |
| number <VAR>value</VAR> by 2 raised to the power <VAR>exponent</VAR>. (It can |
| be used to reassemble floating-point numbers that were taken apart |
| by <CODE>frexp</CODE>.) |
| <br><br> For example, <CODE>ldexp (0.8, 4)</CODE> returns <CODE>12.8</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-ldexpf" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float value"/> |
| <parameter content="int exponent"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions return the result of multiplying the floating-point |
| number <VAR>value</VAR> by 2 raised to the power <VAR>exponent</VAR>. (It can |
| be used to reassemble floating-point numbers that were taken apart |
| by <CODE>frexp</CODE>.) |
| <br><br> For example, <CODE>ldexp (0.8, 4)</CODE> returns <CODE>12.8</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-ldexpl" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double value"/> |
| <parameter content="int exponent"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions return the result of multiplying the floating-point |
| number <VAR>value</VAR> by 2 raised to the power <VAR>exponent</VAR>. (It can |
| be used to reassemble floating-point numbers that were taken apart |
| by <CODE>frexp</CODE>.) |
| <br><br> For example, <CODE>ldexp (0.8, 4)</CODE> returns <CODE>12.8</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-scalb" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double value"/> |
| <parameter content="int exponent"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>scalb</CODE> function is the BSD name for <CODE>ldexp</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-scalbf" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float value"/> |
| <parameter content="int exponent"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>scalb</CODE> function is the BSD name for <CODE>ldexp</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-scalbl" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double value"/> |
| <parameter content="int exponent"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>scalb</CODE> function is the BSD name for <CODE>ldexp</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-scalbn" type="function"> |
| <function returntype="long long int"> |
| <prototype> |
| <parameter content="double x"/> |
| <parameter content="int n"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| <CODE>scalbn</CODE> is identical to <CODE>scalb</CODE>, except that the exponent |
| <VAR>n</VAR> is an <CODE>int</CODE> instead of a floating-point number. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-scalbnf" type="function"> |
| <function returntype="long long int"> |
| <prototype> |
| <parameter content="float x"/> |
| <parameter content="int n"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| <CODE>scalbn</CODE> is identical to <CODE>scalb</CODE>, except that the exponent |
| <VAR>n</VAR> is an <CODE>int</CODE> instead of a floating-point number. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-scalbnl" type="function"> |
| <function returntype="long long int"> |
| <prototype> |
| <parameter content="long double x"/> |
| <parameter content="int n"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| <CODE>scalbn</CODE> is identical to <CODE>scalb</CODE>, except that the exponent |
| <VAR>n</VAR> is an <CODE>int</CODE> instead of a floating-point number. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-scalbln" type="function"> |
| <function returntype="long long int"> |
| <prototype> |
| <parameter content="double x"/> |
| <parameter content="long int n"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| <CODE>scalbln</CODE> is identical to <CODE>scalb</CODE>, except that the exponent |
| <VAR>n</VAR> is a <CODE>long int</CODE> instead of a floating-point number. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-scalblnf" type="function"> |
| <function returntype="long long int"> |
| <prototype> |
| <parameter content="float x"/> |
| <parameter content="long int n"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| <CODE>scalbln</CODE> is identical to <CODE>scalb</CODE>, except that the exponent |
| <VAR>n</VAR> is a <CODE>long int</CODE> instead of a floating-point number. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-scalblnl" type="function"> |
| <function returntype="long long int"> |
| <prototype> |
| <parameter content="long double x"/> |
| <parameter content="long int n"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| <CODE>scalbln</CODE> is identical to <CODE>scalb</CODE>, except that the exponent |
| <VAR>n</VAR> is a <CODE>long int</CODE> instead of a floating-point number. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-significand" type="function"> |
| <function returntype="long long int"> |
| <prototype> |
| <parameter content="double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| <CODE>significand</CODE> returns the mantissa of <VAR>x</VAR> scaled to the range |
| [1, 2). |
| It is equivalent to <CODE>scalb (<VAR>x</VAR>, (double) -ilogb (<VAR>x</VAR>))</CODE>. |
| <br><br> This function exists mainly for use in certain standardized tests |
| of IEEE 754 conformance. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-significandf" type="function"> |
| <function returntype="long long int"> |
| <prototype> |
| <parameter content="float x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| <CODE>significand</CODE> returns the mantissa of <VAR>x</VAR> scaled to the range |
| [1, 2). |
| It is equivalent to <CODE>scalb (<VAR>x</VAR>, (double) -ilogb (<VAR>x</VAR>))</CODE>. |
| <br><br> This function exists mainly for use in certain standardized tests |
| of IEEE 754 conformance. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-significandl" type="function"> |
| <function returntype="long long int"> |
| <prototype> |
| <parameter content="long double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| <CODE>significand</CODE> returns the mantissa of <VAR>x</VAR> scaled to the range |
| [1, 2). |
| It is equivalent to <CODE>scalb (<VAR>x</VAR>, (double) -ilogb (<VAR>x</VAR>))</CODE>. |
| <br><br> This function exists mainly for use in certain standardized tests |
| of IEEE 754 conformance. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-ceil" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions round <VAR>x</VAR> upwards to the nearest integer, |
| returning that value as a <CODE>double</CODE>. Thus, <CODE>ceil (1.5)</CODE> |
| is <CODE>2.0</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-ceilf" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions round <VAR>x</VAR> upwards to the nearest integer, |
| returning that value as a <CODE>double</CODE>. Thus, <CODE>ceil (1.5)</CODE> |
| is <CODE>2.0</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-ceill" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions round <VAR>x</VAR> upwards to the nearest integer, |
| returning that value as a <CODE>double</CODE>. Thus, <CODE>ceil (1.5)</CODE> |
| is <CODE>2.0</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-floor" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions round <VAR>x</VAR> downwards to the nearest |
| integer, returning that value as a <CODE>double</CODE>. Thus, <CODE>floor |
| (1.5)</CODE> is <CODE>1.0</CODE> and <CODE>floor (-1.5)</CODE> is <CODE>-2.0</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-floorf" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions round <VAR>x</VAR> downwards to the nearest |
| integer, returning that value as a <CODE>double</CODE>. Thus, <CODE>floor |
| (1.5)</CODE> is <CODE>1.0</CODE> and <CODE>floor (-1.5)</CODE> is <CODE>-2.0</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-floorl" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions round <VAR>x</VAR> downwards to the nearest |
| integer, returning that value as a <CODE>double</CODE>. Thus, <CODE>floor |
| (1.5)</CODE> is <CODE>1.0</CODE> and <CODE>floor (-1.5)</CODE> is <CODE>-2.0</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-trunc" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>trunc</CODE> functions round <VAR>x</VAR> towards zero to the nearest |
| integer (returned in floating-point format). Thus, <CODE>trunc (1.5)</CODE> |
| is <CODE>1.0</CODE> and <CODE>trunc (-1.5)</CODE> is <CODE>-1.0</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-truncf" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>trunc</CODE> functions round <VAR>x</VAR> towards zero to the nearest |
| integer (returned in floating-point format). Thus, <CODE>trunc (1.5)</CODE> |
| is <CODE>1.0</CODE> and <CODE>trunc (-1.5)</CODE> is <CODE>-1.0</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-truncl" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>trunc</CODE> functions round <VAR>x</VAR> towards zero to the nearest |
| integer (returned in floating-point format). Thus, <CODE>trunc (1.5)</CODE> |
| is <CODE>1.0</CODE> and <CODE>trunc (-1.5)</CODE> is <CODE>-1.0</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-rint" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions round <VAR>x</VAR> to an integer value according to the |
| current rounding mode. , for |
| information about the various rounding modes. The default |
| rounding mode is to round to the nearest integer; some machines |
| support other modes, but round-to-nearest is always used unless |
| you explicitly select another. |
| <br><br> If <VAR>x</VAR> was not initially an integer, these functions raise the |
| inexact exception. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-rintf" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions round <VAR>x</VAR> to an integer value according to the |
| current rounding mode. , for |
| information about the various rounding modes. The default |
| rounding mode is to round to the nearest integer; some machines |
| support other modes, but round-to-nearest is always used unless |
| you explicitly select another. |
| <br><br> If <VAR>x</VAR> was not initially an integer, these functions raise the |
| inexact exception. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-rintl" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions round <VAR>x</VAR> to an integer value according to the |
| current rounding mode. , for |
| information about the various rounding modes. The default |
| rounding mode is to round to the nearest integer; some machines |
| support other modes, but round-to-nearest is always used unless |
| you explicitly select another. |
| <br><br> If <VAR>x</VAR> was not initially an integer, these functions raise the |
| inexact exception. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-nearbyint" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions return the same value as the <CODE>rint</CODE> functions, but |
| do not raise the inexact exception if <VAR>x</VAR> is not an integer. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-nearbyintf" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions return the same value as the <CODE>rint</CODE> functions, but |
| do not raise the inexact exception if <VAR>x</VAR> is not an integer. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-nearbyintl" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions return the same value as the <CODE>rint</CODE> functions, but |
| do not raise the inexact exception if <VAR>x</VAR> is not an integer. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-round" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions are similar to <CODE>rint</CODE>, but they round halfway |
| cases away from zero instead of to the nearest integer (or other |
| current rounding mode). |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-roundf" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions are similar to <CODE>rint</CODE>, but they round halfway |
| cases away from zero instead of to the nearest integer (or other |
| current rounding mode). |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-roundl" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions are similar to <CODE>rint</CODE>, but they round halfway |
| cases away from zero instead of to the nearest integer (or other |
| current rounding mode). |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-lrint" type="function"> |
| <function returntype="long int"> |
| <prototype> |
| <parameter content="double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions are just like <CODE>rint</CODE>, but they return a |
| <CODE>long int</CODE> instead of a floating-point number. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-lrintf" type="function"> |
| <function returntype="long int"> |
| <prototype> |
| <parameter content="float x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions are just like <CODE>rint</CODE>, but they return a |
| <CODE>long int</CODE> instead of a floating-point number. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-lrintl" type="function"> |
| <function returntype="long int"> |
| <prototype> |
| <parameter content="long double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions are just like <CODE>rint</CODE>, but they return a |
| <CODE>long int</CODE> instead of a floating-point number. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-llrint" type="function"> |
| <function returntype="long long int"> |
| <prototype> |
| <parameter content="double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions are just like <CODE>rint</CODE>, but they return a |
| <CODE>long long int</CODE> instead of a floating-point number. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-llrintf" type="function"> |
| <function returntype="long long int"> |
| <prototype> |
| <parameter content="float x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions are just like <CODE>rint</CODE>, but they return a |
| <CODE>long long int</CODE> instead of a floating-point number. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-llrintl" type="function"> |
| <function returntype="long long int"> |
| <prototype> |
| <parameter content="long double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions are just like <CODE>rint</CODE>, but they return a |
| <CODE>long long int</CODE> instead of a floating-point number. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-lround" type="function"> |
| <function returntype="long int"> |
| <prototype> |
| <parameter content="double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions are just like <CODE>round</CODE>, but they return a |
| <CODE>long int</CODE> instead of a floating-point number. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-lroundf" type="function"> |
| <function returntype="long int"> |
| <prototype> |
| <parameter content="float x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions are just like <CODE>round</CODE>, but they return a |
| <CODE>long int</CODE> instead of a floating-point number. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-lroundl" type="function"> |
| <function returntype="long int"> |
| <prototype> |
| <parameter content="long double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions are just like <CODE>round</CODE>, but they return a |
| <CODE>long int</CODE> instead of a floating-point number. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-llround" type="function"> |
| <function returntype="long long int"> |
| <prototype> |
| <parameter content="double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions are just like <CODE>round</CODE>, but they return a |
| <CODE>long long int</CODE> instead of a floating-point number. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-llroundf" type="function"> |
| <function returntype="long long int"> |
| <prototype> |
| <parameter content="float x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions are just like <CODE>round</CODE>, but they return a |
| <CODE>long long int</CODE> instead of a floating-point number. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-llroundl" type="function"> |
| <function returntype="long long int"> |
| <prototype> |
| <parameter content="long double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions are just like <CODE>round</CODE>, but they return a |
| <CODE>long long int</CODE> instead of a floating-point number. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-modf" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double value"/> |
| <parameter content="double *integer-part"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions break the argument <VAR>value</VAR> into an integer part and a |
| fractional part (between <CODE>-1</CODE> and <CODE>1</CODE>, exclusive). Their sum |
| equals <VAR>value</VAR>. Each of the parts has the same sign as <VAR>value</VAR>, |
| and the integer part is always rounded toward zero. |
| <br><br> <CODE>modf</CODE> stores the integer part in <CODE>*<VAR>integer-part</VAR></CODE>, and |
| returns the fractional part. For example, <CODE>modf (2.5, &intpart)</CODE> |
| returns <CODE>0.5</CODE> and stores <CODE>2.0</CODE> into <CODE>intpart</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-modff" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float value"/> |
| <parameter content="float *integer-part"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions break the argument <VAR>value</VAR> into an integer part and a |
| fractional part (between <CODE>-1</CODE> and <CODE>1</CODE>, exclusive). Their sum |
| equals <VAR>value</VAR>. Each of the parts has the same sign as <VAR>value</VAR>, |
| and the integer part is always rounded toward zero. |
| <br><br> <CODE>modf</CODE> stores the integer part in <CODE>*<VAR>integer-part</VAR></CODE>, and |
| returns the fractional part. For example, <CODE>modf (2.5, &intpart)</CODE> |
| returns <CODE>0.5</CODE> and stores <CODE>2.0</CODE> into <CODE>intpart</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-modfl" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double value"/> |
| <parameter content="long double *integer-part"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions break the argument <VAR>value</VAR> into an integer part and a |
| fractional part (between <CODE>-1</CODE> and <CODE>1</CODE>, exclusive). Their sum |
| equals <VAR>value</VAR>. Each of the parts has the same sign as <VAR>value</VAR>, |
| and the integer part is always rounded toward zero. |
| <br><br> <CODE>modf</CODE> stores the integer part in <CODE>*<VAR>integer-part</VAR></CODE>, and |
| returns the fractional part. For example, <CODE>modf (2.5, &intpart)</CODE> |
| returns <CODE>0.5</CODE> and stores <CODE>2.0</CODE> into <CODE>intpart</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fmod" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double numerator"/> |
| <parameter content="double denominator"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions compute the remainder from the division of |
| <VAR>numerator</VAR> by <VAR>denominator</VAR>. Specifically, the return value is |
| <CODE><VAR>numerator</VAR> - <VAR>n</VAR> * <VAR>denominator</VAR></CODE>, where <VAR>n</VAR> |
| is the quotient of <VAR>numerator</VAR> divided by <VAR>denominator</VAR>, rounded |
| towards zero to an integer. Thus, <CODE>fmod (6.5, 2.3)</CODE> returns |
| <CODE>1.9</CODE>, which is <CODE>6.5</CODE> minus <CODE>4.6</CODE>. |
| <br><br> The result has the same sign as the <VAR>numerator</VAR> and has magnitude |
| less than the magnitude of the <VAR>denominator</VAR>. |
| <br><br> If <VAR>denominator</VAR> is zero, <CODE>fmod</CODE> signals a domain error. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fmodf" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float numerator"/> |
| <parameter content="float denominator"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions compute the remainder from the division of |
| <VAR>numerator</VAR> by <VAR>denominator</VAR>. Specifically, the return value is |
| <CODE><VAR>numerator</VAR> - <VAR>n</VAR> * <VAR>denominator</VAR></CODE>, where <VAR>n</VAR> |
| is the quotient of <VAR>numerator</VAR> divided by <VAR>denominator</VAR>, rounded |
| towards zero to an integer. Thus, <CODE>fmod (6.5, 2.3)</CODE> returns |
| <CODE>1.9</CODE>, which is <CODE>6.5</CODE> minus <CODE>4.6</CODE>. |
| <br><br> The result has the same sign as the <VAR>numerator</VAR> and has magnitude |
| less than the magnitude of the <VAR>denominator</VAR>. |
| <br><br> If <VAR>denominator</VAR> is zero, <CODE>fmod</CODE> signals a domain error. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fmodl" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double numerator"/> |
| <parameter content="long double denominator"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions compute the remainder from the division of |
| <VAR>numerator</VAR> by <VAR>denominator</VAR>. Specifically, the return value is |
| <CODE><VAR>numerator</VAR> - <VAR>n</VAR> * <VAR>denominator</VAR></CODE>, where <VAR>n</VAR> |
| is the quotient of <VAR>numerator</VAR> divided by <VAR>denominator</VAR>, rounded |
| towards zero to an integer. Thus, <CODE>fmod (6.5, 2.3)</CODE> returns |
| <CODE>1.9</CODE>, which is <CODE>6.5</CODE> minus <CODE>4.6</CODE>. |
| <br><br> The result has the same sign as the <VAR>numerator</VAR> and has magnitude |
| less than the magnitude of the <VAR>denominator</VAR>. |
| <br><br> If <VAR>denominator</VAR> is zero, <CODE>fmod</CODE> signals a domain error. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-drem" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double numerator"/> |
| <parameter content="double denominator"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions are like <CODE>fmod</CODE> except that they round the |
| internal quotient <VAR>n</VAR> to the nearest integer instead of towards zero |
| to an integer. For example, <CODE>drem (6.5, 2.3)</CODE> returns <CODE>-0.4</CODE>, |
| which is <CODE>6.5</CODE> minus <CODE>6.9</CODE>. |
| <br><br> The absolute value of the result is less than or equal to half the |
| absolute value of the <VAR>denominator</VAR>. The difference between |
| <CODE>fmod (<VAR>numerator</VAR>, <VAR>denominator</VAR>)</CODE> and <CODE>drem |
| (<VAR>numerator</VAR>, <VAR>denominator</VAR>)</CODE> is always either |
| <VAR>denominator</VAR>, minus <VAR>denominator</VAR>, or zero. |
| <br><br> If <VAR>denominator</VAR> is zero, <CODE>drem</CODE> signals a domain error. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-dremf" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float numerator"/> |
| <parameter content="float denominator"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions are like <CODE>fmod</CODE> except that they round the |
| internal quotient <VAR>n</VAR> to the nearest integer instead of towards zero |
| to an integer. For example, <CODE>drem (6.5, 2.3)</CODE> returns <CODE>-0.4</CODE>, |
| which is <CODE>6.5</CODE> minus <CODE>6.9</CODE>. |
| <br><br> The absolute value of the result is less than or equal to half the |
| absolute value of the <VAR>denominator</VAR>. The difference between |
| <CODE>fmod (<VAR>numerator</VAR>, <VAR>denominator</VAR>)</CODE> and <CODE>drem |
| (<VAR>numerator</VAR>, <VAR>denominator</VAR>)</CODE> is always either |
| <VAR>denominator</VAR>, minus <VAR>denominator</VAR>, or zero. |
| <br><br> If <VAR>denominator</VAR> is zero, <CODE>drem</CODE> signals a domain error. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-dreml" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double numerator"/> |
| <parameter content="long double denominator"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions are like <CODE>fmod</CODE> except that they round the |
| internal quotient <VAR>n</VAR> to the nearest integer instead of towards zero |
| to an integer. For example, <CODE>drem (6.5, 2.3)</CODE> returns <CODE>-0.4</CODE>, |
| which is <CODE>6.5</CODE> minus <CODE>6.9</CODE>. |
| <br><br> The absolute value of the result is less than or equal to half the |
| absolute value of the <VAR>denominator</VAR>. The difference between |
| <CODE>fmod (<VAR>numerator</VAR>, <VAR>denominator</VAR>)</CODE> and <CODE>drem |
| (<VAR>numerator</VAR>, <VAR>denominator</VAR>)</CODE> is always either |
| <VAR>denominator</VAR>, minus <VAR>denominator</VAR>, or zero. |
| <br><br> If <VAR>denominator</VAR> is zero, <CODE>drem</CODE> signals a domain error. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-remainder" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double numerator"/> |
| <parameter content="double denominator"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| This function is another name for <CODE>drem</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-remainderf" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float numerator"/> |
| <parameter content="float denominator"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| This function is another name for <CODE>drem</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-remainderl" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double numerator"/> |
| <parameter content="long double denominator"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| This function is another name for <CODE>drem</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-copysign" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double x"/> |
| <parameter content="double y"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions return <VAR>x</VAR> but with the sign of <VAR>y</VAR>. They work |
| even if <VAR>x</VAR> or <VAR>y</VAR> are NaN or zero. Both of these can carry a |
| sign (although not all implementations support it) and this is one of |
| the few operations that can tell the difference. |
| <br><br> <CODE>copysign</CODE> never raises an exception. |
| <br><br> This function is defined in IEC 559 (and the appendix with |
| recommended functions in IEEE 754/IEEE 854). |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-copysignf" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float x"/> |
| <parameter content="float y"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions return <VAR>x</VAR> but with the sign of <VAR>y</VAR>. They work |
| even if <VAR>x</VAR> or <VAR>y</VAR> are NaN or zero. Both of these can carry a |
| sign (although not all implementations support it) and this is one of |
| the few operations that can tell the difference. |
| <br><br> <CODE>copysign</CODE> never raises an exception. |
| <br><br> This function is defined in IEC 559 (and the appendix with |
| recommended functions in IEEE 754/IEEE 854). |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-copysignl" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double x"/> |
| <parameter content="long double y"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions return <VAR>x</VAR> but with the sign of <VAR>y</VAR>. They work |
| even if <VAR>x</VAR> or <VAR>y</VAR> are NaN or zero. Both of these can carry a |
| sign (although not all implementations support it) and this is one of |
| the few operations that can tell the difference. |
| <br><br> <CODE>copysign</CODE> never raises an exception. |
| <br><br> This function is defined in IEC 559 (and the appendix with |
| recommended functions in IEEE 754/IEEE 854). |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-signbit" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content=" x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| <CODE>signbit</CODE> is a generic macro which can work on all floating-point |
| types. It returns a nonzero value if the value of <VAR>x</VAR> has its sign |
| bit set. |
| <br><br> This is not the same as <CODE>x < 0.0</CODE>, because IEEE 754 floating |
| point allows zero to be signed. The comparison <CODE>-0.0 < 0.0</CODE> is |
| false, but <CODE>signbit (-0.0)</CODE> will return a nonzero value. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-nextafter" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double x"/> |
| <parameter content="double y"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>nextafter</CODE> function returns the next representable neighbor of |
| <VAR>x</VAR> in the direction towards <VAR>y</VAR>. The size of the step between |
| <VAR>x</VAR> and the result depends on the type of the result. If |
| <VAR>x</VAR> = <VAR>y</VAR> the function simply returns <VAR>y</VAR>. If either |
| value is <CODE>NaN</CODE>, <CODE>NaN</CODE> is returned. Otherwise |
| a value corresponding to the value of the least significant bit in the |
| mantissa is added or subtracted, depending on the direction. |
| <CODE>nextafter</CODE> will signal overflow or underflow if the result goes |
| outside of the range of normalized numbers. |
| <br><br> This function is defined in IEC 559 (and the appendix with |
| recommended functions in IEEE 754/IEEE 854). |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-nextafterf" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float x"/> |
| <parameter content="float y"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>nextafter</CODE> function returns the next representable neighbor of |
| <VAR>x</VAR> in the direction towards <VAR>y</VAR>. The size of the step between |
| <VAR>x</VAR> and the result depends on the type of the result. If |
| <VAR>x</VAR> = <VAR>y</VAR> the function simply returns <VAR>y</VAR>. If either |
| value is <CODE>NaN</CODE>, <CODE>NaN</CODE> is returned. Otherwise |
| a value corresponding to the value of the least significant bit in the |
| mantissa is added or subtracted, depending on the direction. |
| <CODE>nextafter</CODE> will signal overflow or underflow if the result goes |
| outside of the range of normalized numbers. |
| <br><br> This function is defined in IEC 559 (and the appendix with |
| recommended functions in IEEE 754/IEEE 854). |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-nextafterl" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double x"/> |
| <parameter content="long double y"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>nextafter</CODE> function returns the next representable neighbor of |
| <VAR>x</VAR> in the direction towards <VAR>y</VAR>. The size of the step between |
| <VAR>x</VAR> and the result depends on the type of the result. If |
| <VAR>x</VAR> = <VAR>y</VAR> the function simply returns <VAR>y</VAR>. If either |
| value is <CODE>NaN</CODE>, <CODE>NaN</CODE> is returned. Otherwise |
| a value corresponding to the value of the least significant bit in the |
| mantissa is added or subtracted, depending on the direction. |
| <CODE>nextafter</CODE> will signal overflow or underflow if the result goes |
| outside of the range of normalized numbers. |
| <br><br> This function is defined in IEC 559 (and the appendix with |
| recommended functions in IEEE 754/IEEE 854). |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-nexttoward" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double x"/> |
| <parameter content="long double y"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions are identical to the corresponding versions of |
| <CODE>nextafter</CODE> except that their second argument is a <CODE>long |
| double</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-nexttowardf" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float x"/> |
| <parameter content="long double y"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions are identical to the corresponding versions of |
| <CODE>nextafter</CODE> except that their second argument is a <CODE>long |
| double</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-nexttowardl" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double x"/> |
| <parameter content="long double y"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions are identical to the corresponding versions of |
| <CODE>nextafter</CODE> except that their second argument is a <CODE>long |
| double</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-nan" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="const char *tagp"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>nan</CODE> function returns a representation of NaN, provided that |
| NaN is supported by the target platform. |
| <CODE>nan ("<VAR>n-char-sequence</VAR>")</CODE> is equivalent to |
| <CODE>strtod ("NAN(<VAR>n-char-sequence</VAR>)")</CODE>. |
| <br><br> The argument <VAR>tagp</VAR> is used in an unspecified manner. On IEEE |
| 754 systems, there are many representations of NaN, and <VAR>tagp</VAR> |
| selects one. On other systems it may do nothing. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-nanf" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="const char *tagp"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>nan</CODE> function returns a representation of NaN, provided that |
| NaN is supported by the target platform. |
| <CODE>nan ("<VAR>n-char-sequence</VAR>")</CODE> is equivalent to |
| <CODE>strtod ("NAN(<VAR>n-char-sequence</VAR>)")</CODE>. |
| <br><br> The argument <VAR>tagp</VAR> is used in an unspecified manner. On IEEE |
| 754 systems, there are many representations of NaN, and <VAR>tagp</VAR> |
| selects one. On other systems it may do nothing. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-nanl" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="const char *tagp"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>nan</CODE> function returns a representation of NaN, provided that |
| NaN is supported by the target platform. |
| <CODE>nan ("<VAR>n-char-sequence</VAR>")</CODE> is equivalent to |
| <CODE>strtod ("NAN(<VAR>n-char-sequence</VAR>)")</CODE>. |
| <br><br> The argument <VAR>tagp</VAR> is used in an unspecified manner. On IEEE |
| 754 systems, there are many representations of NaN, and <VAR>tagp</VAR> |
| selects one. On other systems it may do nothing. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fmin" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double x"/> |
| <parameter content="double y"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>fmin</CODE> function returns the lesser of the two values <VAR>x</VAR> |
| and <VAR>y</VAR>. It is similar to the expression |
| <pre><br> |
| ((x) < (y) ? (x) : (y))<br> |
| </pre> |
| except that <VAR>x</VAR> and <VAR>y</VAR> are only evaluated once. |
| <br><br> If an argument is NaN, the other argument is returned. If both arguments |
| are NaN, NaN is returned. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fminf" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float x"/> |
| <parameter content="float y"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>fmin</CODE> function returns the lesser of the two values <VAR>x</VAR> |
| and <VAR>y</VAR>. It is similar to the expression |
| <pre><br> |
| ((x) < (y) ? (x) : (y))<br> |
| </pre> |
| except that <VAR>x</VAR> and <VAR>y</VAR> are only evaluated once. |
| <br><br> If an argument is NaN, the other argument is returned. If both arguments |
| are NaN, NaN is returned. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fminl" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double x"/> |
| <parameter content="long double y"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>fmin</CODE> function returns the lesser of the two values <VAR>x</VAR> |
| and <VAR>y</VAR>. It is similar to the expression |
| <pre><br> |
| ((x) < (y) ? (x) : (y))<br> |
| </pre> |
| except that <VAR>x</VAR> and <VAR>y</VAR> are only evaluated once. |
| <br><br> If an argument is NaN, the other argument is returned. If both arguments |
| are NaN, NaN is returned. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fmax" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double x"/> |
| <parameter content="double y"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>fmax</CODE> function returns the greater of the two values <VAR>x</VAR> |
| and <VAR>y</VAR>. |
| <br><br> If an argument is NaN, the other argument is returned. If both arguments |
| are NaN, NaN is returned. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fmaxf" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float x"/> |
| <parameter content="float y"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>fmax</CODE> function returns the greater of the two values <VAR>x</VAR> |
| and <VAR>y</VAR>. |
| <br><br> If an argument is NaN, the other argument is returned. If both arguments |
| are NaN, NaN is returned. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fmaxl" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double x"/> |
| <parameter content="long double y"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>fmax</CODE> function returns the greater of the two values <VAR>x</VAR> |
| and <VAR>y</VAR>. |
| <br><br> If an argument is NaN, the other argument is returned. If both arguments |
| are NaN, NaN is returned. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fdim" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double x"/> |
| <parameter content="double y"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>fdim</CODE> function returns the positive difference between |
| <VAR>x</VAR> and <VAR>y</VAR>. The positive difference is <VAR>x</VAR> - |
| <VAR>y</VAR> if <VAR>x</VAR> is greater than <VAR>y</VAR>, and 0 otherwise. |
| <br><br> If <VAR>x</VAR>, <VAR>y</VAR>, or both are NaN, NaN is returned. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fdimf" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float x"/> |
| <parameter content="float y"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>fdim</CODE> function returns the positive difference between |
| <VAR>x</VAR> and <VAR>y</VAR>. The positive difference is <VAR>x</VAR> - |
| <VAR>y</VAR> if <VAR>x</VAR> is greater than <VAR>y</VAR>, and 0 otherwise. |
| <br><br> If <VAR>x</VAR>, <VAR>y</VAR>, or both are NaN, NaN is returned. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fdiml" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double x"/> |
| <parameter content="long double y"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>fdim</CODE> function returns the positive difference between |
| <VAR>x</VAR> and <VAR>y</VAR>. The positive difference is <VAR>x</VAR> - |
| <VAR>y</VAR> if <VAR>x</VAR> is greater than <VAR>y</VAR>, and 0 otherwise. |
| <br><br> If <VAR>x</VAR>, <VAR>y</VAR>, or both are NaN, NaN is returned. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fma" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double x"/> |
| <parameter content="double y"/> |
| <parameter content="double z"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| |
| The <CODE>fma</CODE> function performs floating-point multiply-add. This is |
| the operation (<VAR>x</VAR> <VAR>y</VAR>) + <VAR>z</VAR>, but the |
| intermediate result is not rounded to the destination type. This can |
| sometimes improve the precision of a calculation. |
| <br><br> This function was introduced because some processors have a special |
| instruction to perform multiply-add. The C compiler cannot use it |
| directly, because the expression <samp>x*y + z</samp> is defined to round the |
| intermediate result. <CODE>fma</CODE> lets you choose when you want to round |
| only once. |
| <br><br> |
| On processors which do not implement multiply-add in hardware, |
| <CODE>fma</CODE> can be very slow since it must avoid intermediate rounding. |
| <TT>math.h</TT> defines the symbols <CODE>FP_FAST_FMA</CODE>, |
| <CODE>FP_FAST_FMAF</CODE>, and <CODE>FP_FAST_FMAL</CODE> when the corresponding |
| version of <CODE>fma</CODE> is no slower than the expression <samp>x*y + z</samp>. |
| In the GNU C library, this always means the operation is implemented in |
| hardware. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fmaf" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float x"/> |
| <parameter content="float y"/> |
| <parameter content="float z"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| |
| The <CODE>fma</CODE> function performs floating-point multiply-add. This is |
| the operation (<VAR>x</VAR> <VAR>y</VAR>) + <VAR>z</VAR>, but the |
| intermediate result is not rounded to the destination type. This can |
| sometimes improve the precision of a calculation. |
| <br><br> This function was introduced because some processors have a special |
| instruction to perform multiply-add. The C compiler cannot use it |
| directly, because the expression <samp>x*y + z</samp> is defined to round the |
| intermediate result. <CODE>fma</CODE> lets you choose when you want to round |
| only once. |
| <br><br> |
| On processors which do not implement multiply-add in hardware, |
| <CODE>fma</CODE> can be very slow since it must avoid intermediate rounding. |
| <TT>math.h</TT> defines the symbols <CODE>FP_FAST_FMA</CODE>, |
| <CODE>FP_FAST_FMAF</CODE>, and <CODE>FP_FAST_FMAL</CODE> when the corresponding |
| version of <CODE>fma</CODE> is no slower than the expression <samp>x*y + z</samp>. |
| In the GNU C library, this always means the operation is implemented in |
| hardware. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fmal" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double x"/> |
| <parameter content="long double y"/> |
| <parameter content="long double z"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| |
| The <CODE>fma</CODE> function performs floating-point multiply-add. This is |
| the operation (<VAR>x</VAR> <VAR>y</VAR>) + <VAR>z</VAR>, but the |
| intermediate result is not rounded to the destination type. This can |
| sometimes improve the precision of a calculation. |
| <br><br> This function was introduced because some processors have a special |
| instruction to perform multiply-add. The C compiler cannot use it |
| directly, because the expression <samp>x*y + z</samp> is defined to round the |
| intermediate result. <CODE>fma</CODE> lets you choose when you want to round |
| only once. |
| <br><br> |
| On processors which do not implement multiply-add in hardware, |
| <CODE>fma</CODE> can be very slow since it must avoid intermediate rounding. |
| <TT>math.h</TT> defines the symbols <CODE>FP_FAST_FMA</CODE>, |
| <CODE>FP_FAST_FMAF</CODE>, and <CODE>FP_FAST_FMAL</CODE> when the corresponding |
| version of <CODE>fma</CODE> is no slower than the expression <samp>x*y + z</samp>. |
| In the GNU C library, this always means the operation is implemented in |
| hardware. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-creal" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="complex double z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return the real part of the complex number <VAR>z</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-crealf" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="complex float z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return the real part of the complex number <VAR>z</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-creall" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="complex long double z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return the real part of the complex number <VAR>z</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-cimag" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="complex double z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return the imaginary part of the complex number <VAR>z</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-cimagf" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="complex float z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return the imaginary part of the complex number <VAR>z</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-cimagl" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="complex long double z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return the imaginary part of the complex number <VAR>z</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-conj" type="function"> |
| <function returntype="complex double"> |
| <prototype> |
| <parameter content="complex double z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return the conjugate value of the complex number |
| <VAR>z</VAR>. The conjugate of a complex number has the same real part and a |
| negated imaginary part. In other words, <samp>conj(a + bi) = a + -bi</samp>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-conjf" type="function"> |
| <function returntype="complex float"> |
| <prototype> |
| <parameter content="complex float z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return the conjugate value of the complex number |
| <VAR>z</VAR>. The conjugate of a complex number has the same real part and a |
| negated imaginary part. In other words, <samp>conj(a + bi) = a + -bi</samp>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-conjl" type="function"> |
| <function returntype="complex long double"> |
| <prototype> |
| <parameter content="complex long double z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return the conjugate value of the complex number |
| <VAR>z</VAR>. The conjugate of a complex number has the same real part and a |
| negated imaginary part. In other words, <samp>conj(a + bi) = a + -bi</samp>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-carg" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="complex double z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return the argument of the complex number <VAR>z</VAR>. |
| The argument of a complex number is the angle in the complex plane |
| between the positive real axis and a line passing through zero and the |
| number. This angle is measured in the usual fashion and ranges from 0 |
| to 2. |
| <br><br> <CODE>carg</CODE> has a branch cut along the positive real axis. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-cargf" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="complex float z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return the argument of the complex number <VAR>z</VAR>. |
| The argument of a complex number is the angle in the complex plane |
| between the positive real axis and a line passing through zero and the |
| number. This angle is measured in the usual fashion and ranges from 0 |
| to 2. |
| <br><br> <CODE>carg</CODE> has a branch cut along the positive real axis. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-cargl" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="complex long double z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return the argument of the complex number <VAR>z</VAR>. |
| The argument of a complex number is the angle in the complex plane |
| between the positive real axis and a line passing through zero and the |
| number. This angle is measured in the usual fashion and ranges from 0 |
| to 2. |
| <br><br> <CODE>carg</CODE> has a branch cut along the positive real axis. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-cproj" type="function"> |
| <function returntype="complex double"> |
| <prototype> |
| <parameter content="complex double z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return the projection of the complex value <VAR>z</VAR> onto |
| the Riemann sphere. Values with a infinite imaginary part are projected |
| to positive infinity on the real axis, even if the real part is NaN. If |
| the real part is infinite, the result is equivalent to |
| <br><br> <pre><br> |
| INFINITY + I * copysign (0.0, cimag (z))<br> |
| </pre> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-cprojf" type="function"> |
| <function returntype="complex float"> |
| <prototype> |
| <parameter content="complex float z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return the projection of the complex value <VAR>z</VAR> onto |
| the Riemann sphere. Values with a infinite imaginary part are projected |
| to positive infinity on the real axis, even if the real part is NaN. If |
| the real part is infinite, the result is equivalent to |
| <br><br> <pre><br> |
| INFINITY + I * copysign (0.0, cimag (z))<br> |
| </pre> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-cprojl" type="function"> |
| <function returntype="complex long double"> |
| <prototype> |
| <parameter content="complex long double z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return the projection of the complex value <VAR>z</VAR> onto |
| the Riemann sphere. Values with a infinite imaginary part are projected |
| to positive infinity on the real axis, even if the real part is NaN. If |
| the real part is infinite, the result is equivalent to |
| <br><br> <pre><br> |
| INFINITY + I * copysign (0.0, cimag (z))<br> |
| </pre> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-strtol" type="function"> |
| <function returntype="long int"> |
| <prototype> |
| <parameter content="const char *restrict string"/> |
| <parameter content="char **restrict tailptr"/> |
| <parameter content="int base"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>strtol</CODE> (``string-to-long'') function converts the initial |
| part of <VAR>string</VAR> to a signed integer, which is returned as a value |
| of type <CODE>long int</CODE>. |
| <br><br> This function attempts to decompose <VAR>string</VAR> as follows: |
| <br><br> <OL> |
| <LI> |
| A (possibly empty) sequence of whitespace characters. Which characters |
| are whitespace is determined by the <CODE>isspace</CODE> function |
| . These are discarded. |
| <br><br> <LI> |
| An optional plus or minus sign (<samp>+</samp> or <samp>-</samp>). |
| <br><br> <LI> |
| A nonempty sequence of digits in the radix specified by <VAR>base</VAR>. |
| <br><br> If <VAR>base</VAR> is zero, decimal radix is assumed unless the series of |
| digits begins with <samp>0</samp> (specifying octal radix), or <samp>0x</samp> or |
| <samp>0X</samp> (specifying hexadecimal radix); in other words, the same |
| syntax used for integer constants in C. |
| <br><br> Otherwise <VAR>base</VAR> must have a value between <CODE>2</CODE> and <CODE>36</CODE>. |
| If <VAR>base</VAR> is <CODE>16</CODE>, the digits may optionally be preceded by |
| <samp>0x</samp> or <samp>0X</samp>. If base has no legal value the value returned |
| is <CODE>0l</CODE> and the global variable <CODE>errno</CODE> is set to <CODE>EINVAL</CODE>. |
| <br><br> <LI> |
| Any remaining characters in the string. If <VAR>tailptr</VAR> is not a null |
| pointer, <CODE>strtol</CODE> stores a pointer to this tail in |
| <CODE>*<VAR>tailptr</VAR></CODE>. |
| </OL> |
| <br><br> If the string is empty, contains only whitespace, or does not contain an |
| initial substring that has the expected syntax for an integer in the |
| specified <VAR>base</VAR>, no conversion is performed. In this case, |
| <CODE>strtol</CODE> returns a value of zero and the value stored in |
| <CODE>*<VAR>tailptr</VAR></CODE> is the value of <VAR>string</VAR>. |
| <br><br> In a locale other than the standard <CODE>"C"</CODE> locale, this function |
| may recognize additional implementation-dependent syntax. |
| <br><br> If the string has valid syntax for an integer but the value is not |
| representable because of overflow, <CODE>strtol</CODE> returns either |
| <CODE>LONG_MAX</CODE> or <CODE>LONG_MIN</CODE> , as |
| appropriate for the sign of the value. It also sets <CODE>errno</CODE> |
| to <CODE>ERANGE</CODE> to indicate there was overflow. |
| <br><br> You should not check for errors by examining the return value of |
| <CODE>strtol</CODE>, because the string might be a valid representation of |
| <CODE>0l</CODE>, <CODE>LONG_MAX</CODE>, or <CODE>LONG_MIN</CODE>. Instead, check whether |
| <VAR>tailptr</VAR> points to what you expect after the number |
| (e.g. <CODE>'\0'</CODE> if the string should end after the number). You also |
| need to clear <VAR>errno</VAR> before the call and check it afterward, in |
| case there was overflow. |
| <br><br> There is an example at the end of this section. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-wcstol" type="function"> |
| <function returntype="long int"> |
| <prototype> |
| <parameter content="const wchar_t *restrict string"/> |
| <parameter content="wchar_t **restrict tailptr"/> |
| <parameter content="int base"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>wcstol</CODE> function is equivalent to the <CODE>strtol</CODE> function |
| in nearly all aspects but handles wide character strings. |
| <br><br> The <CODE>wcstol</CODE> function was introduced in Amendment 1 of ISO C90. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-strtoul" type="function"> |
| <function returntype="unsigned long int"> |
| <prototype> |
| <parameter content="const char *retrict string"/> |
| <parameter content="char **restrict tailptr"/> |
| <parameter content="int base"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>strtoul</CODE> (``string-to-unsigned-long'') function is like |
| <CODE>strtol</CODE> except it converts to an <CODE>unsigned long int</CODE> value. |
| The syntax is the same as described above for <CODE>strtol</CODE>. The value |
| returned on overflow is <CODE>ULONG_MAX</CODE> . |
| <br><br> If <VAR>string</VAR> depicts a negative number, <CODE>strtoul</CODE> acts the same |
| as <VAR>strtol</VAR> but casts the result to an unsigned integer. That means |
| for example that <CODE>strtoul</CODE> on <CODE>"-1"</CODE> returns <CODE>ULONG_MAX</CODE> |
| and an input more negative than <CODE>LONG_MIN</CODE> returns |
| (<CODE>ULONG_MAX</CODE> + 1) / 2. |
| <br><br> <CODE>strtoul</CODE> sets <VAR>errno</VAR> to <CODE>EINVAL</CODE> if <VAR>base</VAR> is out of |
| range, or <CODE>ERANGE</CODE> on overflow. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-wcstoul" type="function"> |
| <function returntype="unsigned long int"> |
| <prototype> |
| <parameter content="const wchar_t *restrict string"/> |
| <parameter content="wchar_t **restrict tailptr"/> |
| <parameter content="int base"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>wcstoul</CODE> function is equivalent to the <CODE>strtoul</CODE> function |
| in nearly all aspects but handles wide character strings. |
| <br><br> The <CODE>wcstoul</CODE> function was introduced in Amendment 1 of ISO C90. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-strtoll" type="function"> |
| <function returntype="long long int"> |
| <prototype> |
| <parameter content="const char *restrict string"/> |
| <parameter content="char **restrict tailptr"/> |
| <parameter content="int base"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>strtoll</CODE> function is like <CODE>strtol</CODE> except that it returns |
| a <CODE>long long int</CODE> value, and accepts numbers with a correspondingly |
| larger range. |
| <br><br> If the string has valid syntax for an integer but the value is not |
| representable because of overflow, <CODE>strtoll</CODE> returns either |
| <CODE>LONG_LONG_MAX</CODE> or <CODE>LONG_LONG_MIN</CODE> , as |
| appropriate for the sign of the value. It also sets <CODE>errno</CODE> to |
| <CODE>ERANGE</CODE> to indicate there was overflow. |
| <br><br> The <CODE>strtoll</CODE> function was introduced in ISO C99. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-wcstoll" type="function"> |
| <function returntype="long long int"> |
| <prototype> |
| <parameter content="const wchar_t *restrict string"/> |
| <parameter content="wchar_t **restrict tailptr"/> |
| <parameter content="int base"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>wcstoll</CODE> function is equivalent to the <CODE>strtoll</CODE> function |
| in nearly all aspects but handles wide character strings. |
| <br><br> The <CODE>wcstoll</CODE> function was introduced in Amendment 1 of ISO C90. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-strtoq" type="function"> |
| <function returntype="long long int"> |
| <prototype> |
| <parameter content="const char *restrict string"/> |
| <parameter content="char **restrict tailptr"/> |
| <parameter content="int base"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| <CODE>strtoq</CODE> (``string-to-quad-word'') is the BSD name for <CODE>strtoll</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-wcstoq" type="function"> |
| <function returntype="long long int"> |
| <prototype> |
| <parameter content="const wchar_t *restrict string"/> |
| <parameter content="wchar_t **restrict tailptr"/> |
| <parameter content="int base"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>wcstoq</CODE> function is equivalent to the <CODE>strtoq</CODE> function |
| in nearly all aspects but handles wide character strings. |
| <br><br> The <CODE>wcstoq</CODE> function is a GNU extension. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-strtoull" type="function"> |
| <function returntype="unsigned long long int"> |
| <prototype> |
| <parameter content="const char *restrict string"/> |
| <parameter content="char **restrict tailptr"/> |
| <parameter content="int base"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>strtoull</CODE> function is related to <CODE>strtoll</CODE> the same way |
| <CODE>strtoul</CODE> is related to <CODE>strtol</CODE>. |
| <br><br> The <CODE>strtoull</CODE> function was introduced in ISO C99. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-wcstoull" type="function"> |
| <function returntype="unsigned long long int"> |
| <prototype> |
| <parameter content="const wchar_t *restrict string"/> |
| <parameter content="wchar_t **restrict tailptr"/> |
| <parameter content="int base"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>wcstoull</CODE> function is equivalent to the <CODE>strtoull</CODE> function |
| in nearly all aspects but handles wide character strings. |
| <br><br> The <CODE>wcstoull</CODE> function was introduced in Amendment 1 of ISO C90. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-strtouq" type="function"> |
| <function returntype="unsigned long long int"> |
| <prototype> |
| <parameter content="const char *restrict string"/> |
| <parameter content="char **restrict tailptr"/> |
| <parameter content="int base"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| <CODE>strtouq</CODE> is the BSD name for <CODE>strtoull</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-wcstouq" type="function"> |
| <function returntype="unsigned long long int"> |
| <prototype> |
| <parameter content="const wchar_t *restrict string"/> |
| <parameter content="wchar_t **restrict tailptr"/> |
| <parameter content="int base"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>wcstouq</CODE> function is equivalent to the <CODE>strtouq</CODE> function |
| in nearly all aspects but handles wide character strings. |
| <br><br> The <CODE>wcstouq</CODE> function is a GNU extension. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-strtoimax" type="function"> |
| <function returntype="intmax_t"> |
| <prototype> |
| <parameter content="const char *restrict string"/> |
| <parameter content="char **restrict tailptr"/> |
| <parameter content="int base"/> |
| </prototype> |
| <headers> |
| <header filename = "inttypes.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>strtoimax</CODE> function is like <CODE>strtol</CODE> except that it returns |
| a <CODE>intmax_t</CODE> value, and accepts numbers of a corresponding range. |
| <br><br> If the string has valid syntax for an integer but the value is not |
| representable because of overflow, <CODE>strtoimax</CODE> returns either |
| <CODE>INTMAX_MAX</CODE> or <CODE>INTMAX_MIN</CODE> , as |
| appropriate for the sign of the value. It also sets <CODE>errno</CODE> to |
| <CODE>ERANGE</CODE> to indicate there was overflow. |
| <br><br> See Integers for a description of the <CODE>intmax_t</CODE> type. The |
| <CODE>strtoimax</CODE> function was introduced in ISO C99. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-wcstoimax" type="function"> |
| <function returntype="intmax_t"> |
| <prototype> |
| <parameter content="const wchar_t *restrict string"/> |
| <parameter content="wchar_t **restrict tailptr"/> |
| <parameter content="int base"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>wcstoimax</CODE> function is equivalent to the <CODE>strtoimax</CODE> function |
| in nearly all aspects but handles wide character strings. |
| <br><br> The <CODE>wcstoimax</CODE> function was introduced in ISO C99. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-strtoumax" type="function"> |
| <function returntype="uintmax_t"> |
| <prototype> |
| <parameter content="const char *restrict string"/> |
| <parameter content="char **restrict tailptr"/> |
| <parameter content="int base"/> |
| </prototype> |
| <headers> |
| <header filename = "inttypes.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>strtoumax</CODE> function is related to <CODE>strtoimax</CODE> |
| the same way that <CODE>strtoul</CODE> is related to <CODE>strtol</CODE>. |
| <br><br> See Integers for a description of the <CODE>intmax_t</CODE> type. The |
| <CODE>strtoumax</CODE> function was introduced in ISO C99. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-wcstoumax" type="function"> |
| <function returntype="uintmax_t"> |
| <prototype> |
| <parameter content="const wchar_t *restrict string"/> |
| <parameter content="wchar_t **restrict tailptr"/> |
| <parameter content="int base"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>wcstoumax</CODE> function is equivalent to the <CODE>strtoumax</CODE> function |
| in nearly all aspects but handles wide character strings. |
| <br><br> The <CODE>wcstoumax</CODE> function was introduced in ISO C99. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-atol" type="function"> |
| <function returntype="long int"> |
| <prototype> |
| <parameter content="const char *string"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to the <CODE>strtol</CODE> function with a <VAR>base</VAR> |
| argument of <CODE>10</CODE>, except that it need not detect overflow errors. |
| The <CODE>atol</CODE> function is provided mostly for compatibility with |
| existing code; using <CODE>strtol</CODE> is more robust. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-atoi" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *string"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| This function is like <CODE>atol</CODE>, except that it returns an <CODE>int</CODE>. |
| The <CODE>atoi</CODE> function is also considered obsolete; use <CODE>strtol</CODE> |
| instead. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-atoll" type="function"> |
| <function returntype="long long int"> |
| <prototype> |
| <parameter content="const char *string"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to <CODE>atol</CODE>, except it returns a <CODE>long |
| long int</CODE>. |
| <br><br> The <CODE>atoll</CODE> function was introduced in ISO C99. It too is |
| obsolete (despite having just been added); use <CODE>strtoll</CODE> instead. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-strtod" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="const char *restrict string"/> |
| <parameter content="char **restrict tailptr"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>strtod</CODE> (``string-to-double'') function converts the initial |
| part of <VAR>string</VAR> to a floating-point number, which is returned as a |
| value of type <CODE>double</CODE>. |
| <br><br> This function attempts to decompose <VAR>string</VAR> as follows: |
| <br><br> <OL> |
| <LI> |
| A (possibly empty) sequence of whitespace characters. Which characters |
| are whitespace is determined by the <CODE>isspace</CODE> function |
| . These are discarded. |
| <br><br> <LI> |
| An optional plus or minus sign (<samp>+</samp> or <samp>-</samp>). |
| <br><br> <LI> A floating point number in decimal or hexadecimal format. The |
| decimal format is: |
| <UL> |
| <br><br> <LI> |
| A nonempty sequence of digits optionally containing a decimal-point |
| character---normally <samp>.</samp>, but it depends on the locale |
| . |
| <br><br> <LI> |
| An optional exponent part, consisting of a character <samp>e</samp> or |
| <samp>E</samp>, an optional sign, and a sequence of digits. |
| <br><br> </UL> |
| <br><br> The hexadecimal format is as follows: |
| <UL> |
| <br><br> <LI> |
| A 0x or 0X followed by a nonempty sequence of hexadecimal digits |
| optionally containing a decimal-point character---normally <samp>.</samp>, but |
| it depends on the locale . |
| <br><br> <LI> |
| An optional binary-exponent part, consisting of a character <samp>p</samp> or |
| <samp>P</samp>, an optional sign, and a sequence of digits. |
| <br><br> </UL> |
| <br><br> <LI> |
| Any remaining characters in the string. If <VAR>tailptr</VAR> is not a null |
| pointer, a pointer to this tail of the string is stored in |
| <CODE>*<VAR>tailptr</VAR></CODE>. |
| </OL> |
| <br><br> If the string is empty, contains only whitespace, or does not contain an |
| initial substring that has the expected syntax for a floating-point |
| number, no conversion is performed. In this case, <CODE>strtod</CODE> returns |
| a value of zero and the value returned in <CODE>*<VAR>tailptr</VAR></CODE> is the |
| value of <VAR>string</VAR>. |
| <br><br> In a locale other than the standard <CODE>"C"</CODE> or <CODE>"POSIX"</CODE> locales, |
| this function may recognize additional locale-dependent syntax. |
| <br><br> If the string has valid syntax for a floating-point number but the value |
| is outside the range of a <CODE>double</CODE>, <CODE>strtod</CODE> will signal |
| overflow or underflow as described in Math Error Reporting. |
| <br><br> <CODE>strtod</CODE> recognizes four special input strings. The strings |
| <CODE>"inf"</CODE> and <CODE>"infinity"</CODE> are converted to infinity{}, |
| or to the largest representable value if the floating-point format |
| doesn't support infinities. You can prepend a <CODE>"+"</CODE> or <CODE>"-"</CODE> |
| to specify the sign. Case is ignored when scanning these strings. |
| <br><br> The strings <CODE>"nan"</CODE> and <CODE>"nan(<VAR>chars</VAR></CODE>)" are converted |
| to NaN. Again, case is ignored. If <VAR>chars</VAR> are provided, they |
| are used in some unspecified fashion to select a particular |
| representation of NaN (there can be several). |
| <br><br> Since zero is a valid result as well as the value returned on error, you |
| should check for errors in the same way as for <CODE>strtol</CODE>, by |
| examining <VAR>errno</VAR> and <VAR>tailptr</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-strtof" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="const char *string"/> |
| <parameter content="char **tailptr"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| These functions are analogous to <CODE>strtod</CODE>, but return <CODE>float</CODE> |
| and <CODE>long double</CODE> values respectively. They report errors in the |
| same way as <CODE>strtod</CODE>. <CODE>strtof</CODE> can be substantially faster |
| than <CODE>strtod</CODE>, but has less precision; conversely, <CODE>strtold</CODE> |
| can be much slower but has more precision (on systems where <CODE>long |
| double</CODE> is a separate type). |
| <br><br> These functions have been GNU extensions and are new to ISO C99. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-strtold" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="const char *string"/> |
| <parameter content="char **tailptr"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| These functions are analogous to <CODE>strtod</CODE>, but return <CODE>float</CODE> |
| and <CODE>long double</CODE> values respectively. They report errors in the |
| same way as <CODE>strtod</CODE>. <CODE>strtof</CODE> can be substantially faster |
| than <CODE>strtod</CODE>, but has less precision; conversely, <CODE>strtold</CODE> |
| can be much slower but has more precision (on systems where <CODE>long |
| double</CODE> is a separate type). |
| <br><br> These functions have been GNU extensions and are new to ISO C99. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-wcstod" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="const wchar_t *restrict string"/> |
| <parameter content="wchar_t **restrict tailptr"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>wcstod</CODE>, <CODE>wcstof</CODE>, and <CODE>wcstol</CODE> functions are |
| equivalent in nearly all aspect to the <CODE>strtod</CODE>, <CODE>strtof</CODE>, and |
| <CODE>strtold</CODE> functions but it handles wide character string. |
| <br><br> The <CODE>wcstod</CODE> function was introduced in Amendment 1 of ISO |
| C90. The <CODE>wcstof</CODE> and <CODE>wcstold</CODE> functions were introduced in |
| ISO C99. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-wcstof" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="const wchar_t *string"/> |
| <parameter content="wchar_t **tailptr"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>wcstod</CODE>, <CODE>wcstof</CODE>, and <CODE>wcstol</CODE> functions are |
| equivalent in nearly all aspect to the <CODE>strtod</CODE>, <CODE>strtof</CODE>, and |
| <CODE>strtold</CODE> functions but it handles wide character string. |
| <br><br> The <CODE>wcstod</CODE> function was introduced in Amendment 1 of ISO |
| C90. The <CODE>wcstof</CODE> and <CODE>wcstold</CODE> functions were introduced in |
| ISO C99. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-wcstold" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="const wchar_t *string"/> |
| <parameter content="wchar_t **tailptr"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>wcstod</CODE>, <CODE>wcstof</CODE>, and <CODE>wcstol</CODE> functions are |
| equivalent in nearly all aspect to the <CODE>strtod</CODE>, <CODE>strtof</CODE>, and |
| <CODE>strtold</CODE> functions but it handles wide character string. |
| <br><br> The <CODE>wcstod</CODE> function was introduced in Amendment 1 of ISO |
| C90. The <CODE>wcstof</CODE> and <CODE>wcstold</CODE> functions were introduced in |
| ISO C99. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-atof" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="const char *string"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to the <CODE>strtod</CODE> function, except that it |
| need not detect overflow and underflow errors. The <CODE>atof</CODE> function |
| is provided mostly for compatibility with existing code; using |
| <CODE>strtod</CODE> is more robust. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-ecvt" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="double value"/> |
| <parameter content="int ndigit"/> |
| <parameter content="int *decpt"/> |
| <parameter content="int *neg"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The function <CODE>ecvt</CODE> converts the floating-point number <VAR>value</VAR> |
| to a string with at most <VAR>ndigit</VAR> decimal digits. The |
| returned string contains no decimal point or sign. The first digit of |
| the string is non-zero (unless <VAR>value</VAR> is actually zero) and the |
| last digit is rounded to nearest. <CODE>*<VAR>decpt</VAR></CODE> is set to the |
| index in the string of the first digit after the decimal point. |
| <CODE>*<VAR>neg</VAR></CODE> is set to a nonzero value if <VAR>value</VAR> is negative, |
| zero otherwise. |
| <br><br> If <VAR>ndigit</VAR> decimal digits would exceed the precision of a |
| <CODE>double</CODE> it is reduced to a system-specific value. |
| <br><br> The returned string is statically allocated and overwritten by each call |
| to <CODE>ecvt</CODE>. |
| <br><br> If <VAR>value</VAR> is zero, it is implementation defined whether |
| <CODE>*<VAR>decpt</VAR></CODE> is <CODE>0</CODE> or <CODE>1</CODE>. |
| <br><br> For example: <CODE>ecvt (12.3, 5, &d, &n)</CODE> returns <CODE>"12300"</CODE> |
| and sets <VAR>d</VAR> to <CODE>2</CODE> and <VAR>n</VAR> to <CODE>0</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fcvt" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="double value"/> |
| <parameter content="int ndigit"/> |
| <parameter content="int *decpt"/> |
| <parameter content="int *neg"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The function <CODE>fcvt</CODE> is like <CODE>ecvt</CODE>, but <VAR>ndigit</VAR> specifies |
| the number of digits after the decimal point. If <VAR>ndigit</VAR> is less |
| than zero, <VAR>value</VAR> is rounded to the <VAR>ndigit</VAR>+1'th place to the |
| left of the decimal point. For example, if <VAR>ndigit</VAR> is <CODE>-1</CODE>, |
| <VAR>value</VAR> will be rounded to the nearest 10. If <VAR>ndigit</VAR> is |
| negative and larger than the number of digits to the left of the decimal |
| point in <VAR>value</VAR>, <VAR>value</VAR> will be rounded to one significant digit. |
| <br><br> If <VAR>ndigit</VAR> decimal digits would exceed the precision of a |
| <CODE>double</CODE> it is reduced to a system-specific value. |
| <br><br> The returned string is statically allocated and overwritten by each call |
| to <CODE>fcvt</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-gcvt" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="double value"/> |
| <parameter content="int ndigit"/> |
| <parameter content="char *buf"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| <CODE>gcvt</CODE> is functionally equivalent to <samp>sprintf(buf, "%*g", |
| ndigit, value</samp>. It is provided only for compatibility's sake. It |
| returns <VAR>buf</VAR>. |
| <br><br> If <VAR>ndigit</VAR> decimal digits would exceed the precision of a |
| <CODE>double</CODE> it is reduced to a system-specific value. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-qecvt" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="long double value"/> |
| <parameter content="int ndigit"/> |
| <parameter content="int *decpt"/> |
| <parameter content="int *neg"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| This function is equivalent to <CODE>ecvt</CODE> except that it takes a |
| <CODE>long double</CODE> for the first parameter and that <VAR>ndigit</VAR> is |
| restricted by the precision of a <CODE>long double</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-qfcvt" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="long double value"/> |
| <parameter content="int ndigit"/> |
| <parameter content="int *decpt"/> |
| <parameter content="int *neg"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| This function is equivalent to <CODE>fcvt</CODE> except that it |
| takes a <CODE>long double</CODE> for the first parameter and that <VAR>ndigit</VAR> is |
| restricted by the precision of a <CODE>long double</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-qgcvt" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="long double value"/> |
| <parameter content="int ndigit"/> |
| <parameter content="char *buf"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| This function is equivalent to <CODE>gcvt</CODE> except that it takes a |
| <CODE>long double</CODE> for the first parameter and that <VAR>ndigit</VAR> is |
| restricted by the precision of a <CODE>long double</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-ecvt_r" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="double value"/> |
| <parameter content="int ndigit"/> |
| <parameter content="int *decpt"/> |
| <parameter content="int *neg"/> |
| <parameter content="char *buf"/> |
| <parameter content="size_t len"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>ecvt_r</CODE> function is the same as <CODE>ecvt</CODE>, except |
| that it places its result into the user-specified buffer pointed to by |
| <VAR>buf</VAR>, with length <VAR>len</VAR>. The return value is <CODE>-1</CODE> in |
| case of an error and zero otherwise. |
| <br><br> This function is a GNU extension. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fcvt_r" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="double value"/> |
| <parameter content="int ndigit"/> |
| <parameter content="int *decpt"/> |
| <parameter content="int *neg"/> |
| <parameter content="char *buf"/> |
| <parameter content="size_t len"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>fcvt_r</CODE> function is the same as <CODE>fcvt</CODE>, except that it |
| places its result into the user-specified buffer pointed to by |
| <VAR>buf</VAR>, with length <VAR>len</VAR>. The return value is <CODE>-1</CODE> in |
| case of an error and zero otherwise. |
| <br><br> This function is a GNU extension. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-qecvt_r" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="long double value"/> |
| <parameter content="int ndigit"/> |
| <parameter content="int *decpt"/> |
| <parameter content="int *neg"/> |
| <parameter content="char *buf"/> |
| <parameter content="size_t len"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>qecvt_r</CODE> function is the same as <CODE>qecvt</CODE>, except |
| that it places its result into the user-specified buffer pointed to by |
| <VAR>buf</VAR>, with length <VAR>len</VAR>. The return value is <CODE>-1</CODE> in |
| case of an error and zero otherwise. |
| <br><br> This function is a GNU extension. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-qfcvt_r" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="long double value"/> |
| <parameter content="int ndigit"/> |
| <parameter content="int *decpt"/> |
| <parameter content="int *neg"/> |
| <parameter content="char *buf"/> |
| <parameter content="size_t len"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>qfcvt_r</CODE> function is the same as <CODE>qfcvt</CODE>, except |
| that it places its result into the user-specified buffer pointed to by |
| <VAR>buf</VAR>, with length <VAR>len</VAR>. The return value is <CODE>-1</CODE> in |
| case of an error and zero otherwise. |
| <br><br> This function is a GNU extension. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="dtype-wchar_t" type="dtype"> |
| <structure> |
| </structure> |
| </construct> |
| <construct id="dtype-wint_t" type="dtype"> |
| <structure> |
| </structure> |
| </construct> |
| <construct id="dtype-mbstate_t" type="dtype"> |
| <structure> |
| </structure> |
| </construct> |
| <construct id="function-mbsinit" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const mbstate_t *ps"/> |
| </prototype> |
| <headers> |
| <header filename = "stddef.h"/> |
| <header filename = "wchar.h"/> |
| <header filename = "limits.h"/> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>mbsinit</CODE> function determines whether the state object pointed |
| to by <VAR>ps</VAR> is in the initial state. If <VAR>ps</VAR> is a null pointer or |
| the object is in the initial state the return value is nonzero. Otherwise |
| it is zero. |
| <br><br> <CODE>mbsinit</CODE> was introduced in Amendment 1 to ISO C90 and is |
| declared in <TT>wchar.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-btowc" type="function"> |
| <function returntype="wint_t"> |
| <prototype> |
| <parameter content="int c"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>btowc</CODE> function (``byte to wide character'') converts a valid |
| single byte character <VAR>c</VAR> in the initial shift state into the wide |
| character equivalent using the conversion rules from the currently |
| selected locale of the <CODE>LC_CTYPE</CODE> category. |
| <br><br> If <CODE>(unsigned char) <VAR>c</VAR></CODE> is no valid single byte multibyte |
| character or if <VAR>c</VAR> is <CODE>EOF</CODE>, the function returns <CODE>WEOF</CODE>. |
| <br><br> Please note the restriction of <VAR>c</VAR> being tested for validity only in |
| the initial shift state. No <CODE>mbstate_t</CODE> object is used from |
| which the state information is taken, and the function also does not use |
| any static state. |
| <br><br> The <CODE>btowc</CODE> function was introduced in Amendment 1 to ISO C90 |
| and is declared in <TT>wchar.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-wctob" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="wint_t c"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>wctob</CODE> function (``wide character to byte'') takes as the |
| parameter a valid wide character. If the multibyte representation for |
| this character in the initial state is exactly one byte long, the return |
| value of this function is this character. Otherwise the return value is |
| <CODE>EOF</CODE>. |
| <br><br> <CODE>wctob</CODE> was introduced in Amendment 1 to ISO C90 and |
| is declared in <TT>wchar.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-mbrtowc" type="function"> |
| <function returntype="size_t"> |
| <prototype> |
| <parameter content="wchar_t *restrict pwc"/> |
| <parameter content="const char *restrict s"/> |
| <parameter content="size_t n"/> |
| <parameter content="mbstate_t *restrict ps"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| |
| The <CODE>mbrtowc</CODE> function (``multibyte restartable to wide |
| character'') converts the next multibyte character in the string pointed |
| to by <VAR>s</VAR> into a wide character and stores it in the wide character |
| string pointed to by <VAR>pwc</VAR>. The conversion is performed according |
| to the locale currently selected for the <CODE>LC_CTYPE</CODE> category. If |
| the conversion for the character set used in the locale requires a state, |
| the multibyte string is interpreted in the state represented by the |
| object pointed to by <VAR>ps</VAR>. If <VAR>ps</VAR> is a null pointer, a static, |
| internal state variable used only by the <CODE>mbrtowc</CODE> function is |
| used. |
| <br><br> If the next multibyte character corresponds to the NUL wide character, |
| the return value of the function is 0 and the state object is |
| afterwards in the initial state. If the next <VAR>n</VAR> or fewer bytes |
| form a correct multibyte character, the return value is the number of |
| bytes starting from <VAR>s</VAR> that form the multibyte character. The |
| conversion state is updated according to the bytes consumed in the |
| conversion. In both cases the wide character (either the <CODE>L'\0'</CODE> |
| or the one found in the conversion) is stored in the string pointed to |
| by <VAR>pwc</VAR> if <VAR>pwc</VAR> is not null. |
| <br><br> If the first <VAR>n</VAR> bytes of the multibyte string possibly form a valid |
| multibyte character but there are more than <VAR>n</VAR> bytes needed to |
| complete it, the return value of the function is <CODE>(size_t) -2</CODE> and |
| no value is stored. Please note that this can happen even if <VAR>n</VAR> |
| has a value greater than or equal to <CODE>MB_CUR_MAX</CODE> since the input |
| might contain redundant shift sequences. |
| <br><br> If the first <CODE>n</CODE> bytes of the multibyte string cannot possibly form |
| a valid multibyte character, no value is stored, the global variable |
| <CODE>errno</CODE> is set to the value <CODE>EILSEQ</CODE>, and the function returns |
| <CODE>(size_t) -1</CODE>. The conversion state is afterwards undefined. |
| <br><br> <CODE>mbrtowc</CODE> was introduced in Amendment 1 to ISO C90 and |
| is declared in <TT>wchar.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-mbrlen" type="function"> |
| <function returntype="size_t"> |
| <prototype> |
| <parameter content="const char *restrict s"/> |
| <parameter content="size_t n"/> |
| <parameter content="mbstate_t *ps"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>mbrlen</CODE> function (``multibyte restartable length'') computes |
| the number of at most <VAR>n</VAR> bytes starting at <VAR>s</VAR>, which form the |
| next valid and complete multibyte character. |
| <br><br> If the next multibyte character corresponds to the NUL wide character, |
| the return value is 0. If the next <VAR>n</VAR> bytes form a valid |
| multibyte character, the number of bytes belonging to this multibyte |
| character byte sequence is returned. |
| <br><br> If the first <VAR>n</VAR> bytes possibly form a valid multibyte |
| character but the character is incomplete, the return value is |
| <CODE>(size_t) -2</CODE>. Otherwise the multibyte character sequence is invalid |
| and the return value is <CODE>(size_t) -1</CODE>. |
| <br><br> The multibyte sequence is interpreted in the state represented by the |
| object pointed to by <VAR>ps</VAR>. If <VAR>ps</VAR> is a null pointer, a state |
| object local to <CODE>mbrlen</CODE> is used. |
| <br><br> <CODE>mbrlen</CODE> was introduced in Amendment 1 to ISO C90 and |
| is declared in <TT>wchar.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-wcrtomb" type="function"> |
| <function returntype="size_t"> |
| <prototype> |
| <parameter content="char *restrict s"/> |
| <parameter content="wchar_t wc"/> |
| <parameter content="mbstate_t *restrict ps"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>wcrtomb</CODE> function (``wide character restartable to |
| multibyte'') converts a single wide character into a multibyte string |
| corresponding to that wide character. |
| <br><br> If <VAR>s</VAR> is a null pointer, the function resets the state stored in |
| the objects pointed to by <VAR>ps</VAR> (or the internal <CODE>mbstate_t</CODE> |
| object) to the initial state. This can also be achieved by a call like |
| this: |
| <br><br> <pre><br> |
| wcrtombs (temp_buf, L'\0', ps)<br> |
| </pre> |
| <br><br> |
| since, if <VAR>s</VAR> is a null pointer, <CODE>wcrtomb</CODE> performs as if it |
| writes into an internal buffer, which is guaranteed to be large enough. |
| <br><br> If <VAR>wc</VAR> is the NUL wide character, <CODE>wcrtomb</CODE> emits, if |
| necessary, a shift sequence to get the state <VAR>ps</VAR> into the initial |
| state followed by a single NUL byte, which is stored in the string |
| <VAR>s</VAR>. |
| <br><br> Otherwise a byte sequence (possibly including shift sequences) is written |
| into the string <VAR>s</VAR>. This only happens if <VAR>wc</VAR> is a valid wide |
| character (i.e., it has a multibyte representation in the character set |
| selected by locale of the <CODE>LC_CTYPE</CODE> category). If <VAR>wc</VAR> is no |
| valid wide character, nothing is stored in the strings <VAR>s</VAR>, |
| <CODE>errno</CODE> is set to <CODE>EILSEQ</CODE>, the conversion state in <VAR>ps</VAR> |
| is undefined and the return value is <CODE>(size_t) -1</CODE>. |
| <br><br> If no error occurred the function returns the number of bytes stored in |
| the string <VAR>s</VAR>. This includes all bytes representing shift |
| sequences. |
| <br><br> One word about the interface of the function: there is no parameter |
| specifying the length of the array <VAR>s</VAR>. Instead the function |
| assumes that there are at least <CODE>MB_CUR_MAX</CODE> bytes available since |
| this is the maximum length of any byte sequence representing a single |
| character. So the caller has to make sure that there is enough space |
| available, otherwise buffer overruns can occur. |
| <br><br> <CODE>wcrtomb</CODE> was introduced in Amendment 1 to ISO C90 and is |
| declared in <TT>wchar.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-mbsrtowcs" type="function"> |
| <function returntype="size_t"> |
| <prototype> |
| <parameter content="wchar_t *restrict dst"/> |
| <parameter content="const char **restrict src"/> |
| <parameter content="size_t len"/> |
| <parameter content="mbstate_t *restrict ps"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>mbsrtowcs</CODE> function (``multibyte string restartable to wide |
| character string'') converts an NUL-terminated multibyte character |
| string at <CODE>*<VAR>src</VAR></CODE> into an equivalent wide character string, |
| including the NUL wide character at the end. The conversion is started |
| using the state information from the object pointed to by <VAR>ps</VAR> or |
| from an internal object of <CODE>mbsrtowcs</CODE> if <VAR>ps</VAR> is a null |
| pointer. Before returning, the state object is updated to match the state |
| after the last converted character. The state is the initial state if the |
| terminating NUL byte is reached and converted. |
| <br><br> If <VAR>dst</VAR> is not a null pointer, the result is stored in the array |
| pointed to by <VAR>dst</VAR>; otherwise, the conversion result is not |
| available since it is stored in an internal buffer. |
| <br><br> If <VAR>len</VAR> wide characters are stored in the array <VAR>dst</VAR> before |
| reaching the end of the input string, the conversion stops and <VAR>len</VAR> |
| is returned. If <VAR>dst</VAR> is a null pointer, <VAR>len</VAR> is never checked. |
| <br><br> Another reason for a premature return from the function call is if the |
| input string contains an invalid multibyte sequence. In this case the |
| global variable <CODE>errno</CODE> is set to <CODE>EILSEQ</CODE> and the function |
| returns <CODE>(size_t) -1</CODE>. |
| <br><br> <br><br> In all other cases the function returns the number of wide characters |
| converted during this call. If <VAR>dst</VAR> is not null, <CODE>mbsrtowcs</CODE> |
| stores in the pointer pointed to by <VAR>src</VAR> either a null pointer (if |
| the NUL byte in the input string was reached) or the address of the byte |
| following the last converted multibyte character. |
| <br><br> <CODE>mbsrtowcs</CODE> was introduced in Amendment 1 to ISO C90 and is |
| declared in <TT>wchar.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-wcsrtombs" type="function"> |
| <function returntype="size_t"> |
| <prototype> |
| <parameter content="char *restrict dst"/> |
| <parameter content="const wchar_t **restrict src"/> |
| <parameter content="size_t len"/> |
| <parameter content="mbstate_t *restrict ps"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>wcsrtombs</CODE> function (``wide character string restartable to |
| multibyte string'') converts the NUL-terminated wide character string at |
| <CODE>*<VAR>src</VAR></CODE> into an equivalent multibyte character string and |
| stores the result in the array pointed to by <VAR>dst</VAR>. The NUL wide |
| character is also converted. The conversion starts in the state |
| described in the object pointed to by <VAR>ps</VAR> or by a state object |
| locally to <CODE>wcsrtombs</CODE> in case <VAR>ps</VAR> is a null pointer. If |
| <VAR>dst</VAR> is a null pointer, the conversion is performed as usual but the |
| result is not available. If all characters of the input string were |
| successfully converted and if <VAR>dst</VAR> is not a null pointer, the |
| pointer pointed to by <VAR>src</VAR> gets assigned a null pointer. |
| <br><br> If one of the wide characters in the input string has no valid multibyte |
| character equivalent, the conversion stops early, sets the global |
| variable <CODE>errno</CODE> to <CODE>EILSEQ</CODE>, and returns <CODE>(size_t) -1</CODE>. |
| <br><br> Another reason for a premature stop is if <VAR>dst</VAR> is not a null |
| pointer and the next converted character would require more than |
| <VAR>len</VAR> bytes in total to the array <VAR>dst</VAR>. In this case (and if |
| <VAR>dest</VAR> is not a null pointer) the pointer pointed to by <VAR>src</VAR> is |
| assigned a value pointing to the wide character right after the last one |
| successfully converted. |
| <br><br> Except in the case of an encoding error the return value of the |
| <CODE>wcsrtombs</CODE> function is the number of bytes in all the multibyte |
| character sequences stored in <VAR>dst</VAR>. Before returning the state in |
| the object pointed to by <VAR>ps</VAR> (or the internal object in case |
| <VAR>ps</VAR> is a null pointer) is updated to reflect the state after the |
| last conversion. The state is the initial shift state in case the |
| terminating NUL wide character was converted. |
| <br><br> The <CODE>wcsrtombs</CODE> function was introduced in Amendment 1 to |
| ISO C90 and is declared in <TT>wchar.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-mbsnrtowcs" type="function"> |
| <function returntype="size_t"> |
| <prototype> |
| <parameter content="wchar_t *restrict dst"/> |
| <parameter content="const char **restrict src"/> |
| <parameter content="size_t nmc"/> |
| <parameter content="size_t len"/> |
| <parameter content="mbstate_t *restrict ps"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>mbsnrtowcs</CODE> function is very similar to the <CODE>mbsrtowcs</CODE> |
| function. All the parameters are the same except for <VAR>nmc</VAR>, which is |
| new. The return value is the same as for <CODE>mbsrtowcs</CODE>. |
| <br><br> This new parameter specifies how many bytes at most can be used from the |
| multibyte character string. In other words, the multibyte character |
| string <CODE>*<VAR>src</VAR></CODE> need not be NUL-terminated. But if a NUL byte |
| is found within the <VAR>nmc</VAR> first bytes of the string, the conversion |
| stops here. |
| <br><br> This function is a GNU extension. It is meant to work around the |
| problems mentioned above. Now it is possible to convert a buffer with |
| multibyte character text piece for piece without having to care about |
| inserting NUL bytes and the effect of NUL bytes on the conversion state. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-wcsnrtombs" type="function"> |
| <function returntype="size_t"> |
| <prototype> |
| <parameter content="char *restrict dst"/> |
| <parameter content="const wchar_t **restrict src"/> |
| <parameter content="size_t nwc"/> |
| <parameter content="size_t len"/> |
| <parameter content="mbstate_t *restrict ps"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>wcsnrtombs</CODE> function implements the conversion from wide |
| character strings to multibyte character strings. It is similar to |
| <CODE>wcsrtombs</CODE> but, just like <CODE>mbsnrtowcs</CODE>, it takes an extra |
| parameter, which specifies the length of the input string. |
| <br><br> No more than <VAR>nwc</VAR> wide characters from the input string |
| <CODE>*<VAR>src</VAR></CODE> are converted. If the input string contains a NUL |
| wide character in the first <VAR>nwc</VAR> characters, the conversion stops at |
| this place. |
| <br><br> The <CODE>wcsnrtombs</CODE> function is a GNU extension and just like |
| <CODE>mbsnrtowcs</CODE> helps in situations where no NUL-terminated input |
| strings are available. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-mbtowc" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="wchar_t *restrict result"/> |
| <parameter content="const char *restrict string"/> |
| <parameter content="size_t size"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>mbtowc</CODE> (``multibyte to wide character'') function when called |
| with non-null <VAR>string</VAR> converts the first multibyte character |
| beginning at <VAR>string</VAR> to its corresponding wide character code. It |
| stores the result in <CODE>*<VAR>result</VAR></CODE>. |
| <br><br> <CODE>mbtowc</CODE> never examines more than <VAR>size</VAR> bytes. (The idea is |
| to supply for <VAR>size</VAR> the number of bytes of data you have in hand.) |
| <br><br> <CODE>mbtowc</CODE> with non-null <VAR>string</VAR> distinguishes three |
| possibilities: the first <VAR>size</VAR> bytes at <VAR>string</VAR> start with |
| valid multibyte characters, they start with an invalid byte sequence or |
| just part of a character, or <VAR>string</VAR> points to an empty string (a |
| null character). |
| <br><br> For a valid multibyte character, <CODE>mbtowc</CODE> converts it to a wide |
| character and stores that in <CODE>*<VAR>result</VAR></CODE>, and returns the |
| number of bytes in that character (always at least 1 and never |
| more than <VAR>size</VAR>). |
| <br><br> For an invalid byte sequence, <CODE>mbtowc</CODE> returns -1. For an |
| empty string, it returns 0, also storing <CODE>'\0'</CODE> in |
| <CODE>*<VAR>result</VAR></CODE>. |
| <br><br> If the multibyte character code uses shift characters, then |
| <CODE>mbtowc</CODE> maintains and updates a shift state as it scans. If you |
| call <CODE>mbtowc</CODE> with a null pointer for <VAR>string</VAR>, that |
| initializes the shift state to its standard initial value. It also |
| returns nonzero if the multibyte character code in use actually has a |
| shift state. . |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-wctomb" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="char *string"/> |
| <parameter content="wchar_t wchar"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>wctomb</CODE> (``wide character to multibyte'') function converts |
| the wide character code <VAR>wchar</VAR> to its corresponding multibyte |
| character sequence, and stores the result in bytes starting at |
| <VAR>string</VAR>. At most <CODE>MB_CUR_MAX</CODE> characters are stored. |
| <br><br> <CODE>wctomb</CODE> with non-null <VAR>string</VAR> distinguishes three |
| possibilities for <VAR>wchar</VAR>: a valid wide character code (one that can |
| be translated to a multibyte character), an invalid code, and |
| <CODE>L'\0'</CODE>. |
| <br><br> Given a valid code, <CODE>wctomb</CODE> converts it to a multibyte character, |
| storing the bytes starting at <VAR>string</VAR>. Then it returns the number |
| of bytes in that character (always at least 1 and never more |
| than <CODE>MB_CUR_MAX</CODE>). |
| <br><br> If <VAR>wchar</VAR> is an invalid wide character code, <CODE>wctomb</CODE> returns |
| -1. If <VAR>wchar</VAR> is <CODE>L'\0'</CODE>, it returns <CODE>0</CODE>, also |
| storing <CODE>'\0'</CODE> in <CODE>*<VAR>string</VAR></CODE>. |
| <br><br> If the multibyte character code uses shift characters, then |
| <CODE>wctomb</CODE> maintains and updates a shift state as it scans. If you |
| call <CODE>wctomb</CODE> with a null pointer for <VAR>string</VAR>, that |
| initializes the shift state to its standard initial value. It also |
| returns nonzero if the multibyte character code in use actually has a |
| shift state. . |
| <br><br> Calling this function with a <VAR>wchar</VAR> argument of zero when |
| <VAR>string</VAR> is not null has the side-effect of reinitializing the |
| stored shift state <EM>as well as</EM> storing the multibyte character |
| <CODE>'\0'</CODE> and returning 0. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-mblen" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *string"/> |
| <parameter content="size_t size"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>mblen</CODE> function with a non-null <VAR>string</VAR> argument returns |
| the number of bytes that make up the multibyte character beginning at |
| <VAR>string</VAR>, never examining more than <VAR>size</VAR> bytes. (The idea is |
| to supply for <VAR>size</VAR> the number of bytes of data you have in hand.) |
| <br><br> The return value of <CODE>mblen</CODE> distinguishes three possibilities: the |
| first <VAR>size</VAR> bytes at <VAR>string</VAR> start with valid multibyte |
| characters, they start with an invalid byte sequence or just part of a |
| character, or <VAR>string</VAR> points to an empty string (a null character). |
| <br><br> For a valid multibyte character, <CODE>mblen</CODE> returns the number of |
| bytes in that character (always at least <CODE>1</CODE> and never more than |
| <VAR>size</VAR>). For an invalid byte sequence, <CODE>mblen</CODE> returns |
| -1. For an empty string, it returns 0. |
| <br><br> If the multibyte character code uses shift characters, then <CODE>mblen</CODE> |
| maintains and updates a shift state as it scans. If you call |
| <CODE>mblen</CODE> with a null pointer for <VAR>string</VAR>, that initializes the |
| shift state to its standard initial value. It also returns a nonzero |
| value if the multibyte character code in use actually has a shift state. |
| . |
| <br><br> The function <CODE>mblen</CODE> is declared in <TT>stdlib.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-mbstowcs" type="function"> |
| <function returntype="size_t"> |
| <prototype> |
| <parameter content="wchar_t *wstring"/> |
| <parameter content="const char *string"/> |
| <parameter content="size_t size"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>mbstowcs</CODE> (``multibyte string to wide character string'') |
| function converts the null-terminated string of multibyte characters |
| <VAR>string</VAR> to an array of wide character codes, storing not more than |
| <VAR>size</VAR> wide characters into the array beginning at <VAR>wstring</VAR>. |
| The terminating null character counts towards the size, so if <VAR>size</VAR> |
| is less than the actual number of wide characters resulting from |
| <VAR>string</VAR>, no terminating null character is stored. |
| <br><br> The conversion of characters from <VAR>string</VAR> begins in the initial |
| shift state. |
| <br><br> If an invalid multibyte character sequence is found, the <CODE>mbstowcs</CODE> |
| function returns a value of -1. Otherwise, it returns the number |
| of wide characters stored in the array <VAR>wstring</VAR>. This number does |
| not include the terminating null character, which is present if the |
| number is less than <VAR>size</VAR>. |
| <br><br> Here is an example showing how to convert a string of multibyte |
| characters, allocating enough space for the result. |
| <br><br> <pre><br> |
| wchar_t *<br> |
| mbstowcs_alloc (const char *string)<br> |
| {<br> |
| size_t size = strlen (string) + 1;<br> |
| wchar_t *buf = xmalloc (size * sizeof (wchar_t));<br> |
| <br><br> size = mbstowcs (buf, string, size);<br> |
| if (size == (size_t) -1)<br> |
| return NULL;<br> |
| buf = xrealloc (buf, (size + 1) * sizeof (wchar_t));<br> |
| return buf;<br> |
| }<br> |
| </pre> |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-wcstombs" type="function"> |
| <function returntype="size_t"> |
| <prototype> |
| <parameter content="char *string"/> |
| <parameter content="const wchar_t *wstring"/> |
| <parameter content="size_t size"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>wcstombs</CODE> (``wide character string to multibyte string'') |
| function converts the null-terminated wide character array <VAR>wstring</VAR> |
| into a string containing multibyte characters, storing not more than |
| <VAR>size</VAR> bytes starting at <VAR>string</VAR>, followed by a terminating |
| null character if there is room. The conversion of characters begins in |
| the initial shift state. |
| <br><br> The terminating null character counts towards the size, so if <VAR>size</VAR> |
| is less than or equal to the number of bytes needed in <VAR>wstring</VAR>, no |
| terminating null character is stored. |
| <br><br> If a code that does not correspond to a valid multibyte character is |
| found, the <CODE>wcstombs</CODE> function returns a value of -1. |
| Otherwise, the return value is the number of bytes stored in the array |
| <VAR>string</VAR>. This number does not include the terminating null character, |
| which is present if the number is less than <VAR>size</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="dtype-iconv_t" type="dtype"> |
| <structure> |
| </structure> |
| </construct> |
| <construct id="function-iconv_open" type="function"> |
| <function returntype="iconv_t"> |
| <prototype> |
| <parameter content="const char *tocode"/> |
| <parameter content="const char *fromcode"/> |
| </prototype> |
| <headers> |
| <header filename = "iconv.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>iconv_open</CODE> function has to be used before starting a |
| conversion. The two parameters this function takes determine the |
| source and destination character set for the conversion, and if the |
| implementation has the possibility to perform such a conversion, the |
| function returns a handle. |
| <br><br> If the wanted conversion is not available, the <CODE>iconv_open</CODE> function |
| returns <CODE>(iconv_t) -1</CODE>. In this case the global variable |
| <CODE>errno</CODE> can have the following values: |
| <br><br> <DL> |
| |
| <DT><CODE>EMFILE</CODE> |
| <DD> |
| The process already has <CODE>OPEN_MAX</CODE> file descriptors open. |
| <LI> ENFILE |
| The system limit of open file is reached. |
| <LI> ENOMEM |
| Not enough memory to carry out the operation. |
| <LI> EINVAL |
| The conversion from <VAR>fromcode</VAR> to <VAR>tocode</VAR> is not supported. |
| |
| <br><br> It is not possible to use the same descriptor in different threads to |
| perform independent conversions. The data structures associated |
| with the descriptor include information about the conversion state. |
| This must not be messed up by using it in different conversions. |
| <br><br> An <CODE>iconv</CODE> descriptor is like a file descriptor as for every use a |
| new descriptor must be created. The descriptor does not stand for all |
| of the conversions from <VAR>fromset</VAR> to <VAR>toset</VAR>. |
| <br><br> The GNU C library implementation of <CODE>iconv_open</CODE> has one |
| significant extension to other implementations. To ease the extension |
| of the set of available conversions, the implementation allows storing |
| the necessary files with data and code in an arbitrary number of |
| directories. How this extension must be written will be explained below |
| . Here it is only important to say |
| that all directories mentioned in the <CODE>GCONV_PATH</CODE> environment |
| variable are considered only if they contain a file <TT>gconv-modules</TT>. |
| These directories need not necessarily be created by the system |
| administrator. In fact, this extension is introduced to help users |
| writing and using their own, new conversions. Of course, this does not |
| work for security reasons in SUID binaries; in this case only the system |
| directory is considered and this normally is |
| <TT><VAR>prefix</VAR>/lib/gconv</TT>. The <CODE>GCONV_PATH</CODE> environment |
| variable is examined exactly once at the first call of the |
| <CODE>iconv_open</CODE> function. Later modifications of the variable have no |
| effect. |
| <br><br> The <CODE>iconv_open</CODE> function was introduced early in the X/Open |
| Portability Guide, version 2. It is supported by all commercial |
| Unices as it is required for the Unix branding. However, the quality and |
| completeness of the implementation varies widely. The <CODE>iconv_open</CODE> |
| function is declared in <TT>iconv.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-iconv_close" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="iconv_t cd"/> |
| </prototype> |
| <headers> |
| <header filename = "iconv.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>iconv_close</CODE> function frees all resources associated with the |
| handle <VAR>cd</VAR>, which must have been returned by a successful call to |
| the <CODE>iconv_open</CODE> function. |
| <br><br> If the function call was successful the return value is 0. |
| Otherwise it is -1 and <CODE>errno</CODE> is set appropriately. |
| Defined error are: |
| <br><br> <DL> |
| |
| <DT><CODE>EBADF</CODE> |
| <DD> |
| The conversion descriptor is invalid. |
| |
| <br><br> The <CODE>iconv_close</CODE> function was introduced together with the rest |
| of the <CODE>iconv</CODE> functions in XPG2 and is declared in <TT>iconv.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-iconv" type="function"> |
| <function returntype="size_t"> |
| <prototype> |
| <parameter content="iconv_t cd"/> |
| <parameter content="char **inbuf"/> |
| <parameter content="size_t *inbytesleft"/> |
| <parameter content="char **outbuf"/> |
| <parameter content="size_t *outbytesleft"/> |
| </prototype> |
| <headers> |
| <header filename = "iconv.h"/> |
| </headers> |
| <synopsis> |
| |
| The <CODE>iconv</CODE> function converts the text in the input buffer |
| according to the rules associated with the descriptor <VAR>cd</VAR> and |
| stores the result in the output buffer. It is possible to call the |
| function for the same text several times in a row since for stateful |
| character sets the necessary state information is kept in the data |
| structures associated with the descriptor. |
| <br><br> The input buffer is specified by <CODE>*<VAR>inbuf</VAR></CODE> and it contains |
| <CODE>*<VAR>inbytesleft</VAR></CODE> bytes. The extra indirection is necessary for |
| communicating the used input back to the caller (see below). It is |
| important to note that the buffer pointer is of type <CODE>char</CODE> and the |
| length is measured in bytes even if the input text is encoded in wide |
| characters. |
| <br><br> The output buffer is specified in a similar way. <CODE>*<VAR>outbuf</VAR></CODE> |
| points to the beginning of the buffer with at least |
| <CODE>*<VAR>outbytesleft</VAR></CODE> bytes room for the result. The buffer |
| pointer again is of type <CODE>char</CODE> and the length is measured in |
| bytes. If <VAR>outbuf</VAR> or <CODE>*<VAR>outbuf</VAR></CODE> is a null pointer, the |
| conversion is performed but no output is available. |
| <br><br> If <VAR>inbuf</VAR> is a null pointer, the <CODE>iconv</CODE> function performs the |
| necessary action to put the state of the conversion into the initial |
| state. This is obviously a no-op for non-stateful encodings, but if the |
| encoding has a state, such a function call might put some byte sequences |
| in the output buffer, which perform the necessary state changes. The |
| next call with <VAR>inbuf</VAR> not being a null pointer then simply goes on |
| from the initial state. It is important that the programmer never makes |
| any assumption as to whether the conversion has to deal with states. |
| Even if the input and output character sets are not stateful, the |
| implementation might still have to keep states. This is due to the |
| implementation chosen for the GNU C library as it is described below. |
| Therefore an <CODE>iconv</CODE> call to reset the state should always be |
| performed if some protocol requires this for the output text. |
| <br><br> The conversion stops for one of three reasons. The first is that all |
| characters from the input buffer are converted. This actually can mean |
| two things: either all bytes from the input buffer are consumed or |
| there are some bytes at the end of the buffer that possibly can form a |
| complete character but the input is incomplete. The second reason for a |
| stop is that the output buffer is full. And the third reason is that |
| the input contains invalid characters. |
| <br><br> In all of these cases the buffer pointers after the last successful |
| conversion, for input and output buffer, are stored in <VAR>inbuf</VAR> and |
| <VAR>outbuf</VAR>, and the available room in each buffer is stored in |
| <VAR>inbytesleft</VAR> and <VAR>outbytesleft</VAR>. |
| <br><br> Since the character sets selected in the <CODE>iconv_open</CODE> call can be |
| almost arbitrary, there can be situations where the input buffer contains |
| valid characters, which have no identical representation in the output |
| character set. The behavior in this situation is undefined. The |
| <EM>current</EM> behavior of the GNU C library in this situation is to |
| return with an error immediately. This certainly is not the most |
| desirable solution; therefore, future versions will provide better ones, |
| but they are not yet finished. |
| <br><br> If all input from the input buffer is successfully converted and stored |
| in the output buffer, the function returns the number of non-reversible |
| conversions performed. In all other cases the return value is |
| <CODE>(size_t) -1</CODE> and <CODE>errno</CODE> is set appropriately. In such cases |
| the value pointed to by <VAR>inbytesleft</VAR> is nonzero. |
| <br><br> <DL> |
| |
| <DT><CODE>EILSEQ</CODE> |
| <DD> |
| The conversion stopped because of an invalid byte sequence in the input. |
| After the call, <CODE>*<VAR>inbuf</VAR></CODE> points at the first byte of the |
| invalid byte sequence. |
| <br><br> <LI> E2BIG |
| The conversion stopped because it ran out of space in the output buffer. |
| <br><br> <LI> EINVAL |
| The conversion stopped because of an incomplete byte sequence at the end |
| of the input buffer. |
| <br><br> <LI> EBADF |
| The <VAR>cd</VAR> argument is invalid. |
| |
| <br><br> The <CODE>iconv</CODE> function was introduced in the XPG2 standard and is |
| declared in the <TT>iconv.h</TT> header. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="struct-__gconv_step" type="struct"> |
| <structure> |
| <synopsis> |
| 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><br> |
| </synopsis> |
| <elements> |
| <element content="struct __gconv_loaded_object *__shlib_handle"> |
| </element> |
| <element content="<LI>x const char *__modname"> |
| </element> |
| <element content="<LI>x int __counter"> |
| <synopsis> |
| 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><br> |
| </synopsis> |
| </element> |
| <element content="const char *__from_name"> |
| </element> |
| <element content="<LI>x const char *__to_name"> |
| <synopsis> |
| <CODE>__from_name</CODE> and <CODE>__to_name</CODE> 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><br> |
| </synopsis> |
| </element> |
| <element content="gconv_fct __fct"> |
| </element> |
| <element content="<LI>x gconv_init_fct __init_fct"> |
| </element> |
| <element content="<LI>x gconv_end_fct __end_fct"> |
| <synopsis> |
| These elements contain pointers to the functions in the loadable module. |
| The interface will be explained below. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="int __min_needed_from"> |
| </element> |
| <element content="<LI>x int __max_needed_from"> |
| </element> |
| <element content="<LI>x int __min_needed_to"> |
| </element> |
| <element content="<LI>x int __max_needed_to;"> |
| <synopsis> |
| These values have to be supplied in the init function of the module. The |
| <CODE>__min_needed_from</CODE> value specifies how many bytes a character of |
| the source character set at least needs. The <CODE>__max_needed_from</CODE> |
| specifies the maximum value that also includes possible shift sequences. |
| <br><br> The <CODE>__min_needed_to</CODE> and <CODE>__max_needed_to</CODE> values serve the |
| same purpose as <CODE>__min_needed_from</CODE> and <CODE>__max_needed_from</CODE> but |
| this time for the destination character set. |
| <br><br> It is crucial that these values be accurate since otherwise the |
| conversion functions will have problems or not work at all. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="int __stateful"> |
| <synopsis> |
| This element must also be initialized by the init function. |
| <CODE>int __stateful</CODE> is nonzero if the source character set is stateful. |
| Otherwise it is zero. |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="struct-__gconv_step_data" type="struct"> |
| <structure> |
| <synopsis> |
| This is the data structure that contains the information specific to |
| each use of the conversion functions. |
| <br><br> <br><br> |
| </synopsis> |
| <elements> |
| <element content="char *__outbuf"> |
| </element> |
| <element content="<LI>x char *__outbufend"> |
| <synopsis> |
| These elements specify the output buffer for the conversion step. The |
| <CODE>__outbuf</CODE> element points to the beginning of the buffer, and |
| <CODE>__outbufend</CODE> 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><br> Once the conversion is finished, if the conversion is the last step, the |
| <CODE>__outbuf</CODE> 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 <CODE>__outbufend</CODE> element must not be modified. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="int __is_last"> |
| <synopsis> |
| 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><br> |
| </synopsis> |
| </element> |
| <element content="int __invocation_counter"> |
| <synopsis> |
| 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><br> |
| </synopsis> |
| </element> |
| <element content="int __internal_use"> |
| <synopsis> |
| 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 <CODE>mbsrtowcs</CODE> et.al.: (i.e., the |
| function is not used directly through the <CODE>iconv</CODE> interface). |
| <br><br> This sometimes makes a difference as it is expected that the |
| <CODE>iconv</CODE> functions are used to translate entire texts while the |
| <CODE>mbsrtowcs</CODE> functions are normally used only to convert single |
| strings and might be used multiple times to convert entire texts. |
| <br><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 |
| <CODE>mbsrtowcs</CODE> 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 <CODE>mbsrtowcs</CODE>, the conversion functions have no |
| possibility to find this out. The situation is different for sequences |
| of <CODE>iconv</CODE> calls since the handle allows access to the needed |
| information. |
| <br><br> The <CODE>int __internal_use</CODE> element is mostly used together with |
| <CODE>__invocation_counter</CODE> as follows: |
| <br><br> <pre><br> |
| if (!data->__internal_use<br> |
| && data->__invocation_counter == 0)<br> |
| /* Emit prolog. */<br> |
| <small>...</small><br> |
| </pre> |
| <br><br> This element must never be modified. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="mbstate_t *__statep"> |
| <synopsis> |
| The <CODE>__statep</CODE> element points to an object of type <CODE>mbstate_t</CODE> |
| . The conversion of a stateful character |
| set must use the object pointed to by <CODE>__statep</CODE> to store |
| information about the conversion state. The <CODE>__statep</CODE> element |
| itself must never be modified. |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="function-argp_parse" type="function"> |
| <function returntype="error_t"> |
| <prototype> |
| <parameter content="const struct argp *argp"/> |
| <parameter content="int argc"/> |
| <parameter content="char **argv"/> |
| <parameter content="unsigned flags"/> |
| <parameter content="int *arg_index"/> |
| <parameter content="void *input"/> |
| </prototype> |
| <headers> |
| <header filename = "gconv.h"/> |
| <header filename = "argp.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>argp_parse</CODE> function parses the arguments in <VAR>argv</VAR>, of |
| length <VAR>argc</VAR>, using the argp parser <VAR>argp</VAR>. . |
| <br><br> A value of zero is the same as a <CODE>struct argp</CODE>containing all |
| zeros. <VAR>flags</VAR> is a set of flag bits that modify the parsing |
| behavior. . <VAR>input</VAR> is passed through to the argp |
| parser <VAR>argp</VAR>, and has meaning defined by <VAR>argp</VAR>. A typical |
| usage is to pass a pointer to a structure which is used for specifying |
| parameters to the parser and passing back the results. |
| <br><br> Unless the <CODE>ARGP_NO_EXIT</CODE> or <CODE>ARGP_NO_HELP</CODE> flags are included |
| in <VAR>flags</VAR>, calling <CODE>argp_parse</CODE> may result in the program |
| exiting. This behavior is true if an error is detected, or when an |
| unknown option is encountered. . |
| <br><br> If <VAR>arg_index</VAR> is non-null, the index of the first unparsed option |
| in <VAR>argv</VAR> is returned as a value. |
| <br><br> The return value is zero for successful parsing, or an error code |
| if an error is detected. Different argp parsers |
| may return arbitrary error codes, but the standard error codes are: |
| <CODE>ENOMEM</CODE> if a memory allocation error occurred, or <CODE>EINVAL</CODE> if |
| an unknown option or option argument is encountered. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="struct-argp" type="struct"> |
| <structure> |
| <synopsis> |
| 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><br> |
| </synopsis> |
| <elements> |
| <element content="const struct argp_option *options"> |
| <synopsis> |
| A pointer to a vector of <CODE>argp_option</CODE> structures specifying which |
| options this argp parser understands; it may be zero if there are no |
| options at all. . |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="argp_parser_t parser"> |
| <synopsis> |
| 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 <CODE>ARGP_ERR_UNKNOWN</CODE>. . |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="const char *args_doc"> |
| <synopsis> |
| If non-zero, a string describing what non-option arguments are called by |
| this parser. This is only used to print the <samp>Usage:</samp> 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 <samp> or: </samp> instead of <samp>Usage:</samp>. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="const char *doc"> |
| <synopsis> |
| 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 (<CODE>'\v'</CODE>, <CODE>'\013'</CODE>) 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><br> |
| </synopsis> |
| </element> |
| <element content="const struct argp_child *children"> |
| <synopsis> |
| A pointer to a vector of <CODE>argp_children</CODE> structures. This pointer |
| specifies which additional argp parsers should be combined with this |
| one. . |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="char *(*help_filter)(int <VAR>key</VAR>, const char *<VAR>text</VAR>, void *<VAR>input</VAR>)"> |
| <synopsis> |
| If non-zero, a pointer to a function that filters the output of help |
| messages. . |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="struct-argp_option" type="struct"> |
| <structure> |
| <synopsis> |
| 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><br> |
| </synopsis> |
| <elements> |
| <element content="const char *name"> |
| <synopsis> |
| The long name for this option, corresponding to the long option |
| <samp>--<VAR>name</VAR></samp>; this field may be zero if this option <EM>only</EM> |
| has a short name. To specify multiple names for an option, additional |
| entries may follow this one, with the <CODE>OPTION_ALIAS</CODE> flag |
| set. . |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="int key"> |
| <synopsis> |
| The integer key provided by the current option to the option parser. If |
| <VAR>key</VAR> has a value that is a printable ascii character (i.e., |
| <CODE>isascii (<VAR>key</VAR>)</CODE> is true), it <EM>also</EM> specifies a short |
| option <samp>-<VAR>char</VAR></samp>, where <VAR>char</VAR> is the ascii character |
| with the code <VAR>key</VAR>. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="const char *arg"> |
| <synopsis> |
| If non-zero, this is the name of an argument associated with this |
| option, which must be provided (e.g., with the |
| <samp>--<VAR>name</VAR>=<VAR>value</VAR></samp> or <samp>-<VAR>char</VAR> <VAR>value</VAR></samp> |
| syntaxes), unless the <CODE>OPTION_ARG_OPTIONAL</CODE> flag is set, in which case it <EM>may</EM> be provided. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="int flags"> |
| <synopsis> |
| Flags associated with this option, some of which are referred to above. |
| . |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="const char *doc"> |
| <synopsis> |
| A documentation string for this option, for printing in help messages. |
| <br><br> If both the <CODE>name</CODE> and <CODE>key</CODE> 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 |
| <samp>:</samp> character. |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="function-argp_usage" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="const struct argp_state *state"/> |
| </prototype> |
| <headers> |
| <header filename = "argp.h"/> |
| </headers> |
| <synopsis> |
| Outputs the standard usage message for the argp parser referred to by |
| <VAR>state</VAR> to <CODE><VAR>state</VAR>->err_stream</CODE> and terminate the program |
| with <CODE>exit (argp_err_exit_status)</CODE>. . |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-argp_error" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="const struct argp_state *state"/> |
| <parameter content="const char *fmt"/> |
| <parameter content="..."/> |
| </prototype> |
| <headers> |
| <header filename = "argp.h"/> |
| </headers> |
| <synopsis> |
| Prints the printf format string <VAR>fmt</VAR> and following args, preceded |
| by the program name and <samp>:</samp>, and followed by a <samp>Try <small>...</small> |
| --help</samp> message, and terminates the program with an exit status of |
| <CODE>argp_err_exit_status</CODE>. . |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-argp_failure" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="const struct argp_state *state"/> |
| <parameter content="int status"/> |
| <parameter content="int errnum"/> |
| <parameter content="const char *fmt"/> |
| <parameter content="..."/> |
| </prototype> |
| <headers> |
| <header filename = "argp.h"/> |
| </headers> |
| <synopsis> |
| Similar to the standard gnu error-reporting function <CODE>error</CODE>, this |
| prints the program name and <samp>:</samp>, the printf format string |
| <VAR>fmt</VAR>, and the appropriate following args. If it is non-zero, the |
| standard unix error text for <VAR>errnum</VAR> is printed. If <VAR>status</VAR> is |
| non-zero, it terminates the program with that value as its exit status. |
| <br><br> The difference between <CODE>argp_failure</CODE> and <CODE>argp_error</CODE> is that |
| <CODE>argp_error</CODE> is for <EM>parsing errors</EM>, whereas |
| <CODE>argp_failure</CODE> is for other problems that occur during parsing but |
| don't reflect a syntactic problem with the input, such as illegal values |
| for options, bad phase of the moon, etc. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-argp_state_help" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="const struct argp_state *state"/> |
| <parameter content="FILE *stream"/> |
| <parameter content="unsigned flags"/> |
| </prototype> |
| <headers> |
| <header filename = "argp.h"/> |
| </headers> |
| <synopsis> |
| Outputs a help message for the argp parser referred to by <VAR>state</VAR>, |
| to <VAR>stream</VAR>. The <VAR>flags</VAR> argument determines what sort of help |
| message is produced. . |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="struct-argp_state" type="struct"> |
| <structure> |
| <synopsis> |
| This structure has the following fields, which may be modified as noted: |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="const struct argp *const root_argp"> |
| <synopsis> |
| The top level argp parser being parsed. Note that this is often |
| <EM>not</EM> the same <CODE>struct argp</CODE> passed into <CODE>argp_parse</CODE> by |
| the invoking program. . It is an internal argp parser that |
| contains options implemented by <CODE>argp_parse</CODE> itself, such as |
| <samp>--help</samp>. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="int argc"> |
| </element> |
| <element content="<LI>x char **argv"> |
| <synopsis> |
| The argument vector being parsed. This may be modified. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="int next"> |
| <synopsis> |
| The index in <CODE>argv</CODE> of the next argument to be parsed. This may be |
| modified. |
| <br><br> One way to consume all remaining arguments in the input is to set |
| <CODE><VAR>state</VAR>->next = <VAR>state</VAR>->argc</CODE>, perhaps after recording |
| the value of the <CODE>next</CODE> field to find the consumed arguments. The |
| current option can be re-parsed immediately by decrementing this field, |
| then modifying <CODE><VAR>state</VAR>->argv[<VAR>state</VAR>->next]</CODE> to reflect |
| the option that should be reexamined. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="unsigned flags"> |
| <synopsis> |
| The flags supplied to <CODE>argp_parse</CODE>. These may be modified, although |
| some flags may only take effect when <CODE>argp_parse</CODE> is first |
| invoked. . |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="unsigned arg_num"> |
| <synopsis> |
| While calling a parsing function with the <VAR>key</VAR> argument |
| <CODE>ARGP_KEY_ARG</CODE>, this represents the number of the current arg, |
| starting at 0. It is incremented after each <CODE>ARGP_KEY_ARG</CODE> call |
| returns. At all other times, this is the number of <CODE>ARGP_KEY_ARG</CODE> |
| arguments that have been processed. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="int quoted"> |
| <synopsis> |
| If non-zero, the index in <CODE>argv</CODE> of the first argument following a |
| special <samp>--</samp> 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><br> |
| </synopsis> |
| </element> |
| <element content="void *input"> |
| <synopsis> |
| An arbitrary pointer passed in from the caller of <CODE>argp_parse</CODE>, in |
| the <VAR>input</VAR> argument. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="void **child_inputs"> |
| <synopsis> |
| 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 |
| <CODE><VAR>state</VAR>->child_inputs[<VAR>i</VAR>]</CODE> as <EM>its</EM> |
| <CODE><VAR>state</VAR>->input</CODE> field, where <VAR>i</VAR> is the index of the child |
| in the this parser's <CODE>children</CODE> field. . |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="void *hook"> |
| <synopsis> |
| For the parser function's use. Initialized to 0, but otherwise ignored |
| by argp. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="char *name"> |
| <synopsis> |
| The name used when printing messages. This is initialized to |
| <CODE>argv[0]</CODE>, or <CODE>program_invocation_name</CODE> if <CODE>argv[0]</CODE> is |
| unavailable. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="FILE *err_stream"> |
| </element> |
| <element content="<LI>x FILE *out_stream"> |
| <synopsis> |
| The stdio streams used when argp prints. Error messages are printed to |
| <CODE>err_stream</CODE>, all other output, such as <samp>--help</samp> output) to |
| <CODE>out_stream</CODE>. These are initialized to <CODE>stderr</CODE> and |
| <CODE>stdout</CODE> respectively. . |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="struct-argp_child" type="struct"> |
| <structure> |
| <synopsis> |
| An entry in the list of subsidiary argp parsers pointed to by the |
| <CODE>children</CODE> field in a <CODE>struct argp</CODE>. The fields are as |
| follows: |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="const struct argp *argp"> |
| <synopsis> |
| The child argp parser, or zero to end of the list. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="int flags"> |
| <synopsis> |
| Flags for this child. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="const char *header"> |
| <synopsis> |
| 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 <CODE>""</CODE>. As with |
| header strings specified in an option entry, the conventional value of |
| the last character is <samp>:</samp>. . |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="function-argp_help" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="const struct argp *argp"/> |
| <parameter content="FILE *stream"/> |
| <parameter content="unsigned flags"/> |
| <parameter content="char *name"/> |
| </prototype> |
| <headers> |
| <header filename = "argp.h"/> |
| </headers> |
| <synopsis> |
| This outputs a help message for the argp parser <VAR>argp</VAR> to |
| <VAR>stream</VAR>. The type of messages printed will be determined by |
| <VAR>flags</VAR>. |
| <br><br> Any options such as <samp>--help</samp> that are implemented automatically by |
| argp itself will <EM>not</EM> be present in the help output; for this |
| reason it is best to use <CODE>argp_state_help</CODE> if calling from within |
| an argp parser function. . |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-malloc" type="function"> |
| <function returntype="void *"> |
| <prototype> |
| <parameter content="size_t size"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| This function returns a pointer to a newly allocated block <VAR>size</VAR> |
| bytes long, or a null pointer if the block could not be allocated. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-free" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="void *ptr"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>free</CODE> function deallocates the block of memory pointed at |
| by <VAR>ptr</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-cfree" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="void *ptr"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| This function does the same thing as <CODE>free</CODE>. It's provided for |
| backward compatibility with SunOS; you should use <CODE>free</CODE> instead. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-realloc" type="function"> |
| <function returntype="void *"> |
| <prototype> |
| <parameter content="void *ptr"/> |
| <parameter content="size_t newsize"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>realloc</CODE> function changes the size of the block whose address is |
| <VAR>ptr</VAR> to be <VAR>newsize</VAR>. |
| <br><br> Since the space after the end of the block may be in use, <CODE>realloc</CODE> |
| may find it necessary to copy the block to a new address where more free |
| space is available. The value of <CODE>realloc</CODE> is the new address of the |
| block. If the block needs to be moved, <CODE>realloc</CODE> copies the old |
| contents. |
| <br><br> If you pass a null pointer for <VAR>ptr</VAR>, <CODE>realloc</CODE> behaves just |
| like <samp>malloc (<VAR>newsize</VAR>)</samp>. This can be convenient, but beware |
| that older implementations (before ISO C) may not support this |
| behavior, and will probably crash when <CODE>realloc</CODE> is passed a null |
| pointer. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-calloc" type="function"> |
| <function returntype="void *"> |
| <prototype> |
| <parameter content="size_t count"/> |
| <parameter content="size_t eltsize"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| This function allocates a block long enough to contain a vector of |
| <VAR>count</VAR> elements, each of size <VAR>eltsize</VAR>. Its contents are |
| cleared to zero before <CODE>calloc</CODE> returns. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-memalign" type="function"> |
| <function returntype="void *"> |
| <prototype> |
| <parameter content="size_t boundary"/> |
| <parameter content="size_t size"/> |
| </prototype> |
| <headers> |
| <header filename = "malloc.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>memalign</CODE> function allocates a block of <VAR>size</VAR> bytes whose |
| address is a multiple of <VAR>boundary</VAR>. The <VAR>boundary</VAR> must be a |
| power of two! The function <CODE>memalign</CODE> works by allocating a |
| somewhat larger block, and then returning an address within the block |
| that is on the specified boundary. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-posix_memalign" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="void **memptr"/> |
| <parameter content="size_t alignment"/> |
| <parameter content="size_t size"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>posix_memalign</CODE> function is similar to the <CODE>memalign</CODE> |
| function in that it returns a buffer of <VAR>size</VAR> bytes aligned to a |
| multiple of <VAR>alignment</VAR>. But it adds one requirement to the |
| parameter <VAR>alignment</VAR>: the value must be a power of two multiple of |
| <CODE>sizeof (void *)</CODE>. |
| <br><br> If the function succeeds in allocation memory a pointer to the allocated |
| memory is returned in <CODE>*<VAR>memptr</VAR></CODE> and the return value is zero. |
| Otherwise the function returns an error value indicating the problem. |
| <br><br> This function was introduced in POSIX 1003.1d. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-valloc" type="function"> |
| <function returntype="void *"> |
| <prototype> |
| <parameter content="size_t size"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| Using <CODE>valloc</CODE> is like using <CODE>memalign</CODE> and passing the page size |
| as the value of the second argument. It is implemented like this: |
| <br><br> <pre><br> |
| void *<br> |
| valloc (size_t size)<br> |
| {<br> |
| return memalign (getpagesize (), size);<br> |
| }<br> |
| </pre> |
| <br><br> Query Memory Parameters for more information about the memory |
| subsystem. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-mallopt" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int param"/> |
| <parameter content="int value"/> |
| </prototype> |
| <synopsis> |
| When calling <CODE>mallopt</CODE>, the <VAR>param</VAR> argument specifies the |
| parameter to be set, and <VAR>value</VAR> the new value to be set. Possible |
| choices for <VAR>param</VAR>, as defined in <TT>malloc.h</TT>, are: |
| <br><br> <DL> |
| |
| <DT><CODE>M_TRIM_THRESHOLD</CODE> |
| <DD> |
| This is the minimum size (in bytes) of the top-most, releasable chunk |
| that will cause <CODE>sbrk</CODE> to be called with a negative argument in |
| order to return memory to the system. |
| <LI> M_TOP_PAD |
| This parameter determines the amount of extra memory to obtain from the |
| system when a call to <CODE>sbrk</CODE> is required. It also specifies the |
| number of bytes to retain when shrinking the heap by calling <CODE>sbrk</CODE> |
| with a negative argument. This provides the necessary hysteresis in |
| heap size such that excessive amounts of system calls can be avoided. |
| <LI> M_MMAP_THRESHOLD |
| All chunks larger than this value are allocated outside the normal |
| heap, using the <CODE>mmap</CODE> system call. This way it is guaranteed |
| that the memory for these chunks can be returned to the system on |
| <CODE>free</CODE>. Note that requests smaller than this threshold might still |
| be allocated via <CODE>mmap</CODE>. |
| <LI> M_MMAP_MAX |
| The maximum number of chunks to allocate with <CODE>mmap</CODE>. Setting this |
| to zero disables all use of <CODE>mmap</CODE>. |
| <LI> M_PERTURB |
| If non-zero, memory blocks are filled with values depending on some |
| low order bits of this parameter when they are allocated (except when |
| allocated by <CODE>calloc</CODE>) and freed. This can be used to debug the |
| use of uninitialized or freed heap memory. |
| |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-mcheck" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="void (*abortfn) (enum mcheck_status status)"/> |
| </prototype> |
| <headers> |
| <header filename = "mcheck.h"/> |
| </headers> |
| <synopsis> |
| Calling <CODE>mcheck</CODE> tells <CODE>malloc</CODE> to perform occasional |
| consistency checks. These will catch things such as writing |
| past the end of a block that was allocated with <CODE>malloc</CODE>. |
| <br><br> The <VAR>abortfn</VAR> argument is the function to call when an inconsistency |
| is found. If you supply a null pointer, then <CODE>mcheck</CODE> uses a |
| default function which prints a message and calls <CODE>abort</CODE> |
| . The function you supply is called with |
| one argument, which says what sort of inconsistency was detected; its |
| type is described below. |
| <br><br> It is too late to begin allocation checking once you have allocated |
| anything with <CODE>malloc</CODE>. So <CODE>mcheck</CODE> does nothing in that |
| case. The function returns <CODE>-1</CODE> if you call it too late, and |
| <CODE>0</CODE> otherwise (when it is successful). |
| <br><br> The easiest way to arrange to call <CODE>mcheck</CODE> early enough is to use |
| the option <samp>-lmcheck</samp> when you link your program; then you don't |
| need to modify your program source at all. Alternatively you might use |
| a debugger to insert a call to <CODE>mcheck</CODE> whenever the program is |
| started, for example these gdb commands will automatically call <CODE>mcheck</CODE> |
| whenever the program starts: |
| <br><br> <pre><br> |
| (gdb) break main<br> |
| Breakpoint 1, main (argc=2, argv=0xbffff964) at whatever.c:10<br> |
| (gdb) command 1<br> |
| Type commands for when breakpoint 1 is hit, one per line.<br> |
| End with a line saying just "end".<br> |
| >call mcheck(0)<br> |
| >continue<br> |
| >end<br> |
| (gdb) <small>...</small><br> |
| </pre> |
| <br><br> This will however only work if no initialization function of any object |
| involved calls any of the <CODE>malloc</CODE> functions since <CODE>mcheck</CODE> |
| must be called before the first such function. |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-mprobe" type="function"> |
| <function returntype="enum mcheck_status"> |
| <prototype> |
| <parameter content="void *pointer"/> |
| </prototype> |
| <synopsis> |
| The <CODE>mprobe</CODE> function lets you explicitly check for inconsistencies |
| in a particular allocated block. You must have already called |
| <CODE>mcheck</CODE> at the beginning of the program, to do its occasional |
| checks; calling <CODE>mprobe</CODE> requests an additional consistency check |
| to be done at the time of the call. |
| <br><br> The argument <VAR>pointer</VAR> must be a pointer returned by <CODE>malloc</CODE> |
| or <CODE>realloc</CODE>. <CODE>mprobe</CODE> returns a value that says what |
| inconsistency, if any, was found. The values are described below. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="enum-mcheck_status" type="enum"> |
| <structure> |
| <synopsis> |
| This enumerated type describes what kind of inconsistency was detected |
| in an allocated block, if any. Here are the possible values: |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="MCHECK_DISABLED"> |
| <synopsis> |
| <CODE>mcheck</CODE> was not called before the first allocation. |
| No consistency checking can be done. |
| </synopsis> |
| </element> |
| <element content="MCHECK_OK"> |
| <synopsis> |
| No inconsistency detected. |
| </synopsis> |
| </element> |
| <element content="MCHECK_HEAD"> |
| <synopsis> |
| The data immediately before the block was modified. |
| This commonly happens when an array index or pointer |
| is decremented too far. |
| </synopsis> |
| </element> |
| <element content="MCHECK_TAIL"> |
| <synopsis> |
| The data immediately after the block was modified. |
| This commonly happens when an array index or pointer |
| is incremented too far. |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="struct-mallinfo" type="struct"> |
| <structure> |
| <synopsis> |
| This structure type is used to return information about the dynamic |
| memory allocator. It contains the following members: |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="int arena"> |
| <synopsis> |
| This is the total size of memory allocated with <CODE>sbrk</CODE> by |
| <CODE>malloc</CODE>, in bytes. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="int ordblks"> |
| <synopsis> |
| 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 <CODE>malloc</CODE> requests; see |
| Efficiency and Malloc.) |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="int smblks"> |
| <synopsis> |
| This field is unused. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="int hblks"> |
| <synopsis> |
| This is the total number of chunks allocated with <CODE>mmap</CODE>. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="int hblkhd"> |
| <synopsis> |
| This is the total size of memory allocated with <CODE>mmap</CODE>, in bytes. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="int usmblks"> |
| <synopsis> |
| This field is unused. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="int fsmblks"> |
| <synopsis> |
| This field is unused. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="int uordblks"> |
| <synopsis> |
| This is the total size of memory occupied by chunks handed out by |
| <CODE>malloc</CODE>. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="int fordblks"> |
| <synopsis> |
| This is the total size of memory occupied by free (not in use) chunks. |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="function-mallinfo" type="function"> |
| <function returntype="struct mallinfo"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "malloc.h"/> |
| </headers> |
| <synopsis> |
| This function returns information about the current dynamic memory usage |
| in a structure of type <CODE>struct mallinfo</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-mtrace" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "mcheck.h"/> |
| </headers> |
| <synopsis> |
| When the <CODE>mtrace</CODE> function is called it looks for an environment |
| variable named <CODE>MALLOC_TRACE</CODE>. This variable is supposed to |
| contain a valid file name. The user must have write access. If the |
| file already exists it is truncated. If the environment variable is not |
| set or it does not name a valid file which can be opened for writing |
| nothing is done. The behavior of <CODE>malloc</CODE> etc. is not changed. |
| For obvious reasons this also happens if the application is installed |
| with the SUID or SGID bit set. |
| <br><br> If the named file is successfully opened, <CODE>mtrace</CODE> installs special |
| handlers for the functions <CODE>malloc</CODE>, <CODE>realloc</CODE>, and |
| <CODE>free</CODE> . From then on, all uses of these |
| functions are traced and protocolled into the file. There is now of |
| course a speed penalty for all calls to the traced functions so tracing |
| should not be enabled during normal use. |
| <br><br> This function is a GNU extension and generally not available on other |
| systems. The prototype can be found in <TT>mcheck.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-muntrace" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "mcheck.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>muntrace</CODE> function can be called after <CODE>mtrace</CODE> was used |
| to enable tracing the <CODE>malloc</CODE> calls. If no (successful) call of |
| <CODE>mtrace</CODE> was made <CODE>muntrace</CODE> does nothing. |
| <br><br> Otherwise it deinstalls the handlers for <CODE>malloc</CODE>, <CODE>realloc</CODE>, |
| and <CODE>free</CODE> and then closes the protocol file. No calls are |
| protocolled anymore and the program runs again at full speed. |
| <br><br> This function is a GNU extension and generally not available on other |
| systems. The prototype can be found in <TT>mcheck.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="struct-obstack" type="struct"> |
| <structure> |
| </structure> |
| </construct> |
| <construct id="function-obstack_init" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="struct obstack *obstack-ptr"/> |
| </prototype> |
| <headers> |
| <header filename = "obstack.h"/> |
| </headers> |
| <synopsis> |
| Initialize obstack <VAR>obstack-ptr</VAR> for allocation of objects. This |
| function calls the obstack's <CODE>obstack_chunk_alloc</CODE> function. If |
| allocation of memory fails, the function pointed to by |
| <CODE>obstack_alloc_failed_handler</CODE> is called. The <CODE>obstack_init</CODE> |
| function always returns 1 (Compatibility notice: Former versions of |
| obstack returned 0 if allocation failed). |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-obstack_alloc" type="function"> |
| <function returntype="void *"> |
| <prototype> |
| <parameter content="struct obstack *obstack-ptr"/> |
| <parameter content="int size"/> |
| </prototype> |
| <headers> |
| <header filename = "obstack.h"/> |
| </headers> |
| <synopsis> |
| This allocates an uninitialized block of <VAR>size</VAR> bytes in an obstack |
| and returns its address. Here <VAR>obstack-ptr</VAR> specifies which obstack |
| to allocate the block in; it is the address of the <CODE>struct obstack</CODE> |
| object which represents the obstack. Each obstack function or macro |
| requires you to specify an <VAR>obstack-ptr</VAR> as the first argument. |
| <br><br> This function calls the obstack's <CODE>obstack_chunk_alloc</CODE> function if |
| it needs to allocate a new chunk of memory; it calls |
| <CODE>obstack_alloc_failed_handler</CODE> if allocation of memory by |
| <CODE>obstack_chunk_alloc</CODE> failed. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-obstack_copy" type="function"> |
| <function returntype="void *"> |
| <prototype> |
| <parameter content="struct obstack *obstack-ptr"/> |
| <parameter content="void *address"/> |
| <parameter content="int size"/> |
| </prototype> |
| <headers> |
| <header filename = "obstack.h"/> |
| </headers> |
| <synopsis> |
| This allocates a block and initializes it by copying <VAR>size</VAR> |
| bytes of data starting at <VAR>address</VAR>. It calls |
| <CODE>obstack_alloc_failed_handler</CODE> if allocation of memory by |
| <CODE>obstack_chunk_alloc</CODE> failed. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-obstack_copy0" type="function"> |
| <function returntype="void *"> |
| <prototype> |
| <parameter content="struct obstack *obstack-ptr"/> |
| <parameter content="void *address"/> |
| <parameter content="int size"/> |
| </prototype> |
| <headers> |
| <header filename = "obstack.h"/> |
| </headers> |
| <synopsis> |
| Like <CODE>obstack_copy</CODE>, but appends an extra byte containing a null |
| character. This extra byte is not counted in the argument <VAR>size</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-obstack_free" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="struct obstack *obstack-ptr"/> |
| <parameter content="void *object"/> |
| </prototype> |
| <headers> |
| <header filename = "obstack.h"/> |
| </headers> |
| <synopsis> |
| If <VAR>object</VAR> is a null pointer, everything allocated in the obstack |
| is freed. Otherwise, <VAR>object</VAR> must be the address of an object |
| allocated in the obstack. Then <VAR>object</VAR> is freed, along with |
| everything allocated in <VAR>obstack</VAR> since <VAR>object</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-obstack_blank" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="struct obstack *obstack-ptr"/> |
| <parameter content="int size"/> |
| </prototype> |
| <headers> |
| <header filename = "obstack.h"/> |
| </headers> |
| <synopsis> |
| The most basic function for adding to a growing object is |
| <CODE>obstack_blank</CODE>, which adds space without initializing it. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-obstack_grow" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="struct obstack *obstack-ptr"/> |
| <parameter content="void *data"/> |
| <parameter content="int size"/> |
| </prototype> |
| <headers> |
| <header filename = "obstack.h"/> |
| </headers> |
| <synopsis> |
| To add a block of initialized space, use <CODE>obstack_grow</CODE>, which is |
| the growing-object analogue of <CODE>obstack_copy</CODE>. It adds <VAR>size</VAR> |
| bytes of data to the growing object, copying the contents from |
| <VAR>data</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-obstack_grow0" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="struct obstack *obstack-ptr"/> |
| <parameter content="void *data"/> |
| <parameter content="int size"/> |
| </prototype> |
| <headers> |
| <header filename = "obstack.h"/> |
| </headers> |
| <synopsis> |
| This is the growing-object analogue of <CODE>obstack_copy0</CODE>. It adds |
| <VAR>size</VAR> bytes copied from <VAR>data</VAR>, followed by an additional null |
| character. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-obstack_1grow" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="struct obstack *obstack-ptr"/> |
| <parameter content="char c"/> |
| </prototype> |
| <headers> |
| <header filename = "obstack.h"/> |
| </headers> |
| <synopsis> |
| To add one character at a time, use the function <CODE>obstack_1grow</CODE>. |
| It adds a single byte containing <VAR>c</VAR> to the growing object. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-obstack_ptr_grow" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="struct obstack *obstack-ptr"/> |
| <parameter content="void *data"/> |
| </prototype> |
| <headers> |
| <header filename = "obstack.h"/> |
| </headers> |
| <synopsis> |
| Adding the value of a pointer one can use the function |
| <CODE>obstack_ptr_grow</CODE>. It adds <CODE>sizeof (void *)</CODE> bytes |
| containing the value of <VAR>data</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-obstack_int_grow" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="struct obstack *obstack-ptr"/> |
| <parameter content="int data"/> |
| </prototype> |
| <headers> |
| <header filename = "obstack.h"/> |
| </headers> |
| <synopsis> |
| A single value of type <CODE>int</CODE> can be added by using the |
| <CODE>obstack_int_grow</CODE> function. It adds <CODE>sizeof (int)</CODE> bytes to |
| the growing object and initializes them with the value of <VAR>data</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-obstack_finish" type="function"> |
| <function returntype="void *"> |
| <prototype> |
| <parameter content="struct obstack *obstack-ptr"/> |
| </prototype> |
| <headers> |
| <header filename = "obstack.h"/> |
| </headers> |
| <synopsis> |
| When you are finished growing the object, use the function |
| <CODE>obstack_finish</CODE> to close it off and return its final address. |
| <br><br> Once you have finished the object, the obstack is available for ordinary |
| allocation or for growing another object. |
| <br><br> This function can return a null pointer under the same conditions as |
| <CODE>obstack_alloc</CODE> . |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-obstack_object_size" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="struct obstack *obstack-ptr"/> |
| </prototype> |
| <headers> |
| <header filename = "obstack.h"/> |
| </headers> |
| <synopsis> |
| This function returns the current size of the growing object, in bytes. |
| Remember to call this function <EM>before</EM> finishing the object. |
| After it is finished, <CODE>obstack_object_size</CODE> will return zero. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-obstack_room" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="struct obstack *obstack-ptr"/> |
| </prototype> |
| <headers> |
| <header filename = "obstack.h"/> |
| </headers> |
| <synopsis> |
| This returns the number of bytes that can be added safely to the current |
| growing object (or to an object about to be started) in obstack |
| <VAR>obstack</VAR> using the fast growth functions. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-obstack_1grow_fast" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="struct obstack *obstack-ptr"/> |
| <parameter content="char c"/> |
| </prototype> |
| <headers> |
| <header filename = "obstack.h"/> |
| </headers> |
| <synopsis> |
| The function <CODE>obstack_1grow_fast</CODE> adds one byte containing the |
| character <VAR>c</VAR> to the growing object in obstack <VAR>obstack-ptr</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-obstack_ptr_grow_fast" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="struct obstack *obstack-ptr"/> |
| <parameter content="void *data"/> |
| </prototype> |
| <headers> |
| <header filename = "obstack.h"/> |
| </headers> |
| <synopsis> |
| The function <CODE>obstack_ptr_grow_fast</CODE> adds <CODE>sizeof (void *)</CODE> |
| bytes containing the value of <VAR>data</VAR> to the growing object in |
| obstack <VAR>obstack-ptr</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-obstack_int_grow_fast" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="struct obstack *obstack-ptr"/> |
| <parameter content="int data"/> |
| </prototype> |
| <headers> |
| <header filename = "obstack.h"/> |
| </headers> |
| <synopsis> |
| The function <CODE>obstack_int_grow_fast</CODE> adds <CODE>sizeof (int)</CODE> bytes |
| containing the value of <VAR>data</VAR> to the growing object in obstack |
| <VAR>obstack-ptr</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-obstack_blank_fast" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="struct obstack *obstack-ptr"/> |
| <parameter content="int size"/> |
| </prototype> |
| <headers> |
| <header filename = "obstack.h"/> |
| </headers> |
| <synopsis> |
| The function <CODE>obstack_blank_fast</CODE> adds <VAR>size</VAR> bytes to the |
| growing object in obstack <VAR>obstack-ptr</VAR> without initializing them. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-obstack_base" type="function"> |
| <function returntype="void *"> |
| <prototype> |
| <parameter content="struct obstack *obstack-ptr"/> |
| </prototype> |
| <headers> |
| <header filename = "obstack.h"/> |
| </headers> |
| <synopsis> |
| This function returns the tentative address of the beginning of the |
| currently growing object in <VAR>obstack-ptr</VAR>. If you finish the object |
| immediately, it will have that address. If you make it larger first, it |
| may outgrow the current chunk---then its address will change! |
| <br><br> If no object is growing, this value says where the next object you |
| allocate will start (once again assuming it fits in the current |
| chunk). |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-obstack_next_free" type="function"> |
| <function returntype="void *"> |
| <prototype> |
| <parameter content="struct obstack *obstack-ptr"/> |
| </prototype> |
| <headers> |
| <header filename = "obstack.h"/> |
| </headers> |
| <synopsis> |
| This function returns the address of the first free byte in the current |
| chunk of obstack <VAR>obstack-ptr</VAR>. This is the end of the currently |
| growing object. If no object is growing, <CODE>obstack_next_free</CODE> |
| returns the same value as <CODE>obstack_base</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-obstack_object_size" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="struct obstack *obstack-ptr"/> |
| </prototype> |
| <headers> |
| <header filename = "obstack.h"/> |
| </headers> |
| <synopsis> |
| This function returns the size in bytes of the currently growing object. |
| This is equivalent to |
| <br><br> <pre><br> |
| obstack_next_free (<VAR>obstack-ptr</VAR>) - obstack_base (<VAR>obstack-ptr</VAR>)<br> |
| </pre> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-alloca" type="function"> |
| <function returntype="void *"> |
| <prototype> |
| <parameter content="size_t size"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The return value of <CODE>alloca</CODE> is the address of a block of <VAR>size</VAR> |
| bytes of memory, allocated in the stack frame of the calling function. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-brk" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="void *addr"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| <br><br> <CODE>brk</CODE> sets the high end of the calling process' data segment to |
| <VAR>addr</VAR>. |
| <br><br> The address of the end of a segment is defined to be the address of the |
| last byte in the segment plus 1. |
| <br><br> The function has no effect if <VAR>addr</VAR> is lower than the low end of |
| the data segment. (This is considered success, by the way). |
| <br><br> The function fails if it would cause the data segment to overlap another |
| segment or exceed the process' data storage limit . |
| <br><br> The function is named for a common historical case where data storage |
| and the stack are in the same segment. Data storage allocation grows |
| upward from the bottom of the segment while the stack grows downward |
| toward it from the top of the segment and the curtain between them is |
| called the break. |
| <br><br> The return value is zero on success. On failure, the return value is |
| <CODE>-1</CODE> and <CODE>errno</CODE> is set accordingly. The following <CODE>errno</CODE> |
| values are specific to this function: |
| <br><br> <DL> |
| |
| <DT><CODE>ENOMEM</CODE> |
| <DD> |
| The request would cause the data segment to overlap another segment or |
| exceed the process' data storage limit. |
| |
| <br><br> <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-mlock" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const void *addr"/> |
| <parameter content="size_t len"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| <header filename = "sys/mman.h"/> |
| </headers> |
| <synopsis> |
| <br><br> <CODE>mlock</CODE> locks a range of the calling process' virtual pages. |
| <br><br> The range of memory starts at address <VAR>addr</VAR> and is <VAR>len</VAR> bytes |
| long. Actually, since you must lock whole pages, it is the range of |
| pages that include any part of the specified range. |
| <br><br> When the function returns successfully, each of those pages is backed by |
| (connected to) a real frame (is resident) and is marked to stay that |
| way. This means the function may cause page-ins and have to wait for |
| them. |
| <br><br> When the function fails, it does not affect the lock status of any |
| pages. |
| <br><br> The return value is zero if the function succeeds. Otherwise, it is |
| <CODE>-1</CODE> and <CODE>errno</CODE> is set accordingly. <CODE>errno</CODE> values |
| specific to this function are: |
| <br><br> <DL> |
| |
| <DT><CODE>ENOMEM</CODE> |
| <DD> |
| <OL> |
| <LI> |
| At least some of the specified address range does not exist in the |
| calling process' virtual address space. |
| <LI> |
| The locking would cause the process to exceed its locked page limit. |
| </OL> |
| <br><br> <LI> EPERM |
| The calling process is not superuser. |
| <br><br> <LI> EINVAL |
| <VAR>len</VAR> is not positive. |
| <br><br> <LI> ENOSYS |
| The kernel does not provide <CODE>mlock</CODE> capability. |
| <br><br> |
| <br><br> You can lock <EM>all</EM> a process' memory with <CODE>mlockall</CODE>. You |
| unlock memory with <CODE>munlock</CODE> or <CODE>munlockall</CODE>. |
| <br><br> To avoid all page faults in a C program, you have to use |
| <CODE>mlockall</CODE>, because some of the memory a program uses is hidden |
| from the C code, e.g. the stack and automatic variables, and you |
| wouldn't know what address to tell <CODE>mlock</CODE>. |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-munlock" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const void *addr"/> |
| <parameter content="size_t len"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/mman.h"/> |
| </headers> |
| <synopsis> |
| <br><br> <CODE>munlock</CODE> unlocks a range of the calling process' virtual pages. |
| <br><br> <CODE>munlock</CODE> is the inverse of <CODE>mlock</CODE> and functions completely |
| analogously to <CODE>mlock</CODE>, except that there is no <CODE>EPERM</CODE> |
| failure. |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-mlockall" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int flags"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/mman.h"/> |
| </headers> |
| <synopsis> |
| <br><br> <CODE>mlockall</CODE> locks all the pages in a process' virtual memory address |
| space, and/or any that are added to it in the future. This includes the |
| pages of the code, data and stack segment, as well as shared libraries, |
| user space kernel data, shared memory, and memory mapped files. |
| <br><br> <VAR>flags</VAR> is a string of single bit flags represented by the following |
| macros. They tell <CODE>mlockall</CODE> which of its functions you want. All |
| other bits must be zero. |
| <br><br> <DL> |
| |
| <br><br> <DT><CODE>MCL_CURRENT</CODE> |
| <DD> |
| Lock all pages which currently exist in the calling process' virtual |
| address space. |
| <br><br> <DT><CODE>MCL_FUTURE</CODE> |
| <DD> |
| Set a mode such that any pages added to the process' virtual address |
| space in the future will be locked from birth. This mode does not |
| affect future address spaces owned by the same process so exec, which |
| replaces a process' address space, wipes out <CODE>MCL_FUTURE</CODE>. |
| . |
| <br><br> |
| <br><br> When the function returns successfully, and you specified |
| <CODE>MCL_CURRENT</CODE>, all of the process' pages are backed by (connected |
| to) real frames (they are resident) and are marked to stay that way. |
| This means the function may cause page-ins and have to wait for them. |
| <br><br> When the process is in <CODE>MCL_FUTURE</CODE> mode because it successfully |
| executed this function and specified <CODE>MCL_CURRENT</CODE>, any system call |
| by the process that requires space be added to its virtual address space |
| fails with <CODE>errno</CODE> = <CODE>ENOMEM</CODE> if locking the additional space |
| would cause the process to exceed its locked page limit. In the case |
| that the address space addition that can't be accommodated is stack |
| expansion, the stack expansion fails and the kernel sends a |
| <CODE>SIGSEGV</CODE> signal to the process. |
| <br><br> When the function fails, it does not affect the lock status of any pages |
| or the future locking mode. |
| <br><br> The return value is zero if the function succeeds. Otherwise, it is |
| <CODE>-1</CODE> and <CODE>errno</CODE> is set accordingly. <CODE>errno</CODE> values |
| specific to this function are: |
| <br><br> <DL> |
| |
| <LI> ENOMEM |
| <OL> |
| <LI> |
| At least some of the specified address range does not exist in the |
| calling process' virtual address space. |
| <LI> |
| The locking would cause the process to exceed its locked page limit. |
| </OL> |
| <br><br> <LI> EPERM |
| The calling process is not superuser. |
| <br><br> <LI> EINVAL |
| Undefined bits in <VAR>flags</VAR> are not zero. |
| <br><br> <LI> ENOSYS |
| The kernel does not provide <CODE>mlockall</CODE> capability. |
| <br><br> |
| <br><br> You can lock just specific pages with <CODE>mlock</CODE>. You unlock pages |
| with <CODE>munlockall</CODE> and <CODE>munlock</CODE>. |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-munlockall" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/mman.h"/> |
| </headers> |
| <synopsis> |
| <br><br> <CODE>munlockall</CODE> unlocks every page in the calling process' virtual |
| address space and turn off <CODE>MCL_FUTURE</CODE> future locking mode. |
| <br><br> The return value is zero if the function succeeds. Otherwise, it is |
| <CODE>-1</CODE> and <CODE>errno</CODE> is set accordingly. The only way this |
| function can fail is for generic reasons that all functions and system |
| calls can fail, so there are no specific <CODE>errno</CODE> values. |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getrusage" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int processes"/> |
| <parameter content="struct rusage *rusage"/> |
| </prototype> |
| <headers> |
| <header filename = "malloc.h"/> |
| <header filename = "sys/resource.h"/> |
| </headers> |
| <synopsis> |
| This function reports resource usage totals for processes specified by |
| <VAR>processes</VAR>, storing the information in <CODE>*<VAR>rusage</VAR></CODE>. |
| <br><br> In most systems, <VAR>processes</VAR> has only two valid values: |
| <br><br> <DL> |
| |
| <DT><CODE>RUSAGE_SELF</CODE> |
| <DD> |
| Just the current process. |
| <br><br> <DT><CODE>RUSAGE_CHILDREN</CODE> |
| <DD> |
| All child processes (direct and indirect) that have already terminated. |
| |
| <br><br> In the GNU system, you can also inquire about a particular child process |
| by specifying its process ID. |
| <br><br> The return value of <CODE>getrusage</CODE> is zero for success, and <CODE>-1</CODE> |
| for failure. |
| <br><br> <DL> |
| |
| <LI> EINVAL |
| The argument <VAR>processes</VAR> is not valid. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="struct-rusage" type="struct"> |
| <structure> |
| <synopsis> |
| This data type stores various resource usage statistics. It has the |
| following members, and possibly others: |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="struct timeval ru_utime"> |
| <synopsis> |
| Time spent executing user instructions. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="struct timeval ru_stime"> |
| <synopsis> |
| Time spent in operating system code on behalf of <VAR>processes</VAR>. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="long int ru_maxrss"> |
| <synopsis> |
| The maximum resident set size used, in kilobytes. That is, the maximum |
| number of kilobytes of physical memory that <VAR>processes</VAR> used |
| simultaneously. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="long int ru_ixrss"> |
| <synopsis> |
| 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><br> |
| </synopsis> |
| </element> |
| <element content="long int ru_idrss"> |
| <synopsis> |
| An integral value expressed the same way, which is the amount of |
| unshared memory used for data. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="long int ru_isrss"> |
| <synopsis> |
| An integral value expressed the same way, which is the amount of |
| unshared memory used for stack space. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="long int ru_minflt"> |
| <synopsis> |
| The number of page faults which were serviced without requiring any I/O. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="long int ru_majflt"> |
| <synopsis> |
| The number of page faults which were serviced by doing I/O. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="long int ru_nswap"> |
| <synopsis> |
| The number of times <VAR>processes</VAR> was swapped entirely out of main memory. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="long int ru_inblock"> |
| <synopsis> |
| The number of times the file system had to read from the disk on behalf |
| of <VAR>processes</VAR>. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="long int ru_oublock"> |
| <synopsis> |
| The number of times the file system had to write to the disk on behalf |
| of <VAR>processes</VAR>. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="long int ru_msgsnd"> |
| <synopsis> |
| Number of IPC messages sent. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="long int ru_msgrcv"> |
| <synopsis> |
| Number of IPC messages received. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="long int ru_nsignals"> |
| <synopsis> |
| Number of signals received. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="long int ru_nvcsw"> |
| <synopsis> |
| The number of times <VAR>processes</VAR> voluntarily invoked a context switch |
| (usually to wait for some service). |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="function-vtimes" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="struct vtimes current"/> |
| <parameter content="struct vtimes child"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/resource.h"/> |
| <header filename = "vtimes.h"/> |
| </headers> |
| <synopsis> |
| <br><br> <CODE>vtimes</CODE> reports resource usage totals for a process. |
| <br><br> If <VAR>current</VAR> is non-null, <CODE>vtimes</CODE> stores resource usage totals for |
| the invoking process alone in the structure to which it points. If |
| <VAR>child</VAR> is non-null, <CODE>vtimes</CODE> stores resource usage totals for all |
| past children (which have terminated) of the invoking process in the structure |
| to which it points. |
| <br><br> <h4>Data Type - struct vtimes</h4> |
| This data type contains information about the resource usage of a process. |
| Each member corresponds to a member of the <CODE>struct rusage</CODE> data type |
| described above. |
| <br><br> <DL> |
| |
| <DT><CODE>vm_utime</CODE> |
| <DD> |
| User CPU time. Analogous to <CODE>ru_utime</CODE> in <CODE>struct rusage</CODE> |
| <LI> vm_stime |
| System CPU time. Analogous to <CODE>ru_stime</CODE> in <CODE>struct rusage</CODE> |
| <LI> vm_idsrss |
| Data and stack memory. The sum of the values that would be reported as |
| <CODE>ru_idrss</CODE> and <CODE>ru_isrss</CODE> in <CODE>struct rusage</CODE> |
| <LI> vm_ixrss |
| Shared memory. Analogous to <CODE>ru_ixrss</CODE> in <CODE>struct rusage</CODE> |
| <LI> vm_maxrss |
| Maximent resident set size. Analogous to <CODE>ru_maxrss</CODE> in |
| <CODE>struct rusage</CODE> |
| <LI> vm_majflt |
| Major page faults. Analogous to <CODE>ru_majflt</CODE> in <CODE>struct rusage</CODE> |
| <LI> vm_minflt |
| Minor page faults. Analogous to <CODE>ru_minflt</CODE> in <CODE>struct rusage</CODE> |
| <LI> vm_nswap |
| Swap count. Analogous to <CODE>ru_nswap</CODE> in <CODE>struct rusage</CODE> |
| <LI> vm_inblk |
| Disk reads. Analogous to <CODE>ru_inblk</CODE> in <CODE>struct rusage</CODE> |
| <LI> vm_oublk |
| Disk writes. Analogous to <CODE>ru_oublk</CODE> in <CODE>struct rusage</CODE> |
| |
| |
| <br><br> <br><br> The return value is zero if the function succeeds; <CODE>-1</CODE> otherwise. |
| <br><br> <br><br> <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getrlimit" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int resource"/> |
| <parameter content="struct rlimit *rlp"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/resource.h"/> |
| </headers> |
| <synopsis> |
| Read the current and maximum limits for the resource <VAR>resource</VAR> |
| and store them in <CODE>*<VAR>rlp</VAR></CODE>. |
| <br><br> The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on failure. The |
| only possible <CODE>errno</CODE> error condition is <CODE>EFAULT</CODE>. |
| <br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> on a |
| 32-bit system this function is in fact <CODE>getrlimit64</CODE>. Thus, the |
| LFS interface transparently replaces the old interface. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getrlimit64" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int resource"/> |
| <parameter content="struct rlimit64 *rlp"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/resource.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to <CODE>getrlimit</CODE> but its second parameter is |
| a pointer to a variable of type <CODE>struct rlimit64</CODE>, which allows it |
| to read values which wouldn't fit in the member of a <CODE>struct |
| rlimit</CODE>. |
| <br><br> If the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> on a |
| 32-bit machine, this function is available under the name |
| <CODE>getrlimit</CODE> and so transparently replaces the old interface. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-setrlimit" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int resource"/> |
| <parameter content="const struct rlimit *rlp"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/resource.h"/> |
| </headers> |
| <synopsis> |
| Store the current and maximum limits for the resource <VAR>resource</VAR> |
| in <CODE>*<VAR>rlp</VAR></CODE>. |
| <br><br> The return value is <CODE>0</CODE> on success and <CODE>-1</CODE> on failure. The |
| following <CODE>errno</CODE> error condition is possible: |
| <br><br> <DL> |
| |
| <DT><CODE>EPERM</CODE> |
| <DD> |
| <OL> |
| <LI> |
| The process tried to raise a current limit beyond the maximum limit. |
| <br><br> <LI> |
| The process tried to raise a maximum limit, but is not superuser. |
| </OL> |
| |
| <br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> on a |
| 32-bit system this function is in fact <CODE>setrlimit64</CODE>. Thus, the |
| LFS interface transparently replaces the old interface. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-setrlimit64" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int resource"/> |
| <parameter content="const struct rlimit64 *rlp"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/resource.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to <CODE>setrlimit</CODE> but its second parameter is |
| a pointer to a variable of type <CODE>struct rlimit64</CODE> which allows it |
| to set values which wouldn't fit in the member of a <CODE>struct |
| rlimit</CODE>. |
| <br><br> If the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> on a |
| 32-bit machine this function is available under the name |
| <CODE>setrlimit</CODE> and so transparently replaces the old interface. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="struct-rlimit" type="struct"> |
| <structure> |
| <synopsis> |
| This structure is used with <CODE>getrlimit</CODE> to receive limit values, |
| and with <CODE>setrlimit</CODE> to specify limit values for a particular process |
| and resource. It has two fields: |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="rlim_t rlim_cur"> |
| <synopsis> |
| The current limit |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="struct-rlimit64" type="struct"> |
| <structure> |
| <synopsis> |
| This structure is analogous to the <CODE>rlimit</CODE> structure above, but |
| its components have wider ranges. It has two fields: |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="rlim64_t rlim_cur"> |
| <synopsis> |
| This is analogous to <CODE>rlimit.rlim_cur</CODE>, but with a different type. |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="function-ulimit" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int cmd"/> |
| <parameter content="..."/> |
| </prototype> |
| <headers> |
| <header filename = "sys/resource.h"/> |
| <header filename = "ulimit.h"/> |
| </headers> |
| <synopsis> |
| <br><br> <CODE>ulimit</CODE> gets the current limit or sets the current and maximum |
| limit for a particular resource for the calling process according to the |
| command <VAR>cmd</VAR>.a |
| <br><br> If you are getting a limit, the command argument is the only argument. |
| If you are setting a limit, there is a second argument: |
| <CODE>long int</CODE> <VAR>limit</VAR> which is the value to which you are setting |
| the limit. |
| <br><br> The <VAR>cmd</VAR> values and the operations they specify are: |
| <DL> |
| |
| <br><br> <DT><CODE>GETFSIZE</CODE> |
| <DD> |
| Get the current limit on the size of a file, in units of 512 bytes. |
| <br><br> <DT><CODE>SETFSIZE</CODE> |
| <DD> |
| Set the current and maximum limit on the size of a file to <VAR>limit</VAR> * |
| 512 bytes. |
| <br><br> |
| <br><br> There are also some other <VAR>cmd</VAR> values that may do things on some |
| systems, but they are not supported. |
| <br><br> Only the superuser may increase a maximum limit. |
| <br><br> When you successfully get a limit, the return value of <CODE>ulimit</CODE> is |
| that limit, which is never negative. When you successfully set a limit, |
| the return value is zero. When the function fails, the return value is |
| <CODE>-1</CODE> and <CODE>errno</CODE> is set according to the reason: |
| <br><br> <DL> |
| |
| <LI> EPERM |
| A process tried to increase a maximum limit, but is not superuser. |
| |
| <br><br> <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-vlimit" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int resource"/> |
| <parameter content="int limit"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/vlimit.h"/> |
| </headers> |
| <synopsis> |
| <br><br> <CODE>vlimit</CODE> sets the current limit for a resource for a process. |
| <br><br> <VAR>resource</VAR> identifies the resource: |
| <br><br> <DL> |
| |
| <DT><CODE>LIM_CPU</CODE> |
| <DD> |
| Maximum CPU time. Same as <CODE>RLIMIT_CPU</CODE> for <CODE>setrlimit</CODE>. |
| <DT><CODE>LIM_FSIZE</CODE> |
| <DD> |
| Maximum file size. Same as <CODE>RLIMIT_FSIZE</CODE> for <CODE>setrlimit</CODE>. |
| <LI> LIM_DATA |
| Maximum data memory. Same as <CODE>RLIMIT_DATA</CODE> for <CODE>setrlimit</CODE>. |
| <LI> LIM_STACK |
| Maximum stack size. Same as <CODE>RLIMIT_STACK</CODE> for <CODE>setrlimit</CODE>. |
| <LI> LIM_CORE |
| Maximum core file size. Same as <CODE>RLIMIT_COR</CODE> for <CODE>setrlimit</CODE>. |
| <LI> LIM_MAXRSS |
| Maximum physical memory. Same as <CODE>RLIMIT_RSS</CODE> for <CODE>setrlimit</CODE>. |
| |
| <br><br> The return value is zero for success, and <CODE>-1</CODE> with <CODE>errno</CODE> set |
| accordingly for failure: |
| <br><br> <DL> |
| |
| <LI> EPERM |
| The process tried to set its current limit beyond its maximum limit. |
| |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="struct-sched_param" type="struct"> |
| <structure> |
| <synopsis> |
| This structure describes an absolute priority. |
| </synopsis> |
| </structure> |
| </construct> |
| <construct id="function-sched_setscheduler" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="pid_t pid"/> |
| <parameter content="int policy"/> |
| <parameter content="const struct sched_param *param"/> |
| </prototype> |
| <headers> |
| <header filename = "sched.h"/> |
| </headers> |
| <synopsis> |
| <br><br> This function sets both the absolute priority and the scheduling policy |
| for a process. |
| <br><br> It assigns the absolute priority value given by <VAR>param</VAR> and the |
| scheduling policy <VAR>policy</VAR> to the process with Process ID <VAR>pid</VAR>, |
| or the calling process if <VAR>pid</VAR> is zero. If <VAR>policy</VAR> is |
| negative, <CODE>sched_setscheduler</CODE> keeps the existing scheduling policy. |
| <br><br> The following macros represent the valid values for <VAR>policy</VAR>: |
| <br><br> <DL> |
| |
| <DT><CODE>SCHED_OTHER</CODE> |
| <DD> |
| Traditional Scheduling |
| <DT><CODE>SCHED_FIFO</CODE> |
| <DD> |
| First In First Out |
| <LI> SCHED_RR |
| Round Robin |
| |
| <br><br> <br><br> On success, the return value is <CODE>0</CODE>. Otherwise, it is <CODE>-1</CODE> |
| and <CODE>ERRNO</CODE> is set accordingly. The <CODE>errno</CODE> values specific |
| to this function are: |
| <br><br> <DL> |
| |
| <LI> EPERM |
| <OL> |
| <LI> |
| The calling process does not have <CODE>CAP_SYS_NICE</CODE> permission and |
| <VAR>policy</VAR> is not <CODE>SCHED_OTHER</CODE> (or it's negative and the |
| existing policy is not <CODE>SCHED_OTHER</CODE>. |
| <br><br> <LI> |
| The calling process does not have <CODE>CAP_SYS_NICE</CODE> permission and its |
| owner is not the target process' owner. I.e., the effective uid of the |
| calling process is neither the effective nor the real uid of process |
| <VAR>pid</VAR>. |
| </OL> |
| <br><br> <LI> ESRCH |
| There is no process with pid <VAR>pid</VAR> and <VAR>pid</VAR> is not zero. |
| <br><br> <LI> EINVAL |
| <OL> |
| <LI> |
| <VAR>policy</VAR> does not identify an existing scheduling policy. |
| <br><br> <LI> |
| The absolute priority value identified by *<VAR>param</VAR> is outside the |
| valid range for the scheduling policy <VAR>policy</VAR> (or the existing |
| scheduling policy if <VAR>policy</VAR> is negative) or <VAR>param</VAR> is |
| null. <CODE>sched_get_priority_max</CODE> and <CODE>sched_get_priority_min</CODE> |
| tell you what the valid range is. |
| <br><br> <LI> |
| <VAR>pid</VAR> is negative. |
| </OL> |
| |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-sched_getscheduler" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="pid_t pid"/> |
| </prototype> |
| <headers> |
| <header filename = "sched.h"/> |
| </headers> |
| <synopsis> |
| <br><br> This function returns the scheduling policy assigned to the process with |
| Process ID (pid) <VAR>pid</VAR>, or the calling process if <VAR>pid</VAR> is zero. |
| <br><br> The return value is the scheduling policy. See |
| <CODE>sched_setscheduler</CODE> for the possible values. |
| <br><br> If the function fails, the return value is instead <CODE>-1</CODE> and |
| <CODE>errno</CODE> is set accordingly. |
| <br><br> The <CODE>errno</CODE> values specific to this function are: |
| <br><br> <DL> |
| |
| <br><br> <DT><CODE>ESRCH</CODE> |
| <DD> |
| There is no process with pid <VAR>pid</VAR> and it is not zero. |
| <br><br> <LI> EINVAL |
| <VAR>pid</VAR> is negative. |
| <br><br> |
| <br><br> Note that this function is not an exact mate to <CODE>sched_setscheduler</CODE> |
| because while that function sets the scheduling policy and the absolute |
| priority, this function gets only the scheduling policy. To get the |
| absolute priority, use <CODE>sched_getparam</CODE>. |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-sched_setparam" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="pid_t pid"/> |
| <parameter content="const struct sched_param *param"/> |
| </prototype> |
| <headers> |
| <header filename = "sched.h"/> |
| </headers> |
| <synopsis> |
| <br><br> This function sets a process' absolute priority. |
| <br><br> It is functionally identical to <CODE>sched_setscheduler</CODE> with |
| <VAR>policy</VAR> = <CODE>-1</CODE>. |
| <br><br> <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-sched_getparam" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="pid_t pid"/> |
| <parameter content="const struct sched_param *param"/> |
| </prototype> |
| <headers> |
| <header filename = "sched.h"/> |
| </headers> |
| <synopsis> |
| <br><br> This function returns a process' absolute priority. |
| <br><br> <VAR>pid</VAR> is the Process ID (pid) of the process whose absolute priority |
| you want to know. |
| <br><br> <VAR>param</VAR> is a pointer to a structure in which the function stores the |
| absolute priority of the process. |
| <br><br> On success, the return value is <CODE>0</CODE>. Otherwise, it is <CODE>-1</CODE> |
| and <CODE>ERRNO</CODE> is set accordingly. The <CODE>errno</CODE> values specific |
| to this function are: |
| <br><br> <DL> |
| |
| <br><br> <DT><CODE>ESRCH</CODE> |
| <DD> |
| There is no process with pid <VAR>pid</VAR> and it is not zero. |
| <br><br> <LI> EINVAL |
| <VAR>pid</VAR> is negative. |
| <br><br> |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-sched_get_priority_min" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int *policy"/> |
| </prototype> |
| <headers> |
| <header filename = "sched.h"/> |
| </headers> |
| <synopsis> |
| <br><br> This function returns the lowest absolute priority value that is |
| allowable for a process with scheduling policy <VAR>policy</VAR>. |
| <br><br> On Linux, it is 0 for SCHED_OTHER and 1 for everything else. |
| <br><br> On success, the return value is <CODE>0</CODE>. Otherwise, it is <CODE>-1</CODE> |
| and <CODE>ERRNO</CODE> is set accordingly. The <CODE>errno</CODE> values specific |
| to this function are: |
| <br><br> <DL> |
| |
| <DT><CODE>EINVAL</CODE> |
| <DD> |
| <VAR>policy</VAR> does not identify an existing scheduling policy. |
| |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-sched_get_priority_max" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int *policy"/> |
| </prototype> |
| <headers> |
| <header filename = "sched.h"/> |
| </headers> |
| <synopsis> |
| <br><br> This function returns the highest absolute priority value that is |
| allowable for a process that with scheduling policy <VAR>policy</VAR>. |
| <br><br> On Linux, it is 0 for SCHED_OTHER and 99 for everything else. |
| <br><br> On success, the return value is <CODE>0</CODE>. Otherwise, it is <CODE>-1</CODE> |
| and <CODE>ERRNO</CODE> is set accordingly. The <CODE>errno</CODE> values specific |
| to this function are: |
| <br><br> <DL> |
| |
| <DT><CODE>EINVAL</CODE> |
| <DD> |
| <VAR>policy</VAR> does not identify an existing scheduling policy. |
| |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-sched_rr_get_interval" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="pid_t pid"/> |
| <parameter content="struct timespec *interval"/> |
| </prototype> |
| <headers> |
| <header filename = "sched.h"/> |
| </headers> |
| <synopsis> |
| <br><br> This function returns the length of the quantum (time slice) used with |
| the Round Robin scheduling policy, if it is used, for the process with |
| Process ID <VAR>pid</VAR>. |
| <br><br> It returns the length of time as <VAR>interval</VAR>. |
| <br><br> With a Linux kernel, the round robin time slice is always 150 |
| microseconds, and <VAR>pid</VAR> need not even be a real pid. |
| <br><br> The return value is <CODE>0</CODE> on success and in the pathological case |
| that it fails, the return value is <CODE>-1</CODE> and <CODE>errno</CODE> is set |
| accordingly. There is nothing specific that can go wrong with this |
| function, so there are no specific <CODE>errno</CODE> values. |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-sched_yield" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "sched.h"/> |
| </headers> |
| <synopsis> |
| <br><br> This function voluntarily gives up the process' claim on the CPU. |
| <br><br> Technically, <CODE>sched_yield</CODE> causes the calling process to be made |
| immediately ready to run (as opposed to running, which is what it was |
| before). This means that if it has absolute priority higher than 0, it |
| gets pushed onto the tail of the queue of processes that share its |
| absolute priority and are ready to run, and it will run again when its |
| turn next arrives. If its absolute priority is 0, it is more |
| complicated, but still has the effect of yielding the CPU to other |
| processes. |
| <br><br> If there are no other processes that share the calling process' absolute |
| priority, this function doesn't have any effect. |
| <br><br> To the extent that the containing program is oblivious to what other |
| processes in the system are doing and how fast it executes, this |
| function appears as a no-op. |
| <br><br> The return value is <CODE>0</CODE> on success and in the pathological case |
| that it fails, the return value is <CODE>-1</CODE> and <CODE>errno</CODE> is set |
| accordingly. There is nothing specific that can go wrong with this |
| function, so there are no specific <CODE>errno</CODE> values. |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getpriority" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int class"/> |
| <parameter content="int id"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/resource.h"/> |
| </headers> |
| <synopsis> |
| Return the nice value of a set of processes; <VAR>class</VAR> and <VAR>id</VAR> |
| specify which ones (see below). If the processes specified do not all |
| have the same nice value, this returns the lowest value that any of them |
| has. |
| <br><br> On success, the return value is <CODE>0</CODE>. Otherwise, it is <CODE>-1</CODE> |
| and <CODE>ERRNO</CODE> is set accordingly. The <CODE>errno</CODE> values specific |
| to this function are: |
| <br><br> <DL> |
| |
| <DT><CODE>ESRCH</CODE> |
| <DD> |
| The combination of <VAR>class</VAR> and <VAR>id</VAR> does not match any existing |
| process. |
| <br><br> <LI> EINVAL |
| The value of <VAR>class</VAR> is not valid. |
| |
| <br><br> If the return value is <CODE>-1</CODE>, it could indicate failure, or it could |
| be the nice value. The only way to make certain is to set <CODE>errno = |
| 0</CODE> before calling <CODE>getpriority</CODE>, then use <CODE>errno != 0</CODE> |
| afterward as the criterion for failure. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-setpriority" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int class"/> |
| <parameter content="int id"/> |
| <parameter content="int niceval"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/resource.h"/> |
| </headers> |
| <synopsis> |
| Set the nice value of a set of processes to <VAR>niceval</VAR>; <VAR>class</VAR> |
| and <VAR>id</VAR> specify which ones (see below). |
| <br><br> The return value is <CODE>0</CODE> on success, and <CODE>-1</CODE> on |
| failure. The following <CODE>errno</CODE> error condition are possible for |
| this function: |
| <br><br> <DL> |
| |
| <DT><CODE>ESRCH</CODE> |
| <DD> |
| The combination of <VAR>class</VAR> and <VAR>id</VAR> does not match any existing |
| process. |
| <br><br> <LI> EINVAL |
| The value of <VAR>class</VAR> is not valid. |
| <br><br> <LI> EPERM |
| The call would set the nice value of a process which is owned by a different |
| user than the calling process (i.e., the target process' real or effective |
| uid does not match the calling process' effective uid) and the calling |
| process does not have <CODE>CAP_SYS_NICE</CODE> permission. |
| <br><br> <LI> EACCES |
| The call would lower the process' nice value and the process does not have |
| <CODE>CAP_SYS_NICE</CODE> permission. |
| |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-nice" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int increment"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/resource.h"/> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| Increment the nice value of the calling process by <VAR>increment</VAR>. |
| The return value is the new nice value on success, and <CODE>-1</CODE> on |
| failure. In the case of failure, <CODE>errno</CODE> will be set to the |
| same values as for <CODE>setpriority</CODE>. |
| <br><br> <br><br> Here is an equivalent definition of <CODE>nice</CODE>: |
| <br><br> <pre><br> |
| int<br> |
| nice (int increment)<br> |
| {<br> |
| int result, old = getpriority (PRIO_PROCESS, 0);<br> |
| result = setpriority (PRIO_PROCESS, 0, old + increment);<br> |
| if (result != -1)<br> |
| return old + increment;<br> |
| else<br> |
| return -1;<br> |
| }<br> |
| </pre> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="dtype-cpu_set_t" type="dtype"> |
| <structure> |
| </structure> |
| </construct> |
| <construct id="function-sched_getaffinity" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="pid_t pid"/> |
| <parameter content="size_t cpusetsize"/> |
| <parameter content="cpu_set_t *cpuset"/> |
| </prototype> |
| <headers> |
| <header filename = "sched.h"/> |
| </headers> |
| <synopsis> |
| <br><br> This functions stores the CPU affinity mask for the process or thread |
| with the ID <VAR>pid</VAR> in the <VAR>cpusetsize</VAR> bytes long bitmap |
| pointed to by <VAR>cpuset</VAR>. If successful, the function always |
| initializes all bits in the <CODE>cpu_set_t</CODE> object and returns zero. |
| <br><br> If <VAR>pid</VAR> does not correspond to a process or thread on the system |
| the or the function fails for some other reason, it returns <CODE>-1</CODE> |
| and <CODE>errno</CODE> is set to represent the error condition. |
| <br><br> <DL> |
| |
| <DT><CODE>ESRCH</CODE> |
| <DD> |
| No process or thread with the given ID found. |
| <br><br> <LI> EFAULT |
| The pointer <VAR>cpuset</VAR> is does not point to a valid object. |
| |
| <br><br> This function is a GNU extension and is declared in <TT>sched.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-sched_setaffinity" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="pid_t pid"/> |
| <parameter content="size_t cpusetsize"/> |
| <parameter content="const cpu_set_t *cpuset"/> |
| </prototype> |
| <headers> |
| <header filename = "sched.h"/> |
| </headers> |
| <synopsis> |
| <br><br> This function installs the <VAR>cpusetsize</VAR> bytes long affinity mask |
| pointed to by <VAR>cpuset</VAR> for the process or thread with the ID <VAR>pid</VAR>. |
| If successful the function returns zero and the scheduler will in future |
| take the affinity information into account. |
| <br><br> If the function fails it will return <CODE>-1</CODE> and <CODE>errno</CODE> is set |
| to the error code: |
| <br><br> <DL> |
| |
| <DT><CODE>ESRCH</CODE> |
| <DD> |
| No process or thread with the given ID found. |
| <br><br> <LI> EFAULT |
| The pointer <VAR>cpuset</VAR> is does not point to a valid object. |
| <br><br> <LI> EINVAL |
| The bitset is not valid. This might mean that the affinity set might |
| not leave a processor for the process or thread to run on. |
| |
| <br><br> This function is a GNU extension and is declared in <TT>sched.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getpagesize" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>getpagesize</CODE> function returns the page size of the process. |
| This value is fixed for the runtime of the process but can vary in |
| different runs of the application. |
| <br><br> The function is declared in <TT>unistd.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-get_phys_pages" type="function"> |
| <function returntype="long int"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/sysinfo.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>get_phys_pages</CODE> function returns the total number of pages of |
| physical the system has. To get the amount of memory this number has to |
| be multiplied by the page size. |
| <br><br> This function is a GNU extension. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-get_avphys_pages" type="function"> |
| <function returntype="long int"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/sysinfo.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>get_phys_pages</CODE> function returns the number of available pages of |
| physical the system has. To get the amount of memory this number has to |
| be multiplied by the page size. |
| <br><br> This function is a GNU extension. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-get_nprocs_conf" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/sysinfo.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>get_nprocs_conf</CODE> function returns the number of processors the |
| operating system configured. |
| <br><br> This function is a GNU extension. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-get_nprocs" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/sysinfo.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>get_nprocs</CODE> function returns the number of available processors. |
| <br><br> This function is a GNU extension. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getloadavg" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="double loadavg[]"/> |
| <parameter content="int nelem"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| This function gets the 1, 5 and 15 minute load averages of the |
| system. The values are placed in <VAR>loadavg</VAR>. <CODE>getloadavg</CODE> will |
| place at most <VAR>nelem</VAR> elements into the array but never more than |
| three elements. The return value is the number of elements written to |
| <VAR>loadavg</VAR>, or -1 on error. |
| <br><br> This function is declared in <TT>stdlib.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-isatty" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int filedes"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| This function returns <CODE>1</CODE> if <VAR>filedes</VAR> is a file descriptor |
| associated with an open terminal device, and 0 otherwise. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-ttyname" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="int filedes"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| If the file descriptor <VAR>filedes</VAR> is associated with a terminal |
| device, the <CODE>ttyname</CODE> function returns a pointer to a |
| statically-allocated, null-terminated string containing the file name of |
| the terminal file. The value is a null pointer if the file descriptor |
| isn't associated with a terminal, or the file name cannot be determined. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-ttyname_r" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int filedes"/> |
| <parameter content="char *buf"/> |
| <parameter content="size_t len"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>ttyname_r</CODE> function is similar to the <CODE>ttyname</CODE> function |
| except that it places its result into the user-specified buffer starting |
| at <VAR>buf</VAR> with length <VAR>len</VAR>. |
| <br><br> The normal return value from <CODE>ttyname_r</CODE> is 0. Otherwise an |
| error number is returned to indicate the error. The following |
| <CODE>errno</CODE> error conditions are defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EBADF</CODE> |
| <DD> |
| The <VAR>filedes</VAR> argument is not a valid file descriptor. |
| <br><br> <LI> ENOTTY |
| The <VAR>filedes</VAR> is not associated with a terminal. |
| <br><br> <LI> ERANGE |
| The buffer length <VAR>len</VAR> is too small to store the string to be |
| returned. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="struct-termios" type="struct"> |
| <structure> |
| <synopsis> |
| Structure that records all the I/O attributes of a terminal. The |
| structure includes at least the following members: |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="tcflag_t c_iflag"> |
| <synopsis> |
| A bit mask specifying flags for input modes; see Input Modes. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="tcflag_t c_oflag"> |
| <synopsis> |
| A bit mask specifying flags for output modes; see Output Modes. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="tcflag_t c_cflag"> |
| <synopsis> |
| A bit mask specifying flags for control modes; see Control Modes. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="tcflag_t c_lflag"> |
| <synopsis> |
| A bit mask specifying flags for local modes; see Local Modes. |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="dtype-tcflag_t" type="dtype"> |
| <structure> |
| </structure> |
| </construct> |
| <construct id="dtype-cc_t" type="dtype"> |
| <structure> |
| </structure> |
| </construct> |
| <construct id="function-tcgetattr" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int filedes"/> |
| <parameter content="struct termios *termios-p"/> |
| </prototype> |
| <headers> |
| <header filename = "termios.h"/> |
| </headers> |
| <synopsis> |
| This function is used to examine the attributes of the terminal |
| device with file descriptor <VAR>filedes</VAR>. The attributes are returned |
| in the structure that <VAR>termios-p</VAR> points to. |
| <br><br> If successful, <CODE>tcgetattr</CODE> returns 0. A return value of -1 |
| indicates an error. The following <CODE>errno</CODE> error conditions are |
| defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EBADF</CODE> |
| <DD> |
| The <VAR>filedes</VAR> argument is not a valid file descriptor. |
| <br><br> <LI> ENOTTY |
| The <VAR>filedes</VAR> is not associated with a terminal. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-tcsetattr" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int filedes"/> |
| <parameter content="int when"/> |
| <parameter content="const struct termios *termios-p"/> |
| </prototype> |
| <headers> |
| <header filename = "termios.h"/> |
| </headers> |
| <synopsis> |
| This function sets the attributes of the terminal device with file |
| descriptor <VAR>filedes</VAR>. The new attributes are taken from the |
| structure that <VAR>termios-p</VAR> points to. |
| <br><br> The <VAR>when</VAR> argument specifies how to deal with input and output |
| already queued. It can be one of the following values: |
| <br><br> <DL> |
| |
| <DT><CODE>TCSANOW</CODE> |
| <DD> |
| |
| Make the change immediately. |
| <br><br> <DT><CODE>TCSADRAIN</CODE> |
| <DD> |
| |
| Make the change after waiting until all queued output has been written. |
| You should usually use this option when changing parameters that affect |
| output. |
| <br><br> <LI> TCSAFLUSH |
| |
| This is like <CODE>TCSADRAIN</CODE>, but also discards any queued input. |
| <br><br> <LI> TCSASOFT |
| |
| This is a flag bit that you can add to any of the above alternatives. |
| Its meaning is to inhibit alteration of the state of the terminal |
| hardware. It is a BSD extension; it is only supported on BSD systems |
| and the GNU system. |
| <br><br> Using <CODE>TCSASOFT</CODE> is exactly the same as setting the <CODE>CIGNORE</CODE> |
| bit in the <CODE>c_cflag</CODE> member of the structure <VAR>termios-p</VAR> points |
| to. , for a description of <CODE>CIGNORE</CODE>. |
| |
| <br><br> If this function is called from a background process on its controlling |
| terminal, normally all processes in the process group are sent a |
| <CODE>SIGTTOU</CODE> signal, in the same way as if the process were trying to |
| write to the terminal. The exception is if the calling process itself |
| is ignoring or blocking <CODE>SIGTTOU</CODE> signals, in which case the |
| operation is performed and no signal is sent. . |
| <br><br> If successful, <CODE>tcsetattr</CODE> returns 0. A return value of |
| -1 indicates an error. The following <CODE>errno</CODE> error |
| conditions are defined for this function: |
| <br><br> <DL> |
| |
| <LI> EBADF |
| The <VAR>filedes</VAR> argument is not a valid file descriptor. |
| <br><br> <LI> ENOTTY |
| The <VAR>filedes</VAR> is not associated with a terminal. |
| <br><br> <LI> EINVAL |
| Either the value of the <CODE>when</CODE> argument is not valid, or there is |
| something wrong with the data in the <VAR>termios-p</VAR> argument. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-cfgetospeed" type="function"> |
| <function returntype="speed_t"> |
| <prototype> |
| <parameter content="const struct termios *termios-p"/> |
| </prototype> |
| <headers> |
| <header filename = "termios.h"/> |
| </headers> |
| <synopsis> |
| This function returns the output line speed stored in the structure |
| <CODE>*<VAR>termios-p</VAR></CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-cfgetispeed" type="function"> |
| <function returntype="speed_t"> |
| <prototype> |
| <parameter content="const struct termios *termios-p"/> |
| </prototype> |
| <headers> |
| <header filename = "termios.h"/> |
| </headers> |
| <synopsis> |
| This function returns the input line speed stored in the structure |
| <CODE>*<VAR>termios-p</VAR></CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-cfsetospeed" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="struct termios *termios-p"/> |
| <parameter content="speed_t speed"/> |
| </prototype> |
| <headers> |
| <header filename = "termios.h"/> |
| </headers> |
| <synopsis> |
| This function stores <VAR>speed</VAR> in <CODE>*<VAR>termios-p</VAR></CODE> as the output |
| speed. The normal return value is 0; a value of -1 |
| indicates an error. If <VAR>speed</VAR> is not a speed, <CODE>cfsetospeed</CODE> |
| returns -1. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-cfsetispeed" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="struct termios *termios-p"/> |
| <parameter content="speed_t speed"/> |
| </prototype> |
| <headers> |
| <header filename = "termios.h"/> |
| </headers> |
| <synopsis> |
| This function stores <VAR>speed</VAR> in <CODE>*<VAR>termios-p</VAR></CODE> as the input |
| speed. The normal return value is 0; a value of -1 |
| indicates an error. If <VAR>speed</VAR> is not a speed, <CODE>cfsetospeed</CODE> |
| returns -1. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-cfsetspeed" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="struct termios *termios-p"/> |
| <parameter content="speed_t speed"/> |
| </prototype> |
| <headers> |
| <header filename = "termios.h"/> |
| </headers> |
| <synopsis> |
| This function stores <VAR>speed</VAR> in <CODE>*<VAR>termios-p</VAR></CODE> as both the |
| input and output speeds. The normal return value is 0; a value |
| of -1 indicates an error. If <VAR>speed</VAR> is not a speed, |
| <CODE>cfsetspeed</CODE> returns -1. This function is an extension in |
| 4.4 BSD. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="dtype-speed_t" type="dtype"> |
| <structure> |
| </structure> |
| </construct> |
| <construct id="function-cfmakeraw" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="struct termios *termios-p"/> |
| </prototype> |
| <headers> |
| <header filename = "termios.h"/> |
| </headers> |
| <synopsis> |
| This function provides an easy way to set up <CODE>*<VAR>termios-p</VAR></CODE> for |
| what has traditionally been called ``raw mode'' in BSD. This uses |
| noncanonical input, and turns off most processing to give an unmodified |
| channel to the terminal. |
| <br><br> It does exactly this: |
| <pre><br> |
| <VAR>termios-p</VAR>->c_iflag &= ~(IGNBRK|BRKINT|PARMRK|ISTRIP<br> |
| |INLCR|IGNCR|ICRNL|IXON);<br> |
| <VAR>termios-p</VAR>->c_oflag &= ~OPOST;<br> |
| <VAR>termios-p</VAR>->c_lflag &= ~(ECHO|ECHONL|ICANON|ISIG|IEXTEN);<br> |
| <VAR>termios-p</VAR>->c_cflag &= ~(CSIZE|PARENB);<br> |
| <VAR>termios-p</VAR>->c_cflag |= CS8;<br> |
| </pre> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="struct-sgttyb" type="struct"> |
| <structure> |
| <synopsis> |
| This structure is an input or output parameter list for <CODE>gtty</CODE> and |
| <CODE>stty</CODE>. |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="char sg_ispeed"> |
| <synopsis> |
| Line speed for input |
| </synopsis> |
| </element> |
| <element content="char sg_ospeed"> |
| <synopsis> |
| Line speed for output |
| </synopsis> |
| </element> |
| <element content="char sg_erase"> |
| <synopsis> |
| Erase character |
| </synopsis> |
| </element> |
| <element content="char sg_kill"> |
| <synopsis> |
| Kill character |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="function-gtty" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int filedes"/> |
| <parameter content="struct sgttyb *attributes"/> |
| </prototype> |
| <headers> |
| <header filename = "termios.h"/> |
| <header filename = "sgtty.h"/> |
| </headers> |
| <synopsis> |
| This function gets the attributes of a terminal. |
| <br><br> <CODE>gtty</CODE> sets *<VAR>attributes</VAR> to describe the terminal attributes |
| of the terminal which is open with file descriptor <VAR>filedes</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-stty" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int filedes"/> |
| <parameter content="struct sgttyb * attributes"/> |
| </prototype> |
| <headers> |
| <header filename = "sgtty.h"/> |
| </headers> |
| <synopsis> |
| <br><br> This function sets the attributes of a terminal. |
| <br><br> <CODE>stty</CODE> sets the terminal attributes of the terminal which is open with |
| file descriptor <VAR>filedes</VAR> to those described by *<VAR>filedes</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-tcsendbreak" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int filedes"/> |
| <parameter content="int duration"/> |
| </prototype> |
| <headers> |
| <header filename = "termios.h"/> |
| </headers> |
| <synopsis> |
| This function generates a break condition by transmitting a stream of |
| zero bits on the terminal associated with the file descriptor |
| <VAR>filedes</VAR>. The duration of the break is controlled by the |
| <VAR>duration</VAR> argument. If zero, the duration is between 0.25 and 0.5 |
| seconds. The meaning of a nonzero value depends on the operating system. |
| <br><br> This function does nothing if the terminal is not an asynchronous serial |
| data port. |
| <br><br> The return value is normally zero. In the event of an error, a value |
| of -1 is returned. The following <CODE>errno</CODE> error conditions |
| are defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EBADF</CODE> |
| <DD> |
| The <VAR>filedes</VAR> is not a valid file descriptor. |
| <br><br> <LI> ENOTTY |
| The <VAR>filedes</VAR> is not associated with a terminal device. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-tcdrain" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int filedes"/> |
| </prototype> |
| <headers> |
| <header filename = "termios.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>tcdrain</CODE> function waits until all queued |
| output to the terminal <VAR>filedes</VAR> has been transmitted. |
| <br><br> This function is a cancellation point in multi-threaded programs. This |
| is a problem if the thread allocates some resources (like memory, file |
| descriptors, semaphores or whatever) at the time <CODE>tcdrain</CODE> is |
| called. If the thread gets canceled these resources stay allocated |
| until the program ends. To avoid this calls to <CODE>tcdrain</CODE> should be |
| protected using cancellation handlers. |
| <br><br> The return value is normally zero. In the event of an error, a value |
| of -1 is returned. The following <CODE>errno</CODE> error conditions |
| are defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EBADF</CODE> |
| <DD> |
| The <VAR>filedes</VAR> is not a valid file descriptor. |
| <br><br> <LI> ENOTTY |
| The <VAR>filedes</VAR> is not associated with a terminal device. |
| <br><br> <LI> EINTR |
| The operation was interrupted by delivery of a signal. |
| . |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-tcflush" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int filedes"/> |
| <parameter content="int queue"/> |
| </prototype> |
| <headers> |
| <header filename = "termios.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>tcflush</CODE> function is used to clear the input and/or output |
| queues associated with the terminal file <VAR>filedes</VAR>. The <VAR>queue</VAR> |
| argument specifies which queue(s) to clear, and can be one of the |
| following values: |
| <br><br> <DL> |
| |
| |
| <DT><CODE>TCIFLUSH</CODE> |
| <DD> |
| <br><br> Clear any input data received, but not yet read. |
| <br><br> |
| <DT><CODE>TCOFLUSH</CODE> |
| <DD> |
| <br><br> Clear any output data written, but not yet transmitted. |
| <br><br> |
| <LI> TCIOFLUSH |
| <br><br> Clear both queued input and output. |
| |
| <br><br> The return value is normally zero. In the event of an error, a value |
| of -1 is returned. The following <CODE>errno</CODE> error conditions |
| are defined for this function: |
| <br><br> <DL> |
| |
| <LI> EBADF |
| The <VAR>filedes</VAR> is not a valid file descriptor. |
| <br><br> <LI> ENOTTY |
| The <VAR>filedes</VAR> is not associated with a terminal device. |
| <br><br> <LI> EINVAL |
| A bad value was supplied as the <VAR>queue</VAR> argument. |
| |
| <br><br> It is unfortunate that this function is named <CODE>tcflush</CODE>, because |
| the term ``flush'' is normally used for quite another operation---waiting |
| until all output is transmitted---and using it for discarding input or |
| output would be confusing. Unfortunately, the name <CODE>tcflush</CODE> comes |
| from POSIX and we cannot change it. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-tcflow" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int filedes"/> |
| <parameter content="int action"/> |
| </prototype> |
| <headers> |
| <header filename = "termios.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>tcflow</CODE> function is used to perform operations relating to |
| XON/XOFF flow control on the terminal file specified by <VAR>filedes</VAR>. |
| <br><br> The <VAR>action</VAR> argument specifies what operation to perform, and can |
| be one of the following values: |
| <br><br> <DL> |
| |
| |
| <DT><CODE>TCOOFF</CODE> |
| <DD> |
| Suspend transmission of output. |
| <br><br> |
| <DT><CODE>TCOON</CODE> |
| <DD> |
| Restart transmission of output. |
| <br><br> |
| <LI> TCIOFF |
| Transmit a STOP character. |
| <br><br> |
| <LI> TCION |
| Transmit a START character. |
| |
| <br><br> For more information about the STOP and START characters, see Special |
| Characters. |
| <br><br> The return value is normally zero. In the event of an error, a value |
| of -1 is returned. The following <CODE>errno</CODE> error conditions |
| are defined for this function: |
| <br><br> <DL> |
| |
| |
| <LI> EBADF |
| The <VAR>filedes</VAR> is not a valid file descriptor. |
| <br><br> |
| <LI> ENOTTY |
| The <VAR>filedes</VAR> is not associated with a terminal device. |
| <br><br> |
| <LI> EINVAL |
| A bad value was supplied as the <VAR>action</VAR> argument. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getpt" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>getpt</CODE> function returns a new file descriptor for the next |
| available master pseudo-terminal. The normal return value from |
| <CODE>getpt</CODE> is a non-negative integer file descriptor. In the case of |
| an error, a value of -1 is returned instead. The following |
| <CODE>errno</CODE> conditions are defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>ENOENT</CODE> |
| <DD> |
| There are no free master pseudo-terminals available. |
| |
| <br><br> This function is a GNU extension. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-grantpt" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int filedes"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>grantpt</CODE> function changes the ownership and access permission |
| of the slave pseudo-terminal device corresponding to the master |
| pseudo-terminal device associated with the file descriptor |
| <VAR>filedes</VAR>. The owner is set from the real user ID of the calling |
| process , and the group is set to a special |
| group (typically tty) or from the real group ID of the calling |
| process. The access permission is set such that the file is both |
| readable and writable by the owner and only writable by the group. |
| <br><br> On some systems this function is implemented by invoking a special |
| <CODE>setuid</CODE> root program. As a |
| consequence, installing a signal handler for the <CODE>SIGCHLD</CODE> signal |
| may interfere with a call to |
| <CODE>grantpt</CODE>. |
| <br><br> The normal return value from <CODE>grantpt</CODE> is 0; a value of |
| -1 is returned in case of failure. The following <CODE>errno</CODE> |
| error conditions are defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EBADF</CODE> |
| <DD> |
| The <VAR>filedes</VAR> argument is not a valid file descriptor. |
| <br><br> <LI> EINVAL |
| The <VAR>filedes</VAR> argument is not associated with a master pseudo-terminal |
| device. |
| <br><br> <LI> EACCES |
| The slave pseudo-terminal device corresponding to the master associated |
| with <VAR>filedes</VAR> could not be accessed. |
| |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-unlockpt" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int filedes"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>unlockpt</CODE> function unlocks the slave pseudo-terminal device |
| corresponding to the master pseudo-terminal device associated with the |
| file descriptor <VAR>filedes</VAR>. On many systems, the slave can only be |
| opened after unlocking, so portable applications should always call |
| <CODE>unlockpt</CODE> before trying to open the slave. |
| <br><br> The normal return value from <CODE>unlockpt</CODE> is 0; a value of |
| -1 is returned in case of failure. The following <CODE>errno</CODE> |
| error conditions are defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EBADF</CODE> |
| <DD> |
| The <VAR>filedes</VAR> argument is not a valid file descriptor. |
| <br><br> <LI> EINVAL |
| The <VAR>filedes</VAR> argument is not associated with a master pseudo-terminal |
| device. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-ptsname" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="int filedes"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| If the file descriptor <VAR>filedes</VAR> is associated with a |
| master pseudo-terminal device, the <CODE>ptsname</CODE> function returns a |
| pointer to a statically-allocated, null-terminated string containing the |
| file name of the associated slave pseudo-terminal file. This string |
| might be overwritten by subsequent calls to <CODE>ptsname</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-ptsname_r" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int filedes"/> |
| <parameter content="char *buf"/> |
| <parameter content="size_t len"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>ptsname_r</CODE> function is similar to the <CODE>ptsname</CODE> function |
| except that it places its result into the user-specified buffer starting |
| at <VAR>buf</VAR> with length <VAR>len</VAR>. |
| <br><br> This function is a GNU extension. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-openpty" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int *amaster"/> |
| <parameter content="int *aslave"/> |
| <parameter content="char *name"/> |
| <parameter content="const struct termios *termp"/> |
| <parameter content="const struct winsize *winp"/> |
| </prototype> |
| <headers> |
| <header filename = "pty.h"/> |
| </headers> |
| <synopsis> |
| This function allocates and opens a pseudo-terminal pair, returning the |
| file descriptor for the master in <VAR>*amaster</VAR>, and the file |
| descriptor for the slave in <VAR>*aslave</VAR>. If the argument <VAR>name</VAR> |
| is not a null pointer, the file name of the slave pseudo-terminal |
| device is stored in <CODE>*name</CODE>. If <VAR>termp</VAR> is not a null pointer, |
| the terminal attributes of the slave are set to the ones specified in |
| the structure that <VAR>termp</VAR> points to . |
| Likewise, if the <VAR>winp</VAR> is not a null pointer, the screen size of |
| the slave is set to the values specified in the structure that |
| <VAR>winp</VAR> points to. |
| <br><br> The normal return value from <CODE>openpty</CODE> is 0; a value of |
| -1 is returned in case of failure. The following <CODE>errno</CODE> |
| conditions are defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>ENOENT</CODE> |
| <DD> |
| There are no free pseudo-terminal pairs available. |
| |
| <br><br> Warning: Using the <CODE>openpty</CODE> function with <VAR>name</VAR> not |
| set to <CODE>NULL</CODE> is very dangerous because it provides no |
| protection against overflowing the string <VAR>name</VAR>. You should use |
| the <CODE>ttyname</CODE> function on the file descriptor returned in |
| <VAR>*slave</VAR> to find out the file name of the slave pseudo-terminal |
| device instead. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-forkpty" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int *amaster"/> |
| <parameter content="char *name"/> |
| <parameter content="const struct termios *termp"/> |
| <parameter content="const struct winsize *winp"/> |
| </prototype> |
| <headers> |
| <header filename = "pty.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to the <CODE>openpty</CODE> function, but in |
| addition, forks a new process and makes the |
| newly opened slave pseudo-terminal device the controlling terminal |
| for the child process. |
| <br><br> If the operation is successful, there are then both parent and child |
| processes and both see <CODE>forkpty</CODE> return, but with different values: |
| it returns a value of 0 in the child process and returns the child's |
| process ID in the parent process. |
| <br><br> If the allocation of a pseudo-terminal pair or the process creation |
| failed, <CODE>forkpty</CODE> returns a value of -1 in the parent |
| process. |
| <br><br> Warning: The <CODE>forkpty</CODE> function has the same problems with |
| respect to the <VAR>name</VAR> argument as <CODE>openpty</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-openlog" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="const char *ident"/> |
| <parameter content="int option"/> |
| <parameter content="int facility"/> |
| </prototype> |
| <headers> |
| <header filename = "syslog.h"/> |
| </headers> |
| <synopsis> |
| <br><br> <CODE>openlog</CODE> opens or reopens a connection to Syslog in preparation |
| for submitting messages. |
| <br><br> <VAR>ident</VAR> is an arbitrary identification string which future |
| <CODE>syslog</CODE> invocations will prefix to each message. This is intended |
| to identify the source of the message, and people conventionally set it |
| to the name of the program that will submit the messages. |
| <br><br> If <VAR>ident</VAR> is NULL, or if <CODE>openlog</CODE> is not called, the default |
| identification string used in Syslog messages will be the program name, |
| taken from argv[0]. |
| <br><br> Please note that the string pointer <VAR>ident</VAR> will be retained |
| internally by the Syslog routines. You must not free the memory that |
| <VAR>ident</VAR> points to. It is also dangerous to pass a reference to an |
| automatic variable since leaving the scope would mean ending the |
| lifetime of the variable. If you want to change the <VAR>ident</VAR> string, |
| you must call <CODE>openlog</CODE> again; overwriting the string pointed to by |
| <VAR>ident</VAR> is not thread-safe. |
| <br><br> You can cause the Syslog routines to drop the reference to <VAR>ident</VAR> and |
| go back to the default string (the program name taken from argv[0]), by |
| calling <CODE>closelog</CODE>: . |
| <br><br> In particular, if you are writing code for a shared library that might get |
| loaded and then unloaded (e.g. a PAM module), and you use <CODE>openlog</CODE>, |
| you must call <CODE>closelog</CODE> before any point where your library might |
| get unloaded, as in this example: |
| <br><br> <pre><br> |
| #include <syslog.h><br> |
| <br><br> void<br> |
| shared_library_function (void)<br> |
| {<br> |
| openlog ("mylibrary", option, priority);<br> |
| <br><br> syslog (LOG_INFO, "shared library has been invoked");<br> |
| <br><br> closelog ();<br> |
| }<br> |
| </pre> |
| <br><br> Without the call to <CODE>closelog</CODE>, future invocations of <CODE>syslog</CODE> |
| by the program using the shared library may crash, if the library gets |
| unloaded and the memory containing the string <CODE>"mylibrary"</CODE> becomes |
| unmapped. This is a limitation of the BSD syslog interface. |
| <br><br> <CODE>openlog</CODE> may or may not open the <TT>/dev/log</TT> socket, depending |
| on <VAR>option</VAR>. If it does, it tries to open it and connect it as a |
| stream socket. If that doesn't work, it tries to open it and connect it |
| as a datagram socket. The socket has the ``Close on Exec'' attribute, |
| so the kernel will close it if the process performs an exec. |
| <br><br> You don't have to use <CODE>openlog</CODE>. If you call <CODE>syslog</CODE> without |
| having called <CODE>openlog</CODE>, <CODE>syslog</CODE> just opens the connection |
| implicitly and uses defaults for the information in <VAR>ident</VAR> and |
| <VAR>options</VAR>. |
| <br><br> <VAR>options</VAR> is a bit string, with the bits as defined by the following |
| single bit masks: |
| <br><br> <DL> |
| |
| <DT><CODE>LOG_PERROR</CODE> |
| <DD> |
| If on, <CODE>openlog</CODE> sets up the connection so that any <CODE>syslog</CODE> |
| on this connection writes its message to the calling process' Standard |
| Error stream in addition to submitting it to Syslog. If off, <CODE>syslog</CODE> |
| does not write the message to Standard Error. |
| <br><br> <LI> LOG_CONS |
| If on, <CODE>openlog</CODE> sets up the connection so that a <CODE>syslog</CODE> on |
| this connection that fails to submit a message to Syslog writes the |
| message instead to system console. If off, <CODE>syslog</CODE> does not write |
| to the system console (but of course Syslog may write messages it |
| receives to the console). |
| <br><br> <LI> LOG_PID |
| When on, <CODE>openlog</CODE> sets up the connection so that a <CODE>syslog</CODE> |
| on this connection inserts the calling process' Process ID (PID) into |
| the message. When off, <CODE>openlog</CODE> does not insert the PID. |
| <br><br> <LI> LOG_NDELAY |
| When on, <CODE>openlog</CODE> opens and connects the <TT>/dev/log</TT> socket. |
| When off, a future <CODE>syslog</CODE> call must open and connect the socket. |
| <br><br> Portability note: In early systems, the sense of this bit was |
| exactly the opposite. |
| <br><br> <LI> LOG_ODELAY |
| This bit does nothing. It exists for backward compatibility. |
| <br><br> |
| <br><br> If any other bit in <VAR>options</VAR> is on, the result is undefined. |
| <br><br> <VAR>facility</VAR> is the default facility code for this connection. A |
| <CODE>syslog</CODE> on this connection that specifies default facility causes |
| this facility to be associated with the message. See <CODE>syslog</CODE> for |
| possible values. A value of zero means the default default, which is |
| <CODE>LOG_USER</CODE>. |
| <br><br> If a Syslog connection is already open when you call <CODE>openlog</CODE>, |
| <CODE>openlog</CODE> ``reopens'' the connection. Reopening is like opening |
| except that if you specify zero for the default facility code, the |
| default facility code simply remains unchanged and if you specify |
| LOG_NDELAY and the socket is already open and connected, <CODE>openlog</CODE> |
| just leaves it that way. |
| <br><br> <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-syslog" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="int facility_priority"/> |
| <parameter content="char *format"/> |
| <parameter content="..."/> |
| </prototype> |
| <headers> |
| <header filename = "syslog.h"/> |
| </headers> |
| <synopsis> |
| <br><br> <CODE>syslog</CODE> submits a message to the Syslog facility. It does this by |
| writing to the Unix domain socket <CODE>/dev/log</CODE>. |
| <br><br> <CODE>syslog</CODE> submits the message with the facility and priority indicated |
| by <VAR>facility_priority</VAR>. The macro <CODE>LOG_MAKEPRI</CODE> generates a |
| facility/priority from a facility and a priority, as in the following |
| example: |
| <br><br> <pre><br> |
| LOG_MAKEPRI(LOG_USER, LOG_WARNING)<br> |
| </pre><br> |
| <br><br> The possible values for the facility code are (macros):<br> |
| <br><br> <br><br> <DL> |
| <br> |
| <DT><CODE>LOG_USER<br></CODE> |
| <DD> |
| A miscellaneous user process<br> |
| <DT><CODE>LOG_MAIL<br></CODE> |
| <DD> |
| Mail<br> |
| <DT><CODE>LOG_DAEMON<br></CODE> |
| <DD> |
| A miscellaneous system daemon<br> |
| <DT><CODE>LOG_AUTH<br></CODE> |
| <DD> |
| Security (authorization)<br> |
| <DT><CODE>LOG_SYSLOG<br></CODE> |
| <DD> |
| Syslog<br> |
| <DT><CODE>LOG_LPR<br></CODE> |
| <DD> |
| Central printer<br> |
| <DT><CODE>LOG_NEWS<br></CODE> |
| <DD> |
| Network news (e.g. Usenet)<br> |
| <DT><CODE>LOG_UUCP<br></CODE> |
| <DD> |
| UUCP<br> |
| <DT><CODE>LOG_CRON<br></CODE> |
| <DD> |
| Cron and At<br> |
| <DT><CODE>LOG_AUTHPRIV<br></CODE> |
| <DD> |
| Private security (authorization)<br> |
| <DT><CODE>LOG_FTP<br></CODE> |
| <DD> |
| Ftp server<br> |
| <DT><CODE>LOG_LOCAL0<br></CODE> |
| <DD> |
| Locally defined<br> |
| <DT><CODE>LOG_LOCAL1<br></CODE> |
| <DD> |
| Locally defined<br> |
| <DT><CODE>LOG_LOCAL2<br></CODE> |
| <DD> |
| Locally defined<br> |
| <DT><CODE>LOG_LOCAL3<br></CODE> |
| <DD> |
| Locally defined<br> |
| <DT><CODE>LOG_LOCAL4<br></CODE> |
| <DD> |
| Locally defined<br> |
| <DT><CODE>LOG_LOCAL5<br></CODE> |
| <DD> |
| Locally defined<br> |
| <DT><CODE>LOG_LOCAL6<br></CODE> |
| <DD> |
| Locally defined<br> |
| <DT><CODE>LOG_LOCAL7<br></CODE> |
| <DD> |
| Locally defined<br> |
| </DL><br> |
| <br><br> Results are undefined if the facility code is anything else.<br> |
| <br><br> NB: <CODE>syslog</CODE> recognizes one other facility code: that of<br> |
| the kernel. But you can't specify that facility code with these<br> |
| functions. If you try, it looks the same to <CODE>syslog</CODE> as if you are<br> |
| requesting the default facility. But you wouldn't want to anyway,<br> |
| because any program that uses the GNU C library is not the kernel.<br> |
| <br><br> You can use just a priority code as <VAR>facility_priority</VAR>. In that<br> |
| case, <CODE>syslog</CODE> assumes the default facility established when the<br> |
| Syslog connection was opened. .<br> |
| <br><br> The possible values for the priority code are (macros):<br> |
| <br><br> <DL> |
| <br> |
| <DT><CODE>LOG_EMERG<br></CODE> |
| <DD> |
| The message says the system is unusable.<br> |
| <DT><CODE>LOG_ALERT<br></CODE> |
| <DD> |
| Action on the message must be taken immediately.<br> |
| <DT><CODE>LOG_CRIT<br></CODE> |
| <DD> |
| The message states a critical condition.<br> |
| <DT><CODE>LOG_ERR<br></CODE> |
| <DD> |
| The message describes an error.<br> |
| <DT><CODE>LOG_WARNING<br></CODE> |
| <DD> |
| The message is a warning.<br> |
| <DT><CODE>LOG_NOTICE<br></CODE> |
| <DD> |
| The message describes a normal but important event.<br> |
| <DT><CODE>LOG_INFO<br></CODE> |
| <DD> |
| The message is purely informational.<br> |
| <DT><CODE>LOG_DEBUG<br></CODE> |
| <DD> |
| The message is only for debugging purposes.<br> |
| </DL><br> |
| <br><br> Results are undefined if the priority code is anything else.<br> |
| <br><br> If the process does not presently have a Syslog connection open (i.e.,<br> |
| it did not call <CODE>openlog</CODE>), <CODE>syslog</CODE> implicitly opens the<br> |
| connection the same as <CODE>openlog</CODE> would, with the following defaults<br> |
| for information that would otherwise be included in an <CODE>openlog</CODE><br> |
| call: The default identification string is the program name. The<br> |
| default default facility is <CODE>LOG_USER</CODE>. The default for all the<br> |
| connection options in <VAR>options</VAR> is as if those bits were off.<br> |
| <CODE>syslog</CODE> leaves the Syslog connection open.<br> |
| <br><br> If the <TT>dev/log</TT> socket is not open and connected, <CODE>syslog</CODE><br> |
| opens and connects it, the same as <CODE>openlog</CODE> with the<br> |
| <CODE>LOG_NDELAY</CODE> option would.<br> |
| <br><br> <CODE>syslog</CODE> leaves <TT>/dev/log</TT> open and connected unless its attempt<br> |
| to send the message failed, in which case <CODE>syslog</CODE> closes it (with the<br> |
| hope that a future implicit open will restore the Syslog connection to a<br> |
| usable state).<br> |
| <br><br> Example:<br> |
| <br><br> <pre><br> |
| <br><br> #include <syslog.h><br> |
| syslog (LOG_MAKEPRI(LOG_LOCAL1, LOG_ERROR),<br> |
| "Unable to make network connection to %s. Error=%m", host);<br> |
| <br><br> </pre> |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-vsyslog" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="int facility_priority"/> |
| <parameter content="char *format"/> |
| <parameter content="va_list arglist"/> |
| </prototype> |
| <headers> |
| <header filename = "syslog.h"/> |
| </headers> |
| <synopsis> |
| <br><br> This is functionally identical to <CODE>syslog</CODE>, with the BSD style variable |
| length argument. |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-closelog" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "syslog.h"/> |
| </headers> |
| <synopsis> |
| <br><br> <CODE>closelog</CODE> closes the current Syslog connection, if there is one. |
| This includes closing the <TT>dev/log</TT> socket, if it is open. |
| <CODE>closelog</CODE> also sets the identification string for Syslog messages |
| back to the default, if <CODE>openlog</CODE> was called with a non-NULL argument |
| to <VAR>ident</VAR>. The default identification string is the program name |
| taken from argv[0]. |
| <br><br> If you are writing shared library code that uses <CODE>openlog</CODE> to |
| generate custom syslog output, you should use <CODE>closelog</CODE> to drop the |
| GNU C library's internal reference to the <VAR>ident</VAR> pointer when you are |
| done. Please read the section on <CODE>openlog</CODE> for more information: |
| . |
| <br><br> <CODE>closelog</CODE> does not flush any buffers. You do not have to call |
| <CODE>closelog</CODE> before re-opening a Syslog connection with <CODE>initlog</CODE>. |
| Syslog connections are automatically closed on exec or exit. |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-setlogmask" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int mask"/> |
| </prototype> |
| <headers> |
| <header filename = "syslog.h"/> |
| </headers> |
| <synopsis> |
| <br><br> <CODE>setlogmask</CODE> sets a mask (the ``logmask'') that determines which |
| future <CODE>syslog</CODE> calls shall be ignored. If a program has not |
| called <CODE>setlogmask</CODE>, <CODE>syslog</CODE> doesn't ignore any calls. You |
| can use <CODE>setlogmask</CODE> to specify that messages of particular |
| priorities shall be ignored in the future. |
| <br><br> A <CODE>setlogmask</CODE> call overrides any previous <CODE>setlogmask</CODE> call. |
| <br><br> Note that the logmask exists entirely independently of opening and |
| closing of Syslog connections. |
| <br><br> Setting the logmask has a similar effect to, but is not the same as, |
| configuring Syslog. The Syslog configuration may cause Syslog to |
| discard certain messages it receives, but the logmask causes certain |
| messages never to get submitted to Syslog in the first place. |
| <br><br> <VAR>mask</VAR> is a bit string with one bit corresponding to each of the |
| possible message priorities. If the bit is on, <CODE>syslog</CODE> handles |
| messages of that priority normally. If it is off, <CODE>syslog</CODE> |
| discards messages of that priority. Use the message priority macros |
| described in syslog; vsyslog and the <CODE>LOG_MASK</CODE> to construct |
| an appropriate <VAR>mask</VAR> value, as in this example: |
| <br><br> <pre><br> |
| LOG_MASK(LOG_EMERG) | LOG_MASK(LOG_ERROR)<br> |
| </pre><br> |
| <br><br> or<br> |
| <br><br> <pre><br> |
| ~(LOG_MASK(LOG_INFO))<br> |
| </pre><br> |
| <br><br> There is also a <CODE>LOG_UPTO</CODE> macro, which generates a mask with the bits<br> |
| on for a certain priority and all priorities above it:<br> |
| <br><br> <pre><br> |
| LOG_UPTO(LOG_ERROR)<br> |
| </pre> |
| <br><br> The unfortunate naming of the macro is due to the fact that internally, |
| higher numbers are used for lower message priorities. |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getsubopt" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="char **optionp"/> |
| <parameter content="const char* const *tokens"/> |
| <parameter content="char **valuep"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| <br><br> The <VAR>optionp</VAR> parameter must be a pointer to a variable containing |
| the address of the string to process. When the function returns the |
| reference is updated to point to the next suboption or to the |
| terminating <samp>\0</samp> character if there is no more suboption available. |
| <br><br> The <VAR>tokens</VAR> parameter references an array of strings containing the |
| known suboptions. All strings must be <samp>\0</samp> terminated and to mark |
| the end a null pointer must be stored. When <CODE>getsubopt</CODE> finds a |
| possible legal suboption it compares it with all strings available in |
| the <VAR>tokens</VAR> array and returns the index in the string as the |
| indicator. |
| <br><br> In case the suboption has an associated value introduced by a <samp>=</samp> |
| character, a pointer to the value is returned in <VAR>valuep</VAR>. The |
| string is <samp>\0</samp> terminated. If no argument is available |
| <VAR>valuep</VAR> is set to the null pointer. By doing this the caller can |
| check whether a necessary value is given or whether no unexpected value |
| is present. |
| <br><br> In case the next suboption in the string is not mentioned in the |
| <VAR>tokens</VAR> array the starting address of the suboption including a |
| possible value is returned in <VAR>valuep</VAR> and the return value of the |
| function is <samp>-1</samp>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getenv" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="const char *name"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| This function returns a string that is the value of the environment |
| variable <VAR>name</VAR>. You must not modify this string. In some non-Unix |
| systems not using the GNU library, it might be overwritten by subsequent |
| calls to <CODE>getenv</CODE> (but not by any other library function). If the |
| environment variable <VAR>name</VAR> is not defined, the value is a null |
| pointer. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-putenv" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="char *string"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>putenv</CODE> function adds or removes definitions from the environment. |
| If the <VAR>string</VAR> is of the form <samp><VAR>name</VAR>=<VAR>value</VAR></samp>, the |
| definition is added to the environment. Otherwise, the <VAR>string</VAR> is |
| interpreted as the name of an environment variable, and any definition |
| for this variable in the environment is removed. |
| <br><br> The difference to the <CODE>setenv</CODE> function is that the exact string |
| given as the parameter <VAR>string</VAR> is put into the environment. If the |
| user should change the string after the <CODE>putenv</CODE> call this will |
| reflect in automatically in the environment. This also requires that |
| <VAR>string</VAR> is no automatic variable which scope is left before the |
| variable is removed from the environment. The same applies of course to |
| dynamically allocated variables which are freed later. |
| <br><br> This function is part of the extended Unix interface. Since it was also |
| available in old SVID libraries you should define either |
| <VAR>_XOPEN_SOURCE</VAR> or <VAR>_SVID_SOURCE</VAR> before including any header. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-setenv" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *name"/> |
| <parameter content="const char *value"/> |
| <parameter content="int replace"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>setenv</CODE> function can be used to add a new definition to the |
| environment. The entry with the name <VAR>name</VAR> is replaced by the |
| value <samp><VAR>name</VAR>=<VAR>value</VAR></samp>. Please note that this is also true |
| if <VAR>value</VAR> is the empty string. To do this a new string is created |
| and the strings <VAR>name</VAR> and <VAR>value</VAR> are copied. A null pointer |
| for the <VAR>value</VAR> parameter is illegal. If the environment already |
| contains an entry with key <VAR>name</VAR> the <VAR>replace</VAR> parameter |
| controls the action. If replace is zero, nothing happens. Otherwise |
| the old entry is replaced by the new one. |
| <br><br> Please note that you cannot remove an entry completely using this function. |
| <br><br> This function was originally part of the BSD library but is now part of |
| the Unix standard. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-unsetenv" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *name"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| Using this function one can remove an entry completely from the |
| environment. If the environment contains an entry with the key |
| <VAR>name</VAR> this whole entry is removed. A call to this function is |
| equivalent to a call to <CODE>putenv</CODE> when the <VAR>value</VAR> part of the |
| string is empty. |
| <br><br> The function return <CODE>-1</CODE> if <VAR>name</VAR> is a null pointer, points to |
| an empty string, or points to a string containing a <CODE>=</CODE> character. |
| It returns <CODE>0</CODE> if the call succeeded. |
| <br><br> This function was originally part of the BSD library but is now part of |
| the Unix standard. The BSD version had no return value, though. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-clearenv" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>clearenv</CODE> function removes all entries from the environment. |
| Using <CODE>putenv</CODE> and <CODE>setenv</CODE> new entries can be added again |
| later. |
| <br><br> If the function is successful it returns <CODE>0</CODE>. Otherwise the return |
| value is nonzero. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-syscall" type="function"> |
| <function returntype="long int"> |
| <prototype> |
| <parameter content="long int sysno"/> |
| <parameter content="..."/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| <br><br> <CODE>syscall</CODE> performs a generic system call. |
| <br><br> call number |
| <VAR>sysno</VAR> is the system call number. Each kind of system call is |
| identified by a number. Macros for all the possible system call numbers |
| are defined in <TT>sys/syscall.h</TT> |
| <br><br> The remaining arguments are the arguments for the system call, in |
| order, and their meanings depend on the kind of system call. Each kind |
| of system call has a definite number of arguments, from zero to five. |
| If you code more arguments than the system call takes, the extra ones to |
| the right are ignored. |
| <br><br> The return value is the return value from the system call, unless the |
| system call failed. In that case, <CODE>syscall</CODE> returns <CODE>-1</CODE> and |
| sets <CODE>errno</CODE> to an error code that the system call returned. Note |
| that system calls do not return <CODE>-1</CODE> when they succeed. |
| |
| <br><br> If you specify an invalid <VAR>sysno</VAR>, <CODE>syscall</CODE> returns <CODE>-1</CODE> |
| with <CODE>errno</CODE> = <CODE>ENOSYS</CODE>. |
| <br><br> Example: |
| <br><br> <pre><br> |
| <br><br> #include <unistd.h><br> |
| #include <sys/syscall.h><br> |
| #include <errno.h><br> |
| <br><br> <small>...</small><br> |
| <br><br> int rc;<br> |
| <br><br> rc = syscall(SYS_chmod, "/etc/passwd", 0444);<br> |
| <br><br> if (rc == -1)<br> |
| fprintf(stderr, "chmod failed, errno = %d\n", errno);<br> |
| <br><br> </pre><br> |
| <br><br> This, if all the compatibility stars are aligned, is equivalent to the<br> |
| following preferable code:<br> |
| <br><br> <pre><br> |
| <br><br> #include <sys/types.h><br> |
| #include <sys/stat.h><br> |
| #include <errno.h><br> |
| <br><br> <small>...</small><br> |
| <br><br> int rc;<br> |
| <br><br> rc = chmod("/etc/passwd", 0444);<br> |
| if (rc == -1)<br> |
| fprintf(stderr, "chmod failed, errno = %d\n", errno);<br> |
| <br><br> </pre> |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-exit" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="int status"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>exit</CODE> function tells the system that the program is done, which |
| causes it to terminate the process. |
| <br><br> <VAR>status</VAR> is the program's exit status, which becomes part of the |
| process' termination status. This function does not return. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-atexit" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="void (*function) (void)"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>atexit</CODE> function registers the function <VAR>function</VAR> to be |
| called at normal program termination. The <VAR>function</VAR> is called with |
| no arguments. |
| <br><br> The return value from <CODE>atexit</CODE> is zero on success and nonzero if |
| the function cannot be registered. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-on_exit" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="void (*function)(int status"/> |
| <parameter content="void *arg)"/> |
| <parameter content="void *arg"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| This function is a somewhat more powerful variant of <CODE>atexit</CODE>. It |
| accepts two arguments, a function <VAR>function</VAR> and an arbitrary |
| pointer <VAR>arg</VAR>. At normal program termination, the <VAR>function</VAR> is |
| called with two arguments: the <VAR>status</VAR> value passed to <CODE>exit</CODE>, |
| and the <VAR>arg</VAR>. |
| <br><br> This function is included in the GNU C library only for compatibility |
| for SunOS, and may not be supported by other implementations. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-abort" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>abort</CODE> function causes abnormal program termination. This |
| does not execute cleanup functions registered with <CODE>atexit</CODE> or |
| <CODE>on_exit</CODE>. |
| <br><br> This function actually terminates the process by raising a |
| <CODE>SIGABRT</CODE> signal, and your program can include a handler to |
| intercept this signal; see Signal Handling. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-_exit" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="int status"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>_exit</CODE> function is the primitive for causing a process to |
| terminate with status <VAR>status</VAR>. Calling this function does not |
| execute cleanup functions registered with <CODE>atexit</CODE> or |
| <CODE>on_exit</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-_Exit" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="int status"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>_Exit</CODE> function is the ISO C equivalent to <CODE>_exit</CODE>. |
| The ISO C committee members were not sure whether the definitions of |
| <CODE>_exit</CODE> and <CODE>_Exit</CODE> were compatible so they have not used the |
| POSIX name. |
| <br><br> This function was introduced in ISO C99 and is declared in |
| <TT>stdlib.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-sin" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions return the sine of <VAR>x</VAR>, where <VAR>x</VAR> is given in |
| radians. The return value is in the range <CODE>-1</CODE> to <CODE>1</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-sinf" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions return the sine of <VAR>x</VAR>, where <VAR>x</VAR> is given in |
| radians. The return value is in the range <CODE>-1</CODE> to <CODE>1</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-sinl" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions return the sine of <VAR>x</VAR>, where <VAR>x</VAR> is given in |
| radians. The return value is in the range <CODE>-1</CODE> to <CODE>1</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-cos" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions return the cosine of <VAR>x</VAR>, where <VAR>x</VAR> is given in |
| radians. The return value is in the range <CODE>-1</CODE> to <CODE>1</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-cosf" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions return the cosine of <VAR>x</VAR>, where <VAR>x</VAR> is given in |
| radians. The return value is in the range <CODE>-1</CODE> to <CODE>1</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-cosl" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions return the cosine of <VAR>x</VAR>, where <VAR>x</VAR> is given in |
| radians. The return value is in the range <CODE>-1</CODE> to <CODE>1</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-tan" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions return the tangent of <VAR>x</VAR>, where <VAR>x</VAR> is given in |
| radians. |
| <br><br> Mathematically, the tangent function has singularities at odd multiples |
| of pi/2. If the argument <VAR>x</VAR> is too close to one of these |
| singularities, <CODE>tan</CODE> will signal overflow. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-tanf" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions return the tangent of <VAR>x</VAR>, where <VAR>x</VAR> is given in |
| radians. |
| <br><br> Mathematically, the tangent function has singularities at odd multiples |
| of pi/2. If the argument <VAR>x</VAR> is too close to one of these |
| singularities, <CODE>tan</CODE> will signal overflow. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-tanl" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions return the tangent of <VAR>x</VAR>, where <VAR>x</VAR> is given in |
| radians. |
| <br><br> Mathematically, the tangent function has singularities at odd multiples |
| of pi/2. If the argument <VAR>x</VAR> is too close to one of these |
| singularities, <CODE>tan</CODE> will signal overflow. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-sincos" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="double x"/> |
| <parameter content="double *sinx"/> |
| <parameter content="double *cosx"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions return the sine of <VAR>x</VAR> in <CODE>*<VAR>sinx</VAR></CODE> and the |
| cosine of <VAR>x</VAR> in <CODE>*<VAR>cos</VAR></CODE>, where <VAR>x</VAR> is given in |
| radians. Both values, <CODE>*<VAR>sinx</VAR></CODE> and <CODE>*<VAR>cosx</VAR></CODE>, are in |
| the range of <CODE>-1</CODE> to <CODE>1</CODE>. |
| <br><br> This function is a GNU extension. Portable programs should be prepared |
| to cope with its absence. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-sincosf" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="float x"/> |
| <parameter content="float *sinx"/> |
| <parameter content="float *cosx"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions return the sine of <VAR>x</VAR> in <CODE>*<VAR>sinx</VAR></CODE> and the |
| cosine of <VAR>x</VAR> in <CODE>*<VAR>cos</VAR></CODE>, where <VAR>x</VAR> is given in |
| radians. Both values, <CODE>*<VAR>sinx</VAR></CODE> and <CODE>*<VAR>cosx</VAR></CODE>, are in |
| the range of <CODE>-1</CODE> to <CODE>1</CODE>. |
| <br><br> This function is a GNU extension. Portable programs should be prepared |
| to cope with its absence. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-sincosl" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="long double x"/> |
| <parameter content="long double *sinx"/> |
| <parameter content="long double *cosx"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions return the sine of <VAR>x</VAR> in <CODE>*<VAR>sinx</VAR></CODE> and the |
| cosine of <VAR>x</VAR> in <CODE>*<VAR>cos</VAR></CODE>, where <VAR>x</VAR> is given in |
| radians. Both values, <CODE>*<VAR>sinx</VAR></CODE> and <CODE>*<VAR>cosx</VAR></CODE>, are in |
| the range of <CODE>-1</CODE> to <CODE>1</CODE>. |
| <br><br> This function is a GNU extension. Portable programs should be prepared |
| to cope with its absence. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-csin" type="function"> |
| <function returntype="complex double"> |
| <prototype> |
| <parameter content="complex double z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return the complex sine of <VAR>z</VAR>. |
| The mathematical definition of the complex sine is |
| <br><br> |
| sin (z) = 1/(2*i) * (exp (z*i) - exp (-z*i)). |
| |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-csinf" type="function"> |
| <function returntype="complex float"> |
| <prototype> |
| <parameter content="complex float z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return the complex sine of <VAR>z</VAR>. |
| The mathematical definition of the complex sine is |
| <br><br> |
| sin (z) = 1/(2*i) * (exp (z*i) - exp (-z*i)). |
| |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-csinl" type="function"> |
| <function returntype="complex long double"> |
| <prototype> |
| <parameter content="complex long double z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return the complex sine of <VAR>z</VAR>. |
| The mathematical definition of the complex sine is |
| <br><br> |
| sin (z) = 1/(2*i) * (exp (z*i) - exp (-z*i)). |
| |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-ccos" type="function"> |
| <function returntype="complex double"> |
| <prototype> |
| <parameter content="complex double z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return the complex cosine of <VAR>z</VAR>. |
| The mathematical definition of the complex cosine is |
| <br><br> |
| cos (z) = 1/2 * (exp (z*i) + exp (-z*i)) |
| |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-ccosf" type="function"> |
| <function returntype="complex float"> |
| <prototype> |
| <parameter content="complex float z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return the complex cosine of <VAR>z</VAR>. |
| The mathematical definition of the complex cosine is |
| <br><br> |
| cos (z) = 1/2 * (exp (z*i) + exp (-z*i)) |
| |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-ccosl" type="function"> |
| <function returntype="complex long double"> |
| <prototype> |
| <parameter content="complex long double z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return the complex cosine of <VAR>z</VAR>. |
| The mathematical definition of the complex cosine is |
| <br><br> |
| cos (z) = 1/2 * (exp (z*i) + exp (-z*i)) |
| |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-ctan" type="function"> |
| <function returntype="complex double"> |
| <prototype> |
| <parameter content="complex double z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return the complex tangent of <VAR>z</VAR>. |
| The mathematical definition of the complex tangent is |
| <br><br> |
| tan (z) = -i * (exp (z*i) - exp (-z*i)) / (exp (z*i) + exp (-z*i)) |
| |
| |
| <br><br> |
| The complex tangent has poles at pi/2 + 2n, where n is an |
| integer. <CODE>ctan</CODE> may signal overflow if <VAR>z</VAR> is too close to a |
| pole. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-ctanf" type="function"> |
| <function returntype="complex float"> |
| <prototype> |
| <parameter content="complex float z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return the complex tangent of <VAR>z</VAR>. |
| The mathematical definition of the complex tangent is |
| <br><br> |
| tan (z) = -i * (exp (z*i) - exp (-z*i)) / (exp (z*i) + exp (-z*i)) |
| |
| |
| <br><br> |
| The complex tangent has poles at pi/2 + 2n, where n is an |
| integer. <CODE>ctan</CODE> may signal overflow if <VAR>z</VAR> is too close to a |
| pole. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-ctanl" type="function"> |
| <function returntype="complex long double"> |
| <prototype> |
| <parameter content="complex long double z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return the complex tangent of <VAR>z</VAR>. |
| The mathematical definition of the complex tangent is |
| <br><br> |
| tan (z) = -i * (exp (z*i) - exp (-z*i)) / (exp (z*i) + exp (-z*i)) |
| |
| |
| <br><br> |
| The complex tangent has poles at pi/2 + 2n, where n is an |
| integer. <CODE>ctan</CODE> may signal overflow if <VAR>z</VAR> is too close to a |
| pole. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-asin" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions compute the arc sine of <VAR>x</VAR>---that is, the value whose |
| sine is <VAR>x</VAR>. The value is in units of radians. Mathematically, |
| there are infinitely many such values; the one actually returned is the |
| one between <CODE>-pi/2</CODE> and <CODE>pi/2</CODE> (inclusive). |
| <br><br> The arc sine function is defined mathematically only |
| over the domain <CODE>-1</CODE> to <CODE>1</CODE>. If <VAR>x</VAR> is outside the |
| domain, <CODE>asin</CODE> signals a domain error. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-asinf" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions compute the arc sine of <VAR>x</VAR>---that is, the value whose |
| sine is <VAR>x</VAR>. The value is in units of radians. Mathematically, |
| there are infinitely many such values; the one actually returned is the |
| one between <CODE>-pi/2</CODE> and <CODE>pi/2</CODE> (inclusive). |
| <br><br> The arc sine function is defined mathematically only |
| over the domain <CODE>-1</CODE> to <CODE>1</CODE>. If <VAR>x</VAR> is outside the |
| domain, <CODE>asin</CODE> signals a domain error. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-asinl" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions compute the arc sine of <VAR>x</VAR>---that is, the value whose |
| sine is <VAR>x</VAR>. The value is in units of radians. Mathematically, |
| there are infinitely many such values; the one actually returned is the |
| one between <CODE>-pi/2</CODE> and <CODE>pi/2</CODE> (inclusive). |
| <br><br> The arc sine function is defined mathematically only |
| over the domain <CODE>-1</CODE> to <CODE>1</CODE>. If <VAR>x</VAR> is outside the |
| domain, <CODE>asin</CODE> signals a domain error. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-acos" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions compute the arc cosine of <VAR>x</VAR>---that is, the value |
| whose cosine is <VAR>x</VAR>. The value is in units of radians. |
| Mathematically, there are infinitely many such values; the one actually |
| returned is the one between <CODE>0</CODE> and <CODE>pi</CODE> (inclusive). |
| <br><br> The arc cosine function is defined mathematically only |
| over the domain <CODE>-1</CODE> to <CODE>1</CODE>. If <VAR>x</VAR> is outside the |
| domain, <CODE>acos</CODE> signals a domain error. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-acosf" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions compute the arc cosine of <VAR>x</VAR>---that is, the value |
| whose cosine is <VAR>x</VAR>. The value is in units of radians. |
| Mathematically, there are infinitely many such values; the one actually |
| returned is the one between <CODE>0</CODE> and <CODE>pi</CODE> (inclusive). |
| <br><br> The arc cosine function is defined mathematically only |
| over the domain <CODE>-1</CODE> to <CODE>1</CODE>. If <VAR>x</VAR> is outside the |
| domain, <CODE>acos</CODE> signals a domain error. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-acosl" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions compute the arc cosine of <VAR>x</VAR>---that is, the value |
| whose cosine is <VAR>x</VAR>. The value is in units of radians. |
| Mathematically, there are infinitely many such values; the one actually |
| returned is the one between <CODE>0</CODE> and <CODE>pi</CODE> (inclusive). |
| <br><br> The arc cosine function is defined mathematically only |
| over the domain <CODE>-1</CODE> to <CODE>1</CODE>. If <VAR>x</VAR> is outside the |
| domain, <CODE>acos</CODE> signals a domain error. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-atan" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions compute the arc tangent of <VAR>x</VAR>---that is, the value |
| whose tangent is <VAR>x</VAR>. The value is in units of radians. |
| Mathematically, there are infinitely many such values; the one actually |
| returned is the one between <CODE>-pi/2</CODE> and <CODE>pi/2</CODE> (inclusive). |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-atanf" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions compute the arc tangent of <VAR>x</VAR>---that is, the value |
| whose tangent is <VAR>x</VAR>. The value is in units of radians. |
| Mathematically, there are infinitely many such values; the one actually |
| returned is the one between <CODE>-pi/2</CODE> and <CODE>pi/2</CODE> (inclusive). |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-atanl" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions compute the arc tangent of <VAR>x</VAR>---that is, the value |
| whose tangent is <VAR>x</VAR>. The value is in units of radians. |
| Mathematically, there are infinitely many such values; the one actually |
| returned is the one between <CODE>-pi/2</CODE> and <CODE>pi/2</CODE> (inclusive). |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-atan2" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double y"/> |
| <parameter content="double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| This function computes the arc tangent of <VAR>y</VAR>/<VAR>x</VAR>, but the signs |
| of both arguments are used to determine the quadrant of the result, and |
| <VAR>x</VAR> is permitted to be zero. The return value is given in radians |
| and is in the range <CODE>-pi</CODE> to <CODE>pi</CODE>, inclusive. |
| <br><br> If <VAR>x</VAR> and <VAR>y</VAR> are coordinates of a point in the plane, |
| <CODE>atan2</CODE> returns the signed angle between the line from the origin |
| to that point and the x-axis. Thus, <CODE>atan2</CODE> is useful for |
| converting Cartesian coordinates to polar coordinates. (To compute the |
| radial coordinate, use <CODE>hypot</CODE>; see Exponents and |
| Logarithms.) |
| <br><br> If both <VAR>x</VAR> and <VAR>y</VAR> are zero, <CODE>atan2</CODE> returns zero. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-atan2f" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float y"/> |
| <parameter content="float x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| This function computes the arc tangent of <VAR>y</VAR>/<VAR>x</VAR>, but the signs |
| of both arguments are used to determine the quadrant of the result, and |
| <VAR>x</VAR> is permitted to be zero. The return value is given in radians |
| and is in the range <CODE>-pi</CODE> to <CODE>pi</CODE>, inclusive. |
| <br><br> If <VAR>x</VAR> and <VAR>y</VAR> are coordinates of a point in the plane, |
| <CODE>atan2</CODE> returns the signed angle between the line from the origin |
| to that point and the x-axis. Thus, <CODE>atan2</CODE> is useful for |
| converting Cartesian coordinates to polar coordinates. (To compute the |
| radial coordinate, use <CODE>hypot</CODE>; see Exponents and |
| Logarithms.) |
| <br><br> If both <VAR>x</VAR> and <VAR>y</VAR> are zero, <CODE>atan2</CODE> returns zero. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-atan2l" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double y"/> |
| <parameter content="long double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| This function computes the arc tangent of <VAR>y</VAR>/<VAR>x</VAR>, but the signs |
| of both arguments are used to determine the quadrant of the result, and |
| <VAR>x</VAR> is permitted to be zero. The return value is given in radians |
| and is in the range <CODE>-pi</CODE> to <CODE>pi</CODE>, inclusive. |
| <br><br> If <VAR>x</VAR> and <VAR>y</VAR> are coordinates of a point in the plane, |
| <CODE>atan2</CODE> returns the signed angle between the line from the origin |
| to that point and the x-axis. Thus, <CODE>atan2</CODE> is useful for |
| converting Cartesian coordinates to polar coordinates. (To compute the |
| radial coordinate, use <CODE>hypot</CODE>; see Exponents and |
| Logarithms.) |
| <br><br> If both <VAR>x</VAR> and <VAR>y</VAR> are zero, <CODE>atan2</CODE> returns zero. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-casin" type="function"> |
| <function returntype="complex double"> |
| <prototype> |
| <parameter content="complex double z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions compute the complex arc sine of <VAR>z</VAR>---that is, the |
| value whose sine is <VAR>z</VAR>. The value returned is in radians. |
| <br><br> Unlike the real-valued functions, <CODE>casin</CODE> is defined for all |
| values of <VAR>z</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-casinf" type="function"> |
| <function returntype="complex float"> |
| <prototype> |
| <parameter content="complex float z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions compute the complex arc sine of <VAR>z</VAR>---that is, the |
| value whose sine is <VAR>z</VAR>. The value returned is in radians. |
| <br><br> Unlike the real-valued functions, <CODE>casin</CODE> is defined for all |
| values of <VAR>z</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-casinl" type="function"> |
| <function returntype="complex long double"> |
| <prototype> |
| <parameter content="complex long double z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions compute the complex arc sine of <VAR>z</VAR>---that is, the |
| value whose sine is <VAR>z</VAR>. The value returned is in radians. |
| <br><br> Unlike the real-valued functions, <CODE>casin</CODE> is defined for all |
| values of <VAR>z</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-cacos" type="function"> |
| <function returntype="complex double"> |
| <prototype> |
| <parameter content="complex double z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions compute the complex arc cosine of <VAR>z</VAR>---that is, the |
| value whose cosine is <VAR>z</VAR>. The value returned is in radians. |
| <br><br> Unlike the real-valued functions, <CODE>cacos</CODE> is defined for all |
| values of <VAR>z</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-cacosf" type="function"> |
| <function returntype="complex float"> |
| <prototype> |
| <parameter content="complex float z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions compute the complex arc cosine of <VAR>z</VAR>---that is, the |
| value whose cosine is <VAR>z</VAR>. The value returned is in radians. |
| <br><br> Unlike the real-valued functions, <CODE>cacos</CODE> is defined for all |
| values of <VAR>z</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-cacosl" type="function"> |
| <function returntype="complex long double"> |
| <prototype> |
| <parameter content="complex long double z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions compute the complex arc cosine of <VAR>z</VAR>---that is, the |
| value whose cosine is <VAR>z</VAR>. The value returned is in radians. |
| <br><br> Unlike the real-valued functions, <CODE>cacos</CODE> is defined for all |
| values of <VAR>z</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-catan" type="function"> |
| <function returntype="complex double"> |
| <prototype> |
| <parameter content="complex double z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions compute the complex arc tangent of <VAR>z</VAR>---that is, |
| the value whose tangent is <VAR>z</VAR>. The value is in units of radians. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-catanf" type="function"> |
| <function returntype="complex float"> |
| <prototype> |
| <parameter content="complex float z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions compute the complex arc tangent of <VAR>z</VAR>---that is, |
| the value whose tangent is <VAR>z</VAR>. The value is in units of radians. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-catanl" type="function"> |
| <function returntype="complex long double"> |
| <prototype> |
| <parameter content="complex long double z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions compute the complex arc tangent of <VAR>z</VAR>---that is, |
| the value whose tangent is <VAR>z</VAR>. The value is in units of radians. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-exp" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions compute <CODE>e</CODE> (the base of natural logarithms) raised |
| to the power <VAR>x</VAR>. |
| <br><br> If the magnitude of the result is too large to be representable, |
| <CODE>exp</CODE> signals overflow. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-expf" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions compute <CODE>e</CODE> (the base of natural logarithms) raised |
| to the power <VAR>x</VAR>. |
| <br><br> If the magnitude of the result is too large to be representable, |
| <CODE>exp</CODE> signals overflow. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-expl" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions compute <CODE>e</CODE> (the base of natural logarithms) raised |
| to the power <VAR>x</VAR>. |
| <br><br> If the magnitude of the result is too large to be representable, |
| <CODE>exp</CODE> signals overflow. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-exp2" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions compute <CODE>2</CODE> raised to the power <VAR>x</VAR>. |
| Mathematically, <CODE>exp2 (x)</CODE> is the same as <CODE>exp (x * log (2))</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-exp2f" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions compute <CODE>2</CODE> raised to the power <VAR>x</VAR>. |
| Mathematically, <CODE>exp2 (x)</CODE> is the same as <CODE>exp (x * log (2))</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-exp2l" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions compute <CODE>2</CODE> raised to the power <VAR>x</VAR>. |
| Mathematically, <CODE>exp2 (x)</CODE> is the same as <CODE>exp (x * log (2))</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-exp10" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions compute <CODE>10</CODE> raised to the power <VAR>x</VAR>. |
| Mathematically, <CODE>exp10 (x)</CODE> is the same as <CODE>exp (x * log (10))</CODE>. |
| <br><br> These functions are GNU extensions. The name <CODE>exp10</CODE> is |
| preferred, since it is analogous to <CODE>exp</CODE> and <CODE>exp2</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-exp10f" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions compute <CODE>10</CODE> raised to the power <VAR>x</VAR>. |
| Mathematically, <CODE>exp10 (x)</CODE> is the same as <CODE>exp (x * log (10))</CODE>. |
| <br><br> These functions are GNU extensions. The name <CODE>exp10</CODE> is |
| preferred, since it is analogous to <CODE>exp</CODE> and <CODE>exp2</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-exp10l" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions compute <CODE>10</CODE> raised to the power <VAR>x</VAR>. |
| Mathematically, <CODE>exp10 (x)</CODE> is the same as <CODE>exp (x * log (10))</CODE>. |
| <br><br> These functions are GNU extensions. The name <CODE>exp10</CODE> is |
| preferred, since it is analogous to <CODE>exp</CODE> and <CODE>exp2</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-pow10" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions compute <CODE>10</CODE> raised to the power <VAR>x</VAR>. |
| Mathematically, <CODE>exp10 (x)</CODE> is the same as <CODE>exp (x * log (10))</CODE>. |
| <br><br> These functions are GNU extensions. The name <CODE>exp10</CODE> is |
| preferred, since it is analogous to <CODE>exp</CODE> and <CODE>exp2</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-pow10f" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions compute <CODE>10</CODE> raised to the power <VAR>x</VAR>. |
| Mathematically, <CODE>exp10 (x)</CODE> is the same as <CODE>exp (x * log (10))</CODE>. |
| <br><br> These functions are GNU extensions. The name <CODE>exp10</CODE> is |
| preferred, since it is analogous to <CODE>exp</CODE> and <CODE>exp2</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-pow10l" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions compute <CODE>10</CODE> raised to the power <VAR>x</VAR>. |
| Mathematically, <CODE>exp10 (x)</CODE> is the same as <CODE>exp (x * log (10))</CODE>. |
| <br><br> These functions are GNU extensions. The name <CODE>exp10</CODE> is |
| preferred, since it is analogous to <CODE>exp</CODE> and <CODE>exp2</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-log" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions compute the natural logarithm of <VAR>x</VAR>. <CODE>exp (log |
| (<VAR>x</VAR>))</CODE> equals <VAR>x</VAR>, exactly in mathematics and approximately in |
| C. |
| <br><br> If <VAR>x</VAR> is negative, <CODE>log</CODE> signals a domain error. If <VAR>x</VAR> |
| is zero, it returns negative infinity; if <VAR>x</VAR> is too close to zero, |
| it may signal overflow. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-logf" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions compute the natural logarithm of <VAR>x</VAR>. <CODE>exp (log |
| (<VAR>x</VAR>))</CODE> equals <VAR>x</VAR>, exactly in mathematics and approximately in |
| C. |
| <br><br> If <VAR>x</VAR> is negative, <CODE>log</CODE> signals a domain error. If <VAR>x</VAR> |
| is zero, it returns negative infinity; if <VAR>x</VAR> is too close to zero, |
| it may signal overflow. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-logl" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions compute the natural logarithm of <VAR>x</VAR>. <CODE>exp (log |
| (<VAR>x</VAR>))</CODE> equals <VAR>x</VAR>, exactly in mathematics and approximately in |
| C. |
| <br><br> If <VAR>x</VAR> is negative, <CODE>log</CODE> signals a domain error. If <VAR>x</VAR> |
| is zero, it returns negative infinity; if <VAR>x</VAR> is too close to zero, |
| it may signal overflow. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-log10" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions return the base-10 logarithm of <VAR>x</VAR>. |
| <CODE>log10 (<VAR>x</VAR>)</CODE> equals <CODE>log (<VAR>x</VAR>) / log (10)</CODE>. |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-log10f" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions return the base-10 logarithm of <VAR>x</VAR>. |
| <CODE>log10 (<VAR>x</VAR>)</CODE> equals <CODE>log (<VAR>x</VAR>) / log (10)</CODE>. |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-log10l" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions return the base-10 logarithm of <VAR>x</VAR>. |
| <CODE>log10 (<VAR>x</VAR>)</CODE> equals <CODE>log (<VAR>x</VAR>) / log (10)</CODE>. |
| <br><br> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-log2" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions return the base-2 logarithm of <VAR>x</VAR>. |
| <CODE>log2 (<VAR>x</VAR>)</CODE> equals <CODE>log (<VAR>x</VAR>) / log (2)</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-log2f" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions return the base-2 logarithm of <VAR>x</VAR>. |
| <CODE>log2 (<VAR>x</VAR>)</CODE> equals <CODE>log (<VAR>x</VAR>) / log (2)</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-log2l" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions return the base-2 logarithm of <VAR>x</VAR>. |
| <CODE>log2 (<VAR>x</VAR>)</CODE> equals <CODE>log (<VAR>x</VAR>) / log (2)</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-logb" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions extract the exponent of <VAR>x</VAR> and return it as a |
| floating-point value. If <CODE>FLT_RADIX</CODE> is two, <CODE>logb</CODE> is equal |
| to <CODE>floor (log2 (x))</CODE>, except it's probably faster. |
| <br><br> If <VAR>x</VAR> is de-normalized, <CODE>logb</CODE> returns the exponent <VAR>x</VAR> |
| would have if it were normalized. If <VAR>x</VAR> is infinity (positive or |
| negative), <CODE>logb</CODE> returns infinity{}. If <VAR>x</VAR> is zero, |
| <CODE>logb</CODE> returns infinity{}. It does not signal. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-logbf" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions extract the exponent of <VAR>x</VAR> and return it as a |
| floating-point value. If <CODE>FLT_RADIX</CODE> is two, <CODE>logb</CODE> is equal |
| to <CODE>floor (log2 (x))</CODE>, except it's probably faster. |
| <br><br> If <VAR>x</VAR> is de-normalized, <CODE>logb</CODE> returns the exponent <VAR>x</VAR> |
| would have if it were normalized. If <VAR>x</VAR> is infinity (positive or |
| negative), <CODE>logb</CODE> returns infinity{}. If <VAR>x</VAR> is zero, |
| <CODE>logb</CODE> returns infinity{}. It does not signal. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-logbl" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions extract the exponent of <VAR>x</VAR> and return it as a |
| floating-point value. If <CODE>FLT_RADIX</CODE> is two, <CODE>logb</CODE> is equal |
| to <CODE>floor (log2 (x))</CODE>, except it's probably faster. |
| <br><br> If <VAR>x</VAR> is de-normalized, <CODE>logb</CODE> returns the exponent <VAR>x</VAR> |
| would have if it were normalized. If <VAR>x</VAR> is infinity (positive or |
| negative), <CODE>logb</CODE> returns infinity{}. If <VAR>x</VAR> is zero, |
| <CODE>logb</CODE> returns infinity{}. It does not signal. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-ilogb" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions are equivalent to the corresponding <CODE>logb</CODE> |
| functions except that they return signed integer values. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-ilogbf" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="float x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions are equivalent to the corresponding <CODE>logb</CODE> |
| functions except that they return signed integer values. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-ilogbl" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="long double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions are equivalent to the corresponding <CODE>logb</CODE> |
| functions except that they return signed integer values. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-pow" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double base"/> |
| <parameter content="double power"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These are general exponentiation functions, returning <VAR>base</VAR> raised |
| to <VAR>power</VAR>. |
| <br><br> Mathematically, <CODE>pow</CODE> would return a complex number when <VAR>base</VAR> |
| is negative and <VAR>power</VAR> is not an integral value. <CODE>pow</CODE> can't |
| do that, so instead it signals a domain error. <CODE>pow</CODE> may also |
| underflow or overflow the destination type. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-powf" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float base"/> |
| <parameter content="float power"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These are general exponentiation functions, returning <VAR>base</VAR> raised |
| to <VAR>power</VAR>. |
| <br><br> Mathematically, <CODE>pow</CODE> would return a complex number when <VAR>base</VAR> |
| is negative and <VAR>power</VAR> is not an integral value. <CODE>pow</CODE> can't |
| do that, so instead it signals a domain error. <CODE>pow</CODE> may also |
| underflow or overflow the destination type. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-powl" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double base"/> |
| <parameter content="long double power"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These are general exponentiation functions, returning <VAR>base</VAR> raised |
| to <VAR>power</VAR>. |
| <br><br> Mathematically, <CODE>pow</CODE> would return a complex number when <VAR>base</VAR> |
| is negative and <VAR>power</VAR> is not an integral value. <CODE>pow</CODE> can't |
| do that, so instead it signals a domain error. <CODE>pow</CODE> may also |
| underflow or overflow the destination type. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-sqrt" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions return the nonnegative square root of <VAR>x</VAR>. |
| <br><br> If <VAR>x</VAR> is negative, <CODE>sqrt</CODE> signals a domain error. |
| Mathematically, it should return a complex number. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-sqrtf" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions return the nonnegative square root of <VAR>x</VAR>. |
| <br><br> If <VAR>x</VAR> is negative, <CODE>sqrt</CODE> signals a domain error. |
| Mathematically, it should return a complex number. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-sqrtl" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions return the nonnegative square root of <VAR>x</VAR>. |
| <br><br> If <VAR>x</VAR> is negative, <CODE>sqrt</CODE> signals a domain error. |
| Mathematically, it should return a complex number. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-cbrt" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions return the cube root of <VAR>x</VAR>. They cannot |
| fail; every representable real value has a representable real cube root. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-cbrtf" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions return the cube root of <VAR>x</VAR>. They cannot |
| fail; every representable real value has a representable real cube root. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-cbrtl" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions return the cube root of <VAR>x</VAR>. They cannot |
| fail; every representable real value has a representable real cube root. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-hypot" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double x"/> |
| <parameter content="double y"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions return <CODE>sqrt (<VAR>x</VAR>*<VAR>x</VAR> + |
| <VAR>y</VAR>*<VAR>y</VAR>)</CODE>. This is the length of the hypotenuse of a right |
| triangle with sides of length <VAR>x</VAR> and <VAR>y</VAR>, or the distance |
| of the point (<VAR>x</VAR>, <VAR>y</VAR>) from the origin. Using this function |
| instead of the direct formula is wise, since the error is |
| much smaller. See also the function <CODE>cabs</CODE> in Absolute Value. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-hypotf" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float x"/> |
| <parameter content="float y"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions return <CODE>sqrt (<VAR>x</VAR>*<VAR>x</VAR> + |
| <VAR>y</VAR>*<VAR>y</VAR>)</CODE>. This is the length of the hypotenuse of a right |
| triangle with sides of length <VAR>x</VAR> and <VAR>y</VAR>, or the distance |
| of the point (<VAR>x</VAR>, <VAR>y</VAR>) from the origin. Using this function |
| instead of the direct formula is wise, since the error is |
| much smaller. See also the function <CODE>cabs</CODE> in Absolute Value. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-hypotl" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double x"/> |
| <parameter content="long double y"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions return <CODE>sqrt (<VAR>x</VAR>*<VAR>x</VAR> + |
| <VAR>y</VAR>*<VAR>y</VAR>)</CODE>. This is the length of the hypotenuse of a right |
| triangle with sides of length <VAR>x</VAR> and <VAR>y</VAR>, or the distance |
| of the point (<VAR>x</VAR>, <VAR>y</VAR>) from the origin. Using this function |
| instead of the direct formula is wise, since the error is |
| much smaller. See also the function <CODE>cabs</CODE> in Absolute Value. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-expm1" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions return a value equivalent to <CODE>exp (<VAR>x</VAR>) - 1</CODE>. |
| They are computed in a way that is accurate even if <VAR>x</VAR> is |
| near zero---a case where <CODE>exp (<VAR>x</VAR>) - 1</CODE> would be inaccurate owing |
| to subtraction of two numbers that are nearly equal. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-expm1f" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions return a value equivalent to <CODE>exp (<VAR>x</VAR>) - 1</CODE>. |
| They are computed in a way that is accurate even if <VAR>x</VAR> is |
| near zero---a case where <CODE>exp (<VAR>x</VAR>) - 1</CODE> would be inaccurate owing |
| to subtraction of two numbers that are nearly equal. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-expm1l" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions return a value equivalent to <CODE>exp (<VAR>x</VAR>) - 1</CODE>. |
| They are computed in a way that is accurate even if <VAR>x</VAR> is |
| near zero---a case where <CODE>exp (<VAR>x</VAR>) - 1</CODE> would be inaccurate owing |
| to subtraction of two numbers that are nearly equal. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-log1p" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions returns a value equivalent to <CODE>log (1 + <VAR>x</VAR>)</CODE>. |
| They are computed in a way that is accurate even if <VAR>x</VAR> is |
| near zero. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-log1pf" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions returns a value equivalent to <CODE>log (1 + <VAR>x</VAR>)</CODE>. |
| They are computed in a way that is accurate even if <VAR>x</VAR> is |
| near zero. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-log1pl" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions returns a value equivalent to <CODE>log (1 + <VAR>x</VAR>)</CODE>. |
| They are computed in a way that is accurate even if <VAR>x</VAR> is |
| near zero. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-cexp" type="function"> |
| <function returntype="complex double"> |
| <prototype> |
| <parameter content="complex double z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return <CODE>e</CODE> (the base of natural |
| logarithms) raised to the power of <VAR>z</VAR>. |
| Mathematically, this corresponds to the value |
| <br><br> |
| exp (z) = exp (creal (z)) * (cos (cimag (z)) + I * sin (cimag (z))) |
| |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-cexpf" type="function"> |
| <function returntype="complex float"> |
| <prototype> |
| <parameter content="complex float z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return <CODE>e</CODE> (the base of natural |
| logarithms) raised to the power of <VAR>z</VAR>. |
| Mathematically, this corresponds to the value |
| <br><br> |
| exp (z) = exp (creal (z)) * (cos (cimag (z)) + I * sin (cimag (z))) |
| |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-cexpl" type="function"> |
| <function returntype="complex long double"> |
| <prototype> |
| <parameter content="complex long double z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return <CODE>e</CODE> (the base of natural |
| logarithms) raised to the power of <VAR>z</VAR>. |
| Mathematically, this corresponds to the value |
| <br><br> |
| exp (z) = exp (creal (z)) * (cos (cimag (z)) + I * sin (cimag (z))) |
| |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-clog" type="function"> |
| <function returntype="complex double"> |
| <prototype> |
| <parameter content="complex double z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return the natural logarithm of <VAR>z</VAR>. |
| Mathematically, this corresponds to the value |
| <br><br> |
| log (z) = log (cabs (z)) + I * carg (z) |
| |
| |
| <br><br> |
| <CODE>clog</CODE> has a pole at 0, and will signal overflow if <VAR>z</VAR> equals |
| or is very close to 0. It is well-defined for all other values of |
| <VAR>z</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-clogf" type="function"> |
| <function returntype="complex float"> |
| <prototype> |
| <parameter content="complex float z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return the natural logarithm of <VAR>z</VAR>. |
| Mathematically, this corresponds to the value |
| <br><br> |
| log (z) = log (cabs (z)) + I * carg (z) |
| |
| |
| <br><br> |
| <CODE>clog</CODE> has a pole at 0, and will signal overflow if <VAR>z</VAR> equals |
| or is very close to 0. It is well-defined for all other values of |
| <VAR>z</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-clogl" type="function"> |
| <function returntype="complex long double"> |
| <prototype> |
| <parameter content="complex long double z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return the natural logarithm of <VAR>z</VAR>. |
| Mathematically, this corresponds to the value |
| <br><br> |
| log (z) = log (cabs (z)) + I * carg (z) |
| |
| |
| <br><br> |
| <CODE>clog</CODE> has a pole at 0, and will signal overflow if <VAR>z</VAR> equals |
| or is very close to 0. It is well-defined for all other values of |
| <VAR>z</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-clog10" type="function"> |
| <function returntype="complex double"> |
| <prototype> |
| <parameter content="complex double z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return the base 10 logarithm of the complex value |
| <VAR>z</VAR>. Mathematically, this corresponds to the value |
| <br><br> |
| log (z) = log10 (cabs (z)) + I * carg (z) |
| |
| |
| <br><br> These functions are GNU extensions. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-clog10f" type="function"> |
| <function returntype="complex float"> |
| <prototype> |
| <parameter content="complex float z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return the base 10 logarithm of the complex value |
| <VAR>z</VAR>. Mathematically, this corresponds to the value |
| <br><br> |
| log (z) = log10 (cabs (z)) + I * carg (z) |
| |
| |
| <br><br> These functions are GNU extensions. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-clog10l" type="function"> |
| <function returntype="complex long double"> |
| <prototype> |
| <parameter content="complex long double z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return the base 10 logarithm of the complex value |
| <VAR>z</VAR>. Mathematically, this corresponds to the value |
| <br><br> |
| log (z) = log10 (cabs (z)) + I * carg (z) |
| |
| |
| <br><br> These functions are GNU extensions. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-csqrt" type="function"> |
| <function returntype="complex double"> |
| <prototype> |
| <parameter content="complex double z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return the complex square root of the argument <VAR>z</VAR>. Unlike |
| the real-valued functions, they are defined for all values of <VAR>z</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-csqrtf" type="function"> |
| <function returntype="complex float"> |
| <prototype> |
| <parameter content="complex float z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return the complex square root of the argument <VAR>z</VAR>. Unlike |
| the real-valued functions, they are defined for all values of <VAR>z</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-csqrtl" type="function"> |
| <function returntype="complex long double"> |
| <prototype> |
| <parameter content="complex long double z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return the complex square root of the argument <VAR>z</VAR>. Unlike |
| the real-valued functions, they are defined for all values of <VAR>z</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-cpow" type="function"> |
| <function returntype="complex double"> |
| <prototype> |
| <parameter content="complex double base"/> |
| <parameter content="complex double power"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return <VAR>base</VAR> raised to the power of |
| <VAR>power</VAR>. This is equivalent to <CODE>cexp (y * clog (x))</CODE> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-cpowf" type="function"> |
| <function returntype="complex float"> |
| <prototype> |
| <parameter content="complex float base"/> |
| <parameter content="complex float power"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return <VAR>base</VAR> raised to the power of |
| <VAR>power</VAR>. This is equivalent to <CODE>cexp (y * clog (x))</CODE> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-cpowl" type="function"> |
| <function returntype="complex long double"> |
| <prototype> |
| <parameter content="complex long double base"/> |
| <parameter content="complex long double power"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return <VAR>base</VAR> raised to the power of |
| <VAR>power</VAR>. This is equivalent to <CODE>cexp (y * clog (x))</CODE> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-sinh" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions return the hyperbolic sine of <VAR>x</VAR>, defined |
| mathematically as <CODE>(exp (<VAR>x</VAR>) - exp (-<VAR>x</VAR>)) / 2</CODE>. They |
| may signal overflow if <VAR>x</VAR> is too large. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-sinhf" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions return the hyperbolic sine of <VAR>x</VAR>, defined |
| mathematically as <CODE>(exp (<VAR>x</VAR>) - exp (-<VAR>x</VAR>)) / 2</CODE>. They |
| may signal overflow if <VAR>x</VAR> is too large. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-sinhl" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions return the hyperbolic sine of <VAR>x</VAR>, defined |
| mathematically as <CODE>(exp (<VAR>x</VAR>) - exp (-<VAR>x</VAR>)) / 2</CODE>. They |
| may signal overflow if <VAR>x</VAR> is too large. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-cosh" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These function return the hyperbolic cosine of <VAR>x</VAR>, |
| defined mathematically as <CODE>(exp (<VAR>x</VAR>) + exp (-<VAR>x</VAR>)) / 2</CODE>. |
| They may signal overflow if <VAR>x</VAR> is too large. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-coshf" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These function return the hyperbolic cosine of <VAR>x</VAR>, |
| defined mathematically as <CODE>(exp (<VAR>x</VAR>) + exp (-<VAR>x</VAR>)) / 2</CODE>. |
| They may signal overflow if <VAR>x</VAR> is too large. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-coshl" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These function return the hyperbolic cosine of <VAR>x</VAR>, |
| defined mathematically as <CODE>(exp (<VAR>x</VAR>) + exp (-<VAR>x</VAR>)) / 2</CODE>. |
| They may signal overflow if <VAR>x</VAR> is too large. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-tanh" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions return the hyperbolic tangent of <VAR>x</VAR>, |
| defined mathematically as <CODE>sinh (<VAR>x</VAR>) / cosh (<VAR>x</VAR>)</CODE>. |
| They may signal overflow if <VAR>x</VAR> is too large. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-tanhf" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions return the hyperbolic tangent of <VAR>x</VAR>, |
| defined mathematically as <CODE>sinh (<VAR>x</VAR>) / cosh (<VAR>x</VAR>)</CODE>. |
| They may signal overflow if <VAR>x</VAR> is too large. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-tanhl" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions return the hyperbolic tangent of <VAR>x</VAR>, |
| defined mathematically as <CODE>sinh (<VAR>x</VAR>) / cosh (<VAR>x</VAR>)</CODE>. |
| They may signal overflow if <VAR>x</VAR> is too large. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-csinh" type="function"> |
| <function returntype="complex double"> |
| <prototype> |
| <parameter content="complex double z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return the complex hyperbolic sine of <VAR>z</VAR>, defined |
| mathematically as <CODE>(exp (<VAR>z</VAR>) - exp (-<VAR>z</VAR>)) / 2</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-csinhf" type="function"> |
| <function returntype="complex float"> |
| <prototype> |
| <parameter content="complex float z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return the complex hyperbolic sine of <VAR>z</VAR>, defined |
| mathematically as <CODE>(exp (<VAR>z</VAR>) - exp (-<VAR>z</VAR>)) / 2</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-csinhl" type="function"> |
| <function returntype="complex long double"> |
| <prototype> |
| <parameter content="complex long double z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return the complex hyperbolic sine of <VAR>z</VAR>, defined |
| mathematically as <CODE>(exp (<VAR>z</VAR>) - exp (-<VAR>z</VAR>)) / 2</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-ccosh" type="function"> |
| <function returntype="complex double"> |
| <prototype> |
| <parameter content="complex double z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return the complex hyperbolic cosine of <VAR>z</VAR>, defined |
| mathematically as <CODE>(exp (<VAR>z</VAR>) + exp (-<VAR>z</VAR>)) / 2</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-ccoshf" type="function"> |
| <function returntype="complex float"> |
| <prototype> |
| <parameter content="complex float z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return the complex hyperbolic cosine of <VAR>z</VAR>, defined |
| mathematically as <CODE>(exp (<VAR>z</VAR>) + exp (-<VAR>z</VAR>)) / 2</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-ccoshl" type="function"> |
| <function returntype="complex long double"> |
| <prototype> |
| <parameter content="complex long double z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return the complex hyperbolic cosine of <VAR>z</VAR>, defined |
| mathematically as <CODE>(exp (<VAR>z</VAR>) + exp (-<VAR>z</VAR>)) / 2</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-ctanh" type="function"> |
| <function returntype="complex double"> |
| <prototype> |
| <parameter content="complex double z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return the complex hyperbolic tangent of <VAR>z</VAR>, |
| defined mathematically as <CODE>csinh (<VAR>z</VAR>) / ccosh (<VAR>z</VAR>)</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-ctanhf" type="function"> |
| <function returntype="complex float"> |
| <prototype> |
| <parameter content="complex float z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return the complex hyperbolic tangent of <VAR>z</VAR>, |
| defined mathematically as <CODE>csinh (<VAR>z</VAR>) / ccosh (<VAR>z</VAR>)</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-ctanhl" type="function"> |
| <function returntype="complex long double"> |
| <prototype> |
| <parameter content="complex long double z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return the complex hyperbolic tangent of <VAR>z</VAR>, |
| defined mathematically as <CODE>csinh (<VAR>z</VAR>) / ccosh (<VAR>z</VAR>)</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-asinh" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions return the inverse hyperbolic sine of <VAR>x</VAR>---the |
| value whose hyperbolic sine is <VAR>x</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-asinhf" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions return the inverse hyperbolic sine of <VAR>x</VAR>---the |
| value whose hyperbolic sine is <VAR>x</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-asinhl" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions return the inverse hyperbolic sine of <VAR>x</VAR>---the |
| value whose hyperbolic sine is <VAR>x</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-acosh" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions return the inverse hyperbolic cosine of <VAR>x</VAR>---the |
| value whose hyperbolic cosine is <VAR>x</VAR>. If <VAR>x</VAR> is less than |
| <CODE>1</CODE>, <CODE>acosh</CODE> signals a domain error. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-acoshf" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions return the inverse hyperbolic cosine of <VAR>x</VAR>---the |
| value whose hyperbolic cosine is <VAR>x</VAR>. If <VAR>x</VAR> is less than |
| <CODE>1</CODE>, <CODE>acosh</CODE> signals a domain error. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-acoshl" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions return the inverse hyperbolic cosine of <VAR>x</VAR>---the |
| value whose hyperbolic cosine is <VAR>x</VAR>. If <VAR>x</VAR> is less than |
| <CODE>1</CODE>, <CODE>acosh</CODE> signals a domain error. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-atanh" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions return the inverse hyperbolic tangent of <VAR>x</VAR>---the |
| value whose hyperbolic tangent is <VAR>x</VAR>. If the absolute value of |
| <VAR>x</VAR> is greater than <CODE>1</CODE>, <CODE>atanh</CODE> signals a domain error; |
| if it is equal to 1, <CODE>atanh</CODE> returns infinity. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-atanhf" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions return the inverse hyperbolic tangent of <VAR>x</VAR>---the |
| value whose hyperbolic tangent is <VAR>x</VAR>. If the absolute value of |
| <VAR>x</VAR> is greater than <CODE>1</CODE>, <CODE>atanh</CODE> signals a domain error; |
| if it is equal to 1, <CODE>atanh</CODE> returns infinity. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-atanhl" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions return the inverse hyperbolic tangent of <VAR>x</VAR>---the |
| value whose hyperbolic tangent is <VAR>x</VAR>. If the absolute value of |
| <VAR>x</VAR> is greater than <CODE>1</CODE>, <CODE>atanh</CODE> signals a domain error; |
| if it is equal to 1, <CODE>atanh</CODE> returns infinity. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-casinh" type="function"> |
| <function returntype="complex double"> |
| <prototype> |
| <parameter content="complex double z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return the inverse complex hyperbolic sine of |
| <VAR>z</VAR>---the value whose complex hyperbolic sine is <VAR>z</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-casinhf" type="function"> |
| <function returntype="complex float"> |
| <prototype> |
| <parameter content="complex float z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return the inverse complex hyperbolic sine of |
| <VAR>z</VAR>---the value whose complex hyperbolic sine is <VAR>z</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-casinhl" type="function"> |
| <function returntype="complex long double"> |
| <prototype> |
| <parameter content="complex long double z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return the inverse complex hyperbolic sine of |
| <VAR>z</VAR>---the value whose complex hyperbolic sine is <VAR>z</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-cacosh" type="function"> |
| <function returntype="complex double"> |
| <prototype> |
| <parameter content="complex double z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return the inverse complex hyperbolic cosine of |
| <VAR>z</VAR>---the value whose complex hyperbolic cosine is <VAR>z</VAR>. Unlike |
| the real-valued functions, there are no restrictions on the value of <VAR>z</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-cacoshf" type="function"> |
| <function returntype="complex float"> |
| <prototype> |
| <parameter content="complex float z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return the inverse complex hyperbolic cosine of |
| <VAR>z</VAR>---the value whose complex hyperbolic cosine is <VAR>z</VAR>. Unlike |
| the real-valued functions, there are no restrictions on the value of <VAR>z</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-cacoshl" type="function"> |
| <function returntype="complex long double"> |
| <prototype> |
| <parameter content="complex long double z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return the inverse complex hyperbolic cosine of |
| <VAR>z</VAR>---the value whose complex hyperbolic cosine is <VAR>z</VAR>. Unlike |
| the real-valued functions, there are no restrictions on the value of <VAR>z</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-catanh" type="function"> |
| <function returntype="complex double"> |
| <prototype> |
| <parameter content="complex double z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return the inverse complex hyperbolic tangent of |
| <VAR>z</VAR>---the value whose complex hyperbolic tangent is <VAR>z</VAR>. Unlike |
| the real-valued functions, there are no restrictions on the value of |
| <VAR>z</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-catanhf" type="function"> |
| <function returntype="complex float"> |
| <prototype> |
| <parameter content="complex float z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return the inverse complex hyperbolic tangent of |
| <VAR>z</VAR>---the value whose complex hyperbolic tangent is <VAR>z</VAR>. Unlike |
| the real-valued functions, there are no restrictions on the value of |
| <VAR>z</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-catanhl" type="function"> |
| <function returntype="complex long double"> |
| <prototype> |
| <parameter content="complex long double z"/> |
| </prototype> |
| <headers> |
| <header filename = "complex.h"/> |
| </headers> |
| <synopsis> |
| These functions return the inverse complex hyperbolic tangent of |
| <VAR>z</VAR>---the value whose complex hyperbolic tangent is <VAR>z</VAR>. Unlike |
| the real-valued functions, there are no restrictions on the value of |
| <VAR>z</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-erf" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| <CODE>erf</CODE> returns the error function of <VAR>x</VAR>. The error |
| function is defined as |
| |
| |
| <pre><br> |
| erf (x) = 2/sqrt(pi) * integral from 0 to x of exp(-t^2) dt<br> |
| </pre> |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-erff" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| <CODE>erf</CODE> returns the error function of <VAR>x</VAR>. The error |
| function is defined as |
| |
| |
| <pre><br> |
| erf (x) = 2/sqrt(pi) * integral from 0 to x of exp(-t^2) dt<br> |
| </pre> |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-erfl" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| <CODE>erf</CODE> returns the error function of <VAR>x</VAR>. The error |
| function is defined as |
| |
| |
| <pre><br> |
| erf (x) = 2/sqrt(pi) * integral from 0 to x of exp(-t^2) dt<br> |
| </pre> |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-erfc" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| <CODE>erfc</CODE> returns <CODE>1.0 - erf(<VAR>x</VAR>)</CODE>, but computed in a |
| fashion that avoids round-off error when <VAR>x</VAR> is large. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-erfcf" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| <CODE>erfc</CODE> returns <CODE>1.0 - erf(<VAR>x</VAR>)</CODE>, but computed in a |
| fashion that avoids round-off error when <VAR>x</VAR> is large. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-erfcl" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| <CODE>erfc</CODE> returns <CODE>1.0 - erf(<VAR>x</VAR>)</CODE>, but computed in a |
| fashion that avoids round-off error when <VAR>x</VAR> is large. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-lgamma" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| <CODE>lgamma</CODE> returns the natural logarithm of the absolute value of |
| the gamma function of <VAR>x</VAR>. The gamma function is defined as |
| |
| |
| <pre><br> |
| gamma (x) = integral from 0 to infinity{} of t^(x-1) e^-t dt<br> |
| </pre><br> |
| <br> |
| <br><br> <br> |
| The sign of the gamma function is stored in the global variable<br> |
| <VAR>signgam</VAR>, which is declared in <TT>math.h</TT>. It is <CODE>1</CODE> if<br> |
| the intermediate result was positive or zero, or <CODE>-1</CODE> if it was<br> |
| negative.<br> |
| <br><br> To compute the real gamma function you can use the <CODE>tgamma</CODE><br> |
| function or you can compute the values as follows:<br> |
| <pre><br> |
| lgam = lgamma(x);<br> |
| gam = signgam*exp(lgam);<br> |
| </pre> |
| <br><br> The gamma function has singularities at the non-positive integers. |
| <CODE>lgamma</CODE> will raise the zero divide exception if evaluated at a |
| singularity. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-lgammaf" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| <CODE>lgamma</CODE> returns the natural logarithm of the absolute value of |
| the gamma function of <VAR>x</VAR>. The gamma function is defined as |
| |
| |
| <pre><br> |
| gamma (x) = integral from 0 to infinity{} of t^(x-1) e^-t dt<br> |
| </pre><br> |
| <br> |
| <br><br> <br> |
| The sign of the gamma function is stored in the global variable<br> |
| <VAR>signgam</VAR>, which is declared in <TT>math.h</TT>. It is <CODE>1</CODE> if<br> |
| the intermediate result was positive or zero, or <CODE>-1</CODE> if it was<br> |
| negative.<br> |
| <br><br> To compute the real gamma function you can use the <CODE>tgamma</CODE><br> |
| function or you can compute the values as follows:<br> |
| <pre><br> |
| lgam = lgamma(x);<br> |
| gam = signgam*exp(lgam);<br> |
| </pre> |
| <br><br> The gamma function has singularities at the non-positive integers. |
| <CODE>lgamma</CODE> will raise the zero divide exception if evaluated at a |
| singularity. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-lgammal" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| <CODE>lgamma</CODE> returns the natural logarithm of the absolute value of |
| the gamma function of <VAR>x</VAR>. The gamma function is defined as |
| |
| |
| <pre><br> |
| gamma (x) = integral from 0 to infinity{} of t^(x-1) e^-t dt<br> |
| </pre><br> |
| <br> |
| <br><br> <br> |
| The sign of the gamma function is stored in the global variable<br> |
| <VAR>signgam</VAR>, which is declared in <TT>math.h</TT>. It is <CODE>1</CODE> if<br> |
| the intermediate result was positive or zero, or <CODE>-1</CODE> if it was<br> |
| negative.<br> |
| <br><br> To compute the real gamma function you can use the <CODE>tgamma</CODE><br> |
| function or you can compute the values as follows:<br> |
| <pre><br> |
| lgam = lgamma(x);<br> |
| gam = signgam*exp(lgam);<br> |
| </pre> |
| <br><br> The gamma function has singularities at the non-positive integers. |
| <CODE>lgamma</CODE> will raise the zero divide exception if evaluated at a |
| singularity. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-lgamma_r" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double x"/> |
| <parameter content="int *signp"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| <CODE>lgamma_r</CODE> is just like <CODE>lgamma</CODE>, but it stores the sign of |
| the intermediate result in the variable pointed to by <VAR>signp</VAR> |
| instead of in the <VAR>signgam</VAR> global. This means it is reentrant. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-lgammaf_r" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float x"/> |
| <parameter content="int *signp"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| <CODE>lgamma_r</CODE> is just like <CODE>lgamma</CODE>, but it stores the sign of |
| the intermediate result in the variable pointed to by <VAR>signp</VAR> |
| instead of in the <VAR>signgam</VAR> global. This means it is reentrant. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-lgammal_r" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double x"/> |
| <parameter content="int *signp"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| <CODE>lgamma_r</CODE> is just like <CODE>lgamma</CODE>, but it stores the sign of |
| the intermediate result in the variable pointed to by <VAR>signp</VAR> |
| instead of in the <VAR>signgam</VAR> global. This means it is reentrant. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-gamma" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions exist for compatibility reasons. They are equivalent to |
| <CODE>lgamma</CODE> etc. It is better to use <CODE>lgamma</CODE> since for one the |
| name reflects better the actual computation, moreover <CODE>lgamma</CODE> is |
| standardized in ISO C99 while <CODE>gamma</CODE> is not. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-gammaf" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions exist for compatibility reasons. They are equivalent to |
| <CODE>lgamma</CODE> etc. It is better to use <CODE>lgamma</CODE> since for one the |
| name reflects better the actual computation, moreover <CODE>lgamma</CODE> is |
| standardized in ISO C99 while <CODE>gamma</CODE> is not. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-gammal" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| These functions exist for compatibility reasons. They are equivalent to |
| <CODE>lgamma</CODE> etc. It is better to use <CODE>lgamma</CODE> since for one the |
| name reflects better the actual computation, moreover <CODE>lgamma</CODE> is |
| standardized in ISO C99 while <CODE>gamma</CODE> is not. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-tgamma" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| <CODE>tgamma</CODE> applies the gamma function to <VAR>x</VAR>. The gamma |
| function is defined as |
| |
| |
| <pre><br> |
| gamma (x) = integral from 0 to infinity{} of t^(x-1) e^-t dt<br> |
| </pre> |
| |
| <br><br> This function was introduced in ISO C99. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-tgammaf" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| <CODE>tgamma</CODE> applies the gamma function to <VAR>x</VAR>. The gamma |
| function is defined as |
| |
| |
| <pre><br> |
| gamma (x) = integral from 0 to infinity{} of t^(x-1) e^-t dt<br> |
| </pre> |
| |
| <br><br> This function was introduced in ISO C99. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-tgammal" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| <CODE>tgamma</CODE> applies the gamma function to <VAR>x</VAR>. The gamma |
| function is defined as |
| |
| |
| <pre><br> |
| gamma (x) = integral from 0 to infinity{} of t^(x-1) e^-t dt<br> |
| </pre> |
| |
| <br><br> This function was introduced in ISO C99. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-j0" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| <CODE>j0</CODE> returns the Bessel function of the first kind of order 0 of |
| <VAR>x</VAR>. It may signal underflow if <VAR>x</VAR> is too large. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-j0f" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| <CODE>j0</CODE> returns the Bessel function of the first kind of order 0 of |
| <VAR>x</VAR>. It may signal underflow if <VAR>x</VAR> is too large. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-j0l" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| <CODE>j0</CODE> returns the Bessel function of the first kind of order 0 of |
| <VAR>x</VAR>. It may signal underflow if <VAR>x</VAR> is too large. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-j1" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| <CODE>j1</CODE> returns the Bessel function of the first kind of order 1 of |
| <VAR>x</VAR>. It may signal underflow if <VAR>x</VAR> is too large. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-j1f" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| <CODE>j1</CODE> returns the Bessel function of the first kind of order 1 of |
| <VAR>x</VAR>. It may signal underflow if <VAR>x</VAR> is too large. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-j1l" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| <CODE>j1</CODE> returns the Bessel function of the first kind of order 1 of |
| <VAR>x</VAR>. It may signal underflow if <VAR>x</VAR> is too large. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-jn" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="int n"/> |
| <parameter content="double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| <CODE>jn</CODE> returns the Bessel function of the first kind of order |
| <VAR>n</VAR> of <VAR>x</VAR>. It may signal underflow if <VAR>x</VAR> is too large. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-jnf" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="int n"/> |
| <parameter content="float x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| <CODE>jn</CODE> returns the Bessel function of the first kind of order |
| <VAR>n</VAR> of <VAR>x</VAR>. It may signal underflow if <VAR>x</VAR> is too large. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-jnl" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="int n"/> |
| <parameter content="long double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| <CODE>jn</CODE> returns the Bessel function of the first kind of order |
| <VAR>n</VAR> of <VAR>x</VAR>. It may signal underflow if <VAR>x</VAR> is too large. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-y0" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| <CODE>y0</CODE> returns the Bessel function of the second kind of order 0 of |
| <VAR>x</VAR>. It may signal underflow if <VAR>x</VAR> is too large. If <VAR>x</VAR> |
| is negative, <CODE>y0</CODE> signals a domain error; if it is zero, |
| <CODE>y0</CODE> signals overflow and returns -infinity. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-y0f" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| <CODE>y0</CODE> returns the Bessel function of the second kind of order 0 of |
| <VAR>x</VAR>. It may signal underflow if <VAR>x</VAR> is too large. If <VAR>x</VAR> |
| is negative, <CODE>y0</CODE> signals a domain error; if it is zero, |
| <CODE>y0</CODE> signals overflow and returns -infinity. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-y0l" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| <CODE>y0</CODE> returns the Bessel function of the second kind of order 0 of |
| <VAR>x</VAR>. It may signal underflow if <VAR>x</VAR> is too large. If <VAR>x</VAR> |
| is negative, <CODE>y0</CODE> signals a domain error; if it is zero, |
| <CODE>y0</CODE> signals overflow and returns -infinity. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-y1" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| <CODE>y1</CODE> returns the Bessel function of the second kind of order 1 of |
| <VAR>x</VAR>. It may signal underflow if <VAR>x</VAR> is too large. If <VAR>x</VAR> |
| is negative, <CODE>y1</CODE> signals a domain error; if it is zero, |
| <CODE>y1</CODE> signals overflow and returns -infinity. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-y1f" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="float x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| <CODE>y1</CODE> returns the Bessel function of the second kind of order 1 of |
| <VAR>x</VAR>. It may signal underflow if <VAR>x</VAR> is too large. If <VAR>x</VAR> |
| is negative, <CODE>y1</CODE> signals a domain error; if it is zero, |
| <CODE>y1</CODE> signals overflow and returns -infinity. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-y1l" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="long double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| <CODE>y1</CODE> returns the Bessel function of the second kind of order 1 of |
| <VAR>x</VAR>. It may signal underflow if <VAR>x</VAR> is too large. If <VAR>x</VAR> |
| is negative, <CODE>y1</CODE> signals a domain error; if it is zero, |
| <CODE>y1</CODE> signals overflow and returns -infinity. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-yn" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="int n"/> |
| <parameter content="double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| <CODE>yn</CODE> returns the Bessel function of the second kind of order <VAR>n</VAR> of |
| <VAR>x</VAR>. It may signal underflow if <VAR>x</VAR> is too large. If <VAR>x</VAR> |
| is negative, <CODE>yn</CODE> signals a domain error; if it is zero, |
| <CODE>yn</CODE> signals overflow and returns -infinity. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-ynf" type="function"> |
| <function returntype="float"> |
| <prototype> |
| <parameter content="int n"/> |
| <parameter content="float x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| <CODE>yn</CODE> returns the Bessel function of the second kind of order <VAR>n</VAR> of |
| <VAR>x</VAR>. It may signal underflow if <VAR>x</VAR> is too large. If <VAR>x</VAR> |
| is negative, <CODE>yn</CODE> signals a domain error; if it is zero, |
| <CODE>yn</CODE> signals overflow and returns -infinity. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-ynl" type="function"> |
| <function returntype="long double"> |
| <prototype> |
| <parameter content="int n"/> |
| <parameter content="long double x"/> |
| </prototype> |
| <headers> |
| <header filename = "math.h"/> |
| </headers> |
| <synopsis> |
| <CODE>yn</CODE> returns the Bessel function of the second kind of order <VAR>n</VAR> of |
| <VAR>x</VAR>. It may signal underflow if <VAR>x</VAR> is too large. If <VAR>x</VAR> |
| is negative, <CODE>yn</CODE> signals a domain error; if it is zero, |
| <CODE>yn</CODE> signals overflow and returns -infinity. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-rand" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>rand</CODE> function returns the next pseudo-random number in the |
| series. The value ranges from <CODE>0</CODE> to <CODE>RAND_MAX</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-srand" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="unsigned int seed"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| This function establishes <VAR>seed</VAR> as the seed for a new series of |
| pseudo-random numbers. If you call <CODE>rand</CODE> before a seed has been |
| established with <CODE>srand</CODE>, it uses the value <CODE>1</CODE> as a default |
| seed. |
| <br><br> To produce a different pseudo-random series each time your program is |
| run, do <CODE>srand (time (0))</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-rand_r" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="unsigned int *seed"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| This function returns a random number in the range 0 to <CODE>RAND_MAX</CODE> |
| just as <CODE>rand</CODE> does. However, all its state is stored in the |
| <VAR>seed</VAR> argument. This means the RNG's state can only have as many |
| bits as the type <CODE>unsigned int</CODE> has. This is far too few to |
| provide a good RNG. |
| <br><br> If your program requires a reentrant RNG, we recommend you use the |
| reentrant GNU extensions to the SVID random number generator. The |
| POSIX.1 interface should only be used when the GNU extensions are not |
| available. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-random" type="function"> |
| <function returntype="long int"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| This function returns the next pseudo-random number in the sequence. |
| The value returned ranges from <CODE>0</CODE> to <CODE>RAND_MAX</CODE>. |
| <br><br> NB: Temporarily this function was defined to return a |
| <CODE>int32_t</CODE> value to indicate that the return value always contains |
| 32 bits even if <CODE>long int</CODE> is wider. The standard demands it |
| differently. Users must always be aware of the 32-bit limitation, |
| though. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-srandom" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="unsigned int seed"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>srandom</CODE> function sets the state of the random number |
| generator based on the integer <VAR>seed</VAR>. If you supply a <VAR>seed</VAR> value |
| of <CODE>1</CODE>, this will cause <CODE>random</CODE> to reproduce the default set |
| of random numbers. |
| <br><br> To produce a different set of pseudo-random numbers each time your |
| program runs, do <CODE>srandom (time (0))</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-initstate" type="function"> |
| <function returntype="void *"> |
| <prototype> |
| <parameter content="unsigned int seed"/> |
| <parameter content="void *state"/> |
| <parameter content="size_t size"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>initstate</CODE> function is used to initialize the random number |
| generator state. The argument <VAR>state</VAR> is an array of <VAR>size</VAR> |
| bytes, used to hold the state information. It is initialized based on |
| <VAR>seed</VAR>. The size must be between 8 and 256 bytes, and should be a |
| power of two. The bigger the <VAR>state</VAR> array, the better. |
| <br><br> The return value is the previous value of the state information array. |
| You can use this value later as an argument to <CODE>setstate</CODE> to |
| restore that state. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-setstate" type="function"> |
| <function returntype="void *"> |
| <prototype> |
| <parameter content="void *state"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>setstate</CODE> function restores the random number state |
| information <VAR>state</VAR>. The argument must have been the result of |
| a previous call to <VAR>initstate</VAR> or <VAR>setstate</VAR>. |
| <br><br> The return value is the previous value of the state information array. |
| You can use this value later as an argument to <CODE>setstate</CODE> to |
| restore that state. |
| <br><br> If the function fails the return value is <CODE>NULL</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="struct-random_data" type="struct"> |
| <structure> |
| </structure> |
| </construct> |
| <construct id="function-random_r" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="struct random_data *restrict buf"/> |
| <parameter content="int32_t *restrict result"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>random_r</CODE> function behaves exactly like the <CODE>random</CODE> |
| function except that it uses and modifies the state in the object |
| pointed to by the first parameter instead of the global state. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-srandom_r" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="unsigned int seed"/> |
| <parameter content="struct random_data *buf"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>srandom_r</CODE> function behaves exactly like the <CODE>srandom</CODE> |
| function except that it uses and modifies the state in the object |
| pointed to by the second parameter instead of the global state. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-initstate_r" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="unsigned int seed"/> |
| <parameter content="char *restrict statebuf"/> |
| <parameter content="size_t statelen"/> |
| <parameter content="struct random_data *restrict buf"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>initstate_r</CODE> function behaves exactly like the <CODE>initstate</CODE> |
| function except that it uses and modifies the state in the object |
| pointed to by the fourth parameter instead of the global state. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-setstate_r" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="char *restrict statebuf"/> |
| <parameter content="struct random_data *restrict buf"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>setstate_r</CODE> function behaves exactly like the <CODE>setstate</CODE> |
| function except that it uses and modifies the state in the object |
| pointed to by the first parameter instead of the global state. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-drand48" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| This function returns a <CODE>double</CODE> value in the range of <CODE>0.0</CODE> |
| to <CODE>1.0</CODE> (exclusive). The random bits are determined by the global |
| state of the random number generator in the C library. |
| <br><br> Since the <CODE>double</CODE> type according to IEEE 754 has a 52-bit |
| mantissa this means 4 bits are not initialized by the random number |
| generator. These are (of course) chosen to be the least significant |
| bits and they are initialized to <CODE>0</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-erand48" type="function"> |
| <function returntype="double"> |
| <prototype> |
| <parameter content="unsigned short int xsubi[3]"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| This function returns a <CODE>double</CODE> value in the range of <CODE>0.0</CODE> |
| to <CODE>1.0</CODE> (exclusive), similarly to <CODE>drand48</CODE>. The argument is |
| an array describing the state of the random number generator. |
| <br><br> This function can be called subsequently since it updates the array to |
| guarantee random numbers. The array should have been initialized before |
| initial use to obtain reproducible results. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-lrand48" type="function"> |
| <function returntype="long int"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>lrand48</CODE> function returns an integer value in the range of |
| <CODE>0</CODE> to <CODE>2^31</CODE> (exclusive). Even if the size of the <CODE>long |
| int</CODE> type can take more than 32 bits, no higher numbers are returned. |
| The random bits are determined by the global state of the random number |
| generator in the C library. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-nrand48" type="function"> |
| <function returntype="long int"> |
| <prototype> |
| <parameter content="unsigned short int xsubi[3]"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to the <CODE>lrand48</CODE> function in that it |
| returns a number in the range of <CODE>0</CODE> to <CODE>2^31</CODE> (exclusive) but |
| the state of the random number generator used to produce the random bits |
| is determined by the array provided as the parameter to the function. |
| <br><br> The numbers in the array are updated afterwards so that subsequent calls |
| to this function yield different results (as is expected of a random |
| number generator). The array should have been initialized before the |
| first call to obtain reproducible results. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-mrand48" type="function"> |
| <function returntype="long int"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>mrand48</CODE> function is similar to <CODE>lrand48</CODE>. The only |
| difference is that the numbers returned are in the range <CODE>-2^31</CODE> to |
| <CODE>2^31</CODE> (exclusive). |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-jrand48" type="function"> |
| <function returntype="long int"> |
| <prototype> |
| <parameter content="unsigned short int xsubi[3]"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>jrand48</CODE> function is similar to <CODE>nrand48</CODE>. The only |
| difference is that the numbers returned are in the range <CODE>-2^31</CODE> to |
| <CODE>2^31</CODE> (exclusive). For the <CODE>xsubi</CODE> parameter the same |
| requirements are necessary. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-srand48" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="long int seedval"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>srand48</CODE> function sets the most significant 32 bits of the |
| internal state of the random number generator to the least |
| significant 32 bits of the <VAR>seedval</VAR> parameter. The lower 16 bits |
| are initialized to the value <CODE>0x330E</CODE>. Even if the <CODE>long |
| int</CODE> type contains more than 32 bits only the lower 32 bits are used. |
| <br><br> Owing to this limitation, initialization of the state of this |
| function is not very useful. But it makes it easy to use a construct |
| like <CODE>srand48 (time (0))</CODE>. |
| <br><br> A side-effect of this function is that the values <CODE>a</CODE> and <CODE>c</CODE> |
| from the internal state, which are used in the congruential formula, |
| are reset to the default values given above. This is of importance once |
| the user has called the <CODE>lcong48</CODE> function (see below). |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-seed48" type="function"> |
| <function returntype="unsigned short int *"> |
| <prototype> |
| <parameter content="unsigned short int seed16v[3]"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>seed48</CODE> function initializes all 48 bits of the state of the |
| internal random number generator from the contents of the parameter |
| <VAR>seed16v</VAR>. Here the lower 16 bits of the first element of |
| <VAR>see16v</VAR> initialize the least significant 16 bits of the internal |
| state, the lower 16 bits of <CODE><VAR>seed16v</VAR>[1]</CODE> initialize the mid-order |
| 16 bits of the state and the 16 lower bits of <CODE><VAR>seed16v</VAR>[2]</CODE> |
| initialize the most significant 16 bits of the state. |
| <br><br> Unlike <CODE>srand48</CODE> this function lets the user initialize all 48 bits |
| of the state. |
| <br><br> The value returned by <CODE>seed48</CODE> is a pointer to an array containing |
| the values of the internal state before the change. This might be |
| useful to restart the random number generator at a certain state. |
| Otherwise the value can simply be ignored. |
| <br><br> As for <CODE>srand48</CODE>, the values <CODE>a</CODE> and <CODE>c</CODE> from the |
| congruential formula are reset to the default values. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-lcong48" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="unsigned short int param[7]"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>lcong48</CODE> function allows the user to change the complete state |
| of the random number generator. Unlike <CODE>srand48</CODE> and |
| <CODE>seed48</CODE>, this function also changes the constants in the |
| congruential formula. |
| <br><br> From the seven elements in the array <VAR>param</VAR> the least significant |
| 16 bits of the entries <CODE><VAR>param</VAR>[0]</CODE> to <CODE><VAR>param</VAR>[2]</CODE> |
| determine the initial state, the least significant 16 bits of |
| <CODE><VAR>param</VAR>[3]</CODE> to <CODE><VAR>param</VAR>[5]</CODE> determine the 48 bit |
| constant <CODE>a</CODE> and <CODE><VAR>param</VAR>[6]</CODE> determines the 16-bit value |
| <CODE>c</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-drand48_r" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="struct drand48_data *buffer"/> |
| <parameter content="double *result"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| This function is equivalent to the <CODE>drand48</CODE> function with the |
| difference that it does not modify the global random number generator |
| parameters but instead the parameters in the buffer supplied through the |
| pointer <VAR>buffer</VAR>. The random number is returned in the variable |
| pointed to by <VAR>result</VAR>. |
| <br><br> The return value of the function indicates whether the call succeeded. |
| If the value is less than <CODE>0</CODE> an error occurred and <VAR>errno</VAR> is |
| set to indicate the problem. |
| <br><br> This function is a GNU extension and should not be used in portable |
| programs. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-erand48_r" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="unsigned short int xsubi[3]"/> |
| <parameter content="struct drand48_data *buffer"/> |
| <parameter content="double *result"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>erand48_r</CODE> function works like <CODE>erand48</CODE>, but in addition |
| it takes an argument <VAR>buffer</VAR> which describes the random number |
| generator. The state of the random number generator is taken from the |
| <CODE>xsubi</CODE> array, the parameters for the congruential formula from the |
| global random number generator data. The random number is returned in |
| the variable pointed to by <VAR>result</VAR>. |
| <br><br> The return value is non-negative if the call succeeded. |
| <br><br> This function is a GNU extension and should not be used in portable |
| programs. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-lrand48_r" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="struct drand48_data *buffer"/> |
| <parameter content="double *result"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to <CODE>lrand48</CODE>, but in addition it takes a |
| pointer to a buffer describing the state of the random number generator |
| just like <CODE>drand48</CODE>. |
| <br><br> If the return value of the function is non-negative the variable pointed |
| to by <VAR>result</VAR> contains the result. Otherwise an error occurred. |
| <br><br> This function is a GNU extension and should not be used in portable |
| programs. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-nrand48_r" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="unsigned short int xsubi[3]"/> |
| <parameter content="struct drand48_data *buffer"/> |
| <parameter content="long int *result"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>nrand48_r</CODE> function works like <CODE>nrand48</CODE> in that it |
| produces a random number in the range <CODE>0</CODE> to <CODE>2^31</CODE>. But instead |
| of using the global parameters for the congruential formula it uses the |
| information from the buffer pointed to by <VAR>buffer</VAR>. The state is |
| described by the values in <VAR>xsubi</VAR>. |
| <br><br> If the return value is non-negative the variable pointed to by |
| <VAR>result</VAR> contains the result. |
| <br><br> This function is a GNU extension and should not be used in portable |
| programs. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-mrand48_r" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="struct drand48_data *buffer"/> |
| <parameter content="double *result"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to <CODE>mrand48</CODE> but like the other reentrant |
| functions it uses the random number generator described by the value in |
| the buffer pointed to by <VAR>buffer</VAR>. |
| <br><br> If the return value is non-negative the variable pointed to by |
| <VAR>result</VAR> contains the result. |
| <br><br> This function is a GNU extension and should not be used in portable |
| programs. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-jrand48_r" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="unsigned short int xsubi[3]"/> |
| <parameter content="struct drand48_data *buffer"/> |
| <parameter content="long int *result"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>jrand48_r</CODE> function is similar to <CODE>jrand48</CODE>. Like the |
| other reentrant functions of this function family it uses the |
| congruential formula parameters from the buffer pointed to by |
| <VAR>buffer</VAR>. |
| <br><br> If the return value is non-negative the variable pointed to by |
| <VAR>result</VAR> contains the result. |
| <br><br> This function is a GNU extension and should not be used in portable |
| programs. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-srand48_r" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="long int seedval"/> |
| <parameter content="struct drand48_data *buffer"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The description of the random number generator represented by the |
| information in <VAR>buffer</VAR> is initialized similarly to what the function |
| <CODE>srand48</CODE> does. The state is initialized from the parameter |
| <VAR>seedval</VAR> and the parameters for the congruential formula are |
| initialized to their default values. |
| <br><br> If the return value is non-negative the function call succeeded. |
| <br><br> This function is a GNU extension and should not be used in portable |
| programs. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-seed48_r" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="unsigned short int seed16v[3]"/> |
| <parameter content="struct drand48_data *buffer"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to <CODE>srand48_r</CODE> but like <CODE>seed48</CODE> it |
| initializes all 48 bits of the state from the parameter <VAR>seed16v</VAR>. |
| <br><br> If the return value is non-negative the function call succeeded. It |
| does not return a pointer to the previous state of the random number |
| generator like the <CODE>seed48</CODE> function does. If the user wants to |
| preserve the state for a later re-run s/he can copy the whole buffer |
| pointed to by <VAR>buffer</VAR>. |
| <br><br> This function is a GNU extension and should not be used in portable |
| programs. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-lcong48_r" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="unsigned short int param[7]"/> |
| <parameter content="struct drand48_data *buffer"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| This function initializes all aspects of the random number generator |
| described in <VAR>buffer</VAR> with the data in <VAR>param</VAR>. Here it is |
| especially true that the function does more than just copying the |
| contents of <VAR>param</VAR> and <VAR>buffer</VAR>. More work is required and |
| therefore it is important to use this function rather than initializing |
| the random number generator directly. |
| <br><br> If the return value is non-negative the function call succeeded. |
| <br><br> This function is a GNU extension and should not be used in portable |
| programs. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-sysconf" type="function"> |
| <function returntype="long int"> |
| <prototype> |
| <parameter content="int parameter"/> |
| </prototype> |
| <headers> |
| <header filename = "limits.h"/> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| This function is used to inquire about runtime system parameters. The |
| <VAR>parameter</VAR> argument should be one of the <samp>_SC_</samp> symbols listed |
| below. |
| <br><br> The normal return value from <CODE>sysconf</CODE> is the value you requested. |
| A value of <CODE>-1</CODE> is returned both if the implementation does not |
| impose a limit, and in case of an error. |
| <br><br> The following <CODE>errno</CODE> error conditions are defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EINVAL</CODE> |
| <DD> |
| The value of the <VAR>parameter</VAR> is invalid. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-pathconf" type="function"> |
| <function returntype="long int"> |
| <prototype> |
| <parameter content="const char *filename"/> |
| <parameter content="int parameter"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| <header filename = "unistdh.h"/> |
| <header filename = "limits.h"/> |
| <header filename = "dirent.h"/> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| This function is used to inquire about the limits that apply to |
| the file named <VAR>filename</VAR>. |
| <br><br> The <VAR>parameter</VAR> argument should be one of the <samp>_PC_</samp> constants |
| listed below. |
| <br><br> The normal return value from <CODE>pathconf</CODE> is the value you requested. |
| A value of <CODE>-1</CODE> is returned both if the implementation does not |
| impose a limit, and in case of an error. In the former case, |
| <CODE>errno</CODE> is not set, while in the latter case, <CODE>errno</CODE> is set |
| to indicate the cause of the problem. So the only way to use this |
| function robustly is to store <CODE>0</CODE> into <CODE>errno</CODE> just before |
| calling it. |
| <br><br> Besides the usual file name errors , |
| the following error condition is defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EINVAL</CODE> |
| <DD> |
| The value of <VAR>parameter</VAR> is invalid, or the implementation doesn't |
| support the <VAR>parameter</VAR> for the specific file. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fpathconf" type="function"> |
| <function returntype="long int"> |
| <prototype> |
| <parameter content="int filedes"/> |
| <parameter content="int parameter"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| </headers> |
| <synopsis> |
| This is just like <CODE>pathconf</CODE> except that an open file descriptor |
| is used to specify the file for which information is requested, instead |
| of a file name. |
| <br><br> The following <CODE>errno</CODE> error conditions are defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EBADF</CODE> |
| <DD> |
| The <VAR>filedes</VAR> argument is not a valid file descriptor. |
| <br><br> <LI> EINVAL |
| The value of <VAR>parameter</VAR> is invalid, or the implementation doesn't |
| support the <VAR>parameter</VAR> for the specific file. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-confstr" type="function"> |
| <function returntype="size_t"> |
| <prototype> |
| <parameter content="int parameter"/> |
| <parameter content="char *buf"/> |
| <parameter content="size_t len"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| <header filename = "limits.h"/> |
| </headers> |
| <synopsis> |
| This function reads the value of a string-valued system parameter, |
| storing the string into <VAR>len</VAR> bytes of memory space starting at |
| <VAR>buf</VAR>. The <VAR>parameter</VAR> argument should be one of the |
| <samp>_CS_</samp> symbols listed below. |
| <br><br> The normal return value from <CODE>confstr</CODE> is the length of the string |
| value that you asked for. If you supply a null pointer for <VAR>buf</VAR>, |
| then <CODE>confstr</CODE> does not try to store the string; it just returns |
| its length. A value of <CODE>0</CODE> indicates an error. |
| <br><br> If the string you asked for is too long for the buffer (that is, longer |
| than <CODE><VAR>len</VAR> - 1</CODE>), then <CODE>confstr</CODE> stores just that much |
| (leaving room for the terminating null character). You can tell that |
| this has happened because <CODE>confstr</CODE> returns a value greater than or |
| equal to <VAR>len</VAR>. |
| <br><br> The following <CODE>errno</CODE> error conditions are defined for this function: |
| <br><br> <DL> |
| |
| <DT><CODE>EINVAL</CODE> |
| <DD> |
| The value of the <VAR>parameter</VAR> is invalid. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-setlocale" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="int category"/> |
| <parameter content="const char *locale"/> |
| </prototype> |
| <headers> |
| <header filename = "unistd.h"/> |
| <header filename = "locale.h"/> |
| </headers> |
| <synopsis> |
| The function <CODE>setlocale</CODE> sets the current locale for category |
| <VAR>category</VAR> to <VAR>locale</VAR>. A list of all the locales the system |
| provides can be created by running |
| <br><br> <pre><br> |
| locale -a<br> |
| </pre> |
| <br><br> If <VAR>category</VAR> is <CODE>LC_ALL</CODE>, this specifies the locale for all |
| purposes. The other possible values of <VAR>category</VAR> specify an |
| single purpose . |
| <br><br> You can also use this function to find out the current locale by passing |
| a null pointer as the <VAR>locale</VAR> argument. In this case, |
| <CODE>setlocale</CODE> returns a string that is the name of the locale |
| currently selected for category <VAR>category</VAR>. |
| <br><br> The string returned by <CODE>setlocale</CODE> can be overwritten by subsequent |
| calls, so you should make a copy of the string if you want to save it past any further calls to |
| <CODE>setlocale</CODE>. (The standard library is guaranteed never to call |
| <CODE>setlocale</CODE> itself.) |
| <br><br> You should not modify the string returned by <CODE>setlocale</CODE>. It might |
| be the same string that was passed as an argument in a previous call to |
| <CODE>setlocale</CODE>. One requirement is that the <VAR>category</VAR> must be |
| the same in the call the string was returned and the one when the string |
| is passed in as <VAR>locale</VAR> parameter. |
| <br><br> When you read the current locale for category <CODE>LC_ALL</CODE>, the value |
| encodes the entire combination of selected locales for all categories. |
| In this case, the value is not just a single locale name. In fact, we |
| don't make any promises about what it looks like. But if you specify |
| the same ``locale name'' with <CODE>LC_ALL</CODE> in a subsequent call to |
| <CODE>setlocale</CODE>, it restores the same combination of locale selections. |
| <br><br> To be sure you can use the returned string encoding the currently selected |
| locale at a later time, you must make a copy of the string. It is not |
| guaranteed that the returned pointer remains valid over time. |
| <br><br> When the <VAR>locale</VAR> argument is not a null pointer, the string returned |
| by <CODE>setlocale</CODE> reflects the newly-modified locale. |
| <br><br> If you specify an empty string for <VAR>locale</VAR>, this means to read the |
| appropriate environment variable and use its value to select the locale |
| for <VAR>category</VAR>. |
| <br><br> If a nonempty string is given for <VAR>locale</VAR>, then the locale of that |
| name is used if possible. |
| <br><br> If you specify an invalid locale name, <CODE>setlocale</CODE> returns a null |
| pointer and leaves the current locale unchanged. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-localeconv" type="function"> |
| <function returntype="struct lconv *"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "locale.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>localeconv</CODE> function returns a pointer to a structure whose |
| components contain information about how numeric and monetary values |
| should be formatted in the current locale. |
| <br><br> You should not modify the structure or its contents. The structure might |
| be overwritten by subsequent calls to <CODE>localeconv</CODE>, or by calls to |
| <CODE>setlocale</CODE>, but no other function in the library overwrites this |
| value. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="struct-lconv" type="struct"> |
| <structure> |
| </structure> |
| </construct> |
| <construct id="function-nl_langinfo" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="nl_item item"/> |
| </prototype> |
| <headers> |
| <header filename = "locale.h"/> |
| <header filename = "langinfo.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>nl_langinfo</CODE> function can be used to access individual |
| elements of the locale categories. Unlike the <CODE>localeconv</CODE> |
| function, which returns all the information, <CODE>nl_langinfo</CODE> |
| lets the caller select what information it requires. This is very |
| fast and it is not a problem to call this function multiple times. |
| <br><br> A second advantage is that in addition to the numeric and monetary |
| formatting information, information from the |
| <CODE>LC_TIME</CODE> and <CODE>LC_MESSAGES</CODE> categories is available. |
| <br><br> The type <CODE>nl_type</CODE> is defined in <TT>nl_types.h</TT>. The argument |
| <VAR>item</VAR> is a numeric value defined in the header <TT>langinfo.h</TT>. |
| The X/Open standard defines the following values: |
| <br><br> <DL> |
| |
| <DT><CODE>CODESET</CODE> |
| <DD> |
| <CODE>nl_langinfo</CODE> returns a string with the name of the coded character |
| set used in the selected locale. |
| <br><br> <DT><CODE>ABDAY_1</CODE> |
| <DD> |
| <LI>x ABDAY_2 |
| <LI>x ABDAY_3 |
| <LI>x ABDAY_4 |
| <LI>x ABDAY_5 |
| <LI>x ABDAY_6 |
| <LI>x ABDAY_7 |
| <CODE>nl_langinfo</CODE> returns the abbreviated weekday name. <CODE>ABDAY_1</CODE> |
| corresponds to Sunday. |
| <DT><CODE>DAY_1</CODE> |
| <DD> |
| <LI>x DAY_2 |
| <LI>x DAY_3 |
| <LI>x DAY_4 |
| <LI>x DAY_5 |
| <LI>x DAY_6 |
| <LI>x DAY_7 |
| Similar to <CODE>ABDAY_1</CODE> etc., but here the return value is the |
| unabbreviated weekday name. |
| <DT><CODE>ABMON_1</CODE> |
| <DD> |
| <LI>x ABMON_2 |
| <LI>x ABMON_3 |
| <LI>x ABMON_4 |
| <LI>x ABMON_5 |
| <LI>x ABMON_6 |
| <LI>x ABMON_7 |
| <LI>x ABMON_8 |
| <LI>x ABMON_9 |
| <LI>x ABMON_10 |
| <LI>x ABMON_11 |
| <LI>x ABMON_12 |
| The return value is abbreviated name of the month. <CODE>ABMON_1</CODE> |
| corresponds to January. |
| <DT><CODE>MON_1</CODE> |
| <DD> |
| <LI>x MON_2 |
| <LI>x MON_3 |
| <LI>x MON_4 |
| <LI>x MON_5 |
| <LI>x MON_6 |
| <LI>x MON_7 |
| <LI>x MON_8 |
| <LI>x MON_9 |
| <LI>x MON_10 |
| <LI>x MON_11 |
| <LI>x MON_12 |
| Similar to <CODE>ABMON_1</CODE> etc., but here the month names are not abbreviated. |
| Here the first value <CODE>MON_1</CODE> also corresponds to January. |
| <DT><CODE>AM_STR</CODE> |
| <DD> |
| <LI>x PM_STR |
| The return values are strings which can be used in the representation of time |
| as an hour from 1 to 12 plus an am/pm specifier. |
| <br><br> Note that in locales which do not use this time representation |
| these strings might be empty, in which case the am/pm format |
| cannot be used at all. |
| <DT><CODE>D_T_FMT</CODE> |
| <DD> |
| The return value can be used as a format string for <CODE>strftime</CODE> to |
| represent time and date in a locale-specific way. |
| <DT><CODE>D_FMT</CODE> |
| <DD> |
| The return value can be used as a format string for <CODE>strftime</CODE> to |
| represent a date in a locale-specific way. |
| <DT><CODE>T_FMT</CODE> |
| <DD> |
| The return value can be used as a format string for <CODE>strftime</CODE> to |
| represent time in a locale-specific way. |
| <DT><CODE>T_FMT_AMPM</CODE> |
| <DD> |
| The return value can be used as a format string for <CODE>strftime</CODE> to |
| represent time in the am/pm format. |
| <br><br> Note that if the am/pm format does not make any sense for the |
| selected locale, the return value might be the same as the one for |
| <CODE>T_FMT</CODE>. |
| <DT><CODE>ERA</CODE> |
| <DD> |
| The return value represents the era used in the current locale. |
| <br><br> Most locales do not define this value. An example of a locale which |
| does define this value is the Japanese one. In Japan, the traditional |
| representation of dates includes the name of the era corresponding to |
| the then-emperor's reign. |
| <br><br> Normally it should not be necessary to use this value directly. |
| Specifying the <CODE>E</CODE> modifier in their format strings causes the |
| <CODE>strftime</CODE> functions to use this information. The format of the |
| returned string is not specified, and therefore you should not assume |
| knowledge of it on different systems. |
| <DT><CODE>ERA_YEAR</CODE> |
| <DD> |
| The return value gives the year in the relevant era of the locale. |
| As for <CODE>ERA</CODE> it should not be necessary to use this value directly. |
| <DT><CODE>ERA_D_T_FMT</CODE> |
| <DD> |
| This return value can be used as a format string for <CODE>strftime</CODE> to |
| represent dates and times in a locale-specific era-based way. |
| <DT><CODE>ERA_D_FMT</CODE> |
| <DD> |
| This return value can be used as a format string for <CODE>strftime</CODE> to |
| represent a date in a locale-specific era-based way. |
| <DT><CODE>ERA_T_FMT</CODE> |
| <DD> |
| This return value can be used as a format string for <CODE>strftime</CODE> to |
| represent time in a locale-specific era-based way. |
| <DT><CODE>ALT_DIGITS</CODE> |
| <DD> |
| The return value is a representation of up to 100 values used to |
| represent the values 0 to 99. As for <CODE>ERA</CODE> this |
| value is not intended to be used directly, but instead indirectly |
| through the <CODE>strftime</CODE> function. When the modifier <CODE>O</CODE> is |
| used in a format which would otherwise use numerals to represent hours, |
| minutes, seconds, weekdays, months, or weeks, the appropriate value for |
| the locale is used instead. |
| <DT><CODE>INT_CURR_SYMBOL</CODE> |
| <DD> |
| The same as the value returned by <CODE>localeconv</CODE> in the |
| <CODE>int_curr_symbol</CODE> element of the <CODE>struct lconv</CODE>. |
| <DT><CODE>CURRENCY_SYMBOL</CODE> |
| <DD> |
| <LI>x CRNCYSTR |
| The same as the value returned by <CODE>localeconv</CODE> in the |
| <CODE>currency_symbol</CODE> element of the <CODE>struct lconv</CODE>. |
| <br><br> <CODE>CRNCYSTR</CODE> is a deprecated alias still required by Unix98. |
| <DT><CODE>MON_DECIMAL_POINT</CODE> |
| <DD> |
| The same as the value returned by <CODE>localeconv</CODE> in the |
| <CODE>mon_decimal_point</CODE> element of the <CODE>struct lconv</CODE>. |
| <DT><CODE>MON_THOUSANDS_SEP</CODE> |
| <DD> |
| The same as the value returned by <CODE>localeconv</CODE> in the |
| <CODE>mon_thousands_sep</CODE> element of the <CODE>struct lconv</CODE>. |
| <DT><CODE>MON_GROUPING</CODE> |
| <DD> |
| The same as the value returned by <CODE>localeconv</CODE> in the |
| <CODE>mon_grouping</CODE> element of the <CODE>struct lconv</CODE>. |
| <DT><CODE>POSITIVE_SIGN</CODE> |
| <DD> |
| The same as the value returned by <CODE>localeconv</CODE> in the |
| <CODE>positive_sign</CODE> element of the <CODE>struct lconv</CODE>. |
| <DT><CODE>NEGATIVE_SIGN</CODE> |
| <DD> |
| The same as the value returned by <CODE>localeconv</CODE> in the |
| <CODE>negative_sign</CODE> element of the <CODE>struct lconv</CODE>. |
| <DT><CODE>INT_FRAC_DIGITS</CODE> |
| <DD> |
| The same as the value returned by <CODE>localeconv</CODE> in the |
| <CODE>int_frac_digits</CODE> element of the <CODE>struct lconv</CODE>. |
| <DT><CODE>FRAC_DIGITS</CODE> |
| <DD> |
| The same as the value returned by <CODE>localeconv</CODE> in the |
| <CODE>frac_digits</CODE> element of the <CODE>struct lconv</CODE>. |
| <DT><CODE>P_CS_PRECEDES</CODE> |
| <DD> |
| The same as the value returned by <CODE>localeconv</CODE> in the |
| <CODE>p_cs_precedes</CODE> element of the <CODE>struct lconv</CODE>. |
| <DT><CODE>P_SEP_BY_SPACE</CODE> |
| <DD> |
| The same as the value returned by <CODE>localeconv</CODE> in the |
| <CODE>p_sep_by_space</CODE> element of the <CODE>struct lconv</CODE>. |
| <DT><CODE>N_CS_PRECEDES</CODE> |
| <DD> |
| The same as the value returned by <CODE>localeconv</CODE> in the |
| <CODE>n_cs_precedes</CODE> element of the <CODE>struct lconv</CODE>. |
| <DT><CODE>N_SEP_BY_SPACE</CODE> |
| <DD> |
| The same as the value returned by <CODE>localeconv</CODE> in the |
| <CODE>n_sep_by_space</CODE> element of the <CODE>struct lconv</CODE>. |
| <DT><CODE>P_SIGN_POSN</CODE> |
| <DD> |
| The same as the value returned by <CODE>localeconv</CODE> in the |
| <CODE>p_sign_posn</CODE> element of the <CODE>struct lconv</CODE>. |
| <DT><CODE>N_SIGN_POSN</CODE> |
| <DD> |
| The same as the value returned by <CODE>localeconv</CODE> in the |
| <CODE>n_sign_posn</CODE> element of the <CODE>struct lconv</CODE>. |
| <br><br> <DT><CODE>INT_P_CS_PRECEDES</CODE> |
| <DD> |
| The same as the value returned by <CODE>localeconv</CODE> in the |
| <CODE>int_p_cs_precedes</CODE> element of the <CODE>struct lconv</CODE>. |
| <DT><CODE>INT_P_SEP_BY_SPACE</CODE> |
| <DD> |
| The same as the value returned by <CODE>localeconv</CODE> in the |
| <CODE>int_p_sep_by_space</CODE> element of the <CODE>struct lconv</CODE>. |
| <DT><CODE>INT_N_CS_PRECEDES</CODE> |
| <DD> |
| The same as the value returned by <CODE>localeconv</CODE> in the |
| <CODE>int_n_cs_precedes</CODE> element of the <CODE>struct lconv</CODE>. |
| <DT><CODE>INT_N_SEP_BY_SPACE</CODE> |
| <DD> |
| The same as the value returned by <CODE>localeconv</CODE> in the |
| <CODE>int_n_sep_by_space</CODE> element of the <CODE>struct lconv</CODE>. |
| <DT><CODE>INT_P_SIGN_POSN</CODE> |
| <DD> |
| The same as the value returned by <CODE>localeconv</CODE> in the |
| <CODE>int_p_sign_posn</CODE> element of the <CODE>struct lconv</CODE>. |
| <DT><CODE>INT_N_SIGN_POSN</CODE> |
| <DD> |
| The same as the value returned by <CODE>localeconv</CODE> in the |
| <CODE>int_n_sign_posn</CODE> element of the <CODE>struct lconv</CODE>. |
| <br><br> <DT><CODE>DECIMAL_POINT</CODE> |
| <DD> |
| <LI>x RADIXCHAR |
| The same as the value returned by <CODE>localeconv</CODE> in the |
| <CODE>decimal_point</CODE> element of the <CODE>struct lconv</CODE>. |
| <br><br> The name <CODE>RADIXCHAR</CODE> is a deprecated alias still used in Unix98. |
| <DT><CODE>THOUSANDS_SEP</CODE> |
| <DD> |
| <LI>x THOUSEP |
| The same as the value returned by <CODE>localeconv</CODE> in the |
| <CODE>thousands_sep</CODE> element of the <CODE>struct lconv</CODE>. |
| <br><br> The name <CODE>THOUSEP</CODE> is a deprecated alias still used in Unix98. |
| <DT><CODE>GROUPING</CODE> |
| <DD> |
| The same as the value returned by <CODE>localeconv</CODE> in the |
| <CODE>grouping</CODE> element of the <CODE>struct lconv</CODE>. |
| <DT><CODE>YESEXPR</CODE> |
| <DD> |
| The return value is a regular expression which can be used with the |
| <CODE>regex</CODE> function to recognize a positive response to a yes/no |
| question. The GNU C library provides the <CODE>rpmatch</CODE> function for |
| easier handling in applications. |
| <DT><CODE>NOEXPR</CODE> |
| <DD> |
| The return value is a regular expression which can be used with the |
| <CODE>regex</CODE> function to recognize a negative response to a yes/no |
| question. |
| <DT><CODE>YESSTR</CODE> |
| <DD> |
| The return value is a locale-specific translation of the positive response |
| to a yes/no question. |
| <br><br> Using this value is deprecated since it is a very special case of |
| message translation, and is better handled by the message |
| translation functions . |
| <br><br> The use of this symbol is deprecated. Instead message translation |
| should be used. |
| <DT><CODE>NOSTR</CODE> |
| <DD> |
| The return value is a locale-specific translation of the negative response |
| to a yes/no question. What is said for <CODE>YESSTR</CODE> is also true here. |
| <br><br> The use of this symbol is deprecated. Instead message translation |
| should be used. |
| </DL> |
| <br><br> The file <TT>langinfo.h</TT> defines a lot more symbols but none of them |
| is official. Using them is not portable, and the format of the |
| return values might change. Therefore we recommended you not use |
| them. |
| <br><br> Note that the return value for any valid argument can be used for |
| in all situations (with the possible exception of the am/pm time formatting |
| codes). If the user has not selected any locale for the |
| appropriate category, <CODE>nl_langinfo</CODE> returns the information from the |
| <CODE>"C"</CODE> locale. It is therefore possible to use this function as |
| shown in the example below. |
| <br><br> If the argument <VAR>item</VAR> is not valid, a pointer to an empty string is |
| returned. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-strfmon" type="function"> |
| <function returntype="ssize_t"> |
| <prototype> |
| <parameter content="char *s"/> |
| <parameter content="size_t maxsize"/> |
| <parameter content="const char *format"/> |
| <parameter content="..."/> |
| </prototype> |
| <synopsis> |
| The <CODE>strfmon</CODE> function is similar to the <CODE>strftime</CODE> function |
| in that it takes a buffer, its size, a format string, |
| and values to write into the buffer as text in a form specified |
| by the format string. Like <CODE>strftime</CODE>, the function |
| also returns the number of bytes written into the buffer. |
| <br><br> There are two differences: <CODE>strfmon</CODE> can take more than one |
| argument, and, of course, the format specification is different. Like |
| <CODE>strftime</CODE>, the format string consists of normal text, which is |
| output as is, and format specifiers, which are indicated by a <samp>%</samp>. |
| Immediately after the <samp>%</samp>, you can optionally specify various flags |
| and formatting information before the main formatting character, in a |
| similar way to <CODE>printf</CODE>: |
| <br><br> <OL> |
| <LI> |
| Immediately following the <samp>%</samp> there can be one or more of the |
| following flags: |
| <DL> |
| |
| <LI> <samp>=<VAR>f</VAR></samp> |
| The single byte character <VAR>f</VAR> is used for this field as the numeric |
| fill character. By default this character is a space character. |
| Filling with this character is only performed if a left precision |
| is specified. It is not just to fill to the given field width. |
| <LI> <samp>^</samp> |
| The number is printed without grouping the digits according to the rules |
| of the current locale. By default grouping is enabled. |
| <LI> <samp>+</samp>, <samp>(</samp> |
| At most one of these flags can be used. They select which format to |
| represent the sign of a currency amount. By default, and if |
| <samp>+</samp> is given, the locale equivalent of +/- is used. If |
| <samp>(</samp> is given, negative amounts are enclosed in parentheses. The |
| exact format is determined by the values of the <CODE>LC_MONETARY</CODE> |
| category of the locale selected at program runtime. |
| <LI> <samp>!</samp> |
| The output will not contain the currency symbol. |
| <LI> <samp>-</samp> |
| The output will be formatted left-justified instead of right-justified if |
| it does not fill the entire field width. |
| </DL> |
| </OL> |
| <br><br> The next part of a specification is an optional field width. If no |
| width is specified 0 is taken. During output, the function first |
| determines how much space is required. If it requires at least as many |
| characters as given by the field width, it is output using as much space |
| as necessary. Otherwise, it is extended to use the full width by |
| filling with the space character. The presence or absence of the |
| <samp>-</samp> flag determines the side at which such padding occurs. If |
| present, the spaces are added at the right making the output |
| left-justified, and vice versa. |
| <br><br> So far the format looks familiar, being similar to the <CODE>printf</CODE> and |
| <CODE>strftime</CODE> formats. However, the next two optional fields |
| introduce something new. The first one is a <samp>#</samp> character followed |
| by a decimal digit string. The value of the digit string specifies the |
| number of <EM>digit</EM> positions to the left of the decimal point (or |
| equivalent). This does <EM>not</EM> include the grouping character when |
| the <samp>^</samp> flag is not given. If the space needed to print the number |
| does not fill the whole width, the field is padded at the left side with |
| the fill character, which can be selected using the <samp>=</samp> flag and by |
| default is a space. For example, if the field width is selected as 6 |
| and the number is 123, the fill character is <samp>*</samp> the result |
| will be <samp>***123</samp>. |
| <br><br> The second optional field starts with a <samp>.</samp> (period) and consists |
| of another decimal digit string. Its value describes the number of |
| characters printed after the decimal point. The default is selected |
| from the current locale (<CODE>frac_digits</CODE>, <CODE>int_frac_digits</CODE>, see |
| ). If the exact representation needs more digits |
| than given by the field width, the displayed value is rounded. If the |
| number of fractional digits is selected to be zero, no decimal point is |
| printed. |
| <br><br> As a GNU extension, the <CODE>strfmon</CODE> implementation in the GNU libc |
| allows an optional <samp>L</samp> next as a format modifier. If this modifier |
| is given, the argument is expected to be a <CODE>long double</CODE> instead of |
| a <CODE>double</CODE> value. |
| <br><br> Finally, the last component is a format specifier. There are three |
| specifiers defined: |
| <br><br> <DL> |
| |
| <LI> <samp>i</samp> |
| Use the locale's rules for formatting an international currency value. |
| <LI> <samp>n</samp> |
| Use the locale's rules for formatting a national currency value. |
| <LI> <samp>%</samp> |
| Place a <samp>%</samp> in the output. There must be no flag, width |
| specifier or modifier given, only <samp>%%</samp> is allowed. |
| </DL> |
| <br><br> As for <CODE>printf</CODE>, the function reads the format string |
| from left to right and uses the values passed to the function following |
| the format string. The values are expected to be either of type |
| <CODE>double</CODE> or <CODE>long double</CODE>, depending on the presence of the |
| modifier <samp>L</samp>. The result is stored in the buffer pointed to by |
| <VAR>s</VAR>. At most <VAR>maxsize</VAR> characters are stored. |
| <br><br> The return value of the function is the number of characters stored in |
| <VAR>s</VAR>, including the terminating <CODE>NULL</CODE> byte. If the number of |
| characters stored would exceed <VAR>maxsize</VAR>, the function returns |
| -1 and the content of the buffer <VAR>s</VAR> is unspecified. In this |
| case <CODE>errno</CODE> is set to <CODE>E2BIG</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-rpmatch" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *response"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The function <CODE>rpmatch</CODE> checks the string in <VAR>response</VAR> whether |
| or not it is a correct yes-or-no answer and if yes, which one. The |
| check uses the <CODE>YESEXPR</CODE> and <CODE>NOEXPR</CODE> data in the |
| <CODE>LC_MESSAGES</CODE> category of the currently selected locale. The |
| return value is as follows: |
| <br><br> <DL> |
| |
| <DT><CODE>1</CODE> |
| <DD> |
| The user entered an affirmative answer. |
| <br><br> <LI> 0 |
| The user entered a negative answer. |
| <br><br> <LI> -1 |
| The answer matched neither the <CODE>YESEXPR</CODE> nor the <CODE>NOEXPR</CODE> |
| regular expression. |
| |
| <br><br> This function is not standardized but available beside in GNU libc at |
| least also in the IBM AIX library. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="dtype-FILE" type="dtype"> |
| <structure> |
| </structure> |
| </construct> |
| <construct id="function-fopen" type="function"> |
| <function returntype="FILE *"> |
| <prototype> |
| <parameter content="const char *filename"/> |
| <parameter content="const char *opentype"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>fopen</CODE> function opens a stream for I/O to the file |
| <VAR>filename</VAR>, and returns a pointer to the stream. |
| <br><br> The <VAR>opentype</VAR> argument is a string that controls how the file is |
| opened and specifies attributes of the resulting stream. It must begin |
| with one of the following sequences of characters: |
| <br><br> <DL> |
| |
| <DT><SAMP>r</SAMP> |
| <DD> |
| Open an existing file for reading only. |
| <br><br> <DT><SAMP>w</SAMP> |
| <DD> |
| Open the file for writing only. If the file already exists, it is |
| truncated to zero length. Otherwise a new file is created. |
| <br><br> <DT><SAMP>a</SAMP> |
| <DD> |
| Open a file for append access; that is, writing at the end of file only. |
| If the file already exists, its initial contents are unchanged and |
| output to the stream is appended to the end of the file. |
| Otherwise, a new, empty file is created. |
| <br><br> <DT><SAMP>r+</SAMP> |
| <DD> |
| Open an existing file for both reading and writing. The initial contents |
| of the file are unchanged and the initial file position is at the |
| beginning of the file. |
| <br><br> <DT><SAMP>w+</SAMP> |
| <DD> |
| Open a file for both reading and writing. If the file already exists, it |
| is truncated to zero length. Otherwise, a new file is created. |
| <br><br> <DT><SAMP>a+</SAMP> |
| <DD> |
| Open or create file for both reading and appending. If the file exists, |
| its initial contents are unchanged. Otherwise, a new file is created. |
| The initial file position for reading is at the beginning of the file, |
| but output is always appended to the end of the file. |
| </DL> |
| <br><br> As you can see, <samp>+</samp> requests a stream that can do both input and |
| output. When using such a stream, you must call <CODE>fflush</CODE> |
| or a file positioning function such as |
| <CODE>fseek</CODE> when switching from reading |
| to writing or vice versa. Otherwise, internal buffers might not be |
| emptied properly. |
| <br><br> Additional characters may appear after these to specify flags for the |
| call. Always put the mode (<samp>r</samp>, <samp>w+</samp>, etc.) first; that is |
| the only part you are guaranteed will be understood by all systems. |
| <br><br> The GNU C library defines one additional character for use in |
| <VAR>opentype</VAR>: the character <samp>x</samp> insists on creating a new |
| file---if a file <VAR>filename</VAR> already exists, <CODE>fopen</CODE> fails |
| rather than opening it. If you use <samp>x</samp> you are guaranteed that |
| you will not clobber an existing file. This is equivalent to the |
| <CODE>O_EXCL</CODE> option to the <CODE>open</CODE> function . |
| <br><br> The character <samp>b</samp> in <VAR>opentype</VAR> has a standard meaning; it |
| requests a binary stream rather than a text stream. But this makes no |
| difference in POSIX systems (including the GNU system). If both |
| <samp>+</samp> and <samp>b</samp> are specified, they can appear in either order. |
| . |
| <br><br> orientation |
| , stream |
| If the <VAR>opentype</VAR> string contains the sequence |
| <CODE>,ccs=<VAR>STRING</VAR></CODE> then <VAR>STRING</VAR> is taken as the name of a |
| coded character set and <CODE>fopen</CODE> will mark the stream as |
| wide-oriented which appropriate conversion functions in place to convert |
| from and to the character set <VAR>STRING</VAR> is place. Any other stream |
| is opened initially unoriented and the orientation is decided with the |
| first file operation. If the first operation is a wide character |
| operation, the stream is not only marked as wide-oriented, also the |
| conversion functions to convert to the coded character set used for the |
| current locale are loaded. This will not change anymore from this point |
| on even if the locale selected for the <CODE>LC_CTYPE</CODE> category is |
| changed. |
| <br><br> Any other characters in <VAR>opentype</VAR> are simply ignored. They may be |
| meaningful in other systems. |
| <br><br> If the open fails, <CODE>fopen</CODE> returns a null pointer. |
| <br><br> When the sources are compiling with <CODE>_FILE_OFFSET_BITS == 64</CODE> on a |
| 32 bit machine this function is in fact <CODE>fopen64</CODE> since the LFS |
| interface replaces transparently the old interface. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fopen64" type="function"> |
| <function returntype="FILE *"> |
| <prototype> |
| <parameter content="const char *filename"/> |
| <parameter content="const char *opentype"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to <CODE>fopen</CODE> but the stream it returns a |
| pointer for is opened using <CODE>open64</CODE>. Therefore this stream can be |
| used even on files larger then 2^31 bytes on 32 bit machines. |
| <br><br> Please note that the return type is still <CODE>FILE *</CODE>. There is no |
| special <CODE>FILE</CODE> type for the LFS interface. |
| <br><br> If the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> on a 32 |
| bits machine this function is available under the name <CODE>fopen</CODE> |
| and so transparently replaces the old interface. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-freopen" type="function"> |
| <function returntype="FILE *"> |
| <prototype> |
| <parameter content="const char *filename"/> |
| <parameter content="const char *opentype"/> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| This function is like a combination of <CODE>fclose</CODE> and <CODE>fopen</CODE>. |
| It first closes the stream referred to by <VAR>stream</VAR>, ignoring any |
| errors that are detected in the process. (Because errors are ignored, |
| you should not use <CODE>freopen</CODE> on an output stream if you have |
| actually done any output using the stream.) Then the file named by |
| <VAR>filename</VAR> is opened with mode <VAR>opentype</VAR> as for <CODE>fopen</CODE>, |
| and associated with the same stream object <VAR>stream</VAR>. |
| <br><br> If the operation fails, a null pointer is returned; otherwise, |
| <CODE>freopen</CODE> returns <VAR>stream</VAR>. |
| <br><br> <CODE>freopen</CODE> has traditionally been used to connect a standard stream |
| such as <CODE>stdin</CODE> with a file of your own choice. This is useful in |
| programs in which use of a standard stream for certain purposes is |
| hard-coded. In the GNU C library, you can simply close the standard |
| streams and open new ones with <CODE>fopen</CODE>. But other systems lack |
| this ability, so using <CODE>freopen</CODE> is more portable. |
| <br><br> When the sources are compiling with <CODE>_FILE_OFFSET_BITS == 64</CODE> on a |
| 32 bit machine this function is in fact <CODE>freopen64</CODE> since the LFS |
| interface replaces transparently the old interface. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-freopen64" type="function"> |
| <function returntype="FILE *"> |
| <prototype> |
| <parameter content="const char *filename"/> |
| <parameter content="const char *opentype"/> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to <CODE>freopen</CODE>. The only difference is that |
| on 32 bit machine the stream returned is able to read beyond the |
| 2^31 bytes limits imposed by the normal interface. It should be |
| noted that the stream pointed to by <VAR>stream</VAR> need not be opened |
| using <CODE>fopen64</CODE> or <CODE>freopen64</CODE> since its mode is not important |
| for this function. |
| <br><br> If the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> on a 32 |
| bits machine this function is available under the name <CODE>freopen</CODE> |
| and so transparently replaces the old interface. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-__freadable" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio_ext.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>__freadable</CODE> function determines whether the stream |
| <VAR>stream</VAR> was opened to allow reading. In this case the return value |
| is nonzero. For write-only streams the function returns zero. |
| <br><br> This function is declared in <TT>stdio_ext.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-__fwritable" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio_ext.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>__fwritable</CODE> function determines whether the stream |
| <VAR>stream</VAR> was opened to allow writing. In this case the return value |
| is nonzero. For read-only streams the function returns zero. |
| <br><br> This function is declared in <TT>stdio_ext.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-__freading" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio_ext.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>__freading</CODE> function determines whether the stream |
| <VAR>stream</VAR> was last read from or whether it is opened read-only. In |
| this case the return value is nonzero, otherwise it is zero. |
| Determining whether a stream opened for reading and writing was last |
| used for writing allows to draw conclusions about the content about the |
| buffer, among other things. |
| <br><br> This function is declared in <TT>stdio_ext.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-__fwriting" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio_ext.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>__fwriting</CODE> function determines whether the stream |
| <VAR>stream</VAR> was last written to or whether it is opened write-only. In |
| this case the return value is nonzero, otherwise it is zero. |
| <br><br> This function is declared in <TT>stdio_ext.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fclose" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| This function causes <VAR>stream</VAR> to be closed and the connection to |
| the corresponding file to be broken. Any buffered output is written |
| and any buffered input is discarded. The <CODE>fclose</CODE> function returns |
| a value of <CODE>0</CODE> if the file was closed successfully, and <CODE>EOF</CODE> |
| if an error was detected. |
| <br><br> It is important to check for errors when you call <CODE>fclose</CODE> to close |
| an output stream, because real, everyday errors can be detected at this |
| time. For example, when <CODE>fclose</CODE> writes the remaining buffered |
| output, it might get an error because the disk is full. Even if you |
| know the buffer is empty, errors can still occur when closing a file if |
| you are using NFS. |
| <br><br> The function <CODE>fclose</CODE> is declared in <TT>stdio.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fcloseall" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| This function causes all open streams of the process to be closed and |
| the connection to corresponding files to be broken. All buffered data |
| is written and any buffered input is discarded. The <CODE>fcloseall</CODE> |
| function returns a value of <CODE>0</CODE> if all the files were closed |
| successfully, and <CODE>EOF</CODE> if an error was detected. |
| <br><br> This function should be used only in special situations, e.g., when an |
| error occurred and the program must be aborted. Normally each single |
| stream should be closed separately so that problems with individual |
| streams can be identified. It is also problematic since the standard |
| streams will also be closed. |
| <br><br> The function <CODE>fcloseall</CODE> is declared in <TT>stdio.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-flockfile" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>flockfile</CODE> function acquires the internal locking object |
| associated with the stream <VAR>stream</VAR>. This ensures that no other |
| thread can explicitly through <CODE>flockfile</CODE>/<CODE>ftrylockfile</CODE> or |
| implicit through a call of a stream function lock the stream. The |
| thread will block until the lock is acquired. An explicit call to |
| <CODE>funlockfile</CODE> has to be used to release the lock. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-ftrylockfile" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>ftrylockfile</CODE> function tries to acquire the internal locking |
| object associated with the stream <VAR>stream</VAR> just like |
| <CODE>flockfile</CODE>. But unlike <CODE>flockfile</CODE> this function does not |
| block if the lock is not available. <CODE>ftrylockfile</CODE> returns zero if |
| the lock was successfully acquired. Otherwise the stream is locked by |
| another thread. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-funlockfile" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>funlockfile</CODE> function releases the internal locking object of |
| the stream <VAR>stream</VAR>. The stream must have been locked before by a |
| call to <CODE>flockfile</CODE> or a successful call of <CODE>ftrylockfile</CODE>. |
| The implicit locking performed by the stream operations do not count. |
| The <CODE>funlockfile</CODE> function does not return an error status and the |
| behavior of a call for a stream which is not locked by the current |
| thread is undefined. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-__fsetlocking" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| <parameter content="int type"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio_ext.h"/> |
| </headers> |
| <synopsis> |
| <br><br> The <CODE>__fsetlocking</CODE> function can be used to select whether the |
| stream operations will implicitly acquire the locking object of the |
| stream <VAR>stream</VAR>. By default this is done but it can be disabled and |
| reinstated using this function. There are three values defined for the |
| <VAR>type</VAR> parameter. |
| <br><br> <DL> |
| |
| <DT><CODE>FSETLOCKING_INTERNAL</CODE> |
| <DD> |
| The stream <CODE>stream</CODE> will from now on use the default internal |
| locking. Every stream operation with exception of the <CODE>_unlocked</CODE> |
| variants will implicitly lock the stream. |
| <br><br> <DT><CODE>FSETLOCKING_BYCALLER</CODE> |
| <DD> |
| After the <CODE>__fsetlocking</CODE> function returns the user is responsible |
| for locking the stream. None of the stream operations will implicitly |
| do this anymore until the state is set back to |
| <CODE>FSETLOCKING_INTERNAL</CODE>. |
| <br><br> <DT><CODE>FSETLOCKING_QUERY</CODE> |
| <DD> |
| <CODE>__fsetlocking</CODE> only queries the current locking state of the |
| stream. The return value will be <CODE>FSETLOCKING_INTERNAL</CODE> or |
| <CODE>FSETLOCKING_BYCALLER</CODE> depending on the state. |
| </DL> |
| <br><br> The return value of <CODE>__fsetlocking</CODE> is either |
| <CODE>FSETLOCKING_INTERNAL</CODE> or <CODE>FSETLOCKING_BYCALLER</CODE> depending on |
| the state of the stream before the call. |
| <br><br> This function and the values for the <VAR>type</VAR> parameter are declared |
| in <TT>stdio_ext.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fwide" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| <parameter content="int mode"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| <br><br> The <CODE>fwide</CODE> function can be used to set and query the state of the |
| orientation of the stream <VAR>stream</VAR>. If the <VAR>mode</VAR> parameter has |
| a positive value the streams get wide oriented, for negative values |
| narrow oriented. It is not possible to overwrite previous orientations |
| with <CODE>fwide</CODE>. I.e., if the stream <VAR>stream</VAR> was already |
| oriented before the call nothing is done. |
| <br><br> If <VAR>mode</VAR> is zero the current orientation state is queried and |
| nothing is changed. |
| <br><br> The <CODE>fwide</CODE> function returns a negative value, zero, or a positive |
| value if the stream is narrow, not at all, or wide oriented |
| respectively. |
| <br><br> This function was introduced in Amendment 1 to ISO C90 and is |
| declared in <TT>wchar.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fputc" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int c"/> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>fputc</CODE> function converts the character <VAR>c</VAR> to type |
| <CODE>unsigned char</CODE>, and writes it to the stream <VAR>stream</VAR>. |
| <CODE>EOF</CODE> is returned if a write error occurs; otherwise the |
| character <VAR>c</VAR> is returned. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fputwc" type="function"> |
| <function returntype="wint_t"> |
| <prototype> |
| <parameter content="wchar_t wc"/> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>fputwc</CODE> function writes the wide character <VAR>wc</VAR> to the |
| stream <VAR>stream</VAR>. <CODE>WEOF</CODE> is returned if a write error occurs; |
| otherwise the character <VAR>wc</VAR> is returned. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fputc_unlocked" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int c"/> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>fputc_unlocked</CODE> function is equivalent to the <CODE>fputc</CODE> |
| function except that it does not implicitly lock the stream. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fputwc_unlocked" type="function"> |
| <function returntype="wint_t"> |
| <prototype> |
| <parameter content="wint_t wc"/> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>fputwc_unlocked</CODE> function is equivalent to the <CODE>fputwc</CODE> |
| function except that it does not implicitly lock the stream. |
| <br><br> This function is a GNU extension. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-putc" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int c"/> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| This is just like <CODE>fputc</CODE>, except that most systems implement it as |
| a macro, making it faster. One consequence is that it may evaluate the |
| <VAR>stream</VAR> argument more than once, which is an exception to the |
| general rule for macros. <CODE>putc</CODE> is usually the best function to |
| use for writing a single character. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-putwc" type="function"> |
| <function returntype="wint_t"> |
| <prototype> |
| <parameter content="wchar_t wc"/> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| This is just like <CODE>fputwc</CODE>, except that it can be implement as |
| a macro, making it faster. One consequence is that it may evaluate the |
| <VAR>stream</VAR> argument more than once, which is an exception to the |
| general rule for macros. <CODE>putwc</CODE> is usually the best function to |
| use for writing a single wide character. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-putc_unlocked" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int c"/> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>putc_unlocked</CODE> function is equivalent to the <CODE>putc</CODE> |
| function except that it does not implicitly lock the stream. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-putwc_unlocked" type="function"> |
| <function returntype="wint_t"> |
| <prototype> |
| <parameter content="wchar_t wc"/> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>putwc_unlocked</CODE> function is equivalent to the <CODE>putwc</CODE> |
| function except that it does not implicitly lock the stream. |
| <br><br> This function is a GNU extension. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-putchar" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int c"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>putchar</CODE> function is equivalent to <CODE>putc</CODE> with |
| <CODE>stdout</CODE> as the value of the <VAR>stream</VAR> argument. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-putwchar" type="function"> |
| <function returntype="wint_t"> |
| <prototype> |
| <parameter content="wchar_t wc"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>putwchar</CODE> function is equivalent to <CODE>putwc</CODE> with |
| <CODE>stdout</CODE> as the value of the <VAR>stream</VAR> argument. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-putchar_unlocked" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int c"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>putchar_unlocked</CODE> function is equivalent to the <CODE>putchar</CODE> |
| function except that it does not implicitly lock the stream. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-putwchar_unlocked" type="function"> |
| <function returntype="wint_t"> |
| <prototype> |
| <parameter content="wchar_t wc"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>putwchar_unlocked</CODE> function is equivalent to the <CODE>putwchar</CODE> |
| function except that it does not implicitly lock the stream. |
| <br><br> This function is a GNU extension. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fputs" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *s"/> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| The function <CODE>fputs</CODE> writes the string <VAR>s</VAR> to the stream |
| <VAR>stream</VAR>. The terminating null character is not written. |
| This function does <EM>not</EM> add a newline character, either. |
| It outputs only the characters in the string. |
| <br><br> This function returns <CODE>EOF</CODE> if a write error occurs, and otherwise |
| a non-negative value. |
| <br><br> For example: |
| <br><br> <pre><br> |
| fputs ("Are ", stdout);<br> |
| fputs ("you ", stdout);<br> |
| fputs ("hungry?\n", stdout);<br> |
| </pre> |
| <br><br> |
| outputs the text <samp>Are you hungry?</samp> followed by a newline. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fputws" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const wchar_t *ws"/> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| The function <CODE>fputws</CODE> writes the wide character string <VAR>ws</VAR> to |
| the stream <VAR>stream</VAR>. The terminating null character is not written. |
| This function does <EM>not</EM> add a newline character, either. It |
| outputs only the characters in the string. |
| <br><br> This function returns <CODE>WEOF</CODE> if a write error occurs, and otherwise |
| a non-negative value. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fputs_unlocked" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *s"/> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>fputs_unlocked</CODE> function is equivalent to the <CODE>fputs</CODE> |
| function except that it does not implicitly lock the stream. |
| <br><br> This function is a GNU extension. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fputws_unlocked" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const wchar_t *ws"/> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>fputws_unlocked</CODE> function is equivalent to the <CODE>fputws</CODE> |
| function except that it does not implicitly lock the stream. |
| <br><br> This function is a GNU extension. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-puts" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *s"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>puts</CODE> function writes the string <VAR>s</VAR> to the stream |
| <CODE>stdout</CODE> followed by a newline. The terminating null character of |
| the string is not written. (Note that <CODE>fputs</CODE> does <EM>not</EM> |
| write a newline as this function does.) |
| <br><br> <CODE>puts</CODE> is the most convenient function for printing simple |
| messages. For example: |
| <br><br> <pre><br> |
| puts ("This is a message.");<br> |
| </pre> |
| <br><br> |
| outputs the text <samp>This is a message.</samp> followed by a newline. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-putw" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int w"/> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| This function writes the word <VAR>w</VAR> (that is, an <CODE>int</CODE>) to |
| <VAR>stream</VAR>. It is provided for compatibility with SVID, but we |
| recommend you use <CODE>fwrite</CODE> instead . |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fgetc" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| This function reads the next character as an <CODE>unsigned char</CODE> from |
| the stream <VAR>stream</VAR> and returns its value, converted to an |
| <CODE>int</CODE>. If an end-of-file condition or read error occurs, |
| <CODE>EOF</CODE> is returned instead. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fgetwc" type="function"> |
| <function returntype="wint_t"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| This function reads the next wide character from the stream <VAR>stream</VAR> |
| and returns its value. If an end-of-file condition or read error |
| occurs, <CODE>WEOF</CODE> is returned instead. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fgetc_unlocked" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>fgetc_unlocked</CODE> function is equivalent to the <CODE>fgetc</CODE> |
| function except that it does not implicitly lock the stream. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fgetwc_unlocked" type="function"> |
| <function returntype="wint_t"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>fgetwc_unlocked</CODE> function is equivalent to the <CODE>fgetwc</CODE> |
| function except that it does not implicitly lock the stream. |
| <br><br> This function is a GNU extension. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getc" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| This is just like <CODE>fgetc</CODE>, except that it is permissible (and |
| typical) for it to be implemented as a macro that evaluates the |
| <VAR>stream</VAR> argument more than once. <CODE>getc</CODE> is often highly |
| optimized, so it is usually the best function to use to read a single |
| character. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getwc" type="function"> |
| <function returntype="wint_t"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| This is just like <CODE>fgetwc</CODE>, except that it is permissible for it to |
| be implemented as a macro that evaluates the <VAR>stream</VAR> argument more |
| than once. <CODE>getwc</CODE> can be highly optimized, so it is usually the |
| best function to use to read a single wide character. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getc_unlocked" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>getc_unlocked</CODE> function is equivalent to the <CODE>getc</CODE> |
| function except that it does not implicitly lock the stream. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getwc_unlocked" type="function"> |
| <function returntype="wint_t"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>getwc_unlocked</CODE> function is equivalent to the <CODE>getwc</CODE> |
| function except that it does not implicitly lock the stream. |
| <br><br> This function is a GNU extension. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getchar" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>getchar</CODE> function is equivalent to <CODE>getc</CODE> with <CODE>stdin</CODE> |
| as the value of the <VAR>stream</VAR> argument. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getwchar" type="function"> |
| <function returntype="wint_t"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>getwchar</CODE> function is equivalent to <CODE>getwc</CODE> with <CODE>stdin</CODE> |
| as the value of the <VAR>stream</VAR> argument. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getchar_unlocked" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>getchar_unlocked</CODE> function is equivalent to the <CODE>getchar</CODE> |
| function except that it does not implicitly lock the stream. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getwchar_unlocked" type="function"> |
| <function returntype="wint_t"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>getwchar_unlocked</CODE> function is equivalent to the <CODE>getwchar</CODE> |
| function except that it does not implicitly lock the stream. |
| <br><br> This function is a GNU extension. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getw" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| This function reads a word (that is, an <CODE>int</CODE>) from <VAR>stream</VAR>. |
| It's provided for compatibility with SVID. We recommend you use |
| <CODE>fread</CODE> instead. Unlike <CODE>getc</CODE>, |
| any <CODE>int</CODE> value could be a valid result. <CODE>getw</CODE> returns |
| <CODE>EOF</CODE> when it encounters end-of-file or an error, but there is no |
| way to distinguish this from an input word with value -1. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getline" type="function"> |
| <function returntype="ssize_t"> |
| <prototype> |
| <parameter content="char **lineptr"/> |
| <parameter content="size_t *n"/> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| This function reads an entire line from <VAR>stream</VAR>, storing the text |
| (including the newline and a terminating null character) in a buffer |
| and storing the buffer address in <CODE>*<VAR>lineptr</VAR></CODE>. |
| <br><br> Before calling <CODE>getline</CODE>, you should place in <CODE>*<VAR>lineptr</VAR></CODE> |
| the address of a buffer <CODE>*<VAR>n</VAR></CODE> bytes long, allocated with |
| <CODE>malloc</CODE>. If this buffer is long enough to hold the line, |
| <CODE>getline</CODE> stores the line in this buffer. Otherwise, |
| <CODE>getline</CODE> makes the buffer bigger using <CODE>realloc</CODE>, storing the |
| new buffer address back in <CODE>*<VAR>lineptr</VAR></CODE> and the increased size |
| back in <CODE>*<VAR>n</VAR></CODE>. |
| . |
| <br><br> If you set <CODE>*<VAR>lineptr</VAR></CODE> to a null pointer, and <CODE>*<VAR>n</VAR></CODE> |
| to zero, before the call, then <CODE>getline</CODE> allocates the initial |
| buffer for you by calling <CODE>malloc</CODE>. |
| <br><br> In either case, when <CODE>getline</CODE> returns, <CODE>*<VAR>lineptr</VAR></CODE> is |
| a <CODE>char *</CODE> which points to the text of the line. |
| <br><br> When <CODE>getline</CODE> is successful, it returns the number of characters |
| read (including the newline, but not including the terminating null). |
| This value enables you to distinguish null characters that are part of |
| the line from the null character inserted as a terminator. |
| <br><br> This function is a GNU extension, but it is the recommended way to read |
| lines from a stream. The alternative standard functions are unreliable. |
| <br><br> If an error occurs or end of file is reached without any bytes read, |
| <CODE>getline</CODE> returns <CODE>-1</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-getdelim" type="function"> |
| <function returntype="ssize_t"> |
| <prototype> |
| <parameter content="char **lineptr"/> |
| <parameter content="size_t *n"/> |
| <parameter content="int delimiter"/> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| This function is like <CODE>getline</CODE> except that the character which |
| tells it to stop reading is not necessarily newline. The argument |
| <VAR>delimiter</VAR> specifies the delimiter character; <CODE>getdelim</CODE> keeps |
| reading until it sees that character (or end of file). |
| <br><br> The text is stored in <VAR>lineptr</VAR>, including the delimiter character |
| and a terminating null. Like <CODE>getline</CODE>, <CODE>getdelim</CODE> makes |
| <VAR>lineptr</VAR> bigger if it isn't big enough. |
| <br><br> <CODE>getline</CODE> is in fact implemented in terms of <CODE>getdelim</CODE>, just |
| like this: |
| <br><br> <pre><br> |
| ssize_t<br> |
| getline (char **lineptr, size_t *n, FILE *stream)<br> |
| {<br> |
| return getdelim (lineptr, n, '\n', stream);<br> |
| }<br> |
| </pre> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fgets" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="char *s"/> |
| <parameter content="int count"/> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>fgets</CODE> function reads characters from the stream <VAR>stream</VAR> |
| up to and including a newline character and stores them in the string |
| <VAR>s</VAR>, adding a null character to mark the end of the string. You |
| must supply <VAR>count</VAR> characters worth of space in <VAR>s</VAR>, but the |
| number of characters read is at most <VAR>count</VAR> 1. The extra |
| character space is used to hold the null character at the end of the |
| string. |
| <br><br> If the system is already at end of file when you call <CODE>fgets</CODE>, then |
| the contents of the array <VAR>s</VAR> are unchanged and a null pointer is |
| returned. A null pointer is also returned if a read error occurs. |
| Otherwise, the return value is the pointer <VAR>s</VAR>. |
| <br><br> Warning: If the input data has a null character, you can't tell. |
| So don't use <CODE>fgets</CODE> unless you know the data cannot contain a null. |
| Don't use it to read files edited by the user because, if the user inserts |
| a null character, you should either handle it properly or print a clear |
| error message. We recommend using <CODE>getline</CODE> instead of <CODE>fgets</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fgetws" type="function"> |
| <function returntype="wchar_t *"> |
| <prototype> |
| <parameter content="wchar_t *ws"/> |
| <parameter content="int count"/> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>fgetws</CODE> function reads wide characters from the stream |
| <VAR>stream</VAR> up to and including a newline character and stores them in |
| the string <VAR>ws</VAR>, adding a null wide character to mark the end of the |
| string. You must supply <VAR>count</VAR> wide characters worth of space in |
| <VAR>ws</VAR>, but the number of characters read is at most <VAR>count</VAR> |
| 1. The extra character space is used to hold the null wide |
| character at the end of the string. |
| <br><br> If the system is already at end of file when you call <CODE>fgetws</CODE>, then |
| the contents of the array <VAR>ws</VAR> are unchanged and a null pointer is |
| returned. A null pointer is also returned if a read error occurs. |
| Otherwise, the return value is the pointer <VAR>ws</VAR>. |
| <br><br> Warning: If the input data has a null wide character (which are |
| null bytes in the input stream), you can't tell. So don't use |
| <CODE>fgetws</CODE> unless you know the data cannot contain a null. Don't use |
| it to read files edited by the user because, if the user inserts a null |
| character, you should either handle it properly or print a clear error |
| message. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fgets_unlocked" type="function"> |
| <function returntype="char *"> |
| <prototype> |
| <parameter content="char *s"/> |
| <parameter content="int count"/> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>fgets_unlocked</CODE> function is equivalent to the <CODE>fgets</CODE> |
| function except that it does not implicitly lock the stream. |
| <br><br> This function is a GNU extension. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fgetws_unlocked" type="function"> |
| <function returntype="wchar_t *"> |
| <prototype> |
| <parameter content="wchar_t *ws"/> |
| <parameter content="int count"/> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>fgetws_unlocked</CODE> function is equivalent to the <CODE>fgetws</CODE> |
| function except that it does not implicitly lock the stream. |
| <br><br> This function is a GNU extension. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-ungetc" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int c"/> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>ungetc</CODE> function pushes back the character <VAR>c</VAR> onto the |
| input stream <VAR>stream</VAR>. So the next input from <VAR>stream</VAR> will |
| read <VAR>c</VAR> before anything else. |
| <br><br> If <VAR>c</VAR> is <CODE>EOF</CODE>, <CODE>ungetc</CODE> does nothing and just returns |
| <CODE>EOF</CODE>. This lets you call <CODE>ungetc</CODE> with the return value of |
| <CODE>getc</CODE> without needing to check for an error from <CODE>getc</CODE>. |
| <br><br> The character that you push back doesn't have to be the same as the last |
| character that was actually read from the stream. In fact, it isn't |
| necessary to actually read any characters from the stream before |
| unreading them with <CODE>ungetc</CODE>! But that is a strange way to write a |
| program; usually <CODE>ungetc</CODE> is used only to unread a character that |
| was just read from the same stream. The GNU C library supports this |
| even on files opened in binary mode, but other systems might not. |
| <br><br> The GNU C library only supports one character of pushback---in other |
| words, it does not work to call <CODE>ungetc</CODE> twice without doing input |
| in between. Other systems might let you push back multiple characters; |
| then reading from the stream retrieves the characters in the reverse |
| order that they were pushed. |
| <br><br> Pushing back characters doesn't alter the file; only the internal |
| buffering for the stream is affected. If a file positioning function |
| (such as <CODE>fseek</CODE>, <CODE>fseeko</CODE> or <CODE>rewind</CODE>; ) is called, any pending pushed-back characters are |
| discarded. |
| <br><br> Unreading a character on a stream that is at end of file clears the |
| end-of-file indicator for the stream, because it makes the character of |
| input available. After you read that character, trying to read again |
| will encounter end of file. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-ungetwc" type="function"> |
| <function returntype="wint_t"> |
| <prototype> |
| <parameter content="wint_t wc"/> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>ungetwc</CODE> function behaves just like <CODE>ungetc</CODE> just that it |
| pushes back a wide character. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fread" type="function"> |
| <function returntype="size_t"> |
| <prototype> |
| <parameter content="void *data"/> |
| <parameter content="size_t size"/> |
| <parameter content="size_t count"/> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| This function reads up to <VAR>count</VAR> objects of size <VAR>size</VAR> into |
| the array <VAR>data</VAR>, from the stream <VAR>stream</VAR>. It returns the |
| number of objects actually read, which might be less than <VAR>count</VAR> if |
| a read error occurs or the end of the file is reached. This function |
| returns a value of zero (and doesn't read anything) if either <VAR>size</VAR> |
| or <VAR>count</VAR> is zero. |
| <br><br> If <CODE>fread</CODE> encounters end of file in the middle of an object, it |
| returns the number of complete objects read, and discards the partial |
| object. Therefore, the stream remains at the actual end of the file. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fread_unlocked" type="function"> |
| <function returntype="size_t"> |
| <prototype> |
| <parameter content="void *data"/> |
| <parameter content="size_t size"/> |
| <parameter content="size_t count"/> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>fread_unlocked</CODE> function is equivalent to the <CODE>fread</CODE> |
| function except that it does not implicitly lock the stream. |
| <br><br> This function is a GNU extension. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fwrite" type="function"> |
| <function returntype="size_t"> |
| <prototype> |
| <parameter content="const void *data"/> |
| <parameter content="size_t size"/> |
| <parameter content="size_t count"/> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| This function writes up to <VAR>count</VAR> objects of size <VAR>size</VAR> from |
| the array <VAR>data</VAR>, to the stream <VAR>stream</VAR>. The return value is |
| normally <VAR>count</VAR>, if the call succeeds. Any other value indicates |
| some sort of error, such as running out of space. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fwrite_unlocked" type="function"> |
| <function returntype="size_t"> |
| <prototype> |
| <parameter content="const void *data"/> |
| <parameter content="size_t size"/> |
| <parameter content="size_t count"/> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>fwrite_unlocked</CODE> function is equivalent to the <CODE>fwrite</CODE> |
| function except that it does not implicitly lock the stream. |
| <br><br> This function is a GNU extension. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-printf" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *template"/> |
| <parameter content="..."/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>printf</CODE> function prints the optional arguments under the |
| control of the template string <VAR>template</VAR> to the stream |
| <CODE>stdout</CODE>. It returns the number of characters printed, or a |
| negative value if there was an output error. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-wprintf" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const wchar_t *template"/> |
| <parameter content="..."/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>wprintf</CODE> function prints the optional arguments under the |
| control of the wide template string <VAR>template</VAR> to the stream |
| <CODE>stdout</CODE>. It returns the number of wide characters printed, or a |
| negative value if there was an output error. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fprintf" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| <parameter content="const char *template"/> |
| <parameter content="..."/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| This function is just like <CODE>printf</CODE>, except that the output is |
| written to the stream <VAR>stream</VAR> instead of <CODE>stdout</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fwprintf" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| <parameter content="const wchar_t *template"/> |
| <parameter content="..."/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| This function is just like <CODE>wprintf</CODE>, except that the output is |
| written to the stream <VAR>stream</VAR> instead of <CODE>stdout</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-sprintf" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="char *s"/> |
| <parameter content="const char *template"/> |
| <parameter content="..."/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| This is like <CODE>printf</CODE>, except that the output is stored in the character |
| array <VAR>s</VAR> instead of written to a stream. A null character is written |
| to mark the end of the string. |
| <br><br> The <CODE>sprintf</CODE> function returns the number of characters stored in |
| the array <VAR>s</VAR>, not including the terminating null character. |
| <br><br> The behavior of this function is undefined if copying takes place |
| between objects that overlap---for example, if <VAR>s</VAR> is also given |
| as an argument to be printed under control of the <samp>%s</samp> conversion. |
| . |
| <br><br> Warning: The <CODE>sprintf</CODE> function can be <h3>dangerous</h3> |
| because it can potentially output more characters than can fit in the |
| allocation size of the string <VAR>s</VAR>. Remember that the field width |
| given in a conversion specification is only a <EM>minimum</EM> value. |
| <br><br> To avoid this problem, you can use <CODE>snprintf</CODE> or <CODE>asprintf</CODE>, |
| described below. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-swprintf" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="wchar_t *s"/> |
| <parameter content="size_t size"/> |
| <parameter content="const wchar_t *template"/> |
| <parameter content="..."/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| This is like <CODE>wprintf</CODE>, except that the output is stored in the |
| wide character array <VAR>ws</VAR> instead of written to a stream. A null |
| wide character is written to mark the end of the string. The <VAR>size</VAR> |
| argument specifies the maximum number of characters to produce. The |
| trailing null character is counted towards this limit, so you should |
| allocate at least <VAR>size</VAR> wide characters for the string <VAR>ws</VAR>. |
| <br><br> The return value is the number of characters generated for the given |
| input, excluding the trailing null. If not all output fits into the |
| provided buffer a negative value is returned. You should try again with |
| a bigger output string. <EM>Note:</EM> this is different from how |
| <CODE>snprintf</CODE> handles this situation. |
| <br><br> Note that the corresponding narrow stream function takes fewer |
| parameters. <CODE>swprintf</CODE> in fact corresponds to the <CODE>snprintf</CODE> |
| function. Since the <CODE>sprintf</CODE> function can be dangerous and should |
| be avoided the ISO C committee refused to make the same mistake |
| again and decided to not define an function exactly corresponding to |
| <CODE>sprintf</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-snprintf" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="char *s"/> |
| <parameter content="size_t size"/> |
| <parameter content="const char *template"/> |
| <parameter content="..."/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>snprintf</CODE> function is similar to <CODE>sprintf</CODE>, except that |
| the <VAR>size</VAR> argument specifies the maximum number of characters to |
| produce. The trailing null character is counted towards this limit, so |
| you should allocate at least <VAR>size</VAR> characters for the string <VAR>s</VAR>. |
| <br><br> The return value is the number of characters which would be generated |
| for the given input, excluding the trailing null. If this value is |
| greater or equal to <VAR>size</VAR>, not all characters from the result have |
| been stored in <VAR>s</VAR>. You should try again with a bigger output |
| string. Here is an example of doing this: |
| <br><br> <pre><br> |
| <br> |
| /* Construct a message describing the value of a variable<br> |
| whose name is <VAR>name</VAR> and whose value is <VAR>value</VAR>. */<br> |
| char *<br> |
| make_message (char *name, char *value)<br> |
| {<br> |
| /* Guess we need no more than 100 chars of space. */<br> |
| int size = 100;<br> |
| char *buffer = (char *) xmalloc (size);<br> |
| int nchars;<br> |
| <br> |
| <br> |
| if (buffer == NULL)<br> |
| return NULL;<br> |
| <br><br> /* Try to print in the allocated space. */<br> |
| nchars = snprintf (buffer, size, "value of %s is %s",<br> |
| name, value);<br> |
| <br> |
| <br> |
| if (nchars >= size)<br> |
| {<br> |
| /* Reallocate buffer now that we know<br> |
| how much space is needed. */<br> |
| size = nchars + 1;<br> |
| buffer = (char *) xrealloc (buffer, size);<br> |
| <br><br> if (buffer != NULL)<br> |
| /* Try again. */<br> |
| snprintf (buffer, size, "value of %s is %s",<br> |
| name, value);<br> |
| }<br> |
| /* The last call worked, return the string. */<br> |
| return buffer;<br> |
| }<br> |
| <br> |
| </pre> |
| <br><br> In practice, it is often easier just to use <CODE>asprintf</CODE>, below. |
| <br><br> Attention: In versions of the GNU C library prior to 2.1 the |
| return value is the number of characters stored, not including the |
| terminating null; unless there was not enough space in <VAR>s</VAR> to |
| store the result in which case <CODE>-1</CODE> is returned. This was |
| changed in order to comply with the ISO C99 standard. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-asprintf" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="char **ptr"/> |
| <parameter content="const char *template"/> |
| <parameter content="..."/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to <CODE>sprintf</CODE>, except that it dynamically |
| allocates a string (as with <CODE>malloc</CODE>; ) to hold the output, instead of putting the output in a |
| buffer you allocate in advance. The <VAR>ptr</VAR> argument should be the |
| address of a <CODE>char *</CODE> object, and a successful call to |
| <CODE>asprintf</CODE> stores a pointer to the newly allocated string at that |
| location. |
| <br><br> The return value is the number of characters allocated for the buffer, or |
| less than zero if an error occurred. Usually this means that the buffer |
| could not be allocated. |
| <br><br> Here is how to use <CODE>asprintf</CODE> to get the same result as the |
| <CODE>snprintf</CODE> example, but more easily: |
| <br><br> <pre><br> |
| /* Construct a message describing the value of a variable<br> |
| whose name is <VAR>name</VAR> and whose value is <VAR>value</VAR>. */<br> |
| char *<br> |
| make_message (char *name, char *value)<br> |
| {<br> |
| char *result;<br> |
| if (asprintf (&result, "value of %s is %s", name, value) < 0)<br> |
| return NULL;<br> |
| return result;<br> |
| }<br> |
| </pre> |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-obstack_printf" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="struct obstack *obstack"/> |
| <parameter content="const char *template"/> |
| <parameter content="..."/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to <CODE>asprintf</CODE>, except that it uses the |
| obstack <VAR>obstack</VAR> to allocate the space. . |
| <br><br> The characters are written onto the end of the current object. |
| To get at them, you must finish the object with <CODE>obstack_finish</CODE> |
| . |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-vprintf" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *template"/> |
| <parameter content="va_list ap"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to <CODE>printf</CODE> except that, instead of taking |
| a variable number of arguments directly, it takes an argument list |
| pointer <VAR>ap</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-vwprintf" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const wchar_t *template"/> |
| <parameter content="va_list ap"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to <CODE>wprintf</CODE> except that, instead of taking |
| a variable number of arguments directly, it takes an argument list |
| pointer <VAR>ap</VAR>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-vfprintf" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| <parameter content="const char *template"/> |
| <parameter content="va_list ap"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| This is the equivalent of <CODE>fprintf</CODE> with the variable argument list |
| specified directly as for <CODE>vprintf</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-vfwprintf" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| <parameter content="const wchar_t *template"/> |
| <parameter content="va_list ap"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| This is the equivalent of <CODE>fwprintf</CODE> with the variable argument list |
| specified directly as for <CODE>vwprintf</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-vsprintf" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="char *s"/> |
| <parameter content="const char *template"/> |
| <parameter content="va_list ap"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| This is the equivalent of <CODE>sprintf</CODE> with the variable argument list |
| specified directly as for <CODE>vprintf</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-vswprintf" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="wchar_t *s"/> |
| <parameter content="size_t size"/> |
| <parameter content="const wchar_t *template"/> |
| <parameter content="va_list ap"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| This is the equivalent of <CODE>swprintf</CODE> with the variable argument list |
| specified directly as for <CODE>vwprintf</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-vsnprintf" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="char *s"/> |
| <parameter content="size_t size"/> |
| <parameter content="const char *template"/> |
| <parameter content="va_list ap"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| This is the equivalent of <CODE>snprintf</CODE> with the variable argument list |
| specified directly as for <CODE>vprintf</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-vasprintf" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="char **ptr"/> |
| <parameter content="const char *template"/> |
| <parameter content="va_list ap"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>vasprintf</CODE> function is the equivalent of <CODE>asprintf</CODE> with the |
| variable argument list specified directly as for <CODE>vprintf</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-obstack_vprintf" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="struct obstack *obstack"/> |
| <parameter content="const char *template"/> |
| <parameter content="va_list ap"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>obstack_vprintf</CODE> function is the equivalent of |
| <CODE>obstack_printf</CODE> with the variable argument list specified directly |
| as for <CODE>vprintf</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-parse_printf_format" type="function"> |
| <function returntype="size_t"> |
| <prototype> |
| <parameter content="const char *template"/> |
| <parameter content="size_t n"/> |
| <parameter content="int *argtypes"/> |
| </prototype> |
| <headers> |
| <header filename = "printf.h"/> |
| </headers> |
| <synopsis> |
| This function returns information about the number and types of |
| arguments expected by the <CODE>printf</CODE> template string <VAR>template</VAR>. |
| The information is stored in the array <VAR>argtypes</VAR>; each element of |
| this array describes one argument. This information is encoded using |
| the various <samp>PA_</samp> macros, listed below. |
| <br><br> The argument <VAR>n</VAR> specifies the number of elements in the array |
| <VAR>argtypes</VAR>. This is the maximum number of elements that |
| <CODE>parse_printf_format</CODE> will try to write. |
| <br><br> <CODE>parse_printf_format</CODE> returns the total number of arguments required |
| by <VAR>template</VAR>. If this number is greater than <VAR>n</VAR>, then the |
| information returned describes only the first <VAR>n</VAR> arguments. If you |
| want information about additional arguments, allocate a bigger |
| array and call <CODE>parse_printf_format</CODE> again. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-register_printf_function" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int spec"/> |
| <parameter content="printf_function handler-function"/> |
| <parameter content="printf_arginfo_function arginfo-function"/> |
| </prototype> |
| <headers> |
| <header filename = "printf.h"/> |
| </headers> |
| <synopsis> |
| This function defines the conversion specifier character <VAR>spec</VAR>. |
| Thus, if <VAR>spec</VAR> is <CODE>'Y'</CODE>, it defines the conversion <samp>%Y</samp>. |
| You can redefine the built-in conversions like <samp>%s</samp>, but flag |
| characters like <samp>#</samp> and type modifiers like <samp>l</samp> can never be |
| used as conversions; calling <CODE>register_printf_function</CODE> for those |
| characters has no effect. It is advisable not to use lowercase letters, |
| since the ISO C standard warns that additional lowercase letters may be |
| standardized in future editions of the standard. |
| <br><br> The <VAR>handler-function</VAR> is the function called by <CODE>printf</CODE> and |
| friends when this conversion appears in a template string. |
| , for information about how to define |
| a function to pass as this argument. If you specify a null pointer, any |
| existing handler function for <VAR>spec</VAR> is removed. |
| <br><br> The <VAR>arginfo-function</VAR> is the function called by |
| <CODE>parse_printf_format</CODE> when this conversion appears in a |
| template string. , for information |
| about this. |
| <br><br> |
| <br><br> Attention: In the GNU C library versions before 2.0 the |
| <VAR>arginfo-function</VAR> function did not need to be installed unless |
| the user used the <CODE>parse_printf_format</CODE> function. This has changed. |
| Now a call to any of the <CODE>printf</CODE> functions will call this |
| function when this format specifier appears in the format string. |
| <br><br> The return value is <CODE>0</CODE> on success, and <CODE>-1</CODE> on failure |
| (which occurs if <VAR>spec</VAR> is out of range). |
| <br><br> You can redefine the standard output conversions, but this is probably |
| not a good idea because of the potential for confusion. Library routines |
| written by other people could break if you do this. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="struct-printf_info" type="struct"> |
| <structure> |
| <synopsis> |
| This structure is used to pass information about the options appearing |
| in an instance of a conversion specifier in a <CODE>printf</CODE> template |
| string to the handler and arginfo functions for that specifier. It |
| contains the following members: |
| <br><br> |
| </synopsis> |
| <elements> |
| <element content="int prec"> |
| <synopsis> |
| This is the precision specified. The value is <CODE>-1</CODE> if no precision |
| was specified. If the precision was given as <samp>*</samp>, the |
| <CODE>printf_info</CODE> 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 <CODE>INT_MIN</CODE>, since the |
| actual value is not known. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="int width"> |
| <synopsis> |
| This is the minimum field width specified. The value is <CODE>0</CODE> if no |
| width was specified. If the field width was given as <samp>*</samp>, the |
| <CODE>printf_info</CODE> 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 <CODE>INT_MIN</CODE>, since the |
| actual value is not known. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="wchar_t spec"> |
| <synopsis> |
| 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><br> |
| </synopsis> |
| </element> |
| <element content="unsigned int is_long_double"> |
| <synopsis> |
| This is a boolean that is true if the <samp>L</samp>, <samp>ll</samp>, or <samp>q</samp> |
| type modifier was specified. For integer conversions, this indicates |
| <CODE>long long int</CODE>, as opposed to <CODE>long double</CODE> for floating |
| point conversions. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="unsigned int is_char"> |
| <synopsis> |
| This is a boolean that is true if the <samp>hh</samp> type modifier was specified. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="unsigned int is_short"> |
| <synopsis> |
| This is a boolean that is true if the <samp>h</samp> type modifier was specified. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="unsigned int is_long"> |
| <synopsis> |
| This is a boolean that is true if the <samp>l</samp> type modifier was specified. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="unsigned int alt"> |
| <synopsis> |
| This is a boolean that is true if the <samp>#</samp> flag was specified. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="unsigned int space"> |
| <synopsis> |
| This is a boolean that is true if the <samp> </samp> flag was specified. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="unsigned int left"> |
| <synopsis> |
| This is a boolean that is true if the <samp>-</samp> flag was specified. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="unsigned int showsign"> |
| <synopsis> |
| This is a boolean that is true if the <samp>+</samp> flag was specified. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="unsigned int group"> |
| <synopsis> |
| This is a boolean that is true if the <samp>'</samp> flag was specified. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="unsigned int extra"> |
| <synopsis> |
| 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 <CODE>printf</CODE> function this variable always contains the value |
| <CODE>0</CODE>. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="unsigned int wide"> |
| <synopsis> |
| This flag is set if the stream is wide oriented. |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="dtype-printf_function" type="dtype"> |
| <structure> |
| </structure> |
| </construct> |
| <construct id="dtype-printf_arginfo_function" type="dtype"> |
| <structure> |
| </structure> |
| </construct> |
| <construct id="function-printf_size" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="FILE *fp"/> |
| <parameter content="const struct printf_info *info"/> |
| <parameter content="const void *const *args"/> |
| </prototype> |
| <headers> |
| <header filename = "printf.h"/> |
| </headers> |
| <synopsis> |
| Print a given floating point number as for the format <CODE>%f</CODE> except |
| that there is a postfix character indicating the divisor for the |
| number to make this less than 1000. There are two possible divisors: |
| powers of 1024 or powers of 1000. Which one is used depends on the |
| format character specified while registered this handler. If the |
| character is of lower case, 1024 is used. For upper case characters, |
| 1000 is used. |
| <br><br> The postfix tag corresponds to bytes, kilobytes, megabytes, gigabytes, |
| etc. The full table is: |
| <br><br> |
| <DL> |
| <DT><pre>low Multiplier From Upper Multiplier</pre> |
| <DD><br> <DT><pre>' ' 1 ' ' 1</pre> |
| <DD><br> <DT><pre>k 2^10 (1024) kilo K 10^3 (1000)</pre> |
| <DD><br> <DT><pre>m 2^20 mega M 10^6</pre> |
| <DD><br> <DT><pre>g 2^30 giga G 10^9</pre> |
| <DD><br> <DT><pre>t 2^40 tera T 10^12</pre> |
| <DD><br> <DT><pre>p 2^50 peta P 10^15</pre> |
| <DD><br> <DT><pre>e 2^60 exa E 10^18</pre> |
| <DD><br> <DT><pre>z 2^70 zetta Z 10^21</pre> |
| <DD><br> <DT><pre>y 2^80 yotta Y 10^24</pre> |
| <DD><br> </DL> |
| |
| |
| <br><br> The default precision is 3, i.e., 1024 is printed with a lower-case |
| format character as if it were <CODE>%.3fk</CODE> and will yield <CODE>1.000k</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-printf_size_info" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const struct printf_info *info"/> |
| <parameter content="size_t n"/> |
| <parameter content="int *argtypes"/> |
| </prototype> |
| <headers> |
| <header filename = "printf.h"/> |
| </headers> |
| <synopsis> |
| This function will return in <VAR>argtypes</VAR> the information about the |
| used parameters in the way the <CODE>vfprintf</CODE> implementation expects |
| it. The format always takes one argument. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-scanf" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *template"/> |
| <parameter content="..."/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>scanf</CODE> function reads formatted input from the stream |
| <CODE>stdin</CODE> under the control of the template string <VAR>template</VAR>. |
| The optional arguments are pointers to the places which receive the |
| resulting values. |
| <br><br> The return value is normally the number of successful assignments. If |
| an end-of-file condition is detected before any matches are performed, |
| including matches against whitespace and literal characters in the |
| template, then <CODE>EOF</CODE> is returned. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-wscanf" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const wchar_t *template"/> |
| <parameter content="..."/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>wscanf</CODE> function reads formatted input from the stream |
| <CODE>stdin</CODE> under the control of the template string <VAR>template</VAR>. |
| The optional arguments are pointers to the places which receive the |
| resulting values. |
| <br><br> The return value is normally the number of successful assignments. If |
| an end-of-file condition is detected before any matches are performed, |
| including matches against whitespace and literal characters in the |
| template, then <CODE>WEOF</CODE> is returned. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fscanf" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| <parameter content="const char *template"/> |
| <parameter content="..."/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| This function is just like <CODE>scanf</CODE>, except that the input is read |
| from the stream <VAR>stream</VAR> instead of <CODE>stdin</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fwscanf" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| <parameter content="const wchar_t *template"/> |
| <parameter content="..."/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| This function is just like <CODE>wscanf</CODE>, except that the input is read |
| from the stream <VAR>stream</VAR> instead of <CODE>stdin</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-sscanf" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *s"/> |
| <parameter content="const char *template"/> |
| <parameter content="..."/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| This is like <CODE>scanf</CODE>, except that the characters are taken from the |
| null-terminated string <VAR>s</VAR> instead of from a stream. Reaching the |
| end of the string is treated as an end-of-file condition. |
| <br><br> The behavior of this function is undefined if copying takes place |
| between objects that overlap---for example, if <VAR>s</VAR> is also given |
| as an argument to receive a string read under control of the <samp>%s</samp>, |
| <samp>%S</samp>, or <samp>%[</samp> conversion. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-swscanf" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const wchar_t *ws"/> |
| <parameter content="const char *template"/> |
| <parameter content="..."/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| This is like <CODE>wscanf</CODE>, except that the characters are taken from the |
| null-terminated string <VAR>ws</VAR> instead of from a stream. Reaching the |
| end of the string is treated as an end-of-file condition. |
| <br><br> The behavior of this function is undefined if copying takes place |
| between objects that overlap---for example, if <VAR>ws</VAR> is also given as |
| an argument to receive a string read under control of the <samp>%s</samp>, |
| <samp>%S</samp>, or <samp>%[</samp> conversion. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-vscanf" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *template"/> |
| <parameter content="va_list ap"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to <CODE>scanf</CODE>, but instead of taking |
| a variable number of arguments directly, it takes an argument list |
| pointer <VAR>ap</VAR> of type <CODE>va_list</CODE> . |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-vwscanf" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const wchar_t *template"/> |
| <parameter content="va_list ap"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to <CODE>wscanf</CODE>, but instead of taking |
| a variable number of arguments directly, it takes an argument list |
| pointer <VAR>ap</VAR> of type <CODE>va_list</CODE> . |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-vfscanf" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| <parameter content="const char *template"/> |
| <parameter content="va_list ap"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| This is the equivalent of <CODE>fscanf</CODE> with the variable argument list |
| specified directly as for <CODE>vscanf</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-vfwscanf" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| <parameter content="const wchar_t *template"/> |
| <parameter content="va_list ap"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| This is the equivalent of <CODE>fwscanf</CODE> with the variable argument list |
| specified directly as for <CODE>vwscanf</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-vsscanf" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const char *s"/> |
| <parameter content="const char *template"/> |
| <parameter content="va_list ap"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| This is the equivalent of <CODE>sscanf</CODE> with the variable argument list |
| specified directly as for <CODE>vscanf</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-vswscanf" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="const wchar_t *s"/> |
| <parameter content="const wchar_t *template"/> |
| <parameter content="va_list ap"/> |
| </prototype> |
| <headers> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| This is the equivalent of <CODE>swscanf</CODE> with the variable argument list |
| specified directly as for <CODE>vwscanf</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-feof" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| <header filename = "wchar.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>feof</CODE> function returns nonzero if and only if the end-of-file |
| indicator for the stream <VAR>stream</VAR> is set. |
| <br><br> This symbol is declared in <TT>stdio.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-feof_unlocked" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>feof_unlocked</CODE> function is equivalent to the <CODE>feof</CODE> |
| function except that it does not implicitly lock the stream. |
| <br><br> This function is a GNU extension. |
| <br><br> This symbol is declared in <TT>stdio.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-ferror" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>ferror</CODE> function returns nonzero if and only if the error |
| indicator for the stream <VAR>stream</VAR> is set, indicating that an error |
| has occurred on a previous operation on the stream. |
| <br><br> This symbol is declared in <TT>stdio.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-ferror_unlocked" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>ferror_unlocked</CODE> function is equivalent to the <CODE>ferror</CODE> |
| function except that it does not implicitly lock the stream. |
| <br><br> This function is a GNU extension. |
| <br><br> This symbol is declared in <TT>stdio.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-clearerr" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| This function clears the end-of-file and error indicators for the |
| stream <VAR>stream</VAR>. |
| <br><br> The file positioning functions also clear the |
| end-of-file indicator for the stream. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-clearerr_unlocked" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>clearerr_unlocked</CODE> function is equivalent to the <CODE>clearerr</CODE> |
| function except that it does not implicitly lock the stream. |
| <br><br> This function is a GNU extension. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-ftell" type="function"> |
| <function returntype="long int"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| This function returns the current file position of the stream |
| <VAR>stream</VAR>. |
| <br><br> This function can fail if the stream doesn't support file positioning, |
| or if the file position can't be represented in a <CODE>long int</CODE>, and |
| possibly for other reasons as well. If a failure occurs, a value of |
| <CODE>-1</CODE> is returned. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-ftello" type="function"> |
| <function returntype="off_t"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>ftello</CODE> function is similar to <CODE>ftell</CODE>, except that it |
| returns a value of type <CODE>off_t</CODE>. Systems which support this type |
| use it to describe all file positions, unlike the POSIX specification |
| which uses a long int. The two are not necessarily the same size. |
| Therefore, using ftell can lead to problems if the implementation is |
| written on top of a POSIX compliant low-level I/O implementation, and using |
| <CODE>ftello</CODE> is preferable whenever it is available. |
| <br><br> If this function fails it returns <CODE>(off_t) -1</CODE>. This can happen due |
| to missing support for file positioning or internal errors. Otherwise |
| the return value is the current file position. |
| <br><br> The function is an extension defined in the Unix Single Specification |
| version 2. |
| <br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> on a |
| 32 bit system this function is in fact <CODE>ftello64</CODE>. I.e., the |
| LFS interface transparently replaces the old interface. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-ftello64" type="function"> |
| <function returntype="off64_t"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to <CODE>ftello</CODE> with the only difference that |
| the return value is of type <CODE>off64_t</CODE>. This also requires that the |
| stream <VAR>stream</VAR> was opened using either <CODE>fopen64</CODE>, |
| <CODE>freopen64</CODE>, or <CODE>tmpfile64</CODE> since otherwise the underlying |
| file operations to position the file pointer beyond the 2^31 |
| bytes limit might fail. |
| <br><br> If the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> on a 32 |
| bits machine this function is available under the name <CODE>ftello</CODE> |
| and so transparently replaces the old interface. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fseek" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| <parameter content="long int offset"/> |
| <parameter content="int whence"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>fseek</CODE> function is used to change the file position of the |
| stream <VAR>stream</VAR>. The value of <VAR>whence</VAR> must be one of the |
| constants <CODE>SEEK_SET</CODE>, <CODE>SEEK_CUR</CODE>, or <CODE>SEEK_END</CODE>, to |
| indicate whether the <VAR>offset</VAR> is relative to the beginning of the |
| file, the current file position, or the end of the file, respectively. |
| <br><br> This function returns a value of zero if the operation was successful, |
| and a nonzero value to indicate failure. A successful call also clears |
| the end-of-file indicator of <VAR>stream</VAR> and discards any characters |
| that were ``pushed back'' by the use of <CODE>ungetc</CODE>. |
| <br><br> <CODE>fseek</CODE> either flushes any buffered output before setting the file |
| position or else remembers it so it will be written later in its proper |
| place in the file. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fseeko" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| <parameter content="off_t offset"/> |
| <parameter content="int whence"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to <CODE>fseek</CODE> but it corrects a problem with |
| <CODE>fseek</CODE> in a system with POSIX types. Using a value of type |
| <CODE>long int</CODE> for the offset is not compatible with POSIX. |
| <CODE>fseeko</CODE> uses the correct type <CODE>off_t</CODE> for the <VAR>offset</VAR> |
| parameter. |
| <br><br> For this reason it is a good idea to prefer <CODE>ftello</CODE> whenever it is |
| available since its functionality is (if different at all) closer the |
| underlying definition. |
| <br><br> The functionality and return value is the same as for <CODE>fseek</CODE>. |
| <br><br> The function is an extension defined in the Unix Single Specification |
| version 2. |
| <br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> on a |
| 32 bit system this function is in fact <CODE>fseeko64</CODE>. I.e., the |
| LFS interface transparently replaces the old interface. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fseeko64" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| <parameter content="off64_t offset"/> |
| <parameter content="int whence"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to <CODE>fseeko</CODE> with the only difference that |
| the <VAR>offset</VAR> parameter is of type <CODE>off64_t</CODE>. This also |
| requires that the stream <VAR>stream</VAR> was opened using either |
| <CODE>fopen64</CODE>, <CODE>freopen64</CODE>, or <CODE>tmpfile64</CODE> since otherwise |
| the underlying file operations to position the file pointer beyond the |
| 2^31 bytes limit might fail. |
| <br><br> If the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> on a 32 |
| bits machine this function is available under the name <CODE>fseeko</CODE> |
| and so transparently replaces the old interface. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-rewind" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>rewind</CODE> function positions the stream <VAR>stream</VAR> at the |
| beginning of the file. It is equivalent to calling <CODE>fseek</CODE> or |
| <CODE>fseeko</CODE> on the <VAR>stream</VAR> with an <VAR>offset</VAR> argument of |
| <CODE>0L</CODE> and a <VAR>whence</VAR> argument of <CODE>SEEK_SET</CODE>, except that |
| the return value is discarded and the error indicator for the stream is |
| reset. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="dtype-fpos_t" type="dtype"> |
| <structure> |
| </structure> |
| </construct> |
| <construct id="dtype-fpos64_t" type="dtype"> |
| <structure> |
| </structure> |
| </construct> |
| <construct id="function-fgetpos" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| <parameter content="fpos_t *position"/> |
| </prototype> |
| <headers> |
| <header filename = "sys/file.h"/> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| This function stores the value of the file position indicator for the |
| stream <VAR>stream</VAR> in the <CODE>fpos_t</CODE> object pointed to by |
| <VAR>position</VAR>. If successful, <CODE>fgetpos</CODE> returns zero; otherwise |
| it returns a nonzero value and stores an implementation-defined positive |
| value in <CODE>errno</CODE>. |
| <br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> on a |
| 32 bit system the function is in fact <CODE>fgetpos64</CODE>. I.e., the LFS |
| interface transparently replaces the old interface. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fgetpos64" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| <parameter content="fpos64_t *position"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to <CODE>fgetpos</CODE> but the file position is |
| returned in a variable of type <CODE>fpos64_t</CODE> to which <VAR>position</VAR> |
| points. |
| <br><br> If the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> on a 32 |
| bits machine this function is available under the name <CODE>fgetpos</CODE> |
| and so transparently replaces the old interface. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fsetpos" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| <parameter content="const fpos_t *position"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| This function sets the file position indicator for the stream <VAR>stream</VAR> |
| to the position <VAR>position</VAR>, which must have been set by a previous |
| call to <CODE>fgetpos</CODE> on the same stream. If successful, <CODE>fsetpos</CODE> |
| clears the end-of-file indicator on the stream, discards any characters |
| that were ``pushed back'' by the use of <CODE>ungetc</CODE>, and returns a value |
| of zero. Otherwise, <CODE>fsetpos</CODE> returns a nonzero value and stores |
| an implementation-defined positive value in <CODE>errno</CODE>. |
| <br><br> When the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> on a |
| 32 bit system the function is in fact <CODE>fsetpos64</CODE>. I.e., the LFS |
| interface transparently replaces the old interface. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fsetpos64" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| <parameter content="const fpos64_t *position"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| This function is similar to <CODE>fsetpos</CODE> but the file position used |
| for positioning is provided in a variable of type <CODE>fpos64_t</CODE> to |
| which <VAR>position</VAR> points. |
| <br><br> If the sources are compiled with <CODE>_FILE_OFFSET_BITS == 64</CODE> on a 32 |
| bits machine this function is available under the name <CODE>fsetpos</CODE> |
| and so transparently replaces the old interface. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fflush" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| This function causes any buffered output on <VAR>stream</VAR> to be delivered |
| to the file. If <VAR>stream</VAR> is a null pointer, then |
| <CODE>fflush</CODE> causes buffered output on <EM>all</EM> open output streams |
| to be flushed. |
| <br><br> This function returns <CODE>EOF</CODE> if a write error occurs, or zero |
| otherwise. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fflush_unlocked" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>fflush_unlocked</CODE> function is equivalent to the <CODE>fflush</CODE> |
| function except that it does not implicitly lock the stream. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-_flushlbf" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio_ext.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>_flushlbf</CODE> function flushes all line buffered streams |
| currently opened. |
| <br><br> This function is declared in the <TT>stdio_ext.h</TT> header. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-__fpurge" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio_ext.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>__fpurge</CODE> function causes the buffer of the stream |
| <VAR>stream</VAR> to be emptied. If the stream is currently in read mode all |
| input in the buffer is lost. If the stream is in output mode the |
| buffered output is not written to the device (or whatever other |
| underlying storage) and the buffer the cleared. |
| <br><br> This function is declared in <TT>stdio_ext.h</TT>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-setvbuf" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| <parameter content="char *buf"/> |
| <parameter content="int mode"/> |
| <parameter content="size_t size"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| This function is used to specify that the stream <VAR>stream</VAR> should |
| have the buffering mode <VAR>mode</VAR>, which can be either <CODE>_IOFBF</CODE> |
| (for full buffering), <CODE>_IOLBF</CODE> (for line buffering), or |
| <CODE>_IONBF</CODE> (for unbuffered input/output). |
| <br><br> If you specify a null pointer as the <VAR>buf</VAR> argument, then <CODE>setvbuf</CODE> |
| allocates a buffer itself using <CODE>malloc</CODE>. This buffer will be freed |
| when you close the stream. |
| <br><br> Otherwise, <VAR>buf</VAR> should be a character array that can hold at least |
| <VAR>size</VAR> characters. You should not free the space for this array as |
| long as the stream remains open and this array remains its buffer. You |
| should usually either allocate it statically, or <CODE>malloc</CODE> |
| the buffer. Using an automatic array |
| is not a good idea unless you close the file before exiting the block |
| that declares the array. |
| <br><br> While the array remains a stream buffer, the stream I/O functions will |
| use the buffer for their internal purposes. You shouldn't try to access |
| the values in the array directly while the stream is using it for |
| buffering. |
| <br><br> The <CODE>setvbuf</CODE> function returns zero on success, or a nonzero value |
| if the value of <VAR>mode</VAR> is not valid or if the request could not |
| be honored. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-setbuf" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| <parameter content="char *buf"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| If <VAR>buf</VAR> is a null pointer, the effect of this function is |
| equivalent to calling <CODE>setvbuf</CODE> with a <VAR>mode</VAR> argument of |
| <CODE>_IONBF</CODE>. Otherwise, it is equivalent to calling <CODE>setvbuf</CODE> |
| with <VAR>buf</VAR>, and a <VAR>mode</VAR> of <CODE>_IOFBF</CODE> and a <VAR>size</VAR> |
| argument of <CODE>BUFSIZ</CODE>. |
| <br><br> The <CODE>setbuf</CODE> function is provided for compatibility with old code; |
| use <CODE>setvbuf</CODE> in all new programs. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-setbuffer" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| <parameter content="char *buf"/> |
| <parameter content="size_t size"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| If <VAR>buf</VAR> is a null pointer, this function makes <VAR>stream</VAR> unbuffered. |
| Otherwise, it makes <VAR>stream</VAR> fully buffered using <VAR>buf</VAR> as the |
| buffer. The <VAR>size</VAR> argument specifies the length of <VAR>buf</VAR>. |
| <br><br> This function is provided for compatibility with old BSD code. Use |
| <CODE>setvbuf</CODE> instead. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-setlinebuf" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| This function makes <VAR>stream</VAR> be line buffered, and allocates the |
| buffer for you. |
| <br><br> This function is provided for compatibility with old BSD code. Use |
| <CODE>setvbuf</CODE> instead. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-__flbf" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio_ext.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>__flbf</CODE> function will return a nonzero value in case the |
| stream <VAR>stream</VAR> is line buffered. Otherwise the return value is |
| zero. |
| <br><br> This function is declared in the <TT>stdio_ext.h</TT> header. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-__fbufsize" type="function"> |
| <function returntype="size_t"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio_ext.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>__fbufsize</CODE> function return the size of the buffer in the |
| stream <VAR>stream</VAR>. This value can be used to optimize the use of the |
| stream. |
| <br><br> This function is declared in the <TT>stdio_ext.h</TT> header. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-__fpending" type="function"> |
| <function returntype="size_t"> |
| <prototype> |
| <parameter content="FILE *stream"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio_ext.h"/> |
| </headers> |
| <synopsis> |
| function returns the number of bytes currently in the output buffer. |
| For wide-oriented stream the measuring unit is wide characters. This |
| function should not be used on buffers in read mode or opened read-only. |
| <br><br> This function is declared in the <TT>stdio_ext.h</TT> header. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-fmemopen" type="function"> |
| <function returntype="FILE *"> |
| <prototype> |
| <parameter content="void *buf"/> |
| <parameter content="size_t size"/> |
| <parameter content="const char *opentype"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| This function opens a stream that allows the access specified by the |
| <VAR>opentype</VAR> argument, that reads from or writes to the buffer specified |
| by the argument <VAR>buf</VAR>. This array must be at least <VAR>size</VAR> bytes long. |
| <br><br> If you specify a null pointer as the <VAR>buf</VAR> argument, <CODE>fmemopen</CODE> |
| dynamically allocates an array <VAR>size</VAR> bytes long (as with <CODE>malloc</CODE>; |
| ). This is really only useful |
| if you are going to write things to the buffer and then read them back |
| in again, because you have no way of actually getting a pointer to the |
| buffer (for this, try <CODE>open_memstream</CODE>, below). The buffer is |
| freed when the stream is closed. |
| <br><br> The argument <VAR>opentype</VAR> is the same as in <CODE>fopen</CODE> |
| . If the <VAR>opentype</VAR> specifies |
| append mode, then the initial file position is set to the first null |
| character in the buffer. Otherwise the initial file position is at the |
| beginning of the buffer. |
| <br><br> When a stream open for writing is flushed or closed, a null character |
| (zero byte) is written at the end of the buffer if it fits. You |
| should add an extra byte to the <VAR>size</VAR> argument to account for this. |
| Attempts to write more than <VAR>size</VAR> bytes to the buffer result |
| in an error. |
| <br><br> For a stream open for reading, null characters (zero bytes) in the |
| buffer do not count as ``end of file''. Read operations indicate end of |
| file only when the file position advances past <VAR>size</VAR> bytes. So, if |
| you want to read characters from a null-terminated string, you should |
| supply the length of the string as the <VAR>size</VAR> argument. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-open_memstream" type="function"> |
| <function returntype="FILE *"> |
| <prototype> |
| <parameter content="char **ptr"/> |
| <parameter content="size_t *sizeloc"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| This function opens a stream for writing to a buffer. The buffer is |
| allocated dynamically and grown as necessary, using <CODE>malloc</CODE>. |
| After you've closed the stream, this buffer is your responsibility to |
| clean up using <CODE>free</CODE> or <CODE>realloc</CODE>. . |
| <br><br> When the stream is closed with <CODE>fclose</CODE> or flushed with |
| <CODE>fflush</CODE>, the locations <VAR>ptr</VAR> and <VAR>sizeloc</VAR> are updated to |
| contain the pointer to the buffer and its size. The values thus stored |
| remain valid only as long as no further output on the stream takes |
| place. If you do more output, you must flush the stream again to store |
| new values before you use them again. |
| <br><br> A null character is written at the end of the buffer. This null character |
| is <EM>not</EM> included in the size value stored at <VAR>sizeloc</VAR>. |
| <br><br> You can move the stream's file position with <CODE>fseek</CODE> or |
| <CODE>fseeko</CODE> . Moving the file position past |
| the end of the data already written fills the intervening space with |
| zeroes. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-open_obstack_stream" type="function"> |
| <function returntype="FILE *"> |
| <prototype> |
| <parameter content="struct obstack *obstack"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| This function opens a stream for writing data into the obstack <VAR>obstack</VAR>. |
| This starts an object in the obstack and makes it grow as data is |
| written . |
| <br><br> Calling <CODE>fflush</CODE> on this stream updates the current size of the |
| object to match the amount of data that has been written. After a call |
| to <CODE>fflush</CODE>, you can examine the object temporarily. |
| <br><br> You can move the file position of an obstack stream with <CODE>fseek</CODE> or |
| <CODE>fseeko</CODE> . Moving the file position past |
| the end of the data written fills the intervening space with zeros. |
| <br><br> To make the object permanent, update the obstack with <CODE>fflush</CODE>, and |
| then use <CODE>obstack_finish</CODE> to finalize the object and get its address. |
| The following write to the stream starts a new object in the obstack, |
| and later writes add to that object until you do another <CODE>fflush</CODE> |
| and <CODE>obstack_finish</CODE>. |
| <br><br> But how do you find out how long the object is? You can get the length |
| in bytes by calling <CODE>obstack_object_size</CODE> , or you can null-terminate the object like this: |
| <br><br> <pre><br> |
| obstack_1grow (<VAR>obstack</VAR>, 0);<br> |
| </pre> |
| <br><br> Whichever one you do, you must do it <EM>before</EM> calling |
| <CODE>obstack_finish</CODE>. (You can do both if you wish.) |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="type-cookie_io_functions_t" type="type"> |
| <structure> |
| <synopsis> |
| 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><br> |
| </synopsis> |
| <elements> |
| <element content="cookie_read_function_t *read"> |
| <synopsis> |
| 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 <CODE>EOF</CODE>. |
| <br><br> |
| </synopsis> |
| </element> |
| <element content="cookie_write_function_t *write"> |
| <synopsis> |
| 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><br> |
| </synopsis> |
| </element> |
| <element content="cookie_seek_function_t *seek"> |
| <synopsis> |
| 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 <CODE>fseek</CODE> or <CODE>fseeko</CODE> on this stream can only seek to |
| locations within the buffer; any attempt to seek outside the buffer will |
| return an <CODE>ESPIPE</CODE> error. |
| <br><br> |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="function-fopencookie" type="function"> |
| <function returntype="FILE *"> |
| <prototype> |
| <parameter content="void *cookie"/> |
| <parameter content="const char *opentype"/> |
| <parameter content="cookie_io_functions_t io-functions"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| </headers> |
| <synopsis> |
| This function actually creates the stream for communicating with the |
| <VAR>cookie</VAR> using the functions in the <VAR>io-functions</VAR> argument. |
| The <VAR>opentype</VAR> argument is interpreted as for <CODE>fopen</CODE>; |
| see Opening Streams. (But note that the ``truncate on |
| open'' option is ignored.) The new stream is fully buffered. |
| <br><br> The <CODE>fopencookie</CODE> function returns the newly created stream, or a null |
| pointer in case of an error. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="dtype-cookie_read_function" type="dtype"> |
| <structure> |
| </structure> |
| </construct> |
| <construct id="dtype-cookie_write_function" type="dtype"> |
| <structure> |
| </structure> |
| </construct> |
| <construct id="dtype-cookie_seek_function" type="dtype"> |
| <structure> |
| </structure> |
| </construct> |
| <construct id="dtype-cookie_close_function" type="dtype"> |
| <structure> |
| </structure> |
| </construct> |
| <construct id="function-fmtmsg" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="long int classification"/> |
| <parameter content="const char *label"/> |
| <parameter content="int severity"/> |
| <parameter content="const char *text"/> |
| <parameter content="const char *action"/> |
| <parameter content="const char *tag"/> |
| </prototype> |
| <headers> |
| <header filename = "stdio.h"/> |
| <header filename = "fmtmsg.h"/> |
| </headers> |
| <synopsis> |
| Display a message described by its parameters on the device(s) specified |
| in the <VAR>classification</VAR> parameter. The <VAR>label</VAR> parameter |
| identifies the source of the message. The string should consist of two |
| colon separated parts where the first part has not more than 10 and the |
| second part not more than 14 characters. The <VAR>text</VAR> parameter |
| describes the condition of the error, the <VAR>action</VAR> parameter possible |
| steps to recover from the error and the <VAR>tag</VAR> parameter is a |
| reference to the online documentation where more information can be |
| found. It should contain the <VAR>label</VAR> value and a unique |
| identification number. |
| <br><br> Each of the parameters can be a special value which means this value |
| is to be omitted. The symbolic names for these values are: |
| <br><br> <DL> |
| |
| <DT><CODE>MM_NULLLBL</CODE> |
| <DD> |
| Ignore <VAR>label</VAR> parameter. |
| <DT><CODE>MM_NULLSEV</CODE> |
| <DD> |
| Ignore <VAR>severity</VAR> parameter. |
| <DT><CODE>MM_NULLMC</CODE> |
| <DD> |
| Ignore <VAR>classification</VAR> parameter. This implies that nothing is |
| actually printed. |
| <DT><CODE>MM_NULLTXT</CODE> |
| <DD> |
| Ignore <VAR>text</VAR> parameter. |
| <DT><CODE>MM_NULLACT</CODE> |
| <DD> |
| Ignore <VAR>action</VAR> parameter. |
| <DT><CODE>MM_NULLTAG</CODE> |
| <DD> |
| Ignore <VAR>tag</VAR> parameter. |
| </DL> |
| <br><br> There is another way certain fields can be omitted from the output to |
| standard error. This is described below in the description of |
| environment variables influencing the behavior. |
| <br><br> The <VAR>severity</VAR> parameter can have one of the values in the following |
| table: |
| class |
| <br><br> <DL> |
| |
| <DT><CODE>MM_NOSEV</CODE> |
| <DD> |
| Nothing is printed, this value is the same as <CODE>MM_NULLSEV</CODE>. |
| <DT><CODE>MM_HALT</CODE> |
| <DD> |
| This value is printed as <CODE>HALT</CODE>. |
| <DT><CODE>MM_ERROR</CODE> |
| <DD> |
| This value is printed as <CODE>ERROR</CODE>. |
| <DT><CODE>MM_WARNING</CODE> |
| <DD> |
| This value is printed as <CODE>WARNING</CODE>. |
| <DT><CODE>MM_INFO</CODE> |
| <DD> |
| This value is printed as <CODE>INFO</CODE>. |
| </DL> |
| <br><br> The numeric value of these five macros are between <CODE>0</CODE> and |
| <CODE>4</CODE>. Using the environment variable <CODE>SEV_LEVEL</CODE> or using the |
| <CODE>addseverity</CODE> function one can add more severity levels with their |
| corresponding string to print. This is described below |
| . |
| <br><br> |
| If no parameter is ignored the output looks like this: |
| <br><br> <pre><br> |
| <VAR>label</VAR>: <VAR>severity-string</VAR>: <VAR>text</VAR><br> |
| TO FIX: <VAR>action</VAR> <VAR>tag</VAR><br> |
| </pre> |
| <br><br> The colons, new line characters and the <CODE>TO FIX</CODE> string are |
| inserted if necessary, i.e., if the corresponding parameter is not |
| ignored. |
| <br><br> This function is specified in the X/Open Portability Guide. It is also |
| available on all systems derived from System V. |
| <br><br> The function returns the value <CODE>MM_OK</CODE> if no error occurred. If |
| only the printing to standard error failed, it returns <CODE>MM_NOMSG</CODE>. |
| If printing to the console fails, it returns <CODE>MM_NOCON</CODE>. If |
| nothing is printed <CODE>MM_NOTOK</CODE> is returned. Among situations where |
| all outputs fail this last value is also returned if a parameter value |
| is incorrect. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-addseverity" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="int severity"/> |
| <parameter content="const char *string"/> |
| </prototype> |
| <synopsis> |
| This function allows the introduction of new severity classes which can be |
| addressed by the <VAR>severity</VAR> parameter of the <CODE>fmtmsg</CODE> function. |
| The <VAR>severity</VAR> parameter of <CODE>addseverity</CODE> must match the value |
| for the parameter with the same name of <CODE>fmtmsg</CODE>, and <VAR>string</VAR> |
| is the string printed in the actual messages instead of the numeric |
| value. |
| <br><br> If <VAR>string</VAR> is <CODE>NULL</CODE> the severity class with the numeric value |
| according to <VAR>severity</VAR> is removed. |
| <br><br> It is not possible to overwrite or remove one of the default severity |
| classes. All calls to <CODE>addseverity</CODE> with <VAR>severity</VAR> set to one |
| of the values for the default classes will fail. |
| <br><br> The return value is <CODE>MM_OK</CODE> if the task was successfully performed. |
| If the return value is <CODE>MM_NOTOK</CODE> something went wrong. This could |
| mean that no more memory is available or a class is not available when |
| it has to be removed. |
| <br><br> This function is not specified in the X/Open Portability Guide although |
| the <CODE>fmtsmg</CODE> function is. It is available on System V systems. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-lfind" type="function"> |
| <function returntype="void *"> |
| <prototype> |
| <parameter content="const void *key"/> |
| <parameter content="void *base"/> |
| <parameter content="size_t *nmemb"/> |
| <parameter content="size_t size"/> |
| <parameter content="comparison_fn_t compar"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| <header filename = "search.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>lfind</CODE> function searches in the array with <CODE>*<VAR>nmemb</VAR></CODE> |
| elements of <VAR>size</VAR> bytes pointed to by <VAR>base</VAR> for an element |
| which matches the one pointed to by <VAR>key</VAR>. The function pointed to |
| by <VAR>compar</VAR> is used decide whether two elements match. |
| <br><br> The return value is a pointer to the matching element in the array |
| starting at <VAR>base</VAR> if it is found. If no matching element is |
| available <CODE>NULL</CODE> is returned. |
| <br><br> The mean runtime of this function is <CODE>*<VAR>nmemb</VAR></CODE>/2. This |
| function should only be used if elements often get added to or deleted from |
| the array in which case it might not be useful to sort the array before |
| searching. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-lsearch" type="function"> |
| <function returntype="void *"> |
| <prototype> |
| <parameter content="const void *key"/> |
| <parameter content="void *base"/> |
| <parameter content="size_t *nmemb"/> |
| <parameter content="size_t size"/> |
| <parameter content="comparison_fn_t compar"/> |
| </prototype> |
| <headers> |
| <header filename = "search.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>lsearch</CODE> function is similar to the <CODE>lfind</CODE> function. It |
| searches the given array for an element and returns it if found. The |
| difference is that if no matching element is found the <CODE>lsearch</CODE> |
| function adds the object pointed to by <VAR>key</VAR> (with a size of |
| <VAR>size</VAR> bytes) at the end of the array and it increments the value of |
| <CODE>*<VAR>nmemb</VAR></CODE> to reflect this addition. |
| <br><br> This means for the caller that if it is not sure that the array contains |
| the element one is searching for the memory allocated for the array |
| starting at <VAR>base</VAR> must have room for at least <VAR>size</VAR> more |
| bytes. If one is sure the element is in the array it is better to use |
| <CODE>lfind</CODE> so having more room in the array is always necessary when |
| calling <CODE>lsearch</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-bsearch" type="function"> |
| <function returntype="void *"> |
| <prototype> |
| <parameter content="const void *key"/> |
| <parameter content="const void *array"/> |
| <parameter content="size_t count"/> |
| <parameter content="size_t size"/> |
| <parameter content="comparison_fn_t compare"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>bsearch</CODE> function searches the sorted array <VAR>array</VAR> for an object |
| that is equivalent to <VAR>key</VAR>. The array contains <VAR>count</VAR> elements, |
| each of which is of size <VAR>size</VAR> bytes. |
| <br><br> The <VAR>compare</VAR> function is used to perform the comparison. This |
| function is called with two pointer arguments and should return an |
| integer less than, equal to, or greater than zero corresponding to |
| whether its first argument is considered less than, equal to, or greater |
| than its second argument. The elements of the <VAR>array</VAR> must already |
| be sorted in ascending order according to this comparison function. |
| <br><br> The return value is a pointer to the matching array element, or a null |
| pointer if no match is found. If the array contains more than one element |
| that matches, the one that is returned is unspecified. |
| <br><br> This function derives its name from the fact that it is implemented |
| using the binary search algorithm. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-qsort" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="void *array"/> |
| <parameter content="size_t count"/> |
| <parameter content="size_t size"/> |
| <parameter content="comparison_fn_t compare"/> |
| </prototype> |
| <headers> |
| <header filename = "stdlib.h"/> |
| </headers> |
| <synopsis> |
| The <VAR>qsort</VAR> function sorts the array <VAR>array</VAR>. The array contains |
| <VAR>count</VAR> elements, each of which is of size <VAR>size</VAR>. |
| <br><br> The <VAR>compare</VAR> function is used to perform the comparison on the |
| array elements. This function is called with two pointer arguments and |
| should return an integer less than, equal to, or greater than zero |
| corresponding to whether its first argument is considered less than, |
| equal to, or greater than its second argument. |
| <br><br> sorting |
| Warning: If two objects compare as equal, their order after |
| sorting is unpredictable. That is to say, the sorting is not stable. |
| This can make a difference when the comparison considers only part of |
| the elements. Two elements with the same sort key may differ in other |
| respects. |
| <br><br> If you want the effect of a stable sort, you can get this result by |
| writing the comparison function so that, lacking other reason |
| distinguish between two elements, it compares them by their addresses. |
| Note that doing this may make the sorting algorithm less efficient, so |
| do it only if necessary. |
| <br><br> Here is a simple example of sorting an array of doubles in numerical |
| order, using the comparison function defined above : |
| <br><br> <pre><br> |
| {<br> |
| double *array;<br> |
| int size;<br> |
| <small>...</small><br> |
| qsort (array, size, sizeof (double), compare_doubles);<br> |
| }<br> |
| </pre> |
| <br><br> The <CODE>qsort</CODE> function derives its name from the fact that it was |
| originally implemented using the ``quick sort'' algorithm. |
| <br><br> The implementation of <CODE>qsort</CODE> in this library might not be an |
| in-place sort and might thereby use an extra amount of memory to store |
| the array. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-hcreate" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="size_t nel"/> |
| </prototype> |
| <headers> |
| <header filename = "search.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>hcreate</CODE> function creates a hashing table which can contain at |
| least <VAR>nel</VAR> elements. There is no possibility to grow this table so |
| it is necessary to choose the value for <VAR>nel</VAR> wisely. The method |
| used to implement this function might make it necessary to make the |
| number of elements in the hashing table larger than the expected maximal |
| number of elements. Hashing tables usually work inefficiently if they are |
| filled 80% or more. The constant access time guaranteed by hashing can |
| only be achieved if few collisions exist. See Knuth's ``The Art of |
| Computer Programming, Part 3: Searching and Sorting'' for more |
| information. |
| <br><br> The weakest aspect of this function is that there can be at most one |
| hashing table used through the whole program. The table is allocated |
| in local memory out of control of the programmer. As an extension the |
| GNU C library provides an additional set of functions with an reentrant |
| interface which provide a similar interface but which allow to keep |
| arbitrarily many hashing tables. |
| <br><br> It is possible to use more than one hashing table in the program run if |
| the former table is first destroyed by a call to <CODE>hdestroy</CODE>. |
| <br><br> The function returns a non-zero value if successful. If it return zero |
| something went wrong. This could either mean there is already a hashing |
| table in use or the program runs out of memory. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-hdestroy" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="void"/> |
| </prototype> |
| <headers> |
| <header filename = "search.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>hdestroy</CODE> function can be used to free all the resources |
| allocated in a previous call of <CODE>hcreate</CODE>. After a call to this |
| function it is again possible to call <CODE>hcreate</CODE> and allocate a new |
| table with possibly different size. |
| <br><br> It is important to remember that the elements contained in the hashing |
| table at the time <CODE>hdestroy</CODE> is called are <EM>not</EM> freed by this |
| function. It is the responsibility of the program code to free those |
| strings (if necessary at all). Freeing all the element memory is not |
| possible without extra, separately kept information since there is no |
| function to iterate through all available elements in the hashing table. |
| If it is really necessary to free a table and all elements the |
| programmer has to keep a list of all table elements and before calling |
| <CODE>hdestroy</CODE> s/he has to free all element's data using this list. |
| This is a very unpleasant mechanism and it also shows that this kind of |
| hashing tables is mainly meant for tables which are created once and |
| used until the end of the program run. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="struct-ENTRY" type="struct"> |
| <structure> |
| <synopsis> |
| Both elements of this structure are pointers to zero-terminated strings. |
| This is a limiting restriction of the functionality of the |
| <CODE>hsearch</CODE> 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><br> |
| </synopsis> |
| <elements> |
| <element content="char *key"> |
| <synopsis> |
| Pointer to a zero-terminated string of characters describing the key for |
| the search or the element in the hashing table. |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="function-hsearch" type="function"> |
| <function returntype="ENTRY *"> |
| <prototype> |
| <parameter content="ENTRY item"/> |
| <parameter content="ACTION action"/> |
| </prototype> |
| <headers> |
| <header filename = "search.h"/> |
| </headers> |
| <synopsis> |
| To search in a hashing table created using <CODE>hcreate</CODE> the |
| <CODE>hsearch</CODE> function must be used. This function can perform simple |
| search for an element (if <VAR>action</VAR> has the <CODE>FIND</CODE>) or it can |
| alternatively insert the key element into the hashing table. Entries |
| are never replaced. |
| <br><br> The key is denoted by a pointer to an object of type <CODE>ENTRY</CODE>. For |
| locating the corresponding position in the hashing table only the |
| <CODE>key</CODE> element of the structure is used. |
| <br><br> If an entry with matching key is found the <VAR>action</VAR> parameter is |
| irrelevant. The found entry is returned. If no matching entry is found |
| and the <VAR>action</VAR> parameter has the value <CODE>FIND</CODE> the function |
| returns a <CODE>NULL</CODE> pointer. If no entry is found and the |
| <VAR>action</VAR> parameter has the value <CODE>ENTER</CODE> a new entry is added |
| to the hashing table which is initialized with the parameter <VAR>item</VAR>. |
| A pointer to the newly added entry is returned. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-hcreate_r" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="size_t nel"/> |
| <parameter content="struct hsearch_data *htab"/> |
| </prototype> |
| <headers> |
| <header filename = "search.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>hcreate_r</CODE> function initializes the object pointed to by |
| <VAR>htab</VAR> to contain a hashing table with at least <VAR>nel</VAR> elements. |
| So this function is equivalent to the <CODE>hcreate</CODE> function except |
| that the initialized data structure is controlled by the user. |
| <br><br> This allows having more than one hashing table at one time. The memory |
| necessary for the <CODE>struct hsearch_data</CODE> object can be allocated |
| dynamically. It must be initialized with zero before calling this |
| function. |
| <br><br> The return value is non-zero if the operation was successful. If the |
| return value is zero, something went wrong, which probably means the |
| programs ran out of memory. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-hdestroy_r" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="struct hsearch_data *htab"/> |
| </prototype> |
| <headers> |
| <header filename = "search.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>hdestroy_r</CODE> function frees all resources allocated by the |
| <CODE>hcreate_r</CODE> function for this very same object <VAR>htab</VAR>. As for |
| <CODE>hdestroy</CODE> it is the programs responsibility to free the strings |
| for the elements of the table. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-hsearch_r" type="function"> |
| <function returntype="int"> |
| <prototype> |
| <parameter content="ENTRY item"/> |
| <parameter content="ACTION action"/> |
| <parameter content="ENTRY **retval"/> |
| <parameter content="struct hsearch_data *htab"/> |
| </prototype> |
| <headers> |
| <header filename = "search.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>hsearch_r</CODE> function is equivalent to <CODE>hsearch</CODE>. The |
| meaning of the first two arguments is identical. But instead of |
| operating on a single global hashing table the function works on the |
| table described by the object pointed to by <VAR>htab</VAR> (which is |
| initialized by a call to <CODE>hcreate_r</CODE>). |
| <br><br> Another difference to <CODE>hcreate</CODE> is that the pointer to the found |
| entry in the table is not the return value of the functions. It is |
| returned by storing it in a pointer variables pointed to by the |
| <VAR>retval</VAR> parameter. The return value of the function is an integer |
| value indicating success if it is non-zero and failure if it is zero. |
| In the latter case the global variable <VAR>errno</VAR> signals the reason for |
| the failure. |
| <br><br> <DL> |
| |
| <DT><CODE>ENOMEM</CODE> |
| <DD> |
| The table is filled and <CODE>hsearch_r</CODE> was called with an so far |
| unknown key and <VAR>action</VAR> set to <CODE>ENTER</CODE>. |
| <LI> ESRCH |
| The <VAR>action</VAR> parameter is <CODE>FIND</CODE> and no corresponding element |
| is found in the table. |
| |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-tsearch" type="function"> |
| <function returntype="void *"> |
| <prototype> |
| <parameter content="const void *key"/> |
| <parameter content="void **rootp"/> |
| <parameter content="comparison_fn_t compar"/> |
| </prototype> |
| <headers> |
| <header filename = "search.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>tsearch</CODE> function searches in the tree pointed to by |
| <CODE>*<VAR>rootp</VAR></CODE> for an element matching <VAR>key</VAR>. The function |
| pointed to by <VAR>compar</VAR> is used to determine whether two elements |
| match. , for a specification of the functions |
| which can be used for the <VAR>compar</VAR> parameter. |
| <br><br> If the tree does not contain a matching entry the <VAR>key</VAR> value will |
| be added to the tree. <CODE>tsearch</CODE> does not make a copy of the object |
| pointed to by <VAR>key</VAR> (how could it since the size is unknown). |
| Instead it adds a reference to this object which means the object must |
| be available as long as the tree data structure is used. |
| <br><br> The tree is represented by a pointer to a pointer since it is sometimes |
| necessary to change the root node of the tree. So it must not be |
| assumed that the variable pointed to by <VAR>rootp</VAR> has the same value |
| after the call. This also shows that it is not safe to call the |
| <CODE>tsearch</CODE> function more than once at the same time using the same |
| tree. It is no problem to run it more than once at a time on different |
| trees. |
| <br><br> The return value is a pointer to the matching element in the tree. If a |
| new element was created the pointer points to the new data (which is in |
| fact <VAR>key</VAR>). If an entry had to be created and the program ran out |
| of space <CODE>NULL</CODE> is returned. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-tfind" type="function"> |
| <function returntype="void *"> |
| <prototype> |
| <parameter content="const void *key"/> |
| <parameter content="void *const *rootp"/> |
| <parameter content="comparison_fn_t compar"/> |
| </prototype> |
| <headers> |
| <header filename = "search.h"/> |
| </headers> |
| <synopsis> |
| The <CODE>tfind</CODE> function is similar to the <CODE>tsearch</CODE> function. It |
| locates an element matching the one pointed to by <VAR>key</VAR> and returns |
| a pointer to this element. But if no matching element is available no |
| new element is entered (note that the <VAR>rootp</VAR> parameter points to a |
| constant pointer). Instead the function returns <CODE>NULL</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-tdelete" type="function"> |
| <function returntype="void *"> |
| <prototype> |
| <parameter content="const void *key"/> |
| <parameter content="void **rootp"/> |
| <parameter content="comparison_fn_t compar"/> |
| </prototype> |
| <headers> |
| <header filename = "search.h"/> |
| </headers> |
| <synopsis> |
| To remove a specific element matching <VAR>key</VAR> from the tree |
| <CODE>tdelete</CODE> can be used. It locates the matching element using the |
| same method as <CODE>tfind</CODE>. The corresponding element is then removed |
| and a pointer to the parent of the deleted node is returned by the |
| function. If there is no matching entry in the tree nothing can be |
| deleted and the function returns <CODE>NULL</CODE>. If the root of the tree |
| is deleted <CODE>tdelete</CODE> returns some unspecified value not equal to |
| <CODE>NULL</CODE>. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="function-tdestroy" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="void *vroot"/> |
| <parameter content="__free_fn_t freefct"/> |
| </prototype> |
| <headers> |
| <header filename = "search.h"/> |
| </headers> |
| <synopsis> |
| If the complete search tree has to be removed one can use |
| <CODE>tdestroy</CODE>. It frees all resources allocated by the <CODE>tsearch</CODE> |
| function to generate the tree pointed to by <VAR>vroot</VAR>. |
| <br><br> For the data in each tree node the function <VAR>freefct</VAR> is called. |
| The pointer to the data is passed as the argument to the function. If |
| no such work is necessary <VAR>freefct</VAR> must point to a function doing |
| nothing. It is called in any case. |
| <br><br> This function is a GNU extension and not covered by the System V or |
| X/Open specifications. |
| </synopsis> |
| </function> |
| </construct> |
| <construct id="dtype-VISIT" type="dtype"> |
| <structure> |
| <synopsis> |
| The <CODE>VISIT</CODE> 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><br> |
| </synopsis> |
| <elements> |
| <element content="preorder"> |
| <synopsis> |
| The current node is an internal node and the function is called before |
| the first child was processed. |
| </synopsis> |
| </element> |
| <element content="postorder"> |
| <synopsis> |
| The current node is an internal node and the function is called after |
| the first child was processed. |
| </synopsis> |
| </element> |
| <element content="endorder"> |
| <synopsis> |
| The current node is an internal node and the function is called after |
| the second child was processed. |
| </synopsis> |
| </element> |
| </elements> |
| </structure> |
| </construct> |
| <construct id="function-twalk" type="function"> |
| <function returntype="void"> |
| <prototype> |
| <parameter content="const void *root"/> |
| <parameter content="__action_fn_t action"/> |
| </prototype> |
| <headers> |
| <header filename = "search.h"/> |
| </headers> |
| <synopsis> |
| For each node in the tree with a node pointed to by <VAR>root</VAR>, the |
| <CODE>twalk</CODE> function calls the function provided by the parameter |
| <VAR>action</VAR>. For leaf nodes the function is called exactly once with |
| <VAR>value</VAR> set to <CODE>leaf</CODE>. For internal nodes the function is |
| called three times, setting the <VAR>value</VAR> parameter or <VAR>action</VAR> to |
| the appropriate value. The <VAR>level</VAR> argument for the <VAR>action</VAR> |
| function is computed while descending the tree with increasing the value |
| by one for the descend to a child, starting with the value 0 for |
| the root node. |
| <br><br> Since the functions used for the <VAR>action</VAR> parameter to <CODE>twalk</CODE> |
| must not modify the tree data, it is safe to run <CODE>twalk</CODE> in more |
| than one thread at the same time, working on the same tree. It is also |
| safe to call <CODE>tfind</CODE> in parallel. Functions which modify the tree |
| must not be used, otherwise the behavior is undefined. |
| </synopsis> |
| </function> |
| </construct> |
| </descriptions> |
