~ubuntu-branches/ubuntu/feisty/argtable2/feisty

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@prefix@/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

100

reported as syntax errors.

101

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

102

.PP

103

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

104

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

105

command line options.

106

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

107

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

108

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

109

.IP

110

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

111

.PP

112

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

113

the glossary table.

114

.PP

115

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

116

structs and their constructor functions.

117

.fi

118

119

.SH FUNCTION REFERENCE

120

.in +1c

121

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

122

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

123

up until the terminating \fBarg_end*\fP entry.

124

Returns zero otherwise.

125

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

126

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

127

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

128

Error details are recorded in the argument table's

129

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

130

the \fBarg_print_errors\fP function.

131

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

132

will contain the argument values extracted from the command line.

133

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

134

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

135

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

136

as parameters of this function.

137

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

138

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

139

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

140

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

141

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

142

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

143

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

144

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

145

.br

146

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

147

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

148

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

149

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

150

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

151

.br

152

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

153

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

154

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

155

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

156

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

157

each entry in the the glossary.

158

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

159

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

160

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

161

the glossary display.

162

.SS "void arg_print_glossary_gnu (FILE *fp, void **argtable)"

163

An alternate form of \fBarg_print_glossary()\fP that prints the glossary

164

using strict GNU formatting conventions wherein long options are vertically aligned in

165

a second column, and lines are wrapped at 80 characters.

166

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

167

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

168

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

169

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

170

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

171

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

172

and then nulling them for safety.

173

174

.SH "LITERAL OPTIONS (struct arg_lit)"

175

.SS Command line examples

176

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

177

.SS Data Structure

178

.nf

179

struct \fBarg_lit\fP

180

{

181

struct \fBarg_hdr\fP hdr;

182

int count;

183

};

184

.fi

185

.SS Constructor Functions

186

.PP

187

.HP

188

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

189

.HP

190

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

191

.HP

192

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

193

.SS Description

194

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

195

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

196

present on the command line.

197

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

198

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

199

200

.SH "INTEGER OPTIONS (struct arg_int)"

201

.SS Command line examples

202

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

203

.SS Data Structure

204

.nf

205

struct \fBarg_int\fP

206

{

207

struct \fBarg_hdr\fP hdr;

208

int count;

209

int *ival;

210

};

211

.fi

212

.SS Constructor Functions

213

.PP

214

.HP

215

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

216

.HP

217

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

218

.HP

219

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

220

.SS Description

221

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

222

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

223

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

224

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

225

.PP

226

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

227

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

228

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

229

The parser will not accept any values beyond that limit.

230

.PP

231

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

232

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

233

for which no command line argument is received.

234

235

.SH "DOUBLE OPTIONS (struct arg_dbl)"

236

.SS Command line examples

237

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

238

.SS Data Structure

239

.nf

240

struct \fBarg_dbl\fP

241

{

242

struct \fBarg_hdr\fP hdr;

243

int count;

244

double *dval;

245

};

246

.fi

247

.SS Constructor Functions

248

.PP

249

.HP

250

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

251

.HP

252

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

253

.HP

254

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

255

.SS Description

256

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

257

258

.SH "STRING OPTIONS (struct arg_str)"

259

.SS Command line examples

260

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

261

.SS Data Structure

262

.nf

263

struct \fBarg_str\fP

264

{

265

struct \fBarg_hdr\fP hdr;

266

int count;

267

const char **sval;

268

};

269

.fi

270

.SS Constructor Functions

271

.PP

272

.HP

273

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

274

.HP

275

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

276

.HP

277

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

278

.SS Description

279

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

280

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

281

an array containing pointers to the parsed string values.

282

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

283

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

284

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

285

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

286

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

287

288

.SH "REGULAR EXPRESSION OPTIONS (struct arg_rex)"

289

.SS Command line examples

290

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

291

.SS Data Structure

292

.nf

293

struct \fBarg_rex\fP

294

{

295

struct \fBarg_hdr\fP hdr;

296

int count;

297

const char **sval;

298

};

299

.fi

300

.SS Constructor Functions

301

.PP

302

.HP

303

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

304

.HP

305

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

306

.HP

