1 '\" te
2 .\" Copyright (c) 2007, 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 PORT_ASSOCIATE 3C "Nov 9, 2007"
7 .SH NAME
8 port_associate, port_dissociate \- associate or dissociate the object with the
9 port
10 .SH SYNOPSIS
11 .LP
12 .nf
13 #include <port.h>
14
15 \fBint\fR \fBport_associate\fR(\fBint\fR \fIport\fR, \fBint\fR \fIsource\fR, \fBuintptr_t\fR \fIobject\fR,
16 \fBint\fR \fIevents\fR, \fBvoid *\fR\fIuser\fR);
17 .fi
18
19 .LP
20 .nf
21 \fBint\fR \fBport_dissociate\fR(\fBint\fR \fIport\fR, \fBint\fR \fIsource\fR, \fBuintptr_t\fR \fIobject\fR);
22 .fi
23
24 .SH DESCRIPTION
25 .sp
26 .LP
56 .LP
57 Objects of type \fBPORT_SOURCE_FD\fR are file descriptors. The event types for
58 \fBPORT_SOURCE_FD\fR objects are described in \fBpoll\fR(2). At most one event
59 notification will be generated per associated file descriptor. For example, if
60 a file descriptor is associated with a port for the \fBPOLLRDNORM\fR event and
61 data is available on the file descriptor at the time the \fBport_associate()\fR
62 function is called, an event is immediately sent to the port. If data is not
63 yet available, one event is sent to the port when data first becomes available.
64 .sp
65 .LP
66 When an event for a \fBPORT_SOURCE_FD\fR object is retrieved, the object no
67 longer has an association with the port. The event can be processed without
68 the possibility that another thread can retrieve a subsequent event for the
69 same object. After processing of the file descriptor is completed, the
70 \fBport_associate()\fR function can be called to reassociate the object with
71 the port.
72 .sp
73 .LP
74 Objects of type \fBPORT_SOURCE_FILE\fR are pointer to the structure
75 \fBfile_obj\fR defined in \fB<sys/port.h>\fR. This event source provides event
76 notification when the specified file/directory is accessed or modified or when
77 its status changes. The path name of the file/directory to be watched is passed
78 in the \fBstruct file_obj\fR along with the \fBaccess\fR, \fBmodification\fR,
79 and \fBchange\fR time stamps acquired from a \fBstat\fR(2) call. If the file
80 name is a symbolic links, it is followed by default. The \fBFILE_NOFOLLOW\fR
81 needs to be passed in along with the specified events if the symbolic link
82 itself needs to be watched and \fBlstat()\fR needs to be used to get the file
83 status of the symbolic link file.
84 .sp
85 .LP
86 The \fBstruct file_obj\fR contains the following elements:
87 .sp
88 .in +2
89 .nf
90 timestruc_t fo_atime; /* Access time got from stat() */
91 timestruc_t fo_mtime; /* Modification time from stat() */
92 timestruc_t fo_ctime; /* Change time from stat() */
93 char *fo_name; /* Pointer to a null terminated path name */
94 .fi
95 .in -2
96
97 .sp
98 .LP
99 At the time the \fBport_associate()\fR function is called, the time stamps
100 passed in the structure \fBfile_obj\fR are compared with the file or
101 directory's current time stamps and, if there has been a change, an event is
102 immediately sent to the port. If not, an event will be sent when such a change
103 occurs.
104 .sp
105 .LP
106 The event types that can be specified at \fBport_associate()\fR time for
107 \fBPORT_SOURCE_FILE\fR are \fBFILE_ACCESS\fR, \fBFILE_MODIFIED\fR, and
108 \fBFILE_ATTRIB\fR, corresponding to the three time stamps. An \fBfo_atime\fR
109 change results in the \fBFILE_ACCESS\fR event, an \fBfo_mtime\fR change results
110 in the \fBFILE_MODIFIED\fR event, and an \fBfo_time\fR change results in the
111 \fBFILE_ATTRIB\fR event.
112 .sp
113 .LP
114 The following exception events are delivered when they occur. These event types
115 cannot be filtered.
116 .sp
117 .in +2
118 .nf
119 FILE_DELETE /* Monitored file/directory was deleted */
120 FILE_RENAME_TO /* Monitored file/directory was renamed */
121 FILE_RENAME_FROM /* Monitored file/directory was renamed */
122 UNMOUNTED /* Monitored file system got unmounted */
123 MOUNTEDOVER /* Monitored file/directory was mounted over */
124 .fi
125 .in -2
126
127 .sp
128 .LP
129 At most one event notification will be generated per associated \fBfile_obj\fR.
130 When the event for the associated \fBfile_obj\fR is retrieved, the object is no
131 longer associated with the port. The event can be processed without the
|
1 '\" te
2 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
3 .\" Copyright (c) 2013, Joyent, Inc. All Rights Reserved.
4 .\" 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.
5 .\" 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.
6 .\" 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]
7 .TH PORT_ASSOCIATE 3C "Jan 18, 2013"
8 .SH NAME
9 port_associate, port_dissociate \- associate or dissociate the object with the
10 port
11 .SH SYNOPSIS
12 .LP
13 .nf
14 #include <port.h>
15
16 \fBint\fR \fBport_associate\fR(\fBint\fR \fIport\fR, \fBint\fR \fIsource\fR, \fBuintptr_t\fR \fIobject\fR,
17 \fBint\fR \fIevents\fR, \fBvoid *\fR\fIuser\fR);
18 .fi
19
20 .LP
21 .nf
22 \fBint\fR \fBport_dissociate\fR(\fBint\fR \fIport\fR, \fBint\fR \fIsource\fR, \fBuintptr_t\fR \fIobject\fR);
23 .fi
24
25 .SH DESCRIPTION
26 .sp
27 .LP
57 .LP
58 Objects of type \fBPORT_SOURCE_FD\fR are file descriptors. The event types for
59 \fBPORT_SOURCE_FD\fR objects are described in \fBpoll\fR(2). At most one event
60 notification will be generated per associated file descriptor. For example, if
61 a file descriptor is associated with a port for the \fBPOLLRDNORM\fR event and
62 data is available on the file descriptor at the time the \fBport_associate()\fR
63 function is called, an event is immediately sent to the port. If data is not
64 yet available, one event is sent to the port when data first becomes available.
65 .sp
66 .LP
67 When an event for a \fBPORT_SOURCE_FD\fR object is retrieved, the object no
68 longer has an association with the port. The event can be processed without
69 the possibility that another thread can retrieve a subsequent event for the
70 same object. After processing of the file descriptor is completed, the
71 \fBport_associate()\fR function can be called to reassociate the object with
72 the port.
73 .sp
74 .LP
75 Objects of type \fBPORT_SOURCE_FILE\fR are pointer to the structure
76 \fBfile_obj\fR defined in \fB<sys/port.h>\fR. This event source provides event
77 notification when the specified file/directory is accessed, modified,
78 truncated or when its status changes. The path name of the file/directory to
79 be watched is passed in the \fBstruct file_obj\fR along with the \fBaccess\fR,
80 \fBmodification\fR, and \fBchange\fR time stamps acquired from a \fBstat\fR(2)
81 call. If the file name is a symbolic link, it is followed by default. The
82 \fBFILE_NOFOLLOW\fR needs to be passed in along with the specified events if
83 the symbolic link itself needs to be watched and \fBlstat()\fR needs to be
84 used to get the file status of the symbolic link file.
85 .sp
86 .LP
87 The \fBstruct file_obj\fR contains the following elements:
88 .sp
89 .in +2
90 .nf
91 timestruc_t fo_atime; /* Access time from stat() */
92 timestruc_t fo_mtime; /* Modification time from stat() */
93 timestruc_t fo_ctime; /* Change time from stat() */
94 char *fo_name; /* Pointer to a null terminated path name */
95 .fi
96 .in -2
97
98 .sp
99 .LP
100 At the time the \fBport_associate()\fR function is called, the time stamps
101 passed in the structure \fBfile_obj\fR are compared with the file or
102 directory's current time stamps and, if there has been a change, an event is
103 immediately sent to the port. If not, an event will be sent when such a change
104 occurs.
105 .sp
106 .LP
107 The event types that can be specified at \fBport_associate()\fR time for
108 \fBPORT_SOURCE_FILE\fR are \fBFILE_ACCESS\fR, \fBFILE_MODIFIED\fR,
109 \fBFILE_ATTRIB\fR, and \fbFILE_TRUNC\fR. The first three of these correspond
110 to the three time stamps: an \fBfo_atime\fR change results in the
111 \fBFILE_ACCESS\fR event, an \fBfo_mtime\fR change results in the
112 \fBFILE_MODIFIED\fR event, and an \fBfo_ctime\fR change results in the
113 \fBFILE_ATTRIB\fR event. If the operation that induced the time stamp update
114 also truncated the file, \fBFILE_TRUNC\fR will be set in the resulting event.
115 .sp
116 .LP
117 The following exception events are delivered when they occur. These event types
118 cannot be filtered.
119 .sp
120 .in +2
121 .nf
122 FILE_DELETE /* Monitored file/directory was deleted */
123 FILE_RENAME_TO /* Monitored file/directory was renamed */
124 FILE_RENAME_FROM /* Monitored file/directory was renamed */
125 UNMOUNTED /* Monitored file system got unmounted */
126 MOUNTEDOVER /* Monitored file/directory was mounted over */
127 .fi
128 .in -2
129
130 .sp
131 .LP
132 At most one event notification will be generated per associated \fBfile_obj\fR.
133 When the event for the associated \fBfile_obj\fR is retrieved, the object is no
134 longer associated with the port. The event can be processed without the
|