Bug 177429 - dd(1) man page is unclear about semantics of conv=sync
Summary: dd(1) man page is unclear about semantics of conv=sync
Status: Open
Alias: None
Product: Documentation
Classification: Unclassified
Component: Manual Pages (show other bugs)
Version: Latest
Hardware: Any Any
: Normal Affects Only Me
Assignee: freebsd-bugs (Nobody)
URL:
Keywords: patch
Depends on:
Blocks:
 
Reported: 2013-03-28 03:30 UTC by Ronald F. Guilmette
Modified: 2021-10-02 01:21 UTC (History)
4 users (show)

See Also:


Attachments
dd(1) patch (628 bytes, patch)
2021-10-02 01:20 UTC, Felix Johnson
felix.the.red: maintainer-approval? (felix.the.red)
Details | Diff

Note You need to log in before you can comment on or make changes to this bug.
Description Ronald F. Guilmette 2013-03-28 03:30:00 UTC
The man page for dd(1) describes the "sync" parameter of the "conv=" option
thusly:

              sync     Pad every input block to the input buffer size.  Spaces
                       are used for pad bytes if a block oriented conversion
                       value is specified, otherwise NUL bytes are used.

This verbage is entirely unclear. What is a "block oriented conversion value"
and how would a user know whether or not he had specified one?

The man page should make this more clear & explicit.

Fix: 

I don't know what the fix is because I don't have the vaguest idea what a
"block oriented conversion value" is.
How-To-Repeat: 
man 1 dd
Comment 1 Peter Pentchev 2013-03-29 13:18:35 UTC
Well, the "conversion value" is the set of all parameters that you have
supplied to "conv" - you can supply more than one using commas.  And I
think that "block-oriented" should mean that some of the things that you
have specified say that the output should be in blocks - either that it
is in blocks by default (and you have *not* requested unblocking it by
using "ascii", "oldascii" or "unblock"), or that you've requested that
dd(1) make it into blocks using one of the "block", "ebcdic", "ibm",
"oldebcdic" and "oldibm" conversion specifiers.

Of course, I could be wrong, but that's how I myself understand the
manual page.

G'luck,
Peter

-- 
Peter Pentchev	roam@ringlet.net roam@FreeBSD.org p.penchev@storpool.com
PGP key:	http://people.FreeBSD.org/~roam/roam.key.asc
Key fingerprint 2EE7 A7A5 17FC 124C F115  C354 651E EFB0 2527 DF13
No language can express every thought unambiguously, least of all this one.
Comment 2 Ronald F. Guilmette 2013-03-29 20:56:51 UTC
In message <20130329131835.GA15952@straylight.m.ringlet.net>, you wrote:

>Of course, I could be wrong, but that's how I myself understand the
>manual page.

Thank you, but I think that the important point here is that the man
page should be clear about all this, so that people can use the tool
without guessing as to the semantics, and without having to rely on
additional sources of information about the semantics (e.g. the source
code).


Regards,
rfg
Comment 3 Eitan Adler freebsd_committer freebsd_triage 2017-12-31 07:59:16 UTC
For bugs matching the following criteria:

Status: In Progress Changed: (is less than) 2014-06-01

Reset to default assignee and clear in-progress tags.

Mail being skipped
Comment 4 Bruce Lilly 2021-02-26 15:53:40 UTC
The POSIX man page is informative:
https://www.unix.com/man-page/posix/1posix/dd/
Comment 5 Felix Johnson freebsd_triage 2021-10-02 01:20:11 UTC
Created attachment 228338 [details]
dd(1) patch

After reading the source code, the sync option has three possible characters to pad the input block with. First is the user-specified value of fillchar; second is a space when block, noblock, ascii, ebcidic, or their synonyms are specified; and a NUL character otherwise.

Document this behavior by updating dd(1).