pullupmsg.9

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

'\" tr
.\" -*- nroff -*-
.\"
.\" @(#) pullupmsg.9,v 1.1.4.1 2004/01/12 23:33:09 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:33:09 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 PULLUPMSG 9 "2004/01/12 23:33:09" "LiS-2_16_18-8" "Linux STREAMS DDI/DKI"
.SH NAME
.B pullupmsg, lis_pullupmsg
\- pull up the bytes in a \fISTREAMS\fR message
.SH SYNOPSIS
.PP
.B #include <sys/stream.h>
.HP 8
.BI "int " retval " = pullupmsg(struct msgb *" mp ", int " len );
.SH DESCRIPTION
.PP
.BR pullupmsg ()
attempts to merge the first
.I len
data bytes of the passed in message pointed to by
.I mp
into a single data block.
.PP
If
.I len
is -1,
.BR pullupmsg ()
attempts to merge all of the leading data blocks of the same type from the
passed in message pointed to by
.I mp
into a single data block.
.PP
If there is nothing to alter (that is, the initial data block contains greater than or 
equal to
.I
len
bytes, or there is only one data block in the message),
.BR pullupmsg ()
returns success without altering the message.
.PP
If the number of bytes in the initial blocks of the passed in message pointed
to by
.I mp
is less than the number of bytes specified in
.IR len ,
.BR pullupmsg ()
will fail.
.PP
.BR pullupmsg ()
does not allocate a new message block, but attaches the altered data block to
the existing initial message block.
.BR pullupmsg ()
does not deallocate the message blocks or data blocks that were absorbed into
the new data block: instead,
.BR pullupmsg ()
sets the
.I b_wptr
to the
.I b_rptr
in the message blocks of all absorbed data blocks.
.PP
.BR pullupmsg ()
is typically used where it is necessary for the first number of bytes in a
.IR STREAMS (4)
message be continguous to meet the needs of the routines processing
the bytes contained in the message.  In this case,
.BR pullupmsg ()
is called before processing the bytes.
.SH "RETURN VALUES"
.PP
Upon success,
.BR pullupmsg ()
returns true (1), and the message pointed to by
.I mp
is altered.
.PP
Upon failure,
.BR pullupmsg ()
returns false (0), and the passed in message is unaltered.
.SH ERRORS
.PP
.BR pullupmsg ()
failes and returns false (0) when
the number bytes in the initial data blocks of the same type in the passed in
message pointed to by
.I mp
is less than the number of bytes specified in
.IR len ;
or, when the passed in message point
.I mp
is
.BR NULL ;
or, when allocation of the necessary blocks fails.
.SH CAVEATS
.PP
It is not always necessary to allocate a new data block to contain the pulled
up bytes: if there is sufficient room in the initial data block, the initial
data block can be reused.
.B LiS
.[
LiS
.]
checks for this possibility and efficiently reuses the initial data block
where possible.
.SH "SEE ALSO"
.PP
.BR msgpullup (9).
.SH VERSIONS
.PP
This manpage was written for
.B LiS\c
.
.[
LiS
.]
.PP
.BR pullupmsg ()
first appeared in SVR 3.
.[
svr3
.]
.\"
.\"
.XX
.[
magic
.]
.[
svr42
.]
.[
svr4
.]
.\"
.\"
.[
$LIST$
.]
.TA