~ubuntu-branches/ubuntu/utopic/binutils-arm64-cross/utopic

ar [\fB\-\-plugin\fR \fIname\fR] [\fB\-X32_64\fR] [\fB\-\fR]\fIp\fR[\fImod\fR [\fIrelpos\fR] [\fIcount\fR]] [\fB\-\-target\fR \fIbfdname\fR] \fIarchive\fR [\fImember\fR...]

137

.SH "DESCRIPTION"

138

.IX Header "DESCRIPTION"

139

The \s-1GNU\s0 \fBar\fR program creates, modifies, and extracts from

140

archives. An \fIarchive\fR is a single file holding a collection of

141

other files in a structure that makes it possible to retrieve

142

the original individual files (called \fImembers\fR of the archive).

143

.PP

144

The original files' contents, mode (permissions), timestamp, owner, and

145

group are preserved in the archive, and can be restored on

146

extraction.

147

.PP

148

\&\s-1GNU\s0 \fBar\fR can maintain archives whose members have names of any

149

length; however, depending on how \fBar\fR is configured on your

150

system, a limit on member-name length may be imposed for compatibility

151

with archive formats maintained with other tools. If it exists, the

152

limit is often 15 characters (typical of formats related to a.out) or 16

153

characters (typical of formats related to coff).

154

.PP

155

\&\fBar\fR is considered a binary utility because archives of this sort

156

are most often used as \fIlibraries\fR holding commonly needed

157

subroutines.

158

.PP

159

\&\fBar\fR creates an index to the symbols defined in relocatable

160

object modules in the archive when you specify the modifier \fBs\fR.

161

Once created, this index is updated in the archive whenever \fBar\fR

162

makes a change to its contents (save for the \fBq\fR update operation).

163

An archive with such an index speeds up linking to the library, and

164

allows routines in the library to call each other without regard to

165

their placement in the archive.

166

.PP

167

You may use \fBnm \-s\fR or \fBnm \-\-print\-armap\fR to list this index

168

table. If an archive lacks the table, another form of \fBar\fR called

169

\&\fBranlib\fR can be used to add just the table.

170

.PP

171

\&\s-1GNU\s0 \fBar\fR can optionally create a \fIthin\fR archive,

172

which contains a symbol index and references to the original copies

173

of the member files of the archive. This is useful for building

174

libraries for use within a local build tree, where the relocatable

175

objects are expected to remain available, and copying the contents of

176

each object would only waste time and space.

177

.PP

178

An archive can either be \fIthin\fR or it can be normal. It cannot

179

be both at the same time. Once an archive is created its format

180

cannot be changed without first deleting it and then creating a new

181

archive in its place.

182

.PP

183

Thin archives are also \fIflattened\fR, so that adding one thin

184

archive to another thin archive does not nest it, as would happen with

185

a normal archive. Instead the elements of the first archive are added

186

individually to the second archive.

187

.PP

188

The paths to the elements of the archive are stored relative to the

189

archive itself.

190

.PP

191

\&\s-1GNU\s0 \fBar\fR is designed to be compatible with two different

192

facilities. You can control its activity using command-line options,

193

like the different varieties of \fBar\fR on Unix systems; or, if you

194

specify the single command-line option \fB\-M\fR, you can control it

195

