Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

ERRSV is undocumented #13485

Closed
p5pRT opened this issue Dec 21, 2013 · 8 comments
Closed

ERRSV is undocumented #13485

p5pRT opened this issue Dec 21, 2013 · 8 comments

Comments

@p5pRT
Copy link

p5pRT commented Dec 21, 2013

Migrated from rt.perl.org#120841 (status was 'pending release')

Searchable as RT120841$

@p5pRT
Copy link
Author

p5pRT commented Dec 21, 2013

From @bulk88

Created by @bulk88

ERRSV is used extensively in perlcall, yet undocumented in perlapi or
perlintern. The only public API alternative to ERRSV is, "sv =
get_sv("@​", 0);" and that doesn't work if something did a PP "delete
$​::{'@​'};" earlier. Please decide whether it is public api or private
api and document it in perlapi or perlintern.

Perl Info

Flags:
     category=docs
     severity=low

Site configuration information for perl 5.19.7:

Configured by Owner at Thu Nov 28 02:32:44 2013.

Summary of my perl5 (revision 5 version 19 subversion 7) configuration:
   Derived from: 8f47723e28b75530b743941cdd8b07f849ec48e2
   Ancestor: 1061065f7a09399eefb50e9a035502621722bcc0
   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 -O1 -MD -Zi -DNDEBUG -G7 -GL 
-DWIN32 -D_CONSOLE -DNO_STRICT  -DPERL_TEXTMODE_SCRIPTS 
-DPERL_HASH_FUNC_ONE_AT_A_TIME -DPERL_IMPLICIT_CONTEXT 
-DPERL_IMPLICIT_SYS -DUSE_PERLIO -D_USE_32BIT_TIME_T',
     optimize='-O1 -MD -Zi -DNDEBUG -G7 -GL',
     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:\perl519\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=perl519.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:\perl519\lib\CORE"  -machine:x86'

Locally applied patches:
     uncommitted-changes
     8f47723e28b75530b743941cdd8b07f849ec48e2


@INC for perl 5.19.7:
     C:/perl519/site/lib
     C:/perl519/lib
     .


Environment for perl 5.19.7:
     HOME (unset)
     LANG (unset)
     LANGUAGE (unset)
     LD_LIBRARY_PATH (unset)
     LOGDIR (unset)
     PATH=C:\perl519\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)

@p5pRT
Copy link
Author

p5pRT commented Oct 6, 2015

From @jkeenan

On Sat Dec 21 15​:05​:50 2013, bulk88 wrote​:

This is a bug report for perl from bulk88@​hotmail.com,
generated with the help of perlbug 1.39 running under perl 5.19.7.

-----------------------------------------------------------------
[Please describe your issue here]

ERRSV is used extensively in perlcall, yet undocumented in perlapi or
perlintern. The only public API alternative to ERRSV is, "sv =
get_sv("@​", 0);" and that doesn't work if something did a PP "delete
$​::{'@​'};" earlier. Please decide whether it is public api or private
api and document it in perlapi or perlintern.

This ticket has received no comments since it was filed in Dec 2013. But documenting aspects of the API is A Good Thing.

Is there anyone who could supply a patch?

Thank you very much.

--
James E Keenan (jkeenan@​cpan.org)

@p5pRT
Copy link
Author

p5pRT commented Oct 6, 2015

The RT System itself - Status changed from 'new' to 'open'

@p5pRT
Copy link
Author

p5pRT commented Oct 6, 2015

From @iabyn

On Sat, Dec 21, 2013 at 03​:05​:50PM -0800, bulk88 wrote​:

ERRSV is used extensively in perlcall, yet undocumented in perlapi or
perlintern. The only public API alternative to ERRSV is, "sv =
get_sv("@​", 0);" and that doesn't work if something did a PP "delete
$​::{'@​'};" earlier. Please decide whether it is public api or private
api and document it in perlapi or perlintern.

Well its used in several examples in perlcall.pod and elsewhere, so I
think it needs to be regarded as part of the API.

Do you want to contribute a pod entry? Perhaps one for CLEAR_ERRSV() too?

--
A power surge on the Bridge is rapidly and correctly diagnosed as a faulty
capacitor by the highly-trained and competent engineering staff.
  -- Things That Never Happen in "Star Trek" #9

@p5pRT
Copy link
Author

p5pRT commented Jul 4, 2019

From @tonycoz

On Tue, 06 Oct 2015 03​:57​:18 -0700, davem wrote​:

On Sat, Dec 21, 2013 at 03​:05​:50PM -0800, bulk88 wrote​:

ERRSV is used extensively in perlcall, yet undocumented in perlapi or
perlintern. The only public API alternative to ERRSV is, "sv =
get_sv("@​", 0);" and that doesn't work if something did a PP "delete
$​::{'@​'};" earlier. Please decide whether it is public api or private
api and document it in perlapi or perlintern.

