~ubuntu-branches/ubuntu/trusty/argtable2/trusty

Argtable is an ANSI C library for parsing GNU style command line arguments with a minimum of fuss. It enables the programmer to define their program's argument syntax directly in the source code as an array of structs. The command line is then parsed according to that specification and the resulting values stored directly into user-defined program variables where they are accessible to the main program.

.PP

This man page is only for reference. Introductory and advanced texts on argtable should be

available on this system in pdf, html, and postscript from under \fB<install-dir>/share/doc/argtable2/\fP along with example source code.

Alternatively refer to the argtable homepage at http://argtable.sourceforge.net.

.SS Constructing an arg_xxx data structure

Each \fBarg_xxx\fP struct has it own unique set of constructor functions

and while these may differ slightly between \fBarg_xxx\fP structs,

they are generally of the form:

.PP

struct \fBarg_xxx* arg_xxx0\fP (const char *shortopts, const char *longopts, const char *datatype, const char *glossary)

.PP

struct \fBarg_xxx* arg_xxx1\fP (const char *shortopts, const char *longopts, const char *datatype, const char *glossary)

.PP

struct \fBarg_xxx* arg_xxxn\fP (const char *shortopts, const char *longopts, const char *datatype, int mincount, int maxcount, const char *glossary)

.PP

The \fBarg_xxx0()\fP and \fBarg_xxx1()\fP forms are merely abbreviated

forms of \fBarg_xxxn()\fP and are provided as a convenience for

the most common arrangements of command line options; namely those

that have zero-or-one occurrences (mincount=0,maxcount=1) and those

that have one exactly one occurrence (mincount=1,maxcount=1) respectively.

.PP

The \fIconst char* shortopts\fP parameter defines the option's short

form tag (eg: -x, -k3, -D"macro").

It can be left as NULL if a short option is not required, otherwise use it to

specify the desired short option character in the string (without the

leading "-" and without any whitespace).

For example, the short option -v is defined simply as "v".

In fact, a command line option may have multiple alternate short form

tags defined for it by concatenating the desired characters into the

shortopts string.

For instance "abc" defines an option which will accept any of the three

equivalent short forms -a, -b, -c interchangeably.

.PP

The \fIconst char* longopts\fP parameter is similar to \fIshortopts\fP,

except it defines the option's long form tags (eg: --help, --depth=3, --name=myfile.txt).

It too can be left as NULL if not required, and it too can have multiple

equivalent tags defined but these must be separated by commas.

For example, if we wish to define two equivalent long options --quiet and

--silent then we would give longopts as "quiet,silent". Remember not to

include any whitespace.

.PP

If both \fIshortopts\fP and \fIlongopts\fP are given as NULL then the

resulting option is an untagged argument.

.PP

The \fIconst char* datatype\fP parameter is a descriptive string you

can use to customize the appearance of the argument data type in error

messages and so forth. It does not affect the actual data type definition

as that is a fixed property of the \fBarg_xxx\fP struct.

So for example, defining a \fIdatatype\fP of "<bar>" will result in the option

being display something like "-x <bar>" or "--foo=<bar>" depending upon

your option tags.

If given as NULL, the \fIdatatype\fP string will revert to the default

value for the particular \fBarg_xxx\fP struct.

You can effectively disable the default by specifying \fIdatatype\fP

as an empty string.

.PP

The \fIint mincount\fP parameter specifies the minimum number of occurrences

that the option must appear on the command line.

If the option does not appear at least that many times then the parser

reports it as a syntax error.

The \fImincount\fP defaults to 0 for the \fBarg_xxx0()\fP functions and

1 for \fBarg_xxx1()\fP functions.

.PP

The \fIint maxcount\fP parameter specifies the maximum number of occurrences

that the option may appear on the command line.

Any occurrences beyond the maximum are discarded by the parser

reported as syntax errors.

100

The \fImaxcount\fP defaults to 1 for both the \fBarg_xxx0()\fP and \fBarg_xxx1()\fP functions.