307

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)

308

.SS Description

309

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

310

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

311

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

312

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

313

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

314

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

315

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.

316

.SS Restrictions

317

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

318

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

319

320

.SH "FILENAME OPTIONS (struct arg_file)"

321

.SS Command line xamples

322

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

323

.SS Data Structure

324

.nf

325

struct \fBarg_file\fP

326

{

327

struct \fBarg_hdr\fP hdr;

328

int count;

329

const char **filename;

330

const char **basename;

331

const char **extension;

332

};

333

.fi

334

.SS Constructor Functions

335

.PP

336

.HP

337

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

338

.HP

339

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

340

.HP

341

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

342

.SS Description

343

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

344

have filename qualities so some additional pasring is done to

345

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

346

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

347

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

348

refer to different components of the same string buffer.

349

.PP

350

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

351

.in +1c

352

.nf

353

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

354

basename[i] = "foo.txt"

355

extension[i] = "txt"

356

.fi

357

.out -1c

358

.PP

359

If the filename has no leading path then the

360

basename is the same as the filename,

361

and if no extension could be identified

362

then it is given as NULL. Note that filename

363

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

364

in the filename.

365

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

366

.in +1c

367

.nf

368

filename[i] = "foo"

369

basename[i] = "foo"

370

extension[i] = NULL

371

.fi

372

.out -1c

373

.PP

374

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

375

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

376

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

377

so you should not attempt to alter them.

378

.PP

379

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

380

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

381

lookups on them.

382

383

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

384

.SS Command line examples

385

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

386

.SS Data Structure

387

.nf

388

struct \fBarg_date\fP

389

{

390

struct \fBarg_hdr\fP hdr;

391

const char *format;

392

int count;

393

struct tm *tmval;

394

};

395

.fi

396

.SS Constructor Functions

397

.PP

398

.HP

399

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

400

.HP

401

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

402

.HP

403

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)

404

.SS Description

405

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

406

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

407

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

408

.SS Restrictions

409

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

410

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

411

412

.SH "REMARK OPTIONS (struct arg_rem)"

413

.SS Data Structure

414

.nf

415

struct \fBarg_rem\fP

416

{

417

struct \fBarg_hdr\fP hdr;

418

};

419

.fi

420

.SS Constructor Function

421

.PP

422

.HP

423

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

424

.SS Description

425

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

426

represent a command line option to be parsed.

427

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

428

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

429

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

430

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

431

insert additional lines of text into the glossary descriptions

432

or to insert additional text fields into the syntax description.

433

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

434

435

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

436

.SS Data Structure

437

.nf

438

struct \fBarg_end\fP

439

{

440

struct \fBarg_hdr\fP hdr;

441

int count;

442

int *error;

443

void **parent;

444

const char **argval;

445

};

446

.fi

447

.SS Constructor Function

448

.PP

449

.HP

450

struct \fBarg_end* arg_end\fP (int maxerrors)

451

.SS Description

452

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

453

and doesn't represent any command line option.

454

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

455

.PP

456

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

457

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

458

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

459

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

460

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

461

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

462

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

463

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

464

.PP

465

The \fBarg_print_errors\fP function will print the errors stored

466

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

467

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

468

.PP

469

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

470

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

471

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

472

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

473

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

474

condition.

475

.PP

476

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

477

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

478

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

479

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

480

parser itself are the exceptions.

481

.PP

482

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

483

structure that reported the error.

484

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

485

pertinent error message when called on to do so

486

by the \fBarg_print_errors\fP function.

487

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

488

listed in the \fBarg_end\fP structure.

489

.PP

490

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

491

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

492

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

493

then there will be no matching command line argument value.

494

495

.SH "FILES"

496

@prefix@/include/argtable2.h

497

.br

498

@prefix@/lib/libargtable2.a

499

.br

500

@prefix@/lib/libargtable2.so

501

.br

502

@prefix@/man3/argtable2.3

503

.br

504

@prefix@/share/doc/argtable2/

505

.br

506

@prefix@/share/doc/argtable2/example/

507

508

.SH "AUTHOR"

509

Stewart Heitmann <sheitmann@users.sourceforge.net>

Older »