1<!-- Creator : groff version 1.19.2 --> 2<!-- CreationDate: Sun Mar 14 19:50:13 2010 --> 3<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 4"http://www.w3.org/TR/html4/loose.dtd"> 5<html> 6<head> 7<meta name="generator" content="groff -Thtml, see www.gnu.org"> 8<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> 9<meta name="Content-Style" content="text/css"> 10<style type="text/css"> 11 p { margin-top: 0; margin-bottom: 0; } 12 pre { margin-top: 0; margin-bottom: 0; } 13 table { margin-top: 0; margin-bottom: 0; } 14</style> 15<title></title> 16</head> 17<body> 18 19<hr> 20 21 22<p valign="top">archive_entry(3) FreeBSD Library Functions 23Manual archive_entry(3)</p> 24 25<p style="margin-top: 1em" valign="top"><b>NAME</b></p> 26 27 28<p style="margin-left:8%;"><b>archive_entry_acl_add_entry</b>, 29<b>archive_entry_acl_add_entry_w</b>, 30<b>archive_entry_acl_clear</b>, 31<b>archive_entry_acl_count</b>, 32<b>archive_entry_acl_next</b>, 33<b>archive_entry_acl_next_w</b>, 34<b>archive_entry_acl_reset</b>, 35<b>archive_entry_acl_text_w</b>, <b>archive_entry_atime</b>, 36<b>archive_entry_atime_nsec</b>, <b>archive_entry_clear</b>, 37<b>archive_entry_clone</b>, 38<b>archive_entry_copy_fflags_text</b>, 39<b>archive_entry_copy_fflags_text_w</b>, 40<b>archive_entry_copy_gname</b>, 41<b>archive_entry_copy_gname_w</b>, 42<b>archive_entry_copy_hardlink</b>, 43<b>archive_entry_copy_hardlink_w</b>, 44<b>archive_entry_copy_link</b>, 45<b>archive_entry_copy_link_w</b>, 46<b>archive_entry_copy_pathname_w</b>, 47<b>archive_entry_copy_sourcepath</b>, 48<b>archive_entry_copy_stat</b>, 49<b>archive_entry_copy_symlink</b>, 50<b>archive_entry_copy_symlink_w</b>, 51<b>archive_entry_copy_uname</b>, 52<b>archive_entry_copy_uname_w</b>, <b>archive_entry_dev</b>, 53<b>archive_entry_devmajor</b>, 54<b>archive_entry_devminor</b>, 55<b>archive_entry_filetype</b>, <b>archive_entry_fflags</b>, 56<b>archive_entry_fflags_text</b>, <b>archive_entry_free</b>, 57<b>archive_entry_gid</b>, <b>archive_entry_gname</b>, 58<b>archive_entry_hardlink</b>, <b>archive_entry_ino</b>, 59<b>archive_entry_mode</b>, <b>archive_entry_mtime</b>, 60<b>archive_entry_mtime_nsec</b>, <b>archive_entry_nlink</b>, 61<b>archive_entry_new</b>, <b>archive_entry_pathname</b>, 62<b>archive_entry_pathname_w</b>, <b>archive_entry_rdev</b>, 63<b>archive_entry_rdevmajor</b>, 64<b>archive_entry_rdevminor</b>, 65<b>archive_entry_set_atime</b>, 66<b>archive_entry_set_ctime</b>, 67<b>archive_entry_set_dev</b>, 68<b>archive_entry_set_devmajor</b>, 69<b>archive_entry_set_devminor</b>, 70<b>archive_entry_set_filetype</b>, 71<b>archive_entry_set_fflags</b>, 72<b>archive_entry_set_gid</b>, 73<b>archive_entry_set_gname</b>, 74<b>archive_entry_set_hardlink</b>, 75<b>archive_entry_set_link</b>, 76<b>archive_entry_set_mode</b>, 77<b>archive_entry_set_mtime</b>, 78<b>archive_entry_set_pathname</b>, 79<b>archive_entry_set_rdevmajor</b>, 80<b>archive_entry_set_rdevminor</b>, 81<b>archive_entry_set_size</b>, 82<b>archive_entry_set_symlink</b>, 83<b>archive_entry_set_uid</b>, 84<b>archive_entry_set_uname</b>, <b>archive_entry_size</b>, 85<b>archive_entry_sourcepath</b>, <b>archive_entry_stat</b>, 86<b>archive_entry_symlink</b>, <b>archive_entry_uid</b>, 87<b>archive_entry_uname</b> — functions for 88manipulating archive entry descriptions</p> 89 90 91<p style="margin-top: 1em" valign="top"><b>SYNOPSIS</b></p> 92 93<p style="margin-left:8%;"><b>#include 94<archive_entry.h></b></p> 95 96<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> 97 98 99<p valign="top"><b>archive_entry_acl_add_entry</b>(<i>struct archive_entry *</i>, 100<i>int type</i>, <i>int permset</i>, 101<i>int tag</i>, <i>int qual</i>, 102<i>const char *name</i>);</p> 103 104<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> 105 106 107<p valign="top"><b>archive_entry_acl_add_entry_w</b>(<i>struct archive_entry *</i>, 108<i>int type</i>, <i>int permset</i>, 109<i>int tag</i>, <i>int qual</i>, 110<i>const wchar_t *name</i>);</p> 111 112<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> 113 114 115<p style="margin-left:14%;"><b>archive_entry_acl_clear</b>(<i>struct archive_entry *</i>);</p> 116 117<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> 118 119 120<p style="margin-left:14%;"><b>archive_entry_acl_count</b>(<i>struct archive_entry *</i>, 121<i>int type</i>);</p> 122 123<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> 124 125 126<p valign="top"><b>archive_entry_acl_next</b>(<i>struct archive_entry *</i>, 127<i>int want_type</i>, <i>int *type</i>, 128<i>int *permset</i>, <i>int *tag</i>, 129<i>int *qual</i>, 130<i>const char **name</i>);</p> 131 132<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> 133 134 135<p valign="top"><b>archive_entry_acl_next_w</b>(<i>struct archive_entry *</i>, 136<i>int want_type</i>, <i>int *type</i>, 137<i>int *permset</i>, <i>int *tag</i>, 138<i>int *qual</i>, 139<i>const wchar_t **name</i>);</p> 140 141<p style="margin-left:8%; margin-top: 1em"><i>int</i></p> 142 143 144<p style="margin-left:14%;"><b>archive_entry_acl_reset</b>(<i>struct archive_entry *</i>, 145<i>int want_type</i>);</p> 146 147<p style="margin-left:8%; margin-top: 1em"><i>const wchar_t 148*</i></p> 149 150 151<p style="margin-left:14%;"><b>archive_entry_acl_text_w</b>(<i>struct archive_entry *</i>, 152<i>int flags</i>);</p> 153 154 155<p style="margin-left:8%; margin-top: 1em"><i>time_t</i></p> 156 157 158<p style="margin-left:14%;"><b>archive_entry_atime</b>(<i>struct archive_entry *</i>);</p> 159 160<p style="margin-left:8%; margin-top: 1em"><i>long</i></p> 161 162 163<p style="margin-left:14%;"><b>archive_entry_atime_nsec</b>(<i>struct archive_entry *</i>);</p> 164 165<p style="margin-left:8%; margin-top: 1em"><i>struct 166archive_entry *</i></p> 167 168 169<p style="margin-left:14%;"><b>archive_entry_clear</b>(<i>struct archive_entry *</i>);</p> 170 171<p style="margin-left:8%; margin-top: 1em"><i>struct 172archive_entry *</i></p> 173 174 175<p style="margin-left:14%;"><b>archive_entry_clone</b>(<i>struct archive_entry *</i>);</p> 176 177<p style="margin-left:8%; margin-top: 1em"><i>const char * 178*</i></p> 179 180 181<p style="margin-left:14%;"><b>archive_entry_copy_fflags_text_w</b>(<i>struct archive_entry *</i>, 182<i>const char *</i>);</p> 183 184<p style="margin-left:8%; margin-top: 1em"><i>const wchar_t 185*</i></p> 186 187 188<p style="margin-left:14%;"><b>archive_entry_copy_fflags_text_w</b>(<i>struct archive_entry *</i>, 189<i>const wchar_t *</i>);</p> 190 191<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> 192 193 194<p style="margin-left:14%;"><b>archive_entry_copy_gname</b>(<i>struct archive_entry *</i>, 195<i>const char *</i>);</p> 196 197<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> 198 199 200<p style="margin-left:14%;"><b>archive_entry_copy_gname_w</b>(<i>struct archive_entry *</i>, 201<i>const wchar_t *</i>);</p> 202 203<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> 204 205 206<p style="margin-left:14%;"><b>archive_entry_copy_hardlink</b>(<i>struct archive_entry *</i>, 207<i>const char *</i>);</p> 208 209<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> 210 211 212<p style="margin-left:14%;"><b>archive_entry_copy_hardlink_w</b>(<i>struct archive_entry *</i>, 213<i>const wchar_t *</i>);</p> 214 215<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> 216 217 218<p style="margin-left:14%;"><b>archive_entry_copy_sourcepath</b>(<i>struct archive_entry *</i>, 219<i>const char *</i>);</p> 220 221<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> 222 223 224<p style="margin-left:14%;"><b>archive_entry_copy_pathname_w</b>(<i>struct archive_entry *</i>, 225<i>const wchar_t *</i>);</p> 226 227<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> 228 229 230<p style="margin-left:14%;"><b>archive_entry_copy_stat</b>(<i>struct archive_entry *</i>, 231<i>const struct stat *</i>);</p> 232 233<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> 234 235 236<p style="margin-left:14%;"><b>archive_entry_copy_symlink</b>(<i>struct archive_entry *</i>, 237<i>const char *</i>);</p> 238 239<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> 240 241 242<p style="margin-left:14%;"><b>archive_entry_copy_symlink_w</b>(<i>struct archive_entry *</i>, 243<i>const wchar_t *</i>);</p> 244 245<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> 246 247 248<p style="margin-left:14%;"><b>archive_entry_copy_uname</b>(<i>struct archive_entry *</i>, 249<i>const char *</i>);</p> 250 251<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> 252 253 254<p style="margin-left:14%;"><b>archive_entry_copy_uname_w</b>(<i>struct archive_entry *</i>, 255<i>const wchar_t *</i>);</p> 256 257 258<p style="margin-left:8%; margin-top: 1em"><i>dev_t</i></p> 259 260 261<p style="margin-left:14%;"><b>archive_entry_dev</b>(<i>struct archive_entry *</i>);</p> 262 263 264<p style="margin-left:8%; margin-top: 1em"><i>dev_t</i></p> 265 266 267<p style="margin-left:14%;"><b>archive_entry_devmajor</b>(<i>struct archive_entry *</i>);</p> 268 269 270<p style="margin-left:8%; margin-top: 1em"><i>dev_t</i></p> 271 272 273<p style="margin-left:14%;"><b>archive_entry_devminor</b>(<i>struct archive_entry *</i>);</p> 274 275 276<p style="margin-left:8%; margin-top: 1em"><i>mode_t</i></p> 277 278 279<p style="margin-left:14%;"><b>archive_entry_filetype</b>(<i>struct archive_entry *</i>);</p> 280 281<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> 282 283 284<p valign="top"><b>archive_entry_fflags</b>(<i>struct archive_entry *</i>, 285<i>unsigned long *set</i>, 286<i>unsigned long *clear</i>);</p> 287 288<p style="margin-left:8%; margin-top: 1em"><i>const char 289*</i></p> 290 291 292<p style="margin-left:14%;"><b>archive_entry_fflags_text</b>(<i>struct archive_entry *</i>);</p> 293 294<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> 295 296 297<p style="margin-left:14%;"><b>archive_entry_free</b>(<i>struct archive_entry *</i>);</p> 298 299<p style="margin-left:8%; margin-top: 1em"><i>const char 300*</i></p> 301 302 303<p style="margin-left:14%;"><b>archive_entry_gname</b>(<i>struct archive_entry *</i>);</p> 304 305<p style="margin-left:8%; margin-top: 1em"><i>const char 306*</i></p> 307 308 309<p style="margin-left:14%;"><b>archive_entry_hardlink</b>(<i>struct archive_entry *</i>);</p> 310 311 312<p style="margin-left:8%; margin-top: 1em"><i>ino_t</i></p> 313 314 315<p style="margin-left:14%;"><b>archive_entry_ino</b>(<i>struct archive_entry *</i>);</p> 316 317 318<p style="margin-left:8%; margin-top: 1em"><i>mode_t</i></p> 319 320 321<p style="margin-left:14%;"><b>archive_entry_mode</b>(<i>struct archive_entry *</i>);</p> 322 323 324<p style="margin-left:8%; margin-top: 1em"><i>time_t</i></p> 325 326 327<p style="margin-left:14%;"><b>archive_entry_mtime</b>(<i>struct archive_entry *</i>);</p> 328 329<p style="margin-left:8%; margin-top: 1em"><i>long</i></p> 330 331 332<p style="margin-left:14%;"><b>archive_entry_mtime_nsec</b>(<i>struct archive_entry *</i>);</p> 333 334<p style="margin-left:8%; margin-top: 1em"><i>unsigned 335int</i></p> 336 337 338<p style="margin-left:14%;"><b>archive_entry_nlink</b>(<i>struct archive_entry *</i>);</p> 339 340<p style="margin-left:8%; margin-top: 1em"><i>struct 341archive_entry *</i></p> 342 343 344<p style="margin-left:14%;"><b>archive_entry_new</b>(<i>void</i>);</p> 345 346<p style="margin-left:8%; margin-top: 1em"><i>const char 347*</i></p> 348 349 350<p style="margin-left:14%;"><b>archive_entry_pathname</b>(<i>struct archive_entry *</i>);</p> 351 352<p style="margin-left:8%; margin-top: 1em"><i>const wchar_t 353*</i></p> 354 355 356<p style="margin-left:14%;"><b>archive_entry_pathname_w</b>(<i>struct archive_entry *</i>);</p> 357 358 359<p style="margin-left:8%; margin-top: 1em"><i>dev_t</i></p> 360 361 362<p style="margin-left:14%;"><b>archive_entry_rdev</b>(<i>struct archive_entry *</i>);</p> 363 364 365<p style="margin-left:8%; margin-top: 1em"><i>dev_t</i></p> 366 367 368<p style="margin-left:14%;"><b>archive_entry_rdevmajor</b>(<i>struct archive_entry *</i>);</p> 369 370 371<p style="margin-left:8%; margin-top: 1em"><i>dev_t</i></p> 372 373 374<p style="margin-left:14%;"><b>archive_entry_rdevminor</b>(<i>struct archive_entry *</i>);</p> 375 376<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> 377 378 379<p style="margin-left:14%;"><b>archive_entry_set_dev</b>(<i>struct archive_entry *</i>, 380<i>dev_t</i>);</p> 381 382<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> 383 384 385<p style="margin-left:14%;"><b>archive_entry_set_devmajor</b>(<i>struct archive_entry *</i>, 386<i>dev_t</i>);</p> 387 388<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> 389 390 391<p style="margin-left:14%;"><b>archive_entry_set_devminor</b>(<i>struct archive_entry *</i>, 392<i>dev_t</i>);</p> 393 394<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> 395 396 397<p style="margin-left:14%;"><b>archive_entry_set_filetype</b>(<i>struct archive_entry *</i>, 398<i>unsigned int</i>);</p> 399 400<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> 401 402 403<p valign="top"><b>archive_entry_set_fflags</b>(<i>struct archive_entry *</i>, 404<i>unsigned long set</i>, 405<i>unsigned long clear</i>);</p> 406 407<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> 408 409 410<p style="margin-left:14%;"><b>archive_entry_set_gid</b>(<i>struct archive_entry *</i>, 411<i>gid_t</i>);</p> 412 413<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> 414 415 416<p style="margin-left:14%;"><b>archive_entry_set_gname</b>(<i>struct archive_entry *</i>, 417<i>const char *</i>);</p> 418 419<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> 420 421 422<p style="margin-left:14%;"><b>archive_entry_set_hardlink</b>(<i>struct archive_entry *</i>, 423<i>const char *</i>);</p> 424 425<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> 426 427 428<p style="margin-left:14%;"><b>archive_entry_set_ino</b>(<i>struct archive_entry *</i>, 429<i>unsigned long</i>);</p> 430 431<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> 432 433 434<p style="margin-left:14%;"><b>archive_entry_set_link</b>(<i>struct archive_entry *</i>, 435<i>const char *</i>);</p> 436 437<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> 438 439 440<p style="margin-left:14%;"><b>archive_entry_set_mode</b>(<i>struct archive_entry *</i>, 441<i>mode_t</i>);</p> 442 443<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> 444 445 446<p style="margin-left:14%;"><b>archive_entry_set_mtime</b>(<i>struct archive_entry *</i>, 447<i>time_t</i>, <i>long nanos</i>);</p> 448 449<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> 450 451 452<p style="margin-left:14%;"><b>archive_entry_set_nlink</b>(<i>struct archive_entry *</i>, 453<i>unsigned int</i>);</p> 454 455<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> 456 457 458<p style="margin-left:14%;"><b>archive_entry_set_pathname</b>(<i>struct archive_entry *</i>, 459<i>const char *</i>);</p> 460 461<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> 462 463 464<p style="margin-left:14%;"><b>archive_entry_set_rdev</b>(<i>struct archive_entry *</i>, 465<i>dev_t</i>);</p> 466 467<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> 468 469 470<p style="margin-left:14%;"><b>archive_entry_set_rdevmajor</b>(<i>struct archive_entry *</i>, 471<i>dev_t</i>);</p> 472 473<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> 474 475 476<p style="margin-left:14%;"><b>archive_entry_set_rdevminor</b>(<i>struct archive_entry *</i>, 477<i>dev_t</i>);</p> 478 479<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> 480 481 482<p style="margin-left:14%;"><b>archive_entry_set_size</b>(<i>struct archive_entry *</i>, 483<i>int64_t</i>);</p> 484 485<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> 486 487 488<p style="margin-left:14%;"><b>archive_entry_set_symlink</b>(<i>struct archive_entry *</i>, 489<i>const char *</i>);</p> 490 491<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> 492 493 494<p style="margin-left:14%;"><b>archive_entry_set_uid</b>(<i>struct archive_entry *</i>, 495<i>uid_t</i>);</p> 496 497<p style="margin-left:8%; margin-top: 1em"><i>void</i></p> 498 499 500<p style="margin-left:14%;"><b>archive_entry_set_uname</b>(<i>struct archive_entry *</i>, 501<i>const char *</i>);</p> 502 503 504<p style="margin-left:8%; margin-top: 1em"><i>int64_t</i></p> 505 506 507<p style="margin-left:14%;"><b>archive_entry_size</b>(<i>struct archive_entry *</i>);</p> 508 509<p style="margin-left:8%; margin-top: 1em"><i>const char 510*</i></p> 511 512 513<p style="margin-left:14%;"><b>archive_entry_sourcepath</b>(<i>struct archive_entry *</i>);</p> 514 515<p style="margin-left:8%; margin-top: 1em"><i>const struct 516stat *</i></p> 517 518 519<p style="margin-left:14%;"><b>archive_entry_stat</b>(<i>struct archive_entry *</i>);</p> 520 521<p style="margin-left:8%; margin-top: 1em"><i>const char 522*</i></p> 523 524 525<p style="margin-left:14%;"><b>archive_entry_symlink</b>(<i>struct archive_entry *</i>);</p> 526 527<p style="margin-left:8%; margin-top: 1em"><i>const char 528*</i></p> 529 530 531<p style="margin-left:14%;"><b>archive_entry_uname</b>(<i>struct archive_entry *</i>);</p> 532 533 534<p style="margin-top: 1em" valign="top"><b>DESCRIPTION</b></p> 535 536<p style="margin-left:8%;">These functions create and 537manipulate data objects that represent entries within an 538archive. You can think of a struct archive_entry as a 539heavy-duty version of struct stat: it includes everything 540from struct stat plus associated pathname, textual group and 541user names, etc. These objects are used by libarchive(3) to 542represent the metadata associated with a particular entry in 543an archive.</p> 544 545<p style="margin-left:8%; margin-top: 1em"><b>Create and 546Destroy</b> <br> 547There are functions to allocate, destroy, clear, and copy 548<i>archive_entry</i> objects:</p> 549 550<p valign="top"><b>archive_entry_clear</b>()</p> 551 552<p style="margin-left:20%;">Erases the object, resetting 553all internal fields to the same state as a newly-created 554object. This is provided to allow you to quickly recycle 555objects without thrashing the heap.</p> 556 557<p valign="top"><b>archive_entry_clone</b>()</p> 558 559<p style="margin-left:20%;">A deep copy operation; all text 560fields are duplicated.</p> 561 562<p valign="top"><b>archive_entry_free</b>()</p> 563 564<p style="margin-left:20%;">Releases the struct 565archive_entry object.</p> 566 567<p valign="top"><b>archive_entry_new</b>()</p> 568 569<p style="margin-left:20%;">Allocate and return a blank 570struct archive_entry object.</p> 571 572<p style="margin-left:8%; margin-top: 1em"><b>Set and Get 573Functions</b> <br> 574Most of the functions here set or read entries in an object. 575Such functions have one of the following forms:</p> 576 577<p valign="top"><b>archive_entry_set_XXXX</b>()</p> 578 579<p style="margin-left:20%;">Stores the provided data in the 580object. In particular, for strings, the pointer is stored, 581not the referenced string.</p> 582 583<p valign="top"><b>archive_entry_copy_XXXX</b>()</p> 584 585<p style="margin-left:20%;">As above, except that the 586referenced data is copied into the object.</p> 587 588<p valign="top"><b>archive_entry_XXXX</b>()</p> 589 590<p style="margin-left:20%;">Returns the specified data. In 591the case of strings, a const-qualified pointer to the string 592is returned.</p> 593 594<p style="margin-left:8%;">String data can be set or 595accessed as wide character strings or normal <i>char</i> 596strings. The functions that use wide character strings are 597suffixed with <b>_w</b>. Note that these are different 598representations of the same data: For example, if you store 599a narrow string and read the corresponding wide string, the 600object will transparently convert formats using the current 601locale. Similarly, if you store a wide string and then store 602a narrow string for the same data, the previously-set wide 603string will be discarded in favor of the new data.</p> 604 605<p style="margin-left:8%; margin-top: 1em">There are a few 606set/get functions that merit additional description:</p> 607 608<p valign="top"><b>archive_entry_set_link</b>()</p> 609 610<p style="margin-left:20%;">This function sets the symlink 611field if it is already set. Otherwise, it sets the hardlink 612field.</p> 613 614<p style="margin-left:8%; margin-top: 1em"><b>File 615Flags</b> <br> 616File flags are transparently converted between a bitmap 617representation and a textual format. For example, if you set 618the bitmap and ask for text, the library will build a 619canonical text format. However, if you set a text format and 620request a text format, you will get back the same text, even 621if it is ill-formed. If you need to canonicalize a textual 622flags string, you should first set the text form, then 623request the bitmap form, then use that to set the bitmap 624form. Setting the bitmap format will clear the internal text 625representation and force it to be reconstructed when you 626next request the text form.</p> 627 628<p style="margin-left:8%; margin-top: 1em">The bitmap 629format consists of two integers, one containing bits that 630should be set, the other specifying bits that should be 631cleared. Bits not mentioned in either bitmap will be 632ignored. Usually, the bitmap of bits to be cleared will be 633set to zero. In unusual circumstances, you can force a 634fully-specified set of file flags by setting the bitmap of 635flags to clear to the complement of the bitmap of flags to 636set. (This differs from fflagstostr(3), which only includes 637names for set bits.) Converting a bitmap to a textual string 638is a platform-specific operation; bits that are not 639meaningful on the current platform will be ignored.</p> 640 641<p style="margin-left:8%; margin-top: 1em">The canonical 642text format is a comma-separated list of flag names. The 643<b>archive_entry_copy_fflags_text</b>() and 644<b>archive_entry_copy_fflags_text_w</b>() functions parse 645the provided text and sets the internal bitmap values. This 646is a platform-specific operation; names that are not 647meaningful on the current platform will be ignored. The 648function returns a pointer to the start of the first name 649that was not recognized, or NULL if every name was 650recognized. Note that every name--including names that 651follow an unrecognized name--will be evaluated, and the 652bitmaps will be set to reflect every name that is 653recognized. (In particular, this differs from 654strtofflags(3), which stops parsing at the first 655unrecognized name.)</p> 656 657<p style="margin-left:8%; margin-top: 1em"><b>ACL 658Handling</b> <br> 659XXX This needs serious help. XXX</p> 660 661<p style="margin-left:8%; margin-top: 1em">An 662‘‘Access Control List’’ (ACL) is a 663list of permissions that grant access to particular users or 664groups beyond what would normally be provided by standard 665POSIX mode bits. The ACL handling here addresses some 666deficiencies in the POSIX.1e draft 17 ACL specification. In 667particular, POSIX.1e draft 17 specifies several different 668formats, but none of those formats include both textual 669user/group names and numeric UIDs/GIDs.</p> 670 671<p style="margin-left:8%; margin-top: 1em">XXX explain ACL 672stuff XXX</p> 673 674<p style="margin-top: 1em" valign="top"><b>SEE ALSO</b></p> 675 676<p style="margin-left:8%;">archive(3)</p> 677 678<p style="margin-top: 1em" valign="top"><b>HISTORY</b></p> 679 680<p style="margin-left:8%;">The <b>libarchive</b> library 681first appeared in FreeBSD 5.3.</p> 682 683<p style="margin-top: 1em" valign="top"><b>AUTHORS</b></p> 684 685<p style="margin-left:8%;">The <b>libarchive</b> library 686was written by Tim Kientzle 687⟨kientzle@acm.org⟩.</p> 688 689 690<p style="margin-left:8%; margin-top: 1em">FreeBSD 9.0 691May 12, 2008 FreeBSD 9.0</p> 692<hr> 693</body> 694</html> 695