diff --git a/include/cdio/cd_types.h b/include/cdio/cd_types.h index 537a4018..f67513ed 100644 --- a/include/cdio/cd_types.h +++ b/include/cdio/cd_types.h @@ -1,5 +1,5 @@ /* - $Id: cd_types.h,v 1.7 2003/11/17 12:06:57 rocky Exp $ + $Id: cd_types.h,v 1.8 2003/11/18 03:35:19 rocky Exp $ Copyright (C) 2003 Rocky Bernstein Copyright (C) 1996,1997,1998 Gerd Knorr @@ -104,10 +104,11 @@ extern "C" { #define CDIO_FS_MATCH_ALL (cdio_fs_anal_t) (~CDIO_FS_MASK) -/** - * The type used to return analysis information from - * cdio_guess_cd_type. These fields make sense only for when an ISO 9660 - * filesystem is used. +/*! + \brief The type used to return analysis information from + cdio_guess_cd_type. + + These fields make sense only for when an ISO-9660 filesystem is used. */ typedef struct { diff --git a/include/cdio/iso9660.h b/include/cdio/iso9660.h index 1ab8c9b8..3f40751d 100644 --- a/include/cdio/iso9660.h +++ b/include/cdio/iso9660.h @@ -1,5 +1,5 @@ /* - $Id: iso9660.h,v 1.32 2003/11/17 12:06:57 rocky Exp $ + $Id: iso9660.h,v 1.33 2003/11/18 03:35:19 rocky Exp $ Copyright (C) 2000 Herbert Valerio Riedel Copyright (C) 2003 Rocky Bernstein @@ -45,7 +45,7 @@ /*! An ISO filename is: "abcde.eee;1" -> '.' ';' - The maximum needed string length is: + For ISO-9660 Level 1, the maximum needed string length is: \verbatim 30 chars (filename + ext) @@ -100,6 +100,11 @@ enum strncpy_pad_check { PRAGMA_BEGIN_PACKED +/*! + \brief ISO-9660 shorter-format time structure. + + @see iso9660_dtime + */ struct iso9660_dtime { uint8_t dt_year; uint8_t dt_month; /**< Has value in range 1..12. Note starts @@ -114,7 +119,10 @@ struct iso9660_dtime { typedef struct iso9660_dtime iso9660_dtime_t; -/*! ISO-9660 Primary Volume Descriptor. +/*! + \brief ISO-9660 longer-format time structure. + + @see iso9660_ltime */ struct iso9660_ltime { char lt_year [_delta( 1, 4)]; /**< Add 1900 to value @@ -136,7 +144,8 @@ struct iso9660_ltime { typedef struct iso9660_ltime iso9660_ltime_t; -/*! ISO-9660 Primary Volume Descriptor. +/*! + \brief ISO-9660 Primary Volume Descriptor. */ struct iso9660_pvd { uint8_t type; /**< 711 encoded */ @@ -193,17 +202,19 @@ typedef struct iso9660_stat iso9660_stat_t; #define EMPTY_ARRAY_SIZE 0 #endif -/* - * XXX JS: The next structure may have an odd length depending on how - * many characters there are in the filename! - * Some compilers (e.g. on Sun3/mc68020) padd the structures to even length. - * For this reason, we cannot use sizeof (struct iso_path_table) or - * sizeof (struct iso_directory_record) to compute on disk sizes. - * Instead, we use offsetof(..., name) and add the name size. - * See mkisofs.h - */ -/*! Format of an ISO-9660 directory record */ +/*! \brief Format of an ISO-9660 directory record + + This structure may have an odd length depending on how many + characters there are in the filename! Some compilers (e.g. on + Sun3/mc68020) pad the structures to an even length. For this reason, + we cannot use sizeof (struct iso_path_table) or sizeof (struct + iso_directory_record) to compute on disk sizes. Instead, we use + offsetof(..., name) and add the name size. See mkisofs.h of the + cdrtools package. + + @see iso9660_stat +*/ struct iso9660_dir { uint8_t length; /*! 711 encoded */ uint8_t xa_length; /*! 711 encoded */ @@ -219,9 +230,14 @@ struct iso9660_dir { } GNUC_PACKED; -/*! The iso9660_stat structure is not part of any ISO 9660 spec. We - just use it for our own purposes for communicating info back that's - pulled out. +/*! \brief Unix stat-like version of iso9660_dir + + The iso9660_stat structure is not part of the ISO-9660 + specification. We use it for our to communicate information + in a C-library friendly way, e.g struct tm time structures and + a C-style filename string. + + @see iso9660_dir */ struct iso9660_stat { /* big endian!! */ enum { _STAT_FILE = 1, _STAT_DIR = 2 } type; diff --git a/include/cdio/types.h b/include/cdio/types.h index 1af9d981..7e748608 100644 --- a/include/cdio/types.h +++ b/include/cdio/types.h @@ -1,5 +1,5 @@ /* - $Id: types.h,v 1.8 2003/11/17 12:06:58 rocky Exp $ + $Id: types.h,v 1.9 2003/11/18 03:35:19 rocky Exp $ Copyright (C) 2000 Herbert Valerio Riedel Copyright (C) 2002,2003 Rocky Bernstein @@ -177,14 +177,23 @@ extern "C" { /* our own offsetof()-like macro */ #define __cd_offsetof(TYPE, MEMBER) ((size_t) &((TYPE *)0)->MEMBER) - /* In many structures on the disk a sector address is stored as a - BCD-encoded mmssff in three bytes. */ + /*! + \brief MSF (minute/second/frame) structure + + One CD-ROMs addressing scheme especially used in audio formats + (Red Book) is an address by minute, sector and frame which + BCD-encoded in three bytes. An alternative format is an lba_t. + + @see lba_t + */ PRAGMA_BEGIN_PACKED - typedef struct { + struct msf_rec { uint8_t m, s, f; - } GNUC_PACKED msf_t; + } GNUC_PACKED; PRAGMA_END_PACKED + typedef struct msf_rec msf_t; + #define msf_t_SIZEOF 3 /* type used for bit-fields in structs (1 <= bits <= 8) */ @@ -199,13 +208,16 @@ extern "C" { typedef uint8_t bitfield_t; #endif - /* The type of a Logical Block Address. */ + /*! The type of a Logical Block Address. + + @see msf_t + */ typedef uint32_t lba_t; - /* The type of an Logical Sector Number. */ + /*! The type of an Logical Sector Number. */ typedef uint32_t lsn_t; - /* The type of an track number 0..99. */ + /*! The type of an track number 0..99. */ typedef uint8_t track_t; /*! diff --git a/include/cdio/util.h b/include/cdio/util.h index 729110b1..2b753722 100644 --- a/include/cdio/util.h +++ b/include/cdio/util.h @@ -1,5 +1,5 @@ /* - $Id: util.h,v 1.1 2003/04/19 08:29:14 rocky Exp $ + $Id: util.h,v 1.2 2003/11/18 03:35:19 rocky Exp $ Copyright (C) 2000 Herbert Valerio Riedel @@ -21,6 +21,12 @@ #ifndef __CDIO_UTIL_H__ #define __CDIO_UTIL_H__ +/*! + \file util.h + \brief Miscellaneous utility functions. + + Warning: this will probably get removed/replaced by using glib.h +*/ #include #undef MAX diff --git a/src/Makefile.am b/src/Makefile.am index 298fc26f..fce1bebe 100644 --- a/src/Makefile.am +++ b/src/Makefile.am @@ -1,4 +1,4 @@ -# $Id: Makefile.am,v 1.17 2003/09/22 01:00:10 rocky Exp $ +# $Id: Makefile.am,v 1.18 2003/11/18 03:35:19 rocky Exp $ # # Copyright (C) 2003 Rocky Bernstein # @@ -21,8 +21,14 @@ #################################################### CDDB_LIBS=@CDDB_LIBS@ -if BUILD_CDINFO +if MAINTAINER_MODE +MAINTAINERCLEANFILES = $(man_MANS) man_MANS = cd-info.1 cd-read.1 +$(man_MANS): %.1: % + -$(HELP2MAN) --output=$@ ./$< +endif + +if BUILD_CDINFO cd_info_SOURCES = cd-info.c util.c util.h cd_info_LDADD = $(LIBISO9660_LIBS) $(LIBCDIO_LIBS) $(LIBPOPT_LIBS) $(CDDB_LIBS) $(VCDINFO_LIBS) @@ -43,7 +49,3 @@ man_MANS = endif INCLUDES = -I$(top_srcdir) $(LIBPOPT_CFLAGS) $(LIBCDIO_CFLAGS) $(VCDINFO_CFLAGS) -if MAINTAINER_MODE -$(man_MANS): %.1: % - -$(HELP2MAN) --output=$@ ./$< -endif