253 lines
4.6 KiB
Groff
253 lines
4.6 KiB
Groff
.\" @(#)putmsg.2 1.1 94/10/31 SMI; from S5R3
|
|
.TH PUTMSG 2 "21 January 1990"
|
|
.SH NAME
|
|
putmsg \- send a message on a stream
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.ft B
|
|
#include <stropts.h>
|
|
.ft
|
|
.fi
|
|
.LP
|
|
.nf
|
|
.ft B
|
|
int putmsg(fd, ctlptr, dataptr, flags)
|
|
int fd;
|
|
struct strbuf *ctlptr;
|
|
struct strbuf *dataptr;
|
|
int flags;
|
|
.ft
|
|
.fi
|
|
.SH DESCRIPTION
|
|
.IX "putmsg()" "" "\fLputmsg()\fP \(em send message on a stream"
|
|
.LP
|
|
.B putmsg(\|)
|
|
creates a message (see
|
|
.BR intro (2))
|
|
from user specified buffer(s)
|
|
and sends the message to a
|
|
.SM STREAMS
|
|
file. The message may contain either a data part,
|
|
a control part or both.
|
|
The data and control parts to be sent are distinguished by placement in
|
|
separate buffers, as described below.
|
|
The semantics of each part is defined by the
|
|
.SM STREAMS
|
|
module that receives the message.
|
|
.LP
|
|
.I fd
|
|
specifies a file descriptor referencing an open
|
|
.IR stream .
|
|
.I ctlptr
|
|
and
|
|
.I dataptr
|
|
each point to a
|
|
.B strbuf
|
|
structure that contains the following members:
|
|
.LP
|
|
.RS
|
|
.nf
|
|
.ft B
|
|
.ta 1i 1.7i 2.5i
|
|
int maxlen; /* not used */
|
|
int len; /* length of data */
|
|
char *buf; /* ptr to buffer */
|
|
.ft R
|
|
.fi
|
|
.DT
|
|
.RE
|
|
.LP
|
|
.I ctlptr
|
|
points to the structure describing the control part, if
|
|
any,
|
|
to be included in the message. The
|
|
.B buf
|
|
field in the
|
|
.B strbuf
|
|
structure points to the buffer where the
|
|
control information resides, and the
|
|
.B len
|
|
field indicates the number of bytes to be sent. The
|
|
.B maxlen
|
|
field is not used in
|
|
.B putmsg(\|)
|
|
(see
|
|
.BR getmsg (2)).
|
|
In a similar manner,
|
|
.I dataptr
|
|
specifies the data, if any, to be included
|
|
in the message.
|
|
.I flags
|
|
may be set to the values 0 or
|
|
.SB RS_HIPRI
|
|
and is used as described below.
|
|
.LP
|
|
To send the data part of a message,
|
|
.I dataptr
|
|
must not be a
|
|
.SM NULL
|
|
pointer and the
|
|
.B len
|
|
field of
|
|
.I dataptr
|
|
must have a value of 0 or greater.
|
|
To send the control part of a message, the corresponding values must be set
|
|
for
|
|
.IR ctlptr .
|
|
No data (control) part will be sent if either
|
|
.I dataptr
|
|
.BI ( ctlptr )
|
|
is a
|
|
.SM NULL
|
|
pointer or the
|
|
.B len
|
|
field of
|
|
.I dataptr
|
|
.BI ( ctlptr )
|
|
is set to \-1.
|
|
.LP
|
|
If a control part is specified, and
|
|
.I flags
|
|
is set to
|
|
.SB RS_HIPRI\s0\fR,
|
|
a
|
|
.I priority
|
|
message is sent. If
|
|
.I flags
|
|
is set to 0, a non-priority message is sent.
|
|
If no control part is specified, and
|
|
.I flags
|
|
is set to
|
|
.SB RS_HIPRI\s0\fR,
|
|
.B putmsg(\|)
|
|
fails and sets
|
|
.B errno
|
|
to
|
|
.SM EINVAL\s0.
|
|
If no control part and no data part are specified, and
|
|
.I flags
|
|
is set to 0, no message is sent, and 0 is returned.
|
|
.LP
|
|
For non-priority messages,
|
|
.B putmsg(\|)
|
|
will block if the
|
|
.I stream
|
|
write queue is full due to internal flow control conditions.
|
|
For priority messages,
|
|
.B putmsg(\|)
|
|
does not block on this condition.
|
|
For non-priority messages,
|
|
.B putmsg(\|)
|
|
does not block when the write queue
|
|
is full and
|
|
.SB O_NDELAY
|
|
is set. Instead, it fails and sets
|
|
.B errno
|
|
to
|
|
.SM EAGAIN\s0.
|
|
.LP
|
|
.B putmsg(\|)
|
|
also blocks, unless prevented by lack of internal
|
|
resources,
|
|
waiting for the availability
|
|
of message blocks in the
|
|
.IR stream ,
|
|
regardless of priority or whether
|
|
.SB O_NDELAY
|
|
has been specified. No partial message is sent.
|
|
.SH RETURN VALUES
|
|
.LP
|
|
.B putmsg(\|)
|
|
returns:
|
|
.TP
|
|
0
|
|
on success.
|
|
.TP
|
|
\-1
|
|
on failure and sets
|
|
.B errno
|
|
to indicate the error.
|
|
.SH ERRORS
|
|
.TP 15
|
|
.SM EAGAIN
|
|
A non-priority message was specified, the
|
|
.SB O_NDELAY
|
|
flag is set and the
|
|
.I stream
|
|
write queue is full due to internal flow control conditions.
|
|
.IP
|
|
Buffers could not be allocated for the message that was to be created.
|
|
.TP
|
|
.SM EBADF
|
|
.I fd
|
|
is not a valid file descriptor open for
|
|
writing.
|
|
.TP
|
|
.SM EFAULT
|
|
.I ctlptr
|
|
or
|
|
.I dataptr
|
|
points outside the allocated address space.
|
|
.TP
|
|
.SM EINTR
|
|
A signal was caught during the
|
|
.B putmsg(\|)
|
|
system call.
|
|
.TP
|
|
.SM EINVAL
|
|
An undefined value was specified in
|
|
.IR flags .
|
|
.IP
|
|
.I flags
|
|
is set to
|
|
.SB RS_HIPRI
|
|
and no control part was supplied.
|
|
.IP
|
|
The
|
|
.I stream
|
|
referenced by
|
|
.I fd
|
|
is linked below a multiplexor.
|
|
.TP
|
|
.SM ENOSTR
|
|
A
|
|
.I stream
|
|
is not associated with
|
|
.IR fd .
|
|
.TP
|
|
.SM ENXIO
|
|
A hangup condition was generated downstream for the specified
|
|
.IR stream .
|
|
.TP
|
|
.SM ERANGE
|
|
The size of the data part of the message does not fall within the range
|
|
specified by the maximum and minimum packet sizes of the topmost
|
|
.I stream
|
|
module.
|
|
.IP
|
|
The control part of
|
|
the message is larger than the maximum
|
|
configured size of the control part of a message.
|
|
.IP
|
|
The data part of the message is larger than
|
|
the maximum configured size of the data part of a message.
|
|
.LP
|
|
A
|
|
.B putmsg(\|)
|
|
also fails if a
|
|
.SM STREAMS
|
|
error message had been processed
|
|
by the
|
|
.I stream
|
|
head before the call to
|
|
.BR putmsg(\|) .
|
|
The error returned is the value contained in the
|
|
.SM STREAMS
|
|
error message.
|
|
.SH "SEE ALSO"
|
|
.BR getmsg (2),
|
|
.BR intro (2),
|
|
.BR poll (2),
|
|
.BR read (2V),
|
|
.BR write (2V)
|