NetBSD Problem Report #57434

From www@netbsd.org  Wed May 24 09:50:00 2023
Return-Path: <www@netbsd.org>
Received: from mail.netbsd.org (mail.netbsd.org [199.233.217.200])
	(using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits))
	(Client CN "mail.NetBSD.org", Issuer "mail.NetBSD.org CA" (not verified))
	by mollari.NetBSD.org (Postfix) with ESMTPS id CE71A1A9238
	for <gnats-bugs@gnats.NetBSD.org>; Wed, 24 May 2023 09:49:59 +0000 (UTC)
Message-Id: <20230524094958.692D11A9239@mollari.NetBSD.org>
Date: Wed, 24 May 2023 09:49:58 +0000 (UTC)
From: isaki@pastel-flower.jp
Reply-To: isaki@pastel-flower.jp
To: gnats-bugs@NetBSD.org
Subject: cp(1) -P description is misleading.
X-Send-Pr-Version: www-1.0

>Number:         57434
>Category:       bin
>Synopsis:       cp(1) -P description is misleading.
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    bin-bug-people
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Wed May 24 09:50:00 +0000 2023
>Last-Modified:  Sat May 27 03:30:02 +0000 2023
>Originator:     Tetsuya Isaki
>Release:        NetBSD 10.0_BETA
>Organization:
>Environment:
NetBSD 10.0_BETA amd64
>Description:
The cp(1) manpage says the following about -P option:

     -P    No symbolic links are followed.  This is the default.

But cp without -P (nor -R) follows symlinks.

 % uname -srm
 NetBSD 10.0_BETA amd64
 % ln -s /netbsd test
 % ls -lF
 total 4
 lrwxr-xr-x  1 isaki  wheel  7 May 20 12:02 test@ -> /netbsd
 % which \cp
 /bin/cp
 % \cp test ./cp_default
 % \cp -P test ./cp_withP
 % ls -lF
 total 28828
 -rwxr-xr-x  1 isaki  wheel  29509280 May 20 12:02 cp_default*
 lrwxr-xr-x  1 isaki  wheel         7 May 20 12:03 cp_withP@ -> /netbsd
 lrwxr-xr-x  1 isaki  wheel         7 May 20 12:02 test@ -> /netbsd
 %

When I see syntax in SYNOPSIS section, I can understand that -P should
be specified with -R.  I think that there needs to be a reference to
-R option in the description of -P, if so.

However, -P can be specified without -R.  I don't know what is correct
(intended) situation, but the followings are that I observed:
1. -P means that "no symbolic links are followed".
   (manpage and its behavior are consistent)
2. If -R is specified, -P is the default. (manpage doesn't explain it enough)
3. If -R is not specified, -P is not the default. (There is no explanation
   about this)
>How-To-Repeat:
man cp
>Fix:
I don't have.

>Audit-Trail:
From: Robert Elz <kre@munnari.OZ.AU>
To: gnats-bugs@netbsd.org
Cc: 
Subject: Re: bin/57434: cp(1) -P description is misleading.
Date: Wed, 24 May 2023 20:41:21 +0700

     Date:        Wed, 24 May 2023 09:50:00 +0000 (UTC)
     From:        isaki@pastel-flower.jp
     Message-ID:  <20230524095000.AA9341A9241@mollari.NetBSD.org>

   | The cp(1) manpage says the following about -P option:
   |      -P    No symbolic links are followed.  This is the default.

 Before I say anything else, let me first agree with you, the man page
 is not at all good (not clear).

   | But cp without -P (nor -R) follows symlinks.

 Not always.   It depends upon -r as well.   A simple cp of a file does
 follow symlinks, a cp -r of a directory tree does not.   So whether -P
 is the default or not, depends...

 Of course, it also isn't great that cp(1) doesn't mention the -r flag
 at all (it is similar to -R, an older variant, but different).

   | When I see syntax in SYNOPSIS section, I can understand that -P should
   | be specified with -R.

 Actually, no, -P and -R aren't (quite) that closely related.   However -P
 is related to -H and -L (at most 1 of those three can be set) and -H and -L
 only apply when -R is set.   It is all very murky...   (-r and -R can't both
 be used, in fact, with -r, none of -R -P -L or -H can also be set - which
 is kind of odd, as -r kind of implies -P, without setting it).

   | However, -P can be specified without -R.  I don't know what is correct
   | (intended) situation, but the followings are that I observed:

 I believe your observations are correct.   However (unsuprisingly) you
 didn't test the (rather older) -r option - when that's set -P is (more or
 less) set as well (it is, but it isn't....)

 kre

From: Tetsuya Isaki <isaki@pastel-flower.jp>
To: gnats-bugs@netbsd.org
Cc: gnats-admin@netbsd.org,
	netbsd-bugs@netbsd.org
Subject: Re: bin/57434: cp(1) -P description is misleading.
Date: Sat, 27 May 2023 12:28:19 +0900

 At Wed, 24 May 2023 13:45:02 +0000 (UTC),
 Robert Elz wrote:
 >    | When I see syntax in SYNOPSIS section, I can understand that -P should
 >    | be specified with -R.
 >  
 >  Actually, no, -P and -R aren't (quite) that closely related.  However -P
 >  is related to -H and -L (at most 1 of those three can be set) and -H and -L
 >  only apply when -R is set.   It is all very murky...

 Indeed..
 Anyway, why I thought that -P should be specified with -R is the
 following notation in the SYNOPSIS section:

   SYNOPSIS
      cp [-R [-H | -L | -P]] ...

 I read it as "When you specify -R, you can also specify probably one of
 -H, -L, or -P at the same time", in other words, "(one of -H, -L, or) -P
 can only be specified with -R".
 If no (in fact, -P can be specified without -R), I feel this bracket
 notation makes confusing...

 >    | However, -P can be specified without -R.  I don't know what is correct
 >    | (intended) situation, but the followings are that I observed:
 >  
 >  I believe your observations are correct.

 Thanks.  Then, how about this?

   -P  No symbolic links are followed.
 -     This is the default.
 +     The -R option implies the -P.

 >  However (unsuprisingly) you
 >  didn't test the (rather older) -r option - when that's set -P is (more or
 >  less) set as well (it is, but it isn't....)

 Thank you for pointing out, but I don't worry about -r this time.
 -r option is not listed in the DESCRIPTION section and is explained
 carefully in the COMPATIBILITY section.  The manpage suggests that
 cp -r may not handle symlinks and etc. expectedly.
 ---
 Tetsuya Isaki <isaki@pastel-flower.jp / isaki@NetBSD.org>

Home	PR Database Search