Man page bugs?

Hi, Michael and list!

I found two problems in the man pages. The first one should be a bug. It is that the type of the 2nd and 4th arguments of splice(2) is wrong. The current prototype of splice(2) in current man page is:

long splice(int fd_in, off_t *off_in, int fd_out,
off_t *off_out, size_t len, unsigned int flags);

However, they should be 'loff_t' instead of 'off_t'. If we use 'off_t', gcc will generate a warning. Patch is in the end of this email and it's against 2.76 release. ;)

The second one is a bit confused. The example given in tee(2) even can not run normally. I got this error:

$ ./example bar.txt
tee: Invalid argument

I looked at tee(2), it is said that:

EINVAL fd_in or fd_out does not refer to a pipe; or fd_in and fd_out
refer to the same pipe.

So the first two arguments of tee(2) in the example is wrong, since neither STDIN_FILENO nor STDOUT_FILENO refers to a pipe. But I am not so sure, because I am new to tee(2). ;) If you can comfirm this is really a bug, I can send a patch to fix this too.

I have checked the newest release of man pages and my kernel version is 2.6.21-1.3194.fc7. Did I miss something obvious?

Index: man-pages-2.76/man2/splice.2
===================================================================

man2/splice.2 +2 -2

@@ -31,8 +31,8 @@ splice \- splice data to/from a pipe
 .B #define _GNU_SOURCE
 .B #include <fcntl.h>
 
-.BI "long splice(int " fd_in ", off_t *" off_in ", int " fd_out ,
-.BI "            off_t *" off_out ", size_t " len \
+.BI "long splice(int " fd_in ", loff_t *" off_in ", int " fd_out ,
+.BI "            loff_t *" off_out ", size_t " len \
 ", unsigned int " flags );
 .fi
 .SH DESCRIPTION

Hi Cong,

Quoted 7 lines · WANG Cong

Hi, Michael and list!

I found two problems in the man pages. The first one should be a bug. It is that the type of the 2nd and 4th arguments of splice(2) is wrong. The current prototype of splice(2) in current man page is:

Quoted 6 lines

long splice(int fd_in, off_t *off_in, int fd_out,
off_t *off_out, size_t len, unsigned int flags);

However, they should be 'loff_t' instead of 'off_t'. If we use 'off_t', gcc will generate a warning. Patch is in the end of this email and it's against 2.76 release. ;)

Thanks for spotting that. Fixed as you suggest, for man-pages-2.77.

Quoted 16 lines

The second one is a bit confused. The example given in tee(2) even can not run normally. I got this error:

$ ./example bar.txt
tee: Invalid argument

I looked at tee(2), it is said that:

EINVAL fd_in or fd_out does not refer to a pipe; or fd_in and fd_out
refer to the same pipe.

So the first two arguments of tee(2) in the example is wrong, since neither STDIN_FILENO nor STDOUT_FILENO refers to a pipe. But I am not so sure, because I am new to tee(2). ;) If you can comfirm this is really a bug, I can send a patch to fix this too.

Quoted 2 lines

I have checked the newest release of man pages and my kernel version is 2.6.21-1.3194.fc7. Did I miss something obvious?

I'm not sure. Perhaps Jens, the implementer of tee(2) can provide a little help. Jens, what's an example of a command line for running the example program in the tee.2 man page?

Quoted 34 lines · Michael Kerrisk

Hi Cong,

Quoted 7 lines · WANG Cong

Hi, Michael and list!

I found two problems in the man pages. The first one should be a bug. It is that the type of the 2nd and 4th arguments of splice(2) is wrong. The current prototype of splice(2) in current man page is:

Quoted 6 lines

long splice(int fd_in, off_t *off_in, int fd_out,
off_t *off_out, size_t len, unsigned int flags);

However, they should be 'loff_t' instead of 'off_t'. If we use 'off_t', gcc will generate a warning. Patch is in the end of this email and it's against 2.76 release. ;)

Thanks for spotting that. Fixed as you suggest, for man-pages-2.77.

Quoted 16 lines

The second one is a bit confused. The example given in tee(2) even can not run normally. I got this error:

$ ./example bar.txt
tee: Invalid argument

I looked at tee(2), it is said that:

EINVAL fd_in or fd_out does not refer to a pipe; or fd_in and fd_out
refer to the same pipe.

So the first two arguments of tee(2) in the example is wrong, since neither STDIN_FILENO nor STDOUT_FILENO refers to a pipe. But I am not so sure, because I am new to tee(2). ;) If you can comfirm this is really a bug, I can send a patch to fix this too.

