getmsg.2

7号信令功能代码,为开源代码

'\" tr
.\" -*- nroff -*-
.\"
.\" @(#) getmsg.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
.R1
bracket-label "\fR[\fB" "\fR]" "\fR, \fB"
no-default-database
database lis.refs
accumulate
move-punctuation
abbreviate A
join-authors ", " ", " " and "
et-al " et al" 2 3
abbreviate-label-ranges ".."
sort-adjacent-labels
.R2
.\"
.\"
.TH GETMSG 2 "2004/01/12 23:45:03" "LiS-2_16_18-8" "Linux STREAMS System Calls"
.SH NAME
getmsg \- get next message off a stream
.SH SYNOPSIS
.PP
.B #include <stropts.h>
.HP 8
.BI "int " retval " = getmsg(int " fd ", struct strbuf *" ctlptr ", struct strbuf *" dataptr ", int *" flagsp );
.SH DESCRIPTION
.PP
.B getmsg
reads a STREAMS message from the read queue of a stream head into the
caller supplied buffers.  The read messages will contain a control part or a
data part or both.  The data and control parts of the message are handled
separately by
.BR getmsg() .
.PP
The meaning and interpretation of the contents of the control part and data
part are specific to the STREAMS module to which the stream head is attached.
The semantics of these contents forms a necessary part of the STREAMS module
documentation.
.PP
The arguments to
.B getmsg()
are interpreted as follows:
.PP
.I fd
specifies a file descriptor referencing an open stream.
.PP
.I ctlptr
a pointer to a
.B strbuf
structure which describes the area used to store the control part of the
received message.
.PP
.I datptr
a pointer to a
.B strbuf
structure which describes the area used to store the data part of the
received message.
.PP
The
.B strbuf
structure contains the following members:
.sp
.nf
\fC\s-1\
struct strbuf {
    int maxlen;         /* maximum buffer length */
    int len;            /* length of data */
    char *buf;          /* ptr to buffer */
};
\s+1\fR
.fi
.TP 12
.I maxlen
specifies the maximum number of bytes that the buffer pointed to by
.I buf
can hold.
When 0 is specified,
.I maxlen
requests that only zero-length message be retrieved.
When -1 is specified,
.I maxlen
requests that the corresponding control or data part not be retrieved.
When set to a positive value,
.I maxlen
requests that at maximum only
.I maxlen
bytes of the control or data part be retrieved.
.TP 12
.I len
is a return value only.  See
.BR "\*(lqRETURN VALUES\*(rq" ,
below.
.TP 12
.I buf
points to the buffer into which the data or control information is to be placed.
.PP
If
.IR ctlptr " or " datptr
is
.BR NULL ,
or the corresponding
.I maxlen
field is set to -1, the control or data part of the message is not
processed and is left on the stream head read queue.
.PP
.I flagsp
should point to an integer that indicates the type of message
the user is able to receive and will return the type of message received.
.PP
For
.BR getmsg() ,
.I flagsp
points to an integer that
can have one of the following values:
.TP 12
.B 0
requests retrieval of the first available message on the stream
head read queue regardless of message priority;
.TP 12
.B RS_HIPRI
requests retrieval of the first high priority message on the stream
head read queue, and that low priority messages not be processed.
.PP
If the stream head is set for non-blocking operation and no message of the
specified type and priority band is available to be read,
.B getmsg()
will fail and set
.I errno
to
.RB [ EAGAIN "] or [" EWOULDBLOCK ].
If the stream head is set for blocking operation,
.B getmsg()
will block until a message of the specified type and priority band becomes
availble on the stream head read queue, or the call is interrupted by a
signal.
If the call is interrupted by a signal in this fashion,
.B getmsg()
will fail and set
.I errno
to
.BR EINTR .
.\"
.PP
If a hangup occurs on the stream from which messages are to be retrieved,
\fBgetmsg\fR continues to operate normally, as described above, until the
stream head read queue is empty.  Thereafter, it returns 0 in the \fIlen\fR
field of \fIctlptr\fR and \fIdataptr\fR.
.SH "RETURN VALUES"
.PP
Upon failure,
.B getmsg()
will return -1 and set
.I errno
as described under
.BR "\*(lqERRORS\*(rq" ,
below.
.PP
Upon success,
.B getmsg()
will return a non-negative value with any of the following flags set:
.TP 12
.B MORECTL
indicates that more control information belonging to the same message is
waiting to be retrieved from the stream head read queue with a subsequent
.B getmsg()
operation.
.TP 12
.B MOREDATA
indicates that more data belonging to the same message is waiting to be
retrieved from the stream head read queue with a subsequent
.B getmsg()
operation.
.B 0
indicates that the entire message was received successfully.
.PP
.B getmsg()
with the appropriate arguments will retrieve a higher priority message before
the remainder of a partially retreived lower priority message is retrieved.
.PP
Upon success,
.B getmsg()
will also alter the
.I len
values in the
.B strbuf
structures pointed to by
.IR ctlbuf " and " datbuf
and the integer value pointed to by
.IR flagp ,
as follows:
The
.I maxlen
member is not altered on return.
If the
.IR ctlptr " or " datptr
a not
.BR NULL ,
and
.I maxlen
is not -1,
the existence and length of the retrieved message is returned in the
.I len
member.
If there is no control or data part retrieved, the
.I len
member of the corresponding
.B strbuf
structure is set to -1.
.PP
If the control or data part retrieved is of zero-length, the control or data
part is removed from the stream head read queue and the returned
.I len
is set to 0.
If
.I maxlen
is greater than or equal to 0 and the number of bytes in the control or
data part is greater than
.IR maxlen ,
only
.I maxlen
bytes are retrieved and the remaining bytes of the corresponding part are left
on the stream head read queue.  In the
.IR retval ,
the corresponding more flag
.BR "" ( MORECTL " or " MOREDATA )
is set.
The
.I buf
member is not altered on return.
.PP
The integer pointed to by
.I flagsp
will contain one of the following values:
.TP 12
.BR 0,
the retrieved message is not a high priority message;
.TP 12
.BR RS_HIPRI,
the retrived message is a high priority message.
.SH ERRORS
.PP
Upon failure,
.B getmsg()
will
return -1 and set
.I errno
as follows:
.TP 12
.RB [ EISDIR ]
.I fd
refers to a directory.
.TP 12
.RB [ EBADF ]
.I fd
is not a valid file descriptor or is not open for reading.
.TP 12
.RB [ EFAULT ]
A specified address is outside the user's accessible address space.
Specified addresses include,
.IR ctlptr ", " datptr ", " flagsp ,
and the
.I buf
fields of the
.B strbuf
structure pointed to by
.IR cttlptr " and " datptr .
.TP 12
.RB [ ENODEV ]
.I fd
refers to a device that does not support the
.B getmsg()
system call.
.TP 12
.RB [ ENOSTR ]
.I fd
refers to a device that has no stream associated with it.
.TP 12
.RB [ EIO ]
I/O error, or,
.I fd
refers to a stream that is open but is in the process of closing.
.\".TP 12
.\".RB [ EPERM ]
.\".I fd
.\"points to a dynamic device and read permission on the device is denied.
.\"
.\"
.\"
.TP 12
.RB [ EINVAL ]
.I fd
is linked under a multiplexing driver; or,
.B getmsg()
is not supported; or, the flags pointed to by
.I flagsp
were invalid for
.BR getmsg() .
.TP 12
.RB [ EAGAIN "], [" EWOULDBLOCK ]
The stream head is set for non-blocking operation and
.B getmsg()
would block: that is, no message of the requested type and priority band is
available to be read.
.TP 12
.RB [ EINTR ]
A signal was caught, or an
.B M_SIG
message processed, before the call to
.B getmsg()
could return any data.
.TP 12
.RB [ ENOSTR ]
.I fd
has no stream associated with the file descriptor.
.TP 12
.RB [ EBADMSG ]
The message at the head of the queue is of an invalid message type (valid
message types include:
.BR M_DATA ", " M_PROTO " and " M_PCPROTO );
or, the message at head of the of the queue is not of the requested type
as specified by
.IR flagsp .
.PP
Other errors may be returned by
.BR getmsg() .
If the STREAMS module sends a
.B M_ERROR
message to the stream head, the error returned on all subsequent read
operations, including
.BR getmsg() ,
is specified in the
.B M_ERROR
message by the STREAMS module.
Which errors are returned under which conditions form part of the
necessary documentation of the STREAMS module.
.SH CAVEATS
.PP
.B LiS
.[
LiS
.]
could handle concurrent readers better.  Linux sockets code blocks concurrent
readers while a partial reader is installed against a socket.  When partial
reads are performed for messages using
.BR getmsg() .
.B LiS
.[
LiS
.]
should install the partial reader and block all other readers from completing
the partial read until the partial reader completes the read or the partial
reader closes the stream.  This would at least keep multiple threads of
execution from interferring with partial reads.
.SH NOTES
.PP
.B LiS
.[
LiS
.]
implements
.B getmsg()
as a call to
.B getpmsg()
with a
.B NULL
.I bandp
pointer.
.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 queue
structure, or is mangled.
.PP
.B LiS
.[
LiS
.]
incorreclty returns
.RB [ EINVAL ]
instead of
.RB [ EIO ]
when
.I q->q_first
yeilds a
.BR "" non- NULL
message pointer, but
.B getq()
later cannot retrieve a message.
.PP
.B LiS
.[
LiS
.]
does not return
.RB [ EIO ]
when
.B getmsg()
is called on a closing stream.
.PP
.B LiS
.[
LiS
.]
incorrectly returns
.RB [ EAGAIN "] or [" EWOULDBLOCK ]
instead of
.RB [ EINTR ]
when an
.B M_SIG
message causes a signal that interrupts the call to
.B getmsg()
before any data is read.
.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 fd
refers to a device that does not support the
.B getmsg()
system call.
.SH "SEE ALSO"
.PP
.BR intro (2),
.BR poll (2),
.BR putmsg (2),
.BR read (2),
.BR write (2),
.BR streamio (2).
.SH VERSIONS
.PP
This manpage was written for
.B LiS\c
.
.[
LiS
.]
.PP
.B getmsg()
first appeared in SVR 3.
.[
svr3
.]
.\"
.\"
.XX
.[
magic
.]
.[
svr42
.]
.[
svr4
.]
.[
svr3
.]
.[
svid
.]
.[
xns
.]
.[
xbd5
.]
.[
$LIST$
.]
.TI