Print this page
10527 Convert mhd(7I) to mandoc
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man7i/mhd.7i
+++ new/usr/src/man/man7i/mhd.7i
1 -'\" te
2 1 .\" Copyright (c) 2005 Sun Microsystems, Inc. All Rights Reserved.
3 -.\" 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.
4 -.\" 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.
5 -.\" 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]
6 -.TH MHD 7I "Mar 18, 2011"
7 -.SH NAME
8 -mhd \- multihost disk control operations
9 -.SH SYNOPSIS
10 -.LP
11 -.nf
12 -\fB#include\fR \fB<sys/mhd.h>\fR
13 -.fi
14 -
15 -.SH DESCRIPTION
16 -.sp
17 -.LP
18 -The \fBmhd\fR \fBioctl\fR(2) control access rights of a multihost disk, using
2 +.\" Copyright (c) 2017, Joyent, Inc.
3 +.\" The contents of this file are subject to the terms of the
4 +.\" Common Development and Distribution License (the "License").
5 +.\" You may not use this file except in compliance with the License.
6 +.\"
7 +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
8 +.\" or http://www.opensolaris.org/os/licensing.
9 +.\" See the License for the specific language governing permissions
10 +.\" and limitations under the License.
11 +.\"
12 +.\" When distributing Covered Code, include this CDDL HEADER in each
13 +.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
14 +.\" If applicable, add the following below this CDDL HEADER, with the
15 +.\" fields enclosed by brackets "[]" replaced with your own identifying
16 +.\" information: Portions Copyright [yyyy] [name of copyright owner]
17 +.Dd October 23, 2017
18 +.Dt MHD 7I
19 +.Os
20 +.Sh NAME
21 +.Nm mhd
22 +.Nd multihost disk control operations
23 +.Sh SYNOPSIS
24 +.In sys/mhd.h
25 +.Sh DESCRIPTION
26 +The
27 +.Nm
28 +.Xr ioctl 2
29 +control access rights of a multihost disk, using
19 30 disk reservations on the disk device.
20 -.sp
21 -.LP
22 -The stability level of this interface (see \fBattributes\fR(5)) is evolving. As
23 -a result, the interface is subject to change and you should limit your use of
31 +.Pp
32 +The stability level of this interface (see
33 +.Xr attributes 5 )
34 +is evolving.
35 +As a result, the interface is subject to change and you should limit your use of
24 36 it.
25 -.sp
26 -.LP
37 +.Pp
27 38 The mhd ioctls fall into two major categories: (1) ioctls for non-shared
28 -multihost disks and (2) ioctls for shared multihost disks.
29 -.sp
30 -.LP
31 -One ioctl, \fBMHIOCENFAILFAST\fR, is applicable to both non-shared and shared
32 -multihost disks. It is described after the first two categories.
33 -.sp
34 -.LP
39 +multihost disks and (2) ioctls for shared multihost disks.
40 +.Pp
41 +One ioctl,
42 +.Dv MHIOCENFAILFAST ,
43 +is applicable to both non-shared and shared multihost disks.
44 +It is described after the first two categories.
45 +.Pp
35 46 All the ioctls require root privilege.
36 -.sp
37 -.LP
47 +.Pp
38 48 For all of the ioctls, the caller should obtain the file descriptor for the
39 -device by calling \fBopen\fR(2) with the \fBO_NDELAY\fR flag; without the
40 -\fBO_NDELAY\fR flag, the open may fail due to another host already having a
41 -conflicting reservation on the device. Some of the ioctls below permit the
42 -caller to forcibly clear a conflicting reservation held by another host,
43 -however, in order to call the ioctl, the caller must first obtain the open file
44 -descriptor.
45 -.SS "Non-shared multihost disks"
46 -.sp
47 -.LP
48 -Non-shared multihost disks ioctls consist of \fBMHIOCTKOWN\fR,
49 -\fBMHIOCRELEASE\fR, \fBHIOCSTATUS\fR, and \fBMHIOCQRESERVE\fR. These ioctl
50 -requests control the access rights of non-shared multihost disks. A non-shared
51 -multihost disk is one that supports serialized, mutually exclusive I/O mastery
52 -by the connected hosts. This is in contrast to the shared-disk model, in which
49 +device by calling
50 +.Xr open 2
51 +with the
52 +.Dv O_NDELAY
53 +flag; without the
54 +.Dv O_NDELAY
55 +flag, the open may fail due to another host already having a
56 +conflicting reservation on the device.
57 +Some of the ioctls below permit the caller to forcibly clear a conflicting
58 +reservation held by another host, however, in order to call the ioctl, the
59 +caller must first obtain the open file descriptor.
60 +.Ss "Non-shared multihost disks"
61 +Non-shared multihost disks ioctls consist of
62 +.Dv MHIOCTKOWN ,
63 +.Dv MHIOCRELEASE ,
64 +.Dv HIOCSTATUS ,
65 +and
66 +.Dv MHIOCQRESERVE .
67 +These ioctl requests control the access rights of non-shared multihost disks.
68 +A non-shared multihost disk is one that supports serialized, mutually exclusive
69 +I/O mastery by the connected hosts.
70 +This is in contrast to the shared-disk model, in which
53 71 concurrent access is allowed from more than one host (see below).
54 -.sp
55 -.LP
72 +.Pp
56 73 A non-shared multihost disk can be in one of two states:
57 -.RS +4
58 -.TP
59 -.ie t \(bu
60 -.el o
74 +.Bl -bullet -width indent
75 +.It
61 76 Exclusive access state, where only one connected host has I/O access
62 -.RE
63 -.RS +4
64 -.TP
65 -.ie t \(bu
66 -.el o
67 -Non-exclusive access state, where all connected hosts have I/O access. An
68 -external hardware reset can cause the disk to enter the non-exclusive access
77 +.It
78 +Non-exclusive access state, where all connected hosts have I/O access.
79 +An external hardware reset can cause the disk to enter the non-exclusive access
69 80 state.
70 -.RE
71 -.sp
72 -.LP
81 +.El
82 +.Pp
73 83 Each multihost disk driver views the machine on which it's running as the
74 -"local host"; each views all other machines as "remote hosts". For each I/O or
75 -ioctl request, the requesting host is the local host.
76 -.sp
77 -.LP
78 -Note that the non-shared ioctls are designed to work with SCSI-2 disks. The
84 +.Dq local host ;
85 +each views all other machines as
86 +.Dq remote hosts .
87 +For each I/O or ioctl request, the requesting host is the local host.
88 +.Pp
89 +Note that the non-shared ioctls are designed to work with SCSI-2 disks.
90 +The
79 91 SCSI-2 RESERVE/RELEASE command set is the underlying hardware facility in the
80 92 device that supports the non-shared ioctls.
81 -.sp
82 -.LP
93 +.Pp
83 94 The function prototypes for the non-shared ioctls are:
84 -.sp
85 -.in +2
86 -.nf
87 -ioctl(fd, MHIOCTKOWN);
88 -ioctl(fd, MHIOCRELEASE);
89 -ioctl(fd, MHIOCSTATUS);
90 -ioctl(fd, MHIOCQRESERVE);
91 -.fi
92 -.in -2
93 -
94 -.sp
95 -.ne 2
96 -.na
97 -\fB\fBMHIOCTKOWN\fR \fR
98 -.ad
99 -.RS 18n
95 +.Bd -literal -offset 2n
96 +.Fn ioctl fd MHIOCTKOWN ;
97 +.Fn ioctl fd MHIOCRELEASE ;
98 +.Fn ioctl fd MHIOCSTATUS ;
99 +.Fn ioctl fd MHIOCQRESERVE ;
100 +.Ed
101 +.Bl -tag -width MHIOCQRESERVE
102 +.It Dv MHIOCTKOWN
100 103 Forcefully acquires exclusive access rights to the multihost disk for the local
101 -host. Revokes all access rights to the multihost disk from remote hosts.
104 +host.
105 +Revokes all access rights to the multihost disk from remote hosts.
102 106 Causes the disk to enter the exclusive access state.
103 -.sp
107 +.Pp
104 108 Implementation Note: Reservations (exclusive access rights) broken via random
105 109 resets should be reinstated by the driver upon their detection, for example, in
106 110 the automatic probe function described below.
107 -.RE
108 -
109 -.sp
110 -.ne 2
111 -.na
112 -\fB\fBMHIOCRELEASE\fR \fR
113 -.ad
114 -.RS 18n
111 +.It Dv MHIOCRELEASE
115 112 Relinquishes exclusive access rights to the multihost disk for the local host.
116 -On success, causes the disk to enter the non- exclusive access state.
117 -.RE
118 -
119 -.sp
120 -.ne 2
121 -.na
122 -\fB\fBMHIOCSTATUS\fR \fR
123 -.ad
124 -.RS 18n
113 +On success, causes the disk to enter the non- exclusive access state.
114 +.It Dv MHIOCSTATUS
125 115 Probes a multihost disk to determine whether the local host has access rights
126 -to the disk. Returns \fB0\fR if the local host has access to the disk,
127 -\fB1\fR if it doesn't, and \fB-1\fR with errno set to \fBEIO\fR if the probe
128 -failed for some other reason.
129 -.RE
130 -
131 -.sp
132 -.ne 2
133 -.na
134 -\fB\fBMHIOCQRESERVE\fR \fR
135 -.ad
136 -.RS 18n
137 -Issues, simply and only, a SCSI-2 Reserve command. If the attempt to reserve
116 +to the disk.
117 +Returns
118 +.Sy 0
119 +if the local host has access to the disk,
120 +.Sy 1
121 +if it doesn't, and
122 +.Sy -1
123 +with
124 +.Va errno
125 +set to
126 +.Er EIO
127 +if the probe failed for some other reason.
128 +.It Dv MHIOCQRESERVE
129 +Issues, simply and only, a SCSI-2 Reserve command.
130 +If the attempt to reserve
138 131 fails due to the SCSI error Reservation Conflict (which implies that some other
139 -host has the device reserved), then the ioctl will return \fB-1\fR with errno
140 -set to \fBEACCES\fR. The \fBMHIOCQRESERVE\fR ioctl does NOT issue a bus device
141 -reset or bus reset prior to attempting the SCSI-2 reserve command. It also
132 +host has the device reserved), then the ioctl will return
133 +.Sy -1
134 +with
135 +.Va errno
136 +set to
137 +.Er EACCES .
138 +The
139 +.Dv MHIOCQRESERVE
140 +ioctl does NOT issue a bus device
141 +reset or bus reset prior to attempting the SCSI-2 reserve command.
142 +It also
142 143 does not take care of re-instating reservations that disappear due to bus
143 144 resets or bus device resets; if that behavior is desired, then the caller can
144 -call \fBMHIOCTKOWN\fR after the \fBMHIOCQRESERVE\fR has returned success. If
145 +call
146 +.Dv MHIOCTKOWN
147 +after the
148 +.Dv MHIOCQRESERVE
149 +has returned success.
150 +If
145 151 the device does not support the SCSI-2 Reserve command, then the ioctl returns
146 -\fB-1\fR with \fBerrno\fR set to \fBENOTSUP.\fR The \fBMHIOCQRESERVE\fR ioctl
147 -is intended to be used by high-availability or clustering software for a
148 -"quorum" disk, hence, the "Q" in the name of the ioctl.
149 -.RE
150 -
151 -.SS "Shared Multihost Disks"
152 -.sp
153 -.LP
154 -Shared multihost disks ioctls control access to shared multihost disks. The
155 -ioctls are merely a veneer on the SCSI-3 Persistent Reservation facility.
152 +.Er -1
153 +with
154 +.Va errno
155 +set to
156 +.Er ENOTSUP .
157 +The
158 +.Dv MHIOCQRESERVE
159 +ioctl is intended to be used by high-availability or clustering software for a
160 +.Dq quorum
161 +disk, hence, the
162 +.Dq Q
163 +in the name of the ioctl.
164 +.El
165 +.Ss "Shared Multihost Disks"
166 +Shared multihost disks ioctls control access to shared multihost disks.
167 +The ioctls are merely a veneer on the SCSI-3 Persistent Reservation facility.
156 168 Therefore, the underlying semantic model is not described in detail here, see
157 -instead the SCSI-3 standard. The SCSI-3 Persistent Reservations support the
169 +instead the SCSI-3 standard.
170 +The SCSI-3 Persistent Reservations support the
158 171 concept of a group of hosts all sharing access to a disk.
159 -.sp
160 -.LP
172 +.Pp
161 173 The function prototypes and descriptions for the shared multihost ioctls are as
162 174 follows:
163 -.sp
164 -.ne 2
165 -.na
166 -\fB\fBioctl\fR(\fBfd\fR, \fBMHIOCGRP_INKEYS\fR, (\fBmhioc_inkeys_t\fR)
167 -\fI*k\fR\fB);\fR\fR
168 -.ad
169 -.sp .6
170 -.RS 4n
171 -Issues the SCSI-3 command Persistent Reserve In Read Keys to the device. On
172 -input, the field \fBk->li\fR should be initialized by the caller with
173 -\fBk->li.listsize\fR reflecting how big of an array the caller has allocated
174 -for the \fBk->li.list\fR field and with \fBk->li.listlen\fR \fB==\fR \fB0.\fR
175 -On return, the field \fBk->li.listlen\fR is updated to indicate the number of
175 +.Bl -tag -width 1n
176 +.It Fn ioctl fd MHIOCGRP_INKEYS "(mhioc_inkeys_t *)k"
177 +.Pp
178 +Issues the SCSI-3 command Persistent Reserve In Read Keys to the device.
179 +On input, the field
180 +.Fa k->li
181 +should be initialized by the caller with
182 +.Fa k->li.listsize
183 +reflecting how big of an array the caller has allocated for the
184 +.Fa k->lilist
185 +field and with
186 +.Ql k->li.listlen\& ==\& 0 .
187 +On return, the field
188 +.Fa k->li.listlen
189 +is updated to indicate the number of
176 190 reservation keys the device currently has: if this value is larger than
177 -\fBk->li.listsize\fR then that indicates that the caller should have passed a
178 -bigger \fBk->li.list\fR array with a bigger \fBk->li.listsize.\fR The number of
179 -array elements actually written by the callee into \fBk->li.list\fR is the
180 -minimum of \fBk->li.listlen\fR and \fBk->li.listsize.\fR The field
181 -k->generation is updated with the generation information returned by the SCSI-3
182 -Read Keys query. If the device does not support SCSI-3 Persistent Reservations,
183 -then this ioctl returns \fB-1\fR with \fBerrno\fR set to \fBENOTSUP\fR.
184 -.RE
185 -
186 -.sp
187 -.ne 2
188 -.na
189 -\fB\fBioctl\fR(\fBfd\fR, \fBMHIOCGRP_INRESV\fR, (\fBmhioc_inresvs_t\fR)
190 -\fI*r\fR\fB);\fR\fR
191 -.ad
192 -.sp .6
193 -.RS 4n
191 +.Fa k->li.listsize
192 +then that indicates that the caller should have passed a bigger
193 +.Fa k->li.list
194 +array with a bigger
195 +.Fa k->li.listsize .
196 +The number of array elements actually written by the callee into
197 +.Fa k->li.list
198 +is the minimum of
199 +.Fa k->li.listlen
200 +and
201 +.Fa k->li.listsize .
202 +The field
203 +.Fa k->generation
204 +is updated with the generation information returned by the SCSI-3
205 +Read Keys query.
206 +If the device does not support SCSI-3 Persistent Reservations,
207 +then this ioctl returns
208 +.Sy -1
209 +with
210 +.Va errno
211 +set to
212 +.Er ENOTSUP .
213 +.It Fn ioctl fd MHIOCGRP_INRESV "(mhioc_inresvs_t *)r"
214 +.Pp
194 215 Issues the SCSI-3 command Persistent Reserve In Read Reservations to the
195 -device. Remarks similar to \fBMHIOCGRP_INKEYS\fR apply to the array
196 -manipulation. If the device does not support SCSI-3 Persistent Reservations,
197 -then this ioctl returns \fB-1\fR with \fBerrno\fR set to \fBENOTSUP\fR.
198 -.RE
199 -
200 -.sp
201 -.ne 2
202 -.na
203 -\fB\fBioctl\fR(\fBfd\fR, \fBMHIOCGRP_REGISTER\fR, (\fBmhioc_register_t\fR)
204 -\fI*r\fR\fB);\fR\fR
205 -.ad
206 -.sp .6
207 -.RS 4n
208 -Issues the SCSI-3 command Persistent Reserve Out Register. The fields of
209 -structure \fIr\fR are all inputs; none of the fields are modified by the ioctl.
210 -The field \fBr->aptpl\fR should be set to true to specify that registrations
216 +device.
217 +Remarks similar to
218 +.Dv MHIOCGRP_INKEYS
219 +apply to the array manipulation.
220 +If the device does not support SCSI-3 Persistent Reservations,
221 +then this ioctl returns
222 +.Sy -1
223 +with
224 +.Va errno
225 +set to
226 +.Er ENOTSUP .
227 +.It Fn ioctl fd MHIOCGRP_REGISTER "(mhioc_register_t *)r"
228 +.Pp
229 +Issues the SCSI-3 command Persistent Reserve Out Register.
230 +The fields of structure
231 +.Va r
232 +are all inputs; none of the fields are modified by the ioctl.
233 +The field
234 +.Fa r->aptpl
235 +should be set to true to specify that registrations
211 236 and reservations should persist across device power failures, or to false to
212 237 specify that registrations and reservations should be cleared upon device power
213 -failure; true is the recommended setting. The field \fBr->oldkey\fR is the key
214 -that the caller believes the device may already have for this host initiator;
215 -if the caller believes that that this host initiator is not already registered
216 -with this device, it should pass the special key of all zeros. To achieve the
217 -effect of unregistering with the device, the caller should pass its current key
218 -for the \fBr->oldkey\fR field and an \fBr->newkey\fR field containing the
219 -special key of all zeros. If the device returns the SCSI error code
220 -Reservation Conflict, this ioctl returns \fB-1\fR with \fBerrno\fR set to
221 -\fBEACCES\fR.
222 -.RE
223 -
224 -.sp
225 -.ne 2
226 -.na
227 -\fB\fBioctl\fR(\fBfd\fR, \fBMHIOCGRP_RESERVE\fR, (\fBmhioc_resv_desc_t\fR)
228 -\fI*r\fR\fB);\fR\fR
229 -.ad
230 -.sp .6
231 -.RS 4n
232 -Issues the SCSI-3 command Persistent Reserve Out Reserve. The fields of
233 -structure \fIr\fR are all inputs; none of the fields are modified by the ioctl.
238 +failure; true is the recommended setting.
239 +The field
240 +.Fa r->oldkey
241 +is the key that the caller believes the device may already have for this host
242 +initiator; if the caller believes that that this host initiator is not already
243 +registered with this device, it should pass the special key of all zeros.
244 +To achieve the effect of unregistering with the device, the caller should pass
245 +its current key for the
246 +.Fa r->oldkey
247 +field and an
248 +.Fa r->newkey
249 +field containing the special key of all zeros.
250 +If the device returns the SCSI error code
251 +Reservation Conflict, this ioctl returns
252 +.Sy -1
253 +with
254 +.Va errno
255 +set to
256 +.Er EACCES .
257 +.It Fn ioctl fd MHIOCGRP_RESERVE "(mhioc_resv_desc_t *)r"
258 +.Pp
259 +Issues the SCSI-3 command Persistent Reserve Out Reserve.
260 +The fields of
261 +structure
262 +.Va r
263 +are all inputs; none of the fields are modified by the ioctl.
234 264 If the device returns the SCSI error code Reservation Conflict, this ioctl
235 -returns \fB-1\fR with \fBerrno\fR set to \fBEACCES.\fR
236 -.RE
237 -
238 -.sp
239 -.ne 2
240 -.na
241 -\fB\fBioctl\fR(\fBfd\fR, \fBMHIOCGRP_PREEMPTANDABORT\fR,
242 -(\fBmhioc_preemptandabort_t\fR) \fI*r\fR\fB);\fR\fR
243 -.ad
244 -.sp .6
245 -.RS 4n
246 -Issues the SCSI-3 command Persistent Reserve Out Preempt-And-Abort. The fields
247 -of structure \fIr\fR are all inputs; none of the fields are modified by the
248 -ioctl. The key of the victim host is specified by the field
249 -\fBr->victim_key\fR. The field \fBr->resvdesc\fR supplies the preempter's key
250 -and the reservation that it is requesting as part of the SCSI-3
251 -Preempt-And-Abort command. If the device returns the SCSI error code
252 -Reservation Conflict, this ioctl returns \fB-1\fR with \fBerrno\fR set to
253 -\fBEACCES.\fR
254 -.RE
255 -
256 -.sp
257 -.ne 2
258 -.na
259 -\fB\fBioctl\fR(\fBfd\fR, \fBMHIOCGRP_PREEMPT\fR,
260 -(\fBmhioc_preemptandabort_t\fR) \fI*r\fR\fB);\fR\fR
261 -.ad
262 -.sp .6
263 -.RS 4n
264 -Similar to \fBMHIOCGRP_PREEMPTANDABORT\fR, but instead issues the SCSI-3
265 -command Persistent Reserve Out Preempt. (Note: This command is not
266 -implemented).
267 -.RE
268 -
269 -.sp
270 -.ne 2
271 -.na
272 -\fB\fBioctl\fR(\fBfd\fR, \fBMHIOCGRP_CLEAR\fR, (\fBmhioc_resv_key_t\fR)
273 -\fI*r\fR\fB);\fR\fR
274 -.ad
275 -.sp .6
276 -.RS 4n
277 -Issues the SCSI-3 command Persistent Reserve Out Clear. The input parameter
278 -\fIr\fR is the reservation key of the caller, which should have been already
279 -registered with the device, by an earlier call to \fBMHIOCGRP_REGISTER\fR.
280 -.RE
281 -
282 -.sp
283 -.LP
265 +returns
266 +.Sy -1
267 +with
268 +.Va errno
269 +set to
270 +.Er EACCES .
271 +.It Fn ioctl fd MHIOCGRP_PREEMPTANDABORT "(mhioc_preemptandabort_t *)r"
272 +.Pp
273 +Issues the SCSI-3 command Persistent Reserve Out Preempt-And-Abort.
274 +The fields
275 +of structure
276 +.Va r
277 +are all inputs; none of the fields are modified by the ioctl.
278 +The key of the victim host is specified by the field
279 +.Fa r->victim_key .
280 +The field
281 +.Fa r->resvdesc
282 +supplies the preempter's key and the reservation that it is requesting as part
283 +of the SCSI-3 Preempt-And-Abort command.
284 +If the device returns the SCSI error code
285 +Reservation Conflict, this ioctl returns
286 +.Sy -1
287 +with
288 +.Va errno
289 +set to
290 +.Er EACCES .
291 +.It Fn ioctl fd MHIOCGRP_PREEMPT "(mhioc_preemptandabort_t *)r"
292 +.Pp
293 +Similar to
294 +.Dv MHIOCGRP_PREEMPTANDABORT ,
295 +but instead issues the SCSI-3 command Persistent Reserve Out Preempt.
296 +(Note: This command is not implemented).
297 +.It Fn ioctl fd MHIOCGRP_CLEAR "(mhioc_resv_key_t *)r"
298 +Issues the SCSI-3 command Persistent Reserve Out Clear.
299 +The input parameter
300 +.Va r
301 +is the reservation key of the caller, which should have been already
302 +registered with the device, by an earlier call to
303 +.Dv MHIOCGRP_REGISTER .
304 +.El
305 +.Pp
284 306 For each device, the non-shared ioctls should not be mixed with the Persistent
285 307 Reserve Out shared ioctls, and vice-versa, otherwise, the underlying device is
286 308 likely to return errors, because SCSI does not permit SCSI-2 reservations to be
287 -mixed with SCSI-3 reservations on a single device. It is, however, legitimate
309 +mixed with SCSI-3 reservations on a single device.
310 +It is, however, legitimate
288 311 to call the Persistent Reserve In ioctls, because these are query only.
289 -Issuing the \fBMHIOCGRP_INKEYS\fR ioctl is the recommended way for a caller to
290 -determine if the device supports SCSI-3 Persistent Reservations (the ioctl
291 -will return \fB-1\fR with \fBerrno\fR set to \fBENOTSUP\fR if the device does
292 -not).
293 -.SS "MHIOCENFAILFAST Ioctl"
294 -.sp
295 -.LP
296 -The \fBMHIOCENFAILFAST\fR ioctl is applicable for both non-shared and shared
312 +Issuing the
313 +.Dv MHIOCGRP_INKEYS
314 +ioctl is the recommended way for a caller to
315 +determine if the device supports SCSI-3 Persistent Reservations (the ioctl
316 +will return
317 +.Sy -1
318 +with
319 +.Va errno
320 +set to
321 +.Er ENOTSUP
322 +if the device does not).
323 +.Ss "MHIOCENFAILFAST Ioctl"
324 +The
325 +.Dv MHIOCENFAILFAST
326 +ioctl is applicable for both non-shared and shared
297 327 disks, and may be used with either the non-shared or shared ioctls.
298 -.sp
299 -.ne 2
300 -.na
301 -\fB\fBioctl\fR(\fBfd\fR, \fBMHIOENFAILFAST\fR, (unsigned int \fI*\fR)
302 -\fImillisecs\fR\fB);\fR\fR
303 -.ad
304 -.sp .6
305 -.RS 4n
328 +.Bl -tag -width 1n
329 +.It Fn ioctl fd MHIOENFAILFAST "(unsigned int *)millisecs"
330 +.Pp
306 331 Enables or disables the failfast option in the multihost disk driver and
307 332 enables or disables automatic probing of a multihost disk, described below.
308 333 The argument is an unsigned integer specifying the number of milliseconds to
309 -wait between executions of the automatic probe function. An argument of zero
310 -disables the failfast option and disables automatic probing. If the
311 -\fBMHIOCENFAILFAST\fR ioctl is never called, the effect is defined to be that
334 +wait between executions of the automatic probe function.
335 +An argument of zero disables the failfast option and disables automatic probing.
336 +If the
337 +.Dv MHIOCENFAILFAST
338 +ioctl is never called, the effect is defined to be that
312 339 both the failfast option and automatic probing are disabled.
313 -.RE
314 -
315 -.SS "Automatic Probing"
316 -.sp
317 -.LP
318 -The \fBMHIOCENFAILFAST\fR ioctl sets up a timeout in the driver to periodically
319 -schedule automatic probes of the disk. The automatic probe function works in
320 -this manner: The driver is scheduled to probe the multihost disk every n
321 -milliseconds, rounded up to the next integral multiple of the system clock's
322 -resolution. If
323 -.RS +4
324 -.TP
325 -1.
326 -the local host no longer has access rights to the multihost disk, and
327 -.RE
328 -.RS +4
329 -.TP
330 -2.
331 -access rights were expected to be held by the local host,
332 -.RE
333 -.sp
334 -.LP
340 +.El
341 +.Ss "Automatic Probing"
342 +The
343 +.Dv MHIOCENFAILFAST
344 +ioctl sets up a timeout in the driver to periodically
345 +schedule automatic probes of the disk.
346 +The automatic probe function works in this manner: The driver is scheduled to
347 +probe the multihost disk every n milliseconds, rounded up to the next integral
348 +multiple of the system clock's resolution.
349 +If
350 +.Bl -enum -offset indent
351 +.It
352 +the local host no longer has access rights to the multihost disk, and
353 +.It
354 +access rights were expected to be held by the local host,
355 +.El
356 +.Pp
335 357 the driver immediately panics the machine to comply with the failfast model.
336 -.sp
337 -.LP
358 +.Pp
338 359 If the driver makes this discovery outside the timeout function, especially
339 360 during a read or write operation, it is imperative that it panic the system
340 361 then as well.
341 -.SH RETURN VALUES
342 -.sp
343 -.LP
344 -Each request returns \fB-1\fR on failure and sets \fBerrno\fR to indicate the
345 -error.
346 -.sp
347 -.ne 2
348 -.na
349 -\fB\fBEPERM\fR \fR
350 -.ad
351 -.RS 14n
362 +.Sh RETURN VALUES
363 +Each request returns
364 +.Sy -1
365 +on failure and sets
366 +.Va errno
367 +to indicate the error.
368 +.Bl -tag -width Er
369 +.It Er EPERM
352 370 Caller is not root.
353 -.RE
354 -
355 -.sp
356 -.ne 2
357 -.na
358 -\fB\fBEACCES\fR \fR
359 -.ad
360 -.RS 14n
371 +.It Er EACCES
361 372 Access rights were denied.
362 -.RE
363 -
364 -.sp
365 -.ne 2
366 -.na
367 -\fB\fBEIO\fR\fR
368 -.ad
369 -.RS 14n
373 +.It Er EIO
370 374 The multihost disk or controller was unable to successfully complete the
371 375 requested operation.
372 -.RE
373 -
374 -.sp
375 -.ne 2
376 -.na
377 -\fB\fBEOPNOTSUP\fR \fR
378 -.ad
379 -.RS 14n
380 -The multihost disk does not support the operation. For example, it does not
381 -support the SCSI-2 Reserve/Release command set, or the SCSI-3 Persistent
382 -Reservation command set.
383 -.RE
384 -
385 -.SH ATTRIBUTES
386 -.sp
387 -.LP
388 -See \fBattributes\fR(5) for a description of the following attributes:
389 -.sp
390 -
391 -.sp
392 -.TS
393 -box;
394 -c | c
395 -l | l .
396 -ATTRIBUTE TYPE ATTRIBUTE VALUE
397 -_
398 -Stability Evolving
399 -.TE
400 -
401 -.SH SEE ALSO
402 -.sp
403 -.LP
404 -\fBioctl\fR(2), \fBopen\fR(2), \fBattributes\fR(5), open(2)
376 +.It Er EOPNOTSUP
377 +The multihost disk does not support the operation.
378 +For example, it does not support the SCSI-2 Reserve/Release command set, or the
379 +SCSI-3 Persistent Reservation command set.
380 +.El
381 +.Sh STABILITY
382 +Uncommitted
383 +.Sh SEE ALSO
384 +.Xr ioctl 2 ,
385 +.Xr open 2 ,
386 +.Xr attributes 5
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX