243 system manual pages should live with the software

Reviewed by: garrett@nexenta.com
Reviewed by: gwr@nexenta.com
Reviewed by: trisk@opensolaris.org
Approved by: gwr@nexenta.com

--HG--
extra : rebase_source : 0c599d0bec0dc8865fbba67721a7a6cd6b1feefb

1 files changed, 307 insertions, 0 deletions

diff --git a/usr/src/man/man3c/port_get.3c b/usr/src/man/man3c/port_get.3c
new file mode 100644
index 0000000000..54575a1e71
--- /dev/null
+++ b/usr/src/man/man3c/port_get.3c
@@ -0,0 +1,307 @@
+'\" te
+.\" Copyright (c) 2007, 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 port_get 3C "31 Jan 2007" "SunOS 5.11" "Standard C Library Functions"
+.SH NAME
+port_get, port_getn \- retrieve event information from a port
+.SH SYNOPSIS
+.LP
+.nf
+#include <port.h>
+
+\fBint\fR \fBport_get\fR(\fBint\fR \fIport\fR, \fBport_event_t *\fR\fIpe\fR,
+     \fBconst timespec_t *\fR\fItimeout\fR);
+.fi
+
+.LP
+.nf
+\fBint\fR \fBport_getn\fR(\fBint\fR \fIport\fR, \fBport_event_t\fR \fIlist\fR[], \fBuint_t\fR \fImax\fR,
+     \fBuint_t *\fR\fInget\fR, \fBconst timespec_t *\fR\fItimeout\fR);
+.fi
+
+.SH DESCRIPTION
+.sp
+.LP
+The \fBport_get()\fR and \fBport_getn()\fR functions retrieve events from a
+port. The \fBport_get()\fR function retrieves at most a single event. The
+\fBport_getn()\fR function can retrieve multiple events.
+.sp
+.LP
+The \fIpe\fR argument points to an uninitialized \fBport_event_t\fR structure
+that is filled in by the system when the \fBport_get()\fR function returns
+successfully.
+.sp
+.LP
+The \fBport_event_t\fR structure contains the following members:
+.sp
+.in +2
+.nf
+int       portev_events;   /* detected events           */
+ushort_t  portev_source;   /* event source              */
+uintptr_t portev_object;   /* specific to event source  */
+void      *portev_user;    /* user defined cookie       */
+.fi
+.in -2
+
+.sp
+.LP
+The \fBportev_events\fR and \fBportev_object\fR members are specific to the
+event source. The \fBportev_events\fR denotes the delivered events. The
+\fBportev_object\fR refers to the associated object (see
+\fBport_create\fR(3C)). The \fBportev_source\fR member specifies the source of
+the event. The \fBportev_user\fR member is a user-specified value.
+.sp
+.LP
+If the \fItimeout\fR pointer is \fINULL\fR, the \fBport_get()\fR function
+blocks until an event is available. To poll for an event without waiting,
+\fItimeout\fR should point to a zeroed \fBtimespec\fR. A non-zeroed
+\fBtimespec\fR specifies the desired time to wait for events. The
+\fBport_get()\fR function returns before the timeout elapses if an event is
+available, a signal occurs, a port is closed by another thread, or the port is
+in or enters alert mode. See \fBport_alert\fR(3C) for details on alert mode.
+.sp
+.LP
+The \fBport_getn()\fR function can retrieve multiple events from a port. The
+\fIlist\fR argument is an array of uninitialized \fBport_event_t\fR structures
+that is filled in by the system when the \fBport_getn()\fR function returns
+succesfully. The \fInget\fR argument points to the desired number of events to
+be retrieved. The \fImax\fR parameter specifies the maximum number of events
+that can be returned in \fIlist\fR[]. If \fImax\fR is 0, the value pointed to
+by \fInget\fR is set to the number of events available on the port. The
+\fBport_getn()\fR function returns immediately but no events are retrieved.
+.sp
+.LP
+The \fBport_getn()\fR function block until the desired number of events are
+available, the timeout elapses, a signal occurs, a port is closed by another
+thread, or the port is in or enters alert mode.
+.sp
+.LP
+On return, the value pointed to by \fInget\fR is updated to the actual number
+of events retrieved in list.
+.sp
+.LP
+Threads calling the \fBport_get()\fR function might starve threads waiting in
+the \fBport_getn()\fR function for more than one event.  Similarly, threads
+calling the \fBport_getn()\fR function for \fIn\fR events might starve threads
+waiting in the \fBport_getn()\fR function for more than \fIn\fR events.
+.sp
+.LP
+The \fBport_get()\fR and the \fBport_getn()\fR functions ignore non-shareable
+events (see \fBport_create\fR(3C)) generated by other processes.
+.SH RETURN VALUES
+.sp
+.LP
+Upon succesful completion, 0 is returned. Otherwise, -1 is returned and errno
+is set to indicate the error.
+.SH ERRORS
+.sp
+.LP
+The \fBport_get()\fR and \fBport_getn()\fR functions will fail if:
+.sp
+.ne 2
+.mk
+.na
+\fB\fBEBADF\fR\fR
+.ad
+.RS 10n
+.rt  
+The \fIport\fR identifier is not valid.
+.RE
+
+.sp
+.ne 2
+.mk
+.na
+\fB\fBEBADFD\fR\fR
+.ad
+.RS 10n
+.rt  
+The \fIport\fR argument is not an event port file descriptor.
+.RE
+
+.sp
+.ne 2
+.mk
+.na
+\fB\fBEFAULT\fR\fR
+.ad
+.RS 10n
+.rt  
+Event or event list can not be delivered (\fIlist\fR[] pointer and/or user
+space reserved to accomodate the list of events is not reasonable), or the
+\fItimeout\fR argument is not reasonable.
+.RE
+
+.sp
+.ne 2
+.mk
+.na
+\fB\fBEINTR\fR\fR
+.ad
+.RS 10n
+.rt  
+A signal was caught during the execution of the function.
+.RE
+
+.sp
+.ne 2
+.mk
+.na
+\fB\fBEINVAL\fR\fR
+.ad
+.RS 10n
+.rt  
+The \fItimeout\fR element \fBtv_sec\fR is < 0 or the \fItimeout\fR element
+\fBtv_nsec\fR is < 0 or > 1000000000.
+.RE
+
+.sp
+.ne 2
+.mk
+.na
+\fB\fBETIME\fR\fR
+.ad
+.RS 10n
+.rt  
+The time interval expired before the expected number of events have been posted
+to the port.
+.RE
+
+.sp
+.LP
+The \fBport_getn()\fR function will fail if:
+.sp
+.ne 2
+.mk
+.na
+\fB\fBEINVAL\fR\fR
+.ad
+.RS 10n
+.rt  
+The \fIlist\fR[] argument is \fINULL\fR, the \fInget\fR argument is \fINULL\fR,
+or the content of \fInget\fR is > \fImax\fR and \fImax\fR is > 0.
+.RE
+
+.sp
+.ne 2
+.mk
+.na
+\fB\fBEFAULT\fR\fR
+.ad
+.RS 10n
+.rt  
+The \fItimeout\fR argument is not reasonable.
+.RE
+
+.sp
+.ne 2
+.mk
+.na
+\fB\fBETIME\fR\fR
+.ad
+.RS 10n
+.rt  
+The time interval expired before the expected number of events have been posted
+to the port (original value in \fInget\fR), or \fInget\fR is updated with the
+number of returned \fBport_event_t\fR structures in \fIlist\fR[].
+.RE
+
+.SH EXAMPLES
+.LP
+\fBExample 1 \fRSend a user event (PORT_SOURCE_USER) to a port and retrieve it
+with \fBport_get()\fR.
+.sp
+.LP
+The following example sends a user event (\fBPORT_SOURCE_USER\fR) to a port and
+retrieves it with \fBport_get()\fR. The \fBportev_user\fR and
+\fBportev_events\fR members of the \fBport_event_t\fR structure are the same as
+the corresponding user and events arguments of the \fBport_send\fR(3C)
+function.
+
+.sp
+.in +2
+.nf
+#include <port.h>
+
+int             myport;
+port_event_t    pe;
+struct timespec timeout;
+int             ret;
+void            *user;
+uintptr_t       object;
+
+myport = port_create();
+if (myport < 0) {
+        /* port creation failed ... */
+        ...
+        return(...);
+}
+\&...
+events = 0x01;          /* own event definition(s) */
+object = <myobject>;
+user = <my_own_value>;
+ret = port_send(myport, events, user);
+if (ret == -1) {
+        /* error detected ... */
+        ...
+        close(myport);
+        return (...);
+}
+
+/*
+ * The following code could also be executed in another thread or
+ * process.
+ */
+timeout.tv_sec = 1;     /* user defined */
+timeout.tv_nsec = 0;
+ret = port_get(myport, &pe, &timeout);
+if (ret == -1) {
+        /*
+         * error detected :
+         * - EINTR or ETIME : log error code and try again ...
+         * - Other kind of errors : may have to close the port ...
+         */
+        return(...);
+}
+
+/*
+ * After port_get() returns successfully, the port_event_t
+ * structure will be filled with:
+ * pe.portev_source =   PORT_SOURCE_USER
+ * pe.portev_events = 0x01
+ * pe.portev_object = <myobject>
+ * pe.portev_user = <my_own_value>
+ */
+\&...
+close(myport);
+.fi
+.in -2
+
+.SH ATTRIBUTES
+.sp
+.LP
+See \fBattributes\fR(5) for descriptions of the following attributes:
+.sp
+
+.sp
+.TS
+tab() box;
+cw(2.75i) |cw(2.75i) 
+lw(2.75i) |lw(2.75i) 
+.
+ATTRIBUTE TYPEATTRIBUTE VALUE
+_
+Architectureall
+_
+Interface StabilityEvolving
+_
+MT-LevelSafe
+.TE
+
+.SH SEE ALSO
+.sp
+.LP
+\fBport_alert\fR(3C), \fBport_associate\fR(3C), \fBport_create\fR(3C),
+\fBport_send\fR(3C), \fBattributes\fR(5)