€•:Š      Œsphinx.addnodes”Œdocument”“”)”}”(Œ	rawsource”Œ ”Œchildren”]”(Œtranslations”ŒLanguagesNode”“”)”}”(hhh]”(h Œpending_xref”“”)”}”(hhh]”Œdocutils.nodes”ŒText”“”ŒChinese (Simplified)”…””}”Œparent”hsbaŒ
attributes”}”(Œids”]”Œclasses”]”Œnames”]”Œdupnames”]”Œbackrefs”]”Œ	refdomain”Œstd”Œreftype”Œdoc”Œ	reftarget”Œ(/translations/zh_CN/networking/strparser”Œmodname”NŒ	classname”NŒrefexplicit”ˆuŒtagname”hhhubh)”}”(hhh]”hŒChinese (Traditional)”…””}”hh2sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ(/translations/zh_TW/networking/strparser”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒItalian”…””}”hhFsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ(/translations/it_IT/networking/strparser”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒJapanese”…””}”hhZsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ(/translations/ja_JP/networking/strparser”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒKorean”…””}”hhnsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ(/translations/ko_KR/networking/strparser”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒSpanish”…””}”hh‚sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ(/translations/sp_SP/networking/strparser”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubeh}”(h]”h ]”h"]”h$]”h&]”Œcurrent_language”ŒEnglish”uh1h
hhŒ	_document”hŒsource”NŒline”NubhŒcomment”“”)”}”(hŒ SPDX-License-Identifier: GPL-2.0”h]”hŒ SPDX-License-Identifier: GPL-2.0”…””}”hh£sbah}”(h]”h ]”h"]”h$]”h&]”Œ	xml:space”Œpreserve”uh1h¡hhhžhhŸŒB/var/lib/git/docbuild/linux/Documentation/networking/strparser.rst”h KubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒStream Parser (strparser)”h]”hŒStream Parser (strparser)”…””}”(hh»hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hh¶hžhhŸh³h Kubhµ)”}”(hhh]”(hº)”}”(hŒIntroduction”h]”hŒIntroduction”…””}”(hhÌhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hhÉhžhhŸh³h KubhŒ	paragraph”“”)”}”(hXo  The stream parser (strparser) is a utility that parses messages of an
application layer protocol running over a data stream. The stream
parser works in conjunction with an upper layer in the kernel to provide
kernel support for application layer messages. For instance, Kernel
Connection Multiplexor (KCM) uses the Stream Parser to parse messages
using a BPF program.”h]”hXo  The stream parser (strparser) is a utility that parses messages of an
application layer protocol running over a data stream. The stream
parser works in conjunction with an upper layer in the kernel to provide
kernel support for application layer messages. For instance, Kernel
Connection Multiplexor (KCM) uses the Stream Parser to parse messages
using a BPF program.”…””}”(hhÜhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K
hhÉhžhubhÛ)”}”(hŒJThe strparser works in one of two modes: receive callback or general
mode.”h]”hŒJThe strparser works in one of two modes: receive callback or general
mode.”…””}”(hhêhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h KhhÉhžhubhÛ)”}”(hŒ¥In receive callback mode, the strparser is called from the data_ready
callback of a TCP socket. Messages are parsed and delivered as they are
received on the socket.”h]”hŒ¥In receive callback mode, the strparser is called from the data_ready
callback of a TCP socket. Messages are parsed and delivered as they are
received on the socket.”…””}”(hhøhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h KhhÉhžhubhÛ)”}”(hŒ×In general mode, a sequence of skbs are fed to strparser from an
outside source. Message are parsed and delivered as the sequence is
processed. This modes allows strparser to be applied to arbitrary
streams of data.”h]”hŒ×In general mode, a sequence of skbs are fed to strparser from an
outside source. Message are parsed and delivered as the sequence is
processed. This modes allows strparser to be applied to arbitrary
streams of data.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h KhhÉhžhubeh}”(h]”Œintroduction”ah ]”h"]”Œintroduction”ah$]”h&]”uh1h´hh¶hžhhŸh³h Kubhµ)”}”(hhh]”(hº)”}”(hŒ	Interface”h]”hŒ	Interface”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj  hžhhŸh³h KubhÛ)”}”(hX@  The API includes a context structure, a set of callbacks, utility
functions, and a data_ready function for receive callback mode. The
callbacks include a parse_msg function that is called to perform
parsing (e.g.  BPF parsing in case of KCM), and a rcv_msg function
that is called when a full message has been completed.”h]”hX@  The API includes a context structure, a set of callbacks, utility
functions, and a data_ready function for receive callback mode. The
callbacks include a parse_msg function that is called to perform
parsing (e.g.  BPF parsing in case of KCM), and a rcv_msg function
that is called when a full message has been completed.”…””}”(hj-  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K hj  hžhubeh}”(h]”Œ	interface”ah ]”h"]”Œ	interface”ah$]”h&]”uh1h´hh¶hžhhŸh³h Kubhµ)”}”(hhh]”(hº)”}”(hŒ	Functions”h]”hŒ	Functions”…””}”(hjF  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjC  hžhhŸh³h K'ubhŒblock_quote”“”)”}”(hX²   ::

    strp_init(struct strparser *strp, struct sock *sk,
            const struct strp_callbacks *cb)

 Called to initialize a stream parser. strp is a struct of type
 strparser that is allocated by the upper layer. sk is the TCP
 socket associated with the stream parser for use with receive
 callback mode; in general mode this is set to NULL. Callbacks
 are called by the stream parser (the callbacks are listed below).

 ::

    void strp_pause(struct strparser *strp)

 Temporarily pause a stream parser. Message parsing is suspended
 and no new messages are delivered to the upper layer.

 ::

    void strp_unpause(struct strparser *strp)

 Unpause a paused stream parser.

 ::

    void strp_stop(struct strparser *strp);

 strp_stop is called to completely stop stream parser operations.
 This is called internally when the stream parser encounters an
 error, and it is called from the upper layer to stop parsing
 operations.

 ::

    void strp_done(struct strparser *strp);

 strp_done is called to release any resources held by the stream
 parser instance. This must be called after the stream processor
 has been stopped.

 ::

    int strp_process(struct strparser *strp, struct sk_buff *orig_skb,
                     unsigned int orig_offset, size_t orig_len,
                     size_t max_msg_size, long timeo)

