- // mode can be: r/w/rb/wb. On writing, aux points to bam_header_t; on reading, aux points to the name of fn_list for SAM
+ /*!
+ @abstract Open a SAM/BAM file
+
+ @param fn SAM/BAM file name; "-" is recognized as stdin (for
+ reading) or stdout (for writing).
+
+ @param mode open mode /[rw](b?)(u?)(h?)/: 'r' for reading, 'w' for
+ writing, 'b' for BAM I/O, 'u' for uncompressed BAM output and 'h'
+ for outputing header in SAM. If 'b' present, it must immediately
+ follow 'r' or 'w'. Valid modes are "r", "w", "wh", "rb", "wb" and
+ "wbu" exclusively.
+
+ @param aux auxiliary data; if mode[0]=='w', aux points to
+ bam_header_t; if strcmp(mode, "rb")==0 and @SQ header lines in SAM
+ are absent, aux points the file name of the list of the reference;
+ aux is not used otherwise.
+
+ @return SAM/BAM file handler
+ */