~ubuntu-branches/ubuntu/utopic/exuberant-ctags/utopic

Viewing changes to ctags.html

Committer: Bazaar Package Importer
Author(s): Colin Watson
Date: 2009-07-14 15:05:23 UTC
mfrom: (1.1.3 upstream)
Revision ID: james.westby@ubuntu.com-20090714150523-rytn1psh622nb709

Tags: 1:5.8-1

http://bugs.debian.org/529215

* New upstream release. Debian bugs fixed:
- Add support for ASP classes (closes: #529215).
* Compress files using gzip -n (cf. debhelper 6.0.6).
* Add a watch file.

files added:
ant.c

configure.ac

debian/watch

dosbatch.c

flex.c

gnu_regex

gnu_regex/README.txt

gnu_regex/regcomp.c

gnu_regex/regex.c

gnu_regex/regex.h

gnu_regex/regex_internal.c

gnu_regex/regex_internal.h

gnu_regex/regexec.c

matlab.c

mk_mingw.mak

ocaml.c

tex.c

vhdl.c

files removed:
acconfig.h

configure.in

mk_ming.mak

files modified:
INSTALL.oth

MAINTAINERS

Makefile.in

NEWS

README

asp.c

config.h.in

configure

ctags.1

ctags.h

ctags.html

debian/changelog

debian/rules

eiffel.c

fortran.c

jscript.c

keyword.c

keyword.h

lisp.c

maintainer.mak

make.c

mk_bc5.mak

mk_mvc.mak

parsers.h

php.c

python.c

read.c

read.h

source.mak

sql.c

vstring.h

Show diffs side-by-side

added added

removed removed

ctags.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"

"http://www.w3.org/TR/html4/loose.dtd">

<html>

p { margin-top: 0; margin-bottom: 0; }

pre { margin-top: 0; margin-bottom: 0; }

table { margin-top: 0; margin-bottom: 0; }

</style>

<title>CTAGS</title>

</head>

<body>

<h1 align=center>CTAGS</h1>

<a href="#SYNOPSIS">SYNOPSIS</a>

<a href="#DESCRIPTION">DESCRIPTION</a>

<a href="#CREDITS">CREDITS</a>

<hr>

<table width="100%" border=0 rules="none" frame="void"

cols="2" cellspacing="0" cellpadding="0">

ctags − Generate tag files for source code

</td>

</table>

ctags −

Generate tag files for source code

<h2>SYNOPSIS</h2>

<table width="100%" border=0 rules="none" frame="void"

cols="2" cellspacing="0" cellpadding="0">

ctags [options] [file(s)]</td>

</table>

<table width="100%" border=0 rules="none" frame="void"

cols="2" cellspacing="0" cellpadding="0">

etags [options] [file(s)]</td>

</table>

ctags

[options] [file(s)]

etags [options] [file(s)]

<h2>DESCRIPTION</h2>

<table width="100%" border=0 rules="none" frame="void"

cols="2" cellspacing="0" cellpadding="0">

The ctags and etags programs (hereinafter

The

ctags and etags programs (hereinafter

collectively referred to as ctags, except where

distinguished) generate an index (or "tag") file

for a variety of language objects found in file(s).

signifies a language object for which an index entry is

available (or, alternatively, the index entry created for

that object).

Alternatively, ctags can generate a cross

reference file which lists, in human readable form,

information about the various source objects found in a set

of language files.

Tag index files are supported by numerous editors, which

allow the user to locate the object associated with a name

appearing in a source file and jump to the file and line

which defines the name. Those known about at the time of

this release are:

</td>

</table>

<table width="100%" border=0 rules="none" frame="void"

cols="2" cellspacing="0" cellpadding="0">

100

Vi(1) and its derivatives (e.g. Elvis, Vim, Vile,

101

Lemmy), CRiSP, Emacs, FTE (Folding Text

Alternatively,

ctags can generate a cross reference file which

lists, in human readable form, information about the various

source objects found in a set of language files.

Tag index files

are supported by numerous editors, which allow the user to

locate the object associated with a name appearing in a

source file and jump to the file and line which defines the

name. Those known about at the time of this release are:

Vi(1)

and its derivatives (e.g. Elvis, Vim, Vile, Lemmy),

CRiSP, Emacs, FTE (Folding Text

102

Editor), JED, jEdit, Mined,

103

NEdit (Nirvana Edit), TSE (The SemWare

104

Editor), UltraEdit, WorkSpace, X2,

105

Zeus</td>

106

</table>

107

108

<table width="100%" border=0 rules="none" frame="void"

109

cols="2" cellspacing="0" cellpadding="0">

110

111

112

113

Ctags is capable of generating different kinds of

114

tags for each of many different languages. For a complete

115

list of supported languages, the names by which they are

116

recognized, and the kinds of tags which are generated for

117

each, see the −−list−languages and

Zeus

Ctags is

capable of generating different kinds of tags for each of

many different languages. For a complete list of supported

languages, the names by which they are recognized, and the

kinds of tags which are generated for each, see the

−−list−languages and

118

−−list−kinds options.

119

</td>

120

</table>

100

121

101

122

102

<h2>SOURCE FILES</h2>

123

124

<table width="100%" border=0 rules="none" frame="void"

125

cols="2" cellspacing="0" cellpadding="0">

126

127

128

129

Unless the −−language−force

130

option is specified, the language of each source file is

131

automatically selected based upon a mapping of file names to

132

languages. The mappings in effect for each language may be

133

display using the −−list−maps

134

option and may be changed using the

135

−−langmap option. On platforms which

136

support it, if the name of a file is not mapped to a

137

language and the file is executable, the first line of the

138

file is checked to see if the file is a "#!"

139

script for a recognized language.

140

141

By default, all other files names are ignored. This

142

permits running ctags on all files in either a single

143

directory (e.g. "ctags *"), or on all files in an

144

entire source directory tree (e.g. "ctags

145

−R"), since only those files whose names are

146

mapped to languages will be scanned.

147

148

[The reason that .h extensions are mapped to C++ files

149

rather than C files is because it is common to use .h

150

extensions in C++, and no harm results in treating them as

151

C++ files.]

152

</td>

153

</table>

103

104

105

Unless the

106

−−language−force option is

107

specified, the language of each source file is automatically

108

selected based upon a mapping of file names to languages.

109

The mappings in effect for each language may be display

110

using the −−list−maps option and

111

may be changed using the −−langmap

112

option. On platforms which support it, if the name of a file

113

is not mapped to a language and the file is executable, the

114

first line of the file is checked to see if the file is a

115

"#!" script for a recognized language.

116

117

By default, all

118

other files names are ignored. This permits running

119

ctags on all files in either a single directory (e.g.

120

"ctags *"), or on all files in an entire source

121

directory tree (e.g. "ctags −R"), since only

122

those files whose names are mapped to languages will be

123

scanned.

124

125

[The reason

126

that .h extensions are mapped to C++ files rather than C

127

files is because it is common to use .h extensions in C++,

128

and no harm results in treating them as C++ files.]

129

154

130

155

131

<h2>OPTIONS</h2>

156

157

<table width="100%" border=0 rules="none" frame="void"

158

cols="2" cellspacing="0" cellpadding="0">

159

160

161

162

Despite the wealth of available options, defaults are set

163

so that ctags is most commonly executed without any

164

options (e.g. "ctags *", or "ctags

165

−R"), which will create a tag file in the current

166

directory for all recognized source files. The options

167

described below are provided merely to allow custom

168

tailoring to meet special needs.

169

170

Note that spaces separating the single-letter options

171

from their parameters are optional.

172

173

Note also that the boolean parameters to the long form

174

options (those beginning with "−−" and

175

that take a "[=yes|no]" parameter)

176

may be omitted, in which case "=yes"

177

is implied. (e.g. −−sort is equivalent to

132

133

134

Despite the

135

wealth of available options, defaults are set so that

136

ctags is most commonly executed without any options

137

(e.g. "ctags *", or "ctags −R"),

138

which will create a tag file in the current directory for

139

all recognized source files. The options described below are

140

provided merely to allow custom tailoring to meet special

141

needs.

142

143

Note that

144

spaces separating the single-letter options from their

145

parameters are optional.

146

147

Note also that

148

the boolean parameters to the long form options (those

149

beginning with "−−" and that take a

150

"[=yes|no]" parameter) may be

151

omitted, in which case "=yes" is

152

implied. (e.g. −−sort is equivalent to

178

153

−−sort=yes). Note further that

179

154

"=1" and "=on" are

180

155

considered synonyms for "=yes", and that

181

156

"=0" and "=off" are

182

157

considered synonyms for "=no".

183

184

Some options are either ignored or useful only when used

185

while running in etags mode (see −e option).

186

Such options will be noted.

187

188

Most options may appear anywhere on the command line,

189

affecting only those files which follow the option. A few

190

options, however, must appear before the first file name and

191

will be noted as such.

192

193

Options taking language names will accept those names in

194

either upper or lower case. See the

158

159

Some options

160

are either ignored or useful only when used while running in

161

etags mode (see −e option). Such options will

162

be noted.

163

164

Most options

165

may appear anywhere on the command line, affecting only

166

those files which follow the option. A few options, however,

167

must appear before the first file name and will be noted as

168

such.

169

170

Options taking

171

language names will accept those names in either upper or

172

lower case. See the

195

173

−−list−languages option for a

196

174

complete list of the built-in language names.

197

</td>

198

</table>

199

175

200

176

<table width="100%" border=0 rules="none" frame="void"

201

cols="4" cellspacing="0" cellpadding="0">

202

203

204

205

206

−a

207

</td>

208

209

210

211

Equivalent to −−append.

212

</td>

213

214

215

216

217

−B

218

</td>

219

220

177

cellspacing="0" cellpadding="0">

178

179

180

181

182

183

184

−a </td>

185

186

187

188

189

Equivalent to

190

−−append. </td>

191

192

193

194

195

196

−B</td>

197

198

199

221

200

222

201

Use backward searching patterns (e.g. ?pattern?).

223

[Ignored in etags mode]

224

</td>

202

[Ignored in etags mode]</td>

225

203

226

204

227

205

228

206

229

−e

230

</td>

207

208

−e</td>

231

209

232

210

233

211

212

234

213

Enable etags mode, which will create a tag file for use

235

214

with the Emacs editor. Alternatively, if ctags is

236

215

invoked by a name containing the string "etags"

237

216

(either by renaming, or creating a link to, the executable),

238

217

etags mode will be enabled. This option must appear before

239

the first file name.

240

</td>

241

</table>

242

243

<table width="100%" border=0 rules="none" frame="void"

244

cols="2" cellspacing="0" cellpadding="0">

245

246

247

248

−f tagfile</td>

249

</table>

250

251

<table width="100%" border=0 rules="none" frame="void"

252

cols="2" cellspacing="0" cellpadding="0">

253

254

255

256

Use the name specified by tagfile for the tag file

257

(default is "tags", or "TAGS" when

258

running in etags mode). If tagfile is specified as

218

the first file name.</td>

219

</table>

220

221

−f

222

tagfile

223

224

Use the name specified by

225

tagfile for the tag file (default is

226

"tags", or "TAGS" when running in etags

227

mode). If tagfile is specified as

259

228

"−", then the tag file is written to

260

229

standard output instead. Ctags will stubbornly refuse

261

230

to take orders if tagfile exists and its first line

272

241

"./−ugly". This option must appear before

273

242

the first file name. If this option is specified more than

274

243

once, only the last will apply.

275

</td>

276

</table>

277

244

278

245

<table width="100%" border=0 rules="none" frame="void"

279

cols="4" cellspacing="0" cellpadding="0">

246

cellspacing="0" cellpadding="0">

280

247

281

248

282

249

283

250

284

−F

285

</td>

251

252

253

−F </td>

286

254

287

255

288

256

289

Use forward searching patterns (e.g. /pattern/)

290

(default). [Ignored in etags mode]

291

</td>

292

</table>

293

294

<table width="100%" border=0 rules="none" frame="void"

295

cols="2" cellspacing="0" cellpadding="0">

296

297

298

299

−h list</td>

300

</table>

301

302

<table width="100%" border=0 rules="none" frame="void"

303

cols="2" cellspacing="0" cellpadding="0">

304

305

306

307

Specifies a list of file extensions, separated by

308

periods, which are to be interpreted as include (or header)

309

files. To indicate files having no extension, use a period

310

not followed by a non-period character (e.g. ".",

311

"..x", ".x."). This option only affects

312

how the scoping of a particular kinds of tags is interpreted

313

(i.e. whether or not they are considered as globally visible

314

or visible only within the file in which they are defined);

315

it does not map the extension to any particular language.

316

Any tag which is located in a non-include file and cannot be

317

seen (e.g. linked to) from another file is considered to

318

have file-limited (e.g. static) scope. No kind of tag

319

appearing in an include file will be considered to have

320

file-limited scope. If the first character in the list is a

321

plus sign, then the extensions in the list will be appended

322

to the current list; otherwise, the list will replace the

323

current list. See, also, the

324

−−file−scope option. The default

325

list is ".h.H.hh.hpp.hxx.h++.inc.def". To restore

326

the default list, specify −h default.

327

Note that if an extension supplied to this option is not

328

already mapped to a particular language (see SOURCE

329

FILES, above), you will also need to use either the

257

258

Use forward

259

searching patterns (e.g. /pattern/) (default). [Ignored in

260

etags mode]</td>

261

</table>

262

263

−h list

264

265

Specifies a list of file

266

extensions, separated by periods, which are to be

267

interpreted as include (or header) files. To indicate files

268

having no extension, use a period not followed by a

269

non-period character (e.g. ".", "..x",

270

".x."). This option only affects how the scoping

271

of a particular kinds of tags is interpreted (i.e. whether

272

or not they are considered as globally visible or visible

273

only within the file in which they are defined); it does not

274

map the extension to any particular language. Any tag which

275

is located in a non-include file and cannot be seen (e.g.

276

linked to) from another file is considered to have

277

file-limited (e.g. static) scope. No kind of tag appearing

278

in an include file will be considered to have file-limited

279

scope. If the first character in the list is a plus sign,

280

then the extensions in the list will be appended to the

281

current list; otherwise, the list will replace the current

282

list. See, also, the −−file−scope

283

option. The default list is

284

".h.H.hh.hpp.hxx.h++.inc.def". To restore the

285

default list, specify −h default. Note

286

that if an extension supplied to this option is not already

287

mapped to a particular language (see SOURCE FILES,

288

above), you will also need to use either the

330

289

−−langmap or

331

290

−−language−force option.

332

</td>

333

</table>

334

335

<table width="100%" border=0 rules="none" frame="void"

336

cols="2" cellspacing="0" cellpadding="0">

337

338

339

340

−I identifier−list</td>

341

</table>

342

343

<table width="100%" border=0 rules="none" frame="void"

344

cols="2" cellspacing="0" cellpadding="0">

345

346

347

348

Specifies a list of identifiers which are to be specially

349

handled while parsing C and C++ source files. This option is

350

specifically provided to handle special cases arising

351

through the use of preprocessor macros. When the identifiers

352

listed are simple identifiers, these identifiers will be

353

ignored during parsing of the source files. If an identifier

354

is suffixed with a ’+’ character, ctags

355

will also ignore any parenthesis-enclosed argument list

356

which may immediately follow the identifier in the source

357

files. If two identifiers are separated with the

358

’=’ character, the first identifiers is replaced

359

by the second identifiers for parsing purposes. The list of

360

identifiers may be supplied directly on the command line or

361

read in from a separate file. If the first character of

291

292

−I

293

identifier−list

294

295

Specifies a list of identifiers

296

which are to be specially handled while parsing C and C++

297

source files. This option is specifically provided to handle

298

special cases arising through the use of preprocessor

299

macros. When the identifiers listed are simple identifiers,

300

these identifiers will be ignored during parsing of the

301

source files. If an identifier is suffixed with a

302

’+’ character, ctags will also ignore any

303

parenthesis-enclosed argument list which may immediately

304

follow the identifier in the source files. If two

305

identifiers are separated with the ’=’

306

character, the first identifiers is replaced by the second

307

identifiers for parsing purposes. The list of identifiers

308

may be supplied directly on the command line or read in from

309

a separate file. If the first character of

362

310

identifier−list is ’@’,

363

311

’.’ or a pathname separator (’/’ or

364

312

’\’), or the first two characters specify a

373

321

−I options may be supplied. To clear the list

374

322

of ignore identifiers, supply a single dash

375

323

("−") for identifier−list.

376

377

This feature is useful when preprocessor macros are used

378

in such a way that they cause syntactic confusion due to

379

their presence. Indeed, this is the best way of working

380

around a number of problems caused by the presence of

381

syntax-busting macros in source files (see CAVEATS,

382

below). Some examples will illustrate this point.

383

</td>

384

</table>

385

386

<table width="100%" border=0 rules="none" frame="void"

387

cols="2" cellspacing="0" cellpadding="0">

388

389

390

391

int foo ARGDECL4(void *, ptr, long int, nbytes)</td>

392

</table>

393

394

<table width="100%" border=0 rules="none" frame="void"

395

cols="2" cellspacing="0" cellpadding="0">

396

397

398

399

In the above example, the macro "ARGDECL4"

400

would be mistakenly interpreted to be the name of the

401

function instead of the correct name of "foo".

402

Specifying −I ARGDECL4 results in the

403

correct behavior.

404

</td>

405

</table>

406

407

<table width="100%" border=0 rules="none" frame="void"

408

cols="2" cellspacing="0" cellpadding="0">

409

410

411

412

/* creates an RCS version string in module */</td>

413

</table>

414

415

<table width="100%" border=0 rules="none" frame="void"

416

cols="2" cellspacing="0" cellpadding="0">

417

418

419

420

MODULE_VERSION("$Revision: 590 $")</td>

421

</table>

422

423

<table width="100%" border=0 rules="none" frame="void"

424

cols="2" cellspacing="0" cellpadding="0">

425

426

427

428

In the above example the macro invocation looks too much

429

like a function definition because it is not followed by a

430

semicolon (indeed, it could even be followed by a global

431

variable definition that would look much like a K&R

432

style function parameter declaration). In fact, this seeming

324

325

This feature is

326

useful when preprocessor macros are used in such a way that

327

they cause syntactic confusion due to their presence.

328

Indeed, this is the best way of working around a number of

329

problems caused by the presence of syntax-busting macros in

330

source files (see CAVEATS, below). Some examples will

331

illustrate this point.

332

333

int foo

334

ARGDECL4(void *, ptr, long int, nbytes)

335

336

In the above

337

example, the macro "ARGDECL4" would be mistakenly

338

interpreted to be the name of the function instead of the

339

correct name of "foo". Specifying −I

340

ARGDECL4 results in the correct behavior.

341

342

/* creates an

343

RCS version string in module */

344

MODULE_VERSION("$Revision: 690 $")

345

346

In the above

347

example the macro invocation looks too much like a function

348

definition because it is not followed by a semicolon

349

(indeed, it could even be followed by a global variable

350

definition that would look much like a K&R style

351

function parameter declaration). In fact, this seeming

433

352

function definition could possibly even cause the rest of

434

353

the file to be skipped over while trying to complete the

435

354

definition. Specifying −I

436

355

MODULE_VERSION+ would avoid such a problem.

437

</td>

438

</table>

439

440

<table width="100%" border=0 rules="none" frame="void"

441

cols="2" cellspacing="0" cellpadding="0">

442

443

444

445

CLASS Example {

446

// your content here

447

};</td>

448

</table>

449

450

<table width="100%" border=0 rules="none" frame="void"

451

cols="2" cellspacing="0" cellpadding="0">

452

453

454

455

The example above uses "CLASS" as a

456

preprocessor macro which expands to something different for

457

each platform. For instance CLASS may be defined as

458

"class __declspec(dllexport)" on Win32 platforms

459

and simply "class" on UNIX. Normally, the absence

460

of the C++ keyword "class" would cause the source

461

file to be incorrectly parsed. Correct behavior can be

462

restored by specifying −I

463

CLASS=class.

464

</td>

465

</table>

466

467

<table width="100%" border=0 rules="none" frame="void"

468

cols="2" cellspacing="0" cellpadding="0">

469

470

471

472

−L file</td>

473

</table>

474

475

<table width="100%" border=0 rules="none" frame="void"

476

cols="2" cellspacing="0" cellpadding="0">

477

478

479

480

Read from file a list of file names for which tags

481

should be generated. If file is specified as

482

"−", then file names are read from standard

483

input. File names read using this option are processed

484

following file names appearing on the command line. Options

485

are also accepted in this input. If this option is specified

486

more than once, only the last will apply. Note:

487

file is read in line-oriented mode, where a new line

488

is the only delimiter and non-trailing white space is

489

considered significant, in order that file names containing

490

spaces may be supplied (however, trailing white space is

491

stripped from lines); this can affect how options are parsed

492

if included in the input.

493

</td>

494

</table>

495

496

<table width="100%" border=0 rules="none" frame="void"

497

cols="5" cellspacing="0" cellpadding="0">

498

499

500

501

502

−n

503

</td>

504

505

506

507

Equivalent to

508

−−excmd=number.

509

</td>

510

511

</td>

512

513

514

515

516

−N

517

</td>

518

519

520

521

Equivalent to

522

−−excmd=pattern.

523

</td>

524

525

</td>

526

</table>

527

528

<table width="100%" border=0 rules="none" frame="void"

529

cols="2" cellspacing="0" cellpadding="0">

530

531

532

533

−o tagfile</td>

534

</table>

535

536

<table width="100%" border=0 rules="none" frame="void"

537

cols="2" cellspacing="0" cellpadding="0">

538

539

540

541

Equivalent to −f tagfile.

542

</td>

543

</table>

544

545

<table width="100%" border=0 rules="none" frame="void"

546

cols="4" cellspacing="0" cellpadding="0">

547

548

549

550

551

−R

552

</td>

553

554

555

556

Equivalent to −−recurse.

557

</td>

558

559

560

561

562

−u

563

</td>

564

565

356

357

CLASS Example {

358

359

// your content here

360

};

361

362

The example

363

above uses "CLASS" as a preprocessor macro which

364

expands to something different for each platform. For

365

instance CLASS may be defined as "class

366

__declspec(dllexport)" on Win32 platforms and simply

367

"class" on UNIX. Normally, the absence of the C++

368

keyword "class" would cause the source file to be

369

incorrectly parsed. Correct behavior can be restored by

370

specifying −I CLASS=class.

371

372

−L file

373

374

Read from file a list of

375

file names for which tags should be generated. If

376

file is specified as "−", then file

377

names are read from standard input. File names read using

378

this option are processed following file names appearing on

379

the command line. Options are also accepted in this input.

380

If this option is specified more than once, only the last

381

will apply. Note: file is read in

382

line-oriented mode, where a new line is the only delimiter

383

and non-trailing white space is considered significant, in

384

order that file names containing spaces may be supplied

385

(however, trailing white space is stripped from lines); this

386

can affect how options are parsed if included in the

387

input.

388

389

<table width="100%" border=0 rules="none" frame="void"

390

cellspacing="0" cellpadding="0">

391

392

393

394

395

396

397

−n </td>

398

399

400

401

402

Equivalent to

403

−−excmd=number. </td>

404

405

</td>

406

407

408

409

410

411

−N</td>

412

413

414

415

416

Equivalent to

417

−−excmd=pattern. </td>

418

419

</td>

420

</table>

421

422

−o

423

tagfile

424

425

Equivalent to −f

426

tagfile.

427

428

<table width="100%" border=0 rules="none" frame="void"

429

cellspacing="0" cellpadding="0">

430

431

432

433

434

435

436

−R </td>

437

438

439

440

441

Equivalent to

442

−−recurse. </td>

443

444

445

446

447

448

−u</td>

449

450

451

566

452

567

453

Equivalent to −−sort=no (i.e.

568

"unsorted").

569

</td>

570

571

572

573

574

−V

575

</td>

576

577

578

579

Equivalent to −−verbose.

580

</td>

581

582

583

584

585

−w

586

</td>

587

588

454

"unsorted"). </td>

455

456

457

458

459

460

−V</td>

461

462

463

464

465

Equivalent to −−verbose.</td>

466

467

468

469

470

471

−w</td>

472

473

474

589

475

590

476

This option is silently ignored for

591

backward-compatibility with the ctags of SVR4 Unix.

592

</td>

477

backward-compatibility with the ctags of SVR4 Unix.</td>

593

478

594

479

595

480

596

481

597

−x

598

</td>

482

483

−x</td>

599

484

600

485

601

486

487

602

488

Print a tabular, human-readable cross reference (xref)

603

489

file to standard output instead of generating a tag file.

604

490

The information contained in the output includes: the tag

613

499

located in a source file (e.g. ctags −x

614

500

−−c−kinds=v

615

501

−−file−scope=no file). This

616

option must appear before the first file name.

617

</td>

618

</table>

619

620

<table width="100%" border=0 rules="none" frame="void"

621

cols="2" cellspacing="0" cellpadding="0">

622

623

624

625

626

−−append[=yes|no]</td>

627

</table>

628

629

<table width="100%" border=0 rules="none" frame="void"

630

cols="2" cellspacing="0" cellpadding="0">

631

632

633

634

Indicates whether tags generated from the specified files

635

should be appended to those already present in the tag file

636

or should replace them. This option is off by default. This

637

option must appear before the first file name.

638

</td>

639

</table>

640

641

<table width="100%" border=0 rules="none" frame="void"

642

cols="2" cellspacing="0" cellpadding="0">

643

644

645

646

647

−−etags−include=file</td>

648

</table>

649

650

<table width="100%" border=0 rules="none" frame="void"

651

cols="2" cellspacing="0" cellpadding="0">

652

653

654

655

Include a reference to file in the tag file. This

656

option may be specified as many times as desired. This

657

supports Emacs’ capability to use a tag file which

658

"includes" other tag files. [Available only in

502

option must appear before the first file name.</td>

503

</table>

504

505

506

−−append[=yes|no]

507

508

Indicates whether tags

509

generated from the specified files should be appended to

510

those already present in the tag file or should replace

511

them. This option is off by default. This option must appear

512

before the first file name.

513

514

515

−−etags−include=file

516

517

Include a reference to

518

file in the tag file. This option may be specified as

519

many times as desired. This supports Emacs’ capability

520

to use a tag file which "includes" other tag

521

files. [Available only in etags mode]

522

523

524

−−exclude=[pattern]

525

526

Add pattern to a list of

527

excluded files and directories. This option may be specified

528

as many times as desired. For each file name considered by

529

ctags, each pattern specified using this

530

option will be compared against both the complete path (e.g.

531

some/path/base.ext) and the base name (e.g. base.ext) of the

532

file, thus allowing patterns which match a given file name

533

irrespective of its path, or match only a specific path. If

534

appropriate support is available from the runtime library of

535

your C compiler, then pattern may contain the usual

536

shell wildcards (not regular expressions) common on Unix (be

537

sure to quote the option parameter to protect the wildcards

538

from being expanded by the shell before being passed to

539

ctags; also be aware that wildcards can match the

540

slash character, ’/’). You can determine if

541

shell wildcards are available on your platform by examining

542

the output of the −−version option, which

543

will include "+wildcards" in the compiled feature

544

list; otherwise, pattern is matched against file

545

names using a simple textual comparison.

546

547

If

548

pattern begins with the character ’@’,

549

then the rest of the string is interpreted as a file name

550

from which to read exclusion patterns, one per line. If

551

pattern is empty, the list of excluded patterns is

552

cleared. Note that at program startup, the default exclude

553

list contains "EIFGEN", "SCCS",

554

"RCS", and "CVS", which are names of

555

directories for which it is generally not desirable to

556

descend while processing the −−recurse

557

option.

558

559

560

−−excmd=type

561

562

Determines the type of EX

563

command used to locate tags in the source file. [Ignored in

659

564

etags mode]

660

</td>

661

</table>

662

663

<table width="100%" border=0 rules="none" frame="void"

664

cols="2" cellspacing="0" cellpadding="0">

665

666

667

668

−−exclude=[pattern]</td>

669

</table>

670

671

<table width="100%" border=0 rules="none" frame="void"

672

cols="2" cellspacing="0" cellpadding="0">

673

674

675

676

Add pattern to a list of excluded files and

677

directories. This option may be specified as many times as

678

desired. For each file name considered by ctags, each

679

pattern specified using this option will be compared

680

against both the complete path (e.g. some/path/base.ext) and

681

the base name (e.g. base.ext) of the file, thus allowing

682

patterns which match a given file name irrespective of its

683

path, or match only a specific path. If appropriate support

684

is available from the runtime library of your C compiler,

685

then pattern may contain the usual shell wildcards

686

(not regular expressions) common on Unix (be sure to quote

687

the option parameter to protect the wildcards from being

688

expanded by the shell before being passed to ctags;

689

also be aware that wildcards can match the slash character,

690

’/’). You can determine if shell wildcards are

691

available on your platform by examining the output of the

692

−−version option, which will include

693

"+wildcards" in the compiled feature list;

694

otherwise, pattern is matched against file names

695

using a simple textual comparison.

696

697

If pattern begins with the character

698

’@’, then the rest of the string is interpreted

699

as a file name from which to read exclusion patterns, one

700

per line. If pattern is empty, the list of excluded

701

patterns is cleared. Note that at program startup, the

702

default exclude list contains "EIFGEN",

703

"SCCS", "RCS", and "CVS",

704

which are names of directories for which it is generally not

705

desirable to descend while processing the

706

−−recurse option.

707

</td>

708

</table>

709

710

<table width="100%" border=0 rules="none" frame="void"

711

cols="2" cellspacing="0" cellpadding="0">

712

713

714

715

−−excmd=type</td>

716

</table>

717

718

<table width="100%" border=0 rules="none" frame="void"

719

cols="2" cellspacing="0" cellpadding="0">

720

721

722

723

Determines the type of EX command used to locate tags in

724

the source file. [Ignored in etags mode]

725

726

The valid values for type (either the entire word

727

or the first letter is accepted) are:

728

</td>

729

</table>

730

731

<table width="100%" border=0 rules="none" frame="void"

732

cols="4" cellspacing="0" cellpadding="0">

565

566

The valid

567

values for type (either the entire word or the first

568

letter is accepted) are:

569

570

<table width="100%" border=0 rules="none" frame="void"

571

cellspacing="0" cellpadding="0">

733

572

734

573

735

574

736

575

737

number

738

</td>

576

577

number</td>

739

578

740

579

741

580

742

Use only line numbers in the tag file for locating tags.

743

This has four advantages:

744

</td>

745

</table>

746

747

<table width="100%" border=0 rules="none" frame="void"

748

cols="4" cellspacing="0" cellpadding="0">

749

750

751

752

753

1.

754

</td>

755

756

757

758

Significantly reduces the size of the resulting tag

759

file.

760

</td>

761

762

763

764

765

2.

766

</td>

767

768

769

770

Eliminates failures to find tags because the line

771

defining the tag has changed, causing the pattern match to

772

fail (note that some editors, such as vim, are able

773

to recover in many such instances).

774

</td>

775

776

777

778

779

3.

780

</td>

781

782

783

784

Eliminates finding identical matching, but incorrect,

785

source lines (see BUGS, below).

786

</td>

787

788

789

790

791

4.

792

</td>

793

794

795

796

Retains separate entries in the tag file for lines which

797

are identical in content. In pattern mode, duplicate

798

entries are dropped because the search patterns they

799

generate are identical, making the duplicate entries

800

useless.

801

</td>

802

</table>

803

804

<table width="100%" border=0 rules="none" frame="void"

805

cols="2" cellspacing="0" cellpadding="0">

806

807

808

809

However, this option has one significant drawback:

810

changes to the source files can cause the line numbers

811

recorded in the tag file to no longer correspond to the

812

lines in the source file, causing jumps to some tags to miss

813

the target definition by one or more lines. Basically, this

814

option is best used when the source code to which it is

815

applied is not subject to change. Selecting this option type

816

causes the following options to be ignored:

817

−BF.

818

</td>

819

</table>

820

821

<table width="100%" border=0 rules="none" frame="void"

822

cols="4" cellspacing="0" cellpadding="0">

823

824

825

826

827

pattern

828

</td>

829

830

831

832

Use only search patterns for all tags, rather than the

833

line numbers usually used for macro definitions. This has

834

the advantage of not referencing obsolete line numbers when

835

lines have been added or removed since the tag file was

836

generated.

837

</td>

838

839

840

841

842

mixed

843

</td>

844

845

581

582

Use only line

583

numbers in the tag file for locating tags. This has four

584

advantages: </td>

585

</table>

586

587

<table width="100%" border=0 rules="none" frame="void"

588

cellspacing="0" cellpadding="0">

589

590

591

592

593

594

1.</td>

595

596

597

598

599

Significantly reduces the size of the

600

resulting tag file.</td>

601

602

603

604

605

606

2.</td>

607

608

609

610

611

Eliminates failures to find tags because

612

the line defining the tag has changed, causing the pattern

613

match to fail (note that some editors, such as vim,

614

are able to recover in many such instances).</td>

615

616

617

618

619

620

3.</td>

621

622

623

624

625

Eliminates finding identical matching, but

626

incorrect, source lines (see BUGS, below).</td>

627

628

629

630

631

632

4.</td>

633

634

635

636

637

Retains separate entries in the tag file

638

for lines which are identical in content. In pattern

639

mode, duplicate entries are dropped because the search

640

patterns they generate are identical, making the duplicate

641

entries useless.</td>

642

</table>

643

644

However, this

645

option has one significant drawback: changes to the source

646

files can cause the line numbers recorded in the tag file to

647

no longer correspond to the lines in the source file,

648

causing jumps to some tags to miss the target definition by

649

one or more lines. Basically, this option is best used when

650

the source code to which it is applied is not subject to

651

change. Selecting this option type causes the following

652

options to be ignored: −BF.

653

654

<table width="100%" border=0 rules="none" frame="void"

655

cellspacing="0" cellpadding="0">

656

657

658

659

660

661

pattern</td>

662

663

664

665

666

Use only search

667

patterns for all tags, rather than the line numbers usually

668

used for macro definitions. This has the advantage of not

669

referencing obsolete line numbers when lines have been added

670

or removed since the tag file was generated.</td>

671

672

673

674

675

676

mixed</td>

677

678

679

846

680

847

681

In this mode, patterns are generally used with a few

848

682

exceptions. For C, line numbers are used for macro

851

685

default for this option. For Fortran, line numbers are used

852

686

for common blocks because their corresponding source lines

853

687

are generally identical, making pattern searches useless for

854

finding all matches.

855

</td>

856

</table>

857

858

<table width="100%" border=0 rules="none" frame="void"

859

cols="2" cellspacing="0" cellpadding="0">

860

861

862

863

864

−−extra=[+|−]flags</td>

865

</table>

866

867

<table width="100%" border=0 rules="none" frame="void"

868

cols="2" cellspacing="0" cellpadding="0">

869

870

871

872

Specifies whether to include extra tag entries for

873

certain kinds of information. The parameter flags is

874

a set of one-letter flags, each representing one kind of

875

extra tag entry to include in the tag file. If flags

876

is preceded by by either the ’+’ or

877

’−’ character, the effect of each flag is

878

added to, or removed from, those currently enabled;

879

otherwise the flags replace any current settings. The

880

meaning of each flag is as follows:

881

</td>

882

</table>

883

884

<table width="100%" border=0 rules="none" frame="void"

885

cols="4" cellspacing="0" cellpadding="0">

886

887

888

889

890

f

891

</td>

892

893

894

895

Include an entry for the base file name of every source

896

file (e.g. "example.c"), which addresses the first

897

line of the file.

898

</td>

899

900

901

902

903

q

904

</td>

905

906

907

908

Include an extra class-qualified tag entry for each tag

909

which is a member of a class (for languages for which this

910

information is extracted; currently C++, Eiffel, and Java).

911

The actual form of the qualified tag depends upon the

912

language from which the tag was derived (using a form that

913

is most natural for how qualified calls are specified in the

914

language). For C++, it is in the form

915

"class::member"; for Eiffel and Java, it is in the

916

form "class.member". This may allow easier

917

location of a specific tags when multiple occurrences of a

918

tag name occur in the tag file. Note, however, that this

919

could potentially more than double the size of the tag

920

file.

921

</td>

922

</table>

923

924

<table width="100%" border=0 rules="none" frame="void"

925

cols="2" cellspacing="0" cellpadding="0">

926

927

928

929

930

−−fields=[+|−]flags</td>

931

</table>

932

933

<table width="100%" border=0 rules="none" frame="void"

934

cols="2" cellspacing="0" cellpadding="0">

935

936

937

938

Specifies the available extension fields which are to be

939

included in the entries of the tag file (see TAG FILE

940

FORMAT, below, for more information). The parameter

941

flags is a set of one-letter flags, each representing

942

one type of extension field to include, with the following

943

meanings (disabled by default unless indicated):

944

</td>

945

</table>

946

947

<table width="100%" border=0 rules="none" frame="void"

948

cols="4" cellspacing="0" cellpadding="0">

949

950

951

952

953

a

954

</td>

955

956

957

958

Access (or export) of class members

959

</td>

960

961

962

963

964

f

965

</td>

966

967

968

969

File-restricted scoping [enabled]

970

</td>

971

972

973

974

975

i

976

</td>

977

978

979

980

Inheritance information

981

</td>

982

983

984

985

986

k

987

</td>

988

989

990

991

Kind of tag as a single letter [enabled]

992

</td>

993

994

995

996

997

K

998

</td>

999

1000

1001

1002

Kind of tag as full name

1003

</td>

1004

1005

1006

1007

1008

l

1009

</td>

1010

1011

1012

1013

Language of source file containing tag

1014

</td>

1015

1016

1017

1018

1019

m

1020

</td>

1021

1022

1023

1024

Implementation information

1025

</td>

1026

1027

1028

1029

1030

n

1031

</td>

1032

1033

1034

1035

Line number of tag definition

1036

</td>

1037

1038

1039

1040

1041

s

1042

</td>

1043

1044

1045

1046

Scope of tag definition [enabled]

1047

</td>

1048

1049

1050

1051

1052

S

1053

</td>

1054

1055

1056

1057

Signature of routine (e.g. prototype or parameter

1058

list)

1059

</td>

1060

1061

1062

1063

1064

z

1065

</td>

1066

1067

1068

1069

Include the "kind:" key in kind field

1070

</td>

1071

1072

1073

1074

1075

t

1076

</td>

1077

1078

1079

1080

Type and name of a variable or typedef as

1081

"typeref:" field [enabled]

1082

</td>

1083

</table>

1084

1085

<table width="100%" border=0 rules="none" frame="void"

1086

cols="2" cellspacing="0" cellpadding="0">

1087

1088

1089

1090

Each letter or group of letters may be preceded by either

1091

’+’ to add it to the default set, or

1092

’−’ to exclude it. In the absence of any

1093

preceding ’+’ or ’−’ sign,

1094

only those kinds explicitly listed in flags will be

1095

included in the output (i.e. overriding the default set).

1096

This option is ignored if the option

1097

−−format=1 has been specified. The

1098

default value of this option is fks.</td>

1099

</table>

1100

1101

<table width="100%" border=0 rules="none" frame="void"

1102

cols="2" cellspacing="0" cellpadding="0">

1103

1104

1105

1106

1107

−−file−scope[=yes|no]</td>

1108

</table>

1109

1110

<table width="100%" border=0 rules="none" frame="void"

1111

cols="2" cellspacing="0" cellpadding="0">

1112

1113

1114

1115

Indicates whether tags scoped only for a single file

1116

(i.e. tags which cannot be seen outside of the file in which

1117

they are defined, such as "static" tags) should be

1118

included in the output. See, also, the −h

1119

option. This option is enabled by default.

1120

</td>

1121

</table>

1122

1123

<table width="100%" border=0 rules="none" frame="void"

1124

cols="2" cellspacing="0" cellpadding="0">

1125

1126

1127

1128

1129

−−filter[=yes|no]</td>

1130

</table>

1131

1132

<table width="100%" border=0 rules="none" frame="void"

1133

cols="2" cellspacing="0" cellpadding="0">

1134

1135

1136

1137

Causes ctags to behave as a filter, reading source

1138

file names from standard input and printing their tags to

1139

standard output on a file-by-file basis. If

1140

−−sorted is enabled, tags are sorted only

1141

within the source file in which they are defined. File names

1142

are read from standard input in line-oriented input mode

1143

(see note for −L option) and only after file

1144

names listed on the command line or from any file supplied

1145

using the −L option. When this option is

1146

enabled, the options −f, −o, and

1147

−−totals are ignored. This option is

1148

quite esoteric and is disabled by default. This option must

1149

appear before the first file name.

1150

</td>

1151

</table>

1152

1153

<table width="100%" border=0 rules="none" frame="void"

1154

cols="2" cellspacing="0" cellpadding="0">

1155

1156

1157

1158

1159

−−filter−terminator=string</td>

1160

</table>

1161

1162

<table width="100%" border=0 rules="none" frame="void"

1163

cols="2" cellspacing="0" cellpadding="0">

1164

1165

1166

1167

Specifies a string to print to standard output following

1168

the tags for each file name parsed when the

1169

−−filter option is enabled. This may

1170

permit an application reading the output of ctags to

688

finding all matches.</td>

689

</table>

690

691

692

−−extra=[+|−]flags

693

694

Specifies whether to include

695

extra tag entries for certain kinds of information. The

696

parameter flags is a set of one-letter flags, each

697

representing one kind of extra tag entry to include in the

698

tag file. If flags is preceded by by either the

699

’+’ or ’−’ character, the

700

effect of each flag is added to, or removed from, those

701

currently enabled; otherwise the flags replace any current

702

settings. The meaning of each flag is as follows:

703

704

<table width="100%" border=0 rules="none" frame="void"

705

cellspacing="0" cellpadding="0">

706

707

708

709

710

711

f</td>

712

713

714

715

716

Include an entry

717

for the base file name of every source file (e.g.

718

"example.c"), which addresses the first line of

719

the file.</td>

720

721

722

723

724

725

q</td>

726

727

728

729

730

Include an extra

731

class-qualified tag entry for each tag which is a member of

732

a class (for languages for which this information is

733

extracted; currently C++, Eiffel, and Java). The actual form

734

of the qualified tag depends upon the language from which

735

the tag was derived (using a form that is most natural for

736

how qualified calls are specified in the language). For C++,

737

it is in the form "class::member"; for Eiffel and

738

Java, it is in the form "class.member". This may

739

allow easier location of a specific tags when multiple

740

occurrences of a tag name occur in the tag file. Note,

741

however, that this could potentially more than double the

742

size of the tag file.</td>

743

</table>

744

745

746

−−fields=[+|−]flags

747

748

Specifies the available

749

extension fields which are to be included in the entries of

750

the tag file (see TAG FILE FORMAT, below, for more

751

information). The parameter flags is a set of

752

one-letter flags, each representing one type of extension

753

field to include, with the following meanings (disabled by

754

default unless indicated):

755

756

<table width="100%" border=0 rules="none" frame="void"

757

cellspacing="0" cellpadding="0">

758

759

760

761

762

763

a</td>

764

765

766

767

768

Access (or export)

769

of class members</td>

770

771

772

773

774

775

f</td>

776

777

778

779

780

File-restricted scoping [enabled]</td>

781

782

783

784

785

786

i</td>

787

788

789

790

791

Inheritance information</td>

792

793

794

795

796

797

k</td>

798

799

800

801

802

Kind of tag as a single letter

803

[enabled] </td>

804

805

806

807

808

809

K</td>

810

811

812

813

814

Kind of tag as full name</td>

815

816

817

818

819

820

l</td>

821

822

823

824

825

Language of source file containing tag</td>

826

827

828

829

830

831

m</td>

832

833

834

835

836

Implementation information</td>

837

838

839

840

841

842

n</td>

843

844

845

846

847

Line number of tag definition</td>

848

849

850

851

852

853

s</td>

854

855

856

857

858

Scope of tag definition [enabled]</td>

859

860

861

862

863

864

S</td>

865

866

867

868

869

Signature of routine (e.g. prototype or

870

parameter list)</td>

871

872

873

874

875

876

z</td>

877

878

879

880

881

Include the "kind:" key in kind

882

field </td>

883

884

885

886

887

888

t</td>

889

890

891

892

893

Type and name of a variable or typedef as

894

"typeref:" field [enabled]</td>

895

</table>

896

897

Each letter or

898

group of letters may be preceded by either ’+’

899

to add it to the default set, or ’−’ to

900

exclude it. In the absence of any preceding ’+’

901

or ’−’ sign, only those kinds explicitly

902

listed in flags will be included in the output (i.e.

903

overriding the default set). This option is ignored if the

904

option −−format=1 has been

905

specified. The default value of this option is

906

fkst.

907

908

909

−−file−scope[=yes|no]

910

911

Indicates whether tags scoped

912

only for a single file (i.e. tags which cannot be seen

913

outside of the file in which they are defined, such as

914

"static" tags) should be included in the output.

915

See, also, the −h option. This option is

916

enabled by default.

917

918

919

−−filter[=yes|no]

920

921

Causes ctags to behave

922

as a filter, reading source file names from standard input

923

and printing their tags to standard output on a file-by-file

924

basis. If −−sorted is enabled, tags are

925

sorted only within the source file in which they are

926

defined. File names are read from standard input in

927

line-oriented input mode (see note for −L

928

option) and only after file names listed on the command line

929

or from any file supplied using the −L option.

930

When this option is enabled, the options −f,

931

−o, and −−totals are

932

ignored. This option is quite esoteric and is disabled by

933

default. This option must appear before the first file

934

name.

935

936

937

−−filter−terminator=string

938

939

Specifies a string to print to

940

standard output following the tags for each file name parsed

941

when the −−filter option is enabled. This

942

may permit an application reading the output of ctags to

1171

943

determine when the output for each file is finished. Note

1172

944

that if the file name read is a directory and

1173

945

−−recurse is enabled, this string will be

1177

949

terminating newline. This option is quite esoteric and is

1178

950

empty by default. This option must appear before the first

1179

951

file name.

1180

</td>

1181

</table>

1182

1183

<table width="100%" border=0 rules="none" frame="void"

1184

cols="2" cellspacing="0" cellpadding="0">

1185

1186

1187

1188

−−format=level</td>

1189

</table>

1190

1191

<table width="100%" border=0 rules="none" frame="void"

1192

cols="2" cellspacing="0" cellpadding="0">

1193

1194

1195

1196

Change the format of the output tag file. Currently the

1197

only valid values for level are 1 or 2.

1198

Level 1 specifies the original tag file format and level 2

1199

specifies a new extended format containing extension fields

1200

(but in a manner which retains backward-compatibility with

1201

original vi(1) implementations). The default level is

1202

2. This option must appear before the first file name.

1203

[Ignored in etags mode]

1204

</td>

1205

</table>

1206

1207

<table width="100%" border=0 rules="none" frame="void"

1208

cols="2" cellspacing="0" cellpadding="0">

1209

1210

1211

1212

−−help</td>

1213

</table>

1214

1215

<table width="100%" border=0 rules="none" frame="void"

1216

cols="2" cellspacing="0" cellpadding="0">

1217

1218

1219

1220

Prints to standard output a detailed usage description,

1221

and then exits.

1222

</td>

1223

</table>

1224

1225

<table width="100%" border=0 rules="none" frame="void"

1226

cols="2" cellspacing="0" cellpadding="0">

1227

1228

1229

1230

−−if0[=yes|no]</td>

1231

</table>

1232

1233

<table width="100%" border=0 rules="none" frame="void"

1234

cols="2" cellspacing="0" cellpadding="0">

1235

1236

1237

1238

Indicates a preference as to whether code within an

1239

"#if 0" branch of a preprocessor conditional

1240

should be examined for non-macro tags (macro tags are always

1241

included). Because the intent of this construct is to

1242

disable code, the default value of this option is no.

1243

Note that this indicates a preference only and does not

1244

guarantee skipping code within an "#if 0" branch,

1245

since the fall-back algorithm used to generate tags when

1246

preprocessor conditionals are too complex follows all

1247

branches of a conditional. This option is disabled by

1248

default.

1249

</td>

1250

</table>

1251

1252

<table width="100%" border=0 rules="none" frame="void"

1253

cols="2" cellspacing="0" cellpadding="0">

1254

1255

1256

1257

1258

−−<LANG>−kinds=[+|−]kinds</td>

1259

</table>

1260

1261

<table width="100%" border=0 rules="none" frame="void"

1262

cols="2" cellspacing="0" cellpadding="0">

1263

1264

1265

1266

Specifies a list of language-specific kinds of tags (or

1267

kinds) to include in the output file for a particular

1268

language, where <LANG> is case-insensitive and

1269

is one of the built-in language names (see the

952

953

954

−−format=level

955

956

Change the format of the output

957

tag file. Currently the only valid values for level

958

are 1 or 2. Level 1 specifies the original tag

959

file format and level 2 specifies a new extended format

960

containing extension fields (but in a manner which retains

961

backward-compatibility with original vi(1)

962

implementations). The default level is 2. This option must

963

appear before the first file name. [Ignored in etags

964

mode]

965

966

−−help

967

968

Prints to standard output a

969

detailed usage description, and then exits.

970

971

972

−−if0[=yes|no]

973

974

Indicates a preference as to

975

whether code within an "#if 0" branch of a

976

preprocessor conditional should be examined for non-macro

977

tags (macro tags are always included). Because the intent of

978

this construct is to disable code, the default value of this

979

option is no. Note that this indicates a preference

980

only and does not guarantee skipping code within an

981

"#if 0" branch, since the fall-back algorithm used

982

to generate tags when preprocessor conditionals are too

983

complex follows all branches of a conditional. This option

984

is disabled by default.

985

986

987

−−<LANG>−kinds=[+|−]kinds

988

989

Specifies a list of

990

language-specific kinds of tags (or kinds) to include in the

991

output file for a particular language, where

992

<LANG> is case-insensitive and is one of the

993

built-in language names (see the

1270

994

−−list−languages option for a

1271

995

complete list). The parameter kinds is a group of

1272

996

one-letter flags designating kinds of tags (particular to

1281

1005

kinds explicitly listed in kinds will be included in

1282

1006

the output (i.e. overriding the default for the specified

1283

1007

language).

1284

1285

As an example for the C language, in order to add

1286

prototypes and external variable declarations to the default

1287

set of tag kinds, but exclude macros, use

1008

1009

As an example

1010

for the C language, in order to add prototypes and external

1011

variable declarations to the default set of tag kinds, but

1012

exclude macros, use

1288

1013

−−c−kinds=+px−d; to

1289

1014

include only tags for functions, use

1290

1015

−−c−kinds=f.

1291

</td>

1292

</table>

1293

1294

<table width="100%" border=0 rules="none" frame="void"

1295

cols="2" cellspacing="0" cellpadding="0">

1296

1297

1298

1299

−−langdef=name</td>

1300

</table>

1301

1302

<table width="100%" border=0 rules="none" frame="void"

1303

cols="2" cellspacing="0" cellpadding="0">

1304

1305

1306

1307

Defines a new user-defined language, name, to be

1308

parsed with regular expressions. Once defined, name

1309

may be used in other options taking language names. The

1310

typical use of this option is to first define the language,

1311

then map file names to it using

1312

−−langmap, then specify regular

1313

expressions using

1016

1017

1018

−−langdef=name

1019

1020

Defines a new user-defined

1021

language, name, to be parsed with regular

1022

expressions. Once defined, name may be used in other

1023

options taking language names. The typical use of this

1024

option is to first define the language, then map file names

1025

to it using −−langmap, then specify

1026

regular expressions using

1314

1027

−−regex−<LANG> to define how

1315

1028

its tags are found.

1316

</td>

1317

</table>

1318

1319

<table width="100%" border=0 rules="none" frame="void"

1320

cols="2" cellspacing="0" cellpadding="0">

1321

1322

1323

1324

1325

−−langmap=map[,map[...]]</td>

1326

</table>

1327

1328

<table width="100%" border=0 rules="none" frame="void"

1329

cols="2" cellspacing="0" cellpadding="0">

1330

1331

1332

1333

Controls how file names are mapped to languages (see the

1029

1030

1031

−−langmap=map[,map[...]]

1032

1033

Controls how file names are

1034

mapped to languages (see the

1334

1035

−−list−maps option). Each

1335

1036

comma-separated map consists of the language name

1336

1037

(either a built-in or user-defined language), a colon, and a

1351

1052

file names using a simple textual comparison. When mapping a

1352

1053

file extension, it will first be unmapped from any other

1353

1054

languages.

1354

1355

If the first character in a map is a plus sign, then the

1356

extensions and file name patterns in that map will be

1357

appended to the current map for that language; otherwise,

1358

the map will replace the current map. For example, to

1359

specify that only files with extensions of .c and .x are to

1360

be treated as C language files, use

1055

1056

If the first

1057

character in a map is a plus sign, then the extensions and

1058

file name patterns in that map will be appended to the

1059

current map for that language; otherwise, the map will

1060

replace the current map. For example, to specify that only

1061

files with extensions of .c and .x are to be treated as C

1062

language files, use

1361

1063

"−−langmap=c:.c.x"; to

1362

1064

also add files with extensions of .j as Java language files,

1363

1065

specify

1381

1083

"−−langmap=default".

1382

1084

Note that file extensions are tested before file name

1383

1085

patterns when inferring the language of a file.

1384

</td>

1385

</table>

1386

1387

<table width="100%" border=0 rules="none" frame="void"

1388

cols="2" cellspacing="0" cellpadding="0">

1389

1390

1391

1392

1393

−−language−force=language</td>

1394

</table>

1395

1396

<table width="100%" border=0 rules="none" frame="void"

1397

cols="2" cellspacing="0" cellpadding="0">

1398

1399

1400

1401

By default, ctags automatically selects the

1402

language of a source file, ignoring those files whose

1403

language cannot be determined (see SOURCE FILES,

1404

above). This option forces the specified language

1405

(case-insensitive; either built-in or user-defined) to be

1406

used for every supplied file instead of automatically

1407

selecting the language based upon its extension. In

1408

addition, the special value auto indicates that the

1409

language should be automatically selected (which effectively

1410

disables this option).

1411

</td>

1412

</table>

1413

1414

<table width="100%" border=0 rules="none" frame="void"

1415

cols="2" cellspacing="0" cellpadding="0">

1416

1417

1418

1419

1420

−−languages=[+|−]list</td>

1421

</table>

1422

1423

<table width="100%" border=0 rules="none" frame="void"

1424

cols="2" cellspacing="0" cellpadding="0">

1425

1426

1427

1428

Specifies the languages for which tag generation is

1429

enabled, with list containing a comma-separated list

1430

of language names (case-insensitive; either built-in or

1431

user-defined). If the first language of list is not

1432

preceded by either a ’+’ or

1086

1087

1088

−−language−force=language

1089

1090

By default, ctags

1091

automatically selects the language of a source file,

1092

ignoring those files whose language cannot be determined

1093

(see SOURCE FILES, above). This option forces the

1094

specified language (case-insensitive; either built-in

1095

or user-defined) to be used for every supplied file instead

1096

of automatically selecting the language based upon its

1097

extension. In addition, the special value auto

1098

indicates that the language should be automatically selected

1099

(which effectively disables this option).

1100

1101

1102

−−languages=[+|−]list

1103

1104

Specifies the languages for

1105

which tag generation is enabled, with list containing

1106

a comma-separated list of language names (case-insensitive;

1107

either built-in or user-defined). If the first language of

1108

list is not preceded by either a ’+’ or

1433

1109

’−’, the current list will be cleared

1434

1110

before adding or removing the languages in list.

1435

1111

Until a ’−’ is encountered, each language

1450

1126

valid argument. See the

1451

1127

−−list−languages option for a

1452

1128

complete list of the built-in language names.

1453

</td>

1454

</table>

1455

1456

<table width="100%" border=0 rules="none" frame="void"

1457

cols="2" cellspacing="0" cellpadding="0">

1458

1459

1460

1461

−−license</td>

1462

</table>

1463

1464

<table width="100%" border=0 rules="none" frame="void"

1465

cols="2" cellspacing="0" cellpadding="0">

1466

1467

1468

1469

Prints a summary of the software license to standard

1470

output, and then exits.

1471

</td>

1472

</table>

1473

1474

<table width="100%" border=0 rules="none" frame="void"

1475

cols="2" cellspacing="0" cellpadding="0">

1476

1477

1478

1479

1480

−−line−directives[=yes|no]</td>

1481

</table>

1482

1483

<table width="100%" border=0 rules="none" frame="void"

1484

cols="2" cellspacing="0" cellpadding="0">

1485

1486

1487

1488

Specifies whether "#line" directives should be

1489

recognized. These are present in the output of preprocessors

1490

and contain the line number, and possibly the file name, of

1491

the original source file(s) from which the preprocessor

1492

output file was generated. When enabled, this option will

1493

cause ctags to generate tag entries marked with the

1494

file names and line numbers of their locations original

1495

source file(s), instead of their actual locations in the

1496

preprocessor output. The actual file names placed into the

1497

tag file will have the same leading path components as the

1498

preprocessor output file, since it is assumed that the

1499

original source files are located relative to the

1500

preprocessor output file (unless, of course, the #line

1501

directive specifies an absolute path). This option is off by

1502

default. Note: This option is generally only useful

1503

when used together with the

1129

1130

1131

−−license

1132

1133

Prints a summary of the

1134

software license to standard output, and then exits.

1135

1136

1137

−−line−directives[=yes|no]

1138

1139

Specifies whether

1140

"#line" directives should be recognized. These are

1141

present in the output of preprocessors and contain the line

1142

number, and possibly the file name, of the original source

1143

file(s) from which the preprocessor output file was

1144

generated. When enabled, this option will cause ctags

1145

to generate tag entries marked with the file names and line

1146

numbers of their locations original source file(s), instead

1147

of their actual locations in the preprocessor output. The

1148

actual file names placed into the tag file will have the

1149

same leading path components as the preprocessor output

1150

file, since it is assumed that the original source files are

1151

located relative to the preprocessor output file (unless, of

1152

course, the #line directive specifies an absolute path).

1153

This option is off by default. Note: This option is

1154

generally only useful when used together with the

1504

1155

−−excmd=number (−n)

1505

1156

option. Also, you may have to use either the

1506

1157

−−langmap or

1507

1158

−−language−force option if the

1508

1159

extension of the preprocessor output file is not known to

1509

1160

ctags.

1510

</td>

1511

</table>

1512

1513

<table width="100%" border=0 rules="none" frame="void"

1514

cols="2" cellspacing="0" cellpadding="0">

1515

1516

1517

1518

1519

−−links[=yes|no]</td>

1520

</table>

1521

1522

<table width="100%" border=0 rules="none" frame="void"

1523

cols="2" cellspacing="0" cellpadding="0">

1524

1525

1526

1527

Indicates whether symbolic links (if supported) should be

1528

followed. When disabled, symbolic links are ignored. This

1529

option is on by default.

1530

</td>

1531

</table>

1532

1533

<table width="100%" border=0 rules="none" frame="void"

1534

cols="2" cellspacing="0" cellpadding="0">

1535

1536

1537

1538

1539

−−list−kinds[=language|all]</td>

1540

</table>

1541

1542

<table width="100%" border=0 rules="none" frame="void"

1543

cols="2" cellspacing="0" cellpadding="0">

1544

1545

1546

1547

Lists the tag kinds recognized for either the specified

1548

language or all languages, and then exits. Each kind of tag

1549

recorded in the tag file is represented by a one-letter

1550

flag, which is also used to filter the tags placed into the

1551

output through use of the

1161

1162

1163

−−links[=yes|no]

1164

1165

Indicates whether symbolic

1166

links (if supported) should be followed. When disabled,

1167

symbolic links are ignored. This option is on by

1168

default.

1169

1170

1171

−−list−kinds[=language|all]

1172

1173

Lists the tag kinds recognized

1174

for either the specified language or all languages, and then

1175

exits. Each kind of tag recorded in the tag file is

1176

represented by a one-letter flag, which is also used to

1177

filter the tags placed into the output through use of the

1552

1178

−−<LANG>−kinds option. Note

1553

1179

that some languages and/or tag kinds may be implemented

1554

1180

using regular expressions and may not be available if regex

1556

1182

−−regex−<LANG> option). Each

1557

1183

kind listed is enabled unless followed by

1558

1184

"[off]".

1559

</td>

1560

</table>

1561

1562

<table width="100%" border=0 rules="none" frame="void"

1563

cols="2" cellspacing="0" cellpadding="0">

1564

1565

1566

1567

1568

−−list−maps[=language|all]</td>

1569

</table>

1570

1571

<table width="100%" border=0 rules="none" frame="void"

1572

cols="2" cellspacing="0" cellpadding="0">

1573

1574

1575

1576

Lists the file extensions and file name patterns which

1577

associate a file name with a language for either the

1578

specified language or all languages, and then exits. See the

1579

−−langmap option, and SOURCE

1580

FILES, above.

1581

</td>

1582

</table>

1583

1584

<table width="100%" border=0 rules="none" frame="void"

1585

cols="2" cellspacing="0" cellpadding="0">

1586

1587

1588

1589

−−list−languages</td>

1590

</table>

1591

1592

<table width="100%" border=0 rules="none" frame="void"

1593

cols="2" cellspacing="0" cellpadding="0">

1594

1595

1596

1597

Lists the names of the languages understood by

1598

ctags, and then exits. These language names are case

1599

insensitive and may be used in the

1185

1186

1187

−−list−maps[=language|all]

1188

1189

Lists the file extensions and

1190

file name patterns which associate a file name with a

1191

language for either the specified language or all languages,

1192

and then exits. See the −−langmap option,

1193

and SOURCE FILES, above.

1194

1195

1196

−−list−languages

1197

1198

Lists the names of the

1199

languages understood by ctags, and then exits. These

1200

language names are case insensitive and may be used in the

1600

1201

−−language−force,

1601

1202

−−languages,

1602

1203

−−<LANG>−kinds, and

1603

1204

−−regex−<LANG> options.

1604

</td>

1605

</table>

1606

1607

<table width="100%" border=0 rules="none" frame="void"

1608

cols="2" cellspacing="0" cellpadding="0">

1609

1610

1611

1612

−−options=file</td>

1613

</table>

1614

1615

<table width="100%" border=0 rules="none" frame="void"

1616

cols="2" cellspacing="0" cellpadding="0">

1617

1618

1619

1620

Read additional options from file. The file should

1621

contain one option per line. As a special case, if

1622

−−options=NONE is specified as the

1623

first option on the command line, it will disable the

1624

automatic reading of any configuration options from either a

1625

file or the environment (see FILES).

1626

</td>

1627

</table>

1628

1629

<table width="100%" border=0 rules="none" frame="void"

1630

cols="2" cellspacing="0" cellpadding="0">

1631

1632

1633

1634

1635

−−recurse[=yes|no]</td>

1636

</table>

1637

1638

<table width="100%" border=0 rules="none" frame="void"

1639

cols="2" cellspacing="0" cellpadding="0">

1640

1641

1642

1643

Recurse into directories encountered in the list of

1644

supplied files. If the list of supplied files is empty and

1645

no file list is specified with the −L option,

1646

then the current directory (i.e. ".") is assumed.

1647

Symbolic links are followed. If you don’t like these

1648

behaviors, either explicitly specify the files or pipe the

1649

output of find(1) into ctags −L−

1650

instead. Note: This option is not supported on all

1651

platforms at present. It is available if the output of the

1652

−−help option includes this option. See,

1653

also, the −−exclude to limit

1654

recursion.

1655

</td>

1656

</table>

1657

1658

<table width="100%" border=0 rules="none" frame="void"

1659

cols="2" cellspacing="0" cellpadding="0">

1660

1661

1662

1663

1664

−−regex−<LANG>=/regexp/replacement/[kind−spec/][flags]</td>

1665

</table>

1666

1667

<table width="100%" border=0 rules="none" frame="void"

1668

cols="2" cellspacing="0" cellpadding="0">

1669

1670

1671

1672

The /regexp/replacement/ pair define a regular

1673

expression replacement pattern, similar in style to

1674

sed substitution commands, with which to generate

1675

tags from source files mapped to the named language,

1676

<LANG>, (case-insensitive; either a built-in or

1677

user-defined language). The regular expression,

1205

1206

1207

−−options=file

1208

1209

Read additional options from

1210

file. The file should contain one option per line. As

1211

a special case, if −−options=NONE

1212

is specified as the first option on the command line, it

1213

will disable the automatic reading of any configuration

1214

options from either a file or the environment (see

1215

FILES).

1216

1217

1218

−−recurse[=yes|no]

1219

1220

Recurse into directories

1221

encountered in the list of supplied files. If the list of

1222

supplied files is empty and no file list is specified with

1223

the −L option, then the current directory (i.e.

1224

".") is assumed. Symbolic links are followed. If

1225

you don’t like these behaviors, either explicitly

1226

specify the files or pipe the output of find(1) into

1227

ctags −L− instead. Note: This

1228

option is not supported on all platforms at present. It is

1229

available if the output of the −−help

1230

option includes this option. See, also, the

1231

−−exclude to limit recursion.

1232

1233

1234

−−regex−<LANG>=/regexp/replacement/[kind−spec/][flags]

1235

1236

The /regexp/replacement/

1237

pair define a regular expression replacement pattern,

1238

similar in style to sed substitution commands, with

1239

which to generate tags from source files mapped to the named

1240

language, <LANG>, (case-insensitive; either a

1241

built-in or user-defined language). The regular expression,

1678

1242

regexp, defines an extended regular expression

1679

1243

(roughly that used by egrep(1)), which is used to

1680

1244

locate a single source line containing a tag and may specify

1692

1256

is added to the current list of regular expressions for the

1693

1257

specified language unless the parameter is omitted, in which

1694

1258

case the current list is cleared.

1695

1696

Unless modified by flags, regexp is

1697

interpreted as a Posix extended regular expression. The

1698

replacement should expand for all matching lines to a

1699

non-empty string of characters, or a warning message will be

1700

reported. An optional kind specifier for tags matching

1701

regexp may follow replacement, which will

1702

determine what kind of tag is reported in the

1703

"kind" extension field (see TAG FILE

1704

FORMAT, below). The full form of kind−spec

1705

is in the form of a single letter, a comma, a name (without

1706

spaces), a comma, a description, followed by a separator,

1707

which specify the short and long forms of the kind value and

1708

its textual description (displayed using

1709

−−list−kinds). Either the kind name

1710

and/or the description may be omitted. If

1711

kind−spec is omitted, it defaults to

1259

1260

Unless modified

1261

by flags, regexp is interpreted as a Posix

1262

extended regular expression. The replacement should

1263

expand for all matching lines to a non-empty string of

1264

characters, or a warning message will be reported. An

1265

optional kind specifier for tags matching regexp may

1266

follow replacement, which will determine what kind of

1267

tag is reported in the "kind" extension field (see

1268

TAG FILE FORMAT, below). The full form of

1269

kind−spec is in the form of a single letter, a

1270

comma, a name (without spaces), a comma, a description,

1271

followed by a separator, which specify the short and long

1272

forms of the kind value and its textual description

1273

(displayed using −−list−kinds).

1274

Either the kind name and/or the description may be omitted.

1275

If kind−spec is omitted, it defaults to

1712

1276

"r,regex". Finally, flags are one or

1713

1277

more single-letter characters having the following effect

1714

1278

upon the interpretation of regexp:

1715

</td>

1716

</table>

1717

1718

<table width="100%" border=0 rules="none" frame="void"

1719

cols="4" cellspacing="0" cellpadding="0">

1720

1721

1722

1723

1724

b

1725

</td>

1726

1727

1728

1729

The pattern is interpreted as a Posix basic regular

1730

expression.

1731

</td>

1732

1733

1734

1735

1736

e

1737

</td>

1738

1739

1740

1741

The pattern is interpreted as a Posix extended regular

1742

expression (default).

1743

</td>

1744

1745

1746

1747

1748

i

1749

</td>

1750

1751

1752

1753

The regular expression is to be applied in a

1754

case-insensitive manner.

1755

</td>

1756

</table>

1757

1758

<table width="100%" border=0 rules="none" frame="void"

1759

cols="2" cellspacing="0" cellpadding="0">

1760

1761

1762

1763

Note that this option is available only if ctags

1764

was compiled with support for regular expressions, which

1765

depends upon your platform. You can determine if support for

1766

regular expressions is compiled in by examining the output

1767

of the −−version option, which will

1768

include "+regex" in the compiled feature list.

1769

1770

For more information on the regular expressions used by

1771

ctags, see either the regex(5,7) man page, or

1772

the GNU info documentation for regex (e.g. "info

1773

regex").</td>

1774

</table>

1775

1776

<table width="100%" border=0 rules="none" frame="void"

1777

cols="2" cellspacing="0" cellpadding="0">

1778

1779

1780

1781

1782

−−sort[=yes|no|foldcase]</td>

1783

</table>

1784

1785

<table width="100%" border=0 rules="none" frame="void"

1786

cols="2" cellspacing="0" cellpadding="0">

1787

1788

1789

1790

Indicates whether the tag file should be sorted on the

1791

tag name (default is yes). Note that the original

1792

vi(1) required sorted tags. The foldcase value

1793

specifies case insensitive (or case-folded) sorting. Fast

1794

binary searches of tag files sorted with case-folding will

1795

require special support from tools using tag files, such as

1796

that found in the ctags readtags library, or Vim version 6.2

1797

or higher (using "set ignorecase"). This option

1798

must appear before the first file name. [Ignored in etags

1799

mode]

1800

</td>

1801

</table>

1802

1803

<table width="100%" border=0 rules="none" frame="void"

1804

cols="2" cellspacing="0" cellpadding="0">

1805

1806

1807

1808

1809

−−tag−relative[=yes|no]</td>

1810

</table>

1811

1812

<table width="100%" border=0 rules="none" frame="void"

1813

cols="2" cellspacing="0" cellpadding="0">

1814

1815

1816

1817

Indicates that the file paths recorded in the tag file

1818

should be relative to the directory containing the tag file,

1819

rather than relative to the current directory, unless the

1820

files supplied on the command line are specified with

1821

absolute paths. This option must appear before the first

1822

file name. The default is yes when running in etags

1823

mode (see the −e option), no

1824

otherwise.

1825

</td>

1826

</table>

1827

1828

<table width="100%" border=0 rules="none" frame="void"

1829

cols="2" cellspacing="0" cellpadding="0">

1830

1831

1832

1833

1834

−−totals[=yes|no]</td>

1835

</table>

1836

1837

<table width="100%" border=0 rules="none" frame="void"

1838

cols="2" cellspacing="0" cellpadding="0">

1839

1840

1841

1842

Prints statistics about the source files read and the tag

1843

file written during the current invocation of ctags.

1844

This option is off by default. This option must appear

1845

before the first file name.

1846

</td>

1847

</table>

1848

1849

<table width="100%" border=0 rules="none" frame="void"

1850

cols="2" cellspacing="0" cellpadding="0">

1851

1852

1853

1854

1855

−−verbose[=yes|no]</td>

1856

</table>

1857

1858

<table width="100%" border=0 rules="none" frame="void"

1859

cols="2" cellspacing="0" cellpadding="0">

1860

1861

1862

1863

Enable verbose mode. This prints out information on

1864

option processing and a brief message describing what action

1865

is being taken for each file considered by ctags.

1866

Normally, ctags does not read command line arguments

1867

until after options are read from the configuration files

1868

(see FILES, below) and the CTAGS environment

1869

variable. However, if this option is the first argument on

1870

the command line, it will take effect before any options are

1871

read from these sources. The default is no.

1872

</td>

1873

</table>

1874

1875

<table width="100%" border=0 rules="none" frame="void"

1876

cols="2" cellspacing="0" cellpadding="0">

1877

1878

1879

1880

−−version</td>

1881

</table>

1882

1883

<table width="100%" border=0 rules="none" frame="void"

1884

cols="2" cellspacing="0" cellpadding="0">

1885

1886

1887

1888

Prints a version identifier for ctags to standard

1889

output, and then exits. This is guaranteed to always contain

1890

the string "Exuberant Ctags".

1891

</td>

1892

</table>

1279

1280

<table width="100%" border=0 rules="none" frame="void"

1281

cellspacing="0" cellpadding="0">

1282

1283

1284

1285

1286

1287

b</td>

1288

1289

1290

1291

1292

The pattern is

1293

interpreted as a Posix basic regular expression.</td>

1294

1295

1296

1297

1298

1299

e</td>

1300

1301

1302

1303

1304

The pattern is

1305

interpreted as a Posix extended regular expression

1306

(default). </td>

1307

1308

1309

1310

1311

1312

i</td>

1313

1314

1315

1316

1317

The regular

1318

expression is to be applied in a case-insensitive

1319

manner. </td>

1320

</table>

1321

1322

Note that this

1323

option is available only if ctags was compiled with

1324

support for regular expressions, which depends upon your

1325

platform. You can determine if support for regular

1326

expressions is compiled in by examining the output of the

1327

−−version option, which will include

1328

"+regex" in the compiled feature list.

1329

1330

For more

1331

information on the regular expressions used by ctags,

1332

see either the regex(5,7) man page, or the GNU info

1333

documentation for regex (e.g. "info regex").

1334

1335

1336

−−sort[=yes|no|foldcase]

1337

1338

Indicates whether the tag file

1339

should be sorted on the tag name (default is yes).

1340

Note that the original vi(1) required sorted tags.

1341

The foldcase value specifies case insensitive (or

1342

case-folded) sorting. Fast binary searches of tag files

1343

sorted with case-folding will require special support from

1344

tools using tag files, such as that found in the ctags

1345

readtags library, or Vim version 6.2 or higher (using

1346

"set ignorecase"). This option must appear before

1347

the first file name. [Ignored in etags mode]

1348

1349

1350

−−tag−relative[=yes|no]

1351

1352

Indicates that the file paths

1353

recorded in the tag file should be relative to the directory

1354

containing the tag file, rather than relative to the current

1355

directory, unless the files supplied on the command line are

1356

specified with absolute paths. This option must appear

1357

before the first file name. The default is yes when

1358

running in etags mode (see the −e option),

1359

no otherwise.

1360

1361

1362

−−totals[=yes|no]

1363

1364

Prints statistics about the

1365

source files read and the tag file written during the

1366

current invocation of ctags. This option is off by

1367

default. This option must appear before the first file

1368

name.

1369

1370

1371

−−verbose[=yes|no]

1372

1373

Enable verbose mode. This

1374

prints out information on option processing and a brief

1375

message describing what action is being taken for each file

1376

considered by ctags. Normally, ctags does not

1377

read command line arguments until after options are read

1378

from the configuration files (see FILES, below) and

1379

the CTAGS environment variable. However, if this

1380

option is the first argument on the command line, it will

1381

take effect before any options are read from these sources.

1382

The default is no.

1383

1384

1385

−−version

1386

1387

Prints a version identifier for

1388

ctags to standard output, and then exits. This is

1389

guaranteed to always contain the string "Exuberant

1390

Ctags".

1391

1893

1392

1894

1393

<h2>OPERATIONAL DETAILS</h2>

1895

1896

<table width="100%" border=0 rules="none" frame="void"

1897

cols="2" cellspacing="0" cellpadding="0">

1898

1899

1900

1901

As ctags considers each file name in turn, it

1902

tries to determine the language of the file by applying the

1903

following three tests in order: if the file extension has

1904

been mapped to a language, if the file name matches a shell

1905

pattern mapped to a language, and finally if the file is

1906

executable and its first line specifies an interpreter using

1907

the Unix-style "#!" specification (if supported on

1908

the platform). If a language was identified, the file is

1909

opened and then the appropriate language parser is called to

1910

operate on the currently open file. The parser parses

1911

through the file and adds an entry to the tag file for each

1912

language object it is written to handle. See TAG FILE

1913

FORMAT, below, for details on these entries.

1914

1915

This implementation of ctags imposes no formatting

1394

1395

1396

As ctags

1397

considers each file name in turn, it tries to determine the

1398

language of the file by applying the following three tests

1399

in order: if the file extension has been mapped to a

1400

language, if the file name matches a shell pattern mapped to

1401

a language, and finally if the file is executable and its

1402

first line specifies an interpreter using the Unix-style

1403

"#!" specification (if supported on the platform).

1404

If a language was identified, the file is opened and then

1405

the appropriate language parser is called to operate on the

1406

currently open file. The parser parses through the file and

1407

adds an entry to the tag file for each language object it is

1408

written to handle. See TAG FILE FORMAT, below, for

1409

details on these entries.

1410

1411

This

1412

implementation of ctags imposes no formatting

1916

1413

requirements on C code as do legacy implementations. Older

1917

1414

implementations of ctags tended to rely upon certain

1918

1415

formatting assumptions in order to help it resolve coding

1919

1416

dilemmas caused by preprocessor conditionals.

1920

1921

In general, ctags tries to be smart about

1922

conditional preprocessor directives. If a preprocessor

1923

conditional is encountered within a statement which defines

1924

a tag, ctags follows only the first branch of that

1417

1418

In general,

1419

ctags tries to be smart about conditional

1420

preprocessor directives. If a preprocessor conditional is

1421

encountered within a statement which defines a tag,

1422

ctags follows only the first branch of that

1925

1423

conditional (except in the special case of "#if

1926

1424

0", in which case it follows only the last branch). The

1927

1425

reason for this is that failing to pursue only one branch

1928

1426

can result in ambiguous syntax, as in the following

1929

1427

example:

1930

</td>

1931

</table>

1932

1933

<table width="100%" border=0 rules="none" frame="void"

1934

cols="2" cellspacing="0" cellpadding="0">

1935

1936

1937

1938

#ifdef TWO_ALTERNATIVES

1939

struct {

1940

#else

1941

union {

1942

#endif</td>

1943

</table>

1944

1945

<table width="100%" border=0 rules="none" frame="void"

1946

cols="2" cellspacing="0" cellpadding="0">

1947

1948

1949

1950

short a;

1951

long b;</td>

1952

</table>

1953

1954

<table width="100%" border=0 rules="none" frame="void"

1955

cols="2" cellspacing="0" cellpadding="0">

1956

1957

1958

1959

}</td>

1960

</table>

1961

1962

<table width="100%" border=0 rules="none" frame="void"

1963

cols="2" cellspacing="0" cellpadding="0">

1964

1965

1966

1967

Both branches cannot be followed, or braces become

1968

unbalanced and ctags would be unable to make sense of

1969

the syntax.

1970

1971

If the application of this heuristic fails to properly

1972

parse a file, generally due to complicated and inconsistent

1973

pairing within the conditionals, ctags will retry the

1974

file using a different heuristic which does not selectively

1428

1429

#ifdef

1430

TWO_ALTERNATIVES

1431

struct {

1432

#else

1433

union {

1434

#endif

1435

1436

short a;

1437

long b;

1438

1439

}

1440

1441

Both branches

1442

cannot be followed, or braces become unbalanced and

1443

ctags would be unable to make sense of the

1444

syntax.

1445

1446

If the

1447

application of this heuristic fails to properly parse a

1448

file, generally due to complicated and inconsistent pairing

1449

within the conditionals, ctags will retry the file

1450

using a different heuristic which does not selectively

1975

1451

follow conditional preprocessor branches, but instead falls

1976

1452

back to relying upon a closing brace ("}") in

1977

1453

column 1 as indicating the end of a block once any brace

1978

1454

imbalance results from following a #if conditional

1979

1455

branch.

1980

1981

Ctags will also try to specially handle arguments

1982

lists enclosed in double sets of parentheses in order to

1983

accept the following conditional construct:

1984

</td>

1985

</table>

1986

1987

<table width="100%" border=0 rules="none" frame="void"

1988

cols="2" cellspacing="0" cellpadding="0">

1989

1990

1991

1992

extern void foo __ARGS((int one, char two));</td>

1993

</table>

1994

1995

<table width="100%" border=0 rules="none" frame="void"

1996

cols="2" cellspacing="0" cellpadding="0">

1997

1998

1999

2000

Any name immediately preceding the "((" will be

1456

1457

Ctags

1458

will also try to specially handle arguments lists enclosed

1459

in double sets of parentheses in order to accept the

1460

following conditional construct:

1461

1462

extern void foo

1463

__ARGS((int one, char two));

1464

1465

Any name

1466

immediately preceding the "((" will be

2001

1467

automatically ignored and the previous name will be

2002

1468

used.

2003

2004

C++ operator definitions are specially handled. In order

2005

for consistency with all types of operators (overloaded and

2006

conversion), the operator name in the tag file will always

2007

be preceded by the string "operator " (i.e. even

2008

if the actual operator definition was written as

1469

1470

C++ operator

1471

definitions are specially handled. In order for consistency

1472

with all types of operators (overloaded and conversion), the

1473

operator name in the tag file will always be preceded by the

1474

string "operator " (i.e. even if the actual

1475

operator definition was written as

2009

1476

"operator<<").

2010

2011

After creating or appending to the tag file, it is sorted

2012

by the tag name, removing identical tag lines.

2013

</td>

2014

</table>

1477

1478

After creating

1479

or appending to the tag file, it is sorted by the tag name,

1480

removing identical tag lines.

1481

2015

1482

2016

1483

<h2>TAG FILE FORMAT</h2>

2017

2018

<table width="100%" border=0 rules="none" frame="void"

2019

cols="2" cellspacing="0" cellpadding="0">

2020

2021

2022

2023

When not running in etags mode, each entry in the tag

2024

file consists of a separate line, each looking like this in

2025

the most general case:

2026

</td>

2027

</table>

2028

2029

<table width="100%" border=0 rules="none" frame="void"

2030

cols="2" cellspacing="0" cellpadding="0">

2031

2032

2033

2034

2035

tag_name<TAB>file_name<TAB>ex_cmd;"<TAB>extension_fields</td>

2036

</table>

2037

2038

<table width="100%" border=0 rules="none" frame="void"

2039

cols="2" cellspacing="0" cellpadding="0">

2040

2041

2042

2043

The fields and separators of these lines are specified as

2044

follows:

2045

</td>

2046

</table>

2047

2048

<table width="100%" border=0 rules="none" frame="void"

2049

cols="4" cellspacing="0" cellpadding="0">

2050

2051

2052

2053

2054

1.

2055

</td>

2056

2057

2058

2059

tag name

2060

</td>

2061

2062

2063

2064

2065

2.

2066

</td>

2067

2068

2069

2070

single tab character

2071

</td>

2072

2073

2074

2075

2076

3.

2077

</td>

2078

2079

2080

2081

name of the file in which the object associated with the

2082

tag is located

2083

</td>

2084

2085

2086

2087

2088

4.

2089

</td>

2090

2091

2092

2093

single tab character

2094

</td>

2095

2096

2097

2098

2099

5.

2100

</td>

2101

2102

2103

2104

EX command used to locate the tag within the file;

2105

generally a search pattern (either /pattern/ or ?pattern?)

2106

or line number (see −−excmd). Tag file

2107

format 2 (see −−format) extends this EX

2108

command under certain circumstances to include a set of

2109

extension fields (described below) embedded in an EX comment

2110

immediately appended to the EX command, which leaves it

2111

backward-compatible with original vi(1)

2112

implementations.

2113

</td>

2114

</table>

2115

2116

<table width="100%" border=0 rules="none" frame="void"

2117

cols="2" cellspacing="0" cellpadding="0">

2118

2119

2120

2121

A few special tags are written into the tag file for

2122

internal purposes. These tags are composed in such a way

2123

that they always sort to the top of the file. Therefore, the

2124

first two characters of these tags are used a magic number

2125

to detect a tag file for purposes of determining whether a

2126

valid tag file is being overwritten rather than a source

2127

file.

2128

2129

Note that the name of each source file will be recorded

2130

in the tag file exactly as it appears on the command line.

2131

Therefore, if the path you specified on the command line was

2132

relative to the current directory, then it will be recorded

2133

in that same manner in the tag file. See, however, the

1484

1485

1486

When not

1487

running in etags mode, each entry in the tag file consists

1488

of a separate line, each looking like this in the most

1489

general case:

1490

1491

1492

tag_name<TAB>file_name<TAB>ex_cmd;"<TAB>extension_fields

1493

1494

The fields and

1495

separators of these lines are specified as follows:

1496

1497

<table width="100%" border=0 rules="none" frame="void"

1498

cellspacing="0" cellpadding="0">

1499

1500

1501

1502

1503

1504

1.</td>

1505

1506

1507

1508

1509

tag name</td>

1510

1511

1512

1513

1514

1515

2.</td>

1516

1517

1518

1519

1520

single tab character</td>

1521

1522

1523

1524

1525

1526

3.</td>

1527

1528

1529

1530

1531

name of the file in which the object

1532

associated with the tag is located</td>

1533

1534

1535

1536

1537

1538

4.</td>

1539

1540

1541

1542

1543

single tab character</td>

1544

1545

1546

1547

1548

1549

5.</td>

1550

1551

1552

1553

1554

EX command used to locate the tag within

1555

the file; generally a search pattern (either /pattern/ or

1556

?pattern?) or line number (see −−excmd).

1557

Tag file format 2 (see −−format) extends

1558

this EX command under certain circumstances to include a set

1559

of extension fields (described below) embedded in an EX

1560

comment immediately appended to the EX command, which leaves

1561

it backward-compatible with original vi(1)

1562

implementations. </td>

1563

</table>

1564

1565

A few special

1566

tags are written into the tag file for internal purposes.

1567

These tags are composed in such a way that they always sort

1568

to the top of the file. Therefore, the first two characters

1569

of these tags are used a magic number to detect a tag file

1570

for purposes of determining whether a valid tag file is

1571

being overwritten rather than a source file.

1572

1573

Note that the

1574

name of each source file will be recorded in the tag file

1575

exactly as it appears on the command line. Therefore, if the

1576

path you specified on the command line was relative to the

1577

current directory, then it will be recorded in that same

1578

manner in the tag file. See, however, the

2134

1579

−−tag−relative option for how this

2135

1580

behavior can be modified.

2136

2137

Extension fields are tab-separated key-value pairs

2138

appended to the end of the EX command as a comment, as

2139

described above. These key value pairs appear in the general

2140

form "key:value". Their presence in

2141

the lines of the tag file are controlled by the

1581

1582

Extension

1583

fields are tab-separated key-value pairs appended to the end

1584

of the EX command as a comment, as described above. These

1585

key value pairs appear in the general form

1586

"key:value". Their presence in the

1587

lines of the tag file are controlled by the

2142

1588

−−fields option. The possible keys and

2143

1589

the meaning of their values are as follows:

2144

</td>

2145

</table>

2146

1590

2147

1591

<table width="100%" border=0 rules="none" frame="void"

2148

cols="4" cellspacing="0" cellpadding="0">

2149

2150

2151

2152

2153

access

2154

</td>

2155

2156

2157

2158

Indicates the visibility of this class member, where

2159

value is specific to the language.

2160

</td>

2161

2162

2163

2164

2165

file

2166

</td>

2167

2168

1592

cellspacing="0" cellpadding="0">

1593

1594

1595

1596

1597

1598

access</td>

1599

1600

1601

1602

1603

Indicates the

1604

visibility of this class member, where value is

1605

specific to the language.</td>

1606

1607

1608

1609

1610

1611

file</td>

1612

1613

1614

2169

1615

2170

1616

Indicates that the tag has file-limited visibility. This

2171

key has no corresponding value.

2172

</td>

1617

key has no corresponding value.</td>

2173

1618

2174

1619

2175

1620

2176

1621

2177

kind

2178

</td>

1622

1623

kind</td>

2179

1624

2180

1625

2181

1626

1627

2182

1628

Indicates the type, or kind, of tag. Its value is either

2183

1629

one of the corresponding one-letter flags described under

2184

1630

the various −−<LANG>−kinds

2185

1631

options above, or a full name. It is permitted (and is, in

2186

1632

fact, the default) for the key portion of this field to be

2187

1633

omitted. The optional behaviors are controlled with the

2188

−−fields option.

2189

</td>

2190

</table>

2191

2192

<table width="100%" border=0 rules="none" frame="void"

2193

cols="2" cellspacing="0" cellpadding="0">

2194

2195

2196

2197

implementation</td>

2198

</table>

2199

2200

<table width="100%" border=0 rules="none" frame="void"

2201

cols="2" cellspacing="0" cellpadding="0">

2202

2203

2204

2205

When present, this indicates a limited implementation

2206

(abstract vs. concrete) of a routine or class, where

2207

value is specific to the language

1634

−−fields option.</td>

1635

</table>

1636

1637

implementation

1638

1639

When present, this indicates a

1640

limited implementation (abstract vs. concrete) of a routine

1641

or class, where value is specific to the language

2208

1642

("virtual" or "pure virtual" for C++;

2209

1643

"abstract" for Java).

2210

</td>

2211

</table>

2212

1644

2213

1645

<table width="100%" border=0 rules="none" frame="void"

2214

cols="4" cellspacing="0" cellpadding="0">

2215

2216

2217

2218

2219

inherits

2220

</td>

2221

2222

2223

2224

When present, value. is a comma-separated list of

2225

classes from which this class is derived (i.e. inherits

2226

from).

2227

</td>

2228

2229

2230

2231

2232

signature

2233

</td>

2234

2235

1646

cellspacing="0" cellpadding="0">

1647

1648

1649

1650

1651

1652

1653

inherits </td>

1654

1655

1656

1657

1658

When present,

1659

value. is a comma-separated list of classes from

1660

which this class is derived (i.e. inherits from).</td>

1661

1662

1663

1664

1665

1666

signature</td>

1667

1668

1669

2236

1670

2237

1671

When present, value is a language-dependent

2238

1672

representation of the signature of a routine. A routine

2239

1673

signature in its complete form specifies the return type of

2240

1674

a routine and its formal argument list. This extension field

2241

1675

is presently supported only for C-based languages and does

2242

not include the return type.

2243

</td>

2244

</table>

2245

2246

<table width="100%" border=0 rules="none" frame="void"

2247

cols="2" cellspacing="0" cellpadding="0">

2248

2249

2250

2251

In addition, information on the scope of the tag

2252

definition may be available, with the key portion equal to

2253

some language-dependent construct name and its value the

2254

name declared for that construct in the program. This scope

2255

entry indicates the scope in which the tag was found. For

2256

example, a tag generated for a C structure member would have

2257

a scope looking like "struct:myStruct".

2258

</td>

2259

</table>

1676

not include the return type.</td>

1677

</table>

1678

1679

In addition,

1680

information on the scope of the tag definition may be

1681

available, with the key portion equal to some

1682

language-dependent construct name and its value the name

1683

declared for that construct in the program. This scope entry

1684

indicates the scope in which the tag was found. For example,

1685

a tag generated for a C structure member would have a scope

1686

looking like "struct:myStruct".

1687

2260

1688

2261

1689

2262

2263

<table width="100%" border=0 rules="none" frame="void"

2264

cols="2" cellspacing="0" cellpadding="0">

2265

2266

2267

2268

Vi will, by default, expect a tag file by the name

2269

"tags" in the current directory. Once the tag file

2270

is built, the following commands exercise the tag indexing

2271

feature:

2272

</td>

2273

</table>

2274

2275

<table width="100%" border=0 rules="none" frame="void"

2276

cols="4" cellspacing="0" cellpadding="0">

2277

2278

2279

2280

2281

vi −t tag

2282

</td>

2283

2284

2285

2286

Start vi and position the cursor at the file and line

2287

where "tag" is defined.

2288

</td>

2289

2290

2291

2292

2293

:ta tag

2294

</td>

2295

2296

2297

2298

Find a tag.

2299

</td>

2300

2301

2302

2303

2304

Ctrl-]

2305

</td>

2306

2307

2308

2309

Find the tag under the cursor.

2310

</td>

2311

2312

2313

2314

2315

Ctrl-T

2316

</td>

2317

2318

2319

2320

Return to previous location before jump to tag (not

2321

widely implemented).

2322

</td>

2323

</table>

1690

1691

1692

Vi will, by

1693

default, expect a tag file by the name "tags" in

1694

the current directory. Once the tag file is built, the

1695

following commands exercise the tag indexing feature:

1696

1697

<table width="100%" border=0 rules="none" frame="void"

1698

cellspacing="0" cellpadding="0">

1699

1700

1701

1702

1703

1704

vi −t

1705

tag </td>

1706

1707

1708

1709

1710

Start vi and

1711

position the cursor at the file and line where

1712

"tag" is defined.</td>

1713

1714

1715

1716

1717

1718

:ta tag</td>

1719

1720

1721

1722

1723

Find a tag.</td>

1724

1725

1726

1727

1728

1729

Ctrl-]</td>

1730

1731

1732

1733

1734

Find the tag under

1735

the cursor.</td>

1736

1737

1738

1739

1740

1741

Ctrl-T</td>

1742

1743

1744

1745

1746

Return to previous

1747

location before jump to tag (not widely implemented).</td>

1748

</table>

1749

2324

1750

2325

1751

<h2>HOW TO USE WITH GNU EMACS</h2>

2326

2327

<table width="100%" border=0 rules="none" frame="void"

2328

cols="2" cellspacing="0" cellpadding="0">

2329

2330

2331

2332

Emacs will, by default, expect a tag file by the name

2333

"TAGS" in the current directory. Once the tag file

2334

is built, the following commands exercise the tag indexing

2335

feature:

2336

</td>

2337

</table>

2338

2339

<table width="100%" border=0 rules="none" frame="void"

2340

cols="2" cellspacing="0" cellpadding="0">

2341

2342

2343

2344

M-x visit−tags−table <RET> FILE

2345

2346

</table>

2347

2348

<table width="100%" border=0 rules="none" frame="void"

2349

cols="2" cellspacing="0" cellpadding="0">

2350

2351

2352

2353

Select the tag file, "FILE", to use.

2354

</td>

2355

</table>

2356

2357

<table width="100%" border=0 rules="none" frame="void"

2358

cols="2" cellspacing="0" cellpadding="0">

2359

2360

2361

2362

M-. [TAG] <RET></td>

2363

</table>

2364

2365

<table width="100%" border=0 rules="none" frame="void"

2366

cols="2" cellspacing="0" cellpadding="0">

2367

2368

2369

2370

Find the first definition of TAG. The default tag is the

2371

identifier under the cursor.

2372

</td>

2373

</table>

2374

2375

<table width="100%" border=0 rules="none" frame="void"

2376

cols="5" cellspacing="0" cellpadding="0">

2377

2378

2379

2380

2381

M-*

2382

</td>

2383

2384

2385

2386

Pop back to where you previously invoked

2387

"M-.".

2388

</td>

2389

2390

</td>

2391

2392

2393

2394

2395

C-u M-.

2396

</td>

2397

2398

2399

2400

Find the next definition for the last tag.

2401

</td>

2402

2403

</td>

2404

</table>

2405

2406

<table width="100%" border=0 rules="none" frame="void"

2407

cols="2" cellspacing="0" cellpadding="0">

2408

2409

2410

2411

For more commands, see the Tags topic in the Emacs

2412

info document.

2413

</td>

2414

</table>

1752

1753

1754

Emacs will, by

1755

default, expect a tag file by the name "TAGS" in

1756

the current directory. Once the tag file is built, the

1757

following commands exercise the tag indexing feature:

1758

1759

M-x visit−tags−table <RET> FILE

1760

<RET>

1761

1762

Select the tag file,

1763

"FILE", to use.

1764

1765

M-. [TAG]

1766

<RET>

1767

1768

Find the first definition of

1769

TAG. The default tag is the identifier under the cursor.

1770

1771

<table width="100%" border=0 rules="none" frame="void"

1772

cellspacing="0" cellpadding="0">

1773

1774

1775

1776

1777

1778

M-*</td>

1779

1780

1781

1782

1783

Pop back to where

1784

you previously invoked "M-.".</td>

1785

1786

</td>

1787

1788

1789

1790

1791

1792

C-u M-.</td>

1793

1794

1795

1796

1797

Find the next

1798

definition for the last tag.</td>

1799

1800

</td>

1801

</table>

1802

1803

For more

1804

commands, see the Tags topic in the Emacs info

1805

document.

1806

2415

1807

2416

1808

<h2>HOW TO USE WITH NEDIT</h2>

2417

2418

<table width="100%" border=0 rules="none" frame="void"

2419

cols="2" cellspacing="0" cellpadding="0">

2420

2421

2422

2423

NEdit version 5.1 and later can handle the new extended

2424

tag file format (see −−format). To make

2425

NEdit use the tag file, select "File−>Load

2426

Tags File". To jump to the definition for a tag,

2427

highlight the word, the press Ctrl-D. NEdit 5.1 can can read

2428

multiple tag files from different directories. Setting the X

2429

resource nedit.tagFile to the name of a tag file instructs

2430

NEdit to automatically load that tag file at startup

2431

time.

2432

</td>

2433

</table>

1809

1810

1811

NEdit version

1812

5.1 and later can handle the new extended tag file format

1813

(see −−format). To make NEdit use the tag

1814

file, select "File−>Load Tags File". To

1815

jump to the definition for a tag, highlight the word, the

1816

press Ctrl-D. NEdit 5.1 can can read multiple tag files from

1817

different directories. Setting the X resource nedit.tagFile

1818

to the name of a tag file instructs NEdit to automatically

1819

load that tag file at startup time.

1820

2434

1821

2435

1822

<h2>CAVEATS</h2>

2436

2437

<table width="100%" border=0 rules="none" frame="void"

2438

cols="2" cellspacing="0" cellpadding="0">

2439

2440

2441

2442

Because ctags is neither a preprocessor nor a

2443

compiler, use of preprocessor macros can fool ctags

2444

into either missing tags or improperly generating

2445

inappropriate tags. Although ctags has been designed

2446

to handle certain common cases, this is the single biggest

2447

cause of reported problems. In particular, the use of

2448

preprocessor constructs which alter the textual syntax of C

2449

can fool ctags. You can work around many such

2450

problems by using the −I option.

2451

2452

Note that since ctags generates patterns for

2453

locating tags (see the −−excmd option),

2454

it is entirely possible that the wrong line may be found by

2455

your editor if there exists another source line which is

2456

identical to the line containing the tag. The following

2457

example demonstrates this condition:

2458

</td>

2459

</table>

2460

2461

<table width="100%" border=0 rules="none" frame="void"

2462

cols="2" cellspacing="0" cellpadding="0">

2463

2464

2465

2466

int variable;

2467

2468

/* ... */

2469

void foo(variable)

2470

int variable;

2471

{</td>

2472

</table>

2473

2474

<table width="100%" border=0 rules="none" frame="void"

2475

cols="2" cellspacing="0" cellpadding="0">

2476

2477

2478

2479

/* ... */</td>

2480

</table>

2481

2482

<table width="100%" border=0 rules="none" frame="void"

2483

cols="2" cellspacing="0" cellpadding="0">

2484

2485

2486

2487

}</td>

2488

</table>

2489

2490

<table width="100%" border=0 rules="none" frame="void"

2491

cols="2" cellspacing="0" cellpadding="0">

2492

2493

2494

2495

Depending upon which editor you use and where in the code

2496

you happen to be, it is possible that the search pattern may

2497

locate the local parameter declaration in foo() before it

2498

finds the actual global variable definition, since the lines

2499

(and therefore their search patterns are identical). This

2500

can be avoided by use of the

2501

−−excmd=n option.

2502

</td>

2503

</table>

1823

1824

1825

Because

1826

ctags is neither a preprocessor nor a compiler, use

1827

of preprocessor macros can fool ctags into either

1828

missing tags or improperly generating inappropriate tags.

1829

Although ctags has been designed to handle certain

1830

common cases, this is the single biggest cause of reported

1831

problems. In particular, the use of preprocessor constructs

1832

which alter the textual syntax of C can fool ctags.

1833

You can work around many such problems by using the

1834

−I option.

1835

1836

Note that since

1837

ctags generates patterns for locating tags (see the

1838

−−excmd option), it is entirely possible

1839

that the wrong line may be found by your editor if there

1840

exists another source line which is identical to the line

1841

containing the tag. The following example demonstrates this

1842

condition:

1843

1844

int

1845

variable;

1846

1847

/* ... */

1848

void foo(variable)

1849

int variable;

1850

{

1851

1852

/* ... */

1853

1854

}

1855

1856

Depending upon

1857

which editor you use and where in the code you happen to be,

1858

it is possible that the search pattern may locate the local

1859

parameter declaration in foo() before it finds the actual

1860

global variable definition, since the lines (and therefore

1861

their search patterns are identical). This can be avoided by

1862

use of the −−excmd=n option.

1863

2504

1864

2505

1865

2506

2507

<table width="100%" border=0 rules="none" frame="void"

2508

cols="2" cellspacing="0" cellpadding="0">

2509

2510

2511

2512

Ctags has more options than ls(1).

2513

2514

When parsing a C++ member function definition (e.g.

1866

1867

1868

Ctags

1869

has more options than ls(1).

1870

1871

When parsing a

1872

C++ member function definition (e.g.

2515

1873

"className::function"), ctags cannot

2516

1874

determine whether the scope specifier is a class name or a

2517

1875

namespace specifier and always lists it as a class name in

2523

1881

are not known when the tag is generated for the function

2524

1882

definition. It will, however be available for prototypes

2525

1883

(e.g −−c++−kinds=+p).

2526

2527

No qualified tags are generated for language objects

2528

inherited into a class.

2529

</td>

2530

</table>

1884

1885

No qualified

1886

tags are generated for language objects inherited into a

1887

class.

1888

2531

1889

2532

1890

<h2>ENVIRONMENT VARIABLES</h2>

2533

1891

1892

2534

1893

<table width="100%" border=0 rules="none" frame="void"

2535

cols="4" cellspacing="0" cellpadding="0">

2536

2537

2538

2539

2540

CTAGS

2541

</td>

2542

2543

2544

2545

If this environment variable exists, it will be expected

2546

to contain a set of default options which are read when

2547

ctags starts, after the configuration files listed in

2548

FILES, below, are read, but before any command line

2549

options are read. Options appearing on the command line will

2550

override options specified in this variable. Only options

2551

will be read from this variable. Note that all white space

2552

in this variable is considered a separator, making it

2553

impossible to pass an option parameter containing an

2554

embedded space. If this is a problem, use a configuration

2555

file instead.

2556

</td>

2557

2558

2559

2560

2561

ETAGS

2562

</td>

2563

2564

1894

cellspacing="0" cellpadding="0">

1895

1896

1897

1898

1899

1900

CTAGS</td>

1901

1902

1903

1904

1905

If this environment

1906

variable exists, it will be expected to contain a set of

1907

default options which are read when ctags starts,

1908

after the configuration files listed in FILES, below,

1909

are read, but before any command line options are read.

1910

Options appearing on the command line will override options

1911

specified in this variable. Only options will be read from

1912

this variable. Note that all white space in this variable is

1913

considered a separator, making it impossible to pass an

1914

option parameter containing an embedded space. If this is a

1915

problem, use a configuration file instead.</td>

1916

1917

1918

1919

1920

1921

ETAGS</td>

1922

1923

1924

2565

1925

2566

1926

Similar to the CTAGS variable above, this

2567

1927

variable, if found, will be read when etags starts.

2568

1928

If this variable is not found, etags will try to use

2569

CTAGS instead.

2570

</td>

1929

CTAGS instead.</td>

2571

1930

2572

1931

2573

1932

2574

1933

2575

TMPDIR

2576

</td>

1934

1935

TMPDIR</td>

2577

1936

2578

1937

2579

1938

1939

2580

1940

On Unix-like hosts where mkstemp() is available, the

2581

1941

value of this variable specifies the directory in which to

2582

1942

place temporary files. This can be useful if the size of a

2590

1950

operating system. If the sort utility of the operating

2591

1951

system is being used, it will generally observe this

2592

1952

variable also. Note that if ctags is setuid, the

2593

value of TMPDIR will be ignored.

2594

</td>

1953

value of TMPDIR will be ignored.</td>

2595

1954

</table>

1955

2596

1956

2597

1957

<h2>FILES</h2>

2598

2599

<table width="100%" border=0 rules="none" frame="void"

2600

cols="2" cellspacing="0" cellpadding="0">

2601

2602

2603

2604

/ctags.cnf (on MSDOS, MSWindows only)

2605

/etc/ctags.conf

2606

/usr/local/etc/ctags.conf

2607

$HOME/.ctags

2608

$HOME/ctags.cnf (on MSDOS, MSWindows only)

2609

.ctags

2610

ctags.cnf (on MSDOS, MSWindows only)</td>

2611

</table>

2612

2613

<table width="100%" border=0 rules="none" frame="void"

2614

cols="2" cellspacing="0" cellpadding="0">

2615

2616

2617

2618

If any of these configuration files exist, each will be

2619

expected to contain a set of default options which are read

2620

in the order listed when ctags starts, but before the

2621

CTAGS environment variable is read or any command

2622

line options are read. This makes it possible to set up

2623

site-wide, personal or project-level defaults. It is

2624

possible to compile ctags to read an additional

2625

configuration file before any of those shown above, which

2626

will be indicated if the output produced by the

2627

−−version option lists the

2628

"custom-conf" feature. Options appearing in the

2629

CTAGS environment variable or on the command line

2630

will override options specified in these files. Only options

2631

will be read from these files. Note that the option files

2632

are read in line-oriented mode in which spaces are

1958

1959

1960

/ctags.cnf

1961

(on MSDOS, MSWindows only)

1962

/etc/ctags.conf

1963

/usr/local/etc/ctags.conf

1964

$HOME/.ctags

1965

$HOME/ctags.cnf (on MSDOS, MSWindows only)

1966

.ctags

1967

ctags.cnf (on MSDOS, MSWindows only)

1968

1969

If any of these configuration

1970

files exist, each will be expected to contain a set of

1971

default options which are read in the order listed when

1972

ctags starts, but before the CTAGS environment

1973

variable is read or any command line options are read. This

1974

makes it possible to set up site-wide, personal or

1975

project-level defaults. It is possible to compile

1976

ctags to read an additional configuration file before

1977

any of those shown above, which will be indicated if the

1978

output produced by the −−version option

1979

lists the "custom-conf" feature. Options appearing

1980

in the CTAGS environment variable or on the command

1981

line will override options specified in these files. Only

1982

options will be read from these files. Note that the option

1983

files are read in line-oriented mode in which spaces are

2633

1984

significant (since shell quoting is not possible). Each line

2634

1985

of the file is read as one command line parameter (as if it

2635

1986

were quoted with single quotes). Therefore, use new lines to

2636

1987

indicate separate command-line arguments.

2637

</td>

2638

</table>

2639

1988

2640

1989

<table width="100%" border=0 rules="none" frame="void"

2641

cols="5" cellspacing="0" cellpadding="0">

1990

cellspacing="0" cellpadding="0">

2642

1991

2643

1992

2644

1993

2645

1994

2646

tags

2647

</td>

1995

1996

tags</td>

2648

1997

2649

1998

2650

1999

2651

The default tag file created by ctags.

2652

</td>

2000

2001

The default tag

2002

file created by ctags.</td>

2653

2003

2654

2004

</td>

2655

2005

2656

2006

2657

2007

2658

2008

2659

TAGS

2660

</td>

2009

2010

TAGS</td>

2661

2011

2662

2012

2663

2013

2664

The default tag file created by etags.

2665

</td>

2014

2015

The default tag

2016

file created by etags.</td>

2666

2017

2667

2018

</td>

2668

2019

</table>

2020

2669

2021

2670

2022

2671

2672

<table width="100%" border=0 rules="none" frame="void"

2673

cols="2" cellspacing="0" cellpadding="0">

2674

2675

2676

2677

The official Exuberant Ctags web site at:

2678

</td>

2679

</table>

2680

2681

<table width="100%" border=0 rules="none" frame="void"

2682

cols="2" cellspacing="0" cellpadding="0">

2683

2684

2685

2686

http://ctags.sourceforge.net</td>

2687

</table>

2688

2689

<table width="100%" border=0 rules="none" frame="void"

2690

cols="2" cellspacing="0" cellpadding="0">

2691

2692

2693

2694

Also ex(1), vi(1), elvis, or, better

2695

yet, vim, the official editor of ctags. For

2696

more information on vim, see the VIM Pages web site

2023

2024

2025

The official

2026

Exuberant Ctags web site at:

2027

2028

2029

http://ctags.sourceforge.net

2030

2031

Also

2032

ex(1), vi(1), elvis, or, better yet,

2033

vim, the official editor of ctags. For more

2034

information on vim, see the VIM Pages web site

2697

2035

at:

2698

</td>

2699

</table>

2700

2701

<table width="100%" border=0 rules="none" frame="void"

2702

cols="2" cellspacing="0" cellpadding="0">

2703

2704

2705

2706

http://www.vim.org/</td>

2707

</table>

2036

2037

2038

http://www.vim.org/

2039

2708

2040

2709

2041

<h2>AUTHOR</h2>

2710

2711

<table width="100%" border=0 rules="none" frame="void"

2712

cols="2" cellspacing="0" cellpadding="0">

2713

2714

2715

2716

Darren Hiebert <dhiebert at

2717

users.sourceforge.net>

2042

2043

2044

Darren Hiebert

2045

2718

2046

http://DarrenHiebert.com/

2719

</td>

2720

</table>

2047

2721

2048

2722

2049

<h2>MOTIVATION</h2>

2723

2724

<table width="100%" border=0 rules="none" frame="void"

2725

cols="2" cellspacing="0" cellpadding="0">

2726

2727

2728

2729

"Think ye at all times of rendering some service to

2730

every member of the human race."

2731

2732

"All effort and exertion put forth by man from the

2733

fullness of his heart is worship, if it is prompted by the

2734

highest motives and the will to do service to

2735

humanity."

2736

</td>

2737

</table>

2738

2739

<table width="100%" border=0 rules="none" frame="void"

2740

cols="2" cellspacing="0" cellpadding="0">

2741

2742

2743

2744

−− From the Baha’i Writings</td>

2745

</table>

2050

2051

2052

"Think ye

2053

at all times of rendering some service to every member of

2054

the human race."

2055

2056

"All

2057

effort and exertion put forth by man from the fullness of

2058

his heart is worship, if it is prompted by the highest

2059

motives and the will to do service to humanity."

2060

2061

−−

2062

From the Baha’i Writings

2063

2746

2064

2747

2065

<h2>CREDITS</h2>

2748

2749

<table width="100%" border=0 rules="none" frame="void"

2750

cols="2" cellspacing="0" cellpadding="0">

2751

2752

2753

2754

This version of ctags was originally derived from

2755

and inspired by the ctags program by Steve Kirkendall

2066

2067

2068

This version of

2069

ctags was originally derived from and inspired by the

2070

ctags program by Steve Kirkendall

2756

2071

<kirkenda@cs.pdx.edu> that comes with the Elvis vi

2757

2072

clone (though virtually none of the original code

2758

2073

remains).

2759

2760

Credit is also due Bram Moolenaar <Bram@vim.org>,

2761

the author of vim, who has devoted so much of his

2762

time and energy both to developing the editor as a service

2763

to others, and to helping the orphans of Uganda.

2764

2765

The section entitled "HOW TO USE WITH GNU

2766

EMACS" was shamelessly stolen from the info page for

2767

GNU etags.

2768

</td>

2769

</table>

2074

2075

Credit is also

2076

due Bram Moolenaar <Bram@vim.org>, the author of

2077

vim, who has devoted so much of his time and energy

2078

both to developing the editor as a service to others, and to

2079

helping the orphans of Uganda.

2080

2081

The section

2082

entitled "HOW TO USE WITH GNU EMACS" was

2083

shamelessly stolen from the info page for GNU

2084

etags.

2770

2085

<hr>

2771

2086

</body>

2772

2087

</html>

Older »