[src/trunk]: src/share/man/man9 - document m_copyback_cow and m_makewritable.

[yamt <yamt%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/ee10c698962f
branches:  trunk
changeset: 569786:ee10c698962f
user:      yamt <yamt%NetBSD.org@localhost>
date:      Mon Sep 06 09:45:27 2004 +0000

description:
- document m_copyback_cow and m_makewritable.
- note limitations of m_copyback.
- bump date.

diffstat:

 share/man/man9/Makefile |   4 ++-
 share/man/man9/mbuf.9   |  73 +++++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 74 insertions(+), 3 deletions(-)

diffs (128 lines):

diff -r 7d3f305bcc40 -r ee10c698962f share/man/man9/Makefile
--- a/share/man/man9/Makefile   Mon Sep 06 09:43:29 2004 +0000
+++ b/share/man/man9/Makefile   Mon Sep 06 09:45:27 2004 +0000
@@ -1,4 +1,4 @@
-#       $NetBSD: Makefile,v 1.163 2004/07/05 11:08:38 sketch Exp $
+#       $NetBSD: Makefile,v 1.164 2004/09/06 09:45:27 yamt Exp $
 
 #      Makefile for section 9 (kernel function and variable) manual pages.
 
@@ -268,6 +268,8 @@
 MLINKS+=mbuf.9 m_get.9 mbuf.9 m_getclr.9 mbuf.9 m_gethdr.9 mbuf.9 m_devget.9 \
        mbuf.9 m_copym.9 mbuf.9 m_copypacket.9 mbuf.9 m_copydata.9 \
        mbuf.9 m_copyback.9 mbuf.9 m_cat.9 mbuf.9 m_dup.9 mbuf.9 m_prepend.9 \
+       mbuf.9 m_copyback_cow.9 \
+       mbuf.9 m_makewritable.9 \
        mbuf.9 m_pulldown.9 \
        mbuf.9 m_pullup.9 mbuf.9 m_split.9 mbuf.9 m_adj.9 mbuf.9 m_free.9 \
        mbuf.9 m_freem.9 mbuf.9 mtod.9 mbuf.9 mtocl.9 mbuf.9 cltom.9 \
diff -r 7d3f305bcc40 -r ee10c698962f share/man/man9/mbuf.9
--- a/share/man/man9/mbuf.9     Mon Sep 06 09:43:29 2004 +0000
+++ b/share/man/man9/mbuf.9     Mon Sep 06 09:45:27 2004 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: mbuf.9,v 1.28 2003/05/27 13:04:25 yamt Exp $
+.\"    $NetBSD: mbuf.9,v 1.29 2004/09/06 09:45:27 yamt Exp $
 .\"
 .\" Copyright (c) 1997 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -34,7 +34,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd May 27, 2003
+.Dd September 6, 2004
 .Dt MBUF 9
 .Os
 .Sh NAME
@@ -47,8 +47,10 @@
 .Nm m_copypacket ,
 .Nm m_copydata ,
 .Nm m_copyback ,
+.Nm m_copyback_cow ,
 .Nm m_cat ,
 .Nm m_dup ,
+.Nm m_makewritable ,
 .Nm m_prepend ,
 .Nm m_pulldown ,
 .Nm m_pullup ,
@@ -92,6 +94,10 @@
 .Fn m_copydata "struct mbuf *m" "int off" "int len" "caddr_t cp"
 .Ft void
 .Fn m_copyback "struct mbuf *m0" "int off" "int len" "caddr_t cp"
+.Ft struct mbuf *
+.Fn m_copyback_cow "struct mbuf *m0" "int off" "int len" "caddr_t cp" "int how"
+.Ft int
+.Fn m_makewritable "struct mbuf **mp" "int off" "int len" "int how"
 .Ft void
 .Fn m_cat "struct mbuf *m" "struct mbuf *n"
 .Ft struct mbuf *
@@ -328,6 +334,69 @@
 starting
 .Fa off
 bytes from the beginning, extending the mbuf chain if necessary.
+Unless attempting to extend the chain,
+.Fn m_copyback
+never fail.
+As extending the chain can fail, caller should check the failure
+by checking the resulted length of the chain in that case.
+It's an error to use
+.Fn m_copyback
+on read-only mbufs.
+.It Fn m_copyback_cow "struct mbuf *m0" "int off" "int len" "caddr_t cp" \
+"int how"
+Copies
+.Fa len
+bytes data from buffer
+.Fa cp
+back into the mbuf chain
+.Fa m0
+as
+.Fn m_copyback
+does.
+Unlike
+.Fn m_copyback ,
+It's safe to use
+.Fn m_copyback_cow
+on read-only mbufs.
+If needed,
+.Fn m_copyback_cow
+automatically allocate new mbufs and adjust chain.
+It returns a pointer to resulted mbuf chain on success.
+Otherwise, it returns NULL.
+In that case, the original mbuf
+.Fa m0
+will be freed.
+The
+.Fa how
+parameter is a choice of
+.Dv M_WAIT / M_DONTWAIT
+from caller.
+Unlike
+.Fn m_copyback ,
+extending the mbuf chain isn't supported.
+It's an error to attempt to extend the mbuf chain using
+.Fn m_copyback_cow .
+.It Fn m_makewritable "struct mbuf **mp" "int off" "int len" "int how"
+Rearranges an mbuf chain so that
+.Fa len
+bytes from offset
+.Fa off
+are writable.
+When it meets read-only mbufs, it allocates new mbufs, adjusts chain as
+.Fn m_copyback_cow
+does, and copies original contents into them.
+The
+.Fa how
+parameter is a choice of
+.Dv M_WAIT / M_DONTWAIT
+from caller.
+.Fn m_makewritable
+preserves the contents of the mbuf chain even in the case of failure.
+It updates a pointer to the mbuf chain pointed by
+.Fa mp .
+It returns 0 on success.
+Otherwise, it returns an error code, typically
+.Dv ENOBUFS .
 .It Fn m_cat "struct mbuf *m" "struct mbuf *n"
 Concatenates mbuf chain
 .Fa n