arm-2011.03/share/doc/arm-arm-none-linux-gnueabi/html/libc/Lookup-Netgroup.html - nest-cam/10950009/arm-none-linux-gnueabi-i686-pc-linux-gnu - Git at Google

 <html lang="en">
 <head>
 <title>Lookup Netgroup - The GNU C Library</title>
 <meta http-equiv="Content-Type" content="text/html">
 <meta name="description" content="The GNU C Library">
 <meta name="generator" content="makeinfo 4.13">
 <link title="Top" rel="start" href="index.html#Top">
 <link rel="up" href="Netgroup-Database.html#Netgroup-Database" title="Netgroup Database">
 <link rel="prev" href="Netgroup-Data.html#Netgroup-Data" title="Netgroup Data">
 <link rel="next" href="Netgroup-Membership.html#Netgroup-Membership" title="Netgroup Membership">
 <link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
 <!--
 This file documents the GNU C library.

 This is Edition 0.12, last updated 2007-10-27,
 of `The GNU C Library Reference Manual', for version
 2.8 (Sourcery G++ Lite 2011.03-41).

 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.''-->
 <meta http-equiv="Content-Style-Type" content="text/css">
 <style type="text/css"><!--
   pre.display { font-family:inherit }
   pre.format  { font-family:inherit }
   pre.smalldisplay { font-family:inherit; font-size:smaller }
   pre.smallformat  { font-family:inherit; font-size:smaller }
   pre.smallexample { font-size:smaller }
   pre.smalllisp    { font-size:smaller }
   span.sc    { font-variant:small-caps }
   span.roman { font-family:serif; font-weight:normal; }
   span.sansserif { font-family:sans-serif; font-weight:normal; }
 --></style>
 <link rel="stylesheet" type="text/css" href="../cs.css">
 </head>
 <body>
 <div class="node">
 <a name="Lookup-Netgroup"></a>
 <p>
 Next:&nbsp;<a rel="next" accesskey="n" href="Netgroup-Membership.html#Netgroup-Membership">Netgroup Membership</a>,
 Previous:&nbsp;<a rel="previous" accesskey="p" href="Netgroup-Data.html#Netgroup-Data">Netgroup Data</a>,
 Up:&nbsp;<a rel="up" accesskey="u" href="Netgroup-Database.html#Netgroup-Database">Netgroup Database</a>
 <hr>
 </div>

 <h4 class="subsection">29.16.2 Looking up one Netgroup</h4>

 <p>The lookup functions for netgroups are a bit different to all other
 system database handling functions.  Since a single netgroup can contain
 many entries a two-step process is needed.  First a single netgroup is
 selected and then one can iterate over all entries in this netgroup.
 These functions are declared in <samp><span class="file">netdb.h</span></samp>.

 <!-- netdb.h -->
 <!-- BSD -->
 <div class="defun">
 &mdash; Function: int <b>setnetgrent</b> (<var>const char *netgroup</var>)<var><a name="index-setnetgrent-3425"></a></var><br>
 <blockquote><p>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>.

         <p>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.
 </p></blockquote></div>

    <p>It is important to remember that there is only one single state for
 iterating the netgroups.  Even if the programmer uses the
 <code>getnetgrent_r</code> function the result is not really reentrant since
 always only one single netgroup at a time can be processed.  If the
 program needs to process more than one netgroup simultaneously she
 must protect this by using external locking.  This problem was
 introduced in the original netgroups implementation in SunOS and since
 we must stay compatible it is not possible to change this.

    <p>Some other functions also use the netgroups state.  Currently these are
 the <code>innetgr</code> function and parts of the implementation of the
 <code>compat</code> service part of the NSS implementation.

 <!-- netdb.h -->
 <!-- BSD -->
 <div class="defun">
 &mdash; Function: int <b>getnetgrent</b> (<var>char **hostp, char **userp, char **domainp</var>)<var><a name="index-getnetgrent-3426"></a></var><br>
 <blockquote><p>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.

         <p>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.
 </p></blockquote></div>

 <!-- netdb.h -->
 <!-- GNU -->
 <div class="defun">
 &mdash; Function: int <b>getnetgrent_r</b> (<var>char **hostp, char **userp, char **domainp, char *buffer, int buflen</var>)<var><a name="index-getnetgrent_005fr-3427"></a></var><br>
 <blockquote><p>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.

         <p>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.

         <p>This function is a GNU extension.  The original implementation in the
 SunOS libc does not provide this function.
 </p></blockquote></div>

 <!-- netdb.h -->
 <!-- BSD -->
 <div class="defun">
 &mdash; Function: void <b>endnetgrent</b> (<var>void</var>)<var><a name="index-endnetgrent-3428"></a></var><br>
 <blockquote><p>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.
 </p></blockquote></div>

    </body></html>
	<html lang="en">
	<head>
	<title>Lookup Netgroup - The GNU C Library</title>
	<meta http-equiv="Content-Type" content="text/html">
	<meta name="description" content="The GNU C Library">
	<meta name="generator" content="makeinfo 4.13">
	<link title="Top" rel="start" href="index.html#Top">
	<link rel="up" href="Netgroup-Database.html#Netgroup-Database" title="Netgroup Database">
	<link rel="prev" href="Netgroup-Data.html#Netgroup-Data" title="Netgroup Data">
	<link rel="next" href="Netgroup-Membership.html#Netgroup-Membership" title="Netgroup Membership">
	<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
	<!--
	This file documents the GNU C library.

	This is Edition 0.12, last updated 2007-10-27,
	of `The GNU C Library Reference Manual', for version
	2.8 (Sourcery G++ Lite 2011.03-41).

	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.''-->
	<meta http-equiv="Content-Style-Type" content="text/css">
	<style type="text/css"><!--
	pre.display { font-family:inherit }
	pre.format { font-family:inherit }
	pre.smalldisplay { font-family:inherit; font-size:smaller }
	pre.smallformat { font-family:inherit; font-size:smaller }
	pre.smallexample { font-size:smaller }
	pre.smalllisp { font-size:smaller }
	span.sc { font-variant:small-caps }
	span.roman { font-family:serif; font-weight:normal; }
	span.sansserif { font-family:sans-serif; font-weight:normal; }
	--></style>
	<link rel="stylesheet" type="text/css" href="../cs.css">
	</head>
	<body>
	<div class="node">
	<a name="Lookup-Netgroup"></a>
	<p>
	Next: <a rel="next" accesskey="n" href="Netgroup-Membership.html#Netgroup-Membership">Netgroup Membership</a>,
	Previous: <a rel="previous" accesskey="p" href="Netgroup-Data.html#Netgroup-Data">Netgroup Data</a>,
	Up: <a rel="up" accesskey="u" href="Netgroup-Database.html#Netgroup-Database">Netgroup Database</a>
	<hr>
	</div>

	<h4 class="subsection">29.16.2 Looking up one Netgroup</h4>

	<p>The lookup functions for netgroups are a bit different to all other
	system database handling functions. Since a single netgroup can contain
	many entries a two-step process is needed. First a single netgroup is
	selected and then one can iterate over all entries in this netgroup.
	These functions are declared in <samp><span class="file">netdb.h</span></samp>.

	<!-- netdb.h -->
	<!-- BSD -->
	<div class="defun">
	— Function: int <b>setnetgrent</b> (<var>const char *netgroup</var>)<var><a name="index-setnetgrent-3425"></a></var><br>
	<blockquote><p>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>.

	<p>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.
	</p></blockquote></div>

	<p>It is important to remember that there is only one single state for
	iterating the netgroups. Even if the programmer uses the
	<code>getnetgrent_r</code> function the result is not really reentrant since
	always only one single netgroup at a time can be processed. If the
	program needs to process more than one netgroup simultaneously she
	must protect this by using external locking. This problem was
	introduced in the original netgroups implementation in SunOS and since
	we must stay compatible it is not possible to change this.

	<p>Some other functions also use the netgroups state. Currently these are
	the <code>innetgr</code> function and parts of the implementation of the
	<code>compat</code> service part of the NSS implementation.

	<!-- netdb.h -->
	<!-- BSD -->
	<div class="defun">
	— Function: int <b>getnetgrent</b> (<var>char hostp, char userp, char **domainp</var>)<var><a name="index-getnetgrent-3426"></a></var><br>
	<blockquote><p>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.

	<p>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.
	</p></blockquote></div>

	<!-- netdb.h -->
	<!-- GNU -->
	<div class="defun">
	— Function: int <b>getnetgrent_r</b> (<var>char hostp, char userp, char *domainp, char buffer, int buflen</var>)<var><a name="index-getnetgrent_005fr-3427"></a></var><br>
	<blockquote><p>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.

	<p>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.

	<p>This function is a GNU extension. The original implementation in the
	SunOS libc does not provide this function.
	</p></blockquote></div>

	<!-- netdb.h -->
	<!-- BSD -->
	<div class="defun">
	— Function: void <b>endnetgrent</b> (<var>void</var>)<var><a name="index-endnetgrent-3428"></a></var><br>
	<blockquote><p>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.
	</p></blockquote></div>

	</body></html>