classification
Title: Misguiding wording 3.0 c-api reference
Type: Stage:
Components: Documentation Versions: Python 3.0
process
Status: closed Resolution: works for me
Dependencies: Superseder:
Assigned To: georg.brandl Nosy List: ebfe, georg.brandl, ggenellina, loewis, pitrou
Priority: normal Keywords:

Created on 2008-12-25 11:54 by ebfe, last changed 2008-12-29 13:37 by georg.brandl. This issue is now closed.

Messages (7)
msg78281 - (view) Author: Lukas Lueg (ebfe) Date: 2008-12-25 11:54
Quote from http://docs.python.org/3.0/c-api/arg.html, regarding the "s"
argument:

"""
s (string or Unicode object) [const char *]

    Convert a Python string or Unicode object to a C pointer to a
character string. You must not provide storage for the string itself; a
pointer to an existing string is stored into the character pointer
variable whose address you pass. 
"""

I guess the phrase "you must not provide storage" is a failed
translation and not meant like that. It should say "you are not required
to provide storage". It's confusing to have such strong wording without
reason.
msg78288 - (view) Author: Gabriel Genellina (ggenellina) Date: 2008-12-26 01:25
Also, it isn't clear that the returned string must not be modified, 
and that the pointer lifetime is of the original string object itself.
(This applies to all string and unicode formats).
msg78345 - (view) Author: Martin v. Löwis (loewis) * (Python committer) Date: 2008-12-27 08:51
> I guess the phrase "you must not provide storage" is a failed
> translation and not meant like that. It should say "you are not required
> to provide storage". It's confusing to have such strong wording without
> reason.

It's stronger than "you are not required to": if you do provide storage
(by allocating memory), then this memory most likely will be garbage,
and you must not attempt to free it afterwards (as doing so would cause
a crash).
msg78452 - (view) Author: Lukas Lueg (ebfe) Date: 2008-12-29 12:47
Whenever the documentation says "you must not" it really says "don't do
that or your application *will* crash, burn and die"... Of course I can
allocate storage for the string, copy it's content and then free or -
nothing will happen. How would it cause a crash - it's my own pointer.

That's exactly the line between "not required to", "should not" and
"must not": The current wording suggests that I may not even touch e.g.
malloc which is confusing and in fact to be ignored in it's current state.
msg78453 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2008-12-29 13:26
For me, when I read "You must not provide storage for the string
itself", it obviously means I mustn't do so *before calling the
PyArg_ParseTuple function*. It is also obvious that I am allowed to copy
the returned contents wherever I want, and it should be obvious to any C
programmer. So I don't see how the wording is misleading.
msg78454 - (view) Author: Martin v. Löwis (loewis) * (Python committer) Date: 2008-12-29 13:31
> Whenever the documentation says "you must not" it really says "don't do
> that or your application *will* crash, burn and die"... Of course I can
> allocate storage for the string, copy it's content and then free or -
> nothing will happen. How would it cause a crash - it's my own pointer.

Suppose you do

  char *s = malloc(MAXPATH);
  if (!PyArg_ParseTuple("s", &s))return NULL;
  do_something_with(s);
  free(s);

then your application *will* crash, burn, and die - because s gets
changed in the call; the original malloc result is garbage, and the
free call will likely crash the malloc implementation (as the block
it points to wasn't malloc-allocated, and isn't the beginning of a
block).
msg78455 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2008-12-29 13:37
I don't see a reason to keep this open any longer.
History
Date User Action Args
2008-12-29 13:37:19georg.brandlsetstatus: open -> closed
resolution: works for me
messages: + msg78455
2008-12-29 13:31:41loewissetmessages: + msg78454
2008-12-29 13:26:35pitrousetnosy: + pitrou
messages: + msg78453
2008-12-29 12:47:38ebfesetmessages: + msg78452
2008-12-27 08:51:52loewissetnosy: + loewis
messages: + msg78345
2008-12-26 01:25:55ggenellinasetnosy: + ggenellina
messages: + msg78288
2008-12-25 11:54:17ebfecreate