diff options
Diffstat (limited to 'static/openbsd/man4/cd.4')
| -rw-r--r-- | static/openbsd/man4/cd.4 | 347 |
1 files changed, 347 insertions, 0 deletions
diff --git a/static/openbsd/man4/cd.4 b/static/openbsd/man4/cd.4 new file mode 100644 index 00000000..73a214f5 --- /dev/null +++ b/static/openbsd/man4/cd.4 @@ -0,0 +1,347 @@ +.\" $OpenBSD: cd.4,v 1.26 2024/12/21 01:00:31 jsg Exp $ +.\" $NetBSD: cd.4,v 1.3 1996/10/20 23:15:21 explorer Exp $ +.\" +.\" Copyright (c) 1996 +.\" Julian Elischer <julian@freebsd.org>. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd $Mdocdate: December 21 2024 $ +.Dt CD 4 +.Os +.Sh NAME +.Nm cd +.Nd ATAPI and SCSI CD-ROM driver +.Sh SYNOPSIS +.Cd "cd* at scsibus?" +.Cd "#cd0 at scsibus0 target 6 lun 0" Pq fixed-configuration example +.Sh DESCRIPTION +The +.Nm +driver provides support for ATAPI and SCSI CD-ROM +.Pq Compact Disc Read-Only Memory +drives, via +.Xr scsibus 4 . +In an attempt to look like a regular disk, the +.Nm +driver synthesizes a partition table, with one partition covering the entire +CD-ROM. +It is possible to modify this partition table using +.Xr disklabel 8 , +but it will only last until the CD-ROM is unmounted. +In general the interfaces are similar to those described by +.Xr wd 4 +and +.Xr sd 4 . +.Pp +As the SCSI adapter is probed during boot, the SCSI bus is scanned for devices. +Any devices found which answer as +.Dq Read-only +and +.Dq removable +CD-ROM or WORM devices will be +.Dq attached +to the +.Nm +driver. +.Pp +The system utility +.Xr disklabel 8 +may be used to read the synthesized +disk label +structure, which will contain correct figures for the size of the +CD-ROM should that information be required. +.Sh IOCTLS +The following +.Xr ioctl 2 +calls which apply to CD-ROM drives are defined in the header files +.In sys/cdio.h +and +.In sys/dkio.h . +.Bl -tag -width Ds +.It Dv DIOCGDINFO , DIOCSDINFO Fa "struct disklabel *" +Read or write the in-core copy of the disklabel for the drive. +The disklabel is initialized with information read from the SCSI inquiry +commands, and should be the same as the information printed at boot. +This structure is defined in +.Xr disklabel 5 . +.\".It Dv CDIOCCAPABILITY +.\".Pq Li "struct ioc_capability" +.\"Retrieve information from the drive on what features it supports. The +.\"information is returned in the following structure: +.\".Bd -literal -offset indent +.\"struct ioc_capability { +.\" u_long play_function; +.\"#define CDDOPLAYTRK 0x00000001 +.\" /* Can play tracks/index */ +.\"#define CDDOPLAYMSF 0x00000002 +.\" /* Can play msf to msf */ +.\"#define CDDOPLAYBLOCKS 0x00000004 +.\" /* Can play range of blocks */ +.\"#define CDDOPAUSE 0x00000100 +.\" /* Output can be paused */ +.\"#define CDDORESUME 0x00000200 +.\" /* Output can be resumed */ +.\"#define CDDORESET 0x00000400 +.\" /* Drive can be completely reset */ +.\"#define CDDOSTART 0x00000800 +.\" /* Audio can be started */ +.\"#define CDDOSTOP 0x00001000 +.\" /* Audio can be stopped */ +.\"#define CDDOPITCH 0x00002000 +.\" /* Audio pitch can be changed */ +.\" +.\" u_long routing_function; +.\"#define CDREADVOLUME 0x00000001 +.\" /* Volume settings can be read */ +.\"#define CDSETVOLUME 0x00000002 +.\" /* Volume settings can be set */ +.\"#define CDSETMONO 0x00000100 +.\" /* Output can be set to mono */ +.\"#define CDSETSTEREO 0x00000200 +.\" /* Output can be set to stereo (def) */ +.\"#define CDSETLEFT 0x00000400 +.\" /* Output can be set to left only */ +.\"#define CDSETRIGHT 0x00000800 +.\" /* Output can be set to right only */ +.\"#define CDSETMUTE 0x00001000 +.\" /* Output can be muted */ +.\"#define CDSETPATCH 0x00008000 +.\" /* Direct routing control allowed */ +.\" +.\" u_long special_function; +.\"#define CDDOEJECT 0x00000001 +.\" /* The tray can be opened */ +.\"#define CDDOCLOSE 0x00000002 +.\" /* The tray can be closed */ +.\"#define CDDOLOCK 0x00000004 +.\" /* The tray can be locked */ +.\"#define CDREADHEADER 0x00000100 +.\" /* Can read Table of Contents */ +.\"#define CDREADENTRIES 0x00000200 +.\" /* Can read TOC Entries */ +.\"#define CDREADSUBQ 0x00000200 +.\" /* Can read Subchannel info */ +.\"#define CDREADRW 0x00000400 +.\" /* Can read subcodes R-W */ +.\"#define CDHASDEBUG 0x00004000 +.\" /* The tray has dynamic debugging */ +.\"}; +.\".Ed +.It Dv CDIOCPLAYTRACKS Fa "struct ioc_play_track *" +Start audio playback given a track address and length. +The structure is defined as follows: +.Bd -literal -offset indent +struct ioc_play_track { + u_char start_track; + u_char start_index; + u_char end_track; + u_char end_index; +}; +.Ed +.It Dv CDIOCPLAYBLOCKS Fa "struct ioc_play_blocks *" +Start audio playback given a block address and length. +The structure is defined as follows: +.Bd -literal -offset indent +struct ioc_play_blocks { + int blk; + int len; +}; +.Ed +.It Dv CDIOCPLAYMSF Fa "struct ioc_play_msf *" +Start audio playback given a +.Dq minutes-seconds-frames +address and length. +The structure is defined as follows: +.Bd -literal -offset indent +struct ioc_play_msf { + u_char start_m; + u_char start_s; + u_char start_f; + u_char end_m; + u_char end_s; + u_char end_f; +}; +.Ed +.It Dv CDIOCREADSUBCHANNEL Fa "struct ioc_read_subchannel *" +Read information from the subchannel at the location specified by this +structure: +.Bd -literal -offset indent +struct ioc_read_subchannel { + u_char address_format; +#define CD_LBA_FORMAT 1 +#define CD_MSF_FORMAT 2 + u_char data_format; +#define CD_SUBQ_DATA 0 +#define CD_CURRENT_POSITION 1 +#define CD_MEDIA_CATALOG 2 +#define CD_TRACK_INFO 3 + u_char track; + int data_len; + struct cd_sub_channel_info *data; +}; +.Ed +.It Dv CDIOREADTOCHEADER Fa "struct ioc_toc_header *" +Return summary information about the table of contents for the +mounted CD-ROM. +The information is returned into the following structure: +.Bd -literal -offset indent +struct ioc_toc_header { + u_short len; + u_char starting_track; + u_char ending_track; +}; +.Ed +.It Dv CDIOREADTOCENTRIES Fa "struct ioc_read_toc_entry *" +Return information from the table of contents entries mentioned. +The argument structure is defined as follows: +.Bd -literal -offset indent +struct ioc_read_toc_entry { + u_char address_format; + u_char starting_track; + u_short data_len; + struct cd_toc_entry *data; +}; +.Ed +.Pp +The requested data is written into an area of size +.Li data_len +and pointed to by +.Li data . +.It Dv CDIOCSETPATCH Fa "struct ioc_patch *" +Attach various audio channels to various output channels. +The argument structure is defined thusly: +.Bd -literal -offset indent +struct ioc_patch { + u_char patch[4]; + /* one for each channel */ +}; +.Ed +.It Dv CDIOCGETVOL , CDIOCSETVOL Fa "struct ioc_vol *" +Get (set) information about the volume settings of the output channels. +The argument structure is as follows: +.Bd -literal -offset indent +struct ioc_vol { + u_char vol[4]; + /* one for each channel */ +}; +.Ed +.It Dv CDIOCSETMONO +Patch all output channels to all source channels. +.It Dv CDIOCSETSTEREO +Patch left source channel to the left output channel and the right +source channel to the right output channel. +.It Dv CDIOCSETMUTE +Mute output without changing the volume settings. +.It Dv CDIOCSETLEFT , CDIOCSETRIGHT +Attach both output channels to the left (right) source channel. +.It Dv CDIOCSETDEBUG , CDIOCCLRDEBUG +Turn on (off) debugging for the appropriate device. +.It Dv CDIOCPAUSE , CDIOCRESUME +Pause (resume) audio play, without resetting the location of the read-head. +.It Dv CDIOCRESET +Reset the drive. +.It Dv CDIOCSTART , CDIOCSTOP +Tell the drive to spin-up (-down) the CD-ROM. +.It Dv CDIOCALLOW , CDIOCPREVENT +Tell the drive to allow (prevent) manual ejection of the CD-ROM disc. +Not all drives support this feature. +.It Dv CDIOCEJECT +Eject the CD-ROM. +.\".It Dv CDIOCCLOSE +.\"Tell the drive to close its door and load the media. Not all drives +.\"support this feature. +.\" +.\".It Dv CDIOCPITCH +.\".Pq Li "struct ioc_pitch" +.\"For drives that support it, this command instructs the drive to play +.\"the audio at a faster or slower rate than normal. Values of +.\".Li speed +.\"between -32767 and -1 result in slower playback; a zero value +.\"indicates normal speed; and values from 1 to 32767 give faster +.\"playback. Drives with less than 16 bits of resolution will silently +.\"ignore less-significant bits. The structure is defined thusly: +.\".Bd -literal -offset indent +.\"struct ioc_pitch { +.\" short speed; +.\"}; +.\".Ed +.El +.Pp +In addition the general +.Xr scsi 4 +ioctls may be used with the +.Nm +driver, if used against the `whole disk' partition (i.e., +.Pa /dev/rcd0c ) . +.Sh NOTES +When a CD-ROM is changed in a drive controlled by the +.Nm +driver, then the act of changing the media will invalidate the +disklabel and information held within the kernel. +To stop corruption, all accesses to the device will be discarded until +there are no more open file descriptors referencing the device. +During this period, all new open attempts will be rejected. +When no more open file descriptors reference the device, the first next open +will load a new set of parameters (including disklabel) for the drive. +.Pp +The audio code in the +.Nm +driver only supports SCSI-2 standard audio commands. +Because many CD-ROM manufacturers have not followed the standard, there are +many CD-ROM drives for which audio will not work. +Some work is planned to support some of the more common +.Dq broken +CD-ROM drives; however, this is not yet under way. +.Sh FILES +.Bl -tag -width /dev/rcd[0-9][a-p] -compact +.It Pa /dev/cd[0-9][a-p] +block mode CD-ROM devices +.It Pa /dev/rcd[0-9][a-p] +raw mode CD-ROM devices +.El +.Sh DIAGNOSTICS +None. +.Sh SEE ALSO +.Xr cdio 1 , +.Xr eject 1 , +.Xr ioctl 2 , +.Xr intro 4 , +.Xr scsi 4 , +.Xr scsibus 4 , +.Xr sd 4 , +.Xr wd 4 , +.Xr disklabel 5 , +.Xr disklabel 8 +.Sh HISTORY +.An Julian Elischer +wrote +.Nm +for Mach 2.5 and ported it to 386BSD. +.Sh BUGS +The names of the structures used for the third argument to +.Fn ioctl +were poorly chosen, and a number of spelling errors have survived in +the names of the +.Fn ioctl +commands. |