AMIGA - NFO_#?
 ----------------------------------------------------------------------------

   NAME

      nfo_fsquery() - General purpose filesystem query routine.



   SYNOPSIS

      success = nfo_fsquery(userlen, exlen, file, edval, 
                                  termsig, userdata, usercode);

      BOOL nfo_fsquery(ULONG, ULONG, UBYTE *, LONG, 
                 ULONG, void *, BOOL (*)(struct nfo_fsq_cb *));



   FUNCTION

      This function allows to query objects on a filesystem. It
      uses 'ExAll()' to do that and this 'ExAllData' structure
      that is available to user in the callback.



   INPUTS

      userlen  - General purpose buffer length that can be used
                 in the callback per 'nfo_fsquery()'. Passing 0
                 will give user 4 bytes in the callback member.

      exlen    - 'ExAll()' buffer length, see source code for a
                 minimum value.

      file     - File or path to 'Lock()'.

      edval    - One of ED_xxx val. as taken from 'dos/exall.h'.

      termsig  - Optional termination signal to get out of the
                 loop at any time. Values from 'AllocSignal()'
                 must be '(1L << sig)'. 0 means no term. sig.

      userdata - External user data/structure.

      usercode - Callback function.



   RETURNS

      Returns TRUE if everything went fine or FALSE otherwise.



   BASES

      SysBase, DOSBase



   NOTES

      Although this function was written in such a way that it
      can call itself in the callback, it is generally not wise
      to do so without constant stack size monitoring! This
      function will eat at most 120 bytes of stack. In theory
      this should allow up to 25 inner calls with 4096 bytes of
      stack, practically it is 15 before stack drops to 1024
      bytes. This is still most efficient way of listing files
      if you know you wont cross(by recursing) 15 directories.

      Callback structure is described in the header file.

      If termination signal was used then it must be cleared
      ('Signal(0L, signal)') after the function returns or else
      it will trigger further!



   SEE ALSO

   EXAMPLE

      ...

      void fsq_abspath(BOOL path, UBYTE *buf, LONG buflen, 
                                        UBYTE *base, UBYTE *visit)
      {
        txt_psnprintf(buf, buflen, "%s%c%s%c", 
                                        base, txt_needslash(base), 
                       visit, ((path) ? txt_needslash(visit) : 0));
      }

      BOOL fsq_cb(struct nfo_fsq_cb *fc)
      {
        if (fc->fc_ead->ed_Type == ST_FILE)
        {
          fsq_abspath(FALSE, fc->fc_userptr, fc->fc_userlen,
                                 fc->fc_file, fc->fc_ead->ed_Name);

          FPrintf(Output(), "   file: %s\n", (LONG)fc->fc_userptr);
        }
        else
        {
          fsq_abspath(TRUE, fc->fc_userptr, fc->fc_userlen,
                                 fc->fc_file, fc->fc_ead->ed_Name);

          FPrintf(Output(), " dir: %s\n", (LONG)fc->fc_userptr);

          if (nfo_stackreport(NULL) > 1024)
          {
            if ((nfo_fsquery(fc->fc_userlen, fc->fc_exlen, 
                      fc->fc_userptr, fc->fc_edval, fc->fc_termsig, 
                       fc->fc_userdata, fc->fc_usercode)) == FALSE)
            {
              /*
               * This is to get rid of irrelevant error messages.
              */
              if ((SetSignal(0L, 0L) & fc->fc_termsig) != 
                                                    fc->fc_termsig)
              {
                FPrintf(Output(), "error: cant access '%s'!\n", 
                                             (LONG)fc->fc_userptr);

                Signal(FindTask(NULL), fc->fc_termsig);
              }

              return FALSE;
            }
          }
          else
          {
            FPrintf(Output(), "   warning: stack overflow"
                                                    " avoided!\n");
          }
        }

        return TRUE;
      }

      int main(int argc, char **argv)
      {
        if (argc >= 2)
        {
          nfo_fsquery(1024, 1024, argv[1], ED_TYPE, SIGBREAKF_CTRL_C, 
                                                      NULL, fsq_cb);

          SetSignal(0L, SIGBREAKF_CTRL_C);
        }

        return 0;
      }



   BUGS

      None known.



 ----------------------------------------------------------------------------