[OpenAFS-devel] File Descriptor use in the vol package

[Rod Widdowson]

The vol package uses three separate types of file descriptor.

FILE *f
int fd
FD_t 

The first need no description.

The second are usually manipulated via the unix "syscall type" apis
(open/read/write/fstat) but these apis are mostly (but not entirely)
abstracted away via macros afs_open/afs_read/afs_write/afs_fstat.

The last is an abstraction over whatever is provided natively by the
operating system.  On Unix derivatives therefore FD_t is defined as
being int.  However on other operating systems (notably Windows) this
is entirely different (on windows FD_t is a HANDLE in OpenVMS 
it would be a channel)

There is no use of APIs to convert between FD_t and int.  Nonetheless
the "int fd" type is also used in operating systems where FD_t =/=
int, and this mixing of modes is known to cause issues which transcend
readability - a file opened by the "int" APIs may not be manipulatable
via the FD_t ones and the int APIs may not have the required semantics.

In some modules (namei_ops and vutil) FD_t is being cast to and from
an int.  One assumes that this is self cancelling (it is in vutil).

The rest of this mail is the best function by function audit I can
manage of the use of these three types of descriptor.  In the table
below P means the the descriptor type is a parameter or is inside a
structure passed as parameter and U means that the descriptor type is
used inside the function.

Note that I am not talking about the descriptors used to handle AFS
files within the server (such as IHandle_t) except inasmuch as when
the structures contain these descriptors themselves

I am also not at this stage looking at directory descriptors.

Module  Function              FILE      int     FD_T    Notes
devname.c:
        vol_DevName             U                       Solaris only
gi.c:
        main                            U               iopen
ihandle.c
        ih_open                                 UP
        fd_close                                P
        ih_fdclose                              U
        fd_reallyclose                          U
        stream_fdopen                            P
        stream_open                             U
        ih_size                                  P      
namei_ops.c/listinodes.c:
        emul_flock                      U
        namei_ViceREADME                U               not WIN32       
        namei_icreate                   U       U       int cast to FD_t
        namei_iopen                     U               int cast to FD_t
        namei_GetLinkCount                      P
        SetOGM                          P
        CheckOGm                        U       P       FD_t case to int
        namei_SetLinkCount              P
        namei_copy_on_write             U       U       not WIN32
        namei_examine_special   P       U       UP      int cast to FD_t 
                                                        (in FdHandle_s)
        namei_examine_reg       P               P       
        namei_examine_file      P               P       listsubdirs_work_node 
                                                        has both!
        _namei_examine_file_spawn
                                P               P       ditto
        namei_ListAFSSubDirs    P               U       
        DecodeInode (WIN32)             U       U       int cast to FD_t (in FdHandle_s)
                                                        This also appears to leak open files.
        namei_ConvertROtoRWvolume
                                        U       U       int case to FD_t
        WriteInodeInfo          PU
        ListViceInodes          PU
        namei_ListAFSFiles      P
        namei_ListAFSSubDirs    PU              U
        convertVolumeInfo                       P
partition.c:
        VerifyXFSInodeSize              U               AIX only
        VInitPartition_r                U               Not WIN32, NAMEI_ENV
        VAttachPartitions       U                       SUN5, SGI, SUN, LINUX22                    
        VLockPartition_r                U       U       int cast to FD_t (not for WIN32)
        VUnlockPartition_r              U       U       FD_t case to int (not for WIN32)        
salvaged.c:
        DoSalvageVolume         U                       Logging
        SalvageLogCleanup               U               Pidfile
vol-salvage.c:
        SalvageFileSysParallel  U       U               FILE == logging, int Not WIN32
        CheckLogFile            U                       Logging
        showlog                 U                       Logging
        Log                     U                       Logging
        Abort                   U                       Logging
        nt_SetupPartitionSalvage
                                U                       Logging
        IsPartitionMounted      U                       SGI
        SalvageFileSys1         U       U       U       uses fileno to convert FILE*->int
        GetInodeSummary                 PU
        DeleteExtraVolumeHeaderFile     P
        AskVolumeSummary                P
        DoSalvageVolumeGroup            PU
        PrintInodeList                  PU
        SalvageIndex                            U
        DistilVnodeEssence                      U
vol-info.c:
        HandleVolume                    U
        PrintVnodes                     U       U       FD_t cast to int(not WIN32)
vutil.c:
        VReadVolumeDiskHeader           U       
        _VWriteVolumeDiskHeader         U
        _VHandleVolumeHeader            U
        _VOpenPath                      P       P       return is FD_t or int depending on build
        _VlockFd                        P       P       param is FD_t or int depending on build
        _VUnlockFd                      P       P       ditto
        _VCloseFd                       P       P       ditto



[Apologies for the wrapping].