2000-12-30 Marcus Brinkmann <marcus@gnu.org>

	* netfs.h (struct node): Adjust comment fixes by last change
	to be more in line with similar comments elsewhere.
	* make-node.c (netfs_make_node): Return 0 if malloc does.
	Reported by Neal H Walfield <neal@cs.uml.edu>.

2000-12-29  Neal H Walfield <neal@cs.uml.edu>

        * dir-lookup.c (netfs_S_dir_lookup):  Do not bother zeroing np, it
	happens later anyway.  Replace bcopy with memcpy.
	* file-get-translator.c (netfs_S_file_get_translator): Replace
	bcopy with memcpy.
	* io-seek.c (netfs_S_io_seek): Only get the lock if we need it.
	* io-stat.c (netfs_S_io_stat): Replace bcopy with memcpy.
	* io-write.c (netfs_S_io_write): Wait until the lock is needed.
	* netfs.h: Complete documentation revision.  The locking protocol
	is now very explicit.
	* nput.c (netfs_nput): Added comment.
	* nrele.c (netfs_nrele): Likewise.
	* set-get-trans.c: Likewise.

13 files changed, 205 insertions, 120 deletions

diff --git a/libnetfs/ChangeLog b/libnetfs/ChangeLog
index 3afcd466..c2bce820 100644
--- a/libnetfs/ChangeLog
+++ b/libnetfs/ChangeLog
@@ -1,3 +1,25 @@
+2000-12-30  Marcus Brinkmann  <marcus@gnu.org>
+
+	* netfs.h (struct node): Adjust comment fixes by last change
+	to be more in line with similar comments elsewhere.
+	* make-node.c (netfs_make_node): Return 0 if malloc does.
+	Reported by Neal H Walfield <neal@cs.uml.edu>.
+
+2000-12-29  Neal H Walfield <neal@cs.uml.edu>
+
+        * dir-lookup.c (netfs_S_dir_lookup):  Do not bother zeroing np, it
+	happens later anyway.  Replace bcopy with memcpy.
+	* file-get-translator.c (netfs_S_file_get_translator): Replace
+	bcopy with memcpy.
+	* io-seek.c (netfs_S_io_seek): Only get the lock if we need it.
+	* io-stat.c (netfs_S_io_stat): Replace bcopy with memcpy.
+	* io-write.c (netfs_S_io_write): Wait until the lock is needed.
+	* netfs.h: Complete documentation revision.  The locking protocol
+	is now very explicit.
+	* nput.c (netfs_nput): Added comment.
+	* nrele.c (netfs_nrele): Likewise.
+	* set-get-trans.c: Likewise.
+
 2000-03-17  Roland McGrath  <roland@baalperazim.frob.com>
 
 	* file-exec.c (netfs_S_file_exec): Fix typo and braino in last change.
