Net::Cmd(3perl)

📦
version 5.44.0 · 14 versions
, in arch rolling

✨ NAME ✨

Net::Cmd — the Network Command class, aka the glow-up backbone that FTP, SMTP and all their protocol besties inherit from 💅 (it's a 3perl page, from the Perl Programmers Reference Guide, and yes we're getting into it)

🌸 SYNOPSIS 🌸

use Net::Cmd;

@ISA = qw(Net::Cmd);

Okay bestie, look at that. Two lines. It's giving minimalist icon. 🎀

🦋 DESCRIPTION 🦋

Net::Cmd is basically a whole lil collection of methods that a sub-class of IO::Socket::INET can inherit. The way that it works? These methods implement everything you need for a command-based protocol — think FTP, think SMTP, think "I send a command, the server talks back" energy. No cap. 🔥

Now listen, real talk: if your sub-class doesn't also derive from IO::Socket::INET or something similar (like IO::Socket::IP, IO::Socket::INET6 or IO::Socket::SSL — yes those all count), then you have to provide the following methods yourself, by other means:

  • close()
  • timeout()

That's the vibe check. If you skip it, don't come crying to me. 😭

👑 Public Methods 👑

These are the ones that give you, the user, an actual user interface to the Net::Cmd object. Main character methods only. ✨

  • debug($level) — Sets the level of debug info for this object. If you don't pass $level, you just get the current state handed back to you. If you do pass it, the state changes to $level and the previous state gets returned. Different packages may implement different levels, but any non-zero value means copies of every command and every response also get yeeted to STDERR. And if $level is undef? Then the debug level gets set to the default debug level for the class. You can also call this as a static method to set/get the default debug level for a given class. 💅
  • message() — Returns the text message from the last command. In scalar context you get one single string; in list context you get each line as its own separate element. (Peep "PSEUDO RESPONSES" below for the tea. 🍓)
  • code() — Returns the 3-digit code from the last command. If a command is still pending, you get 0. (Also see "PSEUDO RESPONSES" below. 👀)
  • ok() — Returns non-zero if the last code value was greater than zero and less than 400. This holds true for most command servers. Servers where it doesn't hold? They get to override this method. Their problem, honestly.
  • status() — Returns the most significant digit of the current status code. If a command is pending, CMD_PENDING is what you get back.
  • datasend($data) — Sends data to the remote server, converting LF to CRLF. Any line starting with a . gets prefixed with another .. Pro tip: $data can be an array or a reference to an array. And heads up — the $data you pass in must be encoded by the caller to octets of whatever encoding is required, e.g. by using the Encode module's encode() function. Don't skip that step bestie.
  • dataend() — Ends the sending of data to the remote server. How? First it makes sure the data already sent ends with CRLF, then it sends .CRLF to end the transmission. Once that data is sent, dataend calls response and returns true if response returns CMD_OK. Clean. Neat. Slay. 🌈

🧚 Protected Methods 🧚

These ones are NOT for you, bestie. They're not meant to be called by the user — they're meant to be used or over-ridden by a sub-class of Net::Cmd. It's giving "staff only" door. 🙈

  • debug_print($dir, $text) — Prints debugging information. $dir denotes the direction, where true means data being sent to the server. It calls debug_text before printing to STDERR.
  • debug_text($dir, $text) — This method is called to print debugging information. $text is the text being sent. The method should return the text to be printed. This exists primarily for modules like FTP where passwords get sent but we absolutely do NOT want them showing up in the debug info. Privacy queen behavior honestly. 💜
  • command($cmd[, $args, ... ]) — Sends a command to the command server. All arguments first get joined with a space character, then CRLF is appended, and that string is what gets sent to the command server. Returns undef upon failure. 😭
  • unsupported() — Sets the status code to 580 and the response text to 'Unsupported command'. Returns zero. Short. Sweet. Rejection message delivered. 💀
  • response() — Obtains a response from the server. On success, the most significant digit of the status code is returned. On failure, timeout, etc., CMD_ERROR is returned.
  • parse_response($text) — This method is called by response as a method with one argument. It should return an array of 2 values: the 3-digit status code, and a flag which is true when this is part of a multi-line response and this line is not the last. Two values, no more, no less. 🎀
  • getline() — Retrieves one line, delimited by CRLF, from the remote server. Returns undef upon failure.