101

.PP

102

The \fIconst char* glossary\fP parameter is another descriptive string

103

but this one appears in the glossary table summarizing the program's

104

command line options.

105

The glossary table is generated automatically by the \fBarg_print_glossary\fP

106

function (see later). For example, a glossary string of "the foobar factor"

107

would appear in the glossary table along side the option something like:

108

.IP

109

\fC--foo=<bar> the foobar factor\fP

110

.PP

111

Specifying a NULL glossary string causes that option to be omitted from

112

the glossary table.

113

.PP

114

See below for the exact definitions of the individual \fBarg_xxx\fP

115

structs and their constructor functions.

116

.fi

117

118

.SH FUNCTION REFERENCE

119

.in +1c

120

.SS "int arg_nullcheck (void **argtable)"

121

Returns non-zero if the \fIargtable[]\fP array contains any NULL entries

122

up until the terminating \fBarg_end*\fP entry.

123

Returns zero otherwise.

124

.SS "int arg_parse (int argc, char **argv, void **argtable)"

125

Parse the command line arguments in \fIargv[]\fP using the command line syntax

126

specified in \fIargtable[]\fP, returning the number of errors encountered.

127

Error details are recorded in the argument table's

128

\fBarg_end\fP structure from where they can be displayed later with

129

the \fBarg_print_errors\fP function.

130

Upon a successful parse, the \fBarg_xxx\fP structures referenced in \fIargtable[]\fP

131

will contain the argument values extracted from the command line.

132

.SS "void arg_print_option (FILE *fp, const char *shortopts, const char *longopts, const char *datatype, const char *suffix)"

133

This function prints an option's syntax, as in \fB-K|--scalar=<int>\fP,

134

where the short options, long options, and datatype are all given

135

as parameters of this function.

136

It is primarily used within the \fBarg_xxx\fP structures' \fIerrorfn\fP

137

functions as a way of displaying an option's syntax inside of error

138

messages. However, it can also be used in user code if desired.

139

The \fIsuffix\fP string is provided as a convenience for appending newlines

140

and so forth to the end of the display and can be given as NULL if not required.

141

.SS "void arg_print_syntax (FILE *fp, void **argtable, const char *suffix)"

142

Prints the GNU style command line syntax for the given argument table,

143

as in: [-abcv] [--scalar=<n>] [-o myfile] <file> [<file>]

144

.br

145

The \fIsuffix\fP string is provided as a convenience for appending newlines

146

and so forth to the end of the display and can be given as NULL if not required.

147

.SS "void arg_print_syntaxv (FILE *fp, void **argtable, const char *suffix)"

148

Prints the verbose form of the command line syntax for the given argument table,

149

as in: [-a] [-b] [-c] [--scalar=<n>] [-o myfile] [-v|--verbose] <file> [<file>]

150

.br

151

The \fIsuffix\fP string is provided as a convenience for appending newlines

152

and so forth to the end of the display and can be given as NULL if not required.

153

.SS "void arg_print_glossary (FILE *fp, void **argtable, const char *format)"

154

Prints a glossary table describing each option in the given argument table.

155

The \fIformat\fP string is passed to printf to control the formatting of

156

each entry in the the glossary.

157

It must have exactly two "%s" format parameters as in "%-25s %s\\n",

158

the first is for the option's syntax and the second for its glossary string.

159

If an option's glossary string is NULL then that option in omitted from

160

the glossary display.

161

.SS "void arg_print_errors (FILE *fp, struct \fBarg_end\fP *end, const char *progname)"

162

Prints the details of all errors stored in the \fIend\fP data structure.

163

The \fIprogname\fP string is prepended to each error message.

164

.SS "void arg_freetable (void ** argtable, size_t n)"

165

Deallocates the memory used by each \fBarg_xxx\fP struct referenced by \fIargtable[]\fP.

166

It does this by calling \fBfree\fP for each of the \fIn\fP pointers in the argtable array

167

