/usr/share/doc/zsh-common/html/Zsh-Modules.html is in zsh-doc 5.4.2-3ubuntu3.1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642 1643 1644 1645 1646 1647 1648 1649 1650 1651 1652 1653 1654 1655 1656 1657 1658 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 1671 1672 1673 1674 1675 1676 1677 1678 1679 1680 1681 1682 1683 1684 1685 1686 1687 1688 1689 1690 1691 1692 1693 1694 1695 1696 1697 1698 1699 1700 1701 1702 1703 1704 1705 1706 1707 1708 1709 1710 1711 1712 1713 1714 1715 1716 1717 1718 1719 1720 1721 1722 1723 1724 1725 1726 1727 1728 1729 1730 1731 1732 1733 1734 1735 1736 1737 1738 1739 1740 1741 1742 1743 1744 1745 1746 1747 1748 1749 1750 1751 1752 1753 1754 1755 1756 1757 1758 1759 1760 1761 1762 1763 1764 1765 1766 1767 1768 1769 1770 1771 1772 1773 1774 1775 1776 1777 1778 1779 1780 1781 1782 1783 1784 1785 1786 1787 1788 1789 1790 1791 1792 1793 1794 1795 1796 1797 1798 1799 1800 1801 1802 1803 1804 1805 1806 1807 1808 1809 1810 1811 1812 1813 1814 1815 1816 1817 1818 1819 1820 1821 1822 1823 1824 1825 1826 1827 1828 1829 1830 1831 1832 1833 1834 1835 1836 1837 1838 1839 1840 1841 1842 1843 1844 1845 1846 1847 1848 1849 1850 1851 1852 1853 1854 1855 1856 1857 1858 1859 1860 1861 1862 1863 1864 1865 1866 1867 1868 1869 1870 1871 1872 1873 1874 1875 1876 1877 1878 1879 1880 1881 1882 1883 1884 1885 1886 1887 1888 1889 1890 1891 1892 1893 1894 1895 1896 1897 1898 1899 1900 1901 1902 1903 1904 1905 1906 1907 1908 1909 1910 1911 1912 1913 1914 1915 1916 1917 1918 1919 1920 1921 1922 1923 1924 1925 1926 1927 1928 1929 1930 1931 1932 1933 1934 1935 1936 1937 1938 1939 1940 1941 1942 1943 1944 1945 1946 1947 1948 1949 1950 1951 1952 1953 1954 1955 1956 1957 1958 1959 1960 1961 1962 1963 1964 1965 1966 1967 1968 1969 1970 1971 1972 1973 1974 1975 1976 1977 1978 1979 1980 1981 1982 1983 1984 1985 1986 1987 1988 1989 1990 1991 1992 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 2010 2011 2012 2013 2014 2015 2016 2017 2018 2019 2020 2021 2022 2023 2024 2025 2026 2027 2028 2029 2030 2031 2032 2033 2034 2035 2036 2037 2038 2039 2040 2041 2042 2043 2044 2045 2046 2047 2048 2049 2050 2051 2052 2053 2054 2055 2056 2057 2058 2059 2060 2061 2062 2063 2064 2065 2066 2067 2068 2069 2070 2071 2072 2073 2074 2075 2076 2077 2078 2079 2080 2081 2082 2083 2084 2085 2086 2087 2088 2089 2090 2091 2092 2093 2094 2095 2096 2097 2098 2099 2100 2101 2102 2103 2104 2105 2106 2107 2108 2109 2110 2111 2112 2113 2114 2115 2116 2117 2118 2119 2120 2121 2122 2123 2124 2125 2126 2127 2128 2129 2130 2131 2132 2133 2134 2135 2136 2137 2138 2139 2140 2141 2142 2143 2144 2145 2146 2147 2148 2149 2150 2151 2152 2153 2154 2155 2156 2157 2158 2159 2160 2161 2162 2163 2164 2165 2166 2167 2168 2169 2170 2171 2172 2173 2174 2175 2176 2177 2178 2179 2180 2181 2182 2183 2184 2185 2186 2187 2188 2189 2190 2191 2192 2193 2194 2195 2196 2197 2198 2199 2200 2201 2202 2203 2204 2205 2206 2207 2208 2209 2210 2211 2212 2213 2214 2215 2216 2217 2218 2219 2220 2221 2222 2223 2224 2225 2226 2227 2228 2229 2230 2231 2232 2233 2234 2235 2236 2237 2238 2239 2240 2241 2242 2243 2244 2245 2246 2247 2248 2249 2250 2251 2252 2253 2254 2255 2256 2257 2258 2259 2260 2261 2262 2263 2264 2265 2266 2267 2268 2269 2270 2271 2272 2273 2274 2275 2276 2277 2278 2279 2280 2281 2282 2283 2284 2285 2286 2287 2288 2289 2290 2291 2292 2293 2294 2295 2296 2297 2298 2299 2300 2301 2302 2303 2304 2305 2306 2307 2308 2309 2310 2311 2312 2313 2314 2315 2316 2317 2318 2319 2320 2321 2322 2323 2324 2325 2326 2327 2328 2329 2330 2331 2332 2333 2334 2335 2336 2337 2338 2339 2340 2341 2342 2343 2344 2345 2346 2347 2348 2349 2350 2351 2352 2353 2354 2355 2356 2357 2358 2359 2360 2361 2362 2363 2364 2365 2366 2367 2368 2369 2370 2371 2372 2373 2374 2375 2376 2377 2378 2379 2380 2381 2382 2383 2384 2385 2386 2387 2388 2389 2390 2391 2392 2393 2394 2395 2396 2397 2398 2399 2400 2401 2402 2403 2404 2405 2406 2407 2408 2409 2410 2411 2412 2413 2414 2415 2416 2417 2418 2419 2420 2421 2422 2423 2424 2425 2426 2427 2428 2429 2430 2431 2432 2433 2434 2435 2436 2437 2438 2439 2440 2441 2442 2443 2444 2445 2446 2447 2448 2449 2450 2451 2452 2453 2454 2455 2456 2457 2458 2459 2460 2461 2462 2463 2464 2465 2466 2467 2468 2469 2470 2471 2472 2473 2474 2475 2476 2477 2478 2479 2480 2481 2482 2483 2484 2485 2486 2487 2488 2489 2490 2491 2492 2493 2494 2495 2496 2497 2498 2499 2500 2501 2502 2503 2504 2505 2506 2507 2508 2509 2510 2511 2512 2513 2514 2515 2516 2517 2518 2519 2520 2521 2522 2523 2524 2525 2526 2527 2528 2529 2530 2531 2532 2533 2534 2535 2536 2537 2538 2539 2540 2541 2542 2543 2544 2545 2546 2547 2548 2549 2550 2551 2552 2553 2554 2555 2556 2557 2558 2559 2560 2561 2562 2563 2564 2565 2566 2567 2568 2569 2570 2571 2572 2573 2574 2575 2576 2577 2578 2579 2580 2581 2582 2583 2584 2585 2586 2587 2588 2589 2590 2591 2592 2593 2594 2595 2596 2597 2598 2599 2600 2601 2602 2603 2604 2605 2606 2607 2608 2609 2610 2611 2612 2613 2614 2615 2616 2617 2618 2619 2620 2621 2622 2623 2624 2625 2626 2627 2628 2629 2630 2631 2632 2633 2634 2635 2636 2637 2638 2639 2640 2641 2642 2643 2644 2645 2646 2647 2648 2649 2650 2651 2652 2653 2654 2655 2656 2657 2658 2659 2660 2661 2662 2663 2664 2665 2666 2667 2668 2669 2670 2671 2672 2673 2674 2675 2676 2677 2678 2679 2680 2681 2682 2683 2684 2685 2686 2687 2688 2689 2690 2691 2692 2693 2694 2695 2696 2697 2698 2699 2700 2701 2702 2703 2704 2705 2706 2707 2708 2709 2710 2711 2712 2713 2714 2715 2716 2717 2718 2719 2720 2721 2722 2723 2724 2725 2726 2727 2728 2729 2730 2731 2732 2733 2734 2735 2736 2737 2738 2739 2740 2741 2742 2743 2744 2745 2746 2747 2748 2749 2750 2751 2752 2753 2754 2755 2756 2757 2758 2759 2760 2761 2762 2763 2764 2765 2766 2767 2768 2769 2770 2771 2772 2773 2774 2775 2776 2777 2778 2779 2780 2781 2782 2783 2784 2785 2786 2787 2788 2789 2790 2791 2792 2793 2794 2795 2796 2797 2798 2799 2800 2801 2802 2803 2804 2805 2806 2807 2808 2809 2810 2811 2812 2813 2814 2815 2816 2817 2818 2819 2820 2821 2822 2823 2824 2825 2826 2827 2828 2829 2830 2831 2832 2833 2834 2835 2836 2837 2838 2839 2840 2841 2842 2843 2844 2845 2846 2847 2848 2849 2850 2851 2852 2853 2854 2855 2856 2857 2858 2859 2860 2861 2862 2863 2864 2865 2866 2867 2868 2869 2870 2871 2872 2873 2874 2875 2876 2877 2878 2879 2880 2881 2882 2883 2884 2885 2886 2887 2888 2889 2890 2891 2892 2893 2894 2895 2896 2897 2898 2899 2900 2901 2902 2903 2904 2905 2906 2907 2908 2909 2910 2911 2912 2913 2914 2915 2916 2917 2918 2919 2920 2921 2922 2923 2924 2925 2926 2927 2928 2929 2930 2931 2932 2933 2934 2935 2936 2937 2938 2939 2940 2941 2942 2943 2944 2945 2946 2947 2948 2949 2950 2951 2952 2953 2954 2955 2956 2957 2958 2959 2960 2961 2962 2963 2964 2965 2966 2967 2968 2969 2970 2971 2972 2973 2974 2975 2976 2977 2978 2979 2980 2981 2982 2983 2984 2985 2986 2987 2988 2989 2990 2991 2992 2993 2994 2995 2996 2997 2998 2999 3000 3001 3002 3003 3004 3005 3006 3007 3008 3009 3010 3011 3012 3013 3014 3015 3016 3017 3018 3019 3020 3021 3022 3023 3024 3025 3026 3027 3028 3029 3030 3031 3032 3033 3034 3035 3036 3037 3038 3039 3040 3041 3042 3043 3044 3045 3046 3047 3048 3049 3050 3051 3052 3053 3054 3055 3056 3057 3058 3059 3060 3061 3062 3063 3064 3065 3066 3067 3068 3069 3070 3071 3072 3073 3074 3075 3076 3077 3078 3079 3080 3081 3082 3083 3084 3085 3086 3087 3088 3089 3090 3091 3092 3093 3094 3095 3096 3097 3098 3099 3100 3101 3102 3103 3104 3105 3106 3107 3108 3109 3110 3111 3112 3113 3114 3115 3116 3117 3118 3119 3120 3121 3122 3123 3124 3125 3126 3127 3128 3129 3130 3131 3132 3133 3134 3135 3136 3137 3138 3139 3140 3141 3142 3143 3144 3145 3146 3147 3148 3149 3150 3151 3152 3153 3154 3155 3156 3157 3158 3159 3160 3161 3162 3163 3164 3165 3166 3167 3168 3169 3170 3171 3172 3173 3174 3175 3176 3177 3178 3179 3180 3181 3182 3183 3184 3185 3186 3187 3188 3189 3190 3191 3192 3193 3194 3195 3196 3197 3198 3199 3200 3201 3202 3203 3204 3205 3206 3207 3208 3209 3210 3211 3212 3213 3214 3215 3216 3217 3218 3219 3220 3221 3222 3223 3224 3225 3226 3227 3228 3229 3230 3231 3232 3233 3234 3235 3236 3237 3238 3239 3240 3241 3242 3243 3244 3245 3246 3247 3248 3249 3250 3251 3252 3253 3254 3255 3256 3257 3258 3259 3260 3261 3262 3263 3264 3265 3266 3267 3268 3269 3270 3271 3272 3273 3274 3275 3276 3277 3278 3279 3280 3281 3282 3283 3284 3285 3286 3287 3288 3289 3290 3291 3292 3293 3294 3295 3296 3297 3298 3299 3300 3301 3302 3303 3304 3305 3306 3307 3308 3309 3310 3311 3312 3313 3314 3315 3316 3317 3318 3319 3320 3321 3322 3323 3324 3325 3326 3327 3328 3329 3330 3331 3332 3333 3334 3335 3336 3337 3338 3339 3340 3341 3342 3343 3344 3345 3346 3347 3348 3349 3350 3351 3352 3353 3354 3355 3356 3357 3358 3359 3360 3361 3362 3363 3364 3365 3366 3367 3368 3369 3370 3371 3372 3373 3374 3375 3376 3377 3378 3379 3380 3381 3382 3383 3384 3385 3386 3387 3388 3389 3390 3391 3392 3393 3394 3395 3396 3397 3398 3399 3400 3401 3402 3403 3404 3405 3406 3407 3408 3409 3410 3411 3412 3413 3414 3415 3416 3417 3418 3419 3420 3421 3422 3423 3424 3425 3426 3427 3428 3429 3430 3431 3432 3433 3434 3435 3436 3437 3438 3439 3440 3441 3442 3443 3444 3445 3446 3447 3448 3449 3450 3451 3452 3453 3454 3455 3456 3457 3458 3459 3460 3461 3462 3463 3464 3465 3466 3467 3468 3469 3470 3471 3472 3473 3474 3475 3476 3477 3478 3479 3480 3481 3482 3483 3484 3485 3486 3487 3488 3489 3490 3491 3492 3493 3494 3495 3496 3497 3498 3499 3500 3501 3502 3503 3504 3505 3506 3507 3508 3509 3510 3511 3512 3513 3514 3515 3516 3517 3518 3519 3520 3521 3522 3523 3524 3525 3526 3527 3528 3529 3530 3531 3532 3533 3534 3535 3536 3537 3538 3539 3540 3541 3542 3543 3544 3545 3546 3547 3548 3549 3550 3551 3552 3553 3554 3555 3556 3557 3558 3559 3560 3561 3562 3563 3564 3565 3566 3567 3568 3569 3570 3571 3572 3573 3574 3575 3576 3577 3578 3579 3580 3581 3582 3583 3584 3585 3586 3587 3588 3589 3590 3591 3592 3593 3594 3595 3596 3597 3598 3599 3600 3601 3602 3603 3604 3605 3606 3607 3608 3609 3610 3611 3612 3613 3614 3615 3616 3617 3618 3619 3620 3621 3622 3623 3624 3625 3626 3627 3628 3629 3630 3631 3632 3633 3634 3635 3636 3637 3638 3639 3640 3641 3642 3643 3644 3645 3646 3647 3648 3649 3650 3651 3652 3653 3654 3655 3656 3657 3658 3659 3660 3661 3662 3663 3664 3665 3666 3667 3668 3669 3670 3671 3672 3673 3674 3675 3676 3677 3678 3679 3680 3681 3682 3683 3684 3685 3686 3687 3688 3689 3690 3691 3692 3693 3694 3695 3696 3697 3698 3699 3700 3701 3702 3703 3704 3705 3706 3707 3708 3709 3710 3711 3712 3713 3714 3715 3716 3717 3718 3719 3720 3721 3722 3723 3724 3725 3726 3727 3728 3729 3730 3731 3732 3733 3734 3735 3736 3737 3738 3739 3740 3741 3742 3743 3744 3745 3746 3747 3748 3749 3750 3751 3752 3753 3754 3755 3756 3757 3758 3759 3760 3761 3762 3763 3764 3765 3766 3767 3768 3769 3770 3771 3772 3773 3774 3775 3776 3777 3778 3779 3780 3781 3782 3783 3784 3785 3786 3787 3788 3789 3790 3791 3792 3793 3794 3795 3796 3797 3798 3799 3800 3801 3802 3803 3804 3805 3806 3807 3808 3809 3810 3811 3812 3813 3814 3815 3816 3817 3818 3819 3820 3821 3822 3823 3824 3825 3826 3827 3828 3829 3830 3831 3832 3833 3834 3835 3836 3837 3838 3839 3840 3841 3842 3843 3844 3845 3846 3847 3848 3849 3850 3851 3852 3853 3854 3855 3856 3857 3858 3859 3860 3861 3862 3863 3864 3865 3866 3867 3868 3869 3870 3871 3872 3873 3874 3875 3876 3877 3878 3879 3880 3881 3882 3883 3884 3885 3886 3887 3888 3889 3890 3891 3892 3893 3894 3895 3896 3897 3898 3899 3900 3901 3902 3903 3904 3905 3906 3907 3908 3909 3910 3911 3912 3913 3914 3915 3916 3917 3918 3919 3920 3921 3922 3923 3924 3925 3926 3927 3928 3929 3930 3931 3932 3933 3934 3935 3936 3937 3938 3939 3940 3941 3942 3943 3944 3945 3946 3947 3948 3949 3950 3951 3952 3953 3954 3955 3956 3957 3958 3959 3960 3961 3962 3963 3964 3965 3966 3967 3968 3969 3970 3971 3972 3973 3974 3975 3976 3977 3978 3979 3980 3981 3982 3983 3984 3985 3986 3987 3988 3989 3990 3991 3992 3993 3994 3995 3996 3997 3998 3999 4000 4001 4002 4003 4004 4005 4006 4007 4008 4009 4010 4011 4012 4013 4014 4015 4016 4017 4018 4019 4020 4021 4022 4023 4024 4025 4026 4027 4028 4029 4030 4031 4032 4033 4034 4035 4036 4037 4038 4039 4040 4041 4042 4043 4044 4045 4046 4047 4048 4049 4050 4051 4052 4053 4054 4055 4056 4057 4058 4059 4060 4061 4062 4063 4064 4065 4066 4067 4068 4069 4070 4071 4072 4073 4074 4075 4076 4077 4078 4079 4080 4081 4082 4083 4084 4085 4086 4087 4088 4089 4090 4091 4092 4093 4094 4095 4096 4097 4098 4099 4100 4101 4102 4103 4104 4105 4106 4107 4108 4109 4110 4111 4112 4113 4114 4115 4116 4117 4118 4119 4120 4121 4122 4123 4124 4125 4126 4127 4128 4129 4130 4131 4132 4133 4134 4135 4136 4137 4138 4139 4140 4141 4142 4143 4144 4145 4146 4147 4148 4149 4150 4151 4152 4153 4154 4155 4156 4157 4158 4159 4160 4161 4162 4163 4164 4165 4166 4167 4168 4169 4170 4171 4172 4173 4174 4175 4176 4177 4178 4179 4180 4181 4182 4183 4184 4185 4186 4187 4188 4189 4190 4191 4192 4193 4194 4195 4196 4197 4198 4199 4200 4201 4202 4203 4204 4205 4206 4207 4208 4209 4210 4211 4212 4213 4214 4215 4216 4217 4218 4219 4220 4221 4222 4223 4224 4225 4226 4227 4228 4229 4230 4231 4232 4233 4234 4235 4236 4237 4238 4239 4240 4241 4242 4243 4244 4245 4246 4247 4248 4249 4250 4251 4252 4253 4254 4255 4256 4257 4258 4259 4260 4261 4262 4263 4264 4265 4266 4267 4268 4269 4270 4271 4272 4273 4274 4275 4276 4277 4278 4279 4280 4281 4282 4283 4284 4285 4286 4287 4288 4289 4290 4291 4292 4293 4294 4295 4296 4297 4298 4299 4300 4301 4302 4303 4304 4305 4306 4307 4308 4309 4310 4311 4312 4313 4314 4315 4316 4317 4318 4319 4320 4321 4322 4323 4324 4325 4326 4327 4328 4329 4330 4331 4332 4333 4334 4335 4336 4337 4338 4339 4340 4341 4342 4343 4344 4345 4346 4347 4348 4349 4350 4351 4352 4353 4354 4355 4356 4357 4358 4359 4360 4361 4362 4363 4364 4365 4366 4367 4368 4369 4370 4371 4372 4373 4374 4375 4376 4377 4378 4379 4380 4381 4382 4383 4384 4385 4386 4387 4388 4389 4390 4391 4392 4393 4394 4395 4396 4397 4398 4399 4400 4401 4402 4403 4404 4405 4406 4407 4408 4409 4410 4411 4412 4413 4414 4415 4416 4417 4418 4419 4420 4421 4422 4423 4424 4425 4426 4427 4428 4429 4430 4431 4432 4433 4434 4435 4436 4437 4438 4439 4440 4441 4442 4443 4444 4445 4446 4447 4448 4449 4450 4451 4452 4453 4454 4455 4456 4457 4458 4459 4460 4461 4462 4463 4464 4465 4466 4467 4468 4469 4470 4471 4472 4473 4474 4475 4476 4477 4478 4479 4480 4481 4482 4483 4484 4485 4486 4487 4488 4489 4490 4491 4492 4493 4494 4495 4496 4497 4498 4499 4500 4501 4502 4503 4504 4505 4506 4507 4508 4509 4510 4511 4512 4513 4514 4515 4516 4517 4518 4519 4520 4521 4522 4523 4524 4525 4526 4527 4528 4529 4530 4531 4532 4533 4534 4535 4536 4537 4538 4539 4540 4541 4542 4543 4544 4545 4546 4547 4548 4549 4550 4551 4552 4553 4554 4555 4556 4557 4558 4559 4560 4561 4562 4563 4564 4565 4566 4567 4568 4569 4570 4571 4572 4573 4574 4575 4576 4577 4578 4579 4580 4581 4582 4583 4584 4585 4586 4587 4588 4589 4590 4591 4592 4593 4594 4595 4596 4597 4598 4599 4600 4601 4602 4603 4604 4605 4606 4607 4608 4609 4610 4611 4612 4613 4614 4615 4616 4617 4618 4619 4620 4621 4622 4623 4624 4625 4626 4627 4628 4629 4630 4631 4632 4633 4634 4635 4636 4637 4638 4639 4640 4641 4642 4643 4644 4645 4646 4647 4648 4649 4650 4651 4652 4653 4654 4655 4656 4657 4658 4659 4660 4661 4662 4663 4664 4665 4666 4667 4668 4669 4670 4671 4672 4673 4674 4675 4676 4677 4678 4679 4680 4681 4682 4683 4684 4685 4686 4687 4688 4689 4690 4691 4692 4693 4694 4695 4696 4697 4698 4699 4700 4701 4702 4703 4704 4705 4706 4707 4708 4709 4710 4711 4712 4713 4714 4715 4716 4717 4718 4719 4720 4721 4722 4723 4724 4725 4726 4727 4728 4729 4730 4731 4732 4733 4734 4735 4736 4737 4738 4739 4740 4741 4742 4743 4744 4745 4746 4747 4748 4749 4750 4751 4752 4753 4754 4755 4756 4757 4758 4759 4760 4761 4762 4763 4764 4765 4766 4767 4768 4769 4770 4771 4772 4773 4774 4775 4776 4777 4778 4779 4780 4781 4782 4783 4784 4785 4786 4787 4788 4789 4790 4791 4792 4793 4794 4795 4796 4797 4798 4799 4800 4801 4802 4803 4804 4805 4806 4807 4808 4809 4810 4811 4812 4813 4814 4815 4816 4817 4818 4819 4820 4821 4822 4823 4824 4825 4826 4827 4828 4829 4830 4831 4832 4833 4834 4835 4836 4837 4838 4839 4840 4841 4842 4843 4844 4845 4846 4847 4848 4849 4850 4851 4852 4853 4854 4855 4856 4857 4858 4859 4860 4861 4862 4863 4864 4865 4866 4867 4868 4869 4870 4871 4872 4873 4874 4875 4876 4877 4878 4879 4880 4881 4882 4883 4884 4885 4886 4887 4888 4889 4890 4891 4892 4893 4894 4895 4896 4897 4898 4899 4900 4901 4902 4903 4904 4905 4906 4907 4908 4909 4910 4911 4912 4913 4914 4915 4916 4917 4918 4919 4920 4921 4922 4923 4924 4925 4926 4927 4928 4929 4930 4931 4932 4933 4934 4935 4936 4937 4938 4939 4940 4941 4942 4943 4944 4945 4946 4947 4948 4949 4950 4951 4952 4953 4954 4955 4956 4957 4958 4959 4960 4961 4962 4963 4964 4965 4966 4967 4968 4969 4970 4971 4972 4973 4974 4975 4976 4977 4978 4979 4980 4981 4982 4983 4984 4985 4986 4987 4988 4989 4990 4991 4992 4993 4994 4995 4996 4997 4998 4999 5000 5001 5002 5003 5004 5005 5006 5007 5008 5009 5010 5011 5012 5013 5014 5015 5016 5017 5018 5019 5020 5021 5022 5023 5024 5025 5026 5027 5028 5029 5030 5031 5032 5033 5034 5035 5036 5037 5038 5039 5040 5041 5042 5043 5044 5045 5046 5047 5048 5049 5050 5051 5052 5053 5054 5055 5056 5057 5058 5059 5060 5061 5062 5063 5064 5065 5066 5067 5068 5069 5070 5071 5072 5073 5074 5075 5076 5077 5078 5079 5080 5081 5082 5083 5084 5085 5086 5087 5088 5089 5090 5091 5092 5093 5094 5095 5096 5097 5098 5099 5100 5101 5102 5103 5104 5105 5106 5107 5108 5109 5110 5111 5112 5113 5114 5115 5116 5117 5118 5119 5120 5121 5122 5123 5124 5125 5126 5127 5128 5129 5130 5131 5132 5133 5134 5135 5136 5137 5138 5139 5140 5141 5142 5143 5144 5145 5146 5147 5148 5149 5150 5151 5152 5153 5154 5155 5156 5157 5158 5159 5160 5161 5162 5163 5164 5165 5166 5167 5168 5169 5170 5171 5172 5173 5174 5175 5176 5177 5178 5179 5180 5181 5182 5183 5184 5185 5186 5187 5188 5189 5190 5191 5192 5193 5194 5195 5196 5197 5198 5199 5200 5201 5202 5203 5204 5205 5206 5207 5208 5209 5210 5211 5212 5213 5214 5215 5216 5217 5218 5219 5220 5221 5222 5223 5224 5225 5226 5227 5228 5229 5230 5231 5232 5233 5234 5235 5236 5237 5238 5239 5240 5241 5242 5243 5244 5245 5246 5247 5248 5249 5250 5251 5252 5253 5254 5255 5256 5257 5258 5259 5260 5261 5262 5263 5264 5265 5266 5267 5268 5269 5270 5271 5272 5273 5274 5275 5276 5277 5278 5279 5280 5281 5282 5283 5284 5285 5286 5287 5288 5289 5290 5291 5292 5293 5294 5295 5296 5297 5298 5299 5300 5301 5302 5303 5304 5305 5306 5307 5308 5309 5310 5311 5312 5313 5314 5315 5316 5317 5318 5319 5320 5321 5322 5323 5324 5325 5326 5327 5328 5329 5330 5331 5332 5333 5334 5335 5336 5337 5338 5339 5340 5341 5342 5343 5344 5345 5346 5347 5348 5349 5350 5351 5352 5353 5354 5355 5356 5357 5358 5359 5360 5361 5362 5363 5364 5365 5366 5367 5368 5369 5370 5371 5372 5373 5374 5375 5376 5377 5378 5379 5380 5381 5382 5383 5384 5385 5386 5387 5388 5389 5390 5391 5392 5393 5394 5395 5396 5397 5398 5399 5400 5401 5402 5403 5404 5405 5406 5407 5408 5409 5410 5411 5412 5413 5414 5415 5416 5417 5418 5419 5420 5421 5422 5423 5424 5425 5426 5427 5428 5429 5430 5431 5432 5433 5434 5435 5436 5437 5438 5439 5440 5441 5442 5443 5444 5445 5446 5447 5448 5449 5450 5451 5452 5453 5454 5455 5456 5457 5458 5459 5460 5461 5462 5463 5464 5465 5466 5467 5468 5469 5470 5471 5472 5473 5474 5475 5476 5477 5478 5479 5480 5481 5482 5483 5484 5485 5486 5487 5488 5489 5490 5491 5492 5493 5494 5495 5496 5497 5498 5499 5500 5501 5502 5503 5504 5505 5506 5507 5508 5509 5510 5511 5512 5513 5514 5515 5516 5517 5518 5519 5520 5521 5522 5523 5524 5525 5526 5527 5528 5529 5530 5531 5532 5533 5534 5535 5536 5537 5538 5539 5540 5541 5542 5543 5544 5545 5546 5547 5548 5549 5550 5551 5552 5553 5554 5555 5556 5557 5558 5559 5560 5561 5562 5563 5564 5565 5566 5567 5568 5569 5570 5571 5572 5573 5574 5575 5576 5577 5578 5579 5580 5581 5582 5583 5584 5585 5586 5587 5588 5589 5590 5591 5592 5593 5594 5595 5596 5597 5598 5599 5600 5601 5602 5603 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Created by GNU Texinfo 6.5, http://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>22 Zsh Modules (zsh)</title>
<meta name="description" content="22 Zsh Modules (zsh)">
<meta name="keywords" content="22 Zsh Modules (zsh)">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="texi2any">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smalllisp {margin-left: 3.2em}
kbd {font-style: oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nolinebreak {white-space: nowrap}
span.roman {font-family: initial; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
ul.no-bullet {list-style: none}
-->
</style>
</head>
<body lang="en">
<a name="Zsh-Modules"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="Completion-Using-compctl.html#Completion-Using-compctl" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="Completion-Using-compctl.html#Example" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#Description-5" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Zsh-Modules-1"></a>
<h1 class="chapter">22 Zsh Modules</h1>
<p><a name="index-modules"></a>
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top"><a href="#The-zsh_002fattr-Module">22.2 The zsh/attr Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fcap-Module">22.3 The zsh/cap Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fclone-Module">22.4 The zsh/clone Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fcompctl-Module">22.5 The zsh/compctl Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fcomplete-Module">22.6 The zsh/complete Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fcomplist-Module">22.7 The zsh/complist Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fcomputil-Module">22.8 The zsh/computil Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fcurses-Module">22.9 The zsh/curses Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fdatetime-Module">22.10 The zsh/datetime Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fdb_002fgdbm-Module">22.11 The zsh/db/gdbm Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fdeltochar-Module">22.12 The zsh/deltochar Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fexample-Module">22.13 The zsh/example Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002ffiles-Module">22.14 The zsh/files Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002flanginfo-Module">22.15 The zsh/langinfo Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fmapfile-Module">22.16 The zsh/mapfile Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fmathfunc-Module">22.17 The zsh/mathfunc Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fnewuser-Module">22.18 The zsh/newuser Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fparameter-Module">22.19 The zsh/parameter Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fpcre-Module">22.20 The zsh/pcre Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fparam_002fprivate-Module">22.21 The zsh/param/private Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fregex-Module">22.22 The zsh/regex Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fsched-Module">22.23 The zsh/sched Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fnet_002fsocket-Module">22.24 The zsh/net/socket Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fstat-Module">22.25 The zsh/stat Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fsystem-Module">22.26 The zsh/system Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fnet_002ftcp-Module">22.27 The zsh/net/tcp Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002ftermcap-Module">22.28 The zsh/termcap Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fterminfo-Module">22.29 The zsh/terminfo Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fzftp-Module">22.30 The zsh/zftp Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fzle-Module">22.31 The zsh/zle Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fzleparameter-Module">22.32 The zsh/zleparameter Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fzprof-Module">22.33 The zsh/zprof Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fzpty-Module">22.34 The zsh/zpty Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fzselect-Module">22.35 The zsh/zselect Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fzutil-Module">22.36 The zsh/zutil Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
</table>
<hr>
<a name="Description-5"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Zsh-Modules" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Zsh-Modules" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fattr-Module" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h2 class="section">22.1 Description</h2>
<p>Some optional parts of zsh are in modules, separate from the core
of the shell. Each of these modules may be linked in to the
shell at build time,
or can be dynamically linked while the shell is running
if the installation supports this feature.
Modules are linked at runtime with the <tt>zmodload</tt> command,
see <a href="Shell-Builtin-Commands.html#Shell-Builtin-Commands">Shell Builtin Commands</a>.
</p>
<p>The modules that are bundled with the zsh distribution are:
</p>
<dl compact="compact">
<dt><tt>zsh/attr</tt></dt>
<dd><p>Builtins for manipulating extended attributes (xattr).
</p>
</dd>
<dt><tt>zsh/cap</tt></dt>
<dd><p>Builtins for manipulating POSIX.1e (POSIX.6) capability (privilege) sets.
</p>
</dd>
<dt><tt>zsh/clone</tt></dt>
<dd><p>A builtin that can clone a running shell onto another terminal.
</p>
</dd>
<dt><tt>zsh/compctl</tt></dt>
<dd><p>The <tt>compctl</tt> builtin for controlling completion.
</p>
</dd>
<dt><tt>zsh/complete</tt></dt>
<dd><p>The basic completion code.
</p>
</dd>
<dt><tt>zsh/complist</tt></dt>
<dd><p>Completion listing extensions.
</p>
</dd>
<dt><tt>zsh/computil</tt></dt>
<dd><p>A module with utility builtins needed for the shell function based
completion system.
</p>
</dd>
<dt><tt>zsh/curses</tt></dt>
<dd><p>curses windowing commands
</p>
</dd>
<dt><tt>zsh/datetime</tt></dt>
<dd><p>Some date/time commands and parameters.
</p>
</dd>
<dt><tt>zsh/db/gdbm</tt></dt>
<dd><p>Builtins for managing associative array parameters tied to GDBM databases.
</p>
</dd>
<dt><tt>zsh/deltochar</tt></dt>
<dd><p>A ZLE function duplicating EMACS’ <tt>zap-to-char</tt>.
</p>
</dd>
<dt><tt>zsh/example</tt></dt>
<dd><p>An example of how to write a module.
</p>
</dd>
<dt><tt>zsh/files</tt></dt>
<dd><p>Some basic file manipulation commands as builtins.
</p>
</dd>
<dt><tt>zsh/langinfo</tt></dt>
<dd><p>Interface to locale information.
</p>
</dd>
<dt><tt>zsh/mapfile</tt></dt>
<dd><p>Access to external files via a special associative array.
</p>
</dd>
<dt><tt>zsh/mathfunc</tt></dt>
<dd><p>Standard scientific functions for use in mathematical evaluations.
</p>
</dd>
<dt><tt>zsh/newuser</tt></dt>
<dd><p>Arrange for files for new users to be installed.
</p>
</dd>
<dt><tt>zsh/parameter</tt></dt>
<dd><p>Access to internal hash tables via special associative arrays.
</p>
</dd>
<dt><tt>zsh/pcre</tt></dt>
<dd><p>Interface to the PCRE library.
</p>
</dd>
<dt><tt>zsh/param/private</tt></dt>
<dd><p>Builtins for managing private-scoped parameters in function context.
</p>
</dd>
<dt><tt>zsh/regex</tt></dt>
<dd><p>Interface to the POSIX regex library.
</p>
</dd>
<dt><tt>zsh/sched</tt></dt>
<dd><p>A builtin that provides a timed execution facility within the shell.
</p>
</dd>
<dt><tt>zsh/net/socket</tt></dt>
<dd><p>Manipulation of Unix domain sockets
</p>
</dd>
<dt><tt>zsh/stat</tt></dt>
<dd><p>A builtin command interface to the <tt>stat</tt> system call.
</p>
</dd>
<dt><tt>zsh/system</tt></dt>
<dd><p>A builtin interface to various low-level system features.
</p>
</dd>
<dt><tt>zsh/net/tcp</tt></dt>
<dd><p>Manipulation of TCP sockets
</p>
</dd>
<dt><tt>zsh/termcap</tt></dt>
<dd><p>Interface to the termcap database.
</p>
</dd>
<dt><tt>zsh/terminfo</tt></dt>
<dd><p>Interface to the terminfo database.
</p>
</dd>
<dt><tt>zsh/zftp</tt></dt>
<dd><p>A builtin FTP client.
</p>
</dd>
<dt><tt>zsh/zle</tt></dt>
<dd><p>The Zsh Line Editor, including the <tt>bindkey</tt> and <tt>vared</tt> builtins.
</p>
</dd>
<dt><tt>zsh/zleparameter</tt></dt>
<dd><p>Access to internals of the Zsh Line Editor via parameters.
</p>
</dd>
<dt><tt>zsh/zprof</tt></dt>
<dd><p>A module allowing profiling for shell functions.
</p>
</dd>
<dt><tt>zsh/zpty</tt></dt>
<dd><p>A builtin for starting a command in a pseudo-terminal.
</p>
</dd>
<dt><tt>zsh/zselect</tt></dt>
<dd><p>Block and return when file descriptors are ready.
</p>
</dd>
<dt><tt>zsh/zutil</tt></dt>
<dd><p>Some utility builtins, e.g. the one for supporting configuration via
styles.
</p>
</dd>
</dl>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top"><a href="#The-zsh_002fattr-Module">22.2 The zsh/attr Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fcap-Module">22.3 The zsh/cap Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fclone-Module">22.4 The zsh/clone Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fcompctl-Module">22.5 The zsh/compctl Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fcomplete-Module">22.6 The zsh/complete Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fcomplist-Module">22.7 The zsh/complist Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fcomputil-Module">22.8 The zsh/computil Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fcurses-Module">22.9 The zsh/curses Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fdatetime-Module">22.10 The zsh/datetime Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fdb_002fgdbm-Module">22.11 The zsh/db/gdbm Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fdeltochar-Module">22.12 The zsh/deltochar Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fexample-Module">22.13 The zsh/example Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002ffiles-Module">22.14 The zsh/files Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002flanginfo-Module">22.15 The zsh/langinfo Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fmapfile-Module">22.16 The zsh/mapfile Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fmathfunc-Module">22.17 The zsh/mathfunc Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fnewuser-Module">22.18 The zsh/newuser Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fparameter-Module">22.19 The zsh/parameter Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fpcre-Module">22.20 The zsh/pcre Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fparam_002fprivate-Module">22.21 The zsh/param/private Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fregex-Module">22.22 The zsh/regex Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fsched-Module">22.23 The zsh/sched Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fnet_002fsocket-Module">22.24 The zsh/net/socket Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fstat-Module">22.25 The zsh/stat Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fsystem-Module">22.26 The zsh/system Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fnet_002ftcp-Module">22.27 The zsh/net/tcp Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002ftermcap-Module">22.28 The zsh/termcap Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fterminfo-Module">22.29 The zsh/terminfo Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fzftp-Module">22.30 The zsh/zftp Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fzle-Module">22.31 The zsh/zle Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fzleparameter-Module">22.32 The zsh/zleparameter Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fzprof-Module">22.33 The zsh/zprof Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fzpty-Module">22.34 The zsh/zpty Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fzselect-Module">22.35 The zsh/zselect Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#The-zsh_002fzutil-Module">22.36 The zsh/zutil Module</a></td><td> </td><td align="left" valign="top">
</td></tr>
</table>
<hr>
<a name="The-zsh_002fattr-Module"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Description-5" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Zsh-Modules" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fcap-Module" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="The-zsh_002fattr-Module-1"></a>
<h2 class="section">22.2 The zsh/attr Module</h2>
<p>The <tt>zsh/attr</tt> module is used for manipulating extended attributes.
The <tt>-h</tt> option causes all commands to operate on symbolic links instead
of their targets.
The builtins in this module are:
</p>
<dl compact="compact">
<dd><a name="index-zgetattr"></a>
<a name="index-extended-attributes_002c-xattr_002c-getting-from-files"></a>
</dd>
<dt><tt>zgetattr</tt> [ <tt>-h</tt> ] <var>filename</var> <var>attribute</var> [ <var>parameter</var> ]</dt>
<dd><p>Get the extended attribute <var>attribute</var> from the specified
<var>filename</var>. If the optional argument <var>parameter</var> is given, the
attribute is set on that parameter instead of being printed to stdout.
</p>
<a name="index-zsetattr"></a>
<a name="index-extended-attributes_002c-xattr_002c-setting-on-files"></a>
</dd>
<dt><tt>zsetattr</tt> [ <tt>-h</tt> ] <var>filename</var> <var>attribute</var> <var>value</var></dt>
<dd><p>Set the extended attribute <var>attribute</var> on the specified
<var>filename</var> to <var>value</var>.
</p>
<a name="index-zdelattr"></a>
<a name="index-extended-attributes_002c-xattr_002c-removing_002c-deleting"></a>
</dd>
<dt><tt>zdelattr</tt> [ <tt>-h</tt> ] <var>filename</var> <var>attribute</var></dt>
<dd><p>Remove the extended attribute <var>attribute</var> from the specified
<var>filename</var>.
</p>
<a name="index-zlistattr"></a>
<a name="index-extended-attributes_002c-xattr_002c-listing"></a>
</dd>
<dt><tt>zlistattr</tt> [ <tt>-h</tt> ] <var>filename</var> [ <var>parameter</var> ]</dt>
<dd><p>List the extended attributes currently set on the specified
<var>filename</var>. If the optional argument <var>parameter</var> is given, the
list of attributes is set on that parameter instead of being printed to stdout.
</p>
</dd>
</dl>
<p><tt>zgetattr</tt> and <tt>zlistattr</tt> allocate memory dynamically. If the
attribute or list of attributes grows between the allocation and the call
to get them, they return 2. On all other errors, 1 is returned. This
allows the calling function to check for this case and retry.
</p><hr>
<a name="The-zsh_002fcap-Module"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fattr-Module" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Zsh-Modules" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fclone-Module" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="The-zsh_002fcap-Module-1"></a>
<h2 class="section">22.3 The zsh/cap Module</h2>
<p>The <tt>zsh/cap</tt> module is used for manipulating POSIX.1e (POSIX.6) capability
sets. If the operating system does not support this interface, the
builtins defined by this module will do nothing.
The builtins in this module are:
</p>
<dl compact="compact">
<dd><a name="index-cap"></a>
<a name="index-capabilities_002c-setting"></a>
</dd>
<dt><tt>cap</tt> [ <var>capabilities</var> ]</dt>
<dd><p>Change the shell’s process capability sets to the specified <var>capabilities</var>,
otherwise display the shell’s current capabilities.
</p>
<a name="index-getcap"></a>
<a name="index-capabilities_002c-getting-from-files"></a>
</dd>
<dt><tt>getcap</tt> <var>filename</var> ...</dt>
<dd><p>This is a built-in implementation of the POSIX standard utility. It displays
the capability sets on each specified <var>filename</var>.
</p>
<a name="index-setcap"></a>
<a name="index-capabilities_002c-setting-on-files"></a>
</dd>
<dt><tt>setcap</tt> <var>capabilities</var> <var>filename</var> ...</dt>
<dd><p>This is a built-in implementation of the POSIX standard utility. It sets
the capability sets on each specified <var>filename</var> to the specified
<var>capabilities</var>.
</p>
</dd>
</dl>
<hr>
<a name="The-zsh_002fclone-Module"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fcap-Module" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Zsh-Modules" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fcompctl-Module" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="The-zsh_002fclone-Module-1"></a>
<h2 class="section">22.4 The zsh/clone Module</h2>
<p>The <tt>zsh/clone</tt> module makes available one builtin command:
</p>
<dl compact="compact">
<dd><a name="index-clone"></a>
<a name="index-shell_002c-cloning"></a>
<a name="index-cloning-the-shell"></a>
<a name="index-terminal"></a>
</dd>
<dt><tt>clone</tt> <var>tty</var></dt>
<dd><p>Creates a forked instance of the current shell, attached to the specified
<var>tty</var>. In the new shell, the <tt>PID</tt>, <tt>PPID</tt> and <tt>TTY</tt> special
parameters are changed appropriately. <tt>$!</tt> is set to zero in the new
shell, and to the new shell’s PID in the original shell.
</p>
<p>The return status of the builtin is zero in both shells if successful,
and non-zero on error.
</p>
<p>The target of <tt>clone</tt> should be an unused terminal, such as an unused virtual
console or a virtual terminal created by
</p>
<div class="example">
<pre class="example">xterm -e sh -c 'trap : INT QUIT TSTP; tty;
while :; do sleep 100000000; done'
</pre></div>
<p>Some words of explanation are warranted about this long xterm command
line: when doing clone on a pseudo-terminal, some other session
("session" meant as a unix session group, or SID) is already owning
the terminal. Hence the cloned zsh cannot acquire the pseudo-terminal
as a controlling tty. That means two things:
</p>
<ul>
<li> the job control signals will go to the sh-started-by-xterm process
group (that’s why we disable INT QUIT and TSTP with trap; otherwise
the while loop could get suspended or killed)
</li><li> the cloned shell will have job control disabled, and the job
control keys (control-C, control-\ and control-Z) will not work.
</li></ul>
<p>This does not apply when cloning to an <em>unused</em> vc.
</p>
<p>Cloning to a used (and unprepared) terminal will result in two
processes reading simultaneously from the same terminal, with
input bytes going randomly to either process.
</p>
<p><tt>clone</tt> is mostly useful as a shell built-in replacement for
openvt.
</p>
</dd>
</dl>
<hr>
<a name="The-zsh_002fcompctl-Module"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fclone-Module" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Zsh-Modules" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fcomplete-Module" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="The-zsh_002fcompctl-Module-1"></a>
<h2 class="section">22.5 The zsh/compctl Module</h2>
<p>The <tt>zsh/compctl</tt> module makes available two builtin commands. <tt>compctl</tt>,
is the old, deprecated way to control completions for ZLE. See
<a href="Completion-Using-compctl.html#Completion-Using-compctl">Completion Using compctl</a>.
The other builtin command, <tt>compcall</tt> can be used in user-defined
completion widgets, see
<a href="Completion-Widgets.html#Completion-Widgets">Completion Widgets</a>.
</p><hr>
<a name="The-zsh_002fcomplete-Module"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fcompctl-Module" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Zsh-Modules" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fcomplist-Module" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="The-zsh_002fcomplete-Module-1"></a>
<h2 class="section">22.6 The zsh/complete Module</h2>
<p>The <tt>zsh/complete</tt> module makes available several builtin commands which
can be used in user-defined completion widgets, see
<a href="Completion-Widgets.html#Completion-Widgets">Completion Widgets</a>.
</p><hr>
<a name="The-zsh_002fcomplist-Module"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fcomplete-Module" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Zsh-Modules" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#Colored-completion-listings" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="The-zsh_002fcomplist-Module-1"></a>
<h2 class="section">22.7 The zsh/complist Module</h2>
<a name="index-completion_002c-listing-1"></a>
<a name="index-completion_002c-coloured-listings"></a>
<a name="index-completion_002c-scroll-listings"></a>
<p>The <tt>zsh/complist</tt> module offers three extensions to completion listings:
the ability to highlight matches in such a list, the ability to
scroll through long lists and a different style of menu completion.
</p>
<hr>
<a name="Colored-completion-listings"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fcomplist-Module" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fcomplist-Module" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#Scrolling-in-completion-listings" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h3 class="subsection">22.7.1 Colored completion listings</h3>
<p>Whenever one of the parameters <tt>ZLS_COLORS</tt> or <tt>ZLS_COLOURS</tt> is set
and the <tt>zsh/complist</tt> module is loaded or linked into the shell,
completion lists will be colored. Note, however, that <tt>complist</tt> will
not automatically be loaded if it is not linked in: on systems with
dynamic loading, ‘<tt>zmodload zsh/complist</tt>’ is required.
</p>
<p><a name="index-ZLS_005fCOLORS"></a>
<a name="index-ZLS_005fCOLOURS"></a>
The parameters <tt>ZLS_COLORS</tt> and <tt>ZLS_COLOURS</tt> describe how matches
are highlighted. To turn on highlighting an empty value suffices, in
which case all the default values given below will be used. The format of
the value of these parameters is the same as used by the GNU version of the
<tt>ls</tt> command: a colon-separated list of specifications of the form
‘<var>name</var><tt>=</tt><var>value</var>’. The <var>name</var> may be one of the following strings,
most of which specify file types for which the <var>value</var> will be used.
The strings and their default values are:
</p>
<dl compact="compact">
<dt><tt>no 0</tt></dt>
<dd><p>for normal text (i.e. when displaying something other than a matched file)
</p>
</dd>
<dt><tt>fi 0</tt></dt>
<dd><p>for regular files
</p>
</dd>
<dt><tt>di 32</tt></dt>
<dd><p>for directories
</p>
</dd>
<dt><tt>ln 36</tt></dt>
<dd><p>for symbolic links. If this has the special value <tt>target</tt>,
symbolic links are dereferenced and the target file used to
determine the display format.
</p>
</dd>
<dt><tt>pi 31</tt></dt>
<dd><p>for named pipes (FIFOs)
</p>
</dd>
<dt><tt>so 33</tt></dt>
<dd><p>for sockets
</p>
</dd>
<dt><tt>bd 44;37</tt></dt>
<dd><p>for block devices
</p>
</dd>
<dt><tt>cd 44;37</tt></dt>
<dd><p>for character devices
</p>
</dd>
<dt><tt>or</tt> <var>none</var></dt>
<dd><p>for a symlink to nonexistent file (default is the value defined for <tt>ln</tt>)
</p>
</dd>
<dt><tt>mi</tt> <var>none</var></dt>
<dd><p>for a non-existent file (default is the value defined for <tt>fi</tt>); this code
is currently not used
</p>
</dd>
<dt><tt>su 37;41</tt></dt>
<dd><p>for files with setuid bit set
</p>
</dd>
<dt><tt>sg 30;43</tt></dt>
<dd><p>for files with setgid bit set
</p>
</dd>
<dt><tt>tw 30;42</tt></dt>
<dd><p>for world writable directories with sticky bit set
</p>
</dd>
<dt><tt>ow 34;43</tt></dt>
<dd><p>for world writable directories without sticky bit set
</p>
</dd>
<dt><tt>sa</tt> <var>none</var></dt>
<dd><p>for files with an associated suffix alias; this is only tested
after specific suffixes, as described below
</p>
</dd>
<dt><tt>st 37;44</tt></dt>
<dd><p>for directories with sticky bit set but not world writable
</p>
</dd>
<dt><tt>ex 35</tt></dt>
<dd><p>for executable files
</p>
</dd>
<dt><tt>lc \e[</tt></dt>
<dd><p>for the left code (see below)
</p>
</dd>
<dt><tt>rc m</tt></dt>
<dd><p>for the right code
</p>
</dd>
<dt><tt>tc 0</tt></dt>
<dd><p>for the character indicating the file type printed after filenames if
the <tt>LIST_TYPES</tt> option is set
</p>
</dd>
<dt><tt>sp 0</tt></dt>
<dd><p>for the spaces printed after matches to align the next column
</p>
</dd>
<dt><tt>ec</tt> <var>none</var></dt>
<dd><p>for the end code
</p>
</dd>
</dl>
<p>Apart from these strings, the <var>name</var> may also be an asterisk
(‘<tt>*</tt>’) followed by any string. The <var>value</var> given for such a
string will be used for all files whose name ends with the string.
The <var>name</var> may also be an equals sign (‘<tt>=</tt>’) followed by a
pattern; the <tt>EXTENDED_GLOB</tt> option will be turned on for evaluation
of the pattern. The <var>value</var> given for this pattern will be used for all
matches (not just filenames) whose display string are matched by
the pattern. Definitions for the form with the leading equal sign take
precedence over the values defined for file types, which in turn take
precedence over the form with the leading asterisk (file extensions).
</p>
<p>The leading-equals form also allows different parts of the displayed
strings to be colored differently. For this, the pattern has to use the
‘<tt>(#b)</tt>’ globbing flag and pairs of parentheses surrounding the
parts of the strings that are to be colored differently. In this case
the <var>value</var> may consist of more than one color code separated by
equal signs. The first code will be used for all parts for which no
explicit code is specified and the following codes will be used for
the parts matched by the sub-patterns in parentheses. For example,
the specification ‘<tt>=(#b)(?)*(?)=0=3=7</tt>’ will be used for all
matches which are at least two characters long and will use
the code ‘<tt>3</tt>’ for the first character, ‘<tt>7</tt>’ for the last
character and ‘<tt>0</tt>’ for the rest.
</p>
<p>All three forms of <var>name</var> may be preceded by a pattern in
parentheses. If this is given, the <var>value</var> will be used
only for matches in groups whose names are matched by the pattern
given in the parentheses. For example, ‘<tt>(g*)m*=43</tt>’ highlights all
matches beginning with ‘<tt>m</tt>’ in groups whose names begin with
‘<tt>g</tt>’ using the color code ‘<tt>43</tt>’. In case of the ‘<tt>lc</tt>’,
‘<tt>rc</tt>’, and ‘<tt>ec</tt>’ codes, the group pattern is ignored.
</p>
<p>Note also that all patterns are tried in the order in which they
appear in the parameter value until the first one matches which is
then used. Patterns may be matched against completions, descriptions
(possibly with spaces appended for padding), or lines consisting of a
completion followed by a description. For consistent coloring it may be
necessary to use more than one pattern or a pattern with backreferences.
</p>
<p>When printing a match, the code prints the value of <tt>lc</tt>, the value
for the file-type or the last matching specification with a ‘<tt>*</tt>’,
the value of <tt>rc</tt>, the string to display for the match itself, and
then the value of <tt>ec</tt> if that is defined or the values of <tt>lc</tt>,
<tt>no</tt>, and <tt>rc</tt> if <tt>ec</tt> is not defined.
</p>
<p>The default values are ISO 6429 (ANSI) compliant and can be used on
vt100 compatible terminals such as <tt>xterm</tt>s. On monochrome terminals
the default values will have no visible effect. The <tt>colors</tt>
function from the contribution can be used to get associative arrays
containing the codes for ANSI terminals (see
<a href="User-Contributions.html#Other-Functions">Other Functions</a>). For example, after loading <tt>colors</tt>, one could use
‘<tt>$color[red]</tt>’ to get the code for foreground color red and
‘<tt>$color[bg-green]</tt>’ for the code for background color green.
</p>
<p>If the completion system invoked by compinit is used, these
parameters should not be set directly because the system controls them
itself. Instead, the <tt>list-colors</tt> style should be used (see
<a href="Completion-System.html#Completion-System-Configuration">Completion System Configuration</a>).
</p>
<hr>
<a name="Scrolling-in-completion-listings"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Colored-completion-listings" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fcomplist-Module" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#Menu-selection" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h3 class="subsection">22.7.2 Scrolling in completion listings</h3>
<p>To enable scrolling through a completion list, the <tt>LISTPROMPT</tt>
parameter must be set. Its value will be used as the prompt; if it
is the empty string, a default prompt will be used. The value may
contain escapes of the form ‘<tt>%x</tt>’. It supports the escapes
‘<tt>%B</tt>’, ‘<tt>%b</tt>’, ‘<tt>%S</tt>’, ‘<tt>%s</tt>’, ‘<tt>%U</tt>’, ‘<tt>%u</tt>’, ‘<tt>%F</tt>’,
‘<tt>%f</tt>’, ‘<tt>%K</tt>’, ‘<tt>%k</tt>’ and
‘<tt>%{</tt><var>...</var><tt>%}</tt>’ used also in shell prompts as well as three pairs of
additional sequences: a ‘<tt>%l</tt>’ or ‘<tt>%L</tt>’ is replaced by the number
of the last line shown and the total number of lines in the form
‘<var>number</var><tt>/</tt><var>total</var>’; a ‘<tt>%m</tt>’ or ‘<tt>%M</tt>’ is replaced with
the number of the last match shown and the total number of matches; and
‘<tt>%p</tt>’ or ‘<tt>%P</tt>’ is replaced with ‘<tt>Top</tt>’, ‘<tt>Bottom</tt>’ or the
position of the first line shown in percent of the total number of
lines, respectively. In each of these cases the form with the uppercase
letter will be replaced with a string of fixed width, padded to the
right with spaces, while the lowercase form will not be padded.
</p>
<p>If the parameter <tt>LISTPROMPT</tt> is set, the completion code will not ask if
the list should be shown. Instead it immediately starts displaying the
list, stopping after the first screenful, showing the prompt at the bottom,
waiting for a keypress after temporarily switching to the <tt>listscroll</tt>
keymap. Some of the zle functions have a special meaning while scrolling
lists:
</p>
<dl compact="compact">
<dt><tt>send-break</tt></dt>
<dd><p>stops listing discarding the key pressed
</p>
</dd>
<dt><tt>accept-line</tt>, <tt>down-history</tt>, <tt>down-line-or-history</tt></dt>
<dt><tt>down-line-or-search</tt>, <tt>vi-down-line-or-history</tt></dt>
<dd><p>scrolls forward one line
</p>
</dd>
<dt><tt>complete-word</tt>, <tt>menu-complete</tt>, <tt>expand-or-complete</tt></dt>
<dt><tt>expand-or-complete-prefix</tt>, <tt>menu-complete-or-expand</tt></dt>
<dd><p>scrolls forward one screenful
</p>
</dd>
<dt><tt>accept-search</tt></dt>
<dd><p>stop listing but take no other action
</p>
</dd>
</dl>
<p>Every other character stops listing and immediately processes the key
as usual. Any key that is not bound in the <tt>listscroll</tt> keymap or
that is bound to <tt>undefined-key</tt> is looked up in the keymap
currently selected.
</p>
<p>As for the <tt>ZLS_COLORS</tt> and <tt>ZLS_COLOURS</tt> parameters,
<tt>LISTPROMPT</tt> should not be set directly when using the shell
function based completion system. Instead, the <tt>list-prompt</tt> style
should be used.
</p>
<hr>
<a name="Menu-selection"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Scrolling-in-completion-listings" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fcomplist-Module" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fcomputil-Module" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h3 class="subsection">22.7.3 Menu selection</h3>
<p><a name="index-completion_002c-selecting-by-cursor"></a>
<a name="index-MENUSELECT"></a>
<a name="index-menu_002dselect"></a>
The <tt>zsh/complist</tt> module also offers an alternative style of selecting
matches from a list, called menu selection, which can be used if the
shell is set up to return to the last prompt after showing a
completion list (see the <tt>ALWAYS_LAST_PROMPT</tt> option in
<a href="Options.html#Options">Options</a>).
</p>
<p>Menu selection can be invoked directly by
the widget <tt>menu-select</tt> defined by this module. This is a standard
ZLE widget that can be bound to a key in the usual way as described
in <a href="Zsh-Line-Editor.html#Zsh-Line-Editor">Zsh Line Editor</a>.
</p>
<p>Alternatively,
the parameter <tt>MENUSELECT</tt> can be set to an integer, which gives the
minimum number of matches that must be present before menu selection is
automatically turned on. This second method requires that menu completion
be started, either directly from a widget such as <tt>menu-complete</tt>, or due
to one of the options <tt>MENU_COMPLETE</tt> or <tt>AUTO_MENU</tt> being set. If
<tt>MENUSELECT</tt> is set, but is 0, 1 or empty, menu selection will always be
started during an ambiguous menu completion.
</p>
<p>When using the completion system based on shell functions, the
<tt>MENUSELECT</tt> parameter should not be used (like the <tt>ZLS_COLORS</tt>
and <tt>ZLS_COLOURS</tt> parameters described above). Instead, the <tt>menu</tt>
style should be used with the <tt>select=</tt><var>...</var> keyword.
</p>
<p>After menu selection is started, the matches will be listed. If there
are more matches than fit on the screen, only the first screenful is
shown. The
matches to insert into the command line can be selected from this
list. In the list one match is highlighted using the value for <tt>ma</tt>
from the <tt>ZLS_COLORS</tt> or <tt>ZLS_COLOURS</tt> parameter. The default
value for this is ‘<tt>7</tt>’ which forces the selected match to be
highlighted using standout mode on a vt100-compatible terminal. If
neither <tt>ZLS_COLORS</tt> nor <tt>ZLS_COLOURS</tt> is set, the same terminal
control sequence as for the ‘<tt>%S</tt>’ escape in prompts is used.
</p>
<p>If there are more matches than fit on the screen and the parameter
<tt>MENUPROMPT</tt> is set, its value will be shown below the matches. It
supports the same escape sequences as <tt>LISTPROMPT</tt>, but the number
of the match or line shown will be that of the one where the mark is
placed. If its value is the empty string, a default prompt will be
used.
</p>
<p>The <tt>MENUSCROLL</tt> parameter can be used to specify how the list is
scrolled. If the parameter is unset, this is done line by line, if it
is set to ‘<tt>0</tt>’ (zero), the list will scroll half the number of
lines of the screen. If the value is positive, it gives the number of
lines to scroll and if it is negative, the list will be scrolled
the number of lines of the screen minus the (absolute) value.
</p>
<p>As for the <tt>ZLS_COLORS</tt>, <tt>ZLS_COLOURS</tt> and <tt>LISTPROMPT</tt>
parameters, neither <tt>MENUPROMPT</tt> nor <tt>MENUSCROLL</tt> should be
set directly when using the shell function based completion
system. Instead, the <tt>select-prompt</tt> and <tt>select-scroll</tt> styles
should be used.
</p>
<p>The completion code sometimes decides not to show all of the matches
in the list. These hidden matches are either matches for which the
completion function which added them explicitly requested that they
not appear in the list (using the <tt>-n</tt> option of the <tt>compadd</tt>
builtin command) or they are matches which duplicate a string already
in the list (because they differ only in things like prefixes or
suffixes that are not displayed). In the list used for menu selection,
however, even these matches are shown so that it is possible to select
them. To highlight such matches the <tt>hi</tt> and <tt>du</tt> capabilities in
the <tt>ZLS_COLORS</tt> and <tt>ZLS_COLOURS</tt> parameters are supported for
hidden matches of the first and second kind, respectively.
</p>
<p>Selecting matches is done by moving the mark around using the zle movement
functions. When not all matches can be shown on the screen at the same
time, the list will scroll up and down when crossing the top or
bottom line. The following zle functions have special meaning during
menu selection. Note that the following always
perform the same task within the menu selection map and cannot be
replaced by user defined widgets, nor can the set of functions
be extended:
</p>
<dl compact="compact">
<dt><tt>accept-line</tt>, <tt>accept-search</tt></dt>
<dd><p>accept the current match and leave menu selection (but do
not cause the command line to be accepted)
</p>
</dd>
<dt><tt>send-break</tt></dt>
<dd><p>leaves menu selection and restores the previous contents of the
command line
</p>
</dd>
<dt><tt>redisplay</tt>, <tt>clear-screen</tt></dt>
<dd><p>execute their normal function without leaving menu selection
</p>
</dd>
<dt><tt>accept-and-hold</tt>, <tt>accept-and-menu-complete</tt></dt>
<dd><p>accept the currently inserted match and continue selection allowing to
select the next match to insert into the line
</p>
</dd>
<dt><tt>accept-and-infer-next-history</tt></dt>
<dd><p>accepts the current match and then tries completion with
menu selection again; in the case of files this allows one to select
a directory and immediately attempt to complete files in it; if there
are no matches, a message is shown and one can use <tt>undo</tt> to go back
to completion on the previous level, every other key leaves menu
selection (including the other zle functions which are otherwise
special during menu selection)
</p>
</dd>
<dt><tt>undo</tt></dt>
<dd><p>removes matches inserted during the menu selection by one of the three
functions before
</p>
</dd>
<dt><tt>down-history</tt>, <tt>down-line-or-history</tt></dt>
<dt><tt>vi-down-line-or-history</tt>, <tt>down-line-or-search</tt></dt>
<dd><p>moves the mark one line down
</p>
</dd>
<dt><tt>up-history</tt>, <tt>up-line-or-history</tt></dt>
<dt><tt>vi-up-line-or-history</tt>, <tt>up-line-or-search</tt></dt>
<dd><p>moves the mark one line up
</p>
</dd>
<dt><tt>forward-char</tt>, <tt>vi-forward-char</tt></dt>
<dd><p>moves the mark one column right
</p>
</dd>
<dt><tt>backward-char</tt>, <tt>vi-backward-char</tt></dt>
<dd><p>moves the mark one column left
</p>
</dd>
<dt><tt>forward-word</tt>, <tt>vi-forward-word</tt></dt>
<dt><tt>vi-forward-word-end</tt>, <tt>emacs-forward-word</tt></dt>
<dd><p>moves the mark one screenful down
</p>
</dd>
<dt><tt>backward-word</tt>, <tt>vi-backward-word</tt>, <tt>emacs-backward-word</tt></dt>
<dd><p>moves the mark one screenful up
</p>
</dd>
<dt><tt>vi-forward-blank-word</tt>, <tt>vi-forward-blank-word-end</tt></dt>
<dd><p>moves the mark to the first line of the next group of matches
</p>
</dd>
<dt><tt>vi-backward-blank-word</tt></dt>
<dd><p>moves the mark to the last line of the previous group of matches
</p>
</dd>
<dt><tt>beginning-of-history</tt></dt>
<dd><p>moves the mark to the first line
</p>
</dd>
<dt><tt>end-of-history</tt></dt>
<dd><p>moves the mark to the last line
</p>
</dd>
<dt><tt>beginning-of-buffer-or-history</tt>, <tt>beginning-of-line</tt></dt>
<dt><tt>beginning-of-line-hist</tt>, <tt>vi-beginning-of-line</tt></dt>
<dd><p>moves the mark to the leftmost column
</p>
</dd>
<dt><tt>end-of-buffer-or-history</tt>, <tt>end-of-line</tt></dt>
<dt><tt>end-of-line-hist</tt>, <tt>vi-end-of-line</tt></dt>
<dd><p>moves the mark to the rightmost column
</p>
</dd>
<dt><tt>complete-word</tt>, <tt>menu-complete</tt>, <tt>expand-or-complete</tt></dt>
<dt><tt>expand-or-complete-prefix</tt>, <tt>menu-expand-or-complete</tt></dt>
<dd><p>moves the mark to the next match
</p>
</dd>
<dt><tt>reverse-menu-complete</tt></dt>
<dd><p>moves the mark to the previous match
</p>
</dd>
<dt><tt>vi-insert</tt></dt>
<dd><p>this toggles between normal and interactive mode; in interactive mode
the keys bound to <tt>self-insert</tt> and <tt>self-insert-unmeta</tt> insert
into the command line as in normal editing mode but without leaving
menu selection; after each character completion is tried again and the
list changes to contain only the new matches; the completion widgets
make the longest unambiguous string be inserted in the command line
and <tt>undo</tt> and <tt>backward-delete-char</tt> go back to the previous set
of matches
</p>
</dd>
<dt><tt>history-incremental-search-forward</tt></dt>
<dt><tt>history-incremental-search-backward</tt></dt>
<dd><p>this starts incremental searches in the list of completions displayed;
in this mode, <tt>accept-line</tt> only leaves incremental search, going
back to the normal menu selection mode
</p>
</dd>
</dl>
<p>All movement functions wrap around at the edges; any other zle function not
listed leaves menu selection and executes that function. It is possible to
make widgets in the above list do the same by using the form of the widget
with a ‘<tt>.</tt>’ in front. For example, the widget ‘<tt>.accept-line</tt>’ has
the effect of leaving menu selection and accepting the entire command line.
</p>
<p>During this selection the widget uses the keymap <tt>menuselect</tt>. Any
key that is not defined in this keymap or that is bound to
<tt>undefined-key</tt> is looked up in the keymap currently selected. This
is used to ensure that the most important keys used during selection
(namely the cursor keys, return, and TAB) have sensible defaults. However,
keys in the <tt>menuselect</tt> keymap can be modified directly using the
<tt>bindkey</tt> builtin command (see
<a href="#The-zsh_002fzle-Module">The zsh/zle Module</a>). For example, to make the return key leave menu selection without
accepting the match currently selected one could call
</p>
<div class="example">
<pre class="example">bindkey -M menuselect '^M' send-break
</pre></div>
<p>after loading the <tt>zsh/complist</tt> module.
</p><hr>
<a name="The-zsh_002fcomputil-Module"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Menu-selection" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Zsh-Modules" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fcurses-Module" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="The-zsh_002fcomputil-Module-1"></a>
<h2 class="section">22.8 The zsh/computil Module</h2>
<a name="index-completion_002c-utility"></a>
<p>The <tt>zsh/computil</tt> module adds several builtin commands that are used by
some of the completion functions in the completion system based on shell
functions (see
<a href="Completion-System.html#Completion-System">Completion System</a>
). Except for <tt>compquote</tt> these builtin commands are very
specialised and thus not very interesting when writing your own
completion functions. In summary, these builtin commands are:
</p>
<dl compact="compact">
<dd><a name="index-comparguments"></a>
</dd>
<dt><tt>comparguments</tt></dt>
<dd><p>This is used by the <tt>_arguments</tt> function to do the argument and
command line parsing. Like <tt>compdescribe</tt> it has an option <tt>-i</tt> to
do the parsing and initialize some internal state and various options
to access the state information to decide what should be completed.
</p>
<a name="index-compdescribe"></a>
</dd>
<dt><tt>compdescribe</tt></dt>
<dd><p>This is used by the <tt>_describe</tt> function to build the displays for
the matches and to get the strings to add as matches with their
options. On the first call one of the options <tt>-i</tt> or <tt>-I</tt> should be
supplied as the first argument. In the first case, display strings without
the descriptions will be generated, in the second case, the string used to
separate the matches from their descriptions must be given as the
second argument and the descriptions (if any) will be shown. All other
arguments are like the definition arguments to <tt>_describe</tt> itself.
</p>
<p>Once <tt>compdescribe</tt> has been called with either the <tt>-i</tt> or the
<tt>-I</tt> option, it can be repeatedly called with the <tt>-g</tt> option and
the names of four parameters as its arguments. This will step through
the different sets of matches and store the value of <tt>compstate[list]</tt>
in the first scalar, the options for <tt>compadd</tt> in the second array,
the matches in the third array, and the strings to be displayed in the
completion listing in the fourth array. The arrays may then be directly
given to <tt>compadd</tt> to register the matches with the completion code.
</p>
<a name="index-compfiles"></a>
</dd>
<dt><tt>compfiles</tt></dt>
<dd><p>Used by the <tt>_path_files</tt> function to optimize complex recursive
filename generation (globbing). It does three things. With the
<tt>-p</tt> and <tt>-P</tt> options it builds the glob patterns to use,
including the paths already handled and trying to optimize the
patterns with respect to the prefix and suffix from the line and the
match specification currently used. The <tt>-i</tt> option does the
directory tests for the <tt>ignore-parents</tt> style and the <tt>-r</tt> option
tests if a component for some of the matches are equal to the string
on the line and removes all other matches if that is true.
</p>
<a name="index-compgroups"></a>
</dd>
<dt><tt>compgroups</tt></dt>
<dd><p>Used by the <tt>_tags</tt> function to implement the internals of the
<tt>group-order</tt> style. This only takes its arguments as names of
completion groups and creates the groups for it (all six types: sorted
and unsorted, both without removing duplicates, with removing all
duplicates and with removing consecutive duplicates).
</p>
<a name="index-compquote"></a>
</dd>
<dt><tt>compquote</tt> [ <tt>-p</tt> ] <var>names</var> ...</dt>
<dd><p>There may be reasons to write completion functions that have to add
the matches using the <tt>-Q</tt> option to <tt>compadd</tt> and perform quoting
themselves. Instead of interpreting the first character of the
<tt>all_quotes</tt> key of the <tt>compstate</tt> special association and using
the <tt>q</tt> flag for parameter expansions, one can use this builtin
command. The arguments are the names of scalar or array parameters
and the values of these parameters are quoted as needed for the
innermost quoting level. If the <tt>-p</tt> option is given, quoting is
done as if there is some prefix before the values of the parameters,
so that a leading equal sign will not be quoted.
</p>
<p>The return status is non-zero in case of an error and zero otherwise.
</p>
<a name="index-comptags"></a>
<a name="index-comptry"></a>
</dd>
<dt><tt>comptags</tt></dt>
<dt><tt>comptry</tt></dt>
<dd><p>These implement the internals of the tags mechanism.
</p>
<a name="index-compvalues"></a>
</dd>
<dt><tt>compvalues</tt></dt>
<dd><p>Like <tt>comparguments</tt>, but for the <tt>_values</tt> function.
</p>
</dd>
</dl>
<hr>
<a name="The-zsh_002fcurses-Module"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fcomputil-Module" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Zsh-Modules" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#Builtin" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="The-zsh_002fcurses-Module-1"></a>
<h2 class="section">22.9 The zsh/curses Module</h2>
<p>The <tt>zsh/curses</tt> module makes available one builtin command and
various parameters.
</p>
<hr>
<a name="Builtin"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fcurses-Module" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fcurses-Module" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#Parameters-2" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h3 class="subsection">22.9.1 Builtin</h3>
<dl compact="compact">
<dd><a name="index-zcurses"></a>
<a name="index-windows_002c-curses"></a>
</dd>
<dt><tt>zcurses</tt> <tt>init</tt></dt>
<dt><tt>zcurses</tt> <tt>end</tt></dt>
<dt><tt>zcurses</tt> <tt>addwin</tt> <var>targetwin</var> <var>nlines</var> <var>ncols</var> <var>begin_y</var> <var>begin_x</var> [ <var>parentwin</var> ]</dt>
<dt><tt>zcurses</tt> <tt>delwin</tt> <var>targetwin</var></dt>
<dt><tt>zcurses</tt> <tt>refresh</tt> [ <var>targetwin</var> ... ]</dt>
<dt><tt>zcurses</tt> <tt>touch</tt> <var>targetwin</var> ...</dt>
<dt><tt>zcurses</tt> <tt>move</tt> <var>targetwin</var> <var>new_y</var> <var>new_x</var></dt>
<dt><tt>zcurses</tt> <tt>clear</tt> <var>targetwin</var> [ <tt>redraw</tt> | <tt>eol</tt> | <tt>bot</tt> ]</dt>
<dt><tt>zcurses</tt> <tt>position</tt> <var>targetwin</var> <var>array</var></dt>
<dt><tt>zcurses</tt> <tt>char</tt> <var>targetwin</var> <var>character</var></dt>
<dt><tt>zcurses</tt> <tt>string</tt> <var>targetwin</var> <var>string</var></dt>
<dt><tt>zcurses</tt> <tt>border</tt> <var>targetwin</var> <var>border</var></dt>
<dt><tt>zcurses</tt> <tt>attr</tt> <var>targetwin</var> [ [<tt>+</tt>|<tt>-</tt>]<var>attribute</var> | <var>fg_col</var><tt>/</tt><var>bg_col</var> ] [...]</dt>
<dt><tt>zcurses</tt> <tt>bg</tt> <var>targetwin</var> [ [<tt>+</tt>|<tt>-</tt>]<var>attribute</var> | <var>fg_col</var><tt>/</tt><var>bg_col</var> | <tt>@</tt><var>char</var> ] [...]</dt>
<dt><tt>zcurses</tt> <tt>scroll</tt> <var>targetwin</var> [ <tt>on</tt> | <tt>off</tt> | [<tt>+</tt>|<tt>-</tt>]<var>lines</var> ]</dt>
<dt><tt>zcurses</tt> <tt>input</tt> <var>targetwin</var> [ <var>param</var> [ <var>kparam</var> [ <var>mparam</var> ] ] ]</dt>
<dt><tt>zcurses</tt> <tt>mouse</tt> [ <tt>delay</tt> <var>num</var> | [<tt>+</tt>|<tt>-</tt>]<tt>motion</tt> ]</dt>
<dt><tt>zcurses</tt> <tt>timeout</tt> <var>targetwin</var> <var>intval</var></dt>
<dt><tt>zcurses</tt> <tt>querychar</tt> <var>targetwin</var> [ <var>param</var> ]</dt>
<dt><tt>zcurses</tt> <tt>resize</tt> <var>height</var> <var>width</var> [ <tt>endwin</tt> | <tt>nosave</tt> | <tt>endwin_nosave</tt> ]</dt>
<dd><p>Manipulate curses windows. All uses of this command should be
bracketed by ‘<tt>zcurses init</tt>’ to initialise use of curses, and
‘<tt>zcurses end</tt>’ to end it; omitting ‘<tt>zcurses end</tt>’ can cause
the terminal to be in an unwanted state.
</p>
<p>The subcommand <tt>addwin</tt> creates a window with <var>nlines</var> lines and
<var>ncols</var> columns. Its upper left corner will be placed at row
<var>begin_y</var> and column
<var>begin_x</var> of the screen. <var>targetwin</var> is a string and refers
to the name of a window that is not currently assigned. Note
in particular the curses convention that vertical values appear
before horizontal values.
</p>
<p>If <tt>addwin</tt> is given an existing window as the final argument, the new
window is created as a subwindow of <var>parentwin</var>. This differs from an
ordinary new window in that the memory of the window contents is shared
with the parent’s memory. Subwindows must be deleted before their parent.
Note that the coordinates of subwindows are relative to the screen, not
the parent, as with other windows.
</p>
<p>Use the subcommand <tt>delwin</tt> to delete a window created with
<tt>addwin</tt>. Note that <tt>end</tt> does <em>not</em> implicitly delete windows,
and that <tt>delwin</tt> does not erase the screen image of the window.
</p>
<p>The window corresponding to the full visible screen is called
<tt>stdscr</tt>; it always exists after ‘<tt>zcurses init</tt>’ and cannot
be delete with <tt>delwin</tt>.
</p>
<p>The subcommand <tt>refresh</tt> will refresh window <var>targetwin</var>; this is
necessary to make any pending changes (such as characters you have
prepared for output with <tt>char</tt>) visible on the screen. <tt>refresh</tt>
without an argument causes the screen to be cleared and redrawn.
If multiple windows are given, the screen is updated once at the end.
</p>
<p>The subcommand <tt>touch</tt> marks the <var>targetwin</var>s listed as changed.
This is necessary before <tt>refresh</tt>ing windows if a window that
was in front of another window (which may be <tt>stdscr</tt>) is deleted.
</p>
<p>The subcommand <tt>move</tt> moves the cursor position in <var>targetwin</var> to
new coordinates <var>new_y</var> and <var>new_x</var>. Note that the
subcommand <tt>string</tt> (but not the subcommand <tt>char</tt>) advances the
cursor position over the characters added.
</p>
<p>The subcommand <tt>clear</tt> erases the contents of <var>targetwin</var>. One
(and no more than one) of three options may be specified. With the
option <tt>redraw</tt>, in addition the next <tt>refresh</tt> of <var>targetwin</var>
will cause the screen to be cleared and repainted. With the option
<tt>eol</tt>, <var>targetwin</var> is only cleared to the end of the current cursor
line. With the option
<tt>bot</tt>, <var>targetwin</var> is cleared to the end of the window, i.e
everything to the right and below the cursor is cleared.
</p>
<p>The subcommand <tt>position</tt> writes various positions associated with
<var>targetwin</var> into the array named <var>array</var>.
These are, in order:
</p><dl compact="compact">
<dt>-</dt>
<dd><p>The y and x coordinates of the cursor relative to the top left
of <var>targetwin</var>
</p></dd>
<dt>-</dt>
<dd><p>The y and x coordinates of the top left of <var>targetwin</var> on the
screen
</p></dd>
<dt>-</dt>
<dd><p>The size of <var>targetwin</var> in y and x dimensions.
</p></dd>
</dl>
<p>Outputting characters and strings are achieved by <tt>char</tt> and <tt>string</tt>
respectively.
</p>
<p>To draw a border around window <var>targetwin</var>, use <tt>border</tt>. Note
that the border is not subsequently handled specially: in other words,
the border is simply a set of characters output at the edge of the
window. Hence it can be overwritten, can scroll off the window, etc.
</p>
<p>The subcommand <tt>attr</tt> will set <var>targetwin</var>’s attributes or
foreground/background color pair for any successive character output.
Each <var>attribute</var> given on the line may be prepended by a <tt>+</tt> to set
or a <tt>-</tt> to unset that attribute; <tt>+</tt> is assumed if absent. The
attributes supported are <tt>blink</tt>, <tt>bold</tt>, <tt>dim</tt>, <tt>reverse</tt>,
<tt>standout</tt>, and <tt>underline</tt>.
</p>
<p>Each <var>fg_col</var><tt>/</tt><var>bg_col</var> attribute (to be read as
‘<var>fg_col</var> on <var>bg_col</var>’) sets the foreground and background color
for character output. The color <tt>default</tt> is sometimes available
(in particular if the library is ncurses), specifying the foreground
or background color with which the terminal started. The color pair
<tt>default/default</tt> is always available. To use more than the 8 named
colors (red, green, etc.) construct the <var>fg_col</var><tt>/</tt><var>bg_col</var>
pairs where <var>fg_col</var> and <var>bg_col</var> are decimal integers, e.g
<tt>128/200</tt>. The maximum color value is 254 if the terminal supports
256 colors.
</p>
<p><tt>bg</tt> overrides the color and other attributes of all characters in the
window. Its usual use is to set the background initially, but it will
overwrite the attributes of any characters at the time when it is called.
In addition to the arguments allowed with <tt>attr</tt>, an argument <tt>@</tt><var>char</var>
specifies a character to be shown in otherwise blank areas of the window.
Owing to limitations of curses this cannot be a multibyte character
(use of ASCII characters only is recommended). As the specified set
of attributes override the existing background, turning attributes
off in the arguments is not useful, though this does not cause an error.
</p>
<p>The subcommand <tt>scroll</tt> can be used with <tt>on</tt> or <tt>off</tt> to enabled
or disable scrolling of a window when the cursor would otherwise move
below the window due to typing or output. It can also be used with a
positive or negative integer to scroll the window up or down the given
number of lines without changing the current cursor position (which
therefore appears to move in the opposite direction relative to the
window). In the second case, if scrolling is <tt>off</tt> it is temporarily
turned <tt>on</tt> to allow the window to be scrolled.
</p>
<p>The subcommand <tt>input</tt> reads a single character from the window
without echoing it back. If <var>param</var> is supplied the character is
assigned to the parameter <var>param</var>, else it is assigned to the
parameter <tt>REPLY</tt>.
</p>
<p>If both <var>param</var> and <var>kparam</var> are supplied, the key is read in
‘keypad’ mode. In this mode special keys such as function keys and
arrow keys return the name of the key in the parameter <var>kparam</var>. The
key names are the macros defined in the <tt>curses.h</tt> or <tt>ncurses.h</tt>
with the prefix ‘<tt>KEY_</tt>’ removed; see also the description of the
parameter <tt>zcurses_keycodes</tt> below. Other keys cause a value to be
set in <var>param</var> as before. On a successful return only one of
<var>param</var> or <var>kparam</var> contains a non-empty string; the other is set
to an empty string.
</p>
<p>If <var>mparam</var> is also supplied, <tt>input</tt> attempts to handle mouse
input. This is only available with the ncurses library; mouse handling
can be detected by checking for the exit status of ‘<tt>zcurses mouse</tt>’ with
no arguments. If a mouse
button is clicked (or double- or triple-clicked, or pressed or released with
a configurable delay from being clicked) then <tt>kparam</tt> is set to the string
<tt>MOUSE</tt>, and <var>mparam</var> is set to an array consisting of the
following elements:
</p><dl compact="compact">
<dt>-</dt>
<dd><p>An identifier to discriminate different input devices; this
is only rarely useful.
</p></dd>
<dt>-</dt>
<dd><p>The x, y and z coordinates of the mouse click relative to
the full screen, as three elements in that order (i.e. the y coordinate
is, unusually, after the x coordinate). The z coordinate is only
available for a few unusual input devices and is otherwise set to zero.
</p></dd>
<dt>-</dt>
<dd><p>Any events that occurred as separate items; usually
there will be just one. An event consists of <tt>PRESSED</tt>, <tt>RELEASED</tt>,
<tt>CLICKED</tt>, <tt>DOUBLE_CLICKED</tt> or <tt>TRIPLE_CLICKED</tt> followed
immediately (in the same element) by the number of the button.
</p></dd>
<dt>-</dt>
<dd><p>If the shift key was pressed, the string <tt>SHIFT</tt>.
</p></dd>
<dt>-</dt>
<dd><p>If the control key was pressed, the string <tt>CTRL</tt>.
</p></dd>
<dt>-</dt>
<dd><p>If the alt key was pressed, the string <tt>ALT</tt>.
</p></dd>
</dl>
<p>Not all mouse events may be passed through to the terminal window;
most terminal emulators handle some mouse events themselves. Note
that the ncurses manual implies that using input both with and
without mouse handling may cause the mouse cursor to appear and
disappear.
</p>
<p>The subcommand <tt>mouse</tt> can be used to configure the use of the mouse.
There is no window argument; mouse options are global.
‘<tt>zcurses mouse</tt>’ with no arguments returns status 0 if mouse handling
is possible, else status 1. Otherwise, the possible arguments (which
may be combined on the same command line) are as follows.
<tt>delay</tt> <var>num</var> sets the maximum delay in milliseconds between press and
release events to be considered as a click; the value 0 disables click
resolution, and the default is one sixth of a second. <tt>motion</tt> proceeded
by an optional ‘<tt>+</tt>’ (the default) or <tt>-</tt> turns on or off
reporting of mouse motion in addition to clicks, presses and releases,
which are always reported. However, it appears reports for mouse
motion are not currently implemented.
</p>
<p>The subcommand <tt>timeout</tt> specifies a timeout value for input from
<var>targetwin</var>. If <var>intval</var> is negative, ‘<tt>zcurses input</tt>’ waits
indefinitely for a character to be typed; this is the default. If
<var>intval</var> is zero, ‘<tt>zcurses input</tt>’ returns immediately; if there
is typeahead it is returned, else no input is done and status 1 is
returned. If <var>intval</var> is positive, ‘<tt>zcurses input</tt>’ waits
<var>intval</var> milliseconds for input and if there is none at the end of
that period returns status 1.
</p>
<p>The subcommand <tt>querychar</tt> queries the character at the current cursor
position. The return values are stored in the array named <var>param</var> if
supplied, else in the array <tt>reply</tt>. The first value is the character
(which may be a multibyte character if the system supports them); the
second is the color pair in the usual <var>fg_col</var><tt>/</tt><var>bg_col</var>
notation, or <tt>0</tt> if color is not supported. Any attributes other than
color that apply to the character, as set with the subcommand <tt>attr</tt>,
appear as additional elements.
</p>
<p>The subcommand <tt>resize</tt> resizes <tt>stdscr</tt> and all windows to given
dimensions (windows that stick out from the new dimensions are resized
down). The underlying curses extension (<tt>resize_term call</tt>) can be
unavailable. To verify, zeroes can be used for <var>height</var> and
<var>width</var>. If the result of the subcommand is <tt>0</tt>, resize_term is
available (<tt>2</tt> otherwise). Tests show that resizing can be normally
accomplished by calling <tt>zcurses end</tt> and <tt>zcurses refresh</tt>. The
<tt>resize</tt> subcommand is provided for versatility. Multiple system
configurations have been checked and <tt>zcurses end</tt> and <tt>zcurses
refresh</tt> are still needed for correct terminal state after resize. To
invoke them with <tt>resize</tt>, use <var>endwin</var> argument. Using
<var>nosave</var> argument will cause new terminal state to not be saved
internally by <tt>zcurses</tt>. This is also provided for versatility and
should normally be not needed.
</p>
</dd>
</dl>
<hr>
<a name="Parameters-2"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Builtin" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fcurses-Module" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fdatetime-Module" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h3 class="subsection">22.9.2 Parameters</h3>
<dl compact="compact">
<dd><a name="index-ZCURSES_005fCOLORS"></a>
</dd>
<dt><tt>ZCURSES_COLORS</tt></dt>
<dd><p>Readonly integer. The maximum number of colors the terminal
supports. This value is initialised by the curses library and is not
available until the first time <tt>zcurses init</tt> is run.
</p>
<a name="index-ZCURSES_005fCOLOR_005fPAIRS"></a>
</dd>
<dt><tt>ZCURSES_COLOR_PAIRS</tt></dt>
<dd><p>Readonly integer. The maximum number of color pairs
<var>fg_col</var><tt>/</tt><var>bg_col</var> that may be defined in ‘<tt>zcurses attr</tt>’
commands; note this limit applies to all color pairs that have been
used whether or not they are currently active. This value is initialised
by the curses library and is not available until the first time <tt>zcurses
init</tt> is run.
</p>
<a name="index-zcurses_005fattrs"></a>
</dd>
<dt><tt>zcurses_attrs</tt></dt>
<dd><p>Readonly array. The attributes supported by <tt>zsh/curses</tt>; available
as soon as the module is loaded.
</p>
<a name="index-zcurses_005fcolors"></a>
</dd>
<dt><tt>zcurses_colors</tt></dt>
<dd><p>Readonly array. The colors supported by <tt>zsh/curses</tt>; available
as soon as the module is loaded.
</p>
<a name="index-zcurses_005fkeycodes"></a>
</dd>
<dt><tt>zcurses_keycodes</tt></dt>
<dd><p>Readonly array. The values that may be returned in the second
parameter supplied to ‘<tt>zcurses input</tt>’ in the order in which they
are defined internally by curses. Not all function keys
are listed, only <tt>F0</tt>; curses reserves space for <tt>F0</tt> up to <tt>F63</tt>.
</p>
<a name="index-zcurses_005fwindows"></a>
</dd>
<dt><tt>zcurses_windows</tt></dt>
<dd><p>Readonly array. The current list of windows, i.e. all windows that
have been created with ‘<tt>zcurses addwin</tt>’ and not removed with
‘<tt>zcurses delwin</tt>’.
</p>
</dd>
</dl>
<hr>
<a name="The-zsh_002fdatetime-Module"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Parameters-2" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Zsh-Modules" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fdb_002fgdbm-Module" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="The-zsh_002fdatetime-Module-1"></a>
<h2 class="section">22.10 The zsh/datetime Module</h2>
<p>The <tt>zsh/datetime</tt> module makes available one builtin command:
</p>
<dl compact="compact">
<dd><a name="index-strftime"></a>
<a name="index-date-string_002c-printing"></a>
</dd>
<dt><tt>strftime</tt> [ <tt>-s</tt> <var>scalar</var> ] <var>format</var> <var>epochtime</var></dt>
<dt><tt>strftime</tt> <tt>-r</tt> [ <tt>-q</tt> ] [ <tt>-s</tt> <var>scalar</var> ] <var>format</var> <var>timestring</var></dt>
<dd><p>Output the date denoted by <var>epochtime</var> in the <var>format</var> specified.
See man page strftime(3) for details. The zsh extensions described in
<a href="Prompt-Expansion.html#Prompt-Expansion">Prompt Expansion</a> are also available.
</p>
<dl compact="compact">
<dt><tt>-q</tt></dt>
<dd><p>Run quietly; suppress printing of all error messages described below.
Errors for invalid <var>epochtime</var> values are always printed.
</p>
</dd>
<dt><tt>-r</tt></dt>
<dd><p>With the option <tt>-r</tt> (reverse), use <var>format</var> to parse the input
string <var>timestring</var> and output the number of seconds since the epoch at
which the time occurred. The parsing is implemented by the system
function <tt>strptime</tt>; see man page strptime(3). This means that zsh
format extensions are not available, but for reverse lookup they are not
required.
</p>
<p>In most implementations of <tt>strftime</tt> any timezone in the
<var>timestring</var> is ignored and the local timezone declared by the <tt>TZ</tt>
environment variable is used; other parameters are set to zero if not
present.
</p>
<p>If <var>timestring</var> does not match <var>format</var> the command returns status 1
and prints an error message. If <var>timestring</var> matches <var>format</var> but
not all characters in <var>timestring</var> were used, the conversion succeeds
but also prints an error message.
</p>
<p>If either of the system functions <tt>strptime</tt> or <tt>mktime</tt> is not
available, status 2 is returned and an error message is printed.
</p>
</dd>
<dt><tt>-s</tt> <var>scalar</var></dt>
<dd><p>Assign the date string (or epoch time in seconds if <tt>-r</tt> is given) to
<var>scalar</var> instead of printing it.
</p>
</dd>
</dl>
<p>Note that depending on the system’s declared integral time type,
<tt>strftime</tt> may produce incorrect results for epoch times greater than
2147483647 which corresponds to 2038-01-19 03:14:07 +0000.
</p>
</dd>
</dl>
<p>The <tt>zsh/datetime</tt> module makes available several parameters;
all are readonly:
</p>
<dl compact="compact">
<dd><a name="index-EPOCHREALTIME"></a>
</dd>
<dt><tt>EPOCHREALTIME</tt></dt>
<dd><p>A floating point value representing the number of seconds since
the epoch. The notional accuracy is to nanoseconds if the
<tt>clock_gettime</tt> call is available and to microseconds otherwise,
but in practice the range of double precision floating point and
shell scheduling latencies may be significant effects.
</p>
<a name="index-EPOCHSECONDS"></a>
</dd>
<dt><tt>EPOCHSECONDS</tt></dt>
<dd><p>An integer value representing the number of seconds since the
epoch.
</p>
<a name="index-epochtime"></a>
</dd>
<dt><tt>epochtime</tt></dt>
<dd><p>An array value containing the number of seconds since the epoch
in the first element and the remainder of the time since the epoch
in nanoseconds in the second element. To ensure the two elements
are consistent the array should be copied or otherwise referenced
as a single substitution before the values are used. The following
idiom may be used:
</p>
<div class="example">
<pre class="example">for secs nsecs in $epochtime; do
...
done
</pre></div>
</dd>
</dl>
<hr>
<a name="The-zsh_002fdb_002fgdbm-Module"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fdatetime-Module" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Zsh-Modules" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fdeltochar-Module" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="The-zsh_002fdb_002fgdbm-Module-1"></a>
<h2 class="section">22.11 The zsh/db/gdbm Module</h2>
<p>The <tt>zsh/db/gdbm</tt> module is used to create "tied" associative arrays
that interface to database files. If the GDBM interface is not available,
the builtins defined by this module will report an error. This module is
also intended as a prototype for creating additional database interfaces,
so the <tt>ztie</tt> builtin may move to a more generic module in the future.
</p>
<p>The builtins in this module are:
</p>
<dl compact="compact">
<dd><a name="index-ztie"></a>
<a name="index-database-tied-array_002c-creating"></a>
</dd>
<dt><tt>ztie -d db/gdbm -f</tt> <var>filename</var> [ <tt>-r</tt> ] <var>arrayname</var></dt>
<dd><p>Open the GDBM database identified by <var>filename</var> and, if successful,
create the associative array <var>arrayname</var> linked to the file. To create
a local tied array, the parameter must first be declared, so commands
similar to the following would be executed inside a function scope:
</p>
<div class="example">
<pre class="example">local -A sampledb
ztie -d db/gdbm -f sample.gdbm sampledb
</pre></div>
<p>The <tt>-r</tt> option opens the database file for reading only, creating a
parameter with the readonly attribute. Without this option, using
‘<tt>ztie</tt>’ on a file for which the user does not have write permission is
an error. If writable, the database is opened synchronously so fields
changed in <var>arrayname</var> are immediately written to <var>filename</var>.
</p>
<p>Changes to the file modes <var>filename</var> after it has been opened do not
alter the state of <var>arrayname</var>, but ‘<tt>typeset -r</tt> <var>arrayname</var>’
works as expected.
</p>
<a name="index-zuntie"></a>
<a name="index-database-tied-array_002c-destroying"></a>
</dd>
<dt><tt>zuntie</tt> [ <tt>-u</tt> ] <var>arrayname</var> ...</dt>
<dd><p>Close the GDBM database associated with each <var>arrayname</var> and then
unset the parameter. The <tt>-u</tt> option forces an unset of parameters
made readonly with ‘<tt>ztie -r</tt>’.
</p>
<p>This happens automatically if the parameter is explicitly unset or its
local scope (function) ends. Note that a readonly parameter may not be
explicitly unset, so the only way to unset a global parameter created with
‘<tt>ztie -r</tt>’ is to use ‘<tt>zuntie -u</tt>’.
</p>
<a name="index-zgdbmpath"></a>
<a name="index-database-file-path_002c-reading"></a>
</dd>
<dt><tt>zgdbmpath</tt> <var>parametername</var></dt>
<dd><p>Put path to database file assigned to <var>parametername</var> into <tt>REPLY</tt>
scalar.
</p>
<a name="index-zgdbm_005ftied"></a>
<a name="index-database-tied-arrays_002c-enumerating"></a>
</dd>
<dt><tt>zgdbm_tied</tt></dt>
<dd><p>Array holding names of all tied parameters.
</p>
</dd>
</dl>
<p>The fields of an associative array tied to GDBM are neither cached nor
otherwise stored in memory, they are read from or written to the database
on each reference. Thus, for example, the values in a readonly array may
be changed by a second writer of the same database file.
</p><hr>
<a name="The-zsh_002fdeltochar-Module"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fdb_002fgdbm-Module" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Zsh-Modules" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fexample-Module" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="The-zsh_002fdeltochar-Module-1"></a>
<h2 class="section">22.12 The zsh/deltochar Module</h2>
<p>The <tt>zsh/deltochar</tt> module makes available two ZLE functions:
</p>
<dl compact="compact">
<dd><a name="index-delete_002dto_002dchar"></a>
</dd>
<dt><tt>delete-to-char</tt></dt>
<dd><p>Read a character from the keyboard, and
delete from the cursor position up to and including the next
(or, with repeat count <var>n</var>, the <var>n</var>th) instance of that character.
Negative repeat counts mean delete backwards.
</p>
<a name="index-zap_002dto_002dchar"></a>
</dd>
<dt><tt>zap-to-char</tt></dt>
<dd><p>This behaves like <tt>delete-to-char</tt>, except that the final occurrence of
the character itself is not deleted.
</p>
</dd>
</dl>
<hr>
<a name="The-zsh_002fexample-Module"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fdeltochar-Module" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Zsh-Modules" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002ffiles-Module" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="The-zsh_002fexample-Module-1"></a>
<h2 class="section">22.13 The zsh/example Module</h2>
<p>The <tt>zsh/example</tt> module makes available one builtin command:
</p>
<dl compact="compact">
<dd><a name="index-example"></a>
<a name="index-modules_002c-example"></a>
<a name="index-modules_002c-writing"></a>
<a name="index-writing-modules"></a>
</dd>
<dt><tt>example</tt> [ <tt>-flags</tt> ] [ <var>args</var> ... ]</dt>
<dd><p>Displays the flags and arguments it is invoked with.
</p>
</dd>
</dl>
<p>The purpose of the module is to serve as an example of how to write a
module.
</p><hr>
<a name="The-zsh_002ffiles-Module"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fexample-Module" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Zsh-Modules" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002flanginfo-Module" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="The-zsh_002ffiles-Module-1"></a>
<h2 class="section">22.14 The zsh/files Module</h2>
<a name="index-files_002c-manipulating"></a>
<p>The <tt>zsh/files</tt> module makes available some common commands for file
manipulation as builtins; these commands are probably not needed for
many normal situations but can be useful in emergency recovery
situations with constrained resources. The commands do not implement
all features now required by relevant standards committees.
</p>
<p>For all commands, a variant beginning <tt>zf_</tt> is also available and loaded
automatically. Using the features capability of zmodload will let you load
only those names you want. Note that it’s possible to load only the
builtins with zsh-specific names using the following command:
</p>
<div class="example">
<pre class="example">zmodload -m -F zsh/files b:zf_\*
</pre></div>
<p>The commands loaded by default are:
</p>
<dl compact="compact">
<dd><a name="index-chgrp"></a>
</dd>
<dt><tt>chgrp</tt> [ <tt>-hRs</tt> ] <var>group</var> <var>filename</var> ...</dt>
<dd><p>Changes group of files specified. This is equivalent to <tt>chown</tt> with
a <var>user-spec</var> argument of ‘<tt>:</tt><var>group</var>’.
</p>
<a name="index-chown"></a>
</dd>
<dt><tt>chown</tt> [ <tt>-hRs</tt> ] <var>user-spec</var> <var>filename</var> ...</dt>
<dd><p>Changes ownership and group of files specified.
</p>
<p>The <var>user-spec</var> can be in four forms:
</p>
<dl compact="compact">
<dt><var>user</var></dt>
<dd><p>change owner to <var>user</var>; do not change group
</p></dd>
<dt><var>user</var><tt>::</tt></dt>
<dd><p>change owner to <var>user</var>; do not change group
</p></dd>
<dt><var>user</var><tt>:</tt></dt>
<dd><p>change owner to <var>user</var>; change group to <var>user</var>’s primary group
</p></dd>
<dt><var>user</var><tt>:</tt><var>group</var></dt>
<dd><p>change owner to <var>user</var>; change group to <var>group</var>
</p></dd>
<dt><tt>:</tt><var>group</var></dt>
<dd><p>do not change owner; change group to <var>group</var>
</p></dd>
</dl>
<p>In each case, the ‘<tt>:</tt>’ may instead be a ‘<tt>.</tt>’. The rule is that
if there is a ‘<tt>:</tt>’ then the separator is ‘<tt>:</tt>’, otherwise
if there is a ‘<tt>.</tt>’ then the separator is ‘<tt>.</tt>’, otherwise
there is no separator.
</p>
<p>Each of <var>user</var> and <var>group</var> may be either a username (or group name, as
appropriate) or a decimal user ID (group ID). Interpretation as a name
takes precedence, if there is an all-numeric username (or group name).
</p>
<p>If the target is a symbolic link, the <tt>-h</tt> option causes <tt>chown</tt> to set
the ownership of the link instead of its target.
</p>
<p>The <tt>-R</tt> option causes <tt>chown</tt> to recursively descend into directories,
changing the ownership of all files in the directory after
changing the ownership of the directory itself.
</p>
<p>The <tt>-s</tt> option is a zsh extension to <tt>chown</tt> functionality. It enables
paranoid behaviour, intended to avoid security problems involving
a <tt>chown</tt> being tricked into affecting files other than the ones
intended. It will refuse to follow symbolic links, so that (for example)
‘‘<tt>chown luser /tmp/foo/passwd</tt>’’ can’t accidentally chown <tt>/etc/passwd</tt>
if <tt>/tmp/foo</tt> happens to be a link to <tt>/etc</tt>. It will also check
where it is after leaving directories, so that a recursive chown of
a deep directory tree can’t end up recursively chowning <tt>/usr</tt> as
a result of directories being moved up the tree.
</p>
<a name="index-ln"></a>
</dd>
<dt><tt>ln</tt> [ <tt>-dfhins</tt> ] <var>filename</var> <var>dest</var></dt>
<dt><tt>ln</tt> [ <tt>-dfhins</tt> ] <var>filename</var> ... <var>dir</var></dt>
<dd><p>Creates hard (or, with <tt>-s</tt>, symbolic) links. In the first form, the
specified <var>dest</var>ination is created, as a link to the specified
<var>filename</var>. In the second form, each of the <var>filename</var>s is
taken in turn, and linked to a pathname in the specified <var>dir</var>ectory
that has the same last pathname component.
</p>
<p>Normally, <tt>ln</tt> will not attempt to create hard links to
directories. This check can be overridden using the <tt>-d</tt> option.
Typically only the super-user can actually succeed in creating
hard links to directories.
This does not apply to symbolic links in any case.
</p>
<p>By default, existing files cannot be replaced by links.
The <tt>-i</tt> option causes the user to be queried about replacing
existing files. The <tt>-f</tt> option causes existing files to be
silently deleted, without querying. <tt>-f</tt> takes precedence.
</p>
<p>The <tt>-h</tt> and <tt>-n</tt> options are identical and both exist for
compatibility; either one indicates that if the target is a symlink
then it should not be dereferenced.
Typically this is used in combination with <tt>-sf</tt> so that if an
existing link points to a directory then it will be removed,
instead of followed.
If this option is used with multiple filenames and the target
is a symbolic link pointing to a directory then the result is
an error.
</p>
<a name="index-mkdir"></a>
</dd>
<dt><tt>mkdir</tt> [ <tt>-p</tt> ] [ <tt>-m</tt> <var>mode</var> ] <var>dir</var> ...</dt>
<dd><p>Creates directories. With the <tt>-p</tt> option, non-existing parent
directories are first created if necessary, and there will be
no complaint if the directory already exists.
The <tt>-m</tt> option can be used to specify (in octal) a set of file permissions
for the created directories, otherwise mode 777 modified by the current
<tt>umask</tt> (see man page umask(2)) is used.
</p>
<a name="index-mv"></a>
</dd>
<dt><tt>mv</tt> [ <tt>-fi</tt> ] <var>filename</var> <var>dest</var></dt>
<dt><tt>mv</tt> [ <tt>-fi</tt> ] <var>filename</var> ... <var>dir</var></dt>
<dd><p>Moves files. In the first form, the specified <var>filename</var> is moved
to the specified <var>dest</var>ination. In the second form, each of the
<var>filename</var>s is
taken in turn, and moved to a pathname in the specified <var>dir</var>ectory
that has the same last pathname component.
</p>
<p>By default, the user will be queried before replacing any file
that the user cannot write to, but writable files will be silently
removed.
The <tt>-i</tt> option causes the user to be queried about replacing
any existing files. The <tt>-f</tt> option causes any existing files to be
silently deleted, without querying. <tt>-f</tt> takes precedence.
</p>
<p>Note that this <tt>mv</tt> will not move files across devices.
Historical versions of <tt>mv</tt>, when actual renaming is impossible,
fall back on copying and removing files; if this behaviour is desired,
use <tt>cp</tt> and <tt>rm</tt> manually. This may change in a future version.
</p>
<a name="index-rm"></a>
</dd>
<dt><tt>rm</tt> [ <tt>-dfirs</tt> ] <var>filename</var> ...</dt>
<dd><p>Removes files and directories specified.
</p>
<p>Normally, <tt>rm</tt> will not remove directories (except with the <tt>-r</tt>
option). The <tt>-d</tt> option causes <tt>rm</tt> to try removing directories
with <tt>unlink</tt> (see man page unlink(2)), the same method used for files.
Typically only the super-user can actually succeed in unlinking
directories in this way.
<tt>-d</tt> takes precedence over <tt>-r</tt>.
</p>
<p>By default, the user will be queried before removing any file
that the user cannot write to, but writable files will be silently
removed.
The <tt>-i</tt> option causes the user to be queried about removing
any files. The <tt>-f</tt> option causes files to be
silently deleted, without querying, and suppresses all error indications.
<tt>-f</tt> takes precedence.
</p>
<p>The <tt>-r</tt> option causes <tt>rm</tt> to recursively descend into directories,
deleting all files in the directory before removing the directory with
the <tt>rmdir</tt> system call (see man page rmdir(2)).
</p>
<p>The <tt>-s</tt> option is a zsh extension to <tt>rm</tt> functionality. It enables
paranoid behaviour, intended to avoid common security problems involving
a root-run <tt>rm</tt> being tricked into removing files other than the ones
intended. It will refuse to follow symbolic links, so that (for example)
‘‘<tt>rm /tmp/foo/passwd</tt>’’ can’t accidentally remove <tt>/etc/passwd</tt>
if <tt>/tmp/foo</tt> happens to be a link to <tt>/etc</tt>. It will also check
where it is after leaving directories, so that a recursive removal of
a deep directory tree can’t end up recursively removing <tt>/usr</tt> as
a result of directories being moved up the tree.
</p>
<a name="index-rmdir"></a>
</dd>
<dt><tt>rmdir</tt> <var>dir</var> ...</dt>
<dd><p>Removes empty directories specified.
</p>
<a name="index-sync"></a>
</dd>
<dt><tt>sync</tt></dt>
<dd><p>Calls the system call of the same name (see man page sync(2)), which
flushes dirty buffers to disk. It might return before the I/O has
actually been completed.
</p>
</dd>
</dl>
<hr>
<a name="The-zsh_002flanginfo-Module"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002ffiles-Module" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Zsh-Modules" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fmapfile-Module" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="The-zsh_002flanginfo-Module-1"></a>
<h2 class="section">22.15 The zsh/langinfo Module</h2>
<p>The <tt>zsh/langinfo</tt> module makes available one parameter:
</p>
<dl compact="compact">
<dd><a name="index-langinfo"></a>
</dd>
<dt><tt>langinfo</tt></dt>
<dd><p>An associative array that maps langinfo elements to
their values.
</p>
<p>Your implementation may support a number of the following keys:
</p>
<p><tt>CODESET</tt>,
<tt>D_T_FMT</tt>,
<tt>D_FMT</tt>,
<tt>T_FMT</tt>,
<tt>RADIXCHAR</tt>,
<tt>THOUSEP</tt>,
<tt>YESEXPR</tt>,
<tt>NOEXPR</tt>,
<tt>CRNCYSTR</tt>,
<tt>ABDAY_{1..7}</tt>,
<tt>DAY_{1..7}</tt>,
<tt>ABMON_{1..12}</tt>,
<tt>MON_{1..12}</tt>,
<tt>T_FMT_AMPM</tt>,
<tt>AM_STR</tt>,
<tt>PM_STR</tt>,
<tt>ERA</tt>,
<tt>ERA_D_FMT</tt>,
<tt>ERA_D_T_FMT</tt>,
<tt>ERA_T_FMT</tt>,
<tt>ALT_DIGITS</tt>
</p>
</dd>
</dl>
<hr>
<a name="The-zsh_002fmapfile-Module"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002flanginfo-Module" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Zsh-Modules" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#Limitations" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="The-zsh_002fmapfile-Module-1"></a>
<h2 class="section">22.16 The zsh/mapfile Module</h2>
<a name="index-parameter_002c-file-access-via"></a>
<p>The <tt>zsh/mapfile</tt> module provides one special associative array parameter of
the same name.
</p>
<dl compact="compact">
<dd><a name="index-mapfile"></a>
</dd>
<dt><tt>mapfile</tt></dt>
<dd><p>This associative array takes as keys the names of files; the resulting
value is the content of the file. The value is treated identically to any
other text coming from a parameter. The value may also be assigned to, in
which case the file in question is written (whether or not it originally
existed); or an element may be unset, which will delete the file in
question. For example, ‘<tt>vared mapfile[myfile]</tt>’ works as expected,
editing the file ‘<tt>myfile</tt>’.
</p>
<p>When the array is accessed as a whole, the keys are the names of files in
the current directory, and the values are empty (to save a huge overhead in
memory). Thus <tt>${(k)mapfile}</tt> has the same affect as the glob operator
<tt>*(D)</tt>, since files beginning with a dot are not special. Care must be
taken with expressions such as <tt>rm ${(k)mapfile}</tt>, which will delete
every file in the current directory without the usual ‘<tt>rm *</tt>’ test.
</p>
<p>The parameter <tt>mapfile</tt> may be made read-only; in that case, files
referenced may not be written or deleted.
</p>
<p>A file may conveniently be read into an array as one line per element
with the form
‘<var>array</var><tt>=("${(f@)mapfile[</tt><var>filename</var><tt>]}")</tt>’.
The double quotes and the ‘<tt>@</tt>’ are necessary to prevent empty lines
from being removed. Note that if the file ends with a newline,
the shell will split on the final newline, generating an additional
empty field; this can be suppressed by using
‘<var>array</var><tt>=("${(f@)${mapfile[</tt><var>filename</var><tt>]%$'\n'}}")</tt>’.
</p>
</dd>
</dl>
<hr>
<a name="Limitations"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fmapfile-Module" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fmapfile-Module" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fmathfunc-Module" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h3 class="subsection">22.16.1 Limitations</h3>
<p>Although reading and writing of the file in question is efficiently
handled, zsh’s internal memory management may be arbitrarily baroque;
however, <tt>mapfile</tt> is usually very much more efficient than
anything involving a loop. Note in particular that
the whole contents of the file will always reside physically in memory when
accessed (possibly multiple times, due to standard parameter substitution
operations). In particular, this means handling of sufficiently long files
(greater than the machine’s swap space, or than the range of the pointer
type) will be incorrect.
</p>
<p>No errors are printed or flagged for non-existent, unreadable, or
unwritable files, as the parameter mechanism is too low in the shell
execution hierarchy to make this convenient.
</p>
<p>It is unfortunate that the mechanism for loading modules does not yet allow
the user to specify the name of the shell parameter to be given the special
behaviour.
</p><hr>
<a name="The-zsh_002fmathfunc-Module"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Limitations" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Zsh-Modules" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fnewuser-Module" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="The-zsh_002fmathfunc-Module-1"></a>
<h2 class="section">22.17 The zsh/mathfunc Module</h2>
<a name="index-functions_002c-mathematical"></a>
<a name="index-mathematical-functions"></a>
<p>The <tt>zsh/mathfunc</tt> module provides standard
mathematical functions for use when
evaluating mathematical formulae. The syntax agrees with normal C and
FORTRAN conventions, for example,
</p>
<div class="example">
<pre class="example">(( f = sin(0.3) ))
</pre></div>
<p>assigns the sine of 0.3 to the parameter f.
</p>
<p>Most functions take floating point arguments and return a floating point
value. However, any necessary conversions from or to integer type will be
performed automatically by the shell. Apart from <tt>atan</tt> with a second
argument and the <tt>abs</tt>, <tt>int</tt> and <tt>float</tt> functions, all functions
behave as noted in the manual page for the corresponding C function,
except that any arguments out of range for the function in question will be
detected by the shell and an error reported.
</p>
<p>The following functions take a single floating point argument: <tt>acos</tt>,
<tt>acosh</tt>, <tt>asin</tt>, <tt>asinh</tt>, <tt>atan</tt>, <tt>atanh</tt>, <tt>cbrt</tt>, <tt>ceil</tt>,
<tt>cos</tt>, <tt>cosh</tt>, <tt>erf</tt>, <tt>erfc</tt>, <tt>exp</tt>, <tt>expm1</tt>, <tt>fabs</tt>,
<tt>floor</tt>, <tt>gamma</tt>, <tt>j0</tt>, <tt>j1</tt>, <tt>lgamma</tt>, <tt>log</tt>, <tt>log10</tt>,
<tt>log1p</tt>, <tt>logb</tt>, <tt>sin</tt>, <tt>sinh</tt>, <tt>sqrt</tt>, <tt>tan</tt>, <tt>tanh</tt>,
<tt>y0</tt>, <tt>y1</tt>. The <tt>atan</tt> function can optionally take a second
argument, in which case it behaves like the C function <tt>atan2</tt>.
The <tt>ilogb</tt> function takes a single floating point argument, but
returns an integer.
</p>
<p>The function <tt>signgam</tt> takes no arguments, and returns an integer, which
is the C variable of the same name, as described in man page gamma(3). Note
that it is therefore only useful immediately after a call to <tt>gamma</tt> or
<tt>lgamma</tt>. Note also that ‘<tt>signgam()</tt>’ and ‘<tt>signgam</tt>’ are
distinct expressions.
</p>
<p>The functions <tt>min</tt>, <tt>max</tt>, and <tt>sum</tt> are defined not in this module
but in the <tt>zmathfunc</tt> autoloadable function, described in
<a href="User-Contributions.html#Mathematical-Functions">Mathematical Functions</a>.
</p>
<p>The following functions take two floating point arguments: <tt>copysign</tt>,
<tt>fmod</tt>, <tt>hypot</tt>, <tt>nextafter</tt>.
</p>
<p>The following take an integer first argument and a floating point second
argument: <tt>jn</tt>, <tt>yn</tt>.
</p>
<p>The following take a floating point first argument and an integer second
argument: <tt>ldexp</tt>, <tt>scalb</tt>.
</p>
<p>The function <tt>abs</tt> does not convert the type of its single argument; it
returns the absolute value of either a floating point number or an
integer. The functions <tt>float</tt> and <tt>int</tt> convert their arguments into
a floating point or integer value (by truncation) respectively.
</p>
<p>Note that the C <tt>pow</tt> function is available in ordinary math evaluation
as the ‘<tt>**</tt>’ operator and is not provided here.
</p>
<p>The function <tt>rand48</tt> is available if your system’s mathematical library
has the function <tt>erand48(3)</tt>. It returns a pseudo-random floating point
number between 0 and 1. It takes a single string optional argument.
</p>
<p>If the argument is not present, the random number seed is initialised by
three calls to the <tt>rand(3)</tt> function — this produces the
same random
numbers as the next three values of <tt>$RANDOM</tt>.
</p>
<p>If the argument is present, it gives the name of a scalar parameter where
the current random number seed will be stored. On the first call, the
value must contain at least twelve hexadecimal digits (the remainder of the
string is ignored), or the seed will be initialised in the same manner as
for a call to <tt>rand48</tt> with no argument. Subsequent calls to
<tt>rand48</tt>(<var>param</var>) will then maintain the seed in the
parameter <var>param</var> as a string of twelve hexadecimal digits, with no base
signifier. The random number sequences for different parameters are
completely independent, and are also independent from that used by calls to
<tt>rand48</tt> with no argument.
</p>
<p>For example, consider
</p>
<div class="example">
<pre class="example">print $(( rand48(seed) ))
print $(( rand48() ))
print $(( rand48(seed) ))
</pre></div>
<p>Assuming <tt>$seed</tt> does not exist, it will be initialised by the first
call. In the second call, the default seed is initialised; note, however,
that because of the properties of <tt>rand()</tt> there is a
correlation between
the seeds used for the two initialisations, so for more secure uses, you
should generate your own 12-byte seed. The third call returns to the same
sequence of random numbers used in the first call, unaffected by the
intervening <tt>rand48()</tt>.
</p><hr>
<a name="The-zsh_002fnewuser-Module"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fmathfunc-Module" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Zsh-Modules" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fparameter-Module" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="The-zsh_002fnewuser-Module-1"></a>
<h2 class="section">22.18 The zsh/newuser Module</h2>
<p>The <tt>zsh/newuser</tt> module is loaded at boot if it is
available, the <tt>RCS</tt> option is set, and the <tt>PRIVILEGED</tt> option is not
set (all three are true by default). This takes
place immediately after commands in the global <tt>zshenv</tt> file (typically
<tt>/etc/zsh/zshenv</tt>), if any, have been executed. If the module is not
available it is silently ignored by the shell; the module may safely be
removed from <tt>$MODULE_PATH</tt> by the administrator if it is not required.
</p>
<p>On loading, the module tests if any of the start-up files <tt>.zshenv</tt>,
<tt>.zprofile</tt>, <tt>.zshrc</tt> or <tt>.zlogin</tt> exist in the directory given by
the environment variable <tt>ZDOTDIR</tt>, or the user’s home directory if that
is not set. The test is not performed and the module halts processing if
the shell was in an emulation mode (i.e. had been invoked as some other
shell than zsh).
</p>
<p>If none of the start-up files were found, the module then looks for the
file <tt>newuser</tt> first in a sitewide directory, usually the parent
directory of the <tt>site-functions</tt> directory, and if that is not found the
module searches in a version-specific directory, usually the parent of the
<tt>functions</tt> directory containing version-specific functions. (These
directories can be configured when zsh is built using the
<tt>--enable-site-scriptdir=</tt><var>dir</var> and <tt>--enable-scriptdir=</tt><var>dir</var>
flags to <tt>configure</tt>, respectively; the defaults are
<var>prefix</var><tt>/share/zsh</tt> and <var>prefix</var><tt>/share/zsh/$ZSH_VERSION</tt> where
the default <var>prefix</var> is <tt>/usr/local</tt>.)
</p>
<p>If the file <tt>newuser</tt> is found, it is then sourced in the same manner as
a start-up file. The file is expected to contain code to install start-up
files for the user, however any valid shell code will be executed.
</p>
<p>The <tt>zsh/newuser</tt> module is then unconditionally unloaded.
</p>
<p>Note that it is possible to achieve exactly the same effect as the
<tt>zsh/newuser</tt> module by adding code to <tt>/etc/zsh/zshenv</tt>. The module
exists simply to allow the shell to make arrangements for new users without
the need for intervention by package maintainers and system administrators.
</p>
<p>The script supplied with the module invokes the shell function
<tt>zsh-newuser-install</tt>. This may be invoked directly by the user
even if the <tt>zsh/newuser</tt> module is disabled. Note, however, that
if the module is not installed the function will not be installed either.
The function is documented in
<a href="User-Contributions.html#User-Configuration-Functions">User Configuration Functions</a>.
</p><hr>
<a name="The-zsh_002fparameter-Module"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fnewuser-Module" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Zsh-Modules" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fpcre-Module" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="The-zsh_002fparameter-Module-1"></a>
<h2 class="section">22.19 The zsh/parameter Module</h2>
<a name="index-parameters_002c-special-1"></a>
<p>The <tt>zsh/parameter</tt> module gives access to some of the internal hash
tables used by the shell by defining some special parameters.
</p>
<dl compact="compact">
<dd><a name="index-options-1"></a>
</dd>
<dt><tt>options</tt></dt>
<dd><p>The keys for this associative array are the names of the options that
can be set and unset using the <tt>setopt</tt> and <tt>unsetopt</tt>
builtins. The value of each key is either the string <tt>on</tt> if the
option is currently set, or the string <tt>off</tt> if the option is unset.
Setting a key to one of these strings is like setting or unsetting
the option, respectively. Unsetting a key in this array is like
setting it to the value <tt>off</tt>.
</p>
<a name="index-commands"></a>
</dd>
<dt><tt>commands</tt></dt>
<dd><p>This array gives access to the command hash table. The keys are the
names of external commands, the values are the pathnames of the files
that would be executed when the command would be invoked. Setting a
key in this array defines a new entry in this table in the same way as
with the <tt>hash</tt> builtin. Unsetting a key as in ‘<tt>unset
"commands[foo]"</tt>’ removes the entry for the given key from the command
hash table.
</p>
<a name="index-functions-2"></a>
</dd>
<dt><tt>functions</tt></dt>
<dd><p>This associative array maps names of enabled functions to their
definitions. Setting a key in it is like defining a function with the
name given by the key and the body given by the value. Unsetting a key
removes the definition for the function named by the key.
</p>
<a name="index-dis_005ffunctions"></a>
</dd>
<dt><tt>dis_functions</tt></dt>
<dd><p>Like <tt>functions</tt> but for disabled functions.
</p>
<a name="index-functions_005fsource"></a>
</dd>
<dt><tt>functions_source</tt></dt>
<dd><p>This readonly associative array maps names of enabled functions to the
name of the file containing the source of the function.
</p>
<p>For an autoloaded function that has already been loaded, or marked for
autoload with an absolute path, or that has had its path resolved with
‘<tt>functions -r</tt>’, this is the file found for autoloading, resolved
to an absolute path.
</p>
<p>For a function defined within the body of a script or sourced file,
this is the name of that file. In this case, this is the exact path
originally used to that file, which may be a relative path.
</p>
<p>For any other function, including any defined at an interactive prompt or
an autoload function whose path has not yet been resolved, this is
the empty string. However, the hash element is reported as defined
just so long as the function is present: the keys to this hash are
the same as those to <tt>$funcions</tt>.
</p>
<a name="index-dis_005ffunctions_005fsource"></a>
</dd>
<dt><tt>dis_functions_source</tt></dt>
<dd><p>Like <tt>functions_source</tt> but for disabled functions.
</p>
<a name="index-builtins"></a>
</dd>
<dt><tt>builtins</tt></dt>
<dd><p>This associative array gives information about the builtin commands
currently enabled. The keys are the names of the builtin commands and
the values are either ‘<tt>undefined</tt>’ for builtin commands that will
automatically be loaded from a module if invoked or ‘<tt>defined</tt>’ for
builtin commands that are already loaded.
</p>
<a name="index-dis_005fbuiltins"></a>
</dd>
<dt><tt>dis_builtins</tt></dt>
<dd><p>Like <tt>builtins</tt> but for disabled builtin commands.
</p>
<a name="index-reswords"></a>
</dd>
<dt><tt>reswords</tt></dt>
<dd><p>This array contains the enabled reserved words.
</p>
<a name="index-dis_005freswords"></a>
</dd>
<dt><tt>dis_reswords</tt></dt>
<dd><p>Like <tt>reswords</tt> but for disabled reserved words.
</p>
<a name="index-patchars"></a>
</dd>
<dt><tt>patchars</tt></dt>
<dd><p>This array contains the enabled pattern characters.
</p>
<a name="index-dis_005fpatchars"></a>
</dd>
<dt><tt>dis_patchars</tt></dt>
<dd><p>Like <tt>patchars</tt> but for disabled pattern characters.
</p>
<a name="index-aliases"></a>
</dd>
<dt><tt>aliases</tt></dt>
<dd><p>This maps the names of the regular aliases currently enabled to their
expansions.
</p>
<a name="index-dis_005faliases"></a>
</dd>
<dt><tt>dis_aliases</tt></dt>
<dd><p>Like <tt>aliases</tt> but for disabled regular aliases.
</p>
<a name="index-galiases"></a>
</dd>
<dt><tt>galiases</tt></dt>
<dd><p>Like <tt>aliases</tt>, but for global aliases.
</p>
<a name="index-dis_005fgaliases"></a>
</dd>
<dt><tt>dis_galiases</tt></dt>
<dd><p>Like <tt>galiases</tt> but for disabled global aliases.
</p>
<a name="index-saliases"></a>
</dd>
<dt><tt>saliases</tt></dt>
<dd><p>Like <tt>raliases</tt>, but for suffix aliases.
</p>
<a name="index-dis_005fsaliases"></a>
</dd>
<dt><tt>dis_saliases</tt></dt>
<dd><p>Like <tt>saliases</tt> but for disabled suffix aliases.
</p>
<a name="index-parameters-1"></a>
</dd>
<dt><tt>parameters</tt></dt>
<dd><p>The keys in this associative array are the names of the parameters
currently defined. The values are strings describing the type of the
parameter, in the same format used by the <tt>t</tt> parameter flag, see
<a href="Expansion.html#Parameter-Expansion">Parameter Expansion</a>
.
Setting or unsetting keys in this array is not possible.
</p>
<a name="index-modules-1"></a>
</dd>
<dt><tt>modules</tt></dt>
<dd><p>An associative array giving information about modules. The keys are the names
of the modules loaded, registered to be autoloaded, or aliased. The
value says which state the named module is in and is one of the
strings ‘<tt>loaded</tt>’, ‘<tt>autoloaded</tt>’, or ‘<tt>alias:</tt><var>name</var>’,
where <var>name</var> is the name the module is aliased to.
</p>
<p>Setting or unsetting keys in this array is not possible.
</p>
<a name="index-dirstack"></a>
</dd>
<dt><tt>dirstack</tt></dt>
<dd><p>A normal array holding the elements of the directory stack. Note that
the output of the <tt>dirs</tt> builtin command includes one more
directory, the current working directory.
</p>
<a name="index-history-2"></a>
</dd>
<dt><tt>history</tt></dt>
<dd><p>This associative array maps history event numbers to the full history lines.
Although it is presented as an associative array, the array of all values
(<tt>${history[@]}</tt>) is guaranteed to be returned in order from most recent
to oldest history event, that is, by decreasing history event number.
</p>
<a name="index-historywords"></a>
</dd>
<dt><tt>historywords</tt></dt>
<dd><p>A special array containing the words stored in the history. These also
appear in most to least recent order.
</p>
<a name="index-jobdirs"></a>
</dd>
<dt><tt>jobdirs</tt></dt>
<dd><p>This associative array maps job numbers to the directories from which the
job was started (which may not be the current directory of the job).
</p>
<p>The keys of the associative arrays are usually valid job numbers,
and these are the values output with, for example, <tt>${(k)jobdirs}</tt>.
Non-numeric job references may be used when looking up a value;
for example, <tt>${jobdirs[%+]}</tt> refers to the current job.
</p>
<a name="index-jobtexts"></a>
</dd>
<dt><tt>jobtexts</tt></dt>
<dd><p>This associative array maps job numbers to the texts of the command lines
that were used to start the jobs.
</p>
<p>Handling of the keys of the associative array is as described for
<tt>jobdirs</tt> above.
</p>
<a name="index-jobstates"></a>
</dd>
<dt><tt>jobstates</tt></dt>
<dd><p>This associative array gives information about the states of the jobs
currently known. The keys are the job numbers and the values are
strings of the form
‘<var>job-state</var><tt>:</tt><var>mark</var><tt>:</tt><var>pid</var><tt>=</tt><var>state</var>...’. The
<var>job-state</var> gives the state the whole job is currently in, one of
‘<tt>running</tt>’, ‘<tt>suspended</tt>’, or ‘<tt>done</tt>’. The <var>mark</var> is
‘<tt>+</tt>’ for the current job, ‘<tt>-</tt>’ for the previous job and empty
otherwise. This is followed by one ‘<tt>:</tt><var>pid</var><tt>=</tt><var>state</var>’ for every
process in the job. The <var>pid</var>s are, of course, the process IDs and
the <var>state</var> describes the state of that process.
</p>
<p>Handling of the keys of the associative array is as described for
<tt>jobdirs</tt> above.
</p>
<a name="index-nameddirs"></a>
</dd>
<dt><tt>nameddirs</tt></dt>
<dd><p>This associative array maps the names of named directories to the pathnames
they stand for.
</p>
<a name="index-userdirs"></a>
</dd>
<dt><tt>userdirs</tt></dt>
<dd><p>This associative array maps user names to the pathnames of their home
directories.
</p>
<a name="index-usergroups"></a>
</dd>
<dt><tt>usergroups</tt></dt>
<dd><p>This associative array maps names of system groups of which the current
user is a member to the corresponding group identifiers. The contents
are the same as the groups output by the <tt>id</tt> command.
</p>
<a name="index-funcfiletrace"></a>
</dd>
<dt><tt>funcfiletrace</tt></dt>
<dd><p>This array contains the absolute line numbers and corresponding file
names for the point where the current function, sourced file, or (if
<tt>EVAL_LINENO</tt> is set) <tt>eval</tt> command was
called. The array is of the same length as <tt>funcsourcetrace</tt> and
<tt>functrace</tt>, but differs from <tt>funcsourcetrace</tt> in that the line and
file are the point of call, not the point of definition, and differs
from <tt>functrace</tt> in that all values are absolute line numbers in
files, rather than relative to the start of a function, if any.
</p>
<a name="index-funcsourcetrace"></a>
</dd>
<dt><tt>funcsourcetrace</tt></dt>
<dd><p>This array contains the file names and line numbers of the
points where the functions, sourced files, and (if <tt>EVAL_LINENO</tt> is set)
<tt>eval</tt> commands currently being executed were
defined. The line number is the line where the ‘<tt>function</tt> <var>name</var>’
or ‘<var>name</var> <tt>()</tt>’ started. In the case of an autoloaded
function the line number is reported as zero.
The format of each element is <var>filename</var><tt>:</tt><var>lineno</var>.
</p>
<p>For functions autoloaded from a file in native zsh format, where only the
body of the function occurs in the file, or for files that have been
executed by the <tt>source</tt> or ‘<tt>.</tt>’ builtins, the trace information is
shown as <var>filename</var><tt>:</tt><var>0</var>, since the entire file is the
definition. The source file name is resolved to an absolute path when
the function is loaded or the path to it otherwise resolved.
</p>
<p>Most users will be interested in the information in the
<tt>funcfiletrace</tt> array instead.
</p>
<a name="index-funcstack"></a>
</dd>
<dt><tt>funcstack</tt></dt>
<dd><p>This array contains the names of the functions, sourced files,
and (if <tt>EVAL_LINENO</tt> is set) <tt>eval</tt> commands. currently being
executed. The first element is the name of the function using the
parameter.
</p>
<p>The standard shell array <tt>zsh_eval_context</tt> can be used to
determine the type of shell construct being executed at each depth:
note, however, that is in the opposite order, with the most recent
item last, and it is more detailed, for example including an
entry for <tt>toplevel</tt>, the main shell code being executed
either interactively or from a script, which is not present
in <tt>$funcstack</tt>.
</p>
<a name="index-functrace"></a>
</dd>
<dt><tt>functrace</tt></dt>
<dd><p>This array contains the names and line numbers of the callers
corresponding to the functions currently being executed.
The format of each element is <var>name</var><tt>:</tt><var>lineno</var>.
Callers are also shown for sourced files; the caller is the point
where the <tt>source</tt> or ‘<tt>.</tt>’ command was executed.
</p>
</dd>
</dl>
<hr>
<a name="The-zsh_002fpcre-Module"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fparameter-Module" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Zsh-Modules" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fparam_002fprivate-Module" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="The-zsh_002fpcre-Module-1"></a>
<h2 class="section">22.20 The zsh/pcre Module</h2>
<a name="index-regular-expressions_002c-perl_002dcompatible"></a>
<p>The <tt>zsh/pcre</tt> module makes some commands available as builtins:
</p>
<dl compact="compact">
<dd><a name="index-pcre_005fcompile"></a>
</dd>
<dt><tt>pcre_compile</tt> [ <tt>-aimxs</tt> ] <var>PCRE</var></dt>
<dd><p>Compiles a perl-compatible regular expression.
</p>
<p>Option <tt>-a</tt> will force the pattern to be anchored.
Option <tt>-i</tt> will compile a case-insensitive pattern.
Option <tt>-m</tt> will compile a multi-line pattern; that is,
<tt>^</tt> and <tt>$</tt> will match newlines within the pattern.
Option <tt>-x</tt> will compile an extended pattern, wherein
whitespace and <tt>#</tt> comments are ignored.
Option <tt>-s</tt> makes the dot metacharacter match all characters,
including those that indicate newline.
</p>
<a name="index-pcre_005fstudy"></a>
</dd>
<dt><tt>pcre_study</tt></dt>
<dd><p>Studies the previously-compiled PCRE which may result in faster
matching.
</p>
<a name="index-pcre_005fmatch"></a>
</dd>
<dt><tt>pcre_match</tt> [ <tt>-v</tt> <var>var</var> ] [ <tt>-a</tt> <var>arr</var> ] [ <tt>-n</tt> <var>offset</var> ] [ <tt>-b</tt> ] <var>string</var></dt>
<dd><p>Returns successfully if <tt>string</tt> matches the previously-compiled
PCRE.
</p>
<p>Upon successful match,
if the expression captures substrings within parentheses,
<tt>pcre_match</tt> will set the array <tt>match</tt> to those
substrings, unless the <tt>-a</tt> option is given, in which
case it will set the array <var>arr</var>. Similarly, the variable
<tt>MATCH</tt> will be set to the entire matched portion of the
string, unless the <tt>-v</tt> option is given, in which case the variable
<var>var</var> will be set.
No variables are altered if there is no successful match.
A <tt>-n</tt> option starts searching for a match from the
byte <var>offset</var> position in <var>string</var>. If the <tt>-b</tt> option is given,
the variable <tt>ZPCRE_OP</tt> will be set to an offset pair string,
representing the byte offset positions of the entire matched portion
within the <var>string</var>. For example, a <tt>ZPCRE_OP</tt> set to "32 45" indicates
that the matched portion began on byte offset 32 and ended on byte offset 44.
Here, byte offset position 45 is the position directly after the matched
portion. Keep in mind that the byte position isn’t necessarily the same
as the character position when UTF-8 characters are involved.
Consequently, the byte offset positions are only to be relied on in the
context of using them for subsequent searches on <var>string</var>, using an offset
position as an argument to the <tt>-n</tt> option. This is mostly
used to implement the "find all non-overlapping matches" functionality.
</p>
<p>A simple example of "find all non-overlapping matches":
</p>
<div class="example">
<pre class="example">string="The following zip codes: 78884 90210 99513"
pcre_compile -m "\d{5}"
accum=()
pcre_match -b -- $string
while [[ $? -eq 0 ]] do
b=($=ZPCRE_OP)
accum+=$MATCH
pcre_match -b -n $b[2] -- $string
done
print -l $accum
</pre></div>
</dd>
</dl>
<p>The <tt>zsh/pcre</tt> module makes available the following test condition:
</p>
<dl compact="compact">
<dd><a name="index-pcre_002dmatch"></a>
</dd>
<dt><var>expr</var> <tt>-pcre-match</tt> <var>pcre</var></dt>
<dd><p>Matches a string against a perl-compatible regular expression.
</p>
<p>For example,
</p>
<div class="example">
<pre class="example">[[ "$text" -pcre-match ^d+$ ]] &&
print text variable contains only "d's".
</pre></div>
<p><a name="index-REMATCH_005fPCRE-1"></a>
<a name="index-NO_005fCASE_005fMATCH-1"></a>
If the <tt>REMATCH_PCRE</tt> option is set, the <tt>=~</tt> operator is equivalent to
<tt>-pcre-match</tt>, and the <tt>NO_CASE_MATCH</tt> option may be used. Note that
<tt>NO_CASE_MATCH</tt> never applies to the <tt>pcre_match</tt> builtin, instead use
the <tt>-i</tt> switch of <tt>pcre_compile</tt>.
</p>
</dd>
</dl>
<hr>
<a name="The-zsh_002fparam_002fprivate-Module"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fpcre-Module" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Zsh-Modules" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fregex-Module" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="The-zsh_002fparam_002fprivate-Module-1"></a>
<h2 class="section">22.21 The zsh/param/private Module</h2>
<p>The <tt>zsh/param/private</tt> module is used to create parameters whose scope
is limited to the current function body, and <em>not</em> to other functions
called by the current function.
</p>
<p>This module provides a single autoloaded builtin:
</p>
<dl compact="compact">
<dd><a name="index-private"></a>
<a name="index-private-parameter_002c-creating"></a>
</dd>
<dt><tt>private</tt> [ {<tt>+</tt>|<tt>-</tt>}<tt>AHUahlprtux</tt> ] [ {<tt>+</tt>|<tt>-</tt>}<tt>EFLRZi</tt> [ <var>n</var> ] ] [ <var>name</var>[<tt>=</tt><var>value</var>] ... ]</dt>
<dd><p>The <tt>private</tt> builtin accepts all the same options and arguments as <tt>local</tt>
(<a href="Shell-Builtin-Commands.html#Shell-Builtin-Commands">Shell Builtin Commands</a>) except
for the ‘<tt>-</tt><tt>T</tt>’ option. Tied parameters may not be made private.
</p>
<p>If used at the top level (outside a function scope), <tt>private</tt> creates a
normal parameter in the same manner as <tt>declare</tt> or <tt>typeset</tt>. A
warning about this is printed if <tt>WARN_CREATE_GLOBAL</tt> is set
(<a href="Options.html#Options">Options</a>). Used inside a
function scope, <tt>private</tt> creates a local parameter similar to one
declared with <tt>local</tt>, except having special properties noted below.
</p>
<p>Special parameters which expose or manipulate internal shell state, such
as <tt>ARGC</tt>, <tt>argv</tt>, <tt>COLUMNS</tt>, <tt>LINES</tt>, <tt>UID</tt>, <tt>EUID</tt>, <tt>IFS</tt>,
<tt>PROMPT</tt>, <tt>RANDOM</tt>, <tt>SECONDS</tt>, etc., cannot be made private unless
the ‘<tt>-</tt><tt>h</tt>’ option is used to hide the special meaning of the
parameter. This may change in the future.
</p>
</dd>
</dl>
<p>As with other <tt>typeset</tt> equivalents, <tt>private</tt> is both a builtin and a
reserved word, so arrays may be assigned with parenthesized word list
<var>name</var><tt>=(</tt><var>value</var>...<tt>)</tt> syntax. However, the reserved
word ‘<tt>private</tt>’ is not available until <tt>zsh/param/private</tt> is loaded,
so care must be taken with order of execution and parsing for function
definitions which use <tt>private</tt>. To compensate for this, the module
also adds the option ‘<tt>-P</tt>’ to the ‘<tt>local</tt>’ builtin to declare private
parameters.
</p>
<p>For example, this construction fails if <tt>zsh/param/private</tt> has not yet
been loaded when ‘<tt>bad_declaration</tt>’ is defined:
</p><div class="example">
<pre class="example">bad_declaration() {
zmodload zsh/param/private
private array=( one two three )
}
</pre></div>
<p>This construction works because <tt>local</tt> is already a keyword, and the
module is loaded before the statement is executed:
</p><div class="example">
<pre class="example">good_declaration() {
zmodload zsh/param/private
local -P array=( one two three )
}
</pre></div>
<p>The following is usable in scripts but may have trouble with <tt>autoload</tt>:
</p><div class="example">
<pre class="example">zmodload zsh/param/private
iffy_declaration() {
private array=( one two three )
}
</pre></div>
<p>The <tt>private</tt> builtin may always be used with scalar assignments and
for declarations without assignments.
</p>
<p>Parameters declared with <tt>private</tt> have the following properties:
</p>
<ul>
<li> Within the function body where it is declared, the parameter
behaves as a local, except as noted above for tied or special parameters.
</li><li> The type of a parameter declared private cannot be changed in the
scope where it was declared, even if the parameter is unset. Thus an
array cannot be assigned to a private scalar, etc.
</li><li> Within any other function called by the declaring function, the
private parameter does <em>NOT</em> hide other parameters of the same name, so
for example a global parameter of the same name is visible and may be
assigned or unset. This includes calls to anonymous functions, although
that may also change in the future.
</li><li> An exported private remains in the environment of inner scopes but
appears unset for the current shell in those scopes. Generally, exporting
private parameters should be avoided.
</li></ul>
<p>Note that this differs from the static scope defined by compiled languages
derived from C, in that the a new call to the same function creates a new
scope, i.e., the parameter is still associated with the call stack rather
than with the function definition. It differs from ksh ‘<tt>typeset -S</tt>’
because the syntax used to define the function has no bearing on whether
the parameter scope is respected.
</p><hr>
<a name="The-zsh_002fregex-Module"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fparam_002fprivate-Module" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Zsh-Modules" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fsched-Module" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="The-zsh_002fregex-Module-1"></a>
<h2 class="section">22.22 The zsh/regex Module</h2>
<a name="index-regular-expressions"></a>
<a name="index-regex"></a>
<p>The <tt>zsh/regex</tt> module makes available the following test condition:
</p>
<dl compact="compact">
<dd><a name="index-regex_002dmatch"></a>
</dd>
<dt><var>expr</var> <tt>-regex-match</tt> <var>regex</var></dt>
<dd><p>Matches a string against a POSIX extended regular expression.
On successful match,
matched portion of the string will normally be placed in the <tt>MATCH</tt>
variable. If there are any capturing parentheses within the regex, then
the <tt>match</tt> array variable will contain those.
If the match is not successful, then the variables will not be altered.
</p>
<p>For example,
</p>
<div class="example">
<pre class="example">[[ alphabetical -regex-match ^a([^a]+)a([^a]+)a ]] &&
print -l $MATCH X $match
</pre></div>
<p>If the option <tt>REMATCH_PCRE</tt> is not set, then the <tt>=~</tt> operator will
automatically load this module as needed and will invoke the
<tt>-regex-match</tt> operator.
</p>
<p>If <tt>BASH_REMATCH</tt> is set, then the array <tt>BASH_REMATCH</tt> will be set
instead of <tt>MATCH</tt> and <tt>match</tt>.
</p>
</dd>
</dl>
<hr>
<a name="The-zsh_002fsched-Module"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fregex-Module" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Zsh-Modules" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fnet_002fsocket-Module" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="The-zsh_002fsched-Module-1"></a>
<h2 class="section">22.23 The zsh/sched Module</h2>
<p>The <tt>zsh/sched</tt> module makes available one builtin command and one
parameter.
</p>
<dl compact="compact">
<dd><a name="index-sched"></a>
<a name="index-timed-execution"></a>
<a name="index-execution_002c-timed"></a>
</dd>
<dt><tt>sched</tt> [<tt>-o</tt>] [<tt>+</tt>]<var>hh</var><tt>:</tt><var>mm</var>[<tt>:</tt><var>ss</var>] <var>command</var> ...</dt>
<dt><tt>sched</tt> [<tt>-o</tt>] [<tt>+</tt>]<var>seconds</var> <var>command</var> ...</dt>
<dt><tt>sched</tt> [ <tt>-</tt><var>item</var> ]</dt>
<dd><p>Make an entry in the scheduled list of commands to execute.
The time may be specified in either absolute or relative time,
and either as hours, minutes and (optionally) seconds separated by a
colon, or seconds alone.
An absolute number of seconds indicates the time since the epoch
(1970/01/01 00:00); this is useful in combination with the features in
the <tt>zsh/datetime</tt> module, see
<a href="#The-zsh_002fdatetime-Module">The zsh/datetime Module</a>.
</p>
<p>With no arguments, prints the list of scheduled commands. If the
scheduled command has the <tt>-o</tt> flag set, this is shown at the
start of the command.
</p>
<p>With the argument ‘<tt>-</tt><var>item</var>’, removes the given item
from the list. The numbering of the list is continuous and entries are
in time order, so the numbering can change when entries are added or
deleted.
</p>
<p>Commands are executed either immediately before a prompt, or while
the shell’s line editor is waiting for input. In the latter case
it is useful to be able to produce output that does not interfere
with the line being edited. Providing the option <tt>-o</tt> causes
the shell to clear the command line before the event and redraw it
afterwards. This should be used with any scheduled event that produces
visible output to the terminal; it is not needed, for example, with
output that updates a terminal emulator’s title bar.
</p>
<p>To effect changes to the editor buffer when an event executes, use the
‘<tt>zle</tt>’ command with no arguments to test whether the editor is active,
and if it is, then use ‘<tt>zle </tt><var>widget</var>’ to access the editor via
the named <var>widget</var>.
</p>
<p>The <tt>sched</tt> builtin is not made available by default when the shell
starts in a mode emulating another shell. It can be made available
with the command ‘<tt>zmodload -F zsh/sched b:sched</tt>’.
</p>
</dd>
</dl>
<dl compact="compact">
<dd><a name="index-zsh_005fscheduled_005fevents"></a>
</dd>
<dt><tt>zsh_scheduled_events</tt></dt>
<dd><p>A readonly array corresponding to the events scheduled by the
<tt>sched</tt> builtin. The indices of the array correspond to the numbers
shown when <tt>sched</tt> is run with no arguments (provided that the
<tt>KSH_ARRAYS</tt> option is not set). The value of the array
consists of the scheduled time in seconds since the epoch
(see <a href="#The-zsh_002fdatetime-Module">The zsh/datetime Module</a> for facilities for
using this number), followed by a colon, followed by any options
(which may be empty but will be preceded by a ‘<tt>-</tt>’ otherwise),
followed by a colon, followed by the command to be executed.
</p>
<p>The <tt>sched</tt> builtin should be used for manipulating the events. Note
that this will have an immediate effect on the contents of the array,
so that indices may become invalid.
</p>
</dd>
</dl>
<hr>
<a name="The-zsh_002fnet_002fsocket-Module"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fsched-Module" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Zsh-Modules" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#Outbound-Connections" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="The-zsh_002fnet_002fsocket-Module-1"></a>
<h2 class="section">22.24 The zsh/net/socket Module</h2>
<p>The <tt>zsh/net/socket</tt> module makes available one builtin command:
</p>
<dl compact="compact">
<dd><a name="index-zsocket"></a>
<a name="index-sockets"></a>
<a name="index-sockets_002c-Unix-domain"></a>
</dd>
<dt><tt>zsocket</tt> [ <tt>-altv</tt> ] [ <tt>-d</tt> <var>fd</var> ] [ <var>args</var> ]</dt>
<dd><p><tt>zsocket</tt> is implemented as a builtin to allow full use of shell
command line editing, file I/O, and job control mechanisms.
</p>
</dd>
</dl>
<hr>
<a name="Outbound-Connections"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fnet_002fsocket-Module" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fnet_002fsocket-Module" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#Inbound-Connections" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h3 class="subsection">22.24.1 Outbound Connections</h3>
<p><a name="index-sockets_002c-outbound-Unix-domain"></a>
</p>
<dl compact="compact">
<dt><tt>zsocket</tt> [ <tt>-v</tt> ] [ <tt>-d</tt> <var>fd</var> ] <var>filename</var></dt>
<dd><p>Open a new Unix domain connection to <var>filename</var>.
The shell parameter <tt>REPLY</tt> will be set to the file descriptor
associated with that connection. Currently, only stream connections
are supported.
</p>
<p>If <tt>-d</tt> is specified, its argument
will be taken as the target file descriptor for the
connection.
</p>
<p>In order to elicit more verbose output, use <tt>-v</tt>.
</p>
<p>File descriptors can be closed with normal shell syntax when no longer
needed, for example:
</p>
<div class="example">
<pre class="example">exec {REPLY}>&-
</pre></div>
</dd>
</dl>
<hr>
<a name="Inbound-Connections"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Outbound-Connections" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fnet_002fsocket-Module" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fstat-Module" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h3 class="subsection">22.24.2 Inbound Connections</h3>
<p><a name="index-sockets_002c-inbound-Unix-domain"></a>
</p>
<dl compact="compact">
<dt><tt>zsocket</tt> <tt>-l</tt> [ <tt>-v</tt> ] [ <tt>-d</tt> <var>fd</var> ] <var>filename</var></dt>
<dd><p><tt>zsocket -l</tt> will open a socket listening on <var>filename</var>.
The shell parameter <tt>REPLY</tt> will be set to the file descriptor
associated with that listener.
</p>
<p>If <tt>-d</tt> is specified, its argument
will be taken as the target file descriptor for
the connection.
</p>
<p>In order to elicit more verbose output, use <tt>-v</tt>.
</p>
</dd>
<dt><tt>zsocket</tt> <tt>-a</tt> [ <tt>-tv</tt> ] [ <tt>-d</tt> <var>targetfd</var> ] <var>listenfd</var></dt>
<dd><p><tt>zsocket -a</tt> will accept an incoming connection
to the socket associated with <var>listenfd</var>.
The shell parameter <tt>REPLY</tt> will
be set to the file descriptor associated with
the inbound connection.
</p>
<p>If <tt>-d</tt> is specified, its argument
will be taken as the target file descriptor for the
connection.
</p>
<p>If <tt>-t</tt> is specified, <tt>zsocket</tt> will return
if no incoming connection is pending. Otherwise
it will wait for one.
</p>
<p>In order to elicit more verbose output, use <tt>-v</tt>.
</p>
</dd>
</dl>
<hr>
<a name="The-zsh_002fstat-Module"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Inbound-Connections" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Zsh-Modules" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fsystem-Module" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="The-zsh_002fstat-Module-1"></a>
<h2 class="section">22.25 The zsh/stat Module</h2>
<p>The <tt>zsh/stat</tt> module makes available one builtin command under
two possible names:
</p>
<dl compact="compact">
<dd><a name="index-zstat"></a>
<a name="index-stat"></a>
<a name="index-files_002c-listing"></a>
<a name="index-files_002c-examining"></a>
</dd>
<dt><tt>zstat </tt>[ <tt>-gnNolLtTrs</tt> ] [ <tt>-f</tt> <var>fd</var> ] [ <tt>-H</tt> <var>hash</var> ] [ <tt>-A</tt> <var>array</var> ] [ <tt>-F</tt> <var>fmt</var> ]</dt>
<dt><tt> </tt>[ <tt>+</tt><var>element</var> ] [ <var>file</var> ... ]</dt>
<dt><tt>stat</tt> <var>...</var></dt>
<dd><p>The command acts as a front end to the <tt>stat</tt> system call (see
man page stat(2)). The same command is provided with two names; as
the name <tt>stat</tt> is often used by an external command it is recommended
that only the <tt>zstat</tt> form of the command is used. This can be
arranged by loading the module with the command ‘<tt>zmodload -F zsh/stat
b:zstat</tt>’.
</p>
<p>If the <tt>stat</tt> call fails, the appropriate system error message
printed and status 1 is returned.
The fields of <tt>struct stat</tt> give information about
the files provided as arguments to the command. In addition to those
available from the <tt>stat</tt> call, an extra element ‘<tt>link</tt>’ is provided.
These elements are:
</p>
<dl compact="compact">
<dt><tt>device</tt></dt>
<dd><p>The number of the device on which the file resides.
</p>
</dd>
<dt><tt>inode</tt></dt>
<dd><p>The unique number of the file on this device (‘<em>inode</em>’ number).
</p>
</dd>
<dt><tt>mode</tt></dt>
<dd><p>The mode of the file; that is, the file’s type and access permissions.
With the <tt>-s</tt> option, this will
be returned as a string corresponding to the first column in the
display of the <tt>ls -l</tt> command.
</p>
</dd>
<dt><tt>nlink</tt></dt>
<dd><p>The number of hard links to the file.
</p>
</dd>
<dt><tt>uid</tt></dt>
<dd><p>The user ID of the owner of the file. With the <tt>-s</tt>
option, this is displayed as a user name.
</p>
</dd>
<dt><tt>gid</tt></dt>
<dd><p>The group ID of the file. With the <tt>-s</tt> option, this
is displayed as a group name.
</p>
</dd>
<dt><tt>rdev</tt></dt>
<dd><p>The raw device number. This is only useful for special devices.
</p>
</dd>
<dt><tt>size</tt></dt>
<dd><p>The size of the file in bytes.
</p>
</dd>
<dt><tt>atime</tt></dt>
<dt><tt>mtime</tt></dt>
<dt><tt>ctime</tt></dt>
<dd><p>The last access, modification and inode change times
of the file, respectively, as the number of seconds since
midnight GMT on 1st January, 1970. With the <tt>-s</tt> option,
these are printed as strings for the local time zone; the format
can be altered with the <tt>-F</tt> option, and with the <tt>-g</tt>
option the times are in GMT.
</p>
</dd>
<dt><tt>blksize</tt></dt>
<dd><p>The number of bytes in one allocation block on the
device on which the file resides.
</p>
</dd>
<dt><tt>block</tt></dt>
<dd><p>The number of disk blocks used by the file.
</p>
</dd>
<dt><tt>link</tt></dt>
<dd><p>If the file is a link and the <tt>-L</tt> option is in
effect, this contains the name of the file linked to, otherwise
it is empty. Note that if this element is selected (‘‘<tt>zstat +link</tt>’’)
then the <tt>-L</tt> option is automatically used.
</p>
</dd>
</dl>
<p>A particular element may be selected by including its name
preceded by a ‘<tt>+</tt>’ in the option list; only one element is allowed.
The element may be shortened to any unique set of leading
characters. Otherwise, all elements will be shown for all files.
</p>
<p>Options:
</p>
<dl compact="compact">
<dt><tt>-A</tt> <var>array</var></dt>
<dd><p>Instead of displaying the results on standard
output, assign them to an <var>array</var>, one <tt>struct stat</tt> element per array
element for each file in order. In this case neither the name
of the element nor the name of the files appears in <var>array</var> unless the
<tt>-t</tt> or <tt>-n</tt> options were given, respectively. If <tt>-t</tt> is given,
the element name appears as a prefix to the
appropriate array element; if <tt>-n</tt> is given, the file name
appears as a separate array element preceding all the others.
Other formatting options are respected.
</p>
</dd>
<dt><tt>-H</tt> <var>hash</var></dt>
<dd><p>Similar to <tt>-A</tt>, but instead assign the values to <var>hash</var>. The keys
are the elements listed above. If the <tt>-n</tt> option is provided then the
name of the file is included in the hash with key <tt>name</tt>.
</p>
</dd>
<dt><tt>-f</tt> <var>fd</var></dt>
<dd><p>Use the file on file descriptor <var>fd</var> instead of
named files; no list of file names is allowed in this case.
</p>
</dd>
<dt><tt>-F</tt> <var>fmt</var></dt>
<dd><p>Supplies a <tt>strftime</tt> (see man page strftime(3)) string for the
formatting of the time elements. The <tt>-s</tt> option is implied.
</p>
</dd>
<dt><tt>-g</tt></dt>
<dd><p>Show the time elements in the GMT time zone. The
<tt>-s</tt> option is implied.
</p>
</dd>
<dt><tt>-l</tt></dt>
<dd><p>List the names of the type elements (to standard
output or an array as appropriate) and return immediately;
options other than <tt>-A</tt> and arguments are ignored.
</p>
</dd>
<dt><tt>-L</tt></dt>
<dd><p>Perform an <tt>lstat</tt> (see man page lstat(2)) rather than a <tt>stat</tt>
system call. In this case, if the file is a link, information
about the link itself rather than the target file is returned.
This option is required to make the <tt>link</tt> element useful.
It’s important to note that this is the exact opposite from man page ls(1),
etc.
</p>
</dd>
<dt><tt>-n</tt></dt>
<dd><p>Always show the names of files. Usually these are
only shown when output is to standard output and there is more
than one file in the list.
</p>
</dd>
<dt><tt>-N</tt></dt>
<dd><p>Never show the names of files.
</p>
</dd>
<dt><tt>-o</tt></dt>
<dd><p>If a raw file mode is printed, show it in octal, which is more useful for
human consumption than the default of decimal. A leading zero will be
printed in this case. Note that this does not affect whether a raw or
formatted file mode is shown, which is controlled by the <tt>-r</tt> and <tt>-s</tt>
options, nor whether a mode is shown at all.
</p>
</dd>
<dt><tt>-r</tt></dt>
<dd><p>Print raw data (the default format) alongside string
data (the <tt>-s</tt> format); the string data appears in parentheses
after the raw data.
</p>
</dd>
<dt><tt>-s</tt></dt>
<dd><p>Print <tt>mode</tt>, <tt>uid</tt>, <tt>gid</tt> and the three time
elements as strings instead of numbers. In each case the format
is like that of <tt>ls -l</tt>.
</p>
</dd>
<dt><tt>-t</tt></dt>
<dd><p>Always show the type names for the elements of
<tt>struct stat</tt>. Usually these are only shown when output is to
standard output and no individual element has been selected.
</p>
</dd>
<dt><tt>-T</tt></dt>
<dd><p>Never show the type names of the <tt>struct stat</tt> elements.
</p>
</dd>
</dl>
</dd>
</dl>
<hr>
<a name="The-zsh_002fsystem-Module"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fstat-Module" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Zsh-Modules" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#Builtins" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="The-zsh_002fsystem-Module-1"></a>
<h2 class="section">22.26 The zsh/system Module</h2>
<p>The <tt>zsh/system</tt> module makes available various builtin commands and
parameters.
</p>
<hr>
<a name="Builtins"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fsystem-Module" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fsystem-Module" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#Math-Functions" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h3 class="subsection">22.26.1 Builtins</h3>
<dl compact="compact">
<dd><a name="index-syserror"></a>
</dd>
<dt><tt>syserror</tt> [ <tt>-e</tt> <var>errvar</var> ] [ <tt>-p</tt> <var>prefix</var> ] [ <var>errno</var> | <var>errname</var> ]</dt>
<dd><p>This command prints out the error message associated with <var>errno</var>, a
system error number, followed by a newline to standard error.
</p>
<p>Instead of the error number, a name <var>errname</var>, for example
<tt>ENOENT</tt>, may be used. The set of names is the same as the contents
of the array <tt>errnos</tt>, see below.
</p>
<p>If the string <var>prefix</var> is given, it is printed in front of the error
message, with no intervening space.
</p>
<p>If <var>errvar</var> is supplied, the entire message, without a newline, is
assigned to the parameter names <var>errvar</var> and nothing is output.
</p>
<p>A return status of 0 indicates the message was successfully printed
(although it may not be useful if the error number was out of the
system’s range), a return status of 1 indicates an error in the
parameters, and a return status of 2 indicates the error name was
not recognised (no message is printed for this).
</p>
<a name="index-sysopen"></a>
</dd>
<dt><tt>sysopen</tt> [ <tt>-arw</tt> ] [ <tt>-m</tt> <var>permissions</var> ] [ <tt>-o</tt> <var>options</var> ]</dt>
<dt><tt> </tt><tt>-u</tt> <var>fd</var> <var>file</var></dt>
<dd><p>This command opens a file. The <tt>-r</tt>, <tt>-w</tt> and <tt>-a</tt> flags indicate
whether the file should be opened for reading, writing and appending,
respectively. The <tt>-m</tt> option allows the initial permissions to use when
creating a file to be specified in octal form. The file descriptor is
specified with <tt>-u</tt>. Either an explicit file descriptor in the range 0 to 9 can
be specified or a variable name can be given to which the file descriptor
number will be assigned.
</p>
<p>The <tt>-o</tt> option allows various system specific options to be
specified as a comma-separated list. The following is a list of possible
options. Note that, depending on the system, some may not be available.
</p><dl compact="compact">
<dt><tt>cloexec</tt></dt>
<dd><p>mark file to be closed when other programs are executed
</p>
</dd>
<dt><tt>create</tt></dt>
<dt><tt>creat</tt></dt>
<dd><p>create file if it does not exist
</p>
</dd>
<dt><tt>excl</tt></dt>
<dd><p>create file, error if it already exists
</p>
</dd>
<dt><tt>noatime</tt></dt>
<dd><p>suppress updating of the file atime
</p>
</dd>
<dt><tt>nofollow</tt></dt>
<dd><p>fail if <var>file</var> is a symbolic link
</p>
</dd>
<dt><tt>sync</tt></dt>
<dd><p>request that writes wait until data has been physically written
</p>
</dd>
<dt><tt>truncate</tt></dt>
<dt><tt>trunc</tt></dt>
<dd><p>truncate file to size 0
</p>
</dd>
</dl>
<p>To close the file, use one of the following:
</p>
<div class="example">
<pre class="example"><tt>exec {</tt><var>fd</var><tt>}<&-</tt>
<tt>exec {</tt><var>fd</var><tt>}>&-</tt>
</pre></div>
<a name="index-sysread"></a>
</dd>
<dt><tt>sysread </tt>[ <tt>-c</tt> <var>countvar</var> ] [ <tt>-i</tt> <var>infd</var> ] [ <tt>-o</tt> <var>outfd</var> ]</dt>
<dt><tt> </tt>[ <tt>-s</tt> <var>bufsize</var> ] [ <tt>-t</tt> <var>timeout</var> ] [ <var>param</var> ]</dt>
<dd><p>Perform a single system read from file descriptor <var>infd</var>, or zero if
that is not given. The result of the read is stored in <var>param</var> or
<tt>REPLY</tt> if that is not given. If <var>countvar</var> is given, the number
of bytes read is assigned to the parameter named by <var>countvar</var>.
</p>
<p>The maximum number of bytes read is <var>bufsize</var> or 8192 if that is not
given, however the command returns as soon as any number of bytes was
successfully read.
</p>
<p>If <var>timeout</var> is given, it specifies a timeout in seconds, which may
be zero to poll the file descriptor. This is handled by the <tt>poll</tt>
system call if available, otherwise the <tt>select</tt> system call if
available.
</p>
<p>If <var>outfd</var> is given, an attempt is made to write all the bytes just
read to the file descriptor <var>outfd</var>. If this fails, because of a
system error other than <tt>EINTR</tt> or because of an internal zsh error
during an interrupt, the bytes read but not written are stored in the
parameter named by <var>param</var> if supplied (no default is used in this
case), and the number of bytes read but not written is stored in the
parameter named by <var>countvar</var> if that is supplied. If it was
successful, <var>countvar</var> contains the full number of bytes transferred,
as usual, and <var>param</var> is not set.
</p>
<p>The error <tt>EINTR</tt> (interrupted system call) is handled internally so
that shell interrupts are transparent to the caller. Any other error
causes a return.
</p>
<p>The possible return statuses are
</p><dl compact="compact">
<dt>0</dt>
<dd><p>At least one byte of data was successfully read and, if appropriate,
written.
</p>
</dd>
<dt>1</dt>
<dd><p>There was an error in the parameters to the command. This is the only
error for which a message is printed to standard error.
</p>
</dd>
<dt>2</dt>
<dd><p>There was an error on the read, or on polling the input file descriptor
for a timeout. The parameter <tt>ERRNO</tt> gives the error.
</p>
</dd>
<dt>3</dt>
<dd><p>Data were successfully read, but there was an error writing them
to <var>outfd</var>. The parameter <tt>ERRNO</tt> gives the error.
</p>
</dd>
<dt>4</dt>
<dd><p>The attempt to read timed out. Note this does not set <tt>ERRNO</tt> as this
is not a system error.
</p>
</dd>
<dt>5</dt>
<dd><p>No system error occurred, but zero bytes were read. This usually
indicates end of file. The parameters are set according to the
usual rules; no write to <var>outfd</var> is attempted.
</p>
</dd>
</dl>
</dd>
<dt><tt>sysseek</tt> [ <tt>-u</tt> <var>fd</var> ] [ <tt>-w</tt> <tt>start</tt>|<tt>end</tt>|<tt>current</tt> ] <var>offset</var></dt>
<dd><p>The current file position at which future reads and writes will take place is
adjusted to the specified byte offset. The <var>offset</var> is evaluated as a math
expression. The <tt>-u</tt> option allows the file descriptor to be specified. By
default the offset is specified relative to the start or the file but, with the
<tt>-w</tt> option, it is possible to specify that the offset should be relative to
the current position or the end of the file.
</p>
</dd>
<dt><tt>syswrite</tt> [ <tt>-c</tt> <var>countvar</var> ] [ <tt>-o</tt> <var>outfd</var> ] <var>data</var></dt>
<dd><p>The data (a single string of bytes) are written to the file descriptor
<var>outfd</var>, or 1 if that is not given, using the <tt>write</tt> system call.
Multiple write operations may be used if the first does not write all
the data.
</p>
<p>If <var>countvar</var> is given, the number of byte written is stored in the
parameter named by <var>countvar</var>; this may not be the full length of
<var>data</var> if an error occurred.
</p>
<p>The error <tt>EINTR</tt> (interrupted system call) is handled internally by
retrying; otherwise an error causes the command to return. For example,
if the file descriptor is set to non-blocking output, an error
<tt>EAGAIN</tt> (on some systems, <tt>EWOULDBLOCK</tt>) may result in the command
returning early.
</p>
<p>The return status may be 0 for success, 1 for an error in the parameters
to the command, or 2 for an error on the write; no error message is
printed in the last case, but the parameter <tt>ERRNO</tt> will reflect
the error that occurred.
</p>
</dd>
<dt><tt>zsystem flock</tt> [ <tt>-t</tt> <var>timeout</var> ] [ <tt>-f</tt> <var>var</var> ] [<tt>-er</tt>] <var>file</var></dt>
<dt><tt>zsystem flock -u</tt> <var>fd_expr</var></dt>
<dd><p>The builtin <tt>zsystem</tt>’s subcommand <tt>flock</tt> performs advisory file
locking (via the man page fcntl(2) system call) over the entire contents
of the given file. This form of locking requires the processes
accessing the file to cooperate; its most obvious use is between two
instances of the shell itself.
</p>
<p>In the first form the named <var>file</var>, which must already exist, is
locked by opening a file descriptor to the file and applying a lock to
the file descriptor. The lock terminates when the shell process that
created the lock exits; it is therefore often convenient to create file
locks within subshells, since the lock is automatically released when
the subshell exits. Status 0 is returned if the lock succeeds, else
status 1.
</p>
<p>In the second form the file descriptor given by the arithmetic
expression <var>fd_expr</var> is closed, releasing a lock. The file descriptor
can be queried by using the ‘<tt>-f</tt> <var>var</var>’ form during the lock;
on a successful lock, the shell variable <var>var</var> is set to the file
descriptor used for locking. The lock will be released if the
file descriptor is closed by any other means, for example using
‘<tt>exec {</tt><var>var</var><tt>}>&-</tt>’; however, the form described here performs
a safety check that the file descriptor is in use for file locking.
</p>
<p>By default the shell waits indefinitely for the lock to succeed.
The option <tt>-t</tt> <var>timeout</var> specifies a timeout for the lock in
seconds; currently this must be an integer. The shell will attempt
to lock the file once a second during this period. If the attempt
times out, status 2 is returned.
</p>
<p>If the option <tt>-e</tt> is given, the file descriptor for the lock is
preserved when the shell uses <tt>exec</tt> to start a new process;
otherwise it is closed at that point and the lock released.
</p>
<p>If the option <tt>-r</tt> is given, the lock is only for reading, otherwise
it is for reading and writing. The file descriptor is opened
accordingly.
</p>
</dd>
<dt><tt>zsystem supports</tt> <var>subcommand</var></dt>
<dd><p>The builtin <tt>zsystem</tt>’s subcommand <tt>supports</tt> tests whether a
given subcommand is supported. It returns status 0 if so, else
status 1. It operates silently unless there was a syntax error
(i.e. the wrong number of arguments), in which case status 255
is returned. Status 1 can indicate one of two things: <var>subcommand</var>
is known but not supported by the current operating system, or
<var>subcommand</var> is not known (possibly because this is an older
version of the shell before it was implemented).
</p>
</dd>
</dl>
<hr>
<a name="Math-Functions"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Builtins" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fsystem-Module" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#Parameters-3" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h3 class="subsection">22.26.2 Math Functions</h3>
<dl compact="compact">
<dt><tt>systell(<var>fd</var>)</tt></dt>
<dd><p>The systell math function returns the current file position for the file
descriptor passed as an argument.
</p>
</dd>
</dl>
<hr>
<a name="Parameters-3"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Math-Functions" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fsystem-Module" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fnet_002ftcp-Module" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h3 class="subsection">22.26.3 Parameters</h3>
<dl compact="compact">
<dd><a name="index-errnos"></a>
</dd>
<dt><tt>errnos</tt></dt>
<dd><p>A readonly array of the names of errors defined on the system. These
are typically macros defined in C by including the system header file
<tt>errno.h</tt>. The index of each name (assuming the option <tt>KSH_ARRAYS</tt>
is unset) corresponds to the error number. Error numbers <var>num</var>
before the last known error which have no name are given the name
<tt>E</tt><var>num</var> in the array.
</p>
<p>Note that aliases for errors are not handled; only the canonical name is
used.
</p>
<a name="index-sysparams"></a>
</dd>
<dt><tt>sysparams</tt></dt>
<dd><p>A readonly associative array. The keys are:
</p>
<dl compact="compact">
<dt><tt>pid</tt></dt>
<dd><a name="index-pid_002c-sysparams"></a>
<p>Returns the process ID of the current process, even in subshells. Compare
<tt>$$</tt>, which returns the process ID of the main shell process.
</p>
</dd>
<dt><tt>ppid</tt></dt>
<dd><a name="index-ppid_002c-sysparams"></a>
<p>Returns the process ID of the parent of the current process, even in
subshells. Compare <tt>$PPID</tt>, which returns the process ID of the parent
of the main shell process.
</p>
</dd>
</dl>
</dd>
</dl>
<hr>
<a name="The-zsh_002fnet_002ftcp-Module"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Parameters-3" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Zsh-Modules" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#Outbound-Connections-1" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="The-zsh_002fnet_002ftcp-Module-1"></a>
<h2 class="section">22.27 The zsh/net/tcp Module</h2>
<p>The <tt>zsh/net/tcp</tt> module makes available one builtin command:
</p>
<dl compact="compact">
<dd><a name="index-ztcp"></a>
<a name="index-TCP"></a>
<a name="index-sockets_002c-TCP"></a>
</dd>
<dt><tt>ztcp</tt> [ <tt>-acflLtv</tt> ] [ <tt>-d</tt> <var>fd</var> ] [ <var>args</var> ]</dt>
<dd><p><tt>ztcp</tt> is implemented as a builtin to allow full use of shell
command line editing, file I/O, and job control mechanisms.
</p>
<p>If <tt>ztcp</tt> is run with no options, it will output
the contents of its session table.
</p>
<p>If it is run with only the option <tt>-L</tt>, it will output the contents of
the session table in a format suitable for automatic parsing. The option
is ignored if given with a command to open or close a session. The output
consists of a set of lines, one per session, each containing the following
elements separated by spaces:
</p>
<dl compact="compact">
<dt>File descriptor</dt>
<dd><p>The file descriptor in use for the connection. For normal inbound (<tt>I</tt>)
and outbound (<tt>O</tt>) connections this may be read and written by the usual
shell mechanisms. However, it should only be close with ‘<tt>ztcp -c</tt>’.
</p>
</dd>
<dt>Connection type</dt>
<dd><p>A letter indicating how the session was created:
</p>
<dl compact="compact">
<dt><tt>Z</tt></dt>
<dd><p>A session created with the <tt>zftp</tt> command.
</p>
</dd>
<dt><tt>L</tt></dt>
<dd><p>A connection opened for listening with ‘<tt>ztcp -l</tt>’.
</p>
</dd>
<dt><tt>I</tt></dt>
<dd><p>An inbound connection accepted with ‘<tt>ztcp -a</tt>’.
</p>
</dd>
<dt><tt>O</tt></dt>
<dd><p>An outbound connection created with ‘<tt>ztcp</tt> <var>host</var> <var>...</var>’.
</p>
</dd>
</dl>
</dd>
<dt>The local host</dt>
<dd><p>This is usually set to an all-zero IP address as the address of the
localhost is irrelevant.
</p>
</dd>
<dt>The local port</dt>
<dd><p>This is likely to be zero unless the connection is for listening.
</p>
</dd>
<dt>The remote host</dt>
<dd><p>This is the fully qualified domain name of the peer, if available, else an
IP address. It is an all-zero IP address for a session opened for
listening.
</p>
</dd>
<dt>The remote port</dt>
<dd><p>This is zero for a connection opened for listening.
</p>
</dd>
</dl>
</dd>
</dl>
<hr>
<a name="Outbound-Connections-1"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fnet_002ftcp-Module" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fnet_002ftcp-Module" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#Inbound-Connections-1" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h3 class="subsection">22.27.1 Outbound Connections</h3>
<p><a name="index-sockets_002c-outbound-TCP"></a>
</p>
<dl compact="compact">
<dt><tt>ztcp</tt> [ <tt>-v</tt> ] [ <tt>-d</tt> <var>fd</var> ] <var>host</var> [ <var>port</var> ]</dt>
<dd><p>Open a new TCP connection to <var>host</var>. If the <var>port</var> is
omitted, it will default to port 23. The connection will
be added to the session table and the shell parameter
<tt>REPLY</tt> will be set to the file descriptor associated
with that connection.
</p>
<p>If <tt>-d</tt> is specified, its argument will be taken as the target file
descriptor for the connection.
</p>
<p>In order to elicit more verbose output, use <tt>-v</tt>.
</p>
</dd>
</dl>
<hr>
<a name="Inbound-Connections-1"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Outbound-Connections-1" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fnet_002ftcp-Module" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#Closing-Connections" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h3 class="subsection">22.27.2 Inbound Connections</h3>
<p><a name="index-sockets_002c-inbound-TCP"></a>
</p>
<dl compact="compact">
<dt><tt>ztcp</tt> <tt>-l</tt> [ <tt>-v</tt> ] [ <tt>-d</tt> <var>fd</var> ] <var>port</var></dt>
<dd><p><tt>ztcp -l</tt> will open a socket listening on TCP
<var>port</var>. The socket will be added to the
session table and the shell parameter <tt>REPLY</tt>
will be set to the file descriptor associated
with that listener.
</p>
<p>If <tt>-d</tt> is specified, its argument will be taken as the target file
descriptor for the connection.
</p>
<p>In order to elicit more verbose output, use <tt>-v</tt>.
</p>
</dd>
<dt><tt>ztcp</tt> <tt>-a</tt> [ <tt>-tv</tt> ] [ <tt>-d</tt> <var>targetfd</var> ] <var>listenfd</var></dt>
<dd><p><tt>ztcp -a</tt> will accept an incoming connection
to the port associated with <var>listenfd</var>.
The connection will be added to the session
table and the shell parameter <tt>REPLY</tt> will
be set to the file descriptor associated with
the inbound connection.
</p>
<p>If <tt>-d</tt> is specified, its argument
will be taken as the target file descriptor for the
connection.
</p>
<p>If <tt>-t</tt> is specified, <tt>ztcp</tt> will return
if no incoming connection is pending. Otherwise
it will wait for one.
</p>
<p>In order to elicit more verbose output, use <tt>-v</tt>.
</p>
</dd>
</dl>
<hr>
<a name="Closing-Connections"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Inbound-Connections-1" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fnet_002ftcp-Module" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#Example-2" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h3 class="subsection">22.27.3 Closing Connections</h3>
<p><a name="index-sockets_002c-closing-TCP"></a>
</p>
<dl compact="compact">
<dt><tt>ztcp</tt> <tt>-cf</tt> [ <tt>-v</tt> ] [ <var>fd</var> ]</dt>
<dt><tt>ztcp</tt> <tt>-c</tt> [ <tt>-v</tt> ] [ <var>fd</var> ]</dt>
<dd><p><tt>ztcp -c</tt> will close the socket associated
with <var>fd</var>. The socket will be removed from the
session table. If <var>fd</var> is not specified,
<tt>ztcp</tt> will close everything in the session table.
</p>
<p>Normally, sockets registered by zftp (see
<a href="#The-zsh_002fzftp-Module">The zsh/zftp Module</a>
) cannot be closed this way. In order
to force such a socket closed, use <tt>-f</tt>.
</p>
<p>In order to elicit more verbose output, use <tt>-v</tt>.
</p>
</dd>
</dl>
<hr>
<a name="Example-2"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Closing-Connections" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fnet_002ftcp-Module" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002ftermcap-Module" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h3 class="subsection">22.27.4 Example</h3>
<p><a name="index-TCP_002c-example"></a>
Here is how to create a TCP connection between two instances of zsh. We
need to pick an unassigned port; here we use the randomly chosen 5123.
</p>
<p>On <tt>host1</tt>,
</p><div class="example">
<pre class="example">zmodload zsh/net/tcp
ztcp -l 5123
listenfd=$REPLY
ztcp -a $listenfd
fd=$REPLY
</pre></div>
<p>The second from last command blocks until there is an incoming connection.
</p>
<p>Now create a connection from <tt>host2</tt> (which may, of course, be the same
machine):
</p><div class="example">
<pre class="example">zmodload zsh/net/tcp
ztcp host1 5123
fd=$REPLY
</pre></div>
<p>Now on each host, <tt>$fd</tt> contains a file descriptor for talking to the
other. For example, on <tt>host1</tt>:
</p><div class="example">
<pre class="example">print This is a message >&$fd
</pre></div>
<p>and on <tt>host2</tt>:
</p><div class="example">
<pre class="example">read -r line <&$fd; print -r - $line
</pre></div>
<p>prints ‘<tt>This is a message</tt>’.
</p>
<p>To tidy up, on <tt>host1</tt>:
</p><div class="example">
<pre class="example">ztcp -c $listenfd
ztcp -c $fd
</pre></div>
<p>and on <tt>host2</tt>
</p><div class="example">
<pre class="example">ztcp -c $fd
</pre></div>
<hr>
<a name="The-zsh_002ftermcap-Module"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Example-2" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Zsh-Modules" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fterminfo-Module" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="The-zsh_002ftermcap-Module-1"></a>
<h2 class="section">22.28 The zsh/termcap Module</h2>
<p>The <tt>zsh/termcap</tt> module makes available one builtin command:
</p>
<dl compact="compact">
<dd><a name="index-echotc"></a>
<a name="index-termcap-value_002c-printing"></a>
</dd>
<dt><tt>echotc</tt> <var>cap</var> [ <var>arg</var> ... ]</dt>
<dd><p>Output the termcap value corresponding to the capability
<var>cap</var>, with optional arguments.
</p>
</dd>
</dl>
<p>The <tt>zsh/termcap</tt> module makes available one parameter:
</p>
<dl compact="compact">
<dd><a name="index-termcap"></a>
</dd>
<dt><tt>termcap</tt></dt>
<dd><p>An associative array that maps termcap capability codes to
their values.
</p>
</dd>
</dl>
<hr>
<a name="The-zsh_002fterminfo-Module"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002ftermcap-Module" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Zsh-Modules" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fzftp-Module" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="The-zsh_002fterminfo-Module-1"></a>
<h2 class="section">22.29 The zsh/terminfo Module</h2>
<p>The <tt>zsh/terminfo</tt> module makes available one builtin command:
</p>
<dl compact="compact">
<dd><a name="index-echoti"></a>
<a name="index-terminfo-value_002c-printing"></a>
</dd>
<dt><tt>echoti</tt> <var>cap</var> [ <var>arg</var> ]</dt>
<dd><p>Output the terminfo value corresponding to the capability
<var>cap</var>, instantiated with <var>arg</var> if applicable.
</p>
</dd>
</dl>
<p>The <tt>zsh/terminfo</tt> module makes available one parameter:
</p>
<dl compact="compact">
<dd><a name="index-terminfo"></a>
</dd>
<dt><tt>terminfo</tt></dt>
<dd><p>An associative array that maps terminfo capability names to
their values.
</p>
</dd>
</dl>
<hr>
<a name="The-zsh_002fzftp-Module"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fterminfo-Module" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Zsh-Modules" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#Subcommands" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="The-zsh_002fzftp-Module-1"></a>
<h2 class="section">22.30 The zsh/zftp Module</h2>
<p>The <tt>zsh/zftp</tt> module makes available one builtin command:
</p>
<dl compact="compact">
<dd><a name="index-zftp"></a>
<a name="index-FTP"></a>
<a name="index-files_002c-transferring"></a>
</dd>
<dt><tt>zftp</tt> <var>subcommand</var> [ <var>args</var> ]</dt>
<dd><p>The <tt>zsh/zftp</tt> module is a client for FTP (file transfer protocol). It
is implemented as a builtin to allow full use of shell command line
editing, file I/O, and job control mechanisms. Often, users will
access it via shell functions providing a more powerful interface; a set is
provided with the <tt>zsh</tt> distribution and is described in
<a href="Zftp-Function-System.html#Zftp-Function-System">Zftp Function System</a>. However, the <tt>zftp</tt> command is entirely usable in its
own right.
</p>
<p>All commands consist of the command name <tt>zftp</tt> followed by the name
of a subcommand. These are listed below. The return status of each
subcommand is supposed to reflect the success or failure of the remote
operation. See a description of the variable <tt>ZFTP_VERBOSE</tt> for
more information on how responses from the server may be printed.
</p>
</dd>
</dl>
<hr>
<a name="Subcommands"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fzftp-Module" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fzftp-Module" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#Parameters-4" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h3 class="subsection">22.30.1 Subcommands</h3>
<p><a name="index-zftp_002c-subcommands"></a>
</p>
<dl compact="compact">
<dd><a name="index-FTP_002c-starting-a-session"></a>
</dd>
<dt><tt>open</tt> <var>host</var>[<tt>:</tt><var>port</var>] [ <var>user</var> [ <var>password</var> [ <var>account</var> ] ] ]</dt>
<dd><p>Open a new FTP session to <var>host</var>, which may be the name of a TCP/IP
connected host or an IP number in the standard dot notation. If the
argument is in the form <var>host</var><tt>:</tt><var>port</var>, open a connection to
TCP port <var>port</var> instead of the standard FTP port 21. This may be
the name of a TCP service or a number: see the description of
<tt>ZFTP_PORT</tt> below for more information.
</p>
<p>If IPv6 addresses in colon format are used, the <var>host</var> should be
surrounded by quoted square brackets to distinguish it from the <var>port</var>,
for example <tt>'[fe80::203:baff:fe02:8b56]'</tt>. For consistency this is
allowed with all forms of <var>host</var>.
</p>
<p>Remaining arguments are passed to the <tt>login</tt> subcommand. Note that
if no arguments beyond <var>host</var> are supplied, <tt>open</tt> will <em>not</em>
automatically call <tt>login</tt>. If no arguments at all are supplied,
<tt>open</tt> will use the parameters set by the <tt>params</tt> subcommand.
</p>
<p>After a successful open, the shell variables <tt>ZFTP_HOST</tt>, <tt>ZFTP_PORT</tt>,
<tt>ZFTP_IP</tt> and <tt>ZFTP_SYSTEM</tt> are available; see ‘Variables’
below.
</p>
</dd>
<dt><tt>login</tt> [ <var>name</var> [ <var>password</var> [ <var>account</var> ] ] ]</dt>
<dt><tt>user</tt> [ <var>name</var> [ <var>password</var> [ <var>account</var> ] ] ]</dt>
<dd><p>Login the user <var>name</var> with parameters <var>password</var> and <var>account</var>.
Any of the parameters can be omitted, and will be read from standard
input if needed (<var>name</var> is always needed). If
standard input is a terminal, a prompt for each one will be printed on
standard error and <var>password</var> will not be echoed. If any of the
parameters are not used, a warning message is printed.
</p>
<p>After a successful login, the shell variables <tt>ZFTP_USER</tt>,
<tt>ZFTP_ACCOUNT</tt> and <tt>ZFTP_PWD</tt> are available; see ‘Variables’
below.
</p>
<p>This command may be re-issued when a user is already logged in, and
the server will first be reinitialized for a new user.
</p>
</dd>
<dt><tt>params</tt> [ <var>host</var> [ <var>user</var> [ <var>password</var> [ <var>account</var> ] ] ] ]</dt>
<dt><tt>params</tt> <tt>-</tt></dt>
<dd><p>Store the given parameters for a later <tt>open</tt> command with no
arguments. Only those given on the command line will be remembered.
If no arguments are given, the parameters currently set are printed,
although the password will appear as a line of stars; the return status is
one if no parameters were set, zero otherwise.
</p>
<p>Any of the parameters may be specified as a ‘<tt>?</tt>’, which
may need to be quoted to protect it from shell expansion. In this case,
the appropriate parameter will be read from stdin as with the
<tt>login</tt> subcommand, including special handling of <var>password</var>. If the
‘<tt>?</tt>’ is followed by a string, that is used as the prompt for reading the
parameter instead of the default message (any necessary punctuation and
whitespace should be included at the end of the prompt). The first letter
of the parameter (only) may be quoted with a ‘<tt>\</tt>’; hence an argument
<tt>"\\$word"</tt> guarantees that the string from the shell parameter <tt>$word</tt>
will be treated literally, whether or not it begins with a ‘<tt>?</tt>’.
</p>
<p>If instead a single ‘<tt>-</tt>’ is given, the existing parameters, if any,
are deleted. In that case, calling <tt>open</tt> with no arguments will
cause an error.
</p>
<p>The list of parameters is not deleted after a <tt>close</tt>, however it
will be deleted if the <tt>zsh/zftp</tt> module is unloaded.
</p>
<p>For example,
</p>
<div class="example">
<pre class="example">zftp params ftp.elsewhere.xx juser '?Password for juser: '
</pre></div>
<p>will store the host <tt>ftp.elsewhere.xx</tt> and the user <tt>juser</tt> and
then prompt the user for the corresponding password with the given prompt.
</p>
</dd>
<dt><tt>test</tt></dt>
<dd><p>Test the connection; if the server has reported
that it has closed the connection (maybe due to a timeout), return
status 2; if no connection was open anyway, return status 1; else
return status 0. The <tt>test</tt> subcommand is
silent, apart from messages printed by the <tt>$ZFTP_VERBOSE</tt>
mechanism, or error messages if the connection closes. There is no
network overhead for this test.
</p>
<p>The test is only supported on systems with either the
<tt>select(2)</tt> or
<tt>poll(2)</tt> system calls; otherwise the message ‘<tt>not
supported on this system</tt>’ is printed instead.
</p>
<p>The <tt>test</tt> subcommand will automatically be called at the start of any
other subcommand for the current session when a connection is open.
</p>
</dd>
<dt><tt>cd</tt> <var>directory</var></dt>
<dd><p>Change the remote directory to <var>directory</var>. Also alters the shell
variable <tt>ZFTP_PWD</tt>.
</p>
</dd>
<dt><tt>cdup</tt></dt>
<dd><p>Change the remote directory to the one higher in the directory tree.
Note that <tt>cd ..</tt> will also work correctly on non-UNIX systems.
</p>
</dd>
<dt><tt>dir</tt> [ <var>arg</var> ... ]</dt>
<dd><p>Give a (verbose) listing of the remote directory. The <var>arg</var>s are
passed directly to the server. The command’s behaviour is implementation
dependent, but a UNIX server will typically interpret <var>arg</var>s as
arguments to the <tt>ls</tt> command and with no arguments return the
result of ‘<tt>ls -l</tt>’. The directory is listed to standard output.
</p>
</dd>
<dt><tt>ls</tt> [ <var>arg</var> ... ]</dt>
<dd><p>Give a (short) listing of the remote directory. With no <var>arg</var>,
produces a raw list of the files in the directory, one per line.
Otherwise, up to vagaries of the server implementation, behaves
similar to <tt>dir</tt>.
</p>
</dd>
<dt><tt>type</tt> [ <var>type</var> ]</dt>
<dd><p>Change the type for the transfer to <var>type</var>, or print the current type
if <var>type</var> is absent. The allowed values are ‘<tt>A</tt>’ (ASCII),
‘<tt>I</tt>’ (Image, i.e. binary), or ‘<tt>B</tt>’ (a synonym for ‘<tt>I</tt>’).
</p>
<p>The FTP default for a transfer is ASCII. However, if <tt>zftp</tt> finds
that the remote host is a UNIX machine with 8-bit byes, it will
automatically switch to using binary for file transfers upon
<tt>open</tt>. This can subsequently be overridden.
</p>
<p>The transfer type is only passed to the remote host when a data
connection is established; this command involves no network overhead.
</p>
</dd>
<dt><tt>ascii</tt></dt>
<dd><p>The same as <tt>type A</tt>.
</p>
</dd>
<dt><tt>binary</tt></dt>
<dd><p>The same as <tt>type I</tt>.
</p>
</dd>
<dt><tt>mode</tt> [ <tt>S</tt> | <tt>B</tt> ]</dt>
<dd><p>Set the mode type to stream (<tt>S</tt>) or block (<tt>B</tt>). Stream mode is
the default; block mode is not widely supported.
</p>
</dd>
<dt><tt>remote</tt> <var>file</var> ...</dt>
<dt><tt>local</tt> [ <var>file</var> ... ]</dt>
<dd><p>Print the size and last modification time of the remote or local
files. If there is more than one item on the list, the name of the
file is printed first. The first number is the file size, the second
is the last modification time of the file in the format
<tt>CCYYMMDDhhmmSS</tt> consisting of year, month, date, hour, minutes and
seconds in GMT. Note that this format, including the length, is
guaranteed, so that time strings can be directly compared via the
<tt>[[</tt> builtin’s <tt><</tt> and <tt>></tt> operators, even if they are too long
to be represented as integers.
</p>
<p>Not all servers support the commands for retrieving this information.
In that case, the <tt>remote</tt> command will print nothing and return
status 2, compared with status 1 for a file not found.
</p>
<p>The <tt>local</tt> command (but not <tt>remote</tt>) may be used with no
arguments, in which case the information comes from examining file
descriptor zero. This is the same file as seen by a <tt>put</tt> command
with no further redirection.
</p>
</dd>
<dt><tt>get</tt> <var>file</var> ...</dt>
<dd><p>Retrieve all <var>file</var>s from the server, concatenating them
and sending them to standard output.
</p>
</dd>
<dt><tt>put</tt> <var>file</var> ...</dt>
<dd><p>For each <var>file</var>, read a file from standard input and send that to
the remote host with the given name.
</p>
</dd>
<dt><tt>append</tt> <var>file</var> ...</dt>
<dd><p>As <tt>put</tt>, but if the remote <var>file</var> already exists, data is
appended to it instead of overwriting it.
</p>
</dd>
<dt><tt>getat</tt> <var>file</var> <var>point</var></dt>
<dt><tt>putat</tt> <var>file</var> <var>point</var></dt>
<dt><tt>appendat</tt> <var>file</var> <var>point</var></dt>
<dd><p>Versions of <tt>get</tt>, <tt>put</tt> and <tt>append</tt> which will start the
transfer at the given <var>point</var> in the remote <var>file</var>. This is
useful for appending to an incomplete local file. However, note that
this ability is not universally supported by servers (and is not quite
the behaviour specified by the standard).
</p>
</dd>
<dt><tt>delete</tt> <var>file</var> ...</dt>
<dd><p>Delete the list of files on the server.
</p>
</dd>
<dt><tt>mkdir</tt> <var>directory</var></dt>
<dd><p>Create a new directory <var>directory</var> on the server.
</p>
</dd>
<dt><tt>rmdir</tt> <var>directory</var></dt>
<dd><p>Delete the directory <var>directory</var> on the server.
</p>
</dd>
<dt><tt>rename</tt> <var>old-name</var> <var>new-name</var></dt>
<dd><p>Rename file <var>old-name</var> to <var>new-name</var> on the server.
</p>
</dd>
<dt><tt>site</tt> <var>arg</var> ...</dt>
<dd><p>Send a host-specific command to the server. You will probably
only need this if instructed by the server to use it.
</p>
</dd>
<dt><tt>quote</tt> <var>arg</var> ...</dt>
<dd><p>Send the raw FTP command sequence to the server. You should be
familiar with the FTP command set as defined in RFC959 before doing
this. Useful commands may include <tt>STAT</tt> and <tt>HELP</tt>. Note also
the mechanism for returning messages as described for the variable
<tt>ZFTP_VERBOSE</tt> below, in particular that all messages from the
control connection are sent to standard error.
</p>
</dd>
<dt><tt>close</tt></dt>
<dt><tt>quit</tt></dt>
<dd><p>Close the current data connection. This unsets the shell parameters
<tt>ZFTP_HOST</tt>, <tt>ZFTP_PORT</tt>, <tt>ZFTP_IP</tt>, <tt>ZFTP_SYSTEM</tt>, <tt>ZFTP_USER</tt>,
<tt>ZFTP_ACCOUNT</tt>, <tt>ZFTP_PWD</tt>, <tt>ZFTP_TYPE</tt> and <tt>ZFTP_MODE</tt>.
</p>
</dd>
<dt><tt>session</tt> [ <var>sessname</var> ]</dt>
<dd><p>Allows multiple FTP sessions to be used at once. The name of the session
is an arbitrary string of characters; the default session is called
‘<tt>default</tt>’. If this command is called without an argument, it will list
all the current sessions; with an argument, it will either switch to the
existing session called <var>sessname</var>, or create a new session of that name.
</p>
<p>Each session remembers the status of the connection, the set of
connection-specific shell parameters (the same set as are unset when a
connection closes, as given in the description of <tt>close</tt>), and any user
parameters specified with the <tt>params</tt> subcommand. Changing to a
previous session restores those values; changing to a new session
initialises them in the same way as if <tt>zftp</tt> had just been loaded. The
name of the current session is given by the parameter <tt>ZFTP_SESSION</tt>.
</p>
</dd>
<dt><tt>rmsession</tt> [ <var>sessname</var> ]</dt>
<dd><p>Delete a session; if a name is not given, the current session is deleted.
If the current session is deleted, the earliest existing session becomes
the new current session, otherwise the current session is not changed.
If the session being deleted is the only one, a new session called
‘<tt>default</tt>’ is created and becomes the current session; note that this is
a new session even if the session being deleted is also called
‘<tt>default</tt>’. It is recommended that sessions not be deleted while
background commands which use <tt>zftp</tt> are still active.
</p>
</dd>
</dl>
<hr>
<a name="Parameters-4"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Subcommands" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fzftp-Module" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#Functions-3" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h3 class="subsection">22.30.2 Parameters</h3>
<p><a name="index-zftp_002c-parameters"></a>
The following shell parameters are used by <tt>zftp</tt>. Currently none
of them are special.
</p>
<dl compact="compact">
<dd><a name="index-ZFTP_005fTMOUT"></a>
</dd>
<dt><tt>ZFTP_TMOUT</tt></dt>
<dd><p>Integer. The time in seconds to wait for a network operation to
complete before returning an error. If this is not set when the
module is loaded, it will be given the default value 60. A value of
zero turns off timeouts. If a timeout occurs on the control
connection it will be closed. Use a larger value if this occurs too
frequently.
</p>
<a name="index-ZFTP_005fIP"></a>
</dd>
<dt><tt>ZFTP_IP</tt></dt>
<dd><p>Readonly. The IP address of the current connection in dot notation.
</p>
<a name="index-ZFTP_005fHOST"></a>
</dd>
<dt><tt>ZFTP_HOST</tt></dt>
<dd><p>Readonly. The hostname of the current remote server. If the host was
opened as an IP number, <tt>ZFTP_HOST</tt> contains that instead; this
saves the overhead for a name lookup, as IP numbers are most commonly
used when a nameserver is unavailable.
</p>
<a name="index-ZFTP_005fPORT"></a>
</dd>
<dt><tt>ZFTP_PORT</tt></dt>
<dd><p>Readonly. The number of the remote TCP port to which the connection is
open (even if the port was originally specified as a named service).
Usually this is the standard FTP port, 21.
</p>
<p>In the unlikely event that your system does not have the appropriate
conversion functions, this appears in network byte order. If your
system is little-endian, the port then consists of two swapped bytes and the
standard port will be reported as 5376. In that case, numeric ports passed
to <tt>zftp open</tt> will also need to be in this format.
</p>
<a name="index-ZFTP_005fSYSTEM"></a>
</dd>
<dt><tt>ZFTP_SYSTEM</tt></dt>
<dd><p>Readonly. The system type string returned by the server in response
to an FTP <tt>SYST</tt> request. The most interesting case is a string
beginning <tt>"UNIX Type: L8"</tt>, which ensures maximum compatibility
with a local UNIX host.
</p>
<a name="index-ZFTP_005fTYPE"></a>
</dd>
<dt><tt>ZFTP_TYPE</tt></dt>
<dd><p>Readonly. The type to be used for data transfers , either ‘<tt>A</tt>’ or
‘<tt>I</tt>’. Use the <tt>type</tt> subcommand to change this.
</p>
<a name="index-ZFTP_005fUSER"></a>
</dd>
<dt><tt>ZFTP_USER</tt></dt>
<dd><p>Readonly. The username currently logged in, if any.
</p>
<a name="index-ZFTP_005fACCOUNT"></a>
</dd>
<dt><tt>ZFTP_ACCOUNT</tt></dt>
<dd><p>Readonly. The account name of the current user, if any. Most servers
do not require an account name.
</p>
<a name="index-ZFTP_005fPWD"></a>
</dd>
<dt><tt>ZFTP_PWD</tt></dt>
<dd><p>Readonly. The current directory on the server.
</p>
<a name="index-ZFTP_005fCODE"></a>
</dd>
<dt><tt>ZFTP_CODE</tt></dt>
<dd><p>Readonly. The three digit code of the last FTP reply from the server
as a string. This can still be read after the connection is closed, and
is not changed when the current session changes.
</p>
<a name="index-ZFTP_005fREPLY"></a>
</dd>
<dt><tt>ZFTP_REPLY</tt></dt>
<dd><p>Readonly. The last line of the last reply sent by the server. This
can still be read after the connection is closed, and is not changed when
the current session changes.
</p>
<a name="index-ZFTP_005fSESSION"></a>
</dd>
<dt><tt>ZFTP_SESSION</tt></dt>
<dd><p>Readonly. The name of the current FTP session; see the description of the
<tt>session</tt> subcommand.
</p>
<a name="index-ZFTP_005fPREFS"></a>
</dd>
<dt><tt>ZFTP_PREFS</tt></dt>
<dd><p>A string of preferences for altering aspects of <tt>zftp</tt>’s behaviour.
Each preference is a single character. The following are defined:
</p>
<dl compact="compact">
<dt><tt>P</tt></dt>
<dd><p>Passive: attempt to make the remote server initiate data transfers.
This is slightly more efficient than sendport mode. If the letter
<tt>S</tt> occurs later in the string, <tt>zftp</tt> will use sendport mode if
passive mode is not available.
</p>
</dd>
<dt><tt>S</tt></dt>
<dd><p>Sendport: initiate transfers by the FTP <tt>PORT</tt> command. If this
occurs before any <tt>P</tt> in the string, passive mode will never be
attempted.
</p>
</dd>
<dt><tt>D</tt></dt>
<dd><p>Dumb: use only the bare minimum of FTP commands. This prevents
the variables <tt>ZFTP_SYSTEM</tt> and <tt>ZFTP_PWD</tt> from being set, and
will mean all connections default to ASCII type. It may prevent
<tt>ZFTP_SIZE</tt> from being set during a transfer if the server
does not send it anyway (many servers do).
</p>
</dd>
</dl>
<p>If <tt>ZFTP_PREFS</tt> is not set when <tt>zftp</tt> is loaded, it will be set to a
default of ‘<tt>PS</tt>’, i.e. use passive mode if available, otherwise
fall back to sendport mode.
</p>
<a name="index-ZFTP_005fVERBOSE"></a>
</dd>
<dt><tt>ZFTP_VERBOSE</tt></dt>
<dd><p>A string of digits between 0 and 5 inclusive, specifying which
responses from the server should be printed. All responses go to
standard error. If any of the numbers 1 to 5 appear in the string,
raw responses from the server with reply codes beginning with that
digit will be printed to standard error. The first digit of the three
digit reply code is defined by RFC959 to correspond to:
</p>
<dl compact="compact">
<dt>1.</dt>
<dd><p>A positive preliminary reply.
</p>
</dd>
<dt>2.</dt>
<dd><p>A positive completion reply.
</p>
</dd>
<dt>3.</dt>
<dd><p>A positive intermediate reply.
</p>
</dd>
<dt>4.</dt>
<dd><p>A transient negative completion reply.
</p>
</dd>
<dt>5.</dt>
<dd><p>A permanent negative completion reply.
</p>
</dd>
</dl>
<p>It should be noted that, for unknown reasons, the reply ‘Service not
available’, which forces termination of a connection, is classified as
421, i.e. ‘transient negative’, an interesting interpretation of the word
‘transient’.
</p>
<p>The code 0 is special: it indicates that all but the last line of
multiline replies read from the server will be printed to standard
error in a processed format. By convention, servers use this
mechanism for sending information for the user to read. The
appropriate reply code, if it matches the same response, takes
priority.
</p>
<p>If <tt>ZFTP_VERBOSE</tt> is not set when <tt>zftp</tt> is loaded, it will be
set to the default value <tt>450</tt>, i.e., messages destined for the user
and all errors will be printed. A null string is valid and
specifies that no messages should be printed.
</p>
</dd>
</dl>
<hr>
<a name="Functions-3"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Parameters-4" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fzftp-Module" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#Problems" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h3 class="subsection">22.30.3 Functions</h3>
<p><a name="index-zftp_002c-functions"></a>
</p>
<dl compact="compact">
<dd><a name="index-zftp_005fchpwd_002c-specification"></a>
</dd>
<dt><tt>zftp_chpwd</tt></dt>
<dd><p>If this function is set by the user, it is called every time the
directory changes on the server, including when a user is logged
in, or when a connection is closed. In the last case, <tt>$ZFTP_PWD</tt>
will be unset; otherwise it will reflect the new directory.
</p>
<a name="index-zftp_005fprogress_002c-specification"></a>
</dd>
<dt><tt>zftp_progress</tt></dt>
<dd><p>If this function is set by the user, it will be called during
a <tt>get</tt>, <tt>put</tt> or <tt>append</tt> operation each time sufficient data
has been received from the host. During a <tt>get</tt>, the data is sent
to standard output, so it is vital that this function should write
to standard error or directly to the terminal, <em>not</em> to standard
output.
</p>
<p>When it is called with a transfer in progress, the following
additional shell parameters are set:
</p>
<dl compact="compact">
<dd><a name="index-ZFTP_005fFILE"></a>
</dd>
<dt><tt>ZFTP_FILE</tt></dt>
<dd><p>The name of the remote file being transferred from or to.
</p>
<a name="index-ZFTP_005fTRANSFER"></a>
</dd>
<dt><tt>ZFTP_TRANSFER</tt></dt>
<dd><p>A <tt>G</tt> for a <tt>get</tt> operation and a <tt>P</tt> for a <tt>put</tt> operation.
</p>
<a name="index-ZFTP_005fSIZE"></a>
</dd>
<dt><tt>ZFTP_SIZE</tt></dt>
<dd><p>The total size of the complete file being transferred:
the same as the first value provided by the
<tt>remote</tt> and <tt>local</tt> subcommands for a particular file.
If the server cannot supply this value for a remote file being
retrieved, it will not be set. If input is from a pipe the value may
be incorrect and correspond simply to a full pipe buffer.
</p>
<a name="index-ZFTP_005fCOUNT"></a>
</dd>
<dt><tt>ZFTP_COUNT</tt></dt>
<dd><p>The amount of data so far transferred; a number between zero and
<tt>$ZFTP_SIZE</tt>, if that is set. This number is always available.
</p>
</dd>
</dl>
<p>The function is initially called with <tt>ZFTP_TRANSFER</tt> set
appropriately and <tt>ZFTP_COUNT</tt> set to zero. After the transfer is
finished, the function will be called one more time with
<tt>ZFTP_TRANSFER</tt> set to <tt>GF</tt> or <tt>PF</tt>, in case it wishes to tidy
up. It is otherwise never called twice with the same value of
<tt>ZFTP_COUNT</tt>.
</p>
<p>Sometimes the progress meter may cause disruption. It is up to the
user to decide whether the function should be defined and to use
<tt>unfunction</tt> when necessary.
</p>
</dd>
</dl>
<hr>
<a name="Problems"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Functions-3" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fzftp-Module" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fzle-Module" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h3 class="subsection">22.30.4 Problems</h3>
<p><a name="index-zftp_002c-problems"></a>
</p>
<p>A connection may not be opened in the left hand side of a pipe as this
occurs in a subshell and the file information is not updated in the main
shell. In the case of type or mode changes or closing the connection in a
subshell, the information is returned but variables are not updated until
the next call to <tt>zftp</tt>. Other status changes in subshells will not be
reflected by changes to the variables (but should be otherwise harmless).
</p>
<p>Deleting sessions while a <tt>zftp</tt> command is active in the background can
have unexpected effects, even if it does not use the session being deleted.
This is because all shell subprocesses share information on the state of
all connections, and deleting a session changes the ordering of that
information.
</p>
<p>On some operating systems, the control connection is not valid after a
fork(), so that operations in subshells, on the left hand side
of a pipeline, or in the background are not possible, as they should be.
This is presumably a bug in the operating system.
</p><hr>
<a name="The-zsh_002fzle-Module"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Problems" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Zsh-Modules" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fzleparameter-Module" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="The-zsh_002fzle-Module-1"></a>
<h2 class="section">22.31 The zsh/zle Module</h2>
<p>The <tt>zsh/zle</tt> module contains the Zsh Line Editor. See
<a href="Zsh-Line-Editor.html#Zsh-Line-Editor">Zsh Line Editor</a>.
</p><hr>
<a name="The-zsh_002fzleparameter-Module"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fzle-Module" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Zsh-Modules" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fzprof-Module" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="The-zsh_002fzleparameter-Module-1"></a>
<h2 class="section">22.32 The zsh/zleparameter Module</h2>
<a name="index-parameters_002c-special-2"></a>
<p>The <tt>zsh/zleparameter</tt> module defines two special parameters that can be
used to access internal information of the Zsh Line Editor (see
<a href="Zsh-Line-Editor.html#Zsh-Line-Editor">Zsh Line Editor</a>).
</p>
<dl compact="compact">
<dd><a name="index-keymaps-2"></a>
</dd>
<dt><tt>keymaps</tt></dt>
<dd><p>This array contains the names of the keymaps currently defined.
</p>
<a name="index-widgets-1"></a>
</dd>
<dt><tt>widgets</tt></dt>
<dd><p>This associative array contains one entry per widget. The name
of the widget is the key and the value gives information about the
widget. It is either
the string ‘<tt>builtin</tt>’ for builtin widgets,
a string of the form ‘<tt>user:</tt><var>name</var>’ for user-defined widgets,
where <var>name</var> is the name of the shell function implementing the widget,
a string of the form ‘<tt>completion:</tt><var>type</var><tt>:</tt><var>name</var>’
for completion widgets,
or a null value if the widget is not yet fully defined.
In the penultimate case, <var>type</var> is the name of the builtin widget the
completion widget imitates in its behavior and <var>name</var> is the name
of the shell function implementing the completion widget.
</p>
</dd>
</dl>
<hr>
<a name="The-zsh_002fzprof-Module"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fzleparameter-Module" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Zsh-Modules" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fzpty-Module" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="The-zsh_002fzprof-Module-1"></a>
<h2 class="section">22.33 The zsh/zprof Module</h2>
<a name="index-functions_002c-profiling"></a>
<p>When loaded, the <tt>zsh/zprof</tt> causes shell functions to be profiled.
The profiling results can be obtained with the <tt>zprof</tt>
builtin command made available by this module. There is no way to turn
profiling off other than unloading the module.
</p>
<dl compact="compact">
<dd><a name="index-zprof"></a>
</dd>
<dt><tt>zprof</tt> [ <tt>-c</tt> ]</dt>
<dd><p>Without the <tt>-c</tt> option, <tt>zprof</tt> lists profiling results to
standard output. The format is comparable to that of commands like
<tt>gprof</tt>.
</p>
<p>At the top there is a summary listing all functions that were called
at least once. This summary is sorted in decreasing order of the
amount of time spent in each. The lines contain
the number of the function in order, which is used in
other parts of the list in suffixes of the form
‘<tt>[</tt><var>num</var><tt>]</tt>’, then the number of calls made to the function.
The next three columns list the time in
milliseconds spent in the function and its descendants, the average
time in milliseconds spent in the function and its descendants per
call and the percentage of time spent in all shell functions used in
this function and its descendants. The following three columns give
the same information, but counting only the time spent in the function
itself. The final column shows the name of the function.
</p>
<p>After the summary, detailed information about every function that was
invoked is listed, sorted in decreasing order of the amount of time spent
in each function and its descendants. Each of these entries consists of
descriptions for the functions that called the function described, the
function itself, and the functions that were called from it. The
description for the function itself has the same format as in the summary
(and shows the same information). The other lines don’t show the number of
the function at the beginning and have their function named indented to
make it easier to distinguish the line showing the function described in
the section from the surrounding lines.
</p>
<p>The information shown in this case is almost the same as in the summary,
but only refers to the call hierarchy being displayed. For example, for a
calling function the column showing the total running time lists the time
spent in the described function and its descendants only for the times when
it was called from that particular calling function. Likewise, for a
called function, this columns lists the total time spent in the called
function and its descendants only for the times when it was called from the
function described.
</p>
<p>Also in this case, the column showing the number of calls to a function
also shows a slash and then the total number of invocations made to the
called function.
</p>
<p>As long as the <tt>zsh/zprof</tt> module is loaded, profiling will be done and
multiple invocations of the <tt>zprof</tt> builtin command will show the
times and numbers of calls since the module was loaded. With the
<tt>-c</tt> option, the <tt>zprof</tt> builtin command will reset its internal
counters and will not show the listing.
</p>
</dd>
</dl>
<hr>
<a name="The-zsh_002fzpty-Module"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fzprof-Module" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Zsh-Modules" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fzselect-Module" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="The-zsh_002fzpty-Module-1"></a>
<h2 class="section">22.34 The zsh/zpty Module</h2>
<p>The <tt>zsh/zpty</tt> module offers one builtin:
</p>
<dl compact="compact">
<dd><a name="index-zpty"></a>
</dd>
<dt><tt>zpty</tt> [ <tt>-e</tt> ] [ <tt>-b</tt> ] <var>name</var> [ <var>arg</var> ... ]</dt>
<dd><p>The arguments following <var>name</var> are concatenated with spaces between,
then executed as a command, as if passed to the <tt>eval</tt> builtin. The
command runs under a newly assigned pseudo-terminal; this is useful for
running commands non-interactively which expect an interactive
environment. The <var>name</var> is not part of the command, but is used to
refer to this command in later calls to <tt>zpty</tt>.
</p>
<p>With the <tt>-e</tt> option, the pseudo-terminal is set up so that input
characters are echoed.
</p>
<p>With the <tt>-b</tt> option, input to and output from the pseudo-terminal are
made non-blocking.
</p>
<p>The shell parameter <tt>REPLY</tt> is set to the file descriptor assigned to
the master side of the pseudo-terminal. This allows the terminal to be
monitored with ZLE descriptor handlers (see <a href="Zsh-Line-Editor.html#Zle-Builtins">Zle Builtins</a>) or manipulated with <tt>sysread</tt> and
<tt>syswrite</tt> (see <a href="#The-zsh_002fsystem-Module">The zsh/system Module</a>). <em>Warning</em>: Use of <tt>sysread</tt>
and <tt>syswrite</tt> is <em>not</em> recommended, use <tt>zpty -r</tt> and <tt>zpty -w</tt>
unless you know exactly what you are doing.
</p>
</dd>
<dt><tt>zpty</tt> <tt>-d</tt> [ <var>name</var> ... ]</dt>
<dd><p>The second form, with the <tt>-d</tt> option, is used to delete commands
previously started, by supplying a list of their <var>name</var>s. If no
<var>name</var> is given, all commands are deleted. Deleting a command causes
the HUP signal to be sent to the corresponding process.
</p>
</dd>
<dt><tt>zpty</tt> <tt>-w</tt> [ <tt>-n</tt> ] <var>name</var> [ <var>string</var> ... ]</dt>
<dd><p>The <tt>-w</tt> option can be used to send the to command <var>name</var> the given
<var>string</var>s as input (separated by spaces). If the <tt>-n</tt> option is
<em>not</em> given, a newline is added at the end.
</p>
<p>If no <var>string</var> is provided, the standard input is copied to the
pseudo-terminal; this may stop before copying the full input if the
pseudo-terminal is non-blocking.
</p>
<p>Note that the command under the pseudo-terminal sees this input as if it
were typed, so beware when sending special tty driver characters such as
word-erase, line-kill, and end-of-file.
</p>
</dd>
<dt><tt>zpty</tt> <tt>-r</tt> [ <tt>-mt</tt> ] <var>name</var> [ <var>param</var> [ <var>pattern</var> ] ]</dt>
<dd><p>The <tt>-r</tt> option can be used to read the output of the command <var>name</var>.
With only a <var>name</var> argument, the output read is copied to the standard
output. Unless the pseudo-terminal is non-blocking, copying continues
until the command under the pseudo-terminal exits; when non-blocking, only
as much output as is immediately available is copied. The return status is
zero if any output is copied.
</p>
<p>When also given a <var>param</var> argument, at most one line is read and stored
in the parameter named <var>param</var>. Less than a full line may be read if
the pseudo-terminal is non-blocking. The return status is zero if at least
one character is stored in <var>param</var>.
</p>
<p>If a <var>pattern</var> is given as well, output is read until the whole string
read matches the <var>pattern</var>, even in the non-blocking case. The return
status is zero if the string read matches the pattern, or if the command
has exited but at least one character could still be read. If the option
<tt>-m</tt> is present, the return status is zero only if the pattern matches.
As of this writing, a maximum of one megabyte of output can be consumed
this way; if a full megabyte is read without matching the pattern, the
return status is non-zero.
</p>
<p>In all cases, the return status is non-zero if nothing could be read, and
is <tt>2</tt> if this is because the command has finished.
</p>
<p>If the <tt>-r</tt> option is combined with the <tt>-t</tt> option, <tt>zpty</tt> tests
whether output is available before trying to read. If no output is
available, <tt>zpty</tt> immediately returns the status <tt>1</tt>. When used
with a <var>pattern</var>, the behaviour on a failed poll is similar to
when the command has exited: the return value is zero if at least
one character could still be read even if the pattern failed to match.
</p>
</dd>
<dt><tt>zpty</tt> <tt>-t</tt> <var>name</var></dt>
<dd><p>The <tt>-t</tt> option without the <tt>-r</tt> option can be used to test
whether the command <var>name</var> is still running. It returns a zero
status if the command is running and a non-zero value otherwise.
</p>
</dd>
<dt><tt>zpty</tt> [ <tt>-L</tt> ]</dt>
<dd><p>The last form, without any arguments, is used to list the commands
currently defined. If the <tt>-L</tt> option is given, this is done in the
form of calls to the <tt>zpty</tt> builtin.
</p>
</dd>
</dl>
<hr>
<a name="The-zsh_002fzselect-Module"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fzpty-Module" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Zsh-Modules" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fzutil-Module" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="The-zsh_002fzselect-Module-1"></a>
<h2 class="section">22.35 The zsh/zselect Module</h2>
<p>The <tt>zsh/zselect</tt> module makes available one builtin command:
</p>
<dl compact="compact">
<dd><a name="index-zselect"></a>
<a name="index-select_002c-system-call"></a>
<a name="index-file-descriptors_002c-waiting-for"></a>
</dd>
<dt><tt>zselect</tt> [ <tt>-rwe</tt> ] [ <tt>-t</tt> <var>timeout</var> ] [ <tt>-a</tt> <var>array</var> ] [ <tt>-A</tt> <var>assoc</var> ] [ <var>fd</var> ... ]</dt>
<dd><p>The <tt>zselect</tt> builtin is a front-end to the ‘select’ system call, which
blocks until a file descriptor is ready for reading or writing, or has an
error condition, with an optional timeout. If this is not available on
your system, the command prints an error message and returns status 2
(normal errors return status 1). For more information, see your systems
documentation for man page select(3). Note there is no connection with the
shell builtin of the same name.
</p>
<p>Arguments and options may be intermingled in any order. Non-option
arguments are file descriptors, which must be decimal integers. By
default, file descriptors are to be tested for reading, i.e. <tt>zselect</tt>
will return when data is available to be read from the file descriptor, or
more precisely, when a read operation from the file descriptor will not
block. After a <tt>-r</tt>, <tt>-w</tt> and <tt>-e</tt>, the given file descriptors are
to be tested for reading, writing, or error conditions. These options and
an arbitrary list of file descriptors may be given in any order.
</p>
<p>(The presence of an ‘error condition’ is not well defined in the
documentation for many implementations of the select system call.
According to recent versions of the POSIX specification, it is really an
<em>exception</em> condition, of which the only standard example is out-of-band
data received on a socket. So zsh users are unlikely to find the <tt>-e</tt>
option useful.)
</p>
<p>The option ‘<tt>-t</tt> <var>timeout</var>’ specifies a timeout in hundredths of a
second. This may be zero, in which case the file descriptors will simply
be polled and <tt>zselect</tt> will return immediately. It is possible to call
zselect with no file descriptors and a non-zero timeout for use as a
finer-grained replacement for ‘sleep’; note, however, the return status is
always 1 for a timeout.
</p>
<p>The option ‘<tt>-a</tt> <var>array</var>’ indicates that <var>array</var> should be set to
indicate the file descriptor(s) which are ready. If the option
is not
given, the array <tt>reply</tt> will be used for this purpose. The array will
contain a string similar to the arguments for <tt>zselect</tt>. For example,
</p>
<div class="example">
<pre class="example">zselect -t 0 -r 0 -w 1
</pre></div>
<p>might return immediately with status 0 and <tt>$reply</tt> containing ‘<tt>-r 0 -w
1</tt>’ to show that both file descriptors are ready for the requested
operations.
</p>
<p>The option ‘<tt>-A</tt> <var>assoc</var>’ indicates that the associative array
<var>assoc</var> should be set to indicate the file descriptor(s)
which are ready. This option overrides the option <tt>-a</tt>, nor will
<tt>reply</tt> be modified. The keys of <tt>assoc</tt> are the file descriptors, and
the corresponding values are any of the characters ‘<tt>rwe</tt>’ to indicate
the condition.
</p>
<p>The command returns status 0 if some file descriptors are ready for
reading. If the operation timed out, or a timeout of 0 was given and no
file descriptors were ready, or there was an error, it returns status 1 and
the array will not be set (nor modified in any way). If there was an error
in the select operation the appropriate error message is printed.
</p>
</dd>
</dl>
<hr>
<a name="The-zsh_002fzutil-Module"></a>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#The-zsh_002fzselect-Module" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Zsh-Modules" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="The-zsh_002fzutil-Module-1"></a>
<h2 class="section">22.36 The zsh/zutil Module</h2>
<a name="index-builtins_002c-utility"></a>
<p>The <tt>zsh/zutil</tt> module only adds some builtins:
</p>
<dl compact="compact">
<dd><a name="index-zstyle"></a>
</dd>
<dt><tt>zstyle</tt> [ <tt>-L</tt> [ <var>pattern</var> [ <var>style</var> ] ] ]</dt>
<dt><tt>zstyle</tt> [ <tt>-e</tt> | <tt>-</tt> | <tt>-</tt><tt>-</tt> ] <var>pattern</var> <var>style</var> <var>string</var> ...</dt>
<dt><tt>zstyle -d</tt> [ <var>pattern</var> [ <var>style</var> ... ] ]</dt>
<dt><tt>zstyle -g</tt> <var>name</var> [ <var>pattern</var> [ <var>style</var> ] ]</dt>
<dt><tt>zstyle -</tt>{<tt>a</tt>|<tt>b</tt>|<tt>s</tt>} <var>context</var> <var>style</var> <var>name</var> [ <var>sep</var> ]</dt>
<dt><tt>zstyle -</tt>{<tt>T</tt>|<tt>t</tt>} <var>context</var> <var>style</var> [ <var>string</var> ... ]</dt>
<dt><tt>zstyle -m</tt> <var>context</var> <var>style</var> <var>pattern</var></dt>
<dd><p>This builtin command is used to define and lookup styles. Styles are
pairs of names and values, where the values consist of any number of
strings. They are stored together with patterns and lookup is done by
giving a string, called the ‘context’, which is compared to the
patterns. The definition stored for the first matching pattern will be
returned.
</p>
<p>For ordering of comparisons, patterns are searched from most specific to
least specific, and patterns that are equally specific keep the order in
which they were defined. A pattern is considered to be more specific
than another if it contains more components (substrings separated by
colons) or if the patterns for the components are more specific, where
simple strings are considered to be more specific than patterns and
complex patterns are considered to be more specific than the pattern
‘<tt>*</tt>’.
</p>
<p>The first form (without arguments) lists the definitions. Styles
are shown in alphabetic order and patterns are shown in the order
<tt>zstyle</tt> will test them.
</p>
<p>If the <tt>-L</tt> option is given, listing is done in the form of calls to
<tt>zstyle</tt>. The optional first argument is a pattern which will be matched
against the string supplied as the pattern for the context; note that
this means, for example, ‘<tt>zstyle -L ":completion:*"</tt>’ will
match any supplied pattern beginning ‘<tt>:completion:</tt>’, not
just <tt>":completion:*"</tt>: use <tt>":completion:\*"</tt> to match that.
The optional second argument limits the output to a specific <var>style</var> (not a
pattern). <tt>-L</tt> is not compatible with any other options.
</p>
<p>The other forms are the following:
</p>
<dl compact="compact">
<dt><tt>zstyle</tt> [ <tt>-</tt> | <tt>-</tt><tt>-</tt> | <tt>-e</tt> ] <var>pattern</var> <var>style</var> <var>string</var> ...</dt>
<dd><a name="index-reply_002c-use-of-4"></a>
<p>Defines the given <var>style</var> for the <var>pattern</var> with the <var>string</var>s as
the value. If the <tt>-e</tt> option is given, the <var>string</var>s will be
concatenated (separated by spaces) and the resulting string will be
evaluated (in the same way as it is done by the <tt>eval</tt> builtin
command) when the style is looked up. In this case the parameter
‘<tt>reply</tt>’ must be assigned to set the strings returned after the
evaluation. Before evaluating the value, <tt>reply</tt> is unset, and
if it is still unset after the evaluation, the style is treated as if
it were not set.
</p>
</dd>
<dt><tt>zstyle -d</tt> [ <var>pattern</var> [ <var>style</var> ... ] ]</dt>
<dd><p>Delete style definitions. Without arguments all definitions are deleted,
with a <var>pattern</var> all definitions for that pattern are deleted and if
any <var>style</var>s are given, then only those styles are deleted for the
<var>pattern</var>.
</p>
</dd>
<dt><tt>zstyle -g</tt> <var>name</var> [ <var>pattern</var> [ <var>style</var> ] ]</dt>
<dd><p>Retrieve a style definition. The <var>name</var> is
used as the name of an array in which the results are stored. Without
any further arguments, all patterns defined are returned. With a
<var>pattern</var> the styles defined for that pattern are returned and with
both a <var>pattern</var> and a <var>style</var>, the value strings of that
combination is returned.
</p>
</dd>
</dl>
<p>The other forms can be used to look up or test patterns.
</p>
<dl compact="compact">
<dt><tt>zstyle -s</tt> <var>context</var> <var>style</var> <var>name</var> [ <var>sep</var> ]</dt>
<dd><p>The parameter <var>name</var> is set to the value of the style interpreted as a
string. If the value contains several strings they are concatenated with
spaces (or with the <var>sep</var> string if that is given) between them.
</p>
</dd>
<dt><tt>zstyle -b</tt> <var>context</var> <var>style</var> <var>name</var></dt>
<dd><p>The value is stored in <var>name</var> as a boolean, i.e. as the string
‘<tt>yes</tt>’ if the value has only one string and that string is equal to one
of ‘<tt>yes</tt>’, ‘<tt>true</tt>’, ‘<tt>on</tt>’, or ‘<tt>1</tt>’. If the value is any other
string or has more than one string, the parameter is set to ‘<tt>no</tt>’.
</p>
</dd>
<dt><tt>zstyle -a</tt> <var>context</var> <var>style</var> <var>name</var></dt>
<dd><p>The value is stored in <var>name</var> as an array. If <var>name</var> is declared
as an associative array, the first, third, etc. strings are used as the
keys and the other strings are used as the values.
</p>
</dd>
<dt><tt>zstyle -t</tt> <var>context</var> <var>style</var> [ <var>string</var> ... ]</dt>
<dt><tt>zstyle -T</tt> <var>context</var> <var>style</var> [ <var>string</var> ... ]</dt>
<dd><p>Test the value of a style, i.e. the <tt>-t</tt> option only returns a status
(sets <tt>$?</tt>). Without any <var>string</var> the return status is zero if the
style is defined for at least one matching pattern, has only one string in
its value, and that is equal to one of ‘<tt>true</tt>’, ‘<tt>yes</tt>’, ‘<tt>on</tt>’ or
‘<tt>1</tt>’. If any <var>string</var>s are given the status is zero if and only if
at least one of the <var>string</var>s is equal to at least one of the strings
in the value. If the style is defined but doesn’t match, the return status
is <tt>1</tt>. If the style is not defined, the status is <tt>2</tt>.
</p>
<p>The <tt>-T</tt> option tests the values of the style like <tt>-t</tt>, but it
returns status zero (rather than <tt>2</tt>) if the style is not defined for any
matching pattern.
</p>
</dd>
<dt><tt>zstyle -m</tt> <var>context</var> <var>style</var> <var>pattern</var></dt>
<dd><p>Match a value. Returns status zero if the
<var>pattern</var> matches at least one of the strings in the value.
</p>
</dd>
</dl>
<a name="index-zformat"></a>
</dd>
<dt><tt>zformat -f</tt> <var>param</var> <var>format</var> <var>spec</var> ...</dt>
<dt><tt>zformat -a</tt> <var>array</var> <var>sep</var> <var>spec</var> ...</dt>
<dd><p>This builtin provides two different forms of formatting. The first form
is selected with the <tt>-f</tt> option. In this case the <var>format</var>
string will be modified by replacing sequences starting with a percent
sign in it with strings from the <var>spec</var>s. Each <var>spec</var> should be
of the form ‘<var>char</var><tt>:</tt><var>string</var>’ which will cause every
appearance of the sequence ‘<tt>%</tt><var>char</var>’ in <var>format</var> to be replaced
by the <var>string</var>. The ‘<tt>%</tt>’ sequence may also contain optional
minimum and maximum field width specifications between the ‘<tt>%</tt>’ and
the ‘<var>char</var>’ in the form ‘<tt>%</tt><var>min</var><tt>.</tt><var>max</var><tt>c</tt>’,
i.e. the minimum field width is given first and if the maximum field
width is used, it has to be preceded by a dot. Specifying a minimum field
width makes the result be padded with spaces to the right if the
<var>string</var> is shorter than the requested width. Padding to the left
can be achieved by giving a negative minimum field width. If a maximum
field width is specified, the <var>string</var> will be truncated after that
many characters. After all ‘<tt>%</tt>’ sequences for the given <var>spec</var>s
have been processed, the resulting string is stored in the parameter
<var>param</var>.
</p>
<p>The <tt>%</tt>-escapes also understand ternary expressions in the form used by
prompts. The <tt>%</tt> is followed by a ‘<tt>(</tt>’ and then an ordinary
format specifier character as described above. There may be a set of
digits either before or after the ‘<tt>(</tt>’; these specify a test
number, which defaults to zero. Negative numbers are also allowed. An
arbitrary delimiter character follows the format specifier, which is
followed by a piece of ‘true’ text, the delimiter character again, a piece
of ‘false’ text, and a closing parenthesis. The complete expression
(without the digits) thus looks like
‘<tt>%(</tt><var>X</var><tt>.</tt><var>text1</var><tt>.</tt><var>text2</var><tt>)</tt>’, except that
the ‘<tt>.</tt>’ character is arbitrary. The value given for the format
specifier in the <var>char</var><tt>:</tt><var>string</var> expressions is evaluated as a
mathematical expression, and compared with the test number. If they are
the same, <var>text1</var> is output, else <var>text2</var> is output. A parenthesis
may be escaped in <var>text2</var> as <tt>%)</tt>. Either of <var>text1</var> or
<var>text2</var> may contain nested <tt>%</tt>-escapes.
</p>
<p>For example:
</p>
<div class="example">
<pre class="example">zformat -f REPLY "The answer is '%3(c.yes.no)'." c:3
</pre></div>
<p>outputs "The answer is ’yes’." to <tt>REPLY</tt> since the value for the format
specifier <tt>c</tt> is 3, agreeing with the digit argument to the ternary
expression.
</p>
<p>The second form, using the <tt>-a</tt> option, can be used for aligning
strings. Here, the <var>spec</var>s are of the form
‘<var>left</var><tt>:</tt><var>right</var>’ where ‘<var>left</var>’ and ‘<var>right</var>’ are
arbitrary strings. These strings are modified by replacing the colons
by the <var>sep</var> string and padding the <var>left</var> strings with spaces
to the right so that the <var>sep</var> strings in the result (and hence the
<var>right</var> strings after them) are all aligned if the strings are
printed below each other. All strings without a colon are left
unchanged and all strings with an empty <var>right</var> string have the
trailing colon removed. In both cases the lengths of the strings
are not used to determine how the other strings are to be aligned.
The resulting strings are stored in the <var>array</var>.
</p>
<a name="index-zregexparse"></a>
</dd>
<dt><tt>zregexparse</tt></dt>
<dd><p>This implements some internals of the <tt>_regex_arguments</tt> function.
</p>
<a name="index-zparseopts"></a>
</dd>
<dt><tt>zparseopts</tt> [ <tt>-D</tt> <tt>-K</tt> <tt>-M</tt> <tt>-E</tt> ] [ <tt>-a</tt> <var>array</var> ] [ <tt>-A</tt> <var>assoc</var> ] [ <tt>-</tt> ] <var>spec</var> ...</dt>
<dd><p>This builtin simplifies the parsing of options in positional parameters,
i.e. the set of arguments given by <tt>$*</tt>. Each <var>spec</var> describes one
option and must be of the form ‘<var>opt</var>[<tt>=</tt><var>array</var>]’. If an option
described by <var>opt</var> is found in the positional parameters it is copied
into the <var>array</var> specified with the <tt>-a</tt> option; if the optional
‘<tt>=</tt><var>array</var>’ is given, it is instead copied into that array, which
should be declared as a normal array and never as an associative array.
</p>
<p>Note that it is an error to give any <var>spec</var> without an
‘<tt>=</tt><var>array</var>’ unless one of the <tt>-a</tt> or <tt>-A</tt> options is used.
</p>
<p>Unless the <tt>-E</tt> option is given, parsing stops at the first string
that isn’t described by one of the <var>spec</var>s. Even with <tt>-E</tt>,
parsing always stops at a positional parameter equal to ‘<tt>-</tt>’ or
‘<tt>-</tt><tt>-</tt>’.
</p>
<p>The <var>opt</var> description must be one of the following. Any of the special
characters can appear in the option name provided it is preceded by a
backslash.
</p>
<dl compact="compact">
<dt><var>name</var></dt>
<dt><var>name</var><tt>+</tt></dt>
<dd><p>The <var>name</var> is the name of the option without the leading ‘<tt>-</tt>’. To
specify a GNU-style long option, one of the usual two leading ‘<tt>-</tt>’ must
be included in <var>name</var>; for example, a ‘<tt>-</tt><tt>-file</tt>’ option is
represented by a <var>name</var> of ‘<tt>-file</tt>’.
</p>
<p>If a ‘<tt>+</tt>’ appears after <var>name</var>, the option is appended to <var>array</var>
each time it is found in the positional parameters; without the ‘<tt>+</tt>’
only the <em>last</em> occurrence of the option is preserved.
</p>
<p>If one of these forms is used, the option takes no argument, so parsing
stops if the next positional parameter does not also begin with ‘<tt>-</tt>’
(unless the <tt>-E</tt> option is used).
</p>
</dd>
<dt><var>name</var><tt>:</tt></dt>
<dt><var>name</var><tt>:-</tt></dt>
<dt><var>name</var><tt>::</tt></dt>
<dd><p>If one or two colons are given, the option takes an argument; with one
colon, the argument is mandatory and with two colons it is optional. The
argument is appended to the <var>array</var> after the option itself.
</p>
<p>An optional argument is put into the same array element as the option name
(note that this makes empty strings as arguments indistinguishable). A
mandatory argument is added as a separate element unless the ‘<tt>:-</tt>’ form
is used, in which case the argument is put into the same element.
</p>
<p>A ‘<tt>+</tt>’ as described above may appear between the <var>name</var> and the
first colon.
</p>
</dd>
</dl>
<p>The options of <tt>zparseopts</tt> itself cannot be stacked because, for
example, the stack ‘<tt>-DEK</tt>’ is indistinguishable from a <var>spec</var> for
the GNU-style long option ‘<tt>--DEK</tt>’. The options of <tt>zparseopts</tt>
itself are:
</p>
<dl compact="compact">
<dt><tt>-a</tt> <var>array</var></dt>
<dd><p>As described above, this names the default array in which to store the
recognised options.
</p>
</dd>
<dt><tt>-A</tt> <var>assoc</var></dt>
<dd><p>If this is given, the options and their values are also put into an
associative array with the option names as keys and the arguments (if any)
as the values.
</p>
</dd>
<dt><tt>-D</tt></dt>
<dd><p>If this option is given, all options found are removed from the positional
parameters of the calling shell or shell function, up to but not including
any not described by the <var>spec</var>s. This is similar to using the <tt>shift</tt>
builtin.
</p>
</dd>
<dt><tt>-K</tt></dt>
<dd><p>With this option, the arrays specified with the <tt>-a</tt> option and with the
‘<tt>=</tt><var>array</var>’ forms are kept unchanged when none of the <var>spec</var>s for
them is used. Otherwise the entire array is replaced when any of the
<var>spec</var>s is used. Individual elements of associative arrays specified
with the <tt>-A</tt> option are preserved by <tt>-K</tt>. This allows assignment of
default values to arrays before calling <tt>zparseopts</tt>.
</p>
</dd>
<dt><tt>-M</tt></dt>
<dd><p>This changes the assignment rules to implement a map among equivalent
option names. If any <var>spec</var> uses the ‘<tt>=</tt><var>array</var>’ form, the
string <var>array</var> is interpreted as the name of another <var>spec</var>,
which is used to choose where to store the values. If no other <var>spec</var>
is found, the values are stored as usual. This changes only the way the
values are stored, not the way <tt>$*</tt> is parsed, so results may be
unpredictable if the ‘<var>name</var><tt>+</tt>’ specifier is used inconsistently.
</p>
</dd>
<dt><tt>-E</tt></dt>
<dd><p>This changes the parsing rules to <em>not</em> stop at the first string
that isn’t described by one of the <var>spec</var>s. It can be used to test
for or (if used together with <tt>-D</tt>) extract options and their
arguments, ignoring all other options and arguments that may be in the
positional parameters.
</p>
</dd>
</dl>
<p>For example,
</p>
<div class="example">
<pre class="example">set -- -a -bx -c y -cz baz -cend
zparseopts a=foo b:=bar c+:=bar
</pre></div>
<p>will have the effect of
</p>
<div class="example">
<pre class="example">foo=(-a)
bar=(-b x -c y -c z)
</pre></div>
<p>The arguments from ‘<tt>baz</tt>’ on will not be used.
</p>
<p>As an example for the <tt>-E</tt> option, consider:
</p>
<div class="example">
<pre class="example">set -- -a x -b y -c z arg1 arg2
zparseopts -E -D b:=bar
</pre></div>
<p>will have the effect of
</p>
<div class="example">
<pre class="example">bar=(-b y)
set -- -a x -c z arg1 arg2
</pre></div>
<p>I.e., the option <tt>-b</tt> and its arguments are taken from the
positional parameters and put into the array <tt>bar</tt>.
</p>
<p>The <tt>-M</tt> option can be used like this:
</p>
<div class="example">
<pre class="example">set -- -a -bx -c y -cz baz -cend
zparseopts -A bar -M a=foo b+: c:=b
</pre></div>
<p>to have the effect of
</p>
<div class="example">
<pre class="example">foo=(-a)
bar=(-a '' -b xyz)
</pre></div>
</dd>
</dl>
<hr>
<table class="header" cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Zsh-Modules" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="Calendar-Function-System.html#Calendar-Function-System" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="zsh_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concept-Index.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="zsh_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<p><font size="-1">
This document was generated on <em>September 10, 2018</em> using <a href="http://www.gnu.org/software/texinfo/"><em>texi2any</em></a>.
</font></p>
<font size="-1">Zsh version 5.4.2, released on August 27, 2017.</font>
</body>
</html>
|