Quoted 5 lines

Quoted 2 lines

I have checked the newest release of man pages and my kernel version is 2.6.21-1.3194.fc7. Did I miss something obvious?

I'm not sure. Perhaps Jens, the implementer of tee(2) can provide a little help. Jens, what's an example of a command line for running the example program in the tee.2 man page?

It's not a bug, it should be run as:

$  echo hello | ./example output_file | cat

so that both stdin and stdout are pipes, as described in the man page. The man page is correct.

Quoted 41 lines · Jens Axboe

Quoted 34 lines · Michael Kerrisk

Hi Cong,

Quoted 7 lines · WANG Cong

Hi, Michael and list!

I found two problems in the man pages. The first one should be a bug. It is that the type of the 2nd and 4th arguments of splice(2) is wrong. The current prototype of splice(2) in current man page is:

Quoted 6 lines

long splice(int fd_in, off_t *off_in, int fd_out,
off_t *off_out, size_t len, unsigned int flags);

However, they should be 'loff_t' instead of 'off_t'. If we use 'off_t', gcc will generate a warning. Patch is in the end of this email and it's against 2.76 release. ;)

Thanks for spotting that. Fixed as you suggest, for man-pages-2.77.

Quoted 16 lines

The second one is a bit confused. The example given in tee(2) even can not run normally. I got this error:

$ ./example bar.txt
tee: Invalid argument

I looked at tee(2), it is said that:

EINVAL fd_in or fd_out does not refer to a pipe; or fd_in and fd_out
refer to the same pipe.

So the first two arguments of tee(2) in the example is wrong, since neither STDIN_FILENO nor STDOUT_FILENO refers to a pipe. But I am not so sure, because I am new to tee(2). ;) If you can comfirm this is really a bug, I can send a patch to fix this too.

Quoted 5 lines

Quoted 2 lines

I have checked the newest release of man pages and my kernel version is 2.6.21-1.3194.fc7. Did I miss something obvious?

I'm not sure. Perhaps Jens, the implementer of tee(2) can provide a little help. Jens, what's an example of a command line for running the example program in the tee.2 man page?

Quoted 6 lines

It's not a bug, it should be run as:

$  echo hello | ./example output_file | cat

so that both stdin and stdout are pipes, as described in the man page. The man page is correct.

Hi jens,

Yes, I guessed you probably should run it like that. And it does produce the expected output on stdout. However, the command then blocks, and if one types control-C, the output_file is empty. How should this program be terminated so that something does end up in the output_file?

Quoted 44 lines · Michael Kerrisk

Quoted 41 lines · Jens Axboe

Quoted 39 lines · Michael Kerrisk

Hi Cong,

Quoted 7 lines · WANG Cong

Hi, Michael and list!

I found two problems in the man pages. The first one should be a bug. It is that the type of the 2nd and 4th arguments of splice(2) is wrong. The current prototype of splice(2) in current man page is:

Quoted 6 lines

long splice(int fd_in, off_t *off_in, int fd_out,
off_t *off_out, size_t len, unsigned int flags);

However, they should be 'loff_t' instead of 'off_t'. If we use 'off_t', gcc will generate a warning. Patch is in the end of this email and it's against 2.76 release. ;)

Thanks for spotting that. Fixed as you suggest, for man-pages-2.77.

Quoted 11 lines

The second one is a bit confused. The example given in tee(2) even can not run normally. I got this error:

$ ./example bar.txt
tee: Invalid argument

I looked at tee(2), it is said that:

EINVAL fd_in or fd_out does not refer to a pipe; or fd_in and fd_out
refer to the same pipe.

Quoted 7 lines

So the first two arguments of tee(2) in the example is wrong, since neither STDIN_FILENO nor STDOUT_FILENO refers to a pipe. But I am not so sure, because I am new to tee(2). ;) If you can comfirm this is really a bug, I can send a patch to fix this too.

I have checked the newest release of man pages and my kernel version is 2.6.21-1.3194.fc7. Did I miss something obvious?

I'm not sure. Perhaps Jens, the implementer of tee(2) can provide a little help. Jens, what's an example of a command line for running the example program in the tee.2 man page?

Quoted 6 lines

Quoted 6 lines

It's not a bug, it should be run as:

$  echo hello | ./example output_file | cat

so that both stdin and stdout are pipes, as described in the man page. The man page is correct.

Quoted 7 lines

Hi jens,