strp_process is called in general mode for a stream parser to
parse an sk_buff. The number of bytes processed or a negative
error number is returned. Note that strp_process does not
consume the sk_buff. max_msg_size is maximum size the stream
parser will parse. timeo is timeout for completing a message.

::

    void strp_data_ready(struct strparser *strp);

The upper layer calls strp_tcp_data_ready when data is ready on
the lower socket for strparser to process. This should be called
from a data_ready callback that is set on the socket. Note that
maximum messages size is the limit of the receive socket
buffer and message timeout is the receive timeout for the socket.

::

    void strp_check_rcv(struct strparser *strp);

strp_check_rcv is called to check for new messages on the socket.
This is normally called at initialization of a stream parser
instance or after strp_unpause.
”h]”(jU  )”}”(hX  ::

   strp_init(struct strparser *strp, struct sock *sk,
           const struct strp_callbacks *cb)

Called to initialize a stream parser. strp is a struct of type
strparser that is allocated by the upper layer. sk is the TCP
socket associated with the stream parser for use with receive
callback mode; in general mode this is set to NULL. Callbacks
are called by the stream parser (the callbacks are listed below).

::

   void strp_pause(struct strparser *strp)

Temporarily pause a stream parser. Message parsing is suspended
and no new messages are delivered to the upper layer.

::

   void strp_unpause(struct strparser *strp)

Unpause a paused stream parser.

::

   void strp_stop(struct strparser *strp);

strp_stop is called to completely stop stream parser operations.
This is called internally when the stream parser encounters an
error, and it is called from the upper layer to stop parsing
operations.

::

   void strp_done(struct strparser *strp);

strp_done is called to release any resources held by the stream
parser instance. This must be called after the stream processor
has been stopped.

::

   int strp_process(struct strparser *strp, struct sk_buff *orig_skb,
                    unsigned int orig_offset, size_t orig_len,
                    size_t max_msg_size, long timeo)
”h]”(hŒliteral_block”“”)”}”(hŒ[strp_init(struct strparser *strp, struct sock *sk,
        const struct strp_callbacks *cb)”h]”hŒ[strp_init(struct strparser *strp, struct sock *sk,
        const struct strp_callbacks *cb)”…””}”hj`  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j^  hŸh³h K+hjZ  ubhÛ)”}”(hX:  Called to initialize a stream parser. strp is a struct of type
strparser that is allocated by the upper layer. sk is the TCP
socket associated with the stream parser for use with receive
callback mode; in general mode this is set to NULL. Callbacks
are called by the stream parser (the callbacks are listed below).”h]”hX:  Called to initialize a stream parser. strp is a struct of type
strparser that is allocated by the upper layer. sk is the TCP
socket associated with the stream parser for use with receive
callback mode; in general mode this is set to NULL. Callbacks
are called by the stream parser (the callbacks are listed below).”…””}”(hjn  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K.hjZ  ubj_  )”}”(hŒ'void strp_pause(struct strparser *strp)”h]”hŒ'void strp_pause(struct strparser *strp)”…””}”hj|  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j^  hŸh³h K6hjZ  ubhÛ)”}”(hŒuTemporarily pause a stream parser. Message parsing is suspended
and no new messages are delivered to the upper layer.”h]”hŒuTemporarily pause a stream parser. Message parsing is suspended
and no new messages are delivered to the upper layer.”…””}”(hjŠ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K8hjZ  ubj_  )”}”(hŒ)void strp_unpause(struct strparser *strp)”h]”hŒ)void strp_unpause(struct strparser *strp)”…””}”hj˜  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j^  hŸh³h K=hjZ  ubhÛ)”}”(hŒUnpause a paused stream parser.”h]”hŒUnpause a paused stream parser.”…””}”(hj¦  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K?hjZ  ubj_  )”}”(hŒ'void strp_stop(struct strparser *strp);”h]”hŒ'void strp_stop(struct strparser *strp);”…””}”hj´  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j^  hŸh³h KChjZ  ubhÛ)”}”(hŒÈstrp_stop is called to completely stop stream parser operations.
This is called internally when the stream parser encounters an
error, and it is called from the upper layer to stop parsing
operations.”h]”hŒÈstrp_stop is called to completely stop stream parser operations.
This is called internally when the stream parser encounters an
error, and it is called from the upper layer to stop parsing
operations.”…””}”(hjÂ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h KEhjZ  ubj_  )”}”(hŒ'void strp_done(struct strparser *strp);”h]”hŒ'void strp_done(struct strparser *strp);”…””}”hjÐ  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j^  hŸh³h KLhjZ  ubhÛ)”}”(hŒ‘strp_done is called to release any resources held by the stream
parser instance. This must be called after the stream processor
has been stopped.”h]”hŒ‘strp_done is called to release any resources held by the stream
parser instance. This must be called after the stream processor
has been stopped.”…””}”(hjÞ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h KNhjZ  ubj_  )”}”(hŒ°int strp_process(struct strparser *strp, struct sk_buff *orig_skb,
                 unsigned int orig_offset, size_t orig_len,
                 size_t max_msg_size, long timeo)”h]”hŒ°int strp_process(struct strparser *strp, struct sk_buff *orig_skb,
                 unsigned int orig_offset, size_t orig_len,
                 size_t max_msg_size, long timeo)”…””}”hjì  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j^  hŸh³h KThjZ  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1jT  hŸh³h K)hjV  ubhÛ)”}”(hX0  strp_process is called in general mode for a stream parser to
parse an sk_buff. The number of bytes processed or a negative
error number is returned. Note that strp_process does not
consume the sk_buff. max_msg_size is maximum size the stream
parser will parse. timeo is timeout for completing a message.”h]”hX0  strp_process is called in general mode for a stream parser to
parse an sk_buff. The number of bytes processed or a negative
error number is returned. Note that strp_process does not
consume the sk_buff. max_msg_size is maximum size the stream
parser will parse. timeo is timeout for completing a message.”…””}”(hj   hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h KXhjV  ubj_  )”}”(hŒ-void strp_data_ready(struct strparser *strp);”h]”hŒ-void strp_data_ready(struct strparser *strp);”…””}”hj  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j^  hŸh³h K`hjV  ubhÛ)”}”(hX;  The upper layer calls strp_tcp_data_ready when data is ready on
the lower socket for strparser to process. This should be called
from a data_ready callback that is set on the socket. Note that
maximum messages size is the limit of the receive socket
buffer and message timeout is the receive timeout for the socket.”h]”hX;  The upper layer calls strp_tcp_data_ready when data is ready on
the lower socket for strparser to process. This should be called
from a data_ready callback that is set on the socket. Note that
maximum messages size is the limit of the receive socket
buffer and message timeout is the receive timeout for the socket.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h KbhjV  ubj_  )”}”(hŒ,void strp_check_rcv(struct strparser *strp);”h]”hŒ,void strp_check_rcv(struct strparser *strp);”…””}”hj*  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j^  hŸh³h KjhjV  ubhÛ)”}”(hŒžstrp_check_rcv is called to check for new messages on the socket.
This is normally called at initialization of a stream parser
instance or after strp_unpause.”h]”hŒžstrp_check_rcv is called to check for new messages on the socket.
This is normally called at initialization of a stream parser
instance or after strp_unpause.”…””}”(hj8  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h KlhjV  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1jT  hŸh³h K)hjC  hžhubeh}”(h]”Œ	functions”ah ]”h"]”Œ	functions”ah$]”h&]”uh1h´hh¶hžhhŸh³h K'ubhµ)”}”(hhh]”(hº)”}”(hŒ	Callbacks”h]”hŒ	Callbacks”…””}”(hjW  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjT  hžhhŸh³h KqubhÛ)”}”(hŒThere are seven callbacks:”h]”hŒThere are seven callbacks:”…””}”(hje  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h KshjT  hžhubjU  )”}”(hXt  ::

    int (*parse_msg)(struct strparser *strp, struct sk_buff *skb);

