[WIP] main: oneshot mode, reading source file contents from stdin

Tmain/oneshot.d/run.sh

@@ -0,0 +1,19 @@
+# Copyright: 2026 Masatake YAMATO
+# License: GPL-2
+
+CTAGS=$1
+
+gen()
+{
+	cat <<EOF
+int v;
+int f(void)
+{
+	return 0;
+}
+EOF
+}
+
+gen | ${CTAGS} --quiet --options=NONE --oneshot=sort-no.c --sort=no -o -
+gen | ${CTAGS} --quiet --options=NONE --oneshot=sort-yes.c --sort=yes -o -
+gen | ${CTAGS} --quiet --options=NONE --oneshot=x.c -x

Tmain/oneshot.d/stdout-expected.txt

@@ -0,0 +1,6 @@
+v	sort-no.c	/^int v;$/;"	v	typeref:typename:int
+f	sort-no.c	/^int f(void)$/;"	f	typeref:typename:int
+f	sort-yes.c	/^int f(void)$/;"	f	typeref:typename:int
+v	sort-yes.c	/^int v;$/;"	v	typeref:typename:int
+f                function      2 x.c              int f(void)
+v                variable      1 x.c              int v;

docs/man/ctags.1.rst

@@ -221,6 +221,48 @@ Input/Output File Options
 
 	This option is quite esoteric and is empty by default.
 
+``--oneshot=<filename>``
+	Makes ctags behave as a filter, reading source
+	file contents from standard input and printing their tags to
+	standard output. When this option is enabled, the options ``-L``,
+	``-f``, ``-o``, and ``--totals`` are ignored.
+
+	ctags assumes *<filename>* is the input file
+	name of the contents. It affects language selection.
+	*<filename>* appears as the input file name in the tags output.
+
+	This option is useful for extracting interesting names in command
+	output.
+
+	For example, you can extract C preprocessor macro names in the source
+	code specified by a URL:
+
+	.. code-block:: console
+
+	   $ curl -s -o - \
+				'https://raw.githubusercontent.com/torvalds/linux/refs/heads/master/fs/buffer.c' \
+			| ./ctags --oneshot=buf.c --kinds-C='{macro}'
+	   BH_ENTRY	buf.c	/^#define BH_ENTRY(/;"	d	file:
+	   ...
+
+	Make the output in JSON format:
+
+	.. code-block:: console
+
+	   $ curl -s -o - \
+				'https://raw.githubusercontent.com/torvalds/linux/refs/heads/master/fs/buffer.c' \
+			| ./ctags --oneshot=buf.c --kinds-C='{macro}' --output-format=json \
+			| jq .
+	   {
+	     "_type": "tag",
+	     "name": "BH_ENTRY",
+	     "path": "buf.c",
+	     "pattern": "/^#define BH_ENTRY(/",
+	     "file": true,
+	     "kind": "macro"
+	   }
+	   ...
+
 ``--links[=(yes|no)]``
 	Indicates whether symbolic links (if supported) should be followed.
 	When disabled, symbolic links are ignored. This option is on by default.

docs/news/HEAD.rst

@@ -27,6 +27,12 @@ Extend ``--map-<LANG>=`` and ``--langmap=`` options to choose a parser using reg
 
 	``--list-maps`` has also been extended to include regular-expression-based mappings.
 
+New option: ``--oneshot=<filename>``
+
+	Makes @CTAGS_NAME_EXECUTABLE@ behave as a filter, reading source
+	file contents from standard input and printing their tags to
+	standard output.
+
 Incompatible changes
 ---------------------------------------------------------------------
 Messages for broken symlinks are now emitted at NOTICE level instead of

main/entry.c

