1.. _interactive-mode: 2 3====================================================================== 4Interactive mode 5====================================================================== 6 7Universal Ctags can be run with ``--_interactive``, which enters a REPL that 8can be used programmatically to control ctags generation. In this mode, json 9commands are received over stdin, and corresponding responses are emitted over 10stdout. 11 12This feature needs ctags to be built with json support and this requires libjansson to be installed 13at build-time. If it's supported it will be listed in the output of ``--list-features``: 14 15.. code-block:: console 16 17 $ ctags --list-features | grep json 18 json 19 20Communication with Universal Ctags over stdio uses the `json lines`_ format, where each 21json object appears on a single line and is terminated with a newline. 22 23When ``ctags --_interactive`` is invoked, it will emit a single json object to stdout announcing 24its name and version. This signals the start of the interactive loop, and the user can begin sending 25commands over stdin. 26 27.. code-block:: console 28 29 $ ctags --_interactive 30 {"_type": "program", "name": "Universal Ctags", "version": "0.0.0"} 31 32The following commands are currently supported in interactive mode: 33 34- generate-tags_ 35 36generate-tags 37------------- 38 39The ``generate-tags`` command takes two arguments: 40 41- ``filename``: name of the file to generate tags for (required) 42- ``size``: size in bytes of the file, if the contents will be received over stdin (optional) 43 44The simplest way to generate tags for a file is by passing its path on filesystem(``file request``). The response will include 45one json object per line representing each tag, followed by a single json object with the ``completed`` 46field emitted once the file has been fully processed. 47 48.. code-block:: console 49 50 $ echo '{"command":"generate-tags", "filename":"test.rb"}' | ctags --_interactive 51 {"_type": "program", "name": "Universal Ctags", "version": "0.0.0"} 52 {"_type": "tag", "name": "foobar", "path": "test.rb", "pattern": "/^ def foobar$/", "kind": "method", "scope": "Test", "scopeKind": "class"} 53 {"_type":"completed", "command": "generate-tags"} 54 55The ``generate-tags`` command can also be used to generate tags for code which is not present on filesystem(``inline request``). For example, 56an IDE might want to generate ctags for an unsaved buffer while the user is editing code. When ``size`` is specified, 57the corresponding number of bytes are read over stdin after the json object and newline. 58 59.. code-block:: console 60 61 $ ( 62 echo '{"command":"generate-tags", "filename":"test.rb", "size": 17}' 63 echo 'def foobaz() end' 64 ) | ctags --_interactive 65 {"_type": "program", "name": "Universal Ctags", "version": "0.0.0"} 66 {"_type": "tag", "name": "foobaz", "path": "test.rb", "pattern": "/^def foobaz() end$/", "kind": "method"} 67 {"_type": "completed", "command": "generate-tags"} 68 69.. _json lines: http://jsonlines.org/ 70 71.. _sandbox-submode: 72 73sandbox submode 74-------------------------- 75 76``sandbox`` submode can be used with ``--_interactive=sandbox``. This 77submode will activate a sandbox, to this limits the damage that the 78can be achieved when exploiting a buffer overflow in Universal Ctags. 79 80In the sandbox submode ctags can generate tags only for inline 81requests because ctags has to use open system call to handle file 82requests. The open system call is not allowed in the sandbox. 83 84This feature uses `Seccomp BPF (SECure COMPuting with filters) 85<https://www.kernel.org/doc/html/latest/userspace-api/seccomp_filter.html>`_, 86and is only supported on Linux. To use the sandbox submode `libseccomp 87<https://github.com/seccomp/libseccomp>`_ is needed at build-time. If ctags was 88built with seccomp support, ``sandbox`` is listed in the output of 89``--list-features`` option. 90 91.. code-block:: console 92 93 $ ctags --list-features | grep sandbox 94 sandbox 95 96.. code-block:: console 97 98 $ ( 99 echo '{"command":"generate-tags", "filename":"test.rb", "size": 17}' 100 echo 'def foobaz() end' 101 ) | ctags --_interactive=sandbox 102 {"_type": "program", "name": "Universal Ctags", "version": "0.0.0"} 103 {"_type": "tag", "name": "foobaz", "path": "test.rb", "pattern": "/^def foobaz() end$/", "kind": "method"} 104 {"_type": "completed", "command": "generate-tags"} 105