Skip Menu |
Report information
Id: 116286
Status: pending release
Priority: 0/
Queue: perl5

Owner: Nobody
Requestors: bulk88 <bulk88 [at] hotmail.com>
Cc:
AdminCc:

Operating System: mswin32
PatchStatus: (no value)
Severity: low
Type: docs
Perl Version: 5.17.7
Fixed In: (no value)



Subject: *pvs SV functions don't take "const char*"s
Date: Thu, 3 Jan 2013 14:21:28 -0500
To: perlbug [...] perl.org
From: bulk88 <bulk88 [...] hotmail.com>
Download (untitled) / with headers
text/plain 4.4k
This is a bug report for perl from bulk88@hotmail.com, generated with the help of perlbug 1.39 running under perl 5.17.7. ----------------------------------------------------------------- [Please describe your issue here] perlapi shows prototypes to the *pvs family of functions, like newSVpvs Show quoted text
________________________________________________________________ newSVpvs Like "newSVpvn", but takes a literal string instead of a string/length pair. SV* newSVpvs(const char* s)
________________________________________________________________ another example is sv_setpvs
_______________________________________________________________ sv_setpvs Like sv_setpvn , but takes a literal string instead of a string/length pair. void sv_setpvs(SV* sv, const char* s)
_______________________________________________________________ The 2 quotes are from 2 different pod viewers. The description says "literal string", but the prototype makes you think you can pass a char * if you don't read the description. I'm not sure how this can be made better. would a "const char s []" be any better? would that work embed.fnc and actual C code? Should "literal string" be reworded in the *pvs funcs' POD to make it more clear it is not a char *? One idea I have is SV* newSVpvs("literal string") Overall, the *pvs functions POD are just unclear to someone new. [Please do not change anything below this line] ----------------------------------------------------------------- --- Flags: category=docs severity=low --- Site configuration information for perl 5.17.7: Configured by Owner at Sun Dec 16 13:25:34 2012. Summary of my perl5 (revision 5 version 17 subversion 7 patch blead 2012-12-06.16:42:20 93a641ae382638ffd1980378be4810244d04f4b0 v5.17.6-186-g93a641a) configuration: Snapshot of: 93a641ae382638ffd1980378be4810244d04f4b0 Platform: osname=MSWin32, osvers=5.1, archname=MSWin32-x86-multi-thread uname='' config_args='undef' hint=recommended, useposix=true, d_sigaction=undef useithreads=define, usemultiplicity=define useperlio=define, d_sfio=undef, uselargefiles=define, usesocks=undef use64bitint=undef, use64bitall=undef, uselongdouble=undef usemymalloc=n, bincompat5005=undef Compiler: cc='cl', ccflags ='-nologo -GF -W3 -MD -Zi -DNDEBUG -O1 -GL -G7 -DWIN32 -D_CONSOLE -DNO_STRICT -DPERL_TEXTMODE_SCRIPTS -DPERL_IMPLICIT_CONTEXT -DPERL_IMPLICIT_SYS -DUSE_PERLIO -D_USE_32BIT_TIME_T', optimize='-MD -Zi -DNDEBUG -O1 -GL -G7', cppflags='-DWIN32' ccversion='13.10.6030', gccversion='', gccosandvers='' intsize=4, longsize=4, ptrsize=4, doublesize=8, byteorder=1234 d_longlong=undef, longlongsize=8, d_longdbl=define, longdblsize=8 ivtype='long', ivsize=4, nvtype='double', nvsize=8, Off_t='__int64', lseeksize=8 alignbytes=8, prototype=define Linker and Libraries: ld='link', ldflags ='-nologo -nodefaultlib -debug -opt:ref,icf -ltcg -libpath:"c:\perl517\lib\CORE" -machine:x86' libpth="C:\Program Files\Microsoft Visual Studio .NET 2003\VC7\lib" libs=oldnames.lib kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib netapi32.lib uuid.lib ws2_32.lib mpr.lib winmm.lib version.lib odbc32.lib odbccp32.lib comctl32.lib msvcrt.lib perllibs=oldnames.lib kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib netapi32.lib uuid.lib ws2_32.lib mpr.lib winmm.lib version.lib odbc32.lib odbccp32.lib comctl32.lib msvcrt.lib libc=msvcrt.lib, so=dll, useshrplib=true, libperl=perl517.lib gnulibc_version='' Dynamic Linking: dlsrc=dl_win32.xs, dlext=dll, d_dlsymun=undef, ccdlflags=' ' cccdlflags=' ', lddlflags='-dll -nologo -nodefaultlib -debug -opt:ref,icf -ltcg -libpath:"c:\perl517\lib\CORE" -machine:x86' Locally applied patches: --- @INC for perl 5.17.7: C:/perl517/site/lib C:/perl517/lib . --- Environment for perl 5.17.7: HOME (unset) LANG (unset) LANGUAGE (unset) LD_LIBRARY_PATH (unset) LOGDIR (unset) PATH=C:\perl517\bin;C:\Program Files\Microsoft Visual Studio .NET 2003\Common7\IDE;C:\Program Files\Microsoft Visual Studio .NET 2003\VC7\BIN;C:\Program Files\Microsoft Visual Studio .NET 2003\Common7\Tools;C:\Program Files\Microsoft Visual Studio .NET 2003\Common7\Tools\bin\prerelease;C:\WINDOWS\system32;C:\WINDOWS;C:\WINDOWS\system32\wbem; PERL_BADLANG (unset) SHELL (unset)
Date: Sun, 12 Nov 2017 06:10:39 +0000
Subject: Re: [perl #116286] *pvs SV functions don't take "const char*"s
To: perl5-porters [...] perl.org
From: Zefram <zefram [...] fysh.org>
Download (untitled) / with headers
text/plain 645b
I concur that the use of a "const char *" type for these parameters is misleading. In fact, showing any function prototype is misleading, because these are macros and cannot be implemented as functions. In commit 1568d13a11564a7d9d62aaf6a79b9b04172a2a45 I've changed it so that these parameters are shown with a string literal in place of a type, which should be clear enough. For example, perlapi now shows SV** hv_fetchs(HV* tb, "literal string" key, I32 lval) I also removed the inaccurate words "NUL-terminated" from the prose descriptions of these parameters. -zefram
Date: Sun, 12 Nov 2017 09:10:31 +0100
Subject: Re: [perl #116286] *pvs SV functions don't take "const char*"s
To: Zefram <zefram [...] fysh.org>, perl5-porters [...] perl.org
From: Sawyer X <xsawyerx [...] gmail.com>
Download (untitled) / with headers
text/plain 928b
On 11/12/2017 07:10 AM, Zefram wrote: Show quoted text
> I concur that the use of a "const char *" type for these parameters > is misleading. In fact, showing any function prototype is misleading, > because these are macros and cannot be implemented as functions. > In commit 1568d13a11564a7d9d62aaf6a79b9b04172a2a45 I've changed it so > that these parameters are shown with a string literal in place of a type, > which should be clear enough. For example, perlapi now shows > > SV** hv_fetchs(HV* tb, "literal string" key, > I32 lval)
I think it would be good to have it say what "literal string" refers to, or to have an example. That could help clarify how one could use it, because when someone wants to send something, they are probably getting it from a variable and will not understand which variable type is "literal string" (though they could infer/guess/assume).
Subject: Re: [perl #116286] *pvs SV functions don't take "const char*"s
Date: Sun, 12 Nov 2017 08:44:08 +0000
From: Zefram <zefram [...] fysh.org>
To: perl5-porters [...] perl.org
Download (untitled) / with headers
text/plain 458b
Sawyer X wrote: Show quoted text
>I think it would be good to have it say what "literal string" refers to,
It does. The prose of that very perlapi entry says Like "hv_fetch", but takes a literal string instead of a string/length pair. This ticket started by considering someone who glances at the prototype and *hasn't* read the prose. Apart from the nonsensical reference to "NUL-terminated" literals, the prose was already fine. -zefram


This service is sponsored and maintained by Best Practical Solutions and runs on Perl.org infrastructure.

For issues related to this RT instance (aka "perlbug"), please contact perlbug-admin at perl.org