~ubuntu-branches/ubuntu/trusty/libarchive/trusty

.Fn archive_read_open "struct archive *" "void *client_data" "archive_open_archive_callback *" "archive_read_archive_callback *" "archive_close_archive_callback *"

.Ft int

.Fn archive_read_open_fd "struct archive *" "int fd" "size_t block_size"

.Ft int

.Fn archive_read_open_file "struct archive *" "const char *filename" "size_t block_size"

.Ft int

.Fn archive_read_next_header "struct archive *" "struct archive_entry **"

.Ft ssize_t

.Fn archive_read_data "struct archive *" "void *buff" "size_t len"

.Ft int

.Fn archive_read_data_block "struct archive *" "const void **buff" "size_t *len" "off_t *offset"

.Ft int

.Fn archive_read_data_skip "struct archive *"

.Ft int

.Fn archive_read_data_into_buffer "struct archive *" "void *" "size_t len"

.Ft int

100

.Fn archive_read_data_into_fd "struct archive *" "int fd"

101

.Ft int

102

.Fn archive_read_extract "struct archive *" "struct archive_entry *" "int flags"

103

.Ft void

104

.Fn archive_read_extract_set_progress_callback "struct archive *" "void (*func)(void *)" "void *user_data"

105

.Ft int

106

.Fn archive_read_close "struct archive *"

107

.Ft void

108

.Fn archive_read_finish "struct archive *"

109

.Sh DESCRIPTION

110

These functions provide a complete API for reading streaming archives.

111

The general process is to first create the

112

.Tn struct archive

113

object, set options, initialize the reader, iterate over the archive

114

headers and associated data, then close the archive and release all

115

resources.

116

The following summary describes the functions in approximately the

117

order they would be used:

118

.Bl -tag -compact -width indent

119

.It Fn archive_read_new

120

Allocates and initializes a

121

.Tn struct archive

122

object suitable for reading from an archive.

123

.It Fn archive_read_set_bytes_per_block

124

Sets the block size used for reading the archive data.

125

This controls the size that will be used when invoking the read

126

callback function.

127

The default is 20 records or 10240 bytes for tar formats.

128

.It Fn archive_read_support_compression_all , Fn archive_read_support_compression_bzip2 , Fn archive_read_support_compression_compress , Fn archive_read_support_compression_gzip , Fn archive_read_support_compression_none

129

Enables auto-detection code and decompression support for the

130

specified compression.

131

Note that

132

.Dq none

133

is always enabled by default.

134

For convenience,

135

.Fn archive_read_support_compression_all

136

enables all available decompression code.

137

.It Fn archive_read_support_format_all , Fn archive_read_support_format_cpio , Fn archive_read_support_format_iso9660 , Fn archive_read_support_format_tar, Fn archive_read_support_format_zip

138

Enables support---including auto-detection code---for the

139

specified archive format.

140

For example,

141

.Fn archive_read_support_format_tar

142

enables support for a variety of standard tar formats, old-style tar,

143

ustar, pax interchange format, and many common variants.

144

For convenience,

145

.Fn archive_read_support_format_all

146

enables support for all available formats.

147

Note that there is no default.

148

.It Fn archive_read_open

149

Freeze the settings, open the archive, and prepare for reading entries.

150

This is the most generic version of this call, which accepts

151

three callback functions.

152

Most clients will want to use

153

.Fn archive_read_open_file

154

155

.Fn archive_read_open_fd

156

instead.

157

The library invokes the client-provided functions to obtain

158

raw bytes from the archive.

159

Note: The API permits a decompression method to fork and invoke the

160

callbacks from another process.

161

Although none of the current decompression methods use this technique,

162

future decompression methods may utilize this technique.

163

If the decompressor forks, it will ensure that the open and close

164

callbacks are invoked within the same process as the read callback.

165

In particular, clients should not attempt to use shared variables to

166

communicate between the open/read/close callbacks and the mainline code.

167

.It Fn archive_read_open_fd

168

169

.Fn archive_read_open ,

170

except that it accepts a file descriptor and block size rather than

171

a trio of function pointers.

172

Note that the file descriptor will not be automatically closed at

173

end-of-archive.

174

.It Fn archive_read_open_file

175

176

.Fn archive_read_open ,

177

except that it accepts a simple filename and a block size.

178

A NULL filename represents standard input.

179

.It Fn archive_read_next_header

180

Read the header for the next entry and return a pointer to

181

182

.Tn struct archive_entry .

183

.It Fn archive_read_data

184

Read data associated with the header just read.

185

Internally, this is a convenience function that calls

186

.Fn archive_read_data_block

187

and fills any gaps with nulls so that callers see a single

188

continuous stream of data.

189

.It Fn archive_read_data_block

190

Return the next available block of data for this entry.

191

Unlike

192

.Fn archive_read_data ,

193

the

194

.Fn archive_read_data_block

195

function avoids copying data and allows you to correctly handle

196

sparse files, as supported by some archive formats.

197

The library guarantees that offsets will increase and that blocks

198

will not overlap.

199

Note that the blocks returned from this function can be much larger

200

than the block size read from disk, due to compression

201

