{
    "mode": "perldoc",
    "parameter": "man",
    "section": "-q",
    "url": "https://www.chedong.com/phpMan.php/perldoc/man/json",
    "generated": "2026-06-03T04:24:04Z",
    "sections": {
        "Found in /usr/share/perl/5.34/pod/perlfaq3.pod": {
            "content": "Can I write useful Perl programs on the command line?\nYes. Read perlrun for more information. Some examples follow. (These\nassume standard Unix shell quoting rules.)\n\n# sum first and last fields\nperl -lane 'print $F[0] + $F[-1]' *\n\n# identify text files\nperl -le 'for(@ARGV) {print if -f && -T }' *\n\n# remove (most) comments from C program\nperl -0777 -pe 's{/\\*.*?\\*/}{}gs' foo.c\n\n# make file a month younger than today, defeating reaper daemons\nperl -e '$X=24*60*60; utime(time(),time() + 30 * $X,@ARGV)' *\n\n# find first unused uid\nperl -le '$i++ while getpwuid($i); print $i'\n\n# display reasonable manpath\necho $PATH | perl -nl -072 -e '\ns![^/+]*$!man!&&-d&&!$s{$}++&&push@m,$;END{print\"@m\"}'\n\nOK, the last one was actually an Obfuscated Perl Contest entry. :-)\n",
            "subsections": []
        },
        "Found in /usr/share/perl/5.34/pod/perlfaq4.pod": {
            "content": "How can I output Roman numerals?\nGet the <http://www.cpan.org/modules/by-module/Roman> module.\n\nHow do I manipulate arrays of bits?\nUse \"pack()\" and \"unpack()\", or else \"vec()\" and the bitwise operations.\n\nFor example, you don't have to store individual bits in an array (which\nwould mean that you're wasting a lot of space). To convert an array of\nbits to a string, use \"vec()\" to set the right bits. This sets $vec to\nhave bit N set only if $ints[N] was set:\n\nmy @ints = (...); # array of bits, e.g. ( 1, 0, 0, 1, 1, 0 ... )\nmy $vec = '';\nforeach( 0 .. $#ints ) {\nvec($vec,$,1) = 1 if $ints[$];\n}\n\nThe string $vec only takes up as many bits as it needs. For instance, if\nyou had 16 entries in @ints, $vec only needs two bytes to store them\n(not counting the scalar variable overhead).\n\nHere's how, given a vector in $vec, you can get those bits into your\n@ints array:\n\nsub bitvectolist {\nmy $vec = shift;\nmy @ints;\n# Find null-byte density then select best algorithm\nif ($vec =~ tr/\\0// / length $vec > 0.95) {\nuse integer;\nmy $i;\n\n# This method is faster with mostly null-bytes\nwhile($vec =~ /[^\\0]/g ) {\n$i = -9 + 8 * pos $vec;\npush @ints, $i if vec($vec, ++$i, 1);\npush @ints, $i if vec($vec, ++$i, 1);\npush @ints, $i if vec($vec, ++$i, 1);\npush @ints, $i if vec($vec, ++$i, 1);\npush @ints, $i if vec($vec, ++$i, 1);\npush @ints, $i if vec($vec, ++$i, 1);\npush @ints, $i if vec($vec, ++$i, 1);\npush @ints, $i if vec($vec, ++$i, 1);\n}\n}\nelse {\n# This method is a fast general algorithm\nuse integer;\nmy $bits = unpack \"b*\", $vec;\npush @ints, 0 if $bits =~ s/^(\\d)// && $1;\npush @ints, pos $bits while($bits =~ /1/g);\n}\n\nreturn \\@ints;\n}\n\nThis method gets faster the more sparse the bit vector is. (Courtesy of\nTim Bunce and Winfried Koenig.)\n\nYou can make the while loop a lot shorter with this suggestion from\nBenjamin Goldberg:\n\nwhile($vec =~ /[^\\0]+/g ) {\npush @ints, grep vec($vec, $, 1), $-[0] * 8 .. $+[0] * 8;\n}\n\nOr use the CPAN module Bit::Vector:\n\nmy $vector = Bit::Vector->new($numofbits);\n$vector->IndexListStore(@ints);\nmy @ints = $vector->IndexListRead();\n\nBit::Vector provides efficient methods for bit vector, sets of small\nintegers and \"big int\" math.\n\nHere's a more extensive illustration using vec():\n\n# vec demo\nmy $vector = \"\\xff\\x0f\\xef\\xfe\";\nprint \"Ilya's string \\\\xff\\\\x0f\\\\xef\\\\xfe represents the number \",\nunpack(\"N\", $vector), \"\\n\";\nmy $isset = vec($vector, 23, 1);\nprint \"Its 23rd bit is \", $isset ? \"set\" : \"clear\", \".\\n\";\npvec($vector);\n\nsetvec(1,1,1);\nsetvec(3,1,1);\nsetvec(23,1,1);\n\nsetvec(3,1,3);\nsetvec(3,2,3);\nsetvec(3,4,3);\nsetvec(3,4,7);\nsetvec(3,8,3);\nsetvec(3,8,7);\n\nsetvec(0,32,17);\nsetvec(1,32,17);\n\nsub setvec {\nmy ($offset, $width, $value) = @;\nmy $vector = '';\nvec($vector, $offset, $width) = $value;\nprint \"offset=$offset width=$width value=$value\\n\";\npvec($vector);\n}\n\nsub pvec {\nmy $vector = shift;\nmy $bits = unpack(\"b*\", $vector);\nmy $i = 0;\nmy $BASE = 8;\n\nprint \"vector length in bytes: \", length($vector), \"\\n\";\n@bytes = unpack(\"A8\" x length($vector), $bits);\nprint \"bits are: @bytes\\n\\n\";\n}\n\nHow can I know how many entries are in a hash?\n(contributed by brian d foy)\n\nThis is very similar to \"How do I process an entire hash?\", also in\nperlfaq4, but a bit simpler in the common cases.\n\nYou can use the \"keys()\" built-in function in scalar context to find out\nhave many entries you have in a hash:\n\nmy $keycount = keys %hash; # must be scalar context!\n\nIf you want to find out how many entries have a defined value, that's a\nbit different. You have to check each value. A \"grep\" is handy:\n\nmy $definedvaluecount = grep { defined } values %hash;\n\nYou can use that same structure to count the entries any way that you\nlike. If you want the count of the keys with vowels in them, you just\ntest for that instead:\n\nmy $vowelcount = grep { /[aeiou]/ } keys %hash;\n\nThe \"grep\" in scalar context returns the count. If you want the list of\nmatching items, just use it in list context instead:\n\nmy @definedvalues = grep { defined } values %hash;\n\nThe \"keys()\" function also resets the iterator, which means that you may\nsee strange results if you use this between uses of other hash operators\nsuch as \"each()\".\n",
            "subsections": []
        },
        "Found in /usr/share/perl/5.34/pod/perlfaq5.pod": {
            "content": "How can I manipulate fixed-record-length files?\nThe most efficient way is using pack() and unpack(). This is faster than\nusing substr() when taking many, many strings. It is slower for just a\nfew.\n\nHere is a sample chunk of code to break up and put back together again\nsome fixed-format input lines, in this case from the output of a normal,\nBerkeley-style ps:\n\n# sample input line:\n#   15158 p5  T      0:00 perl /home/tchrist/scripts/now-what\nmy $PST = 'A6 A4 A7 A5 A*';\nopen my $ps, '-|', 'ps';\nprint scalar <$ps>;\nmy @fields = qw( pid tt stat time command );\nwhile (<$ps>) {\nmy %process;\n@process{@fields} = unpack($PST, $);\nfor my $field ( @fields ) {\nprint \"$field: <$process{$field}>\\n\";\n}\nprint 'line=', pack($PST, @process{@fields} ), \"\\n\";\n}\n\nWe've used a hash slice in order to easily handle the fields of each\nrow. Storing the keys in an array makes it easy to operate on them as a\ngroup or loop over them with \"for\". It also avoids polluting the program\nwith global variables and using symbolic references.\n",
            "subsections": []
        },
        "Found in /usr/share/perl/5.34/pod/perlfaq6.pod": {
            "content": "How do I efficiently match many regular expressions at once?\n(contributed by brian d foy)\n\nYou want to avoid compiling a regular expression every time you want to\nmatch it. In this example, perl must recompile the regular expression\nfor every iteration of the \"foreach\" loop since $pattern can change:\n\nmy @patterns = qw( fo+ ba[rz] );\n\nLINE: while( my $line = <> ) {\nforeach my $pattern ( @patterns ) {\nif( $line =~ m/\\b$pattern\\b/i ) {\nprint $line;\nnext LINE;\n}\n}\n}\n\nThe \"qr//\" operator compiles a regular expression, but doesn't apply it.\nWhen you use the pre-compiled version of the regex, perl does less work.\nIn this example, I inserted a \"map\" to turn each pattern into its\npre-compiled form. The rest of the script is the same, but faster:\n\nmy @patterns = map { qr/\\b$\\b/i } qw( fo+ ba[rz] );\n\nLINE: while( my $line = <> ) {\nforeach my $pattern ( @patterns ) {\nif( $line =~ m/$pattern/ ) {\nprint $line;\nnext LINE;\n}\n}\n}\n\nIn some cases, you may be able to make several patterns into a single\nregular expression. Beware of situations that require backtracking\nthough. In this example, the regex is only compiled once because $regex\ndoesn't change between iterations:\n\nmy $regex = join '|', qw( fo+ ba[rz] );\n\nwhile( my $line = <> ) {\nprint if $line =~ m/\\b(?:$regex)\\b/i;\n}\n\nThe function \"list2re\" in Data::Munge on CPAN can also be used to form a\nsingle regex that matches a list of literal strings (not regexes).\n\nFor more details on regular expression efficiency, see *Mastering\nRegular Expressions* by Jeffrey Friedl. He explains how the regular\nexpressions engine works and why some patterns are surprisingly\ninefficient. Once you understand how perl applies regular expressions,\nyou can tune them for individual situations.\n",
            "subsections": []
        },
        "Found in /usr/share/perl/5.34/pod/perlfaq8.pod": {
            "content": "How can I open a pipe both to and from a command?\nThe IPC::Open2 module (part of the standard perl distribution) is an\neasy-to-use approach that internally uses \"pipe()\", \"fork()\", and\n\"exec()\" to do the job. Make sure you read the deadlock warnings in its\ndocumentation, though (see IPC::Open2). See \"Bidirectional Communication\nwith Another Process\" in perlipc and \"Bidirectional Communication with\nYourself\" in perlipc\n\nYou may also use the IPC::Open3 module (part of the standard perl\ndistribution), but be warned that it has a different order of arguments\nfrom IPC::Open2 (see IPC::Open3).\n\nWhy can't I get the output of a command with system()?\nYou're confusing the purpose of \"system()\" and backticks (``).\n\"system()\" runs a command and returns exit status information (as a 16\nbit value: the low 7 bits are the signal the process died from, if any,\nand the high 8 bits are the actual exit value). Backticks (``) run a\ncommand and return what it sent to STDOUT.\n\nmy $exitstatus   = system(\"mail-users\");\nmy $outputstring = `ls`;\n\nHow can I capture STDERR from an external command?\nThere are three basic ways of running external commands:\n\nsystem $cmd;        # using system()\nmy $output = `$cmd`;        # using backticks (``)\nopen (my $pipefh, \"$cmd |\");    # using open()\n\nWith \"system()\", both STDOUT and STDERR will go the same place as the\nscript's STDOUT and STDERR, unless the \"system()\" command redirects\nthem. Backticks and \"open()\" read only the STDOUT of your command.\n\nYou can also use the \"open3()\" function from IPC::Open3. Benjamin\nGoldberg provides some sample code:\n\nTo capture a program's STDOUT, but discard its STDERR:\n\nuse IPC::Open3;\nuse File::Spec;\nmy $in = '';\nopen(NULL, \">\", File::Spec->devnull);\nmy $pid = open3($in, \\*PH, \">&NULL\", \"cmd\");\nwhile( <PH> ) { }\nwaitpid($pid, 0);\n\nTo capture a program's STDERR, but discard its STDOUT:\n\nuse IPC::Open3;\nuse File::Spec;\nmy $in = '';\nopen(NULL, \">\", File::Spec->devnull);\nmy $pid = open3($in, \">&NULL\", \\*PH, \"cmd\");\nwhile( <PH> ) { }\nwaitpid($pid, 0);\n\nTo capture a program's STDERR, and let its STDOUT go to our own STDERR:\n\nuse IPC::Open3;\nmy $in = '';\nmy $pid = open3($in, \">&STDERR\", \\*PH, \"cmd\");\nwhile( <PH> ) { }\nwaitpid($pid, 0);\n\nTo read both a command's STDOUT and its STDERR separately, you can\nredirect them to temp files, let the command run, then read the temp\nfiles:\n\nuse IPC::Open3;\nuse IO::File;\nmy $in = '';\nlocal *CATCHOUT = IO::File->newtmpfile;\nlocal *CATCHERR = IO::File->newtmpfile;\nmy $pid = open3($in, \">&CATCHOUT\", \">&CATCHERR\", \"cmd\");\nwaitpid($pid, 0);\nseek $, 0, 0 for \\*CATCHOUT, \\*CATCHERR;\nwhile( <CATCHOUT> ) {}\nwhile( <CATCHERR> ) {}\n\nBut there's no real need for both to be tempfiles... the following\nshould work just as well, without deadlocking:\n\nuse IPC::Open3;\nmy $in = '';\nuse IO::File;\nlocal *CATCHERR = IO::File->newtmpfile;\nmy $pid = open3($in, \\*CATCHOUT, \">&CATCHERR\", \"cmd\");\nwhile( <CATCHOUT> ) {}\nwaitpid($pid, 0);\nseek CATCHERR, 0, 0;\nwhile( <CATCHERR> ) {}\n\nAnd it'll be faster, too, since we can begin processing the program's\nstdout immediately, rather than waiting for the program to finish.\n\nWith any of these, you can change file descriptors before the call:\n\nopen(STDOUT, \">logfile\");\nsystem(\"ls\");\n\nor you can use Bourne shell file-descriptor redirection:\n\n$output = `$cmd 2>somefile`;\nopen (PIPE, \"cmd 2>somefile |\");\n\nYou can also use file-descriptor redirection to make STDERR a duplicate\nof STDOUT:\n\n$output = `$cmd 2>&1`;\nopen (PIPE, \"cmd 2>&1 |\");\n\nNote that you *cannot* simply open STDERR to be a dup of STDOUT in your\nPerl program and avoid calling the shell to do the redirection. This\ndoesn't work:\n\nopen(STDERR, \">&STDOUT\");\n$alloutput = `cmd args`;  # stderr still escapes\n\nThis fails because the \"open()\" makes STDERR go to where STDOUT was\ngoing at the time of the \"open()\". The backticks then make STDOUT go to\na string, but don't change STDERR (which still goes to the old STDOUT).\n\nNote that you *must* use Bourne shell (sh(1)) redirection syntax in\nbackticks, not csh(1)! Details on why Perl's \"system()\" and backtick and\npipe opens all use the Bourne shell are in the versus/csh.whynot article\nin the \"Far More Than You Ever Wanted To Know\" collection in\n<http://www.cpan.org/misc/olddoc/FMTEYEWTK.tgz> . To capture a command's\nSTDERR and STDOUT together:\n\n$output = `cmd 2>&1`;                       # either with backticks\n$pid = open(PH, \"cmd 2>&1 |\");              # or with an open pipe\nwhile (<PH>) { }                            #    plus a read\n\nTo capture a command's STDOUT but discard its STDERR:\n\n$output = `cmd 2>/dev/null`;                # either with backticks\n$pid = open(PH, \"cmd 2>/dev/null |\");       # or with an open pipe\nwhile (<PH>) { }                            #    plus a read\n\nTo capture a command's STDERR but discard its STDOUT:\n\n$output = `cmd 2>&1 1>/dev/null`;           # either with backticks\n$pid = open(PH, \"cmd 2>&1 1>/dev/null |\");  # or with an open pipe\nwhile (<PH>) { }                            #    plus a read\n\nTo exchange a command's STDOUT and STDERR in order to capture the STDERR\nbut leave its STDOUT to come out our old STDERR:\n\n$output = `cmd 3>&1 1>&2 2>&3 3>&-`;        # either with backticks\n$pid = open(PH, \"cmd 3>&1 1>&2 2>&3 3>&-|\");# or with an open pipe\nwhile (<PH>) { }                            #    plus a read\n\nTo read both a command's STDOUT and its STDERR separately, it's easiest\nto redirect them separately to files, and then read from those files\nwhen the program is done:\n\nsystem(\"program args 1>program.stdout 2>program.stderr\");\n\nOrdering is important in all these examples. That's because the shell\nprocesses file descriptor redirections in strictly left to right order.\n\nsystem(\"prog args 1>tmpfile 2>&1\");\nsystem(\"prog args 2>&1 1>tmpfile\");\n\nThe first command sends both standard out and standard error to the\ntemporary file. The second command sends only the old standard output\nthere, and the old standard error shows up on the old standard out.\n\nIs there a way to hide perl's command line from programs such as \"ps\"?\nFirst of all note that if you're doing this for security reasons (to\navoid people seeing passwords, for example) then you should rewrite your\nprogram so that critical information is never given as an argument.\nHiding the arguments won't make your program completely secure.\n\nTo actually alter the visible command line, you can assign to the\nvariable $0 as documented in perlvar. This won't work on all operating\nsystems, though. Daemon programs like sendmail place their state there,\nas in:\n\n$0 = \"orcus [accepting connections]\";\n",
            "subsections": []
        }
    },
    "flags": [],
    "examples": [],
    "see_also": [],
    "tldr": {
        "source": "official",
        "description": "Format and display manual pages.",
        "examples": [
            {
                "description": "Display the man page for a command",
                "command": "man {{command}}"
            },
            {
                "description": "Open the man page for a command in a browser (`=browser_name` can be omitted if `$BROWSER` is set)",
                "command": "man {{-H|--html=}}{{browser_name}} {{command}}"
            },
            {
                "description": "Display the man page for a command from section 7",
                "command": "man 7 {{command}}"
            },
            {
                "description": "List all available sections for a command",
                "command": "man {{-f|--whatis}} {{command}}"
            },
            {
                "description": "Display the path searched for manpages",
                "command": "man {{-w|--path}}"
            },
            {
                "description": "Display the location of a manpage rather than the manpage itself",
                "command": "man {{-w|--where}} {{command}}"
            },
            {
                "description": "Display the man page using a specific locale",
                "command": "man {{-L|--locale}} {{locale}} {{command}}"
            },
            {
                "description": "Search for manpages containing a search string",
                "command": "man {{-k|--apropos}} \"{{search_string}}\""
            }
        ]
    }
}