On 11 Nov 2014 08:14, Michael Kerrisk (man-pages) wrote:
> On 11/09/2014 04:50 PM, Heinrich Schuchardt wrote:
> > The list contains hex values of different constants. I just wonder for 
> > which architecture (alpha, i386, mips, or sparc at that time). No 
> > information is supplied.
> > 
> > Current values depend on the architecture, e.g.
> > 
> > On amd64
> > 0x82307201      VFAT_IOCTL_READDIR_BOTH
> > 0x82307202      VFAT_IOCTL_READDIR_SHORT
> > 0x80047210      FAT_IOCTL_GET_ATTRIBUTES
> > 0x40047211      FAT_IOCTL_SET_ATTRIBUTES
> > 0x80047213      FAT_IOCTL_GET_VOLUME_ID
> > 
> > On mips
> > 0x42187201      VFAT_IOCTL_READDIR_BOTH
> > 0x42187202      VFAT_IOCTL_READDIR_SHORT
> > 0x40047210      FAT_IOCTL_GET_ATTRIBUTES
> > 0x80047211      FAT_IOCTL_SET_ATTRIBUTES
> > 0x40047213      FAT_IOCTL_GET_VOLUME_ID
> >
> > Hence hex values should be removed.
> 
> It sounds like you are right that the hex values should be 
> removed. But, how did you determine those different
> hex values above? Grepping the sources, it's not
> obvious that amd64 and mips should be different.

ioctl's can integrate the type size right ?  so wouldn't be surprised if it 
changed across arches.

fwiw, strace carries a script to try and do all this magic automatically:
http://sourceforge.net/p/strace/code/ci/master/tree/linux/ioctlent.sh
of course it misses out on ioctls that aren't exported in headers and are 
internal to specific drivers.  i.e. it's not perfect at all, but that's because 
ioctls are a goddamn mess :).

i agree though that the man page should drop hex values as they aren't useful.  
if you're using a "standard" ioctl, you should get it from the relevant header 
file.  if you're using a "non-standard" ioctl, then you get the pieces.

> > I further suggest to remove all documentation of structure details.
> 
> Could you elaborate this point a little. Some examples, and
> why you think they should be removed. I'm not disagreeing, just
> looking to clarify what you mean.

i think for the common/standard ioctls, it's useful to have manpages that delve 
down into the details.  but for the fringe ones, it's a waste of time for the 
vast majority of people.

maybe one way to determine whether it's worth documenting, see if strace has a 
decoder for it :).
-mike