diff --git a/libnetfs/dir-lookup.c b/libnetfs/dir-lookup.c
index 6b5cfda9..ed7853ec 100644
--- a/libnetfs/dir-lookup.c
+++ b/libnetfs/dir-lookup.c
@@ -75,7 +75,6 @@ netfs_S_dir_lookup (struct protid *diruser,
 
   dnp = diruser->po->np;
   mutex_lock (&dnp->lock);
-  np = 0;
 
   netfs_nref (dnp);		/* acquire a reference for later netfs_nput */
 
@@ -300,7 +299,7 @@ netfs_S_dir_lookup (struct protid *diruser,
 	  if (nextname)
 	    {
 	      linkbuf[linklen] = '/';
-	      bcopy (nextname, linkbuf + linklen + 1,
+	      memcpy (linkbuf + linklen + 1, nextname,
 		     nextnamelen - 1);
 	    }
 	  linkbuf[nextnamelen + linklen] = '\0';
diff --git a/libnetfs/file-get-translator.c b/libnetfs/file-get-translator.c
index 1489162a..44caa91c 100644
--- a/libnetfs/file-get-translator.c
+++ b/libnetfs/file-get-translator.c
@@ -1,5 +1,5 @@
 /*
-   Copyright (C) 1996, 1999 Free Software Foundation, Inc.
+   Copyright (C) 1996, 1999, 2000 Free Software Foundation, Inc.
    Written by Michael I. Bushnell, p/BSG.
 
    This file is part of the GNU Hurd.
@@ -52,7 +52,7 @@ netfs_S_file_get_translator (struct protid *user,
 
       if (len  > *translen)
 	*trans = mmap (0, len, PROT_READ|PROT_WRITE, MAP_ANON, 0, 0);
-      bcopy (_HURD_SYMLINK, *trans, sizeof _HURD_SYMLINK);
+      memcpy (*trans, _HURD_SYMLINK, sizeof _HURD_SYMLINK);
 
       err = netfs_attempt_readlink (user->user, np,
 				    *trans + sizeof _HURD_SYMLINK);
@@ -77,7 +77,7 @@ netfs_S_file_get_translator (struct protid *user,
 
       if (buflen > *translen)
 	*trans = mmap (0, buflen, PROT_READ|PROT_WRITE, MAP_ANON, 0, 0);
-      bcopy (buf, *trans, buflen);
+      memcpy (*trans, buf, buflen);
       free (buf);
       *translen = buflen;
       err = 0;
@@ -89,7 +89,7 @@ netfs_S_file_get_translator (struct protid *user,
       len = sizeof _HURD_FIFO;
       if (len > *translen)
 	*trans = mmap (0, len, PROT_READ|PROT_WRITE, MAP_ANON, 0, 0);
-      bcopy (_HURD_FIFO, *trans, sizeof _HURD_FIFO);
+      memcpy (*trans, _HURD_FIFO, sizeof _HURD_FIFO);
       *translen = len;
       err = 0;
     }
@@ -100,7 +100,7 @@ netfs_S_file_get_translator (struct protid *user,
       len = sizeof _HURD_IFSOCK;
       if (len > *translen)
         *trans = mmap (0, len, PROT_READ|PROT_WRITE, MAP_ANON, 0, 0);
-      bcopy (_HURD_IFSOCK, *trans, sizeof _HURD_IFSOCK);
+      memcpy (*trans, _HURD_IFSOCK, sizeof _HURD_IFSOCK);
       *translen = len;
       err = 0;
     }
diff --git a/libnetfs/io-revoke.c b/libnetfs/io-revoke.c
index a5e27802..5b32622a 100644
--- a/libnetfs/io-revoke.c
+++ b/libnetfs/io-revoke.c
@@ -26,17 +26,16 @@ netfs_S_io_revoke (struct protid *cred)
   error_t err;
   struct node *np;
 
-  error_t
-    iterator_function (void *port)
+  error_t iterator_function (void *port)
     {
       struct protid *user = port;
-
+      
       if ((user != cred)
 	  && (user->po->np == np))
 	ports_destroy_right (user);
       return 0;
     }
-
+  
   if (!cred)
     return EOPNOTSUPP;
 
diff --git a/libnetfs/io-seek.c b/libnetfs/io-seek.c
index 1e517ff4..401c5004 100644
--- a/libnetfs/io-seek.c
+++ b/libnetfs/io-seek.c
@@ -1,5 +1,5 @@
 /* 
-   Copyright (C) 1995, 1996 Free Software Foundation, Inc.
+   Copyright (C) 1995, 1996, 2000 Free Software Foundation, Inc.
    Written by Michael I. Bushnell, p/BSG.
 
    This file is part of the GNU Hurd.
@@ -33,7 +33,6 @@ netfs_S_io_seek (struct protid *user,
   if (!user)
     return EOPNOTSUPP;
 
-  mutex_lock (&user->po->np->lock);
   switch (whence)
     {
     case SEEK_SET:
@@ -47,17 +46,27 @@ netfs_S_io_seek (struct protid *user,
       break;
       
     case SEEK_END:
-      err = netfs_validate_stat (user->po->np, user->user);
-      if (!err)
-	user->po->filepointer = user->po->np->nn_stat.st_size + offset;
-      break;
+      {
+        struct node *np;
+
+        np = user->po->np;
+        mutex_lock (&np->lock);
+
+        err = netfs_validate_stat (np, user->user);
+        if (!err)
+	  user->po->filepointer = np->nn_stat.st_size + offset;
+
+        mutex_unlock (&np->lock);
+
+        break;
+      }
       
     default:
       err = EINVAL;
       break;
     }
+
   *newoffset = user->po->filepointer;
-  mutex_unlock (&user->po->np->lock);
   return err;
 }
 
diff --git a/libnetfs/io-stat.c b/libnetfs/io-stat.c
index 5f086318..3826c9d9 100644
--- a/libnetfs/io-stat.c
+++ b/libnetfs/io-stat.c
@@ -1,5 +1,5 @@
 /* 
-   Copyright (C) 1995, 1996, 1997 Free Software Foundation, Inc.
+   Copyright (C) 1995, 1996, 1997, 2000 Free Software Foundation, Inc.
    Written by Michael I. Bushnell, p/BSG.
 
    This file is part of the GNU Hurd.
@@ -37,7 +37,7 @@ netfs_S_io_stat (struct protid *user, io_statbuf_t *statbuf)
   err = netfs_validate_stat (node, user->user);
   if (! err)
     {
-      bcopy (&node->nn_stat, statbuf, sizeof (struct stat));
+      memcpy (statbuf, &node->nn_stat, sizeof (struct stat));
 
       /* Set S_IATRANS and S_IROOT bits as appropriate.  */
       statbuf->st_mode &= ~(S_IATRANS | S_IROOT);
diff --git a/libnetfs/io-write.c b/libnetfs/io-write.c
index 26c3c297..c4423dab 100644
--- a/libnetfs/io-write.c
+++ b/libnetfs/io-write.c
@@ -1,5 +1,5 @@
 /* 
-   Copyright (C) 1995, 1996 Free Software Foundation, Inc.
+   Copyright (C) 1995, 1996, 2000 Free Software Foundation, Inc.
    Written by Michael I. Bushnell, p/BSG.
 
    This file is part of the GNU Hurd.
@@ -36,17 +36,14 @@ netfs_S_io_write (struct protid *user,
   if (!user)
     return EOPNOTSUPP;
   
-  np = user->po->np;
-
-  mutex_lock (&np->lock);
   if ((user->po->openstat & O_WRITE) == 0)
-    {
-      mutex_unlock (&np->lock);
-      return EBADF;
-    }
+    return EBADF;
 
   *amount = datalen;
 
+  np = user->po->np;
+  mutex_lock (&np->lock);
+
   if (off == -1)
     {
       if (user->po->openstat & O_APPEND)
diff --git a/libnetfs/make-node.c b/libnetfs/make-node.c
index 973744e7..c547bfcb 100644
--- a/libnetfs/make-node.c
+++ b/libnetfs/make-node.c
@@ -1,5 +1,5 @@
 /* 
-   Copyright (C) 1995, 1996 Free Software Foundation, Inc.
+   Copyright (C) 1995, 1996, 2000 Free Software Foundation, Inc.
    Written by Michael I. Bushnell, p/BSG.
 
    This file is part of the GNU Hurd.
@@ -25,6 +25,8 @@ struct node *
 netfs_make_node (struct netnode *nn)
 {
   struct node *np = malloc (sizeof (struct node));
+  if (! np)
+    return NULL;
   
   np->nn = nn;
 
diff --git a/libnetfs/netfs.h b/libnetfs/netfs.h
index d75dfe39..b7cb9aaf 100644
--- a/libnetfs/netfs.h
+++ b/libnetfs/netfs.h
@@ -1,6 +1,6 @@
 /* 
 
-   Copyright (C) 1994, 1995, 1996, 1997, 1999 Free Software Foundation
+   Copyright (C) 1994, 1995, 1996, 1997, 1999, 2000 Free Software Foundation
 
    This program is free software; you can redistribute it and/or
    modify it under the terms of the GNU General Public License as
@@ -69,17 +69,19 @@ struct node
 {
   struct node *next, **prevp;
   
-  /* Protocol specific stuff. */
+  /* Protocol specific stuff; defined by user.  */
   struct netnode *nn;
 
+  /* The stat information for this particular node.  */
   struct stat nn_stat;
   
   struct mutex lock;
   
+  /* The number of references to this node.  */
   int references;
   
   mach_port_t sockaddr;
-  
+
   int owner;
   
   struct transbox transbox;
@@ -92,185 +94,197 @@ struct node
 };
 
 /* The user must define this function.  Make sure that NP->nn_stat is
-   filled with current information.  CRED identifies the user
-   responsible for the operation.  */
-error_t netfs_validate_stat (struct node *NP, struct iouser *cred);
+   filled with the most current information.  CRED identifies the user
+   responsible for the operation. NP is locked.  */
+error_t netfs_validate_stat (struct node *np, struct iouser *cred);
 
 /* The user must define this function.  This should attempt a chmod
-   call for the user specified by CRED on node NODE, to change the
-   owner to UID and the group to GID. */
+   call for the user specified by CRED on locked node NP, to change
+   the owner to UID and the group to GID.  */
 error_t netfs_attempt_chown (struct iouser *cred, struct node *np,
 			     uid_t uid, uid_t gid);
 
 /* The user must define this function.  This should attempt a chauthor
-   call for the user specified by CRED on node NODE, to change the
-   author to AUTHOR. */
+   call for the user specified by CRED on locked node NP, thereby
+   changing the author to AUTHOR.  */
 error_t netfs_attempt_chauthor (struct iouser *cred, struct node *np,
 				uid_t author);
 
 /* The user must define this function.  This should attempt a chmod
-   call for the user specified by CRED on node NODE, to change the
-   mode to MODE.  Unlike the normal Unix and Hurd meaning of chmod,
-   this function is also used to attempt to change files into other
-   types.  If such a transition is attempted which is impossible, then
-   return EOPNOTSUPP.
-  */
+   call for the user specified by CRED on locked node NP, thereby
+   changing the mode to MODE.  */
 error_t netfs_attempt_chmod (struct iouser *cred, struct node *np,
 			     mode_t mode);
 
-/* The user must define this function.  Attempt to turn NODE (user CRED)
-   into a symlink with target NAME. */
+/* The user must define this function.  Attempt to turn locked node NP
+   (user CRED) into a symlink with target NAME.  */
 error_t netfs_attempt_mksymlink (struct iouser *cred, struct node *np,
 				 char *name);
 
 /* The user must define this function.  Attempt to turn NODE (user
-   CRED) into a device.  TYPE is either S_IFBLK or S_IFCHR. */
+   CRED) into a device.  TYPE is either S_IFBLK or S_IFCHR.  NP is
+   locked.  */
 error_t netfs_attempt_mkdev (struct iouser *cred, struct node *np,
 			     mode_t type, dev_t indexes);
 
 /* The user may define this function.  Attempt to set the passive
    translator record for FILE to ARGZ (of length ARGZLEN) for user
-   CRED. */
+   CRED. NP is locked.  */
 error_t netfs_set_translator (struct iouser *cred, struct node *np,
 			      char *argz, size_t argzlen);
 
-/* The user may define this function (but should define it together with
-   netfs_set_translator).  For locked node NODE with S_IPTRANS set in its
-   mode, look up the name of its translator.  Store the name into newly
-   malloced storage, and return it in *ARGZ; set *ARGZ_LEN to the total
-   length.  */
-error_t netfs_get_translator (struct node *node, char **argz, size_t *argz_len);
+/* The user may define this function (but should define it together
+   with netfs_set_translator).  For locked node NODE with S_IPTRANS
+   set in its mode, look up the name of its translator.  Store the
+   name into newly malloced storage, and return it in *ARGZ; set
+   *ARGZ_LEN to the total length.  */
+error_t netfs_get_translator (struct node *node, char **argz,
+			      size_t *argz_len);
 
 /* The user must define this function.  This should attempt a chflags
-   call for the user specified by CRED on node NODE, to change the
-   flags to FLAGS. */
+   call for the user specified by CRED on locked node NP, to change
+   the flags to FLAGS.  */
 error_t netfs_attempt_chflags (struct iouser *cred, struct node *np,
 			       int flags);
 
 /* The user must define this function.  This should attempt a utimes
-   call for the user specified by CRED on node NODE, to change the
-   atime to ATIME and the mtime to MTIME.  If ATIME or MTIME is null,
-   then set to the current time.  */
+   call for the user specified by CRED on locked node NP, to change
+   the atime to ATIME and the mtime to MTIME.  If ATIME or MTIME is
+   null, then set to the current time.  */
 error_t netfs_attempt_utimes (struct iouser *cred, struct node *np,
 			      struct timespec *atime, struct timespec *mtime);
 
 /* The user must define this function.  This should attempt to set the
-   size of the file NODE (for user CRED) to SIZE bytes long. */
+   size of the locked file NP (for user CRED) to SIZE bytes long.  */
 error_t netfs_attempt_set_size (struct iouser *cred, struct node *np,
 				off_t size);
 
 /* The user must define this function.  This should attempt to fetch
    filesystem status information for the remote filesystem, for the
-   user CRED. */
+   user CRED. NP is locked.  */
 error_t netfs_attempt_statfs (struct iouser *cred, struct node *np,
 			      struct statfs *st);
 
-/* The user must define this function.  This should sync the file NP
-   completely to disk, for the user CRED.  If WAIT is set, return
-   only after sync is completely finished.  */
+/* The user must define this function.  This should sync the locked
+   file NP completely to disk, for the user CRED.  If WAIT is set,
+   return only after the sync is completely finished.  */
 error_t netfs_attempt_sync (struct iouser *cred, struct node *np,
 			    int wait);
 
 /* The user must define this function.  This should sync the entire
-   remote filesystem.  If WAIT is set, return only after
-   sync is completely finished.  */
+   remote filesystem.  If WAIT is set, return only after the sync is
+   completely finished.  */
 error_t netfs_attempt_syncfs (struct iouser *cred, int wait);
 
-/* The user must define this function.  Lookup NAME in DIR for USER;
-   set *NP to the found name upon return.  If the name was not found,
-   then return ENOENT.  On any error, clear *NP.  (*NP, if found, should
-   be locked, this call should unlock DIR no matter what.) */
+/* The user must define this function.  Lookup NAME in DIR (which is
+   locked) for USER; set *NP to the found name upon return.  If the
+   name was not found, then return ENOENT.  On any error, clear *NP.
+   (*NP, if found, should be locked, this call should unlock DIR no
+   matter what.)  */
 error_t netfs_attempt_lookup (struct iouser *user, struct node *dir, 
 			      char *name, struct node **np);
 
-/* The user must define this function.  Delete NAME in DIR for USER. */
+/* The user must define this function.  Delete NAME in DIR (which is
+   locked) for USER.  */
 error_t netfs_attempt_unlink (struct iouser *user, struct node *dir,
 			      char *name);
 
-/* Note that in this one call, neither of the specific nodes are locked. */
+/* The user must define this function.  Attempt to rename the
+   directory FROMDIR to TODIR. Note that neither of the specific nodes
+   are locked.  */
 error_t netfs_attempt_rename (struct iouser *user, struct node *fromdir,
 			      char *fromname, struct node *todir, 
 			      char *toname, int excl);
 
 /* The user must define this function.  Attempt to create a new
-   directory named NAME in DIR for USER with mode MODE.  */
+   directory named NAME in DIR (which is locked) for USER with mode
+   MODE. */
 error_t netfs_attempt_mkdir (struct iouser *user, struct node *dir,
 			     char *name, mode_t mode);
 
 /* The user must define this function.  Attempt to remove directory
-   named NAME in DIR for USER. */
+   named NAME in DIR (which is locked) for USER.  */
 error_t netfs_attempt_rmdir (struct iouser *user, 
 			     struct node *dir, char *name);
 
 
 /* The user must define this function.  Create a link in DIR with name
-   NAME to FILE for USER.  Note that neither DIR nor FILE are
-   locked.  If EXCL is set, do not delete the target, but return EEXIST
-   if NAME is already found in DIR.   */
+   NAME to FILE for USER. Note that neither DIR nor FILE are
+   locked. If EXCL is set, do not delete the target.  Return EEXIST if
+   NAME is already found in DIR.  */
 error_t netfs_attempt_link (struct iouser *user, struct node *dir,
 			    struct node *file, char *name, int excl);
 
 /* The user must define this function.  Attempt to create an anonymous
-   file related to DIR for USER with MODE.  Set *NP to the returned
-   file upon success.  No matter what, unlock DIR. */
+   file related to DIR (which is locked) for USER with MODE.  Set *NP
+   to the returned file upon success. No matter what, unlock DIR.  */
 error_t netfs_attempt_mkfile (struct iouser *user, struct node *dir,
 			      mode_t mode, struct node **np);
 
 /* The user must define this function.  Attempt to create a file named
-   NAME in DIR for USER with MODE.  Set *NP to the new node upon
-   return.  On any error, clear *NP.  *NP should be locked on success;
-   no matter what, unlock DIR before returning.  */
+   NAME in DIR (which is locked) for USER with MODE.  Set *NP to the
+   new node upon return.  On any error, clear *NP.  *NP should be
+   locked on success; no matter what, unlock DIR before returning.  */
 error_t netfs_attempt_create_file (struct iouser *user, struct node *dir,
 				   char *name, mode_t mode, struct node **np);
 
-/* The user must define this function.  Read the contents of NP (a symlink),
-   for USER, into BUF. */
+/* The user must define this function.  Read the contents of locked
+   node NP (a symlink), for USER, into BUF.  */
 error_t netfs_attempt_readlink (struct iouser *user, struct node *np,
 				char *buf);
 
-/* The user must define this function.  Node NP is being opened by USER,
-   with FLAGS.  NEWNODE is nonzero if we just created this node.  Return
-   an error if we should not permit the open to complete because of a
-   permission restriction. */
+/* The user must define this function. Locked node NP is being opened
+   by USER, with FLAGS.  NEWNODE is nonzero if we just created this
+   node.  Return an error if we should not permit the open to complete
+   because of a permission restriction.  */
 error_t netfs_check_open_permissions (struct iouser *user, struct node *np,
 				      int flags, int newnode);
 
-/* The user must define this function.  Read from the file NP for user
-   CRED starting at OFFSET and continuing for up to *LEN bytes.  Put
-   the data at DATA.  Set *LEN to the amount successfully read upon
-   return.  */
+/* The user must define this function.  Read from the locked file NP
+   for user CRED starting at OFFSET and continuing for up to *LEN
+   bytes.  Put the data at DATA.  Set *LEN to the amount successfully
+   read upon return.  */
 error_t netfs_attempt_read (struct iouser *cred, struct node *np,
 			    off_t offset, size_t *len, void *data);
 
-/* The user must define this function.  Write to the file NP for user
-   CRED starting at OFSET and continuing for up to *LEN bytes from
-   DATA.  Set *LEN to the amount seccessfully written upon return. */
+/* The user must define this function.  Write to the locked file NP
+   for user CRED starting at OFSET and continuing for up to *LEN bytes
+   from DATA.  Set *LEN to the amount seccessfully written upon
+   return.  */
 error_t netfs_attempt_write (struct iouser *cred, struct node *np,
 			     off_t offset, size_t *len, void *data);
 
 /* The user must define this function.  Return the valid access
    types (bitwise OR of O_READ, O_WRITE, and O_EXEC) in *TYPES for
-   file NP and user CRED.   */
+   locked file NP and user CRED.  */
 error_t netfs_report_access (struct iouser *cred, struct node *np,
 			     int *types);
 
-/* The user must define this function.  Create a new user
-   from the specified UID and GID arrays. */
+/* The user must define this function.  Create a new user from the
+   specified UID and GID arrays. */
 struct iouser *netfs_make_user (uid_t *uids, int nuids,
 				       uid_t *gids, int ngids);
 
-/* The user must define this function.  Node NP is all done; free
-   all its associated storage. */
+/* The user must define this function.  Node NP has no more references;
+   free all its associated storage. */
 void netfs_node_norefs (struct node *np);
 
-error_t netfs_get_dirents (struct iouser *, struct node *, int, int, char **,
-			   mach_msg_type_number_t *, vm_size_t, int *);
+/* The user must define this function.  Fill the array *DATA of size
+   BUFSIZE with up to NENTRIES dirents from DIR (which is locked)
+   starting with entry ENTRY for user CRED.  The number of entries in
+   the array is stored in *AMT and the number of bytes in *DATACNT.
+   If the supplied buffer is not large enough to hold the data, it
+   should be grown.  */
+error_t netfs_get_dirents (struct iouser *cred, struct node *dir,
+                           int entry, int nentries, char **data,
+			   mach_msg_type_number_t *datacnt,
+			   vm_size_t bufsize, int *amt);
 
 /* Option parsing */
 
 /* Parse and execute the runtime options in ARGZ & ARGZ_LEN.  EINVAL is
    returned if some option is unrecognized.  The default definition of this
-   routine will parse them using NETFS_RUNTIME_ARGP, which see.  */
+   routine will parse them using NETFS_RUNTIME_ARGP. */
 error_t netfs_set_options (char *argz, size_t argz_len);
 
 /* Append to the malloced string *ARGZ of length *ARGZ_LEN a NUL-separated
@@ -300,31 +314,73 @@ extern const struct argp netfs_std_startup_argp;
    must already have a sane value).  */
 error_t netfs_append_std_options (char **argz, size_t *argz_len);
 
+/* Definitions provided by user */
+
+/* Maximum number of symlinks to follow before returning ELOOP. */
+extern int netfs_maxsymlinks;
+
 /* Definitions provided by netfs. */
-struct node *netfs_make_node (struct netnode *);
 
-mach_port_t netfs_startup (mach_port_t, int);
+/* Given a netnode created by the user program, wraps it in a node
+   structure.  The new node is not locked and has a single reference.
+   If an error occurs, NULL is returned.  */
+struct node *netfs_make_node (struct netnode *);
 
+/* When ever node->references is to be touched, this lock must be
+   held.  Cf. netfs_nrele, netfs_nput, netfs_ref and netfs_drop_node.  */
 extern spin_lock_t netfs_node_refcnt_lock;
 
-extern int netfs_maxsymlinks;
-
+/* Normally called in main.  This function sets up some of the netfs
+   server's internal state.  */
 void netfs_init (void);
+
+/* Starts the netfs server.  Called after netfs_init. BOOTSTRAP is
+   the bootstrap port.  FLAGS indicate how to open the underlying node
+   (Cf. hurd/fsys.defs).  */
+mach_port_t netfs_startup (mach_port_t bootstrap, int flags);
+
+/* Normally called as the last function in main.  The netfs server now
+   begins answering requests. This function never returns.  */
 void netfs_server_loop (void);
-struct protid *netfs_make_protid (struct peropen *, struct iouser *);
+
+/* Creates a new credential from USER which can be NULL on the peropen
+   PO.  Returns NULL and sets errno on error.  */
+struct protid *netfs_make_protid (struct peropen *po, struct iouser *user);
 
 /* Create and return a new peropen structure on node NP with open
-   flags FLAGS.  The initial values for the root_parent, shadow_root, and
-   shadow_root_parent fields are copied from CONTEXT if it's non-zero,
-   otherwise zerod.  */
+   flags FLAGS.  The initial values for the root_parent, shadow_root,
+   and shadow_root_parent fields are copied from CONTEXT if it's
+   non-zero, otherwise zerod.  */
 struct peropen *netfs_make_peropen (struct node *, int,
 				    struct peropen *context);
 
-void netfs_drop_node (struct node *);
+/* Add a reference to locked node NP.  */
+void netfs_nref (struct node *np);
+
+/* Releases a node.  Drops a reference to unlocked node NP.  If this
+   was the last reference, drops the node.  */
+void netfs_nrele (struct node *np);
+
+/* Puts a node back.  Drops a reference to the locked node NP (and
+   releases the lock, too).  If this was the last reference, drops the
+   node.  */
+void netfs_nput (struct node *np);
+
+/* Called internally when no more references to node NP exist. */
+void netfs_drop_node (struct node *np);
+
+/* Called internally when no more references to a protid exit. */
 void netfs_release_protid (void *);
+
+/* Called internally when no more references to a protid exit. */
 void netfs_release_peropen (struct peropen *);
+
+/* The netfs message demuxer. */
 int netfs_demuxer (mach_msg_header_t *, mach_msg_header_t *);
-error_t netfs_shutdown (int);
+
+/* Called to ask the filesystem to shutdown.  If it returns, an error
+   occured.  FLAGS are passed to fsys_goaway. */
+error_t netfs_shutdown (int flags);
 
 extern struct port_class *netfs_protid_class;
 extern struct port_class *netfs_control_class;
@@ -333,10 +389,6 @@ extern struct node *netfs_root_node;
 extern mach_port_t netfs_fsys_identity;
 extern auth_t netfs_auth_server_port;
 
-void netfs_nref (struct node *np);
-void netfs_nrele (struct node *np);
-void netfs_nput (struct node *np);
-
 
 /* Mig gook. */
 typedef struct protid *protid_t;
diff --git a/libnetfs/nput.c b/libnetfs/nput.c
index 1d19482a..c62b7b9f 100644
--- a/libnetfs/nput.c
+++ b/libnetfs/nput.c
@@ -1,5 +1,5 @@
 /* 
-   Copyright (C) 1999 Free Software Foundation, Inc.
+   Copyright (C) 1999, 2000 Free Software Foundation, Inc.
    Written by Thomas Bushnell, BSG.
 
    This file is part of the GNU Hurd.
@@ -28,6 +28,7 @@ netfs_nput (struct node *np)
   np->references--;
   if (np->references == 0)
     netfs_drop_node (np);
+    /* netfs_drop_node drops netfs_node_refcnt_lock for us.  */
   else
     {
       spin_unlock (&netfs_node_refcnt_lock);
diff --git a/libnetfs/nref.c b/libnetfs/nref.c
index f5a970da..4e26910f 100644
--- a/libnetfs/nref.c
+++ b/libnetfs/nref.c
@@ -1,5 +1,5 @@
 /* 
-   Copyright (C) 1999 Free Software Foundation, Inc.
+   Copyright (C) 1999, 2000 Free Software Foundation, Inc.
    Written by Thomas Bushnell, BSG.
 
    This file is part of the GNU Hurd.
diff --git a/libnetfs/nrele.c b/libnetfs/nrele.c
index 0104e01d..dca9599a 100644
--- a/libnetfs/nrele.c
+++ b/libnetfs/nrele.c
@@ -30,6 +30,7 @@ netfs_nrele (struct node *np)
     {
       mutex_lock (&np->lock);
       netfs_drop_node (np);
+      /* netfs_drop_node drops netfs_node_refcnt_lock for us.  */
     }
   else
     spin_unlock (&netfs_node_refcnt_lock);
diff --git a/libnetfs/set-get-trans.c b/libnetfs/set-get-trans.c
index 5d5d7729..b58668d8 100644
--- a/libnetfs/set-get-trans.c
+++ b/libnetfs/set-get-trans.c
@@ -22,6 +22,9 @@
 
 #include "netfs.h"
 
+/* Default implementations of the netfs_set_translator and
+   netfs_set_translator functions. */
+
 /* The user may define this function.  Attempt to set the passive
    translator record for FILE to ARGZ (of length ARGZLEN) for user
    CRED. */