1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
|
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Interactive mode — Universal Ctags 0.3.0 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/classic.css" />
<script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/doctools.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Other changes" href="news.html" />
<link rel="prev" title="Running multiple parsers on an input file" href="running-multi-parsers.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="news.html" title="Other changes"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="running-multi-parsers.html" title="Running multiple parsers on an input file"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li>
<li class="nav-item nav-item-this"><a href="">Interactive mode</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="interactive-mode">
<span id="id1"></span><h1>Interactive mode<a class="headerlink" href="#interactive-mode" title="Permalink to this headline">¶</a></h1>
<p>Universal Ctags can be run with <code class="docutils literal notranslate"><span class="pre">--_interactive</span></code>, which enters a REPL that
can be used programmatically to control ctags generation. In this mode, json
commands are received over stdin, and corresponding responses are emitted over
stdout.</p>
<p>This feature needs ctags to be built with json support and this requires libjansson to be installed
at build-time. If it’s supported it will be listed in the output of <code class="docutils literal notranslate"><span class="pre">--list-features</span></code>:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --list-features <span class="p">|</span> grep json
<span class="go">json</span>
</pre></div>
</div>
<p>Communication with Universal Ctags over stdio uses the <a class="reference external" href="http://jsonlines.org/">json lines</a> format, where each
json object appears on a single line and is terminated with a newline.</p>
<p>When <code class="docutils literal notranslate"><span class="pre">ctags</span> <span class="pre">--_interactive</span></code> is invoked, it will emit a single json object to stdout announcing
its name and version. This signals the start of the interactive loop, and the user can begin sending
commands over stdin.</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --_interactive
<span class="go">{"_type": "program", "name": "Universal Ctags", "version": "0.0.0"}</span>
</pre></div>
</div>
<p>The following commands are currently supported in interactive mode:</p>
<ul class="simple">
<li><p><a class="reference internal" href="#generate-tags">generate-tags</a></p></li>
</ul>
<section id="generate-tags">
<h2>generate-tags<a class="headerlink" href="#generate-tags" title="Permalink to this headline">¶</a></h2>
<p>The <code class="docutils literal notranslate"><span class="pre">generate-tags</span></code> command takes two arguments:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">filename</span></code>: name of the file to generate tags for (required)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">size</span></code>: size in bytes of the file, if the contents will be received over stdin (optional)</p></li>
</ul>
<p>The simplest way to generate tags for a file is by passing its path on filesystem(<code class="docutils literal notranslate"><span class="pre">file</span> <span class="pre">request</span></code>). The response will include
one json object per line representing each tag, followed by a single json object with the <code class="docutils literal notranslate"><span class="pre">completed</span></code>
field emitted once the file has been fully processed.</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span><span class="nb">echo</span> <span class="s1">'{"command":"generate-tags", "filename":"test.rb"}'</span> <span class="p">|</span> ctags --_interactive
<span class="go">{"_type": "program", "name": "Universal Ctags", "version": "0.0.0"}</span>
<span class="go">{"_type": "tag", "name": "foobar", "path": "test.rb", "pattern": "/^ def foobar$/", "kind": "method", "scope": "Test", "scopeKind": "class"}</span>
<span class="go">{"_type":"completed", "command": "generate-tags"}</span>
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">generate-tags</span></code> command can also be used to generate tags for code which is not present on filesystem(<code class="docutils literal notranslate"><span class="pre">inline</span> <span class="pre">request</span></code>). For example,
an IDE might want to generate ctags for an unsaved buffer while the user is editing code. When <code class="docutils literal notranslate"><span class="pre">size</span></code> is specified,
the corresponding number of bytes are read over stdin after the json object and newline.</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span><span class="o">(</span>
<span class="go"> echo '{"command":"generate-tags", "filename":"test.rb", "size": 17}'</span>
<span class="go"> echo 'def foobaz() end'</span>
<span class="go">) | ctags --_interactive</span>
<span class="go">{"_type": "program", "name": "Universal Ctags", "version": "0.0.0"}</span>
<span class="go">{"_type": "tag", "name": "foobaz", "path": "test.rb", "pattern": "/^def foobaz() end$/", "kind": "method"}</span>
<span class="go">{"_type": "completed", "command": "generate-tags"}</span>
</pre></div>
</div>
</section>
<section id="sandbox-submode">
<span id="id2"></span><h2>sandbox submode<a class="headerlink" href="#sandbox-submode" title="Permalink to this headline">¶</a></h2>
<p><code class="docutils literal notranslate"><span class="pre">sandbox</span></code> submode can be used with <code class="docutils literal notranslate"><span class="pre">--_interactive=sandbox</span></code>. This
submode will activate a sandbox, to this limits the damage that the
can be achieved when exploiting a buffer overflow in Universal Ctags.</p>
<p>In the sandbox submode ctags can generate tags only for inline
requests because ctags has to use open system call to handle file
requests. The open system call is not allowed in the sandbox.</p>
<p>This feature uses <a class="reference external" href="https://www.kernel.org/doc/html/latest/userspace-api/seccomp_filter.html">Seccomp BPF (SECure COMPuting with filters)</a>,
and is only supported on Linux. To use the sandbox submode <a class="reference external" href="https://github.com/seccomp/libseccomp">libseccomp</a> is needed at build-time. If ctags was
built with seccomp support, <code class="docutils literal notranslate"><span class="pre">sandbox</span></code> is listed in the output of
<code class="docutils literal notranslate"><span class="pre">--list-features</span></code> option.</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --list-features <span class="p">|</span> grep sandbox
<span class="go">sandbox</span>
</pre></div>
</div>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span><span class="o">(</span>
<span class="go"> echo '{"command":"generate-tags", "filename":"test.rb", "size": 17}'</span>
<span class="go"> echo 'def foobaz() end'</span>
<span class="go">) | ctags --_interactive=sandbox</span>
<span class="go">{"_type": "program", "name": "Universal Ctags", "version": "0.0.0"}</span>
<span class="go">{"_type": "tag", "name": "foobaz", "path": "test.rb", "pattern": "/^def foobaz() end$/", "kind": "method"}</span>
<span class="go">{"_type": "completed", "command": "generate-tags"}</span>
</pre></div>
</div>
</section>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Interactive mode</a><ul>
<li><a class="reference internal" href="#generate-tags">generate-tags</a></li>
<li><a class="reference internal" href="#sandbox-submode">sandbox submode</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="running-multi-parsers.html"
title="previous chapter">Running multiple parsers on an input file</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="news.html"
title="next chapter">Other changes</a></p>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="news.html" title="Other changes"
>next</a> |</li>
<li class="right" >
<a href="running-multi-parsers.html" title="Running multiple parsers on an input file"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li>
<li class="nav-item nav-item-this"><a href="">Interactive mode</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2015, Universal Ctags Team.
Last updated on 11 Jun 2021.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2.
</div>
</body>
</html>
|
