diff options
| author | Jerry Jelinek <jerry.jelinek@joyent.com> | 2019-10-01 11:42:20 +0000 |
|---|---|---|
| committer | Jerry Jelinek <jerry.jelinek@joyent.com> | 2019-10-01 11:42:20 +0000 |
| commit | 2ae9c4827fce220d14433c796b18141d48a597d9 (patch) | |
| tree | ac7a6509389e91c46887f396b23b3cbe0be700ed | |
| parent | d71e63f2240a31f0a5769f8a5e2307c386fd41ad (diff) | |
| parent | 647709cb33adbc9ec046fb9ad41818ffc50b0bf3 (diff) | |
| download | illumos-joyent-2ae9c4827fce220d14433c796b18141d48a597d9.tar.gz | |
[illumos-gate merge]
commit 647709cb33adbc9ec046fb9ad41818ffc50b0bf3
11735 cardbus: cast between incompatible function types
commit 7a2e057ded7c57de0de12bba546e48c437d4aba0
11734 pcic: cast between incompatible function types
commit 16d00323713cfa922181df7d69d973398dea15ff
11733 acpica: cast between incompatible function types
commit 660213e2089ab8409d54154d0a2987504a24fb23
11732 portfs: cast between incompatible function types
commit 8ab009369fb9f9b1e690d195ddcfbd8165a53f34
11731 kaio: cast between incompatible function types
commit 9dd95169794650baa0f951e24046175899beff70
11730 shmsys: cast between incompatible function types
commit d0562c105d77a4d4da85007111e260da7ea2616f
11754 ZoL trim port used wrong offset for sd unmap
commit aef5ddef46ea0369baf07aba4d38ed9b2cd8cd96
11727 usb_ah: cast between incompatible function types
commit fe9b11956841aaade2b3d01981d7e372b9b613a5
11728 exacctsys: cast between incompatible function types
commit 457cb919baede78b33c994ab8c7797c848513997
11726 ttcompat: cast between incompatible function types
commit c6026c814721e22d6b8791b5bdfeeecb85ece59c
11725 tirdwr: cast between incompatible function types
commit c4d76aa4b703811c0527424e3c63151eb77b9972
11724 spppcomp: cast between incompatible function types
commit e81f5104293f278cbf9b239692af80ee10885830
11723 cryptmod: cast between incompatible function types
commit bbe1f46d73a73e54a242bb59596e2daf4e619fe3
11722 usbwcm: cast between incompatible function types
commit 700daa96bb3e99515f0abdc42f1904e78bc282da
11658 Some capabilities are invalid for SMB 2.002
commit 4d633836fc25186ed4c118b2072d2b88cf87a700
11720 rpcmod: cast between incompatible function types
commit 6caf82fa836a9721560a96669ccdd90b3fa7b644
11719 timod: cast between incompatible function types
commit e10751a53e4fcc2850e57448ad13dc3caf40595e
11755 loader: command_lsmod does show garbage on screen
commit eb62f060787d63335f2b0777ff86c16204bca93a
10517 Convert dkio(7I) to mandoc
10518 Convert fbio(7I) to mandoc
10519 Convert fdio(7I) to mandoc
10520 Convert hdio(7I) to mandoc
10521 Convert iec61883(7I) to mandoc
10522 Convert ipnat(7I) to mandoc
10527 Convert mhd(7I) to mandoc
10528 Convert mixer(7I) to mandoc
10529 Convert mtio(7I) to mandoc
10530 Convert prnio(7I) to mandoc
10531 Convert quotactl(7I) to mandoc
10532 Convert sesio(7I) to mandoc
10533 Convert sockio(7I) to mandoc
10560 Convert termio(7I) to mandoc
10561 Convert termiox(7I) to mandoc
10562 Convert visual_io(7I) to mandoc
10563 Convert vt(7I) to mandoc
10564 Convert uscsi(7I) to mandoc
10596 Convert streamio(7I) to mandoc
40 files changed, 10004 insertions, 10436 deletions
diff --git a/usr/src/boot/Makefile.version b/usr/src/boot/Makefile.version index faf491c1af..67889d27d9 100644 --- a/usr/src/boot/Makefile.version +++ b/usr/src/boot/Makefile.version @@ -33,4 +33,4 @@ LOADER_VERSION = 1.1 # Use date like formatting here, YYYY.MM.DD.XX, without leading zeroes. # The version is processed from left to right, the version number can only # be increased. -BOOT_VERSION = $(LOADER_VERSION)-2019.09.20.1 +BOOT_VERSION = $(LOADER_VERSION)-2019.09.27.1 diff --git a/usr/src/boot/sys/boot/common/module.c b/usr/src/boot/sys/boot/common/module.c index ca4090fc24..643625c347 100644 --- a/usr/src/boot/sys/boot/common/module.c +++ b/usr/src/boot/sys/boot/common/module.c @@ -263,7 +263,7 @@ command_lsmod(int argc, char *argv[]) break; if (strcmp(fp->f_type, "hash") == 0) { pager_output(" contents: "); - strncpy(lbuf, PTOV(fp->f_addr), fp->f_size); + strlcpy(lbuf, PTOV(fp->f_addr), sizeof (lbuf)); if (pager_output(lbuf)) break; } diff --git a/usr/src/man/man7i/dkio.7i b/usr/src/man/man7i/dkio.7i index 7a23ff61c8..4b8c26a592 100644 --- a/usr/src/man/man7i/dkio.7i +++ b/usr/src/man/man7i/dkio.7i @@ -17,52 +17,46 @@ .\" .\" Copyright (c) 2009 Sun Microsystems, Inc. All Rights Reserved. .\" Copyright 2016 Nexenta Systems, Inc. +.\" Copyright (c) 2017, Joyent, Inc. .\" -.TH DKIO 7I "Oct 8, 2016" -.SH NAME -dkio \- disk control operations -.SH SYNOPSIS -.LP -.nf -#include <sys/dkio.h> -#include <sys/vtoc.h> -.fi - -.LP -.nf -\fB\fR -.fi - -.SH DESCRIPTION -.LP -Disk drivers support a set of \fBioctl\fR(2) requests for disk controller, -geometry, and partition information. Basic to these \fBioctl()\fR requests are -the definitions in \fB<sys/dkio.h>\fR\&. -.SH IOCTLS -.LP -The following \fBioctl()\fR requests set and/or retrieve the current disk +.Dd October 23, 2017 +.Dt DKIO 7I +.Os +.Sh NAME +.Nm dkio +.Nd disk control operations +.Sh SYNOPSIS +.In sys/dkio.h +.In sys/vtoc.h +.Sh DESCRIPTION +Disk drivers support a set of +.Xr ioctl 2 +requests for disk controller, geometry, and partition information. +Basic to these +.Xr ioctl 2 +requests are the definitions in +.In sys/dkio.h . +.Sh IOCTLS +The following +.Xr ioctl 2 +requests set and/or retrieve the current disk controller, partitions, or geometry information on all architectures: -.sp -.ne 2 -.na -\fB\fBDKIOCINFO\fR\fR -.ad -.sp .6 -.RS 4n -The argument is a pointer to a \fBdk_cinfo\fR structure (described below). This -structure tells the controller-type and attributes regarding bad-block +.Bl -tag -width 1n +.It Dv DKIOCINFO +.Pp +The argument is a pointer to a +.Vt dk_cinfo +structure (described below). +This structure tells the controller-type and attributes regarding bad-block processing done on the controller. -.RE - -.sp -.in +2 -.nf +.Bd -literal -offset 2n /* * Structures and definitions for disk I/O control commands */ #define DK_DEVLEN 16 /* device name max length, */ /* including unit # and NULL */ - /* Used for controller info */ + +/* Used for controller info */ struct dk_cinfo { char dki_cname[DK_DEVLEN]; /* controller name */ /* (no unit #) */ @@ -79,12 +73,11 @@ struct dk_cinfo { ushort_t dki_partition; /* partition number */ ushort_t dki_maxtransfer; /* maximum transfer size */ /* in DEV_BSIZE */ - }; + /* * Controller types */ - #define DKC_UNKNOWN 0 #define DKC_CDROM 1 /* CD-ROM, SCSI or other */ #define DKC_WDC2880 2 @@ -114,157 +107,135 @@ struct dk_cinfo { /* * Flags */ - #define DKI_BAD144 0x01 /* use DEC std 144 */ /* bad sector fwding */ #define DKI_MAPTRK 0x02 /* controller does */ /* track mapping */ #define DKI_FMTTRK 0x04 /* formats only full - /* track at a time*/ + /* track at a time */ #define DKI_FMTVOL 0x08 /* formats only full */ - /* volume at a time*/ + /* volume at a time */ #define DKI_FMTCYL 0x10 /* formats only full */ - /* cylinders at a time*/ - #define DKI_HEXUNIT 0x20 /* unit number printed as */ - /* 3 hexdigits */ + /* cylinders at a time */ + #define DKI_HEXUNIT 0x20 /* unit number printed */ + /* as 3 hexdigits */ #define DKI_PCMCIA_PFD 0x40 /* PCMCIA pseudo-floppy */ /* memory card */ -.fi -.in -2 - -.sp -.ne 2 -.na -\fB\fBDKIOCGAPART\fR\fR -.ad -.sp .6 -.RS 4n -The argument is a pointer to a \fBdk_allmap\fR structure (described below). -This \fBioctl()\fR gets the controller's notion of the current partition table +.Ed +.It Dv DKIOCGAPART +.Pp +The argument is a pointer to a +.Vt dk_allmap +structure (described below). +This +.Xr ioctl 2 +gets the controller's notion of the current partition table for disk drive. -.RE - -.sp -.ne 2 -.na -\fB\fBDKIOCSAPART\fR\fR -.ad -.sp .6 -.RS 4n -The argument is a pointer to a \fBdk_allmap\fR structure (described below). -This \fBioctl()\fR sets the controller's notion of the partition table without +.It Dv DKIOCSAPART +.Pp +The argument is a pointer to a +.Vt dk_allmap +structure (described below). +This +.Xr ioctl 2 +sets the controller's notion of the partition table without changing the disk itself. -.RE - -.sp -.in +2 -.nf +.Bd -literal -offset 2n /* * Partition map (part of dk_label) - */ struct dk_map { + */ +struct dk_map { daddr_t dkl_cylno; /* starting cylinder */ daddr_t dkl_nblk; /* number of blocks */ - }; +}; + /* * Used for all partitions */ struct dk_allmap { struct dk_map dka_map[NDKMAP]; }; -.fi -.in -2 - -.sp -.ne 2 -.na -\fB\fBDKIOCGGEOM\fR\fR -.ad -.RS 14n -The argument is a pointer to a \fBdk_geom\fR structure (described below). This -\fBioctl()\fR gets the controller's notion of the current geometry of the disk -drive. -.RE - -.sp -.ne 2 -.na -\fB\fBDKIOCSGEOM\fR\fR -.ad -.RS 14n -The argument is a pointer to a \fBdk_geom\fR structure (described below). This -\fBioctl()\fR sets the controller's notion of the geometry without changing the -disk itself. -.RE - -.sp -.ne 2 -.na -\fB\fBDKIOCGVTOC\fR\fR -.ad -.RS 14n -The argument is a pointer to a \fBvtoc\fR structure (described below). This -\fBioctl()\fR returns the device's current volume table of contents (VTOC.) For -disks larger than 1TB, DKIOCGEXTVTOC must be used instead. -.RE - -.sp -.ne 2 -.na -\fB\fBDKIOCSVTOC\fR\fR -.ad -.RS 14n -The argument is a pointer to a \fBvtoc\fR structure (described below). This -\fBioctl()\fR changes the VTOC associated with the device. For disks larger -than 1TB, DKIOCSEXTVTOC must be used instead. -.RE - -.sp -.in +2 -.nf +.Ed +.It Dv DKIOCGGEOM +.Pp +The argument is a pointer to a +.Vt dk_geom +structure (described below). +This +.Xr ioctl 2 +gets the controller's notion of the current geometry of the disk drive. +.It Dv DKIOCSGEOM +.Pp +The argument is a pointer to a +.Vt dk_geom +structure (described below). +This +.Xr ioctl 2 +sets the controller's notion of the geometry without changing the disk itself. +.It Dv DKIOCGVTOC +.Pp +The argument is a pointer to a +.Vt vtoc +structure (described below). +This +.Xr ioctl 2 +returns the device's current volume table of contents (VTOC). +For disks larger than 1TB, +.Dv DKIOCGEXTVTOC +must be used instead. +.It Dv DKIOCSVTOC +.Pp +The argument is a pointer to a +.Vt vtoc +structure (described below). +This +.Xr ioctl 2 +changes the VTOC associated with the device. +For disks larger than 1TB, +.Dv DKIOCSEXTVTOC +must be used instead. +.Bd -literal -offset 2n struct partition { -ushort_t p_tag; /* ID tag of partition */ -ushort_t p_flag; /* permission flags */ -daddr_t p_start; /* start sector of partition */ -long p_size; /* # of blocks in partition */ + ushort_t p_tag; /* ID tag of partition */ + ushort_t p_flag; /* permission flags */ + daddr_t p_start; /* start sector of partition */ + long p_size; /* # of blocks in partition */ }; -.fi -.in -2 - -.sp -.LP -If \fBDKIOCSVTOC\fR is used with a floppy diskette, the \fBp_start\fR field -must be the first sector of a cylinder. To compute the number of sectors per +.Ed +.Pp +If +.Dv DKIOCSVTOC +is used with a floppy diskette, the +.Fa p_start +field must be the first sector of a cylinder. +To compute the number of sectors per cylinder, multiply the number of heads by the number of sectors per track. -.sp -.in +2 -.nf +.Bd -literal -offset 2n struct vtoc { -unsigned long v_bootinfo[3]; /* info needed by mboot - /* (unsupported)*/ -unsigned long v_sanity; /* to verify vtoc */ - /* sanity */ -unsigned long v_version; /* layout version */ -char v_volume[LEN_DKL_VVOL]; /* volume name */ -ushort_t v_sectorsz; /* sector size in bytes*/ -ushort_t v_nparts; /* number of partitions*/ -unsigned long v_reserved[10]; /* free space */ -struct partition v_part[V_NUMPAR]; /* partition headers */ -time_t timestamp[V_NUMPAR]; /* partition timestamp */ - /* (unsupported) */ -char v_asciilabel[LEN_DKL_ASCII]; /* compatibility */ + unsigned long v_bootinfo[3]; /* info needed by mboot */ + /* (unsupported) */ + unsigned long v_sanity; /* to verify vtoc */ + /* sanity */ + unsigned long v_version; /* layout version */ + char v_volume[LEN_DKL_VVOL]; /* volume name */ + ushort_t v_sectorsz; /* sector size in bytes */ + ushort_t v_nparts; /* number of partitions */ + unsigned long v_reserved[10]; /* free space */ + struct partition v_part[V_NUMPAR]; /* partition headers */ + time_t timestamp[V_NUMPAR]; /* partition timestamp */ + /* (unsupported) */ + char v_asciilabel[LEN_DKL_ASCII]; /* compatibility */ }; /* -* Partition permission flags -*/ - + * Partition permission flags + */ #define V_UNMNT 0x01 /* Unmountable partition */ #define V_RONLY 0x10 /* Read only */ /* -* Partition identification tags -*/ - + * Partition identification tags + */ #define V_UNASSIGNED 0x00 /* unassigned partition */ #define V_BOOT 0x01 /* Boot partition */ #define V_ROOT 0x02 /* Root filesystem */ @@ -274,213 +245,167 @@ char v_asciilabel[LEN_DKL_ASCII]; /* compatibility */ #define V_VAR 0x07 /* Var partition */ #define V_HOME 0x08 /* Home partition */ #define V_ALTSCTR 0x09 /* Alternate sector partition */ -.fi -.in -2 - -.sp -.ne 2 -.na -\fB\fBDKIOCGEXTVTOC\fR\fR -.ad -.sp .6 -.RS 4n -The argument is a pointer to an \fBextvtoc\fR structure (described below). This -ioctl returns the device's current volume table of contents (VTOC). VTOC is -extended to support a disk up to 2TB in size. For disks larger than 1TB this -ioctl must be used instead of \fBDKIOCGVTOC\fR. -.RE - -.sp -.ne 2 -.na -\fB\fBDKIOCSEXTVTOC\fR\fR -.ad -.sp .6 -.RS 4n -The argument is a pointer to an \fBextvtoc\fR structure (described below). This -ioctl changes the VTOC associated with the device. VTOC is extended to support -a disk up to 2TB in size. For disks larger than 1TB this ioctl must be used -instead of \fBDKIOCSVTOC\fR. -.sp -.in +2 -.nf +.Ed +.It Dv DKIOCGEXTVTOC +.Pp +The argument is a pointer to an +.Vt extvtoc +structure (described below). +This ioctl returns the device's current volume table of contents (VTOC). +VTOC is extended to support a disk up to 2TB in size. +For disks larger than 1TB this ioctl must be used instead of +.Dv DKIOCGVTOC . +.It Dv DKIOCSEXTVTOC +.Pp +The argument is a pointer to an +.Vt extvtoc +structure (described below). +This ioctl changes the VTOC associated with the device. +VTOC is extended to support a disk up to 2TB in size. +For disks larger than 1TB this ioctl must be used instead of +.Vt DKIOCSVTOC . +.Bd -literal -offset 2n struct extpartition { -ushort_t p_tag; /* ID tag of partition */ -ushort_t p_flag; /* permission flags */ -ushort_t p_pad[2]; /* reserved */ -diskaddr_t p_start; /* start sector no of partition */ -diskaddr_t p_size; /* # of blocks in partition */ + ushort_t p_tag; /* ID tag of partition */ + ushort_t p_flag; /* permission flags */ + ushort_t p_pad[2]; /* reserved */ + diskaddr_t p_start; /* start sector no of partition */ + diskaddr_t p_size; /* # of blocks in partition */ }; - struct extvtoc { -uint64_t v_bootinfo[3]; /* info needed by mboot (unsupported) */ -uint64_t v_sanity; /* to verify vtoc sanity */ -uint64_t v_version; /* layout version */ -char v_volume[LEN_DKL_VVOL]; /* volume name */ -ushort_t v_sectorsz; /* sector size in bytes */ -ushort_t v_nparts; /* number of partitions */ -ushort_t pad[2]; -uint64_t v_reserved[10]; -struct extpartition v_part[V_NUMPAR]; /* partition headers */ -uint64_t timestamp[V_NUMPAR]; /* partition timestamp (unsupported)*/ -char v_asciilabel[LEN_DKL_ASCII]; /* for compatibility */ + uint64_t v_bootinfo[3]; /* info needed by mboot (unsupported) */ + uint64_t v_sanity; /* to verify vtoc sanity */ + uint64_t v_version; /* layout version */ + char v_volume[LEN_DKL_VVOL]; /* volume name */ + ushort_t v_sectorsz; /* sector size in bytes */ + ushort_t v_nparts; /* number of partitions */ + ushort_t pad[2]; + uint64_t v_reserved[10]; + struct extpartition v_part[V_NUMPAR]; /* partition headers */ + uint64_t timestamp[V_NUMPAR]; /* partition timestamp */ + /* (unsupported) */ + char v_asciilabel[LEN_DKL_ASCII]; /* for compatibility */ }; - +.Ed +.Pp Partition permissions flags and identification tags are defined the same as vtoc structure. -.fi -.in -2 - -.RE - -.sp -.ne 2 -.na -\fB\fBDKIOCEJECT\fR\fR -.ad -.sp .6 -.RS 4n -If the drive supports removable media, this \fBioctl()\fR requests the disk -drive to eject its disk. -.RE - -.sp -.ne 2 -.na -\fB\fBDKIOCREMOVABLE\fR\fR -.ad -.sp .6 -.RS 4n -The argument to this \fBioctl()\fR is an integer. After successful completion, -this \fBioctl()\fR sets that integer to a non-zero value if the drive in -question has removable media. If the media is not removable, the integer is set -to \fB0\fR. -.RE - -.sp -.ne 2 -.na -\fB\fBDKIOCHOTPLUGGABLE\fR\fR -.ad -.sp .6 -.RS 4n -The argument to this \fBioctl()\fR is an integer. After successful completion, -this \fBioctl()\fR sets that integer to a non-zero value if the drive in -question is hotpluggable. If the media is not hotpluggable, the integer is set -to 0. -.RE - -.sp -.ne 2 -.na -\fB\fBDKIOCSTATE\fR\fR -.ad -.sp .6 -.RS 4n -This \fBioctl()\fR blocks until the state of the drive, inserted or ejected, is -changed. The argument is a pointer to a \fBdkio_state\fR, enum, whose possible -enumerations are listed below. The initial value should be either the last -reported state of the drive, or \fBDKIO_NONE\fR. Upon return, the enum pointed +.It Dv DKIOCEJECT +.Pp +If the drive supports removable media, this +.Xr ioctl 2 +requests the disk drive to eject its disk. +.It Dv DKIOCREMOVABLE +.Pp +The argument to this +.Xr ioctl 2 +is an integer. +After successful completion, this +.Xr ioctl 2 +sets that integer to a non-zero value if the drive in +question has removable media. +If the media is not removable, the integer is set to +.Sy 0 . +.It Dv DKIOCHOTPLUGGABLE +.Pp +The argument to this +.Xr ioctl 2 +is an integer. +After successful completion, this +.Xr ioctl 2 +sets that integer to a non-zero value if the drive in question is hotpluggable. +If the media is not hotpluggable, the integer is set to 0. +.It Dv DKIOCSTATE +.Pp +This +.Xr ioctl 2 +blocks until the state of the drive, inserted or ejected, is changed. +The argument is a pointer to a +.Vt dkio_state , +enum, whose possible enumerations are listed below. +The initial value should be either the last +reported state of the drive, or +.Dv DKIO_NONE . +Upon return, the enum pointed to by the argument is updated with the current state of the drive. -.sp -.in +2 -.nf +.Bd -literal -offset 2n enum dkio_state { -DKIO_NONE, /* Return disk's current state */ -DKIO_EJECTED, /* Disk state is 'ejected' */ -DKIO_INSERTED /* Disk state is 'inserted' */ + DKIO_NONE, /* Return disk's current state */ + DKIO_EJECTED, /* Disk state is 'ejected' */ + DKIO_INSERTED /* Disk state is 'inserted' */ }; -.fi -.in -2 - -.RE - -.sp -.ne 2 -.na -\fB\fBDKIOCLOCK\fR\fR -.ad -.sp .6 -.RS 4n -For devices with removable media, this \fBioctl()\fR requests the disk drive to -lock the door. -.RE - -.sp -.ne 2 -.na -\fB\fBDKIOCUNLOCK\fR\fR -.ad -.sp .6 -.RS 4n -For devices with removable media, this \fBioctl()\fR requests the disk drive to -unlock the door. -.RE - -.sp -.ne 2 -.na -\fB\fBDKIOCGMEDIAINFO\fR\fR -.ad -.sp .6 -.RS 4n -The argument to this \fBioctl()\fR is a pointer to a \fBdk_minfo\fR structure. +.Ed +.It Dv DKIOCLOCK +.Pp +For devices with removable media, this +.Xr ioctl 2 +requests the disk drive to lock the door. +.It Dv DKIOCUNLOCK +.Pp +For devices with removable media, this +.Xr ioctl 2 +requests the disk drive to unlock the door. +.It Dv DKIOCGMEDIAINFO +.Pp +The argument to this +.Xr ioctl 2 +is a pointer to a +.Vt dk_minfo +structure. The structure indicates the type of media or the command set profile used by -the drive to operate on the media. The \fBdk_minfo\fR structure also indicates -the logical media block size the drive uses as the basic unit block size of -operation and the raw formatted capacity of the media in number of logical -blocks. -.RE - -.sp -.ne 2 -.na -\fB\fBDKIOCGMEDIAINFOEXT\fR\fR -.ad -.sp .6 -.RS 4n -The argument to this \fBioctl()\fR is a pointer to a \fBdk_minfo_ext\fR -structure. The structure indicates the type of media or the command set profile -used by the drive to operate on the media. The \fBdk_minfo_ext\fR structure +the drive to operate on the media. +The +.Vt dk_minfo +structure also indicates the logical media block size the drive uses as the +basic unit block size of operation and the raw formatted capacity of the media +in number of logical blocks. +.It Dv DKIOCGMEDIAINFOEXT +.Pp +The argument to this +.Xr ioctl 2 +is a pointer to a +.Vt dk_minfo_ext +structure. +The structure indicates the type of media or the command set profile +used by the drive to operate on the media. +The +.Vt dk_minfo_ext +structure also indicates the logical media block size the drive uses as the basic unit block size of operation, the raw formatted capacity of the media in number of logical blocks and the physical block size of the media. -.RE - -.sp -.in +2 -.nf +.Bd -literal -offset 2n /* -* Used for media info or profile info -*/ + * Used for media info or profile info + */ struct dk_minfo { -uint_t dki_media_type; /* Media type or profile info */ -uint_t dki_lbsize; /* Logical blocksize of media */ -diskaddr_t dki_capacity; /* Capacity as # of dki_lbsize blks */ + uint_t dki_media_type; /* Media type or profile info */ + uint_t dki_lbsize; /* Logical blocksize of media */ + diskaddr_t dki_capacity; /* Capacity as # of dki_lbsize blks */ }; /* -* Used for media info or profile info and physical blocksize -*/ + * Used for media info or profile info and physical blocksize + */ struct dk_minfo_ext { -uint_t dki_media_type; /* Media type or profile info */ -uint_t dki_lbsize; /* Logical blocksize of media */ -diskaddr_t dki_capacity; /* Capacity as # of dki_lbsize blks */ -uint_t dki_pbsize; /* Physical blocksize of media */ + uint_t dki_media_type; /* Media type or profile info */ + uint_t dki_lbsize; /* Logical blocksize of media */ + diskaddr_t dki_capacity; /* Capacity as # of dki_lbsize blks */ + uint_t dki_pbsize; /* Physical blocksize of media */ }; /* -* Media types or profiles known -*/ + * Media types or profiles known + */ #define DK_UNKNOWN 0x00 /* Media inserted - type unknown */ /* -* SFF 8090 Specification Version 3, media types 0x01 - 0xfffe are -* retained to maintain compatibility with SFF8090. The following -* define the optical media type. -*/ + * SFF 8090 Specification Version 3, media types 0x01 - 0xfffe are + * retained to maintain compatibility with SFF8090. The following + * define the optical media type. + */ #define DK_MO_ERASABLE 0x03 /* MO Erasable */ #define DK_MO_WRITEONCE 0x04 /* MO Write once */ #define DK_AS_MO 0x05 /* AS MO */ @@ -492,256 +417,264 @@ uint_t dki_pbsize; /* Physical blocksize of media */ #define DK_DVDRAM 0x12 /* DVD_RAM or DVD-RW */ /* -* Media types for other rewritable magnetic media -*/ + * Media types for other rewritable magnetic media + */ #define DK_FIXED_DISK 0x10001 /* Fixed disk SCSI or otherwise */ #define DK_FLOPPY 0x10002 /* Floppy media */ #define DK_ZIP 0x10003 /* IOMEGA ZIP media */ #define DK_JAZ 0x10004 /* IOMEGA JAZ media */ -.fi -.in -2 - -.sp -.LP +.Ed +.Pp If the media exists and the host can obtain a current profile list, the command -succeeds and returns the \fBdk_minfo\fR structure with data representing that -media. -.sp -.LP +succeeds and returns the +.Vt dk_minfo +structure with data representing that media. +.Pp If there is no media in the drive, the command fails and the host returns an -\fBENXIO\fR error, indicating that it cannot gather the information requested. -.sp -.LP +.Er ENXIO +error, indicating that it cannot gather the information requested. +.Pp If the profile list is not available, the host attempts to identify the media-type based on the available information. -.sp -.LP +.Pp If identification is not possible, the host returns media type -\fBDK_UNKNOWN\fR. See \fINOTES\fR for blocksize usage and capacity information. -.sp -.ne 2 -.na -\fB\fBDKIOCSMBOOT\fR\fR -.ad -.sp .6 -.RS 4n -The argument is a pointer to struct \fImboot\fR. -.sp -Copies the \fImboot\fR information supplied in the argument to the absolute -sector 0 of the device. Prior to copying the information, this \fBioctl()\fR -performs the following checks on the \fImboot\fR data: -.RS +4 -.TP -.ie t \(bu -.el o +.Dv DK_UNKNOWN . +See +.Sx NOTES +for blocksize usage and capacity information. +.It Dv DKIOCSMBOOT +.Pp +The argument is a pointer to struct +.Vt mboot . +.Pp +Copies the +.Vt mboot +information supplied in the argument to the absolute sector 0 of the device. +Prior to copying the information, this +.Xr ioctl 2 +performs the following checks on the +.Vt mboot +data: +.Bl -bullet -offset indent +.It Ensures that the signature field is set to 0xAA55. -.RE -.RS +4 -.TP -.ie t \(bu -.el o +.It Ensures that partitions do not overlap. -.RE -.RS +4 -.TP -.ie t \(bu -.el o +.It On SPARC platforms, determines if the device is a removable media. -.RE -If the above verification fails, \fBerrno\fR is set to \fBEINVAL\fR and the -\fBioctl()\fR command fails. -.sp -x86 Platforms \(em Upon successful write of \fImboot\fR, the partition map -structure maintained in the driver is updated. If the new Solaris partition is +.El +.Pp +If the above verification fails, +.Va errno +is set to +.Er EINVAL +and the +.Xr ioctl 2 +command fails. +.Pp +x86 Platforms \(em Upon successful write of +.Vt mboot , +the partition map structure maintained in the driver is updated. +If the new Solaris partition is different from the previous one, the internal VTOC table maintained in the driver is set as follows: -.sp -If _SUNOS_VTOC_8 is defined: -.sp -Partition: 0. Start: 0. Capacity = Capacity of device. -.sp -Partition: 2. Start: 0. Capacity = Capacity of device. -.sp -If _SUNOS_VTOC_16 is defined: -.sp -Partition: 2. Start: 0. Size = Size specified in mboot - 2 cylinders. -.sp -Partition: 8. Start: 0. Size = Sectors/cylinder. -.sp -Partition: 9. Start: Sectors/cylinder. Size = 2 * sectors/cylinder -.sp +.Pp +If +.Dv _SUNOS_VTOC_8 +is defined: +.Bd -unfilled -offset 4n +Partition: 0 Start: 0 Capacity = Capacity of device. +Partition: 2 Start: 0 Capacity = Capacity of device. +.Ed +.Pp +If +.Dv _SUNOS_VTOC_16 +is defined: +.Bd -unfilled -offset 4n +Partition: 2 Start: 0 Size = Size specified in mboot - 2 cylinders. +Partition: 8 Start: 0 Size = Sectors/cylinder. +Partition: 9 Start: Sectors/cylinder Size = 2 * sectors/cylinder +.Ed +.Pp To determine if the Solaris partition has changed: -.sp +.Bd -offset 4n -ragged If either offset or the size of the Solaris partition is different from the -previous one then it shall be deemed to have changed. In all other cases, the +previous one then it shall be deemed to have changed. +In all other cases, the internal VTOC info remains as before. -.sp -SPARC Platforms \(em The VTOC label and \fImboot\fR both occupy the same -location, namely sector 0. As a result, following the successful write of -\fImboot\fR info, the internal VTOC table maintained in the driver is set as -follows: -.sp -Partition: 0. Start: 0. Size = Capacity of device. -.sp -Partition: 2. Start: 0. Size = Capacity of device. -.sp -See the NOTES section for usage of DKIOCSMBOOT when modifying Solaris -partitions. -.RE - -.sp -.ne 2 -.na -\fB\fBDKIOCGETVOLCAP\fR\fR -.ad -.sp .6 -.RS 4n +.Ed +.Pp +SPARC Platforms \(em The VTOC label and +.Vt mboot +both occupy the same location, namely sector 0. +As a result, following the successful write of +.Vt mboot +info, the internal VTOC table maintained in the driver is set as follows: +.Bd -unfilled -offset 4n +Partition: 0 Start: 0 Size = Capacity of device. +Partition: 2 Start: 0 Size = Capacity of device. +.Ed +.Pp +See the +.Sx NOTES +section for usage of +.Dv DKIOCSMBOOT +when modifying Solaris partitions. +.It Dv DKIOCGETVOLCAP +.Pp This ioctl provides information and status of available capabilities. -.sp -\fIvc_info\fR is a bitmap and the valid flag values are: -.sp -.in +2 -.nf -DKV_ABR_CAP - Capable of application-based recovery -DKV_DMR_CAP - Ability to read specific copy of data when - multiple copies exist. For example, in a two - way mirror, this ioctl is used to read each - side of the mirror. -.fi -.in -2 - -\fIvc_set\fR is a bitmap and the valid flag values are: -.sp -.in +2 -.nf -DKV_ABR_CAP - This flag is set if ABR has been set on a device - that supports ABR functionality. -DKV_DMR_CAP - Directed read has been enabled. -.fi -.in -2 - +.Fa vc_info +is a bitmap and the valid flag values are: +.Pp +.Bl -tag -width DKV_ABR_CAP -compact -offset 2n +.It Dv DKV_ABR_CAP +Capable of application-based recovery +.It Dv DKV_DMR_CAP +Ability to read specific copy of data when multiple copies exist. +For example, in a two way mirror, this ioctl is used to read each +side of the mirror. +.El +.Pp +.Fa vc_set +is a bitmap and the valid flag values are: +.Pp +.Bl -tag -width DKV_ABR_CAP -compact -offset 2n +.It Dv DKV_ABR_CAP +This flag is set if ABR has been set on a device that supports ABR functionality. +.It Dv DKV_DMR_CAP +Directed read has been enabled. +.El +.Pp These capabilities are not required to be persistent across a system reboot and -their persistence depends upon the implementation. For example, if the ABR +their persistence depends upon the implementation. +For example, if the ABR capability for a DRL mirror simply clears the dirty-region list and subsequently stops updating this list, there is no reason for persistence -because the VM recovery is a no-op. Conversely, if the ABR capability is +because the VM recovery is a no-op. +Conversely, if the ABR capability is applied to a non-DRL mirror to indicate that the VM should not perform a full recovery of the mirror following a system crash, the capability must be persistent so that the VM know whether or not to perform recovery. -.sp +.Pp Return Errors: -.sp -.ne 2 -.na -\fB\fBEINVAL\fR\fR -.ad -.RS 11n +.Pp +.Bl -tag -width ENOTSUP -compact -offset 2n +.It Er EINVAL Invalid device for this operation. -.RE - -.sp -.ne 2 -.na -\fB\fBENOTSUP\fR\fR -.ad -.RS 11n +.It Er ENOTSUP Functionality that is attempted to be set is not supported. -.RE - -.RE - -.sp -.ne 2 -.na -\fB\fBDKIOCSETVOLCAP\fR\fR -.ad -.sp .6 -.RS 4n -This ioctl sets the available capabilities for the device. If a capability flag -is not set in vc_set, that capability is cleared. -.sp -\fIvc_info\fR flags are ignored -.sp -\fIvc_set\fR valid flags are: -.sp -.in +2 -.nf -DKV_ABR_CAP - Flag to set application-based recovery. A device can - successfully support ABR only if it is capable. -DKV_DMR_CAP - Flag to set directed read. - - -int -ioctl(int , DKIODMR, vol_directed_rd *); -.fi -.in -2 - -.RE - -.sp -.ne 2 -.na -\fB\fBDKIODMR\fR\fR -.ad -.sp .6 -.RS 4n +.El +.It Dv DKIOCSETVOLCAP +.Pp +This ioctl sets the available capabilities for the device. +If a capability flag +is not set in +.Fa vc_set , +that capability is cleared. +.Pp +.Fa vc_info +flags are ignored. +.Pp +.Fa vc_set +valid flags are: +.Pp +.Bl -tag -width DKV_ABR_CAP -compact -offset 2n +.It Dv DKV_ABR_CAP +Flag to set application-based recovery. +A device can successfully support ABR only if it is capable. +.It Dv DKV_DMR_CAP +Flag to set directed read. +.El +.It Dv DKIODMR +.Pp +.Ft int +.Fo ioctl +.Fa int , +.\" This could be .Fa as well -- but mandoc doesn't seem to allow both +.Dv DKIODMR , +.Fa "vol_directed_rd *" +.Fc +.Pp This ioctl allows highly available applications to perform round-robin reads from the underlying devices of a replicated device. -.sp -.in +2 -.nf -vdr_offset - offset at which the read should occur. -vdr_nbytes - number of bytes to be read -vdr_bytesread - number of bytes successfully read by the kernel. -vdr_data - pointer to a user allocated buffer to return the - data read -vdr_side - side to be read. Initialized to DKV_SIDE_INIT -vdr_side_name - The volume name that has been read. - -Valid vdr_flags are: - DKV_DMR_NEXT_SIDE (set by user) - DKV_DMR_DONE (return value) - DKV_DMR_ERROR (return value) - DKV_DMR_SUCCESS(return value) - DKV_DMR_SHORT(return value) -.fi -.in -2 - -The calling sequence is as follows: The caller sets the \fIvdr_flags\fR to -\fBDK_DMR_NEXT_SIDE\fR and \fIvdr_side\fR to \fBDKV_SIDE_INIT\fR at the start. -Subsequent calls should be made without any changes to these values. If they -are changed the results of the ioctl are indeterminate. -.sp -When \fBDKV_SIDE_INIT\fR is set, the call results in the kernel reading from -the first side. The kernel updates \fIvdr_side\fR to indicate the side that was -read, and \fIvdr_side_name\fR to contain the name of that side. \fIvdr_data\fR -contains the data that was read. Therefore to perform a round-robin read all of +.Pp +.Bl -tag -width vdr_bytesread -offset 2n -compact +.It Fa vdr_offset +Offset at which the read should occur. +.It Fa vdr_nbytes +Number of bytes to be read +.It Fa vdr_bytesread +Number of bytes successfully read by the kernel. +.It Fa vdr_data +Pointer to a user allocated buffer to return the data read +.It Fa vdr_side +Side to be read. +Initialized to +.Dv DKV_SIDE_INIT +.It Fa vdr_side_name +The volume name that has been read. +.El +.Pp +Valid +.Fa vdr_flags +are: +.Pp +.Bl -tag -width DKV_DMR_NEXT_SIDE -offset 2n -compact +.It Dv DKV_DMR_NEXT_SIDE +Set by user +.It Dv DKV_DMR_DONE +Return value +.It Dv DKV_DMR_ERROR +Return value +.It Dv DKV_DMR_SUCCESS +Return value +.It Dv DKV_DMR_SHORT +Return value +.El +.Pp +The calling sequence is as follows: The caller sets the +.Fa vdr_flags +to +.Dv DK_DMR_NEXT_SIDE +and +.Fa vdr_side +to +.Dv DKV_SIDE_INIT +at the start. +Subsequent calls should be made without any changes to these values. +If they are changed the results of the ioctl are indeterminate. +.Pp +When +.Dv DKV_SIDE_INIT +is set, the call results in the kernel reading from the first side. +The kernel updates +.Fa vdr_side +to indicate the side that was read, and +.Fa vdr_side_name +to contain the name of that side. +.Fa vdr_data +contains the data that was read. +Therefore to perform a round-robin read all of the valid sides, there is no need for the caller to change the contents of -\fIvdr_side\fR. -.sp -Subsequent ioctl calls result in reads from the next valid side until all valid -sides have been read. On success, the kernel sets \fBDKV_DMR_SUCCESS\fR. The -following table shows the values of \fIvdr_flags\fR that are returned when an -error occurs: -.sp -.in +2 -.nf -vdr_flags | vdr_side | Notes --------------|-------------------|---------------------------- -DKV_DMR_ERROR| DKV_SIDE_INIT | No valid side to read -DKV_DMR_DONE | Not Init side | All valid sides read -DKV_DMR_SHORT| Any value | Bytes requested cannot - be read. vdr_bytesread - set to bytes actually - read. -.fi -.in -2 - -.sp -.in +2 -.nf +.Fa vdr_side . +.Pp +Subsequent +.Xr ioctl 2 +calls result in reads from the next valid side until all valid +sides have been read. +On success, the kernel sets +.Dv DKV_DMR_SUCCESS . +The following table shows the values of +.Fa vdr_flags +that are returned when an error occurs: +.Bl -column DKV_DMR_SHORT DKV_SIDE_INIT "Bytes requested cannot" -offset 2n +.It Fa vda_flags Ta Fa vdr_side Ta Notes +.It Dv DKV_DMR_ERROR Ta Dv DKV_SIDE_INIT Ta \&No valid side to read +.It Dv DKV_DMR_DONE Ta Not Init side Ta All valid sides read +.It Dv DKV_DMR_SHORT Ta Any value Ta Bytes requested cannot be read Fa vdr_bytesread No set to bytes actually read +.El Typical code fragment: - +.Bd -literal -offset 2n enable->vc_set |= DKV_ABR_SET; retval = ioctl(filedes, DKIOSETVOLCAP, enable); if (retval != EINVAL || retval != ENOTSUP) { @@ -751,7 +684,7 @@ if (retval != EINVAL || retval != ENOTSUP) { dr->vdr_nbytes = 1024; dr->vdr_offset = 0xff00; do { - rval =ioctl(fildes, DKIODMR, dr); + rval = ioctl(fildes, DKIODMR, dr); if (rval != EINVAL) { /* Process data */ } @@ -759,177 +692,176 @@ if (retval != EINVAL || retval != ENOTSUP) { (DKV_DMR_DONE | DKV_DMR_ERROR | DKV_DMR_SHORT) } } -.fi -.in -2 - -.RE - -.SS "RETURN VALUES" -.LP -Upon successful completion, the value returned is \fB0\fR. Otherwise, \fB-1\fR -is returned and \fBerrno\fR is set to indicate the error. -.SS "x86 Only" -.LP -The following \fBioctl()\fR requests set and/or retrieve the current disk +.Ed +.El +.Ss "RETURN VALUES" +Upon successful completion, the value returned is +.Sy 0 . +Otherwise, +.Sy -1 +is returned and +.Va errno +is set to indicate the error. +.Ss "x86 Only" +The following +.Xr ioctl 2 +requests set and/or retrieve the current disk controller, partitions, or geometry information on the x86 architecture. -.sp -.ne 2 -.na -\fB\fBDKIOCG_PHYGEOM\fR\fR -.ad -.sp .6 -.RS 4n -The argument is a pointer to a \fBdk_geom\fR structure (described below). This -\fBioctl()\fR gets the driver's notion of the physical geometry of the disk -drive. It is functionally identical to the \fBDKIOCGGEOM\fR \fBioctl()\fR. -.RE - -.sp -.ne 2 -.na -\fB\fBDKIOCG_VIRTGEOM\fR\fR -.ad -.sp .6 -.RS 4n -The argument is a pointer to a \fBdk_geom\fR structure (described below). This -\fBioctl()\fR gets the controller's (and hence the driver's) notion of the -virtual geometry of the disk drive. Virtual geometry is a view of the disk +.Bl -tag -width 1n +.It Dv DKIOCG_PHYGEOM +.Pp +The argument is a pointer to a +.Vt dk_geom +structure (described below). +This +.Xr ioctl 2 +gets the driver's notion of the physical geometry of the disk drive. +It is functionally identical to the +.Dv DKIOCGGEOM +.Xr ioctl 2 . +.It Dv DKIOCG_VIRTGEOM +.Pp +The argument is a pointer to a +.Vt dk_geom +structure (described below). +This +.Xr ioctl 2 +gets the controller's (and hence the driver's) notion of the +virtual geometry of the disk drive. +Virtual geometry is a view of the disk geometry maintained by the firmware in a host bus adapter or disk controller. If the disk is larger than 8 Gbytes, this ioctl fails because a CHS-based geometry is not relevant or useful for this drive. -.RE - -.sp -.in +2 -.nf +.Bd -literal -offset 2n /* -* Definition of a disk's geometry -*/ -*/struct dk_geom { -unsigned shor dkg_ncyl; /* # of data cylinders */ -unsigned shor dkg_acyl; /* # of alternate cylinders */ -unsigned short dkg_bcyl; /* cyl offset (for fixed head */ - /* area) */ -unsigned short dkg_nhead; /* # of heads */ -unsigned short dkg_obs1; /* obsolete */ -unsigned short dkg_nsect; /* # of sectors per track*/ -unsigned short dkg_intrlv; /* interleave factor */ -unsigned short dkg_obs2; /* obsolete */ -unsigned short dkg_obs3; /* obsolete */ -unsigned short dkg_apc; /* alternates per cylinder */ - /* (SCSI only) */ -unsigned short dkg_rpm; /* revolutions per min*/ -unsigned short dkg_pcyl; /* # of physical cylinders */ -unsigned short dkg_write_reinstruct; /* # sectors to skip, writes*/ -unsigned short dkg_read_reinstruct; /* # sectors to skip, reads*/ -unsigned short dkg_extra[7]; /* for compatible expansion*/ + * Definition of a disk's geometry + */ +struct dk_geom { + unsigned shor dkg_ncyl; /* # of data cylinders */ + unsigned shor dkg_acyl; /* # of alternate cylinders */ + unsigned short dkg_bcyl; /* cyl offset (for fixed head */ + /* area) */ + unsigned short dkg_nhead; /* # of heads */ + unsigned short dkg_obs1; /* obsolete */ + unsigned short dkg_nsect; /* # of sectors per track */ + unsigned short dkg_intrlv; /* interleave factor */ + unsigned short dkg_obs2; /* obsolete */ + unsigned short dkg_obs3; /* obsolete */ + unsigned short dkg_apc; /* alternates per cylinder */ + /* (SCSI only) */ + unsigned short dkg_rpm; /* revolutions per min */ + unsigned short dkg_pcyl; /* # of physical cylinders */ + unsigned short dkg_write_reinstruct; /* # sectors to skip, */ + /* writes */ + unsigned short dkg_read_reinstruct; /* # sectors to skip ,*/ + /* reads */ + unsigned short dkg_extra[7]; /* for compatible expansion */ }; -.fi -.in -2 - -.sp -.ne 2 -.na -\fB\fBDKIOCADDBAD\fR\fR -.ad -.sp .6 -.RS 4n -This \fBioctl()\fR forces the driver to re-examine the alternates slice and -rebuild the internal bad block map accordingly. It should be used whenever the -alternates slice is changed by any method other than the \fBaddbadsec\fR(1M) or -\fBformat\fR(1M) utilities. \fBDKIOCADDBAD\fR can only be used for software -remapping on \fB IDE\fR drives; \fBSCSI\fR drives use hardware remapping of -alternate sectors. -.RE - -.sp -.ne 2 -.na -\fB\fBDKIOCPARTINFO\fR\fR -.ad -.sp .6 -.RS 4n -The argument is a pointer to a \fBpart_info\fR structure (described below). -This \fBioctl()\fR gets the driver's notion of the size and extent of the +.Ed +.It Dv DKIOCADDBAD +.Pp +This +.Xr ioctl 2 +forces the driver to re-examine the alternates slice and +rebuild the internal bad block map accordingly. +It should be used whenever the +alternates slice is changed by any method other than the +.Xr addbadsec 1M +or +.Xr format 1M +utilities. +.Dv DKIOCADDBAD +can only be used for software +remapping on +.Sy IDE +drives; +.Sy SCSI +drives use hardware remapping of alternate sectors. +.It Dv DKIOCPARTINFO +.Pp +The argument is a pointer to a +.Vt part_info +structure (described below). +This +.Xr ioctl 2 +gets the driver's notion of the size and extent of the partition or slice indicated by the file descriptor argument. -.sp -.in +2 -.nf +.Bd -literal -offset 2n /* * Used by applications to get partition or slice information */ struct part_info { -daddr_t p_start; -int p_length; - }; -.fi -.in -2 - -.RE - -.sp -.ne 2 -.na -\fB\fBDKIOCEXTPARTINFO\fR\fR -.ad -.sp .6 -.RS 4n -The argument is a pointer to an \fBextpart_info\fR structure (described below). + daddr_t p_start; + int p_length; +}; +.Ed +.It Dv DKIOCEXTPARTINFO +.Pp +The argument is a pointer to an +.Vt extpart_info +structure (described below). This ioctl gets the driver's notion of the size and extent of the partition or -slice indicated by the file descriptor argument. On disks larger than 1TB, this -ioctl must be used instead of \fBDKIOCPARTINFO\fR. -.sp -.in +2 -.nf +slice indicated by the file descriptor argument. +On disks larger than 1TB, this ioctl must be used instead of +.Dv DKIOCPARTINFO . +.Bd -literal -offset 2n /* -* Used by applications to get partition or slice information -*/ + * Used by applications to get partition or slice information + */ struct extpart_info { -diskkaddr_t p_start; -diskaddr_t p_length; + diskkaddr_t p_start; + diskaddr_t p_length; }; -.fi -.in -2 - -.RE - -.sp -.ne 2 -.na -\fB\fBDKIOCSETEXTPART\fR\fR -.ad -.sp .6 -.RS 4n +.Ed +.It Dv DKIOCSETEXTPART +.Pp This ioctl is used to update the in-memory copy of the logical drive -information maintained by the driver. The ioctl takes no arguments. It causes a -re-read of the partition information and recreation of minor nodes if required. +information maintained by the driver. +The ioctl takes no arguments. +It causes a re-read of the partition information and recreation of minor nodes +if required. Prior to updating the data structures, the ioctl ensures that the partitions do -not overlap. Device nodes are created only for valid partition entries. If -there is any change in the partition offset, size or ID from the previous read, -the partition is deemed to have been changed and hence the device nodes are -recreated. Any modification to any of the logical partitions results in the +not overlap. +Device nodes are created only for valid partition entries. +If there is any change in the partition offset, size or ID from the previous +read, the partition is deemed to have been changed and hence the device nodes +are recreated. +Any modification to any of the logical partitions results in the recreation of all logical device nodes. -.RE - -.SH SEE ALSO -.LP -\fBaddbadsec\fR(1M), \fBfdisk\fR(1M), \fBformat\fR(1M), \fBioctl\fR(2), -\fBcdio\fR(7I), \fBcmdk\fR(7D), \fBfdio\fR(7I), \fBhdio\fR(7I), \fBsd\fR(7D) -.SH NOTES -.LP -Blocksize information provided in \fBDKIOCGMEDIAINFO\fR is the size (in bytes) -of the device's basic unit of operation and can differ from the blocksize that -the Solaris operating environment exports to the user. Capacity information -provided in the \fBDKIOCGMEDIAINFO\fR are for reference only and you are -advised to use the values returned by \fBDKIOCGGEOM\fR or other appropriate -\fBioctl\fR for accessing data using the standard interfaces. -.sp -.LP -For x86 only: If the \fBDKIOCSMBOOT\fR command is used to modify the Solaris -partitions, the VTOC information should also be set appropriately to reflect -the changes to partition. Failure to do so leads to unexpected results when the -device is closed and reopened fresh at a later time. This is because a default -VTOC is assumed by driver when a Solaris partition is changed. The default VTOC -persists until the ioctl \fBDKIOCSVTOC\fR is called to modify VTOC or the -device is closed and reopened. At that point, the old valid VTOC is read from +.El +.Sh SEE ALSO +.Xr addbadsec 1M , +.Xr fdisk 1M , +.Xr format 1M , +.Xr ioctl 2 , +.Xr cmdk 7D , +.Xr sd 7D , +.Xr cdio 7I , +.Xr fdio 7I , +.Xr hdio 7I +.Sh NOTES +Blocksize information provided in +.Dv DKIOCGMEDIAINFO +is the size (in bytes) of the device's basic unit of operation and can differ +from the blocksize that the Solaris operating environment exports to the user. +Capacity information provided in the +.Dv DKIOCGMEDIAINFO +are for reference only and you are advised to use the values returned by +.Dv DKIOCGGEOM +or other appropriate +.Xr ioctl 2 +for accessing data using the standard interfaces. +.Pp +For x86 only: If the +.Dv DKIOCSMBOOT +command is used to modify the Solaris partitions, the VTOC information should +also be set appropriately to reflect the changes to partition. +Failure to do so leads to unexpected results when the +device is closed and reopened fresh at a later time. +This is because a default VTOC is assumed by driver when a Solaris partition +is changed. +The default VTOC persists until the ioctl +.Dv DKIOCSVTOC +is called to modify VTOC or the device is closed and reopened. +At that point, the old valid VTOC is read from the disk if it is still available. diff --git a/usr/src/man/man7i/fbio.7i b/usr/src/man/man7i/fbio.7i index 792147714d..484e60ebec 100644 --- a/usr/src/man/man7i/fbio.7i +++ b/usr/src/man/man7i/fbio.7i @@ -1,87 +1,160 @@ -'\" te .\" Copyright (c) 2003, Sun Microsystems, Inc. -.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. -.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. -.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH FBIO 7I "May 12, 2003" -.SH NAME -fbio \- frame buffer control operations -.SH DESCRIPTION -.sp -.LP +.\" Copyright (c) 2017, Joyent, Inc. +.\" The contents of this file are subject to the terms of the +.\" Common Development and Distribution License (the "License"). +.\" You may not use this file except in compliance with the License. +.\" +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE +.\" or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions +.\" and limitations under the License. +.\" +.\" When distributing Covered Code, include this CDDL HEADER in each +.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. +.\" If applicable, add the following below this CDDL HEADER, with the fields +.\" enclosed by brackets "[]" replaced with your own identifying +.\" information: Portions Copyright [yyyy] [name of copyright owner] +.Dd October 22, 2017 +.Dt FBIO 7I +.Os +.Sh NAME +.Nm fbio +.Nd frame buffer control operations +.Sh DESCRIPTION The frame buffers provided with this release support the same general interface -that is defined by \fB<sys/fbio.h>\fR\&. Each responds to an \fBFBIOGTYPE\fR -\fBioctl\fR(2) request which returns information in a \fBfbtype\fR structure. -.sp -.LP -Each device has an \fBFBTYPE\fR which is used by higher-level software to -determine how to perform graphics functions. Each device is used by opening it, -doing an \fBFBIOGTYPE\fR \fBioctl()\fR to see which frame buffer type is +that is defined by +.In sys/fbio.h . +Each responds to an +.Dv FBIOGTYPE +.Xr ioctl 2 +request which returns information in a +.Vt fbtype +structure. +.Pp +Each device has an +.\" FBTYPE isn't macro, enum, or type, just used to describe a number of +.\" CPP-macros of the form #define FBTYPE_xxxx +.Sy FBTYPE +which is used by higher-level software to +determine how to perform graphics functions. +Each device is used by opening it, doing an +.Dv FBIOGTYPE +.Xr ioctl 2 +to see which frame buffer type is present, and thereby selecting the appropriate device-management routines. -.sp -.LP -\fBFBIOGINFO\fR returns information specific to the GS accelerator. -.sp -.LP -\fBFBIOSVIDEO\fR and \fBFBIOGVIDEO\fR are general-purpose \fBioctl()\fR -requests for controlling possible video features of frame buffers. These -\fBioctl()\fR requests either set or return the value of a flags integer. At -this point, only the \fBFBVIDEO_ON\fR option is available, controlled by -\fBFBIOSVIDEO\fR. \fBFBIOGVIDEO\fR returns the current video state. -.sp -.LP -The \fBFBIOSATTR\fR and \fBFBIOGATTR\fR \fBioctl()\fR requests allow access to -special features of newer frame buffers. They use the \fBfbsattr\fR and -\fBfbgattr\fR structures. -.sp -.LP -Some color frame buffers support the \fBFBIOPUTCMAP\fR and \fBFBIOGETCMAP\fR -\fBioctl()\fR requests, which provide access to the colormap. They use the -\fBfbcmap\fR structure. -.sp -.LP +.Pp +.Dv FBIOGINFO +returns information specific to the GS accelerator. +.Pp +.Dv FBIOSVIDEO +and +.Dv FBIOGVIDEO +are general-purpose +.Xr ioctl 2 +requests for controlling possible video features of frame buffers. +These +.Xr ioctl 2 +requests either set or return the value of a flags integer. +At this point, only the +.Dv FBVIDEO_ON +option is available, controlled by +.Dv FBIOSVIDEO . +.Dv FBIOGVIDEO +returns the current video state. +.Pp +The +.Dv FBIOSATTR +and +.Dv FBIOGATTR +.Xr ioctl 2 +requests allow access to special features of newer frame buffers. +They use the +.Vt fbsattr +and +.Vt fbgattr +structures. +.Pp +Some color frame buffers support the +.Dv FBIOPUTCMAP +and +.Dv FBIOGETCMAP +.Xr ioctl 2 +requests, which provide access to the colormap. +They use the +.Vt fbcmap +structure. +.Pp Also, some framebuffers with multiple colormaps will either encode the colormap -identifier in the high-order bits of the "index" field in the fbcmap structure, -or use the \fBFBIOPUTCMAPI\fR and \fBFBIOGETCMAPI\fR \fBioctl()\fR requests. -.sp -.LP -\fBFBIOVERTICAL\fR is used to wait for the start of the next vertical retrace +identifier in the high-order bits of the +.Dq index +field in the +.Vt fbcmap +structure, or use the +.Dv FBIOPUTCMAPI +and +.Dv FBIOGETCMAPI +.Xr ioctl 2 +requests. +.Pp +.Dv FBIOVERTICAL +is used to wait for the start of the next vertical retrace period. -.sp -.LP -\fBFBIOVRTOFFSET\fR Returns the offset to a read-only \fIvertical retrace -page\fR for those framebuffers that support it. This vertical retrace page may -be mapped into user space with \fBmmap\fR(2). The first word of the vertical -retrace page (type unsigned int) is a counter that is incremented every time -there is a vertical retrace. The user process can use this counter in a -variety of ways. -.sp -.LP -\fBFBIOMONINFO\fR returns a mon_info structure which contains information about +.Pp +.Dv FBIOVRTOFFSET +Returns the offset to a read-only +.Dq Em vertical retrace page +for those framebuffers that support it. +This vertical retrace page may be mapped into user space with +.Xr mmap 2 . +The first word of the vertical +retrace page (type +.Vt "unsigned int" ) +is a counter that is incremented every time there is a vertical retrace. +The user process can use this counter in a variety of ways. +.Pp +.Dv FBIOMONINFO +returns a +.Vt mon_info +structure which contains information about the monitor attached to the framebuffer, if available. -.sp -.LP -\fBFBIOSCURSOR\fR, \fBFBIOGCURSOR\fR, \fBFBIOSCURPOS\fR and \fBFBIOGCURPOS\fR +.Pp +.Dv FBIOSCURSOR , +.Dv FBIOGCURSOR , +.Dv FBIOSCURPOS +and +.Dv FBIOGCURPOS are used to control the hardware cursor for those framebuffers that have this -feature. \fBFBIOGCURMAX\fR returns the maximum sized cursor supported by the -framebuffer. Attempts to create a cursor larger than this will fail. -.sp -.LP -Finally \fBFBIOSDEVINFO\fR and \fBFBIOGDEVINFO\fR are used to transfer +feature. +.Dv FBIOGCURMAX +returns the maximum sized cursor supported by the framebuffer. +Attempts to create a cursor larger than this will fail. +.Pp +Finally +.Dv FBIOSDEVINFO +and +.Dv FBIOGDEVINFO +are used to transfer variable-length, device-specific information into and out of framebuffers. -.SH SEE ALSO -.sp -.LP -\fBioctl\fR(2), \fBmmap\fR(2), \fBcgsix\fR(7D) -.SH BUGS -.sp -.LP -The \fBFBIOSATTR\fR and \fBFBIOGATTR\fR \fBioctl()\fR requests are only -supported by frame buffers which emulate older frame buffer types. If a frame -buffer emulates another frame buffer, \fBFBIOGTYPE\fR returns the emulated -type. To get the real type, use \fBFBIOGATTR\fR. -.sp -.LP -The \fBFBIOGCURPOS\fR ioctl was incorrectly defined in previous operating +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr mmap 2 , +.Xr cgsix 7D +.Sh BUGS +The +.Dv FBIOSATTR +and +.Dv FBIOGATTR +.Xr ioctl 2 +requests are only +supported by frame buffers which emulate older frame buffer types. +If a frame buffer emulates another frame buffer, +.Dv FBIOGTYPE +returns the emulated type. +To get the real type, use +.Dv FBIOGATTR . +.Pp +The +.Dv FBIOGCURPOS +ioctl was incorrectly defined in previous operating systems, and older code running in binary compatibility mode may get incorrect results. diff --git a/usr/src/man/man7i/fdio.7i b/usr/src/man/man7i/fdio.7i index 1cc1487095..a95f84dfaa 100644 --- a/usr/src/man/man7i/fdio.7i +++ b/usr/src/man/man7i/fdio.7i @@ -1,215 +1,189 @@ -'\" te .\" Copyright (c) 2001, Sun Microsystems, Inc. All Rights Reserved -.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. -.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. -.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH FDIO 7I "Apr 26, 2001" -.SH NAME -fdio \- floppy disk control operations -.SH SYNOPSIS -.LP -.nf -\fB#include <sys/fdio.h>\fR -.fi - -.SH DESCRIPTION -.sp -.LP -The Solaris floppy driver supports a set of \fBioctl\fR(2) requests for getting -and setting the floppy drive characteristics. Basic to these \fBioctl\fR(\|) -requests are the definitions in \fB<sys/fdio.h>\fR\&. -.SH IOCTLS -.sp -.LP -The following \fBioctl\fR(\|) requests are available on the Solaris floppy -driver. -.sp -.ne 2 -.na -\fB\fBFDDEFGEOCHAR\fR\fR -.ad -.RS 16n -x86 based systems: This \fBioctl\fR(\|) forces the floppy driver to restore +.\" Copyright (c) 2017, Joyent, Inc. +.\" The contents of this file are subject to the terms of the +.\" Common Development and Distribution License (the "License"). +.\" You may not use this file except in compliance with the License. +.\" +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE +.\" or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions +.\" and limitations under the License. +.\" +.\" When distributing Covered Code, include this CDDL HEADER in each +.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. +.\" If applicable, add the following below this CDDL HEADER, with the +.\" fields enclosed by brackets "[]" replaced with your own identifying +.\" information: Portions Copyright [yyyy] [name of copyright owner] +.Dd October 22, 2017 +.Dt FDIO 7I +.Os +.Sh NAME +.Nm fdio +.Nd floppy disk control operations +.Sh SYNOPSIS +.In sys/fdio.h +.Sh DESCRIPTION +The Solaris floppy driver supports a set of +.Xr ioctl 2 +requests for getting and setting the floppy drive characteristics. +Basic to these +.Xr ioctl 2 +requests are the definitions in +.In sys/fdio.h . +.Sh IOCTLS +The following +.Xr ioctl 2 +requests are available on the Solaris floppy driver. +.Bl -tag -width FDDEFGEOCHAR +.It Dv FDDEFGEOCHAR +x86 based systems: This +.Xr ioctl 2 +forces the floppy driver to restore the diskette and drive characteristics and geometry, and partition information to default values based on the device configuration. -.RE - -.sp -.ne 2 -.na -\fB\fBFDGETCHANGE\fR\fR -.ad -.RS 16n -The argument is a pointer to an \fBint.\fR This \fBioctl\fR(\|) returns the -status of the diskette-changed signal from the floppy interface. The following -defines are provided for cohesion. -.RE - -.sp -.LP -Note: For x86 based systems, use \fBFDGC_DETECTED\fR (which is available only -on x86 based systems) instead of \fBFDGC_HISTORY.\fR -.sp -.in +2 -.nf +.It Dv FDGETCHANGE +The argument is a pointer to an +.Vt int . +This +.Xr ioctl 2 +returns the status of the diskette-changed signal from the floppy interface. +The following defines are provided for cohesion. +.El +.Pp +Note: For x86 based systems, use +.Dv FDGC_DETECTED +(which is available only on x86 based systems) instead of +.Dv FDGC_HISTORY . +.Bd -literal -offset 2n /* * Used by FDGETCHANGE, returned state of the sense disk change bit. */ -#define FDGC_HISTORY 0x01 /* disk has changed since insertion or - last FDGETCHANGE call */ -#define FDGC_CURRENT 0x02 /* if set, indicates drive has floppy, -> otherwise, drive is empty */ +#define FDGC_HISTORY 0x01 /* + * disk has changed since insertion or + * last FDGETCHANGE call + */ +#define FDGC_CURRENT 0x02 /* + * if set, indicates drive has floppy, + * otherwise, drive is empty + */ #define FDGC_CURWPROT 0x10 /* current state of write protect */ #define FDGC_DETECTED 0x20 /* previous state of DISK CHANGE */ -.fi -.in -2 - -.sp -.ne 2 -.na -\fB\fBFDIOGCHAR\fR\fR -.ad -.RS 13n -The argument is a pointer to an \fBfd_char\fR structure (described below). This -\fBioctl\fR(\|) gets the characteristics of the floppy diskette from the floppy -controller. -.RE - -.sp -.ne 2 -.na -\fB\fBFDIOSCHAR\fR\fR -.ad -.RS 13n -The argument is a pointer to an \fBfd_char\fR structure (described below). This -\fBioctl\fR(\|) sets the characteristics of the floppy diskette for the floppy -controller. Typical values in the \fBfd_char\fR structure for a high density -diskette: -.sp -.in +2 -.nf -field value -fdc_medium 0 -fdc_transfer_rate 500 -fdc_ncyl 80 -fdc_nhead 2 -fdc_sec_size 512 -fdc_secptrack 18 -fdc_steps -1 { This field doesn't apply. } -.fi -.in -2 - -.RE - -.sp -.in +2 -.nf +.Ed +.Bl -tag -width FDIOGCHAR +.It Dv FDIOGCHAR +The argument is a pointer to an +.Vt fd_char +structure (described below). +This +.Xr ioctl 2 +gets the characteristics of the floppy diskette from the floppy controller. +.It Dv FDIOSCHAR +The argument is a pointer to an +.Vt fd_char +structure (described below). +This +.Xr ioctl 2 +sets the characteristics of the floppy diskette for the floppy controller. +Typical values in the +.Vt fd_char +structure for a high density diskette: +.Bl -column fdc_stransfer_rate value "{ This field doesn't apply. }" +.It Field Ta Value Ta +.It fdc_medium Ta 0 Ta +.It fdc_transfer_rate Ta 500 Ta +.It fdc_ncyl Ta 80 Ta +.It fdc_nhead Ta 2 Ta +.It fdc_sec_size Ta 512 Ta +.It fdc_secptrack Ta 18 Ta +.It fdc_steps Ta -1 Ta { This field doesn't apply. } +.El +.El +.Bd -literal -offset 2n /* * Floppy characteristics */ struct fd_char { - uchar_t fdc_medium; /* equals 1 if floppy is medium density format */ - int fdc_transfer_rate; /* transfer rate */ - int fdc_ncyl; /* number of cylinders */ - int fdc_nhead; /* number of heads */ - int fdc_sec_size; /* sector size */ - int fdc_secptrack; /* sectors per track */ - int fdc_steps; /* no. of steps per data track */ + uchar_t fdc_medium; /* equals 1 if floppy is medium density format */ + int fdc_transfer_rate; /* transfer rate */ + int fdc_ncyl; /* number of cylinders */ + int fdc_nhead; /* number of heads */ + int fdc_sec_size; /* sector size */ + int fdc_secptrack; /* sectors per track */ + int fdc_steps; /* no. of steps per data track */ }; -.fi -.in -2 - -.sp -.ne 2 -.na -\fB\fBFDGETDRIVECHAR\fR\fR -.ad -.RS 18n -The argument to this \fBioctl\fR(\|) is a pointer to an \fBfd_drive\fR -structure (described below). This \fBioctl\fR(\|) gets the characteristics of -the floppy drive from the floppy controller. -.RE - -.sp -.ne 2 -.na -\fB\fBFDSETDRIVECHAR\fR\fR -.ad -.RS 18n -x86 based systems: The argument to this \fBioctl\fR(\|) is a pointer to an -\fBfd_drive\fR structure (described below). This \fBioctl\fR(\|) sets the -characteristics of the floppy drive for the floppy controller. Only -\fBfdd_steprate\fR, \fBfdd_headsettle\fR, \fBfdd_motoron\fR, and -\fBfdd_motoroff\fR are actually used by the floppy disk driver. -.RE - -.sp -.in +2 -.nf +.Ed +.Bl -tag -width FDGETDRIVECHAR +.It Dv FDGETDRIVECHAR +The argument to this +.Xr ioctl 2 +is a pointer to an +.Vt fd_drive +structure (described below). +This +.Xr ioctl 2 +gets the characteristics of the floppy drive from the floppy controller. +.It Dv FDSETDRIVECHAR +x86 based systems: The argument to this +.Xr ioctl 2 +is a pointer to an +.Vt fd_drive +structure (described below). +This +.Xr ioctl 2 +sets the characteristics of the floppy drive for the floppy controller. +Only +.Fa fdd_steprate , +.Fa fdd_headsettle , +.Fa fdd_motoron , +and +.Fa fdd_motoroff +are actually used by the floppy disk driver. +.El +.Bd -literal -offset 2n /* * Floppy Drive characteristics */ struct fd_drive { - int fdd_ejectable; /* does the drive support eject? */ - int fdd_maxsearch; /* size of per-unit search table */ - int fdd_writeprecomp; /* cyl to start write precompensation */ - int fdd_writereduce; /* cyl to start recucing write current */ - int fdd_stepwidth; /* width of step pulse in 1 us units */ - int fdd_steprate; /* step rate in 100 us units */ - int fdd_headsettle; /* delay, in 100 us units */ - int fdd_headload; /* delay, in 100 us units */ - int fdd_headunload; /* delay, in 100 us units */ - int fdd_motoron; /* delay, in 100 ms units */ - int fdd_motoroff; /* delay, in 100 ms units */ - int fdd_precomplevel; /* bit shift, in nano-secs */ - int fdd_pins; /* defines meaning of pin 1, 2, 4 and 34 */ - int fdd_flags; /* TRUE READY, Starting Sector #, & Motor On */ + int fdd_ejectable; /* does the drive support eject? */ + int fdd_maxsearch; /* size of per-unit search table */ + int fdd_writeprecomp; /* cyl to start write precompensation */ + int fdd_writereduce; /* cyl to start recucing write current */ + int fdd_stepwidth; /* width of step pulse in 1 us units */ + int fdd_steprate; /* step rate in 100 us units */ + int fdd_headsettle; /* delay, in 100 us units */ + int fdd_headload; /* delay, in 100 us units */ + int fdd_headunload; /* delay, in 100 us units */ + int fdd_motoron; /* delay, in 100 ms units */ + int fdd_motoroff; /* delay, in 100 ms units */ + int fdd_precomplevel; /* bit shift, in nano-secs */ + int fdd_pins; /* defines meaning of pin 1, 2, 4 and 34 */ + int fdd_flags; /* TRUE READY, Starting Sector #, & Motor On */ }; -.fi -.in -2 - -.sp -.ne 2 -.na -\fB\fBFDGETSEARCH\fR\fR -.ad -.RS 15n +.Ed +.Bl -tag -width FDGETSEARCH +.It Dv FDGETSEARCH Not available. -.RE - -.sp -.ne 2 -.na -\fB\fBFDSETSEARCH\fR\fR -.ad -.RS 15n +.It Dv FDSETSEARCH Not available. -.RE - -.sp -.ne 2 -.na -\fB\fBFDEJECT\fR\fR -.ad -.RS 15n -SPARC: This \fBioctl\fR(\|) requests the floppy drive to eject the diskette. -.RE - -.sp -.ne 2 -.na -\fB\fBFDIOCMD\fR\fR -.ad -.RS 15n -The argument is a pointer to an \fBfd_cmd\fR structure (described below). This -\fBioctl\fR(\|) allows access to the floppy diskette using the floppy device -driver. Only the \fBFDCMD_WRITE\fR, \fBFDCMD_READ\fR, and -\fBFDCMD_FORMAT_TRACK\fR commands are currently available. -.RE - -.sp -.in +2 -.nf +.It Dv FDEJECT +SPARC: This +.Xr ioctl 2 +requests the floppy drive to eject the diskette. +.It Dv FDIOCMD +The argument is a pointer to an +.Vt fd_cmd +structure (described below). +This +.Xr ioctl 2 +allows access to the floppy diskette using the floppy device driver. +Only the +.Dv FDCMD_WRITE , +.Dv FDCMD_READ , +and +.Dv FDCMD_FORMAT_TRACK +commands are currently available. +.El +.Bd -literal -offset 2n struct fd_cmd { ushort_t fdc_cmd; /* command to be executed */ int fdc_flags; /* execution flags (x86 only) */ @@ -218,20 +192,18 @@ struct fd_cmd { caddr_t fdc_bufaddr; /* user's buffer address */ uint_t fdc_buflen; /* size of user's buffer */ }; -.fi -.in -2 - -.sp -.LP -Please note that the \fBfdc_buflen\fR field is currently unused. The -\fBfdc_secnt\fR field is used to calculate the transfer size, and the buffer is +.Ed +.Pp +Please note that the +.Fa fdc_buflen +field is currently unused. +The +.Fa fdc_secnt +field is used to calculate the transfer size, and the buffer is assumed to be large enough to accommodate the transfer. -.sp -.in +2 -.nf -{ +.Bd -literal -offset 2n /* -* Floppy commands + * Floppy commands */ #define FDCMD_WRITE 1 #define FDCMD_READ 2 @@ -239,29 +211,23 @@ assumed to be large enough to accommodate the transfer. #define FDCMD_REZERO 4 #define FDCMD_FORMAT_UNIT 5 #define FDCMD_FORMAT_TRACK 6 -}; -.fi -.in -2 - -.sp -.ne 2 -.na -\fB\fBFDRAW\fR\fR -.ad -.RS 9n -The argument is a pointer to an \fBfd_raw\fR structure (described below). -This \fBioctl\fR(\|) allows direct control of the floppy drive using the floppy -controller. Refer to the appropriate floppy-controller data sheet for full -details on required command bytes and returned result bytes. The following -commands are supported. -.RE - -.sp -.in +2 -.nf +.Ed +.Bl -tag -width FDRAW +.It Dv FDRAW +The argument is a pointer to an +.Vt fd_raw +structure (described below). +This +.Xr ioctl 2 +allows direct control of the floppy drive using the floppy controller. +Refer to the appropriate floppy-controller data sheet for full +details on required command bytes and returned result bytes. +The following commands are supported. +.El +.Bd -literal -offset 2n /* -* Floppy raw commands -*/ + * Floppy raw commands + */ #define FDRAW_SPECIFY 0x03 #define FDRAW_READID 0x0a (x86 only) #define FDRAW_SENSE_DRV 0x04 @@ -274,34 +240,38 @@ commands are supported. #define FDRAW_RDCMD 0x06 #define FDRAW_WRITEDEL 0x09 #define FDRAW_READDEL 0x0c -.fi -.in -2 - -.sp -.LP -Please note that when using \fBFDRAW_SEEK\fR or \fBFDRAW_REZERO,\fR the -driver automatically issues a \fBFDRAW_SENSE_INT\fR command to clear the -interrupt from the \fBFDRAW_SEEK\fR or the \fBFDRAW_REZERO.\fR The result -bytes returned by these commands are the results from the -\fBFDRAW_SENSE_INT\fR command. Please see the floppy-controller data sheet for -more details on \fBFDRAW_SENSE_INT.\fR -.sp -.in +2 -.nf +.Ed +.Pp +Please note that when using +.Dv FDRAW_SEEK +or +.Dv FDRAW_REZERO , +the driver automatically issues a +.Dv FDRAW_SENSE_INT +command to clear the interrupt from the +.Dv FDRAW_SEEK +or the +.Dv FDRAW_REZERO . +The result bytes returned by these commands are the results from the +.Dv DRAW_SENSE_INT +command. +Please see the floppy-controller data sheet for +more details on +.Dv FDRAW_SENSE_INT . +.Bd -literal -offset 2n /* * Used by FDRAW */ struct fd_raw { - char fdr_cmd[10]; /* user-supplied command bytes */ - short fdr_cnum; /* number of command bytes */ - char fdr_result[10]; /* controller-supplied result bytes */ - ushort_t fdr_nbytes; /* number to transfer if read/write command */ - char *fdr_addr; /* where to transfer if read/write command */ + char fdr_cmd[10]; /* user-supplied command bytes */ + short fdr_cnum; /* number of command bytes */ + char fdr_result[10]; /* controller-supplied result bytes */ + ushort_t fdr_nbytes; /* number to transfer if read/write command */ + char *fdr_addr; /* where to transfer if read/write command */ }; -.fi -.in -2 - -.SH SEE ALSO -.sp -.LP -\fBioctl\fR(2), \fBdkio\fR(7I), \fBfd\fR(7D), \fBhdio\fR(7I) +.Ed +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr fd 7D , +.Xr dkio 7I , +.Xr hdio 7I diff --git a/usr/src/man/man7i/hdio.7i b/usr/src/man/man7i/hdio.7i index 5fb6f841db..2e4460f66c 100644 --- a/usr/src/man/man7i/hdio.7i +++ b/usr/src/man/man7i/hdio.7i @@ -1,125 +1,112 @@ -'\" te .\" Copyright (c) 2002, Sun Microsystems, Inc. -.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. -.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. -.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH HDIO 7I "Aug 13, 2002" -.SH NAME -hdio \- SMD and IPI disk control operations -.SH SYNOPSIS -.LP -.nf -#include <sys/hdio.h> -.fi - -.SH DESCRIPTION -.LP -Note - -.sp -.RS 2 -The SMC and IPI drivers have been discontinued. \fBdkio\fR(7I) is now the -preferred method for retrieving disk information. -.RE -.sp -.LP +.\" Copyright (c) 2017, Joyent, Inc. +.\" The contents of this file are subject to the terms of the +.\" Common Development and Distribution License (the "License"). +.\" You may not use this file except in compliance with the License. +.\" +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE +.\" or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions +.\" and limitations under the License. +.\" +.\" When distributing Covered Code, include this CDDL HEADER in each +.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. +.\" If applicable, add the following below this CDDL HEADER, with the +.\" fields enclosed by brackets "[]" replaced with your own identifying +.\" information: Portions Copyright [yyyy] [name of copyright owner] +.Dd October 23, 2017 +.Dt HDIO 7I +.Os +.Sh NAME +.Nm hdio +.Nd SMD and IPI disk control operations +.Sh SYNOPSIS +.In sys/hdio.h +.Sh DESCRIPTION +Note \(em the SMC and IPI drivers have been discontinued. +.Xr dkio 7I +is now the preferred method for retrieving disk information. +.Pp The SMD and IPI disk drivers supplied with this release support a set of -\fBioctl\fR(2) requests for diagnostics and bad sector information. Basic to -these \fBioctl()\fR requests are the definitions in <\fBsys/hdio.h\fR>. -.SH IOCTLS -.sp -.ne 2 -.na -\fB\fBHDKIOCGTYPE\fR\fR -.ad -.RS 15n -The argument is a pointer to a \fBhdk_type\fR structure (described below). -This \fBioctl()\fR gets specific information from the hard disk. -.RE - -.sp -.ne 2 -.na -\fB\fBHDKIOCSTYPE\fR\fR -.ad -.RS 15n -The argument is a pointer to a \fBhdk_type\fR structure (described below). -This \fBioctl()\fR sets specific information about the hard disk. -.RE - -.sp -.in +2 -.nf +.Xr ioctl 2 +requests for diagnostics and bad sector information. +Basic to these +.Xr ioctl 2 +requests are the definitions in +.In sys/hdio.h . +.Sh IOCTLS +.Bl -tag -width HDKIOCGTYPE +.It Dv HDKIOCGTYPE +The argument is a pointer to a +.Vt hdk_type +structure (described below). +This +.Xr ioctl 2 +gets specific information from the hard disk. +.It Dv HDKIOCSTYPE +The argument is a pointer to a +.Vt hdk_type +structure (described below). +This +.Xr ioctl 2 +sets specific information about the hard disk. +.El +.Bd -literal -offset 2n /* * Used for drive info */ struct hdk_type { - ushort_t hdkt_hsect; /* hard sector count (read only) */ - ushort_t hdkt_promrev; /* prom revision (read only) */ - uchar_t hdkt_drtype; /* drive type (ctlr specific) */ - uchar_t hdkt_drstat; /* drive status (ctlr specific, ro) */ + ushort_t hdkt_hsect; /* hard sector count (read only) */ + ushort_t hdkt_promrev; /* prom revision (read only) */ + uchar_t hdkt_drtype; /* drive type (ctlr specific) */ + uchar_t hdkt_drstat; /* drive status (ctlr specific, ro) */ }; -.fi -.in -2 - -.sp -.ne 2 -.na -\fB\fBHDKIOCGBAD\fR\fR -.ad -.RS 14n -The argument is a pointer to a \fBhdk_badmap\fR structure (described below). -This \fBioctl()\fR is used to get the bad sector map from the disk. -.RE - -.sp -.ne 2 -.na -\fB\fBHDKIOCSBAD\fR\fR -.ad -.RS 14n -The argument is a pointer to a \fBhdk_badmap\fR structure (described below). -This \fBioctl()\fR is used to set the bad sector map on the disk. -.RE - -.sp -.in +2 -.nf +.Ed +.Bl -tag -width HDKIOCGBAD +.It Dv HDKIOCGBAD +The argument is a pointer to a +.Vt hdk_badmap +structure (described below). +This +.Xr ioctl 2 +is used to get the bad sector map from the disk. +.It Dv HDKIOCSBAD +The argument is a pointer to a +.Vt hdk_badmap +structure (described below). +This +.Xr ioctl 2 +is used to set the bad sector map on the disk. +.El +.Bd -literal -offset 2n /* * Used for bad sector map */ struct hdk_badmap { caddr_t hdkb_bufaddr; /* address of user's map buffer */ }; -.fi -.in -2 - -.sp -.ne 2 -.na -\fB\fBHDKIOCGDIAG\fR\fR -.ad -.RS 15n -The argument is a pointer to a \fBhdk_diag\fR structure (described below). -This \fBioctl()\fR gets the most recent command that failed along with the +.Ed +.Bl -tag -width HDKIOCGDIAG +.It Dv HDKIOCGDIAG +The argument is a pointer to a +.Vt hdk_diag +structure (described below). +This +.Xr ioctl 2 +gets the most recent command that failed along with the sector and error number from the hard disk. -.RE - -.sp -.in +2 -.nf +.El +.Bd -literal -offset 2n /* * Used for disk diagnostics */ struct hdk_diag { - ushort_t hdkd_errcmd; /* most recent command in error */ - daddr_t hdkd_errsect; /* most recent sector in error */ - uchar_t hdkd_errno; /* most recent error number */ - uchar_t hdkd_severe; /* severity of most recent error */ + ushort_t hdkd_errcmd; /* most recent command in error */ + daddr_t hdkd_errsect; /* most recent sector in error */ + uchar_t hdkd_errno; /* most recent error number */ + uchar_t hdkd_severe; /* severity of most recent error */ }; -.fi -.in -2 - -.SH SEE ALSO -.sp -.LP -\fBioctl\fR(2), \fBdkio\fR(7I) +.Ed +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr dkio 7I diff --git a/usr/src/man/man7i/iec61883.7i b/usr/src/man/man7i/iec61883.7i index fd30ad7a7b..a157a0c369 100644 --- a/usr/src/man/man7i/iec61883.7i +++ b/usr/src/man/man7i/iec61883.7i @@ -1,108 +1,130 @@ -'\" te .\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. .\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the .\" fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH IEC61883 7I "Mar 27, 2009" -.SH NAME -iec61883 \- IEC 61883 interfaces -.SH SYNOPSIS -.LP -.nf -#include <sys/av/iec61883.h> -.fi - -.SH DESCRIPTION -.sp -.LP +.Dd July 9, 2018 +.Dt IEC61883 7I +.Os +.Sh NAME +.Nm iec61883 +.Nd IEC 61883 interfaces +.Sh SYNOPSIS +.In sys/av/iec61883.h +.Sh DESCRIPTION The set of interfaces described in this man page can be used to control and exchange data with consumer audio/video devices using protocols specified -in\fIIEC 61883 Consumer Electronic Audio/Video Equipment - Digital -Interface\fR, including Common Isochronous Packet (CIP), Connection Management +in +.%T "IIEC 61883 Consumer Electronic Audio/Video Equipment - Digital Interface" +including Common Isochronous Packet (CIP), Connection Management Procedures (CMP) and Function Control Protocol (FCP). -.sp -.LP -An \fBiec61883\fR compliant driver exports two device nodes for isochronous and -for asynchronous transactions. See the \fBFILES\fR section of this man page for -the namespace definition. -.SS "Isochronous Transfers" -.sp -.LP +.Pp +An +.Nm +compliant driver exports two device nodes for isochronous and +for asynchronous transactions. +See the +.Sx FILES +section of this man page for the namespace definition. +.Ss "Isochronous Transfers" Two methods are provided to receive/transmit isochronous data: using -\fBmmap\fR(2) in combination with \fBioctl\fR(2), and \fBread\fR(2) or -\fBwrite\fR(2). -.SS "Mmap/Ioctl" -.sp -.LP +.Xr mmap 2 +in combination with +.Xr ioctl 2 , +and +.Xr read 2 +or +.Xr write 2 . +.Ss "Mmap/Ioctl" This method provides better performance and finer-grained control than -read/write, and is a method of choice for most applications. The data buffer is +read/write, and is a method of choice for most applications. +The data buffer is mapped into a user process address space, which means no data copying between -the kernel and an application is necessary. Synchronization between user -processes and the driver is performed using \fBioctl\fR(2) commands. -.sp -.LP +the kernel and an application is necessary. +Synchronization between user +processes and the driver is performed using +.Xr ioctl 2 +commands. +.Pp An application allocates resources for isochronous transfer using -\fBIEC61883_ISOCH_INIT\fR. Then the data buffer can be mapped into the process -space using \fBmmap\fR(2). -.sp -.LP +.Dv IEC61883_ISOCH_INIT . +Then the data buffer can be mapped into the process +space using +.Xr mmap 2 . +.Pp A circular data buffer consists of one or more equal size frame buffers (further referred to as frames, unless to avoid ambiguity with AV frames). Frames are numbered starting with zero and are always transferred sequentially. -Frames consist equal sized packets. Each packet contains a CIP header and one -or more data blocks. -.sp -.LP +Frames consist equal sized packets. +Each packet contains a CIP header and one or more data blocks. +.Pp A driver and an application act as a producer and a consumer: producer supplies -\fBfull\fR frames (filled with data) to the consumer, and the producer is not -allowed to access those frames until the consumer claims them \fBempty\fR. -.sp -.LP -A transfer can be initiated and suspended with \fBIEC61883_START\fR and -\fBIEC61883_STOP\fR commands respectively. \fBIEC61883_RECV\fR or -\fBIEC61883_XMIT\fR is used for producer-consumer synchronization. -.SS "Read/Write" -.sp -.LP -Using this method, an application calls \fBread\fR(2) or \fBwrite\fR(2) to -receive or transmit a specified amount of data. Bus-specific overhead, such as -isochronous packet headers, is handled by the driver and is not exposed to -applications. Data returned by \fBread\fR(2) contains CIP headers and data -blocks. Empty packets are not returned by \fBread\fR(2). \fBwrite\fR(2) data -should meet the same requirements. -.sp -.LP -If one or more channels have been allocated since \fBopen\fR(2) (see -\fBIEC61883_ISOCH_INIT\fR), the data is received/transmitted using channel that -was created the last. -.sp -.LP +.Em full +frames (filled with data) to the consumer, and the producer is not +allowed to access those frames until the consumer claims them +.Em empty . +.Pp +A transfer can be initiated and suspended with +.Dv IEC61883_START +and +.Dv IEC61883_STOP +commands respectively. +.Dv IEC61883_RECV +or +.Dv IEC61883_XMIT +is used for producer-consumer synchronization. +.Ss "Read/Write" +Using this method, an application calls +.Xr read 2 +or +.Xr write 2 +to receive or transmit a specified amount of data. +Bus-specific overhead, such as isochronous packet headers, is handled by the driver +and is not exposed to applications. +Data returned by +.Xr read 2 +contains CIP headers and data blocks. +Empty packets are not returned by +.Xr read 2 . +.Xr write 2 +data should meet the same requirements. +.Pp +If one or more channels have been allocated since +.Xr open 2 +(see +.Dv IEC61883_ISOCH_INIT ) , +the data is received/transmitted using channel that was created the last. +.Pp If no channels were allocated, the driver uses the broadcast channel by default -and allocates the default-size data buffer. During transmit, the first packet's -CIP header is used to auto-detect the data format. If it is one of the formats -supported by the driver, it is properly transmitted (with inserted empty -packets and timestamps). -.sp -.LP +and allocates the default-size data buffer. +During transmit, the first packet's CIP header is used to auto-detect the data format. +If it is one of the formats supported by the driver, it is properly transmitted (with +inserted empty packets and timestamps). +.Pp For both methods, if during transmit the driver runs out of data, it transmits empty packets containing only a CIP header of the next to be transmitted -packet, as defined in \fIIEC 61883-1\fR. -.SS "Connection Management Procedures" -.sp -.LP +packet, as defined in +.Em IEC 61883-1 . +.Ss "Connection Management Procedures" Applications wishing to follow Connection Management Procedures (CMP) in -combination with isochronous transfers should use the \fBioctl\fR(2) -\fBIEC61883_PLUG_INIT, IEC61883_PLUG_FINI, IEC61883_PLUG_REG_READ\fR and -\fBIEC61883_PLUG_REG_CAS\fR commands. -.SS "Asynchronous Transactions" -.sp -.LP -\fBread\fR(2), \fBwrite\fR(2), \fBioctl\fR(2), and \fBpoll\fR(2) can be used -with asynchronous nodes. Asynchronous data exchange between a driver and an +combination with isochronous transfers should use the +.Xr ioctl 2 +.Dv IEC61883_PLUG_INIT , +.Dv IEC61883_PLUG_FINI , +.Dv IEC61883_PLUG_REG_READ +and +.Dv IEC61883_PLUG_REG_CAS +commands. +.Ss "Asynchronous Transactions" +.Xr read 2 , +.Xr write 2 , +.Xr ioctl 2 , +and +.Xr poll 2 +can be used +with asynchronous nodes. +Asynchronous data exchange between a driver and an application utilizes a common data structure called asynchronous request (ARQ): -.sp -.in +2 -.nf +.Bd -literal -offset 2n typedef struct iec61883_arq { int arq_type; int arq_len; @@ -112,101 +134,106 @@ typedef struct iec61883_arq { uint8_t buf[8]; } arq_data; } iec61883_arq_t; -.fi -.in -2 -.sp - -.sp -.LP -\fBarq_type\fR contains \fBARQ\fR type: -.sp -.ne 2 -.na -\fB\fBIEC61883_ARQ_FCP_CMD\fR\fR -.ad -.br -.na -\fB\fBIEC61883_ARQ_FCP_RESP\fR\fR -.ad -.sp .6 -.RS 4n -\fBFCP\fR command and response frame respectively. Outgoing frames are sent -using \fBwrite\fR(2), incoming frames are received with \fBread\fR(2). -.sp -See \fIIEC 61883-1\fR for the FCP frame structure definition. -.RE - -.sp -.ne 2 -.na -\fB\fBIEC61883_ARQ_BUS_RESET\fR\fR -.ad -.sp .6 -.RS 4n -Returned by the driver when a bus reset occurs. There is no data associated -with this request type, and \fBarq_len\fR is set to 0. -.RE - -.sp -.LP -If \fBarq_len\fR is 4 or 8, then data should be supplied in -\fBarq_data.quadlet\fR or \fBarq_data.octlet\fR respectively, otherwise up to 8 -bytes can be put in \fBarq_data.buf\fR, with the rest of the data following -immediately after. -.SS "write(2)" -.sp -.LP -For a request to be sent to a target, an \fBiec61883_arq_t\fR structure along -with associated data is passed to the driver using \fBwrite\fR(2). -\fBwrite()\fR blocks until the request is completed. -.SS "read(2)" -.sp -.LP -A driver collects incoming ARQs in the internal buffer. Buffer size can be -changed using the \fBioctl\fR(2) command \fBIEC61883_FCP_SET_IBUF_SIZE\fR. -.sp -.LP -Reading an ARQ takes one or two steps depending on data length. An application -first reads \fBsizeof (iec61883_arq_t)\fR bytes: if \fBarq_len\fR is less than -or equal 4, which is usually the case, no additional step is needed. Otherwise, -the remaining \fBarq_len - 4\fR bytes should be read and concatenated. -.sp -.LP -\fBread\fR(2) blocks until the specified amount of data is available, unless -\fBO_NONBLOCK\fR or \fBO_NDELAY\fR flag was set during \fBopen\fR(2), in which -case \fBread\fR(2) returns immediately. -.SS "poll(2)" -.sp -.LP -Applications can \fBpoll\fR(2) asynchronous nodes on the \fBPOLLIN\fR event. -.SS "Bus Reset" -.sp -.LP +.Ed +.Pp +.Fa arq_type +contains +.Sy ARQ +type: +.Pp +.Bl -tag -width " " -compact +.It Dv IEC61883_ARQ_FCP_CMD +.It Dv IEC61883_ARQ_FCP_RESP +.Pp +.Sy FCP +command and response frame respectively. +Outgoing frames are sent using +.Xr write 2 , +incoming frames are received with +.Xr read 2 . +.Pp +See +.Em IIEC 61883-1 +for the FCP frame structure definition. +.Pp +.It Dv IEC61883_ARQ_BUS_RESET +.Pp +Returned by the driver when a bus reset occurs. +There is no data associated with this request type, and \fBarq_len\fR is set to 0. +.El +.Pp +If +.Fa arq_len +is 4 or 8, then data should be supplied in +.Fa arq_data.quadlet +or +.Fa arq_data.octlet +respectively, otherwise up to 8 bytes can be put in +.Fa arq_data.buf , +with the rest of the data following immediately after. +.Ss "write(2)" +For a request to be sent to a target, an +.Vt iec61883_arq_t +structure along with associated data is passed to the driver using +.Xr write 2 . +.Xr write 2 +blocks until the request is completed. +.Ss "read(2)" +A driver collects incoming ARQs in the internal buffer. +Buffer size can be changed using the +.Xr ioctl 2 +command +.Vt IEC61883_FCP_SET_IBUF_SIZE . +.Pp +Reading an ARQ takes one or two steps depending on data length. +An application +first reads +.Ql sizeof (iec61883_arq_t) +bytes: if +.Fa arq_len +is less than or equal 4, which is usually the case, no additional step is needed. +Otherwise, +the remaining +.Ql arq_len - 4 +bytes should be read and concatenated. +.Pp +.Xr read 2 +blocks until the specified amount of data is available, unless +.Dv O_NONBLOCK +or +.Dv O_NDELAY +flag was set during +.Xr open 2 , +in which case +.Xr read 2 +returns immediately. +.Ss "poll(2)" +Applications can +.Xr poll 2 +asynchronous nodes on the +.Dv POLLIN +event. +.Ss "Bus Reset" In case of a bus reset, the driver notifies an application by generating an -\fBARQ\fR of type \fBIEC61883_ARQ_BUS_RESET\fR. -.sp -.LP +.Sy ARQ +of type +.Dv IEC61883_ARQ_BUS_RESET . +.Pp If there were established isochronous connections before bus reset, the driver -attempts to restore all connections as described in \fIIEC 61883\fR and resume -any active transfers that were in progress. -.SH IOCTLS -.sp -.LP +attempts to restore all connections as described in +.Em IEC 61883 +and resume any active transfers that were in progress. +.Sh IOCTLS The following commands only apply to isochronous nodes: -.sp -.ne 2 -.na -\fB\fBIEC61883_ISOCH_INIT\fR\fR -.ad -.sp .6 -.RS 4n +.Bl -tag -width " " +.It Dv IEC61883_ISOCH_INIT +.Pp This command allocates a data buffer and isochronous resources (if necessary) -for the isochronous transfer. The argument is a pointer to the structure: -.sp -.in +2 -.nf +for the isochronous transfer. +The argument is a pointer to the structure: +.Bd -literal -offset 2n typedef struct iec61883_isoch_init { - int ii_version; /* interface version */ + int ii_version; /* interface version */ int ii_pkt_size; /* packet size */ int ii_frame_size; /* packets/frame */ int ii_frame_cnt; /* # of frames */ @@ -221,325 +248,272 @@ typedef struct iec61883_isoch_init { int ii_flags; /* flags */ int ii_handle; /* isoch handle */ int ii_frame_rcnt; /* # of frames */ - off_t *ii_mmap_off /* mmap offset */ + off_t *ii_mmap_off /* mmap offset */ int ii_rchannel; /* channel */ int ii_error; /* error code */ } iec61883_isoch_init_t; -.fi -.in -2 -.sp - -\fBii_version\fR should be set to \fBIEC61883_V1_0\fR. -.sp -The driver attempts to allocate a data buffer consisting of \fBii_frame_cnt\fR -frames, with \fBii_frame_size\fR packets in each frame. Packet size in bytes is -specified by \fBii_pkt_size\fR specifies and should be a multiple of 512 and -compatible with \fBii_bus_speed\fR. -.sp -\fBii_direction\fR can take one of the following values: -.sp -.ne 2 -.na -\fB\fBIEC61883_DIR_RECV\fR\fR -.ad -.sp .6 -.RS 4n +.Ed +.Pp +.Fa ii_version +should be set to +.Dv IEC61883_V1_0 . +.Pp +The driver attempts to allocate a data buffer consisting of +.Fa ii_frame_cnt +frames, with +.Fa ii_frame_size +packets in each frame. +Packet size in bytes is specified by +.Fa ii_pkt_size +specifies and should be a multiple of 512 and compatible with +.Fa ii_bus_speed . +.Pp +.Fa ii_direction +can take one of the following values: +.Bl -tag -width "IEC61883_DIR_RECV" +.It Dv IEC61883_DIR_RECV Receiving isochronous data. -.RE - -.sp -.ne 2 -.na -\fB\fBIEC61883_DIR_XMIT\fR\fR -.ad -.sp .6 -.RS 4n +.It Dv IEC61883_DIR_XMIT Transmitting isochronous data. -.RE - -\fBii_bus_speed\fR chooses bus speed to be used and can be either -\fBIEC61883_S100, IEC61883_S200\fR or \fBIEC61883_S400\fR. -.sp -\fBii_channel\fR is a mask that specifies an isochronous channel number to be -used, with the \fIN\fRth bit representing channel \fIN\fR. When transmitting -data, several bits can be set at a time, in which case the driver chooses one, -for example, \fB0x3FF\fR means a range from 0 to 9. In case of receive, only -one bit can be set. -.sp -\fBii_dbs\fR specifies data block size in quadlets, for example, DBS value for -\fBSD-DVCR\fR is \fB0x78\fR. Refer to \fIIEC 61883\fR for more details on DBS. -.sp -ii_fn specifies fraction number, which defines the number of blocks in which a -source packet is divided. Allowed values are from 0 to 3. Refer to IEC 61883 +.El +.Pp +.Fa ii_bus_speed +chooses bus speed to be used and can be either +.Dv IEC61883_S100 , +.Dv IEC61883_S200 +or +.Dv IEC61883_S400 . +.Pp +.Fa ii_channel +is a mask that specifies an isochronous channel number to be +used, with the +.Em N Ns th +bit representing channel +.Em N . +When transmitting data, several bits can be set at a time, in which case the +driver chooses one, for example, +.Sy 0x3FF +means a range from 0 to 9. +In case of receive, only one bit can be set. +.Pp +.Fa ii_dbs +specifies data block size in quadlets, for example, DBS value for +.Dv SD-DVCR +is +.Sy 0x78 . +Refer to +.Em IEC 61883 +for more details on DBS. +.Pp +.Fa ii_fn +specifies fraction number, which defines the number of blocks in which a +source packet is divided. +Allowed values are from 0 to 3. +Refer to +.Em IEC 61883 for more details on FN. -.sp +.Pp Data rate expected by the AV device can be lower than the bus speed, in which case the driver has to periodically insert empty packets into the data stream -to avoid device buffer overflows. This rate is specified with a fraction N/D, -set by \fBii_rate_n\fR and \fBii_rate_d\fR respectively. Any integer numbers -can be used, or the following predefined constants: -.sp -.ne 2 -.na -\fB\fBIEC61883_RATE_N_DV_NTSC IEC61883_RATE_D_DV_NTSC\fR\fR -.ad -.sp .6 -.RS 4n -Data rate expected by \fBDV-NTSC\fR devices. -.RE - -.sp -.ne 2 -.na -\fB\fBIEC61883_RATE_N_DV_PAL IEC61883_RATE_D_DV_PAL\fR\fR -.ad -.sp .6 -.RS 4n -Data rate expected by \fBDV-PAL\fR devices. -.RE - +to avoid device buffer overflows. +This rate is specified with a fraction N/D, +set by +.Fa ii_rate_n +and +.Fa ii_rate_d +respectively. +Any integer numbers can be used, or the following predefined constants: +.Pp +.Bl -tag -width "IEC61883_RATE_N_DV_NTSC" -compact +.It Dv IEC61883_RATE_N_DV_NTSC +.It Dv IEC61883_RATE_D_DV_NTSC +Data rate expected by +.Sy DV-NTSC +devices. +.Pp +.It Dv IEC61883_RATE_N_DV_PAL +.It Dv IEC61883_RATE_D_DV_PAL +Data rate expected by +.Sy DV-PAL +devices. +.El +.Pp During data transmission, a timestamp based on the current value of the cycle -timer is usually required. \fBii_ts_mode\fR defines timestamp mode to be used: -.sp -.ne 2 -.na -\fB\fBIEC61883_TS_SYT\fR\fR -.ad -.sp .6 -.RS 4n +timer is usually required. +.Fa ii_ts_mode +defines timestamp mode to be used: +.Bl -tag -width IEC61883_TS_NONE +.It Dv IEC61883_TS_SYT Driver puts a timestamp in the SYT field of the first CIP header of each frame. -.RE - -.sp -.ne 2 -.na -\fB\fBIEC61883_TS_NONE\fR\fR -.ad -.sp .6 -.RS 4n +.It Dv IEC61883_TS_NONE No timestamps. -.RE - -\fBii_dbs, ii_fn, ii_rate_n, ii_rate_d\fR and \fBii_ts_mode\fR are only -required for transmission. In other case these should be set to 0. -.sp -\fBii_flags\fR should be set to 0. -.sp -If command succeeds, \fBii_handle\fR contains a handle that should be used with -other isochronous commands. \fBii_frame_rcnt\fR contains the number of -allocated frames (can be less than \fBii_frame_cnt\fR). \fBii_mmap_off\fR -contains an offset to be used in \fBmmap\fR(2), for example, to map an entire -data receive buffer: -.sp -.in +2 -.nf +.El +.Pp +.Fa ii_dbs , +.Fa ii_fn , +.Fa ii_rate_n , +.Fa ii_rate_d +and +.Fa ii_ts_mode +are only required for transmission. +In other case these should be set to 0. +.Pp +.Fa ii_flags +should be set to 0. +.Pp +If command succeeds, +.Fa ii_handle +contains a handle that should be used with other isochronous commands. +.Fa ii_frame_rcnt +contains the number of allocated frames (can be less than +.Fa ii_frame_cnt ) . +.Fa ii_mmap_off +contains an offset to be used in +.Xr mmap 2 , +for example, to map an entire data receive buffer: +.Bd -literal -offset 2n pa = mmap(NULL, init.ii_pkt_size * init.ii_frame_size * init.ii_frame_rcnt, PROT_READ, MAP_PRIVATE, fd, init.ii_mmap_off); -.fi -.in -2 -.sp - -\fBii_rchannel\fR contains channel number. -.sp -In case of command success, \fBii_error\fR is set to 0; otherwise one of the -following values can be returned: -.sp -.ne 2 -.na -\fB\fBIEC61883_ERR_NOMEM\fR\fR -.ad -.sp .6 -.RS 4n +.Ed +.Pp +.Fa ii_rchannel +contains channel number. +.Pp +In case of command success, +.Fa ii_error +is set to 0; otherwise one of the following values can be returned: +.Bl -tag -width IEC61883_ERR_NOCHANNEL +.It Dv IEC61883_ERR_NOMEM Not enough memory for the data buffer. -.RE - -.sp -.ne 2 -.na -\fB\fBIEC61883_ERR_NOCHANNEL\fR\fR -.ad -.sp .6 -.RS 4n +.It Dv IEC61883_ERR_NOCHANNEL Cannot allocate isochronous channel. -.RE - -.sp -.ne 2 -.na -\fB\fBIEC61883_ERR_PKT_SIZE\fR\fR -.ad -.sp .6 -.RS 4n +.It Dv IEC61883_ERR_PKT_SIZE Packet size is not allowed at this bus speed. -.RE - -.sp -.ne 2 -.na -\fB\fBIEC61883_ERR_VERSION\fR\fR -.ad -.sp .6 -.RS 4n +.It Dv IEC61883_ERR_VERSION Interface version is not supported. -.RE - -.sp -.ne 2 -.na -\fB\fBIEC61883_ERR_INVAL\fR\fR -.ad -.sp .6 -.RS 4n +.It Dv IEC61883_ERR_INVAL One or more the parameters are invalid -.RE - -.sp -.ne 2 -.na -\fB\fBIEC61883_ERR_OTHER\fR\fR -.ad -.sp .6 -.RS 4n +.It Dv IEC61883_ERR_OTHER Unspecified error type. -.RE - -.RE - -.sp -.ne 2 -.na -\fB\fBIEC61883_ISOCH_FINI\fR\fR -.ad -.sp .6 -.RS 4n -Argument is a handle returned by \fBIEC61883_ISOCH_INIT\fR. This command frees -any resources associated with this handle. There must be no active transfers +.El +.It Dv IEC61883_ISOCH_FINI +.Pp +Argument is a handle returned by +.Dv IEC61883_ISOCH_INIT . +This command frees any resources associated with this handle. +There must be no active transfers and the data buffer must be unmapped; otherwise the command fails. -.RE - -.sp -.ne 2 -.na -\fB\fBIEC61883_START\fR\fR -.ad -.sp .6 -.RS 4n -This command starts an isochronous transfer. The argument is a handle returned -by \fBIEC61883_ISOCH_INIT\fR. -.RE - -.sp -.ne 2 -.na -\fB\fBIEC61883_STOP\fR\fR -.ad -.sp .6 -.RS 4n -This command stops an isochronous transfer. The argument is a handle returned -by \fBIEC61883_ISOCH_INIT\fR. -.RE - -.sp -.ne 2 -.na -\fB\fBIEC61883_RECV\fR\fR -.ad -.sp .6 -.RS 4n -This command is used to receive full frames and return empty frames to the -driver. The argument is a pointer to the structure: -.sp -.in +2 -.nf +.It Dv IEC61883_START +.Pp +This command starts an isochronous transfer. +The argument is a handle returned +by +.Dv IEC61883_ISOCH_INIT . +.It Dv IEC61883_STOP +.Pp +This command stops an isochronous transfer. +The argument is a handle returned by +.Dv IEC61883_ISOCH_INIT . +.It Dv IEC61883_RECV +.Pp +This command is used to receive full frames and return empty frames to the driver. +The argument is a pointer to the structure: +.Bd -literal -offset 2n typedef struct iec61883_recv { - int rx_handle; /* isoch handle */ - int rx_flags; /* flags */ -iec61883_xfer_t rx_xfer; /* xfer params */ + int rx_handle; /* isoch handle */ + int rx_flags; /* flags */ + iec61883_xfer_t rx_xfer; /* xfer params */ } iec61883_recv_t; typedef struct iec61883_xfer { int xf_empty_idx; /* first empty frame */ - int xf_empty_cnt; /* empty frame count */ + int xf_empty_cnt; /* empty frame count */ int xf_full_idx; /* first full frame */ int xf_full_cnt; /* full frame count */ int xf_error; /* error */ } iec61883_xfer_t; -.fi -.in -2 -.sp - -\fBrx_flags\fR should be set to 0. -.sp -An application sets \fBxf_empty_idx\fR and \fBxf_empty_cnt\fR to indicate -frames it no longer needs. E.g. if a buffer consists of 6 frames, -\fBxf_empty_idx\fR is 4, \fBxf_empty_cnt\fR is 3 - means that frames 4, 5 and 0 -can now be reused by the driver. If there are no empty frames, for example, the -first time this command is called, \fBxf_empty_cnt\fR should be set to 0. -.sp -When the command returns, \fBxf_full_idx\fR and \fBxf_full_cnt\fR specifies the -frames that are full. \fBxf_error\fR is always 0. -.sp +.Ed +.Pp +.Fa rx_flags +should be set to 0. +.Pp +An application sets +.Fa xf_empty_idx +and +.Fa xf_empty_cnt +to indicate frames it no longer needs. +E. g. if a buffer consists of 6 frames, +.Fa xf_empty_idx +is 4, +.Fa xf_empty_cnt +is 3 - means that frames 4, 5 and 0 can now be reused by the driver. +If there are no empty frames, for example, the +first time this command is called, +.Fa xf_empty_cnt +should be set to 0. +.Pp +When the command returns, +.Fa xf_full_idx +and +.Fa xf_full_cnt +specifies the frames that are full. +.Fa xf_error +is always 0. +.Pp In general, AV frame boundaries are not aligned with the frame buffer boundaries, because the first received packet might not be the first packet of an AV frame, and, in contrast with the read/write method, the driver does not remove empty CIP packets. -.sp +.Pp Applications should detect empty packets by comparing adjacent packets' continuity counters (DBC field of the CIP header). -.RE - -.sp -.ne 2 -.na -\fB\fBIEC61883_XMIT\fR\fR -.ad -.sp .6 -.RS 4n +.It Dv IEC61883_XMIT +.Pp This command is used to transmit full frames and get more empty frames from the -driver. The argument is a pointer to the structure: -.sp -.in +2 -.nf +driver. +The argument is a pointer to the structure: +.Bd -literal -offset 2n typedef struct iec61883_xmit { int tx_handle; /* isoch handle */ int tx_flags; /* flags */ iec61883_xfer_t tx_xfer; /* xfer params */ int tx_miss_cnt; /* missed cycles */ } iec61883_xmit_t; -.fi -.in -2 -.sp - -\fBtx_flags\fR should be set to zero. -.sp -The application sets \fBxf_full_idx\fR and \fBxf_full_cnt\fR to specify frames -it wishes to transmit. If there are no frames to transmit (e.g. the first time -this command is called), \fBxf_full_cnt\fR should be set to 0. -.sp -When the command returns, \fBxf_empty_idx\fR and \fBxf_empty_cnt\fR specifies -empty frames which can be to transmit more data. \fBxf_error\fR is always 0. -.sp -\fBtx_miss_cnt\fR contains the number of isochronous cycles missed since last -transfer due to data buffer under run. This can happen when an application does -not supply data fast enough. -.sp +.Ed +.Pp +.Fa tx_flags +should be set to zero. +.Pp +The application sets +.Fa xf_full_idx +and +.Fa xf_full_cnt +to specify frames it wishes to transmit. +If there are no frames to transmit (e. g. the first time this command is called), +.Fa xf_full_cnt +should be set to 0. +.Pp +When the command returns, +.Fa xf_empty_idx +and +.Fa xf_empty_cnt +specifies empty frames which can be to transmit more data. +.Fa xf_error +is always 0. +.Pp +.Fa tx_miss_cnt +contains the number of isochronous cycles missed since last +transfer due to data buffer under run. +This can happen when an application does not supply data fast enough. For the purposes of time stamping, the driver considers the first packet in a frame buffer to be the first packet of an AV frame. -.RE - -.sp -.ne 2 -.na -\fB\fBIEC61883_PLUG_INIT\fR\fR -.ad -.sp .6 -.RS 4n -This command returns a handle for the specified plug. The argument is a pointer +.It Dv IEC61883_PLUG_INIT +.Pp +This command returns a handle for the specified plug. +The argument is a pointer to the structure: -.sp -.in +2 -.nf +.Bd -literal -offset 2n typedef struct iec61883_plug_init { int pi_ver; /* interface version */ int pi_loc; /* plug location */ @@ -549,239 +523,152 @@ typedef struct iec61883_plug_init { int pi_handle; /* plug handle */ int pi_rnum; /* plug number */ } iec61883_plug_init_t; -.fi -.in -2 -.sp - -\fBpi_ver\fR should be set to \fBIEC61883_V1_0\fR. -.sp -\fBpi_loc\fR specifies plug location: -.sp -.ne 2 -.na -\fB\fBIEC61883_LOC_LOCAL\fR\fR -.ad -.sp .6 -.RS 4n -On the local unit (local plug). A plug control register (PCR) is allocated. +.Ed +.Pp +.Fa pi_ver +should be set to +.Dv IEC61883_V1_0 . +.Pp +.Fa pi_loc +specifies plug location: +.Bl -tag -width IEC61883_LOC_REMOTE +.It Dv IEC61883_LOC_LOCAL +On the local unit (local plug). +A plug control register (PCR) is allocated. Command fails if the plug already exists -.RE - -.sp -.ne 2 -.na -\fB\fBIEC61883_LOC_REMOTE\fR\fR -.ad -.sp .6 -.RS 4n -On the remote unit (remote plug). The plug should exist on the remote unit, +.It Dv IEC61883_LOC_REMOTE +On the remote unit (remote plug). +The plug should exist on the remote unit, otherwise the command fails. -.RE - -\fBpi_type\fR specifies isochronous plug type: -.sp -.ne 2 -.na -\fB\fBIEC61883_PLUG_IN IEC61883_PLUG_OUT\fR\fR -.ad -.sp .6 -.RS 4n +.El +.Pp +.Fa pi_type +specifies isochronous plug type: +.Pp +.Bl -tag -width " " -compact +.It Dv IEC61883_PLUG_IN +.It Dv IEC61883_PLUG_OUT +.Pp Input or output plugs. -.RE - -.sp -.ne 2 -.na -\fB\fBIEC61883_PLUG_MASTER_IN IEC61883_PLUG_MASTER_OUT\fR\fR -.ad -.sp .6 -.RS 4n -Master input or master output plug. These plugs always exist on the local unit. -.RE - -\fBpi_num\fR specifies plug number. This should be 0 for master plugs, and from -0 to 31 for input/output plugs. Alternatively, a special value -\fBIEC61883_PLUG_ANY\fR can be used to let the driver choose a free plug -number, create the plug and return the number in \fBpi_rnum\fR. -.sp -\fBpi_flags\fR should be set to 0. -.sp -If the command succeeds, \fBpi_handle\fR contains a handle that should be used -with other plug commands. -.RE - -.sp -.ne 2 -.na -\fB\fBIEC61883_PLUG_FINI\fR\fR -.ad -.sp .6 -.RS 4n -Argument is a handle returned by \fBIEC61883_PLUG_INIT\fR. This command frees -any resources associated with this handle, including the PCR. -.RE - -.sp -.ne 2 -.na -\fB\fBIEC61883_PLUG_REG_READ\fR\fR -.ad -.sp .6 -.RS 4n -Read plug register value. The argument is a pointer to the structure: -.sp -.in +2 -.nf +.Pp +.It Dv IEC61883_PLUG_MASTER_IN +.It Dv IEC61883_PLUG_MASTER_OUT +.Pp +Master input or master output plug. +These plugs always exist on the local unit. +.El +.Pp +.Fa pi_num +specifies plug number. +This should be 0 for master plugs, and from 0 to 31 for input/output plugs. +Alternatively, a special value +.Dv IEC61883_PLUG_ANY +can be used to let the driver choose a free plug +number, create the plug and return the number in +.Fa pi_rnum . +.Pp +.Fa pi_flags +should be set to 0. +.Pp +If the command succeeds, +.Fa pi_handle +contains a handle that should be used with other plug commands. +.It Dv IEC61883_PLUG_FINI +.Pp +Argument is a handle returned by +.Dv IEC61883_PLUG_INIT . +This command frees any resources associated with this handle, including the PCR. +.It Dv IEC61883_PLUG_REG_READ +.Pp +Read plug register value. +The argument is a pointer to the structure: +.Bd -literal -offset 2n typedef struct iec61883_plug_reg_val { int pr_handle; /* plug handle */ - uint32_t pr_val; /* register value */ + uint32_t pr_val; /* register value */ } iec61883_plug_reg_val_t; -.fi -.in -2 -.sp - -\fBpr_handle\fR is a handle returned by \fBIEC61883_PLUG_INIT\fR. Register -value is returned in \fBpr_val\fR. -.RE - -.sp -.ne 2 -.na -\fB\fBIEC61883_PLUG_REG_CAS\fR\fR -.ad -.sp .6 -.RS 4n -Atomically compare and swap plug register value. The argument is a pointer to -the structure: -.sp -.in +2 -.nf +.Ed +.Pp +.Fa pr_handle +is a handle returned by +.Dv IEC61883_PLUG_INIT . +Register +value is returned in +.Fa pr_val . +.It Dv IEC61883_PLUG_REG_CAS +.Pp +Atomically compare and swap plug register value. +The argument is a pointer to the structure: +.Bd -literal -offset 2n typedef struct iec61883_plug_reg_lock { int pl_handle; /* plug handle */ uint32_t pl_arg; /* compare arg */ uint32_t pl_data; /* write value */ UINT32_t pl_old; /* original value */ } iec61883_plug_reg_lock_t; -.fi -.in -2 -.sp - -pr_handle is a handle returned by IEC61883_PLUG_INIT. -.sp -Original register value is compared with pl_arg and if they are equal, register -value is replaced with pl_data. In any case, the original value is stored in -pl_old. -.RE - -.sp -.LP +.Ed +.Pp +.Fa pr_handle +is a handle returned by IEC61883_PLUG_INIT. +.Pp +Original register value is compared with +.Fa pl_arg +and if they are equal, register value is replaced with +.Fa pl_data . +In any case, the original value is stored in +.Fa pl_old . +.El +.Pp The following commands only apply to asynchronous nodes: -.sp -.ne 2 -.na -\fB\fBIEC61883_ARQ_GET_IBUF_SIZE\fR\fR -.ad -.sp .6 -.RS 4n -This command returns current incoming ARQ buffer size. The argument is a -pointer to \fBint\fR. -.RE - -.sp -.ne 2 -.na -\fB\fBIEC61883_ARQ_SET_IBUF_SIZE\fR\fR -.ad -.sp .6 -.RS 4n -This command changes incoming ARQ buffer size. The argument is the new buffer +.Bl -tag -width " " +.It Dv IEC61883_ARQ_GET_IBUF_SIZE +.Pp +This command returns current incoming ARQ buffer size. +The argument is a +pointer to +.Vt int . +.It Dv IEC61883_ARQ_SET_IBUF_SIZE +.Pp +This command changes incoming ARQ buffer size. +The argument is the new buffer size in bytes. -.RE - -.SH FILES -.sp -.ne 2 -.na -\fB\fB/dev/av/N/async\fR\fR -.ad -.RS 19n +.El +.Sh FILES +.Bl -tag -width /dev/av/N/async +.It Pa /dev/av/N/async Device node for asynchronous data -.RE - -.sp -.ne 2 -.na -\fB\fB/dev/av/N/isoch\fR\fR -.ad -.RS 19n +.It Pa /dev/av/N/isoch Device has been disconnected -.RE - -.SH ERRORS -.sp -.ne 2 -.na -\fB\fBEIO\fR\fR -.ad -.RS 10n +.El +.Sh ERRORS +.Bl -tag -width EFAULT +.It Er EIO Bus operation failed. -.sp DMA failure. -.RE - -.sp -.ne 2 -.na -\fB\fBEFAULT\fR\fR -.ad -.RS 10n -\fBioctl\fR(2) argument points to an illegal address. -.RE - -.sp -.ne 2 -.na -\fB\fBEINVAL\fR\fR -.ad -.RS 10n +.It Er EFAULT +.Xr ioctl 2 +argument points to an illegal address. +.It Er EINVAL Invalid argument or argument combination. -.RE - -.sp -.ne 2 -.na -\fB\fBENODEV\fR\fR -.ad -.RS 10n +.It Er ENODEV Device has been disconnected. -.RE - -.SH ATTRIBUTES -.sp -.LP -See \fBattributes\fR(5) for descriptions of the following attributes: -.sp - -.sp -.TS -box; -c | c -l | l . -ATTRIBUTE TYPE ATTRIBUTE VALUE -_ -Architecture All -_ -Stability level Committed -.TE - -.SH SEE ALSO -.sp -.LP -\fBioctl\fR(2), \fBmmap\fR(2), \fBopen\fR(2), \fBpoll\fR(2), \fBread\fR(2), -\fBwrite\fR(2), \fBattributes\fR(5), \fBav1394\fR(7D) -.sp -.LP -\fIIEC 61883 Consumer audio/video equipment - Digital interface\fR -.sp -.LP -\fIIEEE Std 1394-1995 Standard for a High Performance Serial Bus\fR +.El +.Sh ARCHITECTURE +All +.Sh INTERFACE STABILITY +Committed +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr mmap 2 , +.Xr open 2 , +.Xr poll 2 , +.Xr read 2 , +.Xr write 2 , +.Xr attributes 5 , +.Xr av1394 7D +.Rs +.%B IIEC 61883 Consumer audio/video equipment - Digital interface +.Re +.Rs +.%B IEEE Std 1394-1995 Standard for a High Performance Serial Bus +.Re diff --git a/usr/src/man/man7i/ipnat.7i b/usr/src/man/man7i/ipnat.7i index 551790aa7e..5aa277f05f 100644 --- a/usr/src/man/man7i/ipnat.7i +++ b/usr/src/man/man7i/ipnat.7i @@ -1,262 +1,296 @@ -'\" te .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved -.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. -.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. -.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH IPNAT 7I "May 22, 2008" -.SH NAME -ipnat \- IP Filter/NAT module interface -.SH DESCRIPTION -.sp -.LP -The \fBipnat\fR device provides interfaction with the NAT features of the -Solaris IPFilter. -.SH APPLICATION PROGRAMMING INTERFACE -.sp -.LP +.\" Copyright (c) 2017, Joyent, Inc. +.\" The contents of this file are subject to the terms of the +.\" Common Development and Distribution License (the "License"). +.\" You may not use this file except in compliance with the License. +.\" +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE +.\" or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions +.\" and limitations under the License. +.\" +.\" When distributing Covered Code, include this CDDL HEADER in each +.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. +.\" If applicable, add the following below this CDDL HEADER, with the +.\" fields enclosed by brackets "[]" replaced with your own identifying +.\" information: Portions Copyright [yyyy] [name of copyright owner] +.Dd October 23, 2017 +.Dt IPNAT 7I +.Os +.Sh NAME +.Nm ipnat +.Nd IP Filter/NAT module interface +.Sh DESCRIPTION +The +.Sy ipnat +device provides interfaction with the NAT features of the Solaris IPFilter. +.Sh APPLICATION PROGRAMMING INTERFACE The NAT features programming model is a component of the Solaris IP Filter and -is accessed via the NAT device file \fB/dev/ipnat\fR. Opening the device for +is accessed via the NAT device file +.Pa /dev/ipnat . +Opening the device for reading or writing determines which ioctl calls can be successfully made. -.SH IOCTLS -.sp -.LP -The caller must construct a \fBipfobj\fR structure when issuing a -\fBSIOCGNATL\fR or \fBSIOCSTPUT\fR. The \fBipfobj\fR structure is then passed -to the ioctl call and is filled out with ipfo_type set to \fBIPFOBJ_value\fR. -\fBIPFOBJ_ value\fR provides a matching name for the structure, while ipfo_size -is set to the total size of the structure being passed and ipfo_ptr is set to -the structure address. The ipfo_rev structure should be set to the current -value of IPFILTER_VERSION, while ipfo_offset and ipfo_xxxpad should be set to -0. -.sp -.in +2 -.nf +.Sh IOCTLS +The caller must construct a +.Vt ipfobj +structure when issuing a +.Sy SIOCGNATL +or +SIOCSTPUT +ioctl. +The +.Vt ipfobj +structure is then passed +to the ioctl call and is filled out with +.Fa ipfo_type +set to +.Dv IPFOBJ_ Ns value . +.Dv IPFOBJ_ Ns value +provides a matching name for the structure, while +.Fa ipfo_size +is set to the total size of the structure being passed and +.Fa ipfo_ptr +is set to the structure address. +The +.Fa ipfo_rev +structure should be set to the current value of +.Dv IPFILTER_VERSION , +while +.Fa ipfo_offset +and +.Fa ipfo_xxxpad +should be set to 0. +.Bd -literal -offset 2n /* - * Structure used with SIOCGNATL/SIOCSTPUT. - */ - /* - * Object structure description. For passing through in ioctls. - */ - typedef struct ipfobj { - u_32_t ipfo_rev; /* IPFilter version (IPFILTER_VERSION) */ - u_32_t ipfo_size; /* size of object at ipfo_ptr */ - void *ipfo_ptr; /* pointer to object */ - int ipfo_type; /* type of object being pointed to */ - int ipfo_offset; /* bytes from ipfo_ptr where to start */ - u_char ipfo_xxxpad[32]; /* reserved for future use */ - } ipfobj_t; + * Structure used with SIOCGNATL/SIOCSTPUT. + */ - #define IPFILTER_VERSION 4010901 /* IPFilter version */ - #define IPFOBJ_NATSAVE 8 /* struct nat_save */ - #define IPFOBJ_NATLOOKUP 9 /* struct natlookup */ -.fi -.in -2 - -.sp -.LP -The following ioctl() calls may be used to manipulate the ipnat sub-system -inside of ipf. Note that the ipnat driver only accept calls from applications -using the same data model as the kernel. In other words, 64-bit kernels can -only accept calls from 64-bit applications. Calls from 32-bit applications fail -with \fBEINVAL\fR. -.sp -.ne 2 -.na -\fB\fBSIOCSTLCK\fR\fR -.ad -.RS 13n +/* + * Object structure description. For passing through in ioctls. + */ +typedef struct ipfobj { + u_32_t ipfo_rev; /* IPFilter version (IPFILTER_VERSION) */ + u_32_t ipfo_size; /* size of object at ipfo_ptr */ + void *ipfo_ptr; /* pointer to object */ + int ipfo_type; /* type of object being pointed to */ + int ipfo_offset; /* bytes from ipfo_ptr where to start */ + u_char ipfo_xxxpad[32]; /* reserved for future use */ +} ipfobj_t; + +#define IPFILTER_VERSION 4010901 /* IPFilter version */ +#define IPFOBJ_NATSAVE 8 /* struct nat_save */ +#define IPFOBJ_NATLOOKUP 9 /* struct natlookup */ +.Ed +.Pp +The following +.Xr ioctl 2 +calls may be used to manipulate the ipnat sub-system inside of ipf. +Note that the ipnat driver only accept calls from applications +using the same data model as the kernel. +In other words, 64-bit kernels can only accept calls from 64-bit applications. +Calls from 32-bit applications fail +with +.Er EINVAL . +.Bl -tag -width SIOCSTLCK +.It Dv SIOCSTLCK Set or clear the NAT lock to prevent table updates attributable to packet flow-through. -.RE - -.sp -.ne 2 -.na -\fB\fBSIOCGNATL\fR\fR -.ad -.RS 13n +.It Dv SIOCGNATL Search the NAT table for the rdr entry that matches the fields in the natlookup -structure. The caller must populate the structure with the address/port -information of the accepted TCP connection (nl_inip, nl_inport) and the -address/port information of the peer (nl_outip, nl_outport). The nl_flags field -must have the IPN_TCP option set. All other fields must be set to 0. If the -call succeeds, nl_realip and nl_realport are set to the real destination -address and port, respectively. The nl_inport and nl_outport fields must be in -host byte order. -.sp -If \fBIPN_FINDFORWARD\fR is set in nl_flags, a check is made to see if it is +structure. +The caller must populate the structure with the address/port +information of the accepted TCP connection +.Pq Fa nl_inip , Fa nl_inport +and the +address/port information of the peer +.Pq Fa nl_outip , Fa nl_outport . +The +.Fa nl_flags +field must have the +.Dv IPN_TCP +option set. +All other fields must be set to 0. +If the call succeeds, +.Fa nl_realip +and +.Fa nl_realport +are set to the real destination address and port, respectively. +The +.Fa nl_inport +and +.Fa nl_outport +fields must be in host byte order. +If +.Dv IPN_FINDFORWARD +is set in +.Fa nl_flags , +a check is made to see if it is possible to create an outgoing NAT session by checking if a packet coming from -(nl_realip,nl_realport) and destined for (nl_outip,nl_outport) can be -translated. If translation is possible, the flag remains set, otherwise it is +.Pq Fa nl_realip , Fa nl_realport +and destined for +.Pq Fa nl_outip , Fa nl_outport +can be translated. +If translation is possible, the flag remains set, otherwise it is cleared in the structure returned to the caller. -.sp -.in +2 -.nf - /* - * Structure used with SIOCGNATL. - */ - typedef struct natlookup { - i6addr_t nl_inipaddr; - i6addr_t nl_outipaddr; - i6addr_t nl_realipaddr; - int nl_v; - int nl_flags; - u_short nl_inport; - u_short nl_outport; - u_short nl_realport; - } natlookup_t - - #define nl_inip nl_inipaddr.in4 - #define nl_outip nl_outipaddr.in4 - #define nl_realip nl_realipaddr.in4 - #define nl_inip6 nl_inipaddr.in6 - #define nl_outip6 nl_outipaddr.in6 - #define nl_realip6 nl_realipaddr.in6 - - /* - * Accepted values for nl_flags - */ - #define IPN_TCP 0x00001 - #define IPN_FINDFORWARD 0x400000 -.fi -.in -2 - -.RE +.Bd -literal -offset indent +/* + * Structure used with SIOCGNATL. + */ +typedef struct natlookup { + i6addr_t nl_inipaddr; + i6addr_t nl_outipaddr; + i6addr_t nl_realipaddr; + int nl_v; + int nl_flags; + u_short nl_inport; + u_short nl_outport; + u_short nl_realport; +} natlookup_t + +#define nl_inip nl_inipaddr.in4 +#define nl_outip nl_outipaddr.in4 +#define nl_realip nl_realipaddr.in4 +#define nl_inip6 nl_inipaddr.in6 +#define nl_outip6 nl_outipaddr.in6 +#define nl_realip6 nl_realipaddr.in6 -.sp -.ne 2 -.na -\fB\fBSIOCSTPUT\fR\fR -.ad -.RS 13n -Move a NAT mapping structure from user space into the kernel. This ioctl is -used by \fBipfs\fR(1M) to restore NAT sessions saved in -\fB/var/db/ipf/ipnat.ipf\fR. The nat_save structure must have its ipn_nat and -ipn_ipnat structures filled out correctly. Fields not assigned a value must be -initialised to 0. All pointer fields are adjusted, as appropriate, once the +/* + * Accepted values for nl_flags + */ +#define IPN_TCP 0x00001 +#define IPN_FINDFORWARD 0x400000 +.Ed +.It Dv SIOCSTPUT +Move a NAT mapping structure from user space into the kernel. +This ioctl is used by +.Xr ipfs 1M +to restore NAT sessions saved in +.Pa /var/db/ipf/ipnat.ipf . +The +.Vt nat_save +structure must have its +.Fa ipn_nat +and +.Fa ipn_ipnat +structures filled out correctly. +Fields not assigned a value must be initialised to 0. +All pointer fields are adjusted, as appropriate, once the structure is passed into the kernel and none are preserved. -.sp +.Pp To create a translation, the following fields must be set: -.br -.in +2 -Interface name - The interface name on which the host is to be exited must be -set in nat_ifnames[0]. -.in -2 -.br -.in +2 -Local IP address and port number - The connection's local IP address and port -number are stored in network byte order using nat_inip/nat_inport. -.in -2 -.br -.in +2 -Destination address/port - The destination address/port are stored in -nat_oip/nat_oport. -.in -2 -.br -.in +2 -Target address/port - The translation's target address/port is stored in -nat_outip/nat_outport. -.in -2 +.\" Force item bodies to next line using 2n width +.Bl -tag -width 2n +.It "Interface name" +The interface name on which the host is to be exited must be +set in +.Fa nat_ifnames[0] . +.It "Local IP address and port number" +The connection's local IP address and port +number are stored in network byte order using +.Fa nat_inip Ns / Ns Fa nat_inport . +.It "Destination address/port" +The destination address/port are stored in +.Fa nat_oip Ns / Ns Fa nat_oport . +.It "Target address/port" +The translation's target address/port is stored in +.Fa nat_outip Ns / Ns Fa nat_outport . +.El +.Pp The caller must also precalculate the checksum adjustments necessary to -complete the translation and store those values in nat_sumd (delta required for -TCP header) and nat_ipsumd (delta required for IP header). -.sp -.in +2 -.nf +complete the translation and store those values in +.Fa nat_sumd +(delta required for TCP header) and +.Fa nat_ipsumd +(delta required for IP header). +.Bd -literal -offset indent /* - * Structures used with SIOCSTPUT. - */ - typedef struct nat_save { - void *ipn_next; - struct nat ipn_nat; - struct ipnat ipn_ipnat; - struct frentry ipn_fr; - int ipn_dsize; - char ipn_data[4]; - } nat_save_t; - - typedef struct nat { - ipfmutex_t nat_lock; - struct nat *nat_next; - struct nat **nat_pnext; - struct nat *nat_hnext[2]; - struct nat **nat_phnext[2]; - struct hostmap *nat_hm; - void *nat_data; - struct nat **nat_me; - struct ipstate *nat_state; - struct ap_session *nat_aps; - frentry_t *nat_fr; - struct ipnat *nat_ptr; - void *nat_ifps[2]; - void *nat_sync; - ipftqent_t nat_tqe; - u_32_t nat_flags; - u_32_t nat_sumd[2]; - u_32_t nat_ipsumd; - u_32_t nat_mssclamp; - i6addr_t nat_inip6; - i6addr_t nat_outip6; - i6addr_t nat_oip6; - U_QUAD_T nat_pkts[2]; - U_QUAD_T nat_bytes[2]; - union { - udpinfo_t nat_unu; - tcpinfo_t nat_unt; - icmpinfo_t nat_uni; - greinfo_t nat_ugre; - } nat_un; - u_short nat_oport; - u_short nat_use; - u_char nat_p; - int nat_dir; - int nat_ref; - int nat_hv[2]; - char nat_ifnames[2][LIFNAMSIZ]; - int nat_rev; - int nat_v; - } nat_t; - - #define nat_inip nat_inip6.in4 - #define nat_outip nat_outip6.in4 - #define nat_oip nat_oip6.in4 - #define nat_inport nat_un.nat_unt.ts_sport - #define nat_outport nat_un.nat_unt.ts_dport - /* - * Values for nat_dir - */ - #define NAT_INBOUND 0 - #define NAT_OUTBOUND 1 - /* - * Definitions for nat_flags - */ - #define NAT_TCP 0x0001 /* IPN_TCP */ -.fi -.in -2 - -.RE - -.SH EXAMPLES -.sp -.LP -The following example shows how to prepare and use \fBSIOCSTPUT\fR to insert a -NAT session directly into the table. Note that the usual TCP/IP code is omitted -is this example. -.sp -.LP -In the code segment below, incoming_fd is the TCP connection file descriptor -that is accepted as part of the redirect process, while remote_fd is the -outgoing TCP connection to the remote server being translated back to the + * Structures used with SIOCSTPUT. + */ +typedef struct nat_save { + void *ipn_next; + struct nat ipn_nat; + struct ipnat ipn_ipnat; + struct frentry ipn_fr; + int ipn_dsize; + char ipn_data[4]; +} nat_save_t; + +typedef struct nat { + ipfmutex_t nat_lock; + struct nat *nat_next; + struct nat **nat_pnext; + struct nat *nat_hnext[2]; + struct nat **nat_phnext[2]; + struct hostmap *nat_hm; + void *nat_data; + struct nat **nat_me; + struct ipstate *nat_state; + struct ap_session *nat_aps; + frentry_t *nat_fr; + struct ipnat *nat_ptr; + void *nat_ifps[2]; + void *nat_sync; + ipftqent_t nat_tqe; + u_32_t nat_flags; + u_32_t nat_sumd[2]; + u_32_t nat_ipsumd; + u_32_t nat_mssclamp; + i6addr_t nat_inip6; + i6addr_t nat_outip6; + i6addr_t nat_oip6; + U_QUAD_T nat_pkts[2]; + U_QUAD_T nat_bytes[2]; + union { + udpinfo_t nat_unu; + tcpinfo_t nat_unt; + icmpinfo_t nat_uni; + greinfo_t nat_ugre; + } nat_un; + u_short nat_oport; + u_short nat_use; + u_char nat_p; + int nat_dir; + int nat_ref; + int nat_hv[2]; + char nat_ifnames[2][LIFNAMSIZ]; + int nat_rev; + int nat_v; +} nat_t; + +#define nat_inip nat_inip6.in4 +#define nat_outip nat_outip6.in4 +#define nat_oip nat_oip6.in4 +#define nat_inport nat_un.nat_unt.ts_sport +#define nat_outport nat_un.nat_unt.ts_dport +/* + * Values for nat_dir + */ +#define NAT_INBOUND 0 +#define NAT_OUTBOUND 1 +/* + * Definitions for nat_flags + */ +#define NAT_TCP 0x0001 /* IPN_TCP */ +.Ed +.El +.Sh EXAMPLES +The following example shows how to prepare and use +.Fa SIOCSTPUT +to insert a NAT session directly into the table. +Note that the usual TCP/IP code is omitted is this example. +.Pp +In the code segment below, +.Fa incoming_fd +is the TCP connection file descriptor +that is accepted as part of the redirect process, while +.Fa remote_fd +is the outgoing TCP connection to the remote server being translated back to the original IP address/port pair. -.LP -Note - -.sp -.RS 2 +.Pp +Note \(em The following ipnat headers must be included before you can use the code shown in this example: -.sp -.in +2 -.nf +.Bd -literal -offset 2n #include <netinet/in.h> #include <arpa/inet.h> #include <net/if.h> @@ -266,197 +300,137 @@ in this example: #include <netinet/ip_nat.h> #include <string.h> #include <fcntl.h> -.fi -.in -2 - -.RE -.LP -Note - -.sp -.RS 2 +.Ed +.Pp +Note \(em In the example below, various code fragments have been excluded to enhance clarity. -.RE -.sp -.in +2 -.nf +.Bd -literal -offset 2n int - translate_connection(int incoming_fd) - { - struct sockaddr_in usin; - struct natlookup nlp; - struct nat_save ns; - struct ipfobj obj; - struct nat *nat; - int remote_fd; - int nat_fd; - int onoff; +translate_connection(int incoming_fd) +{ + struct sockaddr_in usin; + struct natlookup nlp; + struct nat_save ns; + struct ipfobj obj; + struct nat *nat; + int remote_fd; + int nat_fd; + int onoff; + + memset(&ns, 0, sizeof(ns)); + nat = &ns.ipn_nat + + namelen = sizeof(usin); + getsockname(remote_fd, (struct sockaddr *)&usin, &namelen); + + namelen = sizeof(sin); + getpeername(incoming_fd, (struct sockaddr *) &sin, &namelen); + + namelen = sizeof(sloc); + getsockname(incoming_fd, (struct sockaddr *) &sloc, &namelen); + + bzero((char *) &obi, sizeof(obj)); + obj.ipfo_rev = IPFILTER_VERSION; + obj.ipfo_size = sizeof(nlp); + obj.ipfo_ptr = &nip; + obj.ipfo_type = IPFOBJ_NATLOOKUP; - memset(&ns, 0, sizeof(ns)); - nat = &ns.ipn_nat - - namelen = sizeof(usin); - getsockname(remote_fd, (struct sockaddr *)&usin, &namelen); - - namelen = sizeof(sin); - getpeername(incoming_fd, (struct sockaddr *) &sin, &namelen); - - namelen = sizeof(sloc); - getsockname(incoming_fd, (struct sockaddr *) &sloc, &namelen); - - bzero((char *) &obi, sizeof(obj)); - obj.ipfo_rev = IPFILTER_VERSION; - obj.ipfo_size = sizeof(nlp); - obj.ipfo_ptr = &nip; - obj.ipfo_type = IPFOBJ_NATLOOKUP; - - /* - * Build up the NAT natlookup structure. - */ - bzero((char *) &nlp, sizeof(nlp)); - nlp.nl_outip = sin.sin_addr; - nlp.nl_inip = sloc.sin_addr; - nlp.nl_flags = IPN_TCP; - nlp.nl_outport = ntohs(sin.sin_port); - nlp.nl_inport = ntohs(sloc.sin_port); - - /* - * Open the NAT device and lookup the mapping pair. - */ - nat_fd = open(IPNAT_NAME, O_RDWR); - if (ioctl(nat_fd, SIOCGNATL, &obj) != 0) - return -1; - - nat->nat_inip = usin.sin_addr; - nat->nat_outip = nlp.nl_outip; - nat->nat_oip = nlp.nl_realip; - - sum1 = LONG_SUM(ntohl(usin.sin_addr.s_addr)) + - ntohs(usin.sin_port); - sum2 = LONG_SUM(ntohl(nat->nat_outip.s_addr)) + - ntohs(nlp.nl_outport); - CALC_SUMD(sum1, sum2, sumd); - nat->nat_sumd[0] = (sumd & 0xffff) + (sumd >> 16); - nat->nat_sumd[1] = nat->nat_sumd[0]; + /* + * Build up the NAT natlookup structure. + */ + bzero((char *) &nlp, sizeof(nlp)); + nlp.nl_outip = sin.sin_addr; + nlp.nl_inip = sloc.sin_addr; + nlp.nl_flags = IPN_TCP; + nlp.nl_outport = ntohs(sin.sin_port); + nlp.nl_inport = ntohs(sloc.sin_port); - sum1 = LONG_SUM(ntohl(usin.sin_addr.s_addr)); - sum2 = LONG_SUM(ntohl(nat->nat_outip.s_addr)); - CALC_SUMD(sum1, sum2, sumd); - nat->nat_ipsumd = (sumd & 0xffff) + (sumd >> 16); + /* + * Open the NAT device and lookup the mapping pair. + */ + nat_fd = open(IPNAT_NAME, O_RDWR); + if (ioctl(nat_fd, SIOCGNATL, &obj) != 0) + return -1; - nat->nat_inport = usin.sin_port; - nat->nat_outport = nlp.nl_outport; - nat->nat_oport = nlp.nl_realport; + nat->nat_inip = usin.sin_addr; + nat->nat_outip = nlp.nl_outip; + nat->nat_oip = nlp.nl_realip; - nat->nat_flags = IPN_TCPUDP; + sum1 = LONG_SUM(ntohl(usin.sin_addr.s_addr)) + + ntohs(usin.sin_port); + sum2 = LONG_SUM(ntohl(nat->nat_outip.s_addr)) + + ntohs(nlp.nl_outport); + CALC_SUMD(sum1, sum2, sumd); + nat->nat_sumd[0] = (sumd & 0xffff) + (sumd >> 16); + nat->nat_sumd[1] = nat->nat_sumd[0]; - /* - * Prepare the ipfobj structure, accordingly. - */ - bzero((char *)&obi, sizeof(obj)); - obj.ipfo_rev = IPFILTER_VERSION; - obj.ipfo_size = sizeof(*nsp); - obj.ipfo_ptr = nsp; - obj.ipfo_type = IPFOBJ_NATSAVE; + sum1 = LONG_SUM(ntohl(usin.sin_addr.s_addr)); + sum2 = LONG_SUM(ntohl(nat->nat_outip.s_addr)); + CALC_SUMD(sum1, sum2, sumd); + nat->nat_ipsumd = (sumd & 0xffff) + (sumd >> 16); - onoff = 1; - if (ioctl(nat_fd, SIOCSTPUT, &obj) != 0) - fprintf(stderr, "Error occurred\en"); + nat->nat_inport = usin.sin_port; + nat->nat_outport = nlp.nl_outport; + nat->nat_oport = nlp.nl_realport; - return connect(rem_fd, (struct sockaddr ) &usin, sizeof(usin)); - } -.fi -.in -2 + nat->nat_flags = IPN_TCPUDP; -.SH ERRORS -.sp -.ne 2 -.na -\fBEPERM\fR -.ad -.RS 10n -The device has been opened for reading only. To succeed, the ioctl call must be -opened for both reading and writing. The call may be returned if it is -privileged and the calling process did not assert {\fBPRIV_SYS_NET_CONFIG\fR} + /* + * Prepare the ipfobj structure, accordingly. + */ + bzero((char *)&obi, sizeof(obj)); + obj.ipfo_rev = IPFILTER_VERSION; + obj.ipfo_size = sizeof(*nsp); + obj.ipfo_ptr = nsp; + obj.ipfo_type = IPFOBJ_NATSAVE; + + onoff = 1; + if (ioctl(nat_fd, SIOCSTPUT, &obj) != 0) + fprintf(stderr, "Error occurred\en"); + + return connect(rem_fd, (struct sockaddr)&usin, sizeof(usin)); +} +.Ed +.Sh ERRORS +.Bl -tag -width Er +.It Er EPERM +The device has been opened for reading only. +To succeed, the ioctl call must be opened for both reading and writing. +The call may be returned if it is +privileged and the calling process did not assert +.Brq Sy PRIV_SYS_NET_CONFIG in the effective set. -.RE - -.sp -.ne 2 -.na -\fBENOMEM\fR -.ad -.RS 10n -More memory was allocated than the kernel can provide. The call may also be -returned if the application inserts a NAT entry that exceeds the hash bucket -chain's maximum length. -.RE - -.sp -.ne 2 -.na -\fBEFAULT\fR -.ad -.RS 10n +.It Er ENOMEM +More memory was allocated than the kernel can provide. +The call may also be returned if the application inserts a NAT entry that +exceeds the hash bucket chain's maximum length. +.It Er EFAULT The calling process specified an invalid pointer in the ipfobj structure. -.RE - -.sp -.ne 2 -.na -\fBEINVAL\fR -.ad -.RS 10n +.It Er EINVAL The calling process detected a parameter or field set to an unacceptable value. -.RE - -.sp -.ne 2 -.na -\fBEEXIST\fR -.ad -.RS 10n -The calling process, via \fBSIOCSTPUT\fR, attempted to add a NAT entry that -already exists in the NAT table. -.RE - -.sp -.ne 2 -.na -\fBESRCH\fR -.ad -.RS 10n -The calling process called \fBSIOCSTPUT\fR before setting the SI_NEWFR flag and -providing a pointer in the nat_fr field that cannot be found in the current -rule set. -.RE - -.sp -.ne 2 -.na -\fBEACESS\fR -.ad -.RS 10n -The calling process issued a \fBSIOCSTPUT\fR before issuing a SIOCSTLCK. -.RE - -.SH ATTRIBUTES -.sp -.LP -See \fBattributes\fR(5) for descriptions of the following attributes: -.sp - -.sp -.TS -box; -c | c -l | l . -ATTRIBUTE TYPE ATTRIBUTE VALUE -_ -Interface Stability Committed -.TE - -.SH SEE ALSO -.sp -.LP -\fBipfs\fR(1M), \fBipnat\fR(1M), \fBioctl\fR(2), \fBattributes\fR(5) +.It Er EEXIST +The calling process, via +.Dv SIOCSTPUT , +attempted to add a NAT entry that already exists in the NAT table. +.It Er ESRCH +The calling process called +.Dv SIOCSTPUT +before setting the +.Dv SI_NEWFR +flag and providing a pointer in the +.Fa nat_fr +field that cannot be found in the current rule set. +.It Er EACESS +The calling process issued a +.Dv SIOCSTPUT +before issuing a +.Dv SIOCSTLCK . +.El +.Sh INTERFACE STABILITY +Committed +.Sh SEE ALSO +.Xr ipfs 1M , +.Xr ipnat 1M , +.Xr ioctl 2 , +.Xr attributes 5 diff --git a/usr/src/man/man7i/mhd.7i b/usr/src/man/man7i/mhd.7i index ddfc5d3c30..a6eafc81be 100644 --- a/usr/src/man/man7i/mhd.7i +++ b/usr/src/man/man7i/mhd.7i @@ -1,404 +1,386 @@ -'\" te .\" Copyright (c) 2005 Sun Microsystems, Inc. All Rights Reserved. -.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. -.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. -.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH MHD 7I "Mar 18, 2011" -.SH NAME -mhd \- multihost disk control operations -.SH SYNOPSIS -.LP -.nf -\fB#include\fR \fB<sys/mhd.h>\fR -.fi - -.SH DESCRIPTION -.sp -.LP -The \fBmhd\fR \fBioctl\fR(2) control access rights of a multihost disk, using +.\" Copyright (c) 2017, Joyent, Inc. +.\" The contents of this file are subject to the terms of the +.\" Common Development and Distribution License (the "License"). +.\" You may not use this file except in compliance with the License. +.\" +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE +.\" or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions +.\" and limitations under the License. +.\" +.\" When distributing Covered Code, include this CDDL HEADER in each +.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. +.\" If applicable, add the following below this CDDL HEADER, with the +.\" fields enclosed by brackets "[]" replaced with your own identifying +.\" information: Portions Copyright [yyyy] [name of copyright owner] +.Dd October 23, 2017 +.Dt MHD 7I +.Os +.Sh NAME +.Nm mhd +.Nd multihost disk control operations +.Sh SYNOPSIS +.In sys/mhd.h +.Sh DESCRIPTION +The +.Nm +.Xr ioctl 2 +control access rights of a multihost disk, using disk reservations on the disk device. -.sp -.LP -The stability level of this interface (see \fBattributes\fR(5)) is evolving. As -a result, the interface is subject to change and you should limit your use of +.Pp +The stability level of this interface (see +.Xr attributes 5 ) +is evolving. +As a result, the interface is subject to change and you should limit your use of it. -.sp -.LP +.Pp The mhd ioctls fall into two major categories: (1) ioctls for non-shared -multihost disks and (2) ioctls for shared multihost disks. -.sp -.LP -One ioctl, \fBMHIOCENFAILFAST\fR, is applicable to both non-shared and shared -multihost disks. It is described after the first two categories. -.sp -.LP +multihost disks and (2) ioctls for shared multihost disks. +.Pp +One ioctl, +.Dv MHIOCENFAILFAST , +is applicable to both non-shared and shared multihost disks. +It is described after the first two categories. +.Pp All the ioctls require root privilege. -.sp -.LP +.Pp For all of the ioctls, the caller should obtain the file descriptor for the -device by calling \fBopen\fR(2) with the \fBO_NDELAY\fR flag; without the -\fBO_NDELAY\fR flag, the open may fail due to another host already having a -conflicting reservation on the device. Some of the ioctls below permit the -caller to forcibly clear a conflicting reservation held by another host, -however, in order to call the ioctl, the caller must first obtain the open file -descriptor. -.SS "Non-shared multihost disks" -.sp -.LP -Non-shared multihost disks ioctls consist of \fBMHIOCTKOWN\fR, -\fBMHIOCRELEASE\fR, \fBHIOCSTATUS\fR, and \fBMHIOCQRESERVE\fR. These ioctl -requests control the access rights of non-shared multihost disks. A non-shared -multihost disk is one that supports serialized, mutually exclusive I/O mastery -by the connected hosts. This is in contrast to the shared-disk model, in which +device by calling +.Xr open 2 +with the +.Dv O_NDELAY +flag; without the +.Dv O_NDELAY +flag, the open may fail due to another host already having a +conflicting reservation on the device. +Some of the ioctls below permit the caller to forcibly clear a conflicting +reservation held by another host, however, in order to call the ioctl, the +caller must first obtain the open file descriptor. +.Ss "Non-shared multihost disks" +Non-shared multihost disks ioctls consist of +.Dv MHIOCTKOWN , +.Dv MHIOCRELEASE , +.Dv HIOCSTATUS , +and +.Dv MHIOCQRESERVE . +These ioctl requests control the access rights of non-shared multihost disks. +A non-shared multihost disk is one that supports serialized, mutually exclusive +I/O mastery by the connected hosts. +This is in contrast to the shared-disk model, in which concurrent access is allowed from more than one host (see below). -.sp -.LP +.Pp A non-shared multihost disk can be in one of two states: -.RS +4 -.TP -.ie t \(bu -.el o +.Bl -bullet -width indent +.It Exclusive access state, where only one connected host has I/O access -.RE -.RS +4 -.TP -.ie t \(bu -.el o -Non-exclusive access state, where all connected hosts have I/O access. An -external hardware reset can cause the disk to enter the non-exclusive access +.It +Non-exclusive access state, where all connected hosts have I/O access. +An external hardware reset can cause the disk to enter the non-exclusive access state. -.RE -.sp -.LP +.El +.Pp Each multihost disk driver views the machine on which it's running as the -"local host"; each views all other machines as "remote hosts". For each I/O or -ioctl request, the requesting host is the local host. -.sp -.LP -Note that the non-shared ioctls are designed to work with SCSI-2 disks. The +.Dq local host ; +each views all other machines as +.Dq remote hosts . +For each I/O or ioctl request, the requesting host is the local host. +.Pp +Note that the non-shared ioctls are designed to work with SCSI-2 disks. +The SCSI-2 RESERVE/RELEASE command set is the underlying hardware facility in the device that supports the non-shared ioctls. -.sp -.LP +.Pp The function prototypes for the non-shared ioctls are: -.sp -.in +2 -.nf -ioctl(fd, MHIOCTKOWN); -ioctl(fd, MHIOCRELEASE); -ioctl(fd, MHIOCSTATUS); -ioctl(fd, MHIOCQRESERVE); -.fi -.in -2 - -.sp -.ne 2 -.na -\fB\fBMHIOCTKOWN\fR \fR -.ad -.RS 18n +.Bd -literal -offset 2n +.Fn ioctl fd MHIOCTKOWN ; +.Fn ioctl fd MHIOCRELEASE ; +.Fn ioctl fd MHIOCSTATUS ; +.Fn ioctl fd MHIOCQRESERVE ; +.Ed +.Bl -tag -width MHIOCQRESERVE +.It Dv MHIOCTKOWN Forcefully acquires exclusive access rights to the multihost disk for the local -host. Revokes all access rights to the multihost disk from remote hosts. +host. +Revokes all access rights to the multihost disk from remote hosts. Causes the disk to enter the exclusive access state. -.sp +.Pp Implementation Note: Reservations (exclusive access rights) broken via random resets should be reinstated by the driver upon their detection, for example, in the automatic probe function described below. -.RE - -.sp -.ne 2 -.na -\fB\fBMHIOCRELEASE\fR \fR -.ad -.RS 18n +.It Dv MHIOCRELEASE Relinquishes exclusive access rights to the multihost disk for the local host. -On success, causes the disk to enter the non- exclusive access state. -.RE - -.sp -.ne 2 -.na -\fB\fBMHIOCSTATUS\fR \fR -.ad -.RS 18n +On success, causes the disk to enter the non- exclusive access state. +.It Dv MHIOCSTATUS Probes a multihost disk to determine whether the local host has access rights -to the disk. Returns \fB0\fR if the local host has access to the disk, -\fB1\fR if it doesn't, and \fB-1\fR with errno set to \fBEIO\fR if the probe -failed for some other reason. -.RE - -.sp -.ne 2 -.na -\fB\fBMHIOCQRESERVE\fR \fR -.ad -.RS 18n -Issues, simply and only, a SCSI-2 Reserve command. If the attempt to reserve +to the disk. +Returns +.Sy 0 +if the local host has access to the disk, +.Sy 1 +if it doesn't, and +.Sy -1 +with +.Va errno +set to +.Er EIO +if the probe failed for some other reason. +.It Dv MHIOCQRESERVE +Issues, simply and only, a SCSI-2 Reserve command. +If the attempt to reserve fails due to the SCSI error Reservation Conflict (which implies that some other -host has the device reserved), then the ioctl will return \fB-1\fR with errno -set to \fBEACCES\fR. The \fBMHIOCQRESERVE\fR ioctl does NOT issue a bus device -reset or bus reset prior to attempting the SCSI-2 reserve command. It also +host has the device reserved), then the ioctl will return +.Sy -1 +with +.Va errno +set to +.Er EACCES . +The +.Dv MHIOCQRESERVE +ioctl does NOT issue a bus device +reset or bus reset prior to attempting the SCSI-2 reserve command. +It also does not take care of re-instating reservations that disappear due to bus resets or bus device resets; if that behavior is desired, then the caller can -call \fBMHIOCTKOWN\fR after the \fBMHIOCQRESERVE\fR has returned success. If +call +.Dv MHIOCTKOWN +after the +.Dv MHIOCQRESERVE +has returned success. +If the device does not support the SCSI-2 Reserve command, then the ioctl returns -\fB-1\fR with \fBerrno\fR set to \fBENOTSUP.\fR The \fBMHIOCQRESERVE\fR ioctl -is intended to be used by high-availability or clustering software for a -"quorum" disk, hence, the "Q" in the name of the ioctl. -.RE - -.SS "Shared Multihost Disks" -.sp -.LP -Shared multihost disks ioctls control access to shared multihost disks. The -ioctls are merely a veneer on the SCSI-3 Persistent Reservation facility. +.Er -1 +with +.Va errno +set to +.Er ENOTSUP . +The +.Dv MHIOCQRESERVE +ioctl is intended to be used by high-availability or clustering software for a +.Dq quorum +disk, hence, the +.Dq Q +in the name of the ioctl. +.El +.Ss "Shared Multihost Disks" +Shared multihost disks ioctls control access to shared multihost disks. +The ioctls are merely a veneer on the SCSI-3 Persistent Reservation facility. Therefore, the underlying semantic model is not described in detail here, see -instead the SCSI-3 standard. The SCSI-3 Persistent Reservations support the +instead the SCSI-3 standard. +The SCSI-3 Persistent Reservations support the concept of a group of hosts all sharing access to a disk. -.sp -.LP +.Pp The function prototypes and descriptions for the shared multihost ioctls are as follows: -.sp -.ne 2 -.na -\fB\fBioctl\fR(\fBfd\fR, \fBMHIOCGRP_INKEYS\fR, (\fBmhioc_inkeys_t\fR) -\fI*k\fR\fB);\fR\fR -.ad -.sp .6 -.RS 4n -Issues the SCSI-3 command Persistent Reserve In Read Keys to the device. On -input, the field \fBk->li\fR should be initialized by the caller with -\fBk->li.listsize\fR reflecting how big of an array the caller has allocated -for the \fBk->li.list\fR field and with \fBk->li.listlen\fR \fB==\fR \fB0.\fR -On return, the field \fBk->li.listlen\fR is updated to indicate the number of +.Bl -tag -width 1n +.It Fn ioctl fd MHIOCGRP_INKEYS "(mhioc_inkeys_t *)k" +.Pp +Issues the SCSI-3 command Persistent Reserve In Read Keys to the device. +On input, the field +.Fa k->li +should be initialized by the caller with +.Fa k->li.listsize +reflecting how big of an array the caller has allocated for the +.Fa k->lilist +field and with +.Ql k->li.listlen\& ==\& 0 . +On return, the field +.Fa k->li.listlen +is updated to indicate the number of reservation keys the device currently has: if this value is larger than -\fBk->li.listsize\fR then that indicates that the caller should have passed a -bigger \fBk->li.list\fR array with a bigger \fBk->li.listsize.\fR The number of -array elements actually written by the callee into \fBk->li.list\fR is the -minimum of \fBk->li.listlen\fR and \fBk->li.listsize.\fR The field -k->generation is updated with the generation information returned by the SCSI-3 -Read Keys query. If the device does not support SCSI-3 Persistent Reservations, -then this ioctl returns \fB-1\fR with \fBerrno\fR set to \fBENOTSUP\fR. -.RE - -.sp -.ne 2 -.na -\fB\fBioctl\fR(\fBfd\fR, \fBMHIOCGRP_INRESV\fR, (\fBmhioc_inresvs_t\fR) -\fI*r\fR\fB);\fR\fR -.ad -.sp .6 -.RS 4n +.Fa k->li.listsize +then that indicates that the caller should have passed a bigger +.Fa k->li.list +array with a bigger +.Fa k->li.listsize . +The number of array elements actually written by the callee into +.Fa k->li.list +is the minimum of +.Fa k->li.listlen +and +.Fa k->li.listsize . +The field +.Fa k->generation +is updated with the generation information returned by the SCSI-3 +Read Keys query. +If the device does not support SCSI-3 Persistent Reservations, +then this ioctl returns +.Sy -1 +with +.Va errno +set to +.Er ENOTSUP . +.It Fn ioctl fd MHIOCGRP_INRESV "(mhioc_inresvs_t *)r" +.Pp Issues the SCSI-3 command Persistent Reserve In Read Reservations to the -device. Remarks similar to \fBMHIOCGRP_INKEYS\fR apply to the array -manipulation. If the device does not support SCSI-3 Persistent Reservations, -then this ioctl returns \fB-1\fR with \fBerrno\fR set to \fBENOTSUP\fR. -.RE - -.sp -.ne 2 -.na -\fB\fBioctl\fR(\fBfd\fR, \fBMHIOCGRP_REGISTER\fR, (\fBmhioc_register_t\fR) -\fI*r\fR\fB);\fR\fR -.ad -.sp .6 -.RS 4n -Issues the SCSI-3 command Persistent Reserve Out Register. The fields of -structure \fIr\fR are all inputs; none of the fields are modified by the ioctl. -The field \fBr->aptpl\fR should be set to true to specify that registrations +device. +Remarks similar to +.Dv MHIOCGRP_INKEYS +apply to the array manipulation. +If the device does not support SCSI-3 Persistent Reservations, +then this ioctl returns +.Sy -1 +with +.Va errno +set to +.Er ENOTSUP . +.It Fn ioctl fd MHIOCGRP_REGISTER "(mhioc_register_t *)r" +.Pp +Issues the SCSI-3 command Persistent Reserve Out Register. +The fields of structure +.Va r +are all inputs; none of the fields are modified by the ioctl. +The field +.Fa r->aptpl +should be set to true to specify that registrations and reservations should persist across device power failures, or to false to specify that registrations and reservations should be cleared upon device power -failure; true is the recommended setting. The field \fBr->oldkey\fR is the key -that the caller believes the device may already have for this host initiator; -if the caller believes that that this host initiator is not already registered -with this device, it should pass the special key of all zeros. To achieve the -effect of unregistering with the device, the caller should pass its current key -for the \fBr->oldkey\fR field and an \fBr->newkey\fR field containing the -special key of all zeros. If the device returns the SCSI error code -Reservation Conflict, this ioctl returns \fB-1\fR with \fBerrno\fR set to -\fBEACCES\fR. -.RE - -.sp -.ne 2 -.na -\fB\fBioctl\fR(\fBfd\fR, \fBMHIOCGRP_RESERVE\fR, (\fBmhioc_resv_desc_t\fR) -\fI*r\fR\fB);\fR\fR -.ad -.sp .6 -.RS 4n -Issues the SCSI-3 command Persistent Reserve Out Reserve. The fields of -structure \fIr\fR are all inputs; none of the fields are modified by the ioctl. +failure; true is the recommended setting. +The field +.Fa r->oldkey +is the key that the caller believes the device may already have for this host +initiator; if the caller believes that that this host initiator is not already +registered with this device, it should pass the special key of all zeros. +To achieve the effect of unregistering with the device, the caller should pass +its current key for the +.Fa r->oldkey +field and an +.Fa r->newkey +field containing the special key of all zeros. +If the device returns the SCSI error code +Reservation Conflict, this ioctl returns +.Sy -1 +with +.Va errno +set to +.Er EACCES . +.It Fn ioctl fd MHIOCGRP_RESERVE "(mhioc_resv_desc_t *)r" +.Pp +Issues the SCSI-3 command Persistent Reserve Out Reserve. +The fields of +structure +.Va r +are all inputs; none of the fields are modified by the ioctl. If the device returns the SCSI error code Reservation Conflict, this ioctl -returns \fB-1\fR with \fBerrno\fR set to \fBEACCES.\fR -.RE - -.sp -.ne 2 -.na -\fB\fBioctl\fR(\fBfd\fR, \fBMHIOCGRP_PREEMPTANDABORT\fR, -(\fBmhioc_preemptandabort_t\fR) \fI*r\fR\fB);\fR\fR -.ad -.sp .6 -.RS 4n -Issues the SCSI-3 command Persistent Reserve Out Preempt-And-Abort. The fields -of structure \fIr\fR are all inputs; none of the fields are modified by the -ioctl. The key of the victim host is specified by the field -\fBr->victim_key\fR. The field \fBr->resvdesc\fR supplies the preempter's key -and the reservation that it is requesting as part of the SCSI-3 -Preempt-And-Abort command. If the device returns the SCSI error code -Reservation Conflict, this ioctl returns \fB-1\fR with \fBerrno\fR set to -\fBEACCES.\fR -.RE - -.sp -.ne 2 -.na -\fB\fBioctl\fR(\fBfd\fR, \fBMHIOCGRP_PREEMPT\fR, -(\fBmhioc_preemptandabort_t\fR) \fI*r\fR\fB);\fR\fR -.ad -.sp .6 -.RS 4n -Similar to \fBMHIOCGRP_PREEMPTANDABORT\fR, but instead issues the SCSI-3 -command Persistent Reserve Out Preempt. (Note: This command is not -implemented). -.RE - -.sp -.ne 2 -.na -\fB\fBioctl\fR(\fBfd\fR, \fBMHIOCGRP_CLEAR\fR, (\fBmhioc_resv_key_t\fR) -\fI*r\fR\fB);\fR\fR -.ad -.sp .6 -.RS 4n -Issues the SCSI-3 command Persistent Reserve Out Clear. The input parameter -\fIr\fR is the reservation key of the caller, which should have been already -registered with the device, by an earlier call to \fBMHIOCGRP_REGISTER\fR. -.RE - -.sp -.LP +returns +.Sy -1 +with +.Va errno +set to +.Er EACCES . +.It Fn ioctl fd MHIOCGRP_PREEMPTANDABORT "(mhioc_preemptandabort_t *)r" +.Pp +Issues the SCSI-3 command Persistent Reserve Out Preempt-And-Abort. +The fields +of structure +.Va r +are all inputs; none of the fields are modified by the ioctl. +The key of the victim host is specified by the field +.Fa r->victim_key . +The field +.Fa r->resvdesc +supplies the preempter's key and the reservation that it is requesting as part +of the SCSI-3 Preempt-And-Abort command. +If the device returns the SCSI error code +Reservation Conflict, this ioctl returns +.Sy -1 +with +.Va errno +set to +.Er EACCES . +.It Fn ioctl fd MHIOCGRP_PREEMPT "(mhioc_preemptandabort_t *)r" +.Pp +Similar to +.Dv MHIOCGRP_PREEMPTANDABORT , +but instead issues the SCSI-3 command Persistent Reserve Out Preempt. +(Note: This command is not implemented). +.It Fn ioctl fd MHIOCGRP_CLEAR "(mhioc_resv_key_t *)r" +Issues the SCSI-3 command Persistent Reserve Out Clear. +The input parameter +.Va r +is the reservation key of the caller, which should have been already +registered with the device, by an earlier call to +.Dv MHIOCGRP_REGISTER . +.El +.Pp For each device, the non-shared ioctls should not be mixed with the Persistent Reserve Out shared ioctls, and vice-versa, otherwise, the underlying device is likely to return errors, because SCSI does not permit SCSI-2 reservations to be -mixed with SCSI-3 reservations on a single device. It is, however, legitimate +mixed with SCSI-3 reservations on a single device. +It is, however, legitimate to call the Persistent Reserve In ioctls, because these are query only. -Issuing the \fBMHIOCGRP_INKEYS\fR ioctl is the recommended way for a caller to -determine if the device supports SCSI-3 Persistent Reservations (the ioctl -will return \fB-1\fR with \fBerrno\fR set to \fBENOTSUP\fR if the device does -not). -.SS "MHIOCENFAILFAST Ioctl" -.sp -.LP -The \fBMHIOCENFAILFAST\fR ioctl is applicable for both non-shared and shared +Issuing the +.Dv MHIOCGRP_INKEYS +ioctl is the recommended way for a caller to +determine if the device supports SCSI-3 Persistent Reservations (the ioctl +will return +.Sy -1 +with +.Va errno +set to +.Er ENOTSUP +if the device does not). +.Ss "MHIOCENFAILFAST Ioctl" +The +.Dv MHIOCENFAILFAST +ioctl is applicable for both non-shared and shared disks, and may be used with either the non-shared or shared ioctls. -.sp -.ne 2 -.na -\fB\fBioctl\fR(\fBfd\fR, \fBMHIOENFAILFAST\fR, (unsigned int \fI*\fR) -\fImillisecs\fR\fB);\fR\fR -.ad -.sp .6 -.RS 4n +.Bl -tag -width 1n +.It Fn ioctl fd MHIOENFAILFAST "(unsigned int *)millisecs" +.Pp Enables or disables the failfast option in the multihost disk driver and enables or disables automatic probing of a multihost disk, described below. The argument is an unsigned integer specifying the number of milliseconds to -wait between executions of the automatic probe function. An argument of zero -disables the failfast option and disables automatic probing. If the -\fBMHIOCENFAILFAST\fR ioctl is never called, the effect is defined to be that +wait between executions of the automatic probe function. +An argument of zero disables the failfast option and disables automatic probing. +If the +.Dv MHIOCENFAILFAST +ioctl is never called, the effect is defined to be that both the failfast option and automatic probing are disabled. -.RE - -.SS "Automatic Probing" -.sp -.LP -The \fBMHIOCENFAILFAST\fR ioctl sets up a timeout in the driver to periodically -schedule automatic probes of the disk. The automatic probe function works in -this manner: The driver is scheduled to probe the multihost disk every n -milliseconds, rounded up to the next integral multiple of the system clock's -resolution. If -.RS +4 -.TP -1. -the local host no longer has access rights to the multihost disk, and -.RE -.RS +4 -.TP -2. -access rights were expected to be held by the local host, -.RE -.sp -.LP +.El +.Ss "Automatic Probing" +The +.Dv MHIOCENFAILFAST +ioctl sets up a timeout in the driver to periodically +schedule automatic probes of the disk. +The automatic probe function works in this manner: The driver is scheduled to +probe the multihost disk every n milliseconds, rounded up to the next integral +multiple of the system clock's resolution. +If +.Bl -enum -offset indent +.It +the local host no longer has access rights to the multihost disk, and +.It +access rights were expected to be held by the local host, +.El +.Pp the driver immediately panics the machine to comply with the failfast model. -.sp -.LP +.Pp If the driver makes this discovery outside the timeout function, especially during a read or write operation, it is imperative that it panic the system then as well. -.SH RETURN VALUES -.sp -.LP -Each request returns \fB-1\fR on failure and sets \fBerrno\fR to indicate the -error. -.sp -.ne 2 -.na -\fB\fBEPERM\fR \fR -.ad -.RS 14n +.Sh RETURN VALUES +Each request returns +.Sy -1 +on failure and sets +.Va errno +to indicate the error. +.Bl -tag -width Er +.It Er EPERM Caller is not root. -.RE - -.sp -.ne 2 -.na -\fB\fBEACCES\fR \fR -.ad -.RS 14n +.It Er EACCES Access rights were denied. -.RE - -.sp -.ne 2 -.na -\fB\fBEIO\fR\fR -.ad -.RS 14n +.It Er EIO The multihost disk or controller was unable to successfully complete the requested operation. -.RE - -.sp -.ne 2 -.na -\fB\fBEOPNOTSUP\fR \fR -.ad -.RS 14n -The multihost disk does not support the operation. For example, it does not -support the SCSI-2 Reserve/Release command set, or the SCSI-3 Persistent -Reservation command set. -.RE - -.SH ATTRIBUTES -.sp -.LP -See \fBattributes\fR(5) for a description of the following attributes: -.sp - -.sp -.TS -box; -c | c -l | l . -ATTRIBUTE TYPE ATTRIBUTE VALUE -_ -Stability Evolving -.TE - -.SH SEE ALSO -.sp -.LP -\fBioctl\fR(2), \fBopen\fR(2), \fBattributes\fR(5), open(2) +.It Er EOPNOTSUP +The multihost disk does not support the operation. +For example, it does not support the SCSI-2 Reserve/Release command set, or the +SCSI-3 Persistent Reservation command set. +.El +.Sh STABILITY +Uncommitted +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr open 2 , +.Xr attributes 5 diff --git a/usr/src/man/man7i/mixer.7i b/usr/src/man/man7i/mixer.7i index 6516e78d1e..869b54ccfd 100644 --- a/usr/src/man/man7i/mixer.7i +++ b/usr/src/man/man7i/mixer.7i @@ -1,528 +1,627 @@ -'\" te .\" Copyright (c) 2009 Sun Microsystems, Inc. All rights reserved. -.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. -.\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the -.\" fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH MIXER 7I "May 21, 2009" -.SH NAME -mixer \- generic mixer device interface -.SH SYNOPSIS -.LP -.nf -\fB#include\fR \fB<sys/soundcard.h>\fR -.fi - -.SH DESCRIPTION -.sp -.LP -\&. -.SS "Mixer Pseudo-Device" -.sp -.LP -The \fB/dev/mixer\fR pseudo-device is provided for two purposes: -.RS +4 -.TP -.ie t \(bu -.el o +.\" Copyright 2019, Joyent, Inc. +.\" The contents of this file are subject to the terms of the +.\" Common Development and Distribution License (the "License"). +.\" You may not use this file except in compliance with the License. +.\" +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE +.\" or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions +.\" and limitations under the License. +.\" +.\" When distributing Covered Code, include this CDDL HEADER in each +.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. +.\" If applicable, add the following below this CDDL HEADER, with the +.\" fields enclosed by brackets "[]" replaced with your own identifying +.\" information: Portions Copyright [yyyy] [name of copyright owner] +.Dd February 1, 2019 +.Dt MIXER 7I +.Os +.Sh NAME +.Nm mixer +.Nd generic mixer device interface +.Sh SYNOPSIS +.In sys/soundcard.h +.Sh DESCRIPTION +.Ss "Mixer Pseudo-Device" +The +.Pa /dev/mixer +pseudo-device is provided for two purposes: +.Bl -bullet -offset indent +.It The first purpose is for applications that wish to learn about the list of audio devices on the system, so that they can select (or provide for users to -select) an appropriate audio device. The \fB/dev/mixer\fR pseudo-device +select) an appropriate audio device. +The +.Pa /dev/mixer +pseudo-device provides interfaces to enumerate all of the audio devices on the system. -.RE -.RS +4 -.TP -.ie t \(bu -.el o +.It The second purpose is for mixer panel type applications which need to control master settings for the audio hardware in the system, such as gain levels, balance, port functionality, and other device features. -.RE -.sp -.LP -Ordinary audio applications should \fBnot\fR attempt to adjust their playback -or record volumes or other device settings using this device. Instead, they -should use the \fBSNDCTL_DSP_SETPLAYVOL\fR and \fBSNDCTL_DSP_SETRECVOL\fR -ioctls that are documented in \fBdsp\fR(7I). -.SS "Sndstat Device" -.sp -.LP -The \fB/dev/sndstat\fR device supports \fBread\fR(2), and can be read to +.El +.Pp +Ordinary audio applications should +.Em not +attempt to adjust their playback +or record volumes or other device settings using this device. +Instead, they +should use the +.Dv SNDCTL_DSP_SETPLAYVOL +and +.Dv SNDCTL_DSP_SETRECVOL +ioctls that are documented in +.Xr dsp 7I . +.Ss "Sndstat Device" +The +.Pa /dev/sndstat +device supports +.Xr read 2 , +and can be read to retrieve human-readable information about the audio devices on the system. Software should not attempt to interpret the contents of this device. -.SH IOCTLS -.SS "Information IOCTLs" -.sp -.LP +.Sh IOCTLS +.Ss "Information IOCTLs" The following ioctls are intended to aid applications in identifying the audio -devices available on the system. These ioctls can be issued against either the -pseudo-device \fB/dev/mixer\fR, or a against a file descriptor open to any +devices available on the system. +These ioctls can be issued against either the +pseudo-device +.Pa /dev/mixer , +or a against a file descriptor open to any other audio device in the system. -.sp -.LP -Applications should issue \fBSNDCTL_SYSINFO\fR first to learn what audio +.Pp +Applications should issue +.Dv SNDCTL_SYSINFO +first to learn what audio devices and mixers are available on the system, and then use -\fBSNDCTL_AUDIOINFO\fR or \fBSNDCTL_MIXERINFO\fR to obtain more information +.Dv SNDCTL_AUDIOINFO +or +.Dv SNDCTL_MIXERINFO +to obtain more information about the audio devices or mixers, respectively. -.sp -.ne 2 -.na -\fB\fBOSS_GETVERSION\fR\fR -.ad -.RS 20n +.Bl -tag -width SNDCTL_AUDIOINFO +.It Dv OSS_GETVERSION The argument is a pointer to an integer, which retrieves the version of the -\fBOSS API\fR used. The value is encoded with the major version (currently 4) +.Sy OSS API +used. +The value is encoded with the major version (currently 4) encoded in the most significant 16 bits, and a minor version encoded in the lower 16 bits. -.RE - -.sp -.ne 2 -.na -\fB\fBSNDCTL_SYSINFO\fR\fR -.ad -.RS 20n -The argument is a pointer to an \fBoss_sysinfo\fR structure, which has the -following definition: -.sp -.in +2 -.nf +.It Dv SNDCTL_SYSINFO +The argument is a pointer to an +.Vt oss_sysinfo +structure, which has the following definition: +.Bd -literal -offset 2n typedef struct oss_sysinfo { - char product[32]; /* E.g. SunOS Audio */ - char version[32]; /* E.g. 4.0a */ - int versionnum; /* See OSS_GETVERSION */ - char options[128]; /* NOT SUPPORTED */ + char product[32]; /* E.g. SunOS Audio */ + char version[32]; /* E.g. 4.0a */ + int versionnum; /* See OSS_GETVERSION */ + char options[128]; /* NOT SUPPORTED */ - int numaudios; /* # of audio/dsp devices */ - int openedaudio[8]; /* Reserved, always 0 */ + int numaudios; /* # of audio/dsp devices */ + int openedaudio[8]; /* Reserved, always 0 */ - int numsynths; /* NOT SUPPORTED, always 0 */ - int nummidis; /* NOT SUPPORTED, always 0 */ - int numtimers; /* NOT SUPPORTED, always 0 */ - int nummixers; /* # of mixer devices */ + int numsynths; /* NOT SUPPORTED, always 0 */ + int nummidis; /* NOT SUPPORTED, always 0 */ + int numtimers; /* NOT SUPPORTED, always 0 */ + int nummixers; /* # of mixer devices */ - int openedmidi[8]; /* Mask of midi devices are - busy */ - int numcards; /* Number of sound cards in - the system */ - int numaudioengines; /* Number of audio engines in - the system */ - char license[16]; /* E.g. "GPL" or "CDDL" */ - char revision_info[256]; /* Reserved */ - int filler[172]; /* Reserved */ -} oss_sysinfo; -.fi -.in -2 -.sp + /* Mask of midi devices are busy */ + int openedmidi[8]; -The important fields here are \fBnumaudios\fR, which is used to determine the -number of audio devices that can be queried with \fBSNDCTL_AUDIOINFO\fR, -\fBnummixers\fR which provides a count of mixers on the system, and -\fBnumcards\fR which counts to total number of aggregate devices. A \fBcard\fR + /* Number of sound cards in the system */ + int numcards; + + /* Number of audio engines in the system */ + int numaudioengines; + char license[16]; /* E.g. "GPL" or "CDDL" */ + char revision_info[256]; /* Reserved */ + int filler[172]; /* Reserved */ +} oss_sysinfo; +.Ed +.Pp +The important fields here are +.Fa numaudios , +which is used to determine the +number of audio devices that can be queried with +.Dv SNDCTL_AUDIOINFO , +.Fa nummixers +which provides a count of mixers on the system, and +.Fa numcards +which counts to total number of aggregate devices. +A +.Sy card can consist of one or more audio devices and one or more mixers, although more typically there is exactly one audio device and one mixer for each card. -.RE - -.sp -.ne 2 -.na -\fB\fBSNDCTL_AUDIOINFO\fR\fR -.ad -.RS 20n -The argument is a pointer to an \fBoss_audioinfo\fR structure, which has the -following structure: -.sp -.in +2 -.nf +.It Dv SNDCTL_AUDIOINFO +The argument is a pointer to an +.Vt oss_audioinfo +structure, which has the following structure: +.Bd -literal -offset 2n typedef struct oss_audioinfo { - int dev; /* Device to query */ - char name[64]; /* Human readable name */ - int busy; /* reserved */ - int pid; /* reserved */ - int caps; /* PCM_CAP_INPUT, PCM_CAP_OUTPUT */ - int iformats; /* Supported input formats */ - int oformats; /* Supported output formats */ - int magic; /* reserved */ - char cmd[64]; /* reserved */ + int dev; /* Device to query */ + char name[64]; /* Human readable name */ + int busy; /* reserved */ + int pid; /* reserved */ + + /* PCM_CAP_INPUT, PCM_CAP_OUTPUT */ + int caps; + int iformats; /* Supported input formats */ + int oformats; /* Supported output formats */ + int magic; /* reserved */ + char cmd[64]; /* reserved */ int card_number; - int port_number; /* reserved */ + int port_number; /* reserved */ int mixer_dev; - int legacy_device; /* Obsolete field. - Replaced by devnode */ - int enabled; /* reserved */ - int flags; /* reserved */ - int min_rate; /* Minimum sample rate */ - int max_rate; /* Maximum sample rate */ - int min_channels; /* Minimum number - of channels */ - int max_channels; /* Maximum number - of channels */ - int binding; /* reserved */ - int rate_source; /* reserved */ - char handle[32]; /* reserved */ - unsigned int nrates; /* reserved */ + + /* Obsolete field. Replaced by devnode */ + int legacy_device; + int enabled; /* reserved */ + int flags; /* reserved */ + int min_rate; /* Minimum sample rate */ + int max_rate; /* Maximum sample rate */ + int min_channels; /* Minimum number of channels */ + int max_channels; /* Maximum number of channels */ + int binding; /* reserved */ + int rate_source; /* reserved */ + char handle[32]; /* reserved */ + unsigned int nrates; /* reserved */ unsigned int rates[20]; /* reserved */ char song_name[64]; /* reserved */ - char label[16]; /* reserved */ - int latency; /* reserved */ - char devnode[32]; /* Device special file - name (absolute path) */ - int next_play_engine; /* reserved */ - int next_rec_engine; /* reserved */ - int filler[184]; /* reserved */ -} oss_audioinfo; -.fi -.in -2 -.sp + char label[16]; /* reserved */ + int latency; /* reserved */ + /* Device special file name (absolute path) */ + char devnode[32]; + int next_play_engine; /* reserved */ + int next_rec_engine; /* reserved */ + int filler[184]; /* reserved */ +} oss_audioinfo; +.Ed +.Pp In the above structure, all of the fields are reserved except the following: -d\fBev, name, card_number, mixer_dev, caps, min_rate, max_rate, min_channels, -max_channels,\fR and \fBdevnode\fR. The reserved fields are provided for -compatibility with other OSS implementations, and available for legacy -applications. New applications should not attempt to use these fields. -.sp -The \fBdev\fR field should be initialized by the application to the number of -the device to query. This is a number between zero (inclusive) and value of -\fBnumaudios\fR (exclusive) returned by \fBSNDCTL_SYSINFO\fR. Alternatively, -when issuing the ioctl against a real mixer or \fBdsp\fR device, the special -value \fB-1\fR can be used to indicate that the query is being made against the -device opened. If \fB-1\fR is used, the field is overwritten with the device +.Fa dev , +.Fa name , +.Fa card_number , +.Fa mixer_dev , +.Fa caps , +.Fa min_rate , +.Fa max_rate , +.Fa min_channels , +.Fa max_channels , +and +.Fa devnode . +The reserved fields are provided for compatibility with other OSS +implementations, and available for legacy applications. +New applications should not attempt to use these fields. +.Pp +The +.Fa dev +field should be initialized by the application to the number of +the device to query. +This is a number between zero (inclusive) and value of +.Fa numaudios +(exclusive) returned by +.Dv SNDCTL_SYSINFO . +Alternatively, +when issuing the ioctl against a real mixer or +.Sy dsp +device, the special +value +.Sy -1 +can be used to indicate that the query is being made against the device opened. +If +.Sy -1 +is used, the field is overwritten with the device number for the current device on successful return. -.sp +.Pp No other fields are significant upon entry, but a successful return contains details of the device. -.sp -The \fBname\fR field is a human readable name representing the device. +.Pp +The +.Fa name +field is a human readable name representing the device. Applications should not try to interpret it. -.sp -The \fBcard_number\fR field indicates the number assigned to the aggregate -device. This can be used with the \fBSNDCTL_CARDINFO\fR ioctl. -.sp -The \fBmixer_dev\fR is the mixer device number for the mixing device associated -with the audio device. This can be used with the \fBSNDCTL_MIXERINFO\fR ioctl. -.sp -The caps field contains any of the bits \fBPCM_CAP_INPUT\fR, -\fBPCM_CAP_OUTPUT\fR, and \fBPCM_CAP_DUPLEX\fR. Indicating whether the device +.Pp +The +.Fa card_number +field indicates the number assigned to the aggregate device. +This can be used with the +.Dv SNDCTL_CARDINFO +ioctl. +.Pp +The +.Fa mixer_dev +is the mixer device number for the mixing device associated +with the audio device. +This can be used with the +.Dv SNDCTL_MIXERINFO +ioctl. +.Pp +The +.Fa caps +field contains any of the bits +.Dv PCM_CAP_INPUT , +.Dv PCM_CAP_OUTPUT , +and +.Dv PCM_CAP_DUPLEX . +Indicating whether the device support input, output, and whether input and output can be used simultaneously. All other bits are reserved. -.sp -The \fBmin_rate\fR and \fBmax_rate\fR fields indicate the minimum and maximum -sample rates supported by the device. Most applications should try to use the -maximum supported rate for the best audio quality and lowest system resource -consumption. -.sp -The \fBmin_channels\fR and \fBmax_channels\fR provide an indication of the -number of channels (1 for mono, 2 for stereo, 6 for 5.1, etc.) supported by the -device. -.sp -The \fBdevnode\fR field contains the actual full path to the device node for -this device, such as \fB/dev/sound/audio810:0dsp\fR. Applications should open -this file to access the device. -.RE - -.sp -.ne 2 -.na -\fB\fBSNDCTL_CARDINFO\fR\fR -.ad -.RS 20n -The argument is a pointer to a \fBstruct oss_card_info\fR, which has the -following definition: -.sp -.in +2 -.nf +.Pp +The +.Fa min_rate +and +.Fa max_rate +fields indicate the minimum and maximum sample rates supported by the device. +Most applications should try to use the maximum supported rate for the best +audio quality and lowest system resource consumption. +.Pp +The +.Fa min_channels +and +.Fa max_channels +provide an indication of the number of channels (1 for mono, 2 for stereo, +6 for 5\&.1, etc\&.) supported by the device. +.Pp +The +.Fa devnode +field contains the actual full path to the device node for this device, such as +.Pa /dev/sound/audio810:0dsp . +Applications should open this file to access the device. +.It Dv SNDCTL_CARDINFO +The argument is a pointer to a +.Vt struct oss_card_info , +which has the following definition: +.Bd -literal -offset 2n typedef struct oss_card_info { -int card; - char shortname[16]; - char longname[128]; - int flags;/* reserved */ - char hw_info[400]; - int intr_count;/* reserved */ - int ack_count;/* reserved */ - int filler[154]; + int card; + char shortname[16]; + char longname[128]; + int flags; /* reserved */ + char hw_info[400]; + int intr_count; /* reserved */ + int ack_count; /* reserved */ + int filler[154]; } oss_card_info; -.fi -.in -2 -.sp - +.Ed +.Pp This ioctl is used to query for information about the aggregate audio device. -.sp -The \fBcard\fR field should be initialized by the application to the number of -the card to query. This is a number between zero inclusive and value of -\fBnumcards\fR (exclusive) returned by \fBSNDCTL_SYSINFO\fR.) Alternatively, -when issuing the ioctl against a real mixer or \fBdsp\fR device, the special -value \fB-1\fR can be used to indicate that the query is being made against the -device opened. If \fB-1\fR is used, the field is overwritten with the number +.Pp +The +.Fa card +field should be initialized by the application to the number of +the card to query. +This is a number between zero +.Pq inclusive +and value of +.Fa numcards +.Pq exclusive +returned by +.Dv SNDCTL_SYSINFO . +Alternatively, +when issuing the ioctl against a real mixer or +.Sy dsp +device, the special value +.Sy -1 +can be used to indicate that the query is being made against the device opened. +If +.Sy -1 +is used, the field is overwritten with the number for the current hardware device on successful return. -.sp -The \fBshortname\fR, \fBlongname\fR, and \fBhw_info\fR contain \fBASCIIZ\fR -strings describing the device in more detail. The \fBhw_info\fR member can -contain multiple lines of detail, each line ending in a NEWLINE. -.sp -The flag, intr_count, and ack_count fields are not used by this implementation. -.RE - -.sp -.ne 2 -.na -\fB\fBSNDCTL_MIXERINFO\fR\fR -.ad -.RS 20n -The argument is a pointer to a \fBstruct oss_mixer_info\fR, which has the -following definition: -.sp -.in +2 -.nf +.Pp +The +.Fa shortname , +.Fa longname , +and +.Fa hw_info +contain +.Sy ASCIIZ +strings describing the device in more detail. +The +.Fa hw_info +member can contain multiple lines of detail, each line ending in a NEWLINE. +.Pp +The +.Fa flag , +.Fa intr_count , +and +.Fa ack_count +fields are not used by this implementation. +.It Dv SNDCTL_MIXERINFO +The argument is a pointer to a +.Vt struct oss_mixer_info , +which has the following definition: +.Bd -literal -offset 2n typedef struct oss_mixerinfo { - int dev; - char id[16];/* Reserved */ - char name[32]; - int modify_counter; - int card_number; - int port_number;/* Reserved */ - char handle[32];/* Reserved */ - int magic;/* Reserved */ - int enabled;/* Reserved */ - int caps;/* Reserved */ - int flags;/* Reserved */ - int nrext; - int priority; - char devnode[32];/* Device special file name - (absolute path) */ - int legacy_device;/* Reserved */ - int filler[245];/* Reserved */ -} oss_mixerinfo; -.fi -.in -2 -.sp + int dev; + char id[16]; /* Reserved */ + char name[32]; + int modify_counter; + int card_number; + int port_number; /* Reserved */ + char handle[32]; /* Reserved */ + int magic; /* Reserved */ + int enabled; /* Reserved */ + int caps; /* Reserved */ + int flags; /* Reserved */ + int nrext; + int priority; + /* Deice special file name (absolute path) */ + char devnode[32]; + int legacy_device; /* Reserved */ + int filler[245]; /* Reserved */ +} oss_mixerinfo; +.Ed +.Pp In the above structure, all of the fields are reserved except the following: -\fBdev, name, modify_counter, card_number, nrext, priority,\fR and -\fBdevnode\fR. The reserved fields are provided for compatibility with other -OSS implementations, and available for legacy applications. New applications -should not attempt to use these fields. -.sp -The \fBdev\fR field should be initialized by the application to the number of -the device to query. This is a number between zero inclusive and value of -\fBnummixers\fR (exclusive) returned by \fBSNDCTL_SYSINFO\fR, or by -\fBSNDCTL_MIX_NRMIX\fR. Alternatively, when issuing the ioctl against a real -mixer or \fBdsp\fR device, the special value \fB-1\fR can be used to indicate -that the query is being made against the device opened. If \fB-1\fR is used, +.Fa dev , +.Fa name , +.Fa modify_counter , +.Fa card_number , +.Fa nrext , +.Fa priority , +and +.Fa devnode . +The reserved fields are provided for compatibility with other +OSS implementations, and available for legacy applications. +New applications should not attempt to use these fields. +.Pp +The +.Fa dev +field should be initialized by the application to the number of +the device to query. +This is a number between zero inclusive and value of +.Fa nummixers +(exclusive) returned by +.Dv SNDCTL_SYSINFO , +or by +.Dv SNDCTL_MIX_NRMIX . +Alternatively, when issuing the ioctl against a real mixer or +.Sy dsp +device, the special value +.Sy -1 +can be used to indicate +that the query is being made against the device opened. +If +.Sy -1 +is used, the field is overwritten with the mixer number for the current open file on successful return. -.sp +.Pp No other fields are significant upon entry, but on successful return contains details of the device. -.sp -The \fBname\fR field is a human readable name representing the device. +.Pp +The +.Fa name +field is a human readable name representing the device. Applications should not try to interpret it. -.sp -The \fBmodify_counter\fR is changed by the mixer framework each time the +.Pp +The +.Fa modify_counter +is changed by the mixer framework each time the settings for the various controls or extensions of the device are changed. Applications can poll this value to learn if any other changes need to be searched for. -.sp -The \fBcard_number\fR field is the number of the aggregate audio device this -mixer is located on. It can be used with the \fBSNDCTL_CARDINFO\fR ioctl. -.sp -The \fBnrext\fR field is the number of mixer extensions available on this -mixer. See the \fBSNDCTL_MIX_NREXT\fR description. -.sp +.Pp +The +.Fa card_number +field is the number of the aggregate audio device this +mixer is located on. +It can be used with the +.Dv SNDCTL_CARDINFO +ioctl. +.Pp +The +.Fa nrext +field is the number of mixer extensions available on this mixer. +See the +.Dv SNDCTL_MIX_NREXT +description. +.Pp The priority is used by the framework to assign a preference that applications -can use in choosing a device. Higher values are preferable. Mixers with -priorities less than -1 should never be selected by default. -.sp -The \fBdevnode\fR field contains the actual full path to the device node for -the physical mixer, such as \fB/dev/sound/audio810:0mixer\fR. Applications +can use in choosing a device. +Higher values are preferable. +Mixers with priorities less than -1 should never be selected by default. +.Pp +The +.Fa devnode +field contains the actual full path to the device node for +the physical mixer, such as +.Pa /dev/sound/audio810:0mixer . +Applications should open this file to access the mixer settings. -.RE - -.SS "Mixer Extension IOCTLs" -.sp -.LP -The pseudo \fB/dev/mixer\fR device supports ioctls that can change the -various settings for the audio hardware in the system. -.sp -.LP -Those ioctls should only be used by dedicated mixer applications or desktop -volume controls, and not by typical ordinary audio applications such as media -players. Ordinary applications that wish to adjust their own volume settings -should use the \fBSNDCTL_DSP_SETPLAYVOL\fR or \fBSNDCTL_DSP_SETRECVOL\fR ioctls -for that purpose. See \fBdsp\fR(7I) for more information. Ordinary +.El +.Ss "Mixer Extension IOCTLs" +The pseudo +.Pa /dev/mixer +device supports ioctls that can change the +oarious settings for the audio hardware in the system. +.Pp +Those ioctls should only be used by dedicated mixer applications or desktop +olumme controls, and not by typical ordinary audio applications such as media +players. +Ordinary applications that wish to adjust their own volume settings +should use the +.Dv SNDCTL_DSP_SETPLAYVOL +or +.Dv SNDCTL_DSP_SETRECVOL +ioctls for that purpose. +See +.Xr dsp 7I +for more information. +Ordinary applications should never attempt to change master port selection or hardware settings such as monitor gain settings. -.sp -.LP +.Pp The ioctls in this section can only be used to access the mixer device that is associated with the current file descriptor. -.sp -.LP -Applications should not assume that a single \fB/dev/mixer\fR node is able to -access any physical settings. Instead, they should use the ioctl -\fBSNDCTL_MIXERINFO\fR to determine the device path for the real mixer device, +.Pp +Applications should not assume that a single +.Pa /dev/mixer +node is able to access any physical settings. +Instead, they should use the ioctl +.Dv SNDCTL_MIXERINFO +to determine the device path for the real mixer device, and issue ioctls on a file descriptor opened against the corresponding -\fBdevnode\fR field. -.sp -.LP -When a \fBdev\fR member is specified in each of the following ioctls, the -application should specify \fB-1\fR, although for compatibility the mixer +.Fa devnode +field. +.Pp +When a +.Fa dev +member is specified in each of the following ioctls, the +application should specify +.Sy -1 , +although for compatibility the mixer allows the application to specify the mixer device number. -.sp -.ne 2 -.na -\fB\fBSNDCTL_MIX_NRMIX\fR\fR -.ad -.RS 23n +.Pp +.Bl -tag -width SNDCTL_MIX_ENUMINFO -compact +.It Dv SNDCTL_MIX_NRMIX The argument is a pointer to an integer, which receives the number of mixer -devices in the system. Each can be queried by using its number with the -\fBSNDCTL_MIXERINFO\fR ioctl. The same information is available using the -\fBSNDCTL_SYSINFO\fR ioctl. -.RE - -.sp -.ne 2 -.na -\fB\fBSNDCTL_MIX_NREXT\fR\fR -.ad -.RS 23n -The argument is a pointer to an integer. On entry, the integer should contain -the special value \fB-1\fR. On return the argument receives the number of mixer -extensions (or mixer controls) supported by the mixer device. More details -about each extension can be obtained by \fBSNDCTL_MIX_EXTINFO\fR ioctl. -.RE - -.sp -.ne 2 -.na -\fB\fBSNDCTL_MIX_EXTINFO\fR\fR -.ad -.RS 23n -The argument is a pointer to an \fBoss_mixext\fR structure which is defined as -follows: -.sp -.in +2 -.nf +devices in the system. +Each can be queried by using its number with the +.Dv SNDCTL_MIXERINFO +ioctl. +The same information is available using the +.Fa SNDCTL_SYSINFO +ioctl. +.Pp +.It Dv SNDCTL_MIX_NREXT +The argument is a pointer to an integer. +On entry, the integer should contain +the special value +.Sy -1 . +On return the argument receives the number of mixer +extensions (or mixer controls) supported by the mixer device. +More details +about each extension can be obtained by +.Fa SNDCTL_MIX_EXTINFO +ioctl. +.Pp +.It Dv SNDCTL_MIX_EXTINFO +The argument is a pointer to an +.Vt oss_mixext +structure which is defined as follows: +.Bd -literal -offset 2n typedef struct oss_mixext { - int dev; /* Mixer device number */ - int ctrl; /* Extension number */ - int type; /* Entry type */ + int dev; /* Mixer device number */ + int ctrl; /* Extension number */ + int type; /* Entry type */ int maxvalue; int minvalue; int flags; char id[16]; /* Mnemonic ID (internal use) */ - int parent; /* Entry# of parent - (-1 if root) */ - int dummy; /* NOT SUPPORTED */ + int parent; /* Entry# of parent (-1 if root) */ + int dummy; /* NOT SUPPORTED */ int timestamp; - char data[64]; /* Reserved */ - unsigned char enum_present[32]; /* Mask - of allowed - enum - values */ - int control_no; /* Reserved */ + char data[64]; /* Reserved */ + + /* Mask of allowed enum values */ + unsigned char enum_present[32]; + int control_no; /* Reserved */ unsigned int desc; /* NOT SUPPORTED */ char extname[32]; int update_counter; - int filler[7]; /* Reserved */ + int filler[7]; /* Reserved */ } oss_mixext; -.fi -.in -2 -.sp - -On entry, the \fBdev\fR field should be initialized to the value \fB-1\fR, and -the \fBctrl\fR field should be initialized with the number of the extension -being accessed. Between 0, inclusive, and the value returned by -\fBSNDCTL_MIX_NREXT\fR, exclusive. -.sp +.Ed +.Pp +On entry, the +.Fa dev +field should be initialized to the value +.Sy -1 , +and +the +.Fa ctrl +field should be initialized with the number of the extension +being accessed. +Between 0, inclusive, and the value returned by +.Dv SNDCTL_MIX_NREXT , +exclusive. +.Pp Mixer extensions are organized as a logical tree, starting with a root node. -The root node always has a \fBctrl\fR value of zero. The structure of the tree -can be determined by looking at the parent field, which contains the extension -number of the parent extension, or \fB-1\fR if the extension is the root -extension. -.sp -The type indicates the type of extension used. This implementation supports the -following values: -.sp -.in +2 -.nf -MIXT_DEVROOT Root node for extension tree -MIXT_GROUP Logical grouping of controls -MXIT_ONOFF Boolean value, 0 = off, 1 = on. -MIXT_ENUM Enumerated value, 0 to maxvalue. -MIXT_MONOSLIDER Monophonic slider, 0 to 255. -MIXT_STEREOSLIDER Stereophonic slider, 0 to 255 - (encoded as - lower two bytes in value.) -MIXT_MARKER Place holder, can ignore. -.fi -.in -2 -.sp - -The flags field is a bit array. This implementation makes use of the following +The root node always has a +.Fa ctrl +value of zero. +The structure of the tree can be determined by looking at the parent field, +which contains the extension number of the parent extension, or +.Sy -1 +if the extension is the root extension. +.Pp +The type indicates the type of extension used. +This implementation supports the following values: +.Bl -column -offset 2n "MIXT_STEREOSLIDER" "Enumerated value, 0 to maxvalue" +.It Dv MIXT_DEVROOT Ta Root node for extension tree +.It Dv MIXT_GROUP Ta Logical grouping of controls +.It Dv MXIT_ONOFF Ta Boolean value, 0 = off, 1 = on. +.It Dv MIXT_ENUM Ta Enumerated value, 0 to maxvalue. +.It Dv MIXT_MONOSLIDER Ta Monophonic slider, 0 to 255. +.It Dv MIXT_STEREOSLIDER Ta Stereophonic slider, 0 to 255 (encoded as lower two bytes in value.) +.It Dv MIXT_MARKER Ta Place holder, can ignore. +.El +.Pp +The flags field is a bit array. +This implementation makes use of the following possible bits: -.sp -.in +2 -.nf -MIXF_READABLE Extension's value is readable. -MIXF_WRITEABLE Extension's value is modifiable. -MIXF_POLL Extension can self-update. -MIXF_PCMVOL Extension is for master - PCM playback volume. -MIXF_MAINVOL Extension is for a typical - analog volume -MIXF_RECVOL Extension is for master - record gain. -MIXF_MONVOL Extension is for a monitor - source's gain. -.fi -.in -2 -.sp - -The \fBid\fR field contains an \fBASCIIZ\fR identifier for the extension. -.sp +.Bl -column -offset 2n "MIXF_WRITEABLE" "Extensions value is modifiable" +.It Dv MIXF_READABLE Ta Extension's value is readable. +.It Dv MIXF_WRITEABLE Ta Extension's value is modifiable. +.It Dv MIXF_POLL Ta Extension can self-update. +.It Dv MIXF_PCMVOL Ta Extension is for master PCM playback volume. +.It Dv MIXF_MAINVOL Ta Extension is for a typical analog volume +.It Dv MIXF_RECVOL Ta Extension is for master record gain. +.It Dv MIXF_MONVOL Ta Extension is for a monitor source's gain. +.El +.Pp +The +.Fa id +field contains an +.Sy ASCIIZ +identifier for the extension. +.Pp The timestamp field is set when the extension tree is first initialized. Applications must use the same timestamp value when attempting to change the -values. A change in the timestamp indicates a change a in the structure of the +values. +A change in the timestamp indicates a change a in the structure of the extension tree. -.sp -The \fBenum_present\fR field is a bit mask of possible enumeration values. If a -bit is present in the \fBenum_present\fR mask, then the corresponding -enumeration value is legal. The mask is in little endian order. -.sp -The \fBdesc\fR field provides information about scoping, which can be useful as -layout hints to applications. The following hints are available: -.sp -.in +2 -.nf -MIXEXT_SCOPE_MASK Mask of possible scope - values. -MIXEXT_SCOPE_INPUT Extension is an input - control. -MIXEXT_SCOPE_OUTPUT Extension is an - output control. -MIXEXT_SCOPE_MONITOR Extension relates to - input monitoring. -MIXEXT_SCOPE_OTHER No scoping hint provided. -.fi -.in -2 -.sp - -The \fBextname\fR is the full name of the extension. -.sp -The \fBupdate_counter\fR is incremented each time the control's value is -changed. -.RE - -.sp -.ne 2 -.na -\fB\fBSNDCTL_MIX_ENUMINFO\fR\fR -.ad -.RS 23n -The argument is a pointer to an \fBoss_mixer_enuminfo\fR structure, which is -defined as follows: -.sp -.in +2 -.nf +.Pp +The +.Fa enum_present +field is a bit mask of possible enumeration values. +If a +bit is present in the +.Fa enum_present +mask, then the corresponding enumeration value is legal. +The mask is in little endian order. +.Pp +The +.Fa desc +field provides information about scoping, which can be useful as +layout hints to applications. +The following hints are available: +.Bl -column -offset 2n "MIXEXT_SCOPE_MONITOR" "No scoping hint provided." +.It Dv MIXEXT_SCOPE_MASK Ta Mask of possible scope values. +.It Dv MIXEXT_SCOPE_INPUT Ta Extension is an input control. +.It Dv MIXEXT_SCOPE_OUTPUT Ta Extension is an output control. +.It Dv MIXEXT_SCOPE_MONITOR Ta Extension relates to input monitoring. +.It Dv MIXEXT_SCOPE_OTHER Ta No scoping hint provided. +.El +.Pp +The +.Fa extname +is the full name of the extension. +.Pp +The +.Fa update_counter +is incremented each time the control's value is changed. +.Pp +.It Dv SNDCTL_MIX_ENUMINFO +The argument is a pointer to an +.Vt oss_mixer_enuminfo +structure, which is defined as follows: +.Bd -literal -offset 2n typedef struct oss_mixer_enuminfo { int dev; int ctrl; @@ -531,169 +630,138 @@ typedef struct oss_mixer_enuminfo { short strindex[255]; char strings[3000]; } oss_mixer_enuminfo; -.fi -.in -2 -.sp - -On entry, the \fBdev\fR field should be initialized to the value \fB-1\fR, and -the \fBctrl\fR field should be initialized with the number of the extension -being accessed. Between 0, inclusive, and the value returned by -\fBSNDCTL_MIX_NREXT\fR, exclusive. -.sp -On return the \fBnvalues\fR field contains the number of values, and -\fBstrindex\fR contains an array of indices into the strings member, each index -pointing to an \fBASCIIZ\fR describing the enumeration value. -.RE - -.sp -.ne 2 -.na -\fB\fBSNDCTL_MIX_READ\fR\fR -.ad -.br -.na -\fB\fBSNDCTL_MIX_WRITE\fR\fR -.ad -.RS 23n -The argument is a pointer to an \fBoss_mixer_value\fR structure, defined as -follows: -.sp -.in +2 -.nf +.Ed +.Pp +On entry, the +.Fa dev +field should be initialized to the value +.Sy -1 , +and +the +.Fa ctrl +field should be initialized with the number of the extension being accessed. +Between 0, inclusive, and the value returned by +.Dv SNDCTL_MIX_NREXT , +exclusive. +.Pp +On return the +.Fa nvalues +field contains the number of values, and +.Fa strindex +contains an array of indices into the strings member, each index +pointing to an +.Sy ASCIIZ +describing the enumeration value. +.Pp +.It Dv SNDCTL_MIX_READ +.It Dv SNDCTL_MIX_WRITE +The argument is a pointer to an +.Vt oss_mixer_value +structure, defined as follows: +.Bd -literal -offset 2n typedef struct oss_mixer_value { int dev; int ctrl; int value; - int flags; /* Reserved for future use. - Initialize to 0 */ - int timestamp; /* Must be set to - oss_mixext.timestamp */ - int filler[8]; /* Reserved for future use. - Initialize to 0 */ -} oss_mixer_value; -.fi -.in -2 -.sp -On entry, the \fBdev\fR field should be initialized to the value \fB-1\fR, and -the \fBctrl\fR field should be initialized with the number of the extension -being accessed. Between 0, inclusive, and the value returned by -\fBSNDCTL_MIX_NREXT\fR, exclusive. Additionally, the timestamp member must be -initialized to the same value as was supplied in the \fBoss_mixext\fR structure -used with \fBSNDCTL_MIX_EXTINFO\fR. -.sp -For \fBSNDCTL_MIX_WRITE\fR, the application should supply the new value for the -extension. For \fBSNDCTL_MIX_READ\fR, the mixer returns the extensions current -value in value. -.RE + /* Reserved for future use. Initialize to 0 */ + int flags; -.SS "Compatibility IOCTLs" -.sp -.LP -The following ioctls are for compatibility use only: -.sp -.in +2 -.nf -SOUND_MIXER_READ_VOLUME -SOUND_MIXER_READ_PCM -SOUND_MIXER_READ_OGAIN -SOUND_MIXER_READ_RECGAIN -SOUND_MIXER_READ_RECLEV -SOUND_MIXER_READ_IGAIN -SOUND_MIXER_READ_RECSRC -SOUND_MIXER_READ_RECMASK -SOUND_MIXER_READ_DEVMASK -SOUND_MIXER_READ_STEREODEVS -SOUND_MIXER_WRITE_VOLUME -SOUND_MIXER_WRITE_PCM -SOUND_MIXER_WRITE_OGAIN -SOUND_MIXER_WRITE_RECGAIN -SOUND_MIXER_WRITE_RECLEV -SOUND_MIXER_WRITE_IGAIN -SOUND_MIXER_WRITE_RECSRC -SOUND_MIXER_WRITE_RECMASK -SOUND_MIXER_INFO -SNDCTL_AUDIOINFO_EX -SNDCTL_ENGINEINFO -.fi -.in -2 -.sp + /* Must be set to oss_mixext.timestamp */ + int timestamp; -.sp -.LP + /* Reserved for future use. Initialize to 0 */ + int filler[8]; +} oss_mixer_value; +.Pp +.Ed +On entry, the +.Fa dev +field should be initialized to the value +.Sy -1 , +and the +.Fa ctrl +field should be initialized with the number of the extension +being accessed. +Between 0, inclusive, and the value returned by +.Dv SNDCTL_MIX_NREXT , +exclusive. +Additionally, the timestamp member must be +initialized to the same value as was supplied in the +.Vt oss_mixext +structure +used with +.Dv SNDCTL_MIX_EXTINFO . +.Pp +For +.Dv SNDCTL_MIX_WRITE , +the application should supply the new value for the extension. +For +.Dv SNDCTL_MIX_READ , +the mixer returns the extensions current value in value. +.El +.Ss "Compatibility IOCTLs" +The following ioctls are for compatibility use only: +.Pp +.Bl -tag -offset 2n -width SNDCTL_MIX_ENUMINFO -compact +.It Dv SOUND_MIXER_READ_VOLUME +.It Dv SOUND_MIXER_READ_PCM +.It Dv SOUND_MIXER_READ_OGAIN +.It Dv SOUND_MIXER_READ_RECGAIN +.It Dv SOUND_MIXER_READ_RECLEV +.It Dv SOUND_MIXER_READ_IGAIN +.It Dv SOUND_MIXER_READ_RECSRC +.It Dv SOUND_MIXER_READ_RECMASK +.It Dv SOUND_MIXER_READ_DEVMASK +.It Dv SOUND_MIXER_READ_STEREODEVS +.It Dv SOUND_MIXER_WRITE_VOLUME +.It Dv SOUND_MIXER_WRITE_PCM +.It Dv SOUND_MIXER_WRITE_OGAIN +.It Dv SOUND_MIXER_WRITE_RECGAIN +.It Dv SOUND_MIXER_WRITE_RECLEV +.It Dv SOUND_MIXER_WRITE_IGAIN +.It Dv SOUND_MIXER_WRITE_RECSRC +.It Dv SOUND_MIXER_WRITE_RECMASK +.It Dv SOUND_MIXER_INFO +.It Dv SNDCTL_AUDIOINFO_EX +.It Dv SNDCTL_ENGINEINFO +.El +.Pp These ioctls can affect the software volume levels associated with the calling -process. They have no effect on the physical hardware levels or settings. They -should not be used in new applications. -.SH ERRORS -.sp -.LP -An \fBioctl()\fR fails if: -.sp -.ne 2 -.na -\fB\fBEINVAL\fR\fR -.ad -.RS 10n +process. +They have no effect on the physical hardware levels or settings. +They should not be used in new applications. +.Sh FILES +.Bl -tag -width /dev/sndstat +.It Pa /dev/mixer +Symbolic link to the pseudo mixer device for the system +.It Pa /dev/sndstat +Sound status device +.El +.Sh ERRORS +An +.Xr ioctl 2 +fails if: +.Bl -tag -width EINVAL +.It Er EINVAL The parameter changes requested in the ioctl are invalid or are not supported by the device. -.RE - -.sp -.ne 2 -.na -\fB\fBENXIO\fR\fR -.ad -.RS 10n +.It Er ENXIO The device or extension referenced does not exist. -.RE - -.SH FILES -.sp -.ne 2 -.na -\fB\fB/dev/mixer\fR\fR -.ad -.RS 16n -Symbolic link to the pseudo mixer device for the system -.RE - -.sp -.ne 2 -.na -\fB\fB/dev/sndstat\fR\fR -.ad -.RS 16n -Sound status device -.RE - -.SH ATTRIBUTES -.sp -.LP -See \fBattributes\fR(5) for a description of the following attributes: -.sp - -.sp -.TS -box; -c | c -l | l . -ATTRIBUTE TYPE ATTRIBUTE VALUE -_ -Architecture SPARC, x86 -_ -Stability Level See below. -.TE - -.sp -.LP -The information and mixer extension IOCTLs are Uncommitted. The Compatibility -IOCTLs are Obsolete Uncommitted. The extension names are Uncommitted. -.SH SEE ALSO -.sp -.LP -\fBclose\fR(2), \fBioctl\fR(2), \fBopen\fR(2), , \fBread\fR(2), -\fBattributes\fR(5), \fBdsp\fR(7I) -.SH BUGS -.sp -.LP +.El +.Sh ARCHITECTURE +SPARC +x86 +.Sh INTERFACE STABILITY +The information and mixer extension IOCTLs are Uncommitted. +The Compatibility IOCTLs are Obsolete Uncommitted. +The extension names are Uncommitted. +.Sh SEE ALSO +.Xr close 2 , +.Xr ioctl 2 , +.Xr open 2 , +.Xr read 2 , +.Xr attributes 5 , +.Xr dsp 7I +.Sh BUGS The names of mixer extensions are not guaranteed to be predictable. diff --git a/usr/src/man/man7i/mtio.7i b/usr/src/man/man7i/mtio.7i index 570cc9d174..4663f9c0cd 100644 --- a/usr/src/man/man7i/mtio.7i +++ b/usr/src/man/man7i/mtio.7i @@ -1,308 +1,421 @@ -'\" te .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved -.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. -.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. -.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH MTIO 7I "April 9, 2016" -.SH NAME -mtio \- general magnetic tape interface -.SH SYNOPSIS -.LP -.nf -#include <sys/types.h> -#include <sys/ioctl.h> -#include <sys/mtio.h> -.fi - -.SH DESCRIPTION -.LP +.\" Copyright 2018, Joyent, Inc. +.\" The contents of this file are subject to the terms of the +.\" Common Development and Distribution License (the "License"). +.\" You may not use this file except in compliance with the License. +.\" +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE +.\" or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions +.\" and limitations under the License. +.\" +.\" When distributing Covered Code, include this CDDL HEADER in each +.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. +.\" If applicable, add the following below this CDDL HEADER, with the +.\" fields enclosed by brackets "[]" replaced with your own identifying +.\" information: Portions Copyright [yyyy] [name of copyright owner] +.Dd August 31, 2018 +.Dt MTIO 7I +.Os +.Sh NAME +.Nm mtio +.Nd general magnetic tape interface +.Sh SYNOPSIS +.In sys/types.h +.In sys/ioctl.h +.In sys/mtio.h +.Sh DESCRIPTION 1/2", 1/4", 4mm, and 8mm magnetic tape drives all share the same general character device interface. -.sp -.LP +.Pp There are two types of tape records: data records and end-of-file (EOF) -records. S\fBEOF\fR records are also known as tape marks and file marks. A -record is separated by interrecord (or tape) gaps on a tape. -.sp -.LP -End-of-recorded-media (EOM) is indicated by two \fBEOF\fR marks on 1/2" tape; -by one \fBEOF\fR mark on 1/4", 4mm, and 8mm cartridge tapes. -.SS "1/2" Reel Tape" -.LP -Data bytes are recorded in parallel onto the 9-track tape. Since it is a -variable-length tape device, the number of bytes in a physical record may -vary. -.sp -.LP -The recording formats available (check specific tape drive) are 800 \fBBPI,\fR -1600 \fBBPI,\fR 6250 \fBBPI,\fR and data compression. Actual storage capacity -is a function of the recording format and the length of the tape reel. For -example, using a 2400 foot tape, 20 Mbyte can be stored using 800 \fBBPI,\fR 40 -Mbyte using 1600 \fBBPI,\fR 140 Mbyte using 6250 \fBBPI,\fR or up to 700 Mbyte -using data compression. -.SS "1/4" Cartridge Tape" -.LP -Data is recorded serially onto 1/4" cartridge tape. The number of bytes per -record is determined by the physical record size of the device. The I/O request -size must be a multiple of the physical record size of the device. For -\fBQIC-11,\fR \fBQIC-24,\fR and \fBQIC-150\fR tape drives, the block size is -512 bytes. -.sp -.LP -The records are recorded on tracks in a serpentine motion. As one track is +records. +.Sy EOF +records are also known as tape marks and file marks. +A record is separated by interrecord (or tape) gaps on a tape. +.Pp +End-of-recorded-media (EOM) is indicated by two +.Sy EOF +marks on 1/2\(dq tape; by one +.Sy EOF +mark on 1/4\(dq, 4mm, and 8mm cartridge tapes. +.Ss "1/2\(dq Reel Tape" +Data bytes are recorded in parallel onto the 9-track tape. +Since it is a +variable-length tape device, the number of bytes in a physical record may vary. +.Pp +The recording formats available (check specific tape drive) are 800 +.Sy BPI , +1600 +.Sy BPI , +6250 +.Sy BPI , +and data compression. +Actual storage capacity is a function of the recording format and the length of the tape reel. +For example, using a 2400 foot tape, 20 Mbyte can be stored using 800 +.Sy BPI , +40 Mbyte using 1600 +.Sy BPI , +140 Mbyte using 6250 +.Sy BPI , +or up to 700 Mbyte using data compression. +.Ss "1/4\(dq Cartridge Tape" +Data is recorded serially onto 1/4\(dq cartridge tape. +The number of bytes per +record is determined by the physical record size of the device. +The I/O request +size must be a multiple of the physical record size of the device. +For +.Sy QIC-11 , +.Sy QIC-24 , +and +.Sy QIC-150 +tape drives, the block size is 512 bytes. +.Pp +The records are recorded on tracks in a serpentine motion. +As one track is completed, the drive switches to the next and begins writing in the opposite -direction, eliminating the wasted motion of rewinding. Each file, including the -last, ends with one file mark. -.sp -.LP +direction, eliminating the wasted motion of rewinding. +Each file, including the last, ends with one file mark. +.Pp Storage capacity is based on the number of tracks the drive is capable of -recording. For example, 4-track drives can only record 20 Mbyte of data on a +recording. +For example, 4-track drives can only record 20 Mbyte of data on a 450 foot tape; 9-track drives can record up to 45 Mbyte of data on a tape of -the same length. \fBQIC-11\fR is the only tape format available for 4-track -tape drives. In contrast, 9-track tape drives can use either \fBQIC-24\fR or -\fBQIC-11.\fR Storage capacity is not appreciably affected by using either -format. \fBQIC-24\fR is preferable to \fBQIC-11\fR because it records a +the same length. +.Sy QIC-11 +is the only tape format available for 4-track +tape drives. +In contrast, 9-track tape drives can use either +.Sy QIC-24 +or +.Sy QIC-11 . +Storage capacity is not appreciably affected by using either format. +.Sy QIC-24 +is preferable to +.Sy QIC-11 +because it records a reference signal to mark the position of the first track on the tape, and each block has a unique block number. -.sp -.LP -The \fBQIC-150\fR tape drives require \fBDC-6150\fR (or equivalent) tape -cartridges for writing. However, they can read other tape cartridges in -\fBQIC-11,\fR \fBQIC-24,\fR or \fBQIC-120\fR tape formats. -.SS "8mm Cartridge Tape" -.LP -Data is recorded serially onto 8mm helical scan cartridge tape. Since it is a -variable-length tape device, the number of bytes in a physical record may -vary. The recording formats available (check specific tape drive) are standard +.Pp +The +.Sy QIC-150 +tape drives require +.Sy DC-6150 +(or equivalent) tape cartridges for writing. +However, they can read other tape cartridges in +.Sy QIC-11 , +.Sy QIC-24 , +or +.Sy QIC-120 +tape formats. +.Ss "8mm Cartridge Tape" +Data is recorded serially onto 8mm helical scan cartridge tape. +Since it is a +variable-length tape device, the number of bytes in a physical record may +vary. +The recording formats available (check specific tape drive) are standard 2Gbyte, 5Gbyte, and compressed format. -.SS "4mm DAT Tape" -.LP +.Ss "4mm DAT Tape" Data is recorded either in Digital Data Storage (DDS) tape format or in Digital -Data Storage, Data Compressed (DDS-DC) tape format. Since it is a -variable-length tape device, the number of bytes in a physical record may -vary. The recording formats available are standard 2Gbyte and compressed -format. -.SS "Persistent Error Handling" -.LP +Data Storage, Data Compressed (DDS-DC) tape format. +Since it is a +variable-length tape device, the number of bytes in a physical record may vary. +The recording formats available are standard 2Gbyte and compressed format. +.Ss "Persistent Error Handling" Persistent error handling is a modification of the current error handling -behaviors, BSD and SVR4. With persistent error handling enabled, all tape +behaviors, BSD and SVR4. +With persistent error handling enabled, all tape operations after an error or exception will return immediately with an error. Persistent error handling can be most useful with asynchronous tape operations -that use the \fBaioread\fR(3C) and \fBaiowrite\fR(3C) functions. -.sp -.LP -To enable persistent error handling, the ioctl \fBMTIOCPERSISTENT\fR must be -issued. If this ioctl succeeds, then persistent error handling is enabled and -changes the current error behavior. This ioctl will fail if the device driver +that use the +.Xr aioread 3C +and +.Xr aiowrite 3C +functions. +.Pp +To enable persistent error handling, the ioctl +.Dv MTIOCPERSISTENT +must be issued. +If this ioctl succeeds, then persistent error handling is enabled and +changes the current error behavior. +This ioctl will fail if the device driver does not support persistent error handling. -.sp -.LP +.Pp With persistent error handling enabled, all tape operations after an exception or error will return with the same error as the first command that failed; the -operations will not be executed. An exception is some event that might stop -normal tape operations, such as an End Of File (EOF) mark or an End Of Tape -(EOT) mark. An example of an error is a media error. The \fBMTIOCLRERR\fR ioctl -must be issued to allow normal tape operations to continue and to clear the -error. -.sp -.LP +operations will not be executed. +An exception is some event that might stop +normal tape operations, such as an End Of File (EOF) mark or an End Of Tape +(EOT) mark. +An example of an error is a media error. +The +.Dv MTIOCLRERR +ioctl must be issued to allow normal tape operations to continue and to clear +the error. +.Pp Disabling persistent error handling returns the error behavior to normal SVR4 error handling, and will not occur until all outstanding operations are -completed. Applications should wait for all outstanding operations to complete -before disabling persistent error handling. Closing the device will also +completed. +Applications should wait for all outstanding operations to complete +before disabling persistent error handling. +Closing the device will also disable persistent error handling and clear any errors or exceptions. -.sp -.LP -The \fBRead Operation\fR and \fBWrite Operation\fR subsections contain more -pertinent information reguarding persistent error handling. -.SS "Read Operation" -.LP -The \fBread\fR(2) function reads the next record on the tape. The record size -is passed back as the number of bytes read, provided it is not greater than the -number requested. When a tape mark or end of data is read, a zero byte count is +.Pp +The +.Sx Read Operation +and +.Sx Write Operation +subsections contain more pertinent information reguarding persistent error handling. +.Ss "Read Operation" +The +.Xr read 2 +function reads the next record on the tape. +The record size is passed back as the number of bytes read, provided it is not +greater than the number requested. +When a tape mark or end of data is read, a zero byte count is returned; all successive reads after the zero read will return an error and -\fBerrno\fR will be set to \fBEIO\fR. To move to the next file, an \fBMTFSF\fR -ioctl can be issued before or after the read causing the error. This error -handling behavior is different from the older \fBBSD\fR behavior, where another -read will fetch the first record of the next tape file. If the \fBBSD\fR -behavior is required, device names containing the letter \fBb\fR (for \fBBSD\fR -behavior) in the final component should be used. If persistent error handling +.Va errno +will be set to +.Er EIO . +To move to the next file, an +.Dv MTFSF +ioctl can be issued before or after the read causing the error. +This error +handling behavior is different from the older +.Sy BSD +behavior, where another read will fetch the first record of the next tape file. +If the +.Sy BSD +behavior is required, device names containing the letter +.Ql b +(for +.Sy BSD +behavior) in the final component should be used. +If persistent error handling was enabled with either the BSD or SVR4 tape device behavior, all operations -after this read error will return \fBEIO\fR errors until the \fBMTIOCLRERR\fR -ioctl is issued. An \fBMTFSF\fR ioctl can then he issued. -.sp -.LP +after this read error will return +.Er EIO +errors until the +.Dv MTIOCLRERR +ioctl is issued. +An +.Dv MTFSF +ioctl can then he issued. +.Pp Two successful successive reads that both return zero byte counts indicate -\fBEOM\fR on the tape. No further reading should be performed past the -\fBEOM.\fR -.sp -.LP +.Sy EOM +on the tape. +No further reading should be performed past the +.Sy EOM . +.Pp Fixed-length I/O tape devices require the number of bytes read to be a multiple -of the physical record size. For example, 1/4" cartridge tape devices only read -multiples of 512 bytes. If the blocking factor is greater than 64,512 bytes +of the physical record size. +For example, 1/4\(dq cartridge tape devices only read +multiples of 512 bytes. +If the blocking factor is greater than 64,512 bytes (minphys limit), fixed-length I/O tape devices read multiple records. -.sp -.LP +.Pp Most tape devices which support variable-length I/O operations may read a range -of 1 to 65,535 bytes. If the record size exceeds 65,535 bytes, the driver reads -multiple records to satisfy the request. These multiple records are limited to -65,534 bytes. Newer variable-length tape drivers may relax the above limitation -and allow applications to read record sizes larger than 65,534. Refer to the +of 1 to 65,535 bytes. +If the record size exceeds 65,535 bytes, the driver reads +multiple records to satisfy the request. +These multiple records are limited to +65,534 bytes. +Newer variable-length tape drivers may relax the above limitation +and allow applications to read record sizes larger than 65,534. +Refer to the specific tape driver man page for details. -.sp -.LP -Reading past logical \fBEOT\fR is transparent to the user. A read operation +.Pp +Reading past logical +.Sy EOT +is transparent to the user. +A read operation should never hit physical EOT. -.sp -.LP +.Pp Read requests that are lesser than a physical tape record are not allowed. Appropriate error is returned. -.SS "Write Operation" -.LP -The \fBwrite\fR(2) function writes the next record on the tape. The record has +.Ss "Write Operation" +The +.Xr write 2 +function writes the next record on the tape. +The record has the same length as the given buffer. -.sp -.LP +.Pp Writing is allowed on 1/4" tape at either the beginning of tape or after the -last written file on the tape. With the Exabyte 8200, data may be appended only +last written file on the tape. +With the Exabyte 8200, data may be appended only at the beginning of tape, before a filemark, or after the last written file on the tape. -.sp -.LP -Writing is not so restricted on 1/2", 4mm, and the other 8mm cartridge tape -drives. Care should be used when appending files onto 1/2" reel tape devices, -since an extra file mark is appended after the last file to mark the \fBEOM.\fR -This extra file mark must be overwritten to prevent the creation of a null -file. To facilitate write append operations, a space to the \fBEOM\fR ioctl is -provided. Care should be taken when overwriting records; the erase head is just +.Pp +Writing is not so restricted on 1/2\(dq, 4mm, and the other 8mm cartridge tape +drives. +Care should be used when appending files onto 1/2\(dq reel tape devices, +since an extra file mark is appended after the last file to mark the +.Sy EOM . +This extra file mark must be overwritten to prevent the creation of a null file. +To facilitate write append operations, a space to the +.Sy EOM +ioctl is provided. +Care should be taken when overwriting records; the erase head is just forward of the write head and any following records will also be erased. -.sp -.LP +.Pp Fixed-length I/O tape devices require the number of bytes written to be a -multiple of the physical record size. For example, 1/4" cartridge tape devices +multiple of the physical record size. +For example, 1/4\(dq cartridge tape devices only write multiples of 512 bytes. -.sp -.LP +.Pp Fixed-length I/O tape devices write multiple records if the blocking factor is -greater than 64,512 bytes (minphys limit). These multiple writes are limited to -64,512 bytes. For example, if a write request is issued for 65,536 bytes using -a 1/4" cartridge tape, two writes are issued; the first for 64,512 bytes and +greater than 64,512 bytes (minphys limit). +These multiple writes are limited to +64,512 bytes. +For example, if a write request is issued for 65,536 bytes using +a 1/4\(dq cartridge tape, two writes are issued; the first for 64,512 bytes and the second for 1024 bytes. -.sp -.LP +.Pp Most tape devices which support variable-length I/O operations may write a -range of 1 to 65,535 bytes. If the record size exceeds 65,535 bytes, the driver -writes multiple records to satisfy the request. These multiple records are -limited to 65,534 bytes. As an example, if a write request for 65,540 bytes is +range of 1 to 65,535 bytes. +If the record size exceeds 65,535 bytes, the driver +writes multiple records to satisfy the request. +These multiple records are +limited to 65,534 bytes. +As an example, if a write request for 65,540 bytes is issued, two records are written; one for 65,534 bytes followed by another -record for 6 bytes. Newer variable-length tape drivers may relax the above -limitation and allow applications to write record sizes larger than 65,534. -Refer to the specific tape driver man page for details. -.sp -.LP -When logical \fBEOT\fR is encountered during a write, that write operation +record for 6 bytes. +Newer variable-length tape drivers may relax the above +limitation and allow applications to write record sizes larger than 65,534. +effer to the specific tape driver man page for details. +.Pp +When logical +.Sy EOT +is encountered during a write, that write operation completes and the number of bytes successfully transferred is returned (note that a 'short write' may have occurred and not all the requested bytes would -have been transferred. The actual amount of data written will depend on the -type of device being used). The next write will return a zero byte count. A -third write will successfully transfer some bytes (as indicated by the returned -byte count, which again could be a short write); the fourth will transfer zero -bytes, and so on, until the physical \fBEOT\fR is reached and all writes will -fail with \fBEIO\fR. -.sp -.LP -When logical \fBEOT\fR is encountered with persistent error handling enabled, -the current write may complete or be a short write. The next write will return -a zero byte count. At this point an application should act appropriately for +have been transferred. +The actual amount of data written will depend on the +type of device being used). +The next write will return a zero byte count. +A third write will successfully transfer some bytes (as indicated by the +returned byte count, which again could be a short write); the fourth will +transfer zero bytes, and so on, until the physical +.Sy EOT +is reached and all writes will +fail with +.Er EIO . +.Pp +When logical +.Sy EOT +is encountered with persistent error handling enabled, +the current write may complete or be a short write. +The next write will return a zero byte count. +At this point an application should act appropriately for end of tape cleanup or issue yet another write, which will return the error -\fBENOSPC\fR. After clearing the exception with \fBMTIOCLRERR\fR, the next -write will succeed (possibly short), followed by another zero byte write count, -and then another \fBENOSPC\fR error. -.sp -.LP -Allowing writes after \fBLEOT\fR has been encountered enables the flushing of -buffers. However, it is strongly recommended to terminate the writing and close +.Er ENOSPC . +After clearing the exception with +.Dv MTIOCLRERR , +the next write will succeed (possibly short), followed by another zero byte +write count, and then another +.Er ENOSPC +error. +.Pp +Allowing writes after +.Sy EOT +has been encountered enables the flushing of buffers. +However, it is strongly recommended to terminate the writing and close the file as soon as possible. -.sp -.LP +.Pp Seeks are ignored in tape I/O. -.SS "Close Operation" -.LP +.Ss "Close Operation" Magnetic tapes are rewound when closed, except when the "no-rewind" devices -have been specified. The names of no-rewind device files use the letter \fBn\fR -as the end of the final component. The no-rewind version of \fB/dev/rmt/0l\fR -is \fB/dev/rmt/0ln\fR. In case of error for a no-rewind device, the next open -rewinds the device. -.sp -.LP +have been specified. +The names of no-rewind device files use the letter +.Ql n +as the end of the final component. +The no-rewind version of +.Pa /dev/rmt/0l +is +.Pa /dev/rmt/0ln . +In case of error for a no-rewind device, the next open rewinds the device. +.Pp If the driver was opened for reading and a no-rewind device has been specified, the close advances the tape past the next filemark (unless the current file -position is at \fBEOM),\fR leaving the tape correctly positioned to read the -first record of the next file. However, if the tape is at the first record of a -file it doesn't advance again to the first record of the next file. These -semantics are different from the older \fBBSD\fR behavior. If \fBBSD\fR +position is at +.Sy EOM ) , +leaving the tape correctly positioned to read the first record of the next file. +However, if the tape is at the first record of a +file it doesn't advance again to the first record of the next file. +These semantics are different from the older +.Sy BSD +behavior. +If +.Sy BSD behavior is required where no implicit space operation is executed on close, -the non-rewind device name containing the letter \fBb\fR (for \fBBSD\fR +the non-rewind device name containing the letter +.Ql b +(for +.Sy BSD behavior) in the final component should be specified. -.sp -.LP +.Pp If data was written, a file mark is automatically written by the driver upon -close. If the rewinding device was specified, the tape will be rewound after -the file mark is written. If the user wrote a file mark prior to closing, then -no file mark is written upon close. If a file positioning ioctl, like rewind, +close. +If the rewinding device was specified, the tape will be rewound after +the file mark is written. +If the user wrote a file mark prior to closing, then +no file mark is written upon close. +If a file positioning ioctl, like rewind, is issued after writing, a file mark is written before repositioning the tape. -.sp -.LP -All buffers are flushed on closing a tape device. Hence, it is strongly -recommended that the application wait for all buffers to be flushed before -closing the device. This can be done by writing a filemark via \fBMTWEOF,\fR +.Pp +All buffers are flushed on closing a tape device. +Hence, it is strongly recommended that the application wait for all buffers to +be flushed before closing the device. +This can be done by writing a filemark via +.Dv MTWEOF , even with a zero count. -.sp -.LP -Note that for 1/2" reel tape devices, two file marks are written to mark the -\fBEOM\fR before rewinding or performing a file positioning ioctl. If the user -wrote a file mark before closing a 1/2" reel tape device, the driver will +.Pp +Note that for 1/2\(dq reel tape devices, two file marks are written to mark the +.Sy EOM +before rewinding or performing a file positioning ioctl. +If the user +wrote a file mark before closing a 1/2\(dq reel tape device, the driver will always write a file mark before closing to insure that the end of recorded -media is marked properly. If the non-rewinding device was specified, two file +media is marked properly. +If the non-rewinding device was specified, two file marks are written and the tape is left positioned between the two so that the -second one is overwritten on a subsequent \fBopen\fR(2) and \fBwrite\fR(2). -.sp -.LP -If no data was written and the driver was opened for \fBWRITE-ONLY\fR access, -one or two file marks are written, thus creating a null file. -.sp -.LP +second one is overwritten on a subsequent +.Xr open 2 +and +.Xr write 2 . +.Pp +If no data was written and the driver was opened for +.Sy WRITE-ONLY +access, one or two file marks are written, thus creating a null file. +.Pp After closing the device, persistent error handling will be disabled and any error or exception will be cleared. -.SH IOCTLS -.LP -Not all devices support all \fBioctls\fR. The driver returns an \fBENOTTY\fR +.Sh IOCTLS +Not all devices support all +.Sy ioctls . +The driver returns an +.Er ENOTTY error on unsupported ioctls. -.sp -.LP -The following structure definitions for magnetic tape \fBioctl \fRcommands are -from \fB<sys/mtio.h>\fR\&. -.sp -.LP -The minor device byte structure is:: -.sp -.in +2 -.nf +.Pp +The following structure definitions for magnetic tape +.Xr ioctl 2 +commands are from +.In sys/mtio.h . +.Pp +The minor device byte structure is: +.Bd -literal 15 7 6 5 4 3 2 1 0 ________________________________________________________________________ Unit # BSD Reserved Density Density No rewind Unit # Bits 7-15 behavior Select Select on Close Bits 0-1 -.fi -.in -2 - -.sp -.in +2 -.nf +.Ed +.Bd -literal /* * Layout of minor device byte: */ -#define MTUNIT(dev) (((minor(dev) & 0xff80) >> 5) + -(minor(dev) & 0x3)) +#define MTUNIT(dev) (((minor(dev) & 0xff80) >> 5) + (minor(dev) & 0x3)) #define MT_NOREWIND (1 <<2) #define MT_DENSITY_MASK (3 <<3) #define MT_DENSITY1 (0 <<3) /* Lowest density/format */ @@ -310,251 +423,95 @@ Bits 7-15 behavior Select Select on Close Bits 0-1 #define MT_DENSITY3 (2 <<3) #define MT_DENSITY4 (3 <<3) /* Highest density/format */ #define MTMINOR(unit) (((unit & 0x7fc) << 5) + (unit & 0x3)) -#define MT_BSD (1 <<6) /* BSD behavior on close */ +#define MT_BSD (1 <<6) /* BSD behavior on close */ +/* Structure for MTIOCTOP - magnetic tape operation command */ -/* Structure for MTIOCTOP \(mi magnetic tape operation command */ - -struct mtop { +struct mtop { short mt_op; /* operation */ daddr_t mt_count; /* number of operations */ }; -.fi -.in -2 -.sp -.in +2 -.nf /* Structure for MTIOCLTOP - magnetic tape operation command */ Works exactly like MTIOCTOP except passes 64 bit mt_count values. -struct mtlop { +struct mtlop { short mt_op; short pad[3]; int64_t mt_count; }; -.fi -.in -2 - -.sp -.LP -The following operations of \fBMTIOCTOP\fR and \fBMTIOCLTOP\fR ioctls are -supported: -.sp -.ne 2 -.na -\fBMTWEOF\fR -.ad -.RS 17n -write an end-of-file record -.RE - -.sp -.ne 2 -.na -\fBMTFSF\fR -.ad -.RS 17n -forward space over file mark -.RE - -.sp -.ne 2 -.na -\fBMTBSF\fR -.ad -.RS 17n -backward space over file mark (1/2", 8mm only) -.RE - -.sp -.ne 2 -.na -\fBMTFSR\fR -.ad -.RS 17n -forward space to inter-record gap -.RE - -.sp -.ne 2 -.na -\fBMTBSR\fR -.ad -.RS 17n -backward space to inter-record gap -.RE - -.sp -.ne 2 -.na -\fBMTREW\fR -.ad -.RS 17n -rewind -.RE - -.sp -.ne 2 -.na -\fBMTOFFL\fR -.ad -.RS 17n -rewind and take the drive off-line -.RE - -.sp -.ne 2 -.na -\fBMTNOP\fR -.ad -.RS 17n -no operation, sets status only -.RE - -.sp -.ne 2 -.na -\fBMTRETEN\fR -.ad -.RS 17n -retension the tape (cartridge tape only) -.RE - -.sp -.ne 2 -.na -\fBMTERASE\fR -.ad -.RS 17n -erase the entire tape and rewind -.RE - -.sp -.ne 2 -.na -\fBMTEOM\fR -.ad -.RS 17n -position to EOM -.RE - -.sp -.ne 2 -.na -\fBMTNBSF\fR -.ad -.RS 17n -backward space file to beginning of file -.RE - -.sp -.ne 2 -.na -\fBMTSRSZ\fR -.ad -.RS 17n -set record size -.RE - -.sp -.ne 2 -.na -\fBMTGRSZ\fR -.ad -.RS 17n -get record size -.RE - -.sp -.ne 2 -.na -\fBMTTELL\fR -.ad -.RS 17n -get current position -.RE - -.sp -.ne 2 -.na -\fBMTSEEK\fR -.ad -.RS 17n -go to requested position -.RE - -.sp -.ne 2 -.na -\fBMTFSSF\fR -.ad -.RS 17n -forward to requested number of sequential file marks -.RE - -.sp -.ne 2 -.na -\fBMTBSSF\fR -.ad -.RS 17n -backward to requested number of sequential file marks -.RE - -.sp -.ne 2 -.na -\fBMTLOCK\fR -.ad -.RS 17n -prevent media removal -.RE - -.sp -.ne 2 -.na -\fBMTUNLOCK\fR -.ad -.RS 17n -allow media removal -.RE - -.sp -.ne 2 -.na -\fBMTLOAD\fR -.ad -.RS 17n -load the next tape cartridge into the tape drive -.RE - -.sp -.ne 2 -.na -\fBMTIOCGETERROR\fR -.ad -.RS 17n -retrieve error records from the st driver -.RE - -.sp -.in +2 -.nf -/* structure for MTIOCGET \(mi magnetic tape get status command */ +.Ed +.Pp +The following operations of +.Dv MTIOCTOP +and +.Dv MTIOCLTOP +ioctls are supported: +.Pp +.Bl -tag -width MTIOCGETERROR -compact -offset 2n +.It Dv MTWEOF +Write an end-of-file record +.It Dv MTFSF +Forward space over file mark +.It Dv MTBSF +Backward space over file mark (1/2", 8mm only) +.It Dv MTFSR +Forward space to inter-record gap +.It Dv MTBSR +Backward space to inter-record gap +.It Dv MTREW +Rewind +.It Dv MTOFFL +Rewind and take the drive off-line +.It Dv MTNOP +No operation, sets status only +.It Dv MTRETEN +Retension the tape (cartridge tape only) +.It Dv MTERASE +Erase the entire tape and rewind +.It Dv MTEOM +Position to EOM +.It Dv MTNBSF +Backward space file to beginning of file +.It Dv MTSRSZ +Set record size +.It Dv MTGRSZ +Get record size +.It Dv MTTELL +Get current position +.It Dv MTSEEK +Go to requested position +.It Dv MTFSSF +Forward to requested number of sequential file marks +.It Dv MTBSSF +Backward to requested number of sequential file marks +.It Dv MTLOCK +Prevent media removal +.It Dv MTUNLOCK +Allow media removal +.It Dv MTLOAD +Load the next tape cartridge into the tape drive +.It Dv MTIOCGETERROR +Retrieve error records from the st driver +.El +.Bd -literal -offset 2n +/* structure for MTIOCGET - magnetic tape get status command */ struct mtget { short mt_type; /* type of magtape device */ -/* the following two registers are device dependent */ + + /* the following two registers are device dependent */ short mt_dsreg; /* "drive status" register */ short mt_erreg; /* "error" register */ -/* optional error info. */ + + /* optional error info. */ daddr_t mt_resid; /* residual count */ daddr_t mt_fileno; /* file number of current position */ daddr_t mt_blkno; /* block number of current position */ ushort_t mt_flags; short mt_bf; /* optimum blocking factor */ }; -/* structure for MTIOCGETDRIVETYPE \(mi get tape config data command */ + +/* structure for MTIOCGETDRIVETYPE - get tape config data command */ struct mtdrivetype_request { int size; struct mtdrivetype *mtdtp; @@ -578,516 +535,618 @@ struct mtdrivetype { ushort_t unload_timeout; /* Seconds to unload */ ushort_t erase_timeout; /* Seconds to do long erase */ }; -.fi -.in -2 - -.sp -.in +2 -.nf +.Ed +.Bd -literal -offset 2n /* structure for MTIOCGETPOS and MTIOCRESTPOS - get/set tape position */ - /* - * eof/eot/eom codes. - */ +/* + * eof/eot/eom codes. + */ typedef enum { ST_NO_EOF, ST_EOF_PENDING, /* filemrk pending */ ST_EOF, /* at filemark */ - ST_EOT_PENDING, /* logical eot pend. */ + ST_EOT_PENDING, /* logical eot pend. */ ST_EOT, /* at logical eot */ ST_EOM, /* at physical eot */ ST_WRITE_AFTER_EOM /* flag allowing writes after EOM */ - }pstatus; +} pstatus; - typedef enum { invalid, legacy, logical } posmode; +typedef enum { invalid, legacy, logical } posmode; - typedef struct tapepos { - uint64_t lgclblkno; /* Blks from start of partition */ - int32_t fileno; /* Num. of current file */ - int32_t blkno; /* Blk number in current file */ - int32_t partition; /* Current partition */ - pstatus eof; /* eof states */ - posmode pmode; /* which pos. data is valid */ - char pad[4]; - }tapepos_t; - - If the pmode is legacy,fileno and blkno fields are valid. - If the pmode is logical, lgclblkno field is valid. -.fi -.in -2 - -.sp -.LP -The \fBMTWEOF\fR ioctl is used for writing file marks to tape. Not only does +typedef struct tapepos { + uint64_t lgclblkno; /* Blks from start of partition */ + int32_t fileno; /* Num. of current file */ + int32_t blkno; /* Blk number in current file */ + int32_t partition; /* Current partition */ + pstatus eof; /* eof states */ + posmode pmode; /* which pos. data is valid */ + char pad[4]; +} tapepos_t; +.Ed +.Pp +.Bd -ragged -compact +If the +.Fa pmode +is legacy, +.Fa fileno +and +.Fa blkno +fields are valid. +.Pp +If the +.Fa pmode +is logical, +.Fa lgclblkno +field is valid. +.Ed +.Pp +The +.Dv MTWEOF +ioctl is used for writing file marks to tape. +Not only does this signify the end of a file, but also usually has the side effect of -flushing all buffers in the tape drive to the tape medium. A zero count -\fBMTWEOF\fR will just flush all the buffers and will not write any file marks. +flushing all buffers in the tape drive to the tape medium. +A zero count +.Dv MTWEOF +will just flush all the buffers and will not write any file marks. Because a successful completion of this tape operation will guarantee that all tape data has been written to the tape medium, it is recommended that this tape operation be issued before closing a tape device. -.sp -.LP -When spacing forward over a record (either data or \fBEOF),\fR the tape head is +.Pp +When spacing forward over a record (either data or +.Sy EOF ) , +the tape head is positioned in the tape gap between the record just skipped and the next record. When spacing forward over file marks (EOF records), the tape head is positioned -in the tape gap between the next \fBEOF\fR record and the record that follows -it. -.sp -.LP -When spacing backward over a record (either data or \fBEOF),\fR the tape head -is positioned in the tape gap immediately preceding the tape record where the -tape head is currently positioned. When spacing backward over file marks (EOF -records), the tape head is positioned in the tape gap preceding the \fBEOF.\fR -Thus the next read would fetch the \fBEOF.\fR -.sp -.LP +in the tape gap between the next +.Sy EOF +record and the record that follows it. +.Pp +When spacing backward over a record (either data or +.Sy EOF ) , +the tape head is positioned in the tape gap immediately preceding the tape +record where the tape head is currently positioned. +When spacing backward over file marks (EOF records), the tape head is +positioned in the tape gap preceding the +.Sy EOF . +Thus the next read would fetch the +.Sy EOF . +.Pp Record skipping does not go past a file mark; file skipping does not go past -the \fBEOM.\fR After an \fBMTFSR\fR <huge number> command, the driver leaves -the tape logically positioned \fIbefore\fR the \fBEOF.\fR A related feature is -that \fBEOFs\fR remain pending until the tape is closed. For example, a program +the +.Sy EOM . +After an +.Dv MTFSR +<huge number> command, the driver leaves +the tape logically positioned +.Em before +the +.Sy EOF . +A related feature is that +.Sy EOF Ns s +remain pending until the tape is closed. +For example, a program which first reads all the records of a file up to and including the \fBEOF\fR -and then performs an \fBMTFSF\fR command will leave the tape positioned just -after that same \fBEOF,\fR rather than skipping the next file. -.sp -.LP -The \fBMTNBSF\fR and \fBMTFSF\fR operations are inverses. Thus, an " -\fBMTFSF\fR \(mi1" is equivalent to an " \fBMTNBSF\fR 1". An " \fBMTNBSF\fR 0" -is the same as " \fBMTFSF\fR 0"; both position the tape device at the beginning -of the current file. -.sp -.LP -\fBMTBSF\fR moves the tape backwards by file marks. The tape position will end -on the beginning of the tape side of the desired file mark. An " \fBMTBSF\fR 0" +and then performs an +.Dv MTFSF +command will leave the tape positioned just +after that same +.Sy EOF , +rather than skipping the next file. +.Pp +The +.Dv MTNBSF +and +.Dv MTFSF +operations are inverses. +Thus, an +.Dq Dv MTFSF \(mi1 +is equivalent to an +.Dq Dv MTNBSF 1 . +An +.Dq Dv MTNBSF 0 +is the same as +.Dq Dv MTFSF 0 ; +both position the tape device at the beginning of the current file. +.Pp +.Dv MTBSF +moves the tape backwards by file marks. +The tape position will end +on the beginning of the tape side of the desired file mark. +An +.Dq Dv MTBSF 0 will position the tape at the end of the current file, before the filemark. -.sp -.LP -\fBMTBSR\fR and \fBMTFSR\fR operations perform much like space file operations, -except that they move by records instead of files. Variable-length I/O devices -(1/2" reel, for example) space actual records; fixed-length I/O devices space -physical records (blocks). 1/4" cartridge tape, for example, spaces 512 byte -physical records. The status ioctl residual count contains the number of files +.Pp +.Dv MTBSR +and +.Dv MTFSR +operations perform much like space file operations, +except that they move by records instead of files. +Variable-length I/O devices +(1/2\(dq reel, for example) space actual records; fixed-length I/O devices space +physical records (blocks). +1/4\(dq cartridge tape, for example, spaces 512 byte +physical records. +The status ioctl residual count contains the number of files or records not skipped. -.sp -.LP -MTFSSF and MTBSSF space forward or backward, respectively, to the next -occurrence of the requested number of file marks, one following another. If -there are more sequential file marks on tape than were requested, it spaces -over the requested number and positions after the requested file mark. Note -that not all drives support this command and if a request is sent to a drive -that does not, \fBENOTTY\fR is returned. -.sp -.LP -\fBMTOFFL\fR rewinds and, if appropriate, takes the device off-line by -unloading the tape. It is recommended that the device be closed after offlining +.Pp +.Dv MTFSSF +and +.Dv MTBSSF +space forward or backward, respectively, to the next +occurrence of the requested number of file marks, one following another. +If there are more sequential file marks on tape than were requested, it spaces +over the requested number and positions after the requested file mark. +Note that not all drives support this command and if a request is sent to a +drive that does not, +.Er ENOTTY +is returned. +.Pp +.Dv MTOFFL +rewinds and, if appropriate, takes the device off-line by unloading the tape. +It is recommended that the device be closed after offlining and then re-opened after a tape has been inserted to facilitate portability to -other platforms and other operating systems. Attempting to re-open the device -with no tape will result in an error unless the \fBO_NDELAY\fR flag is used. -(See \fBopen\fR(2).) -.sp -.LP -The \fBMTRETEN\fR retension ioctl applies only to 1/4" cartridge tape devices. +other platforms and other operating systems. +Attempting to re-open the device +with no tape will result in an error unless the +.Dv O_NDELAY +flag is used. +.Po +See +.Xr open 2 . +.Pc +.Pp +The +.Dv MTRETEN +retension ioctl applies only to 1/4\(dq cartridge tape devices. It is used to restore tape tension, improving the tape's soft error rate after extensive start-stop operations or long-term storage. -.sp -.LP -\fBMTERASE\fR rewinds the tape, erases it completely, and returns to the -beginning of tape. Erasing may take a long time depending on the device and/or -tapes. For time details, refer to the drive specific manual. -.sp -.LP -\fBMTEOM\fR positions the tape at a location just after the last file written -on the tape. For 1/4" cartridge and 8mm tape, this is after the last file mark -on the tape. For 1/2" reel tape, this is just after the first file mark but -before the second (and last) file mark on the tape. Additional files can then +.Pp +.Dv MTERASE +rewinds the tape, erases it completely, and returns to the +beginning of tape. +Erasing may take a long time depending on the device and/or +tapes. +For time details, refer to the drive specific manual. +.Pp +.Dv MTEOM +positions the tape at a location just after the last file written +on the tape. +For 1/4\(dq cartridge and 8mm tape, this is after the last file mark +on the tape. +For 1/2\(dq reel tape, this is just after the first file mark but +before the second (and last) file mark on the tape. +Additional files can then be appended onto the tape from that point. -.sp -.LP -Note the difference between \fBMTBSF\fR (backspace over file mark) and -\fBMTNBSF\fR (backspace file to beginning of file). The former moves the tape -backward until it crosses an \fBEOF\fR mark, leaving the tape positioned -\fIbefore\fR the file mark. The latter leaves the tape positioned \fIafter\fR -the file mark. Hence, "\fBMTNBSF\fR n" is equivalent to "\fBMTBSF\fR (n+1)" -followed by "\fBMTFSF\fR 1". The 1/4" cartridge tape devices do not support -\fBMTBSF.\fR -.sp -.LP -\fBMTSRSZ\fR and \fBMTGRSZ\fR are used to set and get fixed record lengths. The -\fBMTSRSZ\fR ioctl allows variable length and fixed length tape drives that -support multiple record sizes to set the record length. The \fBmt_count\fR -field of the \fBmtop\fR struct is used to pass the record size to/from the -\fBst\fR driver. A value of \fB0\fR indicates variable record size. The -\fBMTSRSZ\fR ioctl makes a variable-length tape device behave like a -fixed-length tape device. Refer to the specific tape driver man page for +.Pp +Note the difference between +.Dv MTBSF +(backspace over file mark) and +.Dv MTNBSF +(backspace file to beginning of file). +The former moves the tape +backward until it crosses an +.Sy EOF +mark, leaving the tape positioned +.Em before +the file mark. +The latter leaves the tape positioned +.Em after +the file mark. +Hence, +.Dq Dv MTNBSF n +is equivalent to +.Dq Dv MTBSF (n+1) +followed by +.Dq Dv MTFSF 1 . +The 1/4\(dq cartridge tape devices do not support +.Dv MTBSF . +.Pp +.Dv MTSRSZ +and +.Dv MTGRSZ +are used to set and get fixed record lengths. +The +.Dv MTSRSZ +ioctl allows variable length and fixed length tape drives that +support multiple record sizes to set the record length. +The +.Fa mt_count +field of the +.Vt mtop +struct is used to pass the record size to/from the +.Xr st 7D +driver. +A value of +.Ql 0 +indicates variable record size. +The +.Dv MTSRSZ +ioctl makes a variable-length tape device behave like a +fixed-length tape device. +Refer to the specific tape driver man page for details. -.sp -.LP -\fBMTLOAD\fR loads the next tape cartridge into the tape drive. This is -generally only used with stacker and tower type tape drives which handle -multiple tapes per tape drive. A tape device without a tape inserted can be -opened with the \fBO_NDELAY\fR flag, in order to execute this operation. -.sp -.LP -\fBMTIOCGETERROR\fR allows user-level applications to retrieve error records -from the \fBst\fR driver. An error record consists of the SCSI command cdb -which causes the error and a \fBscsi_arq_status\fR(9S) structure if available. +.Pp +.Dv MTLOAD +loads the next tape cartridge into the tape drive. +This is generally only used with stacker and tower type tape drives which handle +multiple tapes per tape drive. +A tape device without a tape inserted can be +opened with the +.Dv O_NDELAY +flag, in order to execute this operation. +.Pp +.Dv MTIOCGETERROR +allows user-level applications to retrieve error records +from the +.Xr st 7D +driver. +An error record consists of the SCSI command cdb +which causes the error and a +.Xr scsi_arq_status 9S +structure if available. The user-level application is responsible for allocating and releasing the -memory for mtee_cdb_buf and scsi_arq_status of each mterror_entry. Before -issuing the ioctl, the mtee_arq_status_len value should be at least equal to -"sizeof(struct scsi_arq_status)." If more sense data than the size of -\fBscsi_arq_status\fR(9S) is desired, the mtee_arq_status_len may be larger -than "sizeof(struct scsi_arq_status)" by the amount of additional extended -sense data desired. The es_add_len field of \fBscsi_extended_sense\fR(9S) can -be used to determine the amount of valid sense data returned by the device. -.sp -.LP -The \fBMTIOCGET\fR get status \fBioctl\fR call returns the drive ID -(\fImt_type\fR), sense key error (\fImt_erreg\fR), file number -(\fImt_fileno\fR), optimum blocking factor (\fImt_bf\fR) and record number -(\fImt_blkno\fR) of the last error. The residual count (\fImt_resid\fR) is set -to the number of bytes not transferred or files/records not spaced. The flags -word (\fImt_flags\fR) contains information indicating if the device is SCSI, if -the device is a reel device and whether the device supports absolute file -positioning. The \fImt_flags\fR also indicates if the device is requesting -cleaning media be used, whether the device is capable of reporting the -requirement of cleaning media and if the currently loaded media is WORM (Write -Once Read Many) media. -.LP -Note - -.sp -.RS 2 -When tape alert cleaning is managed by the st driver, the tape target driver -may continue to return a "drive needs cleaning" status unless an MTIOCGET -ioctl() call is made while the cleaning media is in the drive. -.RE -.sp -.LP -The \fBMTIOCGETDRIVETYPE\fR get drivetype ioctl call returns the name of the -tape drive as defined in \fBst.conf\fR (\fIname\fR), Vendor \fBID\fR and model -(\fIproduct\fR), \fBID\fR (\fIvid\fR), type of tape device (\fBtype\fR), block -size (\fIbsize\fR), drive options (\fIoptions\fR), maximum read retry count -(\fImax_rretries\fR), maximum write retry count (\fImax_wretries\fR), densities -supported by the drive (\fIdensities\fR), and default density of the tape drive -(\fIdefault_density\fR). -.sp -.LP -The MTIOCGETPOS ioctl returns the current tape position of the drive. It is -returned in struct tapepos as defined in -\fB/usr/include/sys/scsi/targets/stdef.h\fR. -.sp -.LP -The MTIOCRESTPOS ioctl restores a saved position from the MTIOCGETPOS. -.SS "Persistent Error Handling IOCTLs and Asynchronous Tape Operations" -.ne 2 -.na -\fBMTIOCPERSISTENT\fR -.ad -.RS 25n +memory for +.Fa mtee_cdb_buf +and +.Fa scsi_arq_status of each +.Vt mterror_entry . +Before issuing the ioctl, the +.Fa mtee_arq_status_len +value should be at least equal to +.Ql sizeof (struct scsi_arq_status) . +If more sense data than the size of +.Xr scsi_arq_status 9S +is desired, the +.Fa mtee_arq_status_len +may be larger than +.Ql sizeof (struct scsi_arq_status) +by the amount of additional extended sense data desired. +The +.Fa es_add_len +field of +.Xr scsi_extended_sense 9S +can be used to determine the amount of valid sense data returned by the device. +.Pp +The +.Dv MTIOCGET +get status +.Xr ioctl 2 +call returns the drive ID +.Pq Fa mt_type , +sense key error +.Pq Fa mt_erreg , +file number +.Pq Fa mt_fileno , +optimum blocking factor +.Pq Fa mt_bf +and record number +.Pq Fa mt_blkno +of the last error. +The residual count +.Pq Fa mt_resid +is set to the number of bytes not transferred or files/records not spaced. +The flags word +.Pq Fa mt_flags +contains information indicating if the device is SCSI, if the device is a reel +device and whether the device supports absolute file positioning. +The +.Fa mt_flags +also indicates if the device is requesting cleaning media be used, whether the +device is capable of reporting the requirement of cleaning media and if the +currently loaded media is WORM (Write Once Read Many) media. +.Pp +Note \(em When tape alert cleaning is managed by the st driver, the tape +target driver may continue to return a +.Dq drive needs cleaning +status unless an +.Dv MTIOCGE +.Xr ioct 2 +call is made while the cleaning media is in the drive. +.Pp +The +.Dv MTIOCGETDRIVETYPE +get drivetype ioctl call returns the name of the +tape drive as defined in +.Pa st.conf +.Pq Fa name , +Vendor +.Sy ID +and model +.Pq Fa product , +.Sy ID +.Pq Fa vid , +type of tape device +.Pq Fa type , +block size +.Pq Fa size , +drive options +.Pq Fa options , +maximum read retry count +.Pq Fa max_rretries , +maximum write retry count +.Pq Fa max_wretries , +densities supported by the drive +.Pq Fa densities , +and default density of the tape drive +.Pq Fa default_density . +.Pp +The +.Dv MTIOCGETPOS +ioctl returns the current tape position of the drive. +It is returned in struct tapepos as defined in +.Pa /usr/include/sys/scsi/targets/stdef.h . +.Pp +The +.Dv MTIOCRESTPOS +ioctl restores a saved position from the +.Dv MTIOCGETPOS . +.Ss "Persistent Error Handling IOCTLs and Asynchronous Tape Operations" +.Bl -tag -width MTIOCPERSISTENTSTATUS -compact +.It Dv MTIOCPERSISTENT enables/disables persistent error handling -.RE - -.sp -.ne 2 -.na -\fBMTIOCPERSISTENTSTATUS\fR -.ad -.RS 25n +.It Dv MTIOCPERSISTENTSTATUS queries for persistent error handling -.RE - -.sp -.ne 2 -.na -\fBMTIOCLRERR\fR -.ad -.RS 25n +.It Dv MTIOCLRERR clears persistent error handling -.RE - -.sp -.ne 2 -.na -\fBMTIOCGUARANTEEDORDER\fR -.ad -.RS 25n +.It Dv MTIOCGUARANTEEDORDER checks whether driver guarantees order of I/O's -.RE - -.sp -.LP -The \fBMTIOCPERSISTENT\fR ioctl enables or disables persistent error handling. +.El +.Pp +The +.Dv MTIOCPERSISTENT +ioctl enables or disables persistent error handling. It takes as an argument a pointer to an integer that turns it either on or off. -If the ioctl succeeds, the desired operation was successful. It will wait for +If the ioctl succeeds, the desired operation was successful. +It will wait for all outstanding I/O's to complete before changing the persistent error handling -status. For example, -.sp -.in +2 -.nf +status. +For example, +.Bd -literal -offset 2n int on = 1; ioctl(fd, MTIOCPERSISTENT, &on); int off = 0; ioctl(fd, MTIOCPERSISTENT, &off); -.fi -.in -2 - -.sp -.LP -The \fBMTIOCPERSISTENTSTATUS\fR ioctl enables or disables persistent error -handling. It takes as an argument a pointer to an integer inserted by the -driver. The integer can be either 1 if persistent error handling is 'on', or 0 -if persistent error handling is 'off'. It will not wait for outstanding I/O's. +.Ed +.Pp +The +.Dv MTIOCPERSISTENTSTATUS +ioctl enables or disables persistent error +handling. +It takes as an argument a pointer to an integer inserted by the +driver. +The integer can be either 1 if persistent error handling is +.Sq on , +or 0 if persistent error handling is +.Sq off . +It will not wait for outstanding I/O's. For example, -.sp -.in +2 -.nf +.Bd -literal -offset 2n int query; ioctl(fd, MTIOCPERSISTENTSTATUS, &query); -.fi -.in -2 - -.sp -.LP -The \fBMTIOCLRERR\fR ioctl clears persistent error handling and allows tape -operations to continual normally. This ioctl requires no argument and will -always succeed, even if persistent error handling has not been enabled. It will -wait for any outstanding I/O's before it clears the error. -.sp -.LP -The \fBMTIOCGUARANTEEDORDER\fR ioctl is used to determine whether the driver -guarantees the order of I/O's. It takes no argument. If the ioctl succeeds, the -driver will support guaranteed order. If the driver does not support guaranteed -order, then it should not be used for asynchronous I/O with \fBlibaio\fR. It -will wait for any outstanding I/O's before it returns. For example, -.sp -.in +2 -.nf +.Ed +.Pp +The +.Dv MTIOCLRERR +ioctl clears persistent error handling and allows tape +operations to continual normally. +This ioctl requires no argument and will +always succeed, even if persistent error handling has not been enabled. +It will wait for any outstanding I/O's before it clears the error. +.Pp +The +.Dv MTIOCGUARANTEEDORDER +ioctl is used to determine whether the driver +guarantees the order of I/O's. +It takes no argument. +If the ioctl succeeds, the driver will support guaranteed order. +If the driver does not support guaranteed order, then it should not be used +for asynchronous I/O with +.Xr libaio 3lib . +It will wait for any outstanding I/O's before it returns. +For example, +.Bd -literal -offset 2n ioctl(fd, MTIOCGUARANTEEDORDER) -.fi -.in -2 - -.sp -.LP -See the \fBPersistent Error Handling\fR subsection above for more information -on persistent error handling. -.SS "Asynchronous and State Change IOCTLS" -.ne 2 -.na -\fB\fBMTIOCSTATE\fR\fR -.ad -.RS 14n +.Ed +.Pp +See the +.Sx Persistent Error Handling +subsection above for more information on persistent error handling. +.Ss "Asynchronous and State Change IOCTLS" +.Bl -tag -width 1n +.It Dv MTIOCSTATE This ioctl blocks until the state of the drive, inserted or ejected, is -changed. The argument is a pointer to a \fBmtio_state\fR, \fBenum\fR, whose -possible enumerations are listed below. The initial value should be either the -last reported state of the drive, or \fBMTIO_NONE\fR. Upon return, the -\fBenum\fR pointed to by the argument is updated with the current state of the -drive. -.RE - -.sp -.in +2 -.nf +changed. +The argument is a pointer to a +.Vt enum mtio_state , +whose possible enumerations are listed below. +The initial value should be either the last reported state of the drive, or +.Dv MTIO_NONE . +Upon return, the +enum pointed to by the argument is updated with the current state of the drive. +.Bd -literal -offset 2n enum mtio_state { -MTIO_NONE /* Return tape's current state */ -MTIO_EJECTED /* Tape state is "ejected" */ -MTIO_INSERTED /* Tape state is "inserted" */ -; -.fi -.in -2 - -.sp -.LP + MTIO_NONE /* Return tape's current state */ + MTIO_EJECTED /* Tape state is "ejected" */ + MTIO_INSERTED /* Tape state is "inserted" */ +}; +.Ed +.El +.Pp When using asynchronous operations, most ioctls will wait for all outstanding commands to complete before they are executed. -.SS "IOCTLS for Multi-initiator Configurations" -.ne 2 -.na -\fBMTIOCRESERVE\fR -.ad -.RS 21n +.Ss "IOCTLS for Multi-initiator Configurations" +.Bl -tag -width MTIOCFORCERESERVE -compact +.It Dv MTIOCRESERVE reserve the tape drive -.RE - -.sp -.ne 2 -.na -\fBMTIOCRELEASE\fR -.ad -.RS 21n +.It Dv MTIOCRELEASE revert back to the default behavior of reserve on open/release on close -.RE - -.sp -.ne 2 -.na -\fBMTIOCFORCERESERVE\fR -.ad -.RS 21n +.It Dv MTIOCFORCERESERVE reserve the tape unit by breaking reservation held by another host -.RE - -.sp -.LP -The \fBMTIOCRESERVE\fR ioctl reserves the tape drive such that it does not -release the tape drive at close. This changes the default behavior of releasing -the device upon close. Reserving the tape drive that is already reserved has no -effect. For example, -.sp -.LP -\fBioctl(fd, MTIOCRESERVE);\fR -.sp -.LP -The \fBMTIOCRELEASE\fR ioctl reverts back to the default behavior of reserve on +.El +.Pp +The +.Dv MTIOCRESERVE +ioctl reserves the tape drive such that it does not +release the tape drive at close. +This changes the default behavior of releasing the device upon close. +Reserving the tape drive that is already reserved has no effect. +For example, +.Bd -literal -offset 2n +ioctl(fd, MTIOCRESERVE); +.Ed +.Pp +The +.Dv MTIOCRELEASE +ioctl reverts back to the default behavior of reserve on open/release on close operation, and a release will occur during the next -close. Releasing the tape drive that is already released has no effect. For -example, -.sp -.LP -\fBioctl(fd, MTIOCRELEASE);\fR -.sp -.LP -The \fBMTIOCFORCERESERVE\fR ioctl breaks a reservation held by another host, -interrupting any I/O in progress by that other host, and then reserves the tape -unit. This ioctl can be executed only with super-user privileges. It is -recommended to open the tape device in \fBO_NDELAY\fR mode when this ioctl -needs to be executed, otherwise the open will fail if another host indeed has -it reserved. For example, -.sp -.in +2 -.nf +close. +Releasing the tape drive that is already released has no effect. +For example, +.Bd -literal -offset 2n +ioctl(fd, MTIOCRELEASE); +.Ed +.Pp +The +.Dv MTIOCFORCERESERVE +ioctl breaks a reservation held by another host, interrupting any I/O in +progress by that other host, and then reserves the tape unit. +This ioctl can be executed only with super-user privileges. +It is recommended to open the tape device in +.Dv O_NDELAY +mode when this ioctl needs to be executed, otherwise the open will fail if +another host indeed has it reserved. +For example, +.Bd -literal -offset 2n ioctl(fd, MTIOCFORCERESERVE); -.fi -.in -2 - -.SS "IOCTLS for Handling Tape Configuration Options" -.ne 2 -.na -\fBMTIOCSHORTFMK\fR -.ad -.RS 23n -enables/disables support for writing short filemarks. This is specific to -Exabyte drives. -.RE - -.sp -.ne 2 -.na -\fBMTIOCREADIGNOREILI\fR -.ad -.RS 23n +.Ed +.Ss "IOCTLS for Handling Tape Configuration Options" +.Bl -tag -width MTIOCREADIGNOREEOFS +.It Dv MTIOCSHORTFMK +enables/disables support for writing short filemarks. +This is specific to Exabyte drives. +.It Dv MTIOCREADIGNOREILI enables/disables suppress incorrect length indicator (SILI) support during reads -.RE - -.sp -.ne 2 -.na -\fBMTIOCREADIGNOREEOFS\fR -.ad -.RS 23n +.It Dv MTIOCREADIGNOREEOFS enables/disables support for reading past two EOF marks which otherwise indicate -End-Of-recording-Media (EOM) in the case of 1/2" reel tape drives -.RE - -.sp -.LP -The \fBMTIOCSHORTFMK\fR ioctl enables or disables support for short filemarks. +End-Of-recording-Media (EOM) in the case of 1/2\(dq reel tape drives +.El +.Pp +The +.Dv MTIOCSHORTFMK +ioctl enables or disables support for short filemarks. This ioctl is only applicable to Exabyte drives which support short filemarks. -As an argument, it takes a pointer to an integer. If 0 (zero) is the -specified integer, then long filemarks will be written. If 1 is the specified -integer, then short filemarks will be written. The specified tape behavior will -be in effect until the device is closed. -.sp -.LP +As an argument, it takes a pointer to an integer. +If 0 (zero) is the specified integer, then long filemarks will be written. +If 1 is the specified integer, then short filemarks will be written. +The specified tape behavior will be in effect until the device is closed. +.Pp For example: -.sp -.in +2 -.nf +.Bd -literal -offset 2n int on = 1; int off = 0; /* enable short filemarks */ ioctl(fd, MTIOSHORTFMK, &on); /* disable short filemarks */ ioctl(fd, MTIOCSHORTFMK, &off); -.fi -.in -2 - -.sp -.LP -Tape drives which do not support short filemarks will return an \fBerrno\fR of -\fBENOTTY.\fR -.sp -.LP -The \fBMTIOCREADIGNOREILI\fR ioctl enables or disables the suppress incorrect -length indicator (SILI) support during reads. As an argument, it takes a -pointer to an integer. If 0 (zero) is the specified integer, SILI will not be -used during reads and incorrect length indicator will not be suppressed. If 1 -is the specified integer, SILI will be used during reads and incorrect length -indicator will be suppressed. The specified tape behavior will be in effect -until the device is closed. -.sp -.LP +.Ed +.Pp +Tape drives which do not support short filemarks will return an +.Va errno +of +.Er ENOTTY . +.Pp +The +.Dv MTIOCREADIGNOREILI +ioctl enables or disables the suppress incorrect +length indicator (SILI) support during reads. +As an argument, it takes a pointer to an integer. +If 0 (zero) is the specified integer, SILI will not be +used during reads and incorrect length indicator will not be suppressed. +If 1 is the specified integer, SILI will be used during reads and incorrect +length indicator will be suppressed. +The specified tape behavior will be in effect until the device is closed. +.Pp For example: -.sp -.in +2 -.nf +.Bd -literal -offset 2n int on = 1; int off = 0; ioctl(fd, MTIOREADIGNOREILI, &on); ioctl(fd, MTIOREADIGNOREILI, &off); -.fi -.in -2 - -.sp -.LP -The \fBMTIOCREADIGNOREEOFS\fR ioctl enables or disables support for reading +.Ed +.Pp +The +.Dv MTIOCREADIGNOREEOFS +ioctl enables or disables support for reading past double EOF marks which otherwise indicate End-Of-recorded-media (EOM) in -the case of 1/2" reel tape drives. As an argument, it takes a pointer to an -integer. If 0 (zero) is the specified integer, then double EOF marks indicate -End-Of-recodred-media (EOD). If 1 is the specified integer, the double EOF -marks no longer indicate EOM, thus allowing applications to read past two EOF -marks. In this case it is the responsibility of the application to detect -end-of-recorded-media (EOM). The specified tape behavior will be in effect -until the device is closed. -.sp -.LP +the case of 1/2\(dq reel tape drives. +As an argument, it takes a pointer to an integer. +If 0 (zero) is the specified integer, then double EOF marks indicate +End-Of-recodred-media (EOD). +If 1 is the specified integer, the double EOF marks no longer indicate EOM, +thus allowing applications to read past two EOF marks. +In this case it is the responsibility of the application to detect +end-of-recorded-media (EOM). +The specified tape behavior will be in effect until the device is closed. +.Pp For example: -.sp -.in +2 -.nf +.Bd -literal -offset 2n int on = 1; int off = 0; ioctl(fd, MTIOREADIGNOREEOFS, &on); ioctl(fd, MTIOREADIGNOREEOFS, &off); -.fi -.in -2 - -.sp -.LP -Tape drives other than 1/2" reel tapes will return an \fBerrno\fR of -\fBENOTTY.\fR -.SH EXAMPLES -.LP -\fBExample 1 \fRTape Positioning and Tape Drives -.sp -.LP -Suppose you have written three files to the non-rewinding 1/2" tape device, -\fB/dev/rmt/0ln,\fR and that you want to go back and \fBdd\fR(1M) the second -file off the tape. The commands to do this are: - -.sp -.in +2 -.nf -mt \fB-F\fR /dev/rmt/0lbn bsf 3 -mt \fB-F\fR /dev/rmt/0lbn fsf 1 +.Ed +.Pp +Tape drives other than 1/2\(dq reel tapes will return an +.Va errno +of +.Er ENOTTY . +.Sh FILES +.Pa /dev/rmt/ Ns Ao unit number Ac \ + Ns Ao density Ac \ + Ns Bo Ao BSD behavior Ac Bc \ + Ns Bo Ao no rewind Ac Bc +.Pp +Where +.Aq density +can be +.Ql l , +.Ql m , +.Ql h , +.Ql u/c +(low, medium, high, ultra/compressed, respectively), the +.Aq BSD behavior +option is +.Ql b , and the +.Aq no rewind +option is +.Ql n . +.Pp +For example, +.Pa /dev/rmt/0hbn +specifies unit 0, high density, +.Sy BSD +behavior and no rewind. +.Sh EXAMPLES +.Bl -inset +.It Sy Example 1 +Tape Positioning and Tape Drives +.Pp +Suppose you have written three files to the non-rewinding 1/2\(dq tape device, +.Pa /dev/rmt/0ln , +and that you want to go back and +.Xr dd 1M +the second file off the tape. +The commands to do this are: +.Bd -literal -offset 2n +mt -F /dev/rmt/0lbn bsf 3 +mt -F /dev/rmt/0lbn fsf 1 dd if=/dev/rmt/0ln -.fi -.in -2 - -.sp -.LP +.Ed +.Pp To accomplish the same tape positioning in a C program, followed by a get status ioctl: - -.sp -.in +2 -.nf +.Bd -literal -offset 2n struct mtop mt_command; struct mtget mt_status; mt_command.mt_op = MTBSF; @@ -1097,56 +1156,35 @@ mt_command.mt_op = MTFSF; mt_command.mt_count = 1; ioctl(fd, MTIOCTOP, &mt_command); ioctl(fd, MTIOCGET, (char *)&mt_status); -.fi -.in -2 - -.sp -.LP +.Ed +.Pp or - -.sp -.in +2 -.nf +.Bd -literal -offset 2n mt_command.mt_op = MTNBSF; mt_command.mt_count = 2; ioctl(fd, MTIOCTOP, &mt_command); ioctl(fd, MTIOCGET, (char *)&mt_status); -.fi -.in -2 - -.sp -.LP +.Ed +.Pp To get information about the tape drive: - -.sp -.in +2 -.nf +.Bd -literal -offset 2n struct mtdrivetype mtdt; struct mtdrivetype_request mtreq; mtreq.size = sizeof(struct mtdrivetype); mtreq.mtdtp = &mtdt; ioctl(fd, MTIOCGETDRIVETYPE, &mtreq); -.fi -.in -2 - -.SH FILES -.LP -\fB/dev/rmt/\fR\fI<unit number><density>\fR[\fI<BSD behavior>\fR][\fI<no -rewind>\fR] -.sp -.LP -Where \fIdensity\fR can be \fBl,\fR \fBm,\fR \fBh,\fR \fBu/c\fR (low, medium, -high, ultra/compressed, respectively), the \fIBSD behavior \fR option is -\fBb\fR, and the \fIno rewind \fR option is \fBn\fR. -.sp -.LP -For example, \fB/dev/rmt/0hbn\fR specifies unit 0, high density, \fBBSD\fR -behavior and no rewind. -.SH SEE ALSO -.LP -\fBmt\fR(1), \fBtar\fR(1), \fBdd\fR(1M), \fBopen\fR(2), \fBread\fR(2), -\fBwrite\fR(2), \fBaioread\fR(3C), \fBaiowrite\fR(3C), \fBar.h\fR(3HEAD), -\fBst\fR(7D) -.sp -.LP -\fI1/4 Inch Tape Drive Tutorial\fR +.Ed +.El +.Sh SEE ALSO +.Xr mt 1 , +.Xr tar 1 , +.Xr dd 1M , +.Xr open 2 , +.Xr read 2 , +.Xr write 2 , +.Xr aioread 3C , +.Xr aiowrite 3C , +.Xr ar.h 3HEAD , +.Xr st 7D +.Pp +.%T 1/4 Inch Tape Drive Tutorial diff --git a/usr/src/man/man7i/prnio.7i b/usr/src/man/man7i/prnio.7i index d51ea8d8df..0b794f014a 100644 --- a/usr/src/man/man7i/prnio.7i +++ b/usr/src/man/man7i/prnio.7i @@ -1,365 +1,370 @@ -'\" te .\" Copyright (c) 20002 Sun Microsystems, Inc. .\" All Rights Reserved. -.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. -.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. -.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH PRNIO 7I "Jan 2, 2002" -.SH NAME -prnio \- generic printer interface -.SH SYNOPSIS -.nf -\fB#include <sys/prnio.h>\fR -.fi - -.SH DESCRIPTION -The \fBprnio\fR generic printer interface defines ioctl commands and data +.\" Copyright 2018, Joyent, Inc. +.\" The contents of this file are subject to the terms of the +.\" Common Development and Distribution License (the "License"). +.\" You may not use this file except in compliance with the License. +.\" +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE +.\" or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions +.\" and limitations under the License. +.\" +.\" When distributing Covered Code, include this CDDL HEADER in each +.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. +.\" If applicable, add the following below this CDDL HEADER, with the +.\" fields enclosed by brackets "[]" replaced with your own identifying +.\" information: Portions Copyright [yyyy] [name of copyright owner] +.Dd August 31, 2018 +.Dt PRNIO 7I +.Os +.Sh NAME +.Nm prnio +.Nd generic printer interface +.Sh SYNOPSIS +.In sys/prnio.h +.Sh DESCRIPTION +The +.Nm +generic printer interface defines ioctl commands and data structures for printer device drivers. -.sp -.LP -\fBprnio\fR defines and provides facilities for five basic phases of the -printing process: -.RS +4 -.TP -.ie t \(bu -.el o +.Pp +.Nm +defines and provides facilities for five basic phases of the printing process: +.Bl -bullet -offset indent +.It Identification \(em Retrieve device information/attributes -.RE -.RS +4 -.TP -.ie t \(bu -.el o +.It Setup \(em Set device attributes -.RE -.RS +4 -.TP -.ie t \(bu -.el o +.It Transfer \(em Transfer data to or from the device -.RE -.RS +4 -.TP -.ie t \(bu -.el o +.It Cleanup \(em Transfer phase conclusion -.RE -.RS +4 -.TP -.ie t \(bu -.el o +.It Abort \(em Transfer phase interruption -.RE -.sp -.LP +.El +.Pp During the Identification phase, the application retrieves a set of device -capabilities and additional information using the \fBPRNIOC_GET_IFCAP\fR, -\fBPRNIOC_GET_STATUS\fR, \fBPRNIOC_GET_TIMEOUTS\fR, \fBPRNIOC_GET_IFINFO\fR and -\fBPRNIOC_GET_1284_DEVID\fR commands. -.sp -.LP +capabilities and additional information using the +.Dv PRNIOC_GET_IFCAP , +.Dv PRNIOC_GET_STATUS , +.Dv PRNIOC_GET_TIMEOUTS , +.Dv PRNIOC_GET_IFINFO , +and +.Dv PRNIOC_GET_1284_DEVID +commands. +.Pp During the Setup phase the application sets some interface attributes and -probably resets the printer as described in the \fBPRNIOC_SET_IFCAP\fR, -\fBPRNIOC_SET_TIMEOUTS\fR and \fBPRNIOC_RESET\fR sections. -.sp -.LP +probably resets the printer as described in the +.Dv PRNIOC_SET_IFCAP , +.Dv PRNIOC_SET_TIMEOUTS , +and +.Dv PRNIOC_RESET +sections. +.Pp During the Transfer phase, data is transferred in a forward (host to -peripheral) or reverse direction (peripheral to host). Transfer is accomplished -using \fBwrite\fR(2) and \fBread\fR(2) system calls. For \fBprnio\fR compliant +peripheral) or reverse direction (peripheral to host). +Transfer is accomplished +using +.Xr write 2 +and +.Xr read 2 +system calls. +For +.Nm +compliant printer drivers, forward transfer support is mandatory, while reverse transfer -support is optional. Applications can also use \fBPRNIOC_GET_STATUS\fR and -\fBPRNIOC_GET_1284_STATUS\fR commands during the transfer to monitor the device -state. -.sp -.LP -The Cleanup phase is accomplished by closing the device using \fBclose\fR(2). -Device drivers supporting \fBprnio\fR may set non-zero error code as -appropriate. Applications should explicitly \fBclose\fR(2) a device before -exiting and check \fBerrno\fR value. -.sp -.LP -The Abort phase is accomplished by interrupting the \fBwrite\fR(2) and -\fBread\fR(2) system calls. The application can perform some additional cleanup -during the Abort phase as described in \fBPRNIOC_GET_IFCAP\fR section. -.SH IOCTLS -.ne 2 -.na -\fB\fBPRNIOC_GET_IFCAP\fR\fR -.ad -.RS 21n -Application can retrieve printer interface capabilities using this command. The -\fBioctl\fR(2) argument is a pointer to \fBuint_t\fR, a bit field representing -a set of properties and services provided by a printer driver. Set bit means -supported capability. The following values are defined: -.br -.in +2 -\fBPRN_BIDI\fR - When this bit is set, the interface operates in a -bidirectional mode, instead of forward-only mode. -.in -2 -.br -.in +2 -\fBPRN_HOTPLUG\fR - If this bit is set, the interface allows device -hot-plugging. -.in -2 -.br -.in +2 -\fBPRN_1284_DEVID\fR - If this bit is set, the device is capable of returning -\fI1284\fR device ID (see \fBPRNIOC_GET_1284_DEVID\fR.) -.in -2 -.br -.in +2 -\fBPRN_1284_STATUS\fR - If this bit is set, the device driver can return device -status lines (see \fBPRNIOC_GET_1284_STATUS\fR). Some devices support this +support is optional. +Applications can also use +.Dv PRNIOC_GET_STATUS +and +.Dv PRNIOC_GET_1284_STATUS +commands during the transfer to monitor the device state. +.Pp +The Cleanup phase is accomplished by closing the device using +.Xr close 2 . +Device drivers supporting +.Nm +may set non-zero error code as appropriate. +Applications should explicitly +.Xr close 2 +a device before +exiting and check +.Va errno +value. +.Pp +The Abort phase is accomplished by interrupting the +.Xr write 2 +and +.Xr read 2 +system calls. +The application can perform some additional cleanup +during the Abort phase as described in +.Dv PRNIOC_GET_IFCAP +section. +.Sh IOCTLS +.Bl -tag -width PRNIOC_GET_IFINFO +.It Dv PRNIOC_GET_IFCAP +Application can retrieve printer interface capabilities using this command. +The +.Xr ioctl 2 +argument is a pointer to +.Vt uint_t , +a bit field representing +a set of properties and services provided by a printer driver. +Set bit means supported capability. +The following values are defined: +.Bl -tag -width PRN_1284_STATUS +.It Dv PRN_BIDI +When this bit is set, the interface operates in a +bidirectional mode, instead of forward-only mode. +.It Dv PRN_HOTPLUG +If this bit is set, the interface allows device hot-plugging. +.It Dv PRN_1284_DEVID +If this bit is set, the device is capable of returning +.Em 1284 +device ID (see +.Dv PRNIOC_GET_1284_DEVID ) . +.It Dv PRN_1284_STATUS +If this bit is set, the device driver can return device +status lines (see +.Dv PRNIOC_GET_1284_STATUS ) . +Some devices support this ioctl in unidirectional mode only. -.in -2 -.br -.in +2 -\fBPRN_TIMEOUTS\fR - If this bit is set the peripheral may stall during the -transfer phase and the driver can timeout and return from the \fBwrite\fR(2) -and \fBread\fR(2) returning the number of bytes that have been transferred. If -\fBPRN_TIMEOUTS\fR is set, the driver supports this functionality and the -timeout values can be retrieved and modified via the \fBPRNIOC_GET_TIMEOUTS\fR -and \fBPRNIOC_SET_TIMEOUTS\fR ioctls. Otherwise, applications can implement +.It Dv PRN_TIMEOUTS +If this bit is set the peripheral may stall during the +transfer phase and the driver can timeout and return from the +.Xr write 2 +and +.Xr read 2 +returning the number of bytes that have been transferred. +If +.Dv PRN_TIMEOUTS +is set, the driver supports this functionality and the +timeout values can be retrieved and modified via the +.Dv PRNIOC_GET_TIMEOUTS +and +.Dv PRNIOC_SET_TIMEOUTS +ioctls. +Otherwise, applications can implement their own timeouts and abort phase. -.in -2 -.br -.in +2 -\fBPRN_STREAMS\fR - This bit impacts the application abort phase behaviour. If -the device claimed \fBPRN_STREAMS\fR capability, the application must issue an -\fBI_FLUSH\fR \fBioctl\fR(2) before \fBclose\fR(2) to dismiss the untransferred -data. Only STREAMS drivers can support this capability. -.in -2 -.RE - -.sp -.ne 2 -.na -\fBPRNIOC_SET_IFCAP\fR -.ad -.RS 21n -This ioctl can be used to change interface capabilities. The argument is a -pointer to \fBuint_t\fR bit field that is described in detail in the -\fBPRNIOC_GET_IFCAP\fR section. Capabilities should be set one at a time; -otherwise the command will return \fBEINVAL\fR. The following capabilities can -be changed by this ioctl: -.br -.in +2 -\fBPRN_BIDI\fR - When this capability is set, the interface operates in a -bidirectional mode, instead of forward-only mode. Devices that support only one -mode will not return error; applications should use \fBPRNIOC_GET_IFCAP\fR to -check if the mode was successfully changed. Because some capabilities may be +.It Dv PRN_STREAMS +This bit impacts the application abort phase behaviour. +If the device claimed +.Dv PRN_STREAMS +capability, the application must issue an +.Dv I_FLUSH +.Xr ioctl 2 +before +.Xr close 2 +to dismiss the untransferred +data. +Only STREAMS drivers can support this capability. +.El +.It Dv PRNIOC_SET_IFCAP +This ioctl can be used to change interface capabilities. +The argument is a pointer to +.Vt uint_t +bit field that is described in detail in the +.Dv PRNIOC_GET_IFCAP +section. +Capabilities should be set one at a time; +otherwise the command will return +.Er EINVAL . +The following capabilities can be changed by this ioctl: +.Bl -tag -width PRN_BIDI +.It Dv PRN_BIDI +When this capability is set, the interface operates in a +bidirectional mode, instead of forward-only mode. +Devices that support only one +mode will not return error; applications should use +.Dv PRNIOC_GET_IFCAP +to check if the mode was successfully changed. +Because some capabilities may be altered as a side effect of changing other capabilities, this command should be -followed by \fBPRNIOC_GET_IFCAP\fR. -.in -2 -.RE - -.sp -.ne 2 -.na -\fBPRNIOC_GET_IFINFO\fR -.ad -.RS 21n +followed by +.Dv PRNIOC_GET_IFCAP . +.El +.It Dv PRNIOC_GET_IFINFO This command can be used to retrieve printer interface info string, which is an -arbitrary format string usually describing the bus type. The argument is a -pointer to \fBstruct prn_interface_info\fR as described below. -.RE - -.sp -.in +2 -.nf +arbitrary format string usually describing the bus type. +The argument is a +pointer to +.Vt struct prn_interface_info +as described below. +.Bd -literal -offset 2n struct prn_interface_info { uint_t if_len; /* length of buffer */ uint_t if_rlen; /* actual info length */ - char *if_data; /* buffer address */ + char *if_data; /* buffer address */ }; -.fi -.in -2 - -.sp -.LP -The application allocates a buffer and sets \fBif_data\fR and \fBif_len\fR -values to its address and length, respectively. The driver returns the string -to this buffer and sets \fBif_len\fR to its length. If \fBif_len\fR is less -that \fBif_rlen\fR, the driver must return the first \fBif_len\fR bytes of the -string. The application may then repeat the command with a bigger buffer. -.sp -.LP -Although \fBprnio\fR does not limit the contents of the interface info string, -some values are recommended and defined in <\fBsys/prnio.h\fR> by the following -macros: -.br -.in +2 -\fBPRN_PARALLEL\fR - Centronics or \fIIEEE 1284\fR compatible devices -.in -2 -.br -.in +2 -\fBPRN_SERIAL\fR - EIA-232/EIA-485 serial ports -.in -2 -.br -.in +2 -\fBPRN_USB\fR - Universal Serial Bus printers -.in -2 -.br -.in +2 -\fBPRN_1394\fR - \fIIEEE 1394\fR peripherals -.in -2 -.br -.in +2 +.Ed +.Pp +The application allocates a buffer and sets +.Fa if_data +and +.Fa if_len +values to its address and length, respectively. +The driver returns the string +to this buffer and sets +.Fa if_len +to its length. +If +.Fa if_len +is less +than +.Fa if_rlen , +the driver must return the first +.Fa if_len +bytes of the string. +The application may then repeat the command with a bigger buffer. +.Pp +Although +.Nm +does not limit the contents of the interface info string, +some values are recommended and defined in +.In sys/prnio.h +by the following macros: +.Pp +.Bl -tag -width PRN_PARALLEL -compact +.It Dv PRN_PARALLEL +Centronics or +.Em IEEE 1284 +compatible devices +.It Dv PRN_SERIAL +EIA-232/EIA-485 serial ports +.It Dv PRN_USB +Universal Serial Bus printers +.It Dv PRN_1394 +.Em IEEE 1394 +peripherals +.El +.Pp Printer interface info string is for information only: no implications should be made from its value. -.in -2 -.sp -.ne 2 -.na -\fBPRNIOC_RESET\fR -.ad -.RS 25n +.It Dv PRNIOC_RESET Some applications may want to reset the printer state during Setup and/or -Cleanup phase using \fBPRNIOC_RESET\fR command. Reset semantics are +Cleanup phase using +.Dv PRNIOC_RESET +command. +Reset semantics are device-specific, and in general, applications using this command should be aware of the printer type. -.sp -Each \fBprnio\fR compliant driver is required to accept this request, although -performed actions are completely driver-dependent. More information on the -\fBPRNIOC_RESET\fR implementation for the particular driver is available in the +.Pp +Each +.Nm +compliant driver is required to accept this request, although +performed actions are completely driver-dependent. +More information on the +.Dv PRNIOC_RESET +implementation for the particular driver is available in the corresponding man page and printer manual. -.RE - -.sp -.ne 2 -.na -\fBPRNIOC_GET_1284_DEVID\fR -.ad -.RS 25n -This command can be used to retrieve printer device ID as defined by \fIIEEE -1284-1994\fR.The \fBioctl\fR(2) argument is a pointer to \fBstruct -prn_1284_device_id\fR as described below. -.RE - -.sp -.in +2 -.nf +.It Dv PRNIOC_GET_1284_DEVID +This command can be used to retrieve printer device ID as defined by +.Em IEEE 1284-1994 . +The +.Xr ioctl 2 +argument is a pointer to +.Vt struct prn_1284_device_id +as described below. +.Bd -literal -offset 2n struct prn_1284_device_id { uint_t id_len; /* length of buffer */ uint_t id_rlen; /* actual ID length */ - char *id_data; /* buffer address */ + char *id_data; /* buffer address */ }; -.fi -.in -2 - -.sp -.LP +.Ed +.Pp For convenience, the two-byte length field is not considered part of device ID -string and is not returned in the user buffer. Instead, \fBid_rlen\fR value -shall be set to (length - 2) by the driver, where length is the ID length field -value. If buffer length is less than \fBid_rlen\fR, the driver returns the -first \fBid_len\fR bytes of the ID. -.sp -.LP +string and is not returned in the user buffer. +Instead, +.Fa id_rlen +value shall be set to (length - 2) by the driver, where length is the ID +length field value. +If buffer length is less than +.Fa id_rlen , +the driver returns the first +.Fa id_len +bytes of the ID. +.Pp The printer driver must return the most up-to-date value of the device ID. -.sp -.ne 2 -.na -\fBPRNIOC_GET_STATUS\fR -.ad -.RS 21n -This command can be used by applications to retrieve current device status. The -argument is a pointer to \fBuint_t\fR, where the status word is returned. +.It Dv PRNIOC_GET_STATUS +This command can be used by applications to retrieve current device status. +The argument is a pointer to +.Vt uint_t , +where the status word is returned. Status is a combination of the following bits: -.RE - -.in +2 -\fBPRN_ONLINE\fR - For devices that support \fBPRN_HOTPLUG\fR capability, -this bit is set when the device is online, otherwise the device is offline. -Devices without \fBPRN_HOTPLUG\fR support should always have this bit set. -.in -2 -.br -.in +2 -\fBPRN_READY\fR - This bit indicates if the device is ready to receive/send -data. Applications may use this bit for an outbound flow control -.in -2 -.sp -.ne 2 -.na -\fB\fBPRNIOC_GET_1284_STATUS\fR\fR -.ad -.RS 26n -Devices that support \fBPRN_1284_STATUS\fR capability accept this ioctl to -retrieve the device status lines defined in \fIIEEE 1284\fR for use in -Compatibility mode. The following bits may be set by the driver: -.br -.in +2 -\fBPRN_1284_NOFAULT\fR - Device is not in error state -.in -2 -.br -.in +2 -\fBPRN_1284_SELECT\fR - Device is selected -.in -2 -.br -.in +2 -\fBPRN_1284_PE\fR - Paper error -.in -2 -.br -.in +2 -\fBPRN_1284_BUSY\fR - Device is busy -.in -2 -.RE - -.sp -.ne 2 -.na -\fB\fBPRNIOC_GET_TIMEOUTS\fR\fR -.ad -.RS 26n -This command retrieves current transfer timeout values for the driver. The -argument is a pointer to \fBstruct prn_timeouts\fR as described below. -.RE - -.sp -.in +2 -.nf +.Bl -tag -width PRN_ONLINE +.It Dv PRN_ONLINE +For devices that support +.Dv PRN_HOTPLUG +capability, this bit is set when the device is online, otherwise the device is +offline. +Devices without +.Dv PRN_HOTPLUG +support should always have this bit set. +.It Dv PRN_READY +This bit indicates if the device is ready to receive/send data. +Applications may use this bit for an outbound flow control. +.El +.It Dv PRNIOC_GET_1284_STATUS +Devices that support +.Dv PRN_1284_STATUS +capability accept this ioctl to +retrieve the device status lines defined in +.Em IEEE 1284 +for use in Compatibility mode. +The following bits may be set by the driver: +.Pp +.Bl -tag -width PRN_1284_NOFAULT -compact +.It Dv PRN_1284_NOFAULT +Device is not in error state +.It Dv PRN_1284_SELECT +Device is selected +.It Dv PRN_1284_PE +Paper error +.It Dv PRN_1284_BUSY +Device is busy +.El +.It Dv PRNIOC_GET_TIMEOUTS +This command retrieves current transfer timeout values for the driver. +The argument is a pointer to +.Vt struct prn_timeouts +as described below. +.Bd -literal -offset 2n struct prn_timeouts { - uint_t tmo_forward; /* forward transfer timeout */ - uint_t tmo_reverse; /* reverse transfer timeout */ - }; -.fi -.in -2 - -.sp -.LP -\fBtmo_forward\fR and \fBtmo_reverse\fR define forward and reverse transfer -timeouts in seconds. This command is only valid for drivers that support -\fBPRN_TIMEOUTS\fR capability. -.sp -.ne 2 -.na -\fB\fBPRNIOC_SET_TIMEOUTS\fR\fR -.ad -.RS 23n -This command sets current transfer timeout values for the driver. The -argument is a pointer to \fBstruct prn_timeouts\fR. See -\fBPRNIOC_GET_TIMEOUTS\fR for description of this structure. This command is -only valid for drivers that support \fBPRN_TIMEOUTS\fR capability. -.RE - -.SH ATTRIBUTES -See \fBattributes\fR(5) for descriptions of the following attributes: -.sp - -.sp -.TS -box; -c | c -l | l . -ATTRIBUTE TYPE ATTRIBUTE VALUE -_ -Architecture SPARC, IA -_ -Interface Stability Evolving -.TE - -.SH SEE ALSO -\fBclose\fR(2), \fBioctl\fR(2), \fBread\fR(2), \fBwrite\fR(2), -\fBattributes\fR(5), \fBecpp\fR(7D), \fBusbprn\fR(7D), \fBlp\fR(7D) -.sp -.LP -\fIIEEE Std 1284-1994\fR + uint_t tmo_forward; /* forward transfer timeout */ + uint_t tmo_reverse; /* reverse transfer timeout */ +}; +.Ed +.Pp +.Fa tmo_forward +and +.Fa tmo_reverse +define forward and reverse transfer timeouts in seconds. +This command is only valid for drivers that support +.Dv PRN_TIMEOUTS +capability. +.It Dv PRNIOC_SET_TIMEOUTS +This command sets current transfer timeout values for the driver. +The argument is a pointer to +.Vt struct prn_timeouts . +See +.Sx PRNIOC_GET_TIMEOUTS +for description of this structure. +This command is only valid for drivers that support +.Dv PRN_TIMEOUTS +capability. +.El +.Sh SEE ALSO +.Xr close 2 , +.Xr ioctl 2 , +.Xr read 2 , +.Xr write 2 , +.Xr attributes 5 , +.Xr ecpp 7D , +.Xr lp 7D , +.Xr usbprn 7D +.Rs +.%T IEEE Std 1284-1994 +.Re diff --git a/usr/src/man/man7i/quotactl.7i b/usr/src/man/man7i/quotactl.7i index 39717a8dff..30b894542c 100644 --- a/usr/src/man/man7i/quotactl.7i +++ b/usr/src/man/man7i/quotactl.7i @@ -1,243 +1,227 @@ -'\" te .\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved -.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. -.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. -.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH QUOTACTL 7I "Jun 14, 2004" -.SH NAME -quotactl \- manipulate disk quotas -.SH SYNOPSIS -.LP -.nf -#include <sys/fs/ufs_quota.h> -int ioctl(int \fIfd\fR, Q_QUOTACTL, struct quotcl *\fIqp\fR) -.fi - -.SH DESCRIPTION -.sp -.LP -This \fBioctl()\fR call manipulates disk quotas. \fIfd\fR is the file -descriptor returned by the \fBopen()\fR system call after opening the -\fBquotas\fR file (located in the root directory of the filesystem running -quotas.) \fBQ_QUOTACTL\fR is defined in \fB/usr/include/sys/fs/ufs_quota.h\fR. -\fIqp\fR is the address of the \fBquotctl\fR structure which is defined as -.sp -.in +2 -.nf +.\" Copyright (c) 2017, Joyent, Inc. +.\" The contents of this file are subject to the terms of the +.\" Common Development and Distribution License (the "License"). +.\" You may not use this file except in compliance with the License. +.\" +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE +.\" or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions +.\" and limitations under the License. +.\" +.\" When distributing Covered Code, include this CDDL HEADER in each +.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. +.\" If applicable, add the following below this CDDL HEADER, with the +.\" fields enclosed by brackets "[]" replaced with your own identifying +.\" information: Portions Copyright [yyyy] [name of copyright owner] +.Dd October 28, 2017 +.Dt QUOTACTL 7I +.Os +.Sh NAME +.Nm quotactl +.Nd manipulate disk quotas +.Sh SYNOPSIS +.In sys/fs/ufs_quota.h +.Fn "int ioctl" "int fd" "Q_QUOTACTL" "struct quotctl *qp" +.Sh DESCRIPTION +This +.Fn ioctl +call manipulates disk quotas. +.Fa fd +is the file descriptor returned by the +.Xr open 2 +system call after opening the +.Pa quotas +file (located in the root directory of the filesystem running quotas). +.Dv Q_QUOTACTL +is defined in +.Pa /usr/include/sys/fs/ufs_quota.h . +.Fa qp +is the address of the +.Vt quotctl +structure which is defined as +.Bd -literal -offset 2n struct quotctl { int op; uid_t uid; caddr_t addr; }; -.fi -.in -2 - -.sp -.LP -\fIop\fR indicates an operation to be applied to the user \fBID\fR \fIuid\fR. -(See below.) \fIaddr\fR is the address of an optional, command specific, data -structure which is copied in or out of the system. The interpretation of -\fIaddr\fR is given with each value of \fIop\fR below. -.sp -.ne 2 -.na -\fB\fBQ_QUOTAON\fR\fR -.ad -.RS 14n -Turn on quotas for a file system. \fIaddr\fR points to the full pathname of the -\fBquotas\fR file. \fIuid\fR is ignored. It is recommended that \fIuid\fR have -the value of \fB0\fR. This call is restricted to the super-user. -.RE - -.sp -.ne 2 -.na -\fB\fBQ_QUOTAOFF\fR\fR -.ad -.RS 14n -Turn off quotas for a file system. \fIaddr\fR and \fIuid\fR are ignored. It is -recommended that \fIaddr\fR have the value of \fINULL\fR and \fIuid\fR have the -value of \fB0\fR. This call is restricted to the super-user. -.RE - -.sp -.ne 2 -.na -\fB\fBQ_GETQUOTA\fR\fR -.ad -.RS 14n -Get disk quota limits and current usage for user \fIuid\fR. \fIaddr\fR is a -pointer to a \fBdqblk\fR structure (defined in \fB<sys/fs/ufs_quota.h>\fR). +.Ed +.Pp +.Fa op +indicates an operation to be applied to the user +.Sy ID +.Fa uid . +.Po +See below. +.Pc +.Fa addr +is the address of an optional, command specific, data +structure which is copied in or out of the system. +The interpretation of +.Fa addr +is given with each value of +.Fa op +below. +.Bl -tag -width Q_GETQUOTA +.It Sy Q_QUOTAON +Turn on quotas for a file system. +.Fa addr +points to the full pathname of the +.Pa quotas +file. +.Fa uid +is ignored. +It is recommended that +.Fa uid +have the value of +.Sy 0 . +This call is restricted to the super-user. +.It Dv Q_QUOTAOFF +Turn off quotas for a file system. +.Fa addr +and +.Fa uid +are ignored. +It is +recommended that +.Fa addr +have the value of +.Sy NULL +and +.Fa uid +have the value of +.Sy 0 . +This call is restricted to the super-user. +.It Dv Q_GETQUOTA +Get disk quota limits and current usage for user +.Fa uid . +.Fa addr +is a pointer to a +.Vt dqblk +structure +.Po +defined in +.In sys/fs/ufs_quota.h +.Pc . Only the super-user may get the quotas of a user other than himself. -.RE - -.sp -.ne 2 -.na -\fB\fBQ_SETQUOTA\fR\fR -.ad -.RS 14n -Set disk quota limits and current usage for user \fIuid\fR. \fIaddr\fR is a -pointer to a \fBdqblk\fR structure (defined in \fBsys/fs/ufs_quota.h\fR). This -call is restricted to the super-user. -.RE - -.sp -.ne 2 -.na -\fB\fBQ_SETQLIM\fR\fR -.ad -.RS 14n -Set disk quota limits for user \fIuid\fR. \fIaddr\fR is a pointer to a -\fBdqblk\fR structure (defined in \fBsys/fs/ufs_quota.h\fR). This call is -restricted to the super-user. -.RE - -.sp -.ne 2 -.na -\fB\fBQ_SYNC\fR\fR -.ad -.RS 14n -Update the on-disk copy of quota usages for this file system. \fIaddr\fR and -\fIuid\fR are ignored. -.RE - -.sp -.ne 2 -.na -\fB\fBQ_ALLSYNC\fR\fR -.ad -.RS 14n +.It Dv Q_SETQUOTA +Set disk quota limits and current usage for user +.Fa uid . +.Fa addr +is a pointer to a +.Vt dqblk +structure +.Po +defined in +.In sys/fs/ufs_quota.h +.Pc . +This call is restricted to the super-user. +.It Dv Q_SETQLIM +Set disk quota limits for user +.Fa uid . +.Fa addr +is a pointer to a +.Vt dqblk +structure +.Po +defined in +.In sys/fs/ufs_quota.h +.Pc . +This call is restricted to the super-user. +.It Dv Q_SYNC +Update the on-disk copy of quota usages for this file system. +.Fa addr +and +.Fa uid +are ignored. +.It Dv Q_ALLSYNC Update the on-disk copy of quota usages for all file systems with active -quotas. \fIaddr\fR and \fIuid\fR are ignored. -.RE - -.SH RETURN VALUES -.sp -.LP -This \fBioctl()\fR returns: -.sp -.ne 2 -.na -\fB\fB0\fR\fR -.ad -.RS 9n +quotas. +.Fa addr +and +.Fa uid +are ignored. +.El +.Sh RETURN VALUES +This +Fn ioctl +returns: +.Bl -tag -width xx +.It Sy 0 on success. -.RE - -.sp -.ne 2 -.na -\fB\fB\(mi1\fR\fR -.ad -.RS 9n -on failure and sets \fBerrno\fR to indicate the error. -.RE - -.SH ERRORS -.sp -.ne 2 -.na -\fB\fBEFAULT\fR\fR -.ad -.RS 10n -\fIaddr\fR is invalid. -.RE - -.sp -.ne 2 -.na -\fB\fBEINVAL\fR\fR -.ad -.RS 10n -The kernel has not been compiled with the \fBQUOTA\fR option. \fIop\fR is -invalid. -.RE - -.sp -.ne 2 -.na -\fB\fBENOENT\fR\fR -.ad -.RS 10n -The \fBquotas\fR file specified by \fIaddr\fR does not exist. -.RE - -.sp -.ne 2 -.na -\fB\fBEPERM\fR\fR -.ad -.RS 10n +.It Sy \(mi1 +on failure and sets +.Va errno +to indicate the error. +.El +.Sh FILES +.Bl -tag -width x +.It Pa /usr/include/sys/fs/ufs_quota.h +quota-related structure/function definitions and defines +.El +.Sh ERRORS +.Bl -tag -width EFAULT +.It Er EFAULT +.Fa addr +is invalid. +.It Er EINVAL +The kernel has not been compiled with the +.Sy QUOTA +option. +.Fa op +is invalid. +.It Er ENOENT +The +.Pa quotas +file specified by +.Fa addr +does not exist. +.It Er EPERM The call is privileged and the calling process did not assert -{PRIV_SYS_MOUNT} in the effective set. -.RE - -.sp -.ne 2 -.na -\fB\fBESRCH\fR\fR -.ad -.RS 10n -No disk quota is found for the indicated user. Quotas have not been turned on -for this file system. -.RE - -.sp -.ne 2 -.na -\fB\fBEUSERS\fR\fR -.ad -.RS 10n +.Brq Sy PRIV_SYS_MOUNT +in the effective set. +.It Er ESRCH +No disk quota is found for the indicated user. +Quotas have not been turned on for this file system. +.It Er EUSERS The quota table is full. -.RE - -.sp -.LP -If \fIop\fR is \fBQ_QUOTAON\fR, \fBioctl()\fR may set \fBerrno\fR to: -.sp -.ne 2 -.na -\fB\fBEACCES\fR\fR -.ad -.RS 10n -The quota file pointed to by \fIaddr\fR exists but is not a regular file. The -quota file pointed to by \fIaddr\fR exists but is not on the file system -pointed to by \fIspecial\fR. -.RE - -.sp -.ne 2 -.na -\fB\fBEIO\fR\fR -.ad -.RS 10n -Internal I/O error while attempting to read the \fBquotas\fR file pointed to by -\fIaddr\fR. -.RE - -.SH FILES -.sp -.ne 2 -.na -\fB\fB/usr/include/sys/fs/ufs_quota.h\fR\fR -.ad -.sp .6 -.RS 4n -quota-related structure/function definitions and defines -.RE - -.SH SEE ALSO -.sp -.LP -\fBquota\fR(1M), \fBquotacheck\fR(1M), \fBquotaon\fR(1M), \fBgetrlimit\fR(2), -\fBmount\fR(2) -.SH BUGS -.sp -.LP +.El +.Pp +If +.Fa op +is +.Dv Q_QUOTAON , +.Fn ioctl +may set +.Va errno +to: +.Bl -tag -width EACCES +.It Er EACCES +The quota file pointed to by +.Fa addr +exists but is not a regular file. +The quota file pointed to by +.Fa addr +exists but is not on the file system pointed to by +.Fa special . +.It Er EIO +Internal I/O error while attempting to read the +.Pa quotas +file pointed to by +.Fa addr . +.El +.Sh SEE ALSO +.Xr quota 1M , +.Xr quotacheck 1M , +.Xr quotaon 1M , +.Xr getrlimit 2 , +.Xr mount 2 +.Sh BUGS There should be some way to integrate this call with the resource limit -interface provided by \fBsetrlimit()\fR and \fBgetrlimit\fR(2). -.sp -.LP +interface provided by +.Xr setrlimit 2 +and +.Xr getrlimit 2 . +.Pp This call is incompatible with Melbourne quotas. diff --git a/usr/src/man/man7i/sesio.7i b/usr/src/man/man7i/sesio.7i index a130d35c6c..79e1329c47 100644 --- a/usr/src/man/man7i/sesio.7i +++ b/usr/src/man/man7i/sesio.7i @@ -1,135 +1,95 @@ -'\" te .\" Copyright (c) 1997, Sun Microsystems, Inc. All Rights Reserved -.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. -.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. -.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH SESIO 7I "Mar 27, 1997" -.SH NAME -sesio \- enclosure services device driver interface -.SH SYNOPSIS -.LP -.nf -\fB#include <sys/sesio.h>\fR -.fi - -.SH DESCRIPTION -.sp -.LP -The \fBses\fR device driver provides the following ioctls as a means to access +.\" Copyright (c) 2017, Joyent, Inc. +.\" The contents of this file are subject to the terms of the +.\" Common Development and Distribution License (the "License"). +.\" You may not use this file except in compliance with the License. +.\" +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE +.\" or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions +.\" and limitations under the License. +.\" +.\" When distributing Covered Code, include this CDDL HEADER in each +.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. +.\" If applicable, add the following below this CDDL HEADER, with the +.\" fields enclosed by brackets "[]" replaced with your own identifying +.\" information: Portions Copyright [yyyy] [name of copyright owner] +.Dd October 23, 2017 +.Dt SESIO 7I +.Os +.Sh NAME +.Nm sesio +.Nd enclosure services device driver interface +.Sh SYNOPSIS +.In sys/scsi/targets/sesio.h +.Sh DESCRIPTION +The +.Nm ses +device driver provides the following ioctls as a means to access SCSI enclosure services devices. -.SH IOCTLS -.sp -.LP -The \fBses\fR driver supports the following ioctls: -.sp -.ne 2 -.na -\fB\fBSES_IOCTL_GETSTATE\fR\fR -.ad -.RS 22n -This ioctl obtains enclosure state in the \fBses_ioctl\fR structure. -.RE - -.sp -.ne 2 -.na -\fB\fBSES_IOCTL_SETSTATE\fR\fR -.ad -.RS 22n -This ioctl is used to set parameters on the enclosure services device. The -\fBses_ioctl\fR structure is used to pass information into the driver. -.RE - -.SH ERRORS -.sp -.ne 2 -.na -\fB\fBEIO\fR\fR -.ad -.RS 10n -The \fBses\fR driver was unable to obtain data from the enclosure services -device or the data transfer could not be completed. -.RE - -.sp -.ne 2 -.na -\fB\fBENOTTY\fR\fR -.ad -.RS 10n -The \fBses\fR driver does not support the requested ioctl function. -.RE - -.sp -.ne 2 -.na -\fB\fBENXIO\fR\fR -.ad -.RS 10n -The enclosure services device does not exist. -.RE - -.sp -.ne 2 -.na -\fB\fBEFAULT\fR\fR -.ad -.RS 10n -The user specified a bad data length. -.RE - -.SH STRUCTURES -.sp -.LP -The \fBses_ioctl\fR structure has the following fields: -.sp -.in +2 -.nf -uint32_t; /* Size of buffer that follows */ -uint8_t page_code: /* Page to be read/written */ -uint8_t reserved[3]; /* Reserved; Set to 0 */ -unit8t buffer[1]; /* Size arbitrary, user specifies */ -.fi -.in -2 - -.SH EXAMPLES -.LP -\fBExample 1 \fRUsing the \fBSES_IOCTL_GETSTATE\fR ioctl -.sp -.LP -The following example uses the \fBSES_IOCTL_GETSTATE\fR ioctl to recover 20 -bytes of page 4 from a previously opened device. - -.sp -.in +2 -.nf +.Sh IOCTLS +The +.Nm ses +driver supports the following ioctls: +.Bl -tag -width SES_IOCTL_GETSTATE +.It Dv SES_IOCTL_GETSTATE +This ioctl obtains enclosure state in the +.Vt ses_ioctl +structure. +.It Dv SES_IOCTL_SETSTATE +This ioctl is used to set parameters on the enclosure services device. +The +.Vt ses_ioctl +structure is used to pass information into the driver. +.El +.Sh EXAMPLES +.Bl -tag -width "Example 1" +.It Sy "Example 1" +Using the +.Dv SES_IOCTL_GETSTATE +ioctl +.El +.Pp +The following example uses the +.Dv SES_IOCTL_GETSTATE +ioctl to recover 20 bytes of page 4 from a previously opened device. +.Bd -literal -offset 2n char abuf[30]; struct ses_ioctl *sesp; int status; + sesp = (ses_ioctl *)abuf; sesp->size = 20; sesp->page_code = 4; status = ioctl(fd, SES_IOCTL_GETSTATE, abuf); -.fi -.in -2 - -.SH ATTRIBUTES -.sp -.LP -See \fBattributes\fR(5) for descriptions of the following attributes: -.sp - -.sp -.TS -box; -c | c -l | l . -ATTRIBUTE TYPE ATTRIBUTE VALUE -_ -Architecture SPARC -.TE - -.SH SEE ALSO -.sp -.LP -\fBses\fR(7D), \fBioctl\fR(9E) +.Ed +.Sh ERRORS +.Bl -tag -width ENOTTY +.It Er EIO +The +.Nm ses +driver was unable to obtain data from the enclosure services +device or the data transfer could not be completed. +.It Er ENOTTY +The +.Nm ses +driver does not support the requested ioctl function. +.It Er ENXIO +The enclosure services device does not exist. +.It Er EFAULT +The user specified a bad data length. +.El +.Sh STRUCTURES +The +.Vt ses_ioctl +structure has the following fields: +.Bd -literal -offset 2n +uint32_t page_size; /* Size of buffer that follows */ +uint8_t page_code: /* Page to be read/written */ +uint8_t reserved[3]; /* Reserved; Set to 0 */ +.Ed +.Sh ARCHITECTURE +SPARC +.Sh SEE ALSO +.Xr ses 7D , +.Xr ioctl 9E diff --git a/usr/src/man/man7i/sockio.7i b/usr/src/man/man7i/sockio.7i index 96c49b5ca2..58594879ef 100644 --- a/usr/src/man/man7i/sockio.7i +++ b/usr/src/man/man7i/sockio.7i @@ -1,65 +1,97 @@ -'\" te +.\" Copyright (c) 2017, Joyent, Inc. .\" Copyright 1989 AT&T Copyright (c) 1996, Sun Microsystems, Inc. All Rights Reserved -.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. -.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. -.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH SOCKIO 7I "Nov 8, 1996" -.SH NAME -sockio \- ioctls that operate directly on sockets -.SH SYNOPSIS -.LP -.nf -#include <sys/sockio.h> -.fi - -.SH DESCRIPTION -.sp -.LP -The \fBioctls\fR listed in this manual page apply directly to sockets, -independent of any underlying protocol. The \fBsetsockopt()\fR call (see -\fBgetsockopt\fR(3SOCKET)) is the primary method for operating on sockets, -rather than on the underlying protocol or network interface. \fBioctl\fRs for a -specific network interface or protocol are documented in the manual page for -that interface or protocol. -.sp -.ne 2 -.na -\fB\fBSIOCSPGRP\fR\fR -.ad -.RS 15n -The argument is a pointer to an \fBint\fR. Set the process-group \fBID\fR that -will subsequently receive \fBSIGIO\fR or \fBSIGURG\fR signals for the socket -referred to by the descriptor passed to \fBioctl\fR to the value of that -\fBint\fR. The argument must be either positive (in which case it must be a -process \fBID)\fR or negative (in which case it must be a process group). -.RE - -.sp -.ne 2 -.na -\fB\fBSIOCGPGRP\fR\fR -.ad -.RS 15n -The argument is a pointer to an \fBint\fR. Set the value of that \fBint\fR to -the process-group \fBID\fR that is receiving \fBSIGIO\fR or \fBSIGURG\fR -signals for the socket referred to by the descriptor passed to \fBioctl\fR. -.RE - -.sp -.ne 2 -.na -\fB\fBSIOCCATMARK\fR\fR -.ad -.RS 15n -The argument is a pointer to an \fBint\fR. Set the value of that \fBint\fR to -\fB1\fR if the read pointer for the socket referred to by the descriptor passed -to \fBioctl\fR points to a mark in the data stream for an out-of-band message. -Set the value of that \fBint\fR to \fB0\fR if the read pointer for the socket -referred to by the descriptor passed to \fBioctl\fR does not point to a mark -in the data stream for an out-of-band message. -.RE - -.SH SEE ALSO -.sp -.LP -\fBioctl\fR(2), \fBgetsockopt\fR(3SOCKET) +.\" The contents of this file are subject to the terms of the +.\" Common Development and Distribution License (the "License"). +.\" You may not use this file except in compliance with the License. +.\" +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE +.\" or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions +.\" and limitations under the License. +.\" +.\" When distributing Covered Code, include this CDDL HEADER in each +.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. +.\" If applicable, add the following below this CDDL HEADER, with the +.\" fields enclosed by brackets "[]" replaced with your own identifying +.\" information: Portions Copyright [yyyy] [name of copyright owner] +.Dd October 29, 2017 +.Dt SOCKIO 7I +.Os +.Sh NAME +.Nm sockio +.Nd ioctls that operate directly on sockets +.Sh SYNOPSIS +.In sys/sockio.h +.Sh DESCRIPTION +The +.Sy ioctl Ns s +listed in this manual page apply directly to sockets, +independent of any underlying protocol. +The +.Xr setsockopt 3SOCKET +call +.Po +see +.Xr getsockopt 3SOCKET +.Pc +is the primary method for operating on sockets, +rather than on the underlying protocol or network interface. +.Sy ioctl Ns s +for a specific network interface or protocol are documented in the manual page +for that interface or protocol. +.Bl -tag -width SIOCCATMARK +.It Dv SIOCSPGRP +The argument is a pointer to an +.Vt int . +Set the process-group +.Sy ID +that will subsequently receive +.Dv SIGIO +or +.Dv SIGURG +signals for the socket +referred to by the descriptor passed to +.Sy ioctl +to the value of that +.Vt int . +The argument must be either positive (in which case it must be a +process +.Sy ID ) +or negative (in which case it must be a process group). +.It Dv SIOCGPGRP +The argument is a pointer to an +.Vt int . +Get the value of that +.Vt int +to the process-group +.Sy ID +that is receiving +.Dv SIGIO +or +.Dv SIGURG +signals for the socket referred to by the descriptor passed to +.Sy ioctl . +.It Dv SIOCCATMARK +The argument is a pointer to an +.Vt int . +Set the value of that +.Vt int +to +.Sy 1 +if the read pointer for the socket referred to by the descriptor passed +to +.Xr ioctl 2 +points to a mark in the data stream for an out-of-band message. +Set the value of that +.Vt int +to +.Sy 0 +if the read pointer for the socket +referred to by the descriptor passed to +.Sy ioctl +does not point to a mark +in the data stream for an out-of-band message. +.El +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr getsockopt 3SOCKET diff --git a/usr/src/man/man7i/streamio.7i b/usr/src/man/man7i/streamio.7i index 2b7e45629b..d291cd82c3 100644 --- a/usr/src/man/man7i/streamio.7i +++ b/usr/src/man/man7i/streamio.7i @@ -1,1812 +1,1550 @@ -'\" te +.\" Copyright (c) 2017, Joyent, Inc. .\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved. .\" Copyright 1989 AT&T -.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. -.\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with -.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH STREAMIO 7I "Apr 8, 2009" -.SH NAME -streamio \- STREAMS ioctl commands -.SH SYNOPSIS -.LP -.nf -#include <sys/types.h> -#include <stropts.h> -#include <sys/conf.h> - -\fBint\fR \fBioctl\fR(\fBint\fR \fIfildes\fR, \fBint\fR \fIcommand\fR, \fB\&... /*arg*/\fR); -.fi - -.SH DESCRIPTION -.sp -.LP -STREAMS (see \fBIntro\fR(3)) \fBioctl\fR commands are a subset of the -\fBioctl\fR(2) commands and perform a variety of control functions on streams. -.sp -.LP -The \fIfildes\fR argument is an open file descriptor that refers to a stream. -The \fIcommand\fR argument determines the control function to be performed as -described below. The \fIarg\fR argument represents additional information that -is needed by this command. The type of \fIarg\fR depends upon the command, but +.\" The contents of this file are subject to the terms of the +.\" Common Development and Distribution License (the "License"). +.\" You may not use this file except in compliance with the License. +.\" +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE +.\" or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions +.\" and limitations under the License. +.\" +.\" When distributing Covered Code, include this CDDL HEADER in each +.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. +.\" If applicable, add the following below this CDDL HEADER, with the +.\" fields enclosed by brackets "[]" replaced with your own identifying +.\" information: Portions Copyright [yyyy] [name of copyright owner] +.Dd October 29, 2017 +.Dt STREAMIO 7I +.Os +.Sh NAME +.Nm streamio +.Nd STREAMS ioctl commands +.Sh SYNOPSIS +.In sys/types.h +.In stropts.h +.In sys/conf.h +.Ft int +.Fo ioctl +.Fa "int fildes" +.Fa "int command" +.Fa "\&... /*arg*/" +.Fc +.Sh DESCRIPTION +STREAMS (see +.Xr Intro 3 ) +.Fn ioctl +commands are a subset of the +.Xr ioctl 2 +commands and perform a variety of control functions on streams. +.Pp +The +.Fa fildes +argument is an open file descriptor that refers to a stream. +The +.Fa command +argument determines the control function to be performed as +described below. +The +.Fa arg +argument represents additional information that +is needed by this command. +The type of +.Fa arg +depends upon the command, but it is generally an integer or a pointer to a command-specific data structure. -The \fIcommand\fR and \fIarg\fR arguments are interpreted by the STREAM head. +The +.Fa command +and +.Fa arg +arguments are interpreted by the STREAM head. Certain combinations of these arguments may be passed to a module or driver in the stream. -.sp -.LP -Since these STREAMS commands are \fBioctls\fR, they are subject to the errors -described in \fBioctl\fR(2). In addition to those errors, the call will fail -with \fBerrno\fR set to \fBEINVAL,\fR without processing a control function, if -the STREAM referenced by \fIfildes\fR is linked below a multiplexor, or if -\fIcommand\fR is not a valid value for a stream. -.sp -.LP -Also, as described in \fBioctl\fR(2), STREAMS modules and drivers can detect -errors. In this case, the module or driver sends an error message to the STREAM -head containing an error value. This causes subsequent calls to fail with -\fBerrno\fR set to this value. -.SH IOCTLS -.sp -.LP -The following \fBioctl\fR commands, with error values indicated, are applicable -to all STREAMS files: -.sp -.ne 2 -.na -\fB\fBI_PUSH\fR\fR -.ad -.RS 15n -Pushes the module whose name is pointed to by \fIarg\fR onto the top of the -current stream, just below the STREAM head. If the STREAM is a pipe, the module -will be inserted between the stream heads of both ends of the pipe. It then -calls the open routine of the newly-pushed module. On failure, \fBerrno\fR is -set to one of the following values: -.sp -.ne 2 -.na -\fB\fBEINVAL\fR\fR -.ad -.RS 11n +.Pp +Since these STREAMS commands are +.Sy ioctls , +they are subject to the errors described in +.Xr ioctl 2 . +In addition to those errors, the call will fail +with +.Va errno +set to +.Er EINVAL , +without processing a control function, if the STREAM referenced by +.Fa fildes +is linked below a multiplexor, or if +.Fa command +is not a valid value for a stream. +.Pp +Also, as described in +.Xr ioctl 2 , +STREAMS modules and drivers can detect +errors. +In this case, the module or driver sends an error message to the STREAM +head containing an error value. +This causes subsequent calls to fail with +.Va errno +set to this value. +.Sh IOCTLS +The following +.Fn ioctl +commands, with error values indicated, are applicable to all STREAMS files: +.Bl -tag -width I_SETCLTIME +.It Dv I_PUSH +Pushes the module whose name is pointed to by +.Va arg +onto the top of the current stream, just below the STREAM head. +If the STREAM is a pipe, the module +will be inserted between the stream heads of both ends of the pipe. +It then calls the open routine of the newly-pushed module. +On failure, +.Va errno +is set to one of the following values: +.Bl -tag -width ENOTSUP +.It Er EINVAL Invalid module name. -.RE - -.sp -.ne 2 -.na -\fB\fBEFAULT\fR\fR -.ad -.RS 11n -\fIarg\fR points outside the allocated address space. -.RE - -.sp -.ne 2 -.na -\fB\fBENXIO\fR\fR -.ad -.RS 11n +.It Er EFAULT +.Va arg +points outside the allocated address space. +.It Er ENXIO Open routine of new module failed. -.RE - -.sp -.ne 2 -.na -\fB\fBENXIO\fR\fR -.ad -.RS 11n -Hangup received on \fIfildes\fR. -.RE - -.sp -.ne 2 -.na -\fB\fBENOTSUP\fR\fR -.ad -.RS 11n +.It Er ENXIO +Hangup received on +.Va fildes . +.It Er ENOTSUP Pushing a module is not supported on this stream. -.RE - -.RE - -.sp -.ne 2 -.na -\fB\fBI_POP\fR\fR -.ad -.RS 15n +.El +.It Dv I_POP Removes the module just below the STREAM head of the STREAM pointed to by -\fIfildes\fR. To remove a module from a pipe requires that the module was -pushed on the side it is being removed from. \fIarg\fR should be \fB0\fR in an -\fBI_POP\fR request. On failure, \fBerrno\fR is set to one of the following -values: -.sp -.ne 2 -.na -\fB\fBEINVAL\fR\fR -.ad -.RS 11n +.Fa fildes . +To remove a module from a pipe requires that the module was +pushed on the side it is being removed from. +.Fa arg +should be +.Sy 0 +in an +.Dv I_POP +request. +On failure, +.Va errno +is set to one of the following values: +.Bl -tag -width ENOTSUP +.It Er EINVAL No module present in the stream. -.RE - -.sp -.ne 2 -.na -\fB\fBENXIO\fR\fR -.ad -.RS 11n -Hangup received on \fIfildes\fR. -.RE - -.sp -.ne 2 -.na -\fB\fBEPERM\fR\fR -.ad -.RS 11n +.It Er ENXIO +Hangup received on +.Fa fildes . +.It Er EPERM Attempt to pop through an anchor by an unprivileged process. -.RE - -.sp -.ne 2 -.na -\fB\fBENOTSUP\fR\fR -.ad -.RS 11n +.It Er ENOTSUP Removal is not supported. -.RE - -.RE - -.sp -.ne 2 -.na -\fB\fBI_ANCHOR\fR\fR -.ad -.RS 15n +.El +.It Dv I_ANCHOR Positions the stream anchor to be at the stream's module directly below the -stream head. Once this has been done, only a privileged process may pop modules -below the anchor on the stream. \fIarg\fR must be \fB0\fR in an \fBI_ANCHOR\fR -request. On failure, \fBerrno\fR is set to the following value: -.sp -.ne 2 -.na -\fB\fBEINVAL\fR\fR -.ad -.RS 10n +stream head. +Once this has been done, only a privileged process may pop modules +below the anchor on the stream. +.Va arg +must be +.Sy 0 +in an +.Dv I_ANCHOR +request. +On failure, +.Va errno +is set to the following value: +.Bl -tag -width EINVAL +.It Er EINVAL Request to put an anchor on a pipe. -.RE - -.RE - -.sp -.ne 2 -.na -\fB\fBI_LOOK\fR\fR -.ad -.RS 15n +.El +.It Dv I_LOOK Retrieves the name of the module just below the stream head of the stream -pointed to by \fIfildes\fR, and places it in a null terminated character string -pointed at by \fIarg\fR. The buffer pointed to by \fIarg\fR should be at least -\fBFMNAMESZ\fR+1 bytes long. This requires the declaration \fB#include -<sys/conf.h>\fR. On failure, \fBerrno\fR is set to one of the following values: -.sp -.ne 2 -.na -\fB\fBEFAULT\fR\fR -.ad -.RS 10n -\fIarg\fR points outside the allocated address space. -.RE - -.sp -.ne 2 -.na -\fB\fBEINVAL\fR\fR -.ad -.RS 10n +pointed to by +.Fa fildes , +and places it in a null terminated character string +pointed at by +.Fa arg . +The buffer pointed to by +.Fa arg +should be at least +.Dv FMNAMESZ Ns +1 +bytes long. +This requires the declaration +.Ql "#include <sys/conf.h>" . +On failure, +.Dv errno +is set to one of the following values: +.Bl -tag -width EFAULT +.It Er EFAULT +.Fa arg +points outside the allocated address space. +.It Er EINVAL No module present in stream. -.RE - -.RE - -.sp -.ne 2 -.na -\fB\fBI_FLUSH\fR\fR -.ad -.RS 15n +.El +.It Dv I_FLUSH This request flushes all input and/or output queues, depending on the value of -\fIarg\fR. Legal \fIarg\fR values are: -.sp -.ne 2 -.na -\fBFLUSHR\fR -.ad -.RS 11n +.Fa arg . +Legal +.Fa arg +values are: +.Bl -tag -width FLUSHRW +.It Dv FLUSHR Flush read queues. -.RE - -.sp -.ne 2 -.na -\fBFLUSHW\fR -.ad -.RS 11n +.It Dv FLUSHW Flush write queues. -.RE - -.sp -.ne 2 -.na -\fBFLUSHRW\fR -.ad -.RS 11n +.It Dv FLUSHRW Flush read and write queues. -.RE - +.El +.Pp If a pipe or FIFO does not have any modules pushed, the read queue of the -stream head on either end is flushed depending on the value of \fIarg\fR. -.sp -If \fBFLUSHR\fR is set and \fIfildes\fR is a pipe, the read queue for that end -of the pipe is flushed and the write queue for the other end is flushed. If -\fIfildes\fR is a FIFO, both queues are flushed. -.sp -If \fBFLUSHW\fR is set and \fIfildes\fR is a pipe and the other end of the pipe +stream head on either end is flushed depending on the value of +.Fa arg . +.Pp +If +.Dv FLUSHR +is set and +.Fa fildes +is a pipe, the read queue for that end +of the pipe is flushed and the write queue for the other end is flushed. +If +.Fa fildes +is a FIFO, both queues are flushed. +.Pp +If +.Dv FLUSHW +is set and +.Fa fildes +is a pipe and the other end of the pipe exists, the read queue for the other end of the pipe is flushed and the write -queue for this end is flushed. If \fIfildes\fR is a FIFO, both queues of the +queue for this end is flushed. +If +.Fa fildes +is a FIFO, both queues of the FIFO are flushed. -.sp -If \fBFLUSHRW\fR is set, all read queues are flushed, that is, the read queue +.Pp +If +.Dv FLUSHRW +is set, all read queues are flushed, that is, the read queue for the FIFO and the read queue on both ends of the pipe are flushed. -.sp +.Pp Correct flush handling of a pipe or FIFO with modules pushed is achieved via -the \fBpipemod\fR module. This module should be the first module pushed onto a +the +.Sy pipemod +module. +This module should be the first module pushed onto a pipe so that it is at the midpoint of the pipe itself. -.sp -On failure, \fBerrno\fR is set to one of the following values: -.sp -.ne 2 -.na -\fB\fBENOSR\fR\fR -.ad -.RS 10n +.Pp +On failure, +.Va errno +is set to one of the following values: +.Bl -tag -width EINVAL +.It Er ENOSR Unable to allocate buffers for flush message due to insufficient stream memory resources. -.RE - -.sp -.ne 2 -.na -\fB\fBEINVAL\fR\fR -.ad -.RS 10n -Invalid \fIarg\fR value. -.RE - -.sp -.ne 2 -.na -\fB\fBENXIO\fR\fR -.ad -.RS 10n -Hangup received on \fIfildes\fR. -.RE - -.RE - -.sp -.ne 2 -.na -\fB\fBI_FLUSHBAND\fR\fR -.ad -.RS 15n -Flushes a particular band of messages. \fIarg\fR points to a \fBbandinfo\fR +.It Er EINVAL +Invalid +.Va arg +value. +.It Er ENXIO +Hangup received on +.Fa fildes . +.El +.It Dv I_FLUSHBAND +Flushes a particular band of messages. +.Fa arg +points to a +.Vt bandinfo structure that has the following members: -.sp -.in +2 -.nf +.Bd -literal -offset 2n unsigned char bi_pri; int bi_flag; -.fi -.in -2 - -The \fBbi_flag\fR field may be one of \fBFLUSHR\fR, \fBFLUSHW\fR, or -\fBFLUSHRW\fR as described earlier. -.RE - -.sp -.ne 2 -.na -\fB\fBI_SETSIG\fR\fR -.ad -.RS 15n +.Ed +.Pp +The +.Fa bi_flag +field may be one of +.Dv FLUSHR , +.Dv FLUSHW , +or +.Dv FLUSHRW +as described earlier. +.It Dv I_SETSIG Informs the stream head that the user wishes the kernel to issue the -\fBSIGPOLL\fR signal (see \fBsignal\fR(3C)) when a particular event has -occurred on the stream associated with \fIfildes\fR. \fBI_SETSIG\fR supports an -asynchronous processing capability in streams. The value of \fIarg\fR is a -bitmask that specifies the events for which the user should be signaled. It is -the bitwise OR of any combination of the following constants: -.sp -.ne 2 -.na -\fB\fBS_INPUT\fR\fR -.ad -.RS 13n -Any message other than an \fBM_PCPROTO\fR has arrived on a stream head read -queue. This event is maintained for compatibility with previous releases. This -event is triggered even if the message is of zero length. -.RE - -.sp -.ne 2 -.na -\fB\fBS_RDNORM\fR\fR -.ad -.RS 13n +.Dv SIGPOLL +signal (see +.Xr signal 3C ) +when a particular event has occurred on the stream associated with +.Fa fildes . +.Dv I_SETSIG +supports an asynchronous processing capability in streams. +The value of +.Fa arg +is a bitmask that specifies the events for which the user should be signaled. +It is the bitwise OR of any combination of the following constants: +.Bl -tag -width S_BANDURG +.It Dv S_INPUT +Any message other than an +.Dv M_PCPROTO +has arrived on a stream head read queue. +This event is maintained for compatibility with previous releases. +This event is triggered even if the message is of zero length. +.It Dv S_RDNORM An ordinary (non-priority) message has arrived on a stream head read queue. This event is triggered even if the message is of zero length. -.RE - -.sp -.ne 2 -.na -\fB\fBS_RDBAND\fR\fR -.ad -.RS 13n +.It Dv S_RDBAND A priority band message (band > 0) has arrived on a stream head read queue. This event is triggered even if the message is of zero length. -.RE - -.sp -.ne 2 -.na -\fB\fBS_HIPRI\fR\fR -.ad -.RS 13n -A high priority message is present on the stream head read queue. This event is -triggered even if the message is of zero length. -.RE - -.sp -.ne 2 -.na -\fB\fBS_OUTPUT\fR\fR -.ad -.RS 13n -The write queue just below the stream head is no longer full. This notifies the +.It Dv S_HIPRI +A high priority message is present on the stream head read queue. +This event is triggered even if the message is of zero length. +.It Dv S_OUTPUT +The write queue just below the stream head is no longer full. +This notifies the user that there is room on the queue for sending (or writing) data downstream. -.RE - -.sp -.ne 2 -.na -\fB\fBS_WRNORM\fR\fR -.ad -.RS 13n -This event is the same as \fBS_OUTPUT\fR. -.RE - -.sp -.ne 2 -.na -\fB\fBS_WRBAND\fR\fR -.ad -.RS 13n +.It Dv S_WRNORM +This event is the same as +.Dv S_OUTPUT . +.It Dv S_WRBAND A priority band greater than 0 of a queue downstream exists and is writable. This notifies the user that there is room on the queue for sending (or writing) priority data downstream. -.RE - -.sp -.ne 2 -.na -\fB\fBS_MSG\fR\fR -.ad -.RS 13n -A STREAMS signal message that contains the \fBSIGPOLL\fR signal has reached the +.It Dv S_MSG +A STREAMS signal message that contains the +.Dv SIGPOLL +signal has reached the front of the stream head read queue. -.RE - -.sp -.ne 2 -.na -\fB\fBS_ERROR\fR\fR -.ad -.RS 13n -An \fBM_ERROR\fR message has reached the stream head. -.RE - -.sp -.ne 2 -.na -\fB\fBS_HANGUP\fR\fR -.ad -.RS 13n -An \fBM_HANGUP\fR message has reached the stream head. -.RE - -.sp -.ne 2 -.na -\fB\fBS_BANDURG\fR\fR -.ad -.RS 13n -When used in conjunction with \fBS_RDBAND\fR, \fBSIGURG\fR is generated instead -of \fBSIGPOLL\fR when a priority message reaches the front of the stream head +.It Dv S_ERROR +An +.Dv M_ERROR +message has reached the stream head. +.It Dv S_HANGUP +An +.Dv M_HANGUP +message has reached the stream head. +.It Dv S_BANDURG +When used in conjunction with +.Dv S_RDBAND , +.Dv SIGURG +is generated instead of +.Dv SIGPOLL +when a priority message reaches the front of the stream head read queue. -.RE - +.El +.Pp A user process may choose to be signaled only of high priority messages by -setting the \fIarg\fR bitmask to the value \fBS_HIPRI\fR. -.sp -Processes that wish to receive \fBSIGPOLL\fR signals must explicitly register -to receive them using \fBI_SETSIG\fR. If several processes register to receive +setting the +.Fa arg +bitmask to the value +.Dv S_HIPRI . +.Pp +Processes that wish to receive +.Dv SIGPOLL +signals must explicitly register +to receive them using +.Dv I_SETSIG . +If several processes register to receive this signal for the same event on the same stream, each process will be signaled when the event occurs. -.sp -If the value of \fIarg\fR is zero, the calling process will be unregistered and -will not receive further \fBSIGPOLL\fR signals. On failure, \fBerrno\fR is set -to one of the following values: -.sp -.ne 2 -.na -\fB\fBEINVAL\fR\fR -.ad -.RS 10n -\fIarg\fR value is invalid or \fIarg\fR is zero and process is not registered -to receive the \fBSIGPOLL\fR signal. -.RE - -.sp -.ne 2 -.na -\fB\fBEAGAIN\fR\fR -.ad -.RS 10n +.Pp +If the value of +.Fa arg +is zero, the calling process will be unregistered and +will not receive further +.Dv SIGPOLL +signals. +On failure, +.Va errno +is set to one of the following values: +.Bl -tag -width EINVAL +.It Sy EINVAL +.Fa arg +value is invalid or +.Fa arg +is zero and process is not registered to receive the +.Dv SIGPOLL +signal. +.It Sy EAGAIN Allocation of a data structure to store the signal request failed. -.RE - -.RE - -.sp -.ne 2 -.na -\fB\fBI_GETSIG\fR\fR -.ad -.RS 15n +.El +.It Dv I_GETSIG Returns the events for which the calling process is currently registered to be -sent a \fBSIGPOLL\fR signal. The events are returned as a bitmask pointed to -by \fIarg\fR, where the events are those specified in the description of -\fBI_SETSIG\fR above. On failure, \fBerrno\fR is set to one of the following -values: -.sp -.ne 2 -.na -\fB\fBEINVAL\fR\fR -.ad -.RS 10n -Process not registered to receive the \fBSIGPOLL\fR signal. -.RE - -.sp -.ne 2 -.na -\fB\fBEFAULT\fR\fR -.ad -.RS 10n -\fIarg\fR points outside the allocated address space. -.RE - -.RE - -.sp -.ne 2 -.na -\fB\fBI_FIND\fR\fR -.ad -.RS 15n +sent a +.Dv SIGPOLL +signal. +The events are returned as a bitmask pointed to by +.Va arg , +where the events are those specified in the description of +.Dv I_SETSIG +above. +On failure, +.Va errno +is set to one of the following values: +.Bl -tag -width EINVAL +.It Sy EINVAL +Process not registered to receive the +.Dv SIGPOLL +signal. +.It Sy EFAULT +.Fa arg +points outside the allocated address space. +.El +.It Dv I_FIND Compares the names of all modules currently present in the stream to the name -pointed to by \fIarg\fR, and returns 1 if the named module is present in the -stream. It returns 0 if the named module is not present. On failure, -\fBerrno\fR is set to one of the following values: -.sp -.ne 2 -.na -\fB\fBEFAULT\fR\fR -.ad -.RS 10n -\fIarg\fR points outside the allocated address space. -.RE - -.sp -.ne 2 -.na -\fB\fBEINVAL\fR\fR -.ad -.RS 10n -\fIarg\fR does not contain a valid module name. -.RE - -.RE - -.sp -.ne 2 -.na -\fB\fBI_PEEK\fR\fR -.ad -.RS 15n +pointed to by +.Fa arg , +and returns 1 if the named module is present in the stream. +It returns 0 if the named module is not present. +On failure, +.Va errno +is set to one of the following values: +.Bl -tag -width EINVAL +.It Sy EFAULT +.Fa arg +points outside the allocated address space. +.It Sy EINVAL +.Fa arg +does not contain a valid module name. +.El +.It Dv I_PEEK Allows a user to retrieve the information in the first message on the stream -head read queue without taking the message off the queue. \fBI_PEEK\fR is -analogous to \fBgetmsg\fR(2) except that it does not remove the message from -the queue. \fIarg\fR points to a \fBstrpeek\fR structure, which contains the -following members: -.sp -.in +2 -.nf +head read queue without taking the message off the queue. +.Dv I_PEEK +is analogous to +.Xr getmsg 2 +except that it does not remove the message from the queue. +.Fa arg +points to a +.Vt strpeek +structure, which contains the following members: +.Bd -literal -offset 2n struct strbuf ctlbuf; -struct strbuf databuf; +struct strbuf databuf; long flags; -.fi -.in -2 - -The \fBmaxlen\fR field in the \fBctlbuf\fR and \fBdatabuf\fR \fBstrbuf\fR -structures (see \fBgetmsg\fR(2)) must be set to the number of bytes of control -information and/or data information, respectively, to retrieve. \fBflags\fR may -be set to \fBRS_HIPRI\fR or \fB0\fR. If \fBRS_HIPRI\fR is set, \fBI_PEEK\fR -will look for a high priority message on the stream head read queue. Otherwise, -\fBI_PEEK\fR will look for the first message on the stream head read queue. -.sp -\fBI_PEEK\fR returns \fB1\fR if a message was retrieved, and returns \fB0\fR if -no message was found on the stream head read queue. It does not wait for a -message to arrive. On return, \fBctlbuf\fR specifies information in the control -buffer, \fBdatabuf\fR specifies information in the data buffer, and \fBflags\fR -contains the value \fBRS_HIPRI\fR or \fB0\fR. On failure, \fBerrno\fR is set to -the following value: -.sp -.ne 2 -.na -\fB\fBEFAULT\fR\fR -.ad -.RS 11n -\fIarg\fR points, or the buffer area specified in \fBctlbuf\fR or \fBdatabuf\fR +.Ed +.Pp +The +.Ft maxlen +field in the +.Vt ctlbuf +and +.Vt databuf +.Vt strbuf +structures (see +.Xr getmsg 2 ) +must be set to the number of bytes of control +information and/or data information, respectively, to retrieve. +.Fa flags +may be set to +.Dv RS_HIPRI +or +.Sy 0 . +If +.Dv RS_HIPRI +is set, +.Dv I_PEEK +will look for a high priority message on the stream head read queue. +Otherwise, +.Dv I_PEEK +will look for the first message on the stream head read queue. +.Pp +.Dv I_PEEK +returns +.Sy 1 +if a message was retrieved, and returns +.Sy 0 +if no message was found on the stream head read queue. +It does not wait for a message to arrive. +On return, +.Vt ctlbuf +specifies information in the control buffer, +.Vt databuf +specifies information in the data buffer, and +.Fa flags +contains the value +.Dv RS_HIPRI +or +.Sy 0 . +On failure, +.Va errno +is set to the following value: +.Bl -tag -width EBADMSG +.It Er EFAULT +.Fa arg +points, or the buffer area specified in +.Vt ctlbuf +or +.Vt databuf is, outside the allocated address space. -.RE - -.sp -.ne 2 -.na -\fB\fBEBADMSG\fR\fR -.ad -.RS 11n -Queued message to be read is not valid for \fBI_PEEK\fR. -.RE - -.sp -.ne 2 -.na -\fB\fBEINVAL\fR\fR -.ad -.RS 11n -Illegal value for \fBflags\fR. -.RE - -.sp -.ne 2 -.na -\fB\fBENOSR\fR\fR -.ad -.RS 11n -Unable to allocate buffers to perform the I_PEEK due to insufficient STREAMS -memory resources. -.RE - -.RE - -.sp -.ne 2 -.na -\fB\fBI_SRDOPT\fR\fR -.ad -.RS 15n -Sets the read mode (see \fBread\fR(2)) using the value of the argument -\fIarg\fR. Legal \fIarg\fR values are: -.sp -.ne 2 -.na -\fBRNORM\fR -.ad -.RS 9n +.It Er EBADMSG +Queued message to be read is not valid for +.Dv I_PEEK . +.It Er EINVAL +Illegal value for +.Vt flags . +.It Er ENOSR +Unable to allocate buffers to perform the +.Dv I_PEEK +due to insufficient STREAMS memory resources. +.El +.It Dv I_SRDOPT +Sets the read mode (see +.Xr read 2 ) +using the value of the argument +.Va arg . +Legal +.Va arg +values are: +.Bl -tag -width RNORM +.It Dv RNORM Byte-stream mode, the default. -.RE - -.sp -.ne 2 -.na -\fBRMSGD\fR -.ad -.RS 9n +.It Dv RMSGD Message-discard mode. -.RE - -.sp -.ne 2 -.na -\fBRMSGN\fR -.ad -.RS 9n +.It Dv RMSGN Message-nondiscard mode. -.RE - +.El +.Pp In addition, the stream head's treatment of control messages may be changed by -setting the following flags in \fIarg\fR: -.sp -.ne 2 -.na -\fBRPROTNORM\fR -.ad -.RS 13n -Reject \fBread()\fR with \fBEBADMSG\fR if a control message is at the front of -the stream head read queue. -.RE - -.sp -.ne 2 -.na -\fBRPROTDAT\fR -.ad -.RS 13n +setting the following flags in +.Va arg : +.Bl -tag -width RPROTNORM +.It Dv RPROTNORM +Reject +.Xr read 2 +with +.Er EBADMSG +if a control message is at the front of the stream head read queue. +.It Dv RPROTDAT Deliver the control portion of a message as data when a user issues -\fBread()\fR. This is the default behavior. -.RE - -.sp -.ne 2 -.na -\fBRPROTDIS\fR -.ad -.RS 13n +.Xr read 2 . +This is the default behavior. +.It Dv RPROTDIS Discard the control portion of a message, delivering any data portion, when a -user issues a \fBread\fR(\|). -.RE - -On failure, \fBerrno\fR is set to the following value: -.sp -.ne 2 -.na -\fB\fBEINVAL\fR\fR -.ad -.RS 10n -\fIarg\fR is not one of the above legal values, or \fIarg\fR is the bitwise -inclusive \fBOR\fR of \fBRMSGD\fR and \fBRMSGN\fR. -.RE - -.RE - -.sp -.ne 2 -.na -\fB\fBI_GRDOPT\fR\fR -.ad -.RS 15n -Returns the current read mode setting in an \fBint\fR pointed to by the -argument \fIarg\fR. Read modes are described in \fBread\fR(\|). On failure, -\fBerrno\fR is set to the following value: -.sp -.ne 2 -.na -\fB\fBEFAULT\fR\fR -.ad -.RS 10n -\fIarg\fR points outside the allocated address space. -.RE - -.RE - -.sp -.ne 2 -.na -\fB\fBI_NREAD\fR\fR -.ad -.RS 15n +user issues a +.Xr read 2 . +.El +.Pp +On failure, +.Va errno +is set to the following value: +.Bl -tag -width EINVAL +.It Er EINVAL +.Va arg +is not one of the above legal values, or +.Va arg +is the bitwise +inclusive +.Sy OR +of +.Dv RMSGD +and +.Dv RMSGN . +.El +.It Dv I_GRDOPT +Returns the current read mode setting in an +.Vt int +pointed to by the argument +.Fa arg . +Read modes are described in +.Xr read 2 . +On failure, +.Va errno +is set to the following value: +.Bl -tag -width EFAULT +.It Er EFAULT +.Fa arg +points outside the allocated address space. +.El +.It Dv I_NREAD Counts the number of data bytes in data blocks in the first message on the stream head read queue, and places this value in the location pointed to by -\fIarg\fR. The return value for the command is the number of messages on the -stream head read queue. For example, if zero is returned in \fIarg\fR, but the -\fBioctl\fR return value is greater than zero, this indicates that a -zero-length message is next on the queue. On failure, \fBerrno\fR is set to the -following value: -.sp -.ne 2 -.na -\fB\fBEFAULT\fR\fR -.ad -.RS 10n -\fIarg\fR points outside the allocated address space. -.RE - -.RE - -.sp -.ne 2 -.na -\fB\fBI_FDINSERT\fR\fR -.ad -.RS 15n +.Fa arg . +The return value for the command is the number of messages on the +stream head read queue. +For example, if zero is returned in +.Fa arg , +but the +.Fn ioctl +return value is greater than zero, this indicates that a +zero-length message is next on the queue. +On failure, +.Va errno +is set to the following value: +.Bl -tag -width EFAULT +.It Er EFAULT +.Fa arg +points outside the allocated address space. +.El +.It Dv I_FDINSERT Creates a message from specified buffer(s), adds information about another -stream and sends the message downstream. The message contains a control part -and an optional data part. The data and control parts to be sent are +stream and sends the message downstream. +The message contains a control part and an optional data part. +The data and control parts to be sent are distinguished by placement in separate buffers, as described below. -.sp -The \fIarg\fR argument points to a \fBstrfdinsert\fR structure, which contains +.Pp +The +.Fa arg +argument points to a +.Vt strfdinsert +structure, which contains the following members: -.sp -.in +2 -.nf +.Bd -literal -offset 2n struct strbuf ctlbuf; struct strbuf databuf; -t_uscalar_t flags; -int fildes; -int offset; -.fi -.in -2 - -The \fBlen\fR member in the \fBctlbuf strbuf\fR structure (see \fBputmsg\fR(2)) -must be set to the size of a \fBt_uscalar_t\fR plus the number of bytes of -control information to be sent with the message. The \fBfildes\fR member -specifies the file descriptor of the other stream, and the \fBoffset\fR member, -which must be suitably aligned for use as a \fBt_uscalar_t\fR, specifies the -offset from the start of the control buffer where \fBI_FDINSERT\fR will store a -\fBt_uscalar_t\fR whose interpretation is specific to the stream end. The -\fBlen\fR member in the \fBdatabuf strbuf\fR structure must be set to the -number of bytes of data information to be sent with the message, or to 0 if no -data part is to be sent. -.sp -The \fBflags\fR member specifies the type of message to be created. A normal -message is created if \fBflags\fR is set to 0, and a high-priority message is -created if \fBflags\fR is set to \fBRS_HIPRI\fR. For non-priority messages, -\fBI_FDINSERT\fR will block if the stream write queue is full due to internal -flow control conditions. For priority messages, \fBI_FDINSERT\fR does not -block on this condition. For non-priority messages, \fBI_FDINSERT\fR does not -block when the write queue is full and \fBO_NDELAY\fR or \fBO_NONBLOCK\fR is -set. Instead, it fails and sets \fBerrno\fR to \fBEAGAIN\fR. -.sp -\fBI_FDINSERT\fR also blocks, unless prevented by lack of internal resources, -waiting for the availability of message blocks in the stream, regardless of -priority or whether \fBO_NDELAY\fR or \fBO_NONBLOCK\fR has been specified. No -partial message is sent. -.sp -The \fBioctl()\fR function with the \fBI_FDINSERT\fR command will fail if: -.sp -.ne 2 -.na -\fB\fBEAGAIN\fR\fR -.ad -.RS 10n -A non-priority message is specified, the \fBO_NDELAY\fR or \fBO_NONBLOCK\fR +t_uscalar_t flags; +int fildes; +int offset; +.Ed +.Pp +The +.Fa len +member in the +.Vt ctlbuf +.Vt strbuf +structure (see +.Xr putmsg 2 ) +must be set to the size of a +.Vt t_uscalar_t +plus the number of bytes of +control information to be sent with the message. +The +.Fa fildes +member specifies the file descriptor of the other stream, and the +.Fa offset +member, which must be suitably aligned for use as a +.Vt t_uscalar_t , +specifies the offset from the start of the control buffer where +.Dv I_FDINSERT +will store a +.Vt t_uscalar_t +whose interpretation is specific to the stream end. +The +.Fa len +member in the +.Vt databuf +.Vt strbuf +structure must be set to the number of bytes of data information to be sent with +the message, or to 0 if no data part is to be sent. +.Pp +The +.Fa flags +member specifies the type of message to be created. +A normal message is created if +.Fa flags +is set to 0, and a high-priority message is created if +.Fa flags +is set to +.Dv RS_HIPRI . +For non-priority messages, +.Dv I_FDINSERT +will block if the stream write queue is full due to internal +flow control conditions. +For priority messages, +.Dv I_FDINSERT +does not block on this condition. +or non-priority messages, +.Dv I_FDINSERT +does not +block when the write queue is full and +.Dv O_NDELAY +or +.Dv O_NONBLOCK +is set. +Instead, it fails and sets +.Va errno +to +.Er EAGAIN . +.Pp +.Dv I_FDINSERT +also blocks, unless prevented by lack of internal resources, waiting for the +availability of message blocks in the stream, regardless of priority or whether +.Dv O_NDELAY +or +.Dv O_NONBLOCK +has been specified. +No partial message is sent. +.Pp +The +.Fn ioctl +function with the +.Dv I_FDINSERT +command will fail if: +.Bl -tag -width EAGAIN +.It Er EAGAIN +A non-priority message is specified, the +.Dv O_NDELAY +or +.Dv O_NONBLOCK flag is set, and the stream write queue is full due to internal flow control conditions. -.RE - -.sp -.ne 2 -.na -\fB\fBENOSR\fR\fR -.ad -.RS 10n +.It Er ENOSR Buffers can not be allocated for the message that is to be created. -.RE - -.sp -.ne 2 -.na -\fB\fBEFAULT\fR\fR -.ad -.RS 10n -The \fIarg\fR argument points, or the buffer area specified in \fBctlbuf\fR or -\fBdatabuf\fR is, outside the allocated address space. -.RE - -.sp -.ne 2 -.na -\fB\fBEINVAL\fR\fR -.ad -.RS 10n -One of the following: The \fBfildes\fR member of the \fBstrfdinsert\fR +.It Er EFAULT +The +.Fa arg +argument points, or the buffer area specified in +.Vt ctlbuf +or +.Vt databuf +is, outside the allocated address space. +.It Er EINVAL +One of the following: The +.Fa fildes +member of the +.Vt strfdinsert structure is not a valid, open stream file descriptor; the size of a -\fBt_uscalar_t\fR plus \fBoffset\fR is greater than the \fBlen\fR member for -the buffer specified through \fBctlptr\fR; the \fBoffset\fR member does not -specify a properly-aligned location in the data buffer; or an undefined value -is stored in \fBflags\fR. -.RE - -.sp -.ne 2 -.na -\fB\fBENXIO\fR\fR -.ad -.RS 10n -Hangup received on the \fBfildes\fR argument of the \fBioctl\fR call or the -\fBfildes\fR member of the \fBstrfdinsert\fR structure. -.RE - -.sp -.ne 2 -.na -\fB\fBERANGE\fR\fR -.ad -.RS 10n -The \fBlen\fR field for the buffer specified through \fBdatabuf\fR does not -fall within the range specified by the maximum and minimum packet sizes of the -topmost stream module; or the \fBlen\fR member for the buffer specified through -\fBdatabuf\fR is larger than the maximum configured size of the data part of a -message; or the \fBlen\fR member for the buffer specified through \fBctlbuf\fR +.Vt t_uscalar_t +plus +.Fa offset +is greater than the +.Fa len +member for the buffer specified through +.Fa ctlptr ; +the +.Fa offset +member does not specify a properly-aligned location in the data buffer; or an +undefined value is stored in +.Fa flags . +.It Er ENXIO +Hangup received on the +.Fa fildes +argument of the +.Fn ioctl +call or the +.Fa fildes +member of the +.Vt strfdinsert +structure. +.It Er ERANGE +The +.Fa len +field for the buffer specified through +.Vt databuf +does not fall within the range specified by the maximum and minimum packet +sizes of the topmost stream module; or the +.Fa len +member for the buffer specified through +.Vt databuf +is larger than the maximum configured size of the data part of a message; or the +.Fa len +member for the buffer specified through +.Vt ctlbuf is larger than the maximum configured size of the control part of a message. -.RE - -\fBI_FDINSERT\fR can also fail if an error message was received by the stream -head of the stream corresponding to the \fBfildes\fR member of the -\fBstrfdinsert\fR structure. In this case, \fBerrno\fR will be set to the value -in the message. -.RE - -.sp -.ne 2 -.na -\fB\fBI_STR\fR\fR -.ad -.RS 15n -Constructs an internal \fBSTREAMS\fR ioctl message from the data pointed to by -\fIarg\fR, and sends that message downstream. -.sp -This mechanism is provided to send user \fBioctl\fR requests to downstream -modules and drivers. It allows information to be sent with the \fBioctl\fR, and -will return to the user any information sent upstream by the downstream -recipient. \fBI_STR\fR blocks until the system responds with either a positive -or negative acknowledgement message, or until the request times out after some -period of time. If the request times out, it fails with \fBerrno\fR set to -\fBETIME\fR. -.sp -To send requests downstream, \fIarg\fR must point to a \fBstrioctl\fR structure -which contains the following members: -.sp -.in +2 -.nf +.El +.Pp +.Dv I_FDINSERT +can also fail if an error message was received by the stream +head of the stream corresponding to the +.Fa fildes +member of the +.Vt strfdinsert +structure. +In this case, +.Va errno +will be set to the value in the message. +.It Dv I_STR +Constructs an internal +.Sy STREAMS +ioctl message from the data pointed to by +.Fa arg , +and sends that message downstream. +.Pp +This mechanism is provided to send user +.Fn ioctl +requests to downstream modules and drivers. +It allows information to be sent with the +.Fn ioctl , +and will return to the user any information sent upstream by the downstream +recipient. +.Dv I_STR +blocks until the system responds with either a positive or negative +acknowledgement message, or until the request times out after some period of +time. +If the request times out, it fails with +.Va errno +set to +.Er ETIME . +.Pp +To send requests downstream, +.Fa arg +must point to a +.Vt strioctl +structure which contains the following members: +.Bd -literal -offset 2n int ic_cmd; int ic_timout; int ic_len; char *ic_dp; -.fi -.in -2 - -\fBic_cmd\fR is the internal \fBioctl\fR command intended for a downstream -module or driver and \fBic_timout\fR is the number of seconds (-1 = infinite, 0 -= use default, >0 = as specified) an \fBI_STR\fR request will wait for -acknowledgement before timing out. \fBic_len\fR is the number of bytes in the -data argument and \fBic_dp\fR is a pointer to the data argument. The -\fBic_len\fR field has two uses: on input, it contains the length of the data +.Ed +.Pp +.Fa ic_cmd +is the internal +.Fn ioctl +command intended for a downstream module or driver and +.Fa ic_timout +is the number of seconds (-1 = infinite, 0 = use default, >0 = as specified) an +.Dv I_STR +request will wait for acknowledgement before timing out. +.Fa ic_len +is the number of bytes in the data argument and +.Fa ic_dp +is a pointer to the data argument. +The +.Fa ic_len +field has two uses: on input, it contains the length of the data argument passed in, and on return from the command, it contains the number of -bytes being returned to the user (the buffer pointed to by \fBic_dp\fR should -be large enough to contain the maximum amount of data that any module or the -driver in the stream can return). -.sp -At most one \fBI_STR\fR can be active on a stream. Further \fBI_STR\fR calls -will block until the active \fBI_STR\fR completes via a positive or negative -acknowlegment, a timeout, or an error condition at the stream head. By setting -the \fBic_timout\fR field to 0, the user is requesting STREAMS to provide -the \fBDEFAULT\fR timeout. The default timeout is specific to the STREAMS +bytes being returned to the user (the buffer pointed to by +.Fa ic_dp +should be large enough to contain the maximum amount of data that any module or +the driver in the stream can return). +.Pp +At most one +.Dv I_STR +can be active on a stream. +Further +.Dv I_STR +calls +will block until the active +.Dv I_STR +completes via a positive or negative +acknowlegment, a timeout, or an error condition at the stream head. +By setting the +.Fa ic_timout +field to 0, the user is requesting STREAMS to provide +the +.Sy DEFAULT +timeout. +The default timeout is specific to the STREAMS implementation and may vary depending on which release of Solaris you are -using. For Solaris 8 (and earlier versions), the default timeout is fifteen -seconds. The \fBO_NDELAY\fR and \fBO_NONBLOCK\fR (see \fBopen\fR(2)) flags have -no effect on this call. -.sp -The stream head will convert the information pointed to by the \fBstrioctl\fR -structure to an internal \fBioctl\fR command message and send it downstream. On -failure, \fBerrno\fR is set to one of the following values: -.sp -.ne 2 -.na -\fB\fBENOSR\fR\fR -.ad -.RS 10n -Unable to allocate buffers for the \fBioctl\fR message due to insufficient -STREAMS memory resources. -.RE - -.sp -.ne 2 -.na -\fB\fBEFAULT\fR\fR -.ad -.RS 10n -Either \fIarg\fR points outside the allocated address space, or the buffer area -specified by \fBic_dp\fR and \fBic_len\fR (separately for data sent and data -returned) is outside the allocated address space. -.RE - -.sp -.ne 2 -.na -\fB\fBEINVAL\fR\fR -.ad -.RS 10n -\fBic_len\fR is less than 0 or \fBic_len\fR is larger than the maximum -configured size of the data part of a message or \fBic_timout\fR is less than --1. -.RE - -.sp -.ne 2 -.na -\fB\fBENXIO\fR\fR -.ad -.RS 10n -Hangup received on \fIfildes\fR. -.RE - -.sp -.ne 2 -.na -\fB\fBETIME\fR\fR -.ad -.RS 10n -A downstream \fBioctl\fR timed out before acknowledgement was received. -.RE - -An \fBI_STR\fR can also fail while waiting for an acknowledgement if a message -indicating an error or a hangup is received at the stream head. In addition, an +using. +For Solaris 8 (and earlier versions), the default timeout is fifteen +seconds. +The +.Dv O_NDELAY +and +.Dv O_NONBLOCK +(see +.Xr open 2 ) +flags have no effect on this call. +.Pp +The stream head will convert the information pointed to by the +.Vt strioctl +structure to an internal +.Fn ioctl +command message and send it downstream. +On failure, +.Va errno +is set to one of the following values: +.Bl -tag -width EFAULT +.It Er ENOSR +Unable to allocate buffers for the +.Fn ioctl +message due to insufficient STREAMS memory resources. +.It Er EFAULT +Either +.Fa arg +points outside the allocated address space, or the buffer area +specified by +.Fa ic_dp +and +.Fa ic_len +(separately for data sent and data returned) is outside the allocated address +space. +.It Er EINVAL +.Fa ic_len +is less than 0 or +.Fa ic_len +is larger than the maximum configured size of the data part of a message or +.Fa ic_timout +is less than \(mi1. +.It Er ENXIO +Hangup received on +.Fa fildes . +.It Er ETIME +A downstream +.Fn ioctl +timed out before acknowledgement was received. +.El +.Pp +An +.Dv I_STR +can also fail while waiting for an acknowledgement if a message +indicating an error or a hangup is received at the stream head. +In addition, an error code can be returned in the positive or negative acknowledgement message, -in the event the ioctl command sent downstream fails. For these cases, -\fBI_STR\fR will fail with \fBerrno\fR set to the value in the message. -.RE - -.sp -.ne 2 -.na -\fB\fBI_SWROPT\fR\fR -.ad -.RS 15n -Sets the write mode using the value of the argument \fIarg\fR. Legal bit -settings for \fIarg\fR are: -.sp -.ne 2 -.na -\fB\fBSNDZERO\fR\fR -.ad -.RS 11n +in the event the ioctl command sent downstream fails. +For these cases, +.Dv I_STR +will fail with +.Va errno +set to the value in the message. +.It Dv I_SWROPT +Sets the write mode using the value of the argument +.Fa arg . +Legal bit settings for +.Fa arg +are: +.Bl -tag -width SNDZERO +.It Dv SNDZERO Send a zero-length message downstream when a write of 0 bytes occurs. -.RE - +.El +.Pp To not send a zero-length message when a write of 0 bytes occurs, this bit must -not be set in \fIarg\fR. -.sp -On failure, \fBerrno\fR may be set to the following value: -.sp -.ne 2 -.na -\fB\fBEINVAL\fR\fR -.ad -.RS 10n -\fIarg\fR is not the above legal value. -.RE - -.RE - -.sp -.ne 2 -.na -\fB\fBI_GWROPT\fR\fR -.ad -.RS 15n -Returns the current write mode setting, as described above, in the \fBint\fR -that is pointed to by the argument \fIarg\fR. -.RE - -.sp -.ne 2 -.na -\fB\fBI_SENDFD\fR\fR -.ad -.RS 15n -Requests the stream associated with \fIfildes\fR to send a message, containing -a file pointer, to the stream head at the other end of a stream pipe. The file -pointer corresponds to \fIarg\fR, which must be an open file descriptor. -.sp -\fBI_SENDFD\fR converts \fIarg\fR into the corresponding system file pointer. -It allocates a message block and inserts the file pointer in the block. The -user id and group id associated with the sending process are also inserted. -This message is placed directly on the read queue (see \fBIntro\fR(3)) of the -stream head at the other end of the stream pipe to which it is connected. On -failure, \fBerrno\fR is set to one of the following values: -.sp -.ne 2 -.na -\fB\fBEAGAIN\fR\fR -.ad -.RS 10n +not be set in +.Fa arg . +.Pp +On failure, +.Va errno +may be set to the following value: +.Bl -tag -width EINVAL +.It Sy EINVAL +.Fa arg +is not the above legal value. +.El +.It Dv I_GWROPT +Returns the current write mode setting, as described above, in the +.Vt int +that is pointed to by the argument +.Fa arg . +.It Dv I_SENDFD +Requests the stream associated with +.Fa fildes +to send a message, containing +a file pointer, to the stream head at the other end of a stream pipe. +The file +pointer corresponds to +.Fa arg , +which must be an open file descriptor. +.Pp +.Dv I_SENDFD +converts +.Fa arg +into the corresponding system file pointer. +It allocates a message block and inserts the file pointer in the block. +The user id and group id associated with the sending process are also inserted. +This message is placed directly on the read queue (see +.Xr Intro 3 ) +of the stream head at the other end of the stream pipe to which it is connected. +On failure, +.Va errno +is set to one of the following values: +.Bl -tag -width EAGAIN +.It Er EAGAIN The sending stream is unable to allocate a message block to contain the file pointer. -.RE - -.sp -.ne 2 -.na -\fB\fBEAGAIN\fR\fR -.ad -.RS 10n +.It Er EAGAIN The read queue of the receiving stream head is full and cannot accept the -message sent by \fBI_SENDFD.\fR -.RE - -.sp -.ne 2 -.na -\fB\fBEBADF\fR\fR -.ad -.RS 10n -\fIarg\fR is not a valid, open file descriptor. -.RE - -.sp -.ne 2 -.na -\fB\fBEINVAL\fR\fR -.ad -.RS 10n -\fIfildes\fR is not connected to a stream pipe. -.RE - -.sp -.ne 2 -.na -\fB\fBENXIO\fR\fR -.ad -.RS 10n -Hangup received on \fIfildes\fR. -.RE - -.RE - -.sp -.ne 2 -.na -\fB\fBI_RECVFD\fR\fR -.ad -.RS 15n +message sent by +.Dv I_SENDFD . +.It Er EBADF +.Fa arg +is not a valid, open file descriptor. +.It Er EINVAL +.Va fildes +is not connected to a stream pipe. +.It Er ENXIO +Hangup received on +.Fa fildes . +.El +.It Dv I_RECVFD Retrieves the file descriptor associated with the message sent by an -\fBI_SENDFD\fR \fBioctl\fR over a stream pipe. \fIarg\fR is a pointer to a data -buffer large enough to hold an \fBstrrecvfd\fR data structure containing the -following members: -.sp -.in +2 -.nf -int fd; -uid_t uid; -gid_t gid; -.fi -.in -2 - -\fBfd\fR is an integer file descriptor. \fBuid\fR and \fBgid\fR are the user id -and group id, respectively, of the sending stream. -.sp -If \fBO_NDELAY\fR and \fBO_NONBLOCK\fR are clear (see \fBopen\fR(2)), -\fBI_RECVFD\fR will block until a message is present at the stream head. If -\fBO_NDELAY\fR or \fBO_NONBLOCK\fR is set, \fBI_RECVFD\fR will fail with -\fBerrno\fR set to \fBEAGAIN\fR if no message is present at the stream head. -.sp -If the message at the stream head is a message sent by an \fBI_SENDFD\fR, a new +.Dv I_SENDFD +.Fn ioctl +over a stream pipe. +.Fa arg +is a pointer to a data buffer large enough to hold an +.Vt strrecvfd +data structure containing the following members: +.Bd -literal -offset 2n +int fd; +uid_t uid; +gid_t gid; +.Ed +.Pp +.Fa fd +is an integer file descriptor. +.Fa uid +and +.Fa gid +are the user id and group id, respectively, of the sending stream. +.Pp +If +.Dv O_NDELAY +and +.Dv O_NONBLOCK +are clear (see +.Xr open 2 ) , +.Dv I_RECVFD +will block until a message is present at the stream head. +If +.Dv O_NDELAY +or +.Dv O_NONBLOCK +is set, +.Dv I_RECVFD +will fail with +.Va errno +set to +.Er EAGAIN +if no message is present at the stream head. +.Pp +If the message at the stream head is a message sent by an +.Dv I_SENDFD , +a new user file descriptor is allocated for the file pointer contained in the -message. The new file descriptor is placed in the \fBfd\fR field of the -\fBstrrecvfd\fR structure. The structure is copied into the user data buffer -pointed to by \fIarg\fR. On failure, \fBerrno\fR is set to one of the following -values: -.sp -.ne 2 -.na -\fB\fBEAGAIN\fR\fR -.ad -.RS 13n -A message is not present at the stream head read queue, and the \fBO_NDELAY\fR -or \fBO_NONBLOCK\fR flag is set. -.RE - -.sp -.ne 2 -.na -\fB\fBEBADMSG\fR\fR -.ad -.RS 13n +message. +The new file descriptor is placed in the +.Fa fd +field of the +.Vt strrecvfd +structure. +The structure is copied into the user data buffer pointed to by +.Fa arg . +On failure, +.Va errno +is set to one of the following values: +.Bl -tag -width EOVERFLOW +.It Er EAGAIN +A message is not present at the stream head read queue, and the +.Dv O_NDELAY +or +.Dv O_NONBLOCK +flag is set. +.It Er EBADMSG The message at the stream head read queue is not a message containing a passed file descriptor. -.RE - -.sp -.ne 2 -.na -\fB\fBEFAULT\fR\fR -.ad -.RS 13n -\fIarg\fR points outside the allocated address space. -.RE - -.sp -.ne 2 -.na -\fB\fBEMFILE\fR\fR -.ad -.RS 13n -\fBNOFILES\fR file descriptors are currently open. -.RE - -.sp -.ne 2 -.na -\fB\fBENXIO\fR\fR -.ad -.RS 13n -Hangup received on \fIfildes\fR. -.RE - -.sp -.ne 2 -.na -\fB\fBEOVERFLOW\fR\fR -.ad -.RS 13n -\fIuid\fR or \fIgid\fR is too large to be stored in the structure pointed to by -\fIarg\fR. -.RE - -.RE - -.sp -.ne 2 -.na -\fB\fBI_LIST\fR\fR -.ad -.RS 15n +.It Er EFAULT +.Fa arg +points outside the allocated address space. +.It Er EMFILE +.Dv NOFILES +file descriptors are currently open. +.It Er ENXIO +Hangup received on +.Fa fildes . +.It Er EOVERFLOW +.Fa uid +or +.Fa gid +is too large to be stored in the structure pointed to by +.Fa arg . +.El +.It Dv I_LIST Allows the user to list all the module names on the stream, up to and including -the topmost driver name. If \fIarg\fR is \fINULL\fR, the return value is the -number of modules, including the driver, that are on the stream pointed to by -\fIfildes\fR. This allows the user to allocate enough space for the module -names. If \fIarg\fR is non-null, it should point to an \fBstr_list\fR structure -that has the following members: -.sp -.in +2 -.nf +the topmost driver name. +If +.Fa arg +is +.Dv NULL , +the return value is the number of modules, including the driver, that are on +the stream pointed to by +.Fa fildes . +This allows the user to allocate enough space for the module +names. +If +.Fa arg +is non-null, it should point to an +.Vt str_list +structure that has the following members: +.Bd -literal -offset 2n int sl_nmods; struct str_mlist *sl_modlist; -.fi -.in -2 - -The \fBstr_mlist\fR structure has the following member: -.sp -.in +2 -.nf +.Ed +.Pp +The +.Vt str_mlist +structure has the following member: +.Bd -literal -offset 2n char l_name[FMNAMESZ+1]; -.fi -.in -2 - -The \fBsl_nmods\fR member indicates the number of entries the process has -allocated in the array. Upon return, the \fBsl_modlist\fR member of the -\fBstr_list\fR structure contains the list of module names, and the number of -entries that have been filled into the \fBsl_modlist\fR array is found in the -\fBsl_nmods\fR member (the number includes the number of modules including the -driver). The return value from \fBioctl()\fR is 0. The entries are filled in +.Ed +.Pp +The +.Fa sl_nmods +member indicates the number of entries the process has allocated in the array. +Upon return, the +.Fa sl_modlist +member of the +.Vt str_list +structure contains the list of module names, and the number of +entries that have been filled into the +.Fa sl_modlist +array is found in the +.Fa sl_nmods +member (the number includes the number of modules including the driver). +The return value from +.Fn ioctl +is 0. +The entries are filled in starting at the top of the stream and continuing downstream until either the end of the stream is reached, or the number of requested modules -(\fBsl_nmods\fR) is satisfied. On failure, \fBerrno\fR may be set to one of the -following values: -.sp -.ne 2 -.na -\fB\fBEINVAL\fR\fR -.ad -.RS 10n -The \fBsl_nmods\fR member is less than 1. -.RE - -.sp -.ne 2 -.na -\fB\fBEAGAIN\fR\fR -.ad -.RS 10n +.Pq Fa sl_nmods +is satisfied. +On failure, +.Va errno +may be set to one of the following values: +.Bl -tag -width EINVAL +.It Er EINVAL +The +.Fa sl_nmods +member is less than 1. +.It Er EAGAIN Unable to allocate buffers -.RE - -.RE - -.sp -.ne 2 -.na -\fB\fBI_ATMARK\fR\fR -.ad -.RS 15n +.El +.It Dv I_ATMARK Allows the user to see if the current message on the stream head read queue is -``marked'' by some module downstream. \fIarg\fR determines how the checking is +.Dq marked +by some module downstream. +.Fa arg +determines how the checking is done when there may be multiple marked messages on the stream head read queue. It may take the following values: -.sp -.ne 2 -.na -\fB\fBANYMARK\fR\fR -.ad -.RS 12n +.Bl -tag -width LASTMARK +.It Dv ANYMARK Check if the message is marked. -.RE - -.sp -.ne 2 -.na -\fB\fBLASTMARK\fR\fR -.ad -.RS 12n +.It Dv LASTMARK Check if the message is the last one marked on the queue. -.RE - -The return value is \fB1\fR if the mark condition is satisfied and \fB0\fR -otherwise. On failure, \fBerrno\fR is set to the following value: -.sp -.ne 2 -.na -\fB\fBEINVAL\fR\fR -.ad -.RS 10n -Invalid \fIarg\fR value. -.RE - -.RE - -.sp -.ne 2 -.na -\fB\fBI_CKBAND\fR\fR -.ad -.RS 15n +.El +.Pp +The return value is +.Sy 1 +if the mark condition is satisfied and +.Sy 0 +otherwise. +On failure, +.Va errno +is set to the following value: +.Bl -tag -width EINVAL +.It Er EINVAL +Invalid +.Fa arg +value. +.El +.It Dv I_CKBAND Check if the message of a given priority band exists on the stream head read -queue. This returns \fB1\fR if a message of a given priority exists, \fB0\fR if -not, or \fB\(mi1\fR on error. \fIarg\fR should be an integer containing the -value of the priority band in question. On failure, \fBerrno\fR is set to the -following value: -.sp -.ne 2 -.na -\fB\fBEINVAL\fR\fR -.ad -.RS 10n -Invalid \fIarg\fR value. -.RE - -.RE - -.sp -.ne 2 -.na -\fB\fBI_GETBAND\fR\fR -.ad -.RS 15n +queue. +This returns +.Sy 1 +if a message of a given priority exists, +.Sy 0 +if not, or +.Sy \(mi1 +on error. +.Fa arg +should be an integer containing the value of the priority band in question. +On failure, +.Va errno +is set to the following value: +.Bl -tag -width EINVAL +.It Er EINVAL +Invalid +.Fa arg +value. +.El +.It Dv I_GETBAND Returns the priority band of the first message on the stream head read queue in -the integer referenced by \fIarg\fR. On failure, \fBerrno\fR is set to the -following value: -.sp -.ne 2 -.na -\fB\fBENODATA\fR\fR -.ad -.RS 11n +the integer referenced by +.Fa arg . +On failure, +.Va errno +is set to the following value: +.Bl -tag -width ENODATA +.It Er ENODATA No message on the stream head read queue. -.RE - -.RE - -.sp -.ne 2 -.na -\fB\fBI_CANPUT\fR\fR -.ad -.RS 15n -Check if a certain band is writable. \fIarg\fR is set to the priority band in -question. The return value is \fB0\fR if the priority band \fIarg\fR is flow -controlled, \fB1\fR if the band is writable, or \fB\(mi1\fR on error. On -failure, \fBerrno\fR is set to the following value: -.sp -.ne 2 -.na -\fB\fBEINVAL\fR\fR -.ad -.RS 10n -Invalid \fIarg\fR value. -.RE - -.RE - -.sp -.ne 2 -.na -\fB\fBI_SETCLTIME\fR\fR -.ad -.RS 15n +.El +.It Dv I_CANPUT +Check if a certain band is writable. +.Fa arg +is set to the priority band in question. +The return value is +.Sy 0 +if the priority band +.Fa arg +is flow controlled, +.Sy 1 +if the band is writable, or +.Sy \(mi1 +on error. +On failure, +.Va errno +is set to the following value: +.Bl -tag -width EINVAL +.It Sy EINVAL +Invalid +.Va arg +value. +.El +.It Dv I_SETCLTIME Allows the user to set the time the stream head will delay when a stream is -closing and there are data on the write queues. Before closing each module and -driver, the stream head will delay for the specified amount of time to allow -the data to drain. Note, however, that the module or driver may itself delay in -its close routine; this delay is independent of the stream head's delay and is -not settable. If, after the delay, data are still present, data will be -flushed. \fIarg\fR is a pointer to an integer containing the number of +closing and there are data on the write queues. +Before closing each module and driver, the stream head will delay for the +specified amount of time to allow the data to drain. +Note, however, that the module or driver may itself delay in its close routine; +this delay is independent of the stream head's delay and is not settable. +If, after the delay, data are still present, data will be flushed. +.Fa arg +is a pointer to an integer containing the number of milliseconds to delay, rounded up to the nearest legal value on the system. -The default is fifteen seconds. On failure, \fBerrno\fR is set to the following -value: -.sp -.ne 2 -.na -\fB\fBEINVAL\fR\fR -.ad -.RS 10n -Invalid \fIarg\fR value. -.RE - -.RE - -.sp -.ne 2 -.na -\fB\fBI_GETCLTIME\fR\fR -.ad -.RS 15n -Returns the close time delay in the integer pointed by \fIarg\fR. -.RE - -.sp -.ne 2 -.na -\fB\fBI_SERROPT\fR\fR -.ad -.RS 15n -Sets the error mode using the value of the argument \fIarg\fR. -.sp +The default is fifteen seconds. +On failure, +.Va errno +is set to the following value: +.Bl -tag -width EINVAL +.It Er EINVAL +Invalid +.Fa arg +value. +.El +.It Dv I_GETCLTIME +Returns the close time delay in the integer pointed by +.Va arg . +.It Dv I_SERROPT +Sets the error mode using the value of the argument +.Fa arg . +.Pp Normally stream head errors are persistent; once they are set due to an -\fBM_ERROR\fR or \fBM_HANGUP\fR, the error condition will remain until the -stream is closed. This option can be used to set the stream head into -non-persistent error mode i.e. once the error has been returned in response to -a \fBread\fR(2), \fBgetmsg\fR(2), \fBioctl\fR(2), \fBwrite\fR(2), or -\fBputmsg\fR(2) call the error condition will be cleared. The error mode can be -controlled independently for read and write side errors. Legal \fIarg\fR values +.Dv M_ERROR +or +.Dv M_HANGUP , +the error condition will remain until the stream is closed. +This option can be used to set the stream head into +non-persistent error mode i\.e\. once the error has been returned in response +to a +.Xr read 2 , +.Xr getmsg 2 , +.Xr ioctl 2 , +.Xr write 2 , +or +.Xr putmsg 2 +call the error condition will be cleared. +The error mode can be controlled independently for read and write side errors. +Legal +.Fa arg +values are either none or one of: -.sp -.ne 2 -.na -\fB\fBRERRNORM\fR\fR -.ad -.RS 18n +.Bl -tag -width RERRNONPERSIST +.It Dv RERRNORM Persistent read errors, the default. -.RE - -.sp -.ne 2 -.na -\fB\fBRERRNONPERSIST\fR\fR -.ad -.RS 18n +.It Dv RERRNONPERSIST Non-persistent read errors. -.RE - -\fBOR'ed\fR with either none or one of: -.sp -.ne 2 -.na -\fB\fBWERRNORM\fR\fR -.ad -.RS 18n +.El +.Pp +.Sy OR Ns 'ed +with either none or one of: +.Bl -tag -width WERRNONPERSIST +.It Dv WERRNORM Persistent write errors, the default. -.RE - -.sp -.ne 2 -.na -\fB\fBWERRNONPERSIST\fR\fR -.ad -.RS 18n +.It Dv WERRNONPERSIST Non-persistent write errors. -.sp -When no value is specified e.g. for the read side error behavior then the +.El +.Pp +When no value is specified e\.g\. for the read side error behavior then the behavior for that side will be left unchanged. -.RE - -On failure, \fBerrno\fR is set to the following value: -.sp -.ne 2 -.na -\fB\fBEINVAL\fR\fR -.ad -.RS 10n -\fIarg\fR is not one of the above legal values. -.RE - -.RE - -.sp -.ne 2 -.na -\fB\fBI_GERROPT\fR\fR -.ad -.RS 15n -Returns the current error mode setting in an \fBint\fR pointed to by the -argument \fIarg\fR. Error modes are described above for \fBI_SERROPT\fR. On -failure,\fBerrno\fR is set to the following value: -.sp -.ne 2 -.na -\fB\fBEFAULT\fR\fR -.ad -.RS 10n -\fIarg\fR points outside the allocated address space. -.RE - -.RE - -.sp -.LP +.Pp +On failure, +.Va errno +is set to the following value: +.Bl -tag -width EINVAL +.It Er EINVAL +.Va arg +is not one of the above legal values. +.El +.It Dv I_GERROPT +Returns the current error mode setting in an +.Vt int +pointed to by the argument +.Fa arg . +Error modes are described above for +.Dv I_SERROPT . +On failure, +.Va errno +is set to the following value: +.Bl -tag -width EFAULT +.It Sy EFAULT +.Fa arg +points outside the allocated address space. +.El +.El +.Pp The following four commands are used for connecting and disconnecting multiplexed STREAMS configurations. -.sp -.ne 2 -.na -\fB\fBI_LINK\fR\fR -.ad -.RS 13n -Connects two streams, where \fIfildes\fR is the file descriptor of the stream -connected to the multiplexing driver, and \fIarg\fR is the file descriptor of -the stream connected to another driver. The stream designated by \fIarg\fR gets -connected below the multiplexing driver. \fBI_LINK\fR requires the multiplexing +.Bl -tag -width I_PUNLINK +.It Dv I_LINK +Connects two streams, where +.Fa fildes +is the file descriptor of the stream +connected to the multiplexing driver, and +.Fa arg +is the file descriptor of the stream connected to another driver. +The stream designated by +.Va arg +gets +connected below the multiplexing driver. +.Dv I_LINK +requires the multiplexing driver to send an acknowledgement message to the stream head regarding the -linking operation. This call returns a multiplexor ID number (an identifier -used to disconnect the multiplexor, see \fBI_UNLINK\fR) on success, and -1 on -failure. On failure, \fBerrno\fR is set to one of the following values: -.sp -.ne 2 -.na -\fB\fBENXIO\fR\fR -.ad -.RS 10n -Hangup received on \fIfildes\fR. -.RE - -.sp -.ne 2 -.na -\fB\fBETIME\fR\fR -.ad -.RS 10n +linking operation. +This call returns a multiplexor ID number (an identifier +used to disconnect the multiplexor, see +.Dv I_UNLINK ) +on success, and \(mi1 on failure. +On failure, +.Va errno +is set to one of the following values: +.Bl -tag -width EAGAIN +.It Er ENXIO +Hangup received on +.Va fildes . +.It Er ETIME Time out before acknowledgement message was received at stream head. -.RE - -.sp -.ne 2 -.na -\fB\fBEAGAIN\fR\fR -.ad -.RS 10n -Temporarily unable to allocate storage to perform the \fBI_LINK.\fR -.RE - -.sp -.ne 2 -.na -\fB\fBENOSR\fR\fR -.ad -.RS 10n -Unable to allocate storage to perform the \fBI_LINK\fR due to insufficient -\fBSTREAMS\fR memory resources. -.RE - -.sp -.ne 2 -.na -\fB\fBEBADF\fR\fR -.ad -.RS 10n -\fIarg\fR is not a valid, open file descriptor. -.RE - -.sp -.ne 2 -.na -\fB\fBEINVAL\fR\fR -.ad -.RS 10n -\fIfildes\fR stream does not support multiplexing. -.RE - -.sp -.ne 2 -.na -\fB\fBEINVAL\fR\fR -.ad -.RS 10n -\fIarg\fR is not a stream, or is already linked under a multiplexor. -.RE - -.sp -.ne 2 -.na -\fB\fBEINVAL\fR\fR -.ad -.RS 10n -The specified link operation would cause a ``cycle'' in the resulting -configuration; that is, a driver would be linked into the multiplexing -configuration in more than one place. -.RE - -.sp -.ne 2 -.na -\fB\fBEINVAL\fR\fR -.ad -.RS 10n -\fIfildes\fR is the file descriptor of a pipe or FIFO. -.RE - -.sp -.ne 2 -.na -\fB\fBEINVAL\fR\fR -.ad -.RS 10n -Either the upper or lower stream has a major number >= the maximum major number -on the system. -.RE - -An \fBI_LINK\fR can also fail while waiting for the multiplexing driver to +.It Er EAGAIN +Temporarily unable to allocate storage to perform the +.Dv I_LINK . +.It Er ENOSR +Unable to allocate storage to perform the +.Dv I_LINK +due to insufficient +.Sy STREAMS +memory resources. +.It Er EBADF +.Va arg +is not a valid, open file descriptor. +.It Er EINVAL +.Va fildes +stream does not support multiplexing. +.It Er EINVAL +is not a stream, or is already linked under a multiplexor. +.It Er EINVAL +The specified link operation would cause a +.Dq cycle +in the resulting configuration; that is, a driver would be linked into the +multiplexing configuration in more than one place. +.It Er EINVAL +.Va fildes +is the file descriptor of a pipe or FIFO. +.It Er EINVAL +Either the upper or lower stream has a major number \(>= the maximum major +number on the system. +.El +.Pp +An +.Dv I_LINK +can also fail while waiting for the multiplexing driver to acknowledge the link request, if a message indicating an error or a hangup is -received at the stream head of \fIfildes\fR. In addition, an error code can be -returned in the positive or negative acknowledgement message. For these cases, -\fBI_LINK\fR will fail with \fBerrno\fR set to the value in the message. -.RE - -.sp -.ne 2 -.na -\fB\fBI_UNLINK\fR\fR -.ad -.RS 13n -Disconnects the two streams specified by \fIfildes\fR and \fIarg\fR. -\fIfildes\fR is the file descriptor of the stream connected to the multiplexing -driver. \fIarg\fR is the multiplexor ID number that was returned by the -\fBI_LINK\fR. If \fIarg\fR is -1, then all streams that were linked to -\fIfildes\fR are disconnected. As in \fBI_LINK\fR, this command requires the -multiplexing driver to acknowledge the unlink. On failure, \fBerrno\fR is set -to one of the following values: -.sp -.ne 2 -.na -\fB\fBENXIO\fR\fR -.ad -.RS 10n -Hangup received on \fIfildes\fR. -.RE - -.sp -.ne 2 -.na -\fB\fBETIME\fR\fR -.ad -.RS 10n +received at the stream head of +.Fa fildes . +In addition, an error code can be +returned in the positive or negative acknowledgement message. +For these cases, +.Dv I_LINK +will fail with +.Va errno +set to the value in the message. +.It Dv I_UNLINK +Disconnects the two streams specified by +.Fa fildes +and +.Fa arg . +.Fa fildes +is the file descriptor of the stream connected to the multiplexing +driver. +.Fa arg +is the multiplexor ID number that was returned by the +.Dv I_LINK . +If +.Fa arg +is \(mi1, then all streams that were linked to +.Fa fildes +are disconnected. +As in +.Dv I_LINK , +this command requires the multiplexing driver to acknowledge the unlink. +On failure, +.Va errno +is set to one of the following values: +.Bl -tag -width EINVAL +.It Er ENXIO +Hangup received on +.Va fildes . +.It Er ETIME Time out before acknowledgement message was received at stream head. -.RE - -.sp -.ne 2 -.na -\fB\fBENOSR\fR\fR -.ad -.RS 10n -Unable to allocate storage to perform the \fBI_UNLINK\fR due to insufficient +.It Er ENOSR +Unable to allocate storage to perform the +.Dv I_UNLINK +due to insufficient STREAMS memory resources. -.RE - -.sp -.ne 2 -.na -\fB\fBEINVAL\fR\fR -.ad -.RS 10n -\fIarg\fR is an invalid multiplexor ID number or \fIfildes\fR is not the stream -on which the \fBI_LINK\fR that returned \fIarg\fR was performed. -.RE - -.sp -.ne 2 -.na -\fB\fBEINVAL\fR\fR -.ad -.RS 10n -\fIfildes\fR is the file descriptor of a pipe or FIFO. -.RE - -An \fBI_UNLINK\fR can also fail while waiting for the multiplexing driver to +.It Er EINVAL +.Fa arg +is an invalid multiplexor ID number or +.Fa fildes +is not the stream on which the +.Dv I_LINK +that returned +.Fa arg +was performed. +.It Er EINVAL +.Fa fildes +is the file descriptor of a pipe or FIFO. +.El +.Pp +An +.Dv I_UNLINK +can also fail while waiting for the multiplexing driver to acknowledge the link request, if a message indicating an error or a hangup is -received at the stream head of \fIfildes\fR. In addition, an error code can be -returned in the positive or negative acknowledgement message. For these cases, -\fBI_UNLINK\fR will fail with \fBerrno\fR set to the value in the message. -.RE - -.sp -.ne 2 -.na -\fB\fBI_PLINK\fR\fR -.ad -.RS 13n -Connects two streams, where \fIfildes\fR is the file descriptor of the stream -connected to the multiplexing driver, and \fIarg\fR is the file descriptor of -the stream connected to another driver. The stream designated by \fIarg\fR gets -connected via a persistent link below the multiplexing driver. \fBI_PLINK\fR +received at the stream head of +.Fa fildes . +In addition, an error code can be +returned in the positive or negative acknowledgement message. +For these cases, +.Dv I_UNLINK +will fail with +.Va errno +set to the value in the message. +.It Dv I_PLINK +Connects two streams, where +.Fa fildes +is the file descriptor of the stream +connected to the multiplexing driver, and +.Fa arg +is the file descriptor of +the stream connected to another driver. +The stream designated by +.Fa arg +gets +connected via a persistent link below the multiplexing driver. +.Dv I_PLINK requires the multiplexing driver to send an acknowledgement message to the -stream head regarding the linking operation. This call creates a persistent -link that continues to exist even if the file descriptor \fIfildes\fR -associated with the upper stream to the multiplexing driver is closed. This +stream head regarding the linking operation. +This call creates a persistent +link that continues to exist even if the file descriptor +.Fa fildes +associated with the upper stream to the multiplexing driver is closed. +This call returns a multiplexor ID number (an identifier that may be used to -disconnect the multiplexor, see \fBI_PUNLINK\fR) on success, and -1 on failure. -On failure, \fBerrno\fR is set to one of the following values: -.sp -.ne 2 -.na -\fB\fBENXIO\fR\fR -.ad -.RS 10n -Hangup received on \fIfildes\fR. -.RE - -.sp -.ne 2 -.na -\fB\fBETIME\fR\fR -.ad -.RS 10n +disconnect the multiplexor, see +.Dv I_PUNLINK ) +on success, and \(mi1 on failure. +On failure, +.Va errno +is set to one of the following values: +.Bl -tag -width EAGAIN +.It Er ENXIO +Hangup received on +.Fa fildes . +.It Er ETIME Time out before acknowledgement message was received at the stream head. -.RE - -.sp -.ne 2 -.na -\fB\fBEAGAIN\fR\fR -.ad -.RS 10n -Unable to allocate STREAMS storage to perform the \fBI_PLINK.\fR -.RE - -.sp -.ne 2 -.na -\fB\fBEBADF\fR\fR -.ad -.RS 10n -\fIarg\fR is not a valid, open file descriptor. -.RE - -.sp -.ne 2 -.na -\fB\fBEINVAL\fR\fR -.ad -.RS 10n -\fIfildes\fR does not support multiplexing. -.RE - -.sp -.ne 2 -.na -\fB\fBEINVAL\fR\fR -.ad -.RS 10n -\fIarg\fR is not a stream or is already linked under a multiplexor. -.RE - -.sp -.ne 2 -.na -\fB\fBEINVAL\fR\fR -.ad -.RS 10n -The specified link operation would cause a ``cycle'' in the resulting -configuration; that is, if a driver would be linked into the multiplexing -configuration in more than one place. -.RE - -.sp -.ne 2 -.na -\fB\fBEINVAL\fR\fR -.ad -.RS 10n -\fIfildes\fR is the file descriptor of a pipe or FIFO. -.RE - -An \fBI_PLINK\fR can also fail while waiting for the multiplexing driver to +.It Er EAGAIN +Unable to allocate STREAMS storage to perform the +.Dv I_PLINK . +.It Er EBADF +.Va arg +is not a valid, open file descriptor. +.It Er EINVAL +.Va fildes +does not support multiplexing. +.It Er EINVAL +.Va arg +is not a stream or is already linked under a multiplexor. +.It Er EINVAL +The specified link operation would cause a +.Dq cycle +in the resulting configuration; that is, if a driver would be linked into the +multiplexing configuration in more than one place. +.It Er EINVAL +.Fa fildes +is the file descriptor of a pipe or FIFO. +.El +.Pp +An +.Dv I_PLINK +can also fail while waiting for the multiplexing driver to acknowledge the link request, if a message indicating an error on a hangup is -received at the stream head of \fIfildes\fR. In addition, an error code can be -returned in the positive or negative acknowledgement message. For these cases, -\fBI_PLINK\fR will fail with \fBerrno\fR set to the value in the message. -.RE - -.sp -.ne 2 -.na -\fB\fBI_PUNLINK\fR\fR -.ad -.RS 13n -Disconnects the two streams specified by \fIfildes\fR and \fIarg\fR that are -connected with a persistent link. \fIfildes\fR is the file descriptor of the -stream connected to the multiplexing driver. \fIarg\fR is the multiplexor ID -number that was returned by \fBI_PLINK\fR when a stream was linked below the -multiplexing driver. If \fIarg\fR is \fBMUXID_ALL\fR then all streams that are -persistent links to \fIfildes\fR are disconnected. As in \fBI_PLINK,\fR this -command requires the multiplexing driver to acknowledge the unlink. On failure, -\fBerrno\fR is set to one of the following values: -.sp -.ne 2 -.na -\fB\fBENXIO\fR\fR -.ad -.RS 10n -Hangup received on \fIfildes\fR. -.RE - -.sp -.ne 2 -.na -\fB\fBETIME\fR\fR -.ad -.RS 10n +received at the stream head of +.Fa fildes . +In addition, an error code can be +returned in the positive or negative acknowledgement message. +For these cases, +.Dv I_PLINK +will fail with +.Va errno +set to the value in the message. +.It Dv I_PUNLINK +Disconnects the two streams specified by +.Fa fildes +and +.Fa arg +that are +connected with a persistent link. +.Fa fildes +is the file descriptor of the +stream connected to the multiplexing driver. +.Fa arg +is the multiplexor ID number that was returned by +.Dv I_PLINK +when a stream was linked below the multiplexing driver. +If +.Fa arg +is +.Dv MUXID_ALL +then all streams that are persistent links to +.Fa fildes +are disconnected. +As in +.Dv I_PLINK , +this command requires the multiplexing driver to acknowledge the unlink. +On failure, +.Va errno +is set to one of the following values: +.Bl -tag -width EAGAIN +.It Sy ENXIO +Hangup received on +.Fa fildes . +.It Er ETIME Time out before acknowledgement message was received at the stream head. -.RE - -.sp -.ne 2 -.na -\fB\fBEAGAIN\fR\fR -.ad -.RS 10n +.It Er EAGAIN Unable to allocate buffers for the acknowledgement message. -.RE - -.sp -.ne 2 -.na -\fB\fBEINVAL\fR\fR -.ad -.RS 10n +.It Er EINVAL Invalid multiplexor ID number. -.RE - -.sp -.ne 2 -.na -\fB\fBEINVAL\fR\fR -.ad -.RS 10n -\fIfildes\fR is the file descriptor of a pipe or FIFO. -.RE - -An \fBI_PUNLINK\fR can also fail while waiting for the multiplexing driver to +.It Er EINVAL +.Fa fildes +is the file descriptor of a pipe or FIFO. +.El +.Pp +An +.Dv I_PUNLINK +can also fail while waiting for the multiplexing driver to acknowledge the link request if a message indicating an error or a hangup is -received at the stream head of \fIfildes\fR. In addition, an error code can be -returned in the positive or negative acknowledgement message. For these cases, -\fBI_PUNLINK\fR will fail with \fBerrno\fR set to the value in the message. -.RE - -.SH RETURN VALUES -.sp -.LP -Unless specified otherwise above, the return value from \fBioctl()\fR is -\fB0\fR upon success and \fB\(mi1\fR upon failure, with \fIerrno\fR set as -indicated. -.SH SEE ALSO -.sp -.LP -\fBIntro\fR(3), \fBclose\fR(2), \fBfcntl\fR(2), \fBgetmsg\fR(2), -\fBioctl\fR(2), \fBopen\fR(2), \fBpoll\fR(2), \fBputmsg\fR(2), \fBread\fR(2), -\fBwrite\fR(2), \fBsignal\fR(3C), \fBsignal.h\fR(3HEAD), -.sp -.LP -\fISTREAMS Programming Guide\fR +received at the stream head of +.Fa fildes . +In addition, an error code can be +returned in the positive or negative acknowledgement message. +For these cases, +.Dv I_PUNLINK +will fail with +.Va errno +set to the value in the message. +.El +.Sh RETURN VALUES +Unless specified otherwise above, the return value from +.Xr ioctl 2 +is +.Sy 0 +upon success and +.Sy \(mi1 +upon failure, with +.Va errno +set as indicated. +.Sh SEE ALSO +.Xr close 2 , +.Xr fcntl 2 , +.Xr getmsg 2 , +.Xr ioctl 2 , +.Xr open 2 , +.Xr poll 2 , +.Xr putmsg 2 , +.Xr read 2 , +.Xr write 2 , +.Xr Intro 3 , +.Xr signal 3C , +.Xr signal.h 3HEAD +.Pp +.%B STREAMS Programming Guide diff --git a/usr/src/man/man7i/termio.7i b/usr/src/man/man7i/termio.7i index ab95cde52a..c71258de0c 100644 --- a/usr/src/man/man7i/termio.7i +++ b/usr/src/man/man7i/termio.7i @@ -1,2421 +1,2179 @@ -'\" te .\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. -.\" Copyright (c) 2014, Joyent, Inc. All Rights Reserved. +.\" Copyright 2019, Joyent, Inc. All Rights Reserved. .\" Copyright 1989 AT&T -.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. -.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. -.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH TERMIO 7I "Dec 30, 2016" -.SH NAME -termio \- general terminal interface -.SH SYNOPSIS -.LP -.nf -#include <termio.h> - -\fB\fR\fBioctl\fR(\fBint\fR \fIfildes\fR, \fBint\fR \fIrequest\fR, \fBstruct termio *\fR\fIarg\fR); -.fi - -.LP -.nf -\fB\fR\fBioctl\fR(\fBint\fR \fIfildes\fR, \fBint\fR \fIrequest\fR, \fBint\fR \fIarg\fR); -.fi - -.LP -.nf -#include <termios.h> - -\fB\fR\fBioctl\fR(\fBint\fR \fIfildes\fR, \fBint\fR \fIrequest\fR, \fBstruct termios *\fR\fIarg\fR); -.fi - -.SH DESCRIPTION -.LP +.\" The contents of this file are subject to the terms of the +.\" Common Development and Distribution License (the "License"). +.\" You may not use this file except in compliance with the License. +.\" +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE +.\" or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions +.\" and limitations under the License. +.\" +.\" When distributing Covered Code, include this CDDL HEADER in each +.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. +.\" If applicable, add the following below this CDDL HEADER, with the +.\" fields enclosed by brackets "[]" replaced with your own identifying +.\" information: Portions Copyright [yyyy] [name of copyright owner] +.Dd March 17, 2019 +.Dt TERMIO 7I +.Os +.Sh NAME +.Nm termio +.Nd general terminal interface +.Sh SYNOPSIS +.In termio.h +.Fn ioctl "int fildes" "int request" "struct termio *arg" +.Fn ioctl "int fildes" "int request" "int arg" +.Pp +.In termios.h +.Fn ioctl "int fildes" "int request" "struct termios *arg" +.Sh DESCRIPTION This release supports a general interface for asynchronous communications ports -that is hardware-independent. The user interface to this functionality is using -function calls (the preferred interface) described in \fBtermios\fR(3C) or -\fBioctl\fR commands described in this section. This section also discusses the -common features of the terminal subsystem which are relevant with both user +that is hardware-independent. +The user interface to this functionality is using +function calls (the preferred interface) described in +.Xr termios 3C +or +.Fn ioctl +commands described in this section. +This section also discusses the +common features of the terminal subsystem which are relevant with both user interfaces. -.sp -.LP +.Pp When a terminal file is opened, it normally causes the process to wait until a -connection is established. In practice, user programs seldom open terminal +connection is established. +In practice, user programs seldom open terminal files; they are opened by the system and become a user's standard input, -output, and error files. The first terminal file opened by the session leader +output, and error files. +The first terminal file opened by the session leader that is not already associated with a session becomes the controlling terminal -for that session. The controlling terminal plays a special role in handling -quit and interrupt signals, as discussed below. The controlling terminal is -inherited by a child process during a \fBfork\fR(2). A process can break this -association by changing its session using \fBsetsid()\fR (see \fBsetsid\fR(2)). -.sp -.LP +for that session. +The controlling terminal plays a special role in handling +quit and interrupt signals, as discussed below. +The controlling terminal is +inherited by a child process during a +.Xr fork 2 . +A process can break this +association by changing its session using +.Xr setsid 2 . +.Pp A terminal associated with one of these files ordinarily operates in -full-duplex mode. Characters may be typed at any time, even while output is +full-duplex mode. +Characters may be typed at any time, even while output is occurring, and are only lost when the character input buffers of the system -become completely full, which is rare. For example, the number of characters in -the line discipline buffer may exceed {\fBMAX_CANON\fR} and \fBIMAXBEL\fR -(see below) is not set, or the user may accumulate { \fBMAX_INPUT\fR} number of -input characters that have not yet been read by some program. When the input +become completely full, which is rare. +For example, the number of characters in +the line discipline buffer may exceed +.Brq Dv MAX_CANON +and +.Dv IMAXBEL +(see below) is not set, or the user may accumulate +.Brq Dv MAX_INPUT +number of input characters that have not yet been read by some program. +When the input limit is reached, all the characters saved in the buffer up to that point are thrown away without notice. -.SS "Session Management (Job Control)" -.LP +.Ss "Session Management (Job Control)" A control terminal will distinguish one of the process groups in the session -associated with it to be the foreground process group. All other process -groups in the session are designated as background process groups. This -foreground process group plays a special role in handling signal-generating -input characters, as discussed below. By default, when a controlling terminal -is allocated, the controlling process's process group is assigned as +associated with it to be the foreground process group. +All other process +groups in the session are designated as background process groups. +This foreground process group plays a special role in handling signal-generating +input characters, as discussed below. +By default, when a controlling terminal +is allocated, the controlling process's process group is assigned as foreground process group. -.sp -.LP +.Pp Background process groups in the controlling process's session are subject to a job control line discipline when they attempt to access their controlling -terminal. Process groups can be sent signals that will cause them to stop, -unless they have made other arrangements. An exception is made for members of +terminal. +Process groups can be sent signals that will cause them to stop, +unless they have made other arrangements. +An exception is made for members of orphaned process groups. -.sp -.LP -An orphaned process group is one where the process group (see \fBgetpgid\fR(2)) +.Pp +An orphaned process group is one where the process group (see +.Xr getpgid 2 ) has no members with a parent in a different process group but sharing the same -controlling terminal. When a member of an orphaned process group attempts to +controlling terminal. +When a member of an orphaned process group attempts to access its controlling terminal, EIO is returned because there would be no way to restart the process if it were stopped on one of these signals. -.sp -.LP +.Pp If a member of a background process group attempts to read its controlling -terminal, its process group will be sent a \fBSIGTTIN\fR signal, which will -normally cause the members of that process group to stop. If, however, the -process is ignoring or holding \fBSIGTTIN\fR, or is a member of an orphaned -process group, the read will fail with \fBerrno\fR set to \fBEIO\fR, and no -signal is sent. -.sp -.LP +terminal, its process group will be sent a +.Dv SIGTTIN +signal, which will +normally cause the members of that process group to stop. +If, however, the +process is ignoring or holding +.Dv SIGTTIN , +or is a member of an orphaned +process group, the read will fail with +.Va errno +set to +.Er EIO , +and no signal is sent. +.Pp If a member of a background process group attempts to write its controlling -terminal and the \fBTOSTOP\fR bit is set in the \fBc_lflag\fR field, its -process group is sent a \fBSIGTTOU\fR signal, which will normally cause the -members of that process group to stop. If, however, the process is ignoring or -holding \fBSIGTTOU\fR, the write will succeed. If the process is not ignoring -or holding \fBSIGTTOU\fR and is a member of an orphaned process group, the -write will fail with \fBerrno\fR set to \fBEIO\fR, and no signal will be -sent. -.sp -.LP -If \fBTOSTOP\fR is set and a member of a background process group attempts to -\fBioctl\fR its controlling terminal, and that \fBioctl\fR will modify terminal -parameters (for example, \fBTCSETA\fR, \fBTCSETAW\fR, \fBTCSETAF\fR, or -\fBTIOCSPGRP)\fR, its process group will be sent a \fBSIGTTOU\fR signal, which -will normally cause the members of that process group to stop. If, however, the -process is ignoring or holding \fBSIGTTOU\fR, the ioctl will succeed. If the -process is not ignoring or holding \fBSIGTTOU\fR and is a member of an orphaned -process group, the write will fail with \fBerrno\fR set to \fBEIO\fR, and no -signal will be sent. -.SS "Canonical Mode Input Processing" -.LP -Normally, terminal input is processed in units of lines. A line is delimited by -a newline (\fBASCII LF\fR) character, an end-of-file (\fBASCII EOT\fR) -character, or an end-of-line character. This means that a program attempting to -read will block until an entire line has been typed. Also, no matter how many +terminal and the +.Dv TOSTOP +bit is set in the +.Fa c_lflag +field, its process group is sent a +.Dv SIGTTOU +signal, which will normally cause the +members of that process group to stop. +If, however, the process is ignoring or +holding +.Dv SIGTTOU , +the write will succeed. +If the process is not ignoring +or holding +.Dv SIGTTOU +and is a member of an orphaned process group, the +write will fail with +.Va errno +set to +.Er EIO , +and no signal will be sent. +.Pp +If +.Dv TOSTOP +is set and a member of a background process group attempts to +.Fn ioctl +its controlling terminal, and that +.Fn ioctl +will modify terminal parameters (for example, +.Dv TCSETA , +.Dv TCSETAW , +.Dv TCSETAF , +or +.Dv TIOCSPGRP ) , +its process group will be sent a +.Dv SIGTTOU +signal, which will normally cause the members of that process group to stop. +If, however, the process is ignoring or holding +.Dv SIGTTOU , +the ioctl will succeed. +If the process is not ignoring or holding +.Dv SIGTTOU +and is a member of an orphaned +process group, the write will fail with +.Va errno +set to +.Er EIO , +and no signal will be sent. +.Ss "Canonical Mode Input Processing" +Normally, terminal input is processed in units of lines. +A line is delimited by +a newline +.Po +.Sy ASCII LF +.Pc +character, an end-of-file +.Po +.Sy ASCII EOT +.Pc +character, or an end-of-line character. +This means that a program attempting to +read will block until an entire line has been typed. +Also, no matter how many characters are requested in the read call, at most one line will be returned. It is not necessary, however, to read a whole line at once; any number of characters may be requested in a read, even one, without losing information. -.sp -.LP -During input, erase, erase2, and kill processing is normally done. The -\fBERASE\fR and \fBERASE2\fR character (by default, the character \fBDEL\fR for \fBERASE\fR and \fBControl-h\fR for \fBERASE2\fR) erases the last character -typed. The \fBWERASE\fR character (the character \fBControl-w\fR) erases the +.Pp +During input, erase, erase2, and kill processing is normally done. +The +.Sy ERASE +and +.Sy ERASE2 +character (by default, the character +.Sy DEL +for +.Sy ERASE +and +.Sy Control-h +for +.Sy ERASE2 ) +erases the last character typed. +The +.Sy WERASE +character (the character +.Sy Control-w ) +erases the last "word" typed in the current input line (but not any preceding spaces or -tabs). A "word" is defined as a sequence of non-blank characters, with tabs -counted as blanks. None of \fBERASE\fR or \fBERASE2\fR or \fBWERASE\fR will -erase beyond the beginning of the line. The \fBKILL\fR character (by default, -the character \fBNAK\fR) kills (deletes) the entire input line, and optionally -outputs a newline character. All these characters operate on a key stroke basis, -independent of any backspacing or tabbing that may have been done. The -\fBREPRINT\fR character (the character Control-r) prints a newline followed by -all characters that have not been read. Reprinting also occurs automatically if +tabs). +A +.Dq word +is defined as a sequence of non-blank characters, with tabs counted as blanks. +None of +.Sy ERASE +or +.Sy ERASE2 +or +.Sy WERASE +will erase beyond the beginning of the line. +The +.Sy KILL +character (by default, +the character +.Sy NAK ) +kills (deletes) the entire input line, and optionally +outputs a newline character. +All these characters operate on a key stroke basis, +independent of any backspacing or tabbing that may have been done. +The +.Sy REPRINT +character (the character +.Sy Control-r ) +prints a newline followed by all characters that have not been read. +Reprinting also occurs automatically if characters that would normally be erased from the screen are fouled by program -output. The characters are reprinted as if they were being echoed; -consequencely, if \fBECHO\fR is not set, they are not printed. -.sp -.LP -The \fBERASE\fR, \fBERASE2\fR, and \fBKILL\fR characters may be entered -literally by preceding them with the escape character. In this case, the -escape character is not read. The erase, erase2, and kill characters may be -changed. -.SS "Non-canonical Mode Input Processing" -.LP +output. +The characters are reprinted as if they were being echoed; +consequencely, if +.Dv ECHO +is not set, they are not printed. +.Pp +The +.Sy ERASE , +.Sy ERASE2 , +and +.Sy KILL +characters may be entered literally by preceding them with the escape character. +In this case, the escape character is not read. +The erase, erase2, and kill characters may be changed. +.Ss "Non-canonical Mode Input Processing" In non-canonical mode input processing, input characters are not assembled into -lines, and erase and kill processing does not occur. The \fBMIN\fR and -\fBTIME\fR values are used to determine how to process the characters received. -.sp -.LP -\fBMIN\fR represents the minimum number of characters that should be received +lines, and erase and kill processing does not occur. +The +.Sy MIN +and +.Sy TIME +values are used to determine how to process the characters received. +.Pp +.Sy MIN +represents the minimum number of characters that should be received when the read is satisfied (that is, when the characters are returned to the -user). \fBTIME\fR is a timer of 0.10-second granularity that is used to timeout -bursty and short-term data transmissions. The four possible values for -\fBMIN\fR and \fBTIME\fR and their interactions are described below. -.sp -.ne 2 -.na -\fBCase A: MIN > 0, TIME > 0\fR -.ad -.RS 29n -In this case, \fBTIME\fR serves as an intercharacter timer and is activated -after the first character is received. Since it is an intercharacter timer, it -is reset after a character is received. The interaction between \fBMIN\fR and -\fBTIME\fR is as follows: as soon as one character is received, the -intercharacter timer is started. If \fBMIN\fR characters are received before +user). +.Sy TIME +is a timer of 0\&.10-second granularity that is used to timeout +bursty and short-term data transmissions. +The four possible values for +.Sy MIN +and +.Sy TIME +and their interactions are described below. +.Bl -tag -width "Case A: Min > 0, Time > 0" +.It Sy Case A: MIN > 0, TIME > 0 +In this case, +.Sy TIME +serves as an intercharacter timer and is activated +after the first character is received. +Since it is an intercharacter timer, it +is reset after a character is received. +The interaction between +.Sy MIN +and +.Sy TIME +is as follows: as soon as one character is received, the +intercharacter timer is started. +If +.Sy MIN +characters are received before the intercharacter timer expires (note that the timer is reset upon receipt of -each character), the read is satisfied. If the timer expires before \fBMIN\fR +each character), the read is satisfied. +If the timer expires before +.Sy MIN characters are received, the characters received to that point are returned to -the user. Note that if \fBTIME\fR expires, at least one character will be -returned because the timer would not have been enabled unless a character was -received. In this case (MIN > 0, TIME > 0), the read sleeps until the \fBMIN\fR -and \fBTIME\fR mechanisms are activated by the receipt of the first character. +the user. +Note that if +.Sy TIME +expires, at least one character will be +returned because the timer would not have been enabled unless a character was +received. +In this case (MIN > 0, TIME > 0), the read sleeps until the +.Sy MIN +and +.Sy TIME +mechanisms are activated by the receipt of the first character. If the number of characters read is less than the number of characters available, the timer is not reactivated and the subsequent read is satisfied immediately. -.RE - -.sp -.ne 2 -.na -\fBCase B: MIN > 0, TIME = 0\fR -.ad -.RS 29n -In this case, since the value of \fBTIME\fR is zero, the timer plays no role -and only \fBMIN\fR is significant. A pending read is not satisfied until -\fBMIN\fR characters are received (the pending read sleeps until \fBMIN\fR -characters are received). A program that uses this case to read record based -terminal \fBI/O\fR may block indefinitely in the read operation. -.RE - -.sp -.ne 2 -.na -\fBCase C: MIN = 0, TIME > 0\fR -.ad -.RS 29n -In this case, since \fBMIN\fR = 0, \fBTIME\fR no longer represents an +.It Sy Case B: MIN > 0, TIME = 0 +In this case, since the value of +.Sy TIME +is zero, the timer plays no role +and only +.Sy MIN +is significant. +A pending read is not satisfied until +.Sy MIN +characters are received (the pending read sleeps until +.Sy MIN +characters are received). +A program that uses this case to read record based +terminal +.Sy I/O +may block indefinitely in the read operation. +.It Sy Case C: MIN = 0, TIME > 0 +In this case, since +.Sy MIN +0, +.Sy TIME +no longer represents an intercharacter timer: it now serves as a read timer that is activated as soon -as a \fBread\fR is done. A read is satisfied as soon as a single character is -received or the read timer expires. Note that, in this case, if the timer -expires, no character is returned. If the timer does not expire, the only way -the read can be satisfied is if a character is received. In this case, the +as a +.Xr read 2 +is done. +A read is satisfied as soon as a single character is +received or the read timer expires. +Note that, in this case, if the timer +expires, no character is returned. +If the timer does not expire, the only way +the read can be satisfied is if a character is received. +In this case, the read will not block indefinitely waiting for a character; if no character is -received within \fBTIME\fR *.10 seconds after the read is initiated, the read +received within +.Sy TIME +*\&.10 seconds after the read is initiated, the read returns with zero characters. -.RE - -.sp -.ne 2 -.na -\fBCase D: MIN = 0, TIME = 0\fR -.ad -.RS 29n -In this case, return is immediate. The minimum of either the number of +.It Sy Case D: MIN = 0, TIME = 0 +In this case, return is immediate. +The minimum of either the number of characters requested or the number of characters currently available is returned without waiting for more characters to be input. -.RE - -.SS "Comparing Different Cases of MIN, TIME Interaction" -.LP -Some points to note about \fBMIN\fR and \fBTIME\fR : -.RS +4 -.TP -.ie t \(bu -.el o -In the following explanations, note that the interactions of \fBMIN\fR and -\fBTIME\fR are not symmetric. For example, when \fBMIN\fR > 0 and \fBTIME\fR -= 0, \fBTIME\fR has no effect. However, in the opposite case, where \fBMIN\fR -= 0 and \fBTIME\fR > 0, both \fBMIN\fR and \fBTIME\fR play a role in that -\fBMIN\fR is satisfied with the receipt of a single character. -.RE -.RS +4 -.TP -.ie t \(bu -.el o -Also note that in case A (\fBMIN\fR > 0, \fBTIME\fR > 0), \fBTIME\fR represents -an intercharacter timer, whereas in case C ( \fBMIN\fR = 0, \fBTIME\fR > 0), -\fBTIME\fR represents a read timer. -.RE -.sp -.LP -These two points highlight the dual purpose of the \fBMIN/TIME\fR feature. -Cases A and B, where \fBMIN\fR > 0, exist to handle burst mode activity (for +.El +.Ss "Comparing Different Cases of MIN, TIME Interaction" +Some points to note about +.Sy MIN +and +.Sy TIME : +.Bl -bullet -offset 2n +.It +In the following explanations, note that the interactions of +.Sy MIN +and +.Sy TIME +are not symmetric. +For example, when +.Sy MIN +> 0 and +.Sy TIME += 0, +.Sy TIME +has no effect. +However, in the opposite case, where +.Sy MIN += 0 and +.Sy TIME +> 0, both +.Sy MIN +and +.Sy TIME +play a role in that +.Sy MIN +is satisfied with the receipt of a single character. +.It +Also note that in case A +.Po +.Sy MIN +> 0, +.Sy TIME +> 0 +.Pc , +.Sy TIME +represents +an intercharacter timer, whereas in case C +.Po +.Sy MIN += 0, +.Sy TIME +> 0 +.Pc , +.Sy TIME +represents a read timer. +.El +.Pp +These two points highlight the dual purpose of the +.Sy MIN/TIME +feature. +Cases A and B, where +.Sy MIN +> 0, exist to handle burst mode activity (for example, file transfer programs), where a program would like to process at -least \fBMIN\fR characters at a time. In case A, the intercharacter timer is +least +.Sy MIN +characters at a time. +In case A, the inteercharacter timer is activated by a user as a safety measure; in case B, the timer is turned off. -.sp -.LP -Cases C and D exist to handle single character, timed transfers. These cases +.Pp +Cases C and D exist to handle single character, timed transfers. +These cases are readily adaptable to screen-based applications that need to know if a -character is present in the input queue before refreshing the screen. In case +character is present in the input queue before refreshing the screen. +In case C, the read is timed, whereas in case D, it is not. -.sp -.LP -Another important note is that \fBMIN\fR is always just a minimum. It does not -denote a record length. For example, if a program does a read of 20 bytes, -\fBMIN\fR is 10, and 25 characters are present, then 20 characters will be +.Pp +Another important note is that +.Sy MIN +is always just a minimum. +It does not +denote a record length. +For example, if a program does a read of 20 bytes, +.Sy MIN +is 10, and 25 characters are present, then 20 characters will be returned to the user. -.SS "Writing Characters" -.LP +.Ss "Writing Characters" When one or more characters are written, they are transmitted to the terminal -as soon as previously written characters have finished typing. Input characters -are echoed as they are typed if echoing has been enabled. If a process produces +as soon as previously written characters have finished typing. +nputt characters +are echoed as they are typed if echoing has been enabled. +If a process produces characters more rapidly than they can be typed, it will be suspended when its -output queue exceeds some limit. When the queue is drained down to some +output queue exceeds some limit. +When the queue is drained down to some threshold, the program is resumed. -.SS "Special Characters" -.LP -Certain characters have special functions on input. These functions and their -default character values are summarized as follows: -.sp -.ne 2 -.na -\fB\fBINTR\fR\fR -.ad -.RS 11n -(Control-c or \fBASCII ETX\fR) generates a \fBSIGINT\fR signal. \fBSIGINT\fR is -sent to all foreground processes associated with the controlling terminal. +.Ss "Special Characters" +Certain characters have special functions on input. +These functions and their default character values are summarized as follows: +.Bl -tag -width REPRINT +.It Sy INTR +(Control-c or +.Sy ASCII ETX ) +generates a +.Dv SIGINT +signal. +.Dv SIGINT +is sent to all foreground processes associated with the controlling terminal. Normally, each such process is forced to terminate, but arrangements may be made either to ignore the signal or to receive a trap to an agreed upon -location. (See \fBsignal.h\fR(3HEAD)). -.RE - -.sp -.ne 2 -.na -\fB\fBQUIT\fR\fR -.ad -.RS 11n -(Control-| or \fBASCII FS\fR) generates a \fBSIGQUIT\fR signal. Its treatment +location. +(See +.Xr signal.h 3HEAD ) . +.It Sy QUIT +(Control-| or +.Sy ASCII FS ) +generates a +.Dv SIGQUIT +signal. +Its treatment is identical to the interrupt signal except that, unless a receiving process has made other arrangements, it will not only be terminated but a core image -file (called \fBcore\fR) will be created in the current working directory. -.RE - -.sp -.ne 2 -.na -\fB\fBERASE\fR\fR -.ad -.RS 11n -(DEL) erases the preceding character. It does not erase beyond -the start of a line, as delimited by a \fBNL\fR, \fBEOF\fR, \fBEOL\fR, or -\fBEOL2\fR character. -.RE - -.sp -.ne 2 -.na -\fB\fBERASE2\fR\fR -.ad -.RS 11n -(Control-h or \fBASCII BS\fR) erases the preceding character, with behaviour -identical to that of ERASE. -.RE - -.sp -.ne 2 -.na -\fB\fBWERASE\fR\fR -.ad -.RS 11n -(Control-w or \fBASCII ETX\fR) erases the preceding "word". It does not erase -beyond the start of a line, as delimited by a \fBNL\fR, \fBEOF\fR, \fBEOL\fR, -or \fBEOL2\fR character. -.RE - -.sp -.ne 2 -.na -\fB\fBKILL\fR\fR -.ad -.RS 11n -(Control-u or \fBASCII NAK\fR) deletes the entire line, as delimited by a -\fBNL\fR, \fBEOF\fR, \fBEOL\fR, or \fBEOL2\fR character. -.RE - -.sp -.ne 2 -.na -\fB\fBREPRINT\fR\fR -.ad -.RS 11n -(Control-r or \fBASCII DC2\fR) reprints all characters, preceded by a newline, -that have not been read. -.RE - -.sp -.ne 2 -.na -\fB\fBEOF\fR\fR -.ad -.RS 11n -(Control-d or \fBASCII EOT\fR) may be used to generate an end-of-file from a -terminal. When received, all the characters waiting to be read are immediately -passed to the program, without waiting for a newline, and the \fBEOF\fR is -discarded. Thus, if no characters are waiting (that is, the \fBEOF\fR occurred +file (called +.Pa core ) +will be created in the current working directory. +.It Sy ERASE +(DEL) erases the preceding character. +It does not erase beyond +the start of a line, as delimited by a +.Sy NL , +.Sy EOF , +.Sy EOL , +or +.Sy EOL2 +character. +.It Sy ERASE2 +(Control-h or +.Sy ASCII BS ) +erases the preceding character, with behaviour identical to that of ERASE. +.It Sy WERASE +(Control-w or +.Sy ASCII ETX ) +erases the preceding +.Dq word . +It does not erase beyond the start of a line, as delimited by a +.Sy NL , +.Sy EOF , +.Sy EOL , +or +.Sy EOL2 +character. +.It Sy KILL +(Control-u or +.Sy ASCII NAK ) +deletes the entire line, as delimited by a +.Sy NL , +.Sy EOF , +.Sy EOL , +or +.Sy EOL2 +character. +.It Sy REPRINT +(Control-r or +.Sy ASCII DC2 ) +reprints all characters, preceded by a newline, that have not been read. +.It Sy EOF +(Control-d or +.Sy ASCII EOT ) +may be used to generate an end-of-file from a terminal. +When received, all the characters waiting to be read are immediately +passed to the program, without waiting for a newline, and the +.Sy EOF +is discarded. +Thus, if no characters are waiting (that is, the +.Sy EOF +occurred at the beginning of a line) zero characters are passed back, which is the -standard end-of-file indication. Unless escaped, the \fBEOF\fR character is not -echoed. Because \fBEOT\fR is the default \fBEOF\fR character, this prevents -terminals that respond to \fBEOT\fR from hanging up. -.RE - -.sp -.ne 2 -.na -\fB\fBNL\fR\fR -.ad -.RS 11n -(ASCII LF) is the normal line delimiter. It cannot be changed or escaped. -.RE - -.sp -.ne 2 -.na -\fB\fBEOL\fR\fR -.ad -.RS 11n -(ASCII NULL) is an additional line delimiter, like \fBNL\fR . It is not -normally used. -.RE - -.sp -.ne 2 -.na -\fB\fBEOL2\fR\fR -.ad -.RS 11n +standard end-of-file indication. +Unless escaped, the +.Sy EOF +character is not +echoed. +Because +.Sy EOT +is the default +.Sy EOF +character, this prevents +terminals that respond to +.Sy EOT +from hanging up. +.It Sy NL +.Pq Sy ASCII LF +is the normal line delimiter. +It cannot be changed or escaped. +.It Sy EOL +.Pq Sy ASCII NULL +is an additional line delimiter, like +.Sy NL . +It is not normally used. +.It Sy EOL2 is another additional line delimiter. -.RE - -.sp -.ne 2 -.na -\fB\fBSWTCH\fR\fR -.ad -.RS 11n -(Control-z or \fBASCII EM\fR) Header file symbols related to this special +.It Sy SWTCH +(Control-z or +.Sy ASCII EM ) +Header file symbols related to this special character are present for compatibility purposes only and the kernel takes no special action on matching SWTCH (except to discard the character). -.RE - -.sp -.ne 2 -.na -\fB\fBSUSP\fR\fR -.ad -.RS 11n -(Control-z or \fBASCII SUB\fR) generates a \fBSIGTSTP\fR signal. \fBSIGTSTP\fR +.It Sy SUSP +(Control-z or +.Sy ASCII SUB ) +generates a +.Dv SIGTSTP +signal. +.Dv SIGTSTP stops all processes in the foreground process group for that terminal. -.RE - -.sp -.ne 2 -.na -\fB\fBDSUSP\fR\fR -.ad -.RS 11n -(Control-y or \fBASCII EM\fR). It generates a \fBSIGTSTP\fR signal as -\fBSUSP\fR does, but the signal is sent when a process in the foreground -process group attempts to read the \fBDSUSP\fR character, rather than when it -is typed. -.RE - -.sp -.ne 2 -.na -\fB\fBSTOP\fR\fR -.ad -.RS 11n -(Control-s or \fBASCII DC3\fR) can be used to suspend output temporarily. It is -useful with \fBCRT\fR terminals to prevent output from disappearing before it -can be read. While output is suspended, \fBSTOP\fR characters are ignored and +.It Sy DSUSP +(Control-y or +.Sy ASCII EM ) . +It generates a +.Dv SIGTSTP +signal as +.Sy SUSP +does, but the signal is sent when a process in the foreground +process group attempts to read the +.Sy DSUSP +character, rather than when it is typed. +.It Sy STOP +(Control-s or +.Sy ASCII DC3 ) +can be used to suspend output temporarily. +It is useful with +.Sy CRT +terminals to prevent output from disappearing before it can be read. +While output is suspended, +.Sy STOP +characters are ignored and not read. -.RE - -.sp -.ne 2 -.na -\fB\fBSTART\fR\fR -.ad -.RS 11n -(Control-q or \fBASCII DC1\fR) is used to resume output. Output has been -suspended by a \fBSTOP\fR character. While output is not suspended, -\fBSTART\fR characters are ignored and not read. -.RE - -.sp -.ne 2 -.na -\fB\fBDISCARD\fR\fR -.ad -.RS 11n -(Control-o or \fBASCII SI\fR) causes subsequent output to be discarded. Output -is discarded until another \fBDISCARD\fR character is typed, more input +.It Sy START +(Control-q or +.Sy ASCII DC1 ) +is used to resume output. +Output has been suspended by a +.Sy STOP +character. +While output is not suspended, +.Sy START +characters are ignored and not read. +.It Sy DISCARD +(Control-o or +.Sy ASCII SI ) +causes subsequent output to be discarded. +Output is discarded until another +.Sy DISCARD +character is typed, more input arrives, or the condition is cleared by a program. -.RE - -.sp -.ne 2 -.na -\fB\fBSTATUS\fR\fR -.ad -.RS 11n -(Control-t or \fBASCII DC4\fR) generates a \fBSIGINFO\fR signal. Processes with -a handler will output status information when they receive \fBSIGINFO\fR, for -example, \fBdd\fR(1M). If a process does not have a \fBSIGINFO\fR handler, the +.It Sy STATUS +(Control-t or +.Sy ASCII DC4 ) +generates a +.Dv SIGINFO +signal. +Processes with a handler will output status information when they receive +.Dv SIGINFO , +for +example, +.Xr dd 1M . +If a process does not have a +.Dv SIGINFO +handler, the signal will be ignored. -.RE - -.sp -.ne 2 -.na -\fB\fBLNEXT\fR\fR -.ad -.RS 11n -(Control-v or \fBASCII SYN\fR) causes the special meaning of the next character -to be ignored. This works for all the special characters mentioned above. It +.It Sy LNEXT +(Control-v or +.Sy ASCII SYN ) +causes the special meaning of the next character to be ignored. +This works for all the special characters mentioned above. +It allows characters to be input that would otherwise be interpreted by the system -(for example \fBKILL, QUIT\fR). The character values for \fBINTR\fR, -\fBQUIT\fR, \fBERASE\fR, \fBERASE2\fR, \fBWERASE\fR, \fBKILL\fR, \fBREPRINT\fR, -\fBEOF\fR, \fBEOL\fR, \fBEOL2\fR, \fBSWTCH\fR, \fBSUSP\fR, \fBDSUSP\fR, -\fBSTOP\fR, \fBSTART\fR, \fBDISCARD\fR, \fBSTATUS\fR, and \fBLNEXT\fR may be -changed to suit individual tastes. If the value of a special control character -is _POSIX_VDISABLE (0), the function of that special control character is -disabled. -The \fBERASE\fR, \fBERASE2\fR, \fBKILL\fR, and \fBEOF\fR characters may be +(for example +.Sy KILL , +.Sy QUIT ) . +The character values for +.Sy INTR , +.Sy QUIT , +.Sy ERASE , +.Sy ERASE2 , +.Sy WERASE , +.Sy KILL , +.Sy REPRINT , +.Sy EOF , +.Sy EOL , +.Sy EOL2 , +.Sy SWTCH , +.Sy SUSP , +.Sy DSUSP , +.Sy STOP , +.Sy START , +.Sy DISCARD , +.Sy STATUS , +and +.Sy LNEXT +may be changed to suit individual tastes. +If the value of a special control character +is +.Dv _POSIX_VDISABLE +(0), the function of that special control character is disabled. +The +.Sy ERASE , +.Sy ERASE2 , +.Sy KILL , +and +.Sy EOF +characters may be escaped by a preceding backslash (\e) character, in which case no special function is done. -Any of the special characters may be preceded by the \fBLNEXT\fR character, in +Any of the special characters may be preceded by the +.Sy LNEXT +character, in which case no special function is done. -.RE - -.SS "Modem Disconnect" -.LP -When a modem disconnect is detected, a \fBSIGHUP\fR signal is sent to the -terminal's controlling process. Unless other arrangements have been made, these -signals cause the process to terminate. If \fBSIGHUP\fR is ignored or caught, +.El +.Ss "Modem Disconnect" +When a modem disconnect is detected, a +.Dv SIGHUP +signal is sent to the +terminal's controlling process. +Unless other arrangements have been made, these +signals cause the process to terminate. +If +.Dv SIGHUP +is ignored or caught, any subsequent read returns with an end-of-file indication until the terminal is closed. -.sp -.LP -If the controlling process is not in the foreground process group of the -terminal, a \fBSIGTSTP\fR is sent to the terminal's foreground process group. +.Pp +If the controlling process is not in the foreground process group of the +terminal, a +.Dv SIGTSTP +is sent to the terminal's foreground process group. Unless other arrangements have been made, these signals cause the processes to stop. -.sp -.LP +.Pp Processes in background process groups that attempt to access the controlling terminal after modem disconnect while the terminal is still allocated to the -session will receive appropriate \fBSIGTTOU\fR and \fBSIGTTIN\fR signals. -Unless other arrangements have been made, this signal causes the processes to +session will receive appropriate +.Dv SIGTTOU +and +.Dv SIGTTIN +signals. +Unless other arrangements have been made, this signal causes the processes to stop. -.sp -.LP -The controlling terminal will remain in this state until it is reinitialized -with a successful open by the controlling process, or deallocated by the +.Pp +The controlling terminal will remain in this state until it is reinitialized +ithh a successful open by the controlling process, or deallocated by the controlling process. -.SS "Terminal Parameters" -.LP +.Ss "Terminal Parameters" The parameters that control the behavior of devices and modules providing the -\fBtermios\fR interface are specified by the \fBtermios\fR structure defined by -\fBtermios.h\fR. Several \fBioctl\fR(2) system calls that fetch or change +.Vt termios +interface are specified by the +.Vt termios +structure defined by +.In termios.h . +Several +.Xr ioctl 2 +system calls that fetch or change these parameters use this structure that contains the following members: -.sp -.in +2 -.nf - tcflag_t c_iflag; /* input modes */ - tcflag_t c_oflag; /* output modes */ - tcflag_t c_cflag; /* control modes */ - tcflag_t c_lflag; /* local modes */ - cc_t c_cc[NCCS]; /* control chars */ -.fi -.in -2 - -.sp -.LP -The special control characters are defined by the array \fBc_cc\fR. The -symbolic name \fBNCCS\fR is the size of the Control-character array and is also -defined by \fB<termios.h>\fR\&. The relative positions, subscript names, and -typical default values for each function are as follows: -.sp - -.sp -.TS -box; -c | c | c -l | l | l . -Relative Position Subscript Name Typical Default Value -_ -0 VINTR ETX -_ -1 VQUIT FS -_ -2 VERASE DEL -_ -3 VKILL NAK -_ -4 VEOF EOT -_ -5 VEOL NUL -_ -6 VEOL2 NUL -_ -7 VWSTCH NUL -_ -8 VSTART NUL -_ -9 VSTOP DC3 -_ -10 VSUSP SUB -_ -11 VDSUSP EM -_ -12 VREPRINT DC2 -_ -13 VDISCARD SI -_ -14 VWERASE ETB -_ -15 VLNEXT SYN -_ -16 VSTATUS DC4 -_ -17 VERASE2 BS -_ -18-19 Reserved -.TE - -.SS "Input Modes" -.LP -The \fBc_iflag\fR field describes the basic terminal input control: -.sp -.ne 2 -.na -\fB\fBIGNBRK\fR\fR -.ad -.RS 11n - Ignore break condition. -.RE - -.sp -.ne 2 -.na -\fB\fBBRKINT\fR\fR -.ad -.RS 11n +.Bd -literal -offset 2n +tcflag_t c_iflag; /* input modes */ +tcflag_t c_oflag; /* output modes */ +tcflag_t c_cflag; /* control modes */ +tcflag_t c_lflag; /* local modes */ +cc_t c_cc[NCCS]; /* control chars */ +.Ed +.Pp +The special control characters are defined by the array +.Fa c_cc . +The symbolic name +.Dv NCCS +is the size of the Control-character array and is also +defined by +.In termios.h . +The relative positions, subscript names, and +typical default values for each function are as follows: +.Bl -column "Relative Position" "Subscript Name" "Typical Default Value" +.It Relative Position Ta Subscript Name Ta Typical Default Value +.It 0 Ta Dv VINTR Ta Sy ETX +.It 1 Ta Dv VQUIT Ta Sy FS +.It 2 Ta Dv VERASE Ta Sy DEL +.It 3 Ta Dv VKILL Ta Sy NAK +.It 4 Ta Dv VEOF Ta Sy EOT +.It 5 Ta Dv VEOL Ta Sy NUL +.It 6 Ta Dv VEOL2 Ta Sy NUL +.It 7 Ta Dv VWSTCH Ta Sy NUL +.It 8 Ta Dv VSTART Ta Sy NUL +.It 9 Ta Dv VSTOP Ta Sy DC3 +.It 10 Ta Dv VSUSP Ta Sy SUB +.It 11 Ta Dv VDSUSP Ta Sy EM +.It 12 Ta Dv VREPRINT Ta Sy DC2 +.It 13 Ta Dv VDISCARD Ta Sy SI +.It 14 Ta Dv VWERASE Ta Sy ETB +.It 15 Ta Dv VLNEXT Ta Sy SYN +.It 16 Ta Dv VSTATUS Ta Sy DC4 +.It 17 Ta Dv VERASE2 Ta Sy BS +.It 18-19 Ta Reserved Ta +.El +.Ss "Input Modes" +The +.Fa c_iflag +field describes the basic terminal input control: +.Pp +.Bl -tag -width "IMAXBEL" -offset 2n -compact +.It Dv IGNBRK +Ignore break condition. +.It Dv BRKINT Signal interrupt on break. -.RE - -.sp -.ne 2 -.na -\fB\fBIGNPAR\fR\fR -.ad -.RS 11n +.It Dv IGNPAR Ignore characters with parity errors. -.RE - -.sp -.ne 2 -.na -\fB\fBPARMRK\fR\fR -.ad -.RS 11n +.It Dv PARMRK Mark parity errors. -.RE - -.sp -.ne 2 -.na -\fB\fBINPCK\fR\fR -.ad -.RS 11n +.It Dv INPCK Enable input parity check. -.RE - -.sp -.ne 2 -.na -\fB\fBISTRIP\fR\fR -.ad -.RS 11n +.It Dv ISTRIP Strip character. -.RE - -.sp -.ne 2 -.na -\fB\fBINLCR\fR\fR -.ad -.RS 11n +.It Dv INLCR Map NL to CR on input. -.RE - -.sp -.ne 2 -.na -\fB\fBIGNCR\fR\fR -.ad -.RS 11n +.It Dv IGNCR Ignore CR. -.RE - -.sp -.ne 2 -.na -\fB\fBICRNL\fR\fR -.ad -.RS 11n +.It Dv ICRNL Map CR to NL on input. -.RE - -.sp -.ne 2 -.na -\fB\fBIUCLC\fR\fR -.ad -.RS 11n +.It Dv IUCLC Map upper-case to lower-case on input. -.RE - -.sp -.ne 2 -.na -\fB\fBIXON\fR\fR -.ad -.RS 11n +.It Dv IXON Enable start/stop output control. -.RE - -.sp -.ne 2 -.na -\fB\fBIXANY\fR\fR -.ad -.RS 11n +.It Dv IXANY Enable any character to restart output. -.RE - -.sp -.ne 2 -.na -\fB\fBIXOFF\fR\fR -.ad -.RS 11n +.It Dv IXOFF Enable start/stop input control. -.RE - -.sp -.ne 2 -.na -\fB\fBIMAXBEL\fR\fR -.ad -.RS 11n -Echo \fBBEL\fR on input line too long. -.RE - -.sp -.LP -If \fBIGNBRK\fR is set, a break condition (a character framing error with data +.It Dv IMAXBEL +Echo +.Sy BEL +on input line too long. +.El +.Pp +If +.Dv IGNBRK +is set, a break condition (a character framing error with data all zeros) detected on input is ignored, that is, not put on the input queue -and therefore not read by any process. If \fBIGNBRK\fR is not set and -\fBBRKINT\fR is set, the break condition shall flush the input and output +and therefore not read by any process. +If +.Dv IGNBRK +is not set and +.Dv BRKINT +is set, the break condition shall flush the input and output queues and if the terminal is the controlling terminal of a foreground process -group, the break condition generates a single \fBSIGINT\fR signal to that -foreground process group. If neither \fBIGNBRK\fR nor \fBBRKINT\fR is set, a -break condition is read as a single '\e0' (\fBASCII NULL\fR) character, or if -\fBPARMRK\fR is set, as '\e377', '\e0', c, where '\e377' is a single character -with value 377 octal (0xff hex, 255 decimal), '\e0' is a single character with -value 0, and c is the errored character received. -.sp -.LP -If \fBIGNPAR\fR is set, a byte with framing or parity errors (other than -break) is ignored. -.sp -.LP -If \fBPARMRK\fR is set, and \fBIGNPAR\fR is not set, a byte with a framing or +group, the break condition generates a single +.Dv SIGINT +signal to that +foreground process group. +If neither +.Dv IGNBRK +nor +.Dv BRKINT +is set, a +break condition is read as a single +.Ql \e0 +.Pq Sy ASCII NULL +character, or if +.Dv PARMRK +is set, as +.Ql \e377 , +.Ql \e0 , +.Em c , +where +.Ql \e377 +is a single character +with value 377 octal (0xff hex, 255 decimal), +.Ql \e0 +is a single character with value +.Sy 0 , +and +.Em c +is the errored character received. +.Pp +If +.Dv IGNPAR +is set, a byte with framing or parity errors (other than +break) is ignored. +.Pp +If +.Dv PARMRK +is set, and +.Dv IGNPAR +is not set, a byte with a framing or parity error (other than break) is given to the application as the -three-character sequence: '\e377', '\e0', c, where '\e377' is a single -character with value 377 octal (0xff hex, 255 decimal), '\e0' is a single -character with value 0, and c is the errored character received. To avoid -ambiguity in this case, if \fBISTRIP\fR is not set, a valid character -of '\e377' is given to the application as `\e377.' If neither \fBIGNPAR\fR nor -\fBPARMRK\fR is set, a framing or parity error (other than break) is given to -the application as a single '\e0' (\fBASCII NULL\fR) character. -.sp -.LP -If \fBINPCK\fR is set, input parity checking is enabled. If \fBINPCK\fR is not -set, input parity checking is disabled. This allows output parity generation -without input parity errors. Note that whether input parity checking is +three-character sequence: +.Ql \e377 , +.Ql \e0 , +c, where +.Ql \e377 +is a single character with value 377 octal (0xff hex, 255 decimal), +.Ql \e0 +is a single character with value 0, and c is the errored character received. +To avoid ambiguity in this case, if +.Dv ISTRIP +is not set, a valid character +of +.Ql \e377 +is given to the application as +.Ql \e377 . +If neither +.Dv IGNPAR +nor +.Dv PARMRK +is set, a framing or parity error (other than break) is given to +the application as a single +.Ql \e0 +.Po +.Sy ASCII NULL +.Pc +character. +.Pp +If +.Dv INPCK +is set, input parity checking is enabled. +If +.Dv INPCK +is not +set, input parity checking is disabled. +This allows output parity generation +without input parity errors. +Note that whether input parity checking is enabled or disabled is independent of whether parity detection is enabled or -disabled. If parity detection is enabled but input parity checking is +disabled. +If parity detection is enabled but input parity checking is disabled, the hardware to which the terminal is connected will recognize the parity bit, but the terminal special file will not check whether this is set correctly or not. -.sp -.LP -If \fBISTRIP\fR is set, valid input characters are first stripped to seven +.Pp +If +.Dv ISTRIP +is set, valid input characters are first stripped to seven bits, otherwise all eight bits are processed. -.sp -.LP -If \fBINLCR\fR is set, a received \fBNL\fR character is translated into a -\fBCR\fR character. If \fBIGNCR\fR is set, a received \fBCR\fR character is -ignored (not read). Otherwise, if \fBICRNL\fR is set, a received \fBCR\fR -character is translated into a \fBNL\fR character. -.sp -.LP -If \fBIUCLC\fR is set, a received upper case, alphabetic character is +.Pp +If +.Dv INLCR +is set, a received +.Sy NL +character is translated into a +.Sy CR +character. +If +.Dv IGNCR +is set, a received +.Sy CR +character is ignored (not read). +Otherwise, if +.Dv ICRNL +is set, a received +.Sy CR +character is translated into a +.Sy NL +character. +.Pp +If +.Dv IUCLC +is set, a received upper case, alphabetic character is translated into the corresponding lower case character. -.sp -.LP -If \fBIXON\fR is set, start/stop output control is enabled. A received -\fBSTOP\fR character suspends output and a received \fBSTART\fR character -restarts output. The \fBSTOP\fR and \fBSTART\fR characters will not be read, -but will merely perform flow control functions. If \fBIXANY\fR is set, any +.Pp +If +.Dv IXON +is set, start/stop output control is enabled. +A received +.Sy STOP +character suspends output and a received +.Sy START +character +restarts output. +The +.Sy STOP +and +.Sy START +characters will not be read, +but will merely perform flow control functions. +If +.Dv IXANY +is set, any input character restarts output that has been suspended. -.sp -.LP -If \fBIXOFF\fR is set, the system transmits a \fBSTOP\fR character when the -input queue is nearly full, and a \fBSTART\fR character when enough input has +.Pp +If +.Dv IXOFF +is set, the system transmits a +.Sy STOP +character when the +input queue is nearly full, and a +.Sy START +character when enough input has been read so that the input queue is nearly empty again. -.sp -.LP -If \fBIMAXBEL\fR is set, the \fBASCII BEL\fR character is echoed if the input -stream overflows. Further input is not stored, but any input already present in -the input stream is not disturbed. If \fBIMAXBEL\fR is not set, no \fBBEL\fR +.Pp +If +.Dv IMAXBEL +is set, the +.Sy ASCII BEL +character is echoed if the input stream overflows. +Further input is not stored, but any input already present in +the input stream is not disturbed. +If +.Dv IMAXBEL +is not set, no +.Sy BEL character is echoed, and all input present in the input queue is discarded if the input stream overflows. -.SS "Output Modes" -.LP -The \fBc_oflag\fR field specifies the system treatment of output: -.sp -.ne 2 -.na -\fB\fBOPOST\fR\fR -.ad -.RS 10n +.Ss "Output Modes" +The +.Fa c_oflag +field specifies the system treatment of output: +.Pp +.Bl -tag -width ONLRET -offset 2n -compact +.It Dv OPOST Post-process output. -.RE - -.sp -.ne 2 -.na -\fB\fBOLCUC\fR\fR -.ad -.RS 10n +.It Dv OLCUC Map lower case to upper on output. -.RE - -.sp -.ne 2 -.na -\fB\fBONLCR\fR\fR -.ad -.RS 10n +.It Dv ONLCR Map NL to CR-NL on output. -.RE - -.sp -.ne 2 -.na -\fB\fBOCRNL\fR\fR -.ad -.RS 10n +.It Dv OCRNL Map CR to NL on output. -.RE - -.sp -.ne 2 -.na -\fB\fBONOCR\fR\fR -.ad -.RS 10n -No \fBCR\fR output at column 0. -.RE - -.sp -.ne 2 -.na -\fB\fBONLRET\fR\fR -.ad -.RS 10n -\fBNL\fR performs \fBCR\fR function. -.RE - -.sp -.ne 2 -.na -\fB\fBOFILL\fR\fR -.ad -.RS 10n +.It Dv ONOCR +No +.Sy CR +output at column 0. +.It Dv ONLRET +.Sy NL +performs +.Sy CR +function. +.It Dv OFILL Use fill characters for delay. -.RE - -.sp -.ne 2 -.na -\fB\fBOFDEL\fR\fR -.ad -.RS 10n -Fill is \fBDEL\fR, else \fINULL\fR. -.RE - -.sp -.ne 2 -.na -\fB\fBNLDLY\fR\fR -.ad -.RS 10n +.It Dv OFDEL +Fill is +.Sy DEL , +else +.Sy INULL . +.It Dv NLDLY Select newline delays: -.br -.in +2 -\fBNL0\fR -.in -2 -.br -.in +2 -\fBNL1\fR -.in -2 -.RE - -.sp -.ne 2 -.na -\fB\fBCRDLY\fR\fR -.ad -.RS 10n +.Bl -tag -width NL0 -compact -offset 2n +.It Sy NL0 +.It Sy NL1 +.El +.It Dv CRDLY Select carriage-return delays: -.br -.in +2 -\fBCR0\fR -.in -2 -.br -.in +2 -\fBCR1\fR -.in -2 -.br -.in +2 -\fBCR2\fR -.in -2 -.br -.in +2 -\fBCR3\fR -.in -2 -.RE - -.sp -.ne 2 -.na -\fB\fBTABDLY\fR\fR -.ad -.RS 10n +.Bl -tag -width CR0 -compact -offset 2n +.It Dv CR0 +.It Dv CR1 +.It Dv CR2 +.It Dv CR3 +.El +.It Dv TABDLY Select horizontal tab delays or tab expansion: -.sp -.ne 2 -.na -\fB\fBTAB0\fR\fR -.ad -.RS 9n - -.RE - -.sp -.ne 2 -.na -\fB\fBTAB1\fR\fR -.ad -.RS 9n - -.RE - -.sp -.ne 2 -.na -\fB\fBTAB2\fR\fR -.ad -.RS 9n - -.RE - -.sp -.ne 2 -.na -\fB\fBTAB3\fR\fR -.ad -.RS 9n +.Bl -tag -width XTABS -compact -offset 2n +.It Dv TAB0 +.It Dv TAB1 +.It Dv TAB2 +.It Dv TAB3 Expand tabs to spaces -.RE - -.sp -.ne 2 -.na -\fB\fBXTABS\fR\fR -.ad -.RS 9n +.It Dv XTABS Expand tabs to spaces -.RE - -.RE - -.sp -.ne 2 -.na -\fB\fBBSDLY\fR\fR -.ad -.RS 10n +.El +.It Dv BSDLY Select backspace delays: -.br -.in +2 -\fBBS0\fR -.in -2 -.br -.in +2 -\fBBS1\fR -.in -2 -.RE - -.sp -.ne 2 -.na -\fB\fBVTDLY\fR\fR -.ad -.RS 10n +.Bl -tag -width BS0 -offset 2n -compact +.It Dv BS0 +.It Dv BS1 +.El +.It Dv VTDLY Select vertical tab delays: -.br -.in +2 -\fBVT0\fR -.in -2 -.br -.in +2 -\fBVT1\fR -.in -2 -.RE - -.sp -.ne 2 -.na -\fB\fBFFDLY\fR\fR -.ad -.RS 10n +.Bl -tag -width VT0 -offset 2n -compact +.It Dv VT0 +.It Dv VT1 +.El +.It Dv FFDLY Select form feed delays: -.br -.in +2 -\fBFF0\fR -.in -2 -.br -.in +2 -\fBFF1\fR -.in -2 -.RE - -.sp -.LP -If \fBOPOST\fR is set, output characters are post-processed as indicated by the +.Bl -tag -width FF0 -offset 2n -compact +.It Dv FF0 +.It Dv FF1 +.El +.El +.Pp +If +.Dv OPOST +is set, output characters are post-processed as indicated by the remaining flags; otherwise, characters are transmitted without change. -.sp -.LP -If \fBOLCUC\fR is set, a lower case alphabetic character is transmitted as the -corresponding upper case character. This function is often used in conjunction -with \fBIUCLC.\fR -.sp -.LP -If \fBONLCR\fR is set, the \fBNL\fR character is transmitted as the \fBCR-NL\fR -character pair. If \fBOCRNL\fR is set, the \fBCR\fR character is transmitted -as the \fBNL\fR character. If \fBONOCR\fR is set, no \fBCR\fR character is -transmitted when at column 0 (first position). If \fBONRET\fR is set, the -\fBNL\fR character is assumed to do the carriage-return function; the column -pointer is set to 0 and the delays specified for \fBCR\fR are used. Otherwise, -the \fBNL\fR character is assumed to do just the line-feed function; the column -pointer remains unchanged. The column pointer is also set to 0 if the \fBCR\fR +.Pp +If +.Dv OLCUC +is set, a lower case alphabetic character is transmitted as the +corresponding upper case character. +This function is often used in conjunction +with +.Dv IUCLC . +.Pp +If +.Dv ONLCR +is set, the +.Sy NL +character is transmitted as the +.Sy CR-NL +character pair. +If +.Dv OCRNL +is set, the +.Sy CR +character is transmitted as the +.Sy NL +character. +If +.Dv ONOCR +is set, no +.Sy CR +character is transmitted when at column 0 (first position). +If +.Dv ONRET +is set, the +.Sy NL +character is assumed to do the carriage-return function; the column +pointer is set to 0 and the delays specified for +.Sy CR +are used. +Otherwise, the +.Sy NL +character is assumed to do just the line-feed function; the column +pointer remains unchanged. +The column pointer is also set to 0 if the +.Sy CR character is actually transmitted. -.sp -.LP +.Pp The delay bits specify how long transmission stops to allow for mechanical or -other movement when certain characters are sent to the terminal. In all cases, -a value of 0 indicates no delay. If \fBOFILL\fR is set, fill characters are -transmitted for delay instead of a timed delay. This is useful for high baud -rate terminals that need only a minimal delay. If \fBOFDEL\fR is set, the -fill character is \fBDEL\fR ; otherwise it is \fINULL\fR. -.sp -.LP +other movement when certain characters are sent to the terminal. +In all cases, a value of 0 indicates no delay. +If +.Dv OFILL +is set, fill characters are transmitted for delay instead of a timed delay. +This is useful for high baud rate terminals that need only a minimal delay. +If +.Dv OFDEL +is set, the +fill character is +.Sy DEL ; +otherwise it is +.Sy NULL . +.Pp If a form-feed or vertical-tab delay is specified, it lasts for about 2 seconds. -.sp -.LP -Newline delay lasts about 0.10 seconds. If \fBONLRET\fR is set, the -carriage-return delays are used instead of the newline delays. If \fBOFILL\fR +.Pp +Newline delay lasts about 0\&.10 seconds. +If +.Dv ONLRET +is set, the carriage-return delays are used instead of the newline delays. +If +.Dv OFILL is set, two fill characters are transmitted. -.sp -.LP +.Pp Carriage-return delay type 1 is dependent on the current column position, type -2 is about 0.10 seconds, and type 3 is about 0.15 seconds. If \fBOFILL\fR is -set, delay type 1 transmits two fill characters, and type 2 transmits four fill -characters. -.sp -.LP -Horizontal-tab delay type 1 is dependent on the current column position. Type 2 -is about 0.10 seconds. Type 3 specifies that tabs are to be expanded into -spaces. If \fBOFILL\fR is set, two fill characters are transmitted for any -delay. -.sp -.LP -Backspace delay lasts about 0.05 seconds. If \fBOFILL\fR is set, one fill -character is transmitted. -.sp -.LP +2 is about 0\&.10 seconds, and type 3 is about 0\&.15 seconds. +If +.Dv OFILL +is set, delay type 1 transmits two fill characters, and type 2 transmits four +fill characters. +.Pp +Horizontal-tab delay type 1 is dependent on the current column position. +Type 2 is about 0\&.10 seconds. +Type 3 specifies that tabs are to be expanded into spaces. +If +.Dv OFILL +is set, two fill characters are transmitted for any delay. +.Pp +Backspace delay lasts about 0\&.05 seconds. +If +.Dv OFILL +is set, one fill character is transmitted. +.Pp The actual delays depend on line speed and system load. -.SS "Control Modes" -.LP -The \fBc_cflag\fR field describes the hardware control of the terminal: -.sp -.ne 2 -.na -\fB\fBCBAUD\fR\fR -.ad -.RS 13n +.Ss "Control Modes" +The +.Fa c_cflag +field describes the hardware control of the terminal: +.Bl -tag -width CIBAUDEXT -offset 2n +.It Dv CBAUD Baud rate: -.RE - -.sp -.ne 2 -.na -\fB\fBB0\fR\fR -.ad -.RS 13n +.Bl -tag -width B460800 -compact +.It Dv B0 Hang up -.RE - -.sp -.ne 2 -.na -\fB\fBB50\fR\fR -.ad -.RS 13n +.It Dv B50 50 baud -.RE - -.sp -.ne 2 -.na -\fB\fBB75\fR\fR -.ad -.RS 13n +.It Dv B75 75 baud -.RE - -.sp -.ne 2 -.na -\fB\fBB110\fR\fR -.ad -.RS 13n +.It Dv B110 110 baud -.RE - -.sp -.ne 2 -.na -\fB\fBB134\fR\fR -.ad -.RS 13n +.It Dv B134 134 baud -.RE - -.sp -.ne 2 -.na -\fB\fBB150\fR\fR -.ad -.RS 13n +.It Dv B150 150 baud -.RE - -.sp -.ne 2 -.na -\fB\fBB200\fR\fR -.ad -.RS 13n +.It Dv B200 200 baud -.RE - -.sp -.ne 2 -.na -\fB\fBB300\fR\fR -.ad -.RS 13n +.It Dv B300 300 baud -.RE - -.sp -.ne 2 -.na -\fB\fBB600\fR\fR -.ad -.RS 13n +.It Dv B600 600 baud -.RE - -.sp -.ne 2 -.na -\fB\fBB1200\fR\fR -.ad -.RS 13n +.It Dv B1200 1200 baud -.RE - -.sp -.ne 2 -.na -\fB\fBB1800\fR\fR -.ad -.RS 13n +.It Dv B1800 1800 baud -.RE - -.sp -.ne 2 -.na -\fB\fBB2400\fR\fR -.ad -.RS 13n +.It Dv B2400 2400 baud -.RE - -.sp -.ne 2 -.na -\fB\fBB4800\fR\fR -.ad -.RS 13n +.It Dv B4800 4800 baud -.RE - -.sp -.ne 2 -.na -\fB\fBB9600\fR\fR -.ad -.RS 13n +.It Dv B9600 9600 baud -.RE - -.sp -.ne 2 -.na -\fB\fBB19200\fR\fR -.ad -.RS 13n +.It Dv B19200 19200 baud -.RE - -.sp -.ne 2 -.na -\fB\fBEXTA\fR\fR -.ad -.RS 13n +.It Dv EXTA External A -.RE - -.sp -.ne 2 -.na -\fB\fBB38400\fR\fR -.ad -.RS 13n +.It Dv B38400 38400 baud -.RE - -.sp -.ne 2 -.na -\fB\fBEXTB\fR\fR -.ad -.RS 13n +.It Dv EXTB External B -.RE - -.sp -.ne 2 -.na -\fB\fBB57600\fR\fR -.ad -.RS 13n +.It Dv B57600 57600 baud -.RE - -.sp -.ne 2 -.na -\fB\fBB76800\fR\fR -.ad -.RS 13n +.It Dv B76800 76800 baud -.RE - -.sp -.ne 2 -.na -\fB\fBB115200\fR\fR -.ad -.RS 13n +.It Dv B115200 115200 baud -.RE - -.sp -.ne 2 -.na -\fB\fBB153600\fR\fR -.ad -.RS 13n +.It Dv B153600 153600 baud -.RE - -.sp -.ne 2 -.na -\fB\fBB230400\fR\fR -.ad -.RS 13n +.It Dv B230400 230400 baud -.RE - -.sp -.ne 2 -.na -\fB\fBB307200\fR\fR -.ad -.RS 13n +.It Dv B307200 307200 baud -.RE - -.sp -.ne 2 -.na -\fB\fBB460800\fR\fR -.ad -.RS 13n +.It Dv B460800 460800 baud -.RE - -.sp -.ne 2 -.na -\fB\fBCSIZE\fR\fR -.ad -.RS 13n +.El +.It Dv CSIZE Character size: -.RE - -.sp -.ne 2 -.na -\fB\fBCS5\fR\fR -.ad -.RS 13n +.Bl -tag -width CIBAUDEXT -compact +.It Dv CS5 5 bits -.RE - -.sp -.ne 2 -.na -\fB\fBCS6\fR\fR -.ad -.RS 13n +.It Dv CS6 6 bits -.RE - -.sp -.ne 2 -.na -\fB\fBCS7\fR\fR -.ad -.RS 13n +.It Dv CS7 7 bits -.RE - -.sp -.ne 2 -.na -\fB\fBCS8\fR\fR -.ad -.RS 13n +.It Dv CS8 8 bits -.RE - -.sp -.ne 2 -.na -\fB\fBCSTOPB\fR\fR -.ad -.RS 13n +.It Dv CSTOPB Send two stop bits, else one -.RE - -.sp -.ne 2 -.na -\fB\fBCREAD\fR\fR -.ad -.RS 13n +.It Dv CREAD Enable receiver -.RE - -.sp -.ne 2 -.na -\fB\fBPARENB\fR\fR -.ad -.RS 13n +.It Dv PARENB Parity enable -.RE - -.sp -.ne 2 -.na -\fB\fBPARODD\fR\fR -.ad -.RS 13n +.It Dv PARODD Odd parity, else even -.RE - -.sp -.ne 2 -.na -\fB\fBHUPCL\fR\fR -.ad -.RS 13n +.It Dv HUPCL Hang up on last close -.RE - -.sp -.ne 2 -.na -\fB\fBCLOCAL\fR\fR -.ad -.RS 13n +.It Dv CLOCAL Local line, else dial-up -.RE - -.sp -.ne 2 -.na -\fB\fBCIBAUD\fR\fR -.ad -.RS 13n +.It Dv CIBAUD Input baud rate, if different from output rate -.RE - -.sp -.ne 2 -.na -\fB\fBPAREXT\fR\fR -.ad -.RS 13n +.It Dv PAREXT Extended parity for mark and space parity -.RE - -.sp -.ne 2 -.na -\fB\fBCRTSXOFF\fR\fR -.ad -.RS 13n +.It Dv CRTSXOFF Enable inbound hardware flow control -.RE - -.sp -.ne 2 -.na -\fB\fBCRTSCTS\fR\fR -.ad -.RS 13n +.It Dv CRTSCTS Enable outbound hardware flow control -.RE - -.sp -.ne 2 -.na -\fB\fBCBAUDEXT\fR\fR -.ad -.RS 13n +.It Dv CBAUDEXT Bit to indicate output speed > B38400 -.RE - -.sp -.ne 2 -.na -\fB\fBCIBAUDEXT\fR\fR -.ad -.RS 13n +.It Dv CIBAUDEXT Bit to indicate input speed > B38400 -.RE - -.sp -.LP -The \fBCBAUD\fR bits together with the \fBCBAUDEXT\fR bit specify the output -baud rate. To retrieve the output speed from the \fBtermios\fR structure -pointed to by \fBtermios_p\fR see the following code segment. -.sp -.in +2 -.nf +.El +.El +.Pp +The +.Dv CBAUD +bits together with the +.Dv CBAUDEXT +bit specify the output baud rate. +To retrieve the output speed from the +.Vt termios +structure pointed to by +.Fa termios_p +see the following code segment. +.Bd -literal -offset 2n speed_t ospeed; if (termios_p->c_cflag & CBAUDEXT) - ospeed = (termios_p->c_cflag & CBAUD) + CBAUD + 1; + ospeed = (termios_p->c_cflag & CBAUD) + CBAUD + 1; else - ospeed = termios_p->c_cflag & CBAUD; -.fi -.in -2 - -.sp -.LP + ospeed = termios_p->c_cflag & CBAUD; +.Ed +.Pp To store the output speed in the termios structure pointed to by -\fBtermios_p\fR see the following code segment. -.sp -.in +2 -.nf +.Fa termios_p +see the following code segment. +.Bd -literal -offset 2n speed_t ospeed; if (ospeed > CBAUD) { - termios_p->c_cflag |= CBAUDEXT; - ospeed -= (CBAUD + 1); -} else - termios_p->c_cflag &= ~CBAUDEXT; - termios_p->c_cflag = - (termios_p->c_cflag & ~CBAUD) | (ospeed & CBAUD); -.fi -.in -2 - -.sp -.LP -The zero baud rate, B0, is used to hang up the connection. If B0 is specified, -the data-terminal-ready signal is not asserted. Normally, this disconnects the -line. -.sp -.LP -If the \fBCIBAUDEXT\fR or \fBCIBAUD\fR bits are not zero, they specify the -input baud rate, with the \fBCBAUDEXT\fR and \fBCBAUD\fR bits specifying the -output baud rate; otherwise, the output and input baud rates are both specified -by the \fBCBAUDEXT\fR and \fBCBAUD\fR bits. The values for the \fBCIBAUD\fR -bits are the same as the values for the \fBCBAUD\fR bits, shifted left -\fBIBSHIFT\fR bits. For any particular hardware, impossible speed changes are -ignored. To retrieve the input speed in the \fBtermios\fR structure pointed to -by \fBtermios_p\fR see the following code segment. -.sp -.in +2 -.nf + termios_p->c_cflag |= CBAUDEXT; + ospeed -= (CBAUD + 1); +} else { + termios_p->c_cflag &= ~CBAUDEXT; +} +termios_p->c_cflag = + (termios_p->c_cflag & ~CBAUD) | (ospeed & CBAUD); +.Ed +.Pp +The zero baud rate, +.Dv B0 , +is used to hang up the connection. +If +.Dv B0 +is specified, the data-terminal-ready signal is not asserted. +Normally, this disconnects the line. +.Pp +If the +.Dv CIBAUDEXT +or +.Dv CIBAUD +bits are not zero, they specify the input baud rate, with the +.Dv CBAUDEXT +and +.Dv CBAUD +bits specifying the output baud rate; otherwise, the output and input baud +rates are both specified by the +.Dv CBAUDEXT +and +.Dv CBAUD +bits. +The values for the +.Dv CIBAUD +bits are the same as the values for the +.Dv CBAUD +bits, shifted left +.Dv IBSHIFT +bits. +For any particular hardware, impossible speed changes are +ignored. +To retrieve the input speed in the +.Vt termios +structure pointed to +by +.Fa termios_p +see the following code segment. +.Bd -literal -offset 2n speed_t ispeed; -if (termios_p->c_cflag & CIBAUDEXT) - ispeed = ((termios_p->c_cflag & CIBAUD) >> IBSHIFT) - + (CIBAUD >> IBSHIFT) + 1; -else - ispeed = (termios_p->c_cflag & CIBAUD) >> IBSHIFT; -.fi -.in -2 - -.sp -.LP -To store the input speed in the \fBtermios\fR structure pointed to by -\fBtermios_p\fR see the following code segment. -.sp -.in +2 -.nf +if (termios_p->c_cflag & CIBAUDEXT) { + ispeed = ((termios_p->c_cflag & CIBAUD) >> IBSHIFT) + + (CIBAUD >> IBSHIFT) + 1; +} else { + ispeed = (termios_p->c_cflag & CIBAUD) >> IBSHIFT; +} +.Ed +.Pp +To store the input speed in the +.Vt termios +structure pointed to by +.Fa termios_p +see the following code segment. +.Bd -literal -offset 2n speed_t ispeed; if (ispeed == 0) { - ispeed = termios_p->c_cflag & CBAUD; -if (termios_p->c_cflag & CBAUDEXT) - ispeed += (CBAUD + 1); + ispeed = termios_p->c_cflag & CBAUD; + if (termios_p->c_cflag & CBAUDEXT) + ispeed += (CBAUD + 1); } - if ((ispeed << IBSHIFT) > CIBAUD) { - termios_p->c_cflag |= CIBAUDEXT; - ispeed -= ((CIBAUD >> IBSHIFT) + 1); -} else - termios_p->c_cflag &= ~CIBAUDEXT; - termios_p->c_cflag = - (termios_p->c_cflag & ~CIBAUD) | - ((ispeed << IBSHIFT) & CIBAUD); -.fi -.in -2 - -.sp -.LP -The \fBCSIZE\fR bits specify the character size in bits for both transmission -and reception. This size does not include the parity bit, if any. If -\fBCSTOPB\fR is set, two stop bits are used; otherwise, one stop bit is used. +if ((ispeed << IBSHIFT) > CIBAUD) { + termios_p->c_cflag |= CIBAUDEXT; + ispeed -= ((CIBAUD >> IBSHIFT) + 1); +} else { + termios_p->c_cflag &= ~CIBAUDEXT; +} +termios_p->c_cflag = + (termios_p->c_cflag & ~CIBAUD) | ((ispeed << IBSHIFT) & CIBAUD); +.Ed +.Pp +The +.Dv CSIZE +bits specify the character size in bits for both transmission and reception. +This size does not include the parity bit, if any. +If +.Dv CSTOPB +is set, two stop bits are used; otherwise, one stop bit is used. For example, at 110 baud, two stops bits are required. -.sp -.LP -If \fBPARENB\fR is set, parity generation and detection is enabled, and a -parity bit is added to each character. If parity is enabled, the \fBPARODD\fR +.Pp +If +.Dv PARENB +is set, parity generation and detection is enabled, and a +parity bit is added to each character. +If parity is enabled, the +.Dv PARODD flag specifies odd parity if set; otherwise, even parity is used. -.sp -.LP -If \fBCREAD\fR is set, the receiver is enabled. Otherwise, no characters are -received. -.sp -.LP -If \fBHUPCL\fR is set, the line is disconnected when the last process with the -line open closes it or terminates. That is, the data-terminal-ready signal is -not asserted. -.sp -.LP -If \fBCLOCAL\fR is set, the line is assumed to be a local, direct connection +.Pp +If +.Dv CREAD +is set, the receiver is enabled. +Otherwise, no characters are received. +.Pp +If +.Dv HUPCL +is set, the line is disconnected when the last process with the +line open closes it or terminates. +That is, the data-terminal-ready signal is not asserted. +.Pp +If +.Dv CLOCAL +is set, the line is assumed to be a local, direct connection with no modem control; otherwise, modem control is assumed. -.sp -.LP -If \fBCRTSXOFF\fR is set, inbound hardware flow control is enabled. -.sp -.LP -If \fBCRTSCTS\fR is set, outbound hardware flow control is enabled. -.sp -.LP -The four possible combinations for the state of \fBCRTSCTS\fR and -\fBCRTSXOFF\fR bits and their interactions are described below. -.sp -.ne 2 -.na -\fBCase A:\fR -.ad -.RS 11n -\fBCRTSCTS\fR off, \fBCRTSXOFF\fR off. In this case the hardware flow control -is disabled. -.RE - -.sp -.ne 2 -.na -\fBCase B:\fR -.ad -.RS 11n -\fBCRTSCTS\fR on, \fBCRTSXOFF\fR off. In this case only outbound hardware flow -control is enabled. The state of CTS signal is used to do outbound flow -control. It is expected that output will be suspended if CTS is low and resumed +.Pp +If +.Dv CRTSXOFF +is set, inbound hardware flow control is enabled. +.Pp +If +.Dv CRTSCTS +is set, outbound hardware flow control is enabled. +.Pp +The four possible combinations for the state of +.Dv CRTSCTS +and +.Dv CRTSXOFF +bits and their interactions are described below. +.Bl -tag -width "Case C:" +.It Sy Case A : +.Dv CRTSCTS +off, +.Dv CRTSXOFF +off. +In this case the hardware flow control is disabled. +.It Sy Case B : +.Dv CRTSCTS +on, +.Dv CRTSXOFF +off. +In this case only outbound hardware flow control is enabled. +The state of CTS signal is used to do outbound flow control. +It is expected that output will be suspended if CTS is low and resumed when CTS is high. -.RE - -.sp -.ne 2 -.na -\fBCase C:\fR -.ad -.RS 11n -\fBCRTSCTS\fR off, \fBCRTSXOFF\fR on. In this case only inbound hardware flow -control is enabled. The state of RTS signal is used to do inbound flow control. +.It Sy Case C : +.Dv CRTSCTS +off, +.Dv CRTSXOFF +on. +In this case only inbound hardware flow control is enabled. +The state of RTS signal is used to do inbound flow control. It is expected that input will be suspended if RTS is low and resumed when RTS is high. -.RE - -.sp -.ne 2 -.na -\fBCase D:\fR -.ad -.RS 11n -\fBCRTSCTS\fR on, \fBCRTSXOFF\fR on. In this case both inbound and outbound -hardware flow control are enabled. Uses the state of CTS signal to do outbound +.It Sy Case D : +.Dv CRTSCTS +on, +.Dv CRTSXOFF +on. +In this case both inbound and outbound hardware flow control are enabled. +Uses the state of CTS signal to do outbound flow control and RTS signal to do inbound flow control. -.RE - -.SS "Local Modes" -.LP -The \fBc_lflag\fR field of the argument structure is used by the line -discipline to control terminal functions. The basic line discipline provides -the following: -.sp -.ne 2 -.na -\fB\fBISIG\fR\fR -.ad -.RS 11n - Enable signals. -.RE - -.sp -.ne 2 -.na -\fB\fBICANON\fR\fR -.ad -.RS 11n +.El +.Ss "Local Modes" +The +.Fa c_lflag +field of the argument structure is used by the line +discipline to control terminal functions. +The basic line discipline provides the following: +.Pp +.Bl -tag -offset 2n -width SIGTTOU -compact +.It Dv ISIG +Enable signals. +.It Dv ICANON Canonical input (erase and kill processing). -.RE - -.sp -.ne 2 -.na -\fB\fBXCASE\fR\fR -.ad -.RS 11n +.It Dv XCASE Canonical upper/lower presentation. -.RE - -.sp -.ne 2 -.na -\fB\fBECHO\fR\fR -.ad -.RS 11n +.It Dv ECHO Enable echo. -.RE - -.sp -.ne 2 -.na -\fB\fBECHOE\fR\fR -.ad -.RS 11n -Echo erase character as \fBBS-SP-BS\fR &. -.RE - -.sp -.ne 2 -.na -\fB\fBECHOK\fR\fR -.ad -.RS 11n -Echo \fBNL\fR after kill character. -.RE - -.sp -.ne 2 -.na -\fB\fBECHONL\fR\fR -.ad -.RS 11n -Echo \fBNL\fR . -.RE - -.sp -.ne 2 -.na -\fB\fBNOFLSH\fR\fR -.ad -.RS 11n +.It Dv ECHOE +Echo erase character as +.Sy BS Ns - Ns Sy SP Ns - Ns Sy BS +&. +.It Dv ECHOK +Echo +.Sy NL +after kill character. +.It Dv ECHONL +Echo +.Sy NL . +.It Dv NOFLSH Disable flush after interrupt or quit. -.RE - -.sp -.ne 2 -.na -\fB\fBTOSTOP\fR\fR -.ad -.RS 11n -Send \fBSIGTTOU\fR for background output. -.RE - -.sp -.ne 2 -.na -\fB\fBECHOCTL\fR\fR -.ad -.RS 11n -Echo control characters as \fIchar,\fR delete as ^?. -.RE - -.sp -.ne 2 -.na -\fB\fBECHOPRT\fR\fR -.ad -.RS 11n +.It Dv TOSTOP +Send +.It Dv SIGTTOU +for background output. +.It Dv ECHOCTL +Echo control characters as +.Em char , +delete as ^?. +.It Dv ECHOPRT Echo erase character as character erased. -.RE - -.sp -.ne 2 -.na -\fB\fBECHOKE\fR\fR -.ad -.RS 11n -\fBBS-SP-BS\fR erase entire line on line kill. -.RE - -.sp -.ne 2 -.na -\fB\fBFLUSHO\fR\fR -.ad -.RS 11n +.It Dv ECHOKE +.Sy BS Ns - Ns Sy SP Ns - Ns Sy BS +erase entire line on line kill. +.It Dv FLUSHO Output is being flushed. -.RE - -.sp -.ne 2 -.na -\fB\fBPENDIN\fR\fR -.ad -.RS 11n -Retype pending input at next read or input character. -.RE - -.sp -.ne 2 -.na -\fB\fBIEXTEN\fR\fR -.ad -.RS 11n +.It Dv PENDIN +Retype pending input at next read or input character. +.It Dv IEXTEN Enable extended (implementation-defined) functions. -.RE - -.sp -.LP -If \fBISIG\fR is set, each input character is checked against the special -control characters INTR, QUIT, SWTCH, SUSP, STATUS, and \fBDSUSP\fR. If an -input character matches one of these control characters, the function -associated with that character is performed. (Note: If SWTCH is set and the -character matches, the character is simply discarded. No other action is -taken.) If \fBISIG\fR is not set, no checking is done. Thus, these special -input functions are possible only if \fBISIG\fR is set. -.sp -.LP -If \fBICANON\fR is set, canonical processing is enabled. This enables the erase +.El +.Pp +If +.Dv ISIG +is set, each input character is checked against the special +control characters +.Sy INTR , +.Sy QUIT , +.Sy SWTCH , +.Sy SUSP , +.Sy STATUS , +and +.Sy DSUSP . +If an input character matches one of these control characters, the function +associated with that character is performed. +.Po +Note: If +.Sy SWTCH +is set and the character matches, the character is simply discarded. +No other action is taken. +.Pc +If +.Dv ISIG +is not set, no checking is done. +Thus, these special +input functions are possible only if +.Dv ISIG +is set. +.Pp +If +.Dv ICANON +is set, canonical processing is enabled. +This enables the erase and kill edit functions, and the assembly of input characters into lines -delimited by \fBNL-c\fR, \fBEOF\fR, \fBEOL\fR, and \fBEOL\fR . If \fBICANON\fR -is not set, read requests are satisfied directly from the input queue. A read -is not satisfied until at least \fBMIN\fR characters have been received or the -timeout value \fBTIME\fR has expired between characters. This allows fast -bursts of input to be read efficiently while still allowing single character -input. The time value represents tenths of seconds. -.sp -.LP -If \fBXCASE\fR is set and \fBICANON\fR is set, an upper case letter is -accepted on input if preceded by a backslash \fB(\e)\fR character, and is -output preceded by a backslash \fB(\e)\fR character. In this mode, the +delimited by +.Sy NL-c , +.Sy EOF , +.Sy EOL , +and +.Sy EOL . +If +.Dv ICANON +is not set, read requests are satisfied directly from the input queue. +A read is not satisfied until at least +.Sy MIN +characters have been received or the timeout value +.Sy TIME +has expired between characters. +This allows fast bursts of input to be read efficiently while still allowing +single character input. +The time value represents tenths of seconds. +.Pp +If +.Dv XCASE +is set and +.Dv ICANON +is set, an upper case letter is +accepted on input if preceded by a backslash +.Ql \e +character, and is output preceded by a backslash +.Ql \e +character. +In this mode, the following escape sequences are generated on output and accepted on input: -.sp - -.sp -.TS -box; -c | c -l | l . -FOR: USE: -_ -` \e' -_ -| \e! -_ -\(ap \e^ -_ -{ \e( -_ -} \e) -_ -\e \e\e -.TE - -.sp -.LP +.Bl -column "FOR:" "USE:" -offset 2n +.It FOR: Ta USE: +.It ` Ta \e' +.It | Ta \e! +.It \(ap Ta \e^ +.It { Ta \e( +.It } Ta \e) +.It \e Ta \e\e +.El +.Pp For example, input A as \ea, \en as \e\en, and \eN as \e\e\en. -.sp -.LP -If \fBECHO\fR is set, characters are echoed as received. -.sp -.LP -When \fBICANON\fR is set, the following echo functions are possible. -.RS +4 -.TP -.ie t \(bu -.el o -If \fBECHO\fR and \fBECHOE\fR are set, and \fBECHOPRT\fR is not set, the -\fBERASE\fR, \fBERASE2\fR, and \fBWERASE\fR characters are echoed as one or -more ASCII BS SP BS, which clears the last character(s) from a \fBCRT\fR screen. -.RE -.RS +4 -.TP -.ie t \(bu -.el o -If \fBECHO\fR, \fBECHOPRT\fR, and \fBIEXTEN\fR are set, the first \fBERASE\fR, -\fBERASE2\fR, and \fBWERASE\fR character in a sequence echoes as a backslash -(\fB\e\fR), followed by the characters being erased. Subsequent \fBERASE\fR and -\fBWERASE\fR characters echo the characters being erased, in reverse order. The -next non-erase character causes a `/' (slash) to be typed before it is echoed. -\fBECHOPRT\fR should be used for hard copy terminals. -.RE -.RS +4 -.TP -.ie t \(bu -.el o -If \fBECHOKE\fR and \fBIEXTEN\fR are set, the kill character is echoed by -erasing each character on the line from the screen (using the mechanism -selected by \fBECHOE\fR and \fBECHOPR\fRa). -.RE -.RS +4 -.TP -.ie t \(bu -.el o -If \fBECHOK\fR is set, and \fBECHOKE\fR is not set, the \fBNL\fR character is -echoed after the kill character to emphasize that the line is deleted. Note -that a `\' (escape) character or an \fBLNEXT\fR character preceding the erase +.Pp +If +.Dv ECHO +is set, characters are echoed as received. +.Pp +When +.Dv ICANON +is set, the following echo functions are possible. +.Bl -bullet -offset indent +.It +If +.Dv ECHO +and +.Dv ECHOE +are set, and +.Dv ECHOPRT +is not set, the +.Sy ERASE , +.Sy ERASE2 , +and +.Sy WERASE +characters are echoed as one or +more ASCII BS SP BS, which clears the last character(s) from a +.Sy CRT +screen. +.It +If +.Dv ECHO , +.Dv ECHOPRT , +and +.Dv IEXTEN +are set, the first +.Sy ERASE , +.Sy ERASE2 , +and +.Sy WERASE +character in a sequence echoes as a backslash +.Ql \e , +followed by the characters being erased. +Subsequent +.Sy ERASE +and +.Sy WERASE +characters echo the characters being erased, in reverse order. +The +next non-erase character causes a +.Ql / +(slash) to be typed before it is echoed. +.Dv ECHOPRT +should be used for hard copy terminals. +.It +If +.Dv ECHOKE +and +.Dv IEXTEN +are set, the kill character is echoed by +erasing each character on the line from the screen (using the mechanism +selected by +.Dv ECHOE +and +.Dv ECHOPR ) . +.It +If +.Dv ECHOK +is set, and +.Dv ECHOKE +is not set, the +.Sy NL +character is +echoed after the kill character to emphasize that the line is deleted. +Note +that a +.Ql \e +(escape) character or an +.Sy LNEXT +character preceding the erase or kill character removes any special function. -.RE -.RS +4 -.TP -.ie t \(bu -.el o -If \fBECHONL\fR is set, the \fBNL\fR character is echoed even if \fBECHO\fR -is not set. This is useful for terminals set to local echo (so called +.It +If +.Dv ECHONL +is set, the +.Sy NL +character is echoed even if +.Dv ECHO +is not set. +This is useful for terminals set to local echo (so called half-duplex). -.RE -.sp -.LP -If \fBECHOCTL\fR and \fBIEXTEN\fR are set, all control characters (characters -with codes between 0 and 37 octal) other than \fBASCII TAB\fR, \fBASCII NL\fR, -the \fBSTART\fR character, and the \fBSTOP\fR character, \fBASCII CR\fR, and -\fBASCII BS\fR are echoed as ^ \fBX,\fR where \fBX\fR is the character given by -adding 100 octal to the code of the control character (so that the character -with octal code 1 is echoed as ^ \fBA),\fR and the \fBASCII DEL\fR character, -with code 177 octal, is echoed as ^ \fB?\fR. -.sp -.LP -If \fBNOFLSH\fR is set, the normal flush of the input and output queues -associated with the \fBINTR\fR, \fBQUIT\fR, \fBSTATUS\fR, and \fBSUSP\fR -characters is not done. This bit should be set when restarting system calls -that read from or write to a terminal (see \fBsigaction\fR(2)\|). -.sp -.LP -If \fBTOSTOP\fR and \fBIEXTEN\fR are set, the signal \fBSIGTTOU\fR is sent to +.El +.Pp +If +.Dv ECHOCTL +and +.Dv IEXTEN +are set, all control characters (characters +with codes between 0 and 37 octal) other than +.Sy ASCII TAB , +.Sy ASCII NL , +the +.Sy START +character, and the +.Sy STOP +character, +.Sy ASCII CR , +and +.Sy ASCII BS +are echoed as +.No ^ Ns Em X , +where +.Em X +is the character given by adding +.Ql 100 +octal to the code of the control character (so +that the character with octal code +.Ql 1 +is echoed as +.No ^ Ns Sy A ) , +and the +.Sy ASCII DEL +character, +with code +.Ql 177 +octal, is echoed as +.No ^ Ns Sy \&? . +.Pp +If +.Dv NOFLSH +is set, the normal flush of the input and output queues +associated with the +.Sy INTR , +.Sy QUIT , +.Sy STATUS , +and +.Sy SUSP +characters is not done. +This bit should be set when restarting system calls +that read from or write to a terminal +.Po +see +.Xr sigaction 2 +.Pc . +.Pp +If +.Dv TOSTOP +and +.Dv IEXTEN +are set, the signal +.Dv SIGTTOU +is sent to a process that tries to write to its controlling terminal if it is not in the -foreground process group for that terminal. This signal normally stops the -process. Otherwise, the output generated by that process is output to the -current output stream. Processes that are blocking or ignoring \fBSIGTTOU\fR +foreground process group for that terminal. +This signal normally stops the process. +Otherwise, the output generated by that process is output to the +current output stream. +Processes that are blocking or ignoring +.Dv SIGTTOU signals are excepted and allowed to produce output, if any. -.sp -.LP -If \fBFLUSHO\fR and \fBIEXTEN\fR are set, data written to the terminal is -discarded. This bit is set when the \fBFLUSH\fR character is typed. A program -can cancel the effect of typing the \fBFLUSH\fR character by clearing -\fBFLUSHO\fR. -.sp -.LP -If \fBPENDIN\fR and \fBIEXTEN\fR are set, any input that has not yet been read -is reprinted when the next character arrives as input. \fBPENDIN\fR is then +.Pp +If +.Dv FLUSHO +and +.Dv IEXTEN +are set, data written to the terminal is +discarded. +This bit is set when the +.Sy FLUSH +character is typed. +A program can cancel the effect of typing the +.Sy FLUSH +character by clearing +.Dv FLUSHO . +.Pp +If +.Dv PENDIN +and +.Dv IEXTEN +are set, any input that has not yet been read +is reprinted when the next character arrives as input. +.Dv PENDIN +is then automatically cleared. -.sp -.LP -If \fBIEXTEN\fR is set, the following implementation-defined functions are -enabled: special characters ( \fBWERASE\fR, \fBREPRINT\fR, \fBDISCARD\fR, and -\fBLNEXT\fR) and local flags ( \fBTOSTOP\fR, \fBECHOCTL\fR, \fBECHOPRT\fR, -\fBECHOKE\fR, \fBFLUSHO\fR, and \fBPENDIN\fR). -.SS "Minimum and Timeout" -.LP -The \fBMIN\fR and \fBTIME\fR values were described previously, in the -subsection, \fBNon-canonical Mode Input Processing\fR. The initial value of -\fBMIN\fR is 1, and the initial value of \fBTIME\fR is 0. -.SS "Terminal Size" -.LP +.Pp +If +.Dv IEXTEN +is set, the following implementation-defined functions are +enabled: special characters ( +.Sy WERASE , +.Sy REPRINT , +.Sy DISCARD , +and +.Sy LNEXT ) +and local flags ( +.Dv TOSTOP , +.Dv ECHOCTL , +.Dv ECHOPRT , +.Dv ECHOKE , +.Dv FLUSHO , +and +.Dv PENDIN ) . +.Ss "Minimum and Timeout" +The +.Sy MIN +and +.Sy TIME +values were described previously, in the +subsection, +.Sy Non-canonical Mode Input Processing . +The initial value of +.Sy MIN +is 1, and the initial value of +.Sy TIME +is 0. +.Ss "Terminal Size" The number of lines and columns on the terminal's display is specified in the -\fBwinsize\fR structure defined by \fBsys/termios.h\fR and includes the -following members: -.sp -.in +2 -.nf +.Vt winsize +structure defined by +.In sys/termios.h +and includes the following members: +.Bd -literal -offset 2n unsigned short ws_row; /* rows, in characters */ -unsigned short ws_col; /* columns, in characters */ -unsigned short ws_xpixel; /* horizontal size, in pixels */ -unsigned short ws_ypixel; /* vertical size, in pixels */ -.fi -.in -2 - -.SS "Termio Structure" -.LP -The SunOS/SVR4 \fBtermio\fR structure is used by some \fBioctl\fRs; it is -defined by \fBsys/termio.h\fR and includes the following members: -.sp -.in +2 -.nf -unsigned short c_iflag; /* input modes */ -unsigned short c_oflag; /* output modes */ -unsigned short c_cflag; /* control modes */ -unsigned short c_lflag; /* local modes */ -char c_line; /* line discipline */ -unsigned char c_cc[NCC]; /* control chars */ -.fi -.in -2 - -.sp -.LP -The special control characters are defined by the array \fBc_cc\fR. The -symbolic name \fBNCC\fR is the size of the Control-character array and is also -defined by \fBtermio.h\fR. The relative positions, subscript names, and typical -default values for each function are as follows: -.sp - -.sp -.TS -box; -c | c | c -l | l | l . -Relative Positions Subscript Names Typical Default Values -_ -0 VINTR EXT -_ -1 VQUIT FS -_ -2 VERASE DEL -_ -3 VKILL NAK -_ -4 VEOF EOT -_ -5 VEOL NUL -_ -6 VEOL2 NUL -_ -7 Reserved -.TE - -.sp -.LP -The \fBMIN\fR values is stored in the \fBVMIN\fR element of the \fBc_cc\fR -array; the \fBTIME\fR value is stored in the \fBVTIME\fR element of the -\fBc_cc\fR array. The \fBVMIN\fR element is the same element as the -\fBVEOF\fR element; the \fBVTIME\fR element is the same element as the -\fBVEOL\fR element. -.sp -.LP -The calls that use the \fBtermio\fR structure only affect the flags and control -characters that can be stored in the \fBtermio\fR structure; all other flags -and control characters are unaffected. -.SS "Modem Lines" -.LP +unsigned short ws_col; /* columns, in characters */ +unsigned short ws_xpixel; /* horizontal size, in pixels */ +unsigned short ws_ypixel; /* vertical size, in pixels */ +.Ed +.Ss "Termio Structure" +The SunOS/SVR4 +.Vt termio +structure is used by some +.Fn ioctl Ns s ; +it is defined by +.In sys/termio.h +and includes the following members: +.Bd -literal -offset 2n +unsigned short c_iflag; /* input modes */ +unsigned short c_oflag; /* output modes */ +unsigned short c_cflag; /* control modes */ +unsigned short c_lflag; /* local modes */ +char c_line; /* line discipline */ +unsigned char c_cc[NCC]; /* control chars */ +.Ed +.Pp +The special control characters are defined by the array +.Fa c_cc . +The symbolic name +.Dv NCC +is the size of the Control-character array and is also +defined by +.In termio.h . +The relative positions, subscript names, and typical +default values for each function are as follows: +.Bl -column "Relative Positions" "Subscript Names" "Typical Default Values" +.It Relative Positions Ta Subscript Names Ta Typical Default Values +.It 0 Ta VINTR Ta EXT +.It 1 Ta VQUIT Ta FS +.It 2 Ta VERASE Ta DEL +.It 3 Ta VKILL Ta NAK +.It 4 Ta VEOF Ta EOT +.It 5 Ta VEOL Ta NUL +.It 6 Ta VEOL2 Ta NUL +.It 7 Ta Reserved Ta +.El +.Pp +The +.Sy MIN +values is stored in the +.Dv VMIN +element of the +.Fa c_cc +array; the +.Sy TIME +value is stored in the +.Dv VTIME +element of the +.Fa c_cc +array. +The +.Dv VMIN +element is the same element as the +.Dv VEOF +element; the +.Dv VTIME +element is the same element as the +.Dv VEOL +element. +.Pp +The calls that use the +.Va termio +structure only affect the flags and control +characters that can be stored in the +.Vt termio +structure; all other flags and control characters are unaffected. +.Ss "Modem Lines" On special files representing serial ports, modem control lines can be read. -Control lines (if the underlying hardware supports it) may also be changed. -Status lines are read-only. The following modem control and status lines may be -supported by a device; they are defined by \fBsys/termios.h\fR: -.sp -.ne 2 -.na -\fB\fBTIOCM_LE\fR\fR -.ad -.RS 13n - line enable -.RE - -.sp -.ne 2 -.na -\fB\fBTIOCM_DTR\fR\fR -.ad -.RS 13n +Control lines (if the underlying hardware supports it) may also be changed. +Status lines are read-only. +The following modem control and status lines may be +supported by a device; they are defined by +.In sys/termios.h : +.Pp +.Bl -tag -width "TIOCM_DTR" -compact -offset 2n +.It Dv TIOCM_LE +line enable +.It Dv TIOCM_DTR data terminal ready -.RE - -.sp -.ne 2 -.na -\fB\fBTIOCM_RTS\fR\fR -.ad -.RS 13n +.It Dv TIOCM_RTS request to send -.RE - -.sp -.ne 2 -.na -\fB\fBTIOCM_ST\fR\fR -.ad -.RS 13n +.It Dv TIOCM_ST secondary transmit -.RE - -.sp -.ne 2 -.na -\fB\fBTIOCM_SR\fR\fR -.ad -.RS 13n +.It Dv TIOCM_SR secondary receive -.RE - -.sp -.ne 2 -.na -\fB\fBTIOCM_CTS\fR\fR -.ad -.RS 13n +.It Dv TIOCM_CTS clear to send -.RE - -.sp -.ne 2 -.na -\fB\fBTIOCM_CAR\fR\fR -.ad -.RS 13n +.It Dv TIOCM_CAR carrier detect -.RE - -.sp -.ne 2 -.na -\fB\fBTIOCM_RNG\fR\fR -.ad -.RS 13n +.It Dv TIOCM_RNG ring -.RE - -.sp -.ne 2 -.na -\fB\fBTIOCM_DSR\fR\fR -.ad -.RS 13n +.It Dv TIOCM_DSR data set ready -.RE - -.sp -.LP -\fBTIOCM_CD\fR is a synonym for \fBTIOCM_CAR\fR, and \fBTIOCM_RI\fR is a -synonym for \fBTIOCM_RNG\fR. Not all of these are necessarily supported by any +.El +.Pp +.Dv TIOCM_CD +is a synonym for +.Dv TIOCM_CAR , +and +.Dv TIOCM_RI +is a synonym for +.Dv TIOCM_RNG . +Not all of these are necessarily supported by any particular device; check the manual page for the device in question. -.sp -.LP +.Pp The software carrier mode can be enabled or disabled using the -\fBTIOCSSOFTCAR\fR \fBioctl\fR. If the software carrier flag for a line is off, -the line pays attention to the hardware carrier detect (DCD) signal. The -\fBtty\fR device associated with the line cannot be opened until \fBDCD\fR is -asserted. If the software carrier flag is on, the line behaves as if \fBDCD\fR +.Dv TIOCSSOFTCAR +.Fn ioctl . +If the software carrier flag for a line is off, +the line pays attention to the hardware carrier detect (DCD) signal. +The +.Sy tty +device associated with the line cannot be opened until +.Sy DCD +is asserted. +If the software carrier flag is on, the line behaves as if +.Sy DCD is always asserted. -.sp -.LP +.Pp The software carrier flag is usually turned on for locally connected terminals or other devices, and is off for lines with modems. -.sp -.LP -To be able to issue the \fBTIOCGSOFTCAR\fR and \fBTIOCSSOFTCAR\fR \fBioctl\fR -calls, the \fBtty\fR line should be opened with \fBO_NDELAY\fR so that the -\fBopen\fR(2) will not wait for the carrier. -.SS "Default Values" -.LP -The initial \fBtermios\fR values upon driver open is configurable. This is -accomplished by setting the "ttymodes" property in the file -\fB/kernel/drv/options.conf\fR. Since this property is assigned during system -initialization, any change to the "ttymodes" property will not take effect -until the next reboot. The string value assigned to this property should be in -the same format as the output of the \fBstty\fR(1) command with the -g option. -.sp -.LP -If this property is undefined, the following \fBtermios\fR modes are in -effect. The initial input control value is \fBBRKINT\fR, \fBICRNL\fR, -\fBIXON\fR, \fBIMAXBEL\fR. The initial output control value is \fBOPOST\fR, -\fBONLCR\fR, \fBTAB3\fR. The initial hardware control value is \fBB9600\fR, -\fBCS8\fR, \fBCREAD\fR. The initial line-discipline control value is -\fBISIG\fR, \fBICANON\fR, \fBIEXTEN\fR, \fBECHO\fR, \fBECHOK\fR, \fBECHOE\fR, -\fBECHOKE\fR, \fBECHOCTL\fR. -.SH IOCTLS -.LP -The \fBioctl\fRs supported by devices and \fBSTREAMS\fR modules providing the -\fBtermios\fR(3C) interface are listed below. Some calls may not be supported -by all devices or modules. The functionality provided by these calls is also +.Pp +To be able to issue the +.Dv TIOCGSOFTCAR +and +.Dv TIOCSSOFTCAR +.Fn ioctl +calls, the +.Sy tty +line should be opened with +.Dv O_NDELAY +so that the +.Xr open 2 +will not wait for the carrier. +.Ss "Default Values" +The initial +.Vt termios +values upon driver open is configurable. +This is accomplished by setting the "ttymodes" property in the file +.Pa /kernel/drv/options.conf . +Since this property is assigned during system +initialization, any change to the "ttymodes" property will not take effect +until the next reboot. +The string value assigned to this property should be in +the same format as the output of the +.Xr stty 1 +command with the -g option. +.Pp +If this property is undefined, the following +.Vt termios +modes are in effect. +The initial input control value is +.Dv BRKINT , +.Dv ICRNL , +.Dv IXON , +.Dv IMAXBEL . +The initial output control value is +.Dv OPOST , +.Dv ONLCR , +.Dv TAB3 . +The initial hardware control value is +.Dv B9600 , +.Dv CS8 , +.Dv CREAD . +The initial line-discipline control value is +.Dv ISIG , +.Dv ICANON , +.Dv IEXTEN , +.Dv ECHO , +.Dv ECHOK , +.Dv ECHOE , +.Dv ECHOKE , +.Dv ECHOCTL . +.Sh IOCTLS +The +.Fn ioctl Ns s +supported by devices and +.Sy STREAMS +modules providing the +.Xr termios 3C +interface are listed below. +Some calls may not be supported by all devices or modules. +The functionality provided by these calls is also available through the preferred function call interface specified on -\fBtermios\fR. -.sp -.ne 2 -.na -\fB\fBTCGETS\fR\fR -.ad -.RS 16n -The argument is a pointer to a \fBtermios\fR structure. The current terminal -parameters are fetched and stored into that structure. -.RE - -.sp -.ne 2 -.na -\fB\fBTCSETS\fR\fR -.ad -.RS 16n -The argument is a pointer to a \fBtermios\fR structure. The current terminal -parameters are set from the values stored in that structure. The change is -immediate. -.RE - -.sp -.ne 2 -.na -\fB\fBTCSETSW\fR\fR -.ad -.RS 16n -The argument is a pointer to a \fBtermios\fR structure. The current terminal -parameters are set from the values stored in that structure. The change occurs -after all characters queued for output have been transmitted. This form should -be used when changing parameters that affect output. -.RE - -.sp -.ne 2 -.na -\fB\fBTCSETSF\fR\fR -.ad -.RS 16n -The argument is a pointer to a \fBtermios\fR structure. The current terminal -parameters are set from the values stored in that structure. The change occurs -after all characters queued for output have been transmitted; all characters -queued for input are discarded and then the change occurs. -.RE - -.sp -.ne 2 -.na -\fB\fBTCGETA\fR\fR -.ad -.RS 16n -The argument is a pointer to a \fBtermio\fR structure. The current terminal -parameters are fetched, and those parameters that can be stored in a -\fBtermio\fR structure are stored into that structure. -.RE - -.sp -.ne 2 -.na -\fB\fBTCSETA\fR\fR -.ad -.RS 16n -The argument is a pointer to a \fBtermio\fR structure. Those terminal -parameters that can be stored in a \fBtermio\fR structure are set from the -values stored in that structure. The change is immediate. -.RE - -.sp -.ne 2 -.na -\fB\fBTCSETAW\fR\fR -.ad -.RS 16n -The argument is a pointer to a \fBtermio\fR structure. Those terminal -parameters that can be stored in a \fBtermio\fR structure are set from the -values stored in that structure. The change occurs after all characters queued -for output have been transmitted. This form should be used when changing -parameters that affect output. -.RE - -.sp -.ne 2 -.na -\fB\fBTCSETAF\fR\fR -.ad -.RS 16n -The argument is a pointer to a \fBtermio\fR structure. Those terminal -parameters that can be stored in a \fBtermio\fR structure are set from the -values stored in that structure. The change occurs after all characters queued +.Nm termios . +.Bl -tag -width TIOCSSOFTCAR +.It Dv TCGETS +The argument is a pointer to a +.Vt termios +structure. +The current terminal parameters are fetched and stored into that structure. +.It Dv TCSETS +The argument is a pointer to a +.Vt termios +structure. +The current terminal parameters are set from the values stored in that structure. +The change is immediate. +.It Dv TCSETSW +The argument is a pointer to a +.Vt termios +structure. +The current terminal parameters are set from the values stored in that structure. +The change occurs after all characters queued for output have been transmitted. +This form should be used when changing parameters that affect output. +.It Dv TCSETSF +The argument is a pointer to a +.Vt termios +structure. +The current terminal parameters are set from the values stored in that structure. +The change occurs after all characters queued for output have been transmitted; +all characters queued for input are discarded and then the change occurs. +.It Dv TCGETA +The argument is a pointer to a +.Vt termio +structure. +The current terminal parameters are fetched, and those parameters that can be +stored in a +.Vt termio +structure are stored into that structure. +.It Dv TCSETA +The argument is a pointer to a +.Vt termio +structure. +Those terminal parameters that can be stored in a +.Vt termio +structure are set from the values stored in that structure. +The change is immediate. +.It Dv TCSETAW +The argument is a pointer to a +.Vt termio +structure. +Those terminal parameters that can be stored in a +.Vt termio +structure are set from +the values stored in that structure. +The change occurs after all characters queued for output have been transmitted. +This form should be used when changing parameters that affect output. +.It Dv TCSETAF +The argument is a pointer to a +.Vt termio +structure. +Those terminal parameters that can be stored in a +.Vt termio +structure are set from the values stored in that structure. +The change occurs after all characters queued for output have been transmitted; all characters queued for input are discarded and then the change occurs. -.RE - -.sp -.ne 2 -.na -\fB\fBTCSBRK\fR\fR -.ad -.RS 16n -The argument is an \fBint\fR value. Wait for the output to drain. If the -argument is \fB0\fR, then send a break (zero valued bits for 0.25 seconds). -.RE - -.sp -.ne 2 -.na -\fB\fBTCXONC\fR\fR -.ad -.RS 16n -Start/stop control. The argument is an \fBint\fR value. If the argument is -\fB0\fR, suspend output; if \fB1\fR, restart suspended output; if \fB2\fR, -suspend input; if \fB3\fR, restart suspended input. -.RE - -.sp -.ne 2 -.na -\fB\fBTCFLSH\fR\fR -.ad -.RS 16n -The argument is an \fBint\fR value. If the argument is \fB0\fR, flush the input -queue; if \fB1\fR, flush the output queue; if \fB2\fR, flush both the input and -output queues. -.RE - -.sp -.ne 2 -.na -\fB\fBTIOCGPGRP\fR\fR -.ad -.RS 16n -The argument is a pointer to a \fBpid_t\fR. Set the value of that \fBpid_t\fR -to the process group \fBID\fR of the foreground process group associated with -the terminal. See \fBtermios\fR(3C) for a description of \fBTCGETPGRP\fR. -.RE - -.sp -.ne 2 -.na -\fB\fBTIOCSPGRP\fR\fR -.ad -.RS 16n -The argument is a pointer to a \fBpid_t\fR. Associate the process group whose -process group \fBID\fR is specified by the value of that \fBpid_t\fR with the -terminal. The new process group value must be in the range of valid process -group \fBID\fR values. Otherwise, the error \fBEPERM\fR is returned. -.RE - -.sp -.ne 2 -.na -\fB\fBTIOCGSID\fR\fR -.ad -.RS 16n -The argument is a pointer to a \fBpid_t\fR. The session ID of the terminal is -fetched and stored in the \fBpid_t\fR. -.RE - -.sp -.ne 2 -.na -\fB\fBTIOCGWINSZ\fR\fR -.ad -.RS 16n -The argument is a pointer to a \fBwinsize\fR structure. The terminal driver's +.It Dv TCSBRK +The argument is an +.Vt int +value. +Wait for the output to drain. +If the argument is +.Sy 0 , +then send a break (zero valued bits for 0\&.25 seconds). +.It Dv TCXONC +Start/stop control. +The argument is an +.Vt int +value. +If the argument is +.Sy 0 , +suspend output; if +.Sy 1 , +restart suspended output; if +.Sy 2 , +suspend input; if +.Sy 3 , +restart suspended input. +.It Dv TCFLSH +The argument is an +.Vt int +value. +If the argument is +.Sy 0 , +flush the input queue; if +.Sy 1 , +flush the output queue; if +.Sy 2 , +flush both the input and output queues. +.It Dv TIOCGPGRP +The argument is a pointer to a +.Vt pid_t . +Set the value of that +.Vt pid_t +to the process group +.Sy ID +of the foreground process group associated with the terminal. +See +.Xr termios 3C +for a description of +.Dv TCGETPGRP . +.It Dv TIOCSPGRP +The argument is a pointer to a +.Vt pid_t . +Associate the process group whose +process group +.Sy ID +is specified by the value of that +.Vt pid_t +with the terminal. +The new process group value must be in the range of valid process +group +.Sy ID +values. +Otherwise, the error +.Er EPERM +is returned. +.It Dv TIOCGSID +The argument is a pointer to a +.Vt pid_t . +The session ID of the terminal is fetched and stored in the +.Vt pid_t . +.It Dv TIOCGWINSZ +The argument is a pointer to a +.Vt winsize +structure. +The terminal driver's notion of the terminal size is stored into that structure. -.RE - -.sp -.ne 2 -.na -\fB\fBTIOCSWINSZ\fR\fR -.ad -.RS 16n -The argument is a pointer to a \fBwinsize\fR structure. The terminal driver's +.It Dv TIOCSWINSZ +The argument is a pointer to a +.Vt winsize +structure. +The terminal driver's notion of the terminal size is set from the values specified in that structure. -If the new sizes are different from the old sizes, a \fBSIGWINCH\fR signal is -set to the process group of the terminal. -.RE - -.sp -.ne 2 -.na -\fB\fBTIOCMBIS\fR\fR -.ad -.RS 16n -The argument is a pointer to an \fBint\fR whose value is a mask containing -modem control lines to be turned on. The control lines whose bits are set in +If the new sizes are different from the old sizes, a +.Dv SIGWINCH +signal is set to the process group of the terminal. +.It Dv TIOCMBIS +The argument is a pointer to an +.Vt int +whose value is a mask containing modem control lines to be turned on. +The control lines whose bits are set in the argument are turned on; no other control lines are affected. -.RE - -.sp -.ne 2 -.na -\fB\fBTIOCMBIC\fR\fR -.ad -.RS 16n -The argument is a pointer to an \fBint\fR whose value is a mask containing -modem control lines to be turned off. The control lines whose bits are set in +.It Dv TIOCMBIC +The argument is a pointer to an +.Vt int +whose value is a mask containing modem control lines to be turned off. +The control lines whose bits are set in the argument are turned off; no other control lines are affected. -.RE - -.sp -.ne 2 -.na -\fB\fBTIOCMGET\fR\fR -.ad -.RS 16n -The argument is a pointer to an \fBint\fR. The current state of the modem -status lines is fetched and stored in the \fBint\fR pointed to by the -argument. -.RE - -.sp -.ne 2 -.na -\fB\fBTIOCMSET\fR\fR -.ad -.RS 16n -The argument is a pointer to an \fBint\fR containing a new set of modem -control lines. The modem control lines are turned on or off, depending on +.It Dv TIOCMGET +The argument is a pointer to an +.Vt int . +The current state of the modem +status lines is fetched and stored in the +.Vt int +pointed to by the argument. +.It Dv TIOCMSET +The argument is a pointer to an +.Vt int +containing a new set of modem control lines. +The modem control lines are turned on or off, depending on whether the bit for that mode is set or clear. -.RE - -.sp -.ne 2 -.na -\fB\fBTIOCSPPS\fR\fR -.ad -.RS 16n -The argument is a pointer to an \fBint\fR that determines whether -pulse-per-second event handling is to be enabled (non-zero) or disabled (zero). +.It Dv TIOCSPPS +The argument is a pointer to an +.Vt int +that determines whether pulse-per-second event handling is to be enabled +(non-zero) or disabled (zero). If a one-pulse-per-second reference clock is attached to the serial line's data -carrier detect input, the local system clock will be calibrated to it. A clock -with a high error, that is, a deviation of more than 25 microseconds per tick, -is ignored. -.RE - -.sp -.ne 2 -.na -\fB\fBTIOCGPPS\fR\fR -.ad -.RS 16n -The argument is a pointer to an \fBint\fR, in which the state of the even -handling is returned. The \fBint\fR is set to a non-zero value if -pulse-per-second (PPS) handling has been enabled. Otherwise, it is set to zero. -.RE - -.sp -.ne 2 -.na -\fB\fBTIOCGSOFTCAR\fR\fR -.ad -.RS 16n -The argument is a pointer to an \fBint\fR whose value is \fB1\fR or \fB0\fR, +carrier detect input, the local system clock will be calibrated to it. +A clock with a high error, that is, a deviation of more than 25 microseconds +per tick, is ignored. +.It Dv TIOCGPPS +The argument is a pointer to an +.Vt int , +in which the state of the even handling is returned. +The +.Vt int +is set to a non-zero value if pulse-per-second (PPS) handling has been enabled. +Otherwise, it is set to zero. +.It Dv TIOCGSOFTCAR +The argument is a pointer to an +.Vt int +whose value is +.Sy 1 +or +.Sy 0 , depending on whether the software carrier detect is turned on or off. -.RE - -.sp -.ne 2 -.na -\fB\fBTIOCSSOFTCAR\fR\fR -.ad -.RS 16n -The argument is a pointer to an \fBint\fR whose value is \fB1\fR or \fB0\fR. -The value of the integer should be \fB0\fR to turn off software carrier, or -\fB1\fR to turn it on. -.RE - -.sp -.ne 2 -.na -\fB\fBTIOCGPPSEV\fR\fR -.ad -.RS 16n -The argument is a pointer to a \fBstruct\fR \fBppsclockev\fR. This structure -contains the following members: -.sp -.in +2 -.nf +.It Dv TIOCSSOFTCAR +The argument is a pointer to an +.Vt int +whose value is +.Sy 1 +or +.Sy 0 . +The value of the integer should be +.Sy 0 +to turn off software carrier, or +.Sy 1 +to turn it on. +.It Dv TIOCGPPSEV +The argument is a pointer to a +.Vt "struct ppsclockev" . +This structure contains the following members: +.Bd -literal -offset 2n struct timeval tv; uint32_t serial; -.fi -.in -2 - -"tv" is the system clock timestamp when the event (pulse on the \fBDCD\fR pin) -occurred. "serial" is the ordinal of the event, which each consecutive event -being assigned the next ordinal. The first event registered gets a "serial" -value of \fB1\fR. The \fBTIOCGPPSEV\fR returns the last event registered; -multiple calls will persistently return the same event until a new one is -registered. In addition to time stamping and saving the event, if it is of +.Ed +.Pp +.Fa tv +is the system clock timestamp when the event (pulse on the +.Sy DCD +pin) occurred. +.Fa serial +is the ordinal of the event, which each consecutive event +being assigned the next ordinal. +The first event registered gets a +.Fa serial +value of +.Sy 1 . +The +.Dv TIOCGPPSEV +returns the last event registered; multiple calls will persistently return the +same event until a new one is registered. +In addition to time stamping and saving the event, if it is of one-second period and of consistently high accuracy, the local system clock will automatically calibrate to it. -.RE - -.SH FILES -.LP -Files in or under /\fBdev\fR -.SH SEE ALSO -.LP -\fBstty\fR(1), \fBfork\fR(2), \fBgetpgid\fR(2), \fBgetsid\fR(2), -\fBioctl\fR(2), \fBsetsid\fR(2), \fBsigaction\fR(2), \fBsignal\fR(3C), -\fBtcsetpgrp\fR(3C), \fBtermios\fR(3C), \fBsignal.h\fR(3HEAD), -\fBstreamio\fR(7I) +.El +.Sh FILES +Files in or under +.Pa /dev +.Sh SEE ALSO +.Xr stty 1 , +.Xr fork 2 , +.Xr getpgid 2 , +.Xr getsid 2 , +.Xr ioctl 2 , +.Xr setsid 2 , +.Xr sigaction 2 , +.Xr signal 3C , +.Xr tcsetpgrp 3C , +.Xr termios 3C , +.Xr signal.h 3HEAD , +.Xr streamio 7I diff --git a/usr/src/man/man7i/termiox.7i b/usr/src/man/man7i/termiox.7i index 67daa26abc..9fa7597d56 100644 --- a/usr/src/man/man7i/termiox.7i +++ b/usr/src/man/man7i/termiox.7i @@ -1,79 +1,110 @@ -'\" te .\" Copyright 1989 AT&T .\" Copyright (C) 1999, Sun Microsystems, Inc. All Rights Reserved -.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. -.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. -.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH TERMIOX 7I "April 9, 2016" -.SH NAME -termiox \- extended general terminal interface -.SH DESCRIPTION -.LP -The extended general terminal interface supplements the \fBtermio\fR(7I) +.\" Copyright (c) 2017, Joyent, Inc. +.\" The contents of this file are subject to the terms of the +.\" Common Development and Distribution License (the "License"). +.\" You may not use this file except in compliance with the License. +.\" +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE +.\" or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions +.\" and limitations under the License. +.\" +.\" When distributing Covered Code, include this CDDL HEADER in each +.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. +.\" If applicable, add the following below this CDDL HEADER, with the +.\" fields enclosed by brackets "[]" replaced with your own identifying +.\" information: Portions Copyright [yyyy] [name of copyright owner] +.Dd October 29, 2017 +.Dt TERMIOX 7I +.Os +.Sh NAME +.Nm termiox +.Nd extended general terminal interface +.Sh DESCRIPTION +The extended general terminal interface supplements the +.Xr termio 7I general terminal interface by adding support for asynchronous hardware flow control, isochronous flow control and clock modes, and local implementations of -additional asynchronous features. Some systems may not support all of these -capabilities because of either hardware or software limitations. Other systems -may not permit certain functions to be disabled. In these cases the -appropriate bits will be ignored. See <\fBsys/termiox.h\fR> for your system to -find out which capabilities are supported. -.SS "Hardware Flow Control Modes" -.LP -Hardware flow control supplements the \fBtermio\fR(7I) \fBIXON\fR, \fBIXOFF\fR, -and \fBIXANY\fR character flow control. Character flow control occurs when one +additional asynchronous features. +Some systems may not support all of these +capabilities because of either hardware or software limitations. +Other systems may not permit certain functions to be disabled. +In these cases the appropriate bits will be ignored. +See +.In sys/termiox.h +for your system to find out which capabilities are supported. +.Ss "Hardware Flow Control Modes" +Hardware flow control supplements the +.Xr termio 7I +.Dv IXON , +.Dv IXOFF , +and +.Dv IXANY +character flow control. +Character flow control occurs when one device controls the data transfer of another device by the insertion of control -characters in the data stream between devices. Hardware flow control occurs +characters in the data stream between devices. +Hardware flow control occurs when one device controls the data transfer of another device using electrical -control signals on wires (circuits) of the asynchronous interface. Isochronous +control signals on wires (circuits) of the asynchronous interface. +Isochronous hardware flow control occurs when one device controls the data transfer of -another device by asserting or removing the transmit clock signals of that -device. Character flow control and hardware flow control may be simultaneously +another device by asserting or removing the transmit clock signals of that +device. +Character flow control and hardware flow control may be simultaneously set. -.sp -.LP +.Pp In asynchronous, full duplex applications, the use of the Electronic Industries Association's EIA-232-D Request To Send (RTS) and Clear To Send (CTS) circuits -is the preferred method of hardware flow control. An interface to other +is the preferred method of hardware flow control. +An interface to other hardware flow control methods is included to provide a standard interface to these existing methods. -.sp -.LP -The EIA-232-D standard specified only unidirectional hardware flow control - +.Pp +The EIA-232-D standard specified only unidirectional hardware flow control \(em the Data Circuit-terminating Equipment or Data Communications Equipment (DCE) -indicates to the Data Terminal Equipment (DTE) to stop transmitting data. The -\fBtermiox\fR interface allows both unidirectional and bidirectional hardware +indicates to the Data Terminal Equipment (DTE) to stop transmitting data. +The +.Nm +interface allows both unidirectional and bidirectional hardware flow control; when bidirectional flow control is enabled, either the DCE or DTE can indicate to each other to stop transmitting data across the interface. -Note: It is assumed that the asynchronous port is configured as a DTE. If the +Note: It is assumed that the asynchronous port is configured as a DTE. +If the connected device is also a DTE and not a DCE, then DTE to DTE (for example, terminal or printer connected to computer) hardware flow control is possible by using a null modem to interconnect the appropriate data and control circuits. -.SS "Clock Modes" -.LP +.Ss "Clock Modes" Isochronous communication is a variation of asynchronous communication whereby two communicating devices may provide transmit and/or receive clock signals to -one another. Incoming clock signals can be taken from the baud rate generator -on the local isochronous port controller, from CCITT V.24 circuit 114, -Transmitter Signal Element Timing - DCE source (EIA-232-D pin 15), or from -CCITT V.24 circuit 115, Receiver Signal Element Timing - DCE source (EIA-232-D -pin 17). Outgoing clock signals can be sent on CCITT V.24 circuit 113, -Transmitter Signal Element Timing - DTE source (EIA-232-D pin 24), on CCITT -V.24 circuit 128, Receiver Signal Element Timing - DTE source (no EIA-232-D +one another. +Incoming clock signals can be taken from the baud rate generator +on the local isochronous port controller, from CCITT V\.24 circuit 114, +Transmitter Signal Element Timing - DCE source (EIA-232-D pin 15), or from +CITT V\.24 circuit 115, Receiver Signal Element Timing - DCE source (EIA-232-D +pin 17). +Outgoing clock signals can be sent on CCITT V\.24 circuit 113, +Transmitter Signal Element Timing - DTE source (EIA-232-D pin 24), on CCITT +V\.24 circuit 128, Receiver Signal Element Timing - DTE source (no EIA-232-D pin), or not sent at all. -.sp -.LP +.Pp In terms of clock modes, traditional asynchronous communication is implemented simply by using the local baud rate generator as the incoming transmit and receive clock source and not outputting any clock signals. -.SS "Terminal Parameters" -.LP -The parameters that control the behavior of devices providing the \fBtermiox\fR -interface are specified by the \fBtermiox\fR structure defined in the -<\fBsys/termiox.h\fR> header. Several \fBioctl\fR(2) system calls that fetch +.Ss "Terminal Parameters" +The parameters that control the behavior of devices providing the +.Nm +interface are specified by the +.Vt termiox +structure defined in the +.In sys/termiox.h +header. +Several +.Xr ioctl 2 +system calls that fetch or change these parameters use this structure: -.sp -.in +2 -.nf +.Bd -literal -offset 2n #define NFF 5 struct termiox { unsigned short x_hflag; /* hardware flow control modes */ @@ -81,274 +112,302 @@ struct termiox { unsigned short x_rflag[NFF]; /* reserved modes */ unsigned short x_sflag; /* spare local modes */ }; -.fi -.in -2 - -.sp -.LP -The \fBx_hflag\fR field describes hardware flow control modes: -.sp - -.sp -.TS -l l l -l l l . -RTSXOFF 0000001 T{ -Enable RTS hardware flow control on input. -T} -CTSXON 0000002 T{ -Enable CTS hardware flow control on output. -T} -DTRXOFF 0000004 T{ -Enable DTR hardware flow control on input. -T} -CDXON 0000010 T{ -Enable CD hardware flow control on output. -T} -ISXOFF 0000020 T{ -Enable isochronous hardware flow control on input -T} -.TE - -.sp -.LP +.Ed +.Pp +The +.Fa x_hflag +field describes hardware flow control modes: +.Bl -column xxxxxxx xxxxxxx x +.It Dv RTSXOFF Ta 0000001 Ta "Enable RTS hardware flow control on input." +.It Dv CTSXON Ta 0000002 Ta "Enable CTS hardware flow control on output." +.It Dv DTRXOFF Ta 0000004 Ta "Enable DTR hardware flow control on input." +.It Dv CDXON Ta 0000010 Ta "Enable CD hardware flow control on output." +.It Dv ISXOFF Ta 0000020 Ta "Enable isochronous hardware flow control on input." +.El +.Pp The EIA-232-D DTR and CD circuits are used to establish a connection between -two systems. The RTS circuit is also used to establish a connection with a -modem. Thus, both DTR and RTS are activated when an asynchronous port is -opened. If DTR is used for hardware flow control, then RTS must be used for -connectivity. If CD is used for hardware flow control, then CTS must be used -for connectivity. Thus, RTS and DTR (or CTS and CD) cannot both be used for -hardware flow control at the same time. Other mutual exclusions may apply, such -as the simultaneous setting of the \fBtermio\fR(7I) \fBHUPCL\fR and the -\fBtermiox\fR \fBDTRXOFF\fR bits, which use the DTE ready line for different -functions. -.sp -.LP +two systems. +The RTS circuit is also used to establish a connection with a modem. +Thus, both DTR and RTS are activated when an asynchronous port is opened. +If DTR is used for hardware flow control, then RTS must be used for +connectivity. +If CD is used for hardware flow control, then CTS must be used +for connectivity. +Thus, RTS and DTR (or CTS and CD) cannot both be used for +hardware flow control at the same time. +Other mutual exclusions may apply, such as the simultaneous setting of the +.Xr termio 7I +.Dv HUPCL +and the +.Vt termiox +.Dv DTRXOFF +bits, which use the DTE ready line for different functions. +.Pp Variations of different hardware flow control methods may be selected by -setting the appropriate bits. For example, bidirectional RTS/CTS flow -control is selected by setting both the \fBRTSXOFF\fR and \fBCTSXON\fR bits and -bidirectional DTR/CTS flow control is selected by setting both the -\fBDTRXOFF\fR and \fBCTSXON\fR. Modem control or unidirectional CTS hardware -flow control is selected by setting only the \fBCTSXON\fR bit. -.sp -.LP +setting the appropriate bits. +For example, bidirectional RTS/CTS flow control is selected by setting both the +.Dv RTSXOFF +and +.Dv CTSXON +bits and bidirectional DTR/CTS flow control is selected by setting both the +.Dv DTRXOFF +and +.Dv CTSXON . +Modem control or unidirectional CTS hardware +flow control is selected by setting only the +.Dv CTSXON +bit. +.Pp As previously mentioned, it is assumed that the local asynchronous port (for -example, computer) is configured as a DTE. If the connected device (for -example, printer) is also a DTE, it is assumed that the device is connected to -the computer's asynchronous port using a null modem that swaps control circuits -(typically RTS and CTS). The connected DTE drives RTS and the null modem swaps -RTS and CTS so that the remote RTS is received as CTS by the local DTE. In -the case that \fBCTSXON\fR is set for hardware flow control, printer's lowering -of its RTS would cause CTS seen by the computer to be lowered. Output to the -printer is suspended until the printer's raising of its RTS, which would cause -CTS seen by the computer to be raised. -.sp -.LP -If \fBRTSXOFF\fR is set, the Request To Send (RTS) circuit (line) will be +example, computer) is configured as a DTE. +If the connected device (for example, printer) is also a DTE, it is assumed +that the device is connected to the computer's asynchronous port using a null +modem that swaps control circuits (typically RTS and CTS). +The connected DTE drives RTS and the null modem swaps +RTS and CTS so that the remote RTS is received as CTS by the local DTE. +In the case that +.Dv CTSXON +is set for hardware flow control, printer's lowering +of its RTS would cause CTS seen by the computer to be lowered. +Output to the printer is suspended until the printer's raising of its RTS, +which would cause CTS seen by the computer to be raised. +.Pp +If +.Dv RTSXOFF +is set, the Request To Send (RTS) circuit (line) will be raised, and if the asynchronous port needs to have its input stopped, it will -lower the Request To Send (RTS) line. If the RTS line is lowered, it is assumed +lower the Request To Send (RTS) line. +If the RTS line is lowered, it is assumed that the connected device will stop its output until RTS is raised. -.sp -.LP -If \fBCTSXON\fR is set, output will occur only if the Clear To Send (CTS) -circuit (line) is raised by the connected device. If the CTS line is lowered by +.Pp +If +.Dv CTSXON +is set, output will occur only if the Clear To Send (CTS) +circuit (line) is raised by the connected device. +If the CTS line is lowered by the connected device, output is suspended until CTS is raised. -.sp -.LP -If \fBDTRXOFF\fR is set, the DTE Ready (DTR) circuit (line) will be raised, and +.Pp +If +.Dv DTRXOFF +is set, the DTE Ready (DTR) circuit (line) will be raised, and if the asynchronous port needs to have its input stopped, it will lower the DTE -Ready (DTR) line. If the DTR line is lowered, it is assumed that the connected +Ready (DTR) line. +If the DTR line is lowered, it is assumed that the connected device will stop its output until DTR is raised. -.sp -.LP -If \fBCDXON\fR is set, output will occur only if the Received Line Signal -Detector (CD) circuit (line) is raised by the connected device. If the CD line +.Pp +If +.Dv CDXON +is set, output will occur only if the Received Line Signal +Detector (CD) circuit (line) is raised by the connected device. +If the CD line is lowered by the connected device, output is suspended until CD is raised. -.sp -.LP -If \fBISXOFF\fR is set, and if the isochronous port needs to have its input -stopped, it will stop the outgoing clock signal. It is assumed that the -connected device is using this clock signal to create its output. Transit and -receive clock sources are programmed using the \fBx_cflag\fR fields. If the -port is not programmed for external clock generation, \fBISXOFF\fR is ignored. +.Pp +If +.Dv ISXOFF +is set, and if the isochronous port needs to have its input +stopped, it will stop the outgoing clock signal. +It is assumed that the +connected device is using this clock signal to create its output. +Transit and receive clock sources are programmed using the +.Fa x_cflag +fields. +If the port is not programmed for external clock generation, +.Dv ISXOFF +is ignored. Output isochronous flow control is supported by appropriate clock source -programming using the \fBx_cflag\fR field and enabled at the remote connected -device. -.sp -.LP -The \fBx_cflag\fR field specifies the system treatment of clock modes. -.sp - -.sp -.TS -l l l -l l l . -\fBXMTCLK\fR 0000007 Transmit clock source: -\fBXCIBRG\fR 0000000 T{ -Get transmit clock from internal baud rate generator. -T} -\fBXCTSET\fR 0000001 T{ -Get transmit clock from transmitter signal element timing (DCE source) lead, CCITT V.24 circuit 114, EIA-232-D pin 15. -T} -\fBXCRSET\fR 0000002 T{ -Get transmit clock from receiver signal element timing (DCE source) lead, CCITT V.24 circuit 115, EIA-232-D pin 17. -T} -\fBRCVCLK\fR 0000070 Receive clock source: -\fBRCIBRG\fR 0000000 T{ -Get receive clock from internal baud rate generator. -T} -\fBRCTSET\fR 0000010 T{ -Get receive clock from transmitter signal element timing (DCE source) lead, CCITT V.24 circuit 114, EIA-232-D pin 15. -T} -\fBRCRSET\fR 0000020 T{ -Get receive clock from receiver signal element timing (DCE source) lead, CCITT V.24 circuit 115, EIA-232-D pin 17. -T} -\fBTSETCLK\fR 0000700 T{ -Transmitter signal element timing (DTE source) lead, CCITT V.24 circuit 113, EIA-232-D pin 24, clock source: -T} -\fBTSETCOFF\fR 0000000 TSET clock not provided. -\fBTSETCRBRG\fR 0000100 T{ -Output receive baud rate generator on circuit 113. -T} -\fBTSETCTBRG\fR 0000200 T{ -Output transmit baud rate generator on circuit 113 -T} -\fBTSETCTSET\fR 0000300 T{ -Output transmitter signal element timing (DCE source) on circuit 113. -T} -\fBTSETCRSET\fR 0000400 T{ -Output receiver signal element timing (DCE source) on circuit 113. -T} -\fBRSETCLK\fR 0007000 T{ -Receiver signal element timing (DTE source) lead, CCITT V.24 circuit 128, no EIA-232-D pin, clock source: -T} -\fBRSETCOFF\fR 0000000 RSET clock not provided. -\fBRSETCRBRG\fR 0001000 T{ -Output receive baud rate generator on circuit 128. -T} -\fBRSETCTBRG\fR 0002000 T{ -Output transmit baud rate generator on circuit 128. -T} -\fBRSETCTSET\fR 0003000 T{ -Output transmitter signal element timing (DCE source) on circuit 128. -T} -\fBRSETCRSET\fR 0004000 T{ -Output receiver signal element timing (DCE) on circuit 128. -T} -.TE - -.sp -.LP -If the \fBXMTCLK\fR field has a value of \fBXCIBRG\fR the transmit clock is -taken from the hardware internal baud rate generator, as in normal asynchronous -transmission. If \fBXMTCLK\fR = \fBXCTSET\fR the transmit clock is taken from -the Transmitter Signal Element Timing (DCE source) circuit. If \fBXMTCLK\fR = -\fBXCRSET\fR the transmit clock is taken from the Receiver Signal Element +programming using the +.Fa x_cflag +field and enabled at the remote connected device. +.Pp +The +.Fa x_cflag +field specifies the system treatment of clock modes. +.Bl -column xxxxxxxxx xxxxxxxx l +.It Dv XMTCLK Ta 0000007 Ta "Transmit clock source:" +.It Dv XCIBRG Ta 0000000 Ta "Get transmit clock from internal baud rate generator." +.It Dv XCTSET Ta 0000001 Ta "Get transmit clock from transmitter signal element timing (DCE source) lead, CCITT V\.24 circuit 114, EIA-232-D pin 15." +.It Dv XCRSET Ta 0000002 Ta Get transmit clock from receiver signal element timing (DCE source) lead, CCITT V\.4 circuit 115, EIA-232-D pin 17." +.It Dv RCVCLK Ta 0000070 Ta "Receive clock source:" +.It Dv RCIBRG Ta 0000000 Ta "Get receive clock from internal baud rate generator." +.It Dv RCTSET Ta 0000010 Ta "Get receive clock from transmitter signal element timing (DCE source) lead, CCITT V\.24 circuit 114, EIA-232-D pin 15." +.It Dv RCRSET Ta 0000020 Ta "Get receive clock from receiver signal element timing (DCE source) lead, CCITT V\.24 circuit 115, EIA-232-D pin 17." +.It Dv TSETCLK Ta 0000700 Ta "Transmitter signal element timing (DTE source) lead, CCITT V\.24 circuit 113, EIA-232-D pin 24, clock source:" +.It Dv TSETCOFF Ta 0000000 Ta "TSET clock not provided." +.It Dv TSETCRBRG Ta 0000100 Ta "Output receive baud rate generator on circuit 113." +.It Dv TSETCTBRG Ta 0000200 Ta "Output transmit baud rate generator on circuit 113" +.It Dv TSETCTSET Ta 0000300 Ta "Output transmitter signal element timing (DCE source) on circuit 113." +.It Dv TSETCRSET Ta 0000400 Ta "Output receiver signal element timing (DCE source) on circuit 113." +.It Dv RSETCLK Ta 0007000 Ta "Receiver signal element timing (DTE source) lead, CCITT V\.24 circuit 128, no EIA-232-D pin, clock source:" +.It Dv RSETCOFF Ta 0000000 Ta "RSET clock not provided." +.It Dv RSETCRBRG Ta 0001000 Ta "Output receive baud rate generator on circuit 128." +.It Dv RSETCTBRG Ta 0002000 Ta "Output transmit baud rate generator on circuit 128." +.It Dv RSETCTSET Ta 0003000 Ta "Output transmitter signal element timing (DCE source) on circuit 128." +.It Dv RSETCRSET Ta 0004000 Ta "Output receiver signal element timing (DCE) on circuit 128." +.El +.Pp +If the +.Fa XMTCLK +field has a value of +.Dv XCIBRG +the transmit clock is taken from the hardware internal baud rate generator, as +in normal asynchronous transmission. +If +.Fa XMTCLK += +.Dv XCTSET +the transmit clock is taken from +the Transmitter Signal Element Timing (DCE source) circuit. +If +.Fa XMTCLK += +.Dv XCRSET +the transmit clock is taken from the Receiver Signal Element Timing (DCE source) circuit. -.sp -.LP -If the \fBRCVCLK\fR field has a value of \fBRCIBRG\fR the receive clock is +.Pp +If the +.Fa RCVCLK +field has a value of +.Dv RCIBRG , +the receive clock is taken from the hardware Internal Baud Rate Generator, as in normal asynchronous -transmission. If \fBRCVCLK\fR = \fBRCTSET\fR the receive clock is taken from -the Transmitter Signal Element Timing (DCE source) circuit. If \fBRCVCLK\fR = -\fBRCRSET\fR the receive clock is taken from the Receiver Signal Element Timing +transmission. +If +.Fa RCVCLK += +.Dv RCTSET +the receive clock is taken from +the Transmitter Signal Element Timing (DCE source) circuit. +If +.Fa RCVCLK += +.Dv RCRSET +the receive clock is taken from the Receiver Signal Element Timing (DCE source) circuit. -.sp -.LP -If the \fBTSETCLK\fR field has a value of \fBTSETCOFF\fR the Transmitter Signal -Element Timing (DTE source) circuit is not driven. If \fBTSETCLK\fR = -\fBTSETCRBRG\fR the Transmitter Signal Element Timing (DTE source) circuit is -driven by the Receive Baud Rate Generator. If \fBTSETCLK\fR = \fBTSETCTBRG\fR +.Pp +If the +.Fa TSETCLK +field has a value of +.Dv TSETCOFF +the Transmitter Signal Element Timing (DTE source) circuit is not driven. +If +.Fa TSETCLK += +.Dv TSETCRBRG +the Transmitter Signal Element Timing (DTE source) circuit is +driven by the Receive Baud Rate Generator. +If +.Fa TSETCLK += +.Dv TSETCTBRG the Transmitter Signal Element Timing (DTE source) circuit is driven by the -Transmit Baud Rate Generator. If \fBTSETCLK\fR = \fBTSETCTSET\fR the -Transmitter Signal Element Timing (DTE source) circuit is driven by the -Transmitter Signal Element Timing (DCE source). If \fBTSETCLK\fR = -\fBTSETCRBRG\fR the Transmitter Signal Element Timing (DTE source) circuit is +Transmit Baud Rate Generator. +If +.Fa TSETCLK += +.Dv TSETCTSET +the Transmitter Signal Element Timing (DTE source) circuit is driven by the +Transmitter Signal Element Timing (DCE source). +If +.Fa TSETCLK += +.Dv TSETCRBRG +the Transmitter Signal Element Timing (DTE source) circuit is driven by the Receiver Signal Element Timing (DCE source). -.sp -.LP -If the \fBRSETCLK\fR field has a value of \fBRSETCOFF\fR the Receiver Signal -Element Timing (DTE source) circuit is not driven. If \fBRSETCLK\fR = -\fBRSETCRBRG\fR the Receiver Signal Element Timing (DTE source) circuit is -driven by the Receive Baud Rate Generator. If \fBRSETCLK\fR = \fBRSETCTBRG\fR +.Pp +If the +.Fa RSETCLK +field has a value of +.Dv RSETCOFF +the Receiver Signal Element Timing (DTE source) circuit is not driven. +If +.Fa RSETCLK += +.Dv RSETCRBRG +the Receiver Signal Element Timing (DTE source) circuit is +driven by the Receive Baud Rate Generator. +If +.Fa RSETCLK += +.Dv RSETCTBRG the Receiver Signal Element Timing (DTE source) circuit is driven by the -Transmit Baud Rate Generator. If \fBRSETCLK\fR = \fBRSETCTSET\fR the Receiver +Transmit Baud Rate Generator. +If +.Fa RSETCLK += +.Dv RSETCTSET +the Receiver Signal Element Timing (DTE source) circuit is driven by the Transmitter Signal -Element Timing (DCE source). If \fBRSETCLK\fR = \fBRSETCRBRG\fR the Receiver +Element Timing (DCE source). +If +.Fa RSETCLK += +.Dv RSETCRBRG +the Receiver Signal Element Timing (DTE source) circuit is driven by the Receiver Signal Element Timing (DCE source). -.sp -.LP -The \fBx_rflag\fR is reserved for future interface definitions and should not -be used by any implementations. The \fBx_sflag\fR may be used by local +.Pp +The +.Fa x_rflag +is reserved for future interface definitions and should not +be used by any implementations. +The +.Fa x_sflag +may be used by local implementations wishing to customize their terminal interface using the -\fBtermiox\fR ioctl system calls. -.SH IOCTLS -.LP -The \fBioctl\fR(2) system calls have the form: -.sp -.in +2 -.nf -\fBioctl\fR (\fIfildes, command, arg\fR) \fBstruct termiox *\fR \fIarg\fR; -.fi -.in -2 - -.sp -.LP +.Nm +ioctl system calls. +.Sh IOCTLS +The +.Xr ioctl 2 +system calls have the form: +.Bd -literal -offset 2n +struct termiox *arg; +ioctl(fildes, command, arg); +.Ed +.Pp The commands using this form are: -.sp -.ne 2 -.na -\fB\fBTCGETX\fR\fR -.ad -.RS 11n -The argument is a pointer to a \fBtermiox\fR structure. The current terminal -parameters are fetched and stored into that structure. -.RE - -.sp -.ne 2 -.na -\fB\fBTCSETX\fR\fR -.ad -.RS 11n -The argument is a pointer to a \fBtermiox\fR structure. The current terminal -parameters are set from the values stored in that structure. The change is -immediate. -.RE - -.sp -.ne 2 -.na -\fB\fBTCSETXW\fR\fR -.ad -.RS 11n -The argument is a pointer to a \fBtermiox\fR structure. The current terminal -parameters are set from the values stored in that structure. The change occurs -after all characters queued for output have been transmitted. This form should -be used when changing parameters that will affect output. -.RE - -.sp -.ne 2 -.na -\fB\fBTCSETXF\fR\fR -.ad -.RS 11n -The argument is a pointer to a \fBtermiox\fR structure. The current terminal -parameters are set from the values stored in that structure. The change occurs +.Bl -tag -width TCSETXW +.It Dv TCGETX +The argument is a pointer to a +.Vt termiox +structure. +The current terminal parameters are fetched and stored into that structure. +.It Dv TCSETX +The argument is a pointer to a +.Vt termiox +structure. +The current terminal parameters are set from the values stored in that structure. +The change is immediate. +.It Dv TCSETXW +The argument is a pointer to a +.Vt termiox +structure. +The current terminal parameters are set from the values stored in that structure. +The change occurs after all characters queued for output have been transmitted. +This form should be used when changing parameters that will affect output. +.It Dv TCSETXF +The argument is a pointer to a +.Vt termiox +structure. +The current terminal parameters are set from the values stored in that structure. +The change occurs after all characters queued for output have been transmitted; all characters queued for input are discarded and then the change occurs. -.RE - -.SH FILES -.LP -\fB/dev/*\fR -.SH SEE ALSO -.LP -\fBstty\fR(1), \fBioctl\fR(2), \fBtermio\fR(7I) -.SH NOTES -.LP -The termiox(7I) system call is provided for compatibility with previous -releases and its use is discouraged. Instead, the \fBtermio\fR(7I) system -call is recommended. See \fBtermio\fR(7I) for usage information. +.El +.Sh FILES +.Pa /dev/* +.Sh SEE ALSO +.Xr stty 1 , +.Xr ioctl 2 , +.Xr termio 7I +.Sh NOTES +The +.Nm termiox Ns Pq 7I +system call is provided for compatibility with previous +releases and its use is discouraged. +Instead, the +.Xr termio 7I +system call is recommended. +See +.Xr termio 7I +for usage information. diff --git a/usr/src/man/man7i/uscsi.7i b/usr/src/man/man7i/uscsi.7i index c64fe9f9c9..874b07e7e0 100644 --- a/usr/src/man/man7i/uscsi.7i +++ b/usr/src/man/man7i/uscsi.7i @@ -1,49 +1,89 @@ -'\" te .\" Copyright (c) 2007 by Sun Microsystems, Inc. All rights reserved. -.\" Copyright 2016 Joyent, Inc. -.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. -.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. -.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH USCSI 7I "Sep 23, 2016" -.SH NAME -uscsi \- user SCSI command interface -.SH SYNOPSIS -.LP -.nf -#include <sys/scsi/impl/uscsi.h> - -\fB\fR\fBioctl\fR(\fBint\fR \fIfildes\fR, \fBint\fR \fIrequest\fR, \fBstruct uscsi_cmd *\fR\fIcmd\fR); -.fi - -.SH DESCRIPTION -.LP -The \fBuscsi\fR command is very powerful and somewhat dangerous; therefore it -has some permission restrictions. See \fBWARNINGS\fR for more details. -.sp -.LP -Drivers supporting this \fBioctl\fR(2) provide a general interface allowing -user-level applications to cause individual \fBSCSI\fR commands to be directed -to a particular \fBSCSI\fR or \fBATAPI\fR device under control of that driver. -The \fBuscsi\fR command is supported by the \fBsd\fR driver for \fBSCSI\fR -disks and \fBATAPI\fR CD-ROM drives, and by the \fBst\fR driver for \fBSCSI\fR -tape drives. \fBuscsi\fR may also be supported by other device drivers; see the +.\" Copyright 2017 Joyent, Inc. +.\" The contents of this file are subject to the terms of the +.\" Common Development and Distribution License (the "License"). +.\" You may not use this file except in compliance with the License. +.\" +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE +.\" or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions +.\" and limitations under the License. +.\" +.\" When distributing Covered Code, include this CDDL HEADER in each +.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. +.\" If applicable, add the following below this CDDL HEADER, with the +.\" fields enclosed by brackets "[]" replaced with your own identifying +.\" information: Portions Copyright [yyyy] [name of copyright owner] +.Dd October 23, 2017 +.Dt USCSI 7I +.Os +.Sh NAME +.Nm uscsi +.Nd user SCSI command interface +.Sh SYNOPSIS +.In sys/scsi/impl/uscsi.h +.Fo ioctl +.Fa "int filedes" +.Fa "int request" +.Fa "struct uscsi_cmd *cmd" +.Fc +.Sh DESCRIPTION +The +.Nm +command is very powerful and somewhat dangerous; therefore it +has some permission restrictions. +See +.Sx WARNINGS +for more details. +.Pp +Drivers supporting this +.Xr ioctl 2 +provide a general interface allowing user-level applications to cause individual +.Sy SCSI +commands to be directed to a particular +.Sy SCSI +or +.Sy ATAPI +device under control of that driver. +The +.Nm +command is supported by the +.Xr sd 7D +driver for +.Sy SCSI +disks and +.Sy ATAPI +CD-ROM drives, and by the +.Xr st 7D +driver for +.Sy SCSI +tape drives. +.Nm +may also be supported by other device drivers; see the specific device driver manual page for complete information. -.sp -.LP +.Pp Applications must not assume that all Solaris disk device drivers support the -\fBuscsi\fR ioctl command. The \fBSCSI\fR command may include a data transfer -to or from that device, if appropriate for that command. Upon completion of the -command, the user application can determine how many bytes were transferred and -the status returned by the device. Also, optionally, if the command returns a +.Nm +ioctl command. +The +.Sy SCSI +command may include a data transfer +to or from that device, if appropriate for that command. +Upon completion of the command, the user application can determine how many +bytes were transferred and the status returned by the device. +Also, optionally, if the command returns a Check Condition status, the driver will automatically issue a Request Sense -command and return the sense data along with the original status. See the -\fBUSCSI_RQENABLE\fR flag below for this Request Sense processing. The -\fBuscsi_cmd\fR structure is defined in \fB<sys/scsi/impl/uscsi.h>\fR and -includes the following members: -.sp -.in +2 -.nf -int uscsi_flags; /* read, write, etc. see below */ +command and return the sense data along with the original status. +See the +.Sy USCSI_RQENABLE +flag below for this Request Sense processing. +The +.Vt uscsi_cmd +structure is defined in +.In sys/scsi/impl/uscsi.h +and includes the following members: +.Bd -literal -offset 2n +int uscsi_flags; /* read, write, etc. see below */ short uscsi_status; /* resulting status */ short uscsi_timeout; /* Command Timeout */ caddr_t uscsi_cdb /* CDB to send to target */ @@ -56,143 +96,66 @@ uchar_t uscsi_rqstatus; /* status of request sense cmd */ uchar_t uscsi_rqresid; /* resid of request sense cmd */ caddr_t uscsi_rqbuf; /* request sense buffer */ void *uscsi_reserved_5; /* Reserved for future use */ -.fi -.in -2 - -.sp -.LP -The fields of the \fBuscsi_cmd\fR structure have the following meanings: -.sp -.ne 2 -.na -\fB\fBuscsi_flags\fR\fR -.ad -.RS 20n -The \fBI/O\fR direction and other details of how to carry out the \fBSCSI\fR -command. Possible values are described below. -.RE - -.sp -.ne 2 -.na -\fB\fBuscsi_status\fR\fR -.ad -.RS 20n -The \fBSCSI\fR status byte returned by the device is returned in this field. -.RE - -.sp -.ne 2 -.na -\fB\fBuscsi_timeout\fR\fR -.ad -.RS 20n +.Ed +.Pp +The fields of the +.Vt uscsi_cmd +structure have the following meanings: +.Bl -tag -width uscsi_reserved_5 +.It Sy uscsi_flags +The +.Sy I/O +direction and other details of how to carry out the +.Sy SCSI +command. +Possible values are described below. +.It Fa uscsi_status +The +.Sy SCSI +status byte returned by the device is returned in this field. +.It Fa uscsi_timeout Time in seconds to allow for completion of the command. -.RE - -.sp -.ne 2 -.na -\fB\fBuscsi_cdb\fR\fR -.ad -.RS 20n -A pointer to the \fBSCSI\fR CDB (command descriptor block) to be transferred to -the device in command phase. -.RE - -.sp -.ne 2 -.na -\fB\fBuscsi_bufaddr\fR\fR -.ad -.RS 20n +.It Fa uscsi_cdb +A pointer to the +.Sy SCSI +CDB (command descriptor block) to be transferred to the device in command phase. +.It Fa uscsi_bufaddr The user buffer containing the data to be read from or written to the device. -.RE - -.sp -.ne 2 -.na -\fB\fBuscsi_buflen\fR\fR -.ad -.RS 20n -The length of \fBuscsi_bufaddr\fR. -.RE - -.sp -.ne 2 -.na -\fB\fBuscsi_resid\fR\fR -.ad -.RS 20n +.It Sy uscsi_buflen +The length of +.Fa uscsi_bufaddr . +.It Fa uscsi_resid If a data transfer terminates without transferring the entire requested amount, the remainder, or residue, is returned in this field. -.RE - -.sp -.ne 2 -.na -\fB\fBuscsi_cdblen\fR\fR -.ad -.RS 20n -The length of the \fBSCSI\fR CDB to be transferred to the device in command -phase. -.RE - -.sp -.ne 2 -.na -\fB\fBuscsi_rqlen\fR\fR -.ad -.RS 20n -The length of \fBuscsi_rqbuf\fR, the application's Request Sense buffer. -.RE - -.sp -.ne 2 -.na -\fB\fBuscsi_rqstatus\fR\fR -.ad -.RS 20n -The \fBSCSI\fR status byte returned for the Request Sense command executed +.It Fa uscsi_cdblen +The length of the +.Sy SCSI +CDB to be transferred to the device in command phase. +.It Fa uscsi_rqlen +The length of +.Fa uscsi_rqbuf , +the application's Request Sense buffer. +.It Fa uscsi_rqstatus +The +.Sy SCSI +status byte returned for the Request Sense command executed automatically by the driver in response to a Check Condition status return. -.RE - -.sp -.ne 2 -.na -\fB\fBuscsi_rqresid\fR\fR -.ad -.RS 20n +.It Fa uscsi_rqresid The residue, or untransferred data length, of the Request Sense data transfer -(the number of bytes, less than or equal to \fBuscsi_rqlen\fR, which were not -filled with sense data). -.RE - -.sp -.ne 2 -.na -\fB\fBuscsi_rqbuf\fR\fR -.ad -.RS 20n +(the number of bytes, less than or equal to +.Fa uscsi_rqlen , +which were not filled with sense data). +.It Fa uscsi_rqbuf Points to a buffer in application address space to which the results of an automatic Request Sense command are written. -.RE - -.sp -.ne 2 -.na -\fB\fBuscsi_reserved_5\fR\fR -.ad -.RS 20n +.It Fa uscsi_reserved_5 Reserved for future use. -.RE - -.sp -.LP -The \fBuscsi_flags\fR field defines the following: -.sp -.in +2 -.nf +.El +.Pp +The +.Fa uscsi_flags +field defines the following: +.Bd -literal -offset 2n USCSI_WRITE /* send data to device */ USCSI_SILENT /* no error messages */ USCSI_DIAGNOSE /* fail if any error occurs */ @@ -206,272 +169,227 @@ USCSI_RESET_LUN /* reset logical unit */ USCSI_RESET_ALL /* reset all targets */ USCSI_RQENABLE /* enable request sense extensions */ USCSI_RENEGOT /* renegotiate wide/sync on next I/O */ -.fi -.in -2 - -.sp -.LP -The \fBuscsi_flags\fR bits have the following interpretation: -.sp -.ne 2 -.na -\fB\fBUSCSI_WRITE\fR\fR -.ad -.RS 22n +.Ed +.Pp +The +.Fa uscsi_flags +bits have the following interpretation: +.Bl -tag -width USCSI_RESET_TARGET +.It Dv USCSI_WRITE Data will be written from the initiator to the target. -.RE - -.sp -.ne 2 -.na -\fB\fBUSCSI_SILENT\fR\fR -.ad -.RS 22n +.It Dv USCSI_SILENT The driver should not print any console error messages or warnings regarding -failures associated with this \fBSCSI\fR command. -.RE - -.sp -.ne 2 -.na -\fB\fBUSCSI_DIAGNOSE\fR\fR -.ad -.RS 22n +failures associated with this +.Sy SCSI +command. +.It Dv USCSI_DIAGNOSE The driver should not attempt any retries or other recovery mechanisms if this -\fBSCSI\fR command terminates abnormally in any way. -.RE - -.sp -.ne 2 -.na -\fB\fBUSCSI_ISOLATE\fR\fR -.ad -.RS 22n -This \fBSCSI\fR command should not be executed with other commands. -.RE - -.sp -.ne 2 -.na -\fB\fBUSCSI_READ\fR\fR -.ad -.RS 22n +.Sy SCSI +command terminates abnormally in any way. +.It Dv USCSI_ISOLATE +This +.Sy SCSI +command should not be executed with other commands. +.It Dv USCSI_READ Data will be read from the target to the initiator. -.RE - -.sp -.ne 2 -.na -\fB\fBUSCSI_ASYNC\fR\fR -.ad -.RS 22n -Set the \fBSCSI\fR bus to asynchronous mode before running this command. -.RE - -.sp -.ne 2 -.na -\fB\fBUSCSI_SYNC\fR\fR -.ad -.RS 22n -Set the \fBSCSI\fR bus to synchronous mode before running this command. -.RE - -.sp -.ne 2 -.na -\fB\fBUSCSI_RESET\fR\fR -.ad -.RS 22n -Send a \fBSCSI\fR bus device reset message to this target. -.RE - -.sp -.ne 2 -.na -\fB\fBUSCSI_RESET_TARGET\fR\fR -.ad -.RS 22n -Same as USCSI_RESET. Use this flag to request TARGET RESET. (USCSI_RESET is -maintained only for compatibility with old applications). -.RE - -.sp -.ne 2 -.na -\fB\fBUSCSI_RESET_LUN\fR\fR -.ad -.RS 22n -Send a \fBSCSI\fR logical unit reset message to this target. -.RE - -.sp -.ne 2 -.na -\fB\fBUSCSI_RESET_ALL\fR\fR -.ad -.RS 22n -USCSI_RESET_ALL, USCSI_RESET/USCSI_RESET_TARGET and USCSI_RESET_LUN are +.It Dv USCSI_ASYNC +Set the +.Sy SCSI +bus to asynchronous mode before running this command. +.It Dv USCSI_SYNC +Set the +.Sy SCSI +bus to synchronous mode before running this command. +.It Dv USCSI_RESET +Send a +.Sy SCSI +bus device reset message to this target. +.It Dv USCSI_RESET_TARGET +Same as USCSI_RESET. +Use this flag to request TARGET RESET. +.Po +.Dv USCSI_RESET +is maintained only for compatibility with old applications +.Pc . +.It Dv USCSI_RESET_LUN +Send a +.Sy SCSI +logical unit reset message to this target. +.It Dv USCSI_RESET_ALL +.Dv USCSI_RESET_ALL , +.Dv USCSI_RESET/USCSI_RESET_TARGET , +and +.Dv USCSI_RESET_LUN +are mutually exclusive options and issuing them in any simultaneous combination will result in implementation-dependent behavior -.sp -When a USCSI reset request is combined with other \fBSCSI\fR commands, the -following semantics take effect: -.sp -If the USCSI RESET flag is specified, the other fields (other than uscsi_flags) -in the uscsi_cmd are ignored. The uscsi_cdblen \fBmust\fR be set to zero. -.RE - -.sp -.ne 2 -.na -\fB\fBUSCSI_RQENABLE\fR\fR -.ad -.RS 22n -Enable Request Sense extensions. If the user application is prepared to receive -sense data, this bit must be set, the fields \fBuscsi_rqbuf\fR and -\fBuscsi_rqbuflen\fR must be non-zero, and the \fBuscsi_rqbuf\fR must point to -memory writable by the application. -.RE - -.sp -.ne 2 -.na -\fB\fBUSCSI_RENEGOT\fR\fR -.ad -.RS 22n +When a USCSI reset request is combined with other +.Sy SCSI +commands, the following semantics take effect: +If the +.Dv USCSI RESET +flag is specified, the other fields (other than +.Fa uscsi_flags ) +in the +.Vt uscsi_cmd +are ignored. +The +.Fa uscsi_cdblen +field +.Em must +be set to zero. +.It Dv USCSI_RQENABLE +Enable Request Sense extensions. +If the user application is prepared to receive +sense data, this bit must be set, the fields +.Fa uscsi_rqbuf +and +.Fa uscsi_rqbuflen +must be non-zero, and the +.Fa uscsi_rqbuf +must point to memory writable by the application. +.It Dv USCSI_RENEGOT Tells USCSI to renegotiate wide mode and synchronous transfer speed before the -transmitted SCSI command is executed. This flag in effects tells the target -driver to pass the \fBFLAG_RENEGOTIATE_WIDE_SYNC\fR flag in the SCSI packet +transmitted SCSI command is executed. +This flag in effects tells the target driver to pass the +.Dv FLAG_RENEGOTIATE_WIDE_SYNC +flag in the SCSI packet before passing the command to an adapter driver for transport. -.sp -See the \fBscsi_pkt\fR(9S) flag \fBFLAG_RENEGOTIATE_WIDE_SYNC\fR for more -information. -.RE - -The \fBuscsi_xfer_t\fR is a type definition that corresponds to a 64-bit -unsigned integer. It should be used for the \fBUSCSIMAXXFER\fR ioctls. This is +See the +.Xr scsi_pkt 9S +flag +.Dv FLAG_RENEGOTIATE_WIDE_SYNC +for more information. +.El +.Pp +The +.Vt uscsi_xfer_t +is a type definition that corresponds to a 64-bit unsigned integer. +It should be used for the +.Dv USCSIMAXXFER +ioctls. +This is used for determining the maximum transfer size that can be performed in a single -\fBUSCSICMD\fR ioctl. If the SCSI request is larger than the specified size, +.Dv USCSICMD +ioctl. +If the SCSI request is larger than the specified size, then it may not work, depending on the hardware platform. - -.SH IOCTLS -.LP -The \fBioctl\fR supported by drivers providing the \fBuscsi\fR interface is: -.sp -.ne 2 -.na -\fB\fBUSCSICMD\fR\fR -.ad -.RS 12n -The argument is a pointer to a \fBuscsi_cmd\fR structure. The \fBSCSI\fR device -addressed by that driver is selected, and given the \fBSCSI\fR command -addressed by \fBuscsi_cdb\fR. If this command requires a data phase, the -\fBuscsi_buflen\fR and \fBuscsi_bufaddr\fR fields must be set appropriately; if -data phase occurs, the \fBuscsi_resid\fR is returned as the number of bytes not -transferred. The status of the command, as returned by the device, is returned -in the \fBuscsi_status\fR field. If the command terminates with Check Condition +.Sh IOCTLS +The +.Fn ioctl +supported by drivers providing the +.Nm +interface is: +.Bl -tag -width USCSIMAXXFER +.It Dv USCSICMD +The argument is a pointer to a +.Vt uscsi_cmd +structure. +The +.Sy SCSI +device addressed by that driver is selected, and given the +.Sy SCSI +command addressed by +.Fa uscsi_cdb . +If this command requires a data phase, the +.Fa uscsi_buflen +and +.Fa uscsi_bufaddr +fields must be set appropriately; if data phase occurs, the +.Fa uscsi_resid +is returned as the number of bytes not transferred. +The status of the command, as returned by the device, is returned in the +.Fa uscsi_status +field. +If the command terminates with Check Condition status, and Request Sense is enabled, the sense data itself is returned in -\fBuscsi_rqbuf\fR. The \fBuscsi_rqresid\fR provides the residue of the Request -Sense data transfer. -.RE - -.sp -.ne 2 -.na -.B USCSIMAXXFER -.ad -.RS 12n -The argument is a pointer to a \fBuscsi_xfer_t\fR value. The maximum transfer -size that can be used with the \fBUSCSICMD\fR ioctl for the current device will -be returned in the \fBuscsi_xfer_t\fR. -.sp -.LP -Not all devices which support the \fBUSCSICMD\fR ioctl also support the -\fBUSCSIMAXXFER\fR ioctl. -.RE - -.SH ERRORS -.ne 2 -.na -\fB\fBEINVAL\fR\fR -.ad -.RS 10n +.Fa uscsi_rqbuf . +The +.Fa uscsi_rqresid +provides the residue of the Request Sense data transfer. +.It Dv USCSIMAXXFER +The argument is a pointer to a +.Vt uscsi_xfer_t +value. +The maximum transfer size that can be used with the +.Dv USCSICMD +ioctl for the current device will be returned in the +.Vt uscsi_xfer_t . +.Pp +Not all devices which support the +.Dv USCSICMD +ioctl also support the +.Dv USCSIMAXXFER +ioctl. +.El +.Sh ERRORS +.Bl -tag -width EINVAL +.It Er EINVAL A parameter has an incorrect, or unsupported, value. -.RE - -.sp -.ne 2 -.na -\fB\fBEIO\fR\fR -.ad -.RS 10n +.It Er EIO An error occurred during the execution of the command. -.RE - -.sp -.ne 2 -.na -\fB\fBEPERM\fR\fR -.ad -.RS 10n -A process without root credentials tried to execute the \fBUSCSICMD\fR or -\fBUSCSIMAXXFER\fR ioctl. -.RE - -.sp -.ne 2 -.na -\fB\fBEFAULT\fR\fR -.ad -.RS 10n -The \fBuscsi_cmd\fR itself, the \fBuscsi_cdb\fR, the \fBuscsi_buf\fR, the -\fBuscsi_rqbuf\fR, or the \fBuscsi_xfer_t\fR point to an invalid address. -.RE - -.SH ATTRIBUTES -.LP -See \fBattributes\fR(5) for descriptions of the following attributes: -.sp - -.sp -.TS -box; -c | c -l | l . -ATTRIBUTE TYPE ATTRIBUTE VALUE -_ -Interface Stability Committed -.TE - -.SH SEE ALSO -.LP -\fBioctl\fR(2), \fBattributes\fR(5), \fBsd\fR(7D), \fBst\fR(7D) -.sp -.LP -\fIANSI Small Computer System Interface-2 (SCSI-2)\fR -.SH WARNINGS -.LP -The \fBuscsi\fR command is very powerful, but somewhat dangerous, and so its +.It Er EPERM +A process without root credentials tried to execute the +.Dv USCSICMD +or +.Dv USCSIMAXXFER +ioctl. +.It Er EFAULT +The +.Vt uscsi_cmd +itself, the +.Fa uscsi_cdb , +the +.Fa uscsi_buf , +the +.Fa uscsi_rqbuf , +or the +.Vt uscsi_xfer_t +point to an invalid address. +.El +.Sh STABILITY +Committed +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr attributes 5 , +.Xr sd 7D , +.Xr st 7D +.Rs +.%T ANSI Small Computer System Interface-2 (SCSI-2) +.Re +.Sh WARNINGS +The +.Nm +command is very powerful, but somewhat dangerous, and so its use is restricted to processes running as root, regardless of the file -permissions on the device node. The device driver code expects to own the -device state, and \fBuscsi\fR commands can change the state of the device and -confuse the device driver. It is best to use \fBuscsi\fR commands only with no -side effects, and avoid commands such as Mode Select, as they may cause damage -to data stored on the drive or system panics. Also, as the commands are not -checked in any way by the device driver, any block may be overwritten, and the -block numbers are absolute block numbers on the drive regardless of which slice -number is used to send the command. -.sp -.LP -The \fBuscsi\fR interface is not recommended for very large data transfers -(typically more than 16MB). If the requested transfer size exceeds the maximum -transfer size of the DMA engine, it will not be broken up into multiple -transfers and DMA errors may result. The \fBUSCSIMAXXFER\fR ioctl can be used -to determine the maximum transfer size. -.sp -.LP -The \fBUSCSICMD\fR ioctl associates a \fBstruct uscsi_cmd\fR with a device by -using an open file descriptor to the device. Other APIs might provide the same -\fBstruct uscsi_cmd\fR programming interface, but perform device association in -some other manner. +permissions on the device node. +The device driver code expects to own the device state, and +.Nm +commands can change the state of the device and confuse the device driver. +It is best to use +.Nm +commands only with no side effects, and avoid commands such as Mode Select, as +they may cause damage to data stored on the drive or system panics. +Also, as the commands are not checked in any way by the device driver, any block +may be overwritten, and the block numbers are absolute block numbers on the +drive regardless of which slice number is used to send the command. +.Pp +The +.Nm +interface is not recommended for very large data transfers +(typically more than 16MB). +If the requested transfer size exceeds the maximum transfer size of the DMA +engine, it will not be broken up into multiple transfers and DMA errors may +result. +The +.Dv USCSIMAXXFER +ioctl can be used to determine the maximum transfer size. +.Pp +The +.Dv USCSICMD +ioctl associates a +.Vt struct uscsi_cmd +with a device by using an open file descriptor to the device. +Other APIs might provide the same +.Vt struct uscsi_cmd +programming interface, but perform device association in some other manner. diff --git a/usr/src/man/man7i/visual_io.7i b/usr/src/man/man7i/visual_io.7i index 984fe948a8..56cb1da663 100644 --- a/usr/src/man/man7i/visual_io.7i +++ b/usr/src/man/man7i/visual_io.7i @@ -1,308 +1,322 @@ -'\" te .\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved -.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. -.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. -.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH VISUAL_IO 7I "Oct 14, 2005" -.SH NAME -visual_io \- Solaris VISUAL I/O control operations -.SH SYNOPSIS -.LP -.nf -\fB#include <sys/visual_io.h>\fR -.fi - -.SH DESCRIPTION -.sp -.LP -The Solaris VISUAL environment defines a small set of ioctls for controlling +.\" Copyright 2018, Joyent, Inc. +.\" The contents of this file are subject to the terms of the +.\" Common Development and Distribution License (the "License"). +.\" You may not use this file except in compliance with the License. +.\" +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE +.\" or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions +.\" and limitations under the License. +.\" +.\" When distributing Covered Code, include this CDDL HEADER in each +.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. +.\" If applicable, add the following below this CDDL HEADER, with the +.\" fields enclosed by brackets "[]" replaced with your own identifying +.\" information: Portions Copyright [yyyy] [name of copyright owner] +.Dd August 31, 2018 +.Dt VISUAL_IO 7I +.Os +.Sh NAME +.Nm visual_io +.Nd illumos VISUAL I/O control operations +.Sh SYNOPSIS +.In sys/visual_io.h +.Sh DESCRIPTION +The illumos VISUAL environment defines a small set of ioctls for controlling graphics and imaging devices. -.sp -.LP -The \fBVIS_GETIDENTIFIER\fR ioctl is mandatory and must be implemented in -device drivers for graphics devices using the Solaris VISUAL environment. The -\fBVIS_GETIDENTIFIER\fR ioctl is defined to return a device identifier from the -device driver. This identifier must be a uniquely-defined string. -.sp -.LP -There are two additional sets of ioctls. One supports mouse tracking via -hardware cursor operations. Use of this set is optional, however, if a graphics +.Pp +The +.Dv VIS_GETIDENTIFIER +ioctl is mandatory and must be implemented in +device drivers for graphics devices using the illumos VISUAL environment. +The +.Dv VIS_GETIDENTIFIER +ioctl is defined to return a device identifier from the device driver. +This identifier must be a uniquely-defined string. +.Pp +There are two additional sets of ioctls. +One supports mouse tracking via hardware cursor operations. +Use of this set is optional, however, if a graphics device has hardware cursor support and implements these ioctls, the mouse -tracking performance is improved. The remaining set supports the device acting -as the system console device. Use of this set is optional, but if a graphics -device is to be used as the system console device, it must implement these -ioctls. -.sp -.LP +tracking performance is improved. +The remaining set supports the device acting +as the system console device. +Use of this set is optional, but if a graphics device is to be used as the +system console device, it must implement these ioctls. +.Pp The VISUAL environment also defines interfaces for non-ioctl entry points into -the driver that the Solaris operating environment calls when it is running in -standalone mode (for example, when using a stand-alone debugger, entering -the PROM monitor, or when the system panicking). These are also known as -"Polled I/O" entry points, which operate under an an explicit set of -restrictions, described below. -.SH IOCTLS -.sp -.ne 2 -.na -\fB\fBVIS_GETIDENTIFIER\fR\fR -.ad -.RS 21n -This \fBioctl()\fR returns an identifier string to uniquely identify a device -used in the Solaris VISUAL environment. This is a mandatory ioctl and must -return a unique string. We suggest that the name be formed as -\fI<companysymbol><devicetype>\fR\&. For example, the \fBcgsix\fR driver -returns \fBSUNWcg6\fR. -.sp -\fBVIS_GETIDENTIFIER\fR takes a \fBvis_identifier\fR structure as its -parameter. This structure has the form: -.sp -.in +2 -.nf +the driver that the illumos operating environment calls when it is running in +standalone mode (for example, when using a stand-alone debugger, entering +the PROM monitor, or when the system panicking). +These are also known as +.Dq Polled I/O +entry points, which operate under an an explicit set of restrictions, described below. +.Sh IOCTLS +.Bl -tag -width VIS_GETIDENTIFIER -compact +.It Dv VIS_GETIDENTIFIER +This +.Xr ioctl 2 +returns an identifier string to uniquely identify a device +used in the illumos VISUAL environment. +This is a mandatory ioctl and must return a unique string. +We suggest that the name be formed as +.Ao companysymbol Ac Ns Ao devicetype Ac . +For example, the +.Xr cgsix 7D +driver +returns +.Sy SUNWcg6 . +.Pp +.Dv VIS_GETIDENTIFIER +takes a +.Vt vis_identifier +structure as its parameter. +This structure has the form: +.Bd -literal -offset 2n #define VIS_MAXNAMELEN 128 struct vis_identifier { char name[VIS_MAXNAMELEN]; }; -.fi -.in -2 - -.RE - -.sp -.ne 2 -.na -\fB\fBVIS_GETCURSOR\fR\fR -.ad -.br -.na -\fB\fBVIS_SETCURSOR\fR\fR -.ad -.RS 21n +.Ed +.Pp +.It Dv VIS_GETCURSOR +.It Dv VIS_SETCURSOR These ioctls fetch and set various cursor attributes, using the -\fBvis_cursor\fR structure. -.sp -.in +2 -.nf +.Vt vis_cursor +structure. +.Bd -literal -offset 2n struct vis_cursorpos { - short x; /* cursor x coordinate */ - short y; /* cursor y coordinate */ + short x; /* cursor x coordinate */ + short y; /* cursor y coordinate */ }; struct vis_cursorcmap { - int version; /* version */ - int reserved; - unsigned char *red; /* red color map elements */ - unsigned char *green;/* green color map elements */ - unsigned char *blue; /* blue color map elements */ + int version; /* version */ + int reserved; + /* red color map elements */ + unsigned char *red; + /* green color map elements */ + unsigned char *green; + /* blue color map elements */ + unsigned char *blue; }; #define VIS_CURSOR_SETCURSOR 0x01 /* set cursor */ -#define VIS_CURSOR_SETPOSITION 0x02 /* set cursor position */ -#define VIS_CURSOR_SETHOTSPOT 0x04 /* set cursor hot spot */ -#define VIS_CURSOR_SETCOLORMAP 0x08 /* set cursor colormap */ -#define VIS_CURSOR_SETSHAPE 0x10 /* set cursor shape */ + /* set cursor position */ +#define VIS_CURSOR_SETPOSITION 0x02 + /* set cursur hot spot */ +#define VIS_CURSOR_SETHOTSPOT 0x04 + /* set cursor colormap */ +#define VIS_CURSOR_SETCOLORMAP 0x08 + /* set cursor shape */ +#define VIS_CURSOR_SETSHAPE 0x10 #define VIS_CURSOR_SETALL \e (VIS_CURSOR_SETCURSOR | VIS_CURSOR_SETPOSITION | \e VIS_CURSOR_SETHOTSPOT | VIS_CURSOR_SETCOLORMAP | \e VIS_CURSOR_SETSHAPE) struct vis_cursor { - short set; /* what to set */ - short enable; /* cursor on/off */ - struct vis_cursorpos pos; /* cursor position */ - struct vis_cursorpos hot; /* cursor hot spot */ - struct vis_cursorcmap cmap; /* color map info */ - struct vis_cursorpos size; /* cursor bitmap size */ - char *image; /* cursor image bits */ - char *mask; /* cursor mask bits */ + short set; /* what to set */ + short enable; /* cursor on/off */ + struct vis_cursorpos pos; /* cursor position */ + struct vis_cursorpos hot; /* cursor hot spot */ + struct vis_cursorcmap cmap; /* color map info */ + /* cursor bitmap size */ + struct vis_cursorpos size; + char *image; /* cursor image bits */ + char *mask; /* cursor mask bits */ }; -.fi -.in -2 - -.RE - -.sp -.LP -The \fBvis_cursorcmap\fR structure should contain pointers to two elements, +.Ed +.Pp +The +.Vt vis_cursorcmap +structure should contain pointers to two elements, specifying the red, green, and blue values for foreground and background. -.sp -.ne 2 -.na -\fB\fBVIS_SETCURSORPOS\fR\fR -.ad -.br -.na -\fB\fBVIS_MOVECURSOR\fR\fR -.ad -.RS 20n +.Pp +.It Dv VIS_SETCURSORPOS +.It Dv VIS_MOVECURSOR These ioctls fetch and move the current cursor position, using the -\fBvis_cursorpos\fR structure. -.RE - -.SS "Console Optional Ioctls" -.sp -.LP +.Vt vis_cursorpos +structure. +.El +.Ss "Console Optional Ioctls" The following ioctl sets are used by graphics drivers that are part of the -system console device. All of the ioctls must be implemented to be a console -device. In addition, if the system does not have a prom or the prom goes away +system console device. +All of the ioctls must be implemented to be a console device. +In addition, if the system does not have a prom or the prom goes away during boot, the special standalone ioctls (listed below) must also be implemented. -.sp -.LP +.Pp The coordinate system for the console device places 0,0 at the upper left corner of the device, with rows increasing toward the bottom of the device and columns increasing from left to right. -.sp -.ne 2 -.na -\fBVIS_PUTCMAP\fR -.ad -.br -.na -\fB\fBVIS_GETCMAP\fR\fR -.ad -.RS 15n +.Pp +.Bl -tag -width VIS_CONSDISPLAY -compact -offset 2n +.It Dv VIS_PUTCMAP +.It Dv VIS_GETCMAP Set or get color map entries. -.RE - -.sp -.LP -The argument is a pointer to a \fBvis_cmap\fR structure, which contains the +.Pp +The argument is a pointer to a +.Vt vis_cmap +structure, which contains the following fields: -.sp -.in +2 -.nf +.Bd -literal -offset 2n struct vis_cmap { - int index; - int count; + int index; + int count; uchar_t *red; uchar_t *green; uchar_t *blue; } -.fi -.in -2 - -.sp -.LP -\fBindex\fR is the starting index in the color map where you want to start +.Ed +.Pp +.Fa index +is the starting index in the color map where you want to start setting or getting color map entries. -.sp -.LP -\fBcount\fR is the number of color map entries to set or get. It also is the -size of the \fBred\fR, \fBgreen\fR, and \fBblue\fR color arrays. -.sp -.LP -\fB*red\fR, \fB*green\fR, and \fB*blue\fR are pointers to unsigned character -arrays which contain the color map info to set or where the color map info is -placed on a get. -.sp -.ne 2 -.na -\fB\fBVIS_DEVINIT\fR\fR -.ad -.RS 15n +.Pp +.Fa count +is the number of color map entries to set or get. +It also is the +size of the +.Fa red , +.Fa green , +and +.Fa blue +color arrays. +.Pp +.Fa *red , +.Fa *green , +and +.Fa *blue +are pointers to unsigned character arrays which contain the color map info to +set or where the color map info is placed on a get. +.Pp +.It Dv VIS_DEVINIT Initializes the graphics driver as a console device. -.RE - -.sp -.LP -The argument is a pointer to a \fBvis_devinit\fR structure. The graphics driver +.Pp +The argument is a pointer to a +.Vt vis_devinit +structure. +The graphics driver is expected to allocate any local state information needed to be a console device and fill in this structure. -.sp -.in +2 -.nf +.Bd -literal -offset 2n struct vis_devinit { int version; screen_size_t width; screen_size_t height; screen_size_t linebytes; - unit_t size; - int depth; - short mode; + unit_t size; + int depth; + short mode; struct vis_polledio *polledio; vis_modechg_cb_t modechg_cb; struct vis_modechg_arg *modechg_arg; }; -.fi -.in -2 - -.sp -.LP -\fBversion\fR is the version of this structure and should be set to -\fBVIS_CONS_REV\fR. -.sp -.LP -\fBwidth\fR and \fBheight\fR are the width and height of the device. If -\fBmode\fR (see below) is \fBVIS_TEXT\fR then \fBwidth\fR and \fBheight\fR are -the number of characters wide and high of the device. If \fBmode\fR is -\fBVIS_PIXEL\fR then \fBwidth\fR and \fBheight\fR are the number of pixels wide -and high of the device. -.sp -.LP -\fBlinebytes\fR is the number of bytes per line of the device. -.sp -.LP -\fBsize\fR is the total size of the device in pixels. -.sp -.LP -\fBdepth\fR is the pixel depth in device bits. Currently supported depths are: -\fB1\fR, \fB4\fR, \fB8\fR and \fB24\fR. -.sp -.LP -\fBmode\fR is the mode of the device. Either \fBVIS_PIXEL\fR (data to be -displayed is in bitmap format) or \fBVIS_TEXT\fR (data to be displayed is in -ascii format). -.sp -.LP -\fBpolledio\fR is used to pass the address of the structure containing the +.Ed +.Pp +.Fa version +is the version of this structure and should be set to +.Dv VIS_CONS_REV . +.Pp +.Fa width +and +.Fa height +are the width and height of the device. +If +.Fa mode +(see below) is +.Dv VIS_TEXT +then +.Fa width +and +.Fa height +are the number of characters wide and high of the device. +If +.Fa mode +is +.Dv VIS_PIXEL +then +.Fa width +and +.Fa height +are the number of pixels wide and high of the device. +.Pp +.Fa linebytes +is the number of bytes per line of the device. +.Pp +.Fa size +is the total size of the device in pixels. +.Pp +.Fa depth +is the pixel depth in device bits. +Currently supported depths are: +.Sy 1 , +.Sy 4 , +.Sy 8 +and +.Sy 24 . +.Pp +.Fa mode +is the mode of the device. +Either +.Dv VIS_PIXEL +(data to be displayed is in bitmap format) or +.Dv VIS_TEXT +(data to be displayed is in ascii format). +.Pp +.Fa polledio +is used to pass the address of the structure containing the standalone mode polled I/O entry points to the device driver back to the -terminal emulator. The \fBvis_polledio\fR interfaces are described in the -Console Standalone Entry Points section of this manpage. These entry points are -where the operating system enters the driver when the system is running in -standalone mode. These functions perform identically to the VIS_CONSDISPLAY, -VIS_CONSCURSOR and VIS_CONSCOPY ioctls, but are called directly by the Solaris +terminal emulator. +The +.Vt vis_polledio +interfaces are described in the +Console Standalone Entry Points section of this manpage. +These entry points are where the operating system enters the driver when the +system is running in standalone mode. +These functions perform identically to the +.Dv VIS_CONSDISPLAY , +.Dv VIS_CONSCURSOR , +and +.Dv VIS_CONSCOPY +ioctls, but are called directly by the illumos operating environment and must operate under a very strict set of assumptions. -.sp -.LP -\fBmodechg_cb\fR is a callback function passed from the terminal emulator to +.Pp +.Fa modechg_cb +is a callback function passed from the terminal emulator to the framebuffer driver which the frame-buffer driver must call whenever a video -mode change event occurs that changes the screen height, width or depth. The -callback takes two arguments, an opaque handle, \fBmodechg_arg\fR, and the -address of a vis_devinit struct containing the new video mode information. -.sp -.LP -\fBmodechg_arg\fR is an opaque handle passed from the terminal emulator to the +mode change event occurs that changes the screen height, width or depth. +The callback takes two arguments, an opaque handle, +.Fa modechg_arg , +and the address of a +.Vt vis_devinit +struct containing the new video mode information. +.Pp +.Fa modechg_arg +is an opaque handle passed from the terminal emulator to the driver, which the driver must pass back to the terminal emulator as an argument -to the \fBmodechg_cb\fR function when the driver notifies the terminal emulator -of a video mode change. -.sp -.ne 2 -.na -\fB\fBVIS_DEVFINI\fR\fR -.ad -.RS 18n -Tells the graphics driver that it is no longer the system console device. There -is no argument to this ioctl. The driver is expected to free any locally kept +to the +.Fa modechg_cb +function when the driver notifies the terminal emulator of a video mode change. +.Pp +.It Dv VIS_DEVFINI +Tells the graphics driver that it is no longer the system console device. +There is no argument to this ioctl. +The driver is expected to free any locally kept state information related to the console. -.RE - -.sp -.ne 2 -.na -\fB\fBVIS_CONSCURSOR\fR\fR -.ad -.RS 18n -Describes the size and placement of the cursor on the screen. The graphics +.Pp +.It Dv VIS_CONSCURSOR +Describes the size and placement of the cursor on the screen. +The graphics driver is expected to display or hide the cursor at the indicated position. -.RE - -.sp -.LP -The argument is a pointer to a \fBvis_conscursor\fR structure which contains +.Pp +The argument is a pointer to a +.Vt vis_conscursor +structure which contains the following fields: -.sp -.in +2 -.nf +.Bd -literal -offset 2n struct vis_conscursor { screen_pos_t row; screen_pos_t col; @@ -312,48 +326,71 @@ struct vis_conscursor { color_t bg_color; short action; }; -.fi -.in -2 - -.sp -.LP -\fBrow\fR and \fBcol\fR are the first row and column (upper left corner of the -cursor). -.sp -.LP -\fBwidth\fR and \fBheight\fR are the width and height of the cursor. -.sp -.LP -If \fBmode\fR in the \fBVIS_DEVINIT\fR ioctl is set to \fBVIS_PIXEL\fR, then -\fBcol\fR, \fBrow\fR, \fBwidth\fR and \fBheight\fR are in pixels. If \fBmode\fR -in the \fBVIS_DEVINIT\fR ioctl was set to \fBVIS_TEXT\fR, then \fBcol\fR, -\fBrow\fR, \fBwidth\fR and \fBheight\fR are in characters. -.sp -.LP -\fBfg_color\fR and \fBbg_color\fR are the foreground and background color map -indexes to use when the \fBaction\fR (see below) is set to -\fBVIS_DISPLAY_CURSOR\fR. -.sp -.LP -\fBaction\fR indicates whether to display or hide the cursor. It is set to -either \fBVIS_HIDE_CURSOR\fR or \fBVIS_DISPLAY_CURSOR\fR. -.sp -.ne 2 -.na -\fB\fBVIS_CONSDISPLAY\fR\fR -.ad -.RS 19n -Display data on the graphics device. The graphics driver is expected to display -the data contained in the \fBvis_display\fR structure at the specified -position on the console. -.RE - -.sp -.LP -The \fBvis_display\fR structure contains the following fields: -.sp -.in +2 -.nf +.Ed +.Pp +.Fa row +and +.Fa col +are the first row and column (upper left corner of the cursor). +.Pp +.Fa width +and +.Fa height +are the width and height of the cursor. +.Pp +If +.Fa mode +in the +.Dv VIS_DEVINIT +ioctl is set to +.Dv VIS_PIXEL , +then +.Fa col , +.Fa row , +.Fa width +and +.Fa height +are in pixels. +If +.Fa mode +in the +.Dv VIS_DEVINIT +ioctl was set to +.Dv VIS_TEXT , +then +.Fa col , +.Fa row , +.Fa width +and +.Fa height +are in characters. +.Pp +.Fa fg_color +and +.Fa bg_color +are the foreground and background color map +indexes to use when the +.Fa action +(see below) is set to +.Dv VIS_DISPLAY_CURSOR . +.Pp +.Fa action +indicates whether to display or hide the cursor. +It is set to either +.Dv VIS_HIDE_CURSOR +or +.Dv VIS_DISPLAY_CURSOR . +.Pp +.It Dv VIS_CONSDISPLAY +Display data on the graphics device. +The graphics driver is expected to display the data contained in the +.Vt vis_display +structure at the specified position on the console. +.Pp +The +.Vt vis_display +structure contains the following fields: +.Bd -literal -offset 2n struct vis_display { screen_pos_t row; screen_pos_t col; @@ -363,62 +400,135 @@ struct vis_display { color_t fg_color; color_t bg_color; }; -.fi -.in -2 - -.sp -.LP -\fBrow\fR and \fBcol\fR specify at which starting row and column the date is to -be displayed. If \fBmode\fR in the \fBVIS_DEVINIT\fR ioctl was set to -\fBVIS_TEXT\fR, \fBrow\fR and \fBcol\fR are defined to be a character offset -from the starting position of the console device. If \fBmode\fR in the -\fBVIS_DEVINIT\fR ioctl was set to \fBVIS_PIXEL\fR, \fBrow\fR and \fBcol\fR -are defined to be a pixel offset from the starting position of the console +.Ed +.Pp +.Fa row +and +.Fa col +specify at which starting row and column the date is to be displayed. +If +.Fa mode +in the +.Dv VIS_DEVINIT +ioctl was set to +.Dv VIS_TEXT , +.Fa row +and +.Fa col +are defined to be a character offset +from the starting position of the console device. +If +.Fa mode +in the +.Dv VIS_DEVINIT +ioctl was set to +.Dv VIS_PIXEL , +.Fa row +and +.Fa col +are defined to be a pixel offset from the starting position of the console device. -.sp -.LP -\fBwidth\fR and \fBheight\fR specify the size of the \fBdata\fR to be -displayed. If \fBmode\fR in the \fBVIS_DEVINIT\fR ioctl was set to -\fBVIS_TEXT\fR, \fBwidth\fR and \fBheight\fR define the size of \fBdata\fR as -a rectangle that is \fBwidth\fR characters wide and \fBheight\fR characters -high. If \fBmode\fR in the \fBVIS_DEVINIT\fR ioctl was set to \fBVIS_PIXEL\fR, -\fBwidth\fR and \fBheight\fR define the size of \fBdata\fR as a rectangle that -is \fBwidth\fR pixels wide and \fBheight\fR pixels high. -.sp -.LP -\fB*data\fR is a pointer to the data to be displayed on the console device. If -\fBmode\fR in the \fBVIS_DEVINIT\fR ioctl was set to \fBVIS_TEXT\fR, \fBdata\fR -is an array of \fBASCII\fR characters to be displayed on the console device. -The driver must break these characters up appropriately and display it in the -retangle defined by \fBrow\fR, \fBcol\fR, \fBwidth\fR, and \fBheight\fR. If -\fBmode\fR in the \fBVIS_DEVINIT\fR ioctl was set to \fBVIS_PIXEL\fR, -\fBdata\fR is an array of bitmap data to be displayed on the console device. +.Pp +.Fa width +and +.Fa height +specify the size of the +.Fa data +to be displayed. +If +.Fa mode +in the +.Dv VIS_DEVINIT +ioctl was set to +.Dv VIS_TEXT , +.Fa width +and +.Fa height +define the size of +.Fa data +as rectangle that is +.Fa width +characters wide and +.Fa height +characters high. +If +.Fa mode +in the +.Dv VIS_DEVINIT +ioctl was set to +.Dv VIS_PIXEL , +.Fa width +and +.Fa height +define the size of +.Fa data +as a rectangle that is +.Fa width +pixels wide and +.Fa height +pixels high. +.Pp +.Fa *data +is a pointer to the data to be displayed on the console device. +If +.Fa mode +in the +.Dv VIS_DEVINIT +ioctl was set to +.Dv VIS_TEXT , +.Fa data +is an array of +.Sy ASCII +characters to be displayed on the console device. +The driver must break these characters up appropriately and display it in the +rectangle defined by +.Fa row , +.Fa col , +.Fa width , +and +.Fa height . +If +.Fa mode +in the +.Dv VIS_DEVINIT +ioctl was set to +.Dv VIS_PIXEL , +.Fa data +is an array of bitmap data to be displayed on the console device. The driver must break this data up appropriately and display it in the retangle -defined by \fBrow\fR, \fBcol\fR, \fBwidth\fR, and \fBheight\fR. -.sp -.LP -The \fBfg_color\fR and \fBbg_color\fR fields define the foreground and -background color map indexes to use when displaying the data. \fBfb_color\fR is -used for "on" pixels and \fBbg_color\fR is used for "off" pixels. -.sp -.ne 2 -.na -\fB\fBVIS_CONSCOPY\fR\fR -.ad -.RS 16n -Copy data from one location on the device to another. The driver is expected -to copy the specified data. The source data should not be modified. Any -modifications to the source data should be as a side effect of the copy +defined by +.Fa row , +.Fa col , +.Fa width , +and +.Fa height . +.Pp +The +.Fa fg_color +and +.Fa bg_color +fields define the foreground and +background color map indexes to use when displaying the data. +.Fa fb_color +is used for +.Dq on +pixels and +.Fa bg_color +is used for +.Dq off +pixels. +.Pp +.It Dv VIS_CONSCOPY +Copy data from one location on the device to another. +The driver is expected to copy the specified data. +The source data should not be modified. +Any modifications to the source data should be as a side effect of the copy destination overlapping the copy source. -.RE - -.sp -.LP -The argument is a pointer to a \fBvis_copy\fR structure which contains the -following fields: -.sp -.in +2 -.nf +.Pp +The argument is a pointer to a +.Vt vis_copy +structure which contains the following fields: +.Bd -literal -offset 2n struct vis_copy { screen_pos_t s_row; screen_pos_t s_col; @@ -428,135 +538,201 @@ struct vis_copy { screen_pos_t t_col; short direction; }; -.fi -.in -2 - -.sp -.LP -\fBs_row\fR, \fBs_col\fR, \fBe_row\fR, and \fBe_col\fR define the source -rectangle of the copy. \fBs_row\fR and \fBs_col\fR are the upper left corner of -the source rectangle. \fBe_row\fR and \fBe_col\fR are the lower right corner of -the source rectangle. If \fBmode\fR in the \fBVIS_DEVINIT\fR \fBioctl()\fR was -set to \fBVIS_TEXT\fR, \fBs_row\fR, \fBs_col,\fR \fBe_row,\fR and \fBe_col\fR -are defined to be character offsets from the starting position of the console -device. If \fBmode\fR in the \fBVIS_DEVINIT\fR ioctl was set to -\fBVIS_PIXEL\fR, \fBs_row\fR, \fBs_col,\fR \fBe_row,\fR and \fBe_col\fR are -defined to be pixel offsets from the starting position of the console device. -.sp -.LP -\fBt_row\fR and \fBt_col\fR define the upper left corner of the destination -rectangle of the copy. The entire rectangle is copied to this location. If -\fBmode\fR in the \fBVIS_DEVINIT\fR ioctl was set to \fBVIS_TEXT\fR, -\fBt_row\fR, and \fBt_col\fR are defined to be character offsets from the -starting position of the console device. If \fBmode\fR in the -\fBVIS_DEVINIT\fR ioctl was set to \fBVIS_PIXEL\fR, \fBt_row\fR, and -\fBt_col\fR are defined to be pixel offsets from the starting position of the -console device. -.sp -.LP -\fBdirection\fR specifies which way to do the copy. If direction is -\fBVIS_COPY_FORWARD\fR the graphics driver should copy data from position -(\fBs_row\fR, \fBs_col\fR) in the source rectangle to position (\fBt_row\fR, -\fBt_col\fR) in the destination rectangle. If direction is -\fBVIS_COPY_BACKWARDS\fR the graphics driver should copy data from position -(\fBe_row\fR, \fBe_col\fR) in the source rectangle to position -\fB(t_row+(e_row-s_row)\fR, \fBt_col+(e_col-s_col))\fR in the destination -rectangle. -.SS "Console Standalone Entry Points (Polled I/O Interfaces)" -.sp -.LP +.Ed +.Pp +.Fa s_row , +.Fa s_col , +.Fa e_row , +and +.Fa e_col +define the source rectangle of the copy. +.Fa s_row +and +.Fa s_col +are the upper left corner of the source rectangle. +.Fa e_row +and +.Fa e_col +are the lower right corner of the source rectangle. +If +.Fa mode +in the +.Dv VIS_DEVINIT +.Fn ioctl +was set to +.Dv VIS_TEXT , +.Fa s_row , +.Fa s_col , +.Fa e_row , +and +.Fa e_col +are defined to be character offsets from the starting position of the console +device. +If +.Fa mode +in the +.Dv VIS_DEVINIT +.Fn ioctl +was set to +.Dv VIS_PIXEL , +.Fa s_row , +.Fa s_col , +.Fa e_row , +and +.Fa e_col +are +defined to be pixel offsets from the starting position of the console device. +.Pp +.Fa t_row +and +.Fa t_col +define the upper left corner of the destination rectangle of the copy. +The entire rectangle is copied to this location. +If +.Fa mode +in the +.Dv VIS_DEVINIT +ioctl was set to +.Dv VIS_TEXT , +.Fa t_row , +and +.Fa t_col +are defined to be character offsets from the +starting position of the console device. +If +.Fa mode +in the +.Dv VIS_DEVINIT +ioctl was set to +.Dv VIS_PIXEL , +.Fa t_row , +and +.Fa t_col +are defined to be pixel offsets from the starting position of the +onssole device. +.Pp +.Fa direction +specifies which way to do the copy. +If direction is +.Dv VIS_COPY_FORWARD +the graphics driver should copy data from position +.Po +.Fa s_row , +.Fa s_col +.Pc +in the source rectangle to position +.Po +.Fa t_row , +.Fa t_col +.Pc +in the destination rectangle. +If direction is +.Dv VIS_COPY_BACKWARDS +the graphics driver should copy data from position +.Po +.Fa e_row , +.Fa e_col +.Pc +in the source rectangle to position +.Po +.Fa t_row Ns + Ns +.Po +.Fa e_row Ns \- Ns +.Fa s_row +.Pc , +.Fa t_col Ns + Ns +.Po +.Fa e_col Ns \- Ns +.Fa s_col +.Pc +.Pc +in the destination rectangle. +.El +.Ss "Console Standalone Entry Points (Polled I/O Interfaces)" Console standalone entry points are necessary only if the driver is -implementing console-compatible extensions. All console vectored standalone +implementing console-compatible extensions. +All console vectored standalone entry points must be implemented along with all console-related ioctls if the console extension is implemented. -.sp -.in +2 -.nf +.Bd -literal -offset 2n struct vis_polledio { struct vis_polledio_arg *arg; void (*display)(vis_polledio_arg *, struct vis_consdisplay *); void (*copy)(vis_polledio_arg *, struct vis_conscopy *); void (*cursor)(vis_polledio_arg *, struct vis_conscursor *); }; -.fi -.in -2 - -.sp -.LP -The \fBvis_polledio\fR structure is passed from the driver to the Solaris +.Ed +.Pp +The +.Vt vis_polledio +structure is passed from the driver to the illumos operating environment, conveying the entry point addresses of three functions which perform the same operations of their similarly named ioctl counterparts. The rendering parameters for each entry point are derived from the same -structure passed as the respective ioctl. See the Console Optional Ioctls +structure passed as the respective ioctl. +See the +.Sx "Console Optional Ioctls" section of this manpage for an explanation of the specific function each of the -entry points, display(), copy() and cursor() are required to implement. In +entry points, +.Fn display , +.Fn copy , +and +.Fn cursor +are required to implement. +In addition to performing the prescribed function of their ioctl counterparts, the standalone vectors operate in a special context and must adhere to a strict set -of rules. The polled I/O vectors are called directly whenever the system is +of rules. +The polled I/O vectors are called directly whenever the system is quisced (running in a limited context) and must send output to the display. Standalone mode describes the state in which the system is running in -single-threaded mode and only one processor is active. Solaris operating +single-threaded mode and only one processor is active. +illumos operating environment services are stopped, along with all other threads on the system, -prior to entering any of the polled I/O interfaces. The polled I/O vectors are +prior to entering any of the polled I/O interfaces. +The polled I/O vectors are called when the system is running in a standalone debugger, when executing the PROM monitor (OBP) or when panicking. -.sp -.LP +.Pp The following restrictions must be observed in the polled I/O functions: -.RS +4 -.TP -1. +.Bl -enum -offset indent +.It The driver must not allocate memory. -.RE -.RS +4 -.TP -2. +.It The driver must not wait on mutexes. -.RE -.RS +4 -.TP -3. +.It The driver must not wait for interrupts. -.RE -.RS +4 -.TP -4. +.It The driver must not call any DDI or LDI services. -.RE -.RS +4 -.TP -5. +.It The driver must not call any system services. -.RE -.sp -.LP +.El +.Pp The system is single-threaded when calling these functions, meaning that all -other threads are effectively halted. Single-threading makes mutexes (which +other threads are effectively halted. +Single-threading makes mutexes (which cannot be held) easier to deal with, so long as the driver does not disturb any -shared state. See \fIWriting Device Drivers\fR for more information about -implementing polled I/O entry points. -.SH SEE ALSO -.sp -.LP -\fBioctl\fR(2) -.sp -.LP -\fIWriting Device Drivers\fR -.SH NOTES -.sp -.LP +shared state. +See +.%T Writing Device Drivers +for more information about implementing polled I/O entry points. +.Sh SEE ALSO +.Xr ioctl 2 +.Rs +.%T Writing Device Drivers +.Re +.Sh NOTES On SPARC systems, compatible drivers supporting the kernel terminal emulator -should export the \fBtem-support\fR DDI property.\fBtem-support\fR indicates -that the driver supports the kernel terminal emulator. By exporting -\fBtem-support\fR it's possible to avoid premature handling of an incompatible -driver. -.sp -.ne 2 -.na -\fBtem-support\fR -.ad -.RS 15n +should export the +.Sy tem-support +DDI property. +.Sy tem-support +indicates that the driver supports the kernel terminal emulator. +By exporting +.Sy tem-support +it's possible to avoid premature handling of an incompatible driver. +.Bl -tag -width tem-support +.It Sy tem-support This DDI property, set to 1, means driver is compatible with the console kernel framebuffer interface. -.RE - +.El diff --git a/usr/src/man/man7i/vt.7i b/usr/src/man/man7i/vt.7i index b824af02fb..c81860b4f2 100644 --- a/usr/src/man/man7i/vt.7i +++ b/usr/src/man/man7i/vt.7i @@ -1,330 +1,329 @@ -'\" te +.\" Copyright (c) 2017, Joyent, Inc. .\" Copyright (c) 2008 Sun Microsystems, Inc. All Rights Reserved. -.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. -.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. -.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH VT 7I "Sep 22, 2008" -.SH NAME -vt \- Solaris virtual console interface -.SH SYNOPSIS -.LP -.nf -\fB#include <sys/kd.h> \fR -.fi - -.LP -.nf -\fB#include <sys/vt.h> \fR -.fi - -.SH DESCRIPTION -.sp -.LP +.\" The contents of this file are subject to the terms of the +.\" Common Development and Distribution License (the "License"). +.\" You may not use this file except in compliance with the License. +.\" +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE +.\" or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions +.\" and limitations under the License. +.\" +.\" When distributing Covered Code, include this CDDL HEADER in each +.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. +.\" If applicable, add the following below this CDDL HEADER, with the +.\" fields enclosed by brackets "[]" replaced with your own identifying +.\" information: Portions Copyright [yyyy] [name of copyright owner] +.Dd October 29, 2017 +.Dt VT 7I +.Os +.Sh NAME +.Nm vt +.Nd Solaris virtual console interface +.Sh SYNOPSIS +.In sys/kd.h +.In sys/vt.h +.Sh DESCRIPTION The virtual console device driver \(em also known as virtual terminal -(\fBVT\fR) \(em is a layer of management functions that provides facilities to +.Pq Sy VT +\(em is a layer of management functions that provides facilities to support and switch between multiple screen faces on a single physical device. -.sp -.LP -VT's are accessed in the same way as other devices. The \fBopen\fR(2) system -call is used to open the virtual console and \fBread\fR(2), \fBwrite\fR(2) and -\fBioctl\fR(2) are used in the normal way and support the functionality of the -underlying device. In addition, some virtual console-specific ioctls are +.Pp +VT's are accessed in the same way as other devices. +The +.Xr open 2 +system +call is used to open the virtual console and +.Xr read 2 , +.Xr write 2 +and +.Xr ioctl 2 +are used in the normal way and support the functionality of the +underlying device. +In addition, some virtual console-specific ioctls are provided and described below. -.sp -.LP -The VT provides a link between different screen faces and the device. The -\fBactive virtual console\fR corresponds to the currently visible screen face. +.Pp +The VT provides a link between different screen faces and the device. +The +.Sy "active virtual console" +corresponds to the currently visible screen face. Device input is directed to the active console and any device-specific modes that change on a per virtual terminal basis are set to the characteristics associated with the active console. -.sp -.LP -You manage VT's by intercepting keyboard sequences ("hot key"). To maintain -consistency with Xserver, the virtual console device driver supports the Ctrl, -Alt, F# and arrow keys. -.sp -.LP -The sequence \fBAltL + F#\fR (where AltL represents the Alt key and F# -represents function keys 1 through 12) is used to select virtual console 1-12. -The sequence \fBAltGraph + F#\fR (where AltGraph represents the right Alt key -and F# represent function keys 1 through 12) is for virtual console 13-24. -\fBAlt + F1\fR chooses the system console (also known as virtual console 1). -The sequence \fBAlt + ->\fR (where ">" represents the right directional arrow) -selects the next VT in a circular ring fashion and \fBAlt + <-\fR ( where "<" -represents the left directional arrow) changes to the previous console in a -circular fashion. The sequence \fBAlt + ^\fR (where "^" represents the up -directional arrow) is for the last used console. -.sp -.LP -Virtual console switching can be done automatically (\fBVT_AUTO\fR) on receipt -of a ``hot-key'' or by the process owning the VT (\fBVT_PROCESS\fR). When -performed automatically, the process associated with the virtual console is -unaware of the switch. Saving and restoring the device are handled by the -underlying device driver and the virtual console manager. Note that automatic -switching is the default mode. -.sp -.LP -When a ``hot-key'' is sent when in process-controlled switch mode, the process +.Pp +You manage VT's by intercepting keyboard sequences +.Pq Dq "hot key" . +To maintain consistency with Xserver, the virtual console device driver +supports the Ctrl, Alt, F# and arrow keys. +.Pp +The sequence +.Sy "AltL + F#" +(where AltL represents the left Alt key and F# represents function keys 1 +through 12) is used to select virtual console 1-12. +The sequence +.Sy "AltGraph + F#" +(where AltGraph represents the right Alt key and F# represent function keys 1 +through 12) is for virtual console 13-24. +.Sy "Alt + F1" +chooses the system console (also known as virtual console 1). +The sequence +.Sy "Alt + \(->" +(where "\(->" represents the right directional arrow) +selects the next VT in a circular ring fashion and +.Sy "Alt + \(<-" +(where "\(<-" represents the left directional arrow) changes to the previous +console in a circular fashion. +The sequence +.Sy "Alt + \(ua" +(where "\(ua" represents the up directional arrow) is for the last used console. +.Pp +Virtual console switching can be done automatically +.Pq Dv VT_AUTO +on receipt of a +.Dq hot-key +or by the process owning the VT +.Pq Dv VT_PROCESS . +When performed automatically, the process associated with the virtual console is +unaware of the switch. +Saving and restoring the device are handled by the +underlying device driver and the virtual console manager. +Note that automatic switching is the default mode. +.Pp +When a +.Dq hot-key +is sent when in process-controlled switch mode, the process owning the VT is sent a signal (relsig) it has specified to the virtual console -manager (see \fBsignal\fR(3C)) requesting the process to release the physical -device. At this point, the virtual console manager awaits the \fBVT_RELDISP\fR -ioctl from the process. If the process refuses to release the device (meaning -the switch does not occur), it performs a \fBVT_RELDISP\fR ioctl with an -argument of 0 (zero). If the process desires to release the device, it saves +manager (see +.Xr signal 3C ) +requesting the process to release the physical device. +At this point, the virtual console manager awaits the +.Dv VT_RELDISP +ioctl from the process. +If the process refuses to release the device (meaning +the switch does not occur), it performs a +.Dv VT_RELDISP +ioctl with an argument of 0 (zero). +If the process desires to release the device, it saves the device state (keyboard, display, and I/O registers) and then performs a -\fBVT_RELDISP\fR with an argument of 1 to complete the switch. -.sp -.LP +.Dv VT_RELDISP +with an argument of 1 to complete the switch. +.Pp A ring of VT's can contain intermixed auto mode and process control mode -consoles. When an auto mode process becomes active, the underlying device +consoles. +When an auto mode process becomes active, the underlying device driver and the virtual console manager handle the restoring of the device. Process control mode processes are sent a specified signal (acqsig) when they -become the active console. The process then restores the device state -(keyboard, display, and I/O registers) and performs \fBVT_RELDISP\fR ioctl with -an argument of \fBVT_ACKACQ\fR to complete the switching protocol. -.sp -.LP -The modify-operations ioctls (\fBVT_SETMODE\fR, \fBVT_RELDISP\fR, -\fBVT_WAITACTIVE\fR, \fBKDSETMODE\fR) check if the VT is the controlling tty of -the calling process. If not, the sys_devices privilege is enforced. -\fBVT_ACTIVATE\fR requires the sys_devices privilege. Note that there is no +become the active console. +The process then restores the device state +(keyboard, display, and I/O registers) and performs +.Dv VT_RELDISP +ioctl with an argument of +.Dv VT_ACKACQ +to complete the switching protocol. +.Pp +The modify-operations ioctls +.Po +.Dv VT_SETMODE , +.Dv VT_RELDISP , +.Dv VT_WAITACTIVE , +.Dv KDSETMODE +.Pc +check if the VT is the controlling tty of +the calling process. +If not, the sys_devices privilege is enforced. +.Dv VT_ACTIVATE +requires the sys_devices privilege. +Note that there is no controlling tty and privilege check for query/view operations. -.SH IOCTLS -.sp -.LP +.Sh IOCTLS The following ioctls apply to devices that support virtual consoles: -.sp -.ne 2 -.na -\fB\fBVT_ENABLED\fR\fR -.ad -.sp .6 -.RS 4n -Queries to determine if VT functionality is available on the system. The -argument is a pointer to an integer. If VT functionality is available, the +.Bl -tag -width VT_ENABLED +.It Dv VT_ENABLED +Queries to determine if VT functionality is available on the system. +The argument is a pointer to an integer. +If VT functionality is available, the integer is 1, otherwise it is 0. -.RE - -.sp -.ne 2 -.na -\fB\fBVT_OPENQRY\fR\fR -.ad -.sp .6 -.RS 4n -Finds an available VT. The argument is a pointer to an integer. The integer is +.It Dv VT_OPENQRY +Finds an available VT. +The argument is a pointer to an integer. +The integer is filled in with the number of the first available console that no other process -has open (and hence, is available to be opened). If there are no available +has open (and hence, is available to be opened). +If there are no available VT's, -1 is filled in. -.RE - -.sp -.ne 2 -.na -\fB\fBVT_GETMODE\fR\fR -.ad -.sp .6 -.RS 4n -Determines the VT's current mode, either \fBVT_AUTO\fR or \fBVT_PROCESS\fR. The +.It Dv VT_GETMODE +Determines the VT's current mode, either +.Dv VT_AUTO +or +.Dv VT_PROCESS . +The argument is the address of the following structure, as defined in -<\fBsys/vt.h\fR> -.sp -.in +2 -.nf +.In sys/vt.h +.Bd -literal -offset 2n struct vt_mode { - char mode; /* VT mode */ - char waitv; /* not used */ - short relsig;/* signal to use for release request */ - short acqsig;/* signal to use for display acquired */ - short frsig;/* not used */ - } - - /* Virtual console Modes */ - #define VT_AUTO 0 /* automatic VT switching */ - #define VT_PROCESS 1 /* process controls switching */ - + char mode; /* VT mode */ + char waitv; /* not used */ + short relsig; /* signal to use for release request */ + short acqsig; /* signal to use for display acquired */ + short frsig; /* not used */ +} - The structure will be filled in with the current value - for each field. -.fi -.in -2 - -.RE - -.sp -.ne 2 -.na -\fB\fBVT_SETMODE\fR\fR -.ad -.sp .6 -.RS 4n -Sets the VT mode. The argument is a pointer to a vt_mode structure as defined -above. The structure should be filled in with the desired mode. If -process-control mode is specified, the signals used to communicate with the -process should be specified. If any signals are not specified (value is zero), -the signal default is \fBSIGUSR1\fR (for relsig and acqsig). -.RE - -.sp -.ne 2 -.na -\fB\fBVT_RELDISP\fR\fR -.ad -.sp .6 -.RS 4n +/* Virtual console Modes */ +#define VT_AUTO 0 /* automatic VT switching */ +#define VT_PROCESS 1 /* process controls switching */ +.Ed +.Pp +The structure will be filled in with the current value for each field. +.It Dv VT_SETMODE +Sets the VT mode. +The argument is a pointer to a vt_mode structure as defined above. +The structure should be filled in with the desired mode. +If process-control mode is specified, the signals used to communicate with the +process should be specified. +If any signals are not specified (value is zero), the signal default is +.Dv SIGUSR1 +(for relsig and acqsig). +.It Dv VT_RELDISP Tells the VT manager if the process releases (or refuses to release) the -display. An argument of 1 indicates the VT is released. An argument of 0 -indicates refusal to release. The \fBVT_ACKACQ\fR argument indicates if -acquisition of the VT has been completed. -.RE - -.sp -.ne 2 -.na -\fB\fBVT_ACTIVATE\fR\fR -.ad -.sp .6 -.RS 4n +display. +An argument of 1 indicates the VT is released. +An argument of 0 indicates refusal to release. +The +.Dv VT_ACKACQ +argument indicates if acquisition of the VT has been completed. +.It Dv VT_ACTIVATE Makes the VT specified in the argument the active VT (in the same manner as if -a hotkey initiated the switch). If the specified VT is not open or does not -exist, the call fails and errno is set to \fBENXIO\fR. -.RE - -.sp -.ne 2 -.na -\fB\fBVT_WAITACTIVE\fR\fR -.ad -.sp .6 -.RS 4n +a hotkey initiated the switch). +If the specified VT is not open or does not exist, the call fails and errno is +set to +.Er ENXIO . +.It Dv VT_WAITACTIVE If the specified VT is currently active, this call returns immediately. Otherwise, it sleeps until the specified VT becomes active, at which point it returns. -.RE - -.sp -.ne 2 -.na -\fB\fBVT_GETSTATE\fR\fR -.ad -.sp .6 -.RS 4n -Obtains the active VT number and a list of open VTs. The argument is an address -to the following structure: -.sp -.in +2 -.nf +.It Dv VT_GETSTATE +Obtains the active VT number and a list of open VTs. +The argument is an address to the following structure: +.Bd -literal -offset 2n struct vt_stat { - unsigned short v_active, /* number of the active VT */ - v_signal, /* not used */ - v_state; /* count of open VTs. For every 1 in this - field, there is an open VT */ - } -.fi -.in -2 - -With \fBVT_GETSTATE\fR, the VT manager first gets the number of the active VT, + unsigned short v_active, /* number of the active VT */ + v_signal, /* not used */ + /* + * count of open VTs. For every 1 in this + * field, there is an open VT + */ + v_state; +} +.Ed +.Pp +With +.Dv VT_GETSTATE , +the VT manager first gets the number of the active VT, then determines the number of open VTs in the system and sets a 1 for each open -VT in v_state. Next, the VT manager transfers the information in structure -\fBvt_stat\fR passed by the user process. -.RE - -.sp -.ne 2 -.na -\fB\fBKDGETMODE\fR\fR -.ad -.sp .6 -.RS 4n +VT in v_state. +Next, the VT manager transfers the information in structure +.Vt vt_stat +passed by the user process. +.It Dv KDGETMODE Obtains the text/graphics mode associated with the VT. -.sp -.in +2 -.nf - #define KD_TEXT 0 - #define KD_GRAPHICS 1 -.fi -.in -2 - -.RE - -.sp -.ne 2 -.na -\fB\fBKDSETMODE\fR\fR -.ad -.sp .6 -.RS 4n +.Bd -literal -offset 2n +#define KD_TEXT 0 +#define KD_GRAPHICS 1 +.Ed +.It Dv KDSETMODE Sets the text/graphics mode to the VT. -.sp -\fBKD_TEXT\fR indicates that console text is displayed on the screen. Normally -\fBKD_TEXT\fR is combined with \fBVT_AUTO\fR mode for text console terminals, +.It Dv KD_TEXT +indicates that console text is displayed on the screen. +Normally +.Dv KD_TEXT +is combined with +.Dv VT_AUTO +mode for text console terminals, so that the console text display automatically is saved and restored on the hot key screen switches. -.sp -\fBKD_GRAPHICS\fR indicates that the user/application (usually Xserver) has -direct control of the display for this VT in graphics mode. Normally -\fBKD_GRAPHICS\fR is combined with \fBVT_PROCESS\fR mode for this VT indicating -direct control of the display in graphics mode. In this mode, all writes to the +.Pp +.Dv KD_GRAPHICS +indicates that the user/application (usually Xserver) has +direct control of the display for this VT in graphics mode. +Normally +.Dv KD_GRAPHICS +is combined with +.Dv VT_PROCESS +mode for this VT indicating +direct control of the display in graphics mode. +In this mode, all writes to the VT using the write system call are ignored, and you must save and restore the display on the hot key screen switches. -.sp -When the mode of the active VT is changed from \fBKD_TEXT\fR to -\fBKD_GRAPHICS\fR or a VT of \fBKD_GRAPHICS\fR mode is made active from a -previous active VT of \fBKD_TEXT\fR mode, the virtual console manager initiates -a \fBKDSETMODE\fR ioctl with \fBKD_GRAPHICS\fR as the argument to the -underlying console frame buffer device indicating that current display is -running into graphics mode. -.sp -When the mode of the active VT is changed from \fBKD_GRAPHICS\fR to -\fBKD_TEXT\fR or a VT of \fBKD_TEXT\fR mode is actived from a previous active -VT of \fBKD_GRAPHICS\fR mode, the virtual console manager initiates a -\fBKDSETMODE\fR ioctl with \fBKD_TEXT\fR as the argument to the underlying -console frame buffer device indicating that current display is running into -console text mode. -.RE - -.SH FILES -.sp -.ne 2 -.na -\fB\fB/dev/vt/#\fR \fR -.ad -.RS 14n +.Pp +When the mode of the active VT is changed from +.Dv KD_TEXT +to +.Dv KD_GRAPHICS +or a VT of +.Dv KD_GRAPHICS +mode is made active from a +previous active VT of +.Dv KD_TEXT +mode, the virtual console manager initiates a +.Dv KDSETMODE +ioctl with +.Dv KD_GRAPHICS +as the argument to the underlying console frame buffer device indicating that +current display is running into graphics mode. +.Pp +When the mode of the active VT is changed from +.Dv KD_GRAPHICS +to +.Dv KD_TEXT +or a VT of +.Dv KD_TEXT +mode is actived from a previous active VT of +.Dv KD_GRAPHICS +mode, the virtual console manager initiates a +.Dv KDSETMODE +ioctl with +.Dv KD_TEXT +as the argument to the underlying console frame buffer device indicating that +current display is running into console text mode. +.El +.Sh FILES +.Bl -tag -width xxxxxxxxx +.It Pa /dev/vt/# VT devices. -.RE - -.SH SEE ALSO -.sp -.LP -\fBioctl\fR(2), \fBsignal\fR(3C), \fBwscons\fR(7D) -.SH NOTES -.sp -.LP +.El +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr signal 3C , +.Xr wscons 7D +.Sh NOTES By default, there are only five virtual console instance login prompts running -on \fB/dev/vt/#\fR (where "#" represents 2 to 6) in addition to the system -console running on \fB/dev/console\fR. Normally Xorg uses the seventh virtual -console (\fB/dev/vt/7\fR.) To switch from consoles to Xserver (which normally +on +.Pa /dev/vt/# +(where "#" represents 2 to 6) in addition to the system +console running on +.Pa /dev/console . +Normally Xorg uses the seventh virtual console +.Pq Pa /dev/vt/7 . +To switch from consoles to Xserver (which normally picks up the first available virtual console), use [ Ctrl + ] Alt + F7 . -.sp -.in +2 -.nf - # svcs | grep login - online 17:49:11 svc:/system/console-login:default - online 17:49:11 svc:/system/console-login:vt2 - online 17:49:11 svc:/system/console-login:vt3 - online 17:49:11 svc:/system/console-login:vt4 - online 17:49:11 svc:/system/console-login:vt5 - online 17:49:11 svc:/system/console-login:vt6 - - console-login:default is for the system console, others for - virtual consoles. - - You can modify properties/disable/enable and remove/add - virtual consoles using smf(5): - - # svccfg -s console-login add vt8 - # svccfg -s console-login:vt8 setprop ttymon/device=astring: "/dev/vt/8" - # svcadm enable console-login:vt8 -.fi -.in -2 - +.Bd -literal -offset indent +# svcs | grep login +online 17:49:11 svc:/system/console-login:default +online 17:49:11 svc:/system/console-login:vt2 +online 17:49:11 svc:/system/console-login:vt3 +online 17:49:11 svc:/system/console-login:vt4 +online 17:49:11 svc:/system/console-login:vt5 +online 17:49:11 svc:/system/console-login:vt6 +.Ed +.Pp +.Sy console-login:default +is for the system console, others for virtual consoles. +.Pp +You can modify properties/disable/enable and remove/add virtual consoles using +.Xr smf 5 : +.Bd -literal -offset indent +# svccfg -s console-login add vt8 +# svccfg -s console-login:vt8 setprop \e + ttymon/device=astring: "/dev/vt/8" +# svcadm enable console-login:vt8 +.Ed diff --git a/usr/src/uts/common/fs/portfs/port.c b/usr/src/uts/common/fs/portfs/port.c index 04a2a421db..91d998b4b5 100644 --- a/usr/src/uts/common/fs/portfs/port.c +++ b/usr/src/uts/common/fs/portfs/port.c @@ -388,7 +388,7 @@ static int64_t portfs(int, uintptr_t, uintptr_t, uintptr_t, uintptr_t, static struct sysent port_sysent = { 6, SE_ARGC | SE_64RVAL | SE_NOUNLOAD, - (int (*)())portfs, + (int (*)())(uintptr_t)portfs, }; static struct modlsys modlsys = { @@ -404,7 +404,7 @@ portfs32(uint32_t arg1, int32_t arg2, uint32_t arg3, uint32_t arg4, static struct sysent port_sysent32 = { 6, SE_ARGC | SE_64RVAL | SE_NOUNLOAD, - (int (*)())portfs32, + (int (*)())(uintptr_t)portfs32, }; static struct modlsys modlsys32 = { diff --git a/usr/src/uts/common/fs/smbsrv/smb2_negotiate.c b/usr/src/uts/common/fs/smbsrv/smb2_negotiate.c index 52a5dd3a96..7464afe81a 100644 --- a/usr/src/uts/common/fs/smbsrv/smb2_negotiate.c +++ b/usr/src/uts/common/fs/smbsrv/smb2_negotiate.c @@ -11,6 +11,7 @@ /* * Copyright 2018 Nexenta Systems, Inc. All rights reserved. + * Copyright 2019 RackTop Systems. */ /* @@ -22,6 +23,7 @@ static int smb2_negotiate_common(smb_request_t *, uint16_t); +/* List of supported capabilities. Can be patched for testing. */ uint32_t smb2srv_capabilities = SMB2_CAP_DFS | SMB2_CAP_LEASING | @@ -363,7 +365,10 @@ smb2_negotiate_common(smb_request_t *sr, uint16_t version) * One additional check: If KCF is missing something we * require for encryption, turn off that capability. */ - if (s->dialect < SMB_VERS_3_0) { + if (s->dialect < SMB_VERS_2_1) { + /* SMB 2.002 */ + s->srv_cap = smb2srv_capabilities & SMB2_CAP_DFS; + } else if (s->dialect < SMB_VERS_3_0) { /* SMB 2.x */ s->srv_cap = smb2srv_capabilities & SMB_2X_CAPS; } else { diff --git a/usr/src/uts/common/fs/zfs/vdev_disk.c b/usr/src/uts/common/fs/zfs/vdev_disk.c index 3c563e922d..c674dbf811 100644 --- a/usr/src/uts/common/fs/zfs/vdev_disk.c +++ b/usr/src/uts/common/fs/zfs/vdev_disk.c @@ -965,7 +965,7 @@ vdev_disk_io_start(zio_t *zio) dkioc_free_list_t dfl; dfl.dfl_flags = 0; dfl.dfl_num_exts = 1; - dfl.dfl_offset = VDEV_LABEL_START_SIZE; + dfl.dfl_offset = 0; dfl.dfl_exts[0].dfle_start = zio->io_offset; dfl.dfl_exts[0].dfle_length = zio->io_size; diff --git a/usr/src/uts/common/io/cardbus/cardbus.c b/usr/src/uts/common/io/cardbus/cardbus.c index b0bb0a7099..ae82907c87 100644 --- a/usr/src/uts/common/io/cardbus/cardbus.c +++ b/usr/src/uts/common/io/cardbus/cardbus.c @@ -2289,7 +2289,7 @@ cardbus_enable_intr_impl(dev_info_t *dip, dev_info_t *rdip, sih.socket = socket; sih.handler_id = (unsigned)(long)rdip; - sih.handler = (f_tt *)hdlp->ih_cb_func; + sih.handler = (f_tt *)(uintptr_t)hdlp->ih_cb_func; sih.arg1 = hdlp->ih_cb_arg1; sih.arg2 = hdlp->ih_cb_arg2; sih.irq = cardbus_get_pil(dip); @@ -2325,7 +2325,7 @@ cardbus_disable_intr_impl(dev_info_t *dip, dev_info_t *rdip, cih.socket = socket; cih.handler_id = (unsigned)(long)rdip; - cih.handler = (f_tt *)hdlp->ih_cb_func; + cih.handler = (f_tt *)(uintptr_t)hdlp->ih_cb_func; if ((*anp->an_if->pcif_clr_interrupt)(dip, &cih) != SUCCESS) return (DDI_FAILURE); diff --git a/usr/src/uts/common/io/cardbus/cardbus_hp.c b/usr/src/uts/common/io/cardbus/cardbus_hp.c index 1ca4b04e46..a18b69dfcf 100644 --- a/usr/src/uts/common/io/cardbus/cardbus_hp.c +++ b/usr/src/uts/common/io/cardbus/cardbus_hp.c @@ -61,7 +61,7 @@ #define HPC_MAX_OCCUPANTS 8 typedef struct hpc_occupant_info { int i; - char *id[HPC_MAX_OCCUPANTS]; + char *id[HPC_MAX_OCCUPANTS]; } hpc_occupant_info_t; #endif @@ -342,7 +342,7 @@ cardbus_event_handler(caddr_t slot_arg, uint_t event_mask) static int cardbus_pci_control(caddr_t ops_arg, hpc_slot_t slot_hdl, int request, - caddr_t arg) + caddr_t arg) { cbus_t *cbp; int rval = HPC_SUCCESS; @@ -454,7 +454,7 @@ cardbus_pci_control(caddr_t ops_arg, hpc_slot_t slot_hdl, int request, */ static int cardbus_new_slot_state(dev_info_t *dip, hpc_slot_t hdl, - hpc_slot_info_t *slot_info, int slot_state) + hpc_slot_info_t *slot_info, int slot_state) { int cb_instance; cbus_t *cbp; @@ -1111,7 +1111,7 @@ cardbus_close(dev_t dev, int flags, int otyp, cred_t *credp) /*ARGSUSED*/ int cardbus_ioctl(dev_t dev, int cmd, intptr_t arg, int mode, cred_t *credp, - int *rvalp) + int *rvalp) { cbus_t *cbp; dev_info_t *self; @@ -1223,9 +1223,9 @@ cardbus_ioctl(dev_t dev, int cmd, intptr_t arg, int mode, cred_t *credp, /* * check for valid request: - * 1. It is a hotplug slot. - * 2. The slot has no occupant that is in - * the 'configured' state. + * 1. It is a hotplug slot. + * 2. The slot has no occupant that is in + * the 'configured' state. * * The lower 8 bits of the minor number is the PCI * device number for the slot. @@ -1324,7 +1324,7 @@ cardbus_ioctl(dev_t dev, int cmd, intptr_t arg, int mode, cred_t *credp, /* * check for valid request: - * 1. It is a hotplug slot. + * 1. It is a hotplug slot. */ if (cbp->slot_handle == NULL) { rv = ENXIO; @@ -1370,23 +1370,23 @@ cardbus_ioctl(dev_t dev, int cmd, intptr_t arg, int mode, cred_t *credp, case DEVCTL_AP_CONTROL: /* * HPC control functions: - * HPC_CTRL_ENABLE_SLOT/HPC_CTRL_DISABLE_SLOT - * Changes the state of the slot and preserves - * the state across the reboot. - * HPC_CTRL_ENABLE_AUTOCFG/HPC_CTRL_DISABLE_AUTOCFG - * Enables or disables the auto configuration - * of hot plugged occupant if the hardware - * supports notification of the hot plug - * events. - * HPC_CTRL_GET_LED_STATE/HPC_CTRL_SET_LED_STATE - * Controls the state of an LED. - * HPC_CTRL_GET_SLOT_INFO - * Get slot information data structure - * (hpc_slot_info_t). - * HPC_CTRL_GET_BOARD_TYPE - * Get board type information (hpc_board_type_t). - * HPC_CTRL_GET_CARD_INFO - * Get card information (hpc_card_info_t). + * HPC_CTRL_ENABLE_SLOT/HPC_CTRL_DISABLE_SLOT + * Changes the state of the slot and preserves + * the state across the reboot. + * HPC_CTRL_ENABLE_AUTOCFG/HPC_CTRL_DISABLE_AUTOCFG + * Enables or disables the auto configuration + * of hot plugged occupant if the hardware + * supports notification of the hot plug + * events. + * HPC_CTRL_GET_LED_STATE/HPC_CTRL_SET_LED_STATE + * Controls the state of an LED. + * HPC_CTRL_GET_SLOT_INFO + * Get slot information data structure + * (hpc_slot_info_t). + * HPC_CTRL_GET_BOARD_TYPE + * Get board type information (hpc_board_type_t). + * HPC_CTRL_GET_CARD_INFO + * Get card information (hpc_card_info_t). * * These control functions are used by the cfgadm plug-in * to implement "-x" and "-v" options. @@ -1454,7 +1454,7 @@ cardbus_ioctl(dev_t dev, int cmd, intptr_t arg, int mode, cred_t *credp, #endif /* * check for valid request: - * 1. It is a hotplug slot. + * 1. It is a hotplug slot. */ if (cbp->slot_handle == NULL) { rv = ENXIO; @@ -1686,47 +1686,49 @@ struct cardbus_pci_desc { char *fmt; }; +#define CFG_GET(f) ((int(*)())(uintptr_t)f) + static struct cardbus_pci_desc generic_pci_cfg[] = { - { "VendorId =", 0, (int(*)())pci_config_get16, "%s 0x%04x" }, - { "DeviceId =", 2, (int(*)())pci_config_get16, "%s 0x%04x" }, - { "Command =", 4, (int(*)())pci_config_get16, "%s 0x%04x" }, - { "Status =", 6, (int(*)())pci_config_get16, "%s 0x%04x" }, - { "Latency =", 0xd, (int(*)())pci_config_get8, "%s 0x%02x" }, - { "BASE0 =", 0x10, (int(*)())pci_config_get32, "%s 0x%08x" }, - { "BASE1 =", 0x14, (int(*)())pci_config_get32, "%s 0x%08x" }, - { "BASE2 =", 0x18, (int(*)())pci_config_get32, "%s 0x%08x" }, - { "BASE3 =", 0x1c, (int(*)())pci_config_get32, "%s 0x%08x" }, - { "BASE4 =", 0x20, (int(*)())pci_config_get32, "%s 0x%08x" }, - { "CIS Pointer =", 0x28, (int(*)())pci_config_get32, "%s 0x%08x" }, - { "ILINE =", 0x3c, (int(*)())pci_config_get8, "%s 0x%02x" }, - { "IPIN =", 0x3d, (int(*)())pci_config_get8, "%s 0x%02x" }, + { "VendorId =", 0, CFG_GET(pci_config_get16), "%s 0x%04x" }, + { "DeviceId =", 2, CFG_GET(pci_config_get16), "%s 0x%04x" }, + { "Command =", 4, CFG_GET(pci_config_get16), "%s 0x%04x" }, + { "Status =", 6, CFG_GET(pci_config_get16), "%s 0x%04x" }, + { "Latency =", 0xd, CFG_GET(pci_config_get8), "%s 0x%02x" }, + { "BASE0 =", 0x10, CFG_GET(pci_config_get32), "%s 0x%08x" }, + { "BASE1 =", 0x14, CFG_GET(pci_config_get32), "%s 0x%08x" }, + { "BASE2 =", 0x18, CFG_GET(pci_config_get32), "%s 0x%08x" }, + { "BASE3 =", 0x1c, CFG_GET(pci_config_get32), "%s 0x%08x" }, + { "BASE4 =", 0x20, CFG_GET(pci_config_get32), "%s 0x%08x" }, + { "CIS Pointer =", 0x28, CFG_GET(pci_config_get32), "%s 0x%08x" }, + { "ILINE =", 0x3c, CFG_GET(pci_config_get8), "%s 0x%02x" }, + { "IPIN =", 0x3d, CFG_GET(pci_config_get8), "%s 0x%02x" }, { NULL, 0, NULL, NULL } }; static struct cardbus_pci_desc cardbus_pci_cfg[] = { - { "VendorId =", 0, (int(*)())pci_config_get16, "%s 0x%04x" }, - { "DeviceId =", 2, (int(*)())pci_config_get16, "%s 0x%04x" }, - { "Command =", 4, (int(*)())pci_config_get16, "%s 0x%04x" }, - { "Status =", 6, (int(*)())pci_config_get16, "%s 0x%04x" }, - { "CacheLineSz =", 0xc, (int(*)())pci_config_get8, "%s 0x%02x" }, - { "Latency =", 0xd, (int(*)())pci_config_get8, "%s 0x%02x" }, - { "MemBase Addr=", 0x10, (int(*)())pci_config_get32, "%s 0x%08x" }, - { "Pri Bus =", 0x18, (int(*)())pci_config_get8, "%s 0x%02x" }, - { "Sec Bus =", 0x19, (int(*)())pci_config_get8, "%s 0x%02x" }, - { "Sub Bus =", 0x1a, (int(*)())pci_config_get8, "%s 0x%02x" }, - { "CBus Latency=", 0x1b, (int(*)())pci_config_get8, "%s 0x%02x" }, - { "Mem0 Base =", 0x1c, (int(*)())pci_config_get32, "%s 0x%08x" }, - { "Mem0 Limit =", 0x20, (int(*)())pci_config_get32, "%s 0x%08x" }, - { "Mem1 Base =", 0x24, (int(*)())pci_config_get32, "%s 0x%08x" }, - { "Mem1 Limit =", 0x28, (int(*)())pci_config_get32, "%s 0x%08x" }, - { "I/O0 Base =", 0x2c, (int(*)())pci_config_get32, "%s 0x%08x" }, - { "I/O0 Limit =", 0x30, (int(*)())pci_config_get32, "%s 0x%08x" }, - { "I/O1 Base =", 0x34, (int(*)())pci_config_get32, "%s 0x%08x" }, - { "I/O1 Limit =", 0x38, (int(*)())pci_config_get32, "%s 0x%08x" }, - { "ILINE =", 0x3c, (int(*)())pci_config_get8, "%s 0x%02x" }, - { "IPIN =", 0x3d, (int(*)())pci_config_get8, "%s 0x%02x" }, - { "Bridge Ctrl =", 0x3e, (int(*)())pci_config_get16, "%s 0x%04x" }, - { "Legacy Addr =", 0x44, (int(*)())pci_config_get32, "%s 0x%08x" }, + { "VendorId =", 0, CFG_GET(pci_config_get16), "%s 0x%04x" }, + { "DeviceId =", 2, CFG_GET(pci_config_get16), "%s 0x%04x" }, + { "Command =", 4, CFG_GET(pci_config_get16), "%s 0x%04x" }, + { "Status =", 6, CFG_GET(pci_config_get16), "%s 0x%04x" }, + { "CacheLineSz =", 0xc, CFG_GET(pci_config_get8), "%s 0x%02x" }, + { "Latency =", 0xd, CFG_GET(pci_config_get8), "%s 0x%02x" }, + { "MemBase Addr=", 0x10, CFG_GET(pci_config_get32), "%s 0x%08x" }, + { "Pri Bus =", 0x18, CFG_GET(pci_config_get8), "%s 0x%02x" }, + { "Sec Bus =", 0x19, CFG_GET(pci_config_get8), "%s 0x%02x" }, + { "Sub Bus =", 0x1a, CFG_GET(pci_config_get8), "%s 0x%02x" }, + { "CBus Latency=", 0x1b, CFG_GET(pci_config_get8), "%s 0x%02x" }, + { "Mem0 Base =", 0x1c, CFG_GET(pci_config_get32), "%s 0x%08x" }, + { "Mem0 Limit =", 0x20, CFG_GET(pci_config_get32), "%s 0x%08x" }, + { "Mem1 Base =", 0x24, CFG_GET(pci_config_get32), "%s 0x%08x" }, + { "Mem1 Limit =", 0x28, CFG_GET(pci_config_get32), "%s 0x%08x" }, + { "I/O0 Base =", 0x2c, CFG_GET(pci_config_get32), "%s 0x%08x" }, + { "I/O0 Limit =", 0x30, CFG_GET(pci_config_get32), "%s 0x%08x" }, + { "I/O1 Base =", 0x34, CFG_GET(pci_config_get32), "%s 0x%08x" }, + { "I/O1 Limit =", 0x38, CFG_GET(pci_config_get32), "%s 0x%08x" }, + { "ILINE =", 0x3c, CFG_GET(pci_config_get8), "%s 0x%02x" }, + { "IPIN =", 0x3d, CFG_GET(pci_config_get8), "%s 0x%02x" }, + { "Bridge Ctrl =", 0x3e, CFG_GET(pci_config_get16), "%s 0x%04x" }, + { "Legacy Addr =", 0x44, CFG_GET(pci_config_get32), "%s 0x%08x" }, { NULL, 0, NULL, NULL } }; @@ -1796,7 +1798,7 @@ cardbus_dump_pci_config(dev_info_t *dip) void cardbus_dump_socket(dev_info_t *dip) { - ddi_acc_handle_t iohandle; + ddi_acc_handle_t iohandle; caddr_t ioaddr; ddi_device_acc_attr_t attr; attr.devacc_attr_version = DDI_DEVICE_ATTR_V0; diff --git a/usr/src/uts/common/io/cryptmod.c b/usr/src/uts/common/io/cryptmod.c index e2315e8e9e..0975121d09 100644 --- a/usr/src/uts/common/io/cryptmod.c +++ b/usr/src/uts/common/io/cryptmod.c @@ -67,8 +67,8 @@ * Function prototypes. */ static int cryptmodopen(queue_t *, dev_t *, int, int, cred_t *); -static void cryptmodrput(queue_t *, mblk_t *); -static void cryptmodwput(queue_t *, mblk_t *); +static int cryptmodrput(queue_t *, mblk_t *); +static int cryptmodwput(queue_t *, mblk_t *); static int cryptmodclose(queue_t *, int, cred_t *); static int cryptmodwsrv(queue_t *); static int cryptmodrsrv(queue_t *); @@ -92,7 +92,7 @@ static struct module_info cryptmod_minfo = { }; static struct qinit cryptmod_rinit = { - (int (*)())cryptmodrput, /* qi_putp */ + cryptmodrput, /* qi_putp */ cryptmodrsrv, /* qi_svc */ cryptmodopen, /* qi_qopen */ cryptmodclose, /* qi_qclose */ @@ -102,7 +102,7 @@ static struct qinit cryptmod_rinit = { }; static struct qinit cryptmod_winit = { - (int (*)())cryptmodwput, /* qi_putp */ + cryptmodwput, /* qi_putp */ cryptmodwsrv, /* qi_srvp */ NULL, /* qi_qopen */ NULL, /* qi_qclose */ @@ -3254,7 +3254,7 @@ start_stream(queue_t *wq, mblk_t *mp, uchar_t dir) * Write-side put procedure. Its main task is to detect ioctls and * FLUSH operations. Other message types are passed on through. */ -static void +static int cryptmodwput(queue_t *wq, mblk_t *mp) { struct iocblk *iocp; @@ -3267,7 +3267,7 @@ cryptmodwput(queue_t *wq, mblk_t *mp) (tmi->ready & CRYPT_WRITE_READY) && tmi->enc_data.method == CRYPT_METHOD_NONE) { putnext(wq, mp); - return; + return (0); } /* else, put it in the service queue */ if (!putq(wq, mp)) { @@ -3345,7 +3345,7 @@ cryptmodwput(queue_t *wq, mblk_t *mp) stopdir = (uint32_t *)mp->b_cont->b_rptr; if (!CR_DIRECTION_OK(*stopdir)) { miocnak(wq, mp, 0, EINVAL); - return; + return (0); } /* disable the queues until further notice */ @@ -3387,12 +3387,13 @@ cryptmodwput(queue_t *wq, mblk_t *mp) if (wq->q_first != NULL || !canputnext(wq)) { if (!putq(wq, mp)) freemsg(mp); - return; + return (0); } } putnext(wq, mp); break; } + return (0); } /* @@ -3792,7 +3793,7 @@ cryptmodrsrv(queue_t *q) /* * Read-side put procedure. */ -static void +static int cryptmodrput(queue_t *rq, mblk_t *mp) { switch (mp->b_datap->db_type) { @@ -3812,10 +3813,11 @@ cryptmodrput(queue_t *rq, mblk_t *mp) if (rq->q_first != NULL || !canputnext(rq)) { if (!putq(rq, mp)) freemsg(mp); - return; + return (0); } } putnext(rq, mp); break; } + return (0); } diff --git a/usr/src/uts/common/io/pcic.c b/usr/src/uts/common/io/pcic.c index bbf9e11f9e..b2bcc0e91b 100644 --- a/usr/src/uts/common/io/pcic.c +++ b/usr/src/uts/common/io/pcic.c @@ -4744,7 +4744,7 @@ pcic_set_interrupt(dev_info_t *dip, set_irq_handler_t *handler) } pcic->irq_current->intr = - (ddi_intr_handler_t *)handler->handler; + (ddi_intr_handler_t *)(uintptr_t)handler->handler; pcic->irq_current->handler_id = handler->handler_id; pcic->irq_current->arg1 = handler->arg1; pcic->irq_current->arg2 = handler->arg2; @@ -4757,7 +4757,7 @@ pcic_set_interrupt(dev_info_t *dip, set_irq_handler_t *handler) break; default: - intr->intr = (ddi_intr_handler_t *)handler->handler; + intr->intr = (ddi_intr_handler_t *)(uintptr_t)handler->handler; intr->handler_id = handler->handler_id; intr->arg1 = handler->arg1; intr->arg2 = handler->arg2; diff --git a/usr/src/uts/common/io/ppp/spppcomp/spppcomp.c b/usr/src/uts/common/io/ppp/spppcomp/spppcomp.c index db449a07db..313f334684 100644 --- a/usr/src/uts/common/io/ppp/spppcomp/spppcomp.c +++ b/usr/src/uts/common/io/ppp/spppcomp/spppcomp.c @@ -102,10 +102,10 @@ static const char buildtime[] = "Built " __DATE__ " at " __TIME__ static int spppcomp_open(queue_t *, dev_t *, int, int, cred_t *); static int spppcomp_close(queue_t *, int, cred_t *); -static void spppcomp_rput(queue_t *, mblk_t *); -static void spppcomp_rsrv(queue_t *); -static void spppcomp_wput(queue_t *, mblk_t *); -static void spppcomp_wsrv(queue_t *); +static int spppcomp_rput(queue_t *, mblk_t *); +static int spppcomp_rsrv(queue_t *); +static int spppcomp_wput(queue_t *, mblk_t *); +static int spppcomp_wsrv(queue_t *); #define PPPCOMP_MI_MINPSZ (0) #define PPPCOMP_MI_MAXPSZ (INFPSZ) @@ -122,8 +122,8 @@ static struct module_info spppcomp_modinfo = { }; static struct qinit spppcomp_rinit = { - (int (*)())spppcomp_rput, /* qi_putp */ - (int (*)())spppcomp_rsrv, /* qi_srvp */ + spppcomp_rput, /* qi_putp */ + spppcomp_rsrv, /* qi_srvp */ spppcomp_open, /* qi_qopen */ spppcomp_close, /* qi_qclose */ NULL, /* qi_qadmin */ @@ -132,8 +132,8 @@ static struct qinit spppcomp_rinit = { }; static struct qinit spppcomp_winit = { - (int (*)())spppcomp_wput, /* qi_putp */ - (int (*)())spppcomp_wsrv, /* qi_srvp */ + spppcomp_wput, /* qi_putp */ + spppcomp_wsrv, /* qi_srvp */ NULL, /* qi_qopen */ NULL, /* qi_qclose */ NULL, /* qi_qadmin */ @@ -313,7 +313,7 @@ spppcomp_close(queue_t *q, int flag, cred_t *credp) * most processing will be performed here in-line, and deferral * occurs only when necessary. */ -static void +static int spppcomp_wput(queue_t *q, mblk_t *mp) { sppp_comp_t *cp = q->q_ptr; @@ -375,6 +375,7 @@ spppcomp_wput(queue_t *q, mblk_t *mp) freemsg(mp); break; } + return (0); } /* @@ -386,7 +387,7 @@ spppcomp_wput(queue_t *q, mblk_t *mp) * Description: * Write-side service procedure. */ -static void +static int spppcomp_wsrv(queue_t *q) { mblk_t *mp; @@ -404,6 +405,7 @@ spppcomp_wsrv(queue_t *q) (mp = spppcomp_outpkt(q, mp)) != NULL) putnext(q, mp); } + return (0); } /* @@ -1145,7 +1147,7 @@ spppcomp_mctl(queue_t *q, mblk_t *mp) * more and we're in an interrupt context (on the theory that * we're hogging the CPU in this case). */ -static void +static int spppcomp_rput(queue_t *q, mblk_t *mp) { sppp_comp_t *cp = q->q_ptr; @@ -1267,6 +1269,7 @@ spppcomp_rput(queue_t *q, mblk_t *mp) freemsg(mp); break; } + return (0); } /* @@ -1284,7 +1287,7 @@ spppcomp_rput(queue_t *q, mblk_t *mp) * it will put the unprocessed data on the queue for later * handling. */ -static void +static int spppcomp_rsrv(queue_t *q) { mblk_t *mp; @@ -1302,6 +1305,7 @@ spppcomp_rsrv(queue_t *q) (mp = spppcomp_inpkt(q, mp)) != NULL) putnext(q, mp); } + return (0); } /* diff --git a/usr/src/uts/common/io/timod.c b/usr/src/uts/common/io/timod.c index b691108d59..ba81ce3739 100644 --- a/usr/src/uts/common/io/timod.c +++ b/usr/src/uts/common/io/timod.c @@ -311,10 +311,10 @@ int dotilog = 0; static int timodopen(queue_t *, dev_t *, int, int, cred_t *); static int timodclose(queue_t *, int, cred_t *); -static void timodwput(queue_t *, mblk_t *); -static void timodrput(queue_t *, mblk_t *); -static void timodrsrv(queue_t *); -static void timodwsrv(queue_t *); +static int timodwput(queue_t *, mblk_t *); +static int timodrput(queue_t *, mblk_t *); +static int timodrsrv(queue_t *); +static int timodwsrv(queue_t *); static int timodrproc(queue_t *, mblk_t *); static int timodwproc(queue_t *, mblk_t *); @@ -323,8 +323,8 @@ static int timodwproc(queue_t *, mblk_t *); static struct module_info timod_info = {TIMOD_ID, "timod", 0, INFPSZ, 512, 128}; static struct qinit timodrinit = { - (int (*)())timodrput, - (int (*)())timodrsrv, + timodrput, + timodrsrv, timodopen, timodclose, nulldev, @@ -332,8 +332,8 @@ static struct qinit timodrinit = { NULL }; static struct qinit timodwinit = { - (int (*)())timodwput, - (int (*)())timodwsrv, + timodwput, + timodwsrv, timodopen, timodclose, nulldev, @@ -567,7 +567,7 @@ timodclose( * and T_UNITDATA_IND) messages. All others are queued to * be handled by the service procedures. */ -static void +static int timodrput(queue_t *q, mblk_t *mp) { union T_primitives *pptr; @@ -578,7 +578,7 @@ timodrput(queue_t *q, mblk_t *mp) */ if (q->q_first != 0 && mp->b_datap->db_type < QPCTL) { (void) putq(q, mp); - return; + return (0); } /* @@ -623,6 +623,7 @@ timodrput(queue_t *q, mblk_t *mp) (void) timodrproc(q, mp); break; } + return (0); } /* @@ -636,7 +637,7 @@ timodrput(queue_t *q, mblk_t *mp) * from the put procedure. */ /*ARGSUSED*/ -static void +static int timodrsrv(queue_t *q) { mblk_t *mp; @@ -646,7 +647,7 @@ timodrsrv(queue_t *q) tp = (struct tim_tim *)q->q_ptr; if (!tp) - return; + return (0); while ((mp = getq(q)) != NULL) { if (timodrproc(q, mp)) { @@ -654,9 +655,10 @@ timodrsrv(queue_t *q) * timodrproc did a putbq - stop processing * messages. */ - return; + return (0); } } + return (0); } /* @@ -1446,7 +1448,7 @@ timodrproc(queue_t *q, mblk_t *mp) * be handled by the service procedures. */ -static void +static int timodwput(queue_t *q, mblk_t *mp) { union T_primitives *pptr; @@ -1465,7 +1467,7 @@ timodwput(queue_t *q, mblk_t *mp) switch (iocbp->ioc_cmd) { default: (void) putq(q, mp); - return; + return (0); case TI_GETINFO: case TI_SYNC: @@ -1474,7 +1476,7 @@ timodwput(queue_t *q, mblk_t *mp) } } else { (void) putq(q, mp); - return; + return (0); } } /* @@ -1541,6 +1543,7 @@ timodwput(queue_t *q, mblk_t *mp) (void) timodwproc(q, mp); break; } + return (0); } /* * timodwsrv - Module write queue service procedure. @@ -1552,14 +1555,14 @@ timodwput(queue_t *q, mblk_t *mp) * memory allocation could fail, and there is no reasonable * recovery mechanism from the put procedure. */ -static void +static int timodwsrv(queue_t *q) { mblk_t *mp; ASSERT(q != NULL); if (q->q_ptr == NULL) - return; + return (0); while ((mp = getq(q)) != NULL) { if (timodwproc(q, mp)) { @@ -1567,9 +1570,10 @@ timodwsrv(queue_t *q) * timodwproc did a putbq - stop processing * messages. */ - return; + return (0); } } + return (0); } /* diff --git a/usr/src/uts/common/io/tirdwr.c b/usr/src/uts/common/io/tirdwr.c index e42a17aeaf..b15c4752db 100644 --- a/usr/src/uts/common/io/tirdwr.c +++ b/usr/src/uts/common/io/tirdwr.c @@ -25,10 +25,7 @@ */ /* Copyright (c) 1984, 1986, 1987, 1988, 1989 AT&T */ -/* All Rights Reserved */ - - -#pragma ident "%Z%%M% %I% %E% SMI" /* from S5R4 1.4 */ +/* All Rights Reserved */ /* * Transport Interface Library read/write module - issue 1 @@ -76,8 +73,8 @@ static int check_strhead(queue_t *q); * To save instructions, since STREAMS ignores the return value * from these functions, they are defined as void here. Kind of icky, but... */ -static void tirdwrrput(queue_t *q, mblk_t *mp); -static void tirdwrwput(queue_t *q, mblk_t *mp); +static int tirdwrrput(queue_t *q, mblk_t *mp); +static int tirdwrwput(queue_t *q, mblk_t *mp); static struct module_info tirdwr_info = { TIRDWR_ID, @@ -89,8 +86,8 @@ static struct module_info tirdwr_info = { }; static struct qinit tirdwrrinit = { - (int (*)())tirdwrrput, - (int (*)())NULL, + tirdwrrput, + NULL, tirdwropen, tirdwrclose, nulldev, @@ -99,8 +96,8 @@ static struct qinit tirdwrrinit = { }; static struct qinit tirdwrwinit = { - (int (*)())tirdwrwput, - (int (*)())NULL, + tirdwrwput, + NULL, tirdwropen, tirdwrclose, nulldev, @@ -241,7 +238,7 @@ tirdwrclose(queue_t *q, int flag, cred_t *cr) * driver downstream. */ -static void +static int tirdwrrput(queue_t *q, mblk_t *mp) { union T_primitives *pptr; @@ -254,7 +251,7 @@ tirdwrrput(queue_t *q, mblk_t *mp) if ((trwptr->trw_flags & FATAL) && !(trwptr->trw_flags & WAITACK)) { freemsg(mp); - return; + return (0); } switch (mp->b_datap->db_type) { @@ -317,6 +314,7 @@ tirdwrrput(queue_t *q, mblk_t *mp) break; } } + return (0); } @@ -325,7 +323,7 @@ tirdwrrput(queue_t *q, mblk_t *mp) * This is called from the module or * stream head upstream. */ -static void +static int tirdwrwput(queue_t *q, mblk_t *mp) { struct trw_trw *trwptr; @@ -336,7 +334,7 @@ tirdwrwput(queue_t *q, mblk_t *mp) if (trwptr->trw_flags & FATAL) { freemsg(mp); - return; + return (0); } switch (mp->b_datap->db_type) { @@ -353,6 +351,7 @@ tirdwrwput(queue_t *q, mblk_t *mp) send_fatal(q, mp); break; } + return (0); } diff --git a/usr/src/uts/common/io/ttcompat.c b/usr/src/uts/common/io/ttcompat.c index 2cd754afd3..d4cc81e98a 100644 --- a/usr/src/uts/common/io/ttcompat.c +++ b/usr/src/uts/common/io/ttcompat.c @@ -25,7 +25,7 @@ */ /* Copyright (c) 1984, 1986, 1987, 1988, 1989 AT&T */ -/* All Rights Reserved */ +/* All Rights Reserved */ /* * University Copyright- Copyright (c) 1982, 1986, 1988 @@ -111,8 +111,8 @@ _info(struct modinfo *modinfop) static int ttcompatopen(queue_t *, dev_t *, int, int, cred_t *); static int ttcompatclose(queue_t *, int, cred_t *); -static void ttcompatrput(queue_t *, mblk_t *); -static void ttcompatwput(queue_t *, mblk_t *); +static int ttcompatrput(queue_t *, mblk_t *); +static int ttcompatwput(queue_t *, mblk_t *); static struct module_info ttycompatmiinfo = { 0, @@ -124,7 +124,7 @@ static struct module_info ttycompatmiinfo = { }; static struct qinit ttycompatrinit = { - (int (*)())ttcompatrput, + ttcompatrput, NULL, ttcompatopen, ttcompatclose, @@ -142,7 +142,7 @@ static struct module_info ttycompatmoinfo = { }; static struct qinit ttycompatwinit = { - (int (*)())ttcompatwput, + ttcompatwput, NULL, ttcompatopen, ttcompatclose, @@ -217,7 +217,7 @@ ttcompatclose(queue_t *q, int flag, cred_t *crp) * "ioctl" replies, and if it's an "ioctl" whose reply we plan to do * something with, we do it. */ -static void +static int ttcompatrput(queue_t *q, mblk_t *mp) { switch (mp->b_datap->db_type) { @@ -234,13 +234,14 @@ ttcompatrput(queue_t *q, mblk_t *mp) putnext(q, mp); break; } + return (0); } /* * Line discipline output queue put procedure: speeds M_IOCTL * messages. */ -static void +static int ttcompatwput(queue_t *q, mblk_t *mp) { ttcompat_state_t *tp; @@ -257,7 +258,7 @@ ttcompatwput(queue_t *q, mblk_t *mp) default: putnext(q, mp); - return; + return (0); case M_IOCTL: iocbp = (struct iocblk *)mp->b_rptr; @@ -268,7 +269,7 @@ ttcompatwput(queue_t *q, mblk_t *mp) /* these are ioctls with no arguments or are known to stream head */ /* process them right away */ ttcompat_do_ioctl(tp, q, mp); - return; + return (0); case TIOCSETN: case TIOCSLTC: case TIOCSETC: @@ -278,7 +279,7 @@ ttcompatwput(queue_t *q, mblk_t *mp) case TIOCFLUSH: if (iocbp->ioc_count != TRANSPARENT) { putnext(q, mp); - return; + return (0); } mp->b_datap->db_type = M_COPYIN; @@ -311,7 +312,7 @@ ttcompatwput(queue_t *q, mblk_t *mp) tp->t_ioccmd = iocbp->ioc_cmd; tp->t_state |= TS_W_IN; qreply(q, mp); - return; + return (0); } /* switch ioc_cmd */ case M_IOCDATA: @@ -321,7 +322,7 @@ ttcompatwput(queue_t *q, mblk_t *mp) default: putnext(q, mp); - return; + return (0); case TIOCSETN: case TIOCSLTC: @@ -333,7 +334,7 @@ ttcompatwput(queue_t *q, mblk_t *mp) tp->t_state &= ~TS_W_IN; if (csp->cp_rval != 0) { /* failure */ freemsg(mp); - return; + return (0); } /* make it look like an ioctl */ @@ -344,7 +345,7 @@ ttcompatwput(queue_t *q, mblk_t *mp) iocbp->ioc_error = 0; iocbp->ioc_rval = 0; ttcompat_do_ioctl(tp, q, mp); - return; + return (0); case TIOCGLTC: case TIOCLGET: @@ -352,7 +353,7 @@ ttcompatwput(queue_t *q, mblk_t *mp) tp->t_state &= ~TS_W_OUT; if (csp->cp_rval != 0) { /* failure */ freemsg(mp); - return; + return (0); } iocbp = (struct iocblk *)mp->b_rptr; @@ -361,10 +362,11 @@ ttcompatwput(queue_t *q, mblk_t *mp) iocbp->ioc_rval = 0; mp->b_datap->db_type = M_IOCACK; qreply(q, mp); - return; + return (0); } /* switch cp_cmd */ } /* end message switch */ + return (0); } /* @@ -697,7 +699,7 @@ allocfailure: * If this wasn't the response we were waiting for, just pass it up. */ static void -ttcompat_ioctl_ack(queue_t *q, mblk_t *mp) +ttcompat_ioctl_ack(queue_t *q, mblk_t *mp) { ttcompat_state_t *tp; struct iocblk *iocp; diff --git a/usr/src/uts/common/io/usb/clients/audio/usb_ah/usb_ah.c b/usr/src/uts/common/io/usb/clients/audio/usb_ah/usb_ah.c index 3b84d3069f..a56915aabb 100644 --- a/usr/src/uts/common/io/usb/clients/audio/usb_ah/usb_ah.c +++ b/usr/src/uts/common/io/usb/clients/audio/usb_ah/usb_ah.c @@ -75,6 +75,7 @@ static mblk_t *usb_ah_mk_mctl(struct iocblk, void *, size_t); static int usb_ah_open(queue_t *, dev_t *, int, int, cred_t *); static int usb_ah_close(queue_t *, int, cred_t *); static int usb_ah_rput(queue_t *, mblk_t *); +static int usb_ah_wput(queue_t *, mblk_t *); /* * Global Variables @@ -140,7 +141,7 @@ static struct qinit usb_ah_rinit = { /* write side -- just pass everything down */ static struct qinit usb_ah_winit = { - (int (*)(queue_t *, mblk_t *))putnext, + usb_ah_wput, NULL, usb_ah_open, usb_ah_close, @@ -317,7 +318,7 @@ usb_ah_open(queue_t *q, dev_t *devp, int oflag, int sflag, cred_t *crp) */ /* ARGSUSED1 */ static int -usb_ah_close(register queue_t *q, int flag, cred_t *crp) +usb_ah_close(queue_t *q, int flag, cred_t *crp) { usb_ah_state_t *usb_ahd = (usb_ah_state_t *)q->q_ptr; @@ -346,13 +347,19 @@ usb_ah_close(register queue_t *q, int flag, cred_t *crp) return (0); } +static int +usb_ah_wput(queue_t *q, mblk_t *mp) +{ + putnext(q, mp); + return (0); +} /* * usb_ah_rput : * Put procedure for input from driver end of stream (read queue). */ static int -usb_ah_rput(register queue_t *q, register mblk_t *mp) +usb_ah_rput(queue_t *q, mblk_t *mp) { usb_ah_state_t *usb_ahd; @@ -422,10 +429,10 @@ usb_ah_rput(register queue_t *q, register mblk_t *mp) * the command, send it up. */ static void -usb_ah_mctl_receive(register queue_t *q, register mblk_t *mp) +usb_ah_mctl_receive(queue_t *q, mblk_t *mp) { - register usb_ah_state_t *usb_ahd = (usb_ah_state_t *)q->q_ptr; - register struct iocblk *iocp; + usb_ah_state_t *usb_ahd = (usb_ah_state_t *)q->q_ptr; + struct iocblk *iocp; caddr_t data; iocp = (struct iocblk *)mp->b_rptr; @@ -478,7 +485,7 @@ usb_ah_mctl_receive(register queue_t *q, register mblk_t *mp) */ static void usb_ah_repeat_send(usb_ah_state_t *usb_ahd, usb_ah_button_descr_t *bd, - struct iocblk mctlmsg, char *buf, int len) + struct iocblk mctlmsg, char *buf, int len) { mblk_t *dup_mp; diff --git a/usr/src/uts/common/io/usb/clients/usbinput/usbwcm/usbwcm.c b/usr/src/uts/common/io/usb/clients/usbinput/usbwcm/usbwcm.c index 39f2bf252c..2c2266e917 100644 --- a/usr/src/uts/common/io/usb/clients/usbinput/usbwcm/usbwcm.c +++ b/usr/src/uts/common/io/usb/clients/usbinput/usbwcm/usbwcm.c @@ -894,7 +894,7 @@ usbwcm_copyreq(mblk_t *mp, uint_t pvtsize, uint_t state, uint_t reqsize, * overlaps iocp->ioc_count. If user address (cq_addr) * is invalid, it would cause panic later in * usbwcm_copyin: - * freemsg((mblk_t *)copyresp->cp_private); + * freemsg((mblk_t *)copyresp->cp_private); */ cq->cq_private = NULL; } @@ -959,7 +959,7 @@ usbwcm_iocpy(queue_t *q, mblk_t *mp) usbwcm_state_t *usbwcmp = (usbwcm_state_t *)q->q_ptr; struct uwacom_softc *sc = &usbwcmp->usbwcm_softc; struct copyresp *copyresp; - usbwcm_copyin_t *copystat; + usbwcm_copyin_t *copystat; mblk_t *datap, *ioctmp; struct iocblk *iocbp; int err = 0; @@ -1542,7 +1542,7 @@ usbwcm_wput(queue_t *q, mblk_t *mp) * usbwcm_rput() : * Put procedure for input from driver end of stream (read queue). */ -static void +static int usbwcm_rput(queue_t *q, mblk_t *mp) { usbwcm_state_t *usbwcmp = q->q_ptr; @@ -1552,7 +1552,7 @@ usbwcm_rput(queue_t *q, mblk_t *mp) if (usbwcmp == 0) { freemsg(mp); /* nobody's listening */ - return; + return (0); } switch (mp->b_datap->db_type) { @@ -1564,7 +1564,7 @@ usbwcm_rput(queue_t *q, mblk_t *mp) flushq(q, FLUSHDATA); freemsg(mp); - return; + return (0); case M_BREAK: /* @@ -1572,13 +1572,13 @@ usbwcm_rput(queue_t *q, mblk_t *mp) * because nothing is sent from the downstream */ freemsg(mp); - return; + return (0); case M_DATA: if (!(usbwcmp->usbwcm_flags & USBWCM_OPEN)) { freemsg(mp); /* not ready to listen */ - return; + return (0); } /* @@ -1598,18 +1598,19 @@ usbwcm_rput(queue_t *q, mblk_t *mp) case M_CTL: usbwcm_mctl(q, mp); - return; + return (0); case M_ERROR: /* REMOVE */ usbwcmp->usbwcm_flags &= ~USBWCM_QWAIT; freemsg(mp); - return; + return (0); default: putnext(q, mp); - return; + return (0); } + return (0); } @@ -1619,24 +1620,24 @@ static struct module_info modinfo; /* read side queue */ static struct qinit rinit = { - (int (*)())usbwcm_rput, /* put procedure not needed */ - NULL, /* service procedure */ - usbwcm_open, /* called on startup */ - usbwcm_close, /* called on finish */ - NULL, /* for future use */ - &modinfo, /* module information structure */ - NULL /* module statistics structure */ + .qi_putp = usbwcm_rput, + .qi_srvp = NULL, + .qi_qopen = usbwcm_open, + .qi_qclose = usbwcm_close, + .qi_qadmin = NULL, + .qi_minfo = &modinfo, + .qi_mstat = NULL }; /* write side queue */ static struct qinit winit = { - usbwcm_wput, /* put procedure */ - NULL, /* no service proecedure needed */ - NULL, /* open not used on write side */ - NULL, /* close not used on write side */ - NULL, /* for future use */ - &modinfo, /* module information structure */ - NULL /* module statistics structure */ + .qi_putp = usbwcm_wput, + .qi_srvp = NULL, + .qi_qopen = NULL, + .qi_qclose = NULL, + .qi_qadmin = NULL, + .qi_minfo = &modinfo, + .qi_mstat = NULL }; /* STREAMS table */ diff --git a/usr/src/uts/common/os/aio.c b/usr/src/uts/common/os/aio.c index 38f549c096..ae58c198d9 100644 --- a/usr/src/uts/common/os/aio.c +++ b/usr/src/uts/common/os/aio.c @@ -143,7 +143,7 @@ static int aio_port_callback(void *, int *, pid_t, int, void *); static struct sysent kaio_sysent = { 6, SE_NOUNLOAD | SE_64RVAL | SE_ARGC, - (int (*)())kaioc + (int (*)())(uintptr_t)kaioc }; #ifdef _SYSCALL32_IMPL diff --git a/usr/src/uts/common/os/shm.c b/usr/src/uts/common/os/shm.c index 5deae96d73..74f1649a07 100644 --- a/usr/src/uts/common/os/shm.c +++ b/usr/src/uts/common/os/shm.c @@ -186,14 +186,14 @@ static struct sysent ipcshm_sysent = { #else /* _SYSCALL32_IMPL */ SE_ARGC | SE_NOUNLOAD | SE_32RVAL1, #endif /* _SYSCALL32_IMPL */ - (int (*)())shmsys + (int (*)())(uintptr_t)shmsys }; #ifdef _SYSCALL32_IMPL static struct sysent ipcshm_sysent32 = { 4, SE_ARGC | SE_NOUNLOAD | SE_32RVAL1, - (int (*)())shmsys + (int (*)())(uintptr_t)shmsys }; #endif /* _SYSCALL32_IMPL */ @@ -261,7 +261,7 @@ shmat(int shmid, caddr_t uaddr, int uflags, uintptr_t *rvp) struct as *as = pp->p_as; struct segvn_crargs crargs; /* segvn create arguments */ kmutex_t *lock; - struct seg *segspt = NULL; + struct seg *segspt = NULL; caddr_t addr = uaddr; int flags = (uflags & SHMAT_VALID_FLAGS_MASK); int useISM; @@ -629,7 +629,7 @@ shmctl(int shmid, int cmd, void *arg) kshmid_t *sp; /* shared memory header ptr */ STRUCT_DECL(shmid_ds, ds); /* for SVR4 IPC_SET */ int error = 0; - struct cred *cr = CRED(); + struct cred *cr = CRED(); kmutex_t *lock; model_t mdl = get_udatamodel(); struct shmid_ds64 ds64; diff --git a/usr/src/uts/common/rpc/clnt_clts.c b/usr/src/uts/common/rpc/clnt_clts.c index 8a90857172..f881bbc9e2 100644 --- a/usr/src/uts/common/rpc/clnt_clts.c +++ b/usr/src/uts/common/rpc/clnt_clts.c @@ -309,8 +309,8 @@ clnt_clts_stats_fini(zoneid_t zoneid, struct rpc_clts_client **statsp) /* ARGSUSED */ int clnt_clts_kcreate(struct knetconfig *config, struct netbuf *addr, - rpcprog_t pgm, rpcvers_t vers, int retrys, struct cred *cred, - CLIENT **cl) + rpcprog_t pgm, rpcvers_t vers, int retrys, struct cred *cred, + CLIENT **cl) { CLIENT *h; struct cku_private *p; @@ -418,8 +418,8 @@ clnt_clts_kinit(CLIENT *h, struct netbuf *addr, int retrys, cred_t *cred) */ static int clnt_clts_ksettimers(CLIENT *h, struct rpc_timers *t, struct rpc_timers *all, - int minimum, void (*feedback)(int, int, caddr_t), caddr_t arg, - uint32_t xid) + int minimum, void (*feedback)(int, int, caddr_t), caddr_t arg, + uint32_t xid) { /* LINTED pointer alignment */ struct cku_private *p = htop(h); @@ -460,8 +460,8 @@ clnt_clts_ksettimers(CLIENT *h, struct rpc_timers *t, struct rpc_timers *all, */ enum clnt_stat clnt_clts_kcallit_addr(CLIENT *h, rpcproc_t procnum, xdrproc_t xdr_args, - caddr_t argsp, xdrproc_t xdr_results, caddr_t resultsp, - struct timeval wait, struct netbuf *sin) + caddr_t argsp, xdrproc_t xdr_results, caddr_t resultsp, + struct timeval wait, struct netbuf *sin) { /* LINTED pointer alignment */ struct cku_private *p = htop(h); @@ -1004,8 +1004,8 @@ done: static enum clnt_stat clnt_clts_kcallit(CLIENT *h, rpcproc_t procnum, xdrproc_t xdr_args, - caddr_t argsp, xdrproc_t xdr_results, caddr_t resultsp, - struct timeval wait) + caddr_t argsp, xdrproc_t xdr_results, caddr_t resultsp, + struct timeval wait) { return (clnt_clts_kcallit_addr(h, procnum, xdr_args, argsp, xdr_results, resultsp, wait, NULL)); @@ -2005,7 +2005,7 @@ endpnt_repossess(void *a) */ if (endpnt_taskq != NULL) (void) taskq_dispatch(endpnt_taskq, - (task_func_t *)endpnt_reclaim, (void *)ALL_ZONES, + (task_func_t *)(uintptr_t)endpnt_reclaim, (void *)ALL_ZONES, TQ_NOSLEEP); } diff --git a/usr/src/uts/common/rpc/rpcmod.c b/usr/src/uts/common/rpc/rpcmod.c index 5463415c9c..322c6e659f 100644 --- a/usr/src/uts/common/rpc/rpcmod.c +++ b/usr/src/uts/common/rpc/rpcmod.c @@ -212,10 +212,10 @@ int rmm_close(queue_t *, int, cred_t *); * To save instructions, since STREAMS ignores the return value * from these functions, they are defined as void here. Kind of icky, but... */ -void rmm_rput(queue_t *, mblk_t *); -void rmm_wput(queue_t *, mblk_t *); -void rmm_rsrv(queue_t *); -void rmm_wsrv(queue_t *); +int rmm_rput(queue_t *, mblk_t *); +int rmm_wput(queue_t *, mblk_t *); +int rmm_rsrv(queue_t *); +int rmm_wsrv(queue_t *); int rpcmodopen(queue_t *, dev_t *, int, int, cred_t *); int rpcmodclose(queue_t *, int, cred_t *); @@ -237,8 +237,8 @@ static struct module_info rpcmod_info = {RPCMOD_ID, "rpcmod", 0, INFPSZ, 256*1024, 1024}; static struct qinit rpcmodrinit = { - (int (*)())rmm_rput, - (int (*)())rmm_rsrv, + rmm_rput, + rmm_rsrv, rmm_open, rmm_close, nulldev, @@ -252,8 +252,8 @@ static struct qinit rpcmodrinit = { * synchronize with flow control. */ static struct qinit rpcmodwinit = { - (int (*)())rmm_wput, - (int (*)())rmm_wsrv, + rmm_wput, + rmm_wsrv, rmm_open, rmm_close, nulldev, @@ -542,28 +542,32 @@ out: return (error); } -void +int rmm_rput(queue_t *q, mblk_t *mp) { (*((struct temp_slot *)q->q_ptr)->ops->xo_rput)(q, mp); + return (0); } -void +int rmm_rsrv(queue_t *q) { (*((struct temp_slot *)q->q_ptr)->ops->xo_rsrv)(q); + return (0); } -void +int rmm_wput(queue_t *q, mblk_t *mp) { (*((struct temp_slot *)q->q_ptr)->ops->xo_wput)(q, mp); + return (0); } -void +int rmm_wsrv(queue_t *q) { (*((struct temp_slot *)q->q_ptr)->ops->xo_wsrv)(q); + return (0); } int diff --git a/usr/src/uts/common/syscall/exacctsys.c b/usr/src/uts/common/syscall/exacctsys.c index af54737c57..9721c9f4de 100644 --- a/usr/src/uts/common/syscall/exacctsys.c +++ b/usr/src/uts/common/syscall/exacctsys.c @@ -24,8 +24,6 @@ * Use is subject to license terms. */ -#pragma ident "%Z%%M% %I% %E% SMI" - #include <sys/acctctl.h> #include <sys/cmn_err.h> #include <sys/cred.h> @@ -353,7 +351,7 @@ exacct(int code, idtype_t idtype, id_t id, void *buf, size_t bufsize, static struct sysent exacctsys_sysent = { 6, SE_NOUNLOAD | SE_ARGC | SE_LRVAL, - (int (*)())exacct + (int (*)())(uintptr_t)exacct }; static struct modlsys modlsys = { @@ -367,7 +365,7 @@ static struct modlsys modlsys = { static struct sysent exacctsys_sysent32 = { 6, SE_NOUNLOAD | SE_ARGC | SE_32RVAL1, - (int (*)())exacct + (int (*)())(uintptr_t)exacct }; static struct modlsys modlsys32 = { diff --git a/usr/src/uts/intel/io/acpica/osl.c b/usr/src/uts/intel/io/acpica/osl.c index a9d32b281d..a6e7f9788a 100644 --- a/usr/src/uts/intel/io/acpica/osl.c +++ b/usr/src/uts/intel/io/acpica/osl.c @@ -634,7 +634,7 @@ ACPI_OSD_HANDLER acpi_isr; void *acpi_isr_context; uint_t -acpi_wrapper_isr(char *arg) +acpi_wrapper_isr(char *arg, char *arg1 __unused) { _NOTE(ARGUNUSED(arg)) @@ -676,7 +676,7 @@ AcpiOsInstallInterruptHandler(UINT32 InterruptNumber, cmn_err(CE_NOTE, "!acpica: attaching SCI %d", sci_vect); #endif - retval = add_avintr(NULL, SCI_IPL, (avfunc)acpi_wrapper_isr, + retval = add_avintr(NULL, SCI_IPL, acpi_wrapper_isr, "ACPI SCI", sci_vect, NULL, NULL, NULL, NULL); if (retval) { acpi_intr_hooked = 1; @@ -695,7 +695,7 @@ AcpiOsRemoveInterruptHandler(UINT32 InterruptNumber, cmn_err(CE_NOTE, "!acpica: detaching SCI %d", InterruptNumber); #endif if (acpi_intr_hooked) { - rem_avintr(NULL, LOCK_LEVEL - 1, (avfunc)acpi_wrapper_isr, + rem_avintr(NULL, LOCK_LEVEL - 1, acpi_wrapper_isr, InterruptNumber); acpi_intr_hooked = 0; } |