Change --jobserver-fds to more generic --jobserver-auth.

* NEWS: Mention the change.
* main.c: Rename jobserver_fds variable to jobserver_auth and
--jobserver-fds option to --jobserver-auth.
* os.h, posixos.c, w32/w32os.c: Rename jobserver_parse_arg() and
jobserver_get_arg() to jobserver_parse_auth()/jobserver_get_auth().

NEWS

@@ -24,6 +24,12 @@ http://sv.gnu.org/bugs/index.php?group=make&report_id=111&fix_release_id=106&set
   The function is expanded to the contents of the file.  The contents are
   expanded verbatim except that the final newline, if any, is stripped.
 
+* The interface to GNU make's "jobserver" is stable as documented in the
+  manual, for tools which may want to access it.
+
+  WARNING: Backward-incompatibility! The internal-only command line option
+  --jobserver-fds has been renamed for publishing, to --jobserver-auth.
+
 * VMS-specific changes:
 
   * Perl test harness now works.

main.c

@@ -269,9 +269,9 @@ static unsigned int master_job_slots = 0;
 
 static unsigned int inf_jobs = 0;
 
-/* File descriptors for the jobs pipe.  */
+/* Authorization for the jobserver.  */
 
-char *jobserver_fds = NULL;
+char *jobserver_auth = NULL;
 
 /* Handle for the mutex used on Windows to synchronize output of our
    children under -O.  */
@@ -471,7 +471,7 @@ static const struct command_switch switches[] =
 
     /* These are long-style options.  */
     { CHAR_MAX+1, strlist, &db_flags, 1, 1, 0, "basic", 0, "debug" },
-    { CHAR_MAX+2, string, &jobserver_fds, 1, 1, 0, 0, 0, "jobserver-fds" },
+    { CHAR_MAX+2, string, &jobserver_auth, 1, 1, 0, 0, 0, "jobserver-auth" },
     { CHAR_MAX+3, flag, &trace_flag, 1, 1, 0, 0, 0, "trace" },
     { CHAR_MAX+4, flag, &inhibit_print_directory_flag, 1, 1, 0, 0, 0,
       "no-print-directory" },
@@ -1597,22 +1597,22 @@ main (int argc, char **argv, char **envp)
   starting_directory = current_directory;
 
 #ifdef MAKE_JOBSERVER
-  /* If the jobserver_fds option is seen, make sure that -j is reasonable.
+  /* If the jobserver_auth option is seen, make sure that -j is reasonable.
      This can't be usefully set in the makefile, and we want to verify the
-     FDs are valid before any other aspect of make has a chance to start
-     using them for something else.  */
+     authorization is valid before any other aspect of make has a chance to
+     start using it for something else.  */
 
-  if (jobserver_fds)
+  if (jobserver_auth)
     {
-      /* The combination of jobserver_fds and !job_slots means we're using the
-         jobserver.  If !job_slots and no jobserver_fds, we can start infinite
-         jobs.  If we see both jobserver_fds and job_slots >0 that means the
-         user set -j explicitly.  This is broken; in this case obey the user
-         (ignore the jobserver for this make) but print a message.  If we've
-         restarted, we already printed this the first time.  */
+      /* The combination of jobserver_auth and !job_slots means we're using
+         the jobserver.  If !job_slots and no jobserver_auth, we can start
+         infinite jobs.  If we see both jobserver_auth and job_slots >0 that
+         means the user set -j explicitly.  This is broken; in this case obey
+         the user (ignore the jobserver for this make) but print a message.
+         If we've restarted, we already printed this the first time.  */
 
       if (!job_slots)
-        jobserver_parse_arg (jobserver_fds);
+        jobserver_parse_auth (jobserver_auth);
 
       else if (! restarts)
         O (error, NILF,
@@ -1622,8 +1622,8 @@ main (int argc, char **argv, char **envp)
         {
           /* If job_slots is set now then we're not using jobserver */
           jobserver_clear ();
-          free (jobserver_fds);
-          jobserver_fds = NULL;
+          free (jobserver_auth);
+          jobserver_auth = NULL;
         }
     }
 #endif
@@ -2049,8 +2049,8 @@ main (int argc, char **argv, char **envp)
       master_job_slots = job_slots;
       job_slots = 0;
 
-      /* Fill in the jobserver_fds for our children.  */
-      jobserver_fds = jobserver_get_arg ();
+      /* Fill in the jobserver_auth for our children.  */
+      jobserver_auth = jobserver_get_auth ();
     }
 #endif
 
@@ -3394,12 +3394,12 @@ clean_jobserver (int status)
 
       jobserver_clear ();
 
-      /* Clean out jobserver_fds so we don't pass this information to any
+      /* Clean out jobserver_auth so we don't pass this information to any
          sub-makes.  Also reset job_slots since it will be put on the command
          line, not in MAKEFLAGS.  */
       job_slots = default_job_slots;
-      free (jobserver_fds);
-      jobserver_fds = NULL;
+      free (jobserver_auth);
+      jobserver_auth = NULL;
     }
 }
 

os.h

@@ -26,10 +26,10 @@ unsigned int jobserver_enabled ();
 void jobserver_setup (int job_slots);
 
 /* Called in a child instance to connect to the jobserver.  */
