[DOC-FIX] libdiskfs: initialization functions

[Neal H Walfield]

> Please separate this into: typo fixes; substantial text additions; and
> miscellaneous rewordings.  I will apply the first with cursory review, the
> second with appropriate review for correctness, and the third I will
> probably ignore.

Here is the second part:

2001-05-07  Neal H Walfield  <neal@cs.uml.edu>

        * diskfs.h: Fix comments about initialization.

        * diskfs.h: Move diskfs_start_bootstrap prototype from here . . .
        * priv.h: . . . to here.

Index: diskfs.h
===================================================================
RCS file: /home/neal/shared/CVS/hurd/libdiskfs/diskfs.h,v
retrieving revision 1.1.1.2
diff -u -r1.1.1.2 diskfs.h
--- diskfs.h    2001/05/07 18:25:50     1.1.1.2
+++ diskfs.h    2001/05/07 19:01:00
@@ -30,6 +30,11 @@
 #define DISKFS_EXTERN_INLINE extern inline
 #endif
 
+/* The diskfs library provides functions to demultiplex the fs, io,
+   fsys, interrupt, and notify interfaces.  All the server routines
+   have the prefix `diskfs_S_'; `in' arguments of type file_t or io_t
+   appear as `struct protid *' to the stub.  */
+
 /* Each user port referring to a file points to one of these
    (with the aid of the ports library).  */
 struct protid
@@ -549,30 +554,50 @@
 error_t (*diskfs_read_symlink_hook)(struct node *np, char *target);
 
 /* The library exports the following functions for general use */
+
+/* Initialization.  */
 
 /* Call this after arguments have been parsed to initialize the library.
-   You must call this before calling any other diskfs functions, and after
-   parsing diskfs options.  */
+   This must be called before any other diskfs functions.  */
 error_t diskfs_init_diskfs (void);
 
-/* Call this once the filesystem is fully initialized, to advertise the new
-   filesystem control port to our parent filesystem.  If BOOTSTRAP is set,
-   the diskfs will call fsys_startup on that port as appropriate and return
-   the REALNODE returned in that call; otherwise we return MACH_PORT_NULL.
-   FLAGS specifies how to open REALNODE (from the O_* set).  */
-mach_port_t diskfs_startup_diskfs (mach_port_t bootstrap, int flags);
-
 /* Call this after all format-specific initialization is done (except
-   for setting diskfs_root_node); at this point the pagers should be
-   ready to go.  DEMUXER is the demuxer to user.  Normally, this is
-   just diskfs_demuxer.  */
+   possibly setting diskfs_root_node); at this point the pagers should be
+   ready to go.  DEMUXER is the demuxer to use.  Normally, this is
+  just diskfs_demuxer.  */
 void diskfs_spawn_first_thread (ports_demuxer_type demuxer);
+
+/* Call this once the filesystem is fully initialized (e.g. after having
+   called diskfs_init_diskfs, diskfs_spawn_first_thread and initializing
+   diskfs_root_node), to advertise the filesystem control port to the
+   parent filesystem.  If BOOTSTRAP is set, fsys_startup will be called
+   passing it the port and FLAGS, as from the O_* set, indicating how the
+   underlying node should be opened.  The port that it returns will, in
+   turn, be passed back to the callee.  Should BOOTSTRAP not be set, it 
+   is assumed that this is the bootstrap filesystem and special
+   initialization is performed.  In this case, as there is by definition
+   no underlying node, MACH_PORT_NULL is returned.  */
+mach_port_t diskfs_startup_diskfs (mach_port_t bootstrap, int flags);
 
-/* Once diskfs_root_node is set, call this if we are a bootstrap
-   filesystem.  If you call this, then the library will call
-   diskfs_init_completed once it has a valid proc and auth port. */
-void diskfs_start_bootstrap ();
+/* All-in-one initialization function for diskfs filesystems using
+   libstore (including diskfs_init_diskfs).  This parses the arguments,
+   ARGC and ARGV, using STARTUP_ARGP or, if that is NULL,
+   diskfs_store_startup_argp.  Either way, the ARGP_IN_ORDER flag is
+   passed to the argp subsystem.  It then opens the store using
+   store_parsed_open, sets diskfs_hard_readonly and diskfs_readonly if
+   appropriate, gets the bootstrap port and calls diskfs_init_diskfs and
+   diskfs_spawn_first_thread.  The parsed store is returned in
+   *STORE_PARSED, the bootstrap port in *BOOTSTRAP and the store itself
+   directly.  The caller should pass *BOOTSTRAP to diskfs_startup_diskfs
+   after setting diskfs_root_node.  Cf <argp.h> and <hurd/store.h>.
 
+   This call does not return failure; if it encounters a problem, it
+   prints a diagnostic on stderr (or the console) and aborts.  */
+struct store *diskfs_init_main (struct argp *startup_argp,
+                               int argc, char **argv,
+                               struct store_parsed **store_parsed,
+                               mach_port_t *bootstrap);
+
 /* Node NP now has no more references; clean all state.  The
    _diskfs_node_refcnt_lock must be held, and will be released
    upon return.  NP must be locked.  */
@@ -926,32 +951,6 @@
 /* Check if the filesystem is readonly before an operation that
    writes it.  Return 1 if readonly, zero otherwise. */
 int diskfs_check_readonly (void);
-
-/* The diskfs library provides functions to demultiplex the fs, io,
-   fsys, interrupt, and notify interfaces.  All the server routines
-   have the prefix `diskfs_S_'; `in' arguments of type file_t or io_t
-   appear as `struct protid *' to the stub.  */
-
-
-/* All-in-one initialization function for diskfs filesystems using
-   libstore.  This parses arguments using STARTUP_ARGP (defaulting to
-   diskfs_store_startup_argp if it's null; note that the ARGP_IN_ORDER
-   flag is always used); it calls diskfs_init_diskfs; it opens the
-   store with store_parsed_open, and sets diskfs_hard_readonly and
-   diskfs_readonly if the store is unwritable; it calls
-   diskfs_spawn_first_thread; finally, it returns the store and its
-   description in *STORE and *STORE_PARSED, and the bootstrap port in
-   *BOOTSTRAP.  The caller should pass *BOOTSTRAP to
-   diskfs_startup_diskfs after setting diskfs_root_node.
-   (See <argp.h> and <hurd/store.h>.)
-
-   This call cannot return failure; if it encounters a fatal problem,
-   it prints a diagnostic on stderr (or the console) and exits the
-   program.  */
-struct store *diskfs_init_main (struct argp *startup_argp,
-                               int argc, char **argv,
-                               struct store_parsed **store_parsed,
-                               mach_port_t *bootstrap);
 
 /* The following are optional convenience routines and global variable, which
    can be used by any user program that uses a mach device to hold the
Index: priv.h
===================================================================
RCS file: /home/neal/shared/CVS/hurd/libdiskfs/priv.h,v
retrieving revision 1.1.1.2
diff -u -r1.1.1.2 priv.h
--- priv.h      2001/05/07 18:25:51     1.1.1.2
+++ priv.h      2001/05/07 19:01:50
@@ -64,6 +64,9 @@
 /* Needed for MiG. */
 typedef struct protid *protid_t;
 
+/* Called by diskfs_startup_diskfs if we are a bootstrap filesystem.  */
+void diskfs_start_bootstrap ();
+
 /* Actually read or write a file.  The file size must already permit
    the requested access.  NP is the file to read/write.  DATA is a buffer
    to write from or fill on read.  OFFSET is the absolute address (-1

pgpYaF2lR0wpH.pgp
Description: PGP signature