API/ABI rank of headers in /usr/include/isofs/cd9660

["Thomas Schmitt" <scdbackup%gmx.net@localhost>]

Hi,

while fixing rollovers and implementing a new mount_cd9660 option -s,
i stumble over the content of public include directory
  /usr/include/isofs/cd9660
which exposes all header files from the kernel source of cd9660:
  cd9660_extern.h     cd9660_rrip.h       iso_rrip.h
  cd9660_mount.h      cd9660_node.h       iso.h

cd9660_mount.h is needed to operate mount(2) from userland.
I did not find the spot in the man pages yet, which clearly states
this. Is there a documentation gap between man 2 mount,
/usr/include/sys/mount.h, and man 8 mount_cd9660 ?

Whatever, the others are exposing smelly entrails of the kernel
implementation of cd9660.

Are they to be considered API/ABI nevertheless, and thus need
compatibility precautions ?


Reasons against API/ABI rank, except the smell:

I see a small difference between cd9660_extern.h of /usr/include
(6.1.3) and current /usr/src :
-------------------------------------------------------------------
1c1
< /*    $NetBSD: cd9660_extern.h,v 1.24 2008/06/28 01:34:05 rumble Exp $        
*/
---
> /*    $NetBSD: cd9660_extern.h,v 1.26 2013/06/23 07:28:36 dholland Exp $      
> */
88,91c88,91
< #define blkoff(imp, loc)      ((loc) & (imp)->im_bmask)
< #define lblktosize(imp, blk)  ((blk) << (imp)->im_bshift)
< #define lblkno(imp, loc)      ((loc) >> (imp)->im_bshift)
< #define blksize(imp, ip, lbn) ((imp)->logical_block_size)
---
> #define cd9660_blkoff(imp, loc)               ((loc) & (imp)->im_bmask)
> #define cd9660_lblktosize(imp, blk)   ((blk) << (imp)->im_bshift)
> #define cd9660_lblkno(imp, loc)       ((loc) >> (imp)->im_bshift)
> #define cd9660_blksize(imp, ip, lbn)  ((imp)->logical_block_size)
-------------------------------------------------------------------
So API compatibility seems not to be a primary goal here ?

Filesystem UDF, for example, exposes only two of its 6 kernel headers
in /usr/include/fs/udf:
  udf_mount.h    defines public mount(2) struct and flag bits
  ecma167-udf.h  defines C representations of objects out of UDF specs
  
So why would cd9660 need more than this ?
  cd9660_mount.h defines public mount(2) struct and flag bits
  iso.h          defines C representations of objects out of ISO 9660 specs

Already iso_rrip.h defines funtions which are only reachable inside
/usr/src/sys/fs/cd9660. The others expose data structures which i
deem private to the kernel.


I would take outmost precautions for compatibility if the files in
question are really of public API/ABI rank. (Could need some kind
of supervisor for this.)

A change in struct iso_mnt of cd9660_extern.h is inevitable if
NetBSD's mount_cd9660 shall get the option -s, which FreeBSD and
OpenBSD already have. Further there are signed int, where unsigned
is approriate. 

Best would be, of course, if i could consider private all the headers
except  cd9660_mount.h .
My change there is hopefully well behaved in respect to API/ABI
compatibility, thanks to the data_len parameter of mount(2).


Have a nice day :)

Thomas