Well its used in several examples in perlcall.pod and elsewhere, so I
think it needs to be regarded as part of the API.

Do you want to contribute a pod entry? Perhaps one for CLEAR_ERRSV() too?

Patch attached.

I also documented the errno handling macros for internal use.

Tony

@p5pRT
Copy link
Author

p5pRT commented Jul 4, 2019

From @tonycoz

120841-errsv-docs.patch
From 69233ba97da0fb4c228c7c11c673c95a85698572 Mon Sep 17 00:00:00 2001
From: Tony Cook <tony@develop-help.com>
Date: Thu, 4 Jul 2019 10:39:19 +1000
Subject: (perl #120841) document ERRSV and CLEAR_ERRSV()

---
 perl.h | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/perl.h b/perl.h
index a82d055733..6ca32893fb 100644
--- a/perl.h
+++ b/perl.h
@@ -1335,6 +1335,22 @@ EXTERN_C char *crypt(const char *, const char *);
 #   define RESTORE_ERRNO  (errno = saved_errno)
 #endif
 
+/*
+=head1 Warning and Dieing
+
+=for apidoc Amn|SV *|ERRSV
+
+Returns the SV for C<$@>, creating it if needed.
+
+=for apidoc Am|void|CLEAR_ERRSV
+
+Clear the contents of C<$@>, setting it to the empty string.
+
+This replaces any read-only SV with a fresh SV and removes any magic.
+
+=cut
+*/
+
 #define ERRSV GvSVn(PL_errgv)
 
 /* contains inlined gv_add_by_type */
-- 
2.11.0


From ecc05fa56fca41a1bb892a62e4d7fb0183ddee5a Mon Sep 17 00:00:00 2001
From: Tony Cook <tony@develop-help.com>
Date: Thu, 4 Jul 2019 11:12:20 +1000
Subject: (perl #120841) document some errno macros for internal use

---
 perl.h | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/perl.h b/perl.h
index 6ca32893fb..e75ca078a9 100644
--- a/perl.h
+++ b/perl.h
@@ -1264,6 +1264,38 @@ EXTERN_C char *crypt(const char *, const char *);
 EXTERN_C char *crypt(const char *, const char *);
 #endif
 
+/*
+=head2 Errno
+
+=for apidoc m|void|SETERRNO|int errcode|int vmserrcode
+
+Set C<errno>, and on VMS set C<vaxc$errno>.
+
+=for apidoc mn|void|dSAVEDERRNO
+
+Declare variables needed to save C<errno> and any operating system
+specific error number.
+
+=for apidoc mn|void|dSAVE_ERRNO
+
+Declare variables needed to save C<errno> and any operating system
+specific error number, and save them for optional later restoration
+by C<RESTORE_ERRNO>.
+
+=for apidoc mn|void|SAVE_ERRNO
+
+Save C<errno> and any operating system specific error number for
+optional later restoration by C<RESTORE_ERRNO>.  Requires
+C<dSAVEDERRNO> or C<dSAVE_ERRNO> in scope.
+
+=for apidoc mn|RESTORE_ERRNO
+
+Restore C<errno> and any operating system specific error number that
+was saved by C<dSAVE_ERRNO> or C<RESTORE_ERRNO>.
+
+=cut
+*/
+
 #ifdef SETERRNO
 # undef SETERRNO  /* SOCKS might have defined this */
 #endif
-- 
2.11.0

@p5pRT
Copy link
Author

p5pRT commented Jul 8, 2019

From @tonycoz

On Wed, 03 Jul 2019 18​:37​:43 -0700, tonyc wrote​:

On Tue, 06 Oct 2015 03​:57​:18 -0700, davem wrote​:

On Sat, Dec 21, 2013 at 03​:05​:50PM -0800, bulk88 wrote​:

ERRSV is used extensively in perlcall, yet undocumented in perlapi or
perlintern. The only public API alternative to ERRSV is, "sv =
get_sv("@​", 0);" and that doesn't work if something did a PP "delete
$​::{'@​'};" earlier. Please decide whether it is public api or private
api and document it in perlapi or perlintern.

Well its used in several examples in perlcall.pod and elsewhere, so I
think it needs to be regarded as part of the API.

Do you want to contribute a pod entry? Perhaps one for CLEAR_ERRSV() too?

Patch attached.

I also documented the errno handling macros for internal use.

That errno handling documentation had an error, which I've fixed, pushed the ERRSV docs as 40bec30, the fixed errno handling macro docs as 131e494 and an update to apidoc.pl to make it complain a little more loudly in 256dda5.

Tony

@p5pRT
Copy link
Author

p5pRT commented Jul 8, 2019

@tonycoz - Status changed from 'open' to 'pending release'

@p5pRT p5pRT closed this as completed Jul 8, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant