[Bug 2098030] [NEW] man 2 kill has a phrasing issue regarding its RETURN VALUE

[Amit Pinhas]

Public bug reported:

Hello!

I stumbled upon a small mistake, or rather a misphrasing in `man 2
kill`.

At my scenario, I was looking to check an existence of a certain process, and so i have seen that kill will check it for me, as mentioned:
```
If sig is 0, then no signal is sent, but existence and permission
checks are still performed; this can be used to check for the
existence of a process ID...
```
Which is great! I was trying it and it worked just as I expected.
When the process did exist, I would get 0 as a success, and if not, then the call failed, as I expected.

On the other hand, when I read the `RETURN VALUE` section, I saw a small misphrasing:
```
On success (at least one signal was sent), zero is returned.  On
error, -1 is returned...
```
Which seemed rational.

But wait! How can I get 0 when providing sig=0, if no signal was
actually sent, which is the criteria for success of this call???

If i understand correctly, there should be a disclaimer, something like:
```
On success (at least one signal was sent or if sig=0 and the checks done were successful), zero is returned.  On
error, -1 is returned...
```

If you read my thoughts this far, thank you for your time! I love your work and keep it going!
I would like to know how and if I could fix the man page if needed :)

Have a nice day guys!
Much love from Israel :)

** Affects: manpages (Ubuntu)
     Importance: Undecided
         Status: New

-- 
You received this bug notification because you are a member of Ubuntu
Foundations Bugs, which is subscribed to manpages in Ubuntu.
https://bugs.launchpad.net/bugs/2098030

Title:
  man 2 kill has a phrasing issue regarding its RETURN VALUE

Status in manpages package in Ubuntu:
  New

Bug description:
  Hello!

  I stumbled upon a small mistake, or rather a misphrasing in `man 2
  kill`.

  At my scenario, I was looking to check an existence of a certain process, and so i have seen that kill will check it for me, as mentioned:
  ```
  If sig is 0, then no signal is sent, but existence and permission
  checks are still performed; this can be used to check for the
  existence of a process ID...
  ```
  Which is great! I was trying it and it worked just as I expected.
  When the process did exist, I would get 0 as a success, and if not, then the call failed, as I expected.

  On the other hand, when I read the `RETURN VALUE` section, I saw a small misphrasing:
  ```
  On success (at least one signal was sent), zero is returned.  On
  error, -1 is returned...
  ```
  Which seemed rational.

  But wait! How can I get 0 when providing sig=0, if no signal was
  actually sent, which is the criteria for success of this call???

  If i understand correctly, there should be a disclaimer, something like:
  ```
  On success (at least one signal was sent or if sig=0 and the checks done were successful), zero is returned.  On
  error, -1 is returned...
  ```

  If you read my thoughts this far, thank you for your time! I love your work and keep it going!
  I would like to know how and if I could fix the man page if needed :)

  Have a nice day guys!
  Much love from Israel :)

To manage notifications about this bug go to:
https://bugs.launchpad.net/ubuntu/+source/manpages/+bug/2098030/+subscriptions