为何找不到ioctl()完整文档？TIOCGWINSZ定义该去哪查

检索与溯源过程 #

• 最初在POSIX标准站点检索ioctl()的相关文档，仅找到少量基础说明，没有检索到开发者普遍使用的TIOCGWINSZ的任何相关信息
• 编写C程序时仅引入sys/ioctl.h头文件，顺着Debian设备上的实际编译引用链路追溯头文件定义：
  • 第一处追溯到的文件为/usr/include/linux/ioctl.h，其完整内容如下：

  /* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */
  #ifndef _LINUX_IOCTL_H
  #define _LINUX_IOCTL_H
  
  #include <asm/ioctl.h>
  #endif /* _LINUX_IOCTL_H */
  

  • 顺着该文件引入的asm/ioctl.h继续追溯，对应目标文件为/usr/include/asm-generic/ioctl.h，其完整内容如下：

  /* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */
  #ifndef _ASM_GENERIC_IOCTL_H
  #define _ASM_GENERIC_IOCTL_H
  
  /* ioctl command encoding: 32 bits total, command in lower 16 bits,
   * size of the parameter structure in the lower 14 bits of the
   * upper 16 bits.
   * Encoding the size of the parameter structure in the ioctl request
   * is useful for catching programs compiled with old versions
   * and to avoid overwriting user space outside the user buffer area.
   * The highest 2 bits are reserved for indicating the ``access mode''.
   * NOTE: This limits the max parameter size to 16kB -1 !
   */
  
  /*
   * The following is for compatibility across the various Linux
   * platforms.  The generic ioctl numbering scheme doesn't really enforce
   * a type field.  De facto, however, the top 8 bits of the lower 16
   * bits are indeed used as a type field, so we might just as well make
   * this explicit here.  Please be sure to use the decoding macros
   * below from now on.
   */
  #define _IOC_NRBITS 8
  #define _IOC_TYPEBITS   8
  
  /*
   * Let any architecture override either of the following before
   * including this file.
   */
  
  #ifndef _IOC_SIZEBITS
  # define _IOC_SIZEBITS  14
  #endif
  
  #ifndef _IOC_DIRBITS
  # define _IOC_DIRBITS   2
  #endif
  
  #define _IOC_NRMASK ((1 << _IOC_NRBITS)-1)
  #define _IOC_TYPEMASK   ((1 << _IOC_TYPEBITS)-1)
  #define _IOC_SIZEMASK   ((1 << _IOC_SIZEBITS)-1)
  #define _IOC_DIRMASK    ((1 << _IOC_DIRBITS)-1)
  
  #define _IOC_NRSHIFT    0
  #define _IOC_TYPESHIFT  (_IOC_NRSHIFT+_IOC_NRBITS)
  #define _IOC_SIZESHIFT  (_IOC_TYPESHIFT+_IOC_TYPEBITS)
  #define _IOC_DIRSHIFT   (_IOC_SIZESHIFT+_IOC_SIZEBITS)
  
  /*
   * Direction bits, which any architecture can choose to override
   * before including this file.
   *
   * NOTE: _IOC_WRITE means userland is writing and kernel is
   * reading. _IOC_READ means userland is reading and kernel is writing.
   */
  
  #ifndef _IOC_NONE
  # define _IOC_NONE  0U
  #endif
  
  #ifndef _IOC_WRITE
  # define _IOC_WRITE 1U
  #endif
  
  #ifndef _IOC_READ
  # define _IOC_READ  2U
  #endif
  
  #define _IOC(dir,type,nr,size) \
      (((dir)  << _IOC_DIRSHIFT) | \
       ((type) << _IOC_TYPESHIFT) | \
       ((nr)   << _IOC_NRSHIFT) | \
       ((size) << _IOC_SIZESHIFT))
  
  #define _IOC_TYPECHECK(t) (sizeof(t))
  
  /*
   * Used to create numbers.
   *
   * NOTE: _IOW means userland is writing and kernel is reading. _IOR
   * means userland is reading and kernel is writing.
   */
  #define _IO(type,nr)        _IOC(_IOC_NONE,(type),(nr),0)
  #define _IOR(type,nr,size)  _IOC(_IOC_READ,(type),(nr),(_IOC_TYPECHECK(size)))
  #define _IOW(type,nr,size)  _IOC(_IOC_WRITE,(type),(nr),(_IOC_TYPECHECK(size)))
  #define _IOWR(type,nr,size) _IOC(_IOC_READ|_IOC_WRITE,(type),(nr),(_IOC_TYPECHECK(size)))
  #define _IOR_BAD(type,nr,size)  _IOC(_IOC_READ,(type),(nr),sizeof(size))
  #define _IOW_BAD(type,nr,size)  _IOC(_IOC_WRITE,(type),(nr),sizeof(size))
  #define _IOWR_BAD(type,nr,size) _IOC(_IOC_READ|_IOC_WRITE,(type),(nr),sizeof(size))
  
  /* used to decode ioctl numbers.. */
  #define _IOC_DIR(nr)        (((nr) >> _IOC_DIRSHIFT) & _IOC_DIRMASK)
  #define _IOC_TYPE(nr)       (((nr) >> _IOC_TYPESHIFT) & _IOC_TYPEMASK)
  #define _IOC_NR(nr)     (((nr) >> _IOC_NRSHIFT) & _IOC_NRMASK)
  #define _IOC_SIZE(nr)       (((nr) >> _IOC_SIZESHIFT) & _IOC_SIZEMASK)
  
  /* ...and for the drivers/sound files... */
  
  #define IOC_IN      (_IOC_WRITE << _IOC_DIRSHIFT)
  #define IOC_OUT     (_IOC_READ << _IOC_DIRSHIFT)
  #define IOC_INOUT   ((_IOC_WRITE|_IOC_READ) << _IOC_DIRSHIFT)
  #define IOCSIZE_MASK    (_IOC_SIZEMASK << _IOC_SIZESHIFT)
  #define IOCSIZE_SHIFT   (_IOC_SIZESHIFT)
  
  #endif /* _ASM_GENERIC_IOCTL_H */
  

遇到的核心困惑 #

• 上述两个头文件追溯完成后没有后续引入的其他头文件，整条溯源路径完全走到死路，全程没有出现TIOCGWINSZ的任何定义踪迹
• 疑惑为何广泛使用的TIOCGWINSZ既不出现在POSIX标准文档中，也不在追溯到的Linux内核头文件链路里，甚至在对应man手册中也检索不到相关说明
• 认为POSIX相关文档的组织零散混乱，编程新手无法顺着公开资料系统开展学习，甚至会误以为这类常用接口已经从公开文档体系中消失
• 对这类没有配套文档的接口传播状态感到不解，认为不少参与者只是把编程当作业余爱好，哪怕写出的代码没有配套文档、对其他使用者没有实用价值也无所谓；作为标准化组织，POSIX的文档组织状态远低于预期

内容的提问来源于stack exchange，提问作者71GA