parse_msg is called to determine the length of the next message
in the stream. The upper layer must implement this function. It
should parse the sk_buff as containing the headers for the
next application layer message in the stream.

The skb->cb in the input skb is a struct strp_msg. Only
the offset field is relevant in parse_msg and gives the offset
where the message starts in the skb.

The return values of this function are:

=========    ===========================================================
>0           indicates length of successfully parsed message
0            indicates more data must be received to parse the message
-ESTRPIPE    current message should not be processed by the
             kernel, return control of the socket to userspace which
             can proceed to read the messages itself
other < 0    Error in parsing, give control back to userspace
             assuming that synchronization is lost and the stream
             is unrecoverable (application expected to close TCP socket)
=========    ===========================================================

In the case that an error is returned (return value is less than
zero) and the parser is in receive callback mode, then it will set
the error on TCP socket and wake it up. If parse_msg returned
-ESTRPIPE and the stream parser had previously read some bytes for
the current message, then the error set on the attached socket is
ENODATA since the stream is unrecoverable in that case.

::

    void (*lock)(struct strparser *strp)

The lock callback is called to lock the strp structure when
the strparser is performing an asynchronous operation (such as
processing a timeout). In receive callback mode the default
function is to lock_sock for the associated socket. In general
mode the callback must be set appropriately.