⚠️ NOTE: If you do use this method for any reason, please remember to add some debug_print calls into your method. Do not forget. I will know. 👀
  • ungetline($text) — Ungets a line of text from the server. Putting it back, like a polite lil gremlin.
  • rawdatasend($data) — Sends data to the remote server without performing any conversions. $data is a scalar. And same as with datasend(), the $data you pass in must be encoded by the caller to octets of whatever encoding is required, e.g. by using the Encode module's encode() function.
  • read_until_dot() — Reads data from the remote server until a line consisting of a single .. Any lines starting with .. will have one of the .s removed. Returns a reference to a list containing the lines, or undef upon failure. 📜
  • tied_fh() — Returns a filehandle tied to the Net::Cmd object. After issuing a command, you may read from this filehandle using read() or <>. The filehandle will return EOF when the final dot is encountered. Similarly, you may write to the filehandle to send data to the server after issuing a command that expects data to be written. Check the Net::POP3 and Net::SMTP modules for examples of this — they're the blueprint. 🫶

💀 Pseudo Responses 💀

Normally the values returned by message() and code() come straight from the remote server. But in a few circumstances, detailed below, Net::Cmd will return values that it set all by itself. You can alter this behavior by overriding DEF_REPLY_CODE() to specify a different default reply code, or by overriding one of the specific error handling methods below. Your house, your rules. 💅

  • Initial value — Before any command has executed, or if an unexpected error occurs, code() will return "421" (temporary connection failure) and message() will return undef.
  • Connection closed — If the underlying IO::Handle is closed, or if there are any read or write failures, the file handle will be forced closed, and code() will return "421" (temporary connection failure) and message() will return "[$pkg] Connection closed" (where $pkg is the name of the class that subclassed Net::Cmd). The _set_status_closed() method can be overridden to set a different message (by calling set_status()) or otherwise trap this error, if you're feeling fancy.
  • Timeout — If there's a read or write timeout, code() will return "421" (temporary connection failure) and message() will return "[$pkg] Timeout" (where $pkg is the name of the class that subclassed Net::Cmd). The _set_status_timeout() method can be overridden to set a different message (by calling set_status()) or otherwise trap this error. The clock ran out bestie, it happens to everyone. 😤

🌟 EXPORTS 🌟

The following symbols are, or can be, exported by this module:

Default Exports

CMD_INFO, CMD_OK, CMD_MORE, CMD_REJECT, CMD_ERROR, CMD_PENDING.

(These correspond to possible results of response() and status().) The lil legend of the whole module, honestly. ⭐

Optional Exports

None. Nada. Nothing. 🎀

Export Tags

None. Also nothing. 😌

🐛 KNOWN BUGS 🐛

See <https://rt.cpan.org/Dist/Display.html?Status=Active&Queue=libnet>. If you found a bug, that's the spot. Go, be the main character who reports it. 🫡

🫶 AUTHOR 🫶

Graham Barr <gbarr@pobox.com <mailto:gbarr@pobox.com>>.

Steve Hay <shay@cpan.org <mailto:shay@cpan.org>> is now maintaining libnet as of version 1.22_02. Passing the torch, iconic behavior. 💜

Copyright (C) 1995-2006 Graham Barr. All rights reserved.

Copyright (C) 2013-2016, 2020, 2022 Steve Hay. All rights reserved.

📜 LICENCE 📜

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself, i.e. under the terms of either the GNU General Public License or the Artistic License, as specified in the LICENCE file.

🎀 VERSION 🎀

Version 3.15

🗓️ DATE 🗓️

20 March 2023

📖 HISTORY 📖

See the Changes file.

and that's the whole page bestie, no notes, go forth and use Net::Cmd responsibly 💖✨ This lil slice of the Perl Programmers Reference Guide is Net::Cmd(3perl), straight out of perl v5.44.0 with a date stamp of 2026-10-17 — she's serving documentation, she's serving legacy, she's serving iconic. Periodt. 👑🌈

📦 where this page comes from