'\" tr.\" -*- nroff -*-.\".\" @(#) putpmsg.2,v 1.1.4.1 2004/01/12 23:45:03 brian Exp.\".\" =========================================================================.\".\" Copyright (C) 2001-2004  OpenSS7 Corp. <www.openss7.com>.\".\" All Rights Reserved..\".\" Permission is granted to make and distribute verbatim copies of this.\" manual provided the copyright notice and this permission notice are.\" preserved on all copies..\".\" Permission is granted to copy and distribute modified versions of this.\" manual under the conditions for verbatim copying, provided that the.\" entire resulting derived work is distributed under the terms of a.\" permission notice identical to this one.\" .\" Since the Linux kernel and libraries are constantly changing, this.\" manual page may be incorrect or out-of-date.  The author(s) assume no.\" responsibility for errors or omissions, or for damages resulting from.\" the use of the information contained herein.  The author(s) may not.\" have taken the same level of care in the production of this manual,.\" which is licensed free of charge, as they might when working.\" professionally..\" .\" Formatted or processed versions of this manual, if unaccompanied by.\" the source, must acknowledge the copyright and authors of this work..\".\" =========================================================================.\".\" Modified 2004/01/12 23:45:03 by brian.\".\" =========================================================================.so lis.macros.R1bracket-label "\fR[\fB" "\fR]" "\fR, \fB"no-default-databasedatabase lis.refsaccumulatemove-punctuationabbreviate Ajoin-authors ", " ", " " and "et-al " et al" 2 3abbreviate-label-ranges ".."sort-adjacent-labels.R2.\".\".TH PUTPMSG 2 "2004/01/12 23:45:03" "LiS-2_16_18-8" "Linux STREAMS System Calls".SH NAME.B putpmsg\- put a band message to a STREAMS character device.SH SYNOPSIS.PP.B #include <stropts.h>.HP 8.BI "int " retval " = putpmsg(int " fd ", const struct strbuf *" ctlptr ", const struct strbuf *" dataptr ", int " band ", int " flags );.SH DESCRIPTION.PP.B putpmsg()generates a STREAMS message from the buffer supplied in the specified.IR ctlptr " and " dataprfor the queue band.I bandand with options specified by.I flagsand delivers the message to the stream head associated with the STREAMScharacter special file.IR fd ..PPThe resulting STREAMS message can contain a control part as specified by.IR ctlptr ,a data part as specified by.IR datptr ,or both.The control part, when present, will generate.BR M_PROTO " or " M_PCPROTOmessage blocks.The data part, when present, will generate.B M_DATTAmessage blocks.When both control and data parts are present, an.BR M_PROTO " or " M_PCPROTOmessage block followed by one or more.B M_DATAmessage blocks will be generated..PP.I fdis an open file descriptor for the STREAMS character special file to which theSTREAMS message is to be written..PP.IR ctlptr " and " datptrpoint to a.B strbufstructure, which contains the following members:.sp.nf\fC\s-2\struct strbuf {    int maxlen;         /* Maximum buffer length.  */    int len;            /* Length of data.  */    char *buf;          /* Pointer to buffer.  */};\s+2\fR.fi.TP 12.I maxlenNot used by.BR putpmsg() ..TP 12.I lenThe length of the information pointed to by.IR buf ..TP 12.I bufA pointer to the buffer that contains.I lenbytes of information..PP.I ctlptrpoints to a.B strbufstructure describing the control part to be included in the message, or.B NULLif there is no control part.The.I bufmemberof the.B strbufstructure pointed to by.I ctlptrindiates the start of the information to sent in the control part, andthe.I lenmember indicates the length of the information for the control part..PP.I datptrpoints to a.B strbufstructure decribing the data part to be included in the message, or.B NULLis there is no data part.The.I bufmemberof the.B strbufstructure pointed to by.I ctlptrindiates the start of the information to sent in the data part, andthe.I lenmember indicates the length of the information for the data part..I lencan be zero (0) to send zero-length data..PP.I bandspecifies the queue band to which to write data when.I flagsis set to.BR MSG_BAND .When flags is set to other than.BR MSG_BAND ,.I bandmust be set to zero (0)..PP.I flagsspecifies whether to send a high priority message or a band message..I flagscan be one of the following values:.TP 12.B MSG_HIPRISpecifies that a high priority message is to be sent if the request contains acontrol part.IR "" ( ctlptr " is not".BR "" NULL ).This results in an.B M_PCPROTOmessage being placed on the stream head..TP 12.B MSG_BANDSpecifies that a normal priority queue band message is to be sent for thespecified.IR band .This results in an.B M_PROTOmessage being placed on the stream head when there is a control part.When there is only a data part, an.B M_DATAmessage for the specified.I bandis placed on the stream head..SH "RETURN VALUE".PPUpon success,.B putpmsg()returns zero (0)..PPUpon failure,.B putpmsg()returns 1 and sets.I errnoto an appropritate error number..SH ERRORS.PPWhen.B putpmsg()fails, it returns -1 and sets.I errnoto one of the following:.TP 12.\".RB [ EACCES ].\".I fd.\"is a dynamic device, and write permission on the device is denied..TP 12.RB [ EAGAIN ]The stream head is set for non-blocking operation and.B putpmsg()would block: that is, the message is being sent with.I flagsset to.B MSG_BANDand the corresponding.I bandis flow controlled..TP 12.RB [ EBADF ].I fdis not a valid file descriptor or is not open for reading..TP 12.RB [ EFAULT ].IR ctlptr ", " datptr ", " ctlptr->buf " or " datptr->bufpoint outside the caller's address space..TP 12.RB [ EINTR ]A signal arrived before the operation could complete..TP 12.RB [ EINVAL ]The values of.IR band " or " flags ,or the combination of.IR ctlptr ", " datptr ", and the values of " band " and " flagswere invalid,such as when.I flagsis specified as.B MSG_HIPRIand.I bandis non-zero,or,.I fdrefers to a stream that is linked under a STREAMS multiplexing driver..TP 12.RB [ EIO ]I/O error, or,.I fdrefers to a stream that is open but is in the process of closing, or refers toa pipe and the other end of the pipe is closed..TP 12.RB [ EISDIR ].I fdrefers to a directory..TP 12.RB [ ENODEV ].I fdrefers to a device that does not support the.B putpmsg()system call..TP 12.RB [ ENOSR ]STREAMS resources were insufficient to complete the operation..TP 12.RB [ ENOSTR ].I fdrefers to a device that has no stream associated with it..TP 12.RB [ ENXIO ]A.B M_HANGUPmessage arrived at the stream head for the specified.IR fd ..TP 12.RB [ ERANGE ]The.I lenof the data part of the message is outside the range.I q_minpszto.I q_maxpszinclusive for the topmost STREAMS module or driver under the stream head, or,the.I lenof the control or data part is larger than the maximum sized control or datamessage for the STREAMS subsystem..PPOther errors may be returned by.BR putpmsg() .If the protocol module sends an.B M_ERRORmessage to the stream head, the error returned on all subsequent writeoperations, including.BR putpsmg() ,is specified in the.B M_ERRORmessage by the protocol module.  Which errors are returned under whatconditions form part of the necessary documentation of the protocol module..SH CAVEATS.PP.B LiS.[LiS.]could handle concurrent writes better.  Linux socket code blocks concurrentwriters independently while partial writers are installed agains a socket.When partial writes are performed for messages using.BR putpmsg() ,.B LiS.[LiS.]should install the partial writer and block all writers from completing thepartial write on a given band until the partial writer completes the write orthe partial writer closes the stream.  This would at least keep multiplethreads of execution from interfering with partial writes..SH BUGS.PP.B LiS.[LiS.]incorrectly returns.RB [ EINVAL ]instead of.RB [ EIO ]when the internal head queue pointer points to a structure that is not a queuestructure, or is mangled..PP.B LiS.[LiS.]does not return.RB [ EIO ]when.B putpmsg()is called on a closing stream..PP.B LiS.[LiS.]incorrectly returns.RB [ EAGAIN ]instead of.RB [ EINTR ]when an.B M_SIGmessage causes a signal that interrupts the call to.B putpmsg()before any data is written..PP.B LiS.[LiS.]incorrectly returns.RB [ ENODEV ]instead of.RB [ ENOSTR ]when there is no stream associated with.IR fd ..PP.B LiS.[LiS.]incorrectly returns.RB [ EINVAL ]instead of.RB [ ENODEV ]when.I fdrefers to a device that does not support the.B putpmsg()system call..SH "SEE ALSO".PP.BR intro (2),.BR poll (2),.BR putmsg (2),.BR write (2),.BR streamio (2)..SH VERSIONS.PPThis manpage was written for.B LiS\c..[LiS.].PP.B putpmsg()first appeared in SVR 3..[svr3.].\".\".XX.[magic.].[svr42.].[svr4.].[svr3.].[svid.].[xns.].[xbd5.].[$LIST$.].TI