and internal buffer optimizations.

202

.It Fn archive_read_data_skip

203

A convenience function that repeatedly calls

204

.Fn archive_read_data_block

205

to skip all of the data for this archive entry.

206

.It Fn archive_read_data_into_buffer

207

A convenience function that repeatedly calls

208

.Fn archive_read_data_block

209

to copy the entire entry into the client-supplied buffer.

210

Note that the client is responsible for sizing the buffer appropriately.

211

.It Fn archive_read_data_into_fd

212

A convenience function that repeatedly calls

213

.Fn archive_read_data_block

214

to copy the entire entry to the provided file descriptor.

215

.It Fn archive_read_extract

216

A convenience function that recreates the specified object on

217

disk and reads the entry data into that object.

218

The filename, permissions, and other critical information

219

are taken from the provided

220

.Va archive_entry

221

object.

222

The

223

.Va flags

224

argument modifies how the object is recreated.

225

It consists of a bitwise OR of one or more of the following values:

226

.Bl -tag -compact -width "indent"

227

.It Cm ARCHIVE_EXTRACT_OWNER

228

The user and group IDs should be set on the restored file.

229

By default, the user and group IDs are not restored.

230

.It Cm ARCHIVE_EXTRACT_PERM

231

The permissions (mode bits) should be restored for all objects.

232

By default, permissions are only restored for regular files.

233

.It Cm ARCHIVE_EXTRACT_TIME

234

The timestamps (mtime, ctime, and atime) should be restored.

235

By default, they are ignored.

236

Note that restoring of atime is not currently supported.

237

.It Cm ARCHIVE_EXTRACT_NO_OVERWRITE

238

Existing files on disk will not be overwritten.

239

By default, existing regular files are truncated and overwritten;

240

existing directories will have their permissions updated;

241

other pre-existing objects are unlinked and recreated from scratch.

242

.It Cm ARCHIVE_EXTRACT_UNLINK

243

Existing files on disk will be unlinked and recreated from scratch.

244

By default, existing files are truncated and rewritten, but

245

the file is not recreated.

246

In particular, the default behavior does not break existing hard links.

247

.It Cm ARCHIVE_EXTRACT_ACL

248

Attempt to restore ACLs.

249

By default, extended ACLs are ignored.

250

.It Cm ARCHIVE_EXTRACT_FFLAGS

251

Attempt to restore extended file flags.

252

By default, file flags are ignored.

253

.El

254

Note that not all attributes are set immediately;

255

some attributes are cached in memory and written to disk only

256

when the archive is closed.

257

(For example, read-only directories are initially created

258

writable so that files within those directories can be

259

restored.

260

The final permissions are set when the archive is closed.)

261

.It Fn archive_read_extract_set_progress_callback

262

Sets a pointer to a user-defined callback that can be used

263

for updating progress displays during extraction.

264

The progress function will be invoked during the extraction of large

265

regular files.

266

The progress function will be invoked with the pointer provided to this call.

267

Generally, the data pointed to should include a reference to the archive

268

object and the archive_entry object so that various statistics

269

can be retrieved for the progress display.

270

.It Fn archive_read_close

271

Complete the archive and invoke the close callback.

272

.It Fn archive_read_finish

273

Invokes

274

.Fn archive_read_close

275

if it was not invoked manually, then release all resources.

276

.El

277

.Pp

278

Note that the library determines most of the relevant information about

279

the archive by inspection.

280

In particular, it automatically detects

281

.Xr gzip 1

282

283

.Xr bzip2 1

284

compression and transparently performs the appropriate decompression.

285

It also automatically detects the archive format.

286

.Pp

287

A complete description of the

288

.Tn struct archive

289

and

290

.Tn struct archive_entry

291

objects can be found in the overview manual page for

292

.Xr libarchive 3 .

293

.Sh CLIENT CALLBACKS

294

The callback functions must match the following prototypes:

295

.Bl -item -offset indent

296

.It

297

.Ft typedef ssize_t

298

.Fn archive_read_callback "struct archive *" "void *client_data" "const void **buffer"

299

.It

300

.Ft typedef int

301

.Fn archive_open_callback "struct archive *" "void *client_data"

302

.It

303

.Ft typedef int

304

.Fn archive_close_callback "struct archive *" "void *client_data"

305

.El

306

.Pp

307

The open callback is invoked by

308

.Fn archive_open .

309

It should return

310

.Cm ARCHIVE_OK

311

if the underlying file or data source is successfully

312

opened.

313

If the open fails, it should call

314

.Fn archive_set_error

315

to register an error code and message and return

316

.Cm ARCHIVE_FATAL .

317

.Pp

318

The read callback is invoked whenever the library

319

requires raw bytes from the archive.

320

The read callback should read data into a buffer,

321

set the

322

.Li const void **buffer

323

argument to point to the available data, and

324

return a count of the number of bytes available.

325

The library will invoke the read callback again

326

only after it has consumed this data.

327

The library imposes no constraints on the size

328

of the data blocks returned.

329

On end-of-file, the read callback should

330

return zero.

331

On error, the read callback should invoke

332

.Fn archive_set_error

333

to register an error code and message and