@@ -409,7 +409,7 @@ extern void openTagFile (void)
 	 */
 	if (TagsToStdout)
 	{
-		if (Option.interactive == INTERACTIVE_SANDBOX)
+		if (Option.interactive & INTERACTIVE_WITH_SANDBOX)
 		{
 			TagFile.mio = mio_new_memory (NULL, 0, eRealloc, eFreeNoNullCheck);
 			TagFile.name = NULL;
@@ -536,7 +536,6 @@ static int replacementTruncate (const char *const name, const long size)
 
 #endif
 
-#ifndef EXTERNAL_SORT
 static void internalSortTagFile (void)
 {
 	MIO *mio;
@@ -562,20 +561,25 @@ static void internalSortTagFile (void)
 	if (! TagsToStdout)
 		mio_unref (mio);
 }
-#endif
 
-static void sortTagFile (void)
+static void sortTagFile (bool forceUseInternalSort)
 {
 	if (TagFile.numTags.added > 0L)
 	{
 		if (Option.sorted != SO_UNSORTED)
 		{
 			verbose ("sorting tag file\n");
+
+			if (forceUseInternalSort)
+				internalSortTagFile ();
+			else
+			{
 #ifdef EXTERNAL_SORT
-			externalSortTags (TagsToStdout, TagFile.mio);
+				externalSortTags (TagsToStdout, TagFile.mio);
 #else
-			internalSortTagFile ();
+				internalSortTagFile ();
 #endif
+			}
 		}
 		else if (TagsToStdout)
 			catFile (TagFile.mio);
@@ -632,7 +636,7 @@ static void writeEtagsIncludes (MIO *const mio)
 	}
 }
 
-extern void closeTagFile (const bool resize)
+extern void closeTagFile (const bool resize, bool forceUseInternalSort)
 {
 	long desiredSize, size;
 
@@ -656,7 +660,7 @@ extern void closeTagFile (const bool resize)
 				TagFile.name? TagFile.name: "<mio>", size, desiredSize); )
 		resizeTagFile (desiredSize);
 	}
-	sortTagFile ();
+	sortTagFile (forceUseInternalSort);
 	if (TagsToStdout)
 	{
 		if (mio_unref (TagFile.mio) != 0)

main/entry_p.h

@@ -29,7 +29,7 @@ extern const roleDefinition* getTagRole(const tagEntryInfo *const tag, int roleI
 extern void freeTagFileResources (void);
 extern const char *tagFileName (void);
 extern void openTagFile (void);
-extern void closeTagFile (const bool resize);
+extern void closeTagFile (const bool resize, bool forceUseInternalSort);
 extern void  setupWriter (void *writerClientData);
 extern bool  teardownWriter (const char *inputFilename);
 

main/interactive_p.h

@@ -17,12 +17,30 @@
 struct interactiveModeArgs
 {
 	bool sandbox;
+	const char *fname;			/* --_interactive=oneshot:FNAME */
+	size_t limit;				/* Upper limit of input data
+								 * received via stdin.
+								 * Used in oneshot mode.
+								 * 0 means no limit. */
 };
 
+#ifdef HAVE_JANSSON
 void interactiveLoop (cookedArgs *args, void *user);
 bool jsonErrorPrinter (const errorSelection selection, const char *const format, va_list ap,
 					  void *data);
-int installSyscallFilter (void);
+#endif
+
+void interactiveOneshot (cookedArgs *args, void *user);
+void batchOneshot (cookedArgs *args, void *user);
+
+enum syscallSet {
+	syscall_coreset    = 1 << 0,
+	syscall_open       = 1 << 1,
+	syscall_close      = 1 << 2,
+	syscall_ctrlset    = 1 << 3,
+};
+
+int installSyscallFilter (unsigned int set);
 
 #endif  /* CTAGS_MAIN_INTERACTIVE_H */
 

main/main.c

@@ -67,8 +67,8 @@
 #include "writer_p.h"
 #include "xtag_p.h"
 
-#ifdef HAVE_JANSSON
 #include "interactive_p.h"
+#ifdef HAVE_JANSSON
 #include <jansson.h>
 #include <errno.h>
 #endif
@@ -376,7 +376,7 @@ static void batchMakeTags (cookedArgs *args, void *user CTAGS_ATTR_UNUSED)
 	timeStamp (1);
 
 	if ((! Option.filter) && (!Option.printLanguage))
-		closeTagFile (resize);
+		closeTagFile (resize, false);
 
 	timeStamp (2);
 
@@ -391,27 +391,24 @@ static void batchMakeTags (cookedArgs *args, void *user CTAGS_ATTR_UNUSED)
 #undef timeStamp
 }
 
+static void prepareSandbox (unsigned int set)
+{
+	if (installSyscallFilter (set)) {
+		error (FATAL, "install_syscall_filter failed");
+		/* The explicit exit call is needed because
+		   "error (FATAL,..." just prints a message in
+		   interactive mode. */
+		exit (1);
+	}
+}
+
 #ifdef HAVE_JANSSON
 void interactiveLoop (cookedArgs *args CTAGS_ATTR_UNUSED, void *user)
 {
 	struct interactiveModeArgs *iargs = user;
 
-	if (iargs->sandbox) {
-		/* As of jansson 2.6, the object hashing is seeded off
-		   of /dev/urandom, so trigger the hash seeding
-		   before installing the syscall filter.
-		*/
-		json_t * tmp = json_object ();
-		json_decref (tmp);
-
-		if (installSyscallFilter ()) {
-			error (FATAL, "install_syscall_filter failed");
-			/* The explicit exit call is needed because
-			   "error (FATAL,..." just prints a message in
-			   interactive mode. */
-			exit (1);
-		}
-	}
+	if (iargs->sandbox)
+		prepareSandbox (syscall_coreset);
 
 	char buffer[1024];
 	json_t *request;
@@ -457,7 +454,7 @@ void interactiveLoop (cookedArgs *args CTAGS_ATTR_UNUSED, void *user)
 				if (iargs->sandbox) {
 					error (FATAL,
 						   "invalid request in sandbox submode: reading file contents from a file is limited");
-					closeTagFile (false);
+					closeTagFile (false, false);
 					goto next;
 				}
 
@@ -472,7 +469,7 @@ void interactiveLoop (cookedArgs *args CTAGS_ATTR_UNUSED, void *user)
 				mio_unref (mio);
 			}
 
-			closeTagFile (false);
+			closeTagFile (false, false);
 			fputs ("{\"_type\": \"completed\", \"command\": \"generate-tags\"}\n", stdout);
 			fflush(stdout);
 		}