and then nulling them for safety.

168

169

.SH "LITERAL OPTIONS (struct arg_lit)"

170

.SS Command line examples

171

-x, -y, -z, --help, --verbose

172

.SS Data Structure

173

.nf

174

struct \fBarg_lit\fP

175

{

176

struct \fBarg_hdr\fP hdr;

177

int count;

178

};

179

.fi

180

.SS Constructor Functions

181

.PP

182

.HP

183

struct \fBarg_lit* arg_lit0\fP (const char *shortopts, const char *longopts, const char *glossary)

184

.HP

185

struct \fBarg_lit* arg_lit1\fP (const char *shortopts, const char *longopts, const char *glossary)

186

.HP

187

struct \fBarg_lit* arg_litn\fP (const char *shortopts, const char *longopts, int mincount, int maxcount, const char *glossary)

188

.SS Description

189

Literal options take no argument values so all that is to be seen in the

190

\fBarg_lit\fP struct is the \fIcount\fP of the number of times the option was

191

present on the command line.

192

Upon a successful parse, \fIcount\fP is guaranteed to be within

193

the \fImincount\fP and \fImaxcount\fP limits set for the option at construction.

194

195

.SH "INTEGER OPTIONS (struct arg_int)"

196

.SS Command line examples

197

-x2, -y 7, -z-3, --size=734, --count 124

198

.SS Data Structure

199

.nf

200

struct \fBarg_int\fP

201

{

202

struct \fBarg_hdr\fP hdr;

203

int count;

204

int *ival;

205

};

206

.fi

207

.SS Constructor Functions

208

.PP

209

.HP

210

struct \fBarg_int* arg_int0\fP (const char *shortopts, const char *longopts, const char *datatype, const char *glossary)

211

.HP

212

struct \fBarg_int* arg_int1\fP (const char *shortopts, const char *longopts, const char *datatype, const char *glossary)

213

.HP

214