with a script supplied via standard input, like the \s-1MRI\s0 \*(L"librarian\*(R"

196

program.

197

.SH "OPTIONS"

198

.IX Header "OPTIONS"

199

\&\s-1GNU\s0 \fBar\fR allows you to mix the operation code \fIp\fR and modifier

200

flags \fImod\fR in any order, within the first command-line argument.

201

.PP

202

If you wish, you may begin the first command-line argument with a

203

dash.

204

.PP

205

The \fIp\fR keyletter specifies what operation to execute; it may be

206

any of the following, but you must specify only one of them:

207

.IP "\fBd\fR" 4

208

.IX Item "d"

209

\&\fIDelete\fR modules from the archive. Specify the names of modules to

210

be deleted as \fImember\fR...; the archive is untouched if you

211

specify no files to delete.

212

.Sp

213

If you specify the \fBv\fR modifier, \fBar\fR lists each module

214

as it is deleted.

215

.IP "\fBm\fR" 4

216

.IX Item "m"

217

Use this operation to \fImove\fR members in an archive.

218

.Sp

219

The ordering of members in an archive can make a difference in how

220

programs are linked using the library, if a symbol is defined in more

221

than one member.

222

.Sp

223

If no modifiers are used with \f(CW\*(C`m\*(C'\fR, any members you name in the

224

\&\fImember\fR arguments are moved to the \fIend\fR of the archive;

225

you can use the \fBa\fR, \fBb\fR, or \fBi\fR modifiers to move them to a

226

specified place instead.

227

.IP "\fBp\fR" 4

228

.IX Item "p"

229

\&\fIPrint\fR the specified members of the archive, to the standard

230

output file. If the \fBv\fR modifier is specified, show the member

231

name before copying its contents to standard output.

232

.Sp

233

If you specify no \fImember\fR arguments, all the files in the archive are

234

printed.

235

.IP "\fBq\fR" 4

236

.IX Item "q"

237

\&\fIQuick append\fR; Historically, add the files \fImember\fR... to the end of

238

\&\fIarchive\fR, without checking for replacement.

239

.Sp

240

The modifiers \fBa\fR, \fBb\fR, and \fBi\fR do \fInot\fR affect this

241

operation; new members are always placed at the end of the archive.

242

.Sp

243

The modifier \fBv\fR makes \fBar\fR list each file as it is appended.

244

.Sp

245

Since the point of this operation is speed, the archive's symbol table

246

index is not updated, even if it already existed; you can use \fBar s\fR or

247

\&\fBranlib\fR explicitly to update the symbol table index.

248

.Sp

249

However, too many different systems assume quick append rebuilds the

250

index, so \s-1GNU\s0 \fBar\fR implements \fBq\fR as a synonym for \fBr\fR.

251

.IP "\fBr\fR" 4

252

.IX Item "r"

253

Insert the files \fImember\fR... into \fIarchive\fR (with

254

\&\fIreplacement\fR). This operation differs from \fBq\fR in that any

255

previously existing members are deleted if their names match those being

256

added.

257

.Sp

258

If one of the files named in \fImember\fR... does not exist, \fBar\fR

259

displays an error message, and leaves undisturbed any existing members

260

of the archive matching that name.

261

.Sp

262

By default, new members are added at the end of the file; but you may

263

use one of the modifiers \fBa\fR, \fBb\fR, or \fBi\fR to request

264

placement relative to some existing member.

265

.Sp

266

The modifier \fBv\fR used with this operation elicits a line of

267

output for each file inserted, along with one of the letters \fBa\fR or

268

\&\fBr\fR to indicate whether the file was appended (no old member

269

deleted) or replaced.

270

.IP "\fBs\fR" 4

271

.IX Item "s"

272

Add an index to the archive, or update it if it already exists. Note

273

this command is an exception to the rule that there can only be one

274

command letter, as it is possible to use it as either a command or a

275

modifier. In either case it does the same thing.

276

.IP "\fBt\fR" 4

277

.IX Item "t"

278

Display a \fItable\fR listing the contents of \fIarchive\fR, or those

279

of the files listed in \fImember\fR... that are present in the

280

archive. Normally only the member name is shown; if you also want to

281

see the modes (permissions), timestamp, owner, group, and size, you can

282

request that by also specifying the \fBv\fR modifier.

283

.Sp

284

If you do not specify a \fImember\fR, all files in the archive

285

are listed.

286

.Sp

287

If there is more than one file with the same name (say, \fBfie\fR) in

288

an archive (say \fBb.a\fR), \fBar t b.a fie\fR lists only the

289

first instance; to see them all, you must ask for a complete

290

listing\-\-\-in our example, \fBar t b.a\fR.

291

.IP "\fBx\fR" 4

292

.IX Item "x"

293

\&\fIExtract\fR members (named \fImember\fR) from the archive. You can

294

use the \fBv\fR modifier with this operation, to request that

295

\&\fBar\fR list each name as it extracts it.

296

.Sp

297

If you do not specify a \fImember\fR, all files in the archive

298

are extracted.

299

.Sp

300

Files cannot be extracted from a thin archive.

301

.IP "\fB\-\-help\fR" 4

302

.IX Item "--help"

303

Displays the list of command line options supported by \fBar\fR

304

and then exits.

305

.IP "\fB\-\-version\fR" 4

306

.IX Item "--version"

307

Displays the version information of \fBar\fR and then exits.

308

.PP

309

A number of modifiers (\fImod\fR) may immediately follow the \fIp\fR

310

keyletter, to specify variations on an operation's behavior:

311

.IP "\fBa\fR" 4

312

.IX Item "a"

313

Add new files \fIafter\fR an existing member of the

314

archive. If you use the modifier \fBa\fR, the name of an existing archive

315

member must be present as the \fIrelpos\fR argument, before the

316

\&\fIarchive\fR specification.

317

.IP "\fBb\fR" 4

318

.IX Item "b"

319

Add new files \fIbefore\fR an existing member of the

320

archive. If you use the modifier \fBb\fR, the name of an existing archive

321

member must be present as the \fIrelpos\fR argument, before the

322

\&\fIarchive\fR specification. (same as \fBi\fR).

323

.IP "\fBc\fR" 4

324

.IX Item "c"

325

\&\fICreate\fR the archive. The specified \fIarchive\fR is always

326

created if it did not exist, when you request an update. But a warning is

327

issued unless you specify in advance that you expect to create it, by

328

using this modifier.

329

.IP "\fBD\fR" 4

330

.IX Item "D"

331

Operate in \fIdeterministic\fR mode. When adding files and the archive

332

index use zero for UIDs, GIDs, timestamps, and use consistent file modes

333

for all files. When this option is used, if \fBar\fR is used with

334

identical options and identical input files, multiple runs will create

335

identical output files regardless of the input files' owners, groups,

336

file modes, or modification times.

337

.Sp

338

If \fIbinutils\fR was configured with

339

\&\fB\-\-enable\-deterministic\-archives\fR, then this mode is on by default.

340

It can be disabled with the \fBU\fR modifier, below.

341

.IP "\fBf\fR" 4

342

.IX Item "f"

343

Truncate names in the archive. \s-1GNU\s0 \fBar\fR will normally permit file

344

names of any length. This will cause it to create archives which are

345

not compatible with the native \fBar\fR program on some systems. If

346

this is a concern, the \fBf\fR modifier may be used to truncate file

347

names when putting them in the archive.

348

.IP "\fBi\fR" 4

349

.IX Item "i"

350

Insert new files \fIbefore\fR an existing member of the

351

archive. If you use the modifier \fBi\fR, the name of an existing archive

352

member must be present as the \fIrelpos\fR argument, before the

353

\&\fIarchive\fR specification. (same as \fBb\fR).

354

.IP "\fBl\fR" 4

355

.IX Item "l"

356

This modifier is accepted but not used.

357

.IP "\fBN\fR" 4

358

.IX Item "N"

359

Uses the \fIcount\fR parameter. This is used if there are multiple

360

entries in the archive with the same name. Extract or delete instance

361

\&\fIcount\fR of the given name from the archive.

362

.IP "\fBo\fR" 4

363

.IX Item "o"

364

Preserve the \fIoriginal\fR dates of members when extracting them. If

365

you do not specify this modifier, files extracted from the archive

366

are stamped with the time of extraction.

367

.IP "\fBP\fR" 4

368

.IX Item "P"

369

Use the full path name when matching names in the archive. \s-1GNU\s0

370

\&\fBar\fR can not create an archive with a full path name (such archives

371

are not \s-1POSIX\s0 complaint), but other archive creators can. This option

372

will cause \s-1GNU\s0 \fBar\fR to match file names using a complete path

373

name, which can be convenient when extracting a single file from an

374

archive created by another tool.

375

.IP "\fBs\fR" 4

376

.IX Item "s"

377

Write an object-file index into the archive, or update an existing one,

378

even if no other change is made to the archive. You may use this modifier

379

flag either with any operation, or alone. Running \fBar s\fR on an

380

archive is equivalent to running \fBranlib\fR on it.

381

.IP "\fBS\fR" 4

382

.IX Item "S"

383

Do not generate an archive symbol table. This can speed up building a

384

large library in several steps. The resulting archive can not be used

385

with the linker. In order to build a symbol table, you must omit the

386

\&\fBS\fR modifier on the last execution of \fBar\fR, or you must run

387

\&\fBranlib\fR on the archive.

388

.IP "\fBT\fR" 4

389

.IX Item "T"

390

Make the specified \fIarchive\fR a \fIthin\fR archive. If it already

391

exists and is a regular archive, the existing members must be present

392

in the same directory as \fIarchive\fR.

393

.IP "\fBu\fR" 4

394

.IX Item "u"

395

Normally, \fBar r\fR... inserts all files

396

listed into the archive. If you would like to insert \fIonly\fR those

397

of the files you list that are newer than existing members of the same

398

names, use this modifier. The \fBu\fR modifier is allowed only for the

399

operation \fBr\fR (replace). In particular, the combination \fBqu\fR is

400

not allowed, since checking the timestamps would lose any speed

401

advantage from the operation \fBq\fR.

402

.IP "\fBU\fR" 4

403

.IX Item "U"

404

Do \fInot\fR operate in \fIdeterministic\fR mode. This is the inverse

405

of the \fBD\fR modifier, above: added files and the archive index will

406

get their actual \s-1UID\s0, \s-1GID\s0, timestamp, and file mode values.

407

.Sp

408

This is the default unless \fIbinutils\fR was configured with

409

\&\fB\-\-enable\-deterministic\-archives\fR.

410

.IP "\fBv\fR" 4

411

.IX Item "v"

412

This modifier requests the \fIverbose\fR version of an operation. Many

413

operations display additional information, such as filenames processed,

414

when the modifier \fBv\fR is appended.

415

.IP "\fBV\fR" 4

416

.IX Item "V"

417

This modifier shows the version number of \fBar\fR.

418

.PP

419

\&\fBar\fR ignores an initial option spelt \fB\-X32_64\fR, for

420

compatibility with \s-1AIX\s0. The behaviour produced by this option is the

421

default for \s-1GNU\s0 \fBar\fR. \fBar\fR does not support any of the other

422

\&\fB\-X\fR options; in particular, it does not support \fB\-X32\fR

423

which is the default for \s-1AIX\s0 \fBar\fR.

424

.PP

425

The optional command line switch \fB\-\-plugin\fR \fIname\fR causes

426

\&\fBar\fR to load the plugin called \fIname\fR which adds support

427

for more file formats. This option is only available if the toolchain

428

has been built with plugin support enabled.

429

.PP

430

The optional command line switch \fB\-\-target\fR \fIbfdname\fR

431

specifies that the archive members are in an object code format

432

different from your system's default format. See

433

.IP "\fB@\fR\fIfile\fR" 4

434

.IX Item "@file"

435

Read command-line options from \fIfile\fR. The options read are

436

inserted in place of the original @\fIfile\fR option. If \fIfile\fR

437

does not exist, or cannot be read, then the option will be treated

438

literally, and not removed.

439

.Sp

440

Options in \fIfile\fR are separated by whitespace. A whitespace

441

character may be included in an option by surrounding the entire

442

option in either single or double quotes. Any character (including a

443

backslash) may be included by prefixing the character to be included

444

with a backslash. The \fIfile\fR may itself contain additional

445

@\fIfile\fR options; any such options will be processed recursively.

446

.SH "SEE ALSO"

447

.IX Header "SEE ALSO"

448

\&\fInm\fR\|(1), \fIranlib\fR\|(1), and the Info entries for \fIbinutils\fR.

449

.SH "COPYRIGHT"

450

.IX Header "COPYRIGHT"

451

452

.PP

453

Permission is granted to copy, distribute and/or modify this document

454

under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3

455

or any later version published by the Free Software Foundation;

456

with no Invariant Sections, with no Front-Cover Texts, and with no

457

Back-Cover Texts. A copy of the license is included in the

458

section entitled \*(L"\s-1GNU\s0 Free Documentation License\*(R".

Older »