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

Documentation error #688

Closed
p5pRT opened this issue Oct 7, 1999 · 5 comments
Closed

Documentation error #688

p5pRT opened this issue Oct 7, 1999 · 5 comments

Comments

@p5pRT
Copy link

p5pRT commented Oct 7, 1999

Migrated from rt.perl.org#1586 (status was 'resolved')

Searchable as RT1586$

@p5pRT
Copy link
Author

p5pRT commented Oct 7, 1999

From brian@chele.cais.net

Documentation for setpgrp is incorrect. From perldoc -f setpgrp​:

Sets the current process group for the specified PID, 0 for the current
process. Will produce a fatal error if used on a machine that doesn't
implement setpgrp(2). If the arguments are omitted, it defaults to
0,0. Note that the POSIX version of setpgrp() does not accept any
arguments, so only setpgrp 0,0 is portable.

setpgrp() is not, in fact, a POSIX.1 function, it is SVID derived.
setpgid() is the posix function. You might also document that
setpgrp(a,b) is bsd syntax, and setpgrp(noargs) is BSD4.3 (or is it
4.2, i'm not 100% sure) syntax.

Perl Info


Site configuration information for perl 5.00404:

Configured by stevec at Wed Jul  8 01:35:11 EDT 1998.

Summary of my perl5 (5.0 patchlevel 4 subversion 4) configuration:
  Platform:
    osname=solaris, osvers=2.6, archname=sun4-solaris
    uname='sunos 5.6 generic sun4u sparc sunw,ultra-1 '
    hint=recommended, useposix=true, d_sigaction=define
    bincompat3=y useperlio=undef d_sfio=undef
  Compiler:
    cc='gcc', optimize='-O', gccversion=2.8.1
    cppflags='-I/usr/local/include'
    ccflags ='-I/usr/local/include'
    stdchar='unsigned char', d_stdstdio=define, usevfork=false
    voidflags=15, castflags=0, d_casti32=define, d_castneg=define
    intsize=4, alignbytes=8, usemymalloc=y, prototype=define
  Linker and Libraries:
    ld='gcc', ldflags =' -L/usr/local/lib'
    libpth=/usr/local/lib /lib /usr/lib /usr/ccs/lib
    libs=-lsocket -lnsl -ldl -lm -lc -lcrypt
    libc=/lib/libc.so, so=so
    useshrplib=false, libperl=libperl.a
  Dynamic Linking:
    dlsrc=dl_dlopen.xs, dlext=so, d_dlsymun=undef, ccdlflags=' '
    cccdlflags='-fpic', lddlflags='-G -L/usr/local/lib'

Locally applied patches:
	


@INC for perl 5.00404:
	/usr/local/lib/perl5/sun4-solaris/5.00404
	/usr/local/lib/perl5
	/usr/local/lib/perl5/site_perl/sun4-solaris
	/usr/local/lib/perl5/site_perl
	.


Environment for perl 5.00404:
    HOME=/home2/brian
    LANG (unset)
    LD_LIBRARY_PATH (unset)
    LOGDIR (unset)
    PATH=/usr/ucb:/usr/local/bin:/bin:/usr/ccs/bin:/usr/bin:/etc:/usr/sbin:.
    PERL_BADLANG (unset)
    SHELL=/bin/tcsh

@p5pRT
Copy link
Author

p5pRT commented Oct 7, 1999

From @gsar

On Thu, 07 Oct 1999 10​:30​:23 EDT, Brian Mitchell wrote​:

Documentation for setpgrp is incorrect. From perldoc -f setpgrp​:

Sets the current process group for the specified PID, 0 for the current
process. Will produce a fatal error if used on a machine that doesn't
implement setpgrp(2). If the arguments are omitted, it defaults to
0,0. Note that the POSIX version of setpgrp() does not accept any
arguments, so only setpgrp 0,0 is portable.

setpgrp() is not, in fact, a POSIX.1 function, it is SVID derived.
setpgid() is the posix function. You might also document that
setpgrp(a,b) is bsd syntax, and setpgrp(noargs) is BSD4.3 (or is it
4.2, i'm not 100% sure) syntax.

Thanks. Let me know if this edit doesn't get it right.

Sarathy
gsar@​activestate.com

Inline Patch
-----------------------------------8<-----------------------------------
Change 4310 by gsar@auger on 1999/10/07 23:51:38

	fix setpgrp vs getpgrp and POSIX vs BSD confusion (spotted by
	Brian Mitchell <brian@chele.cais.net>)

Affected files ...

... //depot/perl/pod/perldiag.pod#99 edit
... //depot/perl/pod/perlfunc.pod#107 edit
... //depot/perl/pp_sys.c#118 edit

Differences ...

==== //depot/perl/pod/perldiag.pod#99 (text) ====
Index: perl/pod/perldiag.pod
--- perl/pod/perldiag.pod.~1~	Thu Oct  7 16:51:43 1999
+++ perl/pod/perldiag.pod	Thu Oct  7 16:51:43 1999
@@ -2369,7 +2369,7 @@
 
 =item POSIX getpgrp can't take an argument
 
-(F) Your C compiler uses POSIX getpgrp(), which takes no argument, unlike
+(F) Your system has POSIX getpgrp(), which takes no argument, unlike
 the BSD version, which takes a pid.
 
 =item Possible Y2K bug: %s
@@ -2681,6 +2681,11 @@
 (F) You tried to assign to C<$E<gt>>, and your operating system doesn't support
 the seteuid() system call (or equivalent), or at least Configure didn't
 think so.
+
+=item setpgrp can't take arguments
+
+(F) Your system has the setpgrp() from BSD 4.2, which takes no arguments,
+unlike POSIX setpgid(), which takes a process ID and process group ID.
 
 =item setrgid() not implemented
 

==== //depot/perl/pod/perlfunc.pod#107 (text) ====
Index: perl/pod/perlfunc.pod
--- perl/pod/perlfunc.pod.~1~	Thu Oct  7 16:51:43 1999
+++ perl/pod/perlfunc.pod	Thu Oct  7 16:51:43 1999
@@ -3697,9 +3697,10 @@
 
 Sets the current process group for the specified PID, C<0> for the current
 process.  Will produce a fatal error if used on a machine that doesn't
-implement setpgrp(2).  If the arguments are omitted, it defaults to
-C<0,0>.  Note that the POSIX version of C<setpgrp> does not accept any
-arguments, so only C<setpgrp(0,0)> is portable.  See also C<POSIX::setsid()>.
+implement POSIX setpgid(2) or BSD setpgrp(2).  If the arguments are omitted,
+it defaults to C<0,0>.  Note that the BSD 4.2 version of C<setpgrp> does not
+accept any arguments, so only C<setpgrp(0,0)> is portable.  See also
+C<POSIX::setsid()>.
 
 =item setpriority WHICH,WHO,PRIORITY
 

==== //depot/perl/pp_sys.c#118 (text) ====
Index: perl/pp_sys.c
--- perl/pp_sys.c.~1~	Thu Oct  7 16:51:43 1999
+++ perl/pp_sys.c	Thu Oct  7 16:51:43 1999
@@ -3808,7 +3808,7 @@
     SETi( BSD_SETPGRP(pid, pgrp) >= 0 );
 #else
     if ((pgrp != 0 && pgrp != getpid()) || (pid != 0 && pid != getpid()))
-	DIE(aTHX_ "POSIX setpgrp can't take an argument");
+	DIE(aTHX_ "setpgrp can't take an argument");
     SETi( setpgrp() >= 0 );
 #endif /* USE_BSDPGRP */
     RETURN;
End of Patch.

@p5pRT
Copy link
Author

p5pRT commented Oct 7, 1999

From [Unknown Contact. See original ticket]

Not quite. There is no setpgrp() in posix.1, afaik. s/POSIX/SVID, I
believe. My bug report was confused and im sorry. What I MEANT to say was​:

setpgrp() is not, in fact, a POSIX.1 function, it is SVID derived.
setpgid() is the posix function. You might also document that
setpgrp(a,b) is bsd syntax, and setpgrp(noargs) is SVID derived.

See comments below.

On Thu, 7 Oct 1999, Gurusamy Sarathy wrote​:

On Thu, 07 Oct 1999 10​:30​:23 EDT, Brian Mitchell wrote​:

Documentation for setpgrp is incorrect. From perldoc -f setpgrp​:

Sets the current process group for the specified PID, 0 for the current
process. Will produce a fatal error if used on a machine that doesn't
implement setpgrp(2). If the arguments are omitted, it defaults to
0,0. Note that the POSIX version of setpgrp() does not accept any
arguments, so only setpgrp 0,0 is portable.

setpgrp() is not, in fact, a POSIX.1 function, it is SVID derived.
setpgid() is the posix function. You might also document that
setpgrp(a,b) is bsd syntax, and setpgrp(noargs) is BSD4.3 (or is it
4.2, i'm not 100% sure) syntax.

Thanks. Let me know if this edit doesn't get it right.

Sarathy
gsar@​activestate.com
-----------------------------------8<-----------------------------------
Change 4310 by gsar@​auger on 1999/10/07 23​:51​:38

fix setpgrp vs getpgrp and POSIX vs BSD confusion \(spotted by
Brian Mitchell \<brian@&#8203;chele\.cais\.net>\)

Affected files ...

... //depot/perl/pod/perldiag.pod#99 edit
... //depot/perl/pod/perlfunc.pod#107 edit
... //depot/perl/pp_sys.c#118 edit

Differences ...

==== //depot/perl/pod/perldiag.pod#99 (text) ====
Index​: perl/pod/perldiag.pod
--- perl/pod/perldiag.pod.1 Thu Oct 7 16​:51​:43 1999
+++ perl/pod/perldiag.pod Thu Oct 7 16​:51​:43 1999
@​@​ -2369,7 +2369,7 @​@​

=item POSIX getpgrp can't take an argument

-(F) Your C compiler uses POSIX getpgrp(), which takes no argument, unlike
+(F) Your system has POSIX getpgrp(), which takes no argument, unlike
the BSD version, which takes a pid.

It's actually SVID defined; not POSIX.1 defined I believe (although I
don't have posix.1 handy).

=item Possible Y2K bug​: %s
@​@​ -2681,6 +2681,11 @​@​
(F) You tried to assign to C<$E<gt>>, and your operating system doesn't support
the seteuid() system call (or equivalent), or at least Configure didn't
think so.
+
+=item setpgrp can't take arguments
+
+(F) Your system has the setpgrp() from BSD 4.2, which takes no arguments,
+unlike POSIX setpgid(), which takes a process ID and process group ID.

setpgrp() with no arguments is SVID. setpgrp() with arguments is BSD.

=item setrgid() not implemented

==== //depot/perl/pod/perlfunc.pod#107 (text) ====
Index​: perl/pod/perlfunc.pod
--- perl/pod/perlfunc.pod.1 Thu Oct 7 16​:51​:43 1999
+++ perl/pod/perlfunc.pod Thu Oct 7 16​:51​:43 1999
@​@​ -3697,9 +3697,10 @​@​

Sets the current process group for the specified PID, C<0> for the current
process. Will produce a fatal error if used on a machine that doesn't
-implement setpgrp(2). If the arguments are omitted, it defaults to
-C<0,0>. Note that the POSIX version of C<setpgrp> does not accept any
-arguments, so only C<setpgrp(0,0)> is portable. See also C<POSIX​::setsid()>.
+implement POSIX setpgid(2) or BSD setpgrp(2). If the arguments are omitted,
+it defaults to C<0,0>. Note that the BSD 4.2 version of C<setpgrp> does not
+accept any arguments, so only C<setpgrp(0,0)> is portable. See also
+C<POSIX​::setsid()>.

It's the SVID version that doesnt accept arguments. The BSD version is the
same as setpgid() according to my documentation.

=item setpriority WHICH,WHO,PRIORITY

==== //depot/perl/pp_sys.c#118 (text) ====
Index​: perl/pp_sys.c
--- perl/pp_sys.c.1 Thu Oct 7 16​:51​:43 1999
+++ perl/pp_sys.c Thu Oct 7 16​:51​:43 1999
@​@​ -3808,7 +3808,7 @​@​
SETi( BSD_SETPGRP(pid, pgrp) >= 0 );
#else
if ((pgrp != 0 && pgrp != getpid()) || (pid != 0 && pid != getpid()))
- DIE(aTHX_ "POSIX setpgrp can't take an argument");
+ DIE(aTHX_ "setpgrp can't take an argument");
SETi( setpgrp() >= 0 );
#endif /* USE_BSDPGRP */
RETURN;
End of Patch.

@p5pRT
Copy link
Author

p5pRT commented Oct 7, 1999

From @gsar

On Thu, 07 Oct 1999 20​:09​:48 EDT, Brian Mitchell wrote​:

Not quite. There is no setpgrp() in posix.1, afaik. s/POSIX/SVID, I
believe. My bug report was confused and im sorry. What I MEANT to say was​:

setpgrp() is not, in fact, a POSIX.1 function, it is SVID derived.

I don't think we assert that it is POSIX anymore (after the patch).

setpgid() is the posix function. You might also document that
setpgrp(a,b) is bsd syntax, and setpgrp(noargs) is SVID derived.

See comments below.

My notes are derived from the Linux/glibc manpage for {s,g}etpg{id,rp}.

  NAME
  setpgid, getpgid, setpgrp, getpgrp - set/get process group

  SYNOPSIS
  #include <unistd.h>

  int setpgid(pid_t pid, pid_t pgid);
  pid_t getpgid(pid_t pid);
  int setpgrp(void);
  pid_t getpgrp(void);
  [...]
  CONFORMING TO
  The functions setpgid and getpgrp conform to POSIX.1. The
  function setpgrp is from BSD 4.2. The function getpgid
  conforms to SVr4.

On Thu, 7 Oct 1999, Gurusamy Sarathy wrote​:

@​@​ -2369,7 +2369,7 @​@​

=item POSIX getpgrp can't take an argument

-(F) Your C compiler uses POSIX getpgrp(), which takes no argument, unlike
+(F) Your system has POSIX getpgrp(), which takes no argument, unlike
the BSD version, which takes a pid.

It's actually SVID defined; not POSIX.1 defined I believe (although I
don't have posix.1 handy).

I don't have POSIX.1 documentation either; I just went by what the
manpage says.

=item Possible Y2K bug​: %s
@​@​ -2681,6 +2681,11 @​@​
(F) You tried to assign to C<$E<gt>>, and your operating system doesn't support
the seteuid() system call (or equivalent), or at least Configure didn't
think so.
+
+=item setpgrp can't take arguments
+
+(F) Your system has the setpgrp() from BSD 4.2, which takes no arguments,
+unlike POSIX setpgid(), which takes a process ID and process group ID.

setpgrp() with no arguments is SVID. setpgrp() with arguments is BSD.

The Linux manpage contradicts this (per my reading). See above.

Sets the current process group for the specified PID, C<0> for the current
process. Will produce a fatal error if used on a machine that doesn't
-implement setpgrp(2). If the arguments are omitted, it defaults to
-C<0,0>. Note that the POSIX version of C<setpgrp> does not accept any
-arguments, so only C<setpgrp(0,0)> is portable. See also C<POSIX​::setsid()>.
+implement POSIX setpgid(2) or BSD setpgrp(2). If the arguments are omitted,
+it defaults to C<0,0>. Note that the BSD 4.2 version of C<setpgrp> does not
+accept any arguments, so only C<setpgrp(0,0)> is portable. See also
+C<POSIX​::setsid()>.

It's the SVID version that doesnt accept arguments. The BSD version is the
same as setpgid() according to my documentation.

setpgrp(void) is BSD, according to the Linux manpage.

Sarathy
gsar@​activestate.com

@p5pRT
Copy link
Author

p5pRT commented Oct 8, 1999

From [Unknown Contact. See original ticket]

On Thu, Oct 07, 1999 at 06​:05​:42PM -0700, Gurusamy Sarathy wrote​:

On Thu, 07 Oct 1999 20​:09​:48 EDT, Brian Mitchell wrote​:

Not quite. There is no setpgrp() in posix.1, afaik. s/POSIX/SVID, I
believe. My bug report was confused and im sorry. What I MEANT to say was​:

setpgrp() is not, in fact, a POSIX.1 function, it is SVID derived.

I don't think we assert that it is POSIX anymore (after the patch).

setpgid() is the posix function. You might also document that
setpgrp(a,b) is bsd syntax, and setpgrp(noargs) is SVID derived.

See comments below.

My notes are derived from the Linux/glibc manpage for {s,g}etpg{id,rp}.

NAME
   setpgid\, getpgid\, setpgrp\, getpgrp \- set/get process group

SYNOPSIS
   \#include \<unistd\.h>

   int setpgid\(pid\_t pid\, pid\_t pgid\);
   pid\_t getpgid\(pid\_t pid\);
   int setpgrp\(void\);
   pid\_t getpgrp\(void\);
\[\.\.\.\]
CONFORMING TO
   The functions setpgid and getpgrp conform to POSIX\.1\.  The
   function  setpgrp  is  from BSD 4\.2\.  The function getpgid
   conforms to SVr4\.

On Thu, 7 Oct 1999, Gurusamy Sarathy wrote​:

@​@​ -2369,7 +2369,7 @​@​

=item POSIX getpgrp can't take an argument

-(F) Your C compiler uses POSIX getpgrp(), which takes no argument, unlike
+(F) Your system has POSIX getpgrp(), which takes no argument, unlike
the BSD version, which takes a pid.

It's actually SVID defined; not POSIX.1 defined I believe (although I
don't have posix.1 handy).

I don't have POSIX.1 documentation either; I just went by what the
manpage says.

  I've got POSIX.1 right in front of me. There's only one mention of
setpgrp(), on page 448 (lines 3762 and 3777)​:

  ``System V, without job control, groups processes into process
  groups and creates new process groups via setpgrp() . . . .
  the setpgid() function is similar to the setpgrp() function of
  4.2BSD . . . .''

  Peace,
* Kurt Starsinic (Kurt.Starsinic@​isinet.com) --------- Technical Specialist *
| `The future masters of technology will have to be lighthearted and |
| intelligent. The machine easily masters the grim and the dumb.' |
| -- Marshall McLuhan |
Institute for Scientific Information http​://www.isinet.com/

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

1 participant