improve consistency of code layout

git-svn-id: http://arthurdejong.org/svn/nss-pam-ldapd/nss-pam-ldapd@1240 ef36b2f9-881f-0410-afb5-c4e39611909c

12 files changed, 132 insertions, 37 deletions

diff --git a/nss/Makefile.am b/nss/Makefile.am
index 1efe77b..49e7e64 100644
--- a/nss/Makefile.am
+++ b/nss/Makefile.am
@@ -31,12 +31,13 @@ nss_ldap_so_SOURCES = common.c common.h prototypes.h \
 EXTRA_nss_ldap_so_SOURCES = aliases.c ethers.c group.c hosts.c netgroup.c \
                             networks.c passwd.c protocols.c rpc.c services.c \
                             shadow.c
+nss_ldap_so_DEPENDENCIES = $(NSS_MODULE_OBJS)
+nss_ldap_so_LDADD = ../common/libtio.a ../common/libprot.a $(NSS_MODULE_OBJS)
+
 nss_ldap_so_LDFLAGS = -shared -Wl,-h,$(NSS_LDAP_SONAME)
 if HAVE_VERSION_SCRIPT_FLAG
 nss_ldap_so_LDFLAGS += $(VERSION_SCRIPT_FLAG)\$(srcdir)/nss_ldap.map
 endif
-nss_ldap_so_LDADD = ../common/libtio.a ../common/libprot.a $(NSS_MODULE_OBJS)
-nss_ldap_so_DEPENDENCIES = $(NSS_MODULE_OBJS)
 
 EXTRA_DIST = nss_ldap.map
 
diff --git a/nss/aliases.c b/nss/aliases.c
index 042132a..bbbb1ee 100644
--- a/nss/aliases.c
+++ b/nss/aliases.c
@@ -2,7 +2,7 @@
    aliases.c - NSS lookup functions for aliases database
 
    Copyright (C) 2006 West Consulting
-   Copyright (C) 2006, 2007, 2008 Arthur de Jong
+   Copyright (C) 2006, 2007, 2008, 2010 Arthur de Jong
 
    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Lesser General Public
@@ -28,6 +28,7 @@
 #include "prototypes.h"
 #include "common.h"
 
+/* read an alias entry from the stream */
 static nss_status_t read_aliasent(
         TFILE *fp,struct aliasent *result,
         char *buffer,size_t buflen,int *errnop)
@@ -46,6 +47,7 @@ static nss_status_t read_aliasent(
   return NSS_STATUS_SUCCESS;
 }
 
+/* get an alias entry by name */
 nss_status_t _nss_ldap_getaliasbyname_r(
         const char *name,struct aliasent *result,
         char *buffer,size_t buflen,int *errnop)
