Bug#992377: manpages-dev

[Michael Kerrisk (man-pages)]

tags 992377 fixed-upstream
thanks

Upstream maintainer here. The keyutils pages in Section 2
are an unusual case. The wrapper functions are provided in
the libkeyutils library (instead of, as is conventional, 
the C library), as noted in the add_key(2) page.
The package that provides that library also provides
the  header file. The manual page implies
that, but doesn't make it completely clear. I've added 
a sentence to the manual page to make this more explicit:

   Glibc does not provide a wrapper for this system call.  A  wrapper
   is provided in the libkeyutils library.  **(The accompanying package
   provides the  header file.)**  When employing the  wrap‐
   per in that library, link with -lkeyutils.

Of course, the name of the relevant package depends on the distro.
For Debian, I believe it is "libkeyutils-dev". (I run Fedora,
where the package is the somewhat unconventionally named
"keyutils-libs-devel".)

Thanks,

Michael

Bug#981171: [PATCH 6/6] Use subsection for environment

[Michael Kerrisk (man-pages)]

AGER
>  The user's preferred utility to display text files.
> @@ -218,30 +256,11 @@ variable is null or not set,
>  command could fallback
>  .B more (1)
>  or any suitable paging utility default defined system-wise.
> -.TP
> -.BR EDITOR / VISUAL
> -The user's preferred utility to edit text files.
> -Any string acceptable as a command_string operand to the
> -.I sh\ \-c
> -command shall be valid.
> -.\" .TP
> -.\" .B BROWSER
> -.\" The user's preferred utility to browse URLs. Sequence of colon-separated
> -.\" browser commands. See http://www.catb.org/\(tiesr/BROWSER/ .
> -.PP
> +.SS Other common environment variables
>  Note that the behavior of many programs and library routines is
>  influenced by the presence or value of certain environment variables.
>  Examples include the following:
>  .IP * 3
> -The variables
> -.BR LANG ", " LANGUAGE ", " NLSPATH ", " LOCPATH ,
> -.BR LC_ALL ", " LC_MESSAGES ,
> -and so on influence locale handling; see
> -.BR catopen (3),
> -.BR gettext (3),
> -and
> -.BR locale (7).
> -.IP *
>  .B TMPDIR
>  influences the path prefix of names created by
>  .BR tempnam (3)
> @@ -272,23 +291,13 @@ gives the name of a file containing aliases
>  to be used with
>  .BR gethostbyname (3).
>  .IP *
> -.BR TZ " and " TZDIR
> -give timezone information used by
> -.BR tzset (3)
> -and through that by functions like
> -.BR ctime (3),
> -.BR localtime (3),
> -.BR mktime (3),
> -.BR strftime (3).
> -See also
> -.BR tzselect (8).
> -.IP *
>  .B TERMCAP
>  gives information on how to address a given terminal
>  (or gives the name of a file containing such information).
>  .IP *
> -.BR COLUMNS " and " LINES
> -tell applications about the window size, possibly overriding the actual size.
> +.B USER
> +The name of the logged-in user (used by some BSD-derived programs).
> +Set at login time, see section NOTES below.
>  .IP *
>  .BR PRINTER " or " LPDEST
>  may specify the desired printer to use.

Thanks,

Michael



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#981171: [PATCH 5/6] Create a section ENVIRONMENT

[Michael Kerrisk (man-pages)]

Hello Bastien,

On 1/30/21 12:29 AM, roucaries.bast...@gmail.com wrote:
> From: Bastien Roucariès 
> 
> According to man-page (7):
>  ENVIRONMENT
>   A list of all environment variables that affect the program or 
> function and how they affect it.
> 
> Therefore push the list of variables to an ENVIRONMENT section.

The purpose of the ENVIRONMENT section in other page is to
list the EVs that are relevant for the interface, The environ(7)
page does not such section.

On the other hand, I do like the reorganization that is proposed
in the remainder of the patch, and the subsequent restructuring
of the variables in the following patch.

I've applied this patch, but removed the addition of the
ENVIRONMENT heading.

Thanks!

Cheers,

Michael