Yes, I guessed you probably should run it like that. And it does produce the expected output on stdout. However, the command then blocks, and if one types control-C, the output_file is empty. How should this program be terminated so that something does end up in the output_file?

See ktee.c from the splice sample repo, it works correctly:

axboe@carl:~/git/splice> echo hello | ./ktee outfile | cat hello
axboe@carl:~/git/splice> cat outfile
hello

I don't have the tee(2) man page here so can't verify, but try and compare them!

Quoted 47 lines · Jens Axboe

Quoted 46 lines · Michael Kerrisk

Quoted 43 lines · Jens Axboe

Quoted 34 lines · Michael Kerrisk

Hi Cong,

Quoted 7 lines · WANG Cong

Hi, Michael and list!

I found two problems in the man pages. The first one should be a bug. It is that the type of the 2nd and 4th arguments of splice(2) is wrong. The current prototype of splice(2) in current man page is:

Quoted 6 lines

long splice(int fd_in, off_t *off_in, int fd_out,
off_t *off_out, size_t len, unsigned int flags);

However, they should be 'loff_t' instead of 'off_t'. If we use 'off_t', gcc will generate a warning. Patch is in the end of this email and it's against 2.76 release. ;)

Thanks for spotting that. Fixed as you suggest, for man-pages-2.77.

Quoted 16 lines

The second one is a bit confused. The example given in tee(2) even can not run normally. I got this error:

$ ./example bar.txt
tee: Invalid argument

I looked at tee(2), it is said that:

EINVAL fd_in or fd_out does not refer to a pipe; or fd_in and fd_out
refer to the same pipe.

So the first two arguments of tee(2) in the example is wrong, since neither STDIN_FILENO nor STDOUT_FILENO refers to a pipe. But I am not so sure, because I am new to tee(2). ;) If you can comfirm this is really a bug, I can send a patch to fix this too.

Quoted 5 lines

Quoted 2 lines

I have checked the newest release of man pages and my kernel version is 2.6.21-1.3194.fc7. Did I miss something obvious?

I'm not sure. Perhaps Jens, the implementer of tee(2) can provide a little help. Jens, what's an example of a command line for running the example program in the tee.2 man page?

It's not a bug, it should be run as:

Quoted 4 lines

Quoted 4 lines

Quoted 4 lines

$  echo hello | ./example output_file | cat

so that both stdin and stdout are pipes, as described in the man page. The man page is correct.

I think man page should mention about this usage.

Quoted 9 lines

Quoted 6 lines

Hi jens,

Yes, I guessed you probably should run it like that. And it does produce the expected output on stdout. However, the command then blocks, and if one types control-C, the output_file is empty. How should this program be terminated so that something does end up in the output_file?

See ktee.c from the splice sample repo, it works correctly:

Quoted 8 lines

axboe@carl:~/git/splice> echo hello | ./ktee outfile | cat hello
axboe@carl:~/git/splice> cat outfile
hello

I don't have the tee(2) man page here so can't verify, but try and compare them!

I have the same problem here with what Michael mentioned. But my output file is *not* empty. Shown below:

$ echo hello | ./tee fooo.txt | cat
hello
	<=== here blocked, type ctrl+c, exit
$ cat fooo.txt 
hello

My kernel version is 2.6.21-1.3194.fc7.

Quoted 2 lines

I think man page should mention about this usage.

Hmm, but it does - you even quoted the EINVAL return documentation yourself. The description mentions that it dupes between the pipes referred to by fd_in and fd_out. Not sure how much else we can do there?

Quoted 28 lines

Quoted 10 lines

Quoted 7 lines

Hi jens,

Yes, I guessed you probably should run it like that. And it does produce the expected output on stdout. However, the command then blocks, and if one types control-C, the output_file is empty. How should this program be terminated so that something does end up in the output_file?

See ktee.c from the splice sample repo, it works correctly:

Quoted 8 lines

axboe@carl:~/git/splice> echo hello | ./ktee outfile | cat hello
axboe@carl:~/git/splice> cat outfile
hello

I don't have the tee(2) man page here so can't verify, but try and compare them!

I have the same problem here with what Michael mentioned. But my output file is *not* empty. Shown below:

$ echo hello | ./tee fooo.txt | cat
hello
	<=== here blocked, type ctrl+c, exit
$ cat fooo.txt 
hello

Quoted 1 line

My kernel version is 2.6.21-1.3194.fc7.

I don't know what 'tee' is - is it the one from the man page, or the one from my splice tools?