-void jobserver_parse_arg (const char* arg);
+void jobserver_parse_auth (const char* auth);
 
 /* Returns an allocated buffer used to pass to child instances.  */
-char *jobserver_get_arg ();
+char *jobserver_get_auth ();
 
 /* Clear this instance's jobserver configuration.  */
 void jobserver_clear ();
@@ -61,18 +61,18 @@ int jobserver_acquire (int timeout);
 
 #else
 
-#define jobserver_enabled()       (0)
-#define jobserver_setup(_slots)   (void)(0)
-#define jobserver_parse_arg(_arg) (void)(0)
-#define jobserver_get_arg()       (NULL)
-#define jobserver_clear()         (void)(0)
-#define jobserver_release(_fatal) (void)(0)
-#define jobserver_acquire_all()   (0)
-#define jobserver_signal()        (void)(0)
-#define jobserver_pre_child(_r)   (void)(0)
-#define jobserver_post_child(_r)  (void)(0)
-#define jobserver_pre_acquire()   (void)(0)
-#define jobserver_acquire(_tmout) (0)
+#define jobserver_enabled()         (0)
+#define jobserver_setup(_slots)     (void)(0)
+#define jobserver_parse_auth(_auth) (void)(0)
+#define jobserver_get_auth()        (NULL)
+#define jobserver_clear()           (void)(0)
+#define jobserver_release(_fatal)   (void)(0)
+#define jobserver_acquire_all()     (0)
+#define jobserver_signal()          (void)(0)
+#define jobserver_pre_child(_r)     (void)(0)
+#define jobserver_post_child(_r)    (void)(0)
+#define jobserver_pre_acquire()     (void)(0)
+#define jobserver_acquire(_tmout)   (0)
 
 #endif
 

posixos.c

@@ -80,12 +80,12 @@ jobserver_setup (int slots)
 }
 
 void
-jobserver_parse_arg (const char* arg)
+jobserver_parse_auth (const char *auth)
 {
   /* Given the command-line parameter, parse it.  */
-  if (sscanf (arg, "%d,%d", &job_fds[0], &job_fds[1]) != 2)
+  if (sscanf (auth, "%d,%d", &job_fds[0], &job_fds[1]) != 2)
     OS (fatal, NILF,
-        _("internal error: invalid --jobserver-fds string '%s'"), arg);
+        _("internal error: invalid --jobserver-auth string '%s'"), auth);
 
   DB (DB_JOBS,
       (_("Jobserver client (fds %d,%d)\n"), job_fds[0], job_fds[1]));
@@ -115,11 +115,11 @@ jobserver_parse_arg (const char* arg)
 }
 
 char *
-jobserver_get_arg ()
+jobserver_get_auth ()
 {
-  char *fds = xmalloc ((INTSTR_LENGTH * 2) + 2);
-  sprintf (fds, "%d,%d", job_fds[0], job_fds[1]);
-  return fds;
+  char *auth = xmalloc ((INTSTR_LENGTH * 2) + 2);
+  sprintf (auth, "%d,%d", job_fds[0], job_fds[1]);
+  return auth;
 }
 
 unsigned int

tests/scripts/features/jobserver

@@ -12,7 +12,7 @@ if (!$parallel_jobs) {
   return -1;
 }
 
-# Don't put --jobserver-fds into a re-exec'd MAKEFLAGS.
+# Don't put --jobserver-auth into a re-exec'd MAKEFLAGS.
 # We can't test this directly because there's no way a makefile can
 # show the value of MAKEFLAGS we were re-exec'd with.  We can intuit it
 # by looking for "disabling jobserver mode" warnings; we should only
@@ -59,3 +59,7 @@ default: ; @ #MAKEPATH# -f Makefile2
 rmfiles('Makefile2');
 
 1;
+
+### Local Variables:
+### eval: (setq whitespace-action (delq 'auto-cleanup whitespace-action))
+### End:

w32/w32os.c

@@ -64,30 +64,28 @@ jobserver_setup (int slots)
 }
 
 void
-jobserver_parse_arg (const char* arg)
+jobserver_parse_auth (const char *auth)
 {
   jobserver_semaphore = OpenSemaphore (
   SEMAPHORE_ALL_ACCESS,   /* Semaphore access setting */
     FALSE,                  /* Child processes DON'T inherit */
-    arg);                   /* Semaphore name */
+    auth);                   /* Semaphore name */
 
   if (jobserver_semaphore == NULL)
     {
       DWORD err = GetLastError ();
       const char *estr = map_windows32_error_to_string (err);
-      fatal (NILF, strlen (arg) + INTSTR_LENGTH + strlen (estr),
+      fatal (NILF, strlen (auth) + INTSTR_LENGTH + strlen (estr),
              _("internal error: unable to open jobserver semaphore '%s': (Error %ld: %s)"),
-             arg, err, estr);
+             auth, err, estr);
     }
-  DB (DB_JOBS, (_("Jobserver client (semaphore %s)\n"), arg));
+  DB (DB_JOBS, (_("Jobserver client (semaphore %s)\n"), auth));
 }
 
 char *
-jobserver_get_arg ()
+jobserver_get_auth ()
 {
-  char *fds = xmalloc (MAX_PATH + 1);
-  strcpy (fds, jobserver_semaphore_name);
-  return fds;
+  return xstrdup (jobserver_semaphore_name);
 }
 
 unsigned int