1open(9E) Driver Entry Points open(9E)
2
6 open - gain access to a device
7
9 Block and Character
10 #include <sys/types.h>
11 #include <sys/file.h>
12 #include <sys/errno.h>
13 #include <sys/open.h>
14 #include <sys/cred.h>
15 #include <sys/ddi.h>
16 #include <sys/sunddi.h>
17 int prefixopen(dev_t *devp, int flag, int otyp,
21 cred_t *cred_p);
22 STREAMS
25 #include <sys/file.h>
26 #include <sys/stream.h>
27 #include <sys/ddi.h>
28 #include <sys/sunddi.h>
29 int prefixopen(queue_t *q, dev_t *devp, int oflag, int sflag,
33 cred_t *cred_p);
34
37 Architecture independent level 1 (DDI/DKI). This entry point is
38 required, but it can be nulldev(9F)
39
41 Block and Character
42 devp Pointer to a device number.
43 flag A bit field passed from the user program open(2) system call
46 that instructs the driver on how to open the file. Valid set‐
47 tings are:
48 FEXCL Open the device with exclusive access; fail all
50 other attempts to open the device.
51 FNDELAY Open the device and return immediately. Do not
54 block the open even if something is wrong.
55 FREAD Open the device with read-only permission, If ORed
58 with FWRITE, allow both read and write access.
59 FWRITE Open a device with write-only permission. If ORed
62 with FREAD, allow both read and write access.
63 otyp Parameter supplied for driver to determine how many times a
67 device was opened and for what reasons. For OTYP_BLK and
68 OTYP_CHR, the open() function can be called many times, but
69 the close(9E) function is called only when the last reference
70 to a device is removed. If the device is accessed through
71 file descriptors, it is done by a call to close(2) or
72 exit(2). If the device is accessed through memory mapping, it
73 is done by a call to munmap(2) or exit(2). For OTYP_LYR,
74 there is exactly one close(9E) for each open() operation that
75 is called. This permits software drivers to exist above hard‐
76 ware drivers and removes any ambiguity from the hardware
77 driver regarding how a device is used.
78 OTYP_BLK Open occurred through block interface for the
80 device.
81 OTYP_CHR Open occurred through the raw/character interface
84 for the device.
85 OTYP_LYR Open a layered process. This flag is used when
88 one driver calls another driver's open() or
89 close(9E) function. The calling driver ensures
90 that there is one-layered close for each layered
91 open. This flag applies to both block and charac‐
92 ter devices.
93 cred_p Pointer to the user credential structure.
97 STREAMS
100 q A pointer to the read queue.
101 devp Pointer to a device number. For STREAMS modules, devp always
104 points to the device number associated with the driver at the
105 end (tail) of the stream.
106 oflag Valid oflag values are FEXCL, FNDELAY, FREAD, and FWRITEL —
109 the same as those listed above for flag.. For STREAMS mod‐
110 ules, oflag is always set to 0.
111 sflag Valid values are as follows:
114 CLONEOPEN Indicates that the open() function is called
116 through the clone driver. The driver should
117 return a unique device number.
118 MODOPEN Modules should be called with sflag set to this
121 value. Modules should return an error if they
122 are called with sflag set to a different value.
123 Drivers should return an error if they are
124 called with sflag set to this value.
125 0 Indicates a driver is opened directly, without
128 calling the clone driver.
129 cred_p Pointer to the user credential structure.
133
136 The driver's open() function is called by the kernel during an open(2)
137 or a mount(2) on the special file for the device. A device can be
138 opened simultaneously by multiple processes and the open() driver oper‐
139 ation is called for each open. Note that a device is referenced once
140 its associated open(9E) function is entered, and thus open(9E) opera‐
141 tions which have not yet completed will prevent close(9E) from being
142 called. The function should verify that the minor number component of
143 *devp is valid, that the type of access requested by otyp and flag is
144 appropriate for the device, and, if required, check permissions using
145 the user credentials pointed to by cred_p.
146 The kernel provides open() close() exclusion guarantees to the driver
149 at *devp, otyp granularity. This delays new open() calls to the driver
150 while a last-reference close() call is executing. If the driver has
151 indicated that an EINTR returns safe via the D_OPEN_RETURNS_EINTR
152 cb_ops(9S) cb_flag, a delayed open() may be interrupted by a signal
153 that results in an EINTR return.
154 Last-reference accounting and open() close() exclusion typically sim‐
157 plify driver writing. In some cases, however, they might be an impedi‐
158 ment for certain types of drivers. To overcome any impediment, the
159 driver can change minor numbers in open(9E), as described below, or
160 implement multiple minor nodes for the same device. Both techniques
161 give the driver control over when close() calls occur and whether addi‐
162 tional open() calls will be delayed while close() is executing.
163 The open() function is passed a pointer to a device number so that the
166 driver can change the minor number. This allows drivers to dynamically
167 create minor instances of the device. An example of this might be a
168 pseudo-terminal driver that creates a new pseudo-terminal whenever it
169 is opened. A driver that chooses the minor number dynamically, normally
170 creates only one minor device node in attach(9E) with ddi_cre‐
171 ate_minor_node(9F). It then changes the minor number component of *devp
172 using makedevice(9F) and getmajor(9F). The driver needs to keep track
173 of available minor numbers internally. A driver that dynamically cre‐
174 ates minor numbers might want to avoid returning the original minor
175 number since returning the original minor will result in postponed
176 dynamic opens when original minor close() call occurs.
177 *devp = makedevice(getmajor(*devp), new_minor);
179
182 The open() function should return 0 for success, or the appropriate
183 error number.
184
186 close(2), exit(2), mmap(2), mount(2), munmap(2), open(2), Intro(9E),
187 attach(9E), close(9E), ddi_create_minor_node(9F), getmajor(9F), getmi‐
188 nor(9F), makedevice(9F), nulldev(9F), cb_ops(9S)
189 Writing Device Drivers
192 STREAMS Programming Guide
195
197 Do not attempt to change the major number.
198 When a driver modifies the device number passed in, it must not change
201 the major number portion of the device number. Unless CLONEOPEN is
202 specified, the modified device number must map to the same driver
203 instance indicated by the driver's getinfo(9e) implementation. In other
204 words, cloning across different drivers is not supported. Cloning
205 across different instances of the same driver in only permitted if the
206 driver specified in CLONE_DEV in ddi_create_minor_node(9F) is not sup‐
207 ported.
208SunOS 5.11 24 Apr 2008 open(9E)