Historically this code was like this because for BAM files hts_itr_next() used its BGZF *fp argument (and ignored its void *data argument) and called bam_readrec() which used bam_read1() with the BGZF *fp argument. Meanwhile for CRAM files hts_itr_next() used the void *data argument but ignored the BGZF *fp argument.

This changed — and this bug was introduced — when iterating over SAM files was added and bam_readrec() (using bam_read1() and BGZF *fp) was replaced by sam_readrec() (using sam_read1() and void *data aka htsFile *).

Since then for BAM files, hts_itr_next() has mixed up seeking on the BGZF * with reading from the htsFile *. This works more by luck than design!

So IMHO this bug report is an indication that this code needs a careful review and, if moving to htsFile * everywhere in hts_itr_next(), streamlining and removal of the legacy BGZF * parameter (ABI issues notwithstanding). And/or more heavily deprecating the legacy bam_itr_* functions.

Well, the bam_itr_* interface has now effectively gone as it just calls the sam_itr_* equivalents. You're right, though, the iterator code is quite hairy and would benefit from some simplification.