@@ -58,17 +60,22 @@ nss_status_t _nss_ldap_getaliasbyname_r(
 /* thread-local file pointer to an ongoing request */
 static __thread TFILE *aliasentfp;
 
+/* start a request to read all aliases */
 nss_status_t _nss_ldap_setaliasent(void)
 {
   NSS_SETENT(aliasentfp);
 }
 
-nss_status_t _nss_ldap_getaliasent_r(struct aliasent *result,char *buffer,size_t buflen,int *errnop)
+/* read a single alias entry from the stream */
+nss_status_t _nss_ldap_getaliasent_r(
+        struct aliasent *result,
+        char *buffer,size_t buflen,int *errnop)
 {
   NSS_GETENT(aliasentfp,NSLCD_ACTION_ALIAS_ALL,
              read_aliasent(aliasentfp,result,buffer,buflen,errnop));
 }
 
+/* close the stream opened with setaliasent() above */
 nss_status_t _nss_ldap_endaliasent(void)
 {
   NSS_ENDENT(aliasentfp);
diff --git a/nss/ethers.c b/nss/ethers.c
index f23af43..f69d738 100644
--- a/nss/ethers.c
+++ b/nss/ethers.c
@@ -2,7 +2,7 @@
    ethers.c - NSS lookup functions for ethers database
 
    Copyright (C) 2006 West Consulting
-   Copyright (C) 2006, 2007, 2008 Arthur de Jong
+   Copyright (C) 2006, 2007, 2008, 2010 Arthur de Jong
 
    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Lesser General Public
@@ -29,6 +29,7 @@
 #include "common.h"
 #include "compat/attrs.h"
 
+/* read an ethernet entry from the stream */
 static nss_status_t read_etherent(
         TFILE *fp,struct etherent *result,
         char *buffer,size_t buflen,int *errnop)
@@ -63,11 +64,13 @@ nss_status_t _nss_ldap_getntohost_r(
 /* thread-local file pointer to an ongoing request */
 static __thread TFILE *etherentfp;
 
+/* open a connection to read all ether entries */
 nss_status_t _nss_ldap_setetherent(int UNUSED(stayopen))
 {
   NSS_SETENT(etherentfp);
 }
 
+/* read a single ethernet entry from the stream */
 nss_status_t _nss_ldap_getetherent_r(
         struct etherent *result,
         char *buffer,size_t buflen,int *errnop)
@@ -76,6 +79,7 @@ nss_status_t _nss_ldap_getetherent_r(
              read_etherent(etherentfp,result,buffer,buflen,errnop));
 }
 
+/* close the stream opened with setetherent() above */
 nss_status_t _nss_ldap_endetherent(void)
 {
   NSS_ENDENT(etherentfp);
diff --git a/nss/group.c b/nss/group.c
index 45cfeaa..68d9ef8 100644
--- a/nss/group.c
+++ b/nss/group.c
@@ -2,7 +2,7 @@
    group.c - NSS lookup functions for group database
 
    Copyright (C) 2006 West Consulting
-   Copyright (C) 2006, 2007, 2008, 2009 Arthur de Jong
+   Copyright (C) 2006, 2007, 2008, 2009, 2010 Arthur de Jong
 
    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Lesser General Public
@@ -30,6 +30,7 @@
 #include "common.h"
 #include "compat/attrs.h"
 
+/* read a single group entry from the stream */
 static nss_status_t read_group(
         TFILE *fp,struct group *result,
         char *buffer,size_t buflen,int *errnop)
@@ -99,14 +100,20 @@ static nss_status_t read_gids(
   return NSS_STATUS_SUCCESS;
 }
 
-nss_status_t _nss_ldap_getgrnam_r(const char *name,struct group *result,char *buffer,size_t buflen,int *errnop)
+/* get a group entry by name */
+nss_status_t _nss_ldap_getgrnam_r(
+        const char *name,struct group *result,
+        char *buffer,size_t buflen,int *errnop)
 {
   NSS_BYNAME(NSLCD_ACTION_GROUP_BYNAME,
              name,
              read_group(fp,result,buffer,buflen,errnop));
 }
 
-nss_status_t _nss_ldap_getgrgid_r(gid_t gid,struct group *result,char *buffer,size_t buflen,int *errnop)
+/* get a group entry by numeric gid */
+nss_status_t _nss_ldap_getgrgid_r(
+        gid_t gid,struct group *result,
+        char *buffer,size_t buflen,int *errnop)
 {
   NSS_BYTYPE(NSLCD_ACTION_GROUP_BYGID,
              gid,gid_t,
@@ -144,17 +151,22 @@ nss_status_t _nss_ldap_initgroups_dyn(
 /* thread-local file pointer to an ongoing request */
 static __thread TFILE *grentfp;
 
+/* start a request to read all groups */
 nss_status_t _nss_ldap_setgrent(int UNUSED(stayopen))
 {
   NSS_SETENT(grentfp);
 }
 
-nss_status_t _nss_ldap_getgrent_r(struct group *result,char *buffer,size_t buflen,int *errnop)
+/* read a single group from the stream */
+nss_status_t _nss_ldap_getgrent_r(
+        struct group *result,
+        char *buffer,size_t buflen,int *errnop)
 {
   NSS_GETENT(grentfp,NSLCD_ACTION_GROUP_ALL,
              read_group(grentfp,result,buffer,buflen,errnop));
 }
 
+/* close the stream opened with setgrent() above */
 nss_status_t _nss_ldap_endgrent(void)
 {
   NSS_ENDENT(grentfp);
diff --git a/nss/hosts.c b/nss/hosts.c
index 5a48f6e..6ef9691 100644
--- a/nss/hosts.c
+++ b/nss/hosts.c
@@ -29,7 +29,7 @@
 #include "common.h"
 #include "compat/attrs.h"
 
-/* Redifine some ERROR_OUT macros as we also want to set h_errnop. */
+/* Redefine some ERROR_OUT macros as we also want to set h_errnop. */
 
 #undef ERROR_OUT_OPENERROR
 #define ERROR_OUT_OPENERROR \
@@ -226,6 +226,7 @@ nss_status_t _nss_ldap_gethostent_r(
              read_hostent_nextonempty(hostentfp,AF_INET,result,buffer,buflen,errnop,h_errnop));
 }
 
+/* close the stream opened with sethostent() above */
 nss_status_t _nss_ldap_endhostent(void)
 {
   NSS_ENDENT(hostentfp);
diff --git a/nss/netgroup.c b/nss/netgroup.c
index 6315707..6691579 100644
--- a/nss/netgroup.c
+++ b/nss/netgroup.c
@@ -2,7 +2,7 @@
    netgroup.c - NSS lookup functions for netgroup entries
 
    Copyright (C) 2006 West Consulting
-   Copyright (C) 2006, 2007, 2008 Arthur de Jong
+   Copyright (C) 2006, 2007, 2008, 2010 Arthur de Jong
 
    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Lesser General Public
@@ -89,7 +89,9 @@ static nss_status_t read_netgrent(
 /* thread-local file pointer to an ongoing request */
 static __thread TFILE *netgrentfp;
 
-nss_status_t _nss_ldap_setnetgrent(const char *group,struct __netgrent UNUSED(*result))
+/* start a request to get a netgroup by name */
+nss_status_t _nss_ldap_setnetgrent(
+        const char *group,struct __netgrent UNUSED(*result))
 {
   /* we cannot use NSS_SETENT() here because we have a parameter that is only
      available in this function */
@@ -107,12 +109,16 @@ nss_status_t _nss_ldap_setnetgrent(const char *group,struct __netgrent UNUSED(*r
   return NSS_STATUS_SUCCESS;
 }
 
-nss_status_t _nss_ldap_getnetgrent_r(struct __netgrent *result,char *buffer,size_t buflen,int *errnop)
+/* get a single netgroup tuple from the stream */
+nss_status_t _nss_ldap_getnetgrent_r(
+        struct __netgrent *result,
+        char *buffer,size_t buflen,int *errnop)
 {
   NSS_GETENT(netgrentfp,NSLCD_ACTION_NETGROUP_BYNAME,
              read_netgrent(netgrentfp,result,buffer,buflen,errnop));
 }
 
+/* close the stream opened with setnetgrent() above */
 nss_status_t _nss_ldap_endnetgrent(struct __netgrent UNUSED(* result))
 {
   NSS_ENDENT(netgrentfp);
diff --git a/nss/networks.c b/nss/networks.c
index 3c7d10f..b3a4e39 100644
--- a/nss/networks.c
+++ b/nss/networks.c
@@ -29,7 +29,7 @@
 #include "common.h"
 #include "compat/attrs.h"
 
-/* Redifine some ERROR_OUT macros as we also want to set h_errnop. */
+/* Redefine some ERROR_OUT macros as we also want to set h_errnop. */
 
 #undef ERROR_OUT_OPENERROR
 #define ERROR_OUT_OPENERROR \
@@ -107,7 +107,10 @@ static nss_status_t read_netent(
   WRITE_INT32(fp,4); \
   WRITE_INT32(fp,htonl(addr));
 
-nss_status_t _nss_ldap_getnetbyname_r(const char *name,struct netent *result,char *buffer,size_t buflen,int *errnop,int *h_errnop)
+/* get a network entry by name */
+nss_status_t _nss_ldap_getnetbyname_r(
+        const char *name,struct netent *result,
+        char *buffer,size_t buflen,int *errnop,int *h_errnop)
 {
   NSS_BYNAME(NSLCD_ACTION_NETWORK_BYNAME,
              name,
@@ -116,7 +119,9 @@ nss_status_t _nss_ldap_getnetbyname_r(const char *name,struct netent *result,cha
 
 /* Note: the af parameter is ignored and is assumed to be AF_INET */
 /* TODO: implement handling of af parameter */
-nss_status_t _nss_ldap_getnetbyaddr_r(uint32_t addr,int UNUSED(af),struct netent *result,char *buffer,size_t buflen,int *errnop,int *h_errnop)
+nss_status_t _nss_ldap_getnetbyaddr_r(
+        uint32_t addr,int UNUSED(af),struct netent *result,
+        char *buffer,size_t buflen,int *errnop,int *h_errnop)
 {
   NSS_BYGEN(NSLCD_ACTION_NETWORK_BYADDR,
             WRITE_ADDRESS(fp,addr),
@@ -126,17 +131,22 @@ nss_status_t _nss_ldap_getnetbyaddr_r(uint32_t addr,int UNUSED(af),struct netent
 /* thread-local file pointer to an ongoing request */
 static __thread TFILE *netentfp;
 
+/* start a request to read all networks */
 nss_status_t _nss_ldap_setnetent(int UNUSED(stayopen))
 {
   NSS_SETENT(netentfp);
 }
 
-nss_status_t _nss_ldap_getnetent_r(struct netent *result,char *buffer,size_t buflen,int *errnop,int *h_errnop)
+/* get a single network entry from the stream */
+nss_status_t _nss_ldap_getnetent_r(
+        struct netent *result,
+        char *buffer,size_t buflen,int *errnop,int *h_errnop)
 {
   NSS_GETENT(netentfp,NSLCD_ACTION_NETWORK_ALL,
              read_netent(netentfp,result,buffer,buflen,errnop,h_errnop));
 }
 
+/* close the stream opened by setnetent() above */
 nss_status_t _nss_ldap_endnetent(void)
 {
   NSS_ENDENT(netentfp);
diff --git a/nss/passwd.c b/nss/passwd.c
index 6787d60..f4bf749 100644
--- a/nss/passwd.c
+++ b/nss/passwd.c
@@ -2,7 +2,7 @@
    passwd.c - NSS lookup functions for passwd database
 
    Copyright (C) 2006 West Consulting
-   Copyright (C) 2006, 2007, 2008 Arthur de Jong
+   Copyright (C) 2006, 2007, 2008, 2010 Arthur de Jong
 
    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Lesser General Public
@@ -29,6 +29,7 @@
 #include "common.h"
 #include "compat/attrs.h"
 
+/* read a passwd entry from the stream */
 static nss_status_t read_passwd(
         TFILE *fp,struct passwd *result,
         char *buffer,size_t buflen,int *errnop)
@@ -45,14 +46,20 @@ static nss_status_t read_passwd(
   return NSS_STATUS_SUCCESS;
 }
 
-nss_status_t _nss_ldap_getpwnam_r(const char *name,struct passwd *result,char *buffer,size_t buflen,int *errnop)
+/* get a single passwd entry by name */
+nss_status_t _nss_ldap_getpwnam_r(
+        const char *name,struct passwd *result,
+        char *buffer,size_t buflen,int *errnop)
 {
   NSS_BYNAME(NSLCD_ACTION_PASSWD_BYNAME,
              name,
              read_passwd(fp,result,buffer,buflen,errnop));
 }
 
-nss_status_t _nss_ldap_getpwuid_r(uid_t uid,struct passwd *result,char *buffer,size_t buflen,int *errnop)
+/* get a single passwd entry by uid */
+nss_status_t _nss_ldap_getpwuid_r(
+        uid_t uid,struct passwd *result,
+        char *buffer,size_t buflen,int *errnop)
 {
   NSS_BYTYPE(NSLCD_ACTION_PASSWD_BYUID,
              uid,uid_t,
@@ -62,14 +69,16 @@ nss_status_t _nss_ldap_getpwuid_r(uid_t uid,struct passwd *result,char *buffer,s
 /* thread-local file pointer to an ongoing request */
 static __thread TFILE *pwentfp;
 
-/* open a connection to the nslcd and write the request */
+/* open a connection to read all passwd entries */
 nss_status_t _nss_ldap_setpwent(int UNUSED(stayopen))
 {
   NSS_SETENT(pwentfp);
 }
 
 /* read password data from an opened stream */
-nss_status_t _nss_ldap_getpwent_r(struct passwd *result,char *buffer,size_t buflen,int *errnop)
+nss_status_t _nss_ldap_getpwent_r(
+        struct passwd *result,
+        char *buffer,size_t buflen,int *errnop)
 {
   NSS_GETENT(pwentfp,NSLCD_ACTION_PASSWD_ALL,
              read_passwd(pwentfp,result,buffer,buflen,errnop));
diff --git a/nss/protocols.c b/nss/protocols.c
index 165c24f..cb32923 100644
--- a/nss/protocols.c
+++ b/nss/protocols.c
@@ -2,7 +2,7 @@
    protocols.c - NSS lookup functions for protocol database
 
    Copyright (C) 2006 West Consulting
-   Copyright (C) 2006, 2007, 2008 Arthur de Jong
+   Copyright (C) 2006, 2007, 2008, 2010 Arthur de Jong
 
    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Lesser General Public
@@ -29,6 +29,7 @@
 #include "common.h"
 #include "compat/attrs.h"
 
+/* read a single protocol entry from the stream */
 static nss_status_t read_protoent(
         TFILE *fp,struct protoent *result,
         char *buffer,size_t buflen,int *errnop)
@@ -41,14 +42,20 @@ static nss_status_t read_protoent(
   return NSS_STATUS_SUCCESS;
 }
 
-nss_status_t _nss_ldap_getprotobyname_r(const char *name,struct protoent *result,char *buffer,size_t buflen,int *errnop)
+/* get a protocol entry by name */
+nss_status_t _nss_ldap_getprotobyname_r(
+        const char *name,struct protoent *result,
+        char *buffer,size_t buflen,int *errnop)
 {
   NSS_BYNAME(NSLCD_ACTION_PROTOCOL_BYNAME,
              name,
              read_protoent(fp,result,buffer,buflen,errnop));
 }
 
-nss_status_t _nss_ldap_getprotobynumber_r(int number,struct protoent *result,char *buffer,size_t buflen,int *errnop)
+/* get a protocol entry by number */
+nss_status_t _nss_ldap_getprotobynumber_r(
+        int number,struct protoent *result,
+        char *buffer,size_t buflen,int *errnop)
 {
   NSS_BYINT32(NSLCD_ACTION_PROTOCOL_BYNUMBER,
               number,
@@ -58,17 +65,22 @@ nss_status_t _nss_ldap_getprotobynumber_r(int number,struct protoent *result,cha
 /* thread-local file pointer to an ongoing request */
 static __thread TFILE *protoentfp;
 
+/* start a request to read all protocol entries */
 nss_status_t _nss_ldap_setprotoent(int UNUSED(stayopen))
 {
   NSS_SETENT(protoentfp);
 }
 
-nss_status_t _nss_ldap_getprotoent_r(struct protoent *result,char *buffer,size_t buflen,int *errnop)
+/* get a single protocol entry */
+nss_status_t _nss_ldap_getprotoent_r(
+        struct protoent *result,
+        char *buffer,size_t buflen,int *errnop)
 {
   NSS_GETENT(protoentfp,NSLCD_ACTION_PROTOCOL_ALL,
              read_protoent(protoentfp,result,buffer,buflen,errnop));
 }
 
+/* close the stream opened by setprotoent() above */
 nss_status_t _nss_ldap_endprotoent(void)
 {
   NSS_ENDENT(protoentfp);
diff --git a/nss/rpc.c b/nss/rpc.c
index 596d650..f4663ae 100644
--- a/nss/rpc.c
+++ b/nss/rpc.c
@@ -2,7 +2,7 @@
    rpc.c - NSS lookup functions for rpc database
 
    Copyright (C) 2006 West Consulting
-   Copyright (C) 2006, 2007, 2008 Arthur de Jong
+   Copyright (C) 2006, 2007, 2008, 2010 Arthur de Jong
 
    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Lesser General Public
@@ -29,6 +29,7 @@
 #include "common.h"
 #include "compat/attrs.h"
 
+/* read a sinlge rpc entry from the stream */
 static nss_status_t read_rpcent(
         TFILE *fp,struct rpcent *result,
         char *buffer,size_t buflen,int *errnop)
@@ -41,14 +42,20 @@ static nss_status_t read_rpcent(
   return NSS_STATUS_SUCCESS;
 }
 
-nss_status_t _nss_ldap_getrpcbyname_r(const char *name,struct rpcent *result,char *buffer,size_t buflen,int *errnop)
+/* get a rpc entry by name */
+nss_status_t _nss_ldap_getrpcbyname_r(
+        const char *name,struct rpcent *result,
+        char *buffer,size_t buflen,int *errnop)
 {
   NSS_BYNAME(NSLCD_ACTION_RPC_BYNAME,
              name,
              read_rpcent(fp,result,buffer,buflen,errnop));
 }
 
-nss_status_t _nss_ldap_getrpcbynumber_r(int number,struct rpcent *result,char *buffer,size_t buflen,int *errnop)
+/* get a rpc entry by number */
+nss_status_t _nss_ldap_getrpcbynumber_r(
+        int number,struct rpcent *result,
+        char *buffer,size_t buflen,int *errnop)
 {
   NSS_BYINT32(NSLCD_ACTION_RPC_BYNUMBER,
               number,
@@ -58,17 +65,22 @@ nss_status_t _nss_ldap_getrpcbynumber_r(int number,struct rpcent *result,char *b
 /* thread-local file pointer to an ongoing request */
 static __thread TFILE *protoentfp;
 
+/* request a stream to list all rpc entries */
 nss_status_t _nss_ldap_setrpcent(int UNUSED(stayopen))
 {
   NSS_SETENT(protoentfp);
 }
 
-nss_status_t _nss_ldap_getrpcent_r(struct rpcent *result,char *buffer,size_t buflen,int *errnop)
+/* get an rpc entry from the list */
+nss_status_t _nss_ldap_getrpcent_r(
+        struct rpcent *result,
+        char *buffer,size_t buflen,int *errnop)
 {
   NSS_GETENT(protoentfp,NSLCD_ACTION_RPC_ALL,
              read_rpcent(protoentfp,result,buffer,buflen,errnop));
 }
 
+/* close the stream opened by setrpcent() above */
 nss_status_t _nss_ldap_endrpcent(void)
 {
   NSS_ENDENT(protoentfp);
diff --git a/nss/services.c b/nss/services.c
index 066acb5..39260c6 100644
--- a/nss/services.c
+++ b/nss/services.c
@@ -2,7 +2,7 @@
    service.c - NSS lookup functions for services database
 
    Copyright (C) 2006 West Consulting
-   Copyright (C) 2006, 2007, 2008 Arthur de Jong
+   Copyright (C) 2006, 2007, 2008, 2010 Arthur de Jong
 
    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Lesser General Public
@@ -29,6 +29,7 @@
 #include "common.h"
 #include "compat/attrs.h"
 
+/* read a single services result entry from the stream */
 static nss_status_t read_servent(
         TFILE *fp,struct servent *result,
         char *buffer,size_t buflen,int *errnop)
@@ -45,7 +46,10 @@ static nss_status_t read_servent(
   return NSS_STATUS_SUCCESS;
 }
 
-nss_status_t _nss_ldap_getservbyname_r(const char *name,const char *protocol,struct servent *result,char *buffer,size_t buflen,int *errnop)
+/* get a service entry by name and protocol */
+nss_status_t _nss_ldap_getservbyname_r(
+        const char *name,const char *protocol,struct servent *result,
+        char *buffer,size_t buflen,int *errnop)
 {
   NSS_BYGEN(NSLCD_ACTION_SERVICE_BYNAME,
             WRITE_STRING(fp,name);WRITE_STRING(fp,protocol),
@@ -53,7 +57,10 @@ nss_status_t _nss_ldap_getservbyname_r(const char *name,const char *protocol,str
 
 }
 
-nss_status_t _nss_ldap_getservbyport_r(int port,const char *protocol,struct servent *result,char *buffer,size_t buflen,int *errnop)
+/* get a service entry by port and protocol */
+nss_status_t _nss_ldap_getservbyport_r(
+        int port,const char *protocol,struct servent *result,
+        char *buffer,size_t buflen,int *errnop)
 {
   NSS_BYGEN(NSLCD_ACTION_SERVICE_BYNUMBER,
             WRITE_INT32(fp,ntohs(port));WRITE_STRING(fp,protocol),
@@ -63,17 +70,22 @@ nss_status_t _nss_ldap_getservbyport_r(int port,const char *protocol,struct serv
 /* thread-local file pointer to an ongoing request */
 static __thread TFILE *protoentfp;
 
+/* open request to get all services */
 nss_status_t _nss_ldap_setservent(int UNUSED(stayopen))
 {
   NSS_SETENT(protoentfp);
 }
 
-nss_status_t _nss_ldap_getservent_r(struct servent *result,char *buffer,size_t buflen,int *errnop)
+/* read a single returned service definition */
+nss_status_t _nss_ldap_getservent_r(
+        struct servent *result,
+        char *buffer,size_t buflen,int *errnop)
 {
   NSS_GETENT(protoentfp,NSLCD_ACTION_SERVICE_ALL,
              read_servent(protoentfp,result,buffer,buflen,errnop));
 }
 
+/* close the stream opened by setservent() above */
 nss_status_t _nss_ldap_endservent(void)
 {
   NSS_ENDENT(protoentfp);
diff --git a/nss/shadow.c b/nss/shadow.c
index 8132e17..2fca8d1 100644
--- a/nss/shadow.c
+++ b/nss/shadow.c
@@ -2,7 +2,7 @@
    shadow.c - NSS lookup functions for shadow database
 
    Copyright (C) 2006 West Consulting
-   Copyright (C) 2006, 2007, 2008 Arthur de Jong
+   Copyright (C) 2006, 2007, 2008, 2010 Arthur de Jong
 
    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Lesser General Public
@@ -29,6 +29,7 @@
 #include "common.h"
 #include "compat/attrs.h"
 
+/* read a single shadow entry from the stream */
 static nss_status_t read_spwd(
         TFILE *fp,struct spwd *result,
         char *buffer,size_t buflen,int *errnop)
@@ -47,7 +48,10 @@ static nss_status_t read_spwd(
   return NSS_STATUS_SUCCESS;
 }
 
-nss_status_t _nss_ldap_getspnam_r(const char *name,struct spwd *result,char *buffer,size_t buflen,int *errnop)
+/* get a shadow entry by name */
+nss_status_t _nss_ldap_getspnam_r(
+        const char *name,struct spwd *result,
+        char *buffer,size_t buflen,int *errnop)
 {
   NSS_BYNAME(NSLCD_ACTION_SHADOW_BYNAME,
              name,
@@ -57,17 +61,22 @@ nss_status_t _nss_ldap_getspnam_r(const char *name,struct spwd *result,char *buf
 /* thread-local file pointer to an ongoing request */
 static __thread TFILE *spentfp;
 
+/* start listing all shadow users */
 nss_status_t _nss_ldap_setspent(int UNUSED(stayopen))
 {
   NSS_SETENT(spentfp);
 }
 
-nss_status_t _nss_ldap_getspent_r(struct spwd *result,char *buffer,size_t buflen,int *errnop)
+/* return a single shadow entry read from the stream */
+nss_status_t _nss_ldap_getspent_r(
+        struct spwd *result,
+        char *buffer,size_t buflen,int *errnop)
 {
   NSS_GETENT(spentfp,NSLCD_ACTION_SHADOW_ALL,
              read_spwd(spentfp,result,buffer,buflen,errnop));
 }
 
+/* close the stream opened by setspent() above */
 nss_status_t _nss_ldap_endspent(void)
 {
   NSS_ENDENT(spentfp);