@@ -488,6 +485,68 @@ void interactiveLoop (cookedArgs *args CTAGS_ATTR_UNUSED, void *user)
 }
 #endif
 
+static void oneshotCommon (const char *fname, size_t limit, bool sandbox, int strictSyscallset)
+{
+	openTagFile ();
+
+	if (sandbox && strictSyscallset)
+		prepareSandbox (strictSyscallset);
+
+	MIO *mio = mio_new_memory (NULL, 0, eRealloc, eFreeNoNullCheck);
+	int c;
+	size_t r = 0;
+	while ((c = getchar()) != EOF)
+	{
+		r++;
+		if (limit != 0 && r > limit)
+		{
+			error (WARNING, "input read from stdin exceeds the limit: name: %s, size: %lu",
+				   fname,
+				   (unsigned long) limit);
+			break;
+		}
+		mio_putc (mio, c);
+	}
+
+	mio_seek (mio, 0, SEEK_SET);
+
+	parseFileWithMio (fname, mio, NULL);
+
+	mio_unref (mio);
+
+	closeTagFile (false, sandbox ? true : false);
+}
+
+extern void batchOneshot (cookedArgs *args CTAGS_ATTR_UNUSED, void *user)
+{
+	struct interactiveModeArgs *iargs = user;
+
+	Assert (iargs->fname);
+
+	unsigned int extra_set;
+
+	extra_set = isDestinationStdout () ? syscall_close | syscall_ctrlset
+		: syscall_open | syscall_close | syscall_ctrlset;
+	if (iargs->sandbox)
+		prepareSandbox (syscall_coreset | extra_set);
+
+	extra_set = isDestinationStdout () ? 0
+		: syscall_open | syscall_close;
+	oneshotCommon (iargs->fname, iargs->limit, iargs->sandbox, syscall_coreset | extra_set);
+}
+
+extern void interactiveOneshot (cookedArgs *args CTAGS_ATTR_UNUSED, void *user)
+{
+	struct interactiveModeArgs *iargs = user;
+
+	Assert (iargs->fname);
+
+	if (iargs->sandbox)
+		prepareSandbox (syscall_coreset);
+
+	oneshotCommon (iargs->fname, iargs->limit, iargs->sandbox, 0);
+}
+
 static bool isSafeVar (const char* var)
 {
 	const char *safe_vars[] = {