struct \fBarg_int* arg_intn\fP (const char *shortopts, const char *longopts, const char *datatype, int mincount, int maxcount, const char *glossary

215

.SS Description

216

The \fBarg_int\fP struct contains the \fIcount\fP of the number of times

217

the option was present on the command line and a pointer (\fIival\fP) to

218

an array containing the integer values given with those particular options.

219

The array is fixed at construction time to hold \fImaxcount\fP integers at most.

220

.PP

221

Upon a successful parse, \fIcount\fP is guaranteed to be within

222

the \fImincount\fP and \fImaxcount\fP limits set for the option at construction

223

with the appropriate values store in the \fIival\fP array.

224

The parser will not accept any values beyond that limit.

225

.PP

226

It is quite acceptable to set default values in the \fIival\fP array prior

227

to calling arg_parse if desired as the parser does alter \fIival\fP entries

228

for which no command line argument is received.

229

230

.SH "DOUBLE OPTIONS (struct arg_dbl)"

231

.SS Command line examples

232

-x2.234, -y 7e-03, -z-3.3E+6, --pi=3.1415, --tolerance 1.0E-6

233

.SS Data Structure

234

.nf

235

struct \fBarg_dbl\fP

236

{

237

struct \fBarg_hdr\fP hdr;

238

int count;

239

double *dval;

240

};

241

.fi

242

.SS Constructor Functions

243

.PP

244

.HP

245

struct \fBarg_dbl* arg_dbl0\fP (const char *shortopts, const char *longopts, const char *datatype, const char *glossary)

246

.HP

247

struct \fBarg_dbl* arg_dbl1\fP (const char *shortopts, const char *longopts, const char *datatype, const char *glossary)

248

.HP

249

struct \fBarg_dbl* arg_dbln\fP (const char *shortopts, const char *longopts, const char *datatype, int mincount, int maxcount, const char *glossary

250

.SS Description

251

Like \fBarg_int\fP but the arguments values are stored as doubles in \fIdval\fP.

252

253

.SH "STRING OPTIONS (struct arg_str)"

254

.SS Command line examples

255

-Dmacro, -t mytitle, -m "my message string", --title="hello world"

256

.SS Data Structure

257

.nf

258

struct \fBarg_str\fP

259

{

260

struct \fBarg_hdr\fP hdr;

261

int count;

262

const char **sval;

263

};

264

.fi

265

.SS Constructor Functions

266

.PP

267

.HP

268

struct \fBarg_str* arg_str0\fP (const char *shortopts, const char *longopts, const char *datatype, const char *glossary)

269

.HP

270

struct \fBarg_str* arg_str1\fP (const char *shortopts, const char *longopts, const char *datatype, const char *glossary)

271

.HP

272

struct \fBarg_str* arg_strn\fP (const char *shortopts, const char *longopts, const char *datatype, int mincount, int maxcount, const char *glossary)

273

.SS Description

274

The \fBarg_str\fP struct contains the \fIcount\fP of the number of times

275

the option was present on the command line and a pointer (\fIsval\fP) to

276

an array containing pointers to the parsed string values.

277

The array is fixed at construction time to hold \fImaxcount\fP string pointers at most.

278

These pointers in this array reference the actual command line string buffers stored in argv[],

279

so the string contents should not be should not be altered.

280

Although it is quite acceptable to set default string pointers in the \fIsval\fP array prior

281

to calling arg_parse as the parser does alter them if no matching command line argument is received.

282

283

.SH "REGULAR EXPRESSION OPTIONS (struct arg_rex)"

284

.SS Command line examples

285

"hello world", -t mytitle, -m "my message string", --title="hello world"

286

.SS Data Structure

287

.nf

288

struct \fBarg_rex\fP

289

{

290

struct \fBarg_hdr\fP hdr;

291

int count;

292

const char **sval;

293

};

294

.fi

295

.SS Constructor Functions

296

.PP

297

.HP

298

struct \fBarg_rex* arg_rex0\fP (const char *shortopts, const char *longopts, const char *pattern, const char *datatype, int flags, const char *glossary)

299

.HP

300

struct \fBarg_rex* arg_rex1\fP (const char *shortopts, const char *longopts, const char *pattern, const char *datatype, int flags, const char *glossary)

301

.HP

302

struct \fBarg_rex* arg_rexn\fP (const char *shortopts, const char *longopts, const char *pattern, const char *datatype, int mincount, int maxcount, int flags, const char *glossary)

303

.SS Description

304

Like \fBarg_str\fP but but the string argument values are only accepted if they match a predefined regular expression.

305

The regular expression is defined by the \fIpattern\fP parameter passed to the \fIarg_rex\fP constructor.

306

The regular expression parsing is done using regex, and its behaviour can be controlled via standard regex bit flags

307

which are passed to argtable via the \fIflags\fP parameter in the \fIarg_rex\fP conbstructors. However the only two regex

308

flags that are relevant to argtable are REG_EXTENDED (use extended regular expressions rather than basic ones)

309

and REG_ICASE (ignore case). These may be logically ORed if desired.

310

This argument type is useful for matching command line keywords, particularly if case insensitive strings or pattern matching is required. See \fBregex(3)\fP for more details of regular expression matching.

311

.SS Restrictions

312

Argtable does not support \fBarg_date\fP functionality under Microsoft Windows platforms as the

313

Microsoft compilers do include the necessary \fBregex\fP support as standard.

314

315

.SH "FILENAME OPTIONS (struct arg_file)"

316

.SS Command line xamples

317

-o myfile, -Ihome/foo/bar, --input=~/doc/letter.txt, --name a.out

318

.SS Data Structure

319

.nf

320

struct \fBarg_file\fP

321

{

322

struct \fBarg_hdr\fP hdr;

323

int count;

324

const char **filename;

325

const char **basename;

326

const char **extension;

327

};

328

.fi

329

.SS Constructor Functions

330

.PP

331

.HP

332

struct \fBarg_file* arg_file0\fP (const char *shortopts, const char *longopts, const char *datatype, const char *glossary)

333

.HP

334

struct \fBarg_file* arg_file1\fP (const char *shortopts, const char *longopts, const char *datatype, const char *glossary)

335

.HP

336

struct \fBarg_file* arg_filen\fP (const char *shortopts, const char *longopts, const char *datatype, int mincount, int maxcount, const char *glossary)

337

.SS Description

338

Like \fBarg_str\fP but the argument strings are presumed to

339

have filename qualities so some additional pasring is done to

340

separate out the filename's basename and extension (if they exist).

341

The three arrays filename[], basename[], extension[] each store up

342

to maxcount entries, and the i'th entry of each of these arrays

343

refer to different components of the same string buffer.

344

.PP

345

For instance, \fB-o /home/heitmann/mydir/foo.txt\fP would be parsed as:

346

.in +1c

347

.nf

348

filename[i] = "/home/heitmann/mydir/foo.txt"

349

basename[i] = "foo.txt"

350

extension[i] = "txt"

351

.fi

352

.out -1c

353

.PP

354

If the filename has no leading path then the

355

basename is the same as the filename,

356

and if no extension could be identified

357

then it is given as NULL. Note that filename

358

extensions are defined as all text following the last "."

359

in the filename.

360

Thus \fB-o foo\fP would be parsed as:

361

.in +1c

362

.nf

363

filename[i] = "foo"

364

basename[i] = "foo"

365

extension[i] = NULL

366

.fi

367

.out -1c

368

.PP

369

As with arg_str, the string pointers in \fIfilename[]\fP,

370

\fIbasename[]\fP, and \fIextension[]\fP actually refer to

371

the original \fIargv[]\fP command line string buffers

372

so you should not attempt to alter them.

373

.PP

374

Note also that the parser only ever treats the filenames as strings

375

and never attempts to open them as files or perform any directory

376

lookups on them.

377

378

.SH "DATE/TIME OPTIONS (struct arg_date)"

379

.SS Command line examples

380

12/31/04, -d 1982-11-28, --time 23:59

381

.SS Data Structure

382

.nf

383

struct \fBarg_date\fP

384

{

385

struct \fBarg_hdr\fP hdr;

386

const char *format;

387

int count;

388

struct tm *tmval;

389

};

390

.fi

391

.SS Constructor Functions

392

.PP

393

.HP

394

struct \fBarg_date* arg_date0\fP (const char *shortopts, const char *longopts, const char *format, const char *datatype, const char *glossary)

395

.HP

396

struct \fBarg_date* arg_date1\fP (const char *shortopts, const char *longopts, const char *format, const char *datatype, const char *glossary)

397

.HP

398

struct \fBarg_date* arg_daten\fP (const char *shortopts, const char *longopts, const char *format, const char *datatype, int mincount, int maxcount, const char *glossary)

399

.SS Description

400

Accepts a timestamp string from the command line and converts it to \fIstruct tm\fP format using the system \fBstrptime\fP

401

function. The time format is defined by the \fIformat\fP string passed to the \fIarg_date\fP constructor, and is passed

402

directly to \fBstrptime\fP. See \fBstrptime(3)\fP for more details on the format string.

403

.SS Restrictions

404

Argtable does not support \fBarg_date\fP functionality under Microsoft Windows as the

405

Microsoft compilers do include the necessary \fBstrptime\fP support as standard.

406

407

.SH "REMARK OPTIONS (struct arg_rem)"

408

.SS Data Structure

409

.nf

410

struct \fBarg_rem\fP

411

{

412

struct \fBarg_hdr\fP hdr;

413

};

414

.fi

415

.SS Constructor Function

416

.PP

417

.HP

418

struct \fBarg_rem* arg_rem\fP (const char* datatype, const char* glossary)

419

.SS Description

420

The \fBarg_rem\fP struct is a dummy struct in the sense it does not

421

represent a command line option to be parsed.

422

Instead it provides a means to include additional \fIdatatype\fP and

423

\fIglossary\fP strings in the output of the \fBarg_print_syntax\fP,

424

\fBarg_print_syntaxv\fP, and \fBarg_print_glossary functions\fP.

425

As such, \fBarg_rem\fP structs may be used in the argument table to

426

insert additional lines of text into the glossary descriptions

427

or to insert additional text fields into the syntax description.

428

It has no data members apart from the mandatory \fIarg_hdr\fP struct.

429

430

.SH "END-OF-TABLE OPTIONS (struct arg_end)"

431

.SS Data Structure

432

.nf

433

struct \fBarg_end\fP

434

{

435

struct \fBarg_hdr\fP hdr;

436

int count;

437

int *error;

438

void **parent;

439

const char **argval;

440

};

441

.fi

442

.SS Constructor Function

443

.PP

444

.HP

445

struct \fBarg_end* arg_end\fP (int maxerrors)

446

.SS Description

447

The arg_end struct is primarily used to mark the end of an argument table

448

and doesn't represent any command line option.

449

Every argument table must have an \fBarg_end\fP structure as its last entry.

450

.PP

451

Apart from terminating the argument table, the \fBarg_end\fP structure

452

also stores the error codes generated by the \fBarg_parse\fP function

453

as it attempts to parse the command line with the given argument table.

454

The \fImaxerrors\fP parameter passed to the \fBarg_end\fP constructor

455

specifies the maximum number of errors that the structure can store.

456

Any further errors are discarded and replaced with the single error code

457

ARG_ELIMIT which is later reported to the user by the message "too many errors".

458

A \fImaxerrors\fP limit of 20 is quite reasonable.

459

.PP

460

The \fBarg_print_errors\fP function will print the errors stored

461

in the \fBarg_end\fP struct in the same order as they occurred,

462

so there is no need to understand the internals of the \fBarg_end\fP struct.

463

.PP

464

For those that are curious, the three arrays \fIerror[]\fP, \fIparent[]\fP,

465

and \fIargval[]\fP are each allocated \fImaxerrors\fP entries at construction.

466

As usual, the \fI count\fP variable gives the number of entries actually

467

stored in these arrays. The same value applies to all three arrays as

468

the i'th entry of each all refer to different aspects of the same error

469

condition.

470

.PP

471

The \fIerror[i]\fP entry holds the error code returned by the \fIhdr.scanfn\fP

472

function of the particular \fBarg_xxx\fP that is reporting the error.

473

The meaning if the code is usually known only to the issuing \fBarg_xxx\fP

474

struct. The predefined error codes that \fBarg_end\fP handles from the

475

parser itself are the exceptions.

476

.PP

477

The \fIparent[i]\fP entry points to the parent \fBarg_xxx\fP

478

structure that reported the error.

479

That same \fBarg_xxx\fP structure is also responsible for displaying a

480

pertinent error message when called on to do so

481

by the \fBarg_print_errors\fP function.

482

It calls the \fIhdr.errorfn\fP function of each parent \fBarg_xxx\fP struct

483

listed in the \fBarg_end\fP structure.

484

.PP

485

Lastly, the \fIargval[i]\fP entry points to the command line argument at

486

which the error occurred, although this may be NULL when there is no relevant

487

command line value. For instance, if an error reports a missing option

488

then there will be no matching command line argument value.

489

490

.SH "FILES"

491

\fI<installdir>\fP/include/argtable2.h

492

.br

493

\fI<installdir>\fP/lib/libargtable2.a

494

.br

495

\fI<installdir>\fP/man/man3/argtable2.3

496

.br

497

\fI<installdir>\fP/share/doc/argtable2-x/

498

.br

499

\fI<installdir>\fP/share/doc/argtable2-x/examples/

500

.PP

501

\fI<installdir>\fP = /usr/local on most systems.

502

503

.SH "AUTHOR"

504

Stewart Heitmann <sheitmann@users.sourceforge.net>

Older »