| Summary: | libtar manpages need improvement | ||
|---|---|---|---|
| Product: | [Fedora] Fedora | Reporter: | Denys Vlasenko <dvlasenk> |
| Component: | libtar | Assignee: | Huzaifa S. Sidhpurwala <huzaifas> |
| Status: | CLOSED WONTFIX | QA Contact: | Fedora Extras Quality Assurance <extras-qa> |
| Severity: | unspecified | Docs Contact: | |
| Priority: | unspecified | ||
| Version: | 15 | CC: | huzaifas, kdudka |
| Target Milestone: | --- | ||
| Target Release: | --- | ||
| Hardware: | Unspecified | ||
| OS: | Unspecified | ||
| Whiteboard: | |||
| Fixed In Version: | Doc Type: | Bug Fix | |
| Doc Text: | Story Points: | --- | |
| Clone Of: | Environment: | ||
| Last Closed: | Type: | --- | |
| Regression: | --- | Mount Type: | --- |
| Documentation: | --- | CRM: | |
| Verified Versions: | Category: | --- | |
| oVirt Team: | --- | RHEL 7.3 requirements from Atomic Host: | |
| Cloudforms Team: | --- | Target Upstream Version: | |
(In reply to comment #0) > In general, a small example in this man page (say, one which creates a tarball > with a few files of different types) would be VERY helpful. Sounds like we might package libtar.c to be installed as part of libtar-devel as an example: http://libtar.sourcearchive.com/lines/1.2.11/libtar_8c-source.html (In reply to comment #1) > (In reply to comment #0) > > In general, a small example in this man page (say, one which creates a tarball > > with a few files of different types) would be VERY helpful. > > Sounds like we might package libtar.c to be installed as part of libtar-devel > as an example: > > http://libtar.sourcearchive.com/lines/1.2.11/libtar_8c-source.html This file uses more high-level part of the API (tar_append_tree function) to append files to the archive. Functions on "man th_set_type" manpage are more low level. I needed to use *those* functions, not tar_append_tree, that's why I went to that manpage. This message is a notice that Fedora 15 is now at end of life. Fedora has stopped maintaining and issuing updates for Fedora 15. It is Fedora's policy to close all bug reports from releases that are no longer maintained. At this time, all open bugs with a Fedora 'version' of '15' have been closed as WONTFIX. (Please note: Our normal process is to give advanced warning of this occurring, but we forgot to do that. A thousand apologies.) Package Maintainer: If you wish for this bug to remain open because you plan to fix it in a currently maintained version, feel free to reopen this bug and simply change the 'version' to a later Fedora version. Bug Reporter: Thank you for reporting this issue and we are sorry that we were unable to fix it before Fedora 15 reached end of life. If you would still like to see this bug fixed and are able to reproduce it against a later version of Fedora, you are encouraged to click on "Clone This Bug" (top right of this page) and open it against that version of Fedora. Although we aim to fix as many bugs as possible during every release's lifetime, sometimes those efforts are overtaken by events. Often a more recent Fedora release includes newer upstream software that fixes bugs or makes them obsolete. The process we are following is described here: http://fedoraproject.org/wiki/BugZappers/HouseKeeping This message is a notice that Fedora 15 is now at end of life. Fedora has stopped maintaining and issuing updates for Fedora 15. It is Fedora's policy to close all bug reports from releases that are no longer maintained. At this time, all open bugs with a Fedora 'version' of '15' have been closed as WONTFIX. (Please note: Our normal process is to give advanced warning of this occurring, but we forgot to do that. A thousand apologies.) Package Maintainer: If you wish for this bug to remain open because you plan to fix it in a currently maintained version, feel free to reopen this bug and simply change the 'version' to a later Fedora version. Bug Reporter: Thank you for reporting this issue and we are sorry that we were unable to fix it before Fedora 15 reached end of life. If you would still like to see this bug fixed and are able to reproduce it against a later version of Fedora, you are encouraged to click on "Clone This Bug" (top right of this page) and open it against that version of Fedora. Although we aim to fix as many bugs as possible during every release's lifetime, sometimes those efforts are overtaken by events. Often a more recent Fedora release includes newer upstream software that fixes bugs or makes them obsolete. The process we are following is described here: http://fedoraproject.org/wiki/BugZappers/HouseKeeping |
I needed to code up a small program which crates a tarball. I looked at libtar manpages and they are rather bad. For example, try "man tar_open". It documents: int tar_open(TAR **t, char *pathname, tartype_t *type, int oflags, int mode, int options); int tar_fdopen(TAR **t, int fd, char *pathname, tartype_t *type, int oflags, int mode, int options); int tar_fd(TAR *t");" int tar_close(TAR *t");" Ignore for a second broken ");" at the end of tar_close. There is a bigger problem: SEE ALSO open(2), close(2), calloc(3) Why "SEE ALSO" doesn't mention other tar_FOO functions? How user is going to know which functions exist? Now try "man th_write": ================================= SYNOPSIS #include <libtar.h> int th_read(TAR *t); int th_write(TAR *t); VERSION This man page documents version 1.2 of libtar. DESCRIPTION The th_read() function reads the next block from the tar archive associated with the TAR handle t. It then sets the current tar header associated with t to the contents of the block read. The th_write() function writes the contents of the current tar header associated with t to the tar archive associated with t. ================================= What is "current tar header associated with t"? It is explained, yes, but not in *this* manpage! For some reason, he explanation is in *tar_open* manpage! To be exact, this text needs to be copied to th_write manpage, into DESCRIPTION: "The TAR handle contains a file header structure. When reading a tar archive, this structure contains the last file header read from the tar archive. When writing a tar archive, this structure is used as a staging area to construct the next file header to be written to the archive." Now try "man th_set_type": ================================= SYNOPSIS #include <libtar.h> void th_set_from_stat(TAR *t, struct stat *s); void th_set_type(TAR *t, mode_t mode); void th_set_path(TAR *t, char *pathname); void th_set_link(TAR *t, char *linkname); void th_set_device(TAR *t, dev_t device); void th_set_user(TAR *t, uid_t uid); void th_set_group(TAR *t, gid_t gid); void th_set_mode(TAR *t, mode_t mode); void th_set_mtime(TAR *t, time_t fmtime); void th_set_size(TAR *t, off_t fsize); void th_finish(TAR *t); VERSION This man page documents version 1.2 of libtar. DESCRIPTION The th_set_*() functions each set an individual field of the current tar header associated with the TAR handle t. The th_set_user() and th_set_group() functions set both the numeric user/group ID fields and the user/group name text fields. The other functions set only the field that they refer to. ================================== Well. I have a question which this manpage does not answer - how to use these functions in real world usage. If I just wrote out a file to the tarball, how do I *reset the header so that it doesn't contain any stray data from that file*? Say, if I wrote out a symlink (file with non-empty th_set_link), do I need to clear link name if the next file I plan to write out is not a symlink? If yes, how? th_set_link(t, NULL)? th_set_link(t, "")? Same question for th_set_device... In general, a small example in this man page (say, one which creates a tarball with a few files of different types) would be VERY helpful.