::

    void (*unlock)(struct strparser *strp)

The unlock callback is called to release the lock obtained
by the lock callback. In receive callback mode the default
function is release_sock for the associated socket. In general
mode the callback must be set appropriately.

::

    void (*rcv_msg)(struct strparser *strp, struct sk_buff *skb);

rcv_msg is called when a full message has been received and
is queued. The callee must consume the sk_buff; it can
call strp_pause to prevent any further messages from being
received in rcv_msg (see strp_pause above). This callback
must be set.

The skb->cb in the input skb is a struct strp_msg. This
struct contains two fields: offset and full_len. Offset is
where the message starts in the skb, and full_len is the
the length of the message. skb->len - offset may be greater
than full_len since strparser does not trim the skb.

::

    int (*read_sock)(struct strparser *strp, read_descriptor_t *desc,
                 sk_read_actor_t recv_actor);

The read_sock callback is used by strparser instead of
sock->ops->read_sock, if provided.
::

    int (*read_sock_done)(struct strparser *strp, int err);

 read_sock_done is called when the stream parser is done reading
 the TCP socket in receive callback mode. The stream parser may
 read multiple messages in a loop and this function allows cleanup
 to occur when exiting the loop. If the callback is not set (NULL
 in strp_init) a default function is used.

 ::

    void (*abort_parser)(struct strparser *strp, int err);

 This function is called when stream parser encounters an error
 in parsing. The default function stops the stream parser and
 sets the error in the socket if the parser is in receive callback
 mode. The default function can be changed by setting the callback
 to non-NULL in strp_init.