> 
> Reorder also how to set environment variables to DESCRIPTION instead of after 
> the ENVIRONMENT section
> in order to improve readability.
> 
> Signed-off-by: Bastien Roucariès 
> ---
>  man7/environ.7 | 95 +++---
>  1 file changed, 52 insertions(+), 43 deletions(-)
> 
> diff --git a/man7/environ.7 b/man7/environ.7
> index d1e86ee8d..9fd3f727f 100644
> --- a/man7/environ.7
> +++ b/man7/environ.7
> @@ -87,7 +87,58 @@ The value can be anything that can be represented as a 
> string.
>  The name and the value may not contain an embedded null byte (\(aq\e0\(aq),
>  since this is assumed to terminate the string.
>  .PP
> -Common examples are:
> +Environment variables may be placed in the shell's environment by the
> +.I export
> +command in
> +.BR sh (1),
> +or by the
> +.I setenv
> +command if you use
> +.BR csh (1).
> +.PP
> +The initial environment of the shell is populated in various ways,
> +such as definitions from
> +.IR /etc/environment
> +that are processed by
> +.BR pam_env (8)
> +for all users at login time (on systems that employ
> +.BR pam (8)).
> +In addition, various shell initialization scripts, such as the system-wide
> +.IR /etc/profile
> +script and per-user initializations script may include commands
> +that add variables to the shell's environment;
> +see the manual page of your preferred shell for details.
> +.PP
> +Bourne-style shells support the syntax
> +.PP
> +NAME=value command
> +.PP
> +to create an environment variable definition only in the scope
> +of the process that executes
> +.IR command .
> +Multiple variable definitions, separated by white space, may precede
> +.IR command .
> +.PP
> +Arguments may also be placed in the
> +environment at the point of an
> +.BR exec (3).
> +A C program can manipulate its environment using the functions
> +.BR getenv (3),
> +.BR putenv (3),
> +.BR setenv (3),
> +and
> +.BR unsetenv (3).
> +.PP
> +What follows is a list of environment variables typically seen on a
> +system.
> +This list is incomplete and includes only common variables seen
> +by average users in their day-to-day routine.
> +Care should be taken
> +to not conflict with the variables specified in the next sections.
> +Environment variables specific to a particular program or library function
> +are documented in the ENVIRONMENT section of the appropriate manual page.
> +.SH ENVIRONMENT
> +Common examples of environment variables are:
>  .TP
>  .B USER
>  The name of the logged-in user (used by some BSD-derived programs).
> @@ -178,48 +229,6 @@ command shall be valid.
>  .\" The user's preferred utility to browse URLs. Sequence of colon-separated
>  .\" browser commands. See http://www.catb.org/\(tiesr/BROWSER/ .
>  .PP
> -Names may be placed in the shell's environment by the
> -.I export
> -command in
> -.BR sh (1),
> -or by the
> -.I setenv
> -command if you use
> -.BR csh (1).
> -.PP
> -The initial environment of the shell is populated in various ways,
> -such as definitions from
> -.IR /etc/environment
> -that are processed by
> -.BR pam_env (8)
> -for all users at login time (on systems that employ
> -.BR pam (8)).
> -In addition, various shell initialization scripts, such as the system-wide
> -.IR /etc/profile
> -script and per-user initializations script may include commands
> -that add variables to the shell's environment;
> -see the manual page of your preferred shell for details.
> -.PP
> -Bourne-style shells support the syntax
> -.PP
> -NAME=value command
> -.PP
> -to create an environment variable definition only in the scope
> -of the process that executes
> -.IR command .
> -Multiple variable definitions, separated by white space, may precede
> -.IR command .
> -.PP
> -Arguments may also be placed in the
> -environment at the point of an
> -.BR exec (3).
> -A C program can manipulate its en

Bug#981171: [PATCH 4/6] Better documentation of the environment mechanism

[Michael Kerrisk (man-pages)]

Hello Bastien,

Thanks. This looks better. But still some things to 
improve, I think.

On 1/30/21 12:29 AM, roucaries.bast...@gmail.com wrote:
> From: Bastien Roucariès 
> 
> Document the purpose of the envirment mechanism, compared to the

s/envirment/environment/

> command line argument of a program. Document particularly that
> the environment is shared by many programs and is inherited.
> 
> Define also the so called process environment and "the environment"

s/so called/so-called/

> concept that are used in other manpages.

s/manpages/manual pages/

> 
> Signed-off-by: Bastien Roucariès 
> ---
>  man7/environ.7 | 26 ++
>  1 file changed, 26 insertions(+)
> 
> diff --git a/man7/environ.7 b/man7/environ.7
> index 3c2769bfb..d1e86ee8d 100644
> --- a/man7/environ.7
> +++ b/man7/environ.7
> @@ -43,6 +43,32 @@ The variable
>  .I environ
>  points to an array of pointers to strings called the "environment".
>  The last pointer in this array has the value NULL.
> +.PP
> +At time of execution, a program receive context information by two 
> mechanisms.
> +The first way is the program arguments, represented by the arguments of
> +.I main
> +function,
> +.I argc
> +and
> +.I argv
> +variables. The second way, is the
> +.I environ
> +variable as discuted in this manual.

Oui en français c'est discuter; mais en anglais: to discuss

> +.PP
> +The program arguments are typically used to pass so-called command-line 
> argument specific to

Source lines should be no more than 75 columns or so.

s/so-called command-line argument/values that are/

> +a particular use of the program being invoked, thus changing the program 
> behavior to an use case.

s/, thus changing the program behavior to an use case//
(This test does not really add to the explanation.)

> +The environment, on the other hand, keeps track of information that is 
> shared by many programs and
> +rarely changes.
> +For example, a running process can query the value of the
> +.B TMPDIR
> +environment variable to discover a suitable location to store temporary 
> files.
> +.PP
> +Standard environment variables are used for information about the user’s 
> home directory,
> +current language,...

s/.../ and so on./

> +An user can define additional variables for other purposes.

s/An/A/
(Because the "u" is iotized -- "a 'yooser'") [1]

> +The set of all environment variables that have values is collectively known 
> as
> +the process environment or simply the environment.
> +.PP
>  This array of strings is made available to the process by the
>  .BR execve (2)
>  call when a new program is started.

Thanks,

Michael



[1] https://www.quickanddirtytips.com/education/grammar/a-versus-an

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#981171: [PATCH 3/6] Improve pager section by pointing to more

[Michael Kerrisk (man-pages)]

Hello Bastien,

On 1/30/21 12:29 AM, roucaries.bast...@gmail.com wrote:
> From: Bastien Roucariès 
> 
> More is the default pager according to mailx manual page of POSIX.1-2001 to
> POSIX.1-2017. Mention it.
> ---
>  man7/environ.7 | 8 +++-
>  1 file changed, 7 insertions(+), 1 deletion(-)
> 
> diff --git a/man7/environ.7 b/man7/environ.7
> index 9ac86f357..3c2769bfb 100644
> --- a/man7/environ.7
> +++ b/man7/environ.7
> @@ -135,7 +135,12 @@ The terminal type for which output is to be prepared.
>  The user's preferred utility to display text files.
>  Any string acceptable as a command_string operand to the
>  .I sh\ \-c
> -command shall be valid.
> +command shall be valid. If the
> +.B PAGER
> +variable is null or not set,
> +command could fallback
> +.B more (1)
> +or any suitable paging utility default defined system-wise.

I don't think I've used more(1) in the last 20 years.
Notwithstanding what POSIX may say, it is simply odd to
mention more(1) but not less(1).

>  .TP
>  .BR EDITOR / VISUAL
>  The user's preferred utility to edit text files.
> @@ -348,6 +353,7 @@ and strictly conformant to POSIX.1-2001.
>  .BR csh (1),
>  .BR env (1),
>  .BR login (1),
> +.BR more (1),

This definitely doesn't warrant an entry in the SEE ALSO section...
SEE ALSO is about other pages that might provide information related
to the topic of this page. more(1) doesn't really add anything to
the explanation of environment variables.

>  .BR printenv (1),
>  .BR sh (1),
>  .BR su (1),

I instead applied the patch below.

Thanks,

Michael

--- a/man7/environ.7
+++ b/man7/environ.7
@@ -141,6 +141,13 @@ The user's preferred utility to display text files.
 Any string acceptable as a command-string operand to the
 .I sh\ \-c
 command shall be valid.
+If
+.B PAGER
+is null or is not set,
+then applications that launch a pager will default to a program such as
+.BR less (1)
+or
+.BR more (1).
 .TP
 .BR EDITOR / VISUAL
 The user's preferred utility to edit text files.

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#981171: [PATCH 1/6] Document that means at login time for HOME, LOGNAME, SHELL, USER

[Michael Kerrisk (man-pages)]

Hello Bastien,

Thank you for taking the time to prepare this patch.

As already noted, the subject line of a patch should read

[PATCH ...] page.n: .

I've applied the patch, but made many edits.

On 1/30/21 12:29 AM, roucaries.bast...@gmail.com wrote:
> From: Bastien Roucariès 
> 
> Clearly document that HOME, LOGNAME, SHELL and USER are set at login time
> by program like login (1).
> 
> Document also that using su could result in a mixed environment, and point to
> su manual.
> 
> Signed-off-by: Bastien Roucariès 
> ---
>  man7/environ.7 | 34 ++
>  1 file changed, 30 insertions(+), 4 deletions(-)
> 
> diff --git a/man7/environ.7 b/man7/environ.7
> index 8f89ba86b..e33dcc754 100644
> --- a/man7/environ.7
> +++ b/man7/environ.7
> @@ -65,15 +65,15 @@ Common examples are:
>  .TP
>  .B USER
>  The name of the logged-in user (used by some BSD-derived programs).
> +Set at login time, see section NOTES below.
>  .TP
>  .B LOGNAME
>  The name of the logged-in user (used by some System-V derived programs).
> +Set at login time, see section NOTES below.
>  .TP
>  .B HOME
> -A user's login directory, set by
> -.BR login (1)
> -from the password file
> -.BR passwd (5).
> +A user's login directory, set a login time.
> +Set at login time, see section NOTES below.
>  .TP
>  .B LANG
>  The name of a locale to use for locale categories when not overridden
> @@ -114,6 +114,7 @@ Set by some shells.
>  .TP
>  .B SHELL
>  The absolute pathname of the user's login shell.
> +Set at login time, see section NOTES below.
>  .TP
>  .B TERM
>  The terminal type for which output is to be prepared.
> @@ -260,6 +261,30 @@ The
>  and
>  .B PR_SET_MM_ENV_END
>  operations can be used to control the location of the process's environment.
> +.PP
> +The
> +.B HOME,
> +.B LOGNAME,
> +.B SHELL
> +and
> +.B USER

Please take a careful look at man-pages(7) and also groff_man(7).
The above should be written as:

The
.BR HOME ,
.BR LOGNAME ,
.BR SHELL ,
and
.B USER

> +variables are only set when an user is changing using

s/only//

> +session management interface, typically by program
> +.B login(1)

.BR login (1)

> +from user database (for instance, but not limited, by using
> +.B password (5)

s/password/passwd/

> +database).
> +Particularly,
> +.BR setuid (2)
> +family of function
> +does not set theses variables. Notes that as documented,

I'm not sure that there's value in mentioning that setuid(2)
doesn't change these.

Also, (again) as previously stated, new sentences ("Notes...")
should start on new lines.

> +going to root by
> +.BR su (8)
> +may result in a mixed environment where
> +.B LOGNAME
> +and
> +.B USER
> +are retained from old user.
>  .SH BUGS
>  Clearly there is a security risk here.
>  Many a system command has been
> @@ -305,6 +330,7 @@ should consider renaming their option to
>  .BR login (1),
>  .BR printenv (1),
>  .BR sh (1),
> +.BR su (1),
>  .BR tcsh (1),
>  .BR execve (2),
>  .BR clearenv (3),

Thanks, 

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#981171: [PATCH 2/6] Document PATH resolution

[Michael Kerrisk (man-pages)]

Hello Bastien,

For various reasons, I applied a different patch. See below.

On 1/30/21 12:29 AM, roucaries.bast...@gmail.com wrote:
> From: Bastien Roucariès 
> 
> Document PATH resolution, particularly null sequence and empty PATH
> 
> Document also that since POSIX.1-2001 null sequence for . are deprecated.

But your patch *doesn't* document that the null sequence
is deprecated!

> 
> Signed-off-by: Bastien Roucariès 
> ---
>  man7/environ.7 | 26 +++---
>  1 file changed, 23 insertions(+), 3 deletions(-)
> 
> diff --git a/man7/environ.7 b/man7/environ.7
> index e33dcc754..9ac86f357 100644
> --- a/man7/environ.7
> +++ b/man7/environ.7
> @@ -97,16 +97,28 @@ environment variables).
>  The sequence of directory prefixes that
>  .BR sh (1)
>  and many other
> -programs apply in searching for a file known by an incomplete pathname.
> +programs using
> +.BR execlp (3)
> +apply in searching for a file known by an incomplete pathname.
>  The prefixes are separated by \(aq\fB:\fP\(aq.
> -(Similarly one has
> +When a non-zero-length prefix is applied to this pathname, a \(aq\fB/\fP\(aq
> +(slash) shall be inserted between the prefix and the filename if the prefix
> +did not end in
> +\(aq\fB\(sl\fP\(aq (slash).
> +A zero length prefix is a legacy sequence that indicate the current 
> directory or
> +\(aq\fB.\fP\(aq (see section BUGS below).
> +The list of prefixes shall be searched from beginning to end, applying the
> +pathname to each prefix, until an executable file with the specified name
> +and appropriate execution permissions is found.

As I already remarked, we can't simply lift passages of text from
POSIX. Please don't do this.

> +.IP
> +Similarly one has
>  .B CDPATH
>  used by some shells to find the target
>  of a change directory command,
>  .B MANPATH
>  used by
>  .BR man (1)
> -to find manual pages, and so on)
> +to find manual pages, and so on.
>  .TP
>  .B PWD
>  The current working directory.
> @@ -323,6 +335,14 @@ The authors of
>  .I gzip
>  should consider renaming their option to
>  .BR GZIP_OPT .
> +.PP
> +.B PATH
> +zero lengh sequence,
> +that appears as two adjacent colons \(aq\fB::\fP\(aq, as a initial colon
> +\(aq\fB:\fP\(aq preceding the rest of the list,
> +or as a trailing colon \(aq\fB:\fP\(aq following the rest of the list,
> +shall be replaced by implicit \(aq\fB.\fP\(aq, in order to be portable
> +and strictly conformant to POSIX.1-2001.
>  .SH SEE ALSO
>  .BR bash (1),
>  .BR csh (1),
> 

I instead applied the patch below.

Cheers,

Michael

diff --git a/man7/environ.7 b/man7/environ.7
index dd35050b2..11dfb4862 100644
--- a/man7/environ.7
+++ b/man7/environ.7
@@ -98,8 +98,22 @@ The sequence of directory prefixes that
 .BR sh (1)
 and many other
 programs employ when searching for an executable file that is specified
-as a simple filename (containing no slashes).
-The prefixes are separated by \(aq\fB:\fP\(aq.
+as a simple filename (i.a., a pathname that contains no slashes).
+The prefixes are separated by colons (\fB:\fP).
+The list of prefixes is searched from beginning to end,
+by checking the pathname formed by concatenating
+a prefix, a slash, and the filename,
+until a file with execute permission is found.
+.IP
+As a legacy feature, a zero-length prefix
+(specified as two adjacent colons, or an initial or terminating colon)
+is interpreted to mean the current working directory.
+However, use of this feature is deprecated,
+and POSIX notes that a conforming application shall use
+an explicit pathname (e.g.,
+.IR . )
+to specify the current working directory.
+.IP
 (Similarly one has
 .B CDPATH
 used by some shells to find the target



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#981171: [PATCH 0/6][V2] environement (7)

[Michael Kerrisk (man-pages)]

Hello Bastien

On 1/30/21 12:29 AM, roucaries.bast...@gmail.com wrote:
> Please review and apply
> 
> [PATCH 1/6] Document that means at login time for HOME, LOGNAME,
> [PATCH 2/6] Document PATH resolution
> [PATCH 3/6] Improve pager section by pointing to more
> [PATCH 4/6] Better documentation of the environment mechanism
> [PATCH 5/6] Create a section ENVIRONMENT
> [PATCH 6/6] Use subsection for environment

Thanks for your efforts.

Could I ask you to please have a look at man-pages(7) and
groff_man(7) if you plan to submit more patches. There are
many style and formatting issues that could be improved.

I find myself repeating some of the same points that I made
when reviewing the last round of patches. This is rather
demotivating for me, when I consider reviewing your patches.

Thanks,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#981171: [PATCH 01/13] Do not document mktemp (3)

[Michael Kerrisk (man-pages)]

Hello Bastien,

On Fri, 29 Jan 2021 at 10:18, Bastien ROUCARIES
 wrote:
>
> Hi,
> Le mer. 27 janv. 2021 à 22:28, Michael Kerrisk (man-pages)
>  a écrit :
> >
> > Salut Bastien,
> >
> > On 1/27/21 4:48 PM, roucaries.bast...@gmail.com wrote:
> > > From: Bastien Roucariès 
> > >
> > > Do not use for documentation purposes the unsecure mktemp function
> >
> > This message doesn't correspond to the change below (which removes
> > a reference to "tempnam" and adds a reference to "mktemp".
>
> ok
> >
> > But also, I don't think it makes systems more secure to
> > remove the info that tempnam is influence by TMPDIR.
>
> Yes but not documenting obsolete due to insecurity is better from a
> user point of view experience.
> I believe that manpage of insecure function should not be cited for
> documentation purposes (I am a uni teacher and experiment every days
> the
> bad example uses in teaching)

So, the first thing. AFAIK, the only library function that relies on
TMPDIR is tempnam(). Removing that name will leave a zero-length list
of functions in this sentence.

Secondly, I agree that we should deemphasize undesirable functions.
But if we discuss TMPDIR, it seems silly not to mention the only
function (AFAIK) that uses it.

Finally, the real solution to these sorts of problems is to properly
document the obsolete function, and put a prominent warning in the
documentation, which is exactly what we find in tempnam(3):

   DESCRIPTION
   Never use this function.  Use mkstemp(3) or tmpfile(3) instead.

> > And, this patch is surely not correct. Yes, TMPDIR influences
> > tmpfile(3).

I misspoke there. TMPDIR does not affect tmpfile(), as far as I know.

> > But how does TMPDIR influence mktemp(3), mkstemp(3),
> > and mkdtemp(3), which base the temporary filename on a path
> > supplied by the caller?
> I am sorry
> mkstemp does not need a file path, it need a template. Path is not
> supplied by the caller.

Agreed. I should have said "template".

> The mkstemp manpage may be improved. Do you want a patch for it ?

Improved in what way?

Thanks,

Michael

> File name are implementation dependend and path is $TMPDIR
> >
> > Finally, a request for patches: the format of the
> > subject line should rather be:
> >
> > [PATCH ...] environ.7: Do not document...
> Ok will do
>
> Will redo this patch
> >
> > Thanks,
> >
> > Michael
> >
> > > Signed-off-by: Bastien Roucariès 
> > > ---
> > >  man7/environ.7 | 6 +-
> > >  1 file changed, 5 insertions(+), 1 deletion(-)
> > >
> > > diff --git a/man7/environ.7 b/man7/environ.7
> > > index 182d823d2..d889310d6 100644
> > > --- a/man7/environ.7
> > > +++ b/man7/environ.7
> > > @@ -191,7 +191,10 @@ and
> > >  .IP *
> > >  .B TMPDIR
> > >  influences the path prefix of names created by
> > > -.BR tempnam (3)
> > > +.BR mktemp (1),
> > > +.BR mkstemp (3),
> > > +.BR mkdtemp (3),
> > > +.BR tmpfile (3),
> > >  and other routines, and the temporary directory used by
> > >  .BR sort (1)
> > >  and other programs.
> > > @@ -289,6 +292,7 @@ should consider renaming their option to
> > >  .BR csh (1),
> > >  .BR env (1),
> > >  .BR login (1),
> > > +.BR mktemp (1),
> > >  .BR printenv (1),
> > >  .BR sh (1),
> > >  .BR tcsh (1),
> > >
> >
> >
> > --
> > Michael Kerrisk
> > Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
> > Linux/UNIX System Programming Training: http://man7.org/training/
>


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#981171: [PATCH 03/13] Document that means at login time for HOME, LOGNAME, SHELL, USER

[Michael Kerrisk (man-pages)]

> Something like Note that behavior of su could lead to a mixed environment.

Yes, that would be fine.



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#981171: [PATCH 06/13] Improve pager section by pointing to more

[Michael Kerrisk (man-pages)]

On Fri, 29 Jan 2021 at 12:00, Bastien Roucariès
 wrote:
>
> Le jeudi 28 janvier 2021, 09:31:00 UTC Michael Kerrisk (man-pages) a écrit :
> > On 1/27/21 4:48 PM, roucaries.bast...@gmail.com wrote:
> > > From: Bastien Roucariès 
> > >
> > > More is the default pager in a lot of system mention it
> >
> > Really "more" and not "less"?
>
> Yes, debian distribution have been patched to fallback to pager that is less
> by default. But it is not the standard

I use Fedora. The default is "less" on the applications I looked at.
When you say "it is not the standard", can you say more precisely what
you mean?

Thanks,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#981171: Environment 7 improvments

[Michael Kerrisk (man-pages)]

Hello Bastien,

On 1/27/21 4:48 PM, roucaries.bast...@gmail.com wrote:
> Hi,
> 
> Could you find a serie for better documenting environment

Thank you for your efforts, but there's much to fix, I'm sorry.
I've applied two of the patches, but most of the others need revision,
or better commit messages, or should be dropped.

Thanks,

Michael

> [PATCH 01/13] Do not document mktemp (3)
> [PATCH 02/13] Add a note about portability of environment variable
> [PATCH 03/13] Document that means at login time for HOME, LOGNAME,
> [PATCH 04/13] Document PATH resolution
> [PATCH 05/13] Add see also ld.so (8) for LD_ variables
> [PATCH 06/13] Improve pager section by pointing to more
> [PATCH 07/13] Better documentation of _GNU_SOURCE for environment
> [PATCH 08/13] Better documentation of the environment mechanism
> [PATCH 09/13] Document convention of string in environ
> [PATCH 10/13] Introduce ENVIRONMENT section
> [PATCH 11/13] Reorganize the different environment section
> [PATCH 12/13] Introduce the user custumization section
> [PATCH 13/13] Document LINES and COLUMNS
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#981171: [PATCH 09/13] Document convention of string in environ

[Michael Kerrisk (man-pages)]

Hello Bastien,

On 1/27/21 4:48 PM, roucaries.bast...@gmail.com wrote:
> From: Bastien Roucariès 
> 
> Document the name=value system and that nul byte is forbidden
> 
> Signed-off-by: Bastien Roucariès 

I've applied this patch, but please see a note below.

> ---
>  man7/environ.7 | 12 +---
>  1 file changed, 9 insertions(+), 3 deletions(-)
> 
> diff --git a/man7/environ.7 b/man7/environ.7
> index f9e49a572..f2786fa09 100644
> --- a/man7/environ.7
> +++ b/man7/environ.7
> @@ -90,6 +90,15 @@ current language, etc., and a user can define additional 
> variables for other pur
>  The set of all environment variables that have values is collectively known 
> as
>  the process environment or simply the environment.
>  .PP
> +By convention, the strings in
> +.I environ
> +have the form "\fIname\fP\fB=\fP\fIvalue\fP".
> +Names of environment variables are case-sensitive and must not contain
> +the character "\fB=\fP". The values of environment variables can be anything

Please start new sentences on new lines.

> +that can be represented as a string. A value and a name must not contain an
> +embedded null byte (\(aq\e0\(aq),
> +since this is assumed to terminate the string.
> +.PP
>  This array of strings is made available to the process by the
>  .BR exec (3)
>  call that started the process.
> @@ -99,9 +108,6 @@ it inherits a
>  .I copy
>  of its parent's environment.
>  .PP
> -By convention the strings in
> -.I environ
> -have the form "\fIname\fP\fB=\fP\fIvalue\fP".
>  Common examples are:
>  .TP
>  .B USER

Thanks,

Michael



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#981171: [PATCH 08/13] Better documentation of the environment mechanism

[Michael Kerrisk (man-pages)]

On 1/27/21 4:48 PM, roucaries.bast...@gmail.com wrote:
> From: Bastien Roucariès 
> 
> Compare with argc/argv 

Why? The commit message should explain why you think this 
change is useful.

Thanks,

Michael

> and describe the purpose of environment
> ---
>  man7/environ.7 | 24 
>  1 file changed, 24 insertions(+)
> 
> diff --git a/man7/environ.7 b/man7/environ.7
> index 7eeb1fe0e..f9e49a572 100644
> --- a/man7/environ.7
> +++ b/man7/environ.7
> @@ -66,6 +66,30 @@ if the
>  feature test macro is defined (see
>  .BR feature_test_macros(7)).
>  .PP
> +At time of execution, a program receives context information by two 
> mechanisms.
> +The first way is the program arguments, represented by the
> +.I argc
> +and
> +.I argv
> +arguments of the
> +.I main
> +function. The second is the
> +.I environ
> +variable as discussed in this manual.
> +.PP
> +The program arguments are typically used to pass so-called
> +command-line arguments specific to a particular use of the program
> +being invoked, thus changing the program's behavior for this use case.
> +The environment, on the other hand, keeps track of information that is 
> shared by many programs and
> +rarely changes. For example, a running process can query the value of the
> +.B TMDIR
> +environment variable to discover a suitable location to store temporary 
> files.
> +.PP
> +Standard environment variables are used for information about the user' home 
> directory,
> +current language, etc., and a user can define additional variables for other 
> purposes.
> +The set of all environment variables that have values is collectively known 
> as
> +the process environment or simply the environment.
> +.PP
>  This array of strings is made available to the process by the
>  .BR exec (3)
>  call that started the process.
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#981171: [PATCH 12/13] Introduce the user custumization section

[Michael Kerrisk (man-pages)]

Hello Bastien.

On 1/27/21 4:48 PM, roucaries.bast...@gmail.com wrote:
> From: Bastien Roucariès 


Again, a much better commit message is needed here, to explain what 
you are doing, and why.

> Signed-off-by: Bastien Roucariès 
> ---
>  man7/environ.7 | 74 ++
>  1 file changed, 39 insertions(+), 35 deletions(-)
> 
> diff --git a/man7/environ.7 b/man7/environ.7
> index 236025035..b461e93df 100644
> --- a/man7/environ.7
> +++ b/man7/environ.7
> @@ -82,7 +82,7 @@ command-line arguments specific to a particular use of the 
> program
>  being invoked, thus changing the program's behavior for this use case.
>  The environment, on the other hand, keeps track of information that is 
> shared by many programs and
>  rarely changes. For example, a running process can query the value of the
> -.B TMDIR
> +.B TMPDIR

This is a change completely unrelated to the commit message.
Also, it's actually a fix to a typo introduced in an earlier
patch (08) in this series. Please don't do this sort of thing.
If an earlier patch was broken, please fix that patch.

>  environment variable to discover a suitable location to store temporary 
> files.
>  .PP
>  Standard environment variables are used for information about the user' home 
> directory,
> @@ -161,15 +161,15 @@ Common examples of environment variables defined by 
> POSIX.1-2017 are defined in
>  section. Conforming applications shall not set these environment variables 
> to have
>  meanings other than as described.
>  .TP
> +.B HOME
> +A user's login directory.
> +Set at login time, see section NOTES below.
> +.TP
>  .B LOGNAME
>  The name of the logged-in user (used by some System-V derived programs
>  and POSIX.1-2017).
>  Set at login time, see section NOTES below.
>  .TP
> -.B HOME
> -A user's login directory.
> -Set at login time, see section NOTES below.
> -.TP
>  .B PATH
>  The list of places that shells and other programs look in to find
>  a command when given an incomplete pathname. Elements on this
> @@ -204,26 +204,16 @@ Set at login time, see section NOTES below.
>  .B TERM
>  The terminal type for which output is to be prepared.
>  .TP
> -.B PAGER
> -The user's preferred utility to display text files.
> -Any string acceptable as a command_string operand to the
> -.I sh\ \-c
> -command shall be valid. If the
> -.B PAGER
> -variable is null or not set,
> -command could fall back
> -.B more (1)
> -or any suitable paging utility as the system default.
> -.TP
> -.BR EDITOR / VISUAL
> -The user's preferred utility to edit text files.
> -Any string acceptable as a command_string operand to the
> -.I sh\ \-c
> -command shall be valid.
> -.\" .TP
> -.\" .B BROWSER
> -.\" The user's preferred utility to browse URLs. Sequence of colon-separated
> -.\" browser commands. See http://www.catb.org/\(tiesr/BROWSER/ .
> +.B TMPDIR
> +The current temporary directory.
> +Influences the path prefix of names created by
> +.BR mktemp (1),
> +.BR mkstemp (3),
> +.BR mkdtemp (3),

TMPDIR does not influence the above three, as far as I know. See my 
comments in patch 01.

> +.BR tmpfile (3),
> +and other routines, and the temporary directory used by
> +.BR sort (1)
> +and other programs.
>  .SH INTERNATIONALIZATION ENVIRONMENT VARIABLES
>  .TP
>  .B LANG
> @@ -247,21 +237,35 @@ for further details of the
>  and
>  .B LC_*
>  environment variables.
> +.SH USER CUSTOMIZATION ENVIRONMENT VARIABLES
> +The following variables are commonly used for personalizing
> +applications used by the user.
> +.TP
> +.B PAGER
> +The user's preferred utility to display text files.
> +Any string acceptable as a command_string operand to the
> +.I sh\ \-c
> +command shall be valid. If the
> +.B PAGER
> +variable is null or not set,
> +command could fall back
> +.B more (1)
> +or any suitable paging utility as the system default.
> +.TP
> +.BR EDITOR / VISUAL
> +The user's preferred utility to edit text files.
> +Any string acceptable as a command_string operand to the
> +.I sh\ \-c
> +command shall be valid. Defined by POSIX.1-2017.
> +.\" .TP
> +.\" .B BROWSER
> +.\" The user's preferred utility to browse URLs. Sequence of colon-separated
> +.\" browser commands. See http://www.catb.org/\(tiesr/BROWSER/ .
>  .SH COMMON ENVIRONMENT VARIABLES
>  Note that the behavior of many programs and library routines is
>  influenced by the presence or value of certain environment variables.
>  Examples include the following:
>  .IP * 3
> -.B TMPDIR
> -influences the path prefix of names created by
> -.BR mktemp (1),
> -.BR mkstemp (3),
> -.BR mkdtemp (3),
> -.BR tmpfile (3),
> -and other routines, and the temporary directory used by
> -.BR sort (1)
> -and other programs.
> -.IP *
>  .BR LD_LIBRARY_PATH ", " LD_PRELOAD ,
>  and other
>  .BR LD_*

Thanks,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#981171: [PATCH 10/13] Introduce ENVIRONMENT section

[Michael Kerrisk (man-pages)]

Hello Bastien,

On 1/27/21 4:48 PM, roucaries.bast...@gmail.com wrote:
> From: Bastien Roucariès 

A commit like this deserves a much more detailed commit
message explaining what you are doing and why.
I think there's some good stuff below. but I need a better
commit message, and also this patch probably doesn't apply
without the previous patches.

Thanks,

Michael

> Signed-off-by: Bastien Roucariès 
> ---
>  man7/environ.7 | 92 +++---
>  1 file changed, 49 insertions(+), 43 deletions(-)
> 
> diff --git a/man7/environ.7 b/man7/environ.7
> index f2786fa09..96d47be9f 100644
> --- a/man7/environ.7
> +++ b/man7/environ.7
> @@ -108,7 +108,55 @@ it inherits a
>  .I copy
>  of its parent's environment.
>  .PP
> -Common examples are:
> +Environment variables may be placed in the shell's environment by the
> +.I export
> +command in
> +.BR sh (1),
> +or by the
> +.I setenv
> +command if you use
> +.BR csh (1).
> +.PP
> +The initial environment of the shell is populated in various ways,
> +such as definitions from
> +.IR /etc/environment
> +that are processed by
> +.BR pam_env (8)
> +for all users at login time (on systems that employ
> +.BR pam (8)).
> +In addition, various shell initialization scripts, such as the system-wide
> +.IR /etc/profile
> +script and per-user initialization scripts may include commands
> +that add variables to the shell's environment;
> +see the manual page of your preferred shell for details.
> +.PP
> +Bourne-style shells support the syntax
> +.PP
> +NAME=value command
> +.PP
> +to create an environment variable definition only in the scope
> +of the process that executes
> +.IR command .
> +Multiple variable definitions, separated by white space, may precede
> +.IR command .
> +.PP
> +Arguments may also be placed in the
> +environment at the point of an
> +.BR exec (3).
> +A C program can manipulate its environment using the functions
> +.BR getenv (3),
> +.BR putenv (3),
> +.BR setenv (3),
> +and
> +.BR unsetenv (3).
> +.PP
> +What follows is a list of environment variables typically seen on a
> +system. This list is incomplete and includes only common variables seen
> +by average users in their day-to-day routine.
> +Environment variables specific to a particular program or library function
> +are documented in the ENVIRONMENT section of the appropriate manual page.
> +.SH ENVIRONMENT
> +Common examples of environment variables are:
>  .TP
>  .B USER
>  The name of the logged-in user (used by some BSD-derived programs).
> @@ -196,48 +244,6 @@ command shall be valid.
>  .\" The user's preferred utility to browse URLs. Sequence of colon-separated
>  .\" browser commands. See http://www.catb.org/\(tiesr/BROWSER/ .
>  .PP
> -Names may be placed in the shell's environment by the
> -.I export
> -command in
> -.BR sh (1),
> -or by the
> -.I setenv
> -command if you use
> -.BR csh (1).
> -.PP
> -The initial environment of the shell is populated in various ways,
> -such as definitions from
> -.IR /etc/environment
> -that are processed by
> -.BR pam_env (8)
> -for all users at login time (on systems that employ
> -.BR pam (8)).
> -In addition, various shell initialization scripts, such as the system-wide
> -.IR /etc/profile
> -script and per-user initializations script may include commands
> -that add variables to the shell's environment;
> -see the manual page of your preferred shell for details.
> -.PP
> -Bourne-style shells support the syntax
> -.PP
> -NAME=value command
> -.PP
> -to create an environment variable definition only in the scope
> -of the process that executes
> -.IR command .
> -Multiple variable definitions, separated by white space, may precede
> -.IR command .
> -.PP
> -Arguments may also be placed in the
> -environment at the point of an
> -.BR exec (3).
> -A C program can manipulate its environment using the functions
> -.BR getenv (3),
> -.BR putenv (3),
> -.BR setenv (3),
> -and
> -.BR unsetenv (3).
> -.PP
>  Note that the behavior of many programs and library routines is
>  influenced by the presence or value of certain environment variables.
>  Examples include the following:
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#981171: [PATCH 05/13] Add see also ld.so (8) for LD_ variables

[Michael Kerrisk (man-pages)]

Hello Bastien,

On 1/27/21 4:48 PM, roucaries.bast...@gmail.com wrote:
> From: Bastien Roucariès 
> 
> Signed-off-by: Bastien Roucariès 

Thanks. I applied this patch, but had to make some patches.
See below.

> ---
>  man7/environ.7 | 3 ++-
>  1 file changed, 2 insertions(+), 1 deletion(-)
> 
> diff --git a/man7/environ.7 b/man7/environ.7
> index 11f30c332..81932d894 100644
> --- a/man7/environ.7
> +++ b/man7/environ.7
> @@ -212,7 +212,8 @@ and other programs.
>  .BR LD_LIBRARY_PATH ", " LD_PRELOAD ,
>  and other
>  .BR LD_*
> -variables influence the behavior of the dynamic loader/linker.
> +variables influence the behavior of the dynamic loader/linker. See also

Please start new sentences on new lines, See the discussion of semantic 
"newlines" in man-pages(7).

> +.B ld.so (8)

The previous line should have been

.BR ld.so (8).

Thanks,

Michael

>  .IP *
>  .B POSIXLY_CORRECT
>  makes certain programs and library routines follow



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#981171: [PATCH 06/13] Improve pager section by pointing to more

[Michael Kerrisk (man-pages)]

On 1/27/21 4:48 PM, roucaries.bast...@gmail.com wrote:
> From: Bastien Roucariès 
> 
> More is the default pager in a lot of system mention it

Really "more" and not "less"?

On my system, 'git commit' and 'man' use less(1) when PAGER 
is not set.

Thanks,

Michael

> ---
>  man7/environ.7 | 8 +++-
>  1 file changed, 7 insertions(+), 1 deletion(-)
> 
> diff --git a/man7/environ.7 b/man7/environ.7
> index 81932d894..981038ea1 100644
> --- a/man7/environ.7
> +++ b/man7/environ.7
> @@ -132,7 +132,12 @@ The terminal type for which output is to be prepared.
>  The user's preferred utility to display text files.
>  Any string acceptable as a command_string operand to the
>  .I sh\ \-c
> -command shall be valid.
> +command shall be valid. If the
> +.B PAGER
> +variable is null or not set,
> +command could fall back
> +.B more (1)
> +or any suitable paging utility as the system default.
>  .TP
>  .BR EDITOR / VISUAL
>  The user's preferred utility to edit text files.
> @@ -362,6 +367,7 @@ should use instead an explicit \(aq\fB.\fP\(aq.
>  .BR env (1),
>  .BR login (1),
>  .BR mktemp (1),
> +.BR more (1),
>  .BR printenv (1),
>  .BR sh (1),
>  .BR su (1),
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#981171: [PATCH 04/13] Document PATH resolution

[Michael Kerrisk (man-pages)]

Hello Bastien,

On 1/27/21 4:48 PM, roucaries.bast...@gmail.com wrote:
> From: Bastien Roucariès 
> 
> Document PATH resolution, particularly null sequence and empty PATH
> 
> Signed-off-by: Bastien Roucariès 
> ---
>  man7/environ.7 | 42 ++
>  1 file changed, 34 insertions(+), 8 deletions(-)
> 
> diff --git a/man7/environ.7 b/man7/environ.7
> index 8fc26bb92..11f30c332 100644
> --- a/man7/environ.7
> +++ b/man7/environ.7
> @@ -68,7 +68,8 @@ The name of the logged-in user (used by some BSD-derived 
> programs).
>  Set at login time, see section NOTES below.
>  .TP
>  .B LOGNAME
> -The name of the logged-in user (used by some System-V derived programs).
> +The name of the logged-in user (used by some System-V derived programs
> +and POSIX.1-2017).

Please don't include unrelated changes in the same patch.

>  Set at login time, see section NOTES below.
>  .TP
>  .B HOME
> @@ -94,19 +95,27 @@ for further details of the
>  environment variables).
>  .TP
>  .B PATH
> -The sequence of directory prefixes that
> -.BR sh (1)
> -and many other
> -programs apply in searching for a file known by an incomplete pathname.
> -The prefixes are separated by \(aq\fB:\fP\(aq.
> -(Similarly one has
> +The list of places that shells and other programs look in to find
> +a command when given an incomplete pathname. Elements on this
> +colon-separated  (\(aq\fB:\fP\(aq) list may be absolute or relative directory
> +names or the zero-length string (interpreted as meaning the
> +current directory, see section BUGS below).
> +.B PATH
> +is checked element by element (left to right), applying that directory
> +name as a prefix to the pathname (if it does not already
> +end in a slash, the expansion will insert one between
> +the prefix and the filename),
> +until a file is found with the appropriate name and execution
> +permissions.
> +.IP
> +Similarly one has
>  .B CDPATH
>  used by some shells to find the target
>  of a change directory command,
>  .B MANPATH
>  used by
>  .BR man (1)
> -to find manual pages, and so on)
> +to find manual pages, and so on.
>  .TP
>  .B PWD
>  The current working directory.
> @@ -254,6 +263,9 @@ and
>  are specified by
>  POSIX.1-1996
>  and should be reasonably portable.
> +.PP
> +.B PATH
> +behavior is specified by  POSIX.1-2017.

When you write this, it implies that the behavior was not specified
in earlier in earlier versions of POSIX. Is that true?

>  .SH NOTES
>  The
>  .BR prctl (2)
> @@ -292,6 +304,12 @@ preserves all the variables from the existing shell, and
>  or
>  .I su -l
>  is the recommended way of getting a full root environment.
> +.PP
> +The default search path (used when the environment
> +does not contain the variable \fBPATH\fR)
> +shows some variation across systems. See
> +.B execlp (3)
> +for documentation of the exact behavior.
>  .SH BUGS
>  Clearly there is a security risk here.
>  Many a system command has been
> @@ -330,6 +348,13 @@ The authors of
>  .I gzip
>  should consider renaming their option to
>  .BR GZIP_OPT .
> +.PP
> +A zero-length element in
> +.B PATH,
> +which appears as two adjacent colons \(aq\fB::\fP\(aq or as a leading
> +or trailing colon on the list, is replaced by implicit \(aq\fB.\fP\(aq.
> +In order to be portable and strictly conformant to POSIX.1-2017, a user
> +should use instead an explicit \(aq\fB.\fP\(aq.
>  .SH SEE ALSO
>  .BR bash (1),
>  .BR csh (1),
> @@ -343,6 +368,7 @@ should consider renaming their option to
>  .BR execve (2),
>  .BR clearenv (3),
>  .BR exec (3),
> +.BR execlp (3),

I think this line isn't needed. You mention execlp(3) already above.

>  .BR getenv (3),
>  .BR putenv (3),
>  .BR setenv (3),

I generally like the idea of this patch, but I can't apply it
because of
(a) My first comment above
(b) It depends on earlier patches that I havne't applied.

Thanks,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#981171: [PATCH 07/13] Better documentation of _GNU_SOURCE for environment

[Michael Kerrisk (man-pages)]

Hello Bastien,

On 1/27/21 4:48 PM, roucaries.bast...@gmail.com wrote:
> From: Bastien Roucariès 
> 
> Use feature_test_macros and document that historically
> you should manually declare it.
> ---
>  man7/environ.7 | 24 +---
>  1 file changed, 21 insertions(+), 3 deletions(-)
> 
> diff --git a/man7/environ.7 b/man7/environ.7
> index 981038ea1..7eeb1fe0e 100644
> --- a/man7/environ.7
> +++ b/man7/environ.7
> @@ -36,19 +36,36 @@
>  environ \- user environment
>  .SH SYNOPSIS
>  .nf
> +.B #include 
> +.PP
>  .BI "extern char **" environ ;
>  .fi
> +.PP
> +.RS -4
> +Feature Test Macro Requirements for glibc (see
> +.BR feature_test_macros (7)):
> +.RE
> +.PP
> +.I environ:
> +.nf
> +_GNU_SOURCE
> +.fi

I fear that documenting this in the SYNOPSIS encourages
reliance on nonstandard behavior. I think the existing text
is nearly sufficient. 

>  .SH DESCRIPTION
>  The variable
>  .I environ
>  points to an array of pointers to strings called the "environment".
>  The last pointer in this array has the value NULL.
> -(This variable must be declared in the user program,
> -but is declared in the header file
> +.PP
> +Historically and by standard, this variable must be declared in the user 
> program,
> +but for programmer convenience
> +.I environ
> +is also declared in the header file

I like some of the wording you added here, and I've added.
But, at the same time, I've demoted this piece of text to NOTES,
since it cluttered up the initial paragraph, and as noted above,
I wouldn't encourage use of this nonstandard feature in portable
code.

Thanks,

Michael

>  .I 
>  if the
>  .B _GNU_SOURCE
> -feature test macro is defined.)
> +feature test macro is defined (see
> +.BR feature_test_macros(7)).
> +.PP
>  This array of strings is made available to the process by the
>  .BR exec (3)
>  call that started the process.
> @@ -380,6 +397,7 @@ should use instead an explicit \(aq\fB.\fP\(aq.
>  .BR putenv (3),
>  .BR setenv (3),
>  .BR unsetenv (3),
> +.NR feature_test_macros(7),
>  .BR locale (7),
>  .BR ld.so (8),
>  .BR pam_env (8)
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#981171: [PATCH 13/13] Document LINES and COLUMNS

[Michael Kerrisk (man-pages)]

Hello Bastiern,

On 1/27/21 4:48 PM, roucaries.bast...@gmail.com wrote:
> From: Bastien Roucariès 
> 
> Document the variable LINES and COLUMN
> 
> Signed-off-by: Bastien Roucariès 
> ---
>  man7/environ.7 | 45 ++---
>  1 file changed, 42 insertions(+), 3 deletions(-)
> 
> diff --git a/man7/environ.7 b/man7/environ.7
> index b461e93df..5665ac4d2 100644
> --- a/man7/environ.7
> +++ b/man7/environ.7
> @@ -241,6 +241,48 @@ environment variables.
>  The following variables are commonly used for personalizing
>  applications used by the user.
>  .TP
> +.B COLUMNS

The following text is copied almost word for word from the standard.
For copyright reasons, we can't do that.

> +This variable is a non-negative decimal integer used to indicate the user's 
> preferred width
> +in column positions for the terminal screen or window.
> +If this variable is unset, set to zero, or empty, applications will

How did you determine the bit about 'set to zero'? That's 
not mentioned in the standard?

Similar comments to the above, for LINES, below.

Thanks,

Michael


> +determine the appropriate value themselves.
> +When the
> +.B COLUMNS
> +environment variable
> +is set, any terminal-width information implied by the
> +.B TERM
> +environment variable is overridden.
> +.IP
> +Users and applications should not set
> +.B COLUMNS
> +unless they wish to override the system selection.
> +In this case, applications may produce output unrelated to the terminal 
> characteristics.
> +Users should not need to set this variable in the environment unless
> +there is a specific reason to override the implementation's default behavior,
> +such as to display data in an area arbitrarily smaller than the terminal or 
> window.
> +.TP
> +.B LINES
> +This variable is a non-negative decimal integer used to indicate the user's 
> preferred
> +number of lines for the terminal screen or window.
> +If this variable is unset, set to zero, or empty, applications will
> +determine the appropriate value themselves.
> +When the
> +.B LINES
> +environment variable
> +is set, any terminal-width information implied by the
> +.B TERM
> +environment variable is overridden.
> +.IP
> +As for the related variable
> +.B COLUMNS,
> +users and applications should not set
> +.B LINES
> +unless they wish to override the system selection.
> +In this case, applications may produce output unrelated to the terminal 
> characteristics.
> +Users should not need to set this variable in the environment unless
> +there is a specific reason to override the implementation's default behavior,
> +such as to display data in an area arbitrarily smaller than the terminal or 
> window.
> +.TP
>  .B PAGER
>  The user's preferred utility to display text files.
>  Any string acceptable as a command_string operand to the
> @@ -307,9 +349,6 @@ See also
>  gives information on how to address a given terminal
>  (or gives the name of a file containing such information).
>  .IP *
> -.BR COLUMNS " and " LINES
> -tell applications about the window size, possibly overriding the actual size.
> -.IP *
>  .BR PRINTER " or " LPDEST
>  may specify the desired printer to use.
>  See
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#981171: [PATCH 02/13] Add a note about portability of environment variable

[Michael Kerrisk (man-pages)]

Hello Bastien,

On 1/27/21 4:48 PM, roucaries.bast...@gmail.com wrote:
> From: Bastien Roucariès 
> 
> Some variables are portable at least under UNIX
> 
> Signed-off-by: Bastien Roucariès 
> ---
>  man7/environ.7 | 11 +++
>  1 file changed, 11 insertions(+)
> 
> diff --git a/man7/environ.7 b/man7/environ.7
> index d889310d6..ec886d83d 100644
> --- a/man7/environ.7
> +++ b/man7/environ.7
> @@ -242,6 +242,17 @@ tell applications about the window size, possibly 
> overriding the actual size.
>  may specify the desired printer to use.
>  See
>  .BR lpr (1).
> +.SH CONFORMING TO
> +The variables
> +.B HOME
> +.B LOGNAME,
> +.B PATH,
> +.B PWD,
> +and
> +.B SHELL
> +are specified by
> +POSIX.1-1996
> +and should be reasonably portable.

Why this particular version of the standard? You don't explain.

I don't have a copy of POSIX.1-1996; where did you find it?

I do have a copy of SUSv3, where I expect that much of the detail
is the same as 1996, and there are many other environment variables
specified in that standard, including TZ, LC_*, LINES, COLUMNS, and
TMPDIR. If you start mentioning standards, but you list only 
HOME, LOGNAME, PATH, and PWD, I think it implies to the reader
that those other variables are *not* specified in the standard.

If we're going to document which EVs are in the standards,
(and I'm not sure it is something we want to do), then I think
the information needs to be more consistently done, and also
in the commit message I would want much more precise details
about where the info about each variable was foind.

Thanks,

Michael


>  .SH NOTES
>  The
>  .BR prctl (2)
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#981171: [PATCH 03/13] Document that means at login time for HOME, LOGNAME, SHELL, USER

[Michael Kerrisk (man-pages)]

Hello Bastien,

On 1/27/21 4:48 PM, roucaries.bast...@gmail.com wrote:
> From: Bastien Roucariès 
> 
> Clearly document that su by default does not change this variables.

I'm dubious about this. The place that this should be (and is)
properly documented is the manual page for su(1). Why repeat it
here?

Thanks,

Miuchael

> Signed-off-by: Bastien Roucariès 
> ---
>  man7/environ.7 | 41 +
>  1 file changed, 37 insertions(+), 4 deletions(-)
> 
> diff --git a/man7/environ.7 b/man7/environ.7
> index ec886d83d..8fc26bb92 100644
> --- a/man7/environ.7
> +++ b/man7/environ.7
> @@ -65,15 +65,15 @@ Common examples are:
>  .TP
>  .B USER
>  The name of the logged-in user (used by some BSD-derived programs).
> +Set at login time, see section NOTES below.
>  .TP
>  .B LOGNAME
>  The name of the logged-in user (used by some System-V derived programs).
> +Set at login time, see section NOTES below.
>  .TP
>  .B HOME
> -A user's login directory, set by
> -.BR login (1)
> -from the password file
> -.BR passwd (5).
> +A user's login directory.
> +Set at login time, see section NOTES below.
>  .TP
>  .B LANG
>  The name of a locale to use for locale categories when not overridden
> @@ -114,6 +114,7 @@ Set by some shells.
>  .TP
>  .B SHELL
>  The absolute pathname of the user's login shell.
> +Set at login time, see section NOTES below.
>  .TP
>  .B TERM
>  The terminal type for which output is to be prepared.
> @@ -260,6 +261,37 @@ The
>  and
>  .B PR_SET_MM_ENV_END
>  operations can be used to control the location of the process's environment.
> +.PP
> +The
> +.B HOME,
> +.B LOGNAME,
> +.B SHELL
> +and
> +.B USER
> +variables are set from a user database (such as the
> +.B password (5)
> +database) only when when a user is changed using the
> +session management interface, for instance by the
> +.B login(1)
> +program.
> +In particular, the
> +.B setuid (2)
> +family of functions does not set these variables.
> +Note that as documented in
> +.B su (1),
> +getting a root shell with just the command
> +.I su
> +results in a mixed environment where
> +.B LOGNAME
> +and
> +.B USER
> +are retained from the old user. Using
> +.I su -p
> +preserves all the variables from the existing shell, and
> +.I su -
> +or
> +.I su -l
> +is the recommended way of getting a full root environment.
>  .SH BUGS
>  Clearly there is a security risk here.
>  Many a system command has been
> @@ -306,6 +338,7 @@ should consider renaming their option to
>  .BR mktemp (1),
>  .BR printenv (1),
>  .BR sh (1),
> +.BR su (1),
>  .BR tcsh (1),
>  .BR execve (2),
>  .BR clearenv (3),
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#981171: [PATCH 01/13] Do not document mktemp (3)

[Michael Kerrisk (man-pages)]

Salut Bastien,

On 1/27/21 4:48 PM, roucaries.bast...@gmail.com wrote:
> From: Bastien Roucariès 
> 
> Do not use for documentation purposes the unsecure mktemp function

This message doesn't correspond to the change below (which removes
a reference to "tempnam" and adds a reference to "mktemp".

But also, I don't think it makes systems more secure to
remove the info that tempnam is influence by TMPDIR.

And, this patch is surely not correct. Yes, TMPDIR influences
tmpfile(3). But how does TMPDIR influence mktemp(3), mkstemp(3),
and mkdtemp(3), which base the temporary filename on a path
supplied by the caller?

Finally, a request for patches: the format of the 
subject line should rather be:

[PATCH ...] environ.7: Do not document...

Thanks,

Michael

> Signed-off-by: Bastien Roucariès 
> ---
>  man7/environ.7 | 6 +-
>  1 file changed, 5 insertions(+), 1 deletion(-)
> 
> diff --git a/man7/environ.7 b/man7/environ.7
> index 182d823d2..d889310d6 100644
> --- a/man7/environ.7
> +++ b/man7/environ.7
> @@ -191,7 +191,10 @@ and
>  .IP *
>  .B TMPDIR
>  influences the path prefix of names created by
> -.BR tempnam (3)
> +.BR mktemp (1),
> +.BR mkstemp (3),
> +.BR mkdtemp (3),
> +.BR tmpfile (3),
>  and other routines, and the temporary directory used by
>  .BR sort (1)
>  and other programs.
> @@ -289,6 +292,7 @@ should consider renaming their option to
>  .BR csh (1),
>  .BR env (1),
>  .BR login (1),
> +.BR mktemp (1),
>  .BR printenv (1),
>  .BR sh (1),
>  .BR tcsh (1),
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#656657: manpages: environ(7): Please clarify the usage of $PAGER and $EDITOR with regards to whitespace

[Michael Kerrisk (man-pages)]

https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=866060
seems to be related, and maybe the changes in the patch for that bug
are sufficient to address the concerns in this bug? (That patch as
just been taken upstream.)

Thanks,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#942207: getauxval(3): Clarify that AT_EXECFN and AT_BASE_PLATFORM return pointers.

[Michael Kerrisk (man-pages)]

Hi,

This Debian bug was fixed quite some time ago upstream. Is there a
reason that the bug is still open?

Thanks,

Michael

On Sat, 12 Oct 2019 at 12:51, Witold Baryluk  wrote:
>
> Package: manpages-dev
> Version: 5.02-1
> Severity: normal
>
> Example:
>
>AT_PLATFORM
>   A  pointer  to a string that identifies the hardware platform 
> that the program is run‐
>   ning on.  The dynamic linker uses this in the interpretation of 
> rpath values.
>
>
> does tell it is a pointer.
>
> It is important as the signature is generic:
>
>unsigned long getauxval(unsigned long type);
>
>
> Do the same for:
>
>
>AT_BASE_PLATFORM
>   A string identifying the real platform; may differ from 
> AT_PLATFORM (PowerPC only).
>
>AT_EXECFN
>   Pathname used to execute program.
>
>
> Cheers,
> Witold
>
>
>
> -- System Information:
> Debian Release: bullseye/sid
>   APT prefers testing
>   APT policy: (500, 'testing')
> Architecture: amd64 (x86_64)
> Foreign Architectures: i386
>
> Kernel: Linux 5.2.0-2-amd64 (SMP w/2 CPU cores)
> Kernel taint flags: TAINT_OOT_MODULE, TAINT_UNSIGNED_MODULE
> Locale: LANG=en_US.UTF-8, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8), 
> LANGUAGE=en_US:en (charmap=UTF-8)
> Shell: /bin/sh linked to /bin/dash
> Init: systemd (via /run/systemd/system)
> LSM: AppArmor: enabled
>
> Versions of packages manpages-dev depends on:
> ii  manpages  5.02-1
>
> manpages-dev recommends no packages.
>
> Versions of packages manpages-dev suggests:
> ii  man-db [man-browser]  2.8.7-3
>
> -- no debconf information



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#866060: environ(7): please document the valid values of pathnames for SHELL, PAGER and EDITOR/VISUAL

[Michael Kerrisk (man-pages)]

tags 866060 fixed-upstream
thanks

This patch has been applied upstream.

Cheers,

Michael


On Wed, 13 Jan 2021 at 11:15, Bastien Roucariès
 wrote:
>
> Package: manpages
> Version: 5.10-1
> Followup-For: Bug #866060
>
> Dear Maintainer,
>
> Please found the included patch
>
> Please apply



--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#976312: modf.3: wrong Feature Test Macro Requirements

[Michael Kerrisk (man-pages)]

tags 976312 fixed-upstream
thanks

On Thu, 3 Dec 2020 at 10:18, Bill Allombert  wrote:
>
> Package: manpages-dev
> Version: 4.16-2
> Severity: normal
>
> Hello Tobias,
>
> man modf says:
>
>Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
>
>modf(), modfl():
>_ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
>|| /* Since glibc 2.19: */ _DEFAULT_SOURCE
>|| /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
>
> However as I understand, it should be
>modff(), modfl():
>
> instead. (modf is c89, but not modff)

Thanks. I've fixed the upstream page.

Cheers,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#933000: resolv.conf(5): refers to MAXNS in , but it's in res_state.h now

[Michael Kerrisk (man-pages)]

tags 933000 wontfix
thanks

Upstream maintainer here. As I previously explained, this is not a
valid bug report, and should be closed.

Bug#909789: manpages-dev: stat(2) manpage on ENOENT for dangling symbolic links (broken links)

[Michael Kerrisk (man-pages)]

tags 909789 fixed-upstream
thanks



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#959680: Unclear error handling of hsearch_r in manpage

[Michael Kerrisk (man-pages)]

Hi Witold,

I think you'll have to close the bug. I don't think I have the
necessary rights to fgo that in the bug tracker.

Thanks,

Michael

On Wed, 20 May 2020 at 01:57, Witold Baryluk  wrote:
>
> Hi Michael.
>
> It looks I was inspecting an outdated version of manpages on another
> system, that didn't mention errno.
>
> You are right the current version in Debian does clearly states how
> the errors are communicate.
>
> Please close this bug.
>
> Sorry for the confusion, and thanks for a quick response.
>
> On Wed, 6 May 2020 at 10:27, Michael Kerrisk (man-pages)
>  wrote:
> >
> > Hello Witold,
> >
> > > The man page doesn't tell how the error code is returned back to the
> > > caller.
> > >
> > > Looking at the source code of hsearch and hsearch_r it looks to be via
> > > errno, but manpage doesn't mention this at all.
> >
> > I'm a bit lost here. The manual page says:
> >
> >In the event of an error, these two functions set errno to
> >indicate the cause of the error.
> >
> > This seems clear to me, or, otherwise, I really am missing your
> > point, I'm sorry.
> >
> > --
> > Michael Kerrisk
> > Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
> > Linux/UNIX System Programming Training: http://man7.org/training/



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#959680: Unclear error handling of hsearch_r in manpage

[Michael Kerrisk (man-pages)]

Hello Witold,

> The man page doesn't tell how the error code is returned back to the
> caller.
> 
> Looking at the source code of hsearch and hsearch_r it looks to be via
> errno, but manpage doesn't mention this at all.

I'm a bit lost here. The manual page says:

   In the event of an error, these two functions set errno to
   indicate the cause of the error.

This seems clear to me, or, otherwise, I really am missing your 
point, I'm sorry.

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#959680: Unclear error handling of hsearch_r in manpage

[Michael Kerrisk (man-pages)]

On Sun, 3 May 2020 at 20:45, Witold Baryluk  wrote:
>
> Package: manpages-dev
> Version: 5.06-1
> Severity: normal
>
> Reading manual:
>
> """
> int hsearch_r(ENTRY item, ACTION action, ENTRY **retval,
>   struct hsearch_data *htab);
>
> Return Value:
>
> hsearch_r() returns nonzero on success, and 0 on error.
>
> Errors:
>
> hsearch() and hsearch_r() can fail for the following reasons:
> ENOMEM
>
> action was ENTER, key was not found in the table, and there was no room in 
> the table to add a new entry.
>
> ESRCH
>
> action was FIND, and key was not found in the table.
> """
>
>
> Well, there are few issues.
>
> if hsearch_r returns 0 on error, how are the "reasons" indicated back to
> the caller? The manpage doesn't say anything about it.

But, it does, I think (or I have misunderstood your point).. Under
RETURN VALUE, the manual page says:

   On success, hsearch() returns a pointer to an entry  in  the  hash
   table.   hsearch()  returns  NULL  on error, that is, if action is
   ENTER and the hash table is full, or action is FIND and item  can‐
   not  be  found  in the hash table.  hsearch_r() returns nonzero on
   success, and 0 on error.  In the event  of  an  error,  these  two
   functions set errno to indicate the cause of the error.

> Also I would expect the EINVAL to be returned by hsearch_r when htab is
> NULL.

Why would you expect this? you don't explain. I imagine rather that
the error might be EFAUL or Segmentation Violation (SIGSEGV).

Thanks,

Michael

Bug#947091: manpages-dev: timerfd_settime can fail with ECANCELED

[Michael Kerrisk (man-pages)]

tags 947091 fixed-upstream
thanks

Bug#947091: manpages-dev: timerfd_settime can fail with ECANCELED

[Michael Kerrisk (man-pages)]

tags 947091 fixed-upstream
thanks

Bug#947091: manpages-dev: timerfd_settime can fail with ECANCELED

[Michael Kerrisk (man-pages)]

tags fixed-upstrream
thanks

I applied the following patch upstream.

diff --git a/man2/timerfd_create.2 b/man2/timerfd_create.2
index ec137fbfe..98225dcad 100644
--- a/man2/timerfd_create.2
+++ b/man2/timerfd_create.2
@@ -477,6 +477,9 @@ is not a valid timerfd file descriptor.
 .BR timerfd_settime ()
 can also fail with the following errors:
 .TP
+.B ECANCELED
+See NOTES.
+.TP
 .B EINVAL
 .I new_value
 is not properly initialized (one of the
@@ -493,6 +496,52 @@ These system calls are available on Linux since kernel 2.6.
25.
 Library support is provided by glibc since version 2.8.
 .SH CONFORMING TO
 These system calls are Linux-specific.
+.SH NOTES
+Suppose the following scenario for
+.BR CLOCK_REALTIME
+or
+.BR CLOCK_REALTIME_ALARM
+timer that was created with
+.BR timerfd_create ():
+.IP (a) 4
+The timer has been started
+.RB ( timerfd_settime ())
+with the
+.BR TFD_TIMER_ABSTIME
+and
+.BR TFD_TIMER_CANCEL_ON_SET
+flags;
+.IP (b)
+A discontinuous change (e.g.
+.BR settimeofday (2))
+is subsequently made to the
+.BR CLOCK_REALTIME
+clock; and
+.IP (c)
+the caller once more calls
+.BR timerfd_settime ()
+to rearm the timer (without first doing a
+.BR read (2)
+on the file descriptor).
+.PP
+In this case the following occurs:
+.IP \(bu 2
+The
+.BR timerfd_settime ()
+returns \-1 with
+.I errno
+set to
+.BR ECANCELED .
+(This enables the caller to know that the previous timer was affected
+by a discontinuous change to the clock.)
+.IP \(bu
+The timer
+.I "is successfully rearmed"
+with the settings provided in the second
+.BR timerfd_settime ()
+call.
+(This was probably an implementation accident, but won't be fixed now,
+in case there are applications that depend on this behaviour.)
 .SH BUGS
 Currently,
 .\" 2.6.29

Bug#947091: manpages-dev: timerfd_settime can fail with ECANCELED

[Michael Kerrisk (man-pages)]

Here's a pointer to the upstream discussion:
https://lore.kernel.org/linux-man/4c557b44-4e4e-a689-a17b-f95e6c5ee...@gmail.com/T/#t

Bug#947091: manpages-dev: timerfd_settime can fail with ECANCELED

[Michael Kerrisk (man-pages)]

Upstream maintainer here.

On 12/20/19 9:32 PM, Marc Lehmann wrote:
> Package: manpages-dev
> Version: 5.04-1
> Severity: wishlist
> 
> Dear Maintainer,
> 
> the timerfd_create/settime/... manpage documents that reads from a timerfd
> configured with TFD_TIMER_CANCEL_ON_SET fail with ECANCELED, however, I
> found that timerfd_settime (and probably timerfd_gettime and others) have
> the same behaviour, and of course youc an poll for this event as well, and
> all this is not documented.

Thanks for the bug report.
Using a small test program, I can confirm that this behavior occurs
for timerfd_settime(). (It looks like it doesn't occur for
timerfd_gettime() though.)

> Background: I was implementing time jump detection in libev using the
> relatively new TFD_TIMER_CANCEL_ON_SET feature. For this, I arm the timer
> with some future value and only use it for the side effect of getting
> canceled (although it might occasionally expire).
> 
> The timerfd_create/settime calls look like this (future it_value.tv_sec
> value, zero interval):
> 
>timerfd_create(CLOCK_REALTIME, TFD_CLOEXEC|TFD_NONBLOCK) = 5
>timerfd_settime(5, TFD_TIMER_ABSTIME|TFD_TIMER_CANCEL_ON_SET, 
> {it_interval={tv_sec=0, tv_nsec=0}, it_value={tv_sec=1579464284, tv_nsec=0}}, 
> NULL) = 0
> 
> all normal so far: On every time jump, I rearm the timer with
> timerfd_settime, without having any other interaction with the timerfd
> (other than polling it for read events). The following is the effect of
> "date -s somevalue" three times:
> 
>timerfd_settime(5, TFD_TIMER_ABSTIME|TFD_TIMER_CANCEL_ON_SET, 
> {it_interval={tv_sec=0, tv_nsec=0}, it_value={tv_sec=949273200, tv_nsec=0}}, 
> NULL) = -1 ECANCELED (Operation canceled)
>timerfd_settime(5, TFD_TIMER_ABSTIME|TFD_TIMER_CANCEL_ON_SET, 
> {it_interval={tv_sec=0, tv_nsec=0}, it_value={tv_sec=949273200, tv_nsec=0}}, 
> NULL) = -1 ECANCELED (Operation canceled)
>timerfd_settime(5, TFD_TIMER_ABSTIME|TFD_TIMER_CANCEL_ON_SET, 
> {it_interval={tv_sec=0, tv_nsec=0}, it_value={tv_sec=949273200, tv_nsec=0}}, 
> NULL) = -1 ECANCELED (Operation canceled)
> 
>>From this, I learn that timerfd_settime fails the same way as a read would
> do (probably some error slippage happening) and despite timerfd_settime
> failing with ECANCELED, it actually succeeds in rearming the timer.

Likewise, I confirm that the call does seem to change the timer value, 
even though an error is returned.

> Don't know if this is a kernel bug, but I assume this works more or less
> as designed, but has escaped the documentation as TFD_TIMER_CANCEL_ON_SET
> is a relatively new feature.

Actually, it smells of a kernel bug to me. Either an ECANCELED error should
not be returned, or the timer should not get modified. But not both.
I will attempt to follow this up on LKML.

> As a minor nitpick, the "Operating on a timer file descriptor" is a tiny
> bit misleading, as it doesn't mention timerfd_gettime etc. as supported
> "operations on a timerfd fd". And while it probably isn't a major thing in
> the context, I do expect the utmost exactness from manpages-dev because
> that is my past experiencw with it, so I suggest adding "additional" here:
> 
>The file descriptor returned by timerfd_create() supports the
>following additional operations:

Yes, that makes sense. Done. (But not yet pushed to Git.)

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#942207: getauxval(3): Clarify that AT_EXECFN and AT_BASE_PLATFORM return pointers.

[Michael Kerrisk (man-pages)]

tags 942207 fixed-upstream
thanks

On Sat, 12 Oct 2019 at 12:51, Witold Baryluk  wrote:
>
> Package: manpages-dev
> Version: 5.02-1
> Severity: normal
>
> Example:
>
>AT_PLATFORM
>   A  pointer  to a string that identifies the hardware platform 
> that the program is run‐
>   ning on.  The dynamic linker uses this in the interpretation of 
> rpath values.
>
>
> does tell it is a pointer.
>
> It is important as the signature is generic:
>
>unsigned long getauxval(unsigned long type);
>
>
> Do the same for:
>
>
>AT_BASE_PLATFORM
>   A string identifying the real platform; may differ from 
> AT_PLATFORM (PowerPC only).
>
>AT_EXECFN
>   Pathname used to execute program.

Upstream maintainer here.   I've applied a patch similar to what you
suggest. Thanks for the report.

Cheers,

Michael

diff --git a/man3/getauxval.3 b/man3/getauxval.3
index f7b23085a..456371c6a 100644
--- a/man3/getauxval.3
+++ b/man3/getauxval.3
@@ -60,7 +60,7 @@ values are present on all architectures.
 The base address of the program interpreter (usually, the dynamic linker).
 .TP
 .BR AT_BASE_PLATFORM
-A string identifying the real platform; may differ from
+A pointer to a string identifying the real platform; may differ from
 .BR AT_PLATFORM
 (PowerPC only).
 .TP
@@ -87,7 +87,7 @@ The effective user ID of the thread.
 File descriptor of program.
 .TP
 .BR AT_EXECFN
-Pathname used to execute program.
+A pointer to a string containing the pathname used to execute the program.
 .TP
 .BR AT_FLAGS
 Flags (unused).

Bug#931325: manpages-dev: io_cancel can fail with EINTR

[Michael Kerrisk (man-pages)]

>>> I found that, at least with debians 4.19 kernel, io_cancel can fail with
>>> EINTR on signal delivery, which should be documented as per similar calls.
>>
>> Can you provide some more info on the circumstances where you observed
>> this behavior please.
> 
> Well, while developing the aio backend for libev, but the details are lost
> to my meory by now. I do remember having looked at the kernel code at the
> time to see why it would block, because I didn't expect it to.
> 
> Also, what more detail than "signal delivery can cause EINTR" do you have
> on your mind? 

The thing is, I like to do at least some level of checking of any bug
report. On occasion I've had people send me detailed, well-formed patches
that document something that when I check it turns out to be completely
wrong or a misunderstanding of the underlying details. I'm *not* saying
that this is the case here. But, without some help, it's hard for me to
verify anything.

> This cause of EINTR seems pretty standard to me (signal
> received while in interuptible wait - EINTR) - the only question to me
> would be whether io_cancel does interruptible waits, which isn't clear
> from the documentation, and would device whether it can result in EINTR or
> not.

And there you nailed the point. I want to get an angle to help me in
determining whether io_cancel() does interruptible waits. (It seems to
me plausible that it might do so--although I can't think of specific
cases--but I want to be able to check this.)

Thanks,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#931325: manpages-dev: io_cancel can fail with EINTR

[Michael Kerrisk (man-pages)]

Hello Marc,

On 7/1/19 10:34 PM, Marc Lehmann wrote:

Package: manpages-dev
Version: 4.16-2
Severity: minor

Dear Maintainer,

I found that, at least with debians 4.19 kernel, io_cancel can fail with
EINTR on signal delivery, which should be documented as per similar calls.


Can you provide some more info on the circumstances where you observed
this behavior please.

Thanks,

MIchael

Bug#933000: resolv.conf(5): refers to MAXNS in , but it's in res_state.h now

[Michael Kerrisk (man-pages)]

On 7/25/19 7:15 PM, Axel Beckert wrote:
> Package: manpages
> Version: 5.01-1
> Severity: normal
> File: /usr/share/man/man5/resolv.conf.5.gz
> 
> Hi,
> 
> resolv.conf(5); states:
> 
>nameserver Name server IP address
>   Internet address of a name server that the resolver should
>   query, either an IPv4 address (in dot notation), or an
>   IPv6 address in colon (and possibly dot) notation as per
>   RFC 2373.  Up to MAXNS (currently 3, see ) name
>   servers may be listed, one per keyword.
> But:
> 
> $ fgrep MAXNS /usr/include/resolv.h
> $
> 
> It seems to be in /usr/include/$TRIPLET/bits/types/res_state.h now:
> 
> $ fgrep MAXNS -r /usr/include/
> /usr/include/x86_64-linux-gnu/bits/types/res_state.h:#define MAXNS
>   3   /* max # name servers we'll track */

Upstream maintainer here...

This report is invalid.  includes bits/types/res_state.h

I suggest closing this bug.

Thanks,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#932382: manpages-dev: getutline(3): missing #include in example program

[Michael Kerrisk (man-pages)]

tags 932382 fixed-upstream
thanks

On 7/18/19 5:19 PM, Thorsten Glaser wrote:
> Package: manpages-dev
> Version: 5.01-1
> Severity: minor
> 
> I was just trying to compile the example program from the
> .Sh EXAMPLE
> of the getutline(3) manpage and saw this:
> 
> tglase@tglase:~ $ gcc x.c
> x.c: In function ‘main’:
> x.c:19:12: warning: implicit declaration of function ‘time’; did you mean 
> ‘utimes’? [-Wimplicit-function-declaration]
> time(_time);
> ^~~~
> utimes
> 
> Please fix that, to be a good example ☻
Upstream maintainer here. Fixed for the upcoming 5.02
release. Thanks for the report!

Cheers,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#926292: manpages-dev: memfd_create needs sys/mman.h, not sys/memfd.h

[Michael Kerrisk (man-pages)]

tags 926292 fixed-upstream
thanks

On Sun, 14 Apr 2019 at 19:16, Michael Kerrisk (man-pages)
 wrote:
>
> tags 926292 fixed-upstream
> thanks
>
> On Wed, 3 Apr 2019 at 04:42, Marc Lehmann  wrote:
> >
> > Package: manpages-dev
> > Version: 4.16-1
> > Severity: minor
> >
> > Dear Maintainer,
> >
> > the manpage for memfd_create documents:
> >
> >#include 
> >
> > but as far as I can tell, this heade rnever existed and trhere are not
> > plans to bring it into existance.
> >
> > Instead, the header to use is:
> >
> >#include 
> >
> > And it requires _GNU_SOURCE or equivalent.
> >
> > -- System Information:
> > Debian Release: 9.8
> >   APT prefers stable
> >   APT policy: (990, 'stable'), (500, 'unstable-debug'), (500, 
> > 'testing-debug'), (500, 'stable-updates'), (500, 'stable-debug'), (500, 
> > 'unstable'), (500, 'testing'), (1, 'experimental-debug'), (1, 
> > 'experimental')
> > Architecture: amd64 (x86_64)
> > Foreign Architectures: i386, x32
> >
> > Kernel: Linux 4.19.27-041927-generic (SMP w/8 CPU cores)
> > Locale: LANG=POSIX, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8), LANGUAGE=POSIX 
> > (charmap=UTF-8)
> > Shell: /bin/sh linked to /usr/bin/dash
> > Init: systemd (via /run/systemd/system)
> >
> > Versions of packages manpages-dev depends on:
> > ii  manpages  4.16-1
> >
> > manpages-dev recommends no packages.
> >
> > Versions of packages manpages-dev suggests:
> > ii  konqueror [man-browser]  4:16.08.3-1
> > ii  man-db [man-browser] 2.7.6.1-2
> >
> > -- no debconf information
> >
>
>
> --
> Michael Kerrisk
> Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
> Linux/UNIX System Programming Training: http://man7.org/training/



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#926292: manpages-dev: memfd_create needs sys/mman.h, not sys/memfd.h

[Michael Kerrisk (man-pages)]

tags 926292 fixed-upstream
thanks

On Wed, 3 Apr 2019 at 04:42, Marc Lehmann  wrote:
>
> Package: manpages-dev
> Version: 4.16-1
> Severity: minor
>
> Dear Maintainer,
>
> the manpage for memfd_create documents:
>
>#include 
>
> but as far as I can tell, this heade rnever existed and trhere are not
> plans to bring it into existance.
>
> Instead, the header to use is:
>
>#include 
>
> And it requires _GNU_SOURCE or equivalent.
>
> -- System Information:
> Debian Release: 9.8
>   APT prefers stable
>   APT policy: (990, 'stable'), (500, 'unstable-debug'), (500, 
> 'testing-debug'), (500, 'stable-updates'), (500, 'stable-debug'), (500, 
> 'unstable'), (500, 'testing'), (1, 'experimental-debug'), (1, 'experimental')
> Architecture: amd64 (x86_64)
> Foreign Architectures: i386, x32
>
> Kernel: Linux 4.19.27-041927-generic (SMP w/8 CPU cores)
> Locale: LANG=POSIX, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8), LANGUAGE=POSIX 
> (charmap=UTF-8)
> Shell: /bin/sh linked to /usr/bin/dash
> Init: systemd (via /run/systemd/system)
>
> Versions of packages manpages-dev depends on:
> ii  manpages  4.16-1
>
> manpages-dev recommends no packages.
>
> Versions of packages manpages-dev suggests:
> ii  konqueror [man-browser]  4:16.08.3-1
> ii  man-db [man-browser] 2.7.6.1-2
>
> -- no debconf information
>


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#926292: manpages-dev: memfd_create needs sys/mman.h, not sys/memfd.h

[Michael Kerrisk (man-pages)]

tags fixed-upstream
thanks

This error was fixed in the latest upstream version, which was
released a few weeks ago.

On Wed, 3 Apr 2019 at 04:42, Marc Lehmann  wrote:
>
> Package: manpages-dev
> Version: 4.16-1
> Severity: minor
>
> Dear Maintainer,
>
> the manpage for memfd_create documents:
>
>#include 
>
> but as far as I can tell, this heade rnever existed and trhere are not
> plans to bring it into existance.
>
> Instead, the header to use is:
>
>#include 
>
> And it requires _GNU_SOURCE or equivalent.
>
> -- System Information:
> Debian Release: 9.8
>   APT prefers stable
>   APT policy: (990, 'stable'), (500, 'unstable-debug'), (500, 
> 'testing-debug'), (500, 'stable-updates'), (500, 'stable-debug'), (500, 
> 'unstable'), (500, 'testing'), (1, 'experimental-debug'), (1, 'experimental')
> Architecture: amd64 (x86_64)
> Foreign Architectures: i386, x32
>
> Kernel: Linux 4.19.27-041927-generic (SMP w/8 CPU cores)
> Locale: LANG=POSIX, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8), LANGUAGE=POSIX 
> (charmap=UTF-8)
> Shell: /bin/sh linked to /usr/bin/dash
> Init: systemd (via /run/systemd/system)
>
> Versions of packages manpages-dev depends on:
> ii  manpages  4.16-1
>
> manpages-dev recommends no packages.
>
> Versions of packages manpages-dev suggests:
> ii  konqueror [man-browser]  4:16.08.3-1
> ii  man-db [man-browser] 2.7.6.1-2
>
> -- no debconf information
>


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#915874: rename(1): incorrect note since glibc 2.28

[Michael Kerrisk (man-pages)]

tags fixed-upstream
thanks

A patch to fix this page has already been applied
for the next upstream release.

Thanks,

Michael
(Upstream Maintainer)

On 12/7/18 2:43 PM, Johannes 'josch' Schauer wrote:
> Package: manpages
> Version: 4.16-1
> Severity: normal
> 
> Hi,
> 
> currently, the manpage for rename(2) states:
> 
>Note: There is no glibc wrapper for renameat2(); see NOTES.
> 
> and further down under NOTES:
> 
>Glibc does not provide a wrapper for the renameat2() system call; call
>it using syscall(2).
> 
> but version 2.28 introduced a renameat2() wrapper as can be seen in the
> corresponding section of its NEWS file:
> 
>  * The renameat2 function has been added, a variant of the renameat function
>which has a flags argument.  If the flags are zero, the renameat2 function
>acts like renameat.  If the flag is not zero and there is no kernel
>support for renameat2, the function will fail with an errno value of
>EINVAL.  This is different from the existing gnulib function renameatu,
>which performs a plain rename operation in case of a RENAME_NOREPLACE
>flags and a non-existing destination (and therefore has a race condition
>that can clobber the destination inadvertently).
> 
> So please correct the man page accordingly, as glibc 2.28 is now in
> unstable.
> 
> Thanks!
> 
> cheers, josch
> 
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#909789: manpages-dev: stat(2) manpage on ENOENT for dangling symbolic links (broken links)

[Michael Kerrisk (man-opages)]

tags fixed-upstream
thanks

On 09/28/2018 01:38 PM, Alessandro Vesely wrote:

Package: manpages-dev
Version: 4.10-2
Severity: minor

Dear Maintainer,


Hello Ale,

Upstream maintainer here...


it seems to be a gotcha having stat(x, y) unexpectedly return -1 when x is a
broken link.  The stat(1) command works where stat(2) fails.  The obvious
solution is to use lstat.

It is difficult to fix this without ineffectually lengthening the text.
Perhaps, using the concept of unlinked file, which is valid for hard and soft
links alike, might help.  For example, the man page says:

ENOENT A component of pathname does not exist, or pathname is an empty string.

Alternatively, it could say:

ENOENT A component of pathname is unlinked (does not exist), or pathname is an
empty string.


Thanks for your report!

It's not merely a question of a broken symlink in the final pathname
component, which lstat() could address. ENOENT can also occur if any
component in the pathname is a dangling symbolic link. So I changed the
ENOENT text to:

   ENOENT A  component  of  pathname  does not exist or is a
  dangling symbolic link.

   ENOENT pathname is an empty string and AT_EMPTY_PATH  was
  not specified in flags.


Besides, the 1st paragraph in the NOTES section says "AT_NO_AUTOMOUNT fag".
Please substitute "AT_NO_AUTOMOUNT flag" lest someone smokes their unmounted
devices...


:-)

In fact, that text was fixed about a year ago, so you don't have quite
the most up-to-date pages :-).


Thanks for maintaining man pages


You are welcome!

Cheers,

Michael




-- System Information:
Debian Release: 9.5
   APT prefers stable
   APT policy: (500, 'stable')
Architecture: amd64 (x86_64)
Foreign Architectures: i386

Kernel: Linux 4.9.0-8-amd64 (SMP w/4 CPU cores)
Locale: LANG=en_IE.UTF-8, LC_CTYPE=en_IE.UTF-8 (charmap=UTF-8),
LANGUAGE=en_IE.UTF-8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/bash
Init: sysvinit (via /sbin/init)

Versions of packages manpages-dev depends on:
ii  manpages  4.10-2

manpages-dev recommends no packages.

Versions of packages manpages-dev suggests:
ii  jed-extra [man-browser]  2.5.7-2
ii  man-db [man-browser] 2.7.6.1-2

Bug#882222: Document security problems with system.3 and popen.3 (argument injection)

[Michael Kerrisk (man-pages)]

Hello Bastien

On 22 November 2017 at 14:53, Bastien ROUCARIES
<roucaries.bast...@gmail.com> wrote:
> On Wed, Nov 22, 2017 at 2:45 PM, Michael Kerrisk (man-pages)
> <mtk.manpa...@gmail.com> wrote:
>>> Could you also warn about popen ?
>>
>> I already added a cross reference from popen(3) to the Caveats section
>> in system(3). I should have mentioned that before.
>>
>>> And mention that system(sprintf("command %s")) is a security hole
>>
>> That seems obviously dangerous. But don't you think it is covered by this 
>> text:
>>
>>Any user input that is employed as part of command should be care‐
>>fully sanitized, to ensure that unexpected shell commands or  com‐
>>mand  options  are  not executed.  Such risks are especially grave
>>when using system() from a privileged program.
>> ?
>
> Yes but does not avoid tentation do use escape character
>>
>>> BTW escaping char is hard with shell, better to use execvp
>>
>> Agreed. I would not attempt escaping. Safer to allow only a whitelist
>> of permited characters from user input.
>
> Could you therefore add:
> It is particularly hard to escape argument portably on all the POSIX
> system, including shell variation. It is safer to allow only a
> whitelist
> of permited characters from user input, taking care to use sane IFS.
> Only alphanum character with _ @ - are believed to be safe

Do you have some supporting evidence for that last line. That's an
extremely conservative set. It excludes URLs, for instance.

Thanks,

Michael

> If you need to escape better to use execvp.
>
> Please add also a warning about IFS
>
>
>>
>> Cheers,
>>
>> Michael
>>
>> --
>> Michael Kerrisk
>> Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
>> Linux/UNIX System Programming Training: http://man7.org/training/



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#882222: Document security problems with system.3 and popen.3 (argument injection)

[Michael Kerrisk (man-pages)]

> Could you also warn about popen ?

I already added a cross reference from popen(3) to the Caveats section
in system(3). I should have mentioned that before.

> And mention that system(sprintf("command %s")) is a security hole

That seems obviously dangerous. But don't you think it is covered by this text:

   Any user input that is employed as part of command should be care‐
   fully sanitized, to ensure that unexpected shell commands or  com‐
   mand  options  are  not executed.  Such risks are especially grave
   when using system() from a privileged program.
?

> BTW escaping char is hard with shell, better to use execvp

Agreed. I would not attempt escaping. Safer to allow only a whitelist
of permited characters from user input.

Cheers,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#882222: Document security problems with system.3 and popen.3 (argument injection)

[Michael Kerrisk (man-pages)]

Hello Tobias, and Bastien,

On 22 November 2017 at 09:52, Dr. Tobias Quathamer <to...@debian.org> wrote:
> control: severity -1 important
>
> Am 20.11.2017 um 12:29 schrieb Bastien ROUCARIES:
>> Please document the implication of system.3 and popen.3, particularly
>> argument injection.
> Hi,
>
> thanks for the bug report, I'll take this upstream

I already noticed this Debian bug report, and made a few upstream
changes. See the Caveats subsection towards the end of the current
draft in upstream Git:
https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/man3/system.3
The main changes were to mention the PATH variable more explicitly and
to note that one should carefully sanitize the input of system().

> and we'll see how to
> get this better documented. Do you have a patch ready?
>
> Apart from that, I've lowered the severity of this bug. I do not agree
> with you that this missing documentation is release critical.

I agree. When I look through the source code of Fedora, I see dozens,
if not hundreds of programs using system(). And I imagine that most of
them are doing it quite safely. I find the advice given regarding
system() in the site that you mentioned [1] Bastien is somewhat
overwrought. (And some of the advice there is I find bizarre[2], which
makes me a little skeptical about the site generally.) Certainly, one
should be careful though. (BUt the same is true of any APIs that may
handle user-supplied input.)

Cheers,

Michael

[1] https://wiki.sei.cmu.edu/confluence/pages/viewpage.action?pageId=87152177
[2] For example,
https://wiki.sei.cmu.edu/confluence/display/c/SIG34-C.+Do+not+call+signal%28%29+from+within+interruptible+signal+handlers
seems simply confused.
-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#764449: core.5: please mention security implications of /proc/sys/kernel/core_pattern

[Michael Kerrisk (man-pages)]

After, looking at this for quite a while, I am not convinced there's
an issue here. %e is returned as just the basename of the executable
path, and %t and %E seem even less problematic.

If you think there's an issue, it would be good to show a worked
example of how an "innocent" core_pattern pipe command could lead to
execution of unexpected code.

Bug#860559: timex.offset unit ambiguity

[Michael Kerrisk (man-pages)]

On 04/18/2017 06:31 PM, Zefram wrote:
> Package: manpages-dev
> Version: 3.74-1
> Severity: minor
> 
> adjtimex(2) says:
> 
> #  struct timex {
> #  int modes;   /* mode selector */
> #  long offset; /* time offset (usec) */
> 
> In fact the "offset" field is not necessarily in microseconds.  It is
> in either microseconds or nanoseconds, depending on the STA_NANO status
> flag, just like timex.time.tv_usec.

You are looking at a rather old version of man-pages. This was
fixed in upstream quite a long time back (2014). Take a look at
http://man7.org/linux-man-pages/man2/adjtimex.2.html ; does that
version match what you expect?

Cheers,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#859514: file conflict with keyutils

[Michael Kerrisk (man-pages)]

These manual pages recently (about 3 meeks ago) migrated from the
upstream keyutils project to the upstream man-pages project. See
http://linux-man-pages.blogspot.de/2017/03/man-pages-410-is-released.html
. They have been removed in the upstream keyutils project in its
latest release 9which happened a week or two back). So, the conflist
should disappear for Debian as soon as the latest upstream keyutils
release is packaged.

Bug#859511: libbsd-dev: trying to overwrite '/usr/share/man/man3/explicit_bzero.3.gz', which is also in package manpages-dev 4.10-1

[Michael Kerrisk (man-pages)]

On 5 April 2017 at 11:59, Vincent Lefevre <vinc...@vinc17.net> wrote:
> On 2017-04-04 18:41:10 +0200, Sven Joachim wrote:
>> On 2017-04-04 16:29 +0100, Chris Lamb wrote:
>> > Unpacking libbsd-dev:amd64 (0.8.3-1) ...
>> > dpkg: error processing archive 
>> > /tmp/apt-dpkg-install-tduipc/101-libbsd-dev_0.8.3-1_amd64.deb (--unpack):
>> >  trying to overwrite '/usr/share/man/man3/explicit_bzero.3.gz', which is 
>> > also in package manpages-dev 4.10-1
>>
>> It's libbsd-dev which came first to ship that manpage, manpages-dev only
>> added it in the 4.10-1 upload.
>
> I assume that's because it's a new function in glibc 2.25:

Yes. That's correct (i.e., it was added in glibc 2.25, which is why I
added the man page in upstream man-pages).

> http://man7.org/linux/man-pages/man3/bzero.3.html
>
>   explicit_bzero() first appeared in glibc 2.25.
>
> So, IMHO, manpages-dev does the right thing by providing this
> man page.

I think so.

Cheers,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#847998: [Pkg-sysvinit-devel] Bug#847998: manpages: file conflicts with initscripts

[Michael Kerrisk (man-pages)]

Hello Thorsten,

On 12/16/2016 03:36 PM, Thorsten Glaser wrote:
> On Fri, 16 Dec 2016, Michael Kerrisk (man-pages) wrote:
> 
>> On 12/16/2016 02:53 PM, Thorsten Glaser wrote:
>>> On Fri, 16 Dec 2016, Michael Kerrisk (man-pages) wrote:
>>>
>>>> That doesn't document (upstream) reality though. Once upon a time,
>>>> there were one or two Section 9 pages in the man-pages
>>>> project. No one updated them or added new one in > 15 years,
>>>> and I deleted them years ago, as being out-of-date and useless.
>>>
>>> This is not a reason against restarting this section, though.
>>
>> There is no-one who will work on it. 
> 
> Excuse me for reading this as your statement being “I won’t work on it”

(Yep, it's true. Too much else to do, even if it would be interesting.)

> but you cannot say that “no-one” will. 

Yes, it's merely my prediction.

> For example, if the Debian
> maintainer of those manual pages considers this a good idea, they
> are free to work on this. One manpage at a time is good enough.

Sure. I just don't expect someone to step forward for that
task.

>> And, related to the current discussion, the Debian tmpfs-config
>> would not belong in that section.
> 
> Of course not. I stated something quite different:

I misunderstood.

>>> Hmm. So we could conceivably move the manpage about the
>>> tmpfs filesystem to section 9 as a Debian-local patch

But the same statement applies. The tmpfs filesystem page also
does not belong in section 9...

Have a good weekend!

Cheers,

Michael




-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#847998: [Pkg-sysvinit-devel] Bug#847998: manpages: file conflicts with initscripts

[Michael Kerrisk (man-pages)]

On 12/16/2016 02:53 PM, Thorsten Glaser wrote:
> On Fri, 16 Dec 2016, Michael Kerrisk (man-pages) wrote:
> 
>> That doesn't document (upstream) reality though. Once upon a time,
>> there were one or two Section 9 pages in the man-pages
>> project. No one updated them or added new one in > 15 years,
>> and I deleted them years ago, as being out-of-date and useless.
> 
> This is not a reason against restarting this section, though.

There is no-one who will work on it. 

And, related to the current discussion, the Debian tmpfs-config
would not belong in that section.


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#847998: [Pkg-sysvinit-devel] Bug#847998: manpages: file conflicts with initscripts

[Michael Kerrisk (man-pages)]

On 12/16/2016 02:37 PM, Axel Beckert wrote:
> Hi,
> 
> Thorsten Glaser wrote:
>> On Tue, 13 Dec 2016, Michael Kerrisk (man-pages) wrote:
>>> Upstream man-pages maintainer here; I just added tmpfs(5), unaware
>>> that it would create a conflict for Debian; I assume the conflicting
>>> page is Debian-specific(?). (I don't have such a page on my Fedora
>>
>> Yes.
>>
>>>> The manpage about the Linux tmpfs should be tmpfs(9) as it
>>>> covers a kernel concept (here: a filesystem).
>>>
>>> Not sure where this idea originates. There is no Section 9 on Linux.
>>
>> Ah, hmm, too bad then. We have them on BSD.
> 
> At least "man man" (aka man(1)) on Debian says:
> 
>9   Kernel routines [Non standard]

That doesn't document (upstream) reality though. Once upon a time,
there were one or two Section 9 pages in the man-pages
project. No one updated them or added new one in > 15 years,
and I deleted them years ago, as being out-of-date and useless.

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#847998: [Pkg-sysvinit-devel] Bug#847998: manpages: file conflicts with initscripts

[Michael Kerrisk (man-pages)]

On 12/16/2016 02:40 PM, Thorsten Glaser wrote:
> On Fri, 16 Dec 2016, Axel Beckert wrote:
> 
>>>>> The manpage about the Linux tmpfs should be tmpfs(9) as it
>>>>> covers a kernel concept (here: a filesystem).
>>>>
>>>> Not sure where this idea originates. There is no Section 9 on Linux.
>>>
>>> Ah, hmm, too bad then. We have them on BSD.
>>
>> At least "man man" (aka man(1)) on Debian says:
>>
>>9   Kernel routines [Non standard]
>>
>> The according file comes from the package man-db.
> 
> Hmm. So we could conceivably move the manpage about the
> tmpfs filesystem to section 9 as a Debian-local patch
> (since upstream appears to prefer to not have such a
> section), and then all will be good™.

Is there already something in Section 9 on Debian?


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#848231: bugs in scandir example program

[Michael Kerrisk (man-pages)]

On 15 December 2016 at 14:56, Ian Jackson
<ijack...@chiark.greenend.org.uk> wrote:
> Michael Kerrisk (man-pages) writes ("Re: Bug#848231: bugs in scandir example 
> program"):
>> tags 848231 fixed-upstream
>> thanks
> ...>
>> On 15 December 2016 at 13:55, Ian Jackson
>> > int
>> > main(void)
>> > @@ -18,4 +20,5 @@
>> > }
>> > free(namelist);
>> > }
>> > +   return 0;
>> > }
>> >
>>
>> Thanks, Ian. Fixed pretty much as you suggest. The program doesn't
>> even compile as it was given! Looks like I injected the error after a
>> user report 4 years ago (changed "0" to "NULL").
>
> Thanks.  But, 0 should be 0, not NULL.
>
> NULL is a null pointer constant but main returns int.
>
> (Even if main returned a pointer, 0 would be legal, because 0 is a
> valid nll pointer constant, but I guess for pedagogic reasons using
> NULL is probaby better in manpages where pointers are meant.)

We've misunderstood each other. Here's how I think i is:

1. You sent me a patch against a reasonably old version of the program
(pre 2012 upstream).

2. In 2012, I made this change in the code:

-   n = scandir(".", , 0, alphasort);
+   n = scandir(".", , NULL, alphasort);

3. In that preceding change, I did not add a #include for ,
so the code would not even compile.

All fixed now. This is the current code:

   #define _DEFAULT_SOURCE
   #include 
   #include 
   #include 

   int
   main(void)
   {
   struct dirent **namelist;
   int n;

   n = scandir(".", , NULL, alphasort);
   if (n == -1) {
   perror("scandir");
   exit(EXIT_FAILURE);
       }

   while (n--) {
   printf("%s\n", namelist[n]->d_name);
   free(namelist[n]);
   }
       free(namelist);

   exit(EXIT_SUCCESS);
   }

Cheers,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#848231: bugs in scandir example program

[Michael Kerrisk (man-pages)]

tags 848231 fixed-upstream
thanks

On 15 December 2016 at 13:55, Ian Jackson
<ijack...@chiark.greenend.org.uk> wrote:
> Package: manpages-dev
> Version: 3.74-1
> Severity: minor
>
> I cut and pasted the example program from scandir(3) and found that it
> had some bugs which caused compiler warnings with -Wall.  Here is a
> patch (to the example program, not to the nroff) to fix them.
>
> Thanks,
> Ian.
>
> --- t.c.orig2016-12-15 12:52:33.181859142 +
> +++ t.c 2016-12-15 12:55:08.939521298 +
> @@ -1,6 +1,8 @@
> #define _SVID_SOURCE
> /* print files in current directory in reverse order */
> #include 
> +   #include 
> +   #include 
>
> int
> main(void)
> @@ -18,4 +20,5 @@
> }
> free(namelist);
> }
> +   return 0;
> }
>

Thanks, Ian. Fixed pretty much as you suggest. The program doesn't
even compile as it was given! Looks like I injected the error after a
user report 4 years ago (changed "0" to "NULL").

Cheers,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#848121: [Pkg-sysvinit-devel] File conflict between manpages and initscripts

[Michael Kerrisk (man-pages)]

On 14 December 2016 at 16:45, Ian Jackson
 wrote:
> Axel Beckert writes ("Bug#848121: [Pkg-sysvinit-devel] File conflict between 
> manpages and initscripts"):
>> I must admit that I never was aware that filesystems are in the same
>> manual section as file formats (5). I would have expected them in
>> section 7 or so, but there's probably a not that small intersection
>> between things that fit into section 5 and things that fit in section
>> 7.
>
> I agree.

So, as I've commented elsewhere, various people have some to the same
idea: filesystem pages go into section 5. (I do see the argument for
7, but it's not what various projects have done.)

Also, Linux is not the only one to do this. On FreeBSD we have the
following in Section 5:

$ ls -1 *fs.5
autofs.5
devfs.5
ext2fs.5
fdescfs.5
fs.5
linprocfs.5
linsysfs.5
mqueuefs.5
msdosfs.5
nandfs.5
nullfs.5
procfs.5
tmpfs.5

Note the last!

>> But then again initscripts' tmpfs.5 is IMHO clearly section 5 (file
>> format) and not section 7. While I would put information about the
>> tmpfs file system into section 7 with good conscience, it clearly
>> doesn't make sense since all other file system man pages are in
>> section 5.

(Yes.)

>>
>> Difficult …
>
> I think the only sensible options are:
>
>  - rename all the filesystem manpages to put them in section 7

I doubt that will happen. They come from multiple upstream projects.
And there's no compelling reason for those upstreams to change.

>  - rename the manpage about /etc/default/tmpfs to tmnfs-config(5)
>(or something, better name welcome).

FWIW, I think this may be the best option.

Cheers,

Michael

Bug#848121: [Pkg-sysvinit-devel] Bug#848121: File conflict between manpages and initscripts

[Michael Kerrisk (man-pages)]

Hi,

On 14 December 2016 at 14:52, Axel Beckert <a...@debian.org> wrote:
> Hi,
>
> Dr. Tobias Quathamer wrote:
>> I think there are a few options:
>>
>> 1. Rename the manpage in one of the packages
>> 3. Move one of the manpages to another section
>
> Any suggestions for how to rename them? Do we already have a manpage
> section like e.g. "5sysv"?
>
>> 2. Remove the manpage from one of the packages
>
> This might make sense if one version includes nearly everything from
> the other version (plus additional parts).
>
> I don't know the difference, but I could imagine that the manpages'
> tmpfs.5 has some more systemd-specific information. So if the
> sysvinit-specific parts in tmpfs.5 are not gone (or soon to be
> removed), then we could switch to the version from manpages.

The pages cover different topics

The Debian page describes a Debian config file, /etc/default/tmpfs,
used for configuring various tmpfs filesystems.

The upstream man-pages page describes the basics of the tmpfs
filesystem. (Systemd does not figure in there.) This follows a pattern
for other filesystems where we have pages such as xfs(5), btrfs(5),
nfs(5), ext4(5), ...

Cheers,

Michael

>> 4. Use the Debian alternatives system
>>(don't know if this would work well)
>
> I think that's overkill for this case, but definitely an option.
>
>> 5. Add Breaks/Conflicts to the packages
>>(does not seem to be a desirable solution)
>
> Yes, I agree that this is not desirable.
>
> I think there is at least one more option:
>
> 6. Let one package divert away the other package's version (like
>iceweasel did with firefox for quite a while).
>
>If e.g. initscripts is no more needed in a (future?) default
>installation and manpages' tmpfs.5 covers more systemd-specific
>stuff while (at some point) sysvinit-specific stuff can only be
>found in sysvinit's tmpfs.5, initscripts could divert manpages'
>tmpfs.5 away, so that sysvinit users get the information relevant
>for them and all others get the default, which probably covers also
>systemd-specific stuff.
>
> Regards, Axel
> --
>  ,''`.  |  Axel Beckert <a...@debian.org>, http://people.debian.org/~abe/
> : :' :  |  Debian Developer, ftp.ch.debian.org Admin
> `. `'   |  4096R: 2517 B724 C5F6 CA99 5329  6E61 2FF9 CD59 6126 16B5
>   `-|  1024D: F067 EA27 26B9 C3FC 1486  202E C09E 1D89 9593 0EDE
>



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#847998: manpages: file conflicts with initscripts

[Michael Kerrisk (man-pages)]

On 13 December 2016 at 10:56, Thorsten Glaser <t.gla...@tarent.de> wrote:
> On Tue, 13 Dec 2016, Michael Kerrisk (man-pages) wrote:
>
>> I can't move "them" as they come from diverse projects (nfs-utils,
>
> OK.
>
>> e2fsprogs, btrfs-progs). Obviously, various projects came to the same
>> conclusion (or copied each other's idea) that Section 5 was the right
>> place. And in the Linux man-pages we also have filesystems(5) and
>> proc(5), for example.
>
> So, we could temporarily not ship the Debian-specific manpage, while
> suggesting to the various projects mentioned that section 5 may not
> have been the best place for it. (Again, just collecting suggestions,
> not deciding things for anyone ;-)
>
> If there is no hard policy against section 9 I’d like to have
> kernel-specific stuff there,

This would be Debian-specific then?

> otherwise I think section 7 is at
> least more appropriate than section 5 – or section 4, possibly,
> but that’s “device drivers” on BSD so it doesn’t feel fully
> right either, but at least it’s kernel land, whereas 7 is more
> general.

See my other reply. (FreeBSD) follows the same convention here as Linux...

Cheers,

Michael




-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#847998: manpages: file conflicts with initscripts

[Michael Kerrisk (man-pages)]

>>> And there's certainly precedent for section 5 pages on filesystems.
>>> For example, among others, we have ext4(5), btrfs(5), and nfs(5).
>>
>> But section 5 is for configuration files. You could move them
>> to section 7 (general concepts), though.
>
> I can't move "them" as they come from diverse projects (nfs-utils,
> e2fsprogs, btrfs-progs). Obviously, various projects came to the same
> conclusion (or copied each other's idea) that Section 5 was the right
> place. And in the Linux man-pages we also have filesystems(5) and
> proc(5), for example.

Actually, other operating systems also seemed to come to the same
conclusion. For FreeBSD, I see the following in Section 5:

$ ls -1 *fs.5
autofs.5
devfs.5
ext2fs.5
fdescfs.5
fs.5
linprocfs.5
linsysfs.5
mqueuefs.5
msdosfs.5
nandfs.5
nullfs.5
procfs.5
tmpfs.5

Note the last!

Cheers,

Michael



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#847998: manpages: file conflicts with initscripts

[Michael Kerrisk (man-pages)]

Hello Thorsten,

On 13 December 2016 at 10:43, Thorsten Glaser <t.gla...@tarent.de> wrote:
> On Tue, 13 Dec 2016, Michael Kerrisk (man-pages) wrote:
>
>> Upstream man-pages maintainer here; I just added tmpfs(5), unaware
>> that it would create a conflict for Debian; I assume the conflicting
>> page is Debian-specific(?). (I don't have such a page on my Fedora
>
> Yes.

Thanks for the confirmation.

>> > The manpage about the Linux tmpfs should be tmpfs(9) as it
>> > covers a kernel concept (here: a filesystem).
>>
>> Not sure where this idea originates. There is no Section 9 on Linux.
>
> Ah, hmm, too bad then. We have them on BSD.

(Yes.)

>
>> And there's certainly precedent for section 5 pages on filesystems.
>> For example, among others, we have ext4(5), btrfs(5), and nfs(5).
>
> But section 5 is for configuration files. You could move them
> to section 7 (general concepts), though.

I can't move "them" as they come from diverse projects (nfs-utils,
e2fsprogs, btrfs-progs). Obviously, various projects came to the same
conclusion (or copied each other's idea) that Section 5 was the right
place. And in the Linux man-pages we also have filesystems(5) and
proc(5), for example.

Cheers,

Michael

Bug#847998: manpages: file conflicts with initscripts

[Michael Kerrisk (man-pages)]

Upstream man-pages maintainer here; I just added tmpfs(5), unaware
that it would create a conflict for Debian; I assume the conflicting
page is Debian-specific(?). (I don't have such a page on my Fedora
system.)

On 13 December 2016 at 10:00, Thorsten Glaser <t.gla...@tarent.de> wrote:
> On Tue, 13 Dec 2016, Michael Biebl wrote:
>
>> The tmpfs man page shipped by the manpages package talks about the tmpfs
>> file system.
>> The man page shipped by initscripts talks about the debian/initscripts
>> specific config file /etc/default/tmpfs.
>>
>> My gut feeling is, that debian specific tmpfs man page should be renamed.
>
> From the usual unix policy stuff:
>
> The manpage about /etc/default/tmpfs can be tmpfs(5) as it
> covers a configuration file.
>
> The manpage about the Linux tmpfs should be tmpfs(9) as it
> covers a kernel concept (here: a filesystem).

Not sure where this idea originates. There is no Section 9 on Linux.
And there's certainly precedent for section 5 pages on filesystems.
For example, among others, we have ext4(5), btrfs(5), and nfs(5).

I'm not sure what the best path forward here is.

Cheers,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#574041: [daniel.bal...@gmail.com: man 2 write - clarification]

[Michael Kerrisk (man-pages)]

tags 574041 fixed-upstream
thanks

So, I tried to slightly improve the text here, but in a different way.

See the upstream patch below.

Thanks,

Michael

--- a/man2/write.2
+++ b/man2/write.2
@@ -82,9 +82,9 @@ are performed as an atomic step.

 POSIX requires that a
 .BR read (2)
-which can be proved to occur after a
+that can be proved to occur after a
 .BR write ()
-has returned returns the new data.
+has returned will return the new data.
 Note that not all filesystems are POSIX conforming.
 .SH RETURN VALUE
 On success, the number of bytes written is returned (zero indicates


On 26 March 2014 at 08:34, Michael Kerrisk (man-pages)
<mtk.manpa...@gmail.com> wrote:
> On Sun, Mar 14, 2010 at 9:24 PM, Joey Schulze <j...@infodrom.org> wrote:
>> Package: manpages-dev
>> Version: 3.24-1
>>
>> Forwarded mail from Daniel.
>>
>> - Forwarded message from Daniel Baluta <daniel.bal...@gmail.com> -
>>
>> Date: Wed, 10 Mar 2010 12:48:24 +0200
>> Subject: man 2 write - clarification
>> From: Daniel Baluta <daniel.bal...@gmail.com>
>> To: ubuntu-devel-disc...@lists.ubuntu.com, j...@debian.org
>>
>> Hello,
>>
>> The following phrase taken from man 2 write manual page is confusing:
>> POSIX  requires that a read(2) which can be proved to occur after a
>> write() has returned returns the new data.
>>
>> I think you should you some comas to make a clear statement.
>> POSIX  requires that a read(2), which can be proved to occur after a
>> write() has returned, returns the new data.
>
> Adding those comma would change the meaning of the sentence, rendering
> it incorrect.



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#845172: manpages-dev: no function protypes in example from mbstowcs(3)

[Michael Kerrisk (man-pages)]

Upstream maintainer here.

I added the missing include.

But I am unsure what to do about the other point (regarding gcc
-Wconversion). There is an analogous situation with islower() and
similar functions, where the solution is described by an update I
recently added for the upcoming upstream release

   The standards require that the argument c for these  functions  is
   either  EOF  or a value that is representable in the type unsigned
   char.  If the argument c is of type  char,  it  must  be  cast  to
   unsigned char, as in the following example:

   char c;
   ...
   res = toupper((unsigned char) c);

   This  is necessary because char may be the equivalent signed char,
   in which case a byte where the  top  bit  is  set  would  be  sign
   extended  when converting to int, yielding a value that is outside
   the range of unsigned char.

However, we don't have a similar solution for iswlower(), because
there is no "(unsigned wchar_t)" cast. And casting to (wint_t) seems
incorrect to me, because if wchar_t is a signed type smaller than
wint_t, then sign extension could occur.

I could be wrong, but it seems like an implementation bug that one of
these types is signed and the other is unsigned.

Cheers,

Michael

Bug#839705: manpages-dev: "initial state" in mbstowcs(3) and wcstombs(3)

[Michael Kerrisk (man-pages)]

On 10/06/2016 10:13 AM, Igor Liferenko wrote:
> Dear Maintainer,
> 
> According to definitions of mbstowcs and wcstombs (see below), the phrase
> ``The conversion starts in the initial state.''

See my earlier reply.

> may be left in mbstowcs(3) and wcstombs(3), but the phrase
> ``In this case, the conversion ends in the initial state.''
> should be removed from wcstombs(3) (because there is no such sentence
> in corresponding section of mbstowcs(3) and because this sentence
> makes no sense):
> 
> http://code.metager.de/source/xref/gnu/glibc/stdlib/mbstowcs.c
> 
> http://code.metager.de/source/xref/gnu/glibc/stdlib/wcstombs.c

I'm not sure that the sentence makes no sense. I did change "initial state"
to "initial shift state". Still not sure if that's correct though.

> BTW, in mbstowcs(3) the phrase
> 
> including the terminating null wide character ('\0')
> 
> should be changed to
> 
> including the terminating null byte ('\0')

I fixed this. Thanks.

Cheers,

Michael



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#839705: manpages-dev: "initial state" in mbstowcs(3) and wcstombs(3)

[Michael Kerrisk (man-pages)]

tags 839705 fixed-upstream
thanks

On 10/04/2016 09:30 AM, Igor Liferenko wrote:
> Package: manpages-dev
> Version: 4.07-1
> Severity: normal
> 
> Dear Maintainer,
> 
> In mbstowcs(3) there is this sentence:
> 
> The conversion starts in the initial state.
> 
> And in wcstombs(3) there are these sentences:
> 
> The conversion starts in the initial state.
> 
> In this case, the conversion ends in the initial state.
> 
> "Initial state" is associated only with mbstate_t, but mbstowcs and wcstombs
>  are stateless (in contrast with mbsrtowcs and wcsrtombs).

Looking at your later reply, you seem to understand that "Initial state" here
is sort of okay. But really, the language could be clearer. I applied the 
patch below. (Still not sure if it's 100% correct, but I believe it's an
improvement.)

Cheers,

Michael

diff --git a/man3/mbstowcs.3 b/man3/mbstowcs.3
index e02f7df..bdd624a 100644
--- a/man3/mbstowcs.3
+++ b/man3/mbstowcs.3
@@ -39,8 +39,9 @@ At most
 .I n
 wide characters are written to
 .IR dest .
-The conversion starts
-in the initial state.
+The sequence of characters in the string
+.I src
+shall begin in the initial shift state.
 The conversion can stop for three reasons:
 .IP 1. 3
 An invalid multibyte sequence has been encountered.
diff --git a/man3/wcstombs.3 b/man3/wcstombs.3
index e5498b3..073cc9b 100644
--- a/man3/wcstombs.3
+++ b/man3/wcstombs.3
@@ -36,8 +36,9 @@ At most
 .I n
 bytes are written to
 .IR dest .
-The conversion
-starts in the initial state.
+The sequence of characters placed in
+.IR dest
+begins in the initial shift state.
 The conversion can stop for three reasons:
 .IP 1. 3
 A wide character has been encountered that can not be represented as a
@@ -53,7 +54,7 @@ is returned, but the shift state at this point is lost.
 .IP 3.
 The wide-character string has been completely converted, including the
 terminating null wide character (L\(aq\\0\(aq).
-In this case, the conversion ends in the initial state.
+In this case, the conversion ends in the initial shift state.
 The number of bytes written to
 .IR dest ,
 excluding the terminating null byte (\(aq\\0\(aq), is returned.

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#840499: manpages-dev: Inconsistent symbolic error name for EILSEQ in errno(3)

[Michael Kerrisk (man-pages)]

tags 840499 fixed-upstream
thanks

On 10/12/2016 11:04 AM, Igor Liferenko wrote:
> Package: manpages-dev
> Version: 4.07-1
> Severity: normal
> 
> Dear Maintainer,
> 
> According to bug glibc bug 20687 [1], the text
> 
> Illegal byte sequence (POSIX.1, C99)
> 
> should be changed to
> 
> Invalid or incomplete multibyte or wide character
> 
> [1]: https://sourceware.org/bugzilla/show_bug.cgi?id=20687

I amended the EILSEQ description to note both the glibc text 
and the POSIX text. Thanks for the report.

Cheers,

Michael

> 
> -- System Information:
> Debian Release: stretch/sid
>   APT prefers testing
>   APT policy: (500, 'testing')
> Architecture: amd64 (x86_64)
> 
> Kernel: Linux 4.7.0-1-amd64 (SMP w/4 CPU cores)
> Locale: LANG=en_US.UTF-8, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8)
> Shell: /bin/sh linked to /bin/dash
> Init: systemd (via /run/systemd/system)
> 
> Versions of packages manpages-dev depends on:
> ii  manpages  4.07-1
> 
> manpages-dev recommends no packages.
> 
> Versions of packages manpages-dev suggests:
> ii  man-db [man-browser]  2.7.5-1
> 
> -- no debconf information
> 
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#840499: manpages-dev: Inconsistent symbolic error name for EILSEQ in errno(3)

[Michael Kerrisk (man-pages)]

tags 840499 fixed-upstream
thanks

On 10/12/2016 11:04 AM, Igor Liferenko wrote:
> Package: manpages-dev
> Version: 4.07-1
> Severity: normal
> 
> Dear Maintainer,
> 
> According to bug glibc bug 20687 [1], the text
> 
> Illegal byte sequence (POSIX.1, C99)
> 
> should be changed to
> 
> Invalid or incomplete multibyte or wide character
> 
> [1]: https://sourceware.org/bugzilla/show_bug.cgi?id=20687

I amended the EILSEQ description to note both the glibc text 
and the POSIX text. Thanks for the report.

Cheers,

Michael

> 
> -- System Information:
> Debian Release: stretch/sid
>   APT prefers testing
>   APT policy: (500, 'testing')
> Architecture: amd64 (x86_64)
> 
> Kernel: Linux 4.7.0-1-amd64 (SMP w/4 CPU cores)
> Locale: LANG=en_US.UTF-8, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8)
> Shell: /bin/sh linked to /bin/dash
> Init: systemd (via /run/systemd/system)
> 
> Versions of packages manpages-dev depends on:
> ii  manpages  4.07-1
> 
> manpages-dev recommends no packages.
> 
> Versions of packages manpages-dev suggests:
> ii  man-db [man-browser]  2.7.5-1
> 
> -- no debconf information
> 
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#838956: manpages-dev: Inconsistent documentation in NOTES section of "man wcstombs"

[Michael Kerrisk (man-pages)]

tags 838956 fixed-upstream
thanks

Thanks for this report. I've applied the patch below to the upstream man page.

Cheers,

Michael


diff --git a/man3/wcstombs.3 b/man3/wcstombs.3
index c787250..1f189be 100644
--- a/man3/wcstombs.3
+++ b/man3/wcstombs.3
@@ -112,8 +112,7 @@ current locale.
 .PP
 The function
 .BR wcsrtombs (3)
-provides a thread safe interface to
-the same functionality.
+provides a better interface to the same functionality.
 .SH SEE ALSO
 .BR mblen (3),
 .BR mbstowcs (3),


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#838958: Fwd: Bug#838958: linux: mount(2) _silently_ ignores other mountflags when MS_BIND is set

[Michael Kerrisk (man-pages)]

tags 838958 fixed-upstream
thanks

On 09/27/2016 11:27 AM, Debian Bug Tracking System wrote:
> Processing control commands:
>
>> reassign -1 manpages-dev
> Bug #838958 [src:linux] linux: mount(2) _silently_ ignores other mountflags 
> when MS_BIND is set
> Bug reassigned from package 'src:linux' to 'manpages-dev'.
> Ignoring request to alter found versions of bug #838958 to the same values 
> previously set
> Ignoring request to alter fixed versions of bug #838958 to the same values 
> previously set

By chance, in the most recent upstream release (4.07) I made substantial
changes to the mount(2) page:

http://man7.org/linux/man-pages/man2/mount.2.html

In particular, I think the following new text addresses the doc problem
relevant to this bug:

   Creating a bind mount
   If mountflags includes MS_BIND (available since Linux 2.4), then
   perform a bind mount.  A bind mount makes a file or a directory
   subtree visible at another point within the single directory
   hierarchy.  Bind mounts may cross filesystem boundaries and span
   chroot(2) jails.

   The filesystemtype and data arguments are ignored.

   The remaining bits in the mountflags argument are also ignored, with
   the exception of MS_REC.  (The bind mount has the same mount options
   as the underlying mount point.)  However, see the discussion of
   remounting above, for a method of making an existing bind mount read-
   only.

And the referred-to text describing MS_REMOUNT nowadays says:

   Since Linux 2.6.26, this flag can also be used to make an existing
   bind mount read-only by specifying mountflags as:

   MS_REMOUNT | MS_BIND | MS_RDONLY

   Note that only the MS_RDONLY setting of the bind mount can be changed
   in this manner.

Cheers,

Michael


--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#741360: statm "share" badly described

[Michael Kerrisk (man-pages)]

tags 741360 fixed-upstream
thanks

Hello Zefram,

On 11 March 2014 at 16:48, Zefram <zef...@fysh.org> wrote:
> Package: manpages
> Version: 3.44-1
> Severity: minor
>
> proc(5) says:
>
>/proc/[pid]/statm
>   Provides information about memory usage, measured in pages.  The
>   columns are:
>
>   size   total program size
>  (same as VmSize in /proc/[pid]/status)
>   resident   resident set size
>  (same as VmRSS in /proc/[pid]/status)
>   share  shared pages (from shared mappings)
>
> Actually the "share" value doesn't count all shared pages mapped by the
> process: it only counts *resident* shared pages.  It should be documented
> as such.  The current documentation makes it look as though one can
> subtract share from size to find out how much unshared memory the process
> uses, but actually doing so gives a bogus figure.  I'm currently debugging
> some code (the Perl module Apache::SizeLimit) that makes that mistake.

Thanks for the report. I've applied the patch below for upstream man-pages.

Cheers,

Michael

--- a/man5/proc.5
+++ b/man5/proc.5
@@ -2003,7 +2003,8 @@ size   (1) total program size
(same as VmSize in \fI/proc/[pid]/status\fP)
 resident   (2) resident set size
(same as VmRSS in \fI/proc/[pid]/status\fP)
-shared (3) shared pages (i.e., backed by a file)
+shared (3) number of resident shared pages (i.e., backed by a file)
+   (same as RssFile+RssShmem in \fI/proc/[pid]/status\fP)
 text   (4) text (code)
 .\" (not including libs; broken, includes data segment)
 lib(5) library (unused in Linux 2.6)


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#825548: quotactl(2) man page is incorrect

[Michael Kerrisk (man-pages)]

tags 825548 fixed-upstream
thanks

Hello Jacob

Upstream maintainer here. Thanks for the excellently documented report.

This error appears to have been injected into glibc when copying
some headers from BSD.

I've applied the patch below.

Cheers,

Michael

diff --git a/man2/quotactl.2 b/man2/quotactl.2
index 2cab4c0..8526a14 100644
--- a/man2/quotactl.2
+++ b/man2/quotactl.2
@@ -150,8 +150,8 @@ struct dqblk {  /* Definition since Linux 2.4.22 */
   quota blocks alloc */
 uint64_t dqb_bsoftlimit;   /* preferred limit on
   disk quota blocks */
-uint64_t dqb_curspace; /* current quota block
-  count */
+uint64_t dqb_curspace; /* current occupied space
+  (in bytes) */
 uint64_t dqb_ihardlimit;   /* maximum number of
   allocated inodes */
 uint64_t dqb_isoftlimit;   /* preferred inode limit */

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#825022: man pages for *xattr syscalls are missing from manpages-dev

[Michael Kerrisk (man-pages)]

Note that around May 2015, by mutual agreement between the man-pages
and libattr projects (which hitherto had both carried versions of the
*xattr(2) pages), man-pages became the canonical home for these pages,
and the versions in the libattr project were dropped. Maybe Debian has
not caught up with this?

Thanks,

Michael

Bug#717629: please document LANG and LC_ALL in locale(1)

[Michael Kerrisk (man-pages)]

tags 717629 fixed-upstream
thanks

Hello Vincent,

On 03/14/2016 07:24 AM, Vincent Lefevre wrote:
> On 2016-03-14 06:56:56 +1300, Michael Kerrisk (man-pages) wrote:
>> The goal of the upstream locale(1) page is to document the syntax of
>> the command.
> 
> It did more than that when the bug was reported. Here's the
> ENVIRONMENT VARIABLES section from the locale(1) man page
> of Debian 6 and 7:

I appreciate that the old Debian locale page was different. At the time
the time this Debian bug was raised, the upstream man-pages locale(1)
page didn't exist!

But, I think the upstream pages now provide all the info you hope to
see, albeit not in the place where bug reported first expected it.

Cheers,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#717629: please document LANG and LC_ALL in locale(1)

[Michael Kerrisk (man-pages)]

On 14 March 2016 at 03:31, Aurelien Jarno <aurel...@aurel32.net> wrote:
> control: reassign -1 manpages
>
> On 2013-07-23 09:16, Harald Dunkel wrote:
>> Package: locales
>> Version: 2.13-38
>>
>> Seems that LANG and LC_ALL have been lost in locale(1). It would
>> be nice if they could be added.
>>
>> http://pubs.opengroup.org/onlinepubs/007908799/xbd/envvar.html
>>
>
> Nowaways the locale(1) manpage is provided by the manpages package. I am
> therefore reassigning the bug there.

The goal of the upstream locale(1) page is to document the syntax of
the command.

At the start of the locale(1) page, there is this paragraph:

   When invoked without arguments,  locale  displays  the  current
   locale settings for each locale category (see locale(5)), based
   on the settings of the environment variables that  control  the
   locale (see locale(7)).

And all of the relevant locale environment variables, including LC_ALL
and LANG, are documented in locale(7).

Cheers,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#743525: symlink permissions misdescribed

[Michael Kerrisk (man-pages)]

tags 715261 fixed-upstream
thanks

Yes, there are odd exceptions. Under /proc/PID, there are some "magic"
symlinks that have other permissions. I"ve added some text to the man
page to note this. Thanks for the report.

   On Linux, the permissions of a symbolic link are  not  used  in
   any  operations;  the permissions are always 0777 (read, write,
   and execute for all user categories),  and  can't  be  changed.
   (Note  that  there are some "magic" symbolic links in the /proc
   directory tree—for example, the /proc/PID/fd/* files—that  have
   different permissions.)

Cheers,

Michael

Bug#715261: manpages-dev: readdir_r should be strongly discouraged due to security reasons

[Michael Kerrisk (man-pages)]

tags 715261 fixed-upstream
thanks

glibc 2.24 marks readdir_r() deprecated, and for the upcoming
man-pages-4.05 release, I've significantly reworked the man page to
note the problems and indicate that the function is deprecated.

Thanks,

Michael

Bug#679323: clearenv(3): implies that it's a security tool

[Michael Kerrisk (man-pages)]

On 18 February 2016 at 21:34, Matt Zimmerman  wrote:
> Thanks for following up.  My recommendation is to say something like:
>
> This function DOES NOT securely erase the contents of the environment.
> Security-conscious applications which need to do this should use 
> instead.

So, I think this report is a little confused, but mainly because of
the poor description in the man page.

The security-conscious applications in this context are those that
want to precisely control the environment passed to an exec()ed
program. clearenv() cannot, indeed must not, try to erase the buffers
containing the environment definitions. (See putenv(3) to understand
why.) I've adjusted the man page in away that I hope explains things
better:

   The  clearenv()  function  may  be  useful  in security-conscious
   applications that want to precisely control the environment  that
   is  passed  to  programs executed using exec(3).  The application
   would do this by first clearing the environment and  then  adding
   select environment variables.

   Note that the main effect of clearenv() is to adjust the value of
   the pointer environ(7); this function does not erase the contents
   of the buffers containing the environment definitions.

Cheers,

Michael

Bug#756599: printf(3) manpage: stray asterisk in "NAN*"

[Michael Kerrisk (man-pages)]

tags 756599 fixed-upsteam
thanks

On 17 February 2016 at 01:21, Stéphane Aulery <lk...@free.fr> wrote:
> Hello Michael,
>
> About Debian Bug #756599 [1], I found this explanation [2][3] confirming
> that * is not a selector :

I've removed the stray "*" (commit 4a66305922b197)

Thanks for the report, Jakub. And thanks for reminding me of this bug, Stéphane.

Cheers,

Michael



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#799674: Properly document l/ll length modifier for double/long double argument

[Michael Kerrisk (man-pages)]

On 12/28/2015 08:39 AM, Mathieu Malaterre wrote:
> On Sat, Dec 26, 2015 at 4:54 PM, Michael Kerrisk (man-pages)
> <mtk.manpa...@gmail.com> wrote:
>> (Upstream mainatiner here.)
>>
>> On 09/21/2015 03:08 PM, Mathieu Malaterre wrote:
>>> Package: manpages-dev
>>> Version: 3.65-1
>>> Severity: wishlist
>>>
>>> Currenly the man page for *printf family is difficult to read with
>>> regards to float, double and long double printing. The man page for
>>> *scanf family is much clearer. AFAIK there is a confusion with an old
>>> C89 behavior, since C99 the actual way to print a double is "lf" and
>>> "llf" for long double.
>>>
>>> Right now it reads as:
>>>
>>>   l  (ell) A following integer conversion corresponds to a
>>> long int or unsigned long int argument, or a following n conversion
>>> corresponds to a pointer to a long int argument,  or  a  following  c
>>>   conversion corresponds to a wint_t argument, or a
>>> following s conversion corresponds to a pointer to wchar_t argument.
>>>
>>> Accordingly 'll' and 'L' may need to be updated.
>>
>> So, I looked at this report, and I can't understand what the problem
>> is that is being reported. What precisely do you think needs fixing?
> 
> It should be clear from the documentation that one should use "lf" to
> print/scan to/from a double.
> 
> I'll copy/paste a better written comment from SO
> 
> [...]
> Since С99 the matching between format specifiers and floating-point
> argument types in C is consistent between printf and scanf. It is
> 
> %f for float
> %lf for double
> %Lf for long double
> 
> However, when arguments of type float are passed to variadic functions
> (as variadic parameters) such arguments are implicitly converted to
> type double. This is the reason why in printf format specifiers %f and
> %lf are equivalent and interchangeable. In printf you can "cross-use"
> %lfwith float or %f with double.
> 
> But there's no reason to actually do it in practice. Don't use %f to
> printf arguments of type double. It is a widespread habit born back in
> C89/90 times, but it is a bad habit. Use %lf in printffor double and
> keep %f reserved for float arguments.
> 
> 
> http://stackoverflow.com/a/28222471/136285
> [...]

I'm still puzzled. In the spec for fprintf(), I see:

   l (ell) Specifies that a following d, i, o, u, x, or X conversion
   specifier  applies  to  a long or unsigned long argument;
   that a following n  conversion  specifier  applies  to  a
   pointer to a long argument; that a following c conversion
   specifier applies to a wint_t argument; that a  following
   s  conversion specifier applies to a pointer to a wchar_t
   argument; or has no effect on a following a, A, e, E,  f,
   F, g, or G conversion specifier.

In other words, the standard is explicit that %lf is the same as %f.
What am I missing?

Thanks,

Michael
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#804210: Invalid documentation for return value of sscanf

[Michael Kerrisk (man-pages)]

On 11/06/2015 09:45 AM, Mathieu Malaterre wrote:
> Package: manpages-dev
> Version: 3.74-1
> 
> Currently `man sscanf`` reads as:
> 
> [...]
> RETURN VALUE
>These functions return the number of input items successfully
> matched and assigned, which can be fewer than provided for, or even
> zero in the event of an early matching failure.
> [...]
> 
> This is incorrect in case a read failure occurs before the first
> receiving argument. cppreference reads as (suggested change):
> 
> [...]
> Return value
> 
> Number of receiving arguments successfully assigned, or EOF if read
> failure occurs before the first receiving argument was assigned.
> [...]
> 
> ref: http://en.cppreference.com/w/cpp/io/c/fscanf
> 
> example:
> 
> [...]
> int i;
> int n = sscanf( "ABC", "ABCD%d",  ); // n -> EOF
> [...]

[Upstream maintainer here]

I'm puzzled. Isn't the information you require covered in the
very *next* paragraph of the manual page:

   The value EOF is returned if the end of input is reached before
   either the first successful conversion or  a  matching  failure
   occurs.   EOF is also returned if a read error occurs, in which
   case the error indicator for the stream (see ferror(3)) is set,
   and errno is set to indicate the error.

?

Thanks,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#799674: Properly document l/ll length modifier for double/long double argument

[Michael Kerrisk (man-pages)]

(Upstream mainatiner here.)

On 09/21/2015 03:08 PM, Mathieu Malaterre wrote:
> Package: manpages-dev
> Version: 3.65-1
> Severity: wishlist
> 
> Currenly the man page for *printf family is difficult to read with
> regards to float, double and long double printing. The man page for
> *scanf family is much clearer. AFAIK there is a confusion with an old
> C89 behavior, since C99 the actual way to print a double is "lf" and
> "llf" for long double.
> 
> Right now it reads as:
> 
>   l  (ell) A following integer conversion corresponds to a
> long int or unsigned long int argument, or a following n conversion
> corresponds to a pointer to a long int argument,  or  a  following  c
>   conversion corresponds to a wint_t argument, or a
> following s conversion corresponds to a pointer to wchar_t argument.
> 
> Accordingly 'll' and 'L' may need to be updated.

So, I looked at this report, and I can't understand what the problem
is that is being reported. What precisely do you think needs fixing?

Cheers,

Michael




-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#803459: drand48(3): errors on interval bounds

[Michael Kerrisk (man-pages)]

tags 803459 fixed-upstream
thanks

Hello Vincent
On 10/30/2015 11:17 AM, Vincent Lefevre wrote:
> Package: manpages-dev
> Version: 3.74-1
> Severity: normal
> 
> The drand48(3) man page contains:
> 
>The  drand48()  and  erand48()  functions return nonnegative
>double-precision floating-point values uniformly distributed
>between [0.0, 1.0).
> 
> Instead of "between", it should be "over".
> 
> Then, more importantly, there are errors for lrand48, nrand48,
> lrand48, and jrand48:
> 
>The  lrand48()  and  nrand48()  functions return nonnegative
>long integers uniformly distributed between 0 and 2^31.
> 
>The mrand48() and jrand48()  functions  return  signed  long
>integers uniformly distributed between -2^31 and 2^31.
> 
> According to POSIX, the right bound is 2^31 - 1. Or if you want to
> keep 2^31, you should give a semi-open interval as in POSIX: [0,2^31)
> and [-2^31,2^31) respectively.

Upstream, I have applied the patch below. Thanks for the report.

Cheers,

Michael

diff --git a/man3/drand48.3 b/man3/drand48.3
index 1d4799f..0de9cf2 100644
--- a/man3/drand48.3
+++ b/man3/drand48.3
@@ -81,22 +81,22 @@ The
 and
 .BR erand48 ()
 functions return nonnegative
-double-precision floating-point values uniformly distributed between
-[0.0, 1.0).
+double-precision floating-point values uniformly distributed over the interval
+[0.0,\ 1.0).
 .PP
 The
 .BR lrand48 ()
 and
 .BR nrand48 ()
 functions return nonnegative
-long integers uniformly distributed between 0 and 2^31.
+long integers uniformly distributed over the interval [0,\ 2^31).
 .PP
 The
 .BR mrand48 ()
 and
 .BR jrand48 ()
 functions return signed long
-integers uniformly distributed between \-2^31 and 2^31.
+integers uniformly distributed over the interval [\-2^31,\ 2^31).
 .PP
 The
 .BR srand48 (),

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Bug#794876: manpages-dev: Should guide users away from deprecated sys_errlist more

[Michael Kerrisk (man-pages)]

On 08/07/2015 04:24 PM, Dale E. Martin wrote:
 Package: manpages-dev
 Version: 3.74-1
 Severity: wishlist
 Tags: patch
 
 Dear Maintainer,
 I recently caused a problem for myself when writing some C-code by making
 direct use of sys_errlist.  I did this after reading the manpage for
 perror. The code I wrote worked on Debian 7, but was not binary
 compatible with Debian 6, much to my surprise.  Replacing my use of
 sys_errlist with strerror fixed the problem.
 
 I have attached a suggested update to the perror (3) manpage.  It is meant
 as an example, I have no strong feelings about my actual text.

Hello Dale, 

Your submission would be much better to understand as a diff (preferably
against latest upstream), with an explanation of how your proposed
changes address the problem you encountered.

Thanks,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/


-- 
To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org

Bug#794217: socketpair: unclear where the SOCK_NONBLOCK and SOCK_CLOEXEC flags go

[Michael Kerrisk (man-pages)]

tags 794217 fixed-upstream
thanks

Hello Goswin,

On 07/31/2015 12:41 PM, Goswin von Brederlow wrote:
 Package: manpages-dev
 Version: 3.74-1
 Severity: minor
 File: socketpair
 
 Hi,
 
 reading 'man 2 socketpair' it is unclear where the new SOCK_NONBLOCK
 and SOCK_CLOEXEC flags go in the function call. One has to read
 through man 2 socket to discover that the type argument now also
 serves as flags.
 
 I recommend making this a bit clearer by changing the Notes from:
 
Since   Linux  2.6.27,  socketpair()  supports  the  SOCK_NONBLOCK  and
SOCK_CLOEXEC flags described in socket(2).
 
 to:
 
Since   Linux  2.6.27,  socketpair()  supports  the  SOCK_NONBLOCK  and
SOCK_CLOEXEC flags in the _type_ argument as described in socket(2).

Thanks for the report. I've changed the upstream page, as you propose.

MfG aus München

Michael


 -- System Information:
 Debian Release: jessie/sid
   APT prefers unstable
   APT policy: (500, 'unstable'), (1, 'experimental')
 Architecture: amd64 (x86_64)
 Foreign Architectures: i386, armel
 
 Kernel: Linux 3.14-1-amd64 (SMP w/4 CPU cores)
 Locale: LANG=C, LC_CTYPE=de_DE (charmap=ISO-8859-1)
 Shell: /bin/sh linked to /bin/dash
 Init: sysvinit (via /sbin/init)
 
 Versions of packages manpages-dev depends on:
 ii  manpages  3.61-1
 
 manpages-dev recommends no packages.
 
 Versions of packages manpages-dev suggests:
 ii  man-db [man-browser]  2.6.7.1-1
 
 -- no debconf information
 
 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/


-- 
To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org

Bug#794559: ld.so(8) LD_LIBRARY_PATH also treats ';' as a seperator

[Michael Kerrisk (man-pages)]

tags 794559 fixed-upstream
thanks

On 08/04/2015 02:05 PM, Jonathan David Amery wrote:
 Package: manpages
 Version: 3.44-1
 Severity: normal
 
 The documentation for LD_LIBRARY_PATH notes that the list is colon-seperated;
 however ld.so also treats ';' as a seperator (possibly for compatability 
 reasons).
 
 The manpage should note this otherwise the results of trying to have a library
 path that includes a ';' as part of a directory name are very confusing.

Thanks Jonathan. I confirm your point, and I've applied the patch below.

Cheers,

Michael

diff --git a/man8/ld.so.8 b/man8/ld.so.8
index 700628c..1c643c7 100644
--- a/man8/ld.so.8
+++ b/man8/ld.so.8
@@ -228,8 +228,9 @@ when they are first referenced.
 This is useful when using a debugger.
 .TP
 .B LD_LIBRARY_PATH
-A colon-separated list of directories in which to search for
+A list of directories in which to search for
 ELF libraries at execution-time.
+The items in the list are separated by either colons or semicolons.
 Similar to the
 .B PATH
 environment variable.


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/


-- 
To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org

Bug#788870: Processed: Bug#788870: [base-files] 'LANG=C man 8 resolv+': (fwd)

[Michael Kerrisk (man-pages)]

tags 788870 fixed-upstream
thanks

This reference was removed in upstream man-pages in May 2014, with
commit 0921ce4ab089dca648a4d25f8e7dad8942b84567.

Thanks,

Michael



On 16 June 2015 at 12:36, Debian Bug Tracking System
ow...@bugs.debian.org wrote:
 Processing commands for cont...@bugs.debian.org:

 reassign 788870 manpages
 Bug #788870 [base-files] [base-files] 'LANG=C man 8 resolv+':
 Bug reassigned from package 'base-files' to 'manpages'.
 No longer marked as found in versions base-files/8+deb8u1.
 Ignoring request to alter fixed versions of bug #788870 to the same values 
 previously set
 retitle 788870 manpages references resolv+(8) but does not include it
 Bug #788870 [manpages] [base-files] 'LANG=C man 8 resolv+':
 Changed Bug title to 'manpages references resolv+(8) but does not include it' 
 from '[base-files] 'LANG=C man 8 resolv+':'
 thanks
 Stopping processing here.

 Please contact me if you need assistance.
 --
 788870: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=788870
 Debian Bug Tracking System
 Contact ow...@bugs.debian.org with problems




-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/


-- 
To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org

Bug#787625: /usr/share/man/man7/epoll.7.gz: epoll(7): wrong string provided to perror in example code

[Michael Kerrisk (man-pages)]

tags 787625 fixed-upstream
thanks

Fixed with upstream commit be6b243ae2d6b3ba158684c945076a1fd65a6f2f

On 4 June 2015 at 16:49, Michael Kerrisk (man-pages)
mtk.manpa...@gmail.com wrote:
 On 06/03/2015 03:17 PM, Uwe Kleine-König wrote:
 Package: manpages
 Version: 3.74-1
 Severity: minor
 File: /usr/share/man/man7/epoll.7.gz

 The example code in epoll(7) includes:

nfds = epoll_wait(epollfd, events, MAX_EVENTS, -1);
if (nfds == -1) {
  perror(epoll_pwait);

 I suggest to pass epoll_wait (i.e. without a 'p') to perror instead.

 Thanks, Uwe. Fixed.

 Cheers,

 Michael


 -- System Information:
 Debian Release: 8.0
   APT prefers proposed-updates
   APT policy: (900, 'proposed-updates'), (900, 'stable'), (600, 'unstable'), 
 (500, 'experimental')
 Architecture: amd64 (x86_64)
 Foreign Architectures: i386

 Kernel: Linux 3.16.0-4-amd64 (SMP w/4 CPU cores)
 Locale: LANG=en_US.utf8, LC_CTYPE=en_US.utf8 (charmap=UTF-8)
 Shell: /bin/sh linked to /bin/dash
 Init: systemd (via /run/systemd/system)

 manpages depends on no packages.

 manpages recommends no packages.

 Versions of packages manpages suggests:
 ii  man-db [man-browser]  2.7.0.2-5

 -- no debconf information




 --
 Michael Kerrisk
 Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
 Linux/UNIX System Programming Training: http://man7.org/training/



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/


--
To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org

Bug#787625: /usr/share/man/man7/epoll.7.gz: epoll(7): wrong string provided to perror in example code

[Michael Kerrisk (man-pages)]

On 06/03/2015 03:17 PM, Uwe Kleine-König wrote:
 Package: manpages
 Version: 3.74-1
 Severity: minor
 File: /usr/share/man/man7/epoll.7.gz
 
 The example code in epoll(7) includes:
 
nfds = epoll_wait(epollfd, events, MAX_EVENTS, -1);
if (nfds == -1) {
  perror(epoll_pwait);
 
 I suggest to pass epoll_wait (i.e. without a 'p') to perror instead.

Thanks, Uwe. Fixed.

Cheers,

Michael


 -- System Information:
 Debian Release: 8.0
   APT prefers proposed-updates
   APT policy: (900, 'proposed-updates'), (900, 'stable'), (600, 'unstable'), 
 (500, 'experimental')
 Architecture: amd64 (x86_64)
 Foreign Architectures: i386
 
 Kernel: Linux 3.16.0-4-amd64 (SMP w/4 CPU cores)
 Locale: LANG=en_US.utf8, LC_CTYPE=en_US.utf8 (charmap=UTF-8)
 Shell: /bin/sh linked to /bin/dash
 Init: systemd (via /run/systemd/system)
 
 manpages depends on no packages.
 
 manpages recommends no packages.
 
 Versions of packages manpages suggests:
 ii  man-db [man-browser]  2.7.0.2-5
 
 -- no debconf information
 
 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/


-- 
To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org

Bug#630029: Processed: retitle 630029 to read/write/readv/writev/sendfile.2: undocumented cap on number of bytes read/written

[Michael Kerrisk (man-pages)]

tags 630029 fixed-upstream
thanks

And here's the documentation fix.

Thanks,

Michael

diff --git a/man2/pread.2 b/man2/pread.2
index de1e951..c7a7fdd 100644
--- a/man2/pread.2
+++ b/man2/pread.2
@@ -85,6 +85,12 @@ and
 .BR pwrite ()
 returns the number of bytes written.

+Note that is not an error for a successful call to transfer fewer bytes
+than requested (see
+.BR read (2)
+and
+.BR write (2)).
+
 On error, \-1 is returned and
 .I errno
 is set to indicate the cause of the error.
diff --git a/man2/read.2 b/man2/read.2
index 62d7d8b..c581f72 100644
--- a/man2/read.2
+++ b/man2/read.2
@@ -87,6 +87,8 @@ available right now (maybe because we were close to
end-of-file, or
 because we are reading from a pipe, or from a terminal), or because
 .BR read ()
 was interrupted by a signal.
+See also NOTES.
+
 On error, \-1 is returned, and
 .I errno
 is set appropriately.
@@ -178,6 +180,14 @@ or to return the number of bytes already read.
 .SH CONFORMING TO
 SVr4, 4.3BSD, POSIX.1-2001.
 .SH NOTES
+On Linux,
+.BR read ()
+(and similar system calls) will transfer at most
+0x7000 (2,147,479,552) bytes,
+returning the number of bytes actually transferred.
+.\ commit e28cc71572da38a5a12c1cfe4d7032017adccf69
+(This is true on both 32-bit and 64-bit systems.)
+
 On NFS filesystems, reading small amounts of data will update the
 timestamp only the first time, subsequent calls may not do so.
 This is caused
diff --git a/man2/readv.2 b/man2/readv.2
index 3cc0813..3cf0c2f 100644
--- a/man2/readv.2
+++ b/man2/readv.2
@@ -184,6 +184,13 @@ return the number of bytes read;
 and
 .BR pwritev ()
 return the number of bytes written.
+
+Note that is not an error for a successful call to transfer fewer bytes
+than requested (see
+.BR read (2)
+and
+.BR write (2)).
+
 On error, \-1 is returned, and \fIerrno\fP is set appropriately.
 .SH ERRORS
 The errors are as given for
diff --git a/man2/sendfile.2 b/man2/sendfile.2
index 972564c..ef9ba6c 100644
--- a/man2/sendfile.2
+++ b/man2/sendfile.2
@@ -113,6 +113,7 @@ Note that a successful call to
 .BR sendfile ()
 may write fewer bytes than requested;
 the caller should be prepared to retry the call if there were unsent bytes.
+See also NOTES.

 On error, \-1 is returned, and
 .I errno
@@ -166,6 +167,12 @@ Other UNIX systems implement
 with different semantics and prototypes.
 It should not be used in portable programs.
 .SH NOTES
+.BR sendfile ()
+will transfer at most 0x7000 (2,147,479,552) bytes,
+returning the number of bytes actually transferred.
+.\ commit e28cc71572da38a5a12c1cfe4d7032017adccf69
+(This is true on both 32-bit and 64-bit systems.)
+
 If you plan to use
 .BR sendfile ()
 for sending files to a TCP socket, but need
diff --git a/man2/write.2 b/man2/write.2
index 90ef9b5..3e8c363 100644
--- a/man2/write.2
+++ b/man2/write.2
@@ -89,6 +89,10 @@ Note that not all filesystems are POSIX conforming.
 .SH RETURN VALUE
 On success, the number of bytes written is returned (zero indicates
 nothing was written).
+It is not an error if this number is smaller than the number of bytes
+requested; this may happen for example because the disk device was filled.
+See also NOTES.
+
 On error, \-1 is returned, and \fIerrno\fP is set
 appropriately.

@@ -217,6 +221,14 @@ then the call fails with the error
 .BR EINTR ;
 if it is interrupted after at least one byte has been written,
 the call succeeds, and returns the number of bytes written.
+
+On Linux,
+.BR read ()
+(and similar system calls) will transfer at most
+0x7000 (2,147,479,552) bytes,
+returning the number of bytes actually transferred.
+.\ commit e28cc71572da38a5a12c1cfe4d7032017adccf69
+(This is true on both 32-bit and 64-bit systems.)
 .SH BUGS
 According to POSIX.1-2008/SUSv4 Section XSI 2.9.7
 (Thread Interactions with Regular File Operations):


-- 
To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org

Bug#621057: printf.3: ATTRIBUTES: Note functions those are thread-safe

[Michael Kerrisk (man-pages)]

On 03/23/2015 04:24 AM, Zeng Linggang wrote:
 The markings match glibc markings.

Hello Zeng Linggang,

This patch seems to have been sent twice...

Cheers,

Michael



 Signed-off-by: Zeng Linggang zenglg...@cn.fujitsu.com
 Signed-off-by: Ma Shimiao mashimiao.f...@cn.fujitsu.com
 ---
  man3/printf.3 | 23 +++
  1 file changed, 23 insertions(+)
 
 diff --git a/man3/printf.3 b/man3/printf.3
 index bf84f07..8b24f20 100644
 --- a/man3/printf.3
 +++ b/man3/printf.3
 @@ -822,6 +822,29 @@ A \(aq%\(aq is written.
  No argument is converted.
  The complete conversion
  specification is \(aq%%\(aq.
 +.SH ATTRIBUTES
 +For an explanation of the terms used in this section, see
 +.BR attributes (7).
 +.TS
 +allbox;
 +lb lb lb
 +l l l.
 +InterfaceAttribute   Value
 +T{
 +.BR printf (),
 +.BR fprintf (),
 +.br
 +.BR sprintf (),
 +.BR snprintf (),
 +.br
 +.BR vprintf (),
 +.BR vfprintf (),
 +.br
 +.BR vsprintf (),
 +.BR vsnprintf ()
 +T}   Thread safety   MT-Safe locale
 +.TE
 +
  .SH CONFORMING TO
  The
  .BR fprintf (),
 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/


-- 
To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org

Bug#773443: host.conf.5: spoof deprecated ?

[Michael Kerrisk (man-pages)]

Hello Stéphane,

On 10 March 2015 at 00:26, Stéphane Aulery saul...@free.fr wrote:
 Hello Michael,

 Le lundi 09 mars 2015 à 10:03:09, Michael Kerrisk (man-pages) a écrit :
 On 03/09/2015 08:59 AM, Stéphane Aulery wrote:
  Le lundi 09 mars 2015 à 08:22:01, Michael Kerrisk (man-pages) a écrit :
 
  On 03/08/2015 02:05 PM, Stéphane Aulery wrote:
 
  A Debian user reported that [1]:
 
  spoof* keywords (nospoof, spoofalert, spoof) are here from 1996,
  they are still valid keywords but do not have any effect apparently,
  no libraries or tools use them
 
  it is misleading to see references to resolv+ and rlogin, the keywords
  are just ignored these days; the only meaning they have is that they
  are
  allowed by host.conf syntax
 
  The glibc source code seems to confirm that the keywords nospoof,
  spoofalert and spoof are accepted but without effects. I could find
  nothing in the changelog. Could you please confirm that they are
  obsolete? I could correct the man page accordingly.
 
  I had a quick grep in the glibc source code.
 
  It appears that you (and the reporter) are correct. (Even back in
  glibc 2.1, things look the same).
 
  A patch would be appreciated!

 I dug a little further comparing versions 2.0.6 [1], 2.0.7 [2]
 and trunk [3] of glibc and I come to a different conclusion.

 The keywords nospoof, spoofalert, spoof and RESOLV_SPOOF_CHECK were
 added to glibc 2.0.7 but never implemented and documented in the
 changelog.

Perfect -- that's exactly the sort of detail it's great to have in man-pages!

Cheers,

Michael


 [1] http://ftp.gnu.org/gnu/glibc/glibc-2.0.6.tar.gz
 [2] 
 http://archive.debian.org/debian/dists/hamm/main/source/libs/glibc_2.0.7t.orig.tar.gz
 [3] 
 https://sourceware.org/git/?p=glibc.gita=searchh=HEADst=greps=spoofsr=1

 Regards,

 --
 Stéphane Aulery



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/


--
To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org

Bug#773443: [PATCH] host.conf.5: keywords and env. var. nospoof, spoofalert, spoof and RESOLV_SPOOF_CHECK were added to glibc 2.0.7 but never implemented

[Michael Kerrisk (man-pages)]

 off ,  nowarn  and  warn .
  .SH SEE ALSO
  .BR gethostbyname (3),
  .BR hosts (5),
 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/


-- 
To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org

Bug#773443: host.conf.5: spoof deprecated ?

[Michael Kerrisk (man-pages)]

On 03/09/2015 08:59 AM, Stéphane Aulery wrote:
 Le lundi 09 mars 2015 à 08:22:01, Michael Kerrisk (man-pages) a écrit :
 Hello Stéphane

 On 03/08/2015 02:05 PM, Stéphane Aulery wrote:
 ** COPY OF GLIBC BUGZILLA #18091 FOR INFORMATION **
 https://sourceware.org/bugzilla/show_bug.cgi?id=18091

 -

 Hello,

 A Debian user reported that [1]:

 spoof* keywords (nospoof, spoofalert, spoof) are here from 1996,
 they are still valid keywords but do not have any effect apparently,
 no libraries or tools use them

 it is misleading to see references to resolv+ and rlogin, the keywords
 are just ignored these days; the only meaning they have is that they
 are
 allowed by host.conf syntax

 The glibc source code seems to confirm that the keywords nospoof,
 spoofalert and spoof are accepted but without effects. I could find
 nothing in the changelog. Could you please confirm that they are
 obsolete? I could correct the man page accordingly.

 I had a quick grep in the glibc source code.

 It appears that you (and the reporter) are correct. (Even back in 
 glibc 2.1, things look the same).

 A patch would be appreciated!
 
 Eventually, I may check others values too.
 Do you to want to drop obsolete values or add a note ?

Best to keep a note that they exist, but do nothing.

Cheers,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/


-- 
To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org

Bug#773443: host.conf.5: spoof deprecated ?

[Michael Kerrisk (man-pages)]

Hello Stéphane

On 03/08/2015 02:05 PM, Stéphane Aulery wrote:
 ** COPY OF GLIBC BUGZILLA #18091 FOR INFORMATION **
 https://sourceware.org/bugzilla/show_bug.cgi?id=18091
 
 -
 
 Hello,
 
 A Debian user reported that [1]:
 
 spoof* keywords (nospoof, spoofalert, spoof) are here from 1996,
 they are still valid keywords but do not have any effect apparently,
 no libraries or tools use them

 it is misleading to see references to resolv+ and rlogin, the keywords
 are just ignored these days; the only meaning they have is that they
 are
 allowed by host.conf syntax
 
 The glibc source code seems to confirm that the keywords nospoof,
 spoofalert and spoof are accepted but without effects. I could find
 nothing in the changelog. Could you please confirm that they are
 obsolete? I could correct the man page accordingly.

I had a quick grep in the glibc source code.

It appears that you (and the reporter) are correct. (Even back in 
glibc 2.1, things look the same).

A patch would be appreciated!

Cheers,

Michael

PS For reports like this, when you've checked things, it would speed 
things a little to note how you deduced your info (e.g., reference 
to source file and function).



 
 [1] https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=773443



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/


-- 
To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org