Menu

#1279 Man Page: POST --data<space><data> space is wrong

closed-fixed
5
2013-09-13
2013-09-12
No

In curl version 7.24.0, in Mac OS X 10.8, in the man page, the examples given for the -POST data options: d, -data etc. all have a space between the option and the data. Example: --data <data>. When I do this, it doesn't work. The server gets the data "ata". I noticed that these three characters were the last three characters in the option "data". So I tried it without the space, -d<data>, and it worked.

Discussion

  • Jerry Krinock

    Jerry Krinock - 2013-09-12

    Arghhh! Looks like the server has an HTML filter which removed the greater-than and less-than in my report, so it doesn't make any sense. Please disregard the original and read this instead. [ = less than ] = greater than

    In curl version 7.24.0, in Mac OS X, in the man page, the examples given for the -POST data options: d, -data etc. all have a space between the option and the data. Example: --data [data]. When I do this, it doesn't work. The server gets the data "ata". I noticed that these three characters were the last three characters in the option "data". So I tried it without the space, -d[data], and it worked.

     
  • Dan Fandrich

    Dan Fandrich - 2013-09-13

    I'm confused by this report. You seem to be interchanging one dash, two dashes and no dashes indiscriminently. The number of dashes is critical: -d is not the same as --dash which is not the same as d. --data DATA works fine, as does -dDATA but -data DATA is not going to do what you want. Please double-check your arguments with the documentation and and if it still doesn't work, please let us know.

     
  • Jerry Krinock

    Jerry Krinock - 2013-09-13

    Hello, Dan. Thanks for taking on the issue.

    First of all, there is not a zero-dash version of the option. I just left it out for brevity. There are only one-dash and two-dash versions.

    Indeed, I am interchanging these indiscriminately because that's what the man page does. Here are the three examples given in the man page. They take 5 lines because two of them have a line feed in the middle.

    -d, --data [data]
    '-d name=daniel -d
    skill=lousy'
    --data @foo-
    bar

    There is no explanation in the text of whether or not to use a space between the option and the data, so the only guidance the reader has is the examples, which all have a space (or a line ending).

    Reading from your examples, I think you are telling me that the one-dash options should not have a space before the data, but the two-dash options should have a space before the data. Whatever the rule is, the documentation should state it. That's the issue.

    Thanks!

    Jerry

     
  • Daniel Stenberg

    Daniel Stenberg - 2013-09-13

    In the documentation we always encourage using a space between and that works the same even if you use -d or --data.

    The fact that you can merge short options together with its following argument is more of a generic command line parser feature and I think it should probably be documented at the top of the document describing how options are used in general with curl.

     
  • Jerry Krinock

    Jerry Krinock - 2013-09-13

    Hello Daniel. I agree that documenting at the top of the file would be OK if all options worked the same. However, in my test case the space is causing a failure. Please examine the following transcript. I invoked curl three times with the same arguments each time, passing POST data from a file.

    1. -data, with space. Result: error (7)
    2. -data, no space. Result: Success.
    3. -d, no space. Result: Success.

    Air2:live jk$ curl -data @/Users/jk/Documents/SheepSystems/sheepsystems.com/public_html/cgi-bin/TestData/FreebiePOST.txt http://sheepsystems.com/cgi-bin/test/ProcessOrderTest.pl
    curl: (7) couldn't connect to host
    Air2:live jk$ curl -data@/Users/jk/Documents/SheepSystems/sheepsystems.com/public_html/cgi-bin/TestData/FreebiePOST.txt http://sheepsystems.com/cgi-bin/test/ProcessOrderTest.pl
    Air2:live jk$ curl -d@/Users/jk/Documents/SheepSystems/sheepsystems.com/public_html/cgi-bin/TestData/FreebiePOST.txt http://sheepsystems.com/cgi-bin/test/ProcessOrderTest.pl
    Air2:live jk$

     
  • Daniel Stenberg

    Daniel Stenberg - 2013-09-13

    -data (with one dash) is the same as -d ata. One dash says it is a short option, and short options are single-letter. Short options don't need a space to separate the following argument since it is always a single letter we know if there's anything "tacked on".

    The long option (with two dashes) has multiple letters and one option can have the same name as the beginning of another so we can't have them specified combined: a long option must be specified with a space before the following argument.

    Using -data (with one dash) in any example or documentation is highly confusing.

     
  • Jerry Krinock

    Jerry Krinock - 2013-09-13

    Thanks again, Daniel. The main problem was that it was too late last night and I thought there was a "-data" form of the option which there is not. That led me down the rabbit hole. Also, I see how the correct number of spaces is obvious if you think about it. If you'd like to accommodate people who don't think very well all of the time, I suggest that something like the following paragraph be added to the man page…

    The short "single-dash" form of the options, -d for example, may be used with or without a space between it and its value, although a space is recommended. The long "double-dash" form, --data for example, requires a space between it and its value.

     
  • Daniel Stenberg

    Daniel Stenberg - 2013-09-13
    • status: open --> closed-fixed
    • assigned_to: Daniel Stenberg
     
  • Daniel Stenberg

    Daniel Stenberg - 2013-09-13

    Thanks for that! I took your suggestion as a basis and expanded it somewhat and I've pushed this change: https://github.com/bagder/curl/commit/0a691f8935f49249c71f8926bbbdb9053096bfe7

    It will be visible in the online version of the man page within the hour.

    I hereby consider this case closed!