Protoco...:Roster(3)

okay so bestie, this is Protoco...:Roster(3) — a User Contributed Perl Documentation page, and it's giving roster-protocol realness. We're gonna walk through it together, no cap. 💖

🌸 NAME 🌸

Protoco...:Roster(3) — that's the manual page name shown up top and down at the bottom. The NAME section itself is literally empty in the source, so we're not inventing anything. Iconic minimalism, honestly. 💅

✨ SYNOPSIS ✨

No synopsis text here either, bestie — the source goes straight into DESCRIPTION. Keep scrolling. 🫶

🦋 DESCRIPTION 🦋

Okay so here's the vibe. Example from RFC3921:

        <iq from='juliet@example.com/balcony'
            id='bv1bs71f'
            type='get'>
         <query xmlns='jabber:iq:roster'/>
        </iq>

Response from server:

        <iq id='bv1bs71f'
            to='juliet@example.com/chamber'
            type='result'>
         <query xmlns='jabber:iq:roster' ver='ver7'>
           <item jid='nurse@example.com'/>
           <item jid='romeo@example.net'/>
         </query>
        </iq>

Behind the scenes, this little note is in the source, word-for-word: IQ start - stash current IQ on stream Query start - set IQ query type to xmlns.

Each item is parsed as a roster entry. Periodt.

A roster request for a user that does not exist will return an error as follows:

        <iq id='bv1bs71f'
            to='juliet@example.com/chamber'
            type='error'>
         <error type='auth'>
           <item-not-found
               xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
         </error>
        </iq>

Updates:

An update request is as follows:

        <iq from='juliet@example.com/balcony'
            id='rs1'
            type='set'>
         <query xmlns='jabber:iq:roster'>
           <item jid='nurse@example.com'/>
         </query>
        </iq>

Pass subscription='remove' as the item attribute to remove rather than adding the contact.

More detailed example:

          C: <iq from='juliet@example.com/balcony'
                 id='ph1xaz53'
                 type='set'>
               <query xmlns='jabber:iq:roster'>
                 <item jid='nurse@example.com'
                       name='Nurse'>
                   <group>Servants</group>
                 </item>
               </query>
             </iq>

Server push requests can be sent through as follows:

        <iq id='a78b4q6ha463'
            to='juliet@example.com/chamber'
            type='set'>
         <query xmlns='jabber:iq:roster'>
           <item jid='nurse@example.com'/>
         </query>
        </iq>

with the client reponse being an empty result:

        <iq from='juliet@example.com/balcony'
            id='a78b4q6ha463'
            type='result'/>

Note the original source spells it reponse, and we're keeping that exactly as-is. No autocorrect erasure here. 💀

Until the client sends the initial roster request, it will not receive any server push information.

Subscribe by sending something like this:

          UC: <presence id='xk3h1v69'
                        to='juliet@example.com'
                        type='subscribe'/>

Requesting a new contact will cause the server to send out an ask request:

          US: <iq id='b89c5r7ib574'
                  to='romeo@example.net/foo'
                  type='set'>
                <query xmlns='jabber:iq:roster'>
                  <item ask='subscribe'
                        jid='juliet@example.com'
                        subscription='none'/>
                </query>
              </iq>

🧚 METHODS 🧚

The source literally hits =head1 METHODS right here, and then there are no method entries listed under it on this page. That's the whole section. No thoughts, head empty. 😭

👑 AUTHOR 👑

Tom Molesworth <tom@perlsite.co.uk>

🎀 LICENSE 🎀

Copyright Tom Molesworth 2010-2026. Licensed under the same terms as Perl itself.

---

Cute sign-off time: this was Protoco...:Roster(3), rendered as User Contributed Perl Documentation, with perl v5.42.2 and dated 2026-02-15. Bye bestie, go parse some roster entries. 💜🦋