”h]”(j_  )”}”(hŒ>int (*parse_msg)(struct strparser *strp, struct sk_buff *skb);”h]”hŒ>int (*parse_msg)(struct strparser *strp, struct sk_buff *skb);”…””}”hjw  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j^  hŸh³h Kwhjs  ubhÛ)”}”(hŒèparse_msg is called to determine the length of the next message
in the stream. The upper layer must implement this function. It
should parse the sk_buff as containing the headers for the
next application layer message in the stream.”h]”hŒèparse_msg is called to determine the length of the next message
in the stream. The upper layer must implement this function. It
should parse the sk_buff as containing the headers for the
next application layer message in the stream.”…””}”(hj…  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Kyhjs  ubhÛ)”}”(hŒ›The skb->cb in the input skb is a struct strp_msg. Only
the offset field is relevant in parse_msg and gives the offset
where the message starts in the skb.”h]”hŒ›The skb->cb in the input skb is a struct strp_msg. Only
the offset field is relevant in parse_msg and gives the offset
where the message starts in the skb.”…””}”(hj“  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K~hjs  ubhÛ)”}”(hŒ'The return values of this function are:”h]”hŒ'The return values of this function are:”…””}”(hj¡  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K‚hjs  ubhŒtable”“”)”}”(hhh]”hŒtgroup”“”)”}”(hhh]”(hŒcolspec”“”)”}”(hhh]”h}”(h]”h ]”h"]”h$]”h&]”Œcolwidth”K	uh1j¹  hj¶  ubjº  )”}”(hhh]”h}”(h]”h ]”h"]”h$]”h&]”Œcolwidth”K;uh1j¹  hj¶  ubhŒtbody”“”)”}”(hhh]”(hŒrow”“”)”}”(hhh]”(hŒentry”“”)”}”(hhh]”hÛ)”}”(hŒ>0”h]”hŒ>0”…””}”(hjÞ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K…hjÛ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jÙ  hjÖ  ubjÚ  )”}”(hhh]”hÛ)”}”(hŒ/indicates length of successfully parsed message”h]”hŒ/indicates length of successfully parsed message”…””}”(hjõ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K…hjò  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jÙ  hjÖ  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1jÔ  hjÑ  ubjÕ  )”}”(hhh]”(jÚ  )”}”(hhh]”hÛ)”}”(hŒ0”h]”hŒ0”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K†hj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jÙ  hj  ubjÚ  )”}”(hhh]”hÛ)”}”(hŒ9indicates more data must be received to parse the message”h]”hŒ9indicates more data must be received to parse the message”…””}”(hj,  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K†hj)  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jÙ  hj  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1jÔ  hjÑ  ubjÕ  )”}”(hhh]”(jÚ  )”}”(hhh]”hÛ)”}”(hŒ	-ESTRPIPE”h]”hŒ	-ESTRPIPE”…””}”(hjL  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K‡hjI  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jÙ  hjF  ubjÚ  )”}”(hhh]”hÛ)”}”(hŒŽcurrent message should not be processed by the
kernel, return control of the socket to userspace which
can proceed to read the messages itself”h]”hŒŽcurrent message should not be processed by the
kernel, return control of the socket to userspace which
can proceed to read the messages itself”…””}”(hjc  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K‡hj`  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jÙ  hjF  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1jÔ  hjÑ  ubjÕ  )”}”(hhh]”(jÚ  )”}”(hhh]”hÛ)”}”(hŒ	other < 0”h]”hŒ	other < 0”…””}”(hjƒ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h KŠhj€  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jÙ  hj}  ubjÚ  )”}”(hhh]”hÛ)”}”(hŒ¡Error in parsing, give control back to userspace
assuming that synchronization is lost and the stream
is unrecoverable (application expected to close TCP socket)”h]”hŒ¡Error in parsing, give control back to userspace
assuming that synchronization is lost and the stream
is unrecoverable (application expected to close TCP socket)”…””}”(hjš  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h KŠhj—  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jÙ  hj}  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1jÔ  hjÑ  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1jÏ  hj¶  ubeh}”(h]”h ]”h"]”h$]”h&]”Œcols”Kuh1j´  hj±  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j¯  hjs  ubhÛ)”}”(hX~  In the case that an error is returned (return value is less than
zero) and the parser is in receive callback mode, then it will set
the error on TCP socket and wake it up. If parse_msg returned
-ESTRPIPE and the stream parser had previously read some bytes for
the current message, then the error set on the attached socket is
ENODATA since the stream is unrecoverable in that case.”h]”hX~  In the case that an error is returned (return value is less than
zero) and the parser is in receive callback mode, then it will set
the error on TCP socket and wake it up. If parse_msg returned
-ESTRPIPE and the stream parser had previously read some bytes for
the current message, then the error set on the attached socket is
ENODATA since the stream is unrecoverable in that case.”…””}”(hjÇ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Khjs  ubj_  )”}”(hŒ$void (*lock)(struct strparser *strp)”h]”hŒ$void (*lock)(struct strparser *strp)”…””}”hjÕ  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j^  hŸh³h K˜hjs  ubhÛ)”}”(hX"  The lock callback is called to lock the strp structure when
the strparser is performing an asynchronous operation (such as
processing a timeout). In receive callback mode the default
function is to lock_sock for the associated socket. In general
mode the callback must be set appropriately.”h]”hX"  The lock callback is called to lock the strp structure when
the strparser is performing an asynchronous operation (such as
processing a timeout). In receive callback mode the default
function is to lock_sock for the associated socket. In general
mode the callback must be set appropriately.”…””}”(hjã  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Kšhjs  ubj_  )”}”(hŒ&void (*unlock)(struct strparser *strp)”h]”hŒ&void (*unlock)(struct strparser *strp)”…””}”hjñ  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j^  hŸh³h K¢hjs  ubhÛ)”}”(hŒáThe unlock callback is called to release the lock obtained
by the lock callback. In receive callback mode the default
function is release_sock for the associated socket. In general
mode the callback must be set appropriately.”h]”hŒáThe unlock callback is called to release the lock obtained
by the lock callback. In receive callback mode the default
function is release_sock for the associated socket. In general
mode the callback must be set appropriately.”…””}”(hjÿ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K¤hjs  ubj_  )”}”(hŒ=void (*rcv_msg)(struct strparser *strp, struct sk_buff *skb);”h]”hŒ=void (*rcv_msg)(struct strparser *strp, struct sk_buff *skb);”…””}”hj  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j^  hŸh³h K«hjs  ubhÛ)”}”(hŒôrcv_msg is called when a full message has been received and
is queued. The callee must consume the sk_buff; it can
call strp_pause to prevent any further messages from being
received in rcv_msg (see strp_pause above). This callback
must be set.”h]”hŒôrcv_msg is called when a full message has been received and
is queued. The callee must consume the sk_buff; it can
call strp_pause to prevent any further messages from being
received in rcv_msg (see strp_pause above). This callback
must be set.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K­hjs  ubhÛ)”}”(hX  The skb->cb in the input skb is a struct strp_msg. This
struct contains two fields: offset and full_len. Offset is
where the message starts in the skb, and full_len is the
the length of the message. skb->len - offset may be greater
than full_len since strparser does not trim the skb.”h]”hX  The skb->cb in the input skb is a struct strp_msg. This
struct contains two fields: offset and full_len. Offset is
where the message starts in the skb, and full_len is the
the length of the message. skb->len - offset may be greater
than full_len since strparser does not trim the skb.”…””}”(hj)  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K³hjs  ubj_  )”}”(hŒkint (*read_sock)(struct strparser *strp, read_descriptor_t *desc,
             sk_read_actor_t recv_actor);”h]”hŒkint (*read_sock)(struct strparser *strp, read_descriptor_t *desc,
             sk_read_actor_t recv_actor);”…””}”hj7  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j^  hŸh³h K»hjs  ubhÛ)”}”(hŒ\The read_sock callback is used by strparser instead of
sock->ops->read_sock, if provided.
::”h]”hŒYThe read_sock callback is used by strparser instead of
sock->ops->read_sock, if provided.”…””}”(hjE  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K¾hjs  ubj_  )”}”(hXÁ     int (*read_sock_done)(struct strparser *strp, int err);

read_sock_done is called when the stream parser is done reading
the TCP socket in receive callback mode. The stream parser may
read multiple messages in a loop and this function allows cleanup
to occur when exiting the loop. If the callback is not set (NULL
in strp_init) a default function is used.

::

   void (*abort_parser)(struct strparser *strp, int err);

This function is called when stream parser encounters an error
in parsing. The default function stops the stream parser and
sets the error in the socket if the parser is in receive callback
mode. The default function can be changed by setting the callback
to non-NULL in strp_init.”h]”hXÁ     int (*read_sock_done)(struct strparser *strp, int err);

read_sock_done is called when the stream parser is done reading
the TCP socket in receive callback mode. The stream parser may
read multiple messages in a loop and this function allows cleanup
to occur when exiting the loop. If the callback is not set (NULL
in strp_init) a default function is used.

::

   void (*abort_parser)(struct strparser *strp, int err);

This function is called when stream parser encounters an error
in parsing. The default function stops the stream parser and
sets the error in the socket if the parser is in receive callback
mode. The default function can be changed by setting the callback
to non-NULL in strp_init.”…””}”hjS  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j^  hŸh³h KÂhjs  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1jT  hŸh³h KuhjT  hžhubeh}”(h]”Œ	callbacks”ah ]”h"]”Œ	callbacks”ah$]”h&]”uh1h´hh¶hžhhŸh³h Kqubhµ)”}”(hhh]”(hº)”}”(hŒ
Statistics”h]”hŒ
Statistics”…””}”(hjr  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjo  hžhhŸh³h KÕubhÛ)”}”(hX.  Various counters are kept for each stream parser instance. These are in
the strp_stats structure. strp_aggr_stats is a convenience structure for
accumulating statistics for multiple stream parser instances.
save_strp_stats and aggregate_strp_stats are helper functions to save
and aggregate statistics.”h]”hX.  Various counters are kept for each stream parser instance. These are in
the strp_stats structure. strp_aggr_stats is a convenience structure for
accumulating statistics for multiple stream parser instances.
save_strp_stats and aggregate_strp_stats are helper functions to save
and aggregate statistics.”…””}”(hj€  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K×hjo  hžhubeh}”(h]”Œ
statistics”ah ]”h"]”Œ
statistics”ah$]”h&]”uh1h´hh¶hžhhŸh³h KÕubhµ)”}”(hhh]”(hº)”}”(hŒMessage assembly limits”h]”hŒMessage assembly limits”…””}”(hj™  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj–  hžhhŸh³h KÞubhÛ)”}”(hŒYThe stream parser provide mechanisms to limit the resources consumed by
message assembly.”h]”hŒYThe stream parser provide mechanisms to limit the resources consumed by
message assembly.”…””}”(hj§  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Kàhj–  hžhubhÛ)”}”(hXw  A timer is set when assembly starts for a new message. In receive
callback mode the message timeout is taken from rcvtime for the
associated TCP socket. In general mode, the timeout is passed as an
argument in strp_process. If the timer fires before assembly completes
the stream parser is aborted and the ETIMEDOUT error is set on the TCP
socket if in receive callback mode.”h]”hXw  A timer is set when assembly starts for a new message. In receive
callback mode the message timeout is taken from rcvtime for the
associated TCP socket. In general mode, the timeout is passed as an
argument in strp_process. If the timer fires before assembly completes
the stream parser is aborted and the ETIMEDOUT error is set on the TCP
socket if in receive callback mode.”…””}”(hjµ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Kãhj–  hžhubhÛ)”}”(hX„  In receive callback mode, message length is limited to the receive
buffer size of the associated TCP socket. If the length returned by
parse_msg is greater than the socket buffer size then the stream parser
is aborted with EMSGSIZE error set on the TCP socket. Note that this
makes the maximum size of receive skbuffs for a socket with a stream
parser to be 2*sk_rcvbuf of the TCP socket.”h]”hX„  In receive callback mode, message length is limited to the receive
buffer size of the associated TCP socket. If the length returned by
parse_msg is greater than the socket buffer size then the stream parser
is aborted with EMSGSIZE error set on the TCP socket. Note that this
makes the maximum size of receive skbuffs for a socket with a stream
parser to be 2*sk_rcvbuf of the TCP socket.”…””}”(hjÃ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Kêhj–  hžhubhÛ)”}”(hŒUIn general mode the message length limit is passed in as an argument
to strp_process.”h]”hŒUIn general mode the message length limit is passed in as an argument
to strp_process.”…””}”(hjÑ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h Kñhj–  hžhubeh}”(h]”Œmessage-assembly-limits”ah ]”h"]”Œmessage assembly limits”ah$]”h&]”uh1h´hh¶hžhhŸh³h KÞubhµ)”}”(hhh]”(hº)”}”(hŒAuthor”h]”hŒAuthor”…””}”(hjê  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjç  hžhhŸh³h KõubhÛ)”}”(hŒ Tom Herbert (tom@quantonium.net)”h]”(hŒTom Herbert (”…””}”(hjø  hžhhŸNh NubhŒ	reference”“”)”}”(hŒtom@quantonium.net”h]”hŒtom@quantonium.net”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”Œmailto:tom@quantonium.net”uh1j   hjø  ubhŒ)”…””}”(hjø  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÚhŸh³h K÷hjç  hžhubeh}”(h]”Œauthor”ah ]”h"]”Œauthor”ah$]”h&]”uh1h´hh¶hžhhŸh³h Kõubeh}”(h]”Œstream-parser-strparser”ah ]”h"]”Œstream parser (strparser)”ah$]”h&]”uh1h´hhhžhhŸh³h Kubeh}”(h]”h ]”h"]”h$]”h&]”Œsource”h³uh1hŒcurrent_source”NŒcurrent_line”NŒsettings”Œdocutils.frontend”ŒValues”“”)”}”(h¹NŒ	generator”NŒ	datestamp”NŒsource_link”NŒ
source_url”NŒtoc_backlinks”jÙ  Œfootnote_backlinks”KŒsectnum_xform”KŒstrip_comments”NŒstrip_elements_with_classes”NŒstrip_classes”NŒreport_level”KŒ
halt_level”KŒexit_status_level”KŒdebug”NŒwarning_stream”NŒ	traceback”ˆŒinput_encoding”Œ	utf-8-sig”Œinput_encoding_error_handler”Œstrict”Œoutput_encoding”Œutf-8”Œoutput_encoding_error_handler”jN  Œerror_encoding”Œutf-8”Œerror_encoding_error_handler”Œbackslashreplace”Œlanguage_code”Œen”Œrecord_dependencies”NŒconfig”NŒ	id_prefix”hŒauto_id_prefix”Œid”Œdump_settings”NŒdump_internals”NŒdump_transforms”NŒdump_pseudo_xml”NŒexpose_internals”NŒstrict_visitor”NŒ_disable_config”NŒ_source”h³Œ_destination”NŒ_config_files”]”Œ7/var/lib/git/docbuild/linux/Documentation/docutils.conf”aŒfile_insertion_enabled”ˆŒraw_enabled”KŒline_length_limit”M'Œpep_references”NŒpep_base_url”Œhttps://peps.python.org/”Œpep_file_url_template”Œpep-%04d”Œrfc_references”NŒrfc_base_url”Œ&https://datatracker.ietf.org/doc/html/”Œ	tab_width”KŒtrim_footnote_reference_space”‰Œsyntax_highlight”Œlong”Œsmart_quotes”ˆŒsmartquotes_locales”]”Œcharacter_level_inline_markup”‰Œdoctitle_xform”‰Œdocinfo_xform”KŒsectsubtitle_xform”‰Œimage_loading”Œlink”Œembed_stylesheet”‰Œcloak_email_addresses”ˆŒsection_self_link”‰Œenv”NubŒreporter”NŒindirect_targets”]”Œsubstitution_defs”}”Œsubstitution_names”}”Œrefnames”}”Œrefids”}”Œnameids”}”(j)  j&  j  j  j@  j=  jQ  jN  jl  ji  j“  j  jä  já  j!  j  uŒ	nametypes”}”(j)  ‰j  ‰j@  ‰jQ  ‰jl  ‰j“  ‰jä  ‰j!  ‰uh}”(j&  h¶j  hÉj=  j  jN  jC  ji  jT  j  jo  já  j–  j  jç  uŒfootnote_refs”}”Œcitation_refs”}”Œautofootnotes”]”Œautofootnote_refs”]”Œsymbol_footnotes”]”Œsymbol_footnote_refs”]”Œ	footnotes”]”Œ	citations”]”Œautofootnote_start”KŒsymbol_footnote_start”K Œ
id_counter”Œcollections”ŒCounter”“”}”…”R”Œparse_messages”]”Œtransform_messages”]”Œtransformer”NŒinclude_log”]”Œ
decoration”Nhžhub.