docs: track nwbind endpoint handoffs

src/nwbind.c

@@ -802,6 +802,16 @@ static void handle_fxx(int gelen, int func)
       default :   completition=0xfb; /* not handled  */
     }
   } else if (0x17 == func) { /* Fileserver Enviro */
+    /*
+     * NCP 0x2222/23 File Server Environment forwarded from nwconn.c.
+     * handle_fxx() consumes the standard grouped header before this switch:
+     *   requestdata[0..1]  SubFuncStrucLen
+     *   requestdata[2]     SubFunctionCode
+     *   rdata              payload after SubFunctionCode
+     * Several queue subfunctions are preprocessed by nwconn before they reach
+     * this handler, so endpoint audits must include both the nwconn mutation
+     * and the final nwbind parser below.
+     */
     switch (ufunc) {
      case 0x01 :  { /* Change User Password OLD */
                      completition=0xff;
@@ -2067,14 +2077,23 @@ static void handle_fxx(int gelen, int func)
                   break;
     }  /* switch */
   } else if (func == 0x18) {  /* End of Job */
+    /* Forwarded direct NCP 0x2222/24 cleanup after nwconn releases local handles. */
     if (!(entry8_flags&0x200)) /* pcz: 14-Apr-00 */
       nw_close_connection_jobs(act_connection, ncprequest->task); /* close print jobs */
   } else if (func == 0x19) {  /* logout */
+    /* Forwarded direct NCP 0x2222/25 logout cleanup after nwconn resets connection state. */
     nw_close_connection_jobs(act_connection, -1);  /* close all print jobs */
     write_utmp(0, act_connection, act_c->pid_nwconn, &(act_c->client_adr), NULL);
     act_c->object_id  = 0; /* not LOGIN  */
     act_c->id_flags   = 0; /* no flags   */
   } else if (0x20 == func) { /* Semaphore */
+    /*
+     * NCP 0x2222/32 Semaphore forwarded from nwconn.c.
+     * This group is parsed differently from 0x15/0x16/0x17:
+     *   ufunc = requestdata[0]
+     *   rdata = requestdata + 1
+     * handle_func_0x20() owns the concrete semaphore subfunction layouts.
+     */
     int result = handle_func_0x20(act_c, rdata, ufunc, responsedata);
     if (result > -1) data_len = result;
     else completition=(uint8)-result;

src/nwconn.c

@@ -5182,8 +5182,11 @@ static int handle_ncp_serv(void)
          * This block only documents the file-information subfunctions
          * handled locally here.  Several login, bindery, queue, and
          * management subfunctions in this group are intentionally forwarded
-         * to nwbind or to existing queue prehandlers and should be audited
-         * in the target file when their turn comes.
+         * to nwbind or to existing queue prehandlers.  When auditing one of
+         * those calls, follow the return(-1)/return(-2) path into
+         * src/nwbind.c and document the concrete request/reply layout at the
+         * real handler too; some queue paths are also rewritten here before
+         * forwarding.
          */
         /* uint8 len   = *(requestdata+1); */
         uint8 ufunc    = *(requestdata+2);
@@ -5531,6 +5534,13 @@ static int handle_ncp_serv(void)
       break;
 
       case 0x18 : /* End of Job */
+                  /*
+                   * Direct NCP 0x2222/24 End of Job has no nested payload.
+                   * nwconn releases local file/task handles first, then
+                   * forwards to nwbind so the bindery/queue side can close
+                   * print jobs for this task.  Document further behavior in
+                   * nwbind.c if this endpoint is audited later.
+                   */
                   if (!(entry8_flags&0x200)) /* pcz: 14-Apr-00 */
                     free_connection_task_jobs(ncprequest->task);
                   nw_free_handles(ncprequest->task);
@@ -5538,6 +5548,12 @@ static int handle_ncp_serv(void)
                   break;
 
       case 0x19 : /* logout, some of this call is handled in ncpserv. */
+                  /*
+                   * Direct NCP 0x2222/25 Logout has no nested payload.  The
+                   * connection state is cleared here and nwbind performs the
+                   * remaining bindery/queue logout cleanup, so endpoint docs
+                   * must cover both sides when this call is audited.
+                   */
                   free_queue_jobs();
                   nw_free_handles(-1);
                   set_nw_user(-1, -1,
@@ -5683,6 +5699,14 @@ static int handle_ncp_serv(void)
                   break;
 
       case 0x20 : /* Semaphore */
+                  /*
+                   * Direct NCP 0x2222/32 is the Semaphore group.  Unlike the
+                   * 0x15/0x16/0x17 grouped calls, nwbind consumes a one-byte
+                   * semaphore subfunction directly from requestdata[0] and
+                   * passes requestdata[1..] as that subfunction's payload.
+                   * Follow src/nwbind.c handle_fxx(func == 0x20) and
+                   * handle_func_0x20() for concrete endpoint layout docs.
+                   */
                   return(-1);   /* handled by nwbind */
       
       case 0x21 : { /* Negotiate Buffer Size,  Packetsize  */