334

return -1.

335

.Pp

336

The close callback is invoked by archive_close when

337

the archive processing is complete.

338

The callback should return

339

.Cm ARCHIVE_OK

340

on success.

341

On failure, the callback should invoke

342

.Fn archive_set_error

343

to register an error code and message and

344

return

345

.Cm ARCHIVE_FATAL.

346

.Sh EXAMPLE

347

The following illustrates basic usage of the library.

348

In this example,

349

the callback functions are simply wrappers around the standard

350

.Xr open 2 ,

351

.Xr read 2 ,

352

and

353

.Xr close 2

354

system calls.

355

.Bd -literal -offset indent

356

void

357

list_archive(const char *name)

358

{

359

struct mydata *mydata;

360

struct archive *a;

361

struct archive_entry *entry;

362

363

mydata = malloc(sizeof(struct mydata));

364

a = archive_read_new();

365

mydata->name = name;

366

archive_read_support_compression_all(a);

367

archive_read_support_format_all(a);

368

archive_read_open(a, mydata, myopen, myread, myclose);

369

while (archive_read_next_header(a, &entry) == ARCHIVE_OK) {

370

printf("%s\\n",archive_entry_pathname(entry));

371

archive_read_data_skip(a);

372

}

373

archive_read_finish(a);

374

free(mydata);

375

}

376

377

ssize_t

378

myread(struct archive *a, void *client_data, const void **buff)

379

{

380

struct mydata *mydata = client_data;

381

382

*buff = mydata->buff;

383

return (read(mydata->fd, mydata->buff, 10240));

384

}

385

386

int

387

myopen(struct archive *a, void *client_data)

388

{

389

struct mydata *mydata = client_data;

390

391

mydata->fd = open(mydata->name, O_RDONLY);

392

return (mydata->fd >= 0 ? ARCHIVE_OK : ARCHIVE_FATAL);

393

}

394

395

int

396

myclose(struct archive *a, void *client_data)

397

{

398

struct mydata *mydata = client_data;

399

400

if (mydata->fd > 0)

401

close(mydata->fd);

402

return (ARCHIVE_OK);

403

}

404

.Ed

405

.Sh RETURN VALUES

406

Most functions return zero on success, non-zero on error.

407

The possible return codes include:

408

.Cm ARCHIVE_OK

409

(the operation succeeded),

410

.Cm ARCHIVE_WARN

411

(the operation succeeded but a non-critical error was encountered),

412

.Cm ARCHIVE_EOF

413

(end-of-archive was encountered),

414

.Cm ARCHIVE_RETRY

415

(the operation failed but can be retried),

416

and

417

.Cm ARCHIVE_FATAL

418

(there was a fatal error; the archive should be closed immediately).

419

Detailed error codes and textual descriptions are available from the

420

.Fn archive_errno

421

and

422

.Fn archive_error_string

423

functions.

424

.Pp

425

.Fn archive_read_new

426

returns a pointer to a freshly allocated

427

.Tn struct archive

428

object.

429

It returns

430

.Dv NULL

431

on error.

432

.Pp

433

.Fn archive_read_data

434

returns a count of bytes actually read or zero at the end of the entry.

435

On error, a value of

436

.Cm ARCHIVE_FATAL ,

437

.Cm ARCHIVE_WARN ,

438

439

.Cm ARCHIVE_RETRY

440

is returned and an error code and textual description can be retrieved from the

441

.Fn archive_errno

442

and

443

.Fn archive_error_string

444

functions.

445

.Pp

446

The library expects the client callbacks to behave similarly.

447

If there is an error, you can use

448

.Fn archive_set_error

449

to set an appropriate error code and description,

450

then return one of the non-zero values above.

451

(Note that the value eventually returned to the client may

452

not be the same; many errors that are not critical at the level

453

of basic I/O can prevent the archive from being properly read,

454

thus most I/O errors eventually cause

455

.Cm ARCHIVE_FATAL

456

to be returned.)

457

.\" .Sh ERRORS

458

.Sh SEE ALSO

459

.Xr tar 1 ,

460

.Xr archive 3 ,

461

.Xr archive_util 3 ,

462

.Xr tar 5

463

.Sh HISTORY

464

The

465

.Nm libarchive

466

library first appeared in

467

.Fx 5.3 .

468

.Sh AUTHORS

469

.An -nosplit

470

The

471

.Nm libarchive

472

library was written by

473

.An Tim Kientzle Aq kientzle@acm.org .

474

.Sh BUGS

475

Directories are actually extracted in two distinct phases.

476

Directories are created during

477

.Fn archive_read_extract ,

478

but final permissions are not set until

479

.Fn archive_read_close .

480

This separation is necessary to correctly handle borderline

481

cases such as a non-writable directory containing

482

files, but can cause unexpected results.

483

In particular, directory permissions are not fully

484

restored until the archive is closed.

485

If you use

486

.Xr chdir 2

487

to change the current directory between calls to

488

.Fn archive_read_extract

489

or before calling

490

.Fn archive_read_close ,

491

you may confuse the permission-setting logic with

492

the result that directory permissions are restored

493

incorrectly.

Older »