'\" te .\" Copyright (c) 2013, 2016, Oracle and/or its affiliates. All rights reserved. .TH postwait_post 3C "19 May 2016" "SunOS 5.11" "Standard C Library Functions" .SH NAME postwait_post, postwait_postn \- Post user events to a key to notify one or more waiters. .SH SYNOPSIS .LP .nf #include .fi .LP .nf \fBint\fR \fBpostwait_post\fR(\fBpostwkey_t\fR \fIkey\fR, \fBint\fR \fIuevents\fR, \fBuintptr_t\fR \fIudata\fR); .fi .LP .nf \fBint\fR \fBpostwait_postn\fR(\fBpostwkey_t\fR \fIklist[]\fR, \fBpostwkey_uevdata_t\fR \fIuserd[]\fR, \fBint\fR \fIerrors[]\fR, \fBuint_t\fR \fInent\fR); .fi .LP .nf \fBint\fR \fBpostwait_post_deferred\fR(\fBpostwkey_t\fR \fIkey\fR, \fBint\fR \fIflags\fR, \fBint\fR \fIuevents\fR, \fBuintptr_t\fR \fIudata\fR); .fi .SH DESCRIPTION .sp .LP The \fBpostwait_post()\fR, \fBpostwait_postn()\fR, and \fBpostwait_post_deferred()\fR functions allow threads to post events as part of a post-wait mechanism. Threads can wait and retrieve these events via event ports. .sp .LP Post events consist of an user defined integer type event and an unsigned long item of opaque user data. Both fields are available to the receiving threads. .sp .LP The post-wait mechanism can be used between threads in the same or different processes. A \fBkey\fR is used as the rendezvous point for posting and waiting; these 64 bit keys are generated by \fBpostwait_genkey \fR(3C) call and shared with other processes using any desired form of IPC. No limitations are placed on which processes may use which keys. .sp .LP The \fBpostwait_post()\fR function causes an event of type \fBPORT_SOURCE_POSTWAIT\fR and the associated user values to be delivered to any event ports that are associated with the specified \fBkey\fR. For more information, see \fBport_associate\fR(3C). .sp .LP The \fBpostwait_postn()\fR function posts multiple post events to multiple keys with one system call. Passing NULL for the errors argument could cause this function to post asynchronously with the help of background worker threads. The list of keys to be posted to are passed in the \fBklist\fR array argument. The corresponding user events and user data are passed in the array of struct \fBpostwkey_uevdata_t\fR. The number of elements of this array is specified in \fBnent\fR argument. Passing NULL for userd causes 0 to be used as the value of \fBuevents\fR and \fBudata\fR. .sp .LP The \fBpostwkey_uevdata_t\fR structure contains the following members: .sp .in +2 .nf int pwev_uevents; uintptr_t pwev_udata; .fi .in -2 .sp .LP The \fBpostwait_post_deferred()\fR function is for registering a deferred post. With \fBPWPOST_ATEXIT\fR specified in flags, the deferred post is delivered when the thread that registered the post exits the containing process exits or is killed. Calling \fBpostwait_post_deferred()\fR with \fBPWPOST_CANCEL\fR flag will cancel any outstanding deferred post registered for the \fBkey\fR by this thread. There can be only one deferred post registered by a thread per \fBkey\fR. .sp .LP If \fBPWPOST_VALIDATE_KEY\fR is or'd with \fBPWPOST_ATEXIT\fR, it checks if the key specified is associated with an event port or not. If not, the deferred post registration for that key will fail. .sp .LP To receive post events, the key needs to be associated with an event port. Threads collect the post events from the event port. Delivery of the post event and user values is determined by the associating type of key. Two types of association are permitted: counting and queuing. For more information, see \fBport_associate\fR(3C). .sp .LP For a counting type association, multiple posts that occur before the event is retrieved will be combined resulting in just one event delivery to the event port. A count indicating how many times the key was posted since the last time that an event for that key was collected is returned along with the event. Both the user event and the user data submitted with the post will be ignored for this type of association. .sp .LP For a queuing type association, one event for each post will be queued on the event port. The user event and user data passed are delivered with the posted event. The number of events that can get queued on an event port is subject to the \fBprocess.max-port-events\fR resource limit. For more information, see rctladm(1M). .sp .LP The count and the user values are delivered in the \fBport_event_t\fR structure. The events from an event port are collected using \fBport_get\fR(3C) or \fBport_getn\fR(3C) calls. .sp .LP If a key is associated with more then one event port, a post to that key will result in delivery of the same event to each of those ports. .SH RETURN VALUES .sp .LP Upon successful completion, \fBpostwait_post()\fR will return 0. Otherwise, it will return -1 and sets \fBerrno\fR to indicate the error. .sp .LP In the synchronous mode, the \fBpostwait_postn()\fR function returns the number of successfully submitted events. A non-negative return value less than the \fBnent\fR argument indicates that at least one error has occurred. In this case, each element of the \fBerrors[]\fR array is filled in. An element of the \fBerrors[]\fR array is set to 0 if the post event was successfully sent to the corresponding key in the \fBklist[]\fR array, or is set to indicate the error if not successful. .sp .LP In the asynchronous mode, \fBpostwait_postn()\fR function returns the number of successfully handed-off events. If an error occurs with the \fBpostwait_postn()\fR call, it returns \fI-1\fR and sets \fBerrno\fR to indicate the error. .sp .LP The \fBpostwait_post_deferred()\fR function returns 0, if the deferred post is registered or cancelled successfully. Otherwise it returns \fI-1\fR and the \fBerrno\fR is set to indicate the error. .SH ERRORS .sp .LP The \fBpostwait_post()\fR and \fBsynchronous mode postwait_postn()\fR functions will fail if: .sp .ne 2 .mk .na \fB\fBEAGAIN\fR\fR .ad .RS 10n .rt The maximum number of events per port is exceeded. The maximum allowable number of events per port is the minimum value of the \fBprocess.max-port-events\fR resource control at the time \fBport_create\fR(3C) was called to create the event port to which the key is associated. .RE .sp .ne 2 .mk .na \fB\fBEBADF\fR\fR .ad .RS 10n .rt The event cannot be delivered as the specified key currently is not associated with any event ports. .RE .sp .LP The \fBpostwait_post()\fR and \fBpostwait_postn()\fR functions will fail if: .sp .ne 2 .mk .na \fB\fBENOMEM\fR\fR .ad .RS 10n .rt There is not enough memory available to satisfy the request. .RE .sp .LP The \fBpostwait_postn()\fR function will fail if: .sp .ne 2 .mk .na \fB\fBEFAULT\fR\fR .ad .RS 10n .rt The \fBklist[]\fR or \fBuserd[]\fR or \fBerrors[]\fR pointer is invalid. .RE .sp .LP The \fBpostwait_post_deferred()\fR function will fail if: .sp .ne 2 .mk .na \fB\fBEBUSY\fR\fR .ad .RS 10n .rt If there is already a deferred post registered for the specified key. .RE .sp .ne 2 .mk .na \fB\fBEINVAL\fR\fR .ad .RS 10n .rt If the \fBPWPOST_CANCEL\fR flag is passed and there is no deferred post registered for the specified key or the value passed in flags argument are invalid. .RE .sp .ne 2 .mk .na \fB\fBEAGAIN\fR\fR .ad .RS 10n .rt If the thread has already registered maximum number of allowed deferred posts defined by \fBprocess.max-deferred-posts\fR resource control. .RE .sp .ne 2 .mk .na \fB\fBEBADF\fR\fR .ad .RS 10n .rt If \fBPWPOST_VALIDATE_KEY\fR flag was or'd with \fBPWPOST_ATEXIT\fR, and the key specified is currently not associated with any port. Note that after the key has been validated here, it is possible that the process that has associated the key can exit or get killed. As a result, the key may no longer be associate with any event port. However, a different process can subsequently associate the same key with an event port. .RE .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 _ Interface StabilityCommitted _ MT-LevelSafe, Async-Signal-Safe .TE .SH SEE ALSO .sp .LP \fBpostwait_genkey \fR(3C), \fBport_create\fR(3C), \fBport_sendn\fR(3C), \fBresource-controls \fR(5)