close(9e) - osol9

1close(9E)                     Driver Entry Points                    close(9E)
2
3
4

NAME

6       close - relinquish access to a device
7

SYNOPSIS

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
18
19
20       int prefixclose(dev_t dev, int flag, int otyp, cred_t *cred_p);
21
22
23   STREAMS
24       #include <sys/types.h>
25       #include <sys/stream.h>
26       #include <sys/file.h>
27       #include <sys/errno.h>
28       #include <sys/open.h>
29       #include <sys/cred.h>
30       #include <sys/ddi.h>
31       #include <sys/sunddi.h>
32
33
34
35       int prefixclose(queue_t *q, int flag, cred_t *cred_p);
36
37

INTERFACE LEVEL

39       Architecture  independent  level  1  (DDI/DKI).  This  entry  point  is
40       required for block devices.
41

PARAMETERS

43   Block and Character
44       dev        Device number.
45
46
47       flag       File status flag, as set by the  open(2) or modified by  the
48                  fcntl(2)  system calls. The flag is for information only—the
49                  file should always be  closed  completely.  Possible  values
50                  are:    FEXCL,  FNDELAY, FREAD, FKLYR, and  FWRITE. Refer to
51                  open(9E) for more information.
52
53
54       otyp       Parameter supplied so that the driver can determine how many
55                  times  a  device was opened and for what reasons.  The flags
56                  assume the  open() routine may be called many times, but the
57                  close()  routine  should only be called on the last  close()
58                  of a device.
59
60                  OTYP_BLK    Close  was  through  block  interface  for   the
61                              device.
62
63
64                  OTYP_CHR    Close  was  through  the raw/character interface
65                              for the device.
66
67
68                  OTYP_LYR    Close a layered process (a  higher-level  driver
69                              called the close() routine of the device).
70
71
72
73       *cred_p    Pointer to the  user credential structure.
74
75
76   STREAMS
77       *q         Pointer  to   queue(9S) structure used to reference the read
78                  side of the driver.  (A queue is the central node of a  col‐
79                  lection of structures and routines pointed to by a queue.)
80
81
82       flag       File status flag.
83
84
85       *cred_p    Pointer to the  user credential structure.
86
87

DESCRIPTION

89       For  STREAMS  drivers,  the   close()  routine  is called by the kernel
90       through the  cb_ops(9S) table entry for the device.  (Modules  use  the
91       fmodsw  table.)  A  non-null  value  in the  d_str field of the  cb_ops
92       entry points to a  streamtab structure, which  points  to  a  qinit(9S)
93       containing a pointer to the  close() routine. Non-STREAMS  close() rou‐
94       tines are called directly from the  cb_ops table.
95
96
97       close() ends the connection between the user process  and  the  device,
98       and  prepares the device (hardware and software) so that it is ready to
99       be opened again.
100
101
102       A device may be opened simultaneously by  multiple  processes  and  the
103       open()  driver  routine  is  called  for each open. For all otyp values
104       other than OTYP_LYR, the kernel calls  the  close()  routine  when  the
105       last-reference  occurs. For OTYP_LYR each close operation will call the
106       driver.
107
108
109       Kernel accounting for last-reference occurs at (dev,  otyp)   granular‐
110       ity.   Note  that  a  device is referenced once its associated open(9E)
111       routine is entered, and thus open(9E)'s  which have not  yet  completed
112       will  prevent  close()  from   being called.  The driver's close() call
113       associated with the  last-reference going away is typically  issued  as
114       result  of  a  close(2),  exit(2),  munmap(2), or umount(2). However, a
115       failed open(9E) call can cause this last-reference close() call  to  be
116       issued as a result of an open(2) or mount(2).
117
118
119       The  kernel  provides open() close() exclusion guarantees to the driver
120       at the same devp, otyp granularity as  last-reference  accounting.  The
121       kernel  delays  new calls to the  open() driver routine while the last-
122       reference close() call is executing. For example, a driver that  blocks
123       in  close()  will  not  see  new  calls to open() until it returns from
124       close().  This effectively delays invocation of other cb_ops(9S) driver
125       entry  points that also depend on an open(9E) established device refer‐
126       ence. If the driver has indicated that an EINTR return is safe via  the
127       D_OPEN_RETURNS_EINTR  cb_flag, then a delayed open() may be interrupted
128       by a signal, resulting in an EINTR return from open() prior to  calling
129       open(9E).
130
131
132       Last-reference  accounting  and open() close() exclusion typically sim‐
133       plify driver writing. In some cases, however, they might be an  impedi‐
134       ment  for  certain  types  of  drivers. To overcome any impediment, the
135       driver can change minor numbers in open(9E),  as  described  below,  or
136       implement  multiple  minor  nodes  for the same device. Both techniques
137       give the driver control over when close() calls occur and whether addi‐
138       tional open() calls will be delayed while close() is executing.
139
140
141       In  general, a  close() routine should always check the validity of the
142       minor number component of the  dev parameter.  The routine should  also
143       check  permissions as necessary, by using the user credential structure
144       (if pertinent), and the appropriateness of the  flag and  otyp  parame‐
145       ter values.
146
147
148       close() could perform any of the following general functions:
149
150           o      disable interrupts
151
152           o      hang up phone lines
153
154           o      rewind a tape
155
156           o      deallocate buffers from a private buffering scheme
157
158           o      unlock  an unsharable device (that was locked in the  open()
159                  routine)
160
161           o      flush buffers
162
163           o      notify a device of the close
164
165           o      deallocate any resources allocated on open
166
167
168       The  close() routines of STREAMS drivers and modules are called when  a
169       stream  is  dismantled  or a module popped. The steps for dismantling a
170       stream are performed in the following  order.  First,  any  multiplexor
171       links present are unlinked and the  lower streams are closed. Next, the
172       following steps are performed for each module or driver on the  stream,
173       starting at the head and working toward the tail:
174
175           1.     The write queue is given a chance to drain.
176
177           2.     The  close() routine is called.
178
179           3.     The module or driver is removed from the stream.
180

RETURN VALUES

182       close()  should  return 0 for success, or the appropriate error number.
183       Return errors rarely occur, but if a failure is  detected,  the  driver
184       should  decide whether the severity of the problem warrants either dis‐
185       playing a message on the console or, in worst cases, triggering a  sys‐
186       tem panic.  Generally, a failure in a  close() routine occurs because a
187       problem occurred in the associated device.
188

NOTES

190       If you use qwait_sig(9F), cv_wait_sig(9F) or cv_timedwait_sig(9F),  you
191       should  note  that  close()  may be called in contexts in which signals
192       cannot be received. The ddi_can_receive_sig(9F) function  is   provided
193       to determine when this hazard exists.
194