1#LyX 2.3 created this file. For more info see http://www.lyx.org/ 2\lyxformat 544 3\begin_document 4\begin_header 5\save_transient_properties true 6\origin unavailable 7\textclass article 8\use_default_options true 9\maintain_unincluded_children false 10\language english 11\language_package default 12\inputencoding utf8 13\fontencoding global 14\font_roman "lmodern" "default" 15\font_sans "lmss" "default" 16\font_typewriter "lmtt" "default" 17\font_math "auto" "auto" 18\font_default_family default 19\use_non_tex_fonts false 20\font_sc false 21\font_osf false 22\font_sf_scale 100 100 23\font_tt_scale 100 100 24\use_microtype false 25\use_dash_ligatures true 26\graphics default 27\default_output_format default 28\output_sync 0 29\bibtex_command default 30\index_command default 31\paperfontsize 12 32\spacing single 33\use_hyperref true 34\pdf_bookmarks false 35\pdf_bookmarksnumbered false 36\pdf_bookmarksopen false 37\pdf_bookmarksopenlevel 1 38\pdf_breaklinks false 39\pdf_pdfborder true 40\pdf_colorlinks false 41\pdf_backref page 42\pdf_pdfusetitle true 43\papersize a4paper 44\use_geometry true 45\use_package amsmath 1 46\use_package amssymb 1 47\use_package cancel 1 48\use_package esint 1 49\use_package mathdots 1 50\use_package mathtools 1 51\use_package mhchem 1 52\use_package stackrel 1 53\use_package stmaryrd 1 54\use_package undertilde 1 55\cite_engine natbib 56\cite_engine_type numerical 57\biblio_style plainnat 58\use_bibtopic false 59\use_indices false 60\paperorientation portrait 61\suppress_date false 62\justification true 63\use_refstyle 0 64\use_minted 0 65\index Index 66\shortcut idx 67\color #008000 68\end_index 69\leftmargin 2cm 70\topmargin 2cm 71\rightmargin 2cm 72\bottommargin 2cm 73\secnumdepth 3 74\tocdepth 1 75\paragraph_separation indent 76\paragraph_indentation default 77\is_math_indent 0 78\math_numbering_side default 79\quotes_style english 80\dynamic_quotes 0 81\papercolumns 1 82\papersides 1 83\paperpagestyle default 84\tracking_changes false 85\output_changes false 86\html_math_output 0 87\html_css_as_file 0 88\html_be_strict false 89\end_header 90 91\begin_body 92 93\begin_layout Title 94libHX 3.25 95\begin_inset Newline newline 96\end_inset 97 98Documentation 99\end_layout 100 101\begin_layout Standard 102\begin_inset VSpace defskip 103\end_inset 104 105 106\end_layout 107 108\begin_layout Standard 109\begin_inset CommandInset toc 110LatexCommand tableofcontents 111 112\end_inset 113 114 115\end_layout 116 117\begin_layout Standard 118\begin_inset Newpage clearpage 119\end_inset 120 121 122\end_layout 123 124\begin_layout Section 125Introduction 126\end_layout 127 128\begin_layout Standard 129libHX collects many useful day-to-day functions, intended to reduce the 130 amount of otherwise repeatedly open-coded instructions. 131\end_layout 132 133\begin_layout Section 134Overview 135\end_layout 136 137\begin_layout Itemize 138Maps (key-value pairs) (section 139\begin_inset space ~ 140\end_inset 141 142 143\begin_inset CommandInset ref 144LatexCommand ref 145reference "sec:maps" 146 147\end_inset 148 149) 150\begin_inset Newline newline 151\end_inset 152 153Originally created to provide a data structure like Perl's associative arrays. 154 Different map types and characteristics are available, such as hash-based 155 or the traditional rbtree. 156\end_layout 157 158\begin_layout Itemize 159Deques (section 160\begin_inset space ~ 161\end_inset 162 163 164\begin_inset CommandInset ref 165LatexCommand ref 166reference "sec:deque" 167 168\end_inset 169 170) 171\begin_inset Newline newline 172\end_inset 173 174Double-ended queues, implemented as a doubly-linked list with sentinels, 175 are suitable for both providing stack and queue functionality. 176\end_layout 177 178\begin_layout Itemize 179Inline doubly-linked list, uncounted and counted (sections 180\begin_inset space ~ 181\end_inset 182 183 184\begin_inset CommandInset ref 185LatexCommand ref 186reference "sec:list" 187 188\end_inset 189 190 and 191\begin_inset space ~ 192\end_inset 193 194 195\begin_inset CommandInset ref 196LatexCommand ref 197reference "sec:clist" 198 199\end_inset 200 201) 202\begin_inset Newline newline 203\end_inset 204 205Light-weight linked lists as used in the Linux kernel. 206\end_layout 207 208\begin_layout Itemize 209Common string operations (section 210\begin_inset space ~ 211\end_inset 212 213 214\begin_inset CommandInset ref 215LatexCommand ref 216reference "sec:strings" 217 218\end_inset 219 220) 221\begin_inset Newline newline 222\end_inset 223 224basename, chomp, dirname, getl(ine), split, strlcat/strlcpy, strlower/-upper, 225 str*trim, strsep, etc. 226\end_layout 227 228\begin_layout Itemize 229Memory containers, auto-sizing string operations (section 230\begin_inset space ~ 231\end_inset 232 233 234\begin_inset CommandInset ref 235LatexCommand ref 236reference "sec:mc" 237 238\end_inset 239 240) 241\begin_inset Newline newline 242\end_inset 243 244Scripting-like invocation for string handling 245\begin_inset space ~ 246\end_inset 247 248— automatically doing (re)allocations as needed. 249\end_layout 250 251\begin_layout Itemize 252String formatter (section 253\begin_inset space ~ 254\end_inset 255 256 257\begin_inset CommandInset ref 258LatexCommand ref 259reference "sec:format" 260 261\end_inset 262 263) 264\begin_inset Newline newline 265\end_inset 266 267HXfmt is a small template system for by-name variable expansion. 268 It can be used to substitute placeholders in format strings supplied by 269 the user by appropriate expanded values defined by the program. 270\end_layout 271 272\begin_layout Itemize 273Directory creation, traversal, removal, and file copying (sections 274\begin_inset space ~ 275\end_inset 276 277 278\begin_inset CommandInset ref 279LatexCommand ref 280reference "sec:dir-ops1" 281 282\end_inset 283 284, 285\begin_inset CommandInset ref 286LatexCommand ref 287reference "sec:dir-ops2" 288 289\end_inset 290 291 and 292\begin_inset space ~ 293\end_inset 294 295 296\begin_inset CommandInset ref 297LatexCommand ref 298reference "sec:file-ops" 299 300\end_inset 301 302) 303\end_layout 304 305\begin_layout Itemize 306Option parsing (section 307\begin_inset space ~ 308\end_inset 309 310 311\begin_inset CommandInset ref 312LatexCommand ref 313reference "sec:option" 314 315\end_inset 316 317) 318\begin_inset Newline newline 319\end_inset 320 321Table-/callback-based option parser that works similar to Perl's 322\family typewriter 323Getopt::Long 324\family default 325 326\begin_inset space ~ 327\end_inset 328 329— no open-coding but a single 330\begin_inset Quotes eld 331\end_inset 332 333atomic 334\begin_inset Quotes erd 335\end_inset 336 337 invocation. 338\end_layout 339 340\begin_layout Itemize 341Shell-style config parser (section 342\begin_inset space ~ 343\end_inset 344 345 346\begin_inset CommandInset ref 347LatexCommand ref 348reference "sec:shconf" 349 350\end_inset 351 352) 353\begin_inset Newline newline 354\end_inset 355 356Configuration file reader for Shell-style 357\begin_inset Quotes eld 358\end_inset 359 360configuration 361\begin_inset Quotes erd 362\end_inset 363 364 files with key-value pairs, as usually foudn in 365\family typewriter 366/etc\SpecialChar breakableslash 367sysconfig 368\family default 369. 370\end_layout 371 372\begin_layout Itemize 373Random number gathering (section 374\begin_inset space ~ 375\end_inset 376 377 378\begin_inset CommandInset ref 379LatexCommand ref 380reference "sec:random" 381 382\end_inset 383 384) 385\begin_inset Newline newline 386\end_inset 387 388Convenient wrapper that uses kernel-provided RNG devices when available. 389\end_layout 390 391\begin_layout Itemize 392External process invocation (section 393\begin_inset space ~ 394\end_inset 395 396 397\begin_inset CommandInset ref 398LatexCommand ref 399reference "sec:proc" 400 401\end_inset 402 403) 404\begin_inset Newline newline 405\end_inset 406 407Setting up pipes for the standard file descriptors for sending/capturing 408 data to/from a program. 409\end_layout 410 411\begin_layout Itemize 412 413\shape italic 414a bit more beyond that ... 415 Miscellaneous 416\end_layout 417 418\begin_layout Section 419Resources 420\end_layout 421 422\begin_layout Standard 423As of this writing, the repository is located at 424\end_layout 425 426\begin_layout Itemize 427\begin_inset Flex URL 428status open 429 430\begin_layout Plain Layout 431 432git://libhx.git.sf.net/gitroot/libhx/libhx 433\end_layout 434 435\end_inset 436 437 438\begin_inset space ~ 439\end_inset 440 441— clone URL 442\end_layout 443 444\begin_layout Itemize 445\begin_inset Flex URL 446status open 447 448\begin_layout Plain Layout 449 450http://libhx.git.sf.net/ 451\end_layout 452 453\end_inset 454 455 456\begin_inset space ~ 457\end_inset 458 459— gitweb interface 460\end_layout 461 462\begin_layout Itemize 463\begin_inset Flex URL 464status open 465 466\begin_layout Plain Layout 467 468http://libhx.sf.net/ 469\end_layout 470 471\end_inset 472 473 474\begin_inset space ~ 475\end_inset 476 477— home page (and link to tarballs) 478\end_layout 479 480\begin_layout Itemize 481\begin_inset Flex URL 482status open 483 484\begin_layout Plain Layout 485 486http://freecode.com/projects/libhx/ 487\end_layout 488 489\end_inset 490 491 492\begin_inset space ~ 493\end_inset 494 495— Freecode page (useful for automatic notification of new releases) 496\end_layout 497 498\begin_layout Section 499Installation 500\end_layout 501 502\begin_layout Standard 503libHX uses GNU autotools as a build environment, which means that all you 504 have to run as a end-user is the 505\family typewriter 506configure 507\family default 508 with any options that you need, plus the usual 509\family typewriter 510make 511\family default 512 and 513\family typewriter 514make install 515\family default 516 as desired. 517\end_layout 518 519\begin_layout Standard 520Pay attention to multi-lib Linux distributions where you most likely need 521 to specify a different libdir instead of using the default 522\begin_inset Quotes eld 523\end_inset 524 525lib 526\begin_inset Quotes erd 527\end_inset 528 529. 530 In case of the Debian-style multi-arch/multi-lib proposal ( 531\begin_inset Flex URL 532status collapsed 533 534\begin_layout Plain Layout 535 536http://wiki.debian.org/Multiarch 537\end_layout 538 539\end_inset 540 541): 542\end_layout 543 544\begin_layout LyX-Code 545$ 546\series bold 547./configure --libdir='${prefix}/lib/x86_64-linux-gnu' 548\end_layout 549 550\begin_layout Standard 551and the classic-style 32-64 2-lib distributions: 552\end_layout 553 554\begin_layout LyX-Code 555$ 556\series bold 557./configure --libdir='${prefix}/lib64' 558\end_layout 559 560\begin_layout Subsection 561Requirements 562\end_layout 563 564\begin_layout Itemize 565GNU C Compiler 3.3.5 or newer. 566 Other compilers (non-GCC) have not been tested in months 567\begin_inset space ~ 568\end_inset 569 570— use at your own risk. 571\end_layout 572 573\begin_layout Itemize 574approximately 80–160 575\begin_inset space ~ 576\end_inset 577 578KB of disk space on Linux for the shared library (depends on platform) and 579 header files. 580\end_layout 581 582\begin_layout Standard 583A C++ compiler is only needed if you want to build the C++ test programs 584 that come with libHX. 585 By default, if there is no C++ compiler present, these will not be built. 586\end_layout 587 588\begin_layout Itemize 589No external libraries are needed for compilation of libHX. 590 Helper files, like 591\family typewriter 592libxml_\SpecialChar softhyphen 593helper.h 594\family default 595, may reference their include files, but they are not used during compilation. 596\end_layout 597 598\begin_layout Section 599Portability notice 600\end_layout 601 602\begin_layout Standard 603libHX runs on contemporary versions of Linux, Solaris and the three BSD 604 distributions. 605 It might even work on Microsoft Windows, but this is not tested very often, 606 if at all. 607 Overly old systems, especially Unices, are not within focus. 608 While AIX 609\begin_inset space ~ 610\end_inset 611 6125.3 might still classify as contemporary, strangelets like 613\begin_inset Quotes eld 614\end_inset 615 616Ultrix 617\begin_inset Quotes erd 618\end_inset 619 620 or 621\begin_inset Quotes eld 622\end_inset 623 624Dynix 625\begin_inset Quotes erd 626\end_inset 627 628 you can find in the autotools-related file 629\family typewriter 630config.guess 631\family default 632 are some that are definitely not. 633\end_layout 634 635\begin_layout Standard 636Furthermore, a compiler that understands the C99 or GNU89 standard is required. 637 The integer type 638\begin_inset Quotes eld 639\end_inset 640 641int 642\begin_inset Quotes erd 643\end_inset 644 645 should at best have 32 bits at least. 646 There is no ultra-portable version as of this writing, but feel free to 647 start one akin to the 648\begin_inset Quotes eld 649\end_inset 650 651p 652\begin_inset Quotes erd 653\end_inset 654 655 variants of OpenBSD software such as OpenSSH. 656\end_layout 657 658\begin_layout Section 659History 660\end_layout 661 662\begin_layout Standard 663The origins of libHX trace back, even crossing a language boundary, to when 664 the author started on using Perl in 1999. 665 Some tasks were just too damn useful to be open-coded every time. 666 Two such examples are what is these days known as 667\family typewriter 668HX_basename 669\family default 670 and 671\family typewriter 672HX_mkdir 673\family default 674. 675 The name does not relate to anyone's initials; it is a result of a truncation 676 of the author's nick used years ago. 677\end_layout 678 679\begin_layout Standard 680Around the beginning of 2003, the author also started on the C programming 681 language and soon the small library was converted from Perl to C. 682 The libHX library as of today is the result of working with C ever since, 683 and naturally grew from there to support whatever the author was in need 684 of. 685\end_layout 686 687\begin_layout Standard 688The 689\begin_inset Quotes eld 690\end_inset 691 692correct 693\begin_inset Quotes erd 694\end_inset 695 696 name for libHX is with an uppercase 697\begin_inset Quotes eld 698\end_inset 699 700H 701\begin_inset Quotes erd 702\end_inset 703 704 and uppercase 705\begin_inset Quotes eld 706\end_inset 707 708X 709\begin_inset Quotes erd 710\end_inset 711 712, and the same is used for filenames, such as 713\begin_inset Quotes eld 714\end_inset 715 716libHX.so 717\begin_inset Quotes erd 718\end_inset 719 720 721\begin_inset Foot 722status open 723 724\begin_layout Plain Layout 725Software projects may choose to entirely lowercase the project name for 726 use in filenames, such as the Linux kernel which is released as 727\family typewriter 728linux-${ 729\family default 730\shape italic 731version 732\family typewriter 733\shape default 734}.tar.bz2 735\family default 736, or the project may choose to keep the name for filenames, like Mesa and 737 SDL do. 738 libHX is of the latter. 739\end_layout 740 741\end_inset 742 743. 744\end_layout 745 746\begin_layout Standard 747\begin_inset Newpage clearpage 748\end_inset 749 750 751\end_layout 752 753\begin_layout Part 754General 755\end_layout 756 757\begin_layout Standard 758Many functions are prefixed with 759\begin_inset Quotes eld 760\end_inset 761 762 763\family typewriter 764HX_ 765\family default 766 767\begin_inset Quotes erd 768\end_inset 769 770 or 771\begin_inset Quotes eld 772\end_inset 773 774 775\family typewriter 776HXsubsys_ 777\family default 778 779\begin_inset Quotes erd 780\end_inset 781 782, as are structures (sometimes without underscores, be sure to check the 783 syntax and names), to avoid name clashes with possibly existing files. 784 Functions that are not tied to a specific data structure such as most of 785 the string functions (see chapter 786\begin_inset space ~ 787\end_inset 788 789 790\begin_inset CommandInset ref 791LatexCommand ref 792reference "sec:strings" 793 794\end_inset 795 796) use the subsystem-less prefix, 797\begin_inset Quotes eld 798\end_inset 799 800 801\family typewriter 802HX_ 803\family default 804 805\begin_inset Quotes erd 806\end_inset 807 808. 809 Functions from a clearly-defined subsystem, such as map or deque, augment 810 the base prefix by a suffix, forming e. 811\begin_inset space \thinspace{} 812\end_inset 813 814g. 815\begin_inset space \space{} 816\end_inset 817 818 819\begin_inset Quotes eld 820\end_inset 821 822 823\family typewriter 824HXmap_ 825\family default 826 827\begin_inset Quotes erd 828\end_inset 829 830. 831\end_layout 832 833\begin_layout Section 834Initialization 835\end_layout 836 837\begin_layout LyX-Code 838 839\series bold 840#include 841\series default 842 <libHX/init.h> 843\begin_inset Newline newline 844\end_inset 845 846 847\begin_inset Newline newline 848\end_inset 849 850 851\series bold 852int 853\series default 854 HX_init( 855\series bold 856void 857\series default 858); 859\begin_inset Index idx 860status open 861 862\begin_layout Plain Layout 863 864\family typewriter 865libHX_init 866\end_layout 867 868\end_inset 869 870 871\begin_inset Newline newline 872\end_inset 873 874 875\series bold 876void 877\series default 878 HX_exit( 879\series bold 880void 881\series default 882); 883\begin_inset Index idx 884status open 885 886\begin_layout Plain Layout 887 888\family typewriter 889libHX_exit 890\end_layout 891 892\end_inset 893 894 895\end_layout 896 897\begin_layout Standard 898Before using the library's functions, 899\family typewriter 900HX_init 901\family default 902 must be called. 903 This function will initialize any needed state libHX needs for itself, 904 if any. 905 It is designed to be invoked multiple times, such as for example, from 906 different libraries linking to libHX itself, and will refcount. 907 On success, >0 is returned. 908 If there was an error, it will return a negative error code or zero. 909 910\family typewriter 911HX_exit 912\family default 913 is the logical counterpart of notifying that the library is no longer used. 914\end_layout 915 916\begin_layout Section 917Type-checking casts 918\end_layout 919 920\begin_layout Standard 921The C++ language provides so-called 922\begin_inset Quotes eld 923\end_inset 924 925new-style casts 926\begin_inset Quotes erd 927\end_inset 928 929, referring to the four template-looking invocations 930\family typewriter 931static_cast<> 932\family default 933, 934\family typewriter 935const_cast<> 936\family default 937, 938\family typewriter 939reinterpret_cast<> 940\family default 941 and 942\family typewriter 943dynamic_cast<> 944\family default 945. 946 No such blessing was given to the C language, but still, even using macros 947 that expand to the olde cast make it much easier to find casts in source 948 code and annotate why something was casted, which is already an improvement. 949\begin_inset space ~ 950\end_inset 951 952— Actually, it 953\shape italic 954is 955\shape default 956 possible to do a some type checking, using some GCC extensions, which augments 957 these macros from their documentary nature to an actual safety measure. 958\end_layout 959 960\begin_layout Subsection 961 962\family typewriter 963reinterpret_cast 964\begin_inset Index idx 965status open 966 967\begin_layout Plain Layout 968 969\family typewriter 970reinterpret_cast 971\end_layout 972 973\end_inset 974 975 976\end_layout 977 978\begin_layout Standard 979 980\family typewriter 981reinterpret_cast() 982\family default 983 maps directly to the old-style typecast, 984\family typewriter 985(type)(expr) 986\family default 987, and causes the bit pattern for the expr rvalue to be 988\begin_inset Quotes eld 989\end_inset 990 991reinterpreted 992\begin_inset Quotes erd 993\end_inset 994 995 as a new type. 996 You will notice that 997\begin_inset Quotes eld 998\end_inset 999 1000reinterpret 1001\begin_inset Quotes erd 1002\end_inset 1003 1004 is the longest of all the 1005\family typewriter 1006*_cast 1007\family default 1008 names, and can easily cause your line to grow to 80 columns (the good maximum 1009 in many style guides). 1010 As a side effect, it is a good indicator that something potentially dangerous 1011 might be going on, for example converting intergers from/to pointer. 1012\end_layout 1013 1014\begin_layout LyX-Code 1015 1016\series bold 1017#include 1018\series default 1019 <libHX/defs.h> 1020\begin_inset Index idx 1021status open 1022 1023\begin_layout Plain Layout 1024 1025\family typewriter 1026libHX/defs.h 1027\end_layout 1028 1029\end_inset 1030 1031 1032\begin_inset Newline newline 1033\end_inset 1034 1035 1036\series bold 1037 1038\begin_inset Newline newline 1039\end_inset 1040 1041int 1042\series default 1043 i; 1044\begin_inset Newline newline 1045\end_inset 1046 1047 1048\series bold 1049/* 1050\family roman 1051\series default 1052\shape italic 1053Tree with numeric keys 1054\family default 1055\series bold 1056\shape default 1057 */ 1058\series default 1059 1060\begin_inset Newline newline 1061\end_inset 1062 1063tree = HXhashmap_init(0); 1064\begin_inset Newline newline 1065\end_inset 1066 1067 1068\series bold 1069for 1070\series default 1071 (i = 0; i < 6; ++i) 1072\begin_inset Newline newline 1073\end_inset 1074 1075 HXmap_add(tree, 1076\series bold 1077reinterpret_cast 1078\series default 1079( 1080\series bold 1081void * 1082\series default 1083, 1084\begin_inset Newline newline 1085\end_inset 1086 1087 1088\series bold 1089static_cast 1090\series default 1091( 1092\series bold 1093long 1094\series default 1095, i)), my_data); 1096\end_layout 1097 1098\begin_layout Subsection 1099 1100\family typewriter 1101signed_cast 1102\begin_inset Index idx 1103status open 1104 1105\begin_layout Plain Layout 1106 1107\family typewriter 1108signed_cast 1109\end_layout 1110 1111\end_inset 1112 1113 1114\end_layout 1115 1116\begin_layout Standard 1117This tag is for annotating that the cast was solely done to change the signednes 1118s of pointers to char 1119\begin_inset space ~ 1120\end_inset 1121 1122— and only those. 1123 No integers etc. 1124 The intention is to facilitate working with libraries that use 1125\family typewriter 1126unsigned char 1127\begin_inset space ~ 1128\end_inset 1129 1130* 1131\family default 1132 pointers, such as libcrypto and libssl (from the OpenSSL project) or libxml2, 1133 for example. 1134 See table 1135\begin_inset space ~ 1136\end_inset 1137 1138 1139\begin_inset CommandInset ref 1140LatexCommand ref 1141reference "tab:defs-signed_cast" 1142 1143\end_inset 1144 1145 for the allowed conversions. 1146 C++ does 1147\shape italic 1148not 1149\shape default 1150 actually have a 1151\family typewriter 1152signed_cast<> 1153\family default 1154, and one would have to use 1155\family typewriter 1156reinterpret_cast<> 1157\family default 1158 to do the conversion, because 1159\family typewriter 1160static_cast<> 1161\family default 1162 does not allow conversion from 1163\family typewriter 1164const char 1165\begin_inset space ~ 1166\end_inset 1167 1168* 1169\family default 1170 to 1171\family typewriter 1172const unsigned char 1173\begin_inset space ~ 1174\end_inset 1175 1176* 1177\family default 1178, for example. 1179 (libHX's 1180\family typewriter 1181static_cast() 1182\family default 1183 would also throw at least a compiler warning about the different signedness.) 1184 libHX does provide a 1185\family typewriter 1186signed_cast<> 1187\family default 1188 for C++ though. 1189 This is where 1190\family typewriter 1191signed_cast 1192\family default 1193 comes in. 1194\end_layout 1195 1196\begin_layout Standard 1197\begin_inset Float table 1198wide false 1199sideways false 1200status open 1201 1202\begin_layout Plain Layout 1203\align center 1204\begin_inset Tabular 1205<lyxtabular version="3" rows="7" columns="7"> 1206<features tabularvalignment="middle"> 1207<column alignment="center" valignment="top"> 1208<column alignment="center" valignment="top"> 1209<column alignment="center" valignment="top"> 1210<column alignment="center" valignment="top"> 1211<column alignment="center" valignment="top"> 1212<column alignment="center" valignment="top"> 1213<column alignment="center" valignment="top"> 1214<row> 1215<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none"> 1216\begin_inset Text 1217 1218\begin_layout Plain Layout 1219 1220\series bold 1221From 1222\backslash 1223 To 1224\end_layout 1225 1226\end_inset 1227</cell> 1228<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none"> 1229\begin_inset Text 1230 1231\begin_layout Plain Layout 1232 1233\series bold 1234c* 1235\series default 1236section 1237\end_layout 1238 1239\end_inset 1240</cell> 1241<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none"> 1242\begin_inset Text 1243 1244\begin_layout Plain Layout 1245 1246\series bold 1247sc* 1248\end_layout 1249 1250\end_inset 1251</cell> 1252<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none"> 1253\begin_inset Text 1254 1255\begin_layout Plain Layout 1256 1257\series bold 1258uc* 1259\end_layout 1260 1261\end_inset 1262</cell> 1263<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none"> 1264\begin_inset Text 1265 1266\begin_layout Plain Layout 1267 1268\series bold 1269Cc* 1270\end_layout 1271 1272\end_inset 1273</cell> 1274<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none"> 1275\begin_inset Text 1276 1277\begin_layout Plain Layout 1278 1279\series bold 1280Csc* 1281\end_layout 1282 1283\end_inset 1284</cell> 1285<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none"> 1286\begin_inset Text 1287 1288\begin_layout Plain Layout 1289 1290\series bold 1291Cuc* 1292\end_layout 1293 1294\end_inset 1295</cell> 1296</row> 1297<row> 1298<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> 1299\begin_inset Text 1300 1301\begin_layout Plain Layout 1302 1303\family typewriter 1304\series bold 1305char * 1306\end_layout 1307 1308\end_inset 1309</cell> 1310<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> 1311\begin_inset Text 1312 1313\begin_layout Plain Layout 1314\begin_inset Formula $\checkmark$ 1315\end_inset 1316 1317 1318\end_layout 1319 1320\end_inset 1321</cell> 1322<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> 1323\begin_inset Text 1324 1325\begin_layout Plain Layout 1326\begin_inset Formula $\checkmark$ 1327\end_inset 1328 1329 1330\end_layout 1331 1332\end_inset 1333</cell> 1334<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> 1335\begin_inset Text 1336 1337\begin_layout Plain Layout 1338\begin_inset Formula $\checkmark$ 1339\end_inset 1340 1341 1342\end_layout 1343 1344\end_inset 1345</cell> 1346<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> 1347\begin_inset Text 1348 1349\begin_layout Plain Layout 1350\begin_inset Formula $\checkmark$ 1351\end_inset 1352 1353 1354\end_layout 1355 1356\end_inset 1357</cell> 1358<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> 1359\begin_inset Text 1360 1361\begin_layout Plain Layout 1362\begin_inset Formula $\checkmark$ 1363\end_inset 1364 1365 1366\end_layout 1367 1368\end_inset 1369</cell> 1370<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> 1371\begin_inset Text 1372 1373\begin_layout Plain Layout 1374\begin_inset Formula $\checkmark$ 1375\end_inset 1376 1377 1378\end_layout 1379 1380\end_inset 1381</cell> 1382</row> 1383<row> 1384<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> 1385\begin_inset Text 1386 1387\begin_layout Plain Layout 1388 1389\family typewriter 1390\series bold 1391signed char * 1392\end_layout 1393 1394\end_inset 1395</cell> 1396<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> 1397\begin_inset Text 1398 1399\begin_layout Plain Layout 1400\begin_inset Formula $\checkmark$ 1401\end_inset 1402 1403 1404\end_layout 1405 1406\end_inset 1407</cell> 1408<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> 1409\begin_inset Text 1410 1411\begin_layout Plain Layout 1412\begin_inset Formula $\checkmark$ 1413\end_inset 1414 1415 1416\end_layout 1417 1418\end_inset 1419</cell> 1420<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> 1421\begin_inset Text 1422 1423\begin_layout Plain Layout 1424\begin_inset Formula $\checkmark$ 1425\end_inset 1426 1427 1428\end_layout 1429 1430\end_inset 1431</cell> 1432<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> 1433\begin_inset Text 1434 1435\begin_layout Plain Layout 1436\begin_inset Formula $\checkmark$ 1437\end_inset 1438 1439 1440\end_layout 1441 1442\end_inset 1443</cell> 1444<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> 1445\begin_inset Text 1446 1447\begin_layout Plain Layout 1448\begin_inset Formula $\checkmark$ 1449\end_inset 1450 1451 1452\end_layout 1453 1454\end_inset 1455</cell> 1456<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> 1457\begin_inset Text 1458 1459\begin_layout Plain Layout 1460\begin_inset Formula $\checkmark$ 1461\end_inset 1462 1463 1464\end_layout 1465 1466\end_inset 1467</cell> 1468</row> 1469<row> 1470<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> 1471\begin_inset Text 1472 1473\begin_layout Plain Layout 1474 1475\family typewriter 1476\series bold 1477unsigned char * 1478\end_layout 1479 1480\end_inset 1481</cell> 1482<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> 1483\begin_inset Text 1484 1485\begin_layout Plain Layout 1486\begin_inset Formula $\checkmark$ 1487\end_inset 1488 1489 1490\end_layout 1491 1492\end_inset 1493</cell> 1494<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> 1495\begin_inset Text 1496 1497\begin_layout Plain Layout 1498\begin_inset Formula $\checkmark$ 1499\end_inset 1500 1501 1502\end_layout 1503 1504\end_inset 1505</cell> 1506<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> 1507\begin_inset Text 1508 1509\begin_layout Plain Layout 1510\begin_inset Formula $\checkmark$ 1511\end_inset 1512 1513 1514\end_layout 1515 1516\end_inset 1517</cell> 1518<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> 1519\begin_inset Text 1520 1521\begin_layout Plain Layout 1522\begin_inset Formula $\checkmark$ 1523\end_inset 1524 1525 1526\end_layout 1527 1528\end_inset 1529</cell> 1530<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> 1531\begin_inset Text 1532 1533\begin_layout Plain Layout 1534\begin_inset Formula $\checkmark$ 1535\end_inset 1536 1537 1538\end_layout 1539 1540\end_inset 1541</cell> 1542<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> 1543\begin_inset Text 1544 1545\begin_layout Plain Layout 1546\begin_inset Formula $\checkmark$ 1547\end_inset 1548 1549 1550\end_layout 1551 1552\end_inset 1553</cell> 1554</row> 1555<row> 1556<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> 1557\begin_inset Text 1558 1559\begin_layout Plain Layout 1560 1561\family typewriter 1562\series bold 1563const char * 1564\end_layout 1565 1566\end_inset 1567</cell> 1568<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> 1569\begin_inset Text 1570 1571\begin_layout Plain Layout 1572– 1573\end_layout 1574 1575\end_inset 1576</cell> 1577<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> 1578\begin_inset Text 1579 1580\begin_layout Plain Layout 1581– 1582\end_layout 1583 1584\end_inset 1585</cell> 1586<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> 1587\begin_inset Text 1588 1589\begin_layout Plain Layout 1590– 1591\end_layout 1592 1593\end_inset 1594</cell> 1595<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> 1596\begin_inset Text 1597 1598\begin_layout Plain Layout 1599\begin_inset Formula $\checkmark$ 1600\end_inset 1601 1602 1603\end_layout 1604 1605\end_inset 1606</cell> 1607<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> 1608\begin_inset Text 1609 1610\begin_layout Plain Layout 1611\begin_inset Formula $\checkmark$ 1612\end_inset 1613 1614 1615\end_layout 1616 1617\end_inset 1618</cell> 1619<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> 1620\begin_inset Text 1621 1622\begin_layout Plain Layout 1623\begin_inset Formula $\checkmark$ 1624\end_inset 1625 1626 1627\end_layout 1628 1629\end_inset 1630</cell> 1631</row> 1632<row> 1633<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> 1634\begin_inset Text 1635 1636\begin_layout Plain Layout 1637 1638\family typewriter 1639\series bold 1640const signed char * 1641\end_layout 1642 1643\end_inset 1644</cell> 1645<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> 1646\begin_inset Text 1647 1648\begin_layout Plain Layout 1649– 1650\end_layout 1651 1652\end_inset 1653</cell> 1654<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> 1655\begin_inset Text 1656 1657\begin_layout Plain Layout 1658– 1659\end_layout 1660 1661\end_inset 1662</cell> 1663<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> 1664\begin_inset Text 1665 1666\begin_layout Plain Layout 1667– 1668\end_layout 1669 1670\end_inset 1671</cell> 1672<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> 1673\begin_inset Text 1674 1675\begin_layout Plain Layout 1676\begin_inset Formula $\checkmark$ 1677\end_inset 1678 1679 1680\end_layout 1681 1682\end_inset 1683</cell> 1684<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> 1685\begin_inset Text 1686 1687\begin_layout Plain Layout 1688\begin_inset Formula $\checkmark$ 1689\end_inset 1690 1691 1692\end_layout 1693 1694\end_inset 1695</cell> 1696<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> 1697\begin_inset Text 1698 1699\begin_layout Plain Layout 1700\begin_inset Formula $\checkmark$ 1701\end_inset 1702 1703 1704\end_layout 1705 1706\end_inset 1707</cell> 1708</row> 1709<row> 1710<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none"> 1711\begin_inset Text 1712 1713\begin_layout Plain Layout 1714 1715\family typewriter 1716\series bold 1717const unsigned char * 1718\end_layout 1719 1720\end_inset 1721</cell> 1722<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none"> 1723\begin_inset Text 1724 1725\begin_layout Plain Layout 1726– 1727\end_layout 1728 1729\end_inset 1730</cell> 1731<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none"> 1732\begin_inset Text 1733 1734\begin_layout Plain Layout 1735– 1736\end_layout 1737 1738\end_inset 1739</cell> 1740<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none"> 1741\begin_inset Text 1742 1743\begin_layout Plain Layout 1744– 1745\end_layout 1746 1747\end_inset 1748</cell> 1749<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none"> 1750\begin_inset Text 1751 1752\begin_layout Plain Layout 1753\begin_inset Formula $\checkmark$ 1754\end_inset 1755 1756 1757\end_layout 1758 1759\end_inset 1760</cell> 1761<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none"> 1762\begin_inset Text 1763 1764\begin_layout Plain Layout 1765\begin_inset Formula $\checkmark$ 1766\end_inset 1767 1768 1769\end_layout 1770 1771\end_inset 1772</cell> 1773<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none"> 1774\begin_inset Text 1775 1776\begin_layout Plain Layout 1777\begin_inset Formula $\checkmark$ 1778\end_inset 1779 1780 1781\end_layout 1782 1783\end_inset 1784</cell> 1785</row> 1786</lyxtabular> 1787 1788\end_inset 1789 1790 1791\end_layout 1792 1793\begin_layout Plain Layout 1794\begin_inset Caption Standard 1795 1796\begin_layout Plain Layout 1797\begin_inset CommandInset label 1798LatexCommand label 1799name "tab:defs-signed_cast" 1800 1801\end_inset 1802 1803Accepted conversions for 1804\family typewriter 1805signed_cast() 1806\end_layout 1807 1808\end_inset 1809 1810 1811\end_layout 1812 1813\end_inset 1814 1815 1816\end_layout 1817 1818\begin_layout Subsection 1819 1820\family typewriter 1821static_cast 1822\begin_inset CommandInset label 1823LatexCommand label 1824name "subsec:defs-static_cast" 1825 1826\end_inset 1827 1828 1829\begin_inset Index idx 1830status open 1831 1832\begin_layout Plain Layout 1833 1834\family typewriter 1835static_cast 1836\end_layout 1837 1838\end_inset 1839 1840 1841\end_layout 1842 1843\begin_layout Standard 1844Just like C++'s 1845\family typewriter 1846static_cast<> 1847\family default 1848, libHX's 1849\family typewriter 1850static_cast() 1851\family default 1852 verifies that 1853\family typewriter 1854expr 1855\family default 1856 can be implicitly converted to the new type (by a simple 1857\family typewriter 1858b 1859\begin_inset space ~ 1860\end_inset 1861 1862= 1863\begin_inset space ~ 1864\end_inset 1865 1866a 1867\family default 1868). 1869 Such is mainly useful for forcing a specific type, as is needed in varargs 1870 functions such as 1871\family typewriter 1872printf 1873\family default 1874, and where the conversion actually incurs other side effects, such as truncatio 1875n or promotion: 1876\end_layout 1877 1878\begin_layout LyX-Code 1879 1880\series bold 1881/* 1882\family roman 1883\series default 1884\shape italic 1885Convert to a type printf knows about 1886\family default 1887\series bold 1888\shape default 1889 */ 1890\begin_inset Newline newline 1891\end_inset 1892 1893uint64_t 1894\series default 1895 x = something; 1896\begin_inset Newline newline 1897\end_inset 1898 1899printf("%llu 1900\backslash 1901n", 1902\series bold 1903static_cast 1904\series default 1905( 1906\series bold 1907unsigned long long 1908\series default 1909, x)); 1910\end_layout 1911 1912\begin_layout Standard 1913Because there is no format specifier for 1914\family typewriter 1915uint64_t 1916\family default 1917 for 1918\family typewriter 1919printf 1920\family default 1921, a conversion to an accepted type is necessary to not cause undefined behavior. 1922 The author has seen code that did, for example, 1923\family typewriter 1924printf("%u") 1925\family default 1926 on a 1927\begin_inset Quotes eld 1928\end_inset 1929 1930long 1931\begin_inset Quotes erd 1932\end_inset 1933 1934, which only works on architectures where 1935\family typewriter 1936sizeof(unsigned int) 1937\family default 1938 happens to equal 1939\family typewriter 1940sizeof(unsigned long) 1941\family default 1942, such as x86_32. 1943 On x86_64, an 1944\family typewriter 1945unsigned long 1946\family default 1947 is usually twice as big as an 1948\family typewriter 1949unsigned int 1950\family default 1951, so that 8 bytes are pushed onto the stack, but 1952\family typewriter 1953printf 1954\family default 1955 only unshifts 4 bytes because the developer used 1956\begin_inset Quotes eld 1957\end_inset 1958 1959 1960\family typewriter 1961%u 1962\family default 1963 1964\begin_inset Quotes erd 1965\end_inset 1966 1967, leading to misreading the next variable on the stack. 1968\end_layout 1969 1970\begin_layout LyX-Code 1971 1972\series bold 1973/* 1974\family roman 1975\series default 1976\shape italic 1977Force promotion 1978\family default 1979\series bold 1980\shape default 1981 */ 1982\series default 1983 1984\begin_inset Newline newline 1985\end_inset 1986 1987 1988\series bold 1989double 1990\series default 1991 a_quarter = 1992\series bold 1993static_cast 1994\series default 1995( 1996\series bold 1997double 1998\series default 1999, 1) / 4; 2000\end_layout 2001 2002\begin_layout Standard 2003Were 2004\begin_inset Quotes eld 2005\end_inset 2006 20071 2008\begin_inset Quotes erd 2009\end_inset 2010 2011 not promoted to double, the result in 2012\family typewriter 2013q 2014\family default 2015 would be zero because 1/4 is just an integer division, yielding zero. 2016 By making one of the operands a floating-point quantity, the compiler will 2017 instruct the FPU to compute the result. 2018 Of course, one could have also written 2019\begin_inset Quotes eld 2020\end_inset 2021 2022 2023\family typewriter 20241.0 2025\family default 2026 2027\begin_inset Quotes erd 2028\end_inset 2029 2030 instead of 2031\family typewriter 2032static_cast(double, 1) 2033\family default 2034, but this is left for the programmer to decide which style s/he prefers. 2035\end_layout 2036 2037\begin_layout LyX-Code 2038 2039\series bold 2040/* 2041\family roman 2042\series default 2043\shape italic 2044Force truncation before invoking second sqrt 2045\family default 2046\series bold 2047\shape default 2048 */ 2049\series default 2050 2051\begin_inset Newline newline 2052\end_inset 2053 2054 2055\series bold 2056double 2057\series default 2058 f = sqrt( 2059\series bold 2060static_cast 2061\series default 2062( 2063\series bold 2064int 2065\series default 2066, 10 * sqrt(3.0 / 4))); 2067\end_layout 2068 2069\begin_layout Standard 2070And here, the conversion from 2071\family typewriter 2072double 2073\family default 2074 to 2075\family typewriter 2076int 2077\family default 2078 incurs a (wanted) truncation of the decimal fraction, that is, rounding 2079 down for positive numbers, and rounding up for negative numbers. 2080\end_layout 2081 2082\begin_layout Subsubsection 2083Allowed conversions 2084\end_layout 2085 2086\begin_layout Itemize 2087 2088\series bold 2089Numbers 2090\series default 2091 2092\begin_inset Newline newline 2093\end_inset 2094 2095Conversion between numeric types, such as 2096\family typewriter 2097char 2098\family default 2099, 2100\family typewriter 2101short 2102\family default 2103, 2104\family typewriter 2105int 2106\family default 2107, 2108\family typewriter 2109long 2110\family default 2111, 2112\family typewriter 2113long long 2114\family default 2115, 2116\family typewriter 2117int 2118\shape italic 2119N 2120\shape default 2121_t 2122\family default 2123, both their signed and unsigned variants, 2124\family typewriter 2125float 2126\family default 2127 and 2128\family typewriter 2129double 2130\family default 2131. 2132\end_layout 2133 2134\begin_layout Itemize 2135 2136\series bold 2137Generic Pointer 2138\series default 2139 2140\begin_inset Newline newline 2141\end_inset 2142 2143Conversion from 2144\family typewriter 2145type 2146\begin_inset space ~ 2147\end_inset 2148 2149* 2150\family default 2151 to and from 2152\family typewriter 2153void 2154\begin_inset space ~ 2155\end_inset 2156 2157* 2158\family default 2159. 2160 (Where 2161\family typewriter 2162type 2163\family default 2164 may very well be a type with further indirection.) 2165\end_layout 2166 2167\begin_layout Itemize 2168 2169\series bold 2170Generic Pointer (const) 2171\begin_inset Newline newline 2172\end_inset 2173 2174 2175\series default 2176Conversion from 2177\family typewriter 2178const type 2179\begin_inset space ~ 2180\end_inset 2181 2182* 2183\family default 2184 to and from 2185\family typewriter 2186const void 2187\begin_inset space ~ 2188\end_inset 2189 2190* 2191\family default 2192. 2193\end_layout 2194 2195\begin_layout Subsection 2196 2197\family typewriter 2198const_cast 2199\begin_inset Index idx 2200status open 2201 2202\begin_layout Plain Layout 2203 2204\family typewriter 2205const_cast 2206\end_layout 2207 2208\end_inset 2209 2210 2211\end_layout 2212 2213\begin_layout Standard 2214 2215\family typewriter 2216const_cast 2217\family default 2218 allows to add or remove 2219\begin_inset Quotes eld 2220\end_inset 2221 2222const 2223\begin_inset Quotes erd 2224\end_inset 2225 2226 qualifiers from the type a pointer is pointing to. 2227 Due to technical limitations, it could not be implemented to support arbitrary 2228 indirection. 2229 Instead, 2230\family typewriter 2231const_cast 2232\family default 2233 comes in three variants, to be used for indirection levels of 1 to 3: 2234\end_layout 2235 2236\begin_layout Itemize 2237 2238\family typewriter 2239\series bold 2240const_cast 2241\series default 22421( 2243\series bold 2244type 2245\begin_inset space ~ 2246\end_inset 2247 2248* 2249\series default 2250, expr) 2251\family default 2252 with 2253\family typewriter 2254\series bold 2255typeof 2256\series default 2257(expr) 2258\begin_inset space ~ 2259\end_inset 2260 2261= 2262\series bold 2263type 2264\begin_inset space ~ 2265\end_inset 2266 2267* 2268\family default 2269\series default 2270. 2271 (Similarly for any combinations of const.) 2272\end_layout 2273 2274\begin_layout Itemize 2275 2276\family typewriter 2277\series bold 2278const_cast 2279\series default 22802( 2281\series bold 2282type 2283\begin_inset space ~ 2284\end_inset 2285 2286** 2287\series default 2288, expr) with 2289\series bold 2290typeof 2291\series default 2292(expr) 2293\begin_inset space ~ 2294\end_inset 2295 2296= 2297\series bold 2298type 2299\begin_inset space ~ 2300\end_inset 2301 2302** 2303\family default 2304\series default 2305 (and all combinations of const in all possible locations). 2306\end_layout 2307 2308\begin_layout Itemize 2309 2310\family typewriter 2311\series bold 2312const_cast 2313\series default 23143( 2315\series bold 2316type 2317\begin_inset space ~ 2318\end_inset 2319 2320*** 2321\series default 2322, expr) with 2323\series bold 2324typeof 2325\series default 2326(expr) 2327\begin_inset space ~ 2328\end_inset 2329 2330= 2331\series bold 2332type 2333\begin_inset space ~ 2334\end_inset 2335 2336*** 2337\family default 2338\series default 2339 (and all combinations...). 2340\end_layout 2341 2342\begin_layout Standard 2343As indirection levels above 3 are really unlikely 2344\begin_inset Foot 2345status open 2346 2347\begin_layout Plain Layout 2348See 2349\begin_inset Quotes eld 2350\end_inset 2351 2352Three Star Programmer 2353\begin_inset Quotes erd 2354\end_inset 2355 2356 2357\end_layout 2358 2359\end_inset 2360 2361, having only these three type-checking cast macros was deemed sufficient. 2362 The only place where libHX even uses a level\SpecialChar nobreakdash 23633 indirection is in the option 2364 parser. 2365\end_layout 2366 2367\begin_layout Standard 2368\begin_inset Float table 2369placement H 2370wide false 2371sideways false 2372status open 2373 2374\begin_layout Plain Layout 2375\align center 2376\begin_inset Tabular 2377<lyxtabular version="3" rows="2" columns="2"> 2378<features tabularvalignment="middle"> 2379<column alignment="center" valignment="top"> 2380<column alignment="center" valignment="top"> 2381<row> 2382<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> 2383\begin_inset Text 2384 2385\begin_layout Plain Layout 2386 2387\family typewriter 2388int ** 2389\end_layout 2390 2391\end_inset 2392</cell> 2393<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> 2394\begin_inset Text 2395 2396\begin_layout Plain Layout 2397 2398\family typewriter 2399int *const * 2400\end_layout 2401 2402\end_inset 2403</cell> 2404</row> 2405<row> 2406<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none"> 2407\begin_inset Text 2408 2409\begin_layout Plain Layout 2410 2411\family typewriter 2412const int ** 2413\end_layout 2414 2415\end_inset 2416</cell> 2417<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none"> 2418\begin_inset Text 2419 2420\begin_layout Plain Layout 2421 2422\family typewriter 2423const int *const * 2424\end_layout 2425 2426\end_inset 2427</cell> 2428</row> 2429</lyxtabular> 2430 2431\end_inset 2432 2433 2434\end_layout 2435 2436\begin_layout Plain Layout 2437\begin_inset Caption Standard 2438 2439\begin_layout Plain Layout 2440Accepted expr/target types for 2441\family typewriter 2442const_cast2 2443\family default 2444; example for the 2445\begin_inset Quotes eld 2446\end_inset 2447 2448int 2449\begin_inset Quotes erd 2450\end_inset 2451 2452 type 2453\end_layout 2454 2455\end_inset 2456 2457 2458\end_layout 2459 2460\begin_layout Plain Layout 2461\align center 2462Conversion is permitted when expression and target type are from the table. 2463\end_layout 2464 2465\end_inset 2466 2467 2468\end_layout 2469 2470\begin_layout Standard 2471It is currently not possible to use 2472\family typewriter 2473const_cast 2474\family default 24751/2/3 on pointers to structures whose member structure is unknown. 2476\end_layout 2477 2478\begin_layout Standard 2479\begin_inset Newpage clearpage 2480\end_inset 2481 2482 2483\end_layout 2484 2485\begin_layout Section 2486Macros 2487\end_layout 2488 2489\begin_layout Standard 2490All macros in this section are available through 2491\family typewriter 2492#include <libHX/defs.h> 2493\family default 2494 2495\begin_inset Index idx 2496status open 2497 2498\begin_layout Plain Layout 2499 2500\family typewriter 2501libHX/defs.h 2502\end_layout 2503 2504\end_inset 2505 2506. 2507\end_layout 2508 2509\begin_layout Subsection 2510Preprocessor 2511\end_layout 2512 2513\begin_layout LyX-Code 2514 2515\series bold 2516#define 2517\series default 2518 HX_STRINGIFY(s) 2519\begin_inset Index idx 2520status open 2521 2522\begin_layout Plain Layout 2523 2524\family typewriter 2525HX_STRINGIFY 2526\end_layout 2527 2528\end_inset 2529 2530 2531\end_layout 2532 2533\begin_layout Standard 2534Transforms the expansion of the argument 2535\family typewriter 2536s 2537\family default 2538 into a C string. 2539\end_layout 2540 2541\begin_layout Subsection 2542Sizes 2543\end_layout 2544 2545\begin_layout LyX-Code 2546 2547\series bold 2548#define 2549\series default 2550 HXSIZEOF_Z16 2551\begin_inset Index idx 2552status open 2553 2554\begin_layout Plain Layout 2555 2556\family typewriter 2557HXSIZEOF_Z16 2558\end_layout 2559 2560\end_inset 2561 2562 2563\begin_inset Newline newline 2564\end_inset 2565 2566 2567\series bold 2568#define 2569\series default 2570 HXSIZEOF_Z32 2571\begin_inset Index idx 2572status open 2573 2574\begin_layout Plain Layout 2575 2576\family typewriter 2577HXSIZEOF_Z32 2578\end_layout 2579 2580\end_inset 2581 2582 2583\begin_inset Newline newline 2584\end_inset 2585 2586 2587\series bold 2588#define 2589\series default 2590 HXSIZEOF_Z64 2591\begin_inset Index idx 2592status open 2593 2594\begin_layout Plain Layout 2595 2596\family typewriter 2597HXSIZEOF_Z64 2598\end_layout 2599 2600\end_inset 2601 2602 2603\end_layout 2604 2605\begin_layout Standard 2606Expands to the size needed for a buffer (including ' 2607\family typewriter 2608 2609\backslash 26100 2611\family default 2612') to hold the base-10 string representation of a 16\SpecialChar nobreakdash 2613, 32\SpecialChar nobreakdash 2614 or 64\SpecialChar nobreakdash 2615bit integer. 2616\end_layout 2617 2618\begin_layout Subsection 2619Locators 2620\end_layout 2621 2622\begin_layout LyX-Code 2623output_type 2624\series bold 2625* 2626\series default 2627containerof( 2628\series bold 2629input_type * 2630\series default 2631ptr, output_type, member); 2632\begin_inset Index idx 2633status open 2634 2635\begin_layout Plain Layout 2636 2637\family typewriter 2638containerof 2639\end_layout 2640 2641\end_inset 2642 2643 2644\begin_inset Newline newline 2645\end_inset 2646 2647 2648\series bold 2649size_t 2650\series default 2651 HXsizeof_member(struct_type, member); 2652\begin_inset Index idx 2653status open 2654 2655\begin_layout Plain Layout 2656 2657\family typewriter 2658HXsizeof_member 2659\end_layout 2660 2661\end_inset 2662 2663 2664\begin_inset Newline newline 2665\end_inset 2666 2667output_type HXtypeof_member(struct_type, member); 2668\begin_inset Index idx 2669status open 2670 2671\begin_layout Plain Layout 2672 2673\family typewriter 2674HXtypeof_member 2675\end_layout 2676 2677\end_inset 2678 2679 2680\end_layout 2681 2682\begin_layout Standard 2683 2684\family typewriter 2685containerof 2686\family default 2687 will return a pointer to the struct in which 2688\family typewriter 2689ptr 2690\family default 2691 is contained as the given member. 2692\end_layout 2693 2694\begin_layout LyX-Code 2695 2696\series bold 2697struct 2698\series default 2699 foo { 2700\begin_inset Newline newline 2701\end_inset 2702 2703 2704\series bold 2705int 2706\series default 2707 bar; 2708\begin_inset Newline newline 2709\end_inset 2710 2711 2712\series bold 2713int 2714\series default 2715 baz; 2716\begin_inset Newline newline 2717\end_inset 2718 2719}; 2720\begin_inset Newline newline 2721\end_inset 2722 2723 2724\begin_inset Newline newline 2725\end_inset 2726 2727 2728\series bold 2729static void 2730\series default 2731 test( 2732\series bold 2733int * 2734\series default 2735ptr) 2736\begin_inset Newline newline 2737\end_inset 2738 2739{ 2740\begin_inset Newline newline 2741\end_inset 2742 2743 2744\series bold 2745struct 2746\series default 2747 foo 2748\series bold 2749* 2750\series default 2751self = containerof(baz, 2752\series bold 2753struct 2754\series default 2755 foo, baz); 2756\begin_inset Newline newline 2757\end_inset 2758 2759} 2760\end_layout 2761 2762\begin_layout Standard 2763 2764\family typewriter 2765HXsizeof_member 2766\family default 2767 and 2768\family typewriter 2769HXtypeof_member 2770\family default 2771 are shortcuts (mainly for the C language) to get the size or type of a 2772 named member in a given struct: 2773\end_layout 2774 2775\begin_layout LyX-Code 2776 2777\series bold 2778char 2779\series default 2780 padding[FIELD_SIZEOF( 2781\series bold 2782struct 2783\series default 2784 foo, baz)]; 2785\end_layout 2786 2787\begin_layout Standard 2788In C++, one can simply use 2789\family typewriter 2790sizeof(foo::baz) 2791\family default 2792 and 2793\family typewriter 2794decltype(foo::baz) 2795\family default 2796. 2797\end_layout 2798 2799\begin_layout Subsection 2800Array size 2801\end_layout 2802 2803\begin_layout LyX-Code 2804 2805\series bold 2806size_t 2807\series default 2808 ARRAY_SIZE( 2809\series bold 2810type 2811\series default 2812 array 2813\series bold 2814[] 2815\series default 2816); 2817\series bold 2818/* 2819\family roman 2820\series default 2821\shape italic 2822implemented as a macro 2823\family default 2824\series bold 2825\shape default 2826 */ 2827\series default 2828 2829\begin_inset Index idx 2830status open 2831 2832\begin_layout Plain Layout 2833 2834\family typewriter 2835ARRAY_SIZE 2836\end_layout 2837 2838\end_inset 2839 2840 2841\end_layout 2842 2843\begin_layout Standard 2844Returns the number of elements in 2845\family typewriter 2846array 2847\family default 2848. 2849 This only works with true arrays ( 2850\family typewriter 2851type[] 2852\family default 2853), and will not output a meaningful value when used with a pointer-to-element 2854 ( 2855\family typewriter 2856type 2857\begin_inset space ~ 2858\end_inset 2859 2860* 2861\family default 2862), which is often used for array access too. 2863\end_layout 2864 2865\begin_layout Subsection 2866Compile-time build checks 2867\end_layout 2868 2869\begin_layout LyX-Code 2870 2871\series bold 2872int 2873\series default 2874 BUILD_BUG_ON_EXPR( 2875\series bold 2876bool 2877\series default 2878 condition); 2879\series bold 2880/* 2881\family roman 2882\series default 2883\shape italic 2884implemented as a macro 2885\family default 2886\series bold 2887\shape default 2888 */ 2889\series default 2890 2891\begin_inset Index idx 2892status open 2893 2894\begin_layout Plain Layout 2895 2896\family typewriter 2897BUILD_BUG_ON_EXPR 2898\end_layout 2899 2900\end_inset 2901 2902 2903\begin_inset Newline newline 2904\end_inset 2905 2906 2907\series bold 2908void 2909\series default 2910 BUILD_BUG_ON( 2911\series bold 2912bool 2913\series default 2914 condition); 2915\series bold 2916/* 2917\family roman 2918\series default 2919\shape italic 2920implemented as a macro 2921\family default 2922\series bold 2923\shape default 2924 */ 2925\series default 2926 2927\begin_inset Index idx 2928status open 2929 2930\begin_layout Plain Layout 2931 2932\family typewriter 2933BUILD_BUG_ON 2934\end_layout 2935 2936\end_inset 2937 2938 2939\end_layout 2940 2941\begin_layout Standard 2942Causes the compiler to fail when 2943\family typewriter 2944condition 2945\family default 2946 evaluates to true. 2947 If not implemented for a compiler, it will be a no-op. 2948 2949\family typewriter 2950BUILD_BUG_ON 2951\family default 2952 is meant to be used as a standalone statement, while 2953\family typewriter 2954BUILD_\SpecialChar softhyphen 2955BUG_\SpecialChar softhyphen 2956ON_\SpecialChar softhyphen 2957EXPR 2958\family default 2959 is for when a check is to occur within an expression, that latter of which 2960 is useful for within macros when one cannot, or does not want to use multiple 2961 statements. 2962\end_layout 2963 2964\begin_layout LyX-Code 2965type DEMOTE_TO_PTR(type expr); 2966\series bold 2967/* 2968\family roman 2969\series default 2970\shape italic 2971macro 2972\family default 2973\series bold 2974\shape default 2975 */ 2976\end_layout 2977 2978\begin_layout Standard 2979Changes the type of expr to pointer type: If 2980\family typewriter 2981expr 2982\family default 2983 of array type class, changes it to a pointer to the first element. 2984 If 2985\family typewriter 2986expr 2987\family default 2988 of function type class, changes it to a pointer to the function. 2989\end_layout 2990 2991\begin_layout LyX-Code 2992 2993\series bold 2994int 2995\series default 2996 main( 2997\series bold 2998void 2999\series default 3000); 3001\begin_inset Newline newline 3002\end_inset 3003 3004 3005\series bold 3006int (* 3007\series default 3008fp 3009\series bold 3010) 3011\series default 3012( 3013\series bold 3014void 3015\series default 3016); 3017\begin_inset Newline newline 3018\end_inset 3019 3020 3021\series bold 3022char 3023\series default 3024 a 3025\series bold 3026[ 3027\series default 3028123 3029\series bold 3030] 3031\series default 3032; 3033\begin_inset Newline newline 3034\end_inset 3035 3036DEMOTE_TO_PTR(main); 3037\series bold 3038/* 3039\family roman 3040\series default 3041\shape italic 3042yields 3043\series bold 3044int (*) 3045\series default 3046( 3047\series bold 3048void 3049\series default 3050); 3051\family default 3052\series bold 3053\shape default 3054 */ 3055\series default 3056 3057\begin_inset Newline newline 3058\end_inset 3059 3060DEMOTE_TO_PTR(fp); 3061\series bold 3062/* 3063\series default 3064also yields 3065\family roman 3066\series bold 3067\shape italic 3068int (*) 3069\series default 3070( 3071\series bold 3072void 3073\series default 3074); 3075\family default 3076\series bold 3077\shape default 3078 */ 3079\series default 3080 3081\begin_inset Newline newline 3082\end_inset 3083 3084DEMOTE_TO_PTR(a); 3085\series bold 3086/* 3087\series default 3088yields 3089\family roman 3090\series bold 3091\shape italic 3092char * 3093\family default 3094\shape default 3095 */ 3096\end_layout 3097 3098\begin_layout Subsection 3099UNIX file modes 3100\end_layout 3101 3102\begin_layout LyX-Code 3103 3104\series bold 3105#define 3106\series default 3107 S_IRUGO (S_IRUSR | S_IRGRP | S_IROTH) 3108\begin_inset Index idx 3109status open 3110 3111\begin_layout Plain Layout 3112 3113\family typewriter 3114S_IRUGO 3115\end_layout 3116 3117\end_inset 3118 3119 3120\begin_inset Newline newline 3121\end_inset 3122 3123 3124\series bold 3125#define 3126\series default 3127 S_IWUGO (S_IWUSR | S_IWGRP | S_IWOTH) 3128\begin_inset Index idx 3129status open 3130 3131\begin_layout Plain Layout 3132 3133\family typewriter 3134S_IWUGO 3135\end_layout 3136 3137\end_inset 3138 3139 3140\begin_inset Newline newline 3141\end_inset 3142 3143 3144\series bold 3145#define 3146\series default 3147 S_IXUGO (S_IXUSR | S_IXGRP | S_IXOTH) 3148\begin_inset Index idx 3149status open 3150 3151\begin_layout Plain Layout 3152 3153\family typewriter 3154S_IXUGO 3155\end_layout 3156 3157\end_inset 3158 3159 3160\begin_inset Newline newline 3161\end_inset 3162 3163 3164\series bold 3165#define 3166\series default 3167 S_IRWXUGO (S_IRUGO | S_IWUGO | S_IXUGO) 3168\begin_inset Index idx 3169status open 3170 3171\begin_layout Plain Layout 3172 3173\family typewriter 3174S_IRWXUGO 3175\end_layout 3176 3177\end_inset 3178 3179 3180\end_layout 3181 3182\begin_layout Standard 3183The defines make it vastly easier to specify permissions for large group 3184 of users. 3185 For example, if one wanted to create a file with the permissions 3186\family typewriter 3187rw-r--r-- 3188\family default 3189 (ignoring the umask in this description), 3190\family typewriter 3191S_IRUSR 3192\begin_inset space ~ 3193\end_inset 3194 3195| S_IWUSR 3196\family default 3197 can now be used instead of the longer 3198\family typewriter 3199S_IRUSR 3200\begin_inset space ~ 3201\end_inset 3202 3203| S_IWUSR 3204\begin_inset space ~ 3205\end_inset 3206 3207| S_IRGRP 3208\begin_inset space ~ 3209\end_inset 3210 3211| S_IROTH 3212\family default 3213. 3214\end_layout 3215 3216\begin_layout Subsection 3217VC runtime format specifiers 3218\end_layout 3219 3220\begin_layout Standard 3221The Microsoft Visual C runtime (a weak libc) uses non-standard format specifiers 3222 for certain types. 3223 Whereas C99 specifies 3224\begin_inset Quotes eld 3225\end_inset 3226 3227z 3228\begin_inset Quotes erd 3229\end_inset 3230 3231 for 3232\family typewriter 3233size_t 3234\family default 3235 and 3236\begin_inset Quotes eld 3237\end_inset 3238 3239ll 3240\begin_inset Quotes erd 3241\end_inset 3242 3243 for long long, MSVCRT users must use 3244\begin_inset Quotes eld 3245\end_inset 3246 3247I 3248\begin_inset Quotes erd 3249\end_inset 3250 3251 and 3252\begin_inset Quotes eld 3253\end_inset 3254 3255I64 3256\begin_inset Quotes erd 3257\end_inset 3258 3259 (forming 3260\family typewriter 3261%Id 3262\family default 3263 instead of 3264\family typewriter 3265%zd 3266\family default 3267 for 3268\family typewriter 3269ssize_t 3270\family default 3271, for example). 3272 libHX provides two convenience macros for this: 3273\end_layout 3274 3275\begin_layout LyX-Code 3276 3277\series bold 3278#define 3279\series default 3280 HX_SIZET_FMT "z" 3281\family roman 3282\shape italic 3283 or 3284\family default 3285\shape default 3286"I" 3287\begin_inset Index idx 3288status open 3289 3290\begin_layout Plain Layout 3291HX_SIZET_FMT 3292\end_layout 3293 3294\end_inset 3295 3296 3297\begin_inset Newline newline 3298\end_inset 3299 3300 3301\series bold 3302#define 3303\series default 3304 HX_LONGLONG_FMT "ll" 3305\family roman 3306\shape italic 3307 or 3308\family default 3309\shape default 3310"I64" 3311\begin_inset Index idx 3312status open 3313 3314\begin_layout Plain Layout 3315HX_LONGLONG_FMT 3316\end_layout 3317 3318\end_inset 3319 3320 3321\end_layout 3322 3323\begin_layout Standard 3324These may be used together with printf or scanf: 3325\end_layout 3326 3327\begin_layout LyX-Code 3328printf("struct timespec is of size %" HX_SIZET_FMT "u 3329\backslash 3330n", 3331\begin_inset Newline newline 3332\end_inset 3333 3334 3335\series bold 3336sizeof 3337\series default 3338(struct timespec)); 3339\end_layout 3340 3341\begin_layout Standard 3342\begin_inset Newpage clearpage 3343\end_inset 3344 3345 3346\end_layout 3347 3348\begin_layout Section 3349Miscellaneous functions 3350\end_layout 3351 3352\begin_layout LyX-Code 3353 3354\series bold 3355#include 3356\series default 3357 <libHX/misc.h> 3358\begin_inset Index idx 3359status open 3360 3361\begin_layout Plain Layout 3362 3363\family typewriter 3364libHX/misc.h 3365\end_layout 3366 3367\end_inset 3368 3369 3370\begin_inset Newline newline 3371\end_inset 3372 3373 3374\begin_inset Newline newline 3375\end_inset 3376 3377 3378\series bold 3379int 3380\series default 3381 HX_ffs( 3382\series bold 3383unsigned long 3384\series default 3385 z); 3386\begin_inset Index idx 3387status open 3388 3389\begin_layout Plain Layout 3390 3391\family typewriter 3392HX_ffs 3393\end_layout 3394 3395\end_inset 3396 3397 3398\begin_inset Newline newline 3399\end_inset 3400 3401 3402\series bold 3403int 3404\series default 3405 HX_fls( 3406\series bold 3407unsigned long 3408\series default 3409 z); 3410\begin_inset Index idx 3411status open 3412 3413\begin_layout Plain Layout 3414 3415\family typewriter 3416HX_fls 3417\end_layout 3418 3419\end_inset 3420 3421 3422\begin_inset Newline newline 3423\end_inset 3424 3425 3426\series bold 3427void 3428\series default 3429 HX_hexdump( 3430\series bold 3431FILE * 3432\series default 3433fp, 3434\series bold 3435const void * 3436\series default 3437ptr, 3438\series bold 3439unsigned int 3440\series default 3441 len); 3442\begin_inset Index idx 3443status open 3444 3445\begin_layout Plain Layout 3446 3447\family typewriter 3448HX_hexdump 3449\end_layout 3450 3451\end_inset 3452 3453 3454\begin_inset Newline newline 3455\end_inset 3456 3457 3458\series bold 3459void 3460\series default 3461 HX_zvecfree( 3462\series bold 3463char ** 3464\series default 3465); 3466\begin_inset Index idx 3467status open 3468 3469\begin_layout Plain Layout 3470 3471\family typewriter 3472HX_zvecfree 3473\end_layout 3474 3475\end_inset 3476 3477 3478\begin_inset Newline newline 3479\end_inset 3480 3481 3482\series bold 3483unsigned int 3484\series default 3485 HX_zveclen( 3486\series bold 3487const char *const * 3488\series default 3489); 3490\begin_inset Index idx 3491status open 3492 3493\begin_layout Plain Layout 3494 3495\family typewriter 3496HX_zveclen 3497\end_layout 3498 3499\end_inset 3500 3501 3502\end_layout 3503 3504\begin_layout Description 3505 3506\family typewriter 3507HX_ffs 3508\family default 3509 Finds the first (lowest-significant) bit in a value and returns its position, 3510 or -1 to indicate failure. 3511\end_layout 3512 3513\begin_layout Description 3514 3515\family typewriter 3516HX_fls 3517\family default 3518 Finds the last (most-significant) bit in a value and returns its position, 3519 or -1 to indicate failure. 3520\end_layout 3521 3522\begin_layout Description 3523 3524\family typewriter 3525HX_hexdump 3526\family default 3527 Outputs a nice pretty-printed hex and ASCII dump to the filedescriptor 3528 3529\family typewriter 3530fp 3531\family default 3532. 3533 3534\family typewriter 3535ptr 3536\family default 3537 is the memory area, of which 3538\family typewriter 3539len 3540\family default 3541 bytes will be dumped. 3542\end_layout 3543 3544\begin_layout Description 3545 3546\family typewriter 3547HX_zvecfree 3548\family default 3549 Frees the supplied Z-vector array. 3550 (Frees all array elements from the first element to (excluding) the first 3551 3552\family typewriter 3553NULL 3554\family default 3555 element.) 3556\end_layout 3557 3558\begin_layout Description 3559 3560\family typewriter 3561HX_zveclen 3562\family default 3563 Counts the number of array elements until the first 3564\family typewriter 3565NULL 3566\family default 3567 array element is seen, and returns this number. 3568\end_layout 3569 3570\begin_layout Section 3571Time functions 3572\end_layout 3573 3574\begin_layout Standard 3575Time in POSIX systems is represented in 3576\family typewriter 3577struct timespec 3578\family default 3579. 3580 This structure is composed of two members: one integer for the number of 3581 full seconds in the time value, and one integer for the number of nanoseconds 3582 that remain when subtracting the full seconds from the time value. 3583 POSIX leaves it unspecified how negative time is to be represented with 3584 this structure, so I have devised an algebra for use with the same struct 3585 that gives negative time support. 3586\end_layout 3587 3588\begin_layout Standard 3589Since integers often cannot store negative zero (due to e. 3590\begin_inset space \thinspace{} 3591\end_inset 3592 3593g. 3594\begin_inset space \space{} 3595\end_inset 3596 3597use of 2s complements in the language implementation), we will store the 3598 minus sign in the nanosecond member if the integral second part is zero. 3599 This gives us the property that we can test for negative time by looking 3600 for whether at least one member of the structure is negative. 3601 Also, we want to avoid storing the minus in both members to somewhat aid 3602 the pretty-printing construct often seen, 3603\end_layout 3604 3605\begin_layout LyX-Code 3606printf("%ld.%09ld 3607\backslash 3608n", (long)ts.tv_sec, ts.tv_nsec); 3609\end_layout 3610 3611\begin_layout Standard 3612The number of combinations of a (non-zero) negative number, zero and a (non-zero 3613) positive number is small, so we can actually just exhaustively list them 3614 all. 3615\begin_inset Separator latexpar 3616\end_inset 3617 3618 3619\end_layout 3620 3621\begin_layout Standard 3622\noindent 3623\align center 3624\begin_inset Tabular 3625<lyxtabular version="3" rows="4" columns="6"> 3626<features tabularvalignment="middle"> 3627<column alignment="center" valignment="top"> 3628<column alignment="center" valignment="top"> 3629<column alignment="center" valignment="top"> 3630<column alignment="center" valignment="top"> 3631<column alignment="center" valignment="top"> 3632<column alignment="center" valignment="top"> 3633<row> 3634<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none"> 3635\begin_inset Text 3636 3637\begin_layout Plain Layout 3638Representation 3639\end_layout 3640 3641\end_inset 3642</cell> 3643<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none"> 3644\begin_inset Text 3645 3646\begin_layout Plain Layout 3647Time value 3648\end_layout 3649 3650\end_inset 3651</cell> 3652<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none"> 3653\begin_inset Text 3654 3655\begin_layout Plain Layout 3656R 3657\end_layout 3658 3659\end_inset 3660</cell> 3661<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none"> 3662\begin_inset Text 3663 3664\begin_layout Plain Layout 3665T 3666\end_layout 3667 3668\end_inset 3669</cell> 3670<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none"> 3671\begin_inset Text 3672 3673\begin_layout Plain Layout 3674R 3675\end_layout 3676 3677\end_inset 3678</cell> 3679<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none"> 3680\begin_inset Text 3681 3682\begin_layout Plain Layout 3683T 3684\end_layout 3685 3686\end_inset 3687</cell> 3688</row> 3689<row> 3690<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> 3691\begin_inset Text 3692 3693\begin_layout Plain Layout 3694\begin_inset Formula $\left\{ -1,-1\right\} $ 3695\end_inset 3696 3697 3698\end_layout 3699 3700\end_inset 3701</cell> 3702<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> 3703\begin_inset Text 3704 3705\begin_layout Plain Layout 3706illegal 3707\end_layout 3708 3709\end_inset 3710</cell> 3711<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> 3712\begin_inset Text 3713 3714\begin_layout Plain Layout 3715\begin_inset Formula $\left\{ 0,-1\right\} $ 3716\end_inset 3717 3718 3719\end_layout 3720 3721\end_inset 3722</cell> 3723<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> 3724\begin_inset Text 3725 3726\begin_layout Plain Layout 3727-0.1 3728\begin_inset space \thinspace{} 3729\end_inset 3730 3731s 3732\end_layout 3733 3734\end_inset 3735</cell> 3736<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> 3737\begin_inset Text 3738 3739\begin_layout Plain Layout 3740\begin_inset Formula $\left\{ 1,-1\right\} $ 3741\end_inset 3742 3743 3744\end_layout 3745 3746\end_inset 3747</cell> 3748<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> 3749\begin_inset Text 3750 3751\begin_layout Plain Layout 3752illegal 3753\end_layout 3754 3755\end_inset 3756</cell> 3757</row> 3758<row> 3759<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> 3760\begin_inset Text 3761 3762\begin_layout Plain Layout 3763\begin_inset Formula $\left\{ -1,0\right\} $ 3764\end_inset 3765 3766 3767\end_layout 3768 3769\end_inset 3770</cell> 3771<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> 3772\begin_inset Text 3773 3774\begin_layout Plain Layout 3775-1.0 3776\begin_inset space \thinspace{} 3777\end_inset 3778 3779s 3780\end_layout 3781 3782\end_inset 3783</cell> 3784<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> 3785\begin_inset Text 3786 3787\begin_layout Plain Layout 3788\begin_inset Formula $\left\{ 0,0\right\} $ 3789\end_inset 3790 3791 3792\end_layout 3793 3794\end_inset 3795</cell> 3796<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> 3797\begin_inset Text 3798 3799\begin_layout Plain Layout 38000.0 3801\begin_inset space \thinspace{} 3802\end_inset 3803 3804s 3805\end_layout 3806 3807\end_inset 3808</cell> 3809<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> 3810\begin_inset Text 3811 3812\begin_layout Plain Layout 3813\begin_inset Formula $\left\{ 1,0\right\} $ 3814\end_inset 3815 3816 3817\end_layout 3818 3819\end_inset 3820</cell> 3821<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> 3822\begin_inset Text 3823 3824\begin_layout Plain Layout 38251.0 3826\begin_inset space \thinspace{} 3827\end_inset 3828 3829s 3830\end_layout 3831 3832\end_inset 3833</cell> 3834</row> 3835<row> 3836<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none"> 3837\begin_inset Text 3838 3839\begin_layout Plain Layout 3840\begin_inset Formula $\left\{ -1,1\right\} $ 3841\end_inset 3842 3843 3844\end_layout 3845 3846\end_inset 3847</cell> 3848<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none"> 3849\begin_inset Text 3850 3851\begin_layout Plain Layout 3852-1.1 3853\begin_inset space \thinspace{} 3854\end_inset 3855 3856s 3857\end_layout 3858 3859\end_inset 3860</cell> 3861<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none"> 3862\begin_inset Text 3863 3864\begin_layout Plain Layout 3865\begin_inset Formula $\left\{ 0,1\right\} $ 3866\end_inset 3867 3868 3869\end_layout 3870 3871\end_inset 3872</cell> 3873<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none"> 3874\begin_inset Text 3875 3876\begin_layout Plain Layout 38770.1 3878\begin_inset space \thinspace{} 3879\end_inset 3880 3881s 3882\end_layout 3883 3884\end_inset 3885</cell> 3886<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none"> 3887\begin_inset Text 3888 3889\begin_layout Plain Layout 3890\begin_inset Formula $\left\{ 1,1\right\} $ 3891\end_inset 3892 3893 3894\end_layout 3895 3896\end_inset 3897</cell> 3898<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none"> 3899\begin_inset Text 3900 3901\begin_layout Plain Layout 39021.1 3903\begin_inset space \thinspace{} 3904\end_inset 3905 3906s 3907\end_layout 3908 3909\end_inset 3910</cell> 3911</row> 3912</lyxtabular> 3913 3914\end_inset 3915 3916 3917\end_layout 3918 3919\begin_layout Standard 3920The set of so-extended valid timespecs is therefore: 3921\end_layout 3922 3923\begin_layout Standard 3924\begin_inset Formula 3925\[ 3926K=\left\{ \left(i,f\right):i,f\in\mathbb{Z}\wedge i\neq0\wedge0\leq f<10^{9}\right\} \cup\left\{ \left(i,f\right):i=0\wedge f\in\mathbb{Z}\wedge-10^{9}<f<10^{9}\right\} 3927\] 3928 3929\end_inset 3930 3931 3932\end_layout 3933 3934\begin_layout Subsection 3935Function list 3936\end_layout 3937 3938\begin_layout LyX-Code 3939 3940\series bold 3941#include 3942\series default 3943 <libHX/misc.h> 3944\begin_inset Newline newline 3945\end_inset 3946 3947 3948\begin_inset Newline newline 3949\end_inset 3950 3951 3952\series bold 3953bool 3954\series default 3955 HX_timespec_isneg( 3956\series bold 3957const struct 3958\series default 3959 timespec 3960\series bold 3961* 3962\series default 3963p); 3964\begin_inset Index idx 3965status open 3966 3967\begin_layout Plain Layout 3968HX_timespec_isneg 3969\end_layout 3970 3971\end_inset 3972 3973 3974\begin_inset Newline newline 3975\end_inset 3976 3977 3978\series bold 3979struct 3980\series default 3981 timespec 3982\series bold 3983* 3984\series default 3985HX_timespec_neg( 3986\series bold 3987struct 3988\series default 3989 timespec 3990\series bold 3991* 3992\series default 3993result, 3994\begin_inset Newline newline 3995\end_inset 3996 3997 3998\series bold 3999const struct 4000\series default 4001 timespec 4002\series bold 4003* 4004\series default 4005p); 4006\begin_inset Index idx 4007status open 4008 4009\begin_layout Plain Layout 4010HX_timespec_neg 4011\end_layout 4012 4013\end_inset 4014 4015 4016\begin_inset Newline newline 4017\end_inset 4018 4019 4020\series bold 4021struct 4022\series default 4023 timespec 4024\series bold 4025* 4026\series default 4027HX_timespec_add( 4028\series bold 4029struct 4030\series default 4031 timespec 4032\series bold 4033* 4034\series default 4035result, 4036\begin_inset Newline newline 4037\end_inset 4038 4039 4040\series bold 4041const struct 4042\series default 4043 timespec 4044\series bold 4045* 4046\series default 4047p, 4048\series bold 4049const struct 4050\series default 4051 timespec 4052\series bold 4053* 4054\series default 4055q); 4056\begin_inset Index idx 4057status open 4058 4059\begin_layout Plain Layout 4060HX_timespec_add 4061\end_layout 4062 4063\end_inset 4064 4065 4066\begin_inset Newline newline 4067\end_inset 4068 4069 4070\series bold 4071struct 4072\series default 4073 timespec 4074\series bold 4075* 4076\series default 4077HX_timespec_sub( 4078\series bold 4079struct 4080\series default 4081 timespec 4082\series bold 4083* 4084\series default 4085delta, 4086\begin_inset Newline newline 4087\end_inset 4088 4089 4090\series bold 4091const struct 4092\series default 4093 timespec 4094\series bold 4095* 4096\series default 4097p, 4098\series bold 4099const struct 4100\series default 4101 timespec 4102\series bold 4103* 4104\series default 4105q); 4106\begin_inset Index idx 4107status open 4108 4109\begin_layout Plain Layout 4110 4111\family typewriter 4112HX_timespec_sub 4113\end_layout 4114 4115\end_inset 4116 4117 4118\begin_inset Newline newline 4119\end_inset 4120 4121 4122\series bold 4123struct 4124\series default 4125 timespec 4126\series bold 4127* 4128\series default 4129HX_timespec_mul( 4130\series bold 4131struct 4132\series default 4133 timespec 4134\series bold 4135* 4136\series default 4137delta, 4138\begin_inset Newline newline 4139\end_inset 4140 4141 4142\series bold 4143const struct 4144\series default 4145 timespec 4146\series bold 4147* 4148\series default 4149p, 4150\series bold 4151int 4152\series default 4153 f); 4154\begin_inset Index idx 4155status open 4156 4157\begin_layout Plain Layout 4158HX_timespec_mul 4159\end_layout 4160 4161\end_inset 4162 4163 4164\end_layout 4165 4166\begin_layout LyX-Code 4167 4168\series bold 4169struct 4170\series default 4171 timespec 4172\series bold 4173* 4174\series default 4175HX_timespec_mulf( 4176\series bold 4177struct 4178\series default 4179 timespec 4180\series bold 4181* 4182\series default 4183delta, 4184\begin_inset Newline newline 4185\end_inset 4186 4187 4188\series bold 4189const struct 4190\series default 4191 timespec 4192\series bold 4193* 4194\series default 4195p, 4196\series bold 4197double 4198\series default 4199 f); 4200\begin_inset Index idx 4201status open 4202 4203\begin_layout Plain Layout 4204HX_timespec_mulf 4205\end_layout 4206 4207\end_inset 4208 4209 4210\end_layout 4211 4212\begin_layout LyX-Code 4213 4214\series bold 4215struct 4216\series default 4217 timeval 4218\series bold 4219* 4220\series default 4221HX_timeval_sub( 4222\series bold 4223struct 4224\series default 4225 timeval 4226\series bold 4227* 4228\series default 4229delta, 4230\begin_inset Newline newline 4231\end_inset 4232 4233 4234\series bold 4235const struct 4236\series default 4237 timeval 4238\series bold 4239* 4240\series default 4241p, 4242\series bold 4243const struct 4244\series default 4245 timeval 4246\series bold 4247* 4248\series default 4249q); 4250\begin_inset Index idx 4251status open 4252 4253\begin_layout Plain Layout 4254 4255\family typewriter 4256HX_timeval_sub 4257\end_layout 4258 4259\end_inset 4260 4261 4262\begin_inset Newline newline 4263\end_inset 4264 4265 4266\series bold 4267int 4268\series default 4269 HX_time_compare( 4270\series bold 4271const struct 4272\series default 4273 stat 4274\series bold 4275* 4276\series default 4277a, 4278\series bold 4279const struct 4280\series default 4281 stat 4282\series bold 4283* 4284\series default 4285b, 4286\series bold 4287int 4288\series default 4289 mode); 4290\begin_inset Index idx 4291status open 4292 4293\begin_layout Plain Layout 4294 4295\family typewriter 4296HX_time_compare 4297\end_layout 4298 4299\end_inset 4300 4301 4302\end_layout 4303 4304\begin_layout Description 4305 4306\family typewriter 4307HX_timespec_isneg 4308\family default 4309 Determines whether a timespec structure represents (non-zero) negative 4310 time. 4311\end_layout 4312 4313\begin_layout Description 4314 4315\family typewriter 4316HX_timespec_neg 4317\family default 4318 Computes the negation of the time specified by 4319\family typewriter 4320p 4321\family default 4322. 4323 4324\family typewriter 4325result 4326\family default 4327 and 4328\family typewriter 4329p 4330\family default 4331 may point to the same structure. 4332\end_layout 4333 4334\begin_layout Description 4335 4336\family typewriter 4337HX_timespec_add 4338\family default 4339 Calculates the sum of the two times specified by 4340\family typewriter 4341p 4342\family default 4343 and 4344\family typewriter 4345q 4346\family default 4347, which are of type 4348\family typewriter 4349struct timespec 4350\family default 4351. 4352 Any of 4353\family typewriter 4354result 4355\family default 4356, 4357\family typewriter 4358p 4359\family default 4360 and 4361\family typewriter 4362q 4363\family default 4364 may point to the same structure. 4365\end_layout 4366 4367\begin_layout Description 4368 4369\family typewriter 4370HX_timespec_sub 4371\family default 4372 Calculates the difference between the two timepoints p and q, which are 4373 of type 4374\family typewriter 4375struct timespec 4376\family default 4377 (nanosecond granularity). 4378\end_layout 4379 4380\begin_layout Description 4381 4382\family typewriter 4383HX_timespec_mul 4384\family default 4385 Multiplies the time quantum in 4386\family typewriter 4387p 4388\family default 4389 by 4390\family typewriter 4391f 4392\family default 4393. 4394\end_layout 4395 4396\begin_layout Description 4397 4398\family typewriter 4399HX_timespec_mulf 4400\family default 4401 Multiplies the time quantum in 4402\family typewriter 4403p 4404\family default 4405 by 4406\family typewriter 4407f 4408\family default 4409. 4410\end_layout 4411 4412\begin_layout Description 4413 4414\family typewriter 4415HX_timeval_sub 4416\family default 4417 Calculates the difference between the two timepoints p and q, which are 4418 of type 4419\family typewriter 4420struct timeval 4421\family default 4422 (microsecnod granularity). 4423\end_layout 4424 4425\begin_layout Description 4426 4427\family typewriter 4428HX_time_compare 4429\family default 4430 Compares the timestamps from two 4431\family typewriter 4432struct stat 4433\family default 4434s. 4435 4436\family typewriter 4437mode 4438\family default 4439 indicates which field is compared, which can either be 4440\family typewriter 4441'a' 4442\family default 4443 for the access time, 4444\family typewriter 4445'c' 4446\family default 4447 for the inode change time, 4448\family typewriter 4449'm' 4450\family default 4451 for the modification time, or 4452\family typewriter 4453'o' 4454\family default 4455 for the creation time (where available). 4456 Returns a negative number if the time in 4457\family typewriter 4458a 4459\family default 4460 is less than 4461\family typewriter 4462b 4463\family default 4464, zero when they are equal, or a positive number greater than zero if 4465\family typewriter 4466a 4467\family default 4468 is greater than 4469\family typewriter 4470b 4471\family default 4472. 4473\end_layout 4474 4475\begin_layout Standard 4476The macros 4477\family typewriter 4478HX_TIMESPEC_FMT 4479\family default 4480 4481\begin_inset Index idx 4482status open 4483 4484\begin_layout Plain Layout 4485 4486\family typewriter 4487HX_TIMESPEC_FMT 4488\end_layout 4489 4490\end_inset 4491 4492 and 4493\family typewriter 4494HX_TIMESPEC_EXP 4495\family default 4496 4497\begin_inset Index idx 4498status open 4499 4500\begin_layout Plain Layout 4501 4502\family typewriter 4503HX_TIMESPEC_EXP 4504\end_layout 4505 4506\end_inset 4507 4508 can be used for passing and printing a 4509\family typewriter 4510struct timespec 4511\family default 4512 using the * 4513\family typewriter 4514printf 4515\family default 4516 function family: 4517\end_layout 4518 4519\begin_layout LyX-Code 4520 4521\series bold 4522struct 4523\series default 4524 timespec p; 4525\begin_inset Newline newline 4526\end_inset 4527 4528clock_gettime(CLOCK_MONOTONIC, &p); 4529\begin_inset Newline newline 4530\end_inset 4531 4532printf("Now: " HX_TIMESPEC_FMT, HX_TIMESPEC_EXP(&p)); 4533\end_layout 4534 4535\begin_layout Standard 4536Similarly, 4537\family typewriter 4538HX_TIMEVAL_FMT 4539\family default 4540 4541\begin_inset Index idx 4542status open 4543 4544\begin_layout Plain Layout 4545 4546\family typewriter 4547HX_TIMEVAL_FMT 4548\end_layout 4549 4550\end_inset 4551 4552 and 4553\family typewriter 4554HX_TIMEVAL_EXP 4555\family default 4556 4557\begin_inset Index idx 4558status open 4559 4560\begin_layout Plain Layout 4561 4562\family typewriter 4563HX_TIMEVAL_EXP 4564\end_layout 4565 4566\end_inset 4567 4568 exist for the older 4569\family typewriter 4570struct timeval 4571\family default 4572. 4573\end_layout 4574 4575\begin_layout Standard 4576\begin_inset Newpage clearpage 4577\end_inset 4578 4579 4580\end_layout 4581 4582\begin_layout Section 4583Bitmaps 4584\end_layout 4585 4586\begin_layout LyX-Code 4587 4588\series bold 4589#include 4590\series default 4591 <libHX/misc.h> 4592\begin_inset Newline newline 4593\end_inset 4594 4595 4596\begin_inset Newline newline 4597\end_inset 4598 4599 4600\series bold 4601size_t 4602\series default 4603 HXbitmap_size( 4604\series bold 4605type 4606\series default 4607 array, 4608\series bold 4609unsigned int 4610\series default 4611 bits); 4612\begin_inset Index idx 4613status open 4614 4615\begin_layout Plain Layout 4616 4617\family typewriter 4618HXbitmap_size 4619\end_layout 4620 4621\end_inset 4622 4623 4624\begin_inset Newline newline 4625\end_inset 4626 4627 4628\series bold 4629void 4630\series default 4631 HXbitmap_set( 4632\series bold 4633type * 4634\series default 4635bmap, 4636\series bold 4637unsigned int 4638\series default 4639 bit); 4640\begin_inset Index idx 4641status open 4642 4643\begin_layout Plain Layout 4644 4645\family typewriter 4646HXbitmap_set 4647\end_layout 4648 4649\end_inset 4650 4651 4652\begin_inset Newline newline 4653\end_inset 4654 4655 4656\series bold 4657void 4658\series default 4659 HXbitmap_clear( 4660\series bold 4661type * 4662\series default 4663bmap, 4664\series bold 4665unsigned int 4666\series default 4667 bit); 4668\begin_inset Index idx 4669status open 4670 4671\begin_layout Plain Layout 4672 4673\family typewriter 4674HXbitmap_clear 4675\end_layout 4676 4677\end_inset 4678 4679 4680\begin_inset Newline newline 4681\end_inset 4682 4683 4684\series bold 4685bool 4686\series default 4687 HXbitmap_test( 4688\series bold 4689type * 4690\series default 4691bmap, 4692\series bold 4693unsigned int 4694\series default 4695 bit); 4696\begin_inset Index idx 4697status open 4698 4699\begin_layout Plain Layout 4700 4701\family typewriter 4702HXbitmap_test 4703\end_layout 4704 4705\end_inset 4706 4707 4708\end_layout 4709 4710\begin_layout Standard 4711All of these four are implemented as macros, so they can be used with any 4712 integer type that is desired to be used. 4713\end_layout 4714 4715\begin_layout Description 4716 4717\family typewriter 4718HXbitmap_size 4719\family default 4720 Returns the amount of 4721\begin_inset Quotes eld 4722\end_inset 4723 4724type 4725\begin_inset Quotes erd 4726\end_inset 4727 4728-based integers that would be needed to hold an array of the requested amount 4729 of bits. 4730\end_layout 4731 4732\begin_layout Description 4733 4734\family typewriter 4735HXbitmap_set 4736\family default 4737 Set the specific bit in the bitmap. 4738\end_layout 4739 4740\begin_layout Description 4741 4742\family typewriter 4743HXbitmap_clear 4744\family default 4745 Clear the specific bit in this bitmap. 4746\end_layout 4747 4748\begin_layout Description 4749 4750\family typewriter 4751HXbitmap_test 4752\family default 4753 Test for the specific bit and returns 4754\family typewriter 4755true 4756\family default 4757 if it is set, otherwise 4758\family typewriter 4759false 4760\family default 4761. 4762\end_layout 4763 4764\begin_layout Subsubsection 4765Example 4766\end_layout 4767 4768\begin_layout LyX-Code 4769 4770\series bold 4771#include 4772\series default 4773 <stdlib.h> 4774\begin_inset Newline newline 4775\end_inset 4776 4777 4778\series bold 4779#include 4780\series default 4781 <string.h> 4782\begin_inset Newline newline 4783\end_inset 4784 4785 4786\series bold 4787#include 4788\series default 4789 <libHX/misc.h> 4790\begin_inset Newline newline 4791\end_inset 4792 4793 4794\begin_inset Newline newline 4795\end_inset 4796 4797 4798\series bold 4799int 4800\series default 4801 main( 4802\series bold 4803void 4804\series default 4805) 4806\begin_inset Newline newline 4807\end_inset 4808 4809{ 4810\begin_inset Newline newline 4811\end_inset 4812 4813 4814\series bold 4815unsigned long 4816\series default 4817 bitmap 4818\series bold 4819[ 4820\series default 4821HXbitmap_size( 4822\series bold 4823unsigned long 4824\series default 4825, 128) 4826\series bold 4827] 4828\series default 4829; 4830\begin_inset Newline newline 4831\end_inset 4832 4833 4834\begin_inset Newline newline 4835\end_inset 4836 4837 memset(bitmap, 0, sizeof(bitmap)); 4838\begin_inset Newline newline 4839\end_inset 4840 4841 HXbitmap_set(bitmap, 49); 4842\begin_inset Newline newline 4843\end_inset 4844 4845 4846\series bold 4847return 4848\series default 4849 HXbitmap_get(bitmap, HX_irand(0, 128)) ? 4850\begin_inset Newline newline 4851\end_inset 4852 4853 EXIT_SUCCESS : EXIT_FAILURE; 4854\begin_inset Newline newline 4855\end_inset 4856 4857} 4858\end_layout 4859 4860\begin_layout Standard 4861\begin_inset Newpage clearpage 4862\end_inset 4863 4864 4865\end_layout 4866 4867\begin_layout Part 4868Data structures 4869\end_layout 4870 4871\begin_layout Section 4872Maps 4873\begin_inset CommandInset label 4874LatexCommand label 4875name "sec:maps" 4876 4877\end_inset 4878 4879 4880\end_layout 4881 4882\begin_layout Standard 4883A map is a collection of key-value pairs. 4884 (Some languages, such as Perl, also call them 4885\begin_inset Quotes eld 4886\end_inset 4887 4888associative array 4889\begin_inset Quotes erd 4890\end_inset 4891 4892 or just 4893\begin_inset Quotes eld 4894\end_inset 4895 4896hash 4897\begin_inset Quotes erd 4898\end_inset 4899 4900, however, the underlying storage mechanism may not be an array or a hash, 4901 however.) Each key is unique and has an associated value. 4902 Keys can be any data desired; HXmap allows to specify your own key and 4903 data handling functions so they can be strings, raw pointers, or complex 4904 structures. 4905\end_layout 4906 4907\begin_layout Standard 4908To access any map-related functions, 4909\family typewriter 4910#include <libHX\SpecialChar breakableslash 4911map.h> 4912\family default 4913. 4914\end_layout 4915 4916\begin_layout Subsection 4917Structural definition 4918\begin_inset CommandInset label 4919LatexCommand label 4920name "subsec:maps-def" 4921 4922\end_inset 4923 4924 4925\end_layout 4926 4927\begin_layout Standard 4928The 4929\family typewriter 4930HXmap 4931\family default 4932 structure is a near-opaque type. 4933 Unlike the predecessor map implementation 4934\family typewriter 4935struct HXbtree 4936\family default 4937 from libHX 2.x, the 3.x API exposes much less fields. 4938\end_layout 4939 4940\begin_layout LyX-Code 4941 4942\series bold 4943struct 4944\series default 4945 HXmap { 4946\begin_inset Index idx 4947status open 4948 4949\begin_layout Plain Layout 4950 4951\family typewriter 4952struct HXmap 4953\end_layout 4954 4955\end_inset 4956 4957 4958\begin_inset Newline newline 4959\end_inset 4960 4961 4962\series bold 4963unsigned int 4964\series default 4965 items, flags; 4966\begin_inset Newline newline 4967\end_inset 4968 4969}; 4970\end_layout 4971 4972\begin_layout Description 4973 4974\family typewriter 4975items 4976\family default 4977 The number of items in the tree. 4978 This field tracks the number of items in the map and is used to report 4979 the number of elements to the user, and is updated whenever an element 4980 is inserted or removed from the map. 4981 The field must not be changed by user. 4982\end_layout 4983 4984\begin_layout Description 4985 4986\family typewriter 4987flags 4988\family default 4989 The current behavior flags for the map. 4990 While implementation-private bits are exposed, only 4991\family typewriter 4992HXMAP_NOREPLACE 4993\family default 4994 is currently allowed to be (un)set by the developer while a map exists. 4995\end_layout 4996 4997\begin_layout Standard 4998For retrieving elements from a tree, some functions work with 4999\family typewriter 5000struct HXmap_node 5001\family default 5002, which is defined as follows: 5003\end_layout 5004 5005\begin_layout LyX-Code 5006 5007\series bold 5008struct 5009\series default 5010 HXmap_node { 5011\begin_inset Index idx 5012status open 5013 5014\begin_layout Plain Layout 5015 5016\family typewriter 5017struct HXmap_node 5018\end_layout 5019 5020\end_inset 5021 5022 5023\begin_inset Newline newline 5024\end_inset 5025 5026 5027\series bold 5028union 5029\series default 5030 { 5031\begin_inset Newline newline 5032\end_inset 5033 5034 5035\series bold 5036void * 5037\series default 5038key; 5039\begin_inset Newline newline 5040\end_inset 5041 5042 5043\series bold 5044const char *const 5045\series default 5046 skey; 5047\begin_inset Newline newline 5048\end_inset 5049 5050 }; 5051\begin_inset Newline newline 5052\end_inset 5053 5054 5055\series bold 5056union 5057\series default 5058 { 5059\begin_inset Newline newline 5060\end_inset 5061 5062 5063\series bold 5064void * 5065\series default 5066data; 5067\begin_inset Newline newline 5068\end_inset 5069 5070 5071\series bold 5072char * 5073\series default 5074sdata; 5075\begin_inset Newline newline 5076\end_inset 5077 5078 }; 5079\begin_inset Newline newline 5080\end_inset 5081 5082}; 5083\end_layout 5084 5085\begin_layout Description 5086 5087\family typewriter 5088key 5089\family default 5090 The so-called primary key, which uniquely identifies an element (a key-value 5091 pair) in the map. 5092 The memory portions that make up the key must not be modified. 5093 (If the key changes, so does its hash value and/or position index, and 5094 without taking that into account, writing to the key directly is going 5095 to end up with an inconsistent state. 5096 To change the key, you will need to delete the element and reinsert it 5097 with its new key.) 5098\end_layout 5099 5100\begin_layout Description 5101 5102\family typewriter 5103skey 5104\family default 5105 A convenience type field for when the map's keys are C strings. 5106 It is useful for use with e. 5107\begin_inset space \thinspace{} 5108\end_inset 5109 5110g. 5111\begin_inset space \space{} 5112\end_inset 5113 5114 5115\family typewriter 5116printf 5117\family default 5118 or other varargs function, which would otherwise require casting of the 5119 5120\family typewriter 5121void 5122\begin_inset space ~ 5123\end_inset 5124 5125*key 5126\family default 5127 member to 5128\family typewriter 5129const char 5130\begin_inset space ~ 5131\end_inset 5132 5133* 5134\family default 5135 first. 5136\end_layout 5137 5138\begin_layout Description 5139 5140\family typewriter 5141data 5142\family default 5143 The data associated with the key. 5144\end_layout 5145 5146\begin_layout Description 5147 5148\family typewriter 5149sdata 5150\family default 5151 Convenience type field. 5152\end_layout 5153 5154\begin_layout Subsection 5155Map initialization 5156\end_layout 5157 5158\begin_layout Standard 5159During initialization, you specify the underlying storage type by selecting 5160 a given constructor function. 5161 All further operations are done through the unified HXmap API which uses 5162 a form of virtual calls internally. 5163\end_layout 5164 5165\begin_layout Standard 5166Currently, there are two distinct map types in libHX. 5167 There are a handful of selectable symbols, though. 5168 Abstract types are: 5169\end_layout 5170 5171\begin_layout Description 5172 5173\family typewriter 5174HXMAPT_DEFAULT 5175\family default 5176 5177\begin_inset Index idx 5178status open 5179 5180\begin_layout Plain Layout 5181 5182\family typewriter 5183HXMAPT_DEFAULT 5184\end_layout 5185 5186\end_inset 5187 5188 No further preferences or guarantees; selects any map type that the libHX 5189 maintainer deemed fast. 5190\end_layout 5191 5192\begin_layout Description 5193 5194\family typewriter 5195HXMAPT_ORDERED 5196\family default 5197 5198\begin_inset Index idx 5199status open 5200 5201\begin_layout Plain Layout 5202 5203\family typewriter 5204HXMAPT_ORDERED 5205\end_layout 5206 5207\end_inset 5208 5209 The map shall use a data structure that provides ordered traversal. 5210\end_layout 5211 5212\begin_layout Standard 5213Specific types include: 5214\end_layout 5215 5216\begin_layout Description 5217 5218\family typewriter 5219HXMAPT_HASH 5220\family default 5221 5222\begin_inset Index idx 5223status open 5224 5225\begin_layout Plain Layout 5226 5227\family typewriter 5228HX_MAPT_HASH 5229\end_layout 5230 5231\end_inset 5232 5233 Hash-based map 5234\begin_inset space ~ 5235\end_inset 5236 5237– Amortized 5238\begin_inset Formula $\mathcal{O}\left(1\right)$ 5239\end_inset 5240 5241 insertion, lookup and deletion; unordered. 5242\end_layout 5243 5244\begin_layout Description 5245 5246\family typewriter 5247HXMAPT_RBTREE 5248\family default 5249 5250\begin_inset Index idx 5251status open 5252 5253\begin_layout Plain Layout 5254 5255\family typewriter 5256HX_MAPT_RBTREE 5257\end_layout 5258 5259\end_inset 5260 5261 Red-black binary tree 5262\begin_inset space ~ 5263\end_inset 5264 5265– 5266\begin_inset Formula $\mathcal{O}\left(\log\left(n\right)\right)$ 5267\end_inset 5268 5269 insertion, lookup and deletion; ordered. 5270\end_layout 5271 5272\begin_layout Standard 5273These can then be used with the initialization functions: 5274\end_layout 5275 5276\begin_layout LyX-Code 5277 5278\series bold 5279struct 5280\series default 5281 HXmap 5282\series bold 5283* 5284\series default 5285HXmap_init( 5286\series bold 5287unsigned int 5288\series default 5289 type, 5290\series bold 5291unsigned int 5292\series default 5293 flags); 5294\begin_inset Index idx 5295status open 5296 5297\begin_layout Plain Layout 5298 5299\family typewriter 5300HXmap_init 5301\end_layout 5302 5303\end_inset 5304 5305 5306\begin_inset Newline newline 5307\end_inset 5308 5309 5310\series bold 5311struct 5312\series default 5313 HXmap 5314\series bold 5315* 5316\series default 5317HXmap_init5( 5318\series bold 5319unsigned int 5320\series default 5321 type, 5322\series bold 5323unsigned int 5324\series default 5325 flags, 5326\begin_inset Newline newline 5327\end_inset 5328 5329 5330\series bold 5331const struct 5332\series default 5333 HXmap_ops 5334\series bold 5335* 5336\series default 5337ops, 5338\series bold 5339size_t 5340\series default 5341 key_size, 5342\series bold 5343size_t 5344\series default 5345 data_size); 5346\begin_inset Index idx 5347status open 5348 5349\begin_layout Plain Layout 5350 5351\family typewriter 5352HXmap_init5 5353\end_layout 5354 5355\end_inset 5356 5357 5358\end_layout 5359 5360\begin_layout Standard 5361Both the 5362\family typewriter 5363*_init 5364\family default 5365 and 5366\family typewriter 5367*_init5 5368\family default 5369 variant creates a new map; the latter function allows to specify the operations 5370 in detail as well as key and data size, which may become necessary when 5371 using data sets which have their own way of being managed. 5372 The 5373\family typewriter 5374flags 5375\family default 5376 parameter can contain any of the following: 5377\end_layout 5378 5379\begin_layout Description 5380 5381\family typewriter 5382HXMAP_NONE 5383\family default 5384 5385\begin_inset Index idx 5386status open 5387 5388\begin_layout Plain Layout 5389 5390\family typewriter 5391HXMAP_NONE 5392\end_layout 5393 5394\end_inset 5395 5396 This is just a mnemonic for the value 0, indicating no flags. 5397\end_layout 5398 5399\begin_layout Description 5400 5401\family typewriter 5402HXMAP_NOREPLACE 5403\family default 5404 5405\begin_inset Index idx 5406status open 5407 5408\begin_layout Plain Layout 5409 5410\family typewriter 5411HXMAP_NOREPLACE 5412\end_layout 5413 5414\end_inset 5415 5416 If a key already exists and another add operation is attempted, the key's 5417 associated value will be replaced by the new value. 5418 If this flag is absent, 5419\family typewriter 5420-EEXIST 5421\family default 5422 is returned. 5423 This flag is allowed to be subsequently changed by the developer if so 5424 desired, using bit logic such as 5425\family typewriter 5426map->flags &= ~HXMAP_NOREPLACE; 5427\family default 5428. 5429\end_layout 5430 5431\begin_layout Description 5432 5433\family typewriter 5434HXMAP_SKEY 5435\family default 5436 5437\begin_inset Index idx 5438status open 5439 5440\begin_layout Plain Layout 5441 5442\family typewriter 5443HXMAP_SKEY 5444\end_layout 5445 5446\end_inset 5447 5448 Notifies the constructor that keys will be C-style strings. 5449 The flag presets the 5450\family typewriter 5451k_compare 5452\family default 5453 operation to use 5454\family typewriter 5455strcmp 5456\family default 5457. 5458 In the flag's absence, direct value comparison will be used if the key 5459 size is specified as zero (e. 5460\begin_inset space \thinspace{} 5461\end_inset 5462 5463g. 5464\begin_inset space \space{} 5465\end_inset 5466 5467with the 5468\family typewriter 5469HXhashmap_\SpecialChar softhyphen 5470init4 5471\family default 5472 function call), or 5473\family typewriter 5474memcmp 5475\family default 5476 if the key size is non-zero. 5477\end_layout 5478 5479\begin_layout Description 5480 5481\family typewriter 5482HXMAP_CKEY 5483\family default 5484 5485\begin_inset Index idx 5486status open 5487 5488\begin_layout Plain Layout 5489 5490\family typewriter 5491HXMAP_CKEY 5492\end_layout 5493 5494\end_inset 5495 5496 Instructs the map to make copies of keys when they are added to the map. 5497 This is required when the buffer holding the key changes or goes out of 5498 scope. 5499 The flag presets the 5500\family typewriter 5501k_clone 5502\family default 5503 and 5504\family typewriter 5505k_free 5506\family default 5507 operations to 5508\family typewriter 5509HX_memdup 5510\family default 5511 and 5512\family typewriter 5513free 5514\family default 5515, and as such, the 5516\family typewriter 5517key_size 5518\family default 5519 parameter must not be zero. 5520 If however, 5521\family typewriter 5522HXMAP_SKEY 5523\family default 5524 is also specified, 5525\family typewriter 5526HX_strdup 5527\family default 5528 and 5529\family typewriter 5530free 5531\family default 5532 will be used and 5533\family typewriter 5534key_size 5535\family default 5536 must be zero. 5537\end_layout 5538 5539\begin_layout Description 5540 5541\family typewriter 5542HXMAP_SDATA 5543\family default 5544 5545\begin_inset Index idx 5546status open 5547 5548\begin_layout Plain Layout 5549 5550\family typewriter 5551HXMAP_SDATA 5552\end_layout 5553 5554\end_inset 5555 5556 Notifies the constructor that data will be C-style strings. 5557 This sets up the 5558\family typewriter 5559d_clone 5560\family default 5561 and 5562\family typewriter 5563d_free 5564\family default 5565 operations. 5566\end_layout 5567 5568\begin_layout Description 5569 5570\family typewriter 5571HXMAP_CDATA 5572\family default 5573 5574\begin_inset Index idx 5575status open 5576 5577\begin_layout Plain Layout 5578 5579\family typewriter 5580HXMAP_CDATA 5581\end_layout 5582 5583\end_inset 5584 5585 Instructs the map to make copies of the data when new entries are added 5586 to the map. 5587 This is required when the buffer holding the data either goes out of scope, 5588 or you want to keep the original contents instead of just a pointer. 5589\end_layout 5590 5591\begin_layout Description 5592 5593\family typewriter 5594HXMAP_SCKEY 5595\family default 5596 5597\begin_inset Index idx 5598status open 5599 5600\begin_layout Plain Layout 5601 5602\family typewriter 5603HXMAP_SCKEY 5604\end_layout 5605 5606\end_inset 5607 5608 Mnemonic for the combination of 5609\family typewriter 5610HXMAP_\SpecialChar softhyphen 5611SKEY 5612\family default 5613 OR'ed with 5614\family typewriter 5615HXMAP_\SpecialChar softhyphen 5616CKEY 5617\family default 5618. 5619\end_layout 5620 5621\begin_layout Description 5622 5623\family typewriter 5624HXMAP_SCDATA 5625\family default 5626 5627\begin_inset Index idx 5628status open 5629 5630\begin_layout Plain Layout 5631 5632\family typewriter 5633HXMAP_SCDATA 5634\end_layout 5635 5636\end_inset 5637 5638 Mnemonic for the combination of 5639\family typewriter 5640HXMAP_\SpecialChar softhyphen 5641SDATA 5642\family default 5643 OR'ed with 5644\family typewriter 5645HXMAP_\SpecialChar softhyphen 5646SDATA 5647\family default 5648. 5649\end_layout 5650 5651\begin_layout Description 5652 5653\family typewriter 5654HXMAP_SINGULAR 5655\family default 5656 5657\begin_inset Index idx 5658status open 5659 5660\begin_layout Plain Layout 5661 5662\family typewriter 5663HXMAP_SINGULAR 5664\end_layout 5665 5666\end_inset 5667 5668 Specifies that the 5669\begin_inset Quotes eld 5670\end_inset 5671 5672map 5673\begin_inset Quotes erd 5674\end_inset 5675 5676 is only used as a set, i. 5677\begin_inset space \thinspace{} 5678\end_inset 5679 5680e. 5681\begin_inset space \space{} 5682\end_inset 5683 5684it does not store any values, only keys. 5685 Henceforth, the 5686\family typewriter 5687value 5688\family default 5689 argument to 5690\family typewriter 5691HXmap_add 5692\family default 5693 must always be 5694\family typewriter 5695NULL 5696\family default 5697. 5698\end_layout 5699 5700\begin_layout Subsection 5701Flag combinations 5702\end_layout 5703 5704\begin_layout Standard 5705This subsection highlights the way 5706\family typewriter 5707HXMAP_SKEY 5708\family default 5709 interacts with 5710\family typewriter 5711HXMAP_CKEY 5712\family default 5713 and the key size. 5714 The copy semantics are the same for 5715\family typewriter 5716HXMAP_SDATA 5717\family default 5718 and 5719\family typewriter 5720HXMAP_CDATA 5721\family default 5722. 5723\end_layout 5724 5725\begin_layout Subsubsection* 5726 5727\family typewriter 5728HXMAP_SKEY 5729\family default 5730 is unset, 5731\family typewriter 5732HXMAP_CKEY 5733\family default 5734 is unset 5735\end_layout 5736 5737\begin_layout Standard 5738The 5739\family typewriter 5740key_size 5741\family default 5742 parameter at the time of map construction is ignored. 5743 The pointer value of the 5744\family typewriter 5745key 5746\family default 5747 parameter for the 5748\family typewriter 5749HXmap_add 5750\family default 5751 call is directly stored in the tree, and this is the key that uniquely 5752 identifies the map entry and which is used for comparisons. 5753 This may be used if you intend to directly map pointer values. 5754\end_layout 5755 5756\begin_layout LyX-Code 5757static struct something *x = ..., *y = ...; 5758\begin_inset Newline newline 5759\end_inset 5760 5761HXmap_add(map, &x[0], "foo"); 5762\begin_inset Newline newline 5763\end_inset 5764 5765HXmap_add(map, &x[1], "bar"); 5766\end_layout 5767 5768\begin_layout Subsubsection* 5769 5770\family typewriter 5771HXMAP_SKEY 5772\family default 5773 is set, 5774\family typewriter 5775HXMAP_CKEY 5776\family default 5777 is unset 5778\end_layout 5779 5780\begin_layout Standard 5781The 5782\family typewriter 5783key_size 5784\family default 5785 parameter at the time of map construction is ignored. 5786 The pointer value of the 5787\family typewriter 5788key 5789\family default 5790 parameter for the 5791\family typewriter 5792HXmap_add 5793\family default 5794 call is directly stored in the tree, but it is the C string 5795\shape italic 5796pointed to 5797\shape default 5798 by the 5799\family typewriter 5800key 5801\family default 5802 parameter that serves as the key. 5803\end_layout 5804 5805\begin_layout Subsubsection* 5806 5807\family typewriter 5808HXMAP_SKEY 5809\family default 5810 is set, 5811\family typewriter 5812HXMAP_CKEY 5813\family default 5814 is set 5815\end_layout 5816 5817\begin_layout Standard 5818The 5819\family typewriter 5820key_size 5821\family default 5822 parameter at the time of map construction is ignored. 5823 The string pointed to by the key parameter will be duplicated, and the 5824 resulting pointer will be stored in the tree. 5825 Again, it is the pointed-to string that is the key. 5826\end_layout 5827 5828\begin_layout Subsubsection* 5829 5830\family typewriter 5831HXMAP_SKEY 5832\family default 5833 is unset, 5834\family typewriter 5835HXMAP_CKEY 5836\family default 5837 is set 5838\end_layout 5839 5840\begin_layout Standard 5841The memory block pointed to by the key parameter will be duplicated. 5842 The 5843\family typewriter 5844key_size 5845\family default 5846 parameter must be non-zero for this to successfully work. 5847\end_layout 5848 5849\begin_layout Subsubsection* 5850With separate ops 5851\end_layout 5852 5853\begin_layout Standard 5854However, when a custom 5855\family typewriter 5856struct HXmap_ops 5857\family default 5858 is provided in the call to 5859\family typewriter 5860HXmap_init5 5861\family default 5862, any of these semantics can be overridden. 5863 Particularly, since your own ops can practically ignore 5864\family typewriter 5865key_size 5866\family default 5867, it could be set to any value. 5868\end_layout 5869 5870\begin_layout Subsection 5871Key-data operations 5872\end_layout 5873 5874\begin_layout Standard 5875The 5876\family typewriter 5877HXMAP_SKEY 5878\family default 5879\SpecialChar breakableslash 5880 5881\family typewriter 5882CKEY 5883\family default 5884\SpecialChar breakableslash 5885 5886\family typewriter 5887SDATA 5888\family default 5889\SpecialChar breakableslash 5890 5891\family typewriter 5892CDATA 5893\family default 5894 flags are generally sufficient to set up common maps where keys and/or 5895 data are C strings or simple binary data where 5896\family typewriter 5897memdup 5898\family default 5899/ 5900\family typewriter 5901memcmp 5902\family default 5903 is enough. 5904 Where the provided mechanisms are not cutting it, an extra 5905\family typewriter 5906HXmap_ops 5907\family default 5908 structure with functions specialized in handling the keys and/or data has 5909 to be used as an argument to the initialization function call. 5910\end_layout 5911 5912\begin_layout LyX-Code 5913 5914\series bold 5915struct 5916\series default 5917 HXmap_ops { 5918\begin_inset Index idx 5919status open 5920 5921\begin_layout Plain Layout 5922 5923\family typewriter 5924struct HXmap_ops 5925\end_layout 5926 5927\end_inset 5928 5929 5930\begin_inset Newline newline 5931\end_inset 5932 5933 5934\series bold 5935int (* 5936\series default 5937k_compare 5938\series bold 5939) 5940\series default 5941( 5942\series bold 5943const void * 5944\series default 5945, 5946\series bold 5947const void * 5948\series default 5949, 5950\series bold 5951size_t 5952\series default 5953); 5954\begin_inset Newline newline 5955\end_inset 5956 5957 5958\series bold 5959void *(* 5960\series default 5961k_clone 5962\series bold 5963) 5964\series default 5965( 5966\series bold 5967const void * 5968\series default 5969, 5970\series bold 5971size_t 5972\series default 5973); 5974\begin_inset Newline newline 5975\end_inset 5976 5977 5978\series bold 5979void (* 5980\series default 5981k_free 5982\series bold 5983) 5984\series default 5985( 5986\series bold 5987void * 5988\series default 5989); 5990\begin_inset Newline newline 5991\end_inset 5992 5993 5994\series bold 5995void *(* 5996\series default 5997d_clone 5998\series bold 5999) 6000\series default 6001( 6002\series bold 6003const void * 6004\series default 6005, 6006\series bold 6007size_t 6008\series default 6009); 6010\begin_inset Newline newline 6011\end_inset 6012 6013 6014\series bold 6015void (* 6016\series default 6017d_free 6018\series bold 6019) 6020\series default 6021( 6022\series bold 6023void * 6024\series default 6025); 6026\begin_inset Newline newline 6027\end_inset 6028 6029 6030\series bold 6031unsigned long (* 6032\series default 6033k_hash 6034\series bold 6035) 6036\series default 6037( 6038\series bold 6039const void * 6040\series default 6041, 6042\series bold 6043size_t 6044\series default 6045); 6046\begin_inset Newline newline 6047\end_inset 6048 6049}; 6050\end_layout 6051 6052\begin_layout Description 6053 6054\family typewriter 6055k_compare 6056\family default 6057 Function to compare two keys. 6058 The return value is the same as that of 6059\family typewriter 6060memcmp 6061\family default 6062 or 6063\family typewriter 6064strcmp 6065\family default 6066: negative values indicate that the first key is 6067\begin_inset Quotes eld 6068\end_inset 6069 6070less than 6071\begin_inset Quotes erd 6072\end_inset 6073 6074 the second, zero indicates that both keys are equal, and positive values 6075 indicate that the first key is 6076\begin_inset Quotes eld 6077\end_inset 6078 6079greater than 6080\begin_inset Quotes erd 6081\end_inset 6082 6083 the second. 6084 The size argument in third position is provided so that 6085\family typewriter 6086memcmp 6087\family default 6088, which wants a size parameter, can directly be used without having to write 6089 an own function. 6090\end_layout 6091 6092\begin_layout Description 6093 6094\family typewriter 6095k_clone 6096\family default 6097 Function that will clone (duplicate) a key. 6098 This is used for keys that will be added to the tree, and potentially also 6099 for state-keeping during traversal of the map. 6100 It is valid that this clone function simply returns the value of the pointer 6101 it was actually passed; this is used by default for maps without 6102\family typewriter 6103HXMAP_CKEY 6104\family default 6105 for example. 6106\end_layout 6107 6108\begin_layout Description 6109 6110\family typewriter 6111k_free 6112\family default 6113 Function to free a key. 6114 In most cases it defaults to 6115\family typewriter 6116free 6117\family default 6118(3), but in case you are using complex structs, more cleanup may be needed. 6119\end_layout 6120 6121\begin_layout Description 6122 6123\family typewriter 6124d_clone 6125\family default 6126 Same as 6127\family typewriter 6128k_clone 6129\family default 6130, but for data. 6131\end_layout 6132 6133\begin_layout Description 6134 6135\family typewriter 6136d_free 6137\family default 6138 Same as 6139\family typewriter 6140k_free 6141\family default 6142, but for data. 6143\end_layout 6144 6145\begin_layout Description 6146 6147\family typewriter 6148k_hash 6149\family default 6150 Specifies an alternate hash function. 6151 Only to be used with hash-based maps. 6152 Hashmaps default to using the DJB2 string hash function when 6153\family typewriter 6154HXMAP_SKEY 6155\family default 6156 is given, or otherwise the Jenkins' lookup3 hash function. 6157\end_layout 6158 6159\begin_layout Standard 6160libHX exports two hash functions that you can select for 6161\family typewriter 6162struct HXmap_ops 6163\family default 6164's 6165\family typewriter 6166k_hash 6167\family default 6168 if the default for a given flag combination is not to your liking. 6169\end_layout 6170 6171\begin_layout Description 6172 6173\family typewriter 6174HXhash_jlookup3 6175\family default 6176 6177\begin_inset Index idx 6178status open 6179 6180\begin_layout Plain Layout 6181 6182\family typewriter 6183HXhash_jlookup3 6184\end_layout 6185 6186\end_inset 6187 6188 Bob Jenkins's lookup3 hash. 6189\end_layout 6190 6191\begin_layout Description 6192 6193\family typewriter 6194HXhash_djb2 6195\family default 6196 6197\begin_inset Index idx 6198status open 6199 6200\begin_layout Plain Layout 6201 6202\family typewriter 6203HXhash_djb2 6204\end_layout 6205 6206\end_inset 6207 6208 DJB2 string hash. 6209\end_layout 6210 6211\begin_layout Subsection 6212Map operations 6213\end_layout 6214 6215\begin_layout LyX-Code 6216 6217\series bold 6218int 6219\series default 6220 HXmap_add( 6221\series bold 6222struct 6223\series default 6224 HXmap 6225\series bold 6226* 6227\series default 6228, 6229\series bold 6230const void * 6231\series default 6232key, 6233\series bold 6234const void * 6235\series default 6236value); 6237\begin_inset Index idx 6238status open 6239 6240\begin_layout Plain Layout 6241 6242\family typewriter 6243HXmap_add 6244\end_layout 6245 6246\end_inset 6247 6248 6249\begin_inset Newline newline 6250\end_inset 6251 6252 6253\series bold 6254const struct 6255\series default 6256 HXmap_node 6257\series bold 6258* 6259\series default 6260HXmap_find( 6261\series bold 6262const struct 6263\series default 6264 HXmap 6265\series bold 6266* 6267\series default 6268, 6269\series bold 6270const void * 6271\series default 6272key); 6273\begin_inset Index idx 6274status open 6275 6276\begin_layout Plain Layout 6277 6278\family typewriter 6279HXmap_find 6280\end_layout 6281 6282\end_inset 6283 6284 6285\begin_inset Newline newline 6286\end_inset 6287 6288 6289\series bold 6290void * 6291\series default 6292HXmap_get( 6293\series bold 6294const struct 6295\series default 6296 HXmap 6297\series bold 6298* 6299\series default 6300, 6301\series bold 6302const void * 6303\series default 6304key); 6305\begin_inset Index idx 6306status open 6307 6308\begin_layout Plain Layout 6309 6310\family typewriter 6311HXmap_get 6312\end_layout 6313 6314\end_inset 6315 6316 6317\begin_inset Newline newline 6318\end_inset 6319 6320 6321\series bold 6322void * 6323\series default 6324HXmap_del( 6325\series bold 6326struct 6327\series default 6328 HXmap 6329\series bold 6330* 6331\series default 6332, 6333\series bold 6334const void * 6335\series default 6336key); 6337\begin_inset Index idx 6338status open 6339 6340\begin_layout Plain Layout 6341 6342\family typewriter 6343HXmap_del 6344\end_layout 6345 6346\end_inset 6347 6348 6349\begin_inset Newline newline 6350\end_inset 6351 6352 6353\series bold 6354void 6355\series default 6356 HXmap_free( 6357\series bold 6358struct 6359\series default 6360 HXmap 6361\series bold 6362* 6363\series default 6364); 6365\begin_inset Index idx 6366status open 6367 6368\begin_layout Plain Layout 6369 6370\family typewriter 6371HXmap_free 6372\end_layout 6373 6374\end_inset 6375 6376 6377\begin_inset Newline newline 6378\end_inset 6379 6380 6381\series bold 6382struct 6383\series default 6384 HXmap_node 6385\series bold 6386* 6387\series default 6388HXmap_keysvalues( 6389\series bold 6390const struct 6391\series default 6392 HXmap 6393\series bold 6394* 6395\series default 6396); 6397\begin_inset Index idx 6398status open 6399 6400\begin_layout Plain Layout 6401 6402\family typewriter 6403HXmap_keysvalues 6404\end_layout 6405 6406\end_inset 6407 6408 6409\end_layout 6410 6411\begin_layout Description 6412 6413\family typewriter 6414HXmap_add 6415\family default 6416 6417\family typewriter 6418A 6419\family default 6420dds a new node to the tree using the given key and data. 6421 When an element is in the map, the key may not be modified, as doing so 6422 could possibly invalidate the internal location of the element, or its 6423 ordering with respect to other elements. 6424 If you need to change the key, you will have to delete the element from 6425 the tree and re-insert it. 6426 On error, 6427\family typewriter 6428-errno 6429\family default 6430 will be returned. 6431\begin_inset Newline newline 6432\end_inset 6433 6434When 6435\family typewriter 6436HXMAP_SINGULAR 6437\family default 6438 6439\begin_inset Index idx 6440status open 6441 6442\begin_layout Plain Layout 6443 6444\family typewriter 6445HXMAP_SINGULAR 6446\end_layout 6447 6448\end_inset 6449 6450 is in effect, 6451\family typewriter 6452value 6453\family default 6454 must be 6455\family typewriter 6456NULL 6457\family default 6458, or 6459\family typewriter 6460-EINVAL 6461\family default 6462 is returned. 6463\end_layout 6464 6465\begin_layout Description 6466 6467\family typewriter 6468HXmap_find 6469\family default 6470 Finds the node for the given key. 6471 The key can be read from the node using 6472\family typewriter 6473node->key 6474\family default 6475 or 6476\family typewriter 6477node->skey 6478\family default 6479 (convenience alias for 6480\family typewriter 6481key 6482\family default 6483, but with a type of 6484\family typewriter 6485const char 6486\begin_inset space ~ 6487\end_inset 6488 6489* 6490\family default 6491), and the data by using 6492\family typewriter 6493node->data 6494\family default 6495 or 6496\family typewriter 6497node->sdata 6498\family default 6499. 6500 (see section 6501\begin_inset space ~ 6502\end_inset 6503 6504 6505\begin_inset CommandInset ref 6506LatexCommand ref 6507reference "subsec:maps-def" 6508 6509\end_inset 6510 6511). 6512\end_layout 6513 6514\begin_layout Description 6515 6516\family typewriter 6517HXmap_get 6518\family default 6519 Get is a find operation directly returning 6520\family typewriter 6521node->data 6522\family default 6523 instead of the node itself. 6524 Since 6525\family typewriter 6526HXmap_get 6527\family default 6528 may legitimately return 6529\family typewriter 6530NULL 6531\family default 6532 if 6533\family typewriter 6534NULL 6535\family default 6536 was stored in the tree as the data for a given key, only 6537\family typewriter 6538errno 6539\family default 6540 will really tell whether the node was found or not; in the latter case, 6541 6542\family typewriter 6543errno 6544\family default 6545 is set to 6546\family typewriter 6547ENOENT 6548\family default 6549. 6550\end_layout 6551 6552\begin_layout Description 6553 6554\family typewriter 6555HXmap_del 6556\family default 6557 Removes an element from the map and returns the data value that was associated 6558 with it. 6559 When an error occurred, or the element was not found, 6560\family typewriter 6561NULL 6562\family default 6563 is returned. 6564 Because 6565\family typewriter 6566NULL 6567\family default 6568 can be a valid data value, 6569\family typewriter 6570errno 6571\family default 6572 can be checked for non-zero. 6573 6574\family typewriter 6575errno 6576\family default 6577 will be 6578\family typewriter 6579-ENOENT 6580\family default 6581 if the element was not found, or zero when everything was ok. 6582\end_layout 6583 6584\begin_layout Description 6585 6586\family typewriter 6587HXmap_free 6588\family default 6589 The function will delete all elements in the map and free memory it holds. 6590\end_layout 6591 6592\begin_layout Description 6593 6594\family typewriter 6595HXmap_keysvalues 6596\family default 6597 Returns all key-value-pairs in an array of the size as many items were 6598 in the map ( 6599\family typewriter 6600map->items 6601\family default 6602) at the time it was called. 6603 The memory must be freed using 6604\family typewriter 6605free 6606\family default 6607(3) when it is no longer needed. 6608 The order elements in the array follows the traverser notes (see below), 6609 unless otherwise specified. 6610\end_layout 6611 6612\begin_layout Subsection 6613Map traversal 6614\end_layout 6615 6616\begin_layout LyX-Code 6617 6618\series bold 6619struct 6620\series default 6621 HXmap_trav 6622\series bold 6623* 6624\series default 6625HXmap_travinit( 6626\series bold 6627const struct 6628\series default 6629 HXmap 6630\series bold 6631* 6632\series default 6633); 6634\begin_inset Newline newline 6635\end_inset 6636 6637 6638\series bold 6639const struct 6640\series default 6641 HXmap_node 6642\series bold 6643* 6644\series default 6645HXmap_traverse( 6646\series bold 6647struct 6648\series default 6649 HXmap_trav 6650\series bold 6651* 6652\series default 6653iterator); 6654\begin_inset Newline newline 6655\end_inset 6656 6657 6658\series bold 6659void 6660\series default 6661 HXmap_travfree( 6662\series bold 6663struct 6664\series default 6665 HXmap_trav 6666\series bold 6667* 6668\series default 6669iterator); 6670\begin_inset Newline newline 6671\end_inset 6672 6673 6674\series bold 6675void 6676\series default 6677 HXmap_qfe( 6678\series bold 6679const struct 6680\series default 6681 HXmap 6682\series bold 6683* 6684\series default 6685, 6686\series bold 6687bool (* 6688\series default 6689fn 6690\series bold 6691) 6692\series default 6693( 6694\series bold 6695const struct 6696\series default 6697 HXmap_node 6698\series bold 6699* 6700\series default 6701, 6702\begin_inset Newline newline 6703\end_inset 6704 6705 6706\series bold 6707void * 6708\series default 6709arg), 6710\series bold 6711void * 6712\series default 6713arg); 6714\end_layout 6715 6716\begin_layout Description 6717 6718\family typewriter 6719HXmap_travinit 6720\family default 6721 6722\begin_inset Index idx 6723status open 6724 6725\begin_layout Plain Layout 6726 6727\family typewriter 6728HXmap_travinit 6729\end_layout 6730 6731\end_inset 6732 6733 Initializes a traverser (a. 6734\begin_inset space \thinspace{} 6735\end_inset 6736 6737k. 6738\begin_inset space \thinspace{} 6739\end_inset 6740 6741a. 6742\begin_inset space \space{} 6743\end_inset 6744 6745iterator) for the map, and returns a pointer to it. 6746 6747\family typewriter 6748NULL 6749\family default 6750 will be returned in case of an error, such as memory allocation failure. 6751 Traversers are returned even if the map has zero elements. 6752\end_layout 6753 6754\begin_layout Description 6755 6756\family typewriter 6757HXmap_traverse 6758\family default 6759 6760\begin_inset Index idx 6761status open 6762 6763\begin_layout Plain Layout 6764 6765\family typewriter 6766HXmap_traverse 6767\end_layout 6768 6769\end_inset 6770 6771 Returns a pointer to a 6772\family typewriter 6773struct HXmap_node 6774\family default 6775 for the next element 6776\begin_inset space ~ 6777\end_inset 6778 6779\SpecialChar breakableslash 6780 key-value pair from the map, or 6781\family typewriter 6782NULL 6783\family default 6784 if there are no more entries. 6785\end_layout 6786 6787\begin_layout Description 6788 6789\family typewriter 6790HXmap_travfree 6791\family default 6792 6793\begin_inset Index idx 6794status open 6795 6796\begin_layout Plain Layout 6797 6798\family typewriter 6799HXmap_travfree 6800\end_layout 6801 6802\end_inset 6803 6804 Release the memory associated with a traverser. 6805\end_layout 6806 6807\begin_layout Description 6808 6809\family typewriter 6810HXmap_qfe 6811\family default 6812 6813\begin_inset Index idx 6814status open 6815 6816\begin_layout Plain Layout 6817 6818\family typewriter 6819HXmap_qfe 6820\end_layout 6821 6822\end_inset 6823 6824 The 6825\begin_inset Quotes eld 6826\end_inset 6827 6828quick foreach 6829\begin_inset Quotes erd 6830\end_inset 6831 6832. 6833 Iterates over all map elements in the fastest possible manner, but has 6834 the restriction that no modifications to the map are allowed. 6835 Furthermore, a separate function to handle each visited node, is required. 6836 (Hence this is also called 6837\begin_inset Quotes eld 6838\end_inset 6839 6840closed traversal 6841\begin_inset Quotes erd 6842\end_inset 6843 6844, because one cannot access the stack frame of the original function which 6845 called 6846\family typewriter 6847HXmap_qfe 6848\family default 6849.) The user-defined function returns a bool which indicates whether traversal 6850 shall continue or not. 6851\end_layout 6852 6853\begin_layout Standard 6854Flags for 6855\family typewriter 6856HXmap_travinit 6857\family default 6858: 6859\end_layout 6860 6861\begin_layout Description 6862 6863\family typewriter 6864HXMAP_NOFLAGS 6865\family default 6866 6867\begin_inset Index idx 6868status open 6869 6870\begin_layout Plain Layout 6871 6872\family typewriter 6873HXMAP_NOFLAGS 6874\end_layout 6875 6876\end_inset 6877 6878 A mnemonic for no flags, and is defined to be 6879\family typewriter 68800 6881\family default 6882. 6883\end_layout 6884 6885\begin_layout Description 6886 6887\family typewriter 6888HXMAP_DTRAV 6889\family default 6890 6891\begin_inset Index idx 6892status open 6893 6894\begin_layout Plain Layout 6895 6896\family typewriter 6897HXMAP_DTRAV 6898\end_layout 6899 6900\end_inset 6901 6902 Enable support for deletion during traversal. 6903 As it can make traversal slower, it needs to be explicitly specified for 6904 cases where it is needed, to not penalize cases where it is not. 6905\end_layout 6906 6907\begin_layout Standard 6908WARNING: Modifying the map while a traverser is active is implementation-specifi 6909c behavior! libHX generally ensures that there will be no undefined behavior 6910 (e. 6911\begin_inset space \thinspace{} 6912\end_inset 6913 6914g. 6915\begin_inset space \space{} 6916\end_inset 6917 6918crashes), but there is no guarantee that elements will be returned exactly 6919 once. 6920 There are fundamental cases that one should be aware of: 6921\end_layout 6922 6923\begin_layout Itemize 6924An element is inserted before where the traverser is currently positioned 6925 at. 6926 The element may not be returned in subsequent calls to 6927\family typewriter 6928HXmap_traverse 6929\family default 6930 on an already-active traverser. 6931\end_layout 6932 6933\begin_layout Itemize 6934Insertion or deletion may cause internal data structure to re-layout. 6935\begin_inset Separator latexpar 6936\end_inset 6937 6938 6939\end_layout 6940 6941\begin_deeper 6942\begin_layout Itemize 6943Traversers of ordered data structures may choose to rebuild their state. 6944\end_layout 6945 6946\begin_layout Itemize 6947Traversers of unordered data structures would run risk to return more than 6948 once, or not at all. 6949\end_layout 6950 6951\end_deeper 6952\begin_layout Standard 6953Descriptions for different map types follow. 6954\end_layout 6955 6956\begin_layout Description 6957Hashmaps On 6958\family typewriter 6959HXmap_add 6960\family default 6961, an element may be inserted in a position that is before where the traverser 6962 is currently positioned. 6963 Such elements will not be returned in the remaining calls to 6964\family typewriter 6965HXmap_traverse 6966\family default 6967. 6968 The insertion or deletion of an element may cause the internal data structure 6969 to re-layout itself. 6970 When this happens, the traverser will stop, so as to not return entries 6971 twice. 6972\end_layout 6973 6974\begin_layout Description 6975Binary 6976\begin_inset space ~ 6977\end_inset 6978 6979trees Elements may be added before the traverser's position. 6980 These elements will not be returned in subsequent traversion calls. 6981 If the data structure changes as a result of an addition or deletion, the 6982 traverser will rebuild its state and continue traversal transparently. 6983 Because elements in a binary tree are ordered, that is, element positions 6984 may not change with respect to another when the tree is rebalanced, there 6985 is no risk of returning entries more than once. 6986 Nor will elements that are sorted after the current traverser's position 6987 not be returned (= 6988\begin_inset space ~ 6989\end_inset 6990 6991they will be returned, because they cannot get reordered to before the traverser 6992 like in a hash map). 6993 The HX rbtree implementation also has proper handling for when the node 6994 which is currently visiting is deleted. 6995\end_layout 6996 6997\begin_layout Subsection 6998RB-tree Limitations 6999\end_layout 7000 7001\begin_layout Standard 7002The implementation has a theoretical minimum on the maximum number of nodes, 7003 7004\begin_inset Formula $2^{24}=16{,}777{,}216$ 7005\end_inset 7006 7007. 7008 A worst-case tree with this many elements already has a height of 48 ( 7009\family typewriter 7010RBT_MAXDEP 7011\family default 7012), which is the maximum height currently supported. 7013 The larger the height is that HXrbtree is supposed to handle, the more 7014 memory (linear increase) it needs. 7015 All functions that build or keep a path reserve memory for 7016\family typewriter 7017RBT_MAXDEP 7018\family default 7019 nodes; on x86_64 this is 9 bytes per 7020\begin_inset Formula $\langle$ 7021\end_inset 7022 7023node, direction 7024\begin_inset Formula $\rangle$ 7025\end_inset 7026 7027 pair, amounting to 432 bytes for path tracking alone. 7028 It may not sound like a lot to many, but given that kernel people can limit 7029 their stack usage to 4096 bytes is impressive alone 7030\end_layout 7031 7032\begin_layout Standard 7033\begin_inset Foot 7034status open 7035 7036\begin_layout Plain Layout 7037Not always of course. 7038 Linux kernels are often configured to use an 8K stack because some components 7039 still use a lot of stack space, but even 8K is still damn good. 7040\end_layout 7041 7042\end_inset 7043 7044. 7045\end_layout 7046 7047\begin_layout Subsection 7048Examples 7049\end_layout 7050 7051\begin_layout Subsubsection 7052Case-insensitive ordering 7053\end_layout 7054 7055\begin_layout Standard 7056The correct way: 7057\end_layout 7058 7059\begin_layout LyX-Code 7060 7061\series bold 7062static int 7063\series default 7064 my_strcasecmp( 7065\series bold 7066const void * 7067\series default 7068a, 7069\series bold 7070const void * 7071\series default 7072b, 7073\series bold 7074size_t 7075\series default 7076 z) 7077\begin_inset Newline newline 7078\end_inset 7079 7080{ 7081\begin_inset Newline newline 7082\end_inset 7083 7084 7085\series bold 7086return 7087\series default 7088 strcasecmp(a, b); 7089\begin_inset Newline newline 7090\end_inset 7091 7092} 7093\begin_inset Newline newline 7094\end_inset 7095 7096 7097\begin_inset Newline newline 7098\end_inset 7099 7100 7101\series bold 7102static const struct 7103\series default 7104 HXmap_ops icase = { 7105\begin_inset Newline newline 7106\end_inset 7107 7108 .k_compare = my_strcasecmp, 7109\begin_inset Newline newline 7110\end_inset 7111 7112}; 7113\begin_inset Newline newline 7114\end_inset 7115 7116HXmap_init5(HXMAPT_RBTREE, HXMAP_SKEY, &icase, 0, 7117\shape italic 7118dsize 7119\shape default 7120); 7121\end_layout 7122 7123\begin_layout Standard 7124A hackish way (which wholly depends on the C implementation and use of extra 7125 safeguards is a must): 7126\end_layout 7127 7128\begin_layout LyX-Code 7129 7130\series bold 7131static const struct 7132\series default 7133 HXmap_ops icase = { 7134\begin_inset Newline newline 7135\end_inset 7136 7137 .k_compare = ( 7138\series bold 7139void * 7140\series default 7141)strcasecmp, 7142\begin_inset Newline newline 7143\end_inset 7144 7145}; 7146\begin_inset Newline newline 7147\end_inset 7148 7149BUILD_BUG_ON( 7150\series bold 7151sizeof 7152\series default 7153(DEMOTE_TO_PTR(strcasecmp)) > 7154\series bold 7155sizeof 7156\series default 7157(void *)); 7158\begin_inset Newline newline 7159\end_inset 7160 7161BUILD_BUG_ON( 7162\series bold 7163sizeof 7164\series default 7165(DEMOTE_TO_PTR(strcasecmp)) > 7166\series bold 7167sizeof 7168\series default 7169(icase.k_compare)); 7170\begin_inset Newline newline 7171\end_inset 7172 7173HXmap_init5(HXMAPT_RBTREE, HXMAP_SKEY, &icase, 0, 7174\shape italic 7175dsize 7176\shape default 7177); 7178\end_layout 7179 7180\begin_layout Subsubsection 7181Reverse sorting order 7182\end_layout 7183 7184\begin_layout Standard 7185Any function that behaves like 7186\family typewriter 7187strcmp 7188\family default 7189 can be used. 7190 It merely has to return negative when 7191\begin_inset Formula $a<b$ 7192\end_inset 7193 7194, zero on 7195\begin_inset Formula $a=b$ 7196\end_inset 7197 7198, and positive non-zero when 7199\begin_inset Formula $a>b$ 7200\end_inset 7201 7202. 7203\end_layout 7204 7205\begin_layout LyX-Code 7206 7207\series bold 7208static int 7209\series default 7210 strcmp_rev( 7211\series bold 7212const void * 7213\series default 7214a, 7215\series bold 7216const void * 7217\series default 7218b, 7219\series bold 7220size_t 7221\series default 7222 z) 7223\begin_inset Newline newline 7224\end_inset 7225 7226{ 7227\begin_inset Newline newline 7228\end_inset 7229 7230 7231\series bold 7232/* 7233\family roman 7234\series default 7235\shape italic 7236z is provided for cases when things are raw memory blocks. 7237 7238\family default 7239\series bold 7240\shape default 7241 */ 7242\series default 7243 7244\begin_inset Newline newline 7245\end_inset 7246 7247 7248\series bold 7249return 7250\series default 7251 strcmp(b, a); 7252\begin_inset Newline newline 7253\end_inset 7254 7255} 7256\begin_inset Newline newline 7257\end_inset 7258 7259 7260\begin_inset Newline newline 7261\end_inset 7262 7263 7264\series bold 7265static const struct 7266\series default 7267 HXmap_ops rev = { 7268\begin_inset Newline newline 7269\end_inset 7270 7271 .k_compare = strcmp_rev, 7272\begin_inset Newline newline 7273\end_inset 7274 7275}; 7276\begin_inset Newline newline 7277\end_inset 7278 7279HXmap_init5(HXMAPT_RBTREE, HXMAP_SKEY, &rev, 0, 7280\shape italic 7281dsize 7282\shape default 7283); 7284\end_layout 7285 7286\begin_layout Subsubsection 7287Keys with non-unique data 7288\begin_inset CommandInset label 7289LatexCommand label 7290name "subsec:maps-examples-bigkey" 7291 7292\end_inset 7293 7294 7295\end_layout 7296 7297\begin_layout Standard 7298Keys can actually store non-unique data, as long as this extra fields does 7299 not actually contribute to the logical key 7300\begin_inset space ~ 7301\end_inset 7302 7303— the parts that do uniquely identify it. 7304 In the following example, the 7305\family typewriter 7306notes 7307\family default 7308 member may be part of struct package, which is the key as far as HXmap 7309 is concerned, but still, only the name and versions are used to identify 7310 it. 7311\end_layout 7312 7313\begin_layout LyX-Code 7314 7315\series bold 7316struct 7317\series default 7318 package { 7319\begin_inset Newline newline 7320\end_inset 7321 7322 7323\series bold 7324char * 7325\series default 7326name; 7327\begin_inset Newline newline 7328\end_inset 7329 7330 7331\series bold 7332unsigned int 7333\series default 7334 major_version; 7335\begin_inset Newline newline 7336\end_inset 7337 7338 7339\series bold 7340unsigned int 7341\series default 7342 minor_version; 7343\begin_inset Newline newline 7344\end_inset 7345 7346 7347\series bold 7348char 7349\series default 7350 notes 7351\series bold 7352[ 7353\series default 735464 7355\series bold 7356] 7357\series default 7358; 7359\begin_inset Newline newline 7360\end_inset 7361 7362}; 7363\begin_inset Newline newline 7364\end_inset 7365 7366 7367\begin_inset Newline newline 7368\end_inset 7369 7370 7371\series bold 7372static int 7373\series default 7374 package_cmp( 7375\series bold 7376const void * 7377\series default 7378a, 7379\series bold 7380const void * 7381\series default 7382b) 7383\begin_inset Newline newline 7384\end_inset 7385 7386{ 7387\begin_inset Newline newline 7388\end_inset 7389 7390 7391\series bold 7392const struct 7393\series default 7394 package 7395\series bold 7396* 7397\series default 7398p = a, 7399\series bold 7400* 7401\series default 7402q = b; 7403\begin_inset Newline newline 7404\end_inset 7405 7406 7407\series bold 7408int 7409\series default 7410 ret; 7411\begin_inset Newline newline 7412\end_inset 7413 7414 ret = strcmp(p->name, q->name); 7415\begin_inset Newline newline 7416\end_inset 7417 7418 7419\series bold 7420if 7421\series default 7422 (ret != 0) 7423\begin_inset Newline newline 7424\end_inset 7425 7426 7427\series bold 7428return 7429\series default 7430 ret; 7431\begin_inset Newline newline 7432\end_inset 7433 7434 ret = p->major_version - q->major_version; 7435\begin_inset Newline newline 7436\end_inset 7437 7438 7439\series bold 7440if 7441\series default 7442 (ret != 0) 7443\begin_inset Newline newline 7444\end_inset 7445 7446 7447\series bold 7448return 7449\series default 7450 ret; 7451\begin_inset Newline newline 7452\end_inset 7453 7454 ret = p->minor_version - q->minor_version; 7455\begin_inset Newline newline 7456\end_inset 7457 7458 7459\series bold 7460if 7461\series default 7462 (ret != 0) 7463\begin_inset Newline newline 7464\end_inset 7465 7466 7467\series bold 7468return 7469\series default 7470 ret; 7471\begin_inset Newline newline 7472\end_inset 7473 7474 7475\series bold 7476return 7477\series default 7478 0; 7479\begin_inset Newline newline 7480\end_inset 7481 7482} 7483\begin_inset Newline newline 7484\end_inset 7485 7486 7487\begin_inset Newline newline 7488\end_inset 7489 7490 7491\series bold 7492static const struct 7493\series default 7494 HXmap_ops package_ops = { 7495\begin_inset Newline newline 7496\end_inset 7497 7498 .k_compare = package_cmp, 7499\begin_inset Newline newline 7500\end_inset 7501 7502}; 7503\begin_inset Newline newline 7504\end_inset 7505 7506 7507\begin_inset Newline newline 7508\end_inset 7509 7510HXmap_init5(HXMAPT_RBTREE, 7511\shape italic 7512flags 7513\shape default 7514, &package_ops, 7515\begin_inset Newline newline 7516\end_inset 7517 7518 7519\series bold 7520sizeof 7521\series default 7522( 7523\series bold 7524struct 7525\series default 7526 package), 7527\shape italic 7528dsize 7529\shape default 7530); 7531\end_layout 7532 7533\begin_layout Standard 7534\begin_inset Newpage clearpage 7535\end_inset 7536 7537 7538\end_layout 7539 7540\begin_layout Section 7541Doubly-linked list 7542\begin_inset CommandInset label 7543LatexCommand label 7544name "sec:deque" 7545 7546\end_inset 7547 7548 7549\end_layout 7550 7551\begin_layout Standard 7552HXdeque is a data structure for a doubly-linked non-circular 7553\family typewriter 7554NULL 7555\family default 7556-sentineled list. 7557 Despite being named a deque, which is short for double-ended queue, and 7558 which may be implemented using an array, HXdeque is in fact using a linked 7559 list to provide its deque functionality. 7560 Furthermore, a dedicated root structure and decidated node structures with 7561 indirect data referencing are used. 7562\end_layout 7563 7564\begin_layout Subsection 7565Structural definition 7566\end_layout 7567 7568\begin_layout LyX-Code 7569 7570\series bold 7571#include 7572\series default 7573 <libHX/deque.h> 7574\begin_inset Index idx 7575status open 7576 7577\begin_layout Plain Layout 7578 7579\family typewriter 7580libHX/deque.h 7581\end_layout 7582 7583\end_inset 7584 7585 7586\begin_inset Newline newline 7587\end_inset 7588 7589 7590\begin_inset Newline newline 7591\end_inset 7592 7593 7594\series bold 7595struct 7596\series default 7597 HXdeque { 7598\begin_inset Index idx 7599status open 7600 7601\begin_layout Plain Layout 7602 7603\family typewriter 7604struct HXdeque 7605\end_layout 7606 7607\end_inset 7608 7609 7610\begin_inset Newline newline 7611\end_inset 7612 7613 7614\series bold 7615struct 7616\series default 7617 HXdeque_node 7618\series bold 7619* 7620\series default 7621first, 7622\series bold 7623* 7624\series default 7625last; 7626\begin_inset Newline newline 7627\end_inset 7628 7629 7630\series bold 7631unsigned int 7632\series default 7633 items; 7634\begin_inset Newline newline 7635\end_inset 7636 7637 7638\series bold 7639void * 7640\series default 7641ptr; 7642\begin_inset Newline newline 7643\end_inset 7644 7645}; 7646\begin_inset Newline newline 7647\end_inset 7648 7649 7650\begin_inset Newline newline 7651\end_inset 7652 7653 7654\series bold 7655struct 7656\series default 7657 HXdeque_node { 7658\begin_inset Index idx 7659status open 7660 7661\begin_layout Plain Layout 7662 7663\family typewriter 7664struct HXdeque_node 7665\end_layout 7666 7667\end_inset 7668 7669 7670\begin_inset Newline newline 7671\end_inset 7672 7673 7674\series bold 7675struct 7676\series default 7677 HXdeque_node 7678\series bold 7679* 7680\series default 7681next, 7682\series bold 7683* 7684\series default 7685prev; 7686\begin_inset Newline newline 7687\end_inset 7688 7689 7690\series bold 7691struct 7692\series default 7693 HXdeque 7694\series bold 7695* 7696\series default 7697parent; 7698\begin_inset Newline newline 7699\end_inset 7700 7701 7702\series bold 7703void * 7704\series default 7705ptr; 7706\begin_inset Newline newline 7707\end_inset 7708 7709}; 7710\end_layout 7711 7712\begin_layout Standard 7713The 7714\family typewriter 7715ptr 7716\family default 7717 member in 7718\family typewriter 7719struct HXdeque 7720\family default 7721 provides room for an arbitrary custom user-supplied pointer. 7722 7723\family typewriter 7724items 7725\family default 7726 will reflect the number of elements in the list, and must not be modified. 7727 7728\family typewriter 7729first 7730\family default 7731 and 7732\family typewriter 7733last 7734\family default 7735 provide entrypoints to the list's ends. 7736\end_layout 7737 7738\begin_layout Standard 7739 7740\family typewriter 7741ptr 7742\family default 7743 within 7744\family typewriter 7745struct HXdeque_node 7746\family default 7747 is the pointer to the user's data. 7748 It may be modified and used at will by the user. 7749 See example section 7750\begin_inset space ~ 7751\end_inset 7752 7753. 7754\end_layout 7755 7756\begin_layout Subsection 7757Constructor, destructors 7758\end_layout 7759 7760\begin_layout LyX-Code 7761 7762\series bold 7763struct 7764\series default 7765 HXdeque 7766\series bold 7767* 7768\series default 7769HXdeque_init( 7770\series bold 7771void 7772\series default 7773); 7774\begin_inset Index idx 7775status open 7776 7777\begin_layout Plain Layout 7778 7779\family typewriter 7780HXdeque_init 7781\end_layout 7782 7783\end_inset 7784 7785 7786\begin_inset Newline newline 7787\end_inset 7788 7789 7790\series bold 7791void 7792\series default 7793 HXdeque_free( 7794\series bold 7795struct 7796\series default 7797 HXdeque 7798\series bold 7799* 7800\series default 7801dq); 7802\begin_inset Index idx 7803status open 7804 7805\begin_layout Plain Layout 7806 7807\family typewriter 7808HXdeque_free 7809\end_layout 7810 7811\end_inset 7812 7813 7814\begin_inset Newline newline 7815\end_inset 7816 7817 7818\series bold 7819void 7820\series default 7821 HXdeque_genocide( 7822\series bold 7823struct 7824\series default 7825 HXdeque 7826\series bold 7827* 7828\series default 7829dq); 7830\begin_inset Index idx 7831status open 7832 7833\begin_layout Plain Layout 7834 7835\family typewriter 7836HXdeque_genocide 7837\end_layout 7838 7839\end_inset 7840 7841 7842\begin_inset Newline newline 7843\end_inset 7844 7845 7846\series bold 7847void 7848\series default 7849 HXdeque_genocide2( 7850\series bold 7851struct 7852\series default 7853 HXdeque 7854\series bold 7855* 7856\series default 7857dq, 7858\series bold 7859void (* 7860\series default 7861xfree 7862\series bold 7863) 7864\series default 7865( 7866\series bold 7867void * 7868\series default 7869)); 7870\begin_inset Index idx 7871status open 7872 7873\begin_layout Plain Layout 7874 7875\family typewriter 7876HXdeque_genocide2 7877\end_layout 7878 7879\end_inset 7880 7881 7882\begin_inset Newline newline 7883\end_inset 7884 7885 7886\series bold 7887void ** 7888\series default 7889HXdeque_to_vec( 7890\series bold 7891struct 7892\series default 7893 HXdeque 7894\series bold 7895* 7896\series default 7897dq, 7898\series bold 7899unsigned int * 7900\series default 7901num); 7902\begin_inset Index idx 7903status open 7904 7905\begin_layout Plain Layout 7906 7907\family typewriter 7908HXdeque_to_vec 7909\end_layout 7910 7911\end_inset 7912 7913 7914\end_layout 7915 7916\begin_layout Standard 7917To allocate a new empty list, use 7918\family typewriter 7919HXdeque_init 7920\family default 7921. 7922 7923\family typewriter 7924HXdeque_free 7925\family default 7926 will free the list (including all nodes owned by the list), but not the 7927 data pointers. 7928\end_layout 7929 7930\begin_layout Standard 7931 7932\family typewriter 7933HXdeque_genocide 7934\family default 7935 is a variant that will not only destroy the list, but also calls a freeing 7936 function 7937\family typewriter 7938free() 7939\family default 7940 on all stored data pointers. 7941 This puts a number of restrictions on the characteristics of the list: 7942 all data pointers must have been obtained with 7943\family typewriter 7944malloc 7945\family default 7946, 7947\family typewriter 7948calloc 7949\family default 7950 or 7951\family typewriter 7952realloc 7953\family default 7954 before, and no data pointer must exist twice in the list. 7955 The function is more efficient than an open-coded loop over all nodes calling 7956 7957\family typewriter 7958HXdeque_del 7959\family default 7960. 7961\end_layout 7962 7963\begin_layout Standard 7964A generic variant is available with 7965\family typewriter 7966HXdeque_genocide2 7967\family default 7968, which takes a pointer to an appropriate freeing function. 7969 7970\family typewriter 7971HXdeque_genocide 7972\family default 7973 is thus equivalent to 7974\family typewriter 7975HXdeque_genocide2(dq, free) 7976\family default 7977. 7978\end_layout 7979 7980\begin_layout Standard 7981To convert a linked list to a 7982\family typewriter 7983NULL 7984\family default 7985-terminated array, 7986\family typewriter 7987HXdeque_to_vec 7988\family default 7989 can be used. 7990 If 7991\family typewriter 7992num 7993\family default 7994 is not 7995\family typewriter 7996NULL 7997\family default 7998, the number of elements excluding the 7999\family typewriter 8000NULL 8001\family default 8002 sentinel, is stored in 8003\family typewriter 8004*num 8005\family default 8006. 8007\end_layout 8008 8009\begin_layout Subsection 8010Addition and removal 8011\end_layout 8012 8013\begin_layout LyX-Code 8014 8015\series bold 8016struct 8017\series default 8018 HXdeque_node 8019\series bold 8020* 8021\series default 8022HXdeque_push( 8023\series bold 8024struct 8025\series default 8026 HXdeque 8027\series bold 8028* 8029\series default 8030dq, 8031\series bold 8032void * 8033\series default 8034ptr); 8035\begin_inset Index idx 8036status open 8037 8038\begin_layout Plain Layout 8039 8040\family typewriter 8041HXdeque_push 8042\end_layout 8043 8044\end_inset 8045 8046 8047\begin_inset Newline newline 8048\end_inset 8049 8050 8051\series bold 8052struct 8053\series default 8054 HXdeque_node 8055\series bold 8056* 8057\series default 8058HXdeque_unshift( 8059\series bold 8060struct 8061\series default 8062 HXdeque 8063\series bold 8064* 8065\series default 8066dq, 8067\series bold 8068void * 8069\series default 8070ptr); 8071\begin_inset Index idx 8072status open 8073 8074\begin_layout Plain Layout 8075 8076\family typewriter 8077HXdeque_unshift 8078\end_layout 8079 8080\end_inset 8081 8082 8083\begin_inset Newline newline 8084\end_inset 8085 8086 8087\series bold 8088void * 8089\series default 8090HXdeque_pop( 8091\series bold 8092struct 8093\series default 8094 HXdeque 8095\series bold 8096* 8097\series default 8098dq); 8099\begin_inset Index idx 8100status open 8101 8102\begin_layout Plain Layout 8103 8104\family typewriter 8105HXdeque_pop 8106\end_layout 8107 8108\end_inset 8109 8110 8111\begin_inset Newline newline 8112\end_inset 8113 8114 8115\series bold 8116void * 8117\series default 8118HXdeque_shift( 8119\series bold 8120struct 8121\series default 8122 HXdeque 8123\series bold 8124* 8125\series default 8126dq); 8127\begin_inset Index idx 8128status open 8129 8130\begin_layout Plain Layout 8131 8132\family typewriter 8133HXdeque_shift 8134\end_layout 8135 8136\end_inset 8137 8138 8139\begin_inset Newline newline 8140\end_inset 8141 8142 8143\series bold 8144struct 8145\series default 8146 HXdeque 8147\series bold 8148* 8149\series default 8150HXdeque_move( 8151\series bold 8152struct 8153\series default 8154 HXdeque_node 8155\series bold 8156* 8157\series default 8158target, 8159\begin_inset Newline newline 8160\end_inset 8161 8162 8163\series bold 8164struct 8165\series default 8166 HXdeque_node 8167\series bold 8168* 8169\series default 8170node); 8171\begin_inset Index idx 8172status open 8173 8174\begin_layout Plain Layout 8175 8176\family typewriter 8177HXdeque_move 8178\end_layout 8179 8180\end_inset 8181 8182 8183\begin_inset Newline newline 8184\end_inset 8185 8186 8187\series bold 8188void * 8189\series default 8190HXdeque_del( 8191\series bold 8192struct 8193\series default 8194 HXdeque_node 8195\series bold 8196* 8197\series default 8198node); 8199\begin_inset Index idx 8200status open 8201 8202\begin_layout Plain Layout 8203 8204\family typewriter 8205HXdeque_del 8206\end_layout 8207 8208\end_inset 8209 8210 8211\end_layout 8212 8213\begin_layout Standard 8214 8215\family typewriter 8216HXdeque_\SpecialChar softhyphen 8217push 8218\family default 8219 and 8220\family typewriter 8221HXdeque_\SpecialChar softhyphen 8222unshift 8223\family default 8224 add the data item in a new node at the end ( 8225\begin_inset Quotes eld 8226\end_inset 8227 8228push 8229\begin_inset Quotes erd 8230\end_inset 8231 8232) or as the new first element ( 8233\begin_inset Quotes eld 8234\end_inset 8235 8236unshift 8237\begin_inset Quotes erd 8238\end_inset 8239 8240 as Perl calls it), respectively. 8241 The functions will return the new node on success, or 8242\family typewriter 8243NULL 8244\family default 8245 on failure and 8246\family typewriter 8247errno 8248\family default 8249 will be set. 8250 The node is owned by the list. 8251\end_layout 8252 8253\begin_layout Standard 8254 8255\family typewriter 8256HXdeque_\SpecialChar softhyphen 8257pop 8258\family default 8259 and 8260\family typewriter 8261HXdeque_\SpecialChar softhyphen 8262shift 8263\family default 8264 remove the last ( 8265\begin_inset Quotes eld 8266\end_inset 8267 8268pop 8269\begin_inset Quotes erd 8270\end_inset 8271 8272) or first ( 8273\begin_inset Quotes eld 8274\end_inset 8275 8276shift 8277\begin_inset Quotes erd 8278\end_inset 8279 8280) node, respectively, and return the data pointer that was stored in the 8281 data. 8282\end_layout 8283 8284\begin_layout Standard 8285 8286\family typewriter 8287HXdeque_\SpecialChar softhyphen 8288move 8289\family default 8290 will unlink a node from its list, and reinsert it after the given target 8291 node, which may be in a different list. 8292\end_layout 8293 8294\begin_layout Standard 8295Deleting a node is accomplished by calling 8296\family typewriter 8297HXdeque_del 8298\family default 8299 on it. 8300 The data pointer stored in the node is not freed, but returned. 8301\end_layout 8302 8303\begin_layout Subsection 8304Iteration 8305\end_layout 8306 8307\begin_layout Standard 8308Iterating over a HXdeque linked list is done manually and without additional 8309 overhead of function calls: 8310\end_layout 8311 8312\begin_layout LyX-Code 8313 8314\series bold 8315const struct 8316\series default 8317 HXdeque_node 8318\series bold 8319* 8320\series default 8321node; 8322\begin_inset Newline newline 8323\end_inset 8324 8325 8326\series bold 8327for 8328\series default 8329 (node = dq->first; node != NULL; node = node->next) 8330\begin_inset Newline newline 8331\end_inset 8332 8333 do_something(node->ptr); 8334\end_layout 8335 8336\begin_layout Subsection 8337Searching 8338\end_layout 8339 8340\begin_layout LyX-Code 8341 8342\series bold 8343struct 8344\series default 8345 HXdeque_node 8346\series bold 8347* 8348\series default 8349HXdeque_find( 8350\series bold 8351struct 8352\series default 8353 HXdeque 8354\series bold 8355* 8356\series default 8357dq, 8358\series bold 8359const void * 8360\series default 8361ptr); 8362\begin_inset Index idx 8363status open 8364 8365\begin_layout Plain Layout 8366 8367\family typewriter 8368HXdeque_find 8369\end_layout 8370 8371\end_inset 8372 8373 8374\begin_inset Newline newline 8375\end_inset 8376 8377 8378\series bold 8379void * 8380\series default 8381HXdeque_get( 8382\series bold 8383struct 8384\series default 8385 HXdeque 8386\series bold 8387* 8388\series default 8389dq, 8390\series bold 8391void * 8392\series default 8393ptr); 8394\begin_inset Index idx 8395status open 8396 8397\begin_layout Plain Layout 8398 8399\family typewriter 8400HXdeque_get 8401\end_layout 8402 8403\end_inset 8404 8405 8406\end_layout 8407 8408\begin_layout Standard 8409 8410\family typewriter 8411HXdeque_find 8412\family default 8413 searches for the node which contains 8414\family typewriter 8415ptr 8416\family default 8417, and does so by beginning at the start of the list. 8418 If no node is found, 8419\family typewriter 8420NULL 8421\family default 8422 is returned. 8423 If a pointer is more than once in the list, any node may be returned. 8424\end_layout 8425 8426\begin_layout Standard 8427 8428\family typewriter 8429HXdeque_get 8430\family default 8431 will further return the data pointer stored in the node 8432\begin_inset space ~ 8433\end_inset 8434 8435— however, since that is just what the 8436\family typewriter 8437ptr 8438\family default 8439 argument is, the function practically only checks for existence of 8440\family typewriter 8441ptr 8442\family default 8443 in the list. 8444\end_layout 8445 8446\begin_layout Subsection 8447Examples 8448\end_layout 8449 8450\begin_layout Standard 8451 8452\series bold 8453\begin_inset Float figure 8454placement h 8455wide false 8456sideways false 8457status open 8458 8459\begin_layout LyX-Code 8460 8461\series bold 8462#include 8463\series default 8464 <stdio.h> 8465\begin_inset Newline newline 8466\end_inset 8467 8468 8469\series bold 8470#include 8471\series default 8472 <stdlib.h> 8473\begin_inset Newline newline 8474\end_inset 8475 8476 8477\series bold 8478#include 8479\series default 8480 <string.h> 8481\begin_inset Newline newline 8482\end_inset 8483 8484 8485\series bold 8486#include 8487\series default 8488 <libHX/defs.h> 8489\begin_inset Newline newline 8490\end_inset 8491 8492 8493\series bold 8494#include 8495\series default 8496 <libHX/deque.h> 8497\begin_inset Newline newline 8498\end_inset 8499 8500 8501\series bold 8502#include 8503\series default 8504 <libHX/string.h> 8505\begin_inset Newline newline 8506\end_inset 8507 8508 8509\series bold 8510#include 8511\series default 8512 <pwd.h> 8513\begin_inset Newline newline 8514\end_inset 8515 8516 8517\series bold 8518 8519\begin_inset Newline newline 8520\end_inset 8521 8522int 8523\series default 8524 main( 8525\series bold 8526void 8527\series default 8528) 8529\begin_inset Newline newline 8530\end_inset 8531 8532{ 8533\series bold 8534 8535\begin_inset Newline newline 8536\end_inset 8537 8538 8539\series default 8540 8541\series bold 8542struct 8543\series default 8544 HXdeque 8545\series bold 8546* 8547\series default 8548dq = HXdeque_init(); 8549\begin_inset Newline newline 8550\end_inset 8551 8552 8553\series bold 8554struct 8555\series default 8556 passwd *pw; 8557\begin_inset Newline newline 8558\end_inset 8559 8560 8561\family typewriter 8562\series bold 8563unsigned int 8564\series default 8565 elem; 8566\begin_inset Newline newline 8567\end_inset 8568 8569 8570\series bold 8571char ** 8572\series default 8573users; 8574\family default 8575 8576\begin_inset Newline newline 8577\end_inset 8578 8579 8580\begin_inset Newline newline 8581\end_inset 8582 8583 setpwent(); 8584\begin_inset Newline newline 8585\end_inset 8586 8587 8588\series bold 8589while 8590\series default 8591 ((pw = getpwent()) != NULL) 8592\begin_inset Newline newline 8593\end_inset 8594 8595 HXdeque_push(dq, HX_strdup(pw->pw_name)); 8596\begin_inset Newline newline 8597\end_inset 8598 8599 endpwent(); 8600\begin_inset Newline newline 8601\end_inset 8602 8603 8604\begin_inset Newline newline 8605\end_inset 8606 8607 users = 8608\series bold 8609reinterpret_cast 8610\series default 8611( 8612\series bold 8613char ** 8614\series default 8615, HXdeque_to_vec(dq, &elem)); 8616\begin_inset Newline newline 8617\end_inset 8618 8619 HXdeque_free(dq); 8620\begin_inset Newline newline 8621\end_inset 8622 8623 8624\begin_inset Newline newline 8625\end_inset 8626 8627 qsort(users, elem, 8628\series bold 8629sizeof 8630\series default 8631(*users), 8632\series bold 8633static_cast 8634\series default 8635( 8636\series bold 8637void * 8638\series default 8639, strcmp)); 8640\begin_inset Newline newline 8641\end_inset 8642 8643 return 0; 8644\begin_inset Newline newline 8645\end_inset 8646 8647} 8648\end_layout 8649 8650\begin_layout Plain Layout 8651\begin_inset Caption Standard 8652 8653\begin_layout Plain Layout 8654Example use of HXdeque to store and sort a list 8655\end_layout 8656 8657\end_inset 8658 8659 8660\end_layout 8661 8662\end_inset 8663 8664 8665\end_layout 8666 8667\begin_layout Standard 8668In this example, all usernames are obtained from NSS, and put into a list. 8669 8670\family typewriter 8671HX_strdup 8672\family default 8673 is used, because 8674\family typewriter 8675getpwent 8676\family default 8677 will overwrite the buffer it uses to store its results. 8678 The list is then converted to an array, and the list is freed (because 8679 it is not need it anymore). 8680 8681\family typewriter 8682HXdeque_genocide 8683\family default 8684 must not be used here, because it would free all the data pointers (strings 8685 here) that were just inserted into the list. 8686 Finally, the list is sorted using the well-known 8687\family typewriter 8688qsort 8689\family default 8690 function. 8691 Because 8692\family typewriter 8693strcmp 8694\family default 8695 takes two 8696\family typewriter 8697const char 8698\begin_inset space ~ 8699\end_inset 8700 8701* 8702\family default 8703 arguments, but 8704\family typewriter 8705qsort 8706\family default 8707 mandates a function taking two 8708\family typewriter 8709const void 8710\begin_inset space ~ 8711\end_inset 8712 8713* 8714\family default 8715, a cast can be used to silence the compiler. 8716 This only works because we know that the array consists of a bunch of 8717\family typewriter 8718char 8719\begin_inset space ~ 8720\end_inset 8721 8722* 8723\family default 8724 pointers, so 8725\family typewriter 8726strcmp 8727\family default 8728 will work. 8729\end_layout 8730 8731\begin_layout Standard 8732\begin_inset Newpage clearpage 8733\end_inset 8734 8735 8736\end_layout 8737 8738\begin_layout Section 8739Inline doubly-linked list 8740\begin_inset CommandInset label 8741LatexCommand label 8742name "sec:list" 8743 8744\end_inset 8745 8746 8747\end_layout 8748 8749\begin_layout Standard 8750Classical linked-list implementations, such as HXdeque, either store the 8751 actual data within a node, or indirectly through a pointer, but the 8752\begin_inset Quotes eld 8753\end_inset 8754 8755inline doubly-linked list 8756\begin_inset Quotes erd 8757\end_inset 8758 8759 instead does it reverse and has the list head within the data structure. 8760\end_layout 8761 8762\begin_layout Standard 8763\begin_inset Float figure 8764placement h 8765wide false 8766sideways false 8767status open 8768 8769\begin_layout LyX-Code 8770 8771\series bold 8772struct 8773\series default 8774 package_desc { 8775\begin_inset Newline newline 8776\end_inset 8777 8778 8779\series bold 8780char * 8781\series default 8782package_name; 8783\begin_inset Newline newline 8784\end_inset 8785 8786 8787\series bold 8788int 8789\series default 8790 version; 8791\end_layout 8792 8793\begin_layout LyX-Code 8794}; 8795\end_layout 8796 8797\begin_layout LyX-Code 8798 8799\series bold 8800struct 8801\series default 8802 classic_direct_node { 8803\begin_inset Newline newline 8804\end_inset 8805 8806 8807\series bold 8808struct 8809\series default 8810 classic_direct_node 8811\series bold 8812* 8813\series default 8814next, 8815\series bold 8816* 8817\series default 8818prev; 8819\begin_inset Newline newline 8820\end_inset 8821 8822 8823\series bold 8824struct 8825\series default 8826 package_desc direct_data; 8827\begin_inset Newline newline 8828\end_inset 8829 8830}; 8831\begin_inset Newline newline 8832\end_inset 8833 8834 8835\series bold 8836struct 8837\series default 8838 classic_indirect_node { 8839\begin_inset Newline newline 8840\end_inset 8841 8842 8843\series bold 8844struct 8845\series default 8846 classic_indirect_node 8847\series bold 8848* 8849\series default 8850next, 8851\series bold 8852* 8853\series default 8854prev; 8855\begin_inset Newline newline 8856\end_inset 8857 8858 8859\series bold 8860void * 8861\series default 8862indirect_data; 8863\begin_inset Newline newline 8864\end_inset 8865 8866}; 8867\end_layout 8868 8869\begin_layout Plain Layout 8870\begin_inset Caption Standard 8871 8872\begin_layout Plain Layout 8873Classic linked-list implementations with direct/indirect data blocks. 8874\end_layout 8875 8876\end_inset 8877 8878 8879\end_layout 8880 8881\end_inset 8882 8883 8884\end_layout 8885 8886\begin_layout Standard 8887\begin_inset Float figure 8888placement H 8889wide false 8890sideways false 8891status open 8892 8893\begin_layout LyX-Code 8894 8895\series bold 8896struct 8897\series default 8898 package_desc { 8899\begin_inset Newline newline 8900\end_inset 8901 8902 8903\series bold 8904struct 8905\series default 8906 HXlist_head list; 8907\begin_inset Newline newline 8908\end_inset 8909 8910 8911\series bold 8912char * 8913\series default 8914package_name; 8915\begin_inset Newline newline 8916\end_inset 8917 8918 8919\series bold 8920int 8921\series default 8922 version; 8923\begin_inset Newline newline 8924\end_inset 8925 8926}; 8927\end_layout 8928 8929\begin_layout Plain Layout 8930\begin_inset Caption Standard 8931 8932\begin_layout Plain Layout 8933List head (next,prev pointers) inlined into the data block 8934\end_layout 8935 8936\end_inset 8937 8938 8939\end_layout 8940 8941\end_inset 8942 8943 8944\end_layout 8945 8946\begin_layout Standard 8947At first glance, an inline list does not look much different from 8948\family typewriter 8949struct classic_\SpecialChar softhyphen 8950direct_\SpecialChar softhyphen 8951data 8952\family default 8953, it is mostly a viewpoint decision which struct is in the foreground. 8954\end_layout 8955 8956\begin_layout Subsection 8957Synopsis 8958\end_layout 8959 8960\begin_layout LyX-Code 8961 8962\series bold 8963#include 8964\series default 8965 <libHX/list.h> 8966\begin_inset Index idx 8967status open 8968 8969\begin_layout Plain Layout 8970 8971\family typewriter 8972libHX/list.h 8973\end_layout 8974 8975\end_inset 8976 8977 8978\begin_inset Newline newline 8979\end_inset 8980 8981 8982\begin_inset Newline newline 8983\end_inset 8984 8985 8986\series bold 8987struct 8988\series default 8989 HXlist_head { 8990\begin_inset Index idx 8991status open 8992 8993\begin_layout Plain Layout 8994 8995\family typewriter 8996struct HXlist_head 8997\end_layout 8998 8999\end_inset 9000 9001 9002\begin_inset Newline newline 9003\end_inset 9004 9005 9006\series bold 9007/* 9008\family roman 9009\series default 9010\shape italic 9011All fields considered private 9012\family default 9013\series bold 9014\shape default 9015 */ 9016\series default 9017 9018\begin_inset Newline newline 9019\end_inset 9020 9021}; 9022\begin_inset Newline newline 9023\end_inset 9024 9025 9026\begin_inset Newline newline 9027\end_inset 9028 9029HXLIST_HEAD_INIT(name); 9030\begin_inset Index idx 9031status open 9032 9033\begin_layout Plain Layout 9034 9035\family typewriter 9036HXLIST_HEAD_INIT 9037\end_layout 9038 9039\end_inset 9040 9041 9042\begin_inset Newline newline 9043\end_inset 9044 9045HXLIST_HEAD(name); 9046\begin_inset Index idx 9047status open 9048 9049\begin_layout Plain Layout 9050 9051\family typewriter 9052HXLIST_HEAD 9053\end_layout 9054 9055\end_inset 9056 9057 9058\begin_inset Newline newline 9059\end_inset 9060 9061 9062\series bold 9063void 9064\series default 9065 HXlist_init( 9066\series bold 9067struct 9068\series default 9069 HXlist_head 9070\series bold 9071* 9072\series default 9073list); 9074\begin_inset Index idx 9075status open 9076 9077\begin_layout Plain Layout 9078 9079\family typewriter 9080HXlist_init 9081\end_layout 9082 9083\end_inset 9084 9085 9086\begin_inset Newline newline 9087\end_inset 9088 9089 9090\series bold 9091void 9092\series default 9093 HXlist_add( 9094\series bold 9095struct 9096\series default 9097 HXlist_head 9098\series bold 9099* 9100\series default 9101list, 9102\series bold 9103struct 9104\series default 9105 HXlist_head 9106\series bold 9107* 9108\series default 9109elem); 9110\begin_inset Index idx 9111status open 9112 9113\begin_layout Plain Layout 9114 9115\family typewriter 9116HXlist_add 9117\end_layout 9118 9119\end_inset 9120 9121 9122\begin_inset Newline newline 9123\end_inset 9124 9125 9126\series bold 9127void 9128\series default 9129 HXlist_add_tail( 9130\series bold 9131struct 9132\series default 9133 HXlist_head 9134\series bold 9135* 9136\series default 9137list, 9138\series bold 9139struct 9140\series default 9141 HXlist_head 9142\series bold 9143* 9144\series default 9145elem); 9146\begin_inset Index idx 9147status open 9148 9149\begin_layout Plain Layout 9150 9151\family typewriter 9152HXlist_add_tail 9153\end_layout 9154 9155\end_inset 9156 9157 9158\begin_inset Newline newline 9159\end_inset 9160 9161 9162\series bold 9163void 9164\series default 9165 HXlist_del( 9166\series bold 9167struct 9168\series default 9169 HXlist_head 9170\series bold 9171* 9172\series default 9173element); 9174\begin_inset Index idx 9175status open 9176 9177\begin_layout Plain Layout 9178 9179\family typewriter 9180HXlist_del 9181\end_layout 9182 9183\end_inset 9184 9185 9186\begin_inset Newline newline 9187\end_inset 9188 9189 9190\series bold 9191bool 9192\series default 9193 HXlist_empty( 9194\series bold 9195const struct 9196\series default 9197 HXlist_head 9198\series bold 9199* 9200\series default 9201list); 9202\begin_inset Index idx 9203status open 9204 9205\begin_layout Plain Layout 9206 9207\family typewriter 9208HXlist_empty 9209\end_layout 9210 9211\end_inset 9212 9213 9214\end_layout 9215 9216\begin_layout Description 9217 9218\family typewriter 9219HXLIST_HEAD_INIT 9220\family default 9221 This macro expands to the static initializer for a list head. 9222\end_layout 9223 9224\begin_layout Description 9225 9226\family typewriter 9227HXLIST_HEAD 9228\family default 9229 This macro expands to the definition of a list head (i. 9230\begin_inset space \thinspace{} 9231\end_inset 9232 9233e. 9234\begin_inset space \space{} 9235\end_inset 9236 9237 9238\family typewriter 9239struct HXlist_head name = HXLIST_HEAD_INIT; 9240\family default 9241) 9242\end_layout 9243 9244\begin_layout Description 9245 9246\family typewriter 9247HXlist_init 9248\family default 9249 Initializes the list head. 9250 This function is generally used when the list head is on the heap where 9251 the static initializer cannot be used. 9252\end_layout 9253 9254\begin_layout Description 9255 9256\family typewriter 9257HXlist_add 9258\family default 9259 Adds 9260\family typewriter 9261elem 9262\family default 9263 to the front of the list. 9264\end_layout 9265 9266\begin_layout Description 9267 9268\family typewriter 9269HXlist_add_tail 9270\family default 9271 Adds 9272\family typewriter 9273elem 9274\family default 9275 to the end of the list. 9276\end_layout 9277 9278\begin_layout Description 9279 9280\family typewriter 9281HXlist_del 9282\family default 9283 Deletes the given element from the list. 9284\end_layout 9285 9286\begin_layout Description 9287 9288\family typewriter 9289HXlist_empty 9290\family default 9291 Tests whether the list is empty. 9292 Note: For clists, you could also use 9293\family typewriter 9294clist->items == 0 9295\family default 9296. 9297\end_layout 9298 9299\begin_layout Subsection 9300Traversal 9301\end_layout 9302 9303\begin_layout Standard 9304Traversal is implemented using macros that expand to for() statements which 9305 can syntactically be used like them, i. 9306\begin_inset space \thinspace{} 9307\end_inset 9308 9309e. 9310\begin_inset space \space{} 9311\end_inset 9312 9313curly braces may be omitted if only a single statement is in the body of 9314 the loop. 9315\end_layout 9316 9317\begin_layout Standard 9318The 9319\family typewriter 9320head 9321\family default 9322 parameter specifies the list head ( 9323\family typewriter 9324struct HXlist_head 9325\family default 9326), 9327\family typewriter 9328pos 9329\family default 9330 specifies an iterator, also of type 9331\family typewriter 9332struct HXlist_head 9333\family default 9334. 9335 Lists can either be traversed in forward direction, or, using the 9336\family typewriter 9337_rev 9338\family default 9339 variants, in reverse direction. 9340 The 9341\family typewriter 9342_safe 9343\family default 9344 variants use a temporary 9345\family typewriter 9346n 9347\family default 9348 to hold the next object in the list, which is needed when pos itself is 9349 going to be inaccessible at the end of the block, through, for example, 9350 freeing its encompassing object. 9351\end_layout 9352 9353\begin_layout LyX-Code 9354HXlist_for_each(pos, head) 9355\begin_inset Index idx 9356status open 9357 9358\begin_layout Plain Layout 9359 9360\family typewriter 9361HXlist_for_each 9362\end_layout 9363 9364\end_inset 9365 9366 9367\begin_inset Newline newline 9368\end_inset 9369 9370HXlist_for_each_rev(pos, head) 9371\begin_inset Index idx 9372status open 9373 9374\begin_layout Plain Layout 9375 9376\family typewriter 9377HXlist_for_each_rev 9378\end_layout 9379 9380\end_inset 9381 9382 9383\begin_inset Newline newline 9384\end_inset 9385 9386HXlist_for_each_safe(pos, n, head) 9387\begin_inset Index idx 9388status open 9389 9390\begin_layout Plain Layout 9391 9392\family typewriter 9393HXlist_for_each_safe 9394\end_layout 9395 9396\end_inset 9397 9398 9399\begin_inset Newline newline 9400\end_inset 9401 9402HXlist_for_each_rev_safe(pos, n, head) 9403\begin_inset Index idx 9404status open 9405 9406\begin_layout Plain Layout 9407 9408\family typewriter 9409HXlist_for_each_rev_safe 9410\end_layout 9411 9412\end_inset 9413 9414 9415\end_layout 9416 9417\begin_layout Description 9418 9419\family typewriter 9420HXlist_for_each 9421\family default 9422 Forward iteration over the list heads. 9423\end_layout 9424 9425\begin_layout Description 9426 9427\family typewriter 9428HXlist_for_each_rev 9429\family default 9430 Reverse iteration over the list heads. 9431\end_layout 9432 9433\begin_layout Description 9434 9435\family typewriter 9436HXlist_for_each_safe 9437\family default 9438 Forward iteration over the list heads that is safe against freeing 9439\family typewriter 9440pos 9441\family default 9442. 9443\end_layout 9444 9445\begin_layout Description 9446 9447\family typewriter 9448HXlist_for_each_rev_safe 9449\family default 9450 Reverse iteration over the list heads that is safe against freeing 9451\family typewriter 9452pos 9453\family default 9454. 9455\end_layout 9456 9457\begin_layout Standard 9458The 9459\family typewriter 9460_entry 9461\family default 9462 variants use an iterator 9463\family typewriter 9464pos 9465\family default 9466 of the type of the encompassing object (e. 9467\begin_inset space \thinspace{} 9468\end_inset 9469 9470g. 9471\begin_inset space \space{} 9472\end_inset 9473 9474 9475\family typewriter 9476struct item 9477\family default 9478 in below's example), so that the manual 9479\family typewriter 9480HXlist_entry 9481\family default 9482 invocation is not needed. 9483 9484\family typewriter 9485member 9486\family default 9487 is the name of the list structure embedded into the item. 9488\end_layout 9489 9490\begin_layout LyX-Code 9491HXlist_for_each_entry(pos, head, member) 9492\begin_inset Index idx 9493status open 9494 9495\begin_layout Plain Layout 9496 9497\family typewriter 9498HXlist_for_each_entry 9499\end_layout 9500 9501\end_inset 9502 9503 9504\begin_inset Newline newline 9505\end_inset 9506 9507HXlist_for_each_entry_rev(pos, head, member) 9508\begin_inset Index idx 9509status open 9510 9511\begin_layout Plain Layout 9512 9513\family typewriter 9514HXlist_for_each_entry_rev 9515\end_layout 9516 9517\end_inset 9518 9519 9520\begin_inset Newline newline 9521\end_inset 9522 9523HXlist_for_each_entry_safe(pos, n, head, member) 9524\begin_inset Index idx 9525status open 9526 9527\begin_layout Plain Layout 9528 9529\family typewriter 9530HXlist_for_each_entry_safe 9531\end_layout 9532 9533\end_inset 9534 9535 9536\end_layout 9537 9538\begin_layout Description 9539 9540\family typewriter 9541HXlist_for_each_entry 9542\family default 9543 Forward iteration over the list elements. 9544\end_layout 9545 9546\begin_layout Description 9547 9548\family typewriter 9549HXlist_for_each_entry_rev 9550\family default 9551 Reverse iteration over the list elements. 9552\end_layout 9553 9554\begin_layout Description 9555 9556\family typewriter 9557HXlist_for_each_entry_safe 9558\family default 9559 Forward iteration over the list elements that is safe against freeing 9560\family typewriter 9561pos 9562\family default 9563. 9564\end_layout 9565 9566\begin_layout Subsection 9567Examples 9568\end_layout 9569 9570\begin_layout LyX-Code 9571 9572\series bold 9573struct 9574\series default 9575 item { 9576\begin_inset Newline newline 9577\end_inset 9578 9579 9580\series bold 9581struct 9582\series default 9583 HXlist_head anchor; 9584\begin_inset Newline newline 9585\end_inset 9586 9587 9588\series bold 9589char 9590\series default 9591 name 9592\series bold 9593[ 9594\series default 959532 9596\series bold 9597] 9598\series default 9599; 9600\begin_inset Newline newline 9601\end_inset 9602 9603}; 9604\begin_inset Newline newline 9605\end_inset 9606 9607 9608\begin_inset Newline newline 9609\end_inset 9610 9611 9612\series bold 9613struct 9614\series default 9615 HXlist_head 9616\series bold 9617* 9618\series default 9619e; 9620\begin_inset Newline newline 9621\end_inset 9622 9623 9624\series bold 9625struct 9626\series default 9627 item 9628\series bold 9629* 9630\series default 9631i, 9632\series bold 9633* 9634\series default 9635j; 9636\begin_inset Newline newline 9637\end_inset 9638 9639HXLIST_HEAD(list); 9640\begin_inset Newline newline 9641\end_inset 9642 9643 9644\begin_inset Newline newline 9645\end_inset 9646 9647i = malloc( 9648\series bold 9649sizeof 9650\series default 9651( 9652\series bold 9653* 9654\series default 9655i)); 9656\begin_inset Newline newline 9657\end_inset 9658 9659HXlist_init(&e->anchor); 9660\begin_inset Newline newline 9661\end_inset 9662 9663strcpy(i->name, "foo"); 9664\begin_inset Newline newline 9665\end_inset 9666 9667HXlist_add_tail(&list, &i->anchor); 9668\begin_inset Newline newline 9669\end_inset 9670 9671 9672\begin_inset Newline newline 9673\end_inset 9674 9675i = malloc( 9676\series bold 9677sizeof 9678\series default 9679( 9680\series bold 9681* 9682\series default 9683i)); 9684\begin_inset Newline newline 9685\end_inset 9686 9687HXlist_init(&e->anchor); 9688\begin_inset Newline newline 9689\end_inset 9690 9691strcpy(i->name, "bar"); 9692\begin_inset Newline newline 9693\end_inset 9694 9695HXlist_add_tail(&list, &i->anchor); 9696\begin_inset Newline newline 9697\end_inset 9698 9699 9700\begin_inset Newline newline 9701\end_inset 9702 9703HXlist_for_each(e, &list) { 9704\begin_inset Newline newline 9705\end_inset 9706 9707 i = HXlist_entry(e, 9708\series bold 9709typeof 9710\series default 9711( 9712\series bold 9713* 9714\series default 9715i), anchor); 9716\begin_inset Newline newline 9717\end_inset 9718 9719 printf("e=%p i=%p name=%s 9720\backslash 9721n", e, i, i->name); 9722\begin_inset Newline newline 9723\end_inset 9724 9725} 9726\begin_inset Newline newline 9727\end_inset 9728 9729 9730\begin_inset Newline newline 9731\end_inset 9732 9733HXlist_for_each_entry(i, &list, anchor) 9734\begin_inset Newline newline 9735\end_inset 9736 9737 printf("i=%p name=%s 9738\backslash 9739n", i, i->name); 9740\begin_inset Newline newline 9741\end_inset 9742 9743 9744\begin_inset Newline newline 9745\end_inset 9746 9747HXlist_for_each_entry_rev(i, &list, anchor) 9748\begin_inset Newline newline 9749\end_inset 9750 9751 printf("i=%p name=%s 9752\backslash 9753n", i, i->name); 9754\begin_inset Newline newline 9755\end_inset 9756 9757 9758\begin_inset Newline newline 9759\end_inset 9760 9761HXlist_for_each_entry_safe(i, j, &list, anchor) { 9762\begin_inset Newline newline 9763\end_inset 9764 9765 printf("i=%p name=%s 9766\backslash 9767n", i, i->name); 9768\begin_inset Newline newline 9769\end_inset 9770 9771 free(i); 9772\begin_inset Newline newline 9773\end_inset 9774 9775} 9776\end_layout 9777 9778\begin_layout Subsection 9779When to use HXdeque/HXlist 9780\end_layout 9781 9782\begin_layout Standard 9783The choice whether to use HXdeque or HXlist/HXclist depends on whether one 9784 wants the list head handling on the developer or on the library. 9785 Especially for 9786\begin_inset Quotes eld 9787\end_inset 9788 9789atomic 9790\begin_inset Quotes erd 9791\end_inset 9792 9793 and 9794\begin_inset Quotes eld 9795\end_inset 9796 9797small 9798\begin_inset Quotes erd 9799\end_inset 9800 9801 data, it might be easier to just let HXdeque do the management. 9802 Compare the following two code examples to store strings: 9803\end_layout 9804 9805\begin_layout Standard 9806\begin_inset Float figure 9807placement H 9808wide false 9809sideways false 9810status open 9811 9812\begin_layout LyX-Code 9813 9814\series bold 9815int 9816\series default 9817 main( 9818\family typewriter 9819\series bold 9820int 9821\series default 9822 argc, 9823\series bold 9824const char ** 9825\series default 9826argv) 9827\begin_inset Newline newline 9828\end_inset 9829 9830{ 9831\begin_inset Newline newline 9832\end_inset 9833 9834 9835\series bold 9836struct 9837\series default 9838 HXdeque 9839\series bold 9840* 9841\series default 9842dq = HXdeque_init(); 9843\begin_inset Newline newline 9844\end_inset 9845 9846 9847\series bold 9848while 9849\series default 9850 (--argc) 9851\begin_inset Newline newline 9852\end_inset 9853 9854 HXdeque_push(dq, ++argv); 9855\begin_inset Newline newline 9856\end_inset 9857 9858 9859\family default 9860\series bold 9861return 9862\family typewriter 9863\series default 9864 0; 9865\begin_inset Newline newline 9866\end_inset 9867 9868} 9869\end_layout 9870 9871\begin_layout Plain Layout 9872\begin_inset Caption Standard 9873 9874\begin_layout Plain Layout 9875Storing strings in a HXdeque 9876\end_layout 9877 9878\end_inset 9879 9880 9881\end_layout 9882 9883\end_inset 9884 9885 9886\end_layout 9887 9888\begin_layout Standard 9889\begin_inset Float figure 9890placement H 9891wide false 9892sideways false 9893status open 9894 9895\begin_layout LyX-Code 9896 9897\series bold 9898struct 9899\series default 9900 element { 9901\begin_inset Newline newline 9902\end_inset 9903 9904 9905\series bold 9906struct 9907\series default 9908 HXlist_head list; 9909\begin_inset Newline newline 9910\end_inset 9911 9912 9913\series bold 9914char * 9915\family typewriter 9916\series default 9917data; 9918\begin_inset Newline newline 9919\end_inset 9920 9921}; 9922\begin_inset Newline newline 9923\end_inset 9924 9925 9926\begin_inset Newline newline 9927\end_inset 9928 9929 9930\series bold 9931int 9932\series default 9933 main( 9934\series bold 9935int 9936\series default 9937 main, 9938\series bold 9939const char ** 9940\series default 9941argv) 9942\begin_inset Newline newline 9943\end_inset 9944 9945{ 9946\begin_inset Newline newline 9947\end_inset 9948 9949 HXLIST_HEAD(lh); 9950\begin_inset Newline newline 9951\end_inset 9952 9953 9954\series bold 9955while 9956\series default 9957 (--argc) { 9958\begin_inset Newline newline 9959\end_inset 9960 9961 9962\series bold 9963struct 9964\series default 9965 element 9966\series bold 9967* 9968\series default 9969e = malloc( 9970\family default 9971\series bold 9972sizeof 9973\family typewriter 9974\series default 9975(*e)); 9976\begin_inset Newline newline 9977\end_inset 9978 9979 e->data = *++argv; 9980\begin_inset Newline newline 9981\end_inset 9982 9983 HXlist_init(&e->list); 9984\begin_inset Newline newline 9985\end_inset 9986 9987 HXlist_add_tail(&e->list); 9988\begin_inset Newline newline 9989\end_inset 9990 9991 } 9992\begin_inset Newline newline 9993\end_inset 9994 9995 9996\series bold 9997return 9998\series default 9999 0; 10000\begin_inset Newline newline 10001\end_inset 10002 10003} 10004\end_layout 10005 10006\begin_layout Plain Layout 10007\begin_inset Caption Standard 10008 10009\begin_layout Plain Layout 10010Storing strings in a HXlist 10011\end_layout 10012 10013\end_inset 10014 10015 10016\end_layout 10017 10018\end_inset 10019 10020 10021\end_layout 10022 10023\begin_layout Standard 10024These examples assume that 10025\family typewriter 10026argv 10027\family default 10028 is persistent, which, for the sample, is true. 10029\end_layout 10030 10031\begin_layout Standard 10032With HXlist, one needs to have a struct with a HXlist_head in it, and if 10033 one does not already have such a struct 10034\begin_inset space ~ 10035\end_inset 10036 10037—e. 10038\begin_inset space \thinspace{} 10039\end_inset 10040 10041g. 10042\begin_inset space \space{} 10043\end_inset 10044 10045by means of wanting to store more than just one value 10046\begin_inset space ~ 10047\end_inset 10048 10049— one will need to create it first, as shown, and this may lead to an expansion 10050 of code. 10051\end_layout 10052 10053\begin_layout Standard 10054This however does not mean that HXlist is the better solution over HXdeque 10055 for data already available in a struct. 10056 As each struct has a list_head that is unique to the node, it is not possible 10057 to share this data. 10058 Trying to add a HXlist_head to another list is not going to end well, while 10059 HXdeque has no problem with this as list heads are detached from the actual 10060 data in HXdeque. 10061\end_layout 10062 10063\begin_layout Standard 10064\begin_inset Float figure 10065placement H 10066wide false 10067sideways false 10068status open 10069 10070\begin_layout LyX-Code 10071 10072\series bold 10073struct 10074\series default 10075 point p = {15, 30}; 10076\begin_inset Newline newline 10077\end_inset 10078 10079HXdeque_push(dq, &p); 10080\begin_inset Newline newline 10081\end_inset 10082 10083HXdeque_push(dq, &p); 10084\end_layout 10085 10086\begin_layout Plain Layout 10087\begin_inset Caption Standard 10088 10089\begin_layout Plain Layout 10090Data can be added multiple times in a HXdeque without ill effects 10091\end_layout 10092 10093\end_inset 10094 10095 10096\end_layout 10097 10098\end_inset 10099 10100 10101\end_layout 10102 10103\begin_layout Standard 10104To support this, an extra allocation is needed on the other hand. 10105 In a HXlist, to store 10106\begin_inset Formula $n$ 10107\end_inset 10108 10109 elements of compound data (e. 10110\begin_inset space \thinspace{} 10111\end_inset 10112 10113g. 10114\begin_inset space \space{} 10115\end_inset 10116 10117 10118\family typewriter 10119struct point 10120\family default 10121), 10122\begin_inset Formula $n$ 10123\end_inset 10124 10125 allocations are needed, assuming the list head is a stack object, and the 10126 points are not. 10127 HXdeque will need at least 10128\begin_inset Formula $2n+1$ 10129\end_inset 10130 10131 allocations, 10132\begin_inset Formula $n$ 10133\end_inset 10134 10135 for the nodes, 10136\begin_inset Formula $n$ 10137\end_inset 10138 10139 for the points and another for the head. 10140\end_layout 10141 10142\begin_layout Standard 10143\begin_inset Newpage clearpage 10144\end_inset 10145 10146 10147\end_layout 10148 10149\begin_layout Section 10150Counted inline doubly-linked list 10151\begin_inset CommandInset label 10152LatexCommand label 10153name "sec:clist" 10154 10155\end_inset 10156 10157 10158\end_layout 10159 10160\begin_layout Standard 10161clist is the inline doubly-linked list from chapter 10162\begin_inset space ~ 10163\end_inset 10164 10165 10166\begin_inset CommandInset ref 10167LatexCommand ref 10168reference "sec:list" 10169 10170\end_inset 10171 10172, extended by a counter to retrieve the number of elements in the list in 10173 10174\begin_inset Formula $\mathcal{O}\left(1\right)$ 10175\end_inset 10176 10177 time. 10178 This is also why all operations always require the list head. 10179 For traversal of clists, use the corresponding HXlist macros. 10180\end_layout 10181 10182\begin_layout Subsection 10183Synopsis 10184\end_layout 10185 10186\begin_layout LyX-Code 10187 10188\series bold 10189#include 10190\series default 10191 <libHX/list.h> 10192\begin_inset Index idx 10193status open 10194 10195\begin_layout Plain Layout 10196 10197\family typewriter 10198libHX/list.h 10199\end_layout 10200 10201\end_inset 10202 10203 10204\begin_inset Newline newline 10205\end_inset 10206 10207 10208\begin_inset Newline newline 10209\end_inset 10210 10211 10212\series bold 10213struct 10214\series default 10215 HXclist_head { 10216\begin_inset Index idx 10217status open 10218 10219\begin_layout Plain Layout 10220 10221\family typewriter 10222struct HXclist_head 10223\end_layout 10224 10225\end_inset 10226 10227 10228\begin_inset Newline newline 10229\end_inset 10230 10231 10232\series bold 10233/* 10234\family roman 10235\series default 10236\shape italic 10237public readonly: 10238\family default 10239\series bold 10240\shape default 10241 */ 10242\series default 10243 10244\begin_inset Newline newline 10245\end_inset 10246 10247 10248\series bold 10249unsigned int 10250\series default 10251 items; 10252\begin_inset Newline newline 10253\end_inset 10254 10255 10256\series bold 10257/* 10258\family roman 10259\series default 10260\shape italic 10261Undocumented fields are considered 10262\begin_inset Quotes eld 10263\end_inset 10264 10265private 10266\begin_inset Quotes erd 10267\end_inset 10268 10269 10270\family default 10271\series bold 10272\shape default 10273 */ 10274\series default 10275 10276\begin_inset Newline newline 10277\end_inset 10278 10279}; 10280\begin_inset Newline newline 10281\end_inset 10282 10283 10284\begin_inset Newline newline 10285\end_inset 10286 10287HXCLIST_HEAD_INIT(name); 10288\begin_inset Index idx 10289status open 10290 10291\begin_layout Plain Layout 10292 10293\family typewriter 10294HXCLIST_HEAD_INIT 10295\end_layout 10296 10297\end_inset 10298 10299 10300\begin_inset Newline newline 10301\end_inset 10302 10303HXCLIST_HEAD(name); 10304\begin_inset Index idx 10305status open 10306 10307\begin_layout Plain Layout 10308 10309\family typewriter 10310HXCLIST_HEAD 10311\end_layout 10312 10313\end_inset 10314 10315 10316\begin_inset Newline newline 10317\end_inset 10318 10319 10320\series bold 10321void 10322\series default 10323 HXclist_init( 10324\series bold 10325struct 10326\series default 10327 HXclist_head 10328\series bold 10329* 10330\series default 10331head); 10332\begin_inset Index idx 10333status open 10334 10335\begin_layout Plain Layout 10336 10337\family typewriter 10338HXclist_init 10339\end_layout 10340 10341\end_inset 10342 10343 10344\begin_inset Newline newline 10345\end_inset 10346 10347 10348\series bold 10349void 10350\series default 10351 HXclist_unshift( 10352\series bold 10353struct 10354\series default 10355 HXclist_head 10356\series bold 10357* 10358\series default 10359head, 10360\series bold 10361struct 10362\series default 10363 HXlist_head 10364\series bold 10365* 10366\series default 10367new_node); 10368\begin_inset Index idx 10369status open 10370 10371\begin_layout Plain Layout 10372 10373\family typewriter 10374HXclist_unshift 10375\end_layout 10376 10377\end_inset 10378 10379 10380\begin_inset Newline newline 10381\end_inset 10382 10383 10384\series bold 10385void 10386\series default 10387 HXclist_push( 10388\series bold 10389struct 10390\series default 10391 HXclist_head 10392\series bold 10393* 10394\series default 10395head, 10396\series bold 10397struct 10398\series default 10399 HXlist_head 10400\series bold 10401* 10402\series default 10403new_node); 10404\begin_inset Index idx 10405status open 10406 10407\begin_layout Plain Layout 10408 10409\family typewriter 10410HXclist_push 10411\end_layout 10412 10413\end_inset 10414 10415 10416\begin_inset Newline newline 10417\end_inset 10418 10419 10420\series bold 10421type 10422\series default 10423 HXclist_pop( 10424\series bold 10425struct 10426\series default 10427 HXclist_head 10428\series bold 10429* 10430\series default 10431head, 10432\series bold 10433type 10434\series default 10435, member); 10436\begin_inset Index idx 10437status open 10438 10439\begin_layout Plain Layout 10440 10441\family typewriter 10442HXclist_pop 10443\end_layout 10444 10445\end_inset 10446 10447 10448\begin_inset Newline newline 10449\end_inset 10450 10451 10452\series bold 10453type 10454\series default 10455 HXclist_shift( 10456\series bold 10457struct 10458\series default 10459 HXclist_head 10460\series bold 10461* 10462\series default 10463head, 10464\series bold 10465type 10466\series default 10467, member); 10468\begin_inset Index idx 10469status open 10470 10471\begin_layout Plain Layout 10472 10473\family typewriter 10474HXclist_shift 10475\end_layout 10476 10477\end_inset 10478 10479 10480\begin_inset Newline newline 10481\end_inset 10482 10483 10484\series bold 10485void 10486\series default 10487 HXclist_del( 10488\series bold 10489struct 10490\series default 10491 HXclist_head 10492\series bold 10493* 10494\series default 10495head, 10496\series bold 10497struct 10498\series default 10499HXlist_chead 10500\series bold 10501* 10502\series default 10503node); 10504\begin_inset Index idx 10505status open 10506 10507\begin_layout Plain Layout 10508 10509\family typewriter 10510HXclist_del 10511\end_layout 10512 10513\end_inset 10514 10515 10516\end_layout 10517 10518\begin_layout Description 10519 10520\family typewriter 10521HXCLIST_HEAD_INIT 10522\family default 10523 Macro that expands to the static initializer for a clist. 10524\end_layout 10525 10526\begin_layout Description 10527 10528\family typewriter 10529HXCLIST_HEAD 10530\family default 10531 Macro that expands to the definition of a clist head, with initialization. 10532\end_layout 10533 10534\begin_layout Description 10535 10536\family typewriter 10537HXclist_init 10538\family default 10539 Initializes a clist. 10540 This function is generally used when the head has been allocated from the 10541 heap. 10542\end_layout 10543 10544\begin_layout Description 10545 10546\family typewriter 10547HXclist_unshift 10548\family default 10549 Adds the node to the front of the list. 10550\end_layout 10551 10552\begin_layout Description 10553 10554\family typewriter 10555HXclist_push 10556\family default 10557 Adds the node to the end of the list. 10558\end_layout 10559 10560\begin_layout Description 10561 10562\family typewriter 10563HXclist_pop 10564\family default 10565 Removes the last node in the list and returns it. 10566\end_layout 10567 10568\begin_layout Description 10569 10570\family typewriter 10571HXclist_shift 10572\family default 10573 Removes the first node in the list and returns it. 10574\end_layout 10575 10576\begin_layout Description 10577 10578\family typewriter 10579HXclist_del 10580\family default 10581 Deletes the node from the list. 10582\end_layout 10583 10584\begin_layout Standard 10585The list count in the clist head is updated whenever a modification is done 10586 on the clist through these functions. 10587\end_layout 10588 10589\begin_layout Standard 10590\begin_inset Newpage clearpage 10591\end_inset 10592 10593 10594\end_layout 10595 10596\begin_layout Part 10597Strings and memory 10598\end_layout 10599 10600\begin_layout Section 10601String operations 10602\begin_inset CommandInset label 10603LatexCommand label 10604name "sec:strings" 10605 10606\end_inset 10607 10608 10609\end_layout 10610 10611\begin_layout Standard 10612Some string functions are merely present in libHX because they are otherwise 10613 unportable; some are only in the C libraries of the BSDs, some only in 10614 GNU libc. 10615\end_layout 10616 10617\begin_layout Subsection 10618Locating chars 10619\end_layout 10620 10621\begin_layout LyX-Code 10622 10623\series bold 10624#include 10625\series default 10626 <libHX/string.h> 10627\begin_inset Index idx 10628status open 10629 10630\begin_layout Plain Layout 10631 10632\family typewriter 10633libHX/string.h 10634\end_layout 10635 10636\end_inset 10637 10638 10639\begin_inset Newline newline 10640\end_inset 10641 10642 10643\begin_inset Newline newline 10644\end_inset 10645 10646 10647\series bold 10648void * 10649\series default 10650HX_memmem( 10651\series bold 10652const void * 10653\series default 10654haystack, 10655\series bold 10656size_t 10657\series default 10658 hsize, 10659\begin_inset Newline newline 10660\end_inset 10661 10662 10663\series bold 10664const void * 10665\series default 10666needle, 10667\series bold 10668size_t 10669\series default 10670 nsize); 10671\begin_inset Index idx 10672status open 10673 10674\begin_layout Plain Layout 10675 10676\family typewriter 10677HX_memmem 10678\end_layout 10679 10680\end_inset 10681 10682 10683\series bold 10684 10685\begin_inset Newline newline 10686\end_inset 10687 10688char * 10689\series default 10690HX_strbchr( 10691\series bold 10692const char * 10693\series default 10694start, 10695\series bold 10696const char * 10697\series default 10698now, 10699\series bold 10700char 10701\series default 10702 delimiter); 10703\begin_inset Index idx 10704status open 10705 10706\begin_layout Plain Layout 10707 10708\family typewriter 10709HX_strbchr 10710\end_layout 10711 10712\end_inset 10713 10714 10715\begin_inset Newline newline 10716\end_inset 10717 10718 10719\series bold 10720char * 10721\series default 10722HX_strchr2( 10723\series bold 10724const char * 10725\series default 10726s, 10727\series bold 10728const char * 10729\series default 10730accept); 10731\begin_inset Index idx 10732status open 10733 10734\begin_layout Plain Layout 10735HX_strchr2 10736\end_layout 10737 10738\end_inset 10739 10740 10741\begin_inset Newline newline 10742\end_inset 10743 10744 10745\series bold 10746size_t 10747\series default 10748 HX_strrcspn( 10749\series bold 10750const char * 10751\series default 10752s, 10753\series bold 10754const char * 10755\series default 10756reject); 10757\begin_inset Index idx 10758status open 10759 10760\begin_layout Plain Layout 10761 10762\family typewriter 10763HX_strccspn 10764\end_layout 10765 10766\end_inset 10767 10768 10769\end_layout 10770 10771\begin_layout Description 10772 10773\family typewriter 10774HX_memmem 10775\family default 10776 Analogous to 10777\family typewriter 10778strstr 10779\family default 10780(3), 10781\family typewriter 10782memmem 10783\family default 10784 tries to locate the memory block pointed to by 10785\family typewriter 10786needle 10787\family default 10788 (which is of length 10789\family typewriter 10790nsize 10791\family default 10792) in the block pointed to by 10793\family typewriter 10794haystack 10795\family default 10796 (which is of size 10797\family typewriter 10798hsize 10799\family default 10800). 10801 It returns a pointer to the first occurrence in 10802\family typewriter 10803haystack 10804\family default 10805, or 10806\family typewriter 10807NULL 10808\family default 10809 when it was not found. 10810\end_layout 10811 10812\begin_layout Description 10813 10814\family typewriter 10815HX_strbchr 10816\family default 10817 Searches the character specified by 10818\family typewriter 10819delimiter 10820\family default 10821 in the range from 10822\family typewriter 10823now 10824\family default 10825 to 10826\family typewriter 10827start 10828\family default 10829. 10830 It works like 10831\family typewriter 10832strrchr 10833\family default 10834(3) 10835\begin_inset Index idx 10836status open 10837 10838\begin_layout Plain Layout 10839 10840\family typewriter 10841strrchr 10842\end_layout 10843 10844\end_inset 10845 10846, but begins at 10847\family typewriter 10848now 10849\family default 10850 rather than the end of the string. 10851\end_layout 10852 10853\begin_layout Description 10854 10855\family typewriter 10856HX_strchr2 10857\family default 10858 This function searches the string 10859\family typewriter 10860s 10861\family default 10862 for any set of bytes that are not specified in the second argument, 10863\family typewriter 10864n 10865\family default 10866. 10867 In this regard, the function is the opposite to 10868\family typewriter 10869strpbrk 10870\family default 10871(3) 10872\begin_inset Index idx 10873status open 10874 10875\begin_layout Plain Layout 10876 10877\family typewriter 10878strpbrk 10879\end_layout 10880 10881\end_inset 10882 10883. 10884\end_layout 10885 10886\begin_layout Description 10887 10888\family typewriter 10889HX_strrcspn 10890\family default 10891 Works like 10892\family typewriter 10893strcspn 10894\family default 10895(3) 10896\begin_inset Index idx 10897status open 10898 10899\begin_layout Plain Layout 10900 10901\family typewriter 10902\size normal 10903\color none 10904strcspn 10905\end_layout 10906 10907\end_inset 10908 10909, but processes the string from end to start. 10910\end_layout 10911 10912\begin_layout Subsection 10913Extraction 10914\end_layout 10915 10916\begin_layout LyX-Code 10917 10918\series bold 10919#include 10920\series default 10921 <libHX/string.h> 10922\begin_inset Index idx 10923status open 10924 10925\begin_layout Plain Layout 10926 10927\family typewriter 10928libHX/string.h 10929\end_layout 10930 10931\end_inset 10932 10933 10934\begin_inset Newline newline 10935\end_inset 10936 10937 10938\begin_inset Newline newline 10939\end_inset 10940 10941 10942\series bold 10943char * 10944\series default 10945HX_basename( 10946\series bold 10947const char * 10948\series default 10949s); 10950\begin_inset Index idx 10951status open 10952 10953\begin_layout Plain Layout 10954 10955\family typewriter 10956HX_basename 10957\end_layout 10958 10959\end_inset 10960 10961 10962\begin_inset Newline newline 10963\end_inset 10964 10965 10966\series bold 10967char * 10968\series default 10969HX_basename_exact( 10970\series bold 10971const char * 10972\series default 10973s); 10974\begin_inset Index idx 10975status open 10976 10977\begin_layout Plain Layout 10978 10979\family typewriter 10980HX_basename_exact 10981\end_layout 10982 10983\end_inset 10984 10985 10986\begin_inset Newline newline 10987\end_inset 10988 10989 10990\series bold 10991char * 10992\series default 10993HX_dirname( 10994\series bold 10995const char * 10996\series default 10997s); 10998\begin_inset Index idx 10999status open 11000 11001\begin_layout Plain Layout 11002 11003\family typewriter 11004\size normal 11005\color none 11006HX_dirname 11007\end_layout 11008 11009\end_inset 11010 11011 11012\begin_inset Newline newline 11013\end_inset 11014 11015 11016\series bold 11017char * 11018\series default 11019HX_strmid( 11020\series bold 11021const char * 11022\series default 11023s, 11024\series bold 11025long 11026\series default 11027 offset, 11028\series bold 11029long 11030\series default 11031 length); 11032\begin_inset Index idx 11033status open 11034 11035\begin_layout Plain Layout 11036 11037\family typewriter 11038\size normal 11039\color none 11040HX_strmid 11041\end_layout 11042 11043\end_inset 11044 11045 11046\end_layout 11047 11048\begin_layout Description 11049 11050\family typewriter 11051HX_basename 11052\family default 11053 Returns a pointer to the basename portion of the supplied path 11054\family typewriter 11055s 11056\family default 11057. 11058 The result of this function is never 11059\family typewriter 11060NULL 11061\family default 11062, and must never be freed either. 11063 Trailing slashes are not stripped, to avoid having to do an allocation. 11064 In other words, 11065\family typewriter 11066basename("/mnt/") 11067\family default 11068 will return 11069\begin_inset Quotes eld 11070\end_inset 11071 11072 11073\family typewriter 11074mnt/ 11075\family default 11076 11077\begin_inset Quotes erd 11078\end_inset 11079 11080. 11081 If you need to have the slashes stripped, use 11082\family typewriter 11083HX_basename_exact 11084\family default 11085. 11086 A possible use for this function is, for example, to derive a logging prefix 11087 from 11088\family typewriter 11089argv[0] 11090\family default 11091. 11092\end_layout 11093 11094\begin_layout LyX-Code 11095 11096\series bold 11097int 11098\series default 11099 main( 11100\series bold 11101int 11102\series default 11103 argc, 11104\series bold 11105const char ** 11106\series default 11107argv) 11108\begin_inset Newline newline 11109\end_inset 11110 11111{ 11112\begin_inset Newline newline 11113\end_inset 11114 11115 11116\series bold 11117if 11118\series default 11119 (foo()) 11120\end_layout 11121 11122\begin_layout LyX-Code 11123 fprintf(stderr, "%s: Special condition occurred. 11124\backslash 11125n", 11126\begin_inset Newline newline 11127\end_inset 11128 11129 HX_basename(argv[0])); 11130\begin_inset Newline newline 11131\end_inset 11132 11133 11134\series bold 11135return 11136\series default 11137 0; 11138\begin_inset Newline newline 11139\end_inset 11140 11141} 11142\end_layout 11143 11144\begin_layout Description 11145 11146\family typewriter 11147HX_basename_exact 11148\family default 11149 The accurate and safe version of 11150\family typewriter 11151HX_basename 11152\family default 11153 that deals with trailing slashes correctly and produces the same result 11154 as 11155\family typewriter 11156dirname 11157\family default 11158(3). 11159 It returns a pointer to a newly-allocated string that must be freed when 11160 done using. 11161 11162\family typewriter 11163NULL 11164\family default 11165 may be returned in case of an allocation error. 11166\end_layout 11167 11168\begin_layout Description 11169 11170\family typewriter 11171HX_dirname 11172\family default 11173 Returns a pointer to a new string that contains the directory name portion 11174 (everything except basename). 11175 When done using the string, it must be freed to avoid memory leaks. 11176\end_layout 11177 11178\begin_layout Description 11179 11180\family typewriter 11181HX_strmid 11182\family default 11183 Extract a substring of 11184\family typewriter 11185length 11186\family default 11187 characters from 11188\family typewriter 11189s 11190\family default 11191, beginning at 11192\family typewriter 11193offset 11194\family default 11195. 11196 If 11197\family typewriter 11198offset 11199\family default 11200 is negative, counting beings from the end of the string; 11201\begin_inset Formula $-1$ 11202\end_inset 11203 11204 is the last character (not the 11205\family typewriter 11206' 11207\backslash 112080' 11209\family default 11210 byte). 11211 If 11212\family typewriter 11213length 11214\family default 11215 is negative, it will leave out that many characters off the end. 11216 The function returns a pointer to a new string, and the user has to free 11217 it. 11218\end_layout 11219 11220\begin_layout Subsection 11221In-place transformations 11222\end_layout 11223 11224\begin_layout LyX-Code 11225 11226\series bold 11227#include 11228\series default 11229 <libHX/string.h> 11230\begin_inset Index idx 11231status open 11232 11233\begin_layout Plain Layout 11234 11235\family typewriter 11236libHX/string.h 11237\end_layout 11238 11239\end_inset 11240 11241 11242\begin_inset Newline newline 11243\end_inset 11244 11245 11246\begin_inset Newline newline 11247\end_inset 11248 11249 11250\series bold 11251char * 11252\series default 11253HX_chomp( 11254\series bold 11255char * 11256\series default 11257s); 11258\begin_inset Index idx 11259status open 11260 11261\begin_layout Plain Layout 11262 11263\family typewriter 11264\size normal 11265\color none 11266HX_chomp 11267\end_layout 11268 11269\end_inset 11270 11271 11272\begin_inset Newline newline 11273\end_inset 11274 11275 11276\series bold 11277size_t 11278\series default 11279 HX_strltrim( 11280\series bold 11281char * 11282\series default 11283s); 11284\begin_inset Index idx 11285status open 11286 11287\begin_layout Plain Layout 11288 11289\family typewriter 11290\size normal 11291\color none 11292HX_strltrim 11293\end_layout 11294 11295\end_inset 11296 11297 11298\begin_inset Newline newline 11299\end_inset 11300 11301 11302\series bold 11303char * 11304\series default 11305HX_stpltrim( 11306\series bold 11307const char * 11308\series default 11309s); 11310\begin_inset Index idx 11311status open 11312 11313\begin_layout Plain Layout 11314HX_stpltrim 11315\end_layout 11316 11317\end_inset 11318 11319 11320\begin_inset Newline newline 11321\end_inset 11322 11323 11324\series bold 11325char * 11326\series default 11327HX_strlower( 11328\series bold 11329char * 11330\series default 11331s); 11332\begin_inset Index idx 11333status open 11334 11335\begin_layout Plain Layout 11336 11337\family typewriter 11338\size normal 11339\color none 11340HX_strlower 11341\end_layout 11342 11343\end_inset 11344 11345 11346\begin_inset Newline newline 11347\end_inset 11348 11349 11350\series bold 11351char * 11352\series default 11353HX_strrev( 11354\series bold 11355char * 11356\series default 11357s); 11358\begin_inset Index idx 11359status open 11360 11361\begin_layout Plain Layout 11362 11363\family typewriter 11364\size normal 11365\color none 11366HX_strrev 11367\end_layout 11368 11369\end_inset 11370 11371 11372\begin_inset Newline newline 11373\end_inset 11374 11375 11376\series bold 11377size_t 11378\series default 11379 HX_strrtrim( 11380\series bold 11381char * 11382\series default 11383s); 11384\begin_inset Index idx 11385status open 11386 11387\begin_layout Plain Layout 11388 11389\family typewriter 11390\size normal 11391\color none 11392HX_strrtrim 11393\end_layout 11394 11395\end_inset 11396 11397 11398\begin_inset Newline newline 11399\end_inset 11400 11401 11402\series bold 11403char * 11404\series default 11405HX_strupper( 11406\series bold 11407char * 11408\series default 11409s); 11410\begin_inset Index idx 11411status open 11412 11413\begin_layout Plain Layout 11414 11415\family typewriter 11416\size normal 11417\color none 11418HX_strupper 11419\end_layout 11420 11421\end_inset 11422 11423 11424\end_layout 11425 11426\begin_layout Description 11427 11428\family typewriter 11429HX_chomp 11430\family default 11431 Removes the characters 11432\family typewriter 11433' 11434\backslash 11435r' 11436\family default 11437 and 11438\family typewriter 11439' 11440\backslash 11441n' 11442\family default 11443 from the right edge of the string. 11444 Returns the original argument. 11445\end_layout 11446 11447\begin_layout Description 11448 11449\family typewriter 11450HX_strltrim 11451\family default 11452 Trim all whitespace (characters on which 11453\family typewriter 11454isspace 11455\family default 11456(3) return true) on the left edge of the string. 11457 Returns the number of characters that were stripped. 11458\end_layout 11459 11460\begin_layout Description 11461 11462\family typewriter 11463HX_stpltrim 11464\family default 11465 Returns a pointer to the first non-whitespace character in 11466\family typewriter 11467s 11468\family default 11469. 11470\end_layout 11471 11472\begin_layout Description 11473 11474\family typewriter 11475HX_strlower 11476\family default 11477 Transforms all characters in the string 11478\family typewriter 11479s 11480\family default 11481 into lowercase using 11482\family typewriter 11483tolower 11484\family default 11485(3). 11486 Returns the original argument. 11487\end_layout 11488 11489\begin_layout Description 11490 11491\family typewriter 11492HX_strrev 11493\family default 11494 Reverse the string in-place. 11495 Returns the original argument. 11496\end_layout 11497 11498\begin_layout Description 11499 11500\family typewriter 11501HX_strrtrim 11502\family default 11503 Trim all whitespace on the right edge of the string. 11504 Returns the number of characters that were stripped. 11505\end_layout 11506 11507\begin_layout Description 11508 11509\family typewriter 11510HX_strupper 11511\family default 11512 Transforms all characters in the string 11513\family typewriter 11514s 11515\family default 11516 into uppercase using 11517\family typewriter 11518toupper 11519\family default 11520(3). 11521 Returns the original argument. 11522\end_layout 11523 11524\begin_layout Subsection 11525Out-of-place quoting transforms 11526\end_layout 11527 11528\begin_layout LyX-Code 11529 11530\series bold 11531#include 11532\series default 11533 <libHX/string.h> 11534\begin_inset Index idx 11535status open 11536 11537\begin_layout Plain Layout 11538 11539\family typewriter 11540libHX/string.h 11541\end_layout 11542 11543\end_inset 11544 11545 11546\begin_inset Newline newline 11547\end_inset 11548 11549 11550\begin_inset Newline newline 11551\end_inset 11552 11553 11554\series bold 11555char * 11556\series default 11557HX_strquote( 11558\series bold 11559const char * 11560\series default 11561s, 11562\series bold 11563unsigned int 11564\series default 11565 type, 11566\series bold 11567char ** 11568\series default 11569free_me); 11570\begin_inset Index idx 11571status open 11572 11573\begin_layout Plain Layout 11574 11575\family typewriter 11576HX_strquote 11577\end_layout 11578 11579\end_inset 11580 11581 11582\end_layout 11583 11584\begin_layout Standard 11585 11586\family typewriter 11587HX_strquote 11588\family default 11589 will escape metacharacters in a string according to 11590\family typewriter 11591type 11592\family default 11593, and returns the escaped result. 11594\end_layout 11595 11596\begin_layout Standard 11597Possible values for 11598\family typewriter 11599type 11600\family default 11601: 11602\end_layout 11603 11604\begin_layout Description 11605 11606\family typewriter 11607HXQUOTE_SQUOTE 11608\family default 11609 11610\begin_inset Index idx 11611status open 11612 11613\begin_layout Plain Layout 11614 11615\family typewriter 11616HXQUOTE_SQUOTE 11617\end_layout 11618 11619\end_inset 11620 11621 Escape all single quotes and backslashes in a string with a backslash. 11622 ( 11623\begin_inset Quotes eld 11624\end_inset 11625 11626Ol' 11627\backslash 11628Backslash 11629\begin_inset Quotes erd 11630\end_inset 11631 11632 11633\begin_inset Formula $\rightarrow$ 11634\end_inset 11635 11636 11637\begin_inset Quotes eld 11638\end_inset 11639 11640Ol 11641\backslash 11642' 11643\backslash 11644 11645\backslash 11646Backslash 11647\begin_inset Quotes erd 11648\end_inset 11649 11650) 11651\end_layout 11652 11653\begin_layout Description 11654 11655\family typewriter 11656HXQUOTE_DQUOTE 11657\family default 11658 11659\begin_inset Index idx 11660status open 11661 11662\begin_layout Plain Layout 11663 11664\family typewriter 11665HXQUOTE_DQUOTE 11666\end_layout 11667 11668\end_inset 11669 11670 Escape all double quotes and backslahes in a string with the backslash 11671 method. 11672 ( 11673\begin_inset Quotes eld 11674\end_inset 11675 11676Ol 11677\begin_inset Quotes erd 11678\end_inset 11679 11680 11681\backslash 11682Backslash 11683\begin_inset Quotes erd 11684\end_inset 11685 11686 11687\begin_inset Formula $\rightarrow$ 11688\end_inset 11689 11690 11691\begin_inset Quotes eld 11692\end_inset 11693 11694Ol 11695\backslash 11696 11697\begin_inset Quotes erd 11698\end_inset 11699 11700 11701\backslash 11702 11703\backslash 11704Backslash 11705\begin_inset Quotes erd 11706\end_inset 11707 11708) 11709\end_layout 11710 11711\begin_layout Description 11712 11713\family typewriter 11714HXQUOTE_HTML 11715\family default 11716 11717\begin_inset Index idx 11718status open 11719 11720\begin_layout Plain Layout 11721 11722\family typewriter 11723HXQUOTE_HTML 11724\end_layout 11725 11726\end_inset 11727 11728 Escape ' 11729\family typewriter 11730< 11731\family default 11732', ' 11733\family typewriter 11734> 11735\family default 11736', ' 11737\family typewriter 11738& 11739\family default 11740' and ' 11741\family typewriter 11742" 11743\family default 11744' by their respective HTML entities 11745\family typewriter 11746< 11747\family default 11748, 11749\family typewriter 11750> 11751\family default 11752, 11753\family typewriter 11754& 11755\family default 11756 and 11757\family typewriter 11758" 11759\family default 11760. 11761\end_layout 11762 11763\begin_layout Description 11764 11765\family typewriter 11766HXQUOTE_LDAPFLT 11767\family default 11768 11769\begin_inset Index idx 11770status open 11771 11772\begin_layout Plain Layout 11773 11774\family typewriter 11775HXQUOTE_LDAPFLT 11776\end_layout 11777 11778\end_inset 11779 11780 Escape the string using backslash-plus-hexcode notation as described in 11781 RFC 4515 11782\begin_inset Foot 11783status open 11784 11785\begin_layout Plain Layout 11786\begin_inset Flex URL 11787status collapsed 11788 11789\begin_layout Plain Layout 11790 11791http://tools.ietf.org/html/rfc4515 11792\end_layout 11793 11794\end_inset 11795 11796 11797\end_layout 11798 11799\end_inset 11800 11801, to make it suitable for use in an LDAP search filter. 11802\end_layout 11803 11804\begin_layout Description 11805 11806\family typewriter 11807HXQUOTE_LDAPRDN 11808\family default 11809 11810\begin_inset Index idx 11811status open 11812 11813\begin_layout Plain Layout 11814 11815\family typewriter 11816HXQUOTE_LDAPRDN 11817\end_layout 11818 11819\end_inset 11820 11821 Escape the string using backslash-plus-hexcode notation as described in 11822 RFC 4514 11823\begin_inset Foot 11824status open 11825 11826\begin_layout Plain Layout 11827\begin_inset Flex URL 11828status collapsed 11829 11830\begin_layout Plain Layout 11831 11832http://tools.ietf.org/html/rfc4514 11833\end_layout 11834 11835\end_inset 11836 11837 11838\end_layout 11839 11840\end_inset 11841 11842, to make it suitable for use in an LDAP Relative Distinguished Name. 11843\end_layout 11844 11845\begin_layout Description 11846 11847\family typewriter 11848HXQUOTE_BASE64 11849\family default 11850 11851\begin_inset Index idx 11852status open 11853 11854\begin_layout Plain Layout 11855 11856\family typewriter 11857HXQUOTE_BASE64 11858\end_layout 11859 11860\end_inset 11861 11862 Transform the string to BASE64, as described in RFC 4648 11863\begin_inset Foot 11864status open 11865 11866\begin_layout Plain Layout 11867\begin_inset Flex URL 11868status collapsed 11869 11870\begin_layout Plain Layout 11871 11872http://tools.ietf.org/html/rfc4648 11873\end_layout 11874 11875\end_inset 11876 11877 11878\end_layout 11879 11880\end_inset 11881 11882. 11883\end_layout 11884 11885\begin_layout Description 11886 11887\family typewriter 11888HXQUOTE_URIENC 11889\family default 11890 11891\begin_inset Index idx 11892status open 11893 11894\begin_layout Plain Layout 11895 11896\family typewriter 11897HXQUOTE_URIENC 11898\end_layout 11899 11900\end_inset 11901 11902 Escape the string so that it becomes a valid part for an URI. 11903\end_layout 11904 11905\begin_layout Description 11906 11907\family typewriter 11908HXQUOTE_SQLSQUOTE 11909\family default 11910 11911\begin_inset Index idx 11912status open 11913 11914\begin_layout Plain Layout 11915 11916\family typewriter 11917HXQUOTE_SQLSQUOTE 11918\end_layout 11919 11920\end_inset 11921 11922 Escape all single quotes in the string by double single-quotes, as required 11923 for using it in a single-quoted SQL string. 11924 No surrounding quotes will be generated to facilitate concatenating of 11925 11926\family typewriter 11927HX_strquote 11928\family default 11929 results. 11930\end_layout 11931 11932\begin_layout Description 11933 11934\family typewriter 11935HXQUOTE_SQLBQUOTE 11936\family default 11937 11938\begin_inset Index idx 11939status open 11940 11941\begin_layout Plain Layout 11942 11943\family typewriter 11944HXQUOTE_SQLBQUOTE 11945\end_layout 11946 11947\end_inset 11948 11949 Escape all backticks in the string by double backticks, as required for 11950 using it in a backtick-quoted SQL string (used for table names and columns). 11951 No surrounding ticks will be generated to facilitate concatenation. 11952\end_layout 11953 11954\begin_layout Standard 11955Specifying an unrecognized type will result in 11956\family typewriter 11957NULL 11958\family default 11959 being returned and 11960\family typewriter 11961errno 11962\family default 11963 be set to 11964\family typewriter 11965EINVAL 11966\family default 11967. 11968\end_layout 11969 11970\begin_layout Standard 11971If 11972\family typewriter 11973free_me 11974\family default 11975 is 11976\family typewriter 11977NULL 11978\family default 11979, the function will always allocate memory, even if the string needs no 11980 quoting. 11981 The program then has to free the result: 11982\end_layout 11983 11984\begin_layout LyX-Code 11985 11986\series bold 11987char * 11988\series default 11989s = HX_strquote("<head>", HXQUOTE_HTML, NULL); 11990\begin_inset Newline newline 11991\end_inset 11992 11993printf("%s 11994\backslash 11995n", s); 11996\begin_inset Newline newline 11997\end_inset 11998 11999free(s); 12000\end_layout 12001 12002\begin_layout Standard 12003If 12004\family typewriter 12005free_me 12006\family default 12007 is not 12008\family typewriter 12009NULL 12010\family default 12011 however, the function will put the pointer to the memory area into 12012\family typewriter 12013*free_me 12014\family default 12015, if the string needed quoting. 12016 The program then has to free that after it is done with the quoted result: 12017\end_layout 12018 12019\begin_layout LyX-Code 12020 12021\series bold 12022char * 12023\series default 12024tmp = NULL; 12025\begin_inset Newline newline 12026\end_inset 12027 12028 12029\series bold 12030char * 12031\series default 12032s = HX_strquote("head", HXQUOTE_HTML, &tmp); 12033\begin_inset Newline newline 12034\end_inset 12035 12036printf("%s 12037\backslash 12038n", s); 12039\begin_inset Newline newline 12040\end_inset 12041 12042free(tmp); 12043\end_layout 12044 12045\begin_layout Standard 12046 12047\family typewriter 12048tmp 12049\family default 12050 could be 12051\family typewriter 12052NULL 12053\family default 12054, and since 12055\family typewriter 12056free(NULL) 12057\family default 12058 is not an error, this is perfectly valid. 12059 Furthermore, if 12060\family typewriter 12061*free_me 12062\family default 12063 is not 12064\family typewriter 12065NULL 12066\family default 12067 by the time 12068\family typewriter 12069HX_strquote 12070\family default 12071 is called, the function will free it. 12072 This makes it possible to call 12073\family typewriter 12074HX_strquote 12075\family default 12076 in succession without 12077\family typewriter 12078free 12079\family default 12080s in between: 12081\end_layout 12082 12083\begin_layout LyX-Code 12084 12085\series bold 12086char * 12087\series default 12088tmp = NULL; 12089\begin_inset Newline newline 12090\end_inset 12091 12092printf("%s 12093\backslash 12094n", HX_strquote("<html>", HXQUOTE_HTML, &tmp)); 12095\begin_inset Newline newline 12096\end_inset 12097 12098printf("%s 12099\backslash 12100n", HX_strquote("<head>", HXQUOTE_HTML, &tmp)); 12101\begin_inset Newline newline 12102\end_inset 12103 12104free(tmp); 12105\end_layout 12106 12107\begin_layout Subsection 12108Tokenizing 12109\end_layout 12110 12111\begin_layout LyX-Code 12112 12113\series bold 12114#include 12115\series default 12116 <libHX/string.h> 12117\begin_inset Index idx 12118status open 12119 12120\begin_layout Plain Layout 12121 12122\family typewriter 12123libHX/string.h 12124\end_layout 12125 12126\end_inset 12127 12128 12129\begin_inset Newline newline 12130\end_inset 12131 12132 12133\begin_inset Newline newline 12134\end_inset 12135 12136 12137\series bold 12138char ** 12139\series default 12140HX_split( 12141\series bold 12142const char * 12143\series default 12144s, 12145\series bold 12146const char * 12147\series default 12148delimiters, 12149\begin_inset Newline newline 12150\end_inset 12151 12152 12153\series bold 12154size_t * 12155\series default 12156fields, 12157\series bold 12158int 12159\series default 12160 max); 12161\begin_inset Index idx 12162status open 12163 12164\begin_layout Plain Layout 12165 12166\family typewriter 12167\size normal 12168\color none 12169HX_split 12170\end_layout 12171 12172\end_inset 12173 12174 12175\begin_inset Newline newline 12176\end_inset 12177 12178 12179\series bold 12180char ** 12181\series default 12182HX_split_inplace( 12183\series bold 12184char * 12185\series default 12186s, 12187\series bold 12188const char * 12189\series default 12190delimiters, 12191\series bold 12192int * 12193\series default 12194fields, 12195\series bold 12196int 12197\series default 12198 max); 12199\begin_inset Index idx 12200status open 12201 12202\begin_layout Plain Layout 12203 12204\family typewriter 12205\size normal 12206\color none 12207HX_split_inplace 12208\end_layout 12209 12210\end_inset 12211 12212 12213\begin_inset Newline newline 12214\end_inset 12215 12216 12217\series bold 12218int 12219\series default 12220 HX_split_fixed( 12221\series bold 12222char * 12223\series default 12224s, 12225\series bold 12226const char * 12227\series default 12228delimiters, 12229\series bold 12230int 12231\series default 12232 max, 12233\series bold 12234char ** 12235\series default 12236arr); 12237\begin_inset Index idx 12238status open 12239 12240\begin_layout Plain Layout 12241 12242\family typewriter 12243\size normal 12244\color none 12245HX_split_fixed 12246\end_layout 12247 12248\end_inset 12249 12250 12251\begin_inset Newline newline 12252\end_inset 12253 12254 12255\series bold 12256char * 12257\series default 12258HX_strsep( 12259\series bold 12260char ** 12261\series default 12262sp, 12263\series bold 12264const char * 12265\series default 12266delimiters); 12267\begin_inset Index idx 12268status open 12269 12270\begin_layout Plain Layout 12271 12272\family typewriter 12273\size normal 12274\color none 12275HX_strsep 12276\end_layout 12277 12278\end_inset 12279 12280 12281\begin_inset Newline newline 12282\end_inset 12283 12284 12285\series bold 12286char * 12287\series default 12288HX_strsep2( 12289\series bold 12290char ** 12291\series default 12292sp, 12293\series bold 12294const char * 12295\series default 12296dstr); 12297\begin_inset Index idx 12298status open 12299 12300\begin_layout Plain Layout 12301 12302\family typewriter 12303\size normal 12304\color none 12305HX_strsep2 12306\end_layout 12307 12308\end_inset 12309 12310 12311\end_layout 12312 12313\begin_layout Description 12314 12315\family typewriter 12316HX_split 12317\family default 12318 Split the string 12319\family typewriter 12320s 12321\family default 12322 on any characters from the 12323\begin_inset Quotes eld 12324\end_inset 12325 12326 12327\family typewriter 12328delimiters 12329\family default 12330 12331\begin_inset Quotes erd 12332\end_inset 12333 12334 string. 12335 Both the substrings and the array holding the pointers to these substrings 12336 will be allocated as required; the original string is not modified. 12337 If 12338\family typewriter 12339max 12340\family default 12341 is larger than zero, produces no more than 12342\family typewriter 12343max 12344\family default 12345 fields. 12346 If 12347\family typewriter 12348fields 12349\family default 12350 is not 12351\family typewriter 12352NULL 12353\family default 12354, the number of elements produced will be stored in 12355\family typewriter 12356*fields 12357\family default 12358. 12359 The result is a 12360\family typewriter 12361NULL 12362\family default 12363-terminated array of 12364\family typewriter 12365char 12366\begin_inset space ~ 12367\end_inset 12368 12369* 12370\family default 12371, and the user needs to free it when done with it, using 12372\family typewriter 12373HX_zvecfree 12374\family default 12375 or equivalent. 12376 An empty string (zero-length string) for 12377\family typewriter 12378s 12379\family default 12380 yields a single field. 12381\end_layout 12382 12383\begin_layout Description 12384 12385\family typewriter 12386HX_split_inplace 12387\family default 12388 Split the string 12389\family typewriter 12390s 12391\family default 12392 in-place on any characters from the 12393\begin_inset Quotes eld 12394\end_inset 12395 12396 12397\family typewriter 12398delimiters 12399\family default 12400 12401\begin_inset Quotes erd 12402\end_inset 12403 12404 string. 12405 The array that will be holding the pointers to the substrings will be allocated 12406 and needs to be freed by the user, using 12407\family typewriter 12408free 12409\family default 12410(3). 12411 The 12412\family typewriter 12413fields 12414\family default 12415 and 12416\family typewriter 12417max 12418\family default 12419 arguments work as with 12420\family typewriter 12421HX_split 12422\family default 12423. 12424\end_layout 12425 12426\begin_layout Description 12427 12428\family typewriter 12429HX_split_fixed 12430\family default 12431 Split the string 12432\family typewriter 12433s 12434\family default 12435 in-place on any characters from the 12436\begin_inset Quotes eld 12437\end_inset 12438 12439 12440\family typewriter 12441delimiters 12442\family default 12443 12444\begin_inset Quotes erd 12445\end_inset 12446 12447 string. 12448 The array for the substring pointers must be provided by the user through 12449 the 12450\family typewriter 12451arr 12452\family default 12453 argument. 12454 12455\family typewriter 12456max 12457\family default 12458 must be the number of elements in the array or less. 12459 The array will not be 12460\family typewriter 12461NULL 12462\family default 12463-terminated 12464\begin_inset Foot 12465status open 12466 12467\begin_layout Plain Layout 12468An implementation may however decide to put NULL in the unassigned fields, 12469 but this is implementation and situation-specific. 12470 Do not rely on it. 12471\end_layout 12472 12473\end_inset 12474 12475. 12476 The number of fields produced is returned. 12477\end_layout 12478 12479\begin_layout Description 12480 12481\family typewriter 12482HX_strsep 12483\family default 12484 Extract tokens from a string. 12485\begin_inset Newline newline 12486\end_inset 12487 12488This implementation of 12489\family typewriter 12490strsep 12491\family default 12492 has been added since the function is non-standard (according to the manpage, 12493 conforms to BSD4.4 only) and may not be available on every operating system. 12494\begin_inset Newline newline 12495\end_inset 12496 12497This function extracts tokens, separated by one of the characters in 12498\family typewriter 12499delimiters 12500\family default 12501. 12502 The string is modified in-place and thus must be writable. 12503 The delimiters in the string are then overwritten with 12504\family typewriter 12505' 12506\backslash 125070' 12508\family default 12509, 12510\family typewriter 12511*sp 12512\family default 12513 is advanced to the character after the delimiter, and the original pointer 12514 is returned. 12515 After the final token, 12516\family typewriter 12517strsep 12518\family default 12519 will return 12520\family typewriter 12521NULL 12522\family default 12523. 12524\end_layout 12525 12526\begin_layout Description 12527 12528\family typewriter 12529HX_strsep2 12530\family default 12531 Like 12532\family typewriter 12533HX_strsep 12534\family default 12535, but 12536\family typewriter 12537dstr 12538\family default 12539 is not an array of delimiting characters, but an entire substring that 12540 acts as a delimiter. 12541\end_layout 12542 12543\begin_layout Subsection 12544Size-bounded string ops 12545\end_layout 12546 12547\begin_layout LyX-Code 12548 12549\series bold 12550#include 12551\series default 12552 <libHX/string.h> 12553\begin_inset Index idx 12554status open 12555 12556\begin_layout Plain Layout 12557libHX/string.h 12558\end_layout 12559 12560\end_inset 12561 12562 12563\begin_inset Newline newline 12564\end_inset 12565 12566 12567\begin_inset Newline newline 12568\end_inset 12569 12570 12571\series bold 12572char * 12573\series default 12574HX_strlcat( 12575\series bold 12576char * 12577\series default 12578dest, 12579\series bold 12580const char * 12581\series default 12582src, 12583\series bold 12584size_t 12585\series default 12586 length); 12587\begin_inset Index idx 12588status open 12589 12590\begin_layout Plain Layout 12591 12592\family typewriter 12593\size normal 12594\color none 12595HX_strlcat 12596\end_layout 12597 12598\end_inset 12599 12600 12601\begin_inset Newline newline 12602\end_inset 12603 12604 12605\series bold 12606char * 12607\series default 12608HX_strlcpy( 12609\series bold 12610char * 12611\series default 12612dest, 12613\series bold 12614const char * 12615\series default 12616src, 12617\series bold 12618size_t 12619\series default 12620 length); 12621\begin_inset Index idx 12622status open 12623 12624\begin_layout Plain Layout 12625 12626\family typewriter 12627\size normal 12628\color none 12629HX_strlcpy 12630\end_layout 12631 12632\end_inset 12633 12634 12635\begin_inset Newline newline 12636\end_inset 12637 12638 12639\series bold 12640char * 12641\series default 12642HX_strlncat( 12643\series bold 12644char * 12645\series default 12646dest, 12647\series bold 12648const char * 12649\series default 12650src, 12651\series bold 12652size_t 12653\series default 12654 dlen, 12655\series bold 12656size_t 12657\series default 12658 slen); 12659\begin_inset Index idx 12660status open 12661 12662\begin_layout Plain Layout 12663 12664\family typewriter 12665\size normal 12666\color none 12667HX_strlncat 12668\end_layout 12669 12670\end_inset 12671 12672 12673\begin_inset Newline newline 12674\end_inset 12675 12676 12677\series bold 12678size_t 12679\series default 12680 HX_strnlen( 12681\series bold 12682const char * 12683\series default 12684src, 12685\series bold 12686size_t 12687\series default 12688 max); 12689\begin_inset Index idx 12690status open 12691 12692\begin_layout Plain Layout 12693HX_strnlen 12694\end_layout 12695 12696\end_inset 12697 12698 12699\end_layout 12700 12701\begin_layout Standard 12702 12703\family typewriter 12704HX_strlcat 12705\family default 12706 and 12707\family typewriter 12708HX_strlcpy 12709\family default 12710 provide implementations of the BSD-originating 12711\family typewriter 12712strlcat 12713\family default 12714(3) 12715\begin_inset Index idx 12716status open 12717 12718\begin_layout Plain Layout 12719 12720\family typewriter 12721strlcat 12722\end_layout 12723 12724\end_inset 12725 12726 and 12727\family typewriter 12728strlcpy 12729\family default 12730(3) 12731\begin_inset Index idx 12732status open 12733 12734\begin_layout Plain Layout 12735 12736\family typewriter 12737strlcpy 12738\end_layout 12739 12740\end_inset 12741 12742. 12743 12744\family typewriter 12745strlcat 12746\family default 12747 and 12748\family typewriter 12749strlcpy 12750\family default 12751 are less error-prone variants for 12752\family typewriter 12753strncat 12754\family default 12755 and 12756\family typewriter 12757strncpy 12758\family default 12759 as they always take the length of the entire buffer specified by 12760\family typewriter 12761dest 12762\family default 12763, instead of just the length that is to be written. 12764 The functions guarantee that the buffer is 12765\family typewriter 12766' 12767\backslash 127680' 12769\family default 12770-terminated. 12771\end_layout 12772 12773\begin_layout Standard 12774 12775\family typewriter 12776HX_strnlen 12777\family default 12778 will return the length of the input string or the upper bound given by 12779 12780\family typewriter 12781max 12782\family default 12783, whichever is less. 12784 It will not attempt to access more than this many bytes in the input buffer. 12785\end_layout 12786 12787\begin_layout Subsection 12788Allocation-related 12789\end_layout 12790 12791\begin_layout LyX-Code 12792 12793\series bold 12794#include 12795\series default 12796 <libHX/string.h> 12797\begin_inset Index idx 12798status open 12799 12800\begin_layout Plain Layout 12801 12802\family typewriter 12803libHX/string.h 12804\end_layout 12805 12806\end_inset 12807 12808 12809\begin_inset Newline newline 12810\end_inset 12811 12812 12813\begin_inset Newline newline 12814\end_inset 12815 12816 12817\series bold 12818void * 12819\series default 12820HX_memdup( 12821\series bold 12822const void * 12823\series default 12824ptr, 12825\series bold 12826size_t 12827\series default 12828 length); 12829\begin_inset Index idx 12830status open 12831 12832\begin_layout Plain Layout 12833 12834\family typewriter 12835\size normal 12836\color none 12837HX_memdup 12838\end_layout 12839 12840\end_inset 12841 12842 12843\begin_inset Newline newline 12844\end_inset 12845 12846 12847\series bold 12848char * 12849\series default 12850HX_strdup( 12851\series bold 12852const char * 12853\series default 12854str); 12855\begin_inset Index idx 12856status open 12857 12858\begin_layout Plain Layout 12859 12860\family typewriter 12861\size normal 12862\color none 12863HX_strdup 12864\end_layout 12865 12866\end_inset 12867 12868 12869\begin_inset Newline newline 12870\end_inset 12871 12872 12873\series bold 12874char * 12875\series default 12876HX_strndup( 12877\series bold 12878const char * 12879\series default 12880str, 12881\series bold 12882size_t 12883\series default 12884 max); 12885\begin_inset Index idx 12886status open 12887 12888\begin_layout Plain Layout 12889HX_strndup 12890\end_layout 12891 12892\end_inset 12893 12894 12895\begin_inset Newline newline 12896\end_inset 12897 12898 12899\series bold 12900 12901\begin_inset Note Greyedout 12902status open 12903 12904\begin_layout Plain Layout 12905 12906\family typewriter 12907\series bold 12908char * 12909\series default 12910HX_strclone( 12911\series bold 12912char ** 12913\series default 12914pa, 12915\series bold 12916const char * 12917\series default 12918pb); 12919\family default 12920 12921\begin_inset Index idx 12922status open 12923 12924\begin_layout Plain Layout 12925 12926\family typewriter 12927\size normal 12928\color none 12929HX_strclone 12930\end_layout 12931 12932\end_inset 12933 12934 12935\end_layout 12936 12937\end_inset 12938 12939 12940\series default 12941 12942\begin_inset Newline newline 12943\end_inset 12944 12945 12946\series bold 12947 12948\begin_inset Newline newline 12949\end_inset 12950 12951#ifdef 12952\series default 12953 __cplusplus 12954\begin_inset Newline newline 12955\end_inset 12956 12957 12958\series bold 12959template<typename type> type 12960\series default 12961 HX_memdup( 12962\series bold 12963const void * 12964\series default 12965ptr, 12966\series bold 12967size_t 12968\series default 12969 length); 12970\begin_inset Newline newline 12971\end_inset 12972 12973 12974\series bold 12975#endif 12976\end_layout 12977 12978\begin_layout Description 12979 12980\family typewriter 12981HX_memdup 12982\family default 12983 Duplicates 12984\family typewriter 12985length 12986\family default 12987 bytes from the memory area pointed to by 12988\family typewriter 12989ptr 12990\family default 12991 and returns a pointer to the new memory block. 12992 12993\family typewriter 12994ptr 12995\family default 12996 may not be 12997\family typewriter 12998NULL 12999\family default 13000. 13001\end_layout 13002 13003\begin_layout Description 13004 13005\family typewriter 13006HX_strdup 13007\family default 13008 Duplicates the string. 13009 The function is equivalent to 13010\family typewriter 13011strdup 13012\family default 13013, but the latter may not be available on all platforms. 13014 13015\family typewriter 13016str 13017\family default 13018 may be 13019\family typewriter 13020NULL 13021\family default 13022, in which case 13023\family typewriter 13024NULL 13025\family default 13026 is also returned. 13027\end_layout 13028 13029\begin_layout Description 13030 13031\family typewriter 13032HX_strndup 13033\family default 13034 Duplicates the input string, but copies at most 13035\family typewriter 13036max 13037\family default 13038 characters. 13039 (The resulting string will be NUL-terminated of course.) 13040\family typewriter 13041str 13042\family default 13043 may not be 13044\family typewriter 13045NULL 13046\family default 13047. 13048\end_layout 13049 13050\begin_layout Description 13051 13052\family typewriter 13053HX_strclone 13054\family default 13055 Copies the string pointed to by 13056\family typewriter 13057pb 13058\family default 13059 into 13060\family typewriter 13061*pa 13062\family default 13063. 13064 If 13065\family typewriter 13066*pa 13067\family default 13068 was not 13069\family typewriter 13070NULL 13071\family default 13072 by the time 13073\family typewriter 13074HX_strclone 13075\family default 13076 was called, the string is freed before a new one is allocated. 13077 The function returns 13078\family typewriter 13079NULL 13080\family default 13081 and sets 13082\family typewriter 13083errno 13084\family default 13085 to 13086\family typewriter 13087EINVAL 13088\family default 13089 if 13090\family typewriter 13091pb 13092\family default 13093 is 13094\family typewriter 13095NULL 13096\family default 13097 (this way it can be freed), or, if 13098\family typewriter 13099malloc 13100\family default 13101 fails, returns 13102\family typewriter 13103NULL 13104\family default 13105 and leaves 13106\family typewriter 13107errno 13108\family default 13109 at what 13110\family typewriter 13111malloc 13112\family default 13113 set it to. 13114\begin_inset Newline newline 13115\end_inset 13116 13117The use of this function is deprecated, albeit no replacement is proposed. 13118\end_layout 13119 13120\begin_layout Subsection 13121Examples 13122\end_layout 13123 13124\begin_layout Subsubsection 13125Using HX_split_fixed 13126\begin_inset CommandInset label 13127LatexCommand label 13128name "subsec:string-ex-HX_split_fixed" 13129 13130\end_inset 13131 13132 13133\end_layout 13134 13135\begin_layout Standard 13136 13137\family typewriter 13138HX_split_fixed 13139\family default 13140 is often used just with scoped automatic-storage variables and where the 13141 field count of interest is fixed, as the example for parsing 13142\family typewriter 13143/etc/passwd 13144\family default 13145 shows: 13146\end_layout 13147 13148\begin_layout LyX-Code 13149 13150\series bold 13151#include 13152\series default 13153 <stdio.h> 13154\begin_inset Newline newline 13155\end_inset 13156 13157 13158\series bold 13159#include 13160\series default 13161 <libHX/string.h> 13162\begin_inset Newline newline 13163\end_inset 13164 13165 13166\begin_inset Newline newline 13167\end_inset 13168 13169 13170\series bold 13171char * 13172\series default 13173field[8]; 13174\begin_inset Newline newline 13175\end_inset 13176 13177hxmc_t 13178\series bold 13179* 13180\series default 13181line = NULL; 13182\begin_inset Newline newline 13183\end_inset 13184 13185 13186\begin_inset Newline newline 13187\end_inset 13188 13189 13190\series bold 13191while 13192\series default 13193 (HX_getl(&line, fp) != NULL) { 13194\begin_inset Newline newline 13195\end_inset 13196 13197 13198\series bold 13199if 13200\series default 13201 (HX_split_fixed(line, ":", ARRAY_SIZE(field), field) < 7) { 13202\begin_inset Newline newline 13203\end_inset 13204 13205 fprintf(stderr, "That does not look like a valid line. 13206\backslash 13207n"); 13208\begin_inset Newline newline 13209\end_inset 13210 13211 13212\series bold 13213continue 13214\series default 13215; 13216\begin_inset Newline newline 13217\end_inset 13218 13219 } 13220\begin_inset Newline newline 13221\end_inset 13222 13223 printf("Username: %s 13224\backslash 13225n", field[0]); 13226\begin_inset Newline newline 13227\end_inset 13228 13229} 13230\end_layout 13231 13232\begin_layout Subsubsection 13233Using HX_split_inplace 13234\end_layout 13235 13236\begin_layout Standard 13237Where the number of fields is not previously known and/or estimatable, but 13238 the string can be modified in place, one uses 13239\family typewriter 13240HX_split_inplace 13241\family default 13242 as follows: 13243\end_layout 13244 13245\begin_layout LyX-Code 13246 13247\series bold 13248#include 13249\series default 13250 <errno.h> 13251\begin_inset Newline newline 13252\end_inset 13253 13254 13255\series bold 13256#include 13257\series default 13258 <stdio.h> 13259\begin_inset Newline newline 13260\end_inset 13261 13262 13263\series bold 13264#include 13265\series default 13266 <libHX/string.h> 13267\begin_inset Newline newline 13268\end_inset 13269 13270 13271\begin_inset Newline newline 13272\end_inset 13273 13274 13275\series bold 13276while 13277\series default 13278 (HX_getl(&line, fp) != NULL) { 13279\begin_inset Newline newline 13280\end_inset 13281 13282 13283\series bold 13284char ** 13285\series default 13286field = HX_split_inplace(line, ":", NULL, 0); 13287\begin_inset Newline newline 13288\end_inset 13289 13290 13291\series bold 13292if 13293\series default 13294 (field == NULL) { 13295\begin_inset Newline newline 13296\end_inset 13297 13298 fprintf(stderr, "Badness! %s 13299\backslash 13300n", strerror(errno)); 13301\begin_inset Newline newline 13302\end_inset 13303 13304 13305\series bold 13306break 13307\series default 13308; 13309\begin_inset Newline newline 13310\end_inset 13311 13312 } 13313\begin_inset Newline newline 13314\end_inset 13315 13316 printf("Username: %s 13317\backslash 13318n", field[0]); 13319\begin_inset Newline newline 13320\end_inset 13321 13322 free(field); 13323\begin_inset Newline newline 13324\end_inset 13325 13326} 13327\end_layout 13328 13329\begin_layout Subsubsection 13330Using HX_split 13331\end_layout 13332 13333\begin_layout Standard 13334Where the string is not modifiable in-place, one has to resort to using 13335 the full-fledged 13336\family typewriter 13337HX_split 13338\family default 13339 that allocates space for each substring. 13340\end_layout 13341 13342\begin_layout LyX-Code 13343 13344\series bold 13345#include 13346\series default 13347 <errno.h> 13348\begin_inset Newline newline 13349\end_inset 13350 13351 13352\series bold 13353#include 13354\series default 13355 <stdio.h> 13356\begin_inset Newline newline 13357\end_inset 13358 13359 13360\series bold 13361#include 13362\series default 13363 <libHX/string.h> 13364\begin_inset Newline newline 13365\end_inset 13366 13367 13368\begin_inset Newline newline 13369\end_inset 13370 13371 13372\series bold 13373while 13374\series default 13375 (HX_getl(&line, fp) != NULL) { 13376\begin_inset Newline newline 13377\end_inset 13378 13379 13380\series bold 13381char ** 13382\series default 13383field = HX_split(line, ":", NULL, 0); 13384\begin_inset Newline newline 13385\end_inset 13386 13387 13388\series bold 13389if 13390\series default 13391 (field == NULL) { 13392\begin_inset Newline newline 13393\end_inset 13394 13395 fprintf(stderr, "Badness. 13396 %s 13397\backslash 13398n", strerror(errno)); 13399\begin_inset Newline newline 13400\end_inset 13401 13402 break; 13403\begin_inset Newline newline 13404\end_inset 13405 13406 } 13407\begin_inset Newline newline 13408\end_inset 13409 13410 printf("Username: %s 13411\backslash 13412n", field[0]); 13413\begin_inset Newline newline 13414\end_inset 13415 13416 13417\series bold 13418/* 13419\family roman 13420\series default 13421\shape italic 13422Suppose 13423\begin_inset Quotes eld 13424\end_inset 13425 13426callme 13427\begin_inset Quotes erd 13428\end_inset 13429 13430 needs the original string 13431\family default 13432\series bold 13433\shape default 13434 */ 13435\series default 13436 13437\begin_inset Newline newline 13438\end_inset 13439 13440 callme(line); 13441\begin_inset Newline newline 13442\end_inset 13443 13444 HX_zvecfree(field); 13445\begin_inset Newline newline 13446\end_inset 13447 13448} 13449\end_layout 13450 13451\begin_layout Subsubsection 13452Using HX_strsep 13453\end_layout 13454 13455\begin_layout Standard 13456 13457\family typewriter 13458HX_strsep 13459\family default 13460 provides for thread- and reentrant-safe tokenizing a string where strtok 13461 from the C standard would otherwise fail. 13462\end_layout 13463 13464\begin_layout LyX-Code 13465 13466\series bold 13467#include 13468\series default 13469 <stdio.h> 13470\begin_inset Newline newline 13471\end_inset 13472 13473 13474\series bold 13475#include 13476\series default 13477 <libHX/string.h> 13478\begin_inset Newline newline 13479\end_inset 13480 13481 13482\begin_inset Newline newline 13483\end_inset 13484 13485 13486\series bold 13487char 13488\series default 13489 line 13490\series bold 13491[] 13492\series default 13493 = "root:x:0:0:root:/root:/bin/bash"; 13494\begin_inset Newline newline 13495\end_inset 13496 13497 13498\series bold 13499char * 13500\series default 13501wp, 13502\series bold 13503* 13504\series default 13505p; 13506\begin_inset Newline newline 13507\end_inset 13508 13509 13510\begin_inset Newline newline 13511\end_inset 13512 13513wp = line; 13514\begin_inset Newline newline 13515\end_inset 13516 13517 13518\series bold 13519while 13520\series default 13521 ((p = HX_strsep(&wp, ":")) != NULL) 13522\begin_inset Newline newline 13523\end_inset 13524 13525 printf("%s 13526\backslash 13527n", p) 13528\end_layout 13529 13530\begin_layout Standard 13531\begin_inset Newpage clearpage 13532\end_inset 13533 13534 13535\end_layout 13536 13537\begin_layout Section 13538Memory containers 13539\begin_inset CommandInset label 13540LatexCommand label 13541name "sec:mc" 13542 13543\end_inset 13544 13545 13546\end_layout 13547 13548\begin_layout Standard 13549The HXmc series of functions provide scripting-like semantics for strings, 13550 especially automatically resizing the buffer on demand. 13551 They can also be used to store a binary block of data together with its 13552 length. 13553 (Hence the name: mc = memory container.) 13554\end_layout 13555 13556\begin_layout Standard 13557The benefit of using the HXmc functions is that one does not have to meticulousl 13558y watch buffer and string sizes anymore. 13559\end_layout 13560 13561\begin_layout Standard 13562\begin_inset Float figure 13563placement H 13564wide false 13565sideways false 13566status open 13567 13568\begin_layout Paragraph 13569/* Step 13570\begin_inset space ~ 13571\end_inset 13572 135731 */ 13574\end_layout 13575 13576\begin_layout LyX-Code 13577 13578\series bold 13579char 13580\series default 13581 buf 13582\series bold 13583[ 13584\family roman 13585\series default 13586\shape italic 13587whatever was believed to be long enough 13588\family default 13589\series bold 13590\shape default 13591] 13592\series default 13593 = "helloworld"; 13594\end_layout 13595 13596\begin_layout LyX-Code 13597 13598\series bold 13599if 13600\series default 13601 (strlen(buf) + strlen(".txt") < 13602\series bold 13603sizeof 13604\series default 13605(buf)) 13606\begin_inset Newline newline 13607\end_inset 13608 13609 strcat(s, ".txt"); 13610\end_layout 13611 13612\begin_layout Paragraph 13613/* Step 13614\begin_inset space ~ 13615\end_inset 13616 136172 */ 13618\end_layout 13619 13620\begin_layout LyX-Code 13621 13622\series bold 13623char 13624\series default 13625 buf 13626\series bold 13627[ 13628\family roman 13629\series default 13630\shape italic 13631long_enough 13632\family default 13633\series bold 13634\shape default 13635] 13636\series default 13637 = "helloworld"; 13638\end_layout 13639 13640\begin_layout LyX-Code 13641strlcat(s, ".txt", 13642\series bold 13643sizeof 13644\series default 13645(buf)); 13646\end_layout 13647 13648\begin_layout Paragraph 13649/* Step 13650\begin_inset space ~ 13651\end_inset 13652 136533 */ 13654\end_layout 13655 13656\begin_layout LyX-Code 13657hxmc_t 13658\series bold 13659* 13660\series default 13661buf = HXmc_strinit("helloworld"); 13662\begin_inset Newline newline 13663\end_inset 13664 13665HXmc_strcat(&s, ".txt"); 13666\end_layout 13667 13668\begin_layout Plain Layout 13669\begin_inset Caption Standard 13670 13671\begin_layout Plain Layout 13672Improvement of string safety over time 13673\end_layout 13674 13675\end_inset 13676 13677 13678\end_layout 13679 13680\end_inset 13681 13682 13683\end_layout 13684 13685\begin_layout Standard 13686This makes it quite similar to the string operations (and append seems to 13687 be the most commonly used one to me) supported in scripting languages that 13688 also do without a size argument. 13689 The essential part of such memory containers is that their internal (hidden) 13690 metadata structure contains the length of the memory block in the container. 13691 For binary data this may be the norm, but for C-style strings, the stored 13692 and auto-updated length field serves as an accelerator cache. 13693 For more details, see 13694\family typewriter 13695HXmc_length 13696\family default 13697. 13698\end_layout 13699 13700\begin_layout Standard 13701Of course, the automatic management of memory comes with a bit of overhead 13702 as the string expands beyond its preallocated region. 13703 Such may be mitigated by doing explicit (re)sizing. 13704\end_layout 13705 13706\begin_layout Subsection 13707Structural overview 13708\end_layout 13709 13710\begin_layout Standard 13711HXmc functions do not actually return a pointer to the memory container 13712 (e. 13713\begin_inset space \thinspace{} 13714\end_inset 13715 13716g. 13717\begin_inset space \space{} 13718\end_inset 13719 13720 13721\family typewriter 13722struct 13723\family default 13724) itself, but a pointer to the data block. 13725 Conversely, input parameters to HXmc functions will be the data block pointer. 13726 It is of type 13727\family typewriter 13728hxmc_t 13729\begin_inset space ~ 13730\end_inset 13731 13732* 13733\family default 13734, which is typedef'ed to 13735\family typewriter 13736char 13737\begin_inset space ~ 13738\end_inset 13739 13740* 13741\family default 13742 and inherits all properties and privileges of 13743\family typewriter 13744char 13745\begin_inset space ~ 13746\end_inset 13747 13748* 13749\family default 13750. 13751 Pointer arithmetic is thus supported. 13752 It also means you can just pass it to functions that take a 13753\family typewriter 13754char 13755\begin_inset space ~ 13756\end_inset 13757 13758* 13759\family default 13760 without having to do a member access like 13761\family typewriter 13762s.c_str 13763\family default 13764. 13765 The drawback is that many functions operating on the memory container need 13766 a 13767\family typewriter 13768hxmc_t 13769\begin_inset space ~ 13770\end_inset 13771 13772** 13773\family default 13774 (a level-two indirection), because not only does the memory block move, 13775 but also the memory container itself. 13776 This is due to the implementation of the container metadata which immediately 13777 and always precedes the writable memory block. 13778\end_layout 13779 13780\begin_layout Standard 13781HXmc ensures that the data block is terminated by a NUL ( 13782\family typewriter 13783' 13784\backslash 137850' 13786\family default 13787) byte (unless you trash it), so you do not have to, and of course, to be 13788 on the safe side. 13789 But, the automatic NUL byte is not part of the region allocated by the 13790 user. 13791 That is, when one uses the classic approach with 13792\family typewriter 13793malloc(4096) 13794\family default 13795, the user will have control of 4096 bytes and has to stuff the NUL byte 13796 in there somehow on his own; for strings this means the maximum string 13797 length is 4095. 13798 Requesting space for a 4096-byte sized HXmc container gives you the possibility 13799 to use all 4096 bytes for the string, because HXmc provides a NUL byte. 13800\end_layout 13801 13802\begin_layout Standard 13803By the way, 13804\family typewriter 13805hxmc_t 13806\family default 13807 is the 13808\shape italic 13809only 13810\shape default 13811 typedef in this entire library, to distinguish it from regular 13812\family typewriter 13813char 13814\begin_inset space ~ 13815\end_inset 13816 13817* 13818\family default 13819 that does not have a backing memory cointainer. 13820\end_layout 13821 13822\begin_layout Subsection 13823Constructors, destructors 13824\end_layout 13825 13826\begin_layout LyX-Code 13827 13828\series bold 13829#include 13830\series default 13831 <libHX/string.h> 13832\begin_inset Index idx 13833status open 13834 13835\begin_layout Plain Layout 13836 13837\family typewriter 13838libHX/string.h 13839\end_layout 13840 13841\end_inset 13842 13843 13844\begin_inset Newline newline 13845\end_inset 13846 13847 13848\begin_inset Newline newline 13849\end_inset 13850 13851hxmc_t 13852\series bold 13853* 13854\series default 13855HXmc_strinit( 13856\series bold 13857const char * 13858\series default 13859s); 13860\begin_inset Index idx 13861status open 13862 13863\begin_layout Plain Layout 13864 13865\family typewriter 13866HXmc_strinit 13867\end_layout 13868 13869\end_inset 13870 13871 13872\begin_inset Newline newline 13873\end_inset 13874 13875hxmc_t 13876\series bold 13877* 13878\series default 13879HXmc_meminit( 13880\series bold 13881const void * 13882\series default 13883ptr, 13884\series bold 13885size_t 13886\series default 13887 size); 13888\begin_inset Index idx 13889status open 13890 13891\begin_layout Plain Layout 13892 13893\family typewriter 13894HXmc_meminit 13895\end_layout 13896 13897\end_inset 13898 13899 13900\end_layout 13901 13902\begin_layout Description 13903 13904\family typewriter 13905HXmc_strinit 13906\family default 13907 Creates a new hxmc_t object from the supplied string and returns it. 13908\end_layout 13909 13910\begin_layout Description 13911 13912\family typewriter 13913HXmc_meminit 13914\family default 13915 Creates a new hxmc_t object from the supplied memory buffer of the given 13916 size and returns it. 13917 13918\family typewriter 13919HXmc_meminit(NULL, len) 13920\family default 13921 may be used to obtain an empty container with a preallocated region of 13922 13923\family typewriter 13924len 13925\family default 13926 bytes (zero is accepted for 13927\family typewriter 13928len 13929\family default 13930). 13931\end_layout 13932 13933\begin_layout LyX-Code 13934 13935\series bold 13936void 13937\series default 13938 HXmc_free(hxmc_t 13939\series bold 13940* 13941\series default 13942s); 13943\begin_inset Index idx 13944status open 13945 13946\begin_layout Plain Layout 13947 13948\family typewriter 13949HXmc_free 13950\end_layout 13951 13952\end_inset 13953 13954 13955\begin_inset Newline newline 13956\end_inset 13957 13958 13959\series bold 13960void 13961\series default 13962 HXmc_zvecfree(hxmc_t 13963\series bold 13964** 13965\series default 13966s); 13967\begin_inset Index idx 13968status open 13969 13970\begin_layout Plain Layout 13971 13972\family typewriter 13973HXmc_zvecfree 13974\end_layout 13975 13976\end_inset 13977 13978 13979\end_layout 13980 13981\begin_layout Description 13982 13983\family typewriter 13984HXmc_free 13985\family default 13986 Frees the hxmc object. 13987\end_layout 13988 13989\begin_layout Description 13990 13991\family typewriter 13992HXmc_zvecfree 13993\family default 13994 Frees all hxmc objects in the NULL-terminated array, and finally frees 13995 the array itself, similar to 13996\family typewriter 13997HX_zvecfree 13998\family default 13999. 14000\end_layout 14001 14002\begin_layout Subsection 14003Data manipulation 14004\end_layout 14005 14006\begin_layout Subsubsection 14007Binary-based 14008\end_layout 14009 14010\begin_layout LyX-Code 14011hxmc_t 14012\series bold 14013* 14014\series default 14015HXmc_trunc(hxmc_t 14016\series bold 14017** 14018\series default 14019mc, 14020\series bold 14021size_t 14022\series default 14023 len); 14024\begin_inset Index idx 14025status open 14026 14027\begin_layout Plain Layout 14028 14029\family typewriter 14030\size normal 14031\color none 14032HXmc_trunc 14033\end_layout 14034 14035\end_inset 14036 14037 14038\begin_inset Newline newline 14039\end_inset 14040 14041hxmc_t 14042\series bold 14043* 14044\series default 14045HXmc_setlen(hxmc_t 14046\series bold 14047** 14048\series default 14049mc, 14050\series bold 14051size_t 14052\series default 14053 len); 14054\begin_inset Index idx 14055status open 14056 14057\begin_layout Plain Layout 14058 14059\family typewriter 14060\size normal 14061\color none 14062HXmc_setlen 14063\end_layout 14064 14065\end_inset 14066 14067 14068\begin_inset Newline newline 14069\end_inset 14070 14071hxmc_t 14072\series bold 14073* 14074\series default 14075HXmc_memcpy(hxmc_t 14076\series bold 14077** 14078\series default 14079mc, 14080\series bold 14081const void * 14082\series default 14083ptr, 14084\series bold 14085size_t 14086\series default 14087 len); 14088\begin_inset Index idx 14089status open 14090 14091\begin_layout Plain Layout 14092 14093\family typewriter 14094\size normal 14095\color none 14096HXmc_memcpy 14097\end_layout 14098 14099\end_inset 14100 14101 14102\begin_inset Newline newline 14103\end_inset 14104 14105hxmc_t 14106\series bold 14107* 14108\series default 14109HXmc_memcat(hxmc_t 14110\series bold 14111** 14112\series default 14113mc, 14114\series bold 14115const void * 14116\series default 14117ptr, 14118\series bold 14119size_t 14120\series default 14121 len); 14122\begin_inset Index idx 14123status open 14124 14125\begin_layout Plain Layout 14126 14127\family typewriter 14128\size normal 14129\color none 14130HXmc_memcat 14131\end_layout 14132 14133\end_inset 14134 14135 14136\begin_inset Newline newline 14137\end_inset 14138 14139hxmc_t 14140\series bold 14141* 14142\series default 14143HXmc_mempcat(hxmc_t 14144\series bold 14145** 14146\series default 14147mc, 14148\series bold 14149const void * 14150\series default 14151ptr, 14152\series bold 14153size_t 14154\series default 14155 len); 14156\begin_inset Index idx 14157status open 14158 14159\begin_layout Plain Layout 14160 14161\family typewriter 14162\size normal 14163\color none 14164HXmc_mempcat 14165\end_layout 14166 14167\end_inset 14168 14169 14170\begin_inset Newline newline 14171\end_inset 14172 14173hxmc_t 14174\series bold 14175* 14176\series default 14177HXmc_memins(hxmc_t 14178\series bold 14179** 14180\series default 14181mc, 14182\series bold 14183size_t 14184\series default 14185 pos, 14186\series bold 14187const void * 14188\series default 14189ptr, 14190\series bold 14191size_t 14192\series default 14193 len); 14194\begin_inset Index idx 14195status open 14196 14197\begin_layout Plain Layout 14198 14199\family typewriter 14200HX_memins 14201\end_layout 14202 14203\end_inset 14204 14205 14206\begin_inset Newline newline 14207\end_inset 14208 14209hxmc_t 14210\series bold 14211* 14212\series default 14213HXmc_memdel(hxmc_t 14214\series bold 14215** 14216\series default 14217mc, 14218\series bold 14219size_t 14220\series default 14221 pos, 14222\series bold 14223size_t 14224\series default 14225 len); 14226\begin_inset Index idx 14227status open 14228 14229\begin_layout Plain Layout 14230 14231\family typewriter 14232HX_memdel 14233\end_layout 14234 14235\end_inset 14236 14237 14238\end_layout 14239 14240\begin_layout Standard 14241When 14242\family typewriter 14243ptr 14244\family default 14245 is 14246\family typewriter 14247NULL 14248\family default 14249, each call behaves as if 14250\family typewriter 14251len 14252\family default 14253 would be zero. 14254 Specifically, no undefined behavior will result of the use of 14255\family typewriter 14256NULL 14257\family default 14258. 14259\end_layout 14260 14261\begin_layout Description 14262 14263\family typewriter 14264HXmc_trunc 14265\family default 14266 Truncates the container's data to 14267\family typewriter 14268len 14269\family default 14270 size. 14271 If 14272\family typewriter 14273len 14274\family default 14275 is greater than the current data size of the container, the length is in 14276 fact 14277\shape italic 14278not 14279\shape default 14280 updated, but a reallocation may be triggered, which can be used to do explicit 14281 allocation. 14282\end_layout 14283 14284\begin_layout Description 14285 14286\family typewriter 14287HXmc_setlen 14288\family default 14289 Set the data length, doing a reallocation of the memory container if needed. 14290 The newly available bytes are uninitialized. 14291 Make use of this function when letting 3rd party functions write to the 14292 buffer, but it should not be used with 14293\family typewriter 14294HXmc_str* 14295\family default 14296(), 14297\end_layout 14298 14299\begin_layout Description 14300 14301\family typewriter 14302HXmc_memcpy 14303\family default 14304 Truncates the container's data and copies 14305\family typewriter 14306len 14307\family default 14308 bytes from the memory area pointed to by 14309\family typewriter 14310ptr 14311\family default 14312 to the container. 14313\end_layout 14314 14315\begin_layout Description 14316 14317\family typewriter 14318HXmc_memcat 14319\family default 14320 Concatenates (appends) 14321\family typewriter 14322len 14323\family default 14324 bytes from the memory area pointed to by 14325\family typewriter 14326ptr 14327\family default 14328 to the container's data. 14329\end_layout 14330 14331\begin_layout Description 14332 14333\family typewriter 14334HXmc_mempcat 14335\family default 14336 Prepends 14337\family typewriter 14338len 14339\family default 14340 bytes from the memory area pointed to by 14341\family typewriter 14342ptr 14343\family default 14344 to the container's data. 14345\end_layout 14346 14347\begin_layout Description 14348 14349\family typewriter 14350HXmc_memins 14351\family default 14352 Prepends 14353\family typewriter 14354len 14355\family default 14356 bytes from the memory area pointed to by 14357\family typewriter 14358ptr 14359\family default 14360 to the 14361\family typewriter 14362pos 14363\family default 14364'th byte of the container's data. 14365\end_layout 14366 14367\begin_layout Description 14368 14369\family typewriter 14370HXmc_memdel 14371\family default 14372 Deletes 14373\family typewriter 14374len 14375\family default 14376 bytes from the container beginning at position 14377\family typewriter 14378pos 14379\family default 14380. 14381\end_layout 14382 14383\begin_layout Standard 14384In case of a memory allocation failure, the 14385\family typewriter 14386HXmc_* 14387\family default 14388 functions will return 14389\family typewriter 14390NULL 14391\family default 14392. 14393\end_layout 14394 14395\begin_layout Subsubsection 14396String-based 14397\end_layout 14398 14399\begin_layout Standard 14400The string-based functions correspond to their binary-based equivalents 14401 with a 14402\family typewriter 14403len 14404\family default 14405 argument of 14406\family typewriter 14407strlen(s) 14408\family default 14409. 14410\end_layout 14411 14412\begin_layout LyX-Code 14413hxmc_t 14414\series bold 14415* 14416\series default 14417HXmc_strcpy(hxmc_t 14418\series bold 14419** 14420\series default 14421mc, 14422\series bold 14423const char * 14424\series default 14425s); 14426\begin_inset Index idx 14427status open 14428 14429\begin_layout Plain Layout 14430 14431\family typewriter 14432\size normal 14433\color none 14434HXmc_strcpy 14435\end_layout 14436 14437\end_inset 14438 14439 14440\begin_inset Newline newline 14441\end_inset 14442 14443hxmc_t 14444\series bold 14445* 14446\series default 14447HXmc_strcat(hxmc_t 14448\series bold 14449** 14450\series default 14451mc, 14452\series bold 14453const char * 14454\series default 14455s); 14456\begin_inset Index idx 14457status open 14458 14459\begin_layout Plain Layout 14460 14461\family typewriter 14462\size normal 14463\color none 14464HXmc_strcat 14465\end_layout 14466 14467\end_inset 14468 14469 14470\begin_inset Newline newline 14471\end_inset 14472 14473hxmc_t 14474\series bold 14475* 14476\series default 14477HXmc_strpcat(hxmc_t 14478\series bold 14479** 14480\series default 14481mc, 14482\series bold 14483const char * 14484\series default 14485s); 14486\begin_inset Index idx 14487status open 14488 14489\begin_layout Plain Layout 14490 14491\family typewriter 14492HXmc_strpcat 14493\end_layout 14494 14495\end_inset 14496 14497 14498\begin_inset Newline newline 14499\end_inset 14500 14501hxmc_t 14502\series bold 14503* 14504\series default 14505HXmc_strins(hxmc_t 14506\series bold 14507** 14508\series default 14509mc, 14510\series bold 14511size_t 14512\series default 14513 pos, 14514\series bold 14515const char * 14516\series default 14517s); 14518\begin_inset Index idx 14519status open 14520 14521\begin_layout Plain Layout 14522 14523\family typewriter 14524\size normal 14525\color none 14526HXmc_strins 14527\end_layout 14528 14529\end_inset 14530 14531 14532\end_layout 14533 14534\begin_layout Description 14535 14536\family typewriter 14537HXmc_strcpy 14538\family default 14539 Copies the string pointed to by 14540\family typewriter 14541s 14542\family default 14543 into the memory container given by 14544\family typewriter 14545mc 14546\family default 14547. 14548 If 14549\family typewriter 14550mc 14551\family default 14552 is 14553\family typewriter 14554NULL 14555\family default 14556, the memory container will be deallocated, that is, 14557\family typewriter 14558*mc 14559\family default 14560 becomes 14561\family typewriter 14562NULL 14563\family default 14564. 14565\end_layout 14566 14567\begin_layout Subsubsection 14568From auxiliary sources 14569\end_layout 14570 14571\begin_layout LyX-Code 14572hxmc_t 14573\series bold 14574* 14575\series default 14576HX_getl(hxmc_t 14577\series bold 14578** 14579\series default 14580mc, FILE 14581\series bold 14582* 14583\series default 14584fp); 14585\begin_inset Index idx 14586status open 14587 14588\begin_layout Plain Layout 14589 14590\family typewriter 14591HX_getl 14592\end_layout 14593 14594\end_inset 14595 14596 14597\end_layout 14598 14599\begin_layout Description 14600 14601\family typewriter 14602HX_getl 14603\family default 14604 Read the next line from 14605\family typewriter 14606fp 14607\family default 14608 and store the result in the container. 14609 Returns 14610\family typewriter 14611NULL 14612\family default 14613 on error, or when end of file occurs while no characters have been read. 14614\end_layout 14615 14616\begin_layout Subsection 14617Container properties 14618\end_layout 14619 14620\begin_layout LyX-Code 14621 14622\series bold 14623size_t 14624\series default 14625 HXmc_length( 14626\series bold 14627const 14628\series default 14629 hxmc_t 14630\series bold 14631** 14632\series default 14633mc); 14634\end_layout 14635 14636\begin_layout Description 14637 14638\family typewriter 14639HXmc_length 14640\family default 14641 Returns the length of the memory container. 14642 This is not always equal to the actual string length. 14643 For example, if 14644\family typewriter 14645HX_chomp 14646\family default 14647 was used on an MC-backed string, 14648\family typewriter 14649strlen 14650\family default 14651 will return less than 14652\family typewriter 14653HXmc_length 14654\family default 14655 if newline control characters ( 14656\family typewriter 14657' 14658\backslash 14659r' 14660\family default 14661 and 14662\family typewriter 14663' 14664\backslash 14665n' 14666\family default 14667) were removed. 14668\end_layout 14669 14670\begin_layout Standard 14671\begin_inset Newpage clearpage 14672\end_inset 14673 14674 14675\end_layout 14676 14677\begin_layout Section 14678Format templates 14679\begin_inset CommandInset label 14680LatexCommand label 14681name "sec:format" 14682 14683\end_inset 14684 14685 14686\end_layout 14687 14688\begin_layout Standard 14689HXfmt is a small template system for by-name variable expansion. 14690 It can be used to substitute placeholders in format strings supplied by 14691 the user by appropriate expanded values defined by the program. 14692 Such can be used to allow for flexible configuration files that define 14693 key-value mappings such as 14694\end_layout 14695 14696\begin_layout LyX-Code 14697detect_peer = ping6 -c1 %(ADDR) 14698\begin_inset Newline newline 14699\end_inset 14700 14701#detect_peer = nmap -sP %(ADDR) | grep -Eq "appears to be up" 14702\end_layout 14703 14704\begin_layout Standard 14705Consider for example a monitoring daemon that allows the administrator to 14706 specify a program of his choice with which to detect whether a peer is 14707 alive or not. 14708 The user can choose any program that is desired, but evidently needs to 14709 pass the address to be tested to the program. 14710 This is where the daemon will do a substitution of the string 14711\begin_inset Quotes eld 14712\end_inset 14713 14714 14715\family typewriter 14716ping -c1 %(ADDR) 14717\family default 14718 14719\begin_inset Quotes erd 14720\end_inset 14721 14722 it read from the config file, and put the actual address in it before finally 14723 executing the command. 14724\end_layout 14725 14726\begin_layout Standard 14727\begin_inset Float figure 14728placement H 14729wide false 14730sideways false 14731status open 14732 14733\begin_layout LyX-Code 14734printf("%s has %u files 14735\backslash 14736n", user, num); 14737\begin_inset Newline newline 14738\end_inset 14739 14740printf("%2$u files belong to %1$s 14741\backslash 14742n", num, user); 14743\end_layout 14744 14745\begin_layout Plain Layout 14746\begin_inset Quotes eld 14747\end_inset 14748 14749 14750\family typewriter 14751%s 14752\family default 14753 14754\begin_inset Quotes erd 14755\end_inset 14756 14757 (or 14758\begin_inset Quotes eld 14759\end_inset 14760 14761 14762\family typewriter 14763%1$s 14764\family default 14765 14766\begin_inset Quotes erd 14767\end_inset 14768 14769 here) specifies how large 14770\begin_inset Quotes eld 14771\end_inset 14772 14773user 14774\begin_inset Quotes erd 14775\end_inset 14776 14777 is 14778\begin_inset space ~ 14779\end_inset 14780 14781— 14782\family typewriter 14783sizeof(const char *) 14784\family default 14785 in this case. 14786 If that is missing, there is no way to know the offset of 14787\begin_inset Quotes eld 14788\end_inset 14789 14790 14791\family typewriter 14792num 14793\family default 14794 14795\begin_inset Quotes erd 14796\end_inset 14797 14798 relative to 14799\begin_inset Quotes eld 14800\end_inset 14801 14802 14803\family typewriter 14804user 14805\family default 14806 14807\begin_inset Quotes erd 14808\end_inset 14809 14810, making varargs retrieval impossible. 14811\end_layout 14812 14813\begin_layout Plain Layout 14814\begin_inset Caption Standard 14815 14816\begin_layout Plain Layout 14817 14818\family typewriter 14819printf 14820\family default 14821 positional parameters 14822\end_layout 14823 14824\end_inset 14825 14826 14827\end_layout 14828 14829\end_inset 14830 14831 14832\end_layout 14833 14834\begin_layout Standard 14835 14836\family typewriter 14837printf 14838\family default 14839 14840\begin_inset Index idx 14841status open 14842 14843\begin_layout Plain Layout 14844 14845\family typewriter 14846printf 14847\end_layout 14848 14849\end_inset 14850 14851, at least from GNU libc, has something vaguely similar: positional parameters 14852\begin_inset Index idx 14853status open 14854 14855\begin_layout Plain Layout 14856positional parameters 14857\end_layout 14858 14859\end_inset 14860 14861. 14862 They have inherent drawbacks, though. 14863 One is of course the question of portability, but there is a bigger issue. 14864 All parameters must be specified, otherwise there is no way to determine 14865 the location of all following objects following the missing one on the 14866 stack in a varargs-function like 14867\family typewriter 14868printf 14869\family default 14870., which makes it unsuitable to be used with templates where omitting some 14871 placeholders is allowed. 14872\end_layout 14873 14874\begin_layout Subsection 14875Initialization, use and deallocation 14876\end_layout 14877 14878\begin_layout LyX-Code 14879 14880\series bold 14881#include 14882\series default 14883 <libHX/option.h> 14884\begin_inset Index idx 14885status open 14886 14887\begin_layout Plain Layout 14888 14889\family typewriter 14890libHX/option.h 14891\end_layout 14892 14893\end_inset 14894 14895 14896\begin_inset Newline newline 14897\end_inset 14898 14899 14900\begin_inset Newline newline 14901\end_inset 14902 14903 14904\series bold 14905struct 14906\series default 14907 HXformat_map 14908\series bold 14909* 14910\series default 14911HXformat_init( 14912\series bold 14913void 14914\series default 14915); 14916\begin_inset Index idx 14917status open 14918 14919\begin_layout Plain Layout 14920 14921\family typewriter 14922\size normal 14923\color none 14924HXformat_init 14925\end_layout 14926 14927\end_inset 14928 14929 14930\begin_inset Newline newline 14931\end_inset 14932 14933 14934\series bold 14935void 14936\series default 14937 HXformat_free( 14938\series bold 14939struct 14940\series default 14941 HXformat_map 14942\series bold 14943* 14944\series default 14945table); 14946\begin_inset Index idx 14947status open 14948 14949\begin_layout Plain Layout 14950 14951\family typewriter 14952\size normal 14953\color none 14954HXformat_free 14955\end_layout 14956 14957\end_inset 14958 14959 14960\begin_inset Newline newline 14961\end_inset 14962 14963 14964\series bold 14965int 14966\series default 14967 HXformat_add( 14968\series bold 14969struct 14970\series default 14971 HXformat_map 14972\series bold 14973* 14974\series default 14975table, 14976\series bold 14977const char * 14978\series default 14979key, 14980\begin_inset Newline newline 14981\end_inset 14982 14983 14984\series bold 14985const void * 14986\series default 14987ptr, 14988\series bold 14989unsigned int 14990\series default 14991 ptr_type); 14992\begin_inset Index idx 14993status open 14994 14995\begin_layout Plain Layout 14996 14997\family typewriter 14998\size normal 14999\color none 15000HXformat_add 15001\end_layout 15002 15003\end_inset 15004 15005 15006\end_layout 15007 15008\begin_layout Standard 15009 15010\family typewriter 15011HXformat_init 15012\family default 15013 will allocate and set up a simple string-to-string map that is used for 15014 the underlying storage, and returns it. 15015\end_layout 15016 15017\begin_layout Standard 15018To release the substitution table and memory associated with it, call 15019\family typewriter 15020HXformat_free 15021\family default 15022. 15023\end_layout 15024 15025\begin_layout Standard 15026 15027\family typewriter 15028HXformat_add 15029\family default 15030 is used to add substitution entries. 15031 One can also specify other types such as numeral types. 15032 15033\family typewriter 15034ptr_type 15035\family default 15036 describes the type behind 15037\family typewriter 15038ptr 15039\family default 15040 and are constants from 15041\family typewriter 15042option.h 15043\family default 15044 (cf. 15045\begin_inset space \space{} 15046\end_inset 15047 15048section 15049\begin_inset space ~ 15050\end_inset 15051 15052 15053\begin_inset CommandInset ref 15054LatexCommand ref 15055reference "subsec:option-types" 15056 15057\end_inset 15058 15059) 15060\begin_inset space ~ 15061\end_inset 15062 15063— not all constants can be used, though, and their meaning also differs 15064 from what 15065\family typewriter 15066HX_getopt 15067\family default 15068 or 15069\family typewriter 15070HX_shconfig 15071\family default 15072 use them for 15073\begin_inset space ~ 15074\end_inset 15075 15076— the two could be seen as 15077\begin_inset Quotes eld 15078\end_inset 15079 15080read 15081\begin_inset Quotes erd 15082\end_inset 15083 15084 operations, while HXformat is a write operation. 15085\end_layout 15086 15087\begin_layout Subsubsection 15088Immediate types 15089\end_layout 15090 15091\begin_layout Standard 15092\begin_inset Quotes eld 15093\end_inset 15094 15095Immediate types 15096\begin_inset Quotes erd 15097\end_inset 15098 15099 are resolved when 15100\family typewriter 15101HXformat_add 15102\family default 15103 is called, that is, they are copied and inserted into the tree, and are 15104 subsequently independent from any changes to variables in the program. 15105 Because the HXopt-originating type name, that is, 15106\family typewriter 15107HXTYPE_* 15108\family default 15109, is also used for deferred types, the constant 15110\family typewriter 15111HXFORMAT_IMMED 15112\begin_inset Index idx 15113status open 15114 15115\begin_layout Plain Layout 15116 15117\family typewriter 15118HXFORMAT_IMMED 15119\end_layout 15120 15121\end_inset 15122 15123 15124\family default 15125 needs to be specified on some types to denote an immediate value. 15126\end_layout 15127 15128\begin_layout Itemize 15129 15130\family typewriter 15131HXTYPE_STRING 15132\family default 15133 15134\begin_inset space ~ 15135\end_inset 15136 15137— 15138\family typewriter 15139ptr 15140\family default 15141 is a 15142\family typewriter 15143const char * 15144\family default 15145. 15146\end_layout 15147 15148\begin_layout Itemize 15149 15150\family typewriter 15151HXTYPE_ 15152\family default 15153{ 15154\family typewriter 15155U 15156\family default 15157,}{ 15158\family typewriter 15159CHAR 15160\family default 15161, 15162\family typewriter 15163SHORT 15164\family default 15165, 15166\family typewriter 15167INT 15168\family default 15169, 15170\family typewriter 15171LONG 15172\family default 15173, 15174\family typewriter 15175LLONG 15176\family default 15177} 15178\family typewriter 15179 | HXFORMAT_IMMED 15180\family default 15181 15182\begin_inset space ~ 15183\end_inset 15184 15185— mapping to the standard types 15186\end_layout 15187 15188\begin_layout Subsubsection 15189Deferred types 15190\end_layout 15191 15192\begin_layout Standard 15193\begin_inset Quotes eld 15194\end_inset 15195 15196Deferred types 15197\begin_inset Quotes erd 15198\end_inset 15199 15200 are resolved on every invocation of a formatter function ( 15201\family typewriter 15202HXformat_*printf 15203\family default 15204). 15205 The expansions may be changed by modifying the underlying variable pointed 15206 to, but the pointer must remain valid and its pointee not go out of scope. 15207 Figure 15208\begin_inset space ~ 15209\end_inset 15210 15211 15212\begin_inset CommandInset ref 15213LatexCommand ref 15214reference "fig:hxformat-immediate-deferred" 15215 15216\end_inset 15217 15218 shows the difference in a code sample. 15219\end_layout 15220 15221\begin_layout Itemize 15222 15223\family typewriter 15224HXTYPE_STRP 15225\family default 15226 15227\begin_inset Index idx 15228status open 15229 15230\begin_layout Plain Layout 15231 15232\family typewriter 15233HXTYPE_STRP 15234\end_layout 15235 15236\end_inset 15237 15238 15239\begin_inset space ~ 15240\end_inset 15241 15242— 15243\family typewriter 15244ptr 15245\family default 15246 is a 15247\family typewriter 15248const char *const * 15249\family default 15250; the pointer resolution is deferred until the formatter is called with 15251 one of the 15252\family typewriter 15253HXformat_*printf 15254\family default 15255 functions. 15256 Deferred in the sense it is always resolved anew. 15257 15258\end_layout 15259 15260\begin_layout Itemize 15261 15262\family typewriter 15263HXTYPE_BOOL 15264\family default 15265 15266\begin_inset Index idx 15267status open 15268 15269\begin_layout Plain Layout 15270 15271\family typewriter 15272HXTYPE_BOOL 15273\end_layout 15274 15275\end_inset 15276 15277 15278\begin_inset space ~ 15279\end_inset 15280 15281— 15282\family typewriter 15283ptr 15284\family default 15285 is a 15286\family typewriter 15287const int 15288\begin_inset space ~ 15289\end_inset 15290 15291* 15292\family default 15293. 15294\end_layout 15295 15296\begin_layout Itemize 15297 15298\family typewriter 15299HXTYPE_ 15300\family default 15301{ 15302\family typewriter 15303U 15304\family default 15305,}{ 15306\family typewriter 15307CHAR 15308\family default 15309 15310\begin_inset Index idx 15311status open 15312 15313\begin_layout Plain Layout 15314 15315\family typewriter 15316HXTYPE_CHAR 15317\end_layout 15318 15319\end_inset 15320 15321 15322\begin_inset Index idx 15323status open 15324 15325\begin_layout Plain Layout 15326 15327\family typewriter 15328HXTYPE_UCHAR 15329\end_layout 15330 15331\end_inset 15332 15333, 15334\family typewriter 15335SHORT 15336\family default 15337 15338\begin_inset Index idx 15339status open 15340 15341\begin_layout Plain Layout 15342 15343\family typewriter 15344HXTYPE_SHORT 15345\end_layout 15346 15347\end_inset 15348 15349 15350\begin_inset Index idx 15351status open 15352 15353\begin_layout Plain Layout 15354 15355\family typewriter 15356HXTYPE_USHORT 15357\end_layout 15358 15359\end_inset 15360 15361, 15362\family typewriter 15363INT 15364\family default 15365 15366\begin_inset Index idx 15367status open 15368 15369\begin_layout Plain Layout 15370 15371\family typewriter 15372HXTYPE_INT 15373\end_layout 15374 15375\end_inset 15376 15377 15378\begin_inset Index idx 15379status open 15380 15381\begin_layout Plain Layout 15382 15383\family typewriter 15384HXTYPE_UINT 15385\end_layout 15386 15387\end_inset 15388 15389, 15390\family typewriter 15391LONG 15392\family default 15393 15394\begin_inset Index idx 15395status open 15396 15397\begin_layout Plain Layout 15398 15399\family typewriter 15400HXTYPE_LONG 15401\end_layout 15402 15403\end_inset 15404 15405 15406\begin_inset Index idx 15407status open 15408 15409\begin_layout Plain Layout 15410 15411\family typewriter 15412HXTYPE_ULONG 15413\end_layout 15414 15415\end_inset 15416 15417, 15418\family typewriter 15419LLONG 15420\family default 15421 15422\begin_inset Index idx 15423status open 15424 15425\begin_layout Plain Layout 15426 15427\family typewriter 15428HXTYPE_LLONG 15429\end_layout 15430 15431\end_inset 15432 15433 15434\begin_inset Index idx 15435status open 15436 15437\begin_layout Plain Layout 15438 15439\family typewriter 15440HXTYPE_ULLONG 15441\end_layout 15442 15443\end_inset 15444 15445} 15446\begin_inset space ~ 15447\end_inset 15448 15449— mapping to the standard types with one indirection (e. 15450\begin_inset space \thinspace{} 15451\end_inset 15452 15453g. 15454\begin_inset space \space{} 15455\end_inset 15456 15457 15458\family typewriter 15459int 15460\begin_inset space ~ 15461\end_inset 15462 15463* 15464\family default 15465) 15466\end_layout 15467 15468\begin_layout Itemize 15469 15470\family typewriter 15471HXTYPE_ 15472\family default 15473{ 15474\family typewriter 15475FLOAT 15476\family default 15477 15478\begin_inset Index idx 15479status open 15480 15481\begin_layout Plain Layout 15482 15483\family typewriter 15484HXTYPE_FLOAT 15485\end_layout 15486 15487\end_inset 15488 15489, 15490\family typewriter 15491DOUBLE 15492\family default 15493 15494\begin_inset Index idx 15495status open 15496 15497\begin_layout Plain Layout 15498 15499\family typewriter 15500HXTYPE_DOUBLE 15501\end_layout 15502 15503\end_inset 15504 15505} 15506\begin_inset space ~ 15507\end_inset 15508 15509— mapping to the two floating-point types with one indirection (e. 15510\begin_inset space \thinspace{} 15511\end_inset 15512 15513g. 15514\begin_inset space \space{} 15515\end_inset 15516 15517 15518\family typewriter 15519double 15520\begin_inset space ~ 15521\end_inset 15522 15523* 15524\family default 15525) 15526\end_layout 15527 15528\begin_layout Subsection 15529Invoking the formatter 15530\end_layout 15531 15532\begin_layout LyX-Code 15533 15534\series bold 15535int 15536\series default 15537 HXformat_aprintf( 15538\series bold 15539struct 15540\series default 15541 HXformat_map 15542\series bold 15543* 15544\series default 15545table, hxmc_t 15546\series bold 15547** 15548\series default 15549dest, 15550\series bold 15551const char * 15552\series default 15553template); 15554\begin_inset Index idx 15555status open 15556 15557\begin_layout Plain Layout 15558 15559\family typewriter 15560HXformat_aprintf 15561\end_layout 15562 15563\end_inset 15564 15565 15566\begin_inset Newline newline 15567\end_inset 15568 15569 15570\series bold 15571int 15572\series default 15573 HXformat_sprintf( 15574\series bold 15575struct 15576\series default 15577 HXformat_map 15578\series bold 15579* 15580\series default 15581table, 15582\series bold 15583char * 15584\series default 15585dest, 15586\series bold 15587size_t 15588\series default 15589 size, 15590\series bold 15591const char * 15592\series default 15593template); 15594\begin_inset Index idx 15595status open 15596 15597\begin_layout Plain Layout 15598 15599\family typewriter 15600\size normal 15601\color none 15602HXformat_sprintf 15603\end_layout 15604 15605\end_inset 15606 15607 15608\begin_inset Newline newline 15609\end_inset 15610 15611 15612\series bold 15613int 15614\series default 15615 HXformat_fprintf( 15616\series bold 15617struct 15618\series default 15619 HXformat_map 15620\series bold 15621* 15622\series default 15623table, FILE 15624\series bold 15625* 15626\series default 15627filp, 15628\series bold 15629const char * 15630\series default 15631template); 15632\begin_inset Index idx 15633status open 15634 15635\begin_layout Plain Layout 15636 15637\family typewriter 15638\size normal 15639\color none 15640HXformat_fprintf 15641\end_layout 15642 15643\end_inset 15644 15645 15646\end_layout 15647 15648\begin_layout Description 15649 15650\family typewriter 15651HXformat_aprintf 15652\family default 15653 Substitute placeholders in 15654\family typewriter 15655template 15656\family default 15657 using the given table. 15658 This will produce a string in a HX memory container ( 15659\family typewriter 15660hxmc_t 15661\family default 15662), and the pointer is put into 15663\family typewriter 15664*dest 15665\family default 15666. 15667 The caller will be responsible for freeing it later when it is done using 15668 the result. 15669\end_layout 15670 15671\begin_layout Description 15672 15673\family typewriter 15674HXformat_sprintf 15675\family default 15676 Do substitution and store the expanded result in the buffer 15677\family typewriter 15678dest 15679\family default 15680 which is of size 15681\family typewriter 15682size 15683\family default 15684. 15685\end_layout 15686 15687\begin_layout Description 15688 15689\family typewriter 15690HXformat_fprintf 15691\family default 15692 Do substituion and directly output the expansion to the given stdio stream. 15693\end_layout 15694 15695\begin_layout Standard 15696On success, the length of the expanded string is returned, excluding the 15697 trailing 15698\family typewriter 15699' 15700\backslash 157010' 15702\family default 15703. 15704 While 15705\family typewriter 15706HXformat_sprintf 15707\family default 15708 will not write more than 15709\family typewriter 15710size 15711\family default 15712 bytes (including the 15713\family typewriter 15714' 15715\backslash 157160' 15717\family default 15718), the length it would have taken is returned, similar to what 15719\family typewriter 15720sprintf 15721\family default 15722 does. 15723 On error, negative errno is returned. 15724\end_layout 15725 15726\begin_layout Standard 15727The HXformat function family recognizes make-style like functions and recursive 15728 expansion, described below. 15729\end_layout 15730 15731\begin_layout Subsection 15732Functions 15733\end_layout 15734 15735\begin_layout Standard 15736To expand a variable, one uses a syntax like 15737\begin_inset Quotes eld 15738\end_inset 15739 15740 15741\family typewriter 15742%(NAME) 15743\family default 15744 15745\begin_inset Quotes erd 15746\end_inset 15747 15748 in the format string. 15749 Recursive expansion like 15750\begin_inset Quotes eld 15751\end_inset 15752 15753 15754\family typewriter 15755%(%(USER)) 15756\family default 15757 15758\begin_inset Quotes erd 15759\end_inset 15760 15761 is supported; assuming 15762\family typewriter 15763%(USER) 15764\family default 15765 would expand to 15766\begin_inset Quotes eld 15767\end_inset 15768 15769linux 15770\begin_inset Quotes erd 15771\end_inset 15772 15773, HXformat would try to resolve 15774\begin_inset Quotes eld 15775\end_inset 15776 15777 15778\family typewriter 15779%(linux) 15780\family default 15781 15782\begin_inset Quotes erd 15783\end_inset 15784 15785 next. 15786 Besides these variable substitutions, HXformat also provides function calls 15787 whose syntax is 15788\begin_inset Quotes eld 15789\end_inset 15790 15791 15792\family typewriter 15793%(nameOfFunction parameters[...]) 15794\family default 15795 15796\begin_inset Quotes erd 15797\end_inset 15798 15799. 15800 Parameters can be any text, including variables. 15801 Paramters are separated from another by a delimiter specific to each function. 15802 See this list for details: 15803\end_layout 15804 15805\begin_layout Itemize 15806 15807\family typewriter 15808%(env 15809\family default 15810 15811\shape italic 15812variable 15813\family typewriter 15814\shape default 15815) 15816\begin_inset Newline newline 15817\end_inset 15818 15819 15820\family default 15821The 15822\family typewriter 15823env 15824\family default 15825 function expands to the string that is stored in the environmental variable 15826 by the given name. 15827\end_layout 15828 15829\begin_layout Itemize 15830 15831\family typewriter 15832%(exec 15833\family default 15834\shape italic 15835command 15836\family typewriter 15837\shape default 15838 15839\family default 15840[ 15841\shape italic 15842args 15843\shape default 15844...] 15845\family typewriter 15846) 15847\family default 15848 15849\begin_inset Newline newline 15850\end_inset 15851 15852The 15853\family typewriter 15854exec 15855\family default 15856 function expands to the standard output of the command. 15857 The command is directly run without shell invocation, so no special character 15858 expansion (wildcards, etc.) takes place. 15859 stdin is set to 15860\family typewriter 15861/dev\SpecialChar breakableslash 15862null 15863\family default 15864. 15865 The parameter delimiter is the space character. 15866 To be able to use this function 15867\begin_inset space ~ 15868\end_inset 15869 15870— as it is relevant to security 15871\begin_inset space ~ 15872\end_inset 15873 15874— the fmt table needs to have a key called 15875\begin_inset Quotes eld 15876\end_inset 15877 15878 15879\family typewriter 15880/libhx/exec 15881\family default 15882 15883\begin_inset Quotes erd 15884\end_inset 15885 15886. 15887 See example 15888\begin_inset space ~ 15889\end_inset 15890 15891 15892\begin_inset CommandInset ref 15893LatexCommand ref 15894reference "fig:hxformat-exec" 15895 15896\end_inset 15897 15898 for details. 15899\end_layout 15900 15901\begin_layout Itemize 15902 15903\family typewriter 15904%(if 15905\family default 15906\shape italic 15907condition 15908\family typewriter 15909\shape default 15910, 15911\family default 15912[ 15913\shape italic 15914then 15915\shape default 15916][ 15917\family typewriter 15918, 15919\family default 15920[ 15921\shape italic 15922else 15923\shape default 15924]] 15925\family typewriter 15926) 15927\family default 15928 15929\begin_inset Newline newline 15930\end_inset 15931 15932If the condition parameter expands to a string of non-zero length, the function 15933 expands to the 15934\begin_inset Quotes eld 15935\end_inset 15936 15937then 15938\begin_inset Quotes erd 15939\end_inset 15940 15941 block, otherwise the 15942\begin_inset Quotes eld 15943\end_inset 15944 15945else 15946\begin_inset Quotes erd 15947\end_inset 15948 15949 block. 15950 The delimiter used is a comma. 15951\end_layout 15952 15953\begin_layout Itemize 15954 15955\family typewriter 15956%(lower 15957\family default 15958\shape italic 15959text 15960\family typewriter 15961\shape default 15962) 15963\family default 15964, 15965\family typewriter 15966%(upper 15967\family default 15968\shape italic 15969text 15970\family typewriter 15971\shape default 15972) 15973\family default 15974 15975\begin_inset Newline newline 15976\end_inset 15977 15978Lowercases or uppercases the supplied argument. 15979 As these functions are meant to take only one argument, there is no delimiter 15980 defined that would need escaping if multiple arguments were supposed to 15981 be passed. 15982 15983\family typewriter 15984%(lower a,b) 15985\family default 15986 is equivalent to 15987\family typewriter 15988%(lower "a,b") 15989\family default 15990. 15991\end_layout 15992 15993\begin_layout Itemize 15994 15995\family typewriter 15996%(shell 15997\family default 15998\shape italic 15999command 16000\family typewriter 16001\shape default 16002 16003\family default 16004[ 16005\shape italic 16006args 16007\shape default 16008...] 16009\family typewriter 16010) 16011\family default 16012 16013\begin_inset Newline newline 16014\end_inset 16015 16016Similar to 16017\family typewriter 16018%(exec) 16019\family default 16020, but invokes the shell inbetween (i. 16021\begin_inset space \thinspace{} 16022\end_inset 16023 16024e. 16025\begin_inset space \space{} 16026\end_inset 16027 16028` 16029\family typewriter 16030sh -c ' 16031\family default 16032\shape italic 16033command 16034\shape default 16035... 16036\family typewriter 16037' 16038\family default 16039`) such that special characters, redirection, and so on can be used. 16040\end_layout 16041 16042\begin_layout Itemize 16043 16044\family typewriter 16045%(substr 16046\family default 16047\shape italic 16048text 16049\family typewriter 16050\shape default 16051, 16052\family default 16053\shape italic 16054offset 16055\shape default 16056[ 16057\family typewriter 16058, 16059\family default 16060\shape italic 16061length 16062\shape default 16063] 16064\family typewriter 16065) 16066\family default 16067 16068\begin_inset Newline newline 16069\end_inset 16070 16071Extracts a substring out of the given text, starting at 16072\shape italic 16073offset 16074\shape default 16075 and running for the given length. 16076 If no length is given, will extract until the end of the string. 16077 If 16078\shape italic 16079offset 16080\shape default 16081 is negative, it specifies the offset from the end of the string. 16082 If 16083\shape italic 16084length 16085\shape default 16086 is negative, that many characters are left off the end. 16087\end_layout 16088 16089\begin_layout Itemize 16090 16091\family typewriter 16092%(snl 16093\family default 16094\shape italic 16095text 16096\family typewriter 16097\shape default 16098) 16099\family default 16100 16101\begin_inset Newline newline 16102\end_inset 16103 16104Strips trailing newlines from text and replaces any other newline by a space. 16105 What happens implicity in Makefiles' 16106\family typewriter 16107$(shell 16108\family default 16109... 16110\family typewriter 16111) 16112\family default 16113 statements usually is explicitly separate in libHX. 16114\end_layout 16115 16116\begin_layout Subsection 16117Examples 16118\end_layout 16119 16120\begin_layout Standard 16121\begin_inset Float figure 16122placement H 16123wide false 16124sideways false 16125status open 16126 16127\begin_layout LyX-Code 16128 16129\series bold 16130const char * 16131\series default 16132b = "Hello World"; 16133\begin_inset Newline newline 16134\end_inset 16135 16136 16137\family typewriter 16138\series bold 16139char 16140\series default 16141 c 16142\family default 16143\series bold 16144[] 16145\family typewriter 16146\series default 16147 = "Hello World"; 16148\family default 16149 16150\begin_inset Newline newline 16151\end_inset 16152 16153 16154\family typewriter 16155\series bold 16156struct 16157\series default 16158 HXformat_map 16159\series bold 16160* 16161\series default 16162table = HXformat_init(); 16163\begin_inset Newline newline 16164\end_inset 16165 16166HXformat_add(table, "%(GREETING1)", b, HXTYPE_STRING); 16167\begin_inset Newline newline 16168\end_inset 16169 16170HXformat_add(table, "%(GREETING2)", &c, HXTYPE_STRP); 16171\begin_inset Newline newline 16172\end_inset 16173 16174b = NULL; 16175\begin_inset Newline newline 16176\end_inset 16177 16178snprintf(c, 16179\family default 16180\series bold 16181sizeof 16182\family typewriter 16183\series default 16184(c), "Hello Home"); 16185\begin_inset Newline newline 16186\end_inset 16187 16188HXformat_aprintf(...); 16189\end_layout 16190 16191\begin_layout Plain Layout 16192Upon calling 16193\family typewriter 16194HXformat_*printf 16195\family default 16196, 16197\family typewriter 16198%(GREETING1) 16199\family default 16200 will expand to 16201\begin_inset Quotes eld 16202\end_inset 16203 16204Hello World 16205\begin_inset Quotes erd 16206\end_inset 16207 16208 whereas 16209\family typewriter 16210%(GREETING2) 16211\family default 16212 will expand to 16213\begin_inset Quotes eld 16214\end_inset 16215 16216Hello Home 16217\begin_inset Quotes erd 16218\end_inset 16219 16220. 16221\end_layout 16222 16223\begin_layout Plain Layout 16224\begin_inset Caption Standard 16225 16226\begin_layout Plain Layout 16227\begin_inset CommandInset label 16228LatexCommand label 16229name "fig:hxformat-immediate-deferred" 16230 16231\end_inset 16232 16233Immediate and deferred resolution 16234\end_layout 16235 16236\end_inset 16237 16238 16239\end_layout 16240 16241\end_inset 16242 16243 16244\end_layout 16245 16246\begin_layout Standard 16247\begin_inset Float figure 16248wide false 16249sideways false 16250status open 16251 16252\begin_layout LyX-Code 16253 16254\series bold 16255struct 16256\series default 16257 HXformat_map 16258\series bold 16259* 16260\series default 16261table = HXformat_init(); 16262\begin_inset Newline newline 16263\end_inset 16264 16265HXformat_add(table, "/libhx/exec", NULL, HXTYPE_IMMED); 16266\begin_inset Newline newline 16267\end_inset 16268 16269HXformat_aprintf(table, &result, "%(exec uname -s)"); 16270\end_layout 16271 16272\begin_layout Plain Layout 16273\begin_inset Caption Standard 16274 16275\begin_layout Plain Layout 16276\begin_inset CommandInset label 16277LatexCommand label 16278name "fig:hxformat-exec" 16279 16280\end_inset 16281 16282Using the 16283\family typewriter 16284%(exec) 16285\family default 16286 function 16287\end_layout 16288 16289\end_inset 16290 16291 16292\end_layout 16293 16294\end_inset 16295 16296 16297\end_layout 16298 16299\begin_layout Standard 16300\begin_inset Newpage clearpage 16301\end_inset 16302 16303 16304\end_layout 16305 16306\begin_layout Part 16307Filesystem operations 16308\end_layout 16309 16310\begin_layout Section 16311Dentry operations 16312\end_layout 16313 16314\begin_layout Subsection 16315Synopsis 16316\end_layout 16317 16318\begin_layout LyX-Code 16319 16320\series bold 16321#include <libHX/io.h> 16322\series default 16323 16324\begin_inset Newline newline 16325\end_inset 16326 16327 16328\begin_inset Newline newline 16329\end_inset 16330 16331 16332\series bold 16333int 16334\series default 16335 HX_readlink(hxmc_t 16336\series bold 16337** 16338\series default 16339buf, 16340\series bold 16341const char * 16342\series default 16343path); 16344\begin_inset Index idx 16345status open 16346 16347\begin_layout Plain Layout 16348HX_readlink 16349\end_layout 16350 16351\end_inset 16352 16353 16354\begin_inset Newline newline 16355\end_inset 16356 16357 16358\series bold 16359int 16360\series default 16361 HX_realpath(hxmc_t 16362\series bold 16363** 16364\series default 16365buf, 16366\series bold 16367const char * 16368\series default 16369path, 16370\series bold 16371unsigned int 16372\series default 16373 flags); 16374\begin_inset Index idx 16375status open 16376 16377\begin_layout Plain Layout 16378HX_realpath 16379\end_layout 16380 16381\end_inset 16382 16383 16384\end_layout 16385 16386\begin_layout Standard 16387 16388\family typewriter 16389HX_readlink 16390\family default 16391 calls through to 16392\family typewriter 16393readlink 16394\family default 16395 to read the target of a symbolic link, and stores the result in the memory 16396 container referenced by 16397\family typewriter 16398*buf 16399\family default 16400 (similar to 16401\family typewriter 16402HX_getl 16403\family default 16404 semantics). 16405 If 16406\family typewriter 16407*buf 16408\family default 16409 is 16410\family typewriter 16411NULL 16412\family default 16413, a new container will be allocated and a pointer to it stored in 16414\family typewriter 16415*buf 16416\family default 16417. 16418 The container's content is naturally zero-terminated automatically. 16419 The return value of the function will be the length of the link target, 16420 or negative to indicate the system error value. 16421\end_layout 16422 16423\begin_layout Standard 16424 16425\family typewriter 16426HX_realpath 16427\family default 16428 will normalize the given path by transforming various path components into 16429 alternate descriptions. 16430 The 16431\family typewriter 16432flags 16433\family default 16434 parameter controls its actions: 16435\end_layout 16436 16437\begin_layout Description 16438 16439\family typewriter 16440HX_REALPATH_DEFAULT 16441\family default 16442 16443\begin_inset Index idx 16444status open 16445 16446\begin_layout Plain Layout 16447 16448\family typewriter 16449HX_REALPATH_DEFAULT 16450\end_layout 16451 16452\end_inset 16453 16454 A mnemonic for a set of standard flags: 16455\family typewriter 16456HX_\SpecialChar softhyphen 16457REALPATH_\SpecialChar softhyphen 16458SELF 16459\begin_inset space ~ 16460\end_inset 16461 16462| HX_\SpecialChar softhyphen 16463REALPATH_\SpecialChar softhyphen 16464PARENT 16465\family default 16466. 16467 Note that 16468\family typewriter 16469HX_\SpecialChar softhyphen 16470REALPATH_\SpecialChar softhyphen 16471ABSOLUTE 16472\family default 16473, which would also be required to get libc's 16474\family typewriter 16475realpath 16476\family default 16477(3) behavior, is not included in the set. 16478\end_layout 16479 16480\begin_layout Description 16481 16482\family typewriter 16483HX_REALPATH_ABSOLUTE 16484\family default 16485 16486\begin_inset Index idx 16487status open 16488 16489\begin_layout Plain Layout 16490 16491\family typewriter 16492HX_REALPATH_ABSOLUTE 16493\end_layout 16494 16495\end_inset 16496 16497 Requests that the output path shall be absolute. 16498 In the absence of this flag, an absolute output path will only be produced 16499 if the input path is also absolute. 16500\end_layout 16501 16502\begin_layout Description 16503 16504\family typewriter 16505HX_REALPATH_SELF 16506\family default 16507 16508\begin_inset Index idx 16509status open 16510 16511\begin_layout Plain Layout 16512 16513\family typewriter 16514HX_REALPATH_SELF 16515\end_layout 16516 16517\end_inset 16518 16519 Request resolution of 16520\begin_inset Quotes eld 16521\end_inset 16522 16523. 16524\begin_inset Quotes erd 16525\end_inset 16526 16527 path components. 16528\end_layout 16529 16530\begin_layout Description 16531 16532\family typewriter 16533HX_REALPATH_PARENT 16534\family default 16535 16536\begin_inset Index idx 16537status open 16538 16539\begin_layout Plain Layout 16540 16541\family typewriter 16542HX_REALPATH_PARENT 16543\end_layout 16544 16545\end_inset 16546 16547 Request resolution of 16548\begin_inset Quotes eld 16549\end_inset 16550 16551.. 16552\begin_inset Quotes erd 16553\end_inset 16554 16555 path components. 16556\end_layout 16557 16558\begin_layout Standard 16559The result is stored in a memory container whose pointer is returned through 16560 16561\family typewriter 16562*buf 16563\family default 16564. 16565 The return value of the function will be negative to indicate a possible 16566 system error, or be positive non-zero for success. 16567\end_layout 16568 16569\begin_layout Section 16570Directory traversal 16571\begin_inset CommandInset label 16572LatexCommand label 16573name "sec:dir-ops1" 16574 16575\end_inset 16576 16577 16578\end_layout 16579 16580\begin_layout Standard 16581libHX provides a minimal readdir-style wrapper for cross-platform directory 16582 traversal. 16583 This is needed because the Win32 platforms does not have readdir, and there 16584 is some housekeeping to do on Unixish platforms, since the 16585\family typewriter 16586dirent 16587\family default 16588 structure needs allocation of a path-specific size. 16589\end_layout 16590 16591\begin_layout Subsection 16592Synopsis 16593\end_layout 16594 16595\begin_layout LyX-Code 16596 16597\series bold 16598#include 16599\series default 16600 <libHX/io.h> 16601\begin_inset Index idx 16602status open 16603 16604\begin_layout Plain Layout 16605 16606\family typewriter 16607libHX/io.h 16608\end_layout 16609 16610\end_inset 16611 16612 16613\begin_inset Newline newline 16614\end_inset 16615 16616 16617\begin_inset Newline newline 16618\end_inset 16619 16620 16621\series bold 16622struct 16623\series default 16624 HXdir 16625\series bold 16626* 16627\series default 16628HXdir_open( 16629\series bold 16630const char * 16631\series default 16632directory); 16633\begin_inset Index idx 16634status open 16635 16636\begin_layout Plain Layout 16637 16638\family typewriter 16639\size normal 16640\color none 16641HXdir_open 16642\end_layout 16643 16644\end_inset 16645 16646 16647\begin_inset Newline newline 16648\end_inset 16649 16650 16651\series bold 16652const char * 16653\series default 16654HXdir_read( 16655\series bold 16656struct 16657\series default 16658 HXdir 16659\series bold 16660* 16661\series default 16662handle); 16663\begin_inset Index idx 16664status open 16665 16666\begin_layout Plain Layout 16667 16668\family typewriter 16669\size normal 16670\color none 16671HXdir_read 16672\end_layout 16673 16674\end_inset 16675 16676 16677\begin_inset Newline newline 16678\end_inset 16679 16680 16681\series bold 16682void 16683\series default 16684 HXdir_close( 16685\series bold 16686struct 16687\series default 16688 HXdir 16689\series bold 16690* 16691\series default 16692handle); 16693\begin_inset Index idx 16694status open 16695 16696\begin_layout Plain Layout 16697 16698\family typewriter 16699\size normal 16700\color none 16701HXdir_close 16702\end_layout 16703 16704\end_inset 16705 16706 16707\end_layout 16708 16709\begin_layout Standard 16710 16711\family typewriter 16712HXdir_open 16713\family default 16714 returns a pointer to its private data area, or 16715\family typewriter 16716NULL 16717\family default 16718 upon failure, in which case 16719\family typewriter 16720errno 16721\family default 16722 is preserved from the underlying system calls. 16723 16724\family typewriter 16725HXdir_read 16726\family default 16727 causes the next entry from the directory to be fetched. 16728 The pointer returned by 16729\family typewriter 16730HXdir_read 16731\family default 16732 must not be freed, and the data is overwritten in subsequent calls to the 16733 same handle. 16734 If you want to keep it around, you will have to duplicate it yourself. 16735 16736\family typewriter 16737HXdir_close 16738\family default 16739 will close the directory and free the private data it held. 16740\end_layout 16741 16742\begin_layout Subsection 16743Example 16744\end_layout 16745 16746\begin_layout LyX-Code 16747 16748\series bold 16749#include 16750\series default 16751 <errno.h> 16752\begin_inset Newline newline 16753\end_inset 16754 16755 16756\series bold 16757#include 16758\series default 16759 <stdio.h> 16760\begin_inset Newline newline 16761\end_inset 16762 16763 16764\series bold 16765#include 16766\series default 16767 <libHX/io.h> 16768\begin_inset Newline newline 16769\end_inset 16770 16771 16772\begin_inset Newline newline 16773\end_inset 16774 16775 16776\series bold 16777struct 16778\series default 16779 HXdir 16780\series bold 16781* 16782\series default 16783dh; 16784\begin_inset Newline newline 16785\end_inset 16786 16787 16788\series bold 16789if 16790\series default 16791 ((dh = HXdir_open(".")) == NULL) { 16792\begin_inset Newline newline 16793\end_inset 16794 16795 fprintf(stderr, "Could not open directory: %s 16796\backslash 16797n", strerror(errno)); 16798\begin_inset Newline newline 16799\end_inset 16800 16801 return; 16802\begin_inset Newline newline 16803\end_inset 16804 16805} 16806\begin_inset Newline newline 16807\end_inset 16808 16809 16810\series bold 16811while 16812\series default 16813 ((dentry = HXdir_read(dh)) != NULL) 16814\begin_inset Newline newline 16815\end_inset 16816 16817 printf("%s 16818\backslash 16819n", dentry); 16820\begin_inset Newline newline 16821\end_inset 16822 16823HXdir_close(dh); 16824\end_layout 16825 16826\begin_layout Standard 16827This sample will open the current directory, and print out all entries as 16828 it iterates over them. 16829\end_layout 16830 16831\begin_layout Section 16832Directory operations 16833\begin_inset CommandInset label 16834LatexCommand label 16835name "sec:dir-ops2" 16836 16837\end_inset 16838 16839 16840\end_layout 16841 16842\begin_layout Subsection 16843Synopsis 16844\end_layout 16845 16846\begin_layout LyX-Code 16847 16848\series bold 16849#include 16850\series default 16851 <libHX/io.h> 16852\begin_inset Index idx 16853status open 16854 16855\begin_layout Plain Layout 16856 16857\family typewriter 16858libHX/io.h 16859\end_layout 16860 16861\end_inset 16862 16863 16864\begin_inset Newline newline 16865\end_inset 16866 16867 16868\begin_inset Newline newline 16869\end_inset 16870 16871 16872\series bold 16873int 16874\series default 16875 HX_mkdir( 16876\series bold 16877const char * 16878\series default 16879path, 16880\series bold 16881unsigned int 16882\series default 16883 mode); 16884\begin_inset Index idx 16885status open 16886 16887\begin_layout Plain Layout 16888HX_mkdir 16889\end_layout 16890 16891\end_inset 16892 16893 16894\begin_inset Newline newline 16895\end_inset 16896 16897 16898\series bold 16899int 16900\series default 16901 HX_rrmdir( 16902\series bold 16903const char * 16904\series default 16905path); 16906\begin_inset Index idx 16907status open 16908 16909\begin_layout Plain Layout 16910 16911\family typewriter 16912\size normal 16913\color none 16914HX_rrmdir 16915\end_layout 16916 16917\end_inset 16918 16919 16920\end_layout 16921 16922\begin_layout Standard 16923 16924\family typewriter 16925HX_mkdir 16926\family default 16927 will create the directory given by 16928\family typewriter 16929path 16930\family default 16931 and all its parents that do not exist yet using the given 16932\family typewriter 16933mode 16934\family default 16935. 16936 It is equivalent to the ` 16937\family typewriter 16938mkdir -p 16939\family default 16940` shell command. 16941 It will return >0 for success, or 16942\family typewriter 16943-errno 16944\family default 16945 on error. 16946\end_layout 16947 16948\begin_layout Standard 16949 16950\family typewriter 16951HX_rrmdir 16952\family default 16953 also maps to an operation commonly done on the shell, ` 16954\family typewriter 16955rm -Rf 16956\family default 16957`, deleting the directory given by 16958\family typewriter 16959path 16960\family default 16961, including all files within it and its subdirectories. 16962 Errors during deletion are ignored, but if there was any, the errno value 16963 of the first one is returned negated. 16964\end_layout 16965 16966\begin_layout Section 16967File operations 16968\begin_inset CommandInset label 16969LatexCommand label 16970name "sec:file-ops" 16971 16972\end_inset 16973 16974 16975\end_layout 16976 16977\begin_layout Subsection 16978Synopsis 16979\end_layout 16980 16981\begin_layout LyX-Code 16982 16983\series bold 16984#include 16985\series default 16986 <libHX/io.h> 16987\begin_inset Index idx 16988status open 16989 16990\begin_layout Plain Layout 16991 16992\family typewriter 16993libHX/io.h 16994\end_layout 16995 16996\end_inset 16997 16998 16999\begin_inset Newline newline 17000\end_inset 17001 17002 17003\begin_inset Newline newline 17004\end_inset 17005 17006 17007\series bold 17008int 17009\series default 17010 HX_copy_file( 17011\series bold 17012const char * 17013\series default 17014src, 17015\series bold 17016const char * 17017\series default 17018dest, 17019\series bold 17020unsigned int 17021\series default 17022 flags, ...); 17023\begin_inset Index idx 17024status open 17025 17026\begin_layout Plain Layout 17027 17028\family typewriter 17029HX_copy_file 17030\end_layout 17031 17032\end_inset 17033 17034 17035\begin_inset Newline newline 17036\end_inset 17037 17038 17039\series bold 17040int 17041\series default 17042 HX_copy_dir( 17043\series bold 17044const char * 17045\series default 17046src, 17047\series bold 17048const char * 17049\series default 17050dest, 17051\series bold 17052unsigned int 17053\series default 17054 flags, ...); 17055\begin_inset Index idx 17056status open 17057 17058\begin_layout Plain Layout 17059 17060\family typewriter 17061HX_copy_dir 17062\end_layout 17063 17064\end_inset 17065 17066 17067\end_layout 17068 17069\begin_layout Standard 17070Possible flags that can be used with the functions: 17071\end_layout 17072 17073\begin_layout Description 17074 17075\family typewriter 17076HXF_KEEP 17077\family default 17078 17079\begin_inset Index idx 17080status open 17081 17082\begin_layout Plain Layout 17083 17084\family typewriter 17085HXF_KEEP 17086\end_layout 17087 17088\end_inset 17089 17090 Do not overwrite existing files. 17091\end_layout 17092 17093\begin_layout Description 17094 17095\family typewriter 17096HXF_UID 17097\family default 17098 17099\begin_inset Index idx 17100status open 17101 17102\begin_layout Plain Layout 17103 17104\family typewriter 17105HXF_UID 17106\end_layout 17107 17108\end_inset 17109 17110 Change the new file's owner to the UID given in the varargs section ( 17111\family typewriter 17112... 17113\family default 17114). 17115 17116\family typewriter 17117HXF_UID 17118\family default 17119 is processed before 17120\family typewriter 17121HXF_GID 17122\family default 17123. 17124\end_layout 17125 17126\begin_layout Description 17127 17128\family typewriter 17129HXF_GID 17130\family default 17131 17132\begin_inset Index idx 17133status open 17134 17135\begin_layout Plain Layout 17136 17137\family typewriter 17138HXF_GID 17139\end_layout 17140 17141\end_inset 17142 17143 Change the new file's group owner to the GID given in the varargs section. 17144 This is processed after 17145\family typewriter 17146HXF_UID 17147\family default 17148. 17149\end_layout 17150 17151\begin_layout Standard 17152Error checking is flakey. 17153\end_layout 17154 17155\begin_layout Standard 17156 17157\family typewriter 17158HX_copy_file 17159\family default 17160 will return >0 on success, or 17161\family typewriter 17162-errno 17163\family default 17164 on failure. 17165 Errors can arise from the use of the syscalls 17166\family typewriter 17167open 17168\family default 17169, 17170\family typewriter 17171read 17172\family default 17173 and 17174\family typewriter 17175write 17176\family default 17177. 17178 The return value of 17179\family typewriter 17180fchmod 17181\family default 17182, which is used to set the UID and GID, is actually ignored, which means 17183 verifying that the owner has been set cannot be detected with 17184\family typewriter 17185HX_copy_file 17186\family default 17187 alone (historic negligience?). 17188\end_layout 17189 17190\begin_layout Subsection 17191Filedescriptor I/O 17192\end_layout 17193 17194\begin_layout LyX-Code 17195 17196\series bold 17197#include 17198\series default 17199 <libHX/io.h> 17200\begin_inset Index idx 17201status open 17202 17203\begin_layout Plain Layout 17204 17205\family typewriter 17206libHX/io.h 17207\end_layout 17208 17209\end_inset 17210 17211 17212\begin_inset Newline newline 17213\end_inset 17214 17215 17216\begin_inset Newline newline 17217\end_inset 17218 17219 17220\series bold 17221ssize_t 17222\series default 17223 HXio_fullread( 17224\series bold 17225int 17226\series default 17227 fd, 17228\series bold 17229void * 17230\series default 17231buf, 17232\series bold 17233size_t 17234\series default 17235 size, 17236\series bold 17237unsigned int 17238\series default 17239 flags); 17240\begin_inset Index idx 17241status open 17242 17243\begin_layout Plain Layout 17244 17245\family typewriter 17246HXio_fullread 17247\end_layout 17248 17249\end_inset 17250 17251 17252\begin_inset Newline newline 17253\end_inset 17254 17255 17256\series bold 17257ssize_t 17258\series default 17259 HXio_fullwrite( 17260\series bold 17261int 17262\series default 17263 fd, 17264\series bold 17265const void * 17266\series default 17267buf, 17268\series bold 17269size_t 17270\series default 17271 size, 17272\series bold 17273unsigned int 17274\series default 17275 flags); 17276\begin_inset Index idx 17277status open 17278 17279\begin_layout Plain Layout 17280 17281\family typewriter 17282HXio_fullwrite 17283\end_layout 17284 17285\end_inset 17286 17287 17288\end_layout 17289 17290\begin_layout Standard 17291Since plain 17292\family typewriter 17293read 17294\family default 17295(2) and 17296\family typewriter 17297write 17298\family default 17299(2) may process only part of the buffer 17300\begin_inset space ~ 17301\end_inset 17302 17303— even more likely so with sockets 17304\begin_inset space ~ 17305\end_inset 17306 17307—, libHX provides two functions that calls these in a loop to retry said 17308 operations until the full amount has been processed. 17309 Since 17310\family typewriter 17311read 17312\family default 17313 and 17314\family typewriter 17315write 17316\family default 17317 can also be used with socket file descriptors, so can these. 17318\end_layout 17319 17320\begin_layout Standard 17321\begin_inset Newpage clearpage 17322\end_inset 17323 17324 17325\end_layout 17326 17327\begin_layout Part 17328Options and Configuration Files 17329\end_layout 17330 17331\begin_layout Section 17332Option parsing 17333\begin_inset CommandInset label 17334LatexCommand label 17335name "sec:option" 17336 17337\end_inset 17338 17339 17340\end_layout 17341 17342\begin_layout Standard 17343libHX uses a table-based approach like libpopt 17344\begin_inset Foot 17345status open 17346 17347\begin_layout Plain Layout 17348The alternative would be an iterative, open-coded approach like 17349\family typewriter 17350getopt 17351\family default 17352(3) requires. 17353\end_layout 17354 17355\end_inset 17356 17357. 17358 It provides for both long and short options and the different styles associated 17359 with them, such as absence or presence of an equals sign for long options 17360 ( 17361\family typewriter 17362--foo=bar 17363\family default 17364 and 17365\family typewriter 17366--foo bar 17367\family default 17368), bundling (writing 17369\family typewriter 17370-abc 17371\family default 17372 for non-argument taking options 17373\family typewriter 17374-a -b -c 17375\family default 17376), squashing (writing 17377\family typewriter 17378-fbar 17379\family default 17380 for an argument-requiring option 17381\family typewriter 17382-f 17383\begin_inset space ~ 17384\end_inset 17385 17386bar 17387\family default 17388). 17389 The 17390\begin_inset Quotes eld 17391\end_inset 17392 17393lone dash 17394\begin_inset Quotes erd 17395\end_inset 17396 17397 that is often used to indicate standard input or standard output, is correctly 17398 handled 17399\begin_inset Foot 17400status open 17401 17402\begin_layout Plain Layout 17403popt failed to do this for a long time. 17404\end_layout 17405 17406\end_inset 17407 17408, as in 17409\family typewriter 17410-f 17411\begin_inset space ~ 17412\end_inset 17413 17414- 17415\family default 17416. 17417\end_layout 17418 17419\begin_layout Standard 17420A table-based approach allows for the parser to run as one atomic block 17421 of code (callbacks are, by definition, 17422\begin_inset Quotes eld 17423\end_inset 17424 17425special 17426\begin_inset Quotes erd 17427\end_inset 17428 17429 exceptions), making it more opaque than an open-coded 17430\family typewriter 17431getopt 17432\family default 17433(3) loop. 17434 You give it your argument vector and the table, snip the finger (call the 17435 parser function once), and it is done. 17436 In getopt on the other hand, the 17437\family typewriter 17438getopt 17439\family default 17440 function returns for every argument it parsed and needs to be called repeatedly. 17441\end_layout 17442 17443\begin_layout Subsection 17444Synopsis 17445\begin_inset CommandInset label 17446LatexCommand label 17447name "subsec:option-synopsis" 17448 17449\end_inset 17450 17451 17452\end_layout 17453 17454\begin_layout LyX-Code 17455 17456\series bold 17457#include 17458\series default 17459 <libHX/option.h> 17460\begin_inset Index idx 17461status open 17462 17463\begin_layout Plain Layout 17464 17465\family typewriter 17466libHX/option.h 17467\end_layout 17468 17469\end_inset 17470 17471 17472\begin_inset Newline newline 17473\end_inset 17474 17475 17476\begin_inset Newline newline 17477\end_inset 17478 17479 17480\series bold 17481struct 17482\series default 17483 HXoption { 17484\begin_inset Index idx 17485status open 17486 17487\begin_layout Plain Layout 17488 17489\family typewriter 17490struct HXoption 17491\end_layout 17492 17493\end_inset 17494 17495 17496\begin_inset Newline newline 17497\end_inset 17498 17499 17500\series bold 17501const char 17502\series default 17503 *ln; 17504\begin_inset Newline newline 17505\end_inset 17506 17507 17508\series bold 17509char 17510\series default 17511 sh; 17512\begin_inset Newline newline 17513\end_inset 17514 17515 17516\series bold 17517unsigned int 17518\series default 17519 type; 17520\begin_inset Newline newline 17521\end_inset 17522 17523 17524\series bold 17525void * 17526\series default 17527ptr, 17528\series bold 17529* 17530\series default 17531uptr; 17532\begin_inset Newline newline 17533\end_inset 17534 17535 17536\series bold 17537void (* 17538\series default 17539cb 17540\series bold 17541) 17542\series default 17543( 17544\series bold 17545const struct 17546\series default 17547 HXoptcb 17548\series bold 17549* 17550\series default 17551); 17552\begin_inset Newline newline 17553\end_inset 17554 17555 17556\series bold 17557int 17558\series default 17559 val; 17560\begin_inset Newline newline 17561\end_inset 17562 17563 17564\series bold 17565const char * 17566\series default 17567help, 17568\series bold 17569* 17570\series default 17571htyp; 17572\begin_inset Newline newline 17573\end_inset 17574 17575}; 17576\begin_inset Newline newline 17577\end_inset 17578 17579 17580\begin_inset Newline newline 17581\end_inset 17582 17583 17584\series bold 17585int 17586\series default 17587 HX_getopt( 17588\series bold 17589const struct 17590\series default 17591 HXoption 17592\series bold 17593* 17594\series default 17595options_table, 17596\series bold 17597int * 17598\series default 17599argc, 17600\begin_inset Newline newline 17601\end_inset 17602 17603 17604\series bold 17605const char *** 17606\series default 17607argv, 17608\series bold 17609unsigned int 17610\series default 17611 flags); 17612\end_layout 17613 17614\begin_layout Standard 17615The various fields of 17616\family typewriter 17617struct HXoption 17618\family default 17619 are: 17620\end_layout 17621 17622\begin_layout Description 17623 17624\family typewriter 17625ln 17626\family default 17627 The long option name, if any. 17628 May be 17629\family typewriter 17630NULL 17631\family default 17632 if none is to be assigned for this entry. 17633\end_layout 17634 17635\begin_layout Description 17636 17637\family typewriter 17638sh 17639\family default 17640 The short option name/character, if any. 17641 May be 17642\family typewriter 17643' 17644\backslash 176450' 17646\family default 17647 if none is to be assigned for this entry. 17648\end_layout 17649 17650\begin_layout Description 17651 17652\family typewriter 17653type 17654\family default 17655 The type of the entry, essentially denoting the type of the target variable. 17656\end_layout 17657 17658\begin_layout Description 17659 17660\family typewriter 17661val 17662\family default 17663 An integer value to be stored into 17664\family typewriter 17665*(int 17666\begin_inset space ~ 17667\end_inset 17668 17669*)ptr 17670\family default 17671 when 17672\family typewriter 17673HXTYPE_IVAL 17674\family default 17675 is used. 17676\end_layout 17677 17678\begin_layout Description 17679 17680\family typewriter 17681ptr 17682\family default 17683 A pointer to the variable so that the option parser can store the requested 17684 data in it. 17685 The pointer may be 17686\family typewriter 17687NULL 17688\family default 17689 in which case no data is stored (but 17690\family typewriter 17691cb 17692\family default 17693 is still called if defined, with the data). 17694\end_layout 17695 17696\begin_layout Description 17697 17698\family typewriter 17699uptr 17700\family default 17701 A user-supplied pointer. 17702 Its value is passed verbatim to the callback, and may be used for any purpose 17703 the user wishes. 17704 If 17705\family typewriter 17706type 17707\family default 17708 is 17709\family typewriter 17710HXTYPE_SVAL 17711\family default 17712, it is the value in 17713\family typewriter 17714uptr 17715\family default 17716 that will be used to populate 17717\family typewriter 17718*(const char 17719\begin_inset space ~ 17720\end_inset 17721 17722**)ptr 17723\family default 17724. 17725 (The original 17726\family typewriter 17727.sval 17728\family default 17729 field has been removed in libHX 3.12.) 17730\end_layout 17731 17732\begin_layout Description 17733 17734\family typewriter 17735cb 17736\family default 17737 If not 17738\family typewriter 17739NULL 17740\family default 17741, call out to the referenced function after the option has been parsed (and 17742 the results possibly be stored in 17743\family typewriter 17744ptr 17745\family default 17746) 17747\end_layout 17748 17749\begin_layout Description 17750 17751\family typewriter 17752help 17753\family default 17754 A help string that is shown for the option when the option table is dumped 17755 by request (e. 17756\begin_inset space \thinspace{} 17757\end_inset 17758 17759g. 17760\begin_inset space \space{} 17761\end_inset 17762 17763 17764\family typewriter 17765yourprgram --help 17766\family default 17767) 17768\end_layout 17769 17770\begin_layout Description 17771 17772\family typewriter 17773htyp 17774\family default 17775 String containing a keyword to aid the user in understanding the available 17776 options during dump. 17777 See examples. 17778\end_layout 17779 17780\begin_layout Standard 17781Due to the amount of fields, it is advised to use C99 named initializers 17782 to populate a struct, as they allow to omit unspecified fields, and assume 17783 no specific order of the members: 17784\end_layout 17785 17786\begin_layout LyX-Code 17787 17788\series bold 17789struct 17790\series default 17791 HXoption e = {.sh = 'f', .help = "Force"}; 17792\end_layout 17793 17794\begin_layout Standard 17795It is a sad fact that C++ has not gotten around to implement these yet. 17796 It is advised to put the option parsing code into a separate 17797\family typewriter 17798.c 17799\family default 17800 file that can then be compiled in C99 rather than C++ mode. 17801\end_layout 17802 17803\begin_layout Subsection 17804Type map 17805\begin_inset CommandInset label 17806LatexCommand label 17807name "subsec:option-types" 17808 17809\end_inset 17810 17811 17812\end_layout 17813 17814\begin_layout Description 17815 17816\family typewriter 17817HXTYPE_NONE 17818\series medium 17819 17820\begin_inset Index idx 17821status open 17822 17823\begin_layout Plain Layout 17824 17825\family typewriter 17826\series medium 17827HXTYPE_NONE 17828\end_layout 17829 17830\end_inset 17831 17832 17833\family default 17834\series default 17835 The option does not take any argument, but the presence of the option may 17836 be record by setting the 17837\family typewriter 17838*(int 17839\begin_inset space ~ 17840\end_inset 17841 17842*)ptr 17843\family default 17844 to 1. 17845 Other rules apply when 17846\family typewriter 17847HXOPT_\SpecialChar softhyphen 17848INC 17849\family default 17850 or 17851\family typewriter 17852HXOPT_\SpecialChar softhyphen 17853DEC 17854\family default 17855 are specified as flags (see section 17856\begin_inset space ~ 17857\end_inset 17858 17859 17860\begin_inset CommandInset ref 17861LatexCommand ref 17862reference "subsec:option-flags" 17863 17864\end_inset 17865 17866). 17867\end_layout 17868 17869\begin_layout Description 17870 17871\family typewriter 17872HXTYPE_VAL 17873\series medium 17874 17875\begin_inset Index idx 17876status open 17877 17878\begin_layout Plain Layout 17879 17880\family typewriter 17881\series medium 17882HXTYPE_VAL 17883\end_layout 17884 17885\end_inset 17886 17887 17888\family default 17889\series default 17890 Use the integer value specified by 17891\family typewriter 17892ival 17893\family default 17894 and store it in 17895\family typewriter 17896*(int 17897\begin_inset space ~ 17898\end_inset 17899 17900*)ptr 17901\family default 17902. 17903\end_layout 17904 17905\begin_layout Description 17906 17907\family typewriter 17908HXTYPE_SVAL 17909\series medium 17910 17911\begin_inset Index idx 17912status open 17913 17914\begin_layout Plain Layout 17915 17916\family typewriter 17917\series medium 17918HXTYPE_SVAL 17919\end_layout 17920 17921\end_inset 17922 17923 17924\family default 17925\series default 17926 Use the memory location specified by 17927\family typewriter 17928sval 17929\family default 17930 and store it in 17931\family typewriter 17932*(const char 17933\begin_inset space ~ 17934\end_inset 17935 17936**)ptr 17937\family default 17938. 17939\end_layout 17940 17941\begin_layout Description 17942 17943\family typewriter 17944HXTYPE_BOOL 17945\series medium 17946 17947\begin_inset Index idx 17948status open 17949 17950\begin_layout Plain Layout 17951 17952\family typewriter 17953\series medium 17954HXTYPE_BOOL 17955\end_layout 17956 17957\end_inset 17958 17959 17960\family default 17961\series default 17962 Interpret the supplied argument as a boolean descriptive (must be 17963\begin_inset Quotes eld 17964\end_inset 17965 17966yes 17967\begin_inset Quotes erd 17968\end_inset 17969 17970, 17971\begin_inset Quotes eld 17972\end_inset 17973 17974no 17975\begin_inset Quotes erd 17976\end_inset 17977 17978, 17979\begin_inset Quotes eld 17980\end_inset 17981 17982on 17983\begin_inset Quotes erd 17984\end_inset 17985 17986, 17987\begin_inset Quotes eld 17988\end_inset 17989 17990off 17991\begin_inset Quotes erd 17992\end_inset 17993 17994, 17995\begin_inset Quotes eld 17996\end_inset 17997 17998true 17999\begin_inset Quotes erd 18000\end_inset 18001 18002, 18003\begin_inset Quotes eld 18004\end_inset 18005 18006false 18007\begin_inset Quotes erd 18008\end_inset 18009 18010, 18011\begin_inset Quotes eld 18012\end_inset 18013 180140 18015\begin_inset Quotes erd 18016\end_inset 18017 18018 or 18019\begin_inset Quotes eld 18020\end_inset 18021 180221 18023\begin_inset Quotes erd 18024\end_inset 18025 18026) and store the result in 18027\family typewriter 18028*(int 18029\begin_inset space ~ 18030\end_inset 18031 18032*)ptr 18033\family default 18034. 18035\end_layout 18036 18037\begin_layout Description 18038 18039\family typewriter 18040HXTYPE_STRING 18041\begin_inset Index idx 18042status open 18043 18044\begin_layout Plain Layout 18045 18046\family typewriter 18047HXTYPE_STRING 18048\end_layout 18049 18050\end_inset 18051 18052 18053\family default 18054 The argument string is duplicated to a new memory region and the resulting 18055 pointer stored into 18056\family typewriter 18057*(char 18058\begin_inset space ~ 18059\end_inset 18060 18061**)ptr 18062\family default 18063. 18064 This incurs an allocation so that subsequently modifying the original argument 18065 string in any way will not falsely propagate. 18066\end_layout 18067 18068\begin_layout Description 18069 18070\family typewriter 18071HXTYPE_STRDQ 18072\series medium 18073 18074\begin_inset Index idx 18075status open 18076 18077\begin_layout Plain Layout 18078 18079\family typewriter 18080\series medium 18081HXTYPE_STRDQ 18082\end_layout 18083 18084\end_inset 18085 18086 18087\family default 18088\series default 18089 The argument string is duplicated to a new memory region and the resulting 18090 pointer is added to the given HXdeque. 18091 Note that you often need to use deferred initialization of the options 18092 table to avoid putting 18093\family typewriter 18094NULL 18095\family default 18096 into the entry. 18097 See section 18098\begin_inset space ~ 18099\end_inset 18100 18101 18102\begin_inset CommandInset ref 18103LatexCommand ref 18104reference "subsec:option-pitfalls-static" 18105 18106\end_inset 18107 18108. 18109\end_layout 18110 18111\begin_layout Standard 18112The following table lists the types that map to the common integral and 18113 floating-point types. 18114 Signed and unsigned integeral types are processed using 18115\family typewriter 18116strtol 18117\family default 18118 and 18119\family typewriter 18120strtoul 18121\family default 18122, respectively. 18123 18124\family typewriter 18125strtol 18126\family default 18127 and 18128\family typewriter 18129strtoul 18130\family default 18131 will be called with automatic base detection. 18132 This usually means that a leading 18133\begin_inset Quotes eld 18134\end_inset 18135 181360 18137\begin_inset Quotes erd 18138\end_inset 18139 18140 indicates the string is given in octal (8) base, a leading 18141\begin_inset Quotes eld 18142\end_inset 18143 181440x 18145\begin_inset Quotes erd 18146\end_inset 18147 18148 indicates hexadecimal (16) base, and decimal (10) otherwise. 18149 18150\family typewriter 18151HXTYPE_\SpecialChar softhyphen 18152LLONG 18153\family default 18154, 18155\family typewriter 18156 HXTYPE_\SpecialChar softhyphen 18157ULLONG 18158\family default 18159, 18160\family typewriter 18161 HXTYPE_\SpecialChar softhyphen 18162INT64 18163\family default 18164 and 18165\family typewriter 18166 HXTYPE_\SpecialChar softhyphen 18167UINT64 18168\family default 18169 use 18170\family typewriter 18171 strtoll 18172\family default 18173 and/or 18174\family typewriter 18175 strtoull 18176\family default 18177, which may not be available on all platforms. 18178\begin_inset Separator latexpar 18179\end_inset 18180 18181 18182\end_layout 18183 18184\begin_layout Standard 18185\align center 18186\begin_inset Float table 18187placement H 18188wide false 18189sideways false 18190status open 18191 18192\begin_layout Plain Layout 18193\align center 18194\begin_inset Tabular 18195<lyxtabular version="3" rows="12" columns="4"> 18196<features tabularvalignment="middle"> 18197<column alignment="center" valignment="top"> 18198<column alignment="center" valignment="bottom"> 18199<column alignment="center" valignment="top"> 18200<column alignment="center" valignment="top"> 18201<row> 18202<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none"> 18203\begin_inset Text 18204 18205\begin_layout Plain Layout 18206 18207\family typewriter 18208\series bold 18209type 18210\end_layout 18211 18212\end_inset 18213</cell> 18214<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none"> 18215\begin_inset Text 18216 18217\begin_layout Plain Layout 18218 18219\series bold 18220Type of pointee 18221\end_layout 18222 18223\end_inset 18224</cell> 18225<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none"> 18226\begin_inset Text 18227 18228\begin_layout Plain Layout 18229 18230\series bold 18231type 18232\end_layout 18233 18234\end_inset 18235</cell> 18236<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none"> 18237\begin_inset Text 18238 18239\begin_layout Plain Layout 18240 18241\series bold 18242Type of pointee 18243\end_layout 18244 18245\end_inset 18246</cell> 18247</row> 18248<row> 18249<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> 18250\begin_inset Text 18251 18252\begin_layout Plain Layout 18253 18254\family typewriter 18255HXTYPE_CHAR 18256\begin_inset Index idx 18257status open 18258 18259\begin_layout Plain Layout 18260 18261\family typewriter 18262HXTYPE_CHAR 18263\end_layout 18264 18265\end_inset 18266 18267 18268\end_layout 18269 18270\end_inset 18271</cell> 18272<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> 18273\begin_inset Text 18274 18275\begin_layout Plain Layout 18276 18277\family typewriter 18278char 18279\end_layout 18280 18281\end_inset 18282</cell> 18283<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> 18284\begin_inset Text 18285 18286\begin_layout Plain Layout 18287 18288\family typewriter 18289HXTYPE_INT8 18290\begin_inset Index idx 18291status open 18292 18293\begin_layout Plain Layout 18294 18295\family typewriter 18296HXTYPE_INT8 18297\end_layout 18298 18299\end_inset 18300 18301 18302\end_layout 18303 18304\end_inset 18305</cell> 18306<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> 18307\begin_inset Text 18308 18309\begin_layout Plain Layout 18310 18311\family typewriter 18312int8_t 18313\end_layout 18314 18315\end_inset 18316</cell> 18317</row> 18318<row> 18319<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> 18320\begin_inset Text 18321 18322\begin_layout Plain Layout 18323 18324\family typewriter 18325HXTYPE_UCHAR 18326\begin_inset Index idx 18327status open 18328 18329\begin_layout Plain Layout 18330 18331\family typewriter 18332HXTYPE_UCHAR 18333\end_layout 18334 18335\end_inset 18336 18337 18338\end_layout 18339 18340\end_inset 18341</cell> 18342<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> 18343\begin_inset Text 18344 18345\begin_layout Plain Layout 18346 18347\family typewriter 18348unsigned char 18349\end_layout 18350 18351\end_inset 18352</cell> 18353<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> 18354\begin_inset Text 18355 18356\begin_layout Plain Layout 18357 18358\family typewriter 18359HXTYPE_UINT8 18360\begin_inset Index idx 18361status open 18362 18363\begin_layout Plain Layout 18364 18365\family typewriter 18366HXTYPE_UINT8 18367\end_layout 18368 18369\end_inset 18370 18371 18372\end_layout 18373 18374\end_inset 18375</cell> 18376<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> 18377\begin_inset Text 18378 18379\begin_layout Plain Layout 18380 18381\family typewriter 18382uint8_t 18383\end_layout 18384 18385\end_inset 18386</cell> 18387</row> 18388<row> 18389<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> 18390\begin_inset Text 18391 18392\begin_layout Plain Layout 18393 18394\family typewriter 18395HXTYPE_SHORT 18396\begin_inset Index idx 18397status open 18398 18399\begin_layout Plain Layout 18400 18401\family typewriter 18402HXTYPE_SHORT 18403\end_layout 18404 18405\end_inset 18406 18407 18408\end_layout 18409 18410\end_inset 18411</cell> 18412<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> 18413\begin_inset Text 18414 18415\begin_layout Plain Layout 18416 18417\family typewriter 18418short 18419\end_layout 18420 18421\end_inset 18422</cell> 18423<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> 18424\begin_inset Text 18425 18426\begin_layout Plain Layout 18427 18428\family typewriter 18429HXTYPE_INT16 18430\begin_inset Index idx 18431status open 18432 18433\begin_layout Plain Layout 18434 18435\family typewriter 18436HXTYPE_INT16 18437\end_layout 18438 18439\end_inset 18440 18441 18442\end_layout 18443 18444\end_inset 18445</cell> 18446<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> 18447\begin_inset Text 18448 18449\begin_layout Plain Layout 18450 18451\family typewriter 18452int16_t 18453\end_layout 18454 18455\end_inset 18456</cell> 18457</row> 18458<row> 18459<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> 18460\begin_inset Text 18461 18462\begin_layout Plain Layout 18463 18464\family typewriter 18465HXTYPE_USHORT 18466\begin_inset Index idx 18467status open 18468 18469\begin_layout Plain Layout 18470 18471\family typewriter 18472HXTYPE_USHORT 18473\end_layout 18474 18475\end_inset 18476 18477 18478\end_layout 18479 18480\end_inset 18481</cell> 18482<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> 18483\begin_inset Text 18484 18485\begin_layout Plain Layout 18486 18487\family typewriter 18488unsigned short 18489\end_layout 18490 18491\end_inset 18492</cell> 18493<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> 18494\begin_inset Text 18495 18496\begin_layout Plain Layout 18497 18498\family typewriter 18499HXTYPE_UINT16 18500\begin_inset Index idx 18501status open 18502 18503\begin_layout Plain Layout 18504 18505\family typewriter 18506HXTYPE_UINT16 18507\end_layout 18508 18509\end_inset 18510 18511 18512\end_layout 18513 18514\end_inset 18515</cell> 18516<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> 18517\begin_inset Text 18518 18519\begin_layout Plain Layout 18520 18521\family typewriter 18522uint16_t 18523\end_layout 18524 18525\end_inset 18526</cell> 18527</row> 18528<row> 18529<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> 18530\begin_inset Text 18531 18532\begin_layout Plain Layout 18533 18534\family typewriter 18535HXTYPE_INT 18536\begin_inset Index idx 18537status open 18538 18539\begin_layout Plain Layout 18540 18541\family typewriter 18542HXTYPE_INT 18543\end_layout 18544 18545\end_inset 18546 18547 18548\end_layout 18549 18550\end_inset 18551</cell> 18552<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> 18553\begin_inset Text 18554 18555\begin_layout Plain Layout 18556 18557\family typewriter 18558int 18559\end_layout 18560 18561\end_inset 18562</cell> 18563<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> 18564\begin_inset Text 18565 18566\begin_layout Plain Layout 18567 18568\family typewriter 18569HXTYPE_INT32 18570\begin_inset Index idx 18571status open 18572 18573\begin_layout Plain Layout 18574 18575\family typewriter 18576HXTYPE_INT32 18577\end_layout 18578 18579\end_inset 18580 18581 18582\end_layout 18583 18584\end_inset 18585</cell> 18586<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> 18587\begin_inset Text 18588 18589\begin_layout Plain Layout 18590 18591\family typewriter 18592int32_t 18593\end_layout 18594 18595\end_inset 18596</cell> 18597</row> 18598<row> 18599<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> 18600\begin_inset Text 18601 18602\begin_layout Plain Layout 18603 18604\family typewriter 18605HXTYPE_UINT 18606\begin_inset Index idx 18607status open 18608 18609\begin_layout Plain Layout 18610 18611\family typewriter 18612HXTYPE_UINT 18613\end_layout 18614 18615\end_inset 18616 18617 18618\end_layout 18619 18620\end_inset 18621</cell> 18622<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> 18623\begin_inset Text 18624 18625\begin_layout Plain Layout 18626 18627\family typewriter 18628unsigned int 18629\end_layout 18630 18631\end_inset 18632</cell> 18633<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> 18634\begin_inset Text 18635 18636\begin_layout Plain Layout 18637 18638\family typewriter 18639HXTYPE_UINT32 18640\begin_inset Index idx 18641status open 18642 18643\begin_layout Plain Layout 18644 18645\family typewriter 18646HXTYPE_UINT32 18647\end_layout 18648 18649\end_inset 18650 18651 18652\end_layout 18653 18654\end_inset 18655</cell> 18656<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> 18657\begin_inset Text 18658 18659\begin_layout Plain Layout 18660 18661\family typewriter 18662uint32_t 18663\end_layout 18664 18665\end_inset 18666</cell> 18667</row> 18668<row> 18669<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> 18670\begin_inset Text 18671 18672\begin_layout Plain Layout 18673 18674\family typewriter 18675HXTYPE_LONG 18676\begin_inset Index idx 18677status open 18678 18679\begin_layout Plain Layout 18680 18681\family typewriter 18682HXTYPE_LONG 18683\end_layout 18684 18685\end_inset 18686 18687 18688\end_layout 18689 18690\end_inset 18691</cell> 18692<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> 18693\begin_inset Text 18694 18695\begin_layout Plain Layout 18696 18697\family typewriter 18698long 18699\end_layout 18700 18701\end_inset 18702</cell> 18703<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> 18704\begin_inset Text 18705 18706\begin_layout Plain Layout 18707 18708\family typewriter 18709HXTYPE_INT64 18710\begin_inset Index idx 18711status open 18712 18713\begin_layout Plain Layout 18714 18715\family typewriter 18716HXTYPE_INT64 18717\end_layout 18718 18719\end_inset 18720 18721 18722\end_layout 18723 18724\end_inset 18725</cell> 18726<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> 18727\begin_inset Text 18728 18729\begin_layout Plain Layout 18730 18731\family typewriter 18732int64_t 18733\end_layout 18734 18735\end_inset 18736</cell> 18737</row> 18738<row> 18739<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> 18740\begin_inset Text 18741 18742\begin_layout Plain Layout 18743 18744\family typewriter 18745HXTYPE_ULONG 18746\begin_inset Index idx 18747status open 18748 18749\begin_layout Plain Layout 18750 18751\family typewriter 18752HXTYPE_ULONG 18753\end_layout 18754 18755\end_inset 18756 18757 18758\end_layout 18759 18760\end_inset 18761</cell> 18762<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> 18763\begin_inset Text 18764 18765\begin_layout Plain Layout 18766 18767\family typewriter 18768unsigned long 18769\end_layout 18770 18771\end_inset 18772</cell> 18773<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> 18774\begin_inset Text 18775 18776\begin_layout Plain Layout 18777 18778\family typewriter 18779HXTYPE_UINT64 18780\begin_inset Index idx 18781status open 18782 18783\begin_layout Plain Layout 18784 18785\family typewriter 18786HXTYPE_UINT64 18787\end_layout 18788 18789\end_inset 18790 18791 18792\end_layout 18793 18794\end_inset 18795</cell> 18796<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> 18797\begin_inset Text 18798 18799\begin_layout Plain Layout 18800 18801\family typewriter 18802uint64_t 18803\end_layout 18804 18805\end_inset 18806</cell> 18807</row> 18808<row> 18809<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> 18810\begin_inset Text 18811 18812\begin_layout Plain Layout 18813 18814\family typewriter 18815HXTYPE_LLONG 18816\begin_inset Index idx 18817status open 18818 18819\begin_layout Plain Layout 18820 18821\family typewriter 18822HXTYPE_LLONG 18823\end_layout 18824 18825\end_inset 18826 18827 18828\end_layout 18829 18830\end_inset 18831</cell> 18832<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> 18833\begin_inset Text 18834 18835\begin_layout Plain Layout 18836 18837\family typewriter 18838long long 18839\end_layout 18840 18841\end_inset 18842</cell> 18843<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> 18844\begin_inset Text 18845 18846\begin_layout Plain Layout 18847 18848\family typewriter 18849HXTYPE_FLOAT 18850\begin_inset Index idx 18851status open 18852 18853\begin_layout Plain Layout 18854 18855\family typewriter 18856HXTYPE_FLOAT 18857\end_layout 18858 18859\end_inset 18860 18861 18862\end_layout 18863 18864\end_inset 18865</cell> 18866<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> 18867\begin_inset Text 18868 18869\begin_layout Plain Layout 18870 18871\family typewriter 18872float 18873\end_layout 18874 18875\end_inset 18876</cell> 18877</row> 18878<row> 18879<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> 18880\begin_inset Text 18881 18882\begin_layout Plain Layout 18883 18884\family typewriter 18885HXTYPE_ULLONG 18886\begin_inset Index idx 18887status open 18888 18889\begin_layout Plain Layout 18890 18891\family typewriter 18892HXTYPE_ULLONG 18893\end_layout 18894 18895\end_inset 18896 18897 18898\end_layout 18899 18900\end_inset 18901</cell> 18902<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> 18903\begin_inset Text 18904 18905\begin_layout Plain Layout 18906 18907\family typewriter 18908unsigned long long 18909\end_layout 18910 18911\end_inset 18912</cell> 18913<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none"> 18914\begin_inset Text 18915 18916\begin_layout Plain Layout 18917 18918\family typewriter 18919HXTYPE_DOUBLE 18920\begin_inset Index idx 18921status open 18922 18923\begin_layout Plain Layout 18924 18925\family typewriter 18926HXTYPE_DOUBLE 18927\end_layout 18928 18929\end_inset 18930 18931 18932\end_layout 18933 18934\end_inset 18935</cell> 18936<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none"> 18937\begin_inset Text 18938 18939\begin_layout Plain Layout 18940 18941\family typewriter 18942double 18943\end_layout 18944 18945\end_inset 18946</cell> 18947</row> 18948<row> 18949<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none"> 18950\begin_inset Text 18951 18952\begin_layout Plain Layout 18953 18954\family typewriter 18955HXTYPE_SIZE_T 18956\family default 18957 18958\begin_inset Index idx 18959status open 18960 18961\begin_layout Plain Layout 18962 18963\family typewriter 18964HXTYPE_SIZE_T 18965\end_layout 18966 18967\end_inset 18968 18969 18970\end_layout 18971 18972\end_inset 18973</cell> 18974<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none"> 18975\begin_inset Text 18976 18977\begin_layout Plain Layout 18978 18979\family typewriter 18980size_t 18981\end_layout 18982 18983\end_inset 18984</cell> 18985<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none"> 18986\begin_inset Text 18987 18988\begin_layout Plain Layout 18989 18990\end_layout 18991 18992\end_inset 18993</cell> 18994<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none"> 18995\begin_inset Text 18996 18997\begin_layout Plain Layout 18998 18999\end_layout 19000 19001\end_inset 19002</cell> 19003</row> 19004</lyxtabular> 19005 19006\end_inset 19007 19008 19009\end_layout 19010 19011\begin_layout Plain Layout 19012\begin_inset Caption Standard 19013 19014\begin_layout Plain Layout 19015Integral and floating-point types for the libHX option parser 19016\end_layout 19017 19018\end_inset 19019 19020 19021\end_layout 19022 19023\end_inset 19024 19025 19026\end_layout 19027 19028\begin_layout Standard 19029 19030\family typewriter 19031HXTYPE_\SpecialChar softhyphen 19032FLOAT 19033\family default 19034 and 19035\family typewriter 19036HXTYPE_\SpecialChar softhyphen 19037DOUBLE 19038\family default 19039 make use of 19040\family typewriter 19041strtod 19042\family default 19043 ( 19044\family typewriter 19045strtof 19046\family default 19047 is not used). 19048 A corresponding 19049\family typewriter 19050type 19051\family default 19052 for the 19053\begin_inset Quotes eld 19054\end_inset 19055 19056long double 19057\begin_inset Quotes erd 19058\end_inset 19059 19060 format is not specified, but may be implemented on behalf of the user via 19061 a callback (see section 19062\begin_inset space ~ 19063\end_inset 19064 19065 19066\begin_inset CommandInset ref 19067LatexCommand ref 19068reference "subsec:option-example-cb" 19069 19070\end_inset 19071 19072). 19073\end_layout 19074 19075\begin_layout Subsection 19076Flags 19077\begin_inset CommandInset label 19078LatexCommand label 19079name "subsec:option-flags" 19080 19081\end_inset 19082 19083 19084\end_layout 19085 19086\begin_layout Standard 19087Flags can be combined into the 19088\family typewriter 19089type 19090\family default 19091 parameter by OR'ing them. 19092 It is valid to not specify any flags at all, but most flags collide with 19093 one another. 19094\end_layout 19095 19096\begin_layout Description 19097 19098\family typewriter 19099HXOPT_INC 19100\series medium 19101 19102\begin_inset Index idx 19103status open 19104 19105\begin_layout Plain Layout 19106 19107\family typewriter 19108\series medium 19109HXOPT_INC 19110\end_layout 19111 19112\end_inset 19113 19114 19115\family default 19116\series default 19117 Perform an increment on the memory location specified by the 19118\family typewriter 19119*(int 19120\begin_inset space ~ 19121\end_inset 19122 19123*)ptr 19124\family default 19125 pointer. 19126 Make sure the referenced variable is initialized before! 19127\end_layout 19128 19129\begin_layout Description 19130 19131\family typewriter 19132HXOPT_DEC 19133\family default 19134\series medium 19135 19136\begin_inset Index idx 19137status open 19138 19139\begin_layout Plain Layout 19140 19141\family typewriter 19142HXOPT_DEC 19143\end_layout 19144 19145\end_inset 19146 19147 19148\series default 19149 Perform a decrement on the pointee. 19150\end_layout 19151 19152\begin_layout Standard 19153Only one of 19154\family typewriter 19155HXOPT_\SpecialChar softhyphen 19156INC 19157\family default 19158 and 19159\family typewriter 19160HXOPT_\SpecialChar softhyphen 19161DEC 19162\family default 19163 may be specified at a time, and they require that the base type is 19164\family typewriter 19165HXTYPE_\SpecialChar softhyphen 19166NONE 19167\family default 19168, or they will have no effect. 19169 An example may be found in section 19170\begin_inset space ~ 19171\end_inset 19172 19173 19174\begin_inset CommandInset ref 19175LatexCommand ref 19176reference "subsec:option-example-incdec" 19177 19178\end_inset 19179 19180. 19181\end_layout 19182 19183\begin_layout Description 19184 19185\family typewriter 19186HXOPT_NOT 19187\series medium 19188 19189\begin_inset Index idx 19190status open 19191 19192\begin_layout Plain Layout 19193 19194\family typewriter 19195\series medium 19196HXOPT_NOT 19197\end_layout 19198 19199\end_inset 19200 19201 19202\family default 19203\series default 19204 Binary negation of the argument directly after reading it from the command 19205 line into memory. 19206 Any of the three following operations are executed with the already-negated 19207 value. 19208\end_layout 19209 19210\begin_layout Description 19211 19212\family typewriter 19213HXOPT_OR 19214\series medium 19215 19216\begin_inset Index idx 19217status open 19218 19219\begin_layout Plain Layout 19220 19221\family typewriter 19222HXOPT_OR 19223\end_layout 19224 19225\end_inset 19226 19227 19228\family default 19229\series default 19230 Binary 19231\begin_inset Quotes eld 19232\end_inset 19233 19234OR 19235\begin_inset Quotes erd 19236\end_inset 19237 19238s the pointee with the specified\SpecialChar breakableslash 19239transformed value. 19240\end_layout 19241 19242\begin_layout Description 19243 19244\family typewriter 19245HXOPT_AND 19246\series medium 19247 19248\begin_inset Index idx 19249status open 19250 19251\begin_layout Plain Layout 19252 19253\family typewriter 19254\series medium 19255HXOPT_AND 19256\end_layout 19257 19258\end_inset 19259 19260 19261\family default 19262\series default 19263 Binary 19264\begin_inset Quotes eld 19265\end_inset 19266 19267AND 19268\begin_inset Quotes erd 19269\end_inset 19270 19271s the pointee with the specified\SpecialChar breakableslash 19272transformed value. 19273\end_layout 19274 19275\begin_layout Description 19276 19277\family typewriter 19278HXOPT_XOR 19279\series medium 19280 19281\begin_inset Index idx 19282status open 19283 19284\begin_layout Plain Layout 19285 19286\family typewriter 19287\series medium 19288HXOPT_XOR 19289\end_layout 19290 19291\end_inset 19292 19293 19294\family default 19295\series default 19296 Binary 19297\begin_inset Quotes eld 19298\end_inset 19299 19300XOR 19301\begin_inset Quotes erd 19302\end_inset 19303 19304s the pointee with the specified\SpecialChar breakableslash 19305transformed value. 19306\end_layout 19307 19308\begin_layout Standard 19309Only one of ( 19310\family typewriter 19311HXOPT_OR 19312\family default 19313, 19314\family typewriter 19315HXOPT_\SpecialChar softhyphen 19316AND 19317\family default 19318, 19319\family typewriter 19320HXOPT_\SpecialChar softhyphen 19321XOR 19322\family default 19323) may be specified at a time, but they can be used with any integral 19324\family typewriter 19325type 19326\family default 19327 ( 19328\family typewriter 19329HXTYPE_\SpecialChar softhyphen 19330UINT 19331\family default 19332, 19333\family typewriter 19334HXTYPE_\SpecialChar softhyphen 19335ULONG 19336\family default 19337, etc.). 19338 An example can be found in section 19339\begin_inset space ~ 19340\end_inset 19341 19342 19343\begin_inset CommandInset ref 19344LatexCommand ref 19345reference "subsec:option-example-mask" 19346 19347\end_inset 19348 19349. 19350\end_layout 19351 19352\begin_layout Description 19353 19354\family typewriter 19355HXOPT_OPTIONAL 19356\series medium 19357 19358\begin_inset Index idx 19359status open 19360 19361\begin_layout Plain Layout 19362 19363\family typewriter 19364\series medium 19365HXOPT_OPTIONAL 19366\end_layout 19367 19368\end_inset 19369 19370 19371\family default 19372\series default 19373 This flag allows for an option to take zero or one argument. 19374 Needless to say that this can be confusing to the user. 19375 19376\shape italic 19377iptables 19378\shape default 19379's 19380\begin_inset Quotes eld 19381\end_inset 19382 19383 19384\family typewriter 19385-L 19386\family default 19387 19388\begin_inset Quotes erd 19389\end_inset 19390 19391 option for example is one of this kind (though it does not use the libHX 19392 option parser). 19393 When this flag is used, 19394\begin_inset Quotes eld 19395\end_inset 19396 19397 19398\family typewriter 19399-f -b 19400\family default 19401 19402\begin_inset Quotes erd 19403\end_inset 19404 19405 is interpreted as 19406\family typewriter 19407-f 19408\family default 19409 without an argument, as is 19410\begin_inset Quotes eld 19411\end_inset 19412 19413 19414\family typewriter 19415-f --bar 19416\family default 19417 19418\begin_inset Quotes erd 19419\end_inset 19420 19421 19422\begin_inset space ~ 19423\end_inset 19424 19425— things that look like an option take precedence over an option with an 19426 optional argument. 19427 19428\begin_inset Quotes eld 19429\end_inset 19430 19431 19432\family typewriter 19433-f - 19434\family default 19435 19436\begin_inset Quotes erd 19437\end_inset 19438 19439 of course denotes an option with an argument, as 19440\begin_inset Quotes eld 19441\end_inset 19442 19443 19444\family typewriter 19445- 19446\family default 19447 19448\begin_inset Quotes erd 19449\end_inset 19450 19451 is used to indicate standard input/output. 19452\end_layout 19453 19454\begin_layout Subsection 19455Special entries 19456\end_layout 19457 19458\begin_layout Standard 19459HXopt provides two special entries via macros: 19460\end_layout 19461 19462\begin_layout Description 19463 19464\family typewriter 19465HXOPT_AUTOHELP 19466\series medium 19467 19468\begin_inset Index idx 19469status open 19470 19471\begin_layout Plain Layout 19472 19473\family typewriter 19474\series medium 19475HXOPT_AUTOHELP 19476\end_layout 19477 19478\end_inset 19479 19480 19481\family default 19482\series default 19483 Adds entries to recognize 19484\begin_inset Quotes eld 19485\end_inset 19486 19487 19488\family typewriter 19489-? 19490\family default 19491 19492\begin_inset Quotes erd 19493\end_inset 19494 19495 and 19496\begin_inset Quotes eld 19497\end_inset 19498 19499 19500\family typewriter 19501--help 19502\family default 19503 19504\begin_inset Quotes erd 19505\end_inset 19506 19507 that will display the (long-format) help screen, and 19508\begin_inset Quotes eld 19509\end_inset 19510 19511 19512\family typewriter 19513--usage 19514\family default 19515 19516\begin_inset Quotes erd 19517\end_inset 19518 19519 that will display the short option syntax overview. 19520 All three options will exit the program afterwards. 19521\end_layout 19522 19523\begin_layout Description 19524 19525\family typewriter 19526HXOPT_TABLEEND 19527\series medium 19528 19529\begin_inset Index idx 19530status open 19531 19532\begin_layout Plain Layout 19533 19534\family typewriter 19535\series medium 19536HXOPT_TABLEEND 19537\end_layout 19538 19539\end_inset 19540 19541 19542\family default 19543\series default 19544 This sentinel marks the end of the table and is required on all tables. 19545 (See examples for details.) 19546\end_layout 19547 19548\begin_layout Subsection 19549Invoking the parser 19550\end_layout 19551 19552\begin_layout LyX-Code 19553 19554\series bold 19555int 19556\series default 19557 HX_getopt( 19558\series bold 19559const struct 19560\series default 19561 HXoption 19562\series bold 19563* 19564\series default 19565options_table, 19566\series bold 19567int * 19568\series default 19569argc, 19570\begin_inset Newline newline 19571\end_inset 19572 19573 19574\series bold 19575const char *** 19576\series default 19577argv, 19578\series bold 19579unsigned int 19580\series default 19581 flags); 19582\begin_inset Index idx 19583status open 19584 19585\begin_layout Plain Layout 19586 19587\family typewriter 19588HX_getopt 19589\end_layout 19590 19591\end_inset 19592 19593 19594\end_layout 19595 19596\begin_layout Standard 19597 19598\family typewriter 19599HX_getopt 19600\family default 19601 is the actual parsing function. 19602 It takes the option table, and a pointer to your 19603\family typewriter 19604argc 19605\family default 19606 and 19607\family typewriter 19608argv 19609\family default 19610 variables that you get from the 19611\family typewriter 19612main 19613\family default 19614 function. 19615 The parser will, unlike GNU getopt, literally 19616\begin_inset Quotes eld 19617\end_inset 19618 19619eat 19620\begin_inset Quotes erd 19621\end_inset 19622 19623 all options and their arguments, leaving only non-options in 19624\family typewriter 19625argv 19626\family default 19627, and 19628\family typewriter 19629argc 19630\family default 19631 updated, when finished. 19632 This is similar to how Perl's 19633\begin_inset Quotes eld 19634\end_inset 19635 19636Getopt::Long 19637\begin_inset Quotes erd 19638\end_inset 19639 19640 module works. 19641 Additional flags can control the exact behavior of 19642\family typewriter 19643HX_getopt 19644\family default 19645: 19646\end_layout 19647 19648\begin_layout Description 19649 19650\family typewriter 19651HXOPT_PTHRU 19652\series medium 19653 19654\begin_inset Index idx 19655status open 19656 19657\begin_layout Plain Layout 19658 19659\family typewriter 19660\series medium 19661HXOPT_PTHRU 19662\end_layout 19663 19664\end_inset 19665 19666 19667\family default 19668\series default 19669 19670\begin_inset Quotes eld 19671\end_inset 19672 19673Passthrough mode 19674\begin_inset Quotes erd 19675\end_inset 19676 19677. 19678 Any unknown options are not 19679\begin_inset Quotes eld 19680\end_inset 19681 19682eaten 19683\begin_inset Quotes erd 19684\end_inset 19685 19686 and are instead passed back into the resulting 19687\family typewriter 19688argv 19689\family default 19690 array. 19691\end_layout 19692 19693\begin_layout Description 19694 19695\family typewriter 19696HXOPT_QUIET 19697\series medium 19698 19699\begin_inset Index idx 19700status open 19701 19702\begin_layout Plain Layout 19703 19704\family typewriter 19705\series medium 19706HXOPT_QUIET 19707\end_layout 19708 19709\end_inset 19710 19711 19712\family default 19713\series default 19714 Do not print any diagnostics when encountering errors in the user's input. 19715\end_layout 19716 19717\begin_layout Description 19718 19719\family typewriter 19720HXOPT_HELPONERR 19721\series medium 19722 19723\begin_inset Index idx 19724status open 19725 19726\begin_layout Plain Layout 19727 19728\family typewriter 19729HXOPT_HELPONERR 19730\end_layout 19731 19732\end_inset 19733 19734 19735\family default 19736\series default 19737 Display the (long-format) help when an error, such as an unknown option 19738 or a violation of syntax, is encountered. 19739\end_layout 19740 19741\begin_layout Description 19742 19743\family typewriter 19744HXOPT_USAGEONERR 19745\series medium 19746 19747\begin_inset Index idx 19748status open 19749 19750\begin_layout Plain Layout 19751 19752\family typewriter 19753HXOPT_USAGEONERR 19754\end_layout 19755 19756\end_inset 19757 19758 19759\family default 19760\series default 19761 Display the short-format usage syntax when an error is encountered. 19762\end_layout 19763 19764\begin_layout Description 19765 19766\family typewriter 19767HXOPT_RQ_ORDER 19768\family default 19769 19770\begin_inset Index idx 19771status open 19772 19773\begin_layout Plain Layout 19774 19775\family typewriter 19776HXOPT_RQ_ORDER 19777\end_layout 19778 19779\end_inset 19780 19781 Specifying this option terminates option processing when the first non-option 19782 argument in 19783\family typewriter 19784argv 19785\family default 19786 is encountered. 19787 This behavior is also implicit when the environment variable 19788\family typewriter 19789POSIXLY_CORRECT 19790\family default 19791 is set. 19792\end_layout 19793 19794\begin_layout Standard 19795The return value can be one of the following: 19796\end_layout 19797 19798\begin_layout Description 19799 19800\family typewriter 19801HXOPT_ERR_SUCCESS 19802\family default 19803 19804\begin_inset Index idx 19805status open 19806 19807\begin_layout Plain Layout 19808 19809\family typewriter 19810HXOPT_ERR_SUCCESS 19811\end_layout 19812 19813\end_inset 19814 19815 Parsing was successful. 19816\end_layout 19817 19818\begin_layout Description 19819 19820\family typewriter 19821HXOPT_ERR_UNKN 19822\series medium 19823 19824\begin_inset Index idx 19825status open 19826 19827\begin_layout Plain Layout 19828 19829\family typewriter 19830\series medium 19831HXOPT_ERR_UNKN 19832\end_layout 19833 19834\end_inset 19835 19836 19837\family default 19838\series default 19839 An unknown option was encountered. 19840\end_layout 19841 19842\begin_layout Description 19843 19844\family typewriter 19845HXOPT_ERR_VOID 19846\series medium 19847 19848\begin_inset Index idx 19849status open 19850 19851\begin_layout Plain Layout 19852 19853\family typewriter 19854\series medium 19855HXOPT_ERR_VOID 19856\end_layout 19857 19858\end_inset 19859 19860 19861\family default 19862\series default 19863 An argument was given for an option which does not allow one. 19864 In practice this only happens with 19865\begin_inset Quotes eld 19866\end_inset 19867 19868 19869\family typewriter 19870--foo=bar 19871\family default 19872 19873\begin_inset Quotes erd 19874\end_inset 19875 19876 when 19877\family typewriter 19878--foo 19879\family default 19880 is of type 19881\family typewriter 19882HXTYPE_\SpecialChar softhyphen 19883NONE 19884\family default 19885, 19886\family typewriter 19887HXTYPE_\SpecialChar softhyphen 19888VAL 19889\family default 19890 or 19891\family typewriter 19892HXTYPE_\SpecialChar softhyphen 19893SVAL 19894\family default 19895. 19896 This does not affect 19897\begin_inset Quotes eld 19898\end_inset 19899 19900 19901\family typewriter 19902--foo bar 19903\family default 19904 19905\begin_inset Quotes erd 19906\end_inset 19907 19908, because this can be unambiguously interpreted as 19909\begin_inset Quotes eld 19910\end_inset 19911 19912 19913\family typewriter 19914bar 19915\family default 19916 19917\begin_inset Quotes erd 19918\end_inset 19919 19920 being a remaining argument to the program. 19921\end_layout 19922 19923\begin_layout Description 19924 19925\family typewriter 19926HXOPT_ERR_MIS 19927\series medium 19928 19929\begin_inset Index idx 19930status open 19931 19932\begin_layout Plain Layout 19933 19934\family typewriter 19935\series medium 19936HXOPT_ERR_MIS 19937\end_layout 19938 19939\end_inset 19940 19941 19942\family default 19943\series default 19944 Missing argument for an option that requires one. 19945\end_layout 19946 19947\begin_layout Description 19948 19949\family typewriter 19950HXOPT_ERR_AMBIG 19951\series medium 19952 19953\begin_inset Index idx 19954status open 19955 19956\begin_layout Plain Layout 19957 19958\family typewriter 19959\series medium 19960HXOPT_ERR_AMBIG 19961\end_layout 19962 19963\end_inset 19964 19965 19966\family default 19967\series default 19968 An abbreviation of a long option was ambiguous. 19969\end_layout 19970 19971\begin_layout Description 19972negative 19973\begin_inset space ~ 19974\end_inset 19975 19976non-zero Failure on behalf of lower-level calls; errno. 19977\end_layout 19978 19979\begin_layout Subsection 19980Pitfalls 19981\end_layout 19982 19983\begin_layout Subsubsection 19984Staticness of tables 19985\begin_inset CommandInset label 19986LatexCommand label 19987name "subsec:option-pitfalls-static" 19988 19989\end_inset 19990 19991 19992\end_layout 19993 19994\begin_layout Standard 19995The following is an example of a possible pitfall regarding 19996\family typewriter 19997HXTYPE_\SpecialChar softhyphen 19998STRDQ 19999\family default 20000: 20001\end_layout 20002 20003\begin_layout LyX-Code 20004 20005\series bold 20006static struct 20007\series default 20008 HXdeque 20009\series bold 20010* 20011\series default 20012dq; 20013\begin_inset Newline newline 20014\end_inset 20015 20016 20017\begin_inset Newline newline 20018\end_inset 20019 20020 20021\series bold 20022static bool 20023\series default 20024 get_options( 20025\series bold 20026int * 20027\series default 20028argc, 20029\series bold 20030const char *** 20031\series default 20032argv) 20033\begin_inset Newline newline 20034\end_inset 20035 20036{ 20037\begin_inset Newline newline 20038\end_inset 20039 20040 20041\series bold 20042static const struct 20043\series default 20044 HXoption options_table 20045\series bold 20046[] 20047\series default 20048 = { 20049\begin_inset Newline newline 20050\end_inset 20051 20052 {.sh = 'N', .type = HXTYPE_STRDQ, .q_strdq = dq, 20053\begin_inset Newline newline 20054\end_inset 20055 20056 .help = "Add name"}, 20057\begin_inset Newline newline 20058\end_inset 20059 20060 HXOPT_TABLEEND, 20061\begin_inset Newline newline 20062\end_inset 20063 20064 }; 20065\begin_inset Newline newline 20066\end_inset 20067 20068 20069\series bold 20070return 20071\series default 20072 HX_getopt(options_table, argc, argv, HXOPT_USAGEONERR) == 20073\begin_inset Newline newline 20074\end_inset 20075 20076 HXOPT_ERR_SUCCESS; 20077\begin_inset Newline newline 20078\end_inset 20079 20080} 20081\begin_inset Newline newline 20082\end_inset 20083 20084 20085\begin_inset Newline newline 20086\end_inset 20087 20088 20089\series bold 20090int 20091\series default 20092 main( 20093\series bold 20094int 20095\series default 20096 argc, 20097\series bold 20098const char ** 20099\series default 20100argv) 20101\begin_inset Newline newline 20102\end_inset 20103 20104{ 20105\begin_inset Newline newline 20106\end_inset 20107 20108 dq = HXdeque_init(); 20109\begin_inset Newline newline 20110\end_inset 20111 20112 get_options(&argc, &argv); 20113\begin_inset Newline newline 20114\end_inset 20115 20116 20117\series bold 20118return 20119\series default 20120 0; 20121\begin_inset Newline newline 20122\end_inset 20123 20124} 20125\end_layout 20126 20127\begin_layout Standard 20128The problem here is that 20129\family typewriter 20130options_\SpecialChar softhyphen 20131table 20132\family default 20133 is, due to the 20134\family typewriter 20135static 20136\family default 20137 keyword, initialized at compile-time where 20138\family typewriter 20139dq 20140\family default 20141 is still 20142\family typewriter 20143NULL 20144\family default 20145. 20146 To counter this problem and have it doing the right thing, you must remove 20147 the 20148\family typewriter 20149static 20150\family default 20151 qualifier on the options table when used with 20152\family typewriter 20153HXTYPE_\SpecialChar softhyphen 20154STRDQ 20155\family default 20156, so that it will be evaluated when it is first executed. 20157\end_layout 20158 20159\begin_layout Standard 20160It was not deemed worthwhile to have 20161\family typewriter 20162HXTYPE_\SpecialChar softhyphen 20163STRDQ 20164\family default 20165 take an indirect HXdeque ( 20166\family typewriter 20167struct HXdeque 20168\begin_inset space ~ 20169\end_inset 20170 20171** 20172\family default 20173) instead just to bypass this issue. 20174 (Live with it.) 20175\end_layout 20176 20177\begin_layout Subsection 20178Limitations 20179\end_layout 20180 20181\begin_layout Standard 20182The HX option parser has been influenced by both popt and Getopt::Long, 20183 but eventually, there are differences: 20184\end_layout 20185 20186\begin_layout Itemize 20187Long options with a single dash ( 20188\begin_inset Quotes eld 20189\end_inset 20190 20191 20192\family typewriter 20193-foo bar 20194\family default 20195 20196\begin_inset Quotes erd 20197\end_inset 20198 20199). 20200 This unsupported syntax clashes very easily with support for option bundling 20201 or squashing. 20202 In case of bundling, 20203\begin_inset Quotes eld 20204\end_inset 20205 20206 20207\family typewriter 20208-foo 20209\family default 20210 20211\begin_inset Quotes erd 20212\end_inset 20213 20214 might actually be 20215\begin_inset Quotes eld 20216\end_inset 20217 20218 20219\family typewriter 20220-f -o -o 20221\family default 20222 20223\begin_inset Quotes erd 20224\end_inset 20225 20226, or 20227\begin_inset Quotes eld 20228\end_inset 20229 20230 20231\family typewriter 20232-f oo 20233\family default 20234 20235\begin_inset Quotes erd 20236\end_inset 20237 20238 in case of squashing. 20239 It also introduces redundant ways to specify options, which is not in the 20240 spirit of the author. 20241\end_layout 20242 20243\begin_layout Itemize 20244Options using a 20245\begin_inset Quotes eld 20246\end_inset 20247 20248 20249\family typewriter 20250+ 20251\family default 20252 20253\begin_inset Quotes erd 20254\end_inset 20255 20256 as a prefix, as in 20257\begin_inset Quotes eld 20258\end_inset 20259 20260 20261\family typewriter 20262+foo 20263\family default 20264 20265\begin_inset Quotes erd 20266\end_inset 20267 20268. 20269 Xterm for example uses it as a way to negate an option. 20270 In the author's opinion, using one character to specify options is enough 20271\begin_inset space ~ 20272\end_inset 20273 20274— by GNU standards, a negator is named 20275\begin_inset Quotes eld 20276\end_inset 20277 20278 20279\family typewriter 20280--no-foo 20281\family default 20282 20283\begin_inset Quotes erd 20284\end_inset 20285 20286. 20287 Even Microsoft stuck to a single option introducing character (that would 20288 be 20289\begin_inset Quotes eld 20290\end_inset 20291 20292 20293\family typewriter 20294/ 20295\family default 20296 20297\begin_inset Quotes erd 20298\end_inset 20299 20300). 20301\end_layout 20302 20303\begin_layout Itemize 20304Table nesting like implemented in popt. 20305 HXopt has no provision for nested tables, as the need has not come up yet. 20306 It does however support chained processing (see section 20307\begin_inset space ~ 20308\end_inset 20309 20310 20311\begin_inset CommandInset ref 20312LatexCommand ref 20313reference "subsec:option-example-chained" 20314 20315\end_inset 20316 20317). 20318 You cannot do nested tables even with callbacks, as the new 20319\family typewriter 20320argv 20321\family default 20322 array is only put in place shortly before 20323\family typewriter 20324HX_getopt 20325\family default 20326 returns. 20327\end_layout 20328 20329\begin_layout Subsection 20330Examples 20331\end_layout 20332 20333\begin_layout Subsubsection 20334Basic example 20335\end_layout 20336 20337\begin_layout Standard 20338The following code snippet should provide an equivalent of the GNU getopt 20339 sample 20340\begin_inset Foot 20341status open 20342 20343\begin_layout Plain Layout 20344\begin_inset Flex URL 20345status open 20346 20347\begin_layout Plain Layout 20348 20349http://www.gnu.org/software/libtool/manual/libc/Example-of-Getopt.html 20350\backslash 20351#Example-of-Getopt 20352\end_layout 20353 20354\end_inset 20355 20356 20357\end_layout 20358 20359\end_inset 20360 20361. 20362\end_layout 20363 20364\begin_layout LyX-Code 20365 20366\series bold 20367#include 20368\series default 20369 <stdio.h> 20370\begin_inset Newline newline 20371\end_inset 20372 20373 20374\series bold 20375#include 20376\series default 20377 <stdilb.h> 20378\begin_inset Newline newline 20379\end_inset 20380 20381 20382\series bold 20383#include 20384\series default 20385 <libHX/option.h> 20386\begin_inset Newline newline 20387\end_inset 20388 20389 20390\begin_inset Newline newline 20391\end_inset 20392 20393 20394\series bold 20395int 20396\series default 20397 main( 20398\series bold 20399int 20400\series default 20401 argc, 20402\series bold 20403const char ** 20404\series default 20405argv) 20406\begin_inset Newline newline 20407\end_inset 20408 20409{ 20410\begin_inset Newline newline 20411\end_inset 20412 20413 20414\series bold 20415int 20416\series default 20417 aflag = 0; 20418\begin_inset Newline newline 20419\end_inset 20420 20421 20422\series bold 20423int 20424\series default 20425 bflag = 0; 20426\begin_inset Newline newline 20427\end_inset 20428 20429 20430\series bold 20431char * 20432\series default 20433cflag = NULL; 20434\begin_inset Newline newline 20435\end_inset 20436 20437 20438\begin_inset Newline newline 20439\end_inset 20440 20441 20442\series bold 20443struct 20444\series default 20445 HXoption options_table 20446\series bold 20447[] 20448\series default 20449 = { 20450\begin_inset Newline newline 20451\end_inset 20452 20453 {.sh = 'a', .type = HXTYPE_NONE, .ptr = &aflag}, 20454\begin_inset Newline newline 20455\end_inset 20456 20457 {.sh = 'b', .type = HXTYPE_NONE, .ptr = &bflag}, 20458\begin_inset Newline newline 20459\end_inset 20460 20461 {.sh = 'c', .type = HXTYPE_STRING, .ptr = &cflag}, 20462\begin_inset Newline newline 20463\end_inset 20464 20465 HXOPT_AUTOHELP, 20466\end_layout 20467 20468\begin_layout LyX-Code 20469 HXOPT_TABLEEND, 20470\begin_inset Newline newline 20471\end_inset 20472 20473 }; 20474\begin_inset Newline newline 20475\end_inset 20476 20477 20478\begin_inset Newline newline 20479\end_inset 20480 20481 20482\series bold 20483if 20484\series default 20485 (HX_getopt(options_table, &argc, &argv, HXOPT_USAGEONERR) != 20486\begin_inset Newline newline 20487\end_inset 20488 20489 HXOPT_ERR_SUCCESS) 20490\end_layout 20491 20492\begin_layout LyX-Code 20493 20494\series bold 20495return 20496\series default 20497 EXIT_FAILURE; 20498\begin_inset Newline newline 20499\end_inset 20500 20501 20502\begin_inset Newline newline 20503\end_inset 20504 20505 printf("aflag = %d, bflag = %d, cvalue = %s 20506\backslash 20507n", 20508\begin_inset Newline newline 20509\end_inset 20510 20511 aflag, bflag, cvalue); 20512\begin_inset Newline newline 20513\end_inset 20514 20515 20516\begin_inset Newline newline 20517\end_inset 20518 20519 20520\series bold 20521while 20522\series default 20523 (*++argv != NULL) 20524\begin_inset Newline newline 20525\end_inset 20526 20527 printf("Non-option argument %s 20528\backslash 20529n", *argv); 20530\begin_inset Newline newline 20531\end_inset 20532 20533 20534\begin_inset Newline newline 20535\end_inset 20536 20537 20538\series bold 20539return 20540\series default 20541 EXIT_SUCCESS; 20542\begin_inset Newline newline 20543\end_inset 20544 20545} 20546\end_layout 20547 20548\begin_layout Subsubsection 20549Verbosity levels 20550\begin_inset CommandInset label 20551LatexCommand label 20552name "subsec:option-example-incdec" 20553 20554\end_inset 20555 20556 20557\end_layout 20558 20559\begin_layout LyX-Code 20560 20561\series bold 20562static int 20563\series default 20564 verbosity = 1; 20565\series bold 20566/* 20567\family roman 20568\series default 20569\shape italic 20570somewhat silent by default 20571\family default 20572\series bold 20573\shape default 20574 */ 20575\series default 20576 20577\begin_inset Newline newline 20578\end_inset 20579 20580 20581\series bold 20582static const struct 20583\series default 20584 HXoption options_table 20585\series bold 20586[] 20587\series default 20588 = { 20589\begin_inset Newline newline 20590\end_inset 20591 20592 {.sh = 'q', .type = HXTYPE_NONE | HXOPT_DEC, .q_int = &verbosity, 20593\begin_inset Newline newline 20594\end_inset 20595 20596 .help = "Reduce verbosity"}, 20597\begin_inset Newline newline 20598\end_inset 20599 20600 {.sh = 'v', .type = HXTYPE_NONE | HXOPT_INC, .q_int = &verbosity, 20601\begin_inset Newline newline 20602\end_inset 20603 20604 .help = "Increase verbosity"}, 20605\begin_inset Newline newline 20606\end_inset 20607 20608 HXOPT_TABLEEND, 20609\begin_inset Newline newline 20610\end_inset 20611 20612}; 20613\end_layout 20614 20615\begin_layout Standard 20616This sample option table makes it possible to turn the verbosity of the 20617 program up or down, depending on whether the user specified 20618\family typewriter 20619-q 20620\family default 20621 or 20622\family typewriter 20623-v 20624\family default 20625. 20626 By passing multiple 20627\family typewriter 20628-v 20629\family default 20630 flags, the verbosity can be turned up even more. 20631 The range depends on the 20632\begin_inset Quotes eld 20633\end_inset 20634 20635 20636\family typewriter 20637int 20638\family default 20639 20640\begin_inset Quotes erd 20641\end_inset 20642 20643 data type for your particular platform and compiler; if you want to have 20644 the verbosity capped at a specific level, you will need to use an extra 20645 callback: 20646\end_layout 20647 20648\begin_layout LyX-Code 20649 20650\series bold 20651static int 20652\series default 20653 verbosity = 1; 20654\begin_inset Newline newline 20655\end_inset 20656 20657 20658\begin_inset Newline newline 20659\end_inset 20660 20661 20662\series bold 20663static void 20664\series default 20665 v_check( 20666\series bold 20667const struct 20668\series default 20669 HXoptcb 20670\series bold 20671* 20672\series default 20673cbi) 20674\begin_inset Newline newline 20675\end_inset 20676 20677{ 20678\begin_inset Newline newline 20679\end_inset 20680 20681 20682\series bold 20683if 20684\series default 20685 (verbosity < 0) 20686\begin_inset Newline newline 20687\end_inset 20688 20689 verbosity = 0; 20690\begin_inset Newline newline 20691\end_inset 20692 20693 20694\series bold 20695else if 20696\series default 20697 (verbosity > 4) 20698\begin_inset Newline newline 20699\end_inset 20700 20701 verbosity = 4; 20702\begin_inset Newline newline 20703\end_inset 20704 20705} 20706\begin_inset Newline newline 20707\end_inset 20708 20709 20710\begin_inset Newline newline 20711\end_inset 20712 20713 20714\series bold 20715static const struct 20716\series default 20717 HXoption options_table 20718\series bold 20719[] 20720\series default 20721 = { 20722\begin_inset Newline newline 20723\end_inset 20724 20725 {.sh = 'q', .type = HXTYPE_NONE | HXOPT_DEC, .q_int = &verbosity, 20726\begin_inset Newline newline 20727\end_inset 20728 20729 .cb = v_check, .help = "Lower verbosity"}, 20730\begin_inset Newline newline 20731\end_inset 20732 20733 {.sh = 'v', .type = HXTYPE_NONE | HXOPT_INC, .q_int = &verbosity, 20734\begin_inset Newline newline 20735\end_inset 20736 20737 .cb = v_check, .help = "Raise verbosity"}, 20738\begin_inset Newline newline 20739\end_inset 20740 20741 HXOPT_TABLEEND, 20742\begin_inset Newline newline 20743\end_inset 20744 20745}; 20746\end_layout 20747 20748\begin_layout Subsubsection 20749Mask operations 20750\begin_inset CommandInset label 20751LatexCommand label 20752name "subsec:option-example-mask" 20753 20754\end_inset 20755 20756 20757\end_layout 20758 20759\begin_layout LyX-Code 20760 20761\series bold 20762/* 20763\family roman 20764\series default 20765\shape italic 20766run on all CPU cores by default 20767\family default 20768\series bold 20769\shape default 20770 * 20771\series default 20772/ 20773\begin_inset Newline newline 20774\end_inset 20775 20776 20777\series bold 20778static unsigned int 20779\series default 20780 cpu_mask = ~0U 20781\series bold 20782; 20783\begin_inset Newline newline 20784\end_inset 20785 20786/* 20787\family roman 20788\series default 20789\shape italic 20790use no network connections by default 20791\family default 20792\shape default 20793 20794\series bold 20795*/ 20796\begin_inset Newline newline 20797\end_inset 20798 20799static unsigned int 20800\series default 20801 net_mask = 0; 20802\series bold 20803 20804\begin_inset Newline newline 20805\end_inset 20806 20807static struct 20808\series default 20809 HXoption options_table 20810\series bold 20811[] 20812\series default 20813 = { 20814\begin_inset Newline newline 20815\end_inset 20816 20817 {.sh = 'c', .type = HXTYPE_UINT | HXOPT_NOT | HXOPT_AND, 20818\begin_inset Newline newline 20819\end_inset 20820 20821 .q_uint = &cpu_mask, 20822\begin_inset Newline newline 20823\end_inset 20824 20825 .help = "Mask of cores to exclude", .htyp = "cpu_mask"}, 20826\begin_inset Newline newline 20827\end_inset 20828 20829 {.sh = 'n', .type = HXTYPE_UINT | HXOPT_OR, .q_uint = &net_mask, 20830\end_layout 20831 20832\begin_layout LyX-Code 20833 .help = "Mask of network channels to additionally use", 20834\begin_inset Newline newline 20835\end_inset 20836 20837 .htyp = "channel_mask"}, 20838\begin_inset Newline newline 20839\end_inset 20840 20841 HXOPT_TABLEEND, 20842\begin_inset Newline newline 20843\end_inset 20844 20845}; 20846\end_layout 20847 20848\begin_layout Standard 20849What this options table does is 20850\family typewriter 20851cpu_mask &= ~x 20852\family default 20853 and 20854\family typewriter 20855net_mask |= y 20856\family default 20857, the classic operations of clearing and setting bits. 20858\end_layout 20859 20860\begin_layout Subsubsection 20861Support for non-standard actions 20862\begin_inset CommandInset label 20863LatexCommand label 20864name "subsec:option-example-cb" 20865 20866\end_inset 20867 20868 20869\end_layout 20870 20871\begin_layout Standard 20872Supporting additional types or custom storage formats is easy, by simply 20873 using 20874\family typewriter 20875HXTYPE_\SpecialChar softhyphen 20876STRING 20877\family default 20878, 20879\family typewriter 20880NULL 20881\family default 20882 as the data pointer (usually by not specifying it at all), the pointer 20883 to your data in the user-specified pointer 20884\family typewriter 20885uptr 20886\family default 20887, and the callback function in 20888\family typewriter 20889cb 20890\family default 20891. 20892\end_layout 20893 20894\begin_layout LyX-Code 20895 20896\series bold 20897struct 20898\series default 20899 fixed_point { 20900\begin_inset Newline newline 20901\end_inset 20902 20903 20904\series bold 20905int 20906\series default 20907 integral; 20908\begin_inset Newline newline 20909\end_inset 20910 20911 20912\series bold 20913unsigned int 20914\series default 20915 fraction; 20916\begin_inset Newline newline 20917\end_inset 20918 20919}; 20920\begin_inset Newline newline 20921\end_inset 20922 20923 20924\begin_inset Newline newline 20925\end_inset 20926 20927 20928\series bold 20929static struct 20930\series default 20931 fixed_point number; 20932\end_layout 20933 20934\begin_layout LyX-Code 20935\begin_inset Newline newline 20936\end_inset 20937 20938 20939\series bold 20940static void 20941\series default 20942 fixed_point_parse 20943\series bold 20944(const struct 20945\series default 20946 HXoptcb 20947\series bold 20948 20949\series default 20950*cbi) 20951\begin_inset Newline newline 20952\end_inset 20953 20954{ 20955\begin_inset Newline newline 20956\end_inset 20957 20958 20959\series bold 20960char * 20961\series default 20962end; 20963\begin_inset Newline newline 20964\end_inset 20965 20966 20967\begin_inset Newline newline 20968\end_inset 20969 20970 number.integral = strtol(cbi->data, &end, 0); 20971\begin_inset Newline newline 20972\end_inset 20973 20974 20975\series bold 20976if 20977\series default 20978 (*end == ' 20979\backslash 209800') 20981\begin_inset Newline newline 20982\end_inset 20983 20984 number.fraction = 0; 20985\begin_inset Newline newline 20986\end_inset 20987 20988 20989\series bold 20990else if 20991\series default 20992 (*end == '.') 20993\begin_inset Newline newline 20994\end_inset 20995 20996 number.fraction = strtoul(end + 1, NULL, 0); 20997\begin_inset Newline newline 20998\end_inset 20999 21000 21001\series bold 21002else 21003\series default 21004 21005\begin_inset Newline newline 21006\end_inset 21007 21008 fprintf(stderr, "Illegal input. 21009\backslash 21010n"); 21011\begin_inset Newline newline 21012\end_inset 21013 21014} 21015\begin_inset Newline newline 21016\end_inset 21017 21018 21019\series bold 21020 21021\begin_inset Newline newline 21022\end_inset 21023 21024static const struct 21025\series default 21026 HXoption options_table 21027\series bold 21028[] 21029\series default 21030 = { 21031\begin_inset Newline newline 21032\end_inset 21033 21034 {.sh = 'n', .type = HXTYPE_STRING, .cb = fixed_point_parse, 21035\begin_inset Newline newline 21036\end_inset 21037 21038 .uptr = &number, .help = "Do this or that", 21039\begin_inset Newline newline 21040\end_inset 21041 21042 HXOPT_TABLEEND, 21043\end_layout 21044 21045\begin_layout LyX-Code 21046}; 21047\end_layout 21048 21049\begin_layout Subsubsection 21050Chained argument processing 21051\begin_inset CommandInset label 21052LatexCommand label 21053name "subsec:option-example-chained" 21054 21055\end_inset 21056 21057 21058\end_layout 21059 21060\begin_layout Standard 21061On the first run, only 21062\family typewriter 21063--cake 21064\family default 21065 and 21066\family typewriter 21067--fruit 21068\family default 21069 is considered, which is then used to select the next set of accepted options. 21070 Note that 21071\family typewriter 21072HXOPT_\SpecialChar softhyphen 21073DESTROY_\SpecialChar softhyphen 21074OLD 21075\family default 21076 is used here, which causes the argv that is produced by the first invocation 21077 of 21078\family typewriter 21079HX_getopt 21080\family default 21081 in the 21082\family typewriter 21083get_options 21084\family default 21085 function to be freed as it gets replaced by a new argv again by 21086\family typewriter 21087HX_getopt 21088\family default 21089 in 21090\family typewriter 21091get_cakes 21092\family default 21093\SpecialChar breakableslash 21094 21095\family typewriter 21096get_fruit 21097\family default 21098. 21099 21100\family typewriter 21101HXOPT_\SpecialChar softhyphen 21102DESTROY_\SpecialChar softhyphen 21103OLD 21104\family default 21105 is however 21106\shape italic 21107not 21108\shape default 21109 specified in the first invocation, because the initial argv resides on 21110 the stack and cannot be freed. 21111\end_layout 21112 21113\begin_layout LyX-Code 21114 21115\series bold 21116static bool 21117\series default 21118 get_cakes( 21119\series bold 21120int * 21121\series default 21122argc, 21123\series bold 21124const char *** 21125\series default 21126argv) 21127\begin_inset Newline newline 21128\end_inset 21129 21130{ 21131\begin_inset Newline newline 21132\end_inset 21133 21134 21135\series bold 21136struct 21137\series default 21138 HXoption option_table 21139\series bold 21140[] 21141\series default 21142 = { 21143\begin_inset Newline newline 21144\end_inset 21145 21146 ... 21147\begin_inset Newline newline 21148\end_inset 21149 21150 }; 21151\begin_inset Newline newline 21152\end_inset 21153 21154 21155\series bold 21156return 21157\series default 21158 HX_getopt(cake_table, argc, argv, 21159\begin_inset Newline newline 21160\end_inset 21161 21162 HXOPT_USAGEONERR | HXOPT_DESTROY_OLD) == HXOPT_ERR_SUCCESS; 21163\begin_inset Newline newline 21164\end_inset 21165 21166} 21167\begin_inset Newline newline 21168\end_inset 21169 21170 21171\begin_inset Newline newline 21172\end_inset 21173 21174 21175\series bold 21176static bool 21177\series default 21178 get_fruit( 21179\series bold 21180int * 21181\series default 21182argc, 21183\series bold 21184const char *** 21185\series default 21186argv) 21187\begin_inset Newline newline 21188\end_inset 21189 21190{ 21191\begin_inset Newline newline 21192\end_inset 21193 21194 21195\series bold 21196struct 21197\series default 21198 HXoption fruit_table 21199\series bold 21200[] 21201\series default 21202 = { 21203\begin_inset Newline newline 21204\end_inset 21205 21206 ... 21207\begin_inset Newline newline 21208\end_inset 21209 21210 }; 21211\begin_inset Newline newline 21212\end_inset 21213 21214 21215\series bold 21216return 21217\series default 21218 HX_getopt(fruit_table, argc, argv, 21219\begin_inset Newline newline 21220\end_inset 21221 21222 HXOPT_USAGEONERR | HXOPT_DESTROY_OLD) == HXOPT_ERR_SUCCESS; 21223\begin_inset Newline newline 21224\end_inset 21225 21226} 21227\begin_inset Newline newline 21228\end_inset 21229 21230 21231\begin_inset Newline newline 21232\end_inset 21233 21234 21235\series bold 21236static bool 21237\series default 21238 get_options( 21239\series bold 21240int * 21241\series default 21242argc, 21243\series bold 21244const char *** 21245\series default 21246argv) 21247\begin_inset Newline newline 21248\end_inset 21249 21250{ 21251\begin_inset Newline newline 21252\end_inset 21253 21254 21255\series bold 21256int 21257\series default 21258 cake = 0, fruit = 0; 21259\begin_inset Newline newline 21260\end_inset 21261 21262 21263\series bold 21264struct 21265\series default 21266 HXoption option_table 21267\series bold 21268[] 21269\series default 21270 = { 21271\begin_inset Newline newline 21272\end_inset 21273 21274 {.ln = "cake", .type = HXTYPE_NONE, .ptr = &cake}, 21275\begin_inset Newline newline 21276\end_inset 21277 21278 {.ln = "fruit", .type = HXTYPE_NONE, .ptr = &fruit}, 21279\begin_inset Newline newline 21280\end_inset 21281 21282 HXOPT_TABLEEND, 21283\begin_inset Newline newline 21284\end_inset 21285 21286 }; 21287\begin_inset Newline newline 21288\end_inset 21289 21290 21291\series bold 21292if 21293\series default 21294 (HX_getopt(option_table, argc, argv, HXOPT_PTHRU) != 21295\begin_inset Newline newline 21296\end_inset 21297 21298 HXOPT_ERR_SUCCESS) 21299\begin_inset Newline newline 21300\end_inset 21301 21302 21303\series bold 21304return 21305\series default 21306 false; 21307\begin_inset Newline newline 21308\end_inset 21309 21310 21311\series bold 21312if 21313\series default 21314 (cake) 21315\begin_inset Newline newline 21316\end_inset 21317 21318 21319\series bold 21320return 21321\series default 21322 get_cakes(argc, argv); 21323\begin_inset Newline newline 21324\end_inset 21325 21326 21327\series bold 21328else if 21329\series default 21330 (fruit) 21331\begin_inset Newline newline 21332\end_inset 21333 21334 21335\series bold 21336return 21337\series default 21338 get_fruit(argc, argv); 21339\begin_inset Newline newline 21340\end_inset 21341 21342 21343\series bold 21344return 21345\series default 21346 false; 21347\begin_inset Newline newline 21348\end_inset 21349 21350} 21351\end_layout 21352 21353\begin_layout Standard 21354\begin_inset Newpage clearpage 21355\end_inset 21356 21357 21358\end_layout 21359 21360\begin_layout Section 21361Shell-style configuration file parser 21362\begin_inset CommandInset label 21363LatexCommand label 21364name "sec:shconf" 21365 21366\end_inset 21367 21368 21369\end_layout 21370 21371\begin_layout Standard 21372libHX provides functions to read shell-style configuration files. 21373 Such files are common, for example, in 21374\family typewriter 21375/etc/sysconfig 21376\family default 21377 on Linux systems. 21378 The format is pretty basic; it only knows about 21379\begin_inset Quotes eld 21380\end_inset 21381 21382 21383\family typewriter 21384key=value 21385\family default 21386 21387\begin_inset Quotes erd 21388\end_inset 21389 21390 pairs and does not even have sections like INI files. 21391 Not relying on any features however makes them quite interchangable as 21392 the syntax is accepted by Unix Shells. 21393\end_layout 21394 21395\begin_layout Standard 21396Lines beginning with a hash mark ( 21397\family typewriter 21398# 21399\family default 21400) are ignored, as are empty lines and unrecognized keys. 21401\end_layout 21402 21403\begin_layout LyX-Code 21404 21405\series bold 21406# Minimum / maximum values for automatic UID selection 21407\series default 21408 21409\begin_inset Newline newline 21410\end_inset 21411 21412UID_MIN=100 21413\begin_inset Newline newline 21414\end_inset 21415 21416UID_MAX=65000 21417\begin_inset Newline newline 21418\end_inset 21419 21420 21421\begin_inset Newline newline 21422\end_inset 21423 21424 21425\series bold 21426# Home directory base 21427\series default 21428 21429\begin_inset Newline newline 21430\end_inset 21431 21432HOME="/home" 21433\begin_inset Newline newline 21434\end_inset 21435 21436#HOME="/export/home" 21437\end_layout 21438 21439\begin_layout Standard 21440Any form of variable or parameter substitution or expansion is highly implementa 21441tion specific, and is not supported in libHX's reader. 21442 Even Shell users should not rely on it as you never know in which context 21443 the configuration files are evaluated. 21444 Still, you will have to escape specific sequences like you would need to 21445 in Shell. 21446 The use of single quotes is acceptable. 21447 That means: 21448\end_layout 21449 21450\begin_layout LyX-Code 21451AMOUNT="US 21452\backslash 21453$5" 21454\begin_inset Newline newline 21455\end_inset 21456 21457AMOUNT='US$5' 21458\end_layout 21459 21460\begin_layout Subsection 21461Synopsis 21462\end_layout 21463 21464\begin_layout LyX-Code 21465 21466\series bold 21467#include 21468\series default 21469 <libHX/option.h> 21470\begin_inset Index idx 21471status open 21472 21473\begin_layout Plain Layout 21474 21475\family typewriter 21476libHX/option.h 21477\end_layout 21478 21479\end_inset 21480 21481 21482\begin_inset Newline newline 21483\end_inset 21484 21485 21486\begin_inset Newline newline 21487\end_inset 21488 21489 21490\series bold 21491int 21492\series default 21493 HX_shconfig( 21494\series bold 21495const char * 21496\series default 21497file, 21498\series bold 21499const struct 21500\series default 21501 HXoption 21502\series bold 21503* 21504\series default 21505table); 21506\begin_inset Index idx 21507status open 21508 21509\begin_layout Plain Layout 21510 21511\family typewriter 21512HX_shconfig 21513\end_layout 21514 21515\end_inset 21516 21517 21518\begin_inset Newline newline 21519\end_inset 21520 21521 21522\series bold 21523int 21524\series default 21525 HX_shconfig_pv( 21526\series bold 21527const char ** 21528\series default 21529path_vec, 21530\series bold 21531const char * 21532\series default 21533file, 21534\begin_inset Newline newline 21535\end_inset 21536 21537 21538\series bold 21539const struct 21540\series default 21541 HXoption 21542\series bold 21543* 21544\series default 21545table, 21546\series bold 21547unsigned int 21548\series default 21549 flags); 21550\begin_inset Index idx 21551status open 21552 21553\begin_layout Plain Layout 21554 21555\family typewriter 21556HX_shconfig_pv 21557\end_layout 21558 21559\end_inset 21560 21561 21562\begin_inset Newline newline 21563\end_inset 21564 21565 21566\series bold 21567struct 21568\series default 21569 HXmap 21570\series bold 21571* 21572\series default 21573HX_shconfig_map( 21574\series bold 21575const char * 21576\series default 21577file); 21578\begin_inset Index idx 21579status open 21580 21581\begin_layout Plain Layout 21582 21583\family typewriter 21584HX_shconfig_map 21585\end_layout 21586 21587\end_inset 21588 21589 21590\end_layout 21591 21592\begin_layout Standard 21593The shconfig parser reuses 21594\family typewriter 21595struct HXoption 21596\family default 21597 that fits very well in specifying name-pointer associations. 21598 21599\family typewriter 21600HX_shconfig 21601\family default 21602 will read the given file using the key-to-pointer mappings from the table 21603 to store the variable contents. 21604 Of 21605\family typewriter 21606struct HXoption 21607\family default 21608, described in section 21609\begin_inset space ~ 21610\end_inset 21611 21612 21613\begin_inset CommandInset ref 21614LatexCommand ref 21615reference "subsec:option-synopsis" 21616 21617\end_inset 21618 21619, only the 21620\begin_inset Quotes eld 21621\end_inset 21622 21623 21624\family typewriter 21625ln 21626\family default 21627 21628\begin_inset Quotes erd 21629\end_inset 21630 21631, 21632\begin_inset Quotes eld 21633\end_inset 21634 21635 21636\family typewriter 21637type 21638\family default 21639 21640\begin_inset Quotes erd 21641\end_inset 21642 21643 and 21644\begin_inset Quotes eld 21645\end_inset 21646 21647 21648\family typewriter 21649ptr 21650\family default 21651 21652\begin_inset Quotes erd 21653\end_inset 21654 21655 fields are used. 21656 The list of accepted types is described in section 21657\begin_inset space ~ 21658\end_inset 21659 21660 21661\begin_inset CommandInset ref 21662LatexCommand ref 21663reference "subsec:option-types" 21664 21665\end_inset 21666 21667. 21668\end_layout 21669 21670\begin_layout Standard 21671To parse a file, call 21672\family typewriter 21673HX_shconfig 21674\family default 21675 function with the corresponding parameters. 21676 If you want to read configuration files from different paths, i. 21677\begin_inset space \thinspace{} 21678\end_inset 21679 21680e. 21681\begin_inset space \space{} 21682\end_inset 21683 21684to build up on default values, you can use 21685\family typewriter 21686HX_shconfig_pv 21687\family default 21688 21689\begin_inset Foot 21690status open 21691 21692\begin_layout Plain Layout 21693pv = path vector 21694\end_layout 21695 21696\end_inset 21697 21698, which is a variant for reading a file from multiple locations. 21699 Its purpose is to facilitate reading system-wide settings which are then 21700 overriden by a file in the users home directory, for example (per-setting-overr 21701ide). 21702 It is also possible to do per-file-override, that is, a file in the home 21703 directory has higher precedence than a system-wide one in such a way that 21704 the system-wide configuration file is not even read. 21705 This is accomplished by traversing the paths in the 21706\begin_inset Quotes eld 21707\end_inset 21708 21709other 21710\begin_inset Quotes erd 21711\end_inset 21712 21713 direction (actually you have to turn the array around) and stopping at 21714 the first existing file by use of the 21715\family typewriter 21716SHCONF_\SpecialChar softhyphen 21717ONE 21718\family default 21719 flag. 21720\end_layout 21721 21722\begin_layout Standard 21723 21724\family typewriter 21725HX_shconfig_map 21726\family default 21727 will return all entries from the file in a HXmap, usable for parsing arbitrary 21728 keys without having to specify any static key table. 21729\end_layout 21730 21731\begin_layout Description 21732 21733\family typewriter 21734SHCONF_ONE 21735\series medium 21736 21737\begin_inset Index idx 21738status open 21739 21740\begin_layout Plain Layout 21741 21742\family typewriter 21743\series medium 21744SHCONF_ONE 21745\end_layout 21746 21747\end_inset 21748 21749 21750\family default 21751\series default 21752 Parsing files will stop after one file has been successfully parsed. 21753 This allows for a 21754\begin_inset Quotes eld 21755\end_inset 21756 21757personal overrides system config 21758\begin_inset Quotes erd 21759\end_inset 21760 21761 style. 21762\end_layout 21763 21764\begin_layout Standard 21765The call to 21766\family typewriter 21767HX_shconfig 21768\family default 21769 will either return >0 for success, 0 for no success (actually, this is 21770 never returned) and 21771\family typewriter 21772-errno 21773\family default 21774 for an error. 21775\end_layout 21776 21777\begin_layout Subsection 21778Example 21779\end_layout 21780 21781\begin_layout Subsubsection 21782Per-setting-override 21783\end_layout 21784 21785\begin_layout Standard 21786This example sources key-value pairs from a configuration file in a system 21787 location ( 21788\family typewriter 21789/etc 21790\family default 21791) first, before overriding specific keys with new values from the file in 21792 the home directory. 21793\end_layout 21794 21795\begin_layout LyX-Code 21796 21797\series bold 21798long 21799\series default 21800 uid_min, uid_max; 21801\begin_inset Newline newline 21802\end_inset 21803 21804 21805\series bold 21806char * 21807\series default 21808passwd_file; 21809\begin_inset Newline newline 21810\end_inset 21811 21812 21813\series bold 21814struct 21815\series default 21816 HXoption options_table 21817\series bold 21818[] 21819\series default 21820 = { 21821\begin_inset Newline newline 21822\end_inset 21823 21824 {.ln = "UID_MIN", .type = HXTYPE_LONG, .ptr = &uid_min}, 21825\begin_inset Newline newline 21826\end_inset 21827 21828 {.ln = "UID_MAX", .type = HXTYPE_LONG, .ptr = &uid_max}, 21829\begin_inset Newline newline 21830\end_inset 21831 21832 {.ln = "PWD_FILE", .type = HXTYPE_STRING, .ptr = &passwd_file}, 21833\begin_inset Newline newline 21834\end_inset 21835 21836 HXOPT_TABLEEND, 21837\begin_inset Newline newline 21838\end_inset 21839 21840}; 21841\begin_inset Newline newline 21842\end_inset 21843 21844 21845\series bold 21846const char * 21847\series default 21848home = getenv("HOME"); 21849\begin_inset Newline newline 21850\end_inset 21851 21852 21853\series bold 21854const char * 21855\series default 21856paths 21857\series bold 21858[] 21859\series default 21860 = {"/etc", home, NULL}; 21861\begin_inset Newline newline 21862\end_inset 21863 21864HX_shconfig(paths, "test.cf", options_table, 0); 21865\end_layout 21866 21867\begin_layout Subsubsection 21868Per-file-override 21869\end_layout 21870 21871\begin_layout Standard 21872This particular example reads from the file in the home directory first 21873 (if it exists), but stops after it has been successfull, so any subsequent 21874 locations listed in the 21875\family typewriter 21876paths 21877\family default 21878 variable are not read. 21879 This has the effect that the file from the home directory has the highest 21880 priority too like in the previous example, but without any keys from the 21881 system files. 21882 Note the 21883\family typewriter 21884SHCONF_ONE 21885\family default 21886 flag. 21887\end_layout 21888 21889\begin_layout LyX-Code 21890 21891\series bold 21892const char * 21893\series default 21894home = getenv("HOME"); 21895\begin_inset Newline newline 21896\end_inset 21897 21898 21899\series bold 21900const char * 21901\series default 21902paths 21903\series bold 21904[] 21905\series default 21906 = {home, "/usr/local/etc", "/etc", NULL}; 21907\begin_inset Newline newline 21908\end_inset 21909 21910HX_shconfig_pv(paths, "test.cf", options_table, SHCONF_ONE); 21911\end_layout 21912 21913\begin_layout Standard 21914\begin_inset Newpage clearpage 21915\end_inset 21916 21917 21918\end_layout 21919 21920\begin_layout Part 21921Systems-related components 21922\end_layout 21923 21924\begin_layout Section 21925Random numbers 21926\begin_inset CommandInset label 21927LatexCommand label 21928name "sec:random" 21929 21930\end_inset 21931 21932 21933\end_layout 21934 21935\begin_layout Subsection 21936Function overview 21937\end_layout 21938 21939\begin_layout LyX-Code 21940 21941\series bold 21942#include 21943\series default 21944 <libHX/misc.h> 21945\begin_inset Index idx 21946status open 21947 21948\begin_layout Plain Layout 21949 21950\family typewriter 21951libHX/misc.h 21952\end_layout 21953 21954\end_inset 21955 21956 21957\begin_inset Newline newline 21958\end_inset 21959 21960 21961\begin_inset Newline newline 21962\end_inset 21963 21964 21965\series bold 21966int 21967\series default 21968 HX_rand( 21969\series bold 21970void 21971\series default 21972); 21973\begin_inset Index idx 21974status open 21975 21976\begin_layout Plain Layout 21977 21978\family typewriter 21979HX_rand 21980\end_layout 21981 21982\end_inset 21983 21984 21985\begin_inset Newline newline 21986\end_inset 21987 21988 21989\series bold 21990unsigned int 21991\series default 21992 HX_irand( 21993\series bold 21994unsigned int 21995\series default 21996 min, 21997\series bold 21998unsigned int 21999\series default 22000 max); 22001\begin_inset Index idx 22002status open 22003 22004\begin_layout Plain Layout 22005 22006\family typewriter 22007\size normal 22008\color none 22009HX_irand 22010\end_layout 22011 22012\end_inset 22013 22014 22015\begin_inset Newline newline 22016\end_inset 22017 22018 22019\series bold 22020double 22021\series default 22022 HX_drand( 22023\series bold 22024double 22025\series default 22026 min, 22027\series bold 22028double 22029\series default 22030 max); 22031\begin_inset Index idx 22032status open 22033 22034\begin_layout Plain Layout 22035 22036\family typewriter 22037HX_drand 22038\end_layout 22039 22040\end_inset 22041 22042 22043\end_layout 22044 22045\begin_layout Description 22046 22047\family typewriter 22048HX_rand 22049\family default 22050 Retrieve the next random number. 22051\end_layout 22052 22053\begin_layout Description 22054 22055\family typewriter 22056HX_irand 22057\family default 22058 Retrieve the next random number and fold it so that 22059\begin_inset Formula $\textit{min}\le n<\textit{max}$ 22060\end_inset 22061 22062, where min and max are unsigned integers. 22063\end_layout 22064 22065\begin_layout Description 22066 22067\family typewriter 22068HX_drand 22069\family default 22070 Retrieve the next random number and fold it so that 22071\begin_inset Formula $\textit{min}\le n<\textit{max}$ 22072\end_inset 22073 22074, where min and max are double-precision floating point numbers. 22075\end_layout 22076 22077\begin_layout Subsection 22078Implementation information 22079\end_layout 22080 22081\begin_layout Standard 22082On systems that provide operating system-level random number generators, 22083 predominantly Linux and Unix-alikes such as BSD and Solaris, these will 22084 be used when they are available and random numbers are requested through 22085 22086\family typewriter 22087HX_rand 22088\family default 22089 or 22090\family typewriter 22091HX_irand 22092\family default 22093. 22094\end_layout 22095 22096\begin_layout Standard 22097On Linux, Solaris and the BSDs, this is 22098\family typewriter 22099/dev/urandom 22100\family default 22101 22102\begin_inset Index idx 22103status open 22104 22105\begin_layout Plain Layout 22106 22107\family typewriter 22108/dev/urandom 22109\end_layout 22110 22111\end_inset 22112 22113. 22114\end_layout 22115 22116\begin_layout Standard 22117If no random number generating device is available (and libHX configured 22118 to use it), it will fall back to using the libc's 22119\family typewriter 22120rand 22121\family default 22122 22123\begin_inset Index idx 22124status open 22125 22126\begin_layout Plain Layout 22127 22128\family typewriter 22129rand 22130\end_layout 22131 22132\end_inset 22133 22134 function. 22135 If libc is selected for random number generation, 22136\family typewriter 22137srand 22138\family default 22139 will be called on library initialization with what is believed to be good 22140 defaults 22141\begin_inset space ~ 22142\end_inset 22143 22144— usually this will be before a program's 22145\family typewriter 22146main 22147\family default 22148 function with normal linking, but may actually happen later when used with 22149 22150\family typewriter 22151dlopen 22152\family default 22153. 22154 The initial seed would be the current microtime when 22155\family typewriter 22156gettimeofday 22157\begin_inset Index idx 22158status open 22159 22160\begin_layout Plain Layout 22161 22162\family typewriter 22163gettimeofday 22164\end_layout 22165 22166\end_inset 22167 22168 22169\family default 22170 is available, or just the seconds with 22171\family typewriter 22172time 22173\family default 22174 22175\begin_inset Index idx 22176status open 22177 22178\begin_layout Plain Layout 22179 22180\family typewriter 22181time 22182\end_layout 22183 22184\end_inset 22185 22186. 22187 To counter the problem of different programs potentially using the same 22188 seed within a time window of a second due to the limited granularity of 22189 standard 22190\family typewriter 22191time 22192\family default 22193, the seed is augmented by process ID and parent process ID where available. 22194\end_layout 22195 22196\begin_layout Standard 22197 22198\family typewriter 22199/dev/random 22200\begin_inset Index idx 22201status open 22202 22203\begin_layout Plain Layout 22204 22205\family typewriter 22206/dev/random 22207\end_layout 22208 22209\end_inset 22210 22211 22212\family default 22213 is not used on Linux because it may block during read, and 22214\family typewriter 22215/dev/urandom 22216\family default 22217 is just as good when there is entropy available. 22218 If you need definitive PRNG 22219\begin_inset Index idx 22220status open 22221 22222\begin_layout Plain Layout 22223PRNG 22224\end_layout 22225 22226\end_inset 22227 22228 security, perhaps use one from a crypto suite such as OpenSSL. 22229\end_layout 22230 22231\begin_layout Standard 22232\begin_inset Newpage clearpage 22233\end_inset 22234 22235 22236\end_layout 22237 22238\begin_layout Section 22239Process management 22240\begin_inset CommandInset label 22241LatexCommand label 22242name "sec:proc" 22243 22244\end_inset 22245 22246 22247\end_layout 22248 22249\begin_layout Standard 22250The process code is experimental at this stage (just moved from the pam_mount 22251 codebase). 22252 As it also relies on the POSIX functions 22253\family typewriter 22254fork 22255\family default 22256, 22257\family typewriter 22258execv 22259\family default 22260, 22261\family typewriter 22262execvp 22263\family default 22264 and 22265\family typewriter 22266pipe 22267\family default 22268(2), so it may not be available everywhere. 22269 Where this is the case, the functions will return 22270\family typewriter 22271-ENOSYS 22272\family default 22273. 22274\end_layout 22275 22276\begin_layout Subsection 22277Process metadata structure 22278\end_layout 22279 22280\begin_layout LyX-Code 22281 22282\series bold 22283#include 22284\series default 22285 <libHX/proc.h> 22286\begin_inset Index idx 22287status open 22288 22289\begin_layout Plain Layout 22290 22291\family typewriter 22292libHX/proc.h 22293\end_layout 22294 22295\end_inset 22296 22297 22298\begin_inset Newline newline 22299\end_inset 22300 22301 22302\begin_inset Newline newline 22303\end_inset 22304 22305 22306\series bold 22307struct 22308\series default 22309 HXproc { 22310\begin_inset Newline newline 22311\end_inset 22312 22313 22314\series bold 22315const struct 22316\series default 22317 HXproc_ops 22318\series bold 22319* 22320\series default 22321p_ops; 22322\begin_inset Newline newline 22323\end_inset 22324 22325 22326\series bold 22327void * 22328\series default 22329p_data; 22330\begin_inset Newline newline 22331\end_inset 22332 22333 22334\series bold 22335unsigned int 22336\series default 22337 p_flags; 22338\begin_inset Newline newline 22339\end_inset 22340 22341 22342\begin_inset Newline newline 22343\end_inset 22344 22345 22346\series bold 22347/* 22348\family roman 22349\series default 22350\shape italic 22351Following members should only be read 22352\family default 22353\series bold 22354\shape default 22355 */ 22356\series default 22357 22358\begin_inset Newline newline 22359\end_inset 22360 22361 22362\series bold 22363int 22364\series default 22365 p_stdin, p_stdout, p_stderr; 22366\begin_inset Newline newline 22367\end_inset 22368 22369 22370\series bold 22371int 22372\series default 22373 p_pid; 22374\begin_inset Newline newline 22375\end_inset 22376 22377 22378\series bold 22379char 22380\series default 22381 p_status; 22382\begin_inset Newline newline 22383\end_inset 22384 22385 22386\series bold 22387bool 22388\series default 22389 p_exited, p_terminated; 22390\begin_inset Newline newline 22391\end_inset 22392 22393}; 22394\end_layout 22395 22396\begin_layout Standard 22397When creating a new process with the intent of running it asynchronously 22398 (using 22399\family typewriter 22400HXproc_\SpecialChar softhyphen 22401run_\SpecialChar softhyphen 22402async 22403\family default 22404), the first three fields must be filled in by the user. 22405\end_layout 22406 22407\begin_layout Description 22408 22409\family typewriter 22410p_ops 22411\family default 22412 A table of callbacks, generally used for setting and/or restoring signals 22413 before/after execution. 22414 This member may be 22415\family typewriter 22416NULL 22417\family default 22418. 22419\end_layout 22420 22421\begin_layout Description 22422 22423\family typewriter 22424p_data 22425\family default 22426 Free pointer for the user to supply. 22427 Will be passed to the callback functions when they are invoked. 22428\end_layout 22429 22430\begin_layout Description 22431 22432\family typewriter 22433p_flags 22434\family default 22435 Process creation flags, see below. 22436\end_layout 22437 22438\begin_layout Standard 22439After the subprocess has been started, 22440\family typewriter 22441HXproc_run_async 22442\family default 22443 will have filled in some fields: 22444\end_layout 22445 22446\begin_layout Description 22447 22448\family typewriter 22449p_stdin 22450\family default 22451 If 22452\family typewriter 22453HXPROC_STDIN 22454\family default 22455 was specified in 22456\family typewriter 22457p_flags 22458\family default 22459, 22460\family typewriter 22461p_stdin 22462\family default 22463 will be assigned the write side file descriptor of the subprocess's to-be 22464 stdin. 22465 The subprocess will get the read side file descriptor in this member. 22466 This is so that the correct fd is used in when 22467\family typewriter 22468p_ops->p_postfork 22469\family default 22470 is called. 22471\end_layout 22472 22473\begin_layout Description 22474 22475\family typewriter 22476p_stdout 22477\family default 22478 If 22479\family typewriter 22480HXPROC_STDOUT 22481\family default 22482 is specified in 22483\family typewriter 22484p_flags 22485\family default 22486, 22487\family typewriter 22488p_stdout 22489\family default 22490 will be assigned the read side file descriptor of the subprocess's to-be 22491 stdout. 22492 The subprocess will get the write side file descriptor in this member. 22493\end_layout 22494 22495\begin_layout Description 22496 22497\family typewriter 22498p_stderr 22499\family default 22500 If 22501\family typewriter 22502HXPROC_STDERR 22503\family default 22504 is specified in 22505\family typewriter 22506p_flags 22507\family default 22508, 22509\family typewriter 22510p_stderr 22511\family default 22512 will be assigned the read side file descriptor of the subprocess's to-be 22513 stderr, and the subprocess will get the write side fd. 22514\end_layout 22515 22516\begin_layout Description 22517 22518\family typewriter 22519p_pid 22520\family default 22521 The process ID of the spawned process. 22522\end_layout 22523 22524\begin_layout Standard 22525Upon calling 22526\family typewriter 22527HXproc_wait 22528\family default 22529, further fields will have been filled when the function returns: 22530\end_layout 22531 22532\begin_layout Description 22533 22534\family typewriter 22535p_exited 22536\family default 22537 Whether the process exited normally (cf. 22538\begin_inset space \space{} 22539\end_inset 22540 22541signalled\SpecialChar breakableslash 22542terminated). 22543\end_layout 22544 22545\begin_layout Description 22546 22547\family typewriter 22548p_terminated 22549\family default 22550 Whether the process was terminated (signalled). 22551\end_layout 22552 22553\begin_layout Description 22554 22555\family typewriter 22556p_status 22557\family default 22558 The exit status of the process or the termination signal. 22559\end_layout 22560 22561\begin_layout Subsubsection 22562Flags 22563\begin_inset CommandInset label 22564LatexCommand label 22565name "subsec:proc-pflags" 22566 22567\end_inset 22568 22569 22570\end_layout 22571 22572\begin_layout Standard 22573Possible values for the 22574\family typewriter 22575p_flags 22576\family default 22577 member are: 22578\end_layout 22579 22580\begin_layout Description 22581 22582\family typewriter 22583HXPROC_STDIN 22584\series medium 22585 22586\begin_inset Index idx 22587status open 22588 22589\begin_layout Plain Layout 22590 22591\family typewriter 22592HXPROC_STDIN 22593\end_layout 22594 22595\end_inset 22596 22597 22598\family default 22599\series default 22600 The subprocess's stdin file descriptor shall be connected to the master 22601 program, that is, not inherit the stdin of the master. 22602 Cannot be used for 22603\family typewriter 22604HXproc_\SpecialChar softhyphen 22605run_\SpecialChar softhyphen 22606sync 22607\family default 22608 (because there would be no one to provide data in a sync operation). 22609\end_layout 22610 22611\begin_layout Description 22612 22613\family typewriter 22614HXPROC_STDOUT 22615\series medium 22616 22617\begin_inset Index idx 22618status open 22619 22620\begin_layout Plain Layout 22621 22622\family typewriter 22623\series medium 22624HXPROC_STDOUT 22625\end_layout 22626 22627\end_inset 22628 22629 22630\family default 22631\series default 22632 Connect the stdout file descriptor of the subprocess with the master. 22633 Cannot be used for 22634\family typewriter 22635HXproc_run_sync 22636\family default 22637. 22638\end_layout 22639 22640\begin_layout Description 22641 22642\family typewriter 22643HXPROC_STDERR 22644\series medium 22645 22646\begin_inset Index idx 22647status open 22648 22649\begin_layout Plain Layout 22650 22651\family typewriter 22652\series medium 22653HXPROC_STDERR 22654\end_layout 22655 22656\end_inset 22657 22658 22659\family default 22660\series default 22661 Connect the stderr file descriptor of the subprocess with the master. 22662 Cannot be used for 22663\family typewriter 22664HXproc_run_sync 22665\family default 22666. 22667\end_layout 22668 22669\begin_layout Description 22670 22671\family typewriter 22672HXPROC_NULL_STDIN 22673\family default 22674 22675\begin_inset Index idx 22676status open 22677 22678\begin_layout Plain Layout 22679 22680\family typewriter 22681HXPROC_NULL_STDIN 22682\end_layout 22683 22684\end_inset 22685 22686 The subprocess's stdin file descriptor shall be connected to 22687\family typewriter 22688/dev\SpecialChar breakableslash 22689null 22690\family default 22691. 22692 22693\family typewriter 22694HXPROC_\SpecialChar softhyphen 22695STDIN 22696\family default 22697 and 22698\family typewriter 22699HXPROC_\SpecialChar softhyphen 22700NULL_\SpecialChar softhyphen 22701STDIN 22702\family default 22703 are mutually exclusive. 22704\end_layout 22705 22706\begin_layout Description 22707 22708\family typewriter 22709HXPROC_NULL_STDOUT 22710\family default 22711 22712\begin_inset Index idx 22713status open 22714 22715\begin_layout Plain Layout 22716 22717\family typewriter 22718HXPROC_NULL_STDOUT 22719\end_layout 22720 22721\end_inset 22722 22723 Connect the stdout file descriptor of the subprocess to 22724\family typewriter 22725/dev\SpecialChar breakableslash 22726null 22727\family default 22728, thereby essentially discarding its output. 22729 22730\family typewriter 22731HXPROC_\SpecialChar softhyphen 22732STDOUT 22733\family default 22734 and 22735\family typewriter 22736HXPROC_\SpecialChar softhyphen 22737NULL_\SpecialChar softhyphen 22738STDOUT 22739\family default 22740 are mutuall exclusive. 22741\end_layout 22742 22743\begin_layout Description 22744 22745\family typewriter 22746HXPROC_NULL_STDERR 22747\family default 22748 22749\begin_inset Index idx 22750status open 22751 22752\begin_layout Plain Layout 22753 22754\family typewriter 22755HXPROC_NULL_STDERR 22756\end_layout 22757 22758\end_inset 22759 22760 Connect the stderr file descriptor of the subprocess to 22761\family typewriter 22762/dev\SpecialChar breakableslash 22763null 22764\family default 22765, thereby essentially discarding its output. 22766 22767\family typewriter 22768HXPROC_\SpecialChar softhyphen 22769STDERR 22770\family default 22771 and 22772\family typewriter 22773HXPROC_\SpecialChar softhyphen 22774NULL_\SpecialChar softhyphen 22775STDERR 22776\family default 22777 are mutually exclusive. 22778\end_layout 22779 22780\begin_layout Description 22781 22782\family typewriter 22783HXPROC_VERBOSE 22784\family default 22785 22786\begin_inset Index idx 22787status open 22788 22789\begin_layout Plain Layout 22790 22791\family typewriter 22792HXPROC_VERBOSE 22793\end_layout 22794 22795\end_inset 22796 22797 Have the subprocess print an error message to stderr if exec'ing returned 22798 an error. 22799\end_layout 22800 22801\begin_layout Description 22802 22803\family typewriter 22804HXPROC_A0 22805\family default 22806 22807\begin_inset Index idx 22808status open 22809 22810\begin_layout Plain Layout 22811 22812\family typewriter 22813HXPROC_A0 22814\end_layout 22815 22816\end_inset 22817 22818 22819\family typewriter 22820argv[0] 22821\family default 22822 refers to program file, while 22823\family typewriter 22824argv[1] 22825\family default 22826 to the program invocation name, with 22827\family typewriter 22828argv[2] 22829\family default 22830 being the arguments. 22831 Without this flag, 22832\family typewriter 22833argv[0] 22834\family default 22835 will be both the program file and program invocation name, and arguments 22836 begin at 22837\family typewriter 22838argv[1] 22839\family default 22840. 22841\end_layout 22842 22843\begin_layout Description 22844 22845\family typewriter 22846HXPROC_EXECV 22847\family default 22848 22849\begin_inset Index idx 22850status open 22851 22852\begin_layout Plain Layout 22853 22854\family typewriter 22855HXPROC_EXECV 22856\end_layout 22857 22858\end_inset 22859 22860 Normally, 22861\family typewriter 22862execvp 22863\family default 22864(3) 22865\begin_inset Index idx 22866status open 22867 22868\begin_layout Plain Layout 22869 22870\family typewriter 22871execvp 22872\end_layout 22873 22874\end_inset 22875 22876 will be used which scans 22877\family typewriter 22878$PATH 22879\family default 22880 for the program. 22881 Use this flag to use 22882\family typewriter 22883execv 22884\family default 22885(3) 22886\begin_inset Index idx 22887status open 22888 22889\begin_layout Plain Layout 22890 22891\family typewriter 22892execv 22893\end_layout 22894 22895\end_inset 22896 22897 instead, which will not do such thing. 22898\end_layout 22899 22900\begin_layout Subsection 22901Callbacks 22902\end_layout 22903 22904\begin_layout LyX-Code 22905 22906\series bold 22907#include 22908\series default 22909 <libHX/proc.h> 22910\begin_inset Newline newline 22911\end_inset 22912 22913 22914\begin_inset Newline newline 22915\end_inset 22916 22917 22918\series bold 22919struct 22920\series default 22921 HXproc_ops { 22922\begin_inset Newline newline 22923\end_inset 22924 22925 22926\series bold 22927void (* 22928\series default 22929p_prefork 22930\series bold 22931) 22932\series default 22933( 22934\series bold 22935void * 22936\series default 22937); 22938\begin_inset Newline newline 22939\end_inset 22940 22941 22942\series bold 22943void (* 22944\series default 22945p_postfork 22946\series bold 22947) 22948\series default 22949( 22950\series bold 22951void * 22952\series default 22953); 22954\begin_inset Newline newline 22955\end_inset 22956 22957 22958\series bold 22959void (* 22960\series default 22961p_complete 22962\series bold 22963) 22964\series default 22965( 22966\series bold 22967void * 22968\series default 22969); 22970\begin_inset Newline newline 22971\end_inset 22972 22973}; 22974\end_layout 22975 22976\begin_layout Standard 22977 22978\family typewriter 22979struct HXproc_ops 22980\family default 22981 provides a way to run user-specified functions just before the fork, after, 22982 and when the process has been waited for. 22983 They can be used to set and/or restore signals as needed, for example. 22984 The function pointers can be 22985\family typewriter 22986NULL 22987\family default 22988. 22989 The 22990\family typewriter 22991p_data 22992\family default 22993 member is passed as an argument. 22994\end_layout 22995 22996\begin_layout Description 22997 22998\family typewriter 22999p_prefork 23000\family default 23001 Run immediately before calling 23002\family typewriter 23003fork 23004\family default 23005(2). 23006 This is useful, for taking any action regarding signals, like setting 23007\family typewriter 23008SIGCHLD 23009\family default 23010 to 23011\family typewriter 23012SIG_DFL 23013\family default 23014, or 23015\family typewriter 23016SIGPIPE 23017\family default 23018 to 23019\family typewriter 23020SIG_IGN 23021\family default 23022, for example. 23023\end_layout 23024 23025\begin_layout Description 23026 23027\family typewriter 23028p_postfork 23029\family default 23030 Run in the subprocess (and only there) after forking. 23031 Useful to do a 23032\family typewriter 23033setuid 23034\family default 23035(2) or other change in privilege level. 23036\end_layout 23037 23038\begin_layout Description 23039 23040\family typewriter 23041p_complete 23042\family default 23043 Run in 23044\family typewriter 23045HXproc_wait 23046\family default 23047 when the process has been waited for. 23048 Useful to restore the signal handler(s). 23049\end_layout 23050 23051\begin_layout Subsection 23052Process control 23053\end_layout 23054 23055\begin_layout LyX-Code 23056 23057\series bold 23058#include 23059\series default 23060 <libHX/proc.h> 23061\begin_inset Newline newline 23062\end_inset 23063 23064 23065\series bold 23066 23067\begin_inset Newline newline 23068\end_inset 23069 23070int 23071\series default 23072 HXproc_run_async( 23073\series bold 23074const char *const * 23075\series default 23076argv, 23077\series bold 23078struct 23079\series default 23080 HXproc 23081\series bold 23082* 23083\series default 23084proc); 23085\begin_inset Index idx 23086status open 23087 23088\begin_layout Plain Layout 23089 23090\family typewriter 23091\size normal 23092\color none 23093HXproc_run_async 23094\end_layout 23095 23096\end_inset 23097 23098 23099\begin_inset Newline newline 23100\end_inset 23101 23102 23103\series bold 23104int 23105\series default 23106 HXproc_run_sync( 23107\series bold 23108const char *const * 23109\series default 23110argv, 23111\series bold 23112unsigned int 23113\series default 23114 flags); 23115\begin_inset Index idx 23116status open 23117 23118\begin_layout Plain Layout 23119 23120\family typewriter 23121\size normal 23122\color none 23123HXproc_run_sync 23124\end_layout 23125 23126\end_inset 23127 23128 23129\begin_inset Newline newline 23130\end_inset 23131 23132 23133\series bold 23134int 23135\series default 23136 HXproc_wait( 23137\series bold 23138struct 23139\series default 23140 HXproc 23141\series bold 23142* 23143\series default 23144proc); 23145\begin_inset Index idx 23146status open 23147 23148\begin_layout Plain Layout 23149 23150\family typewriter 23151\size normal 23152\color none 23153HXproc_wait 23154\end_layout 23155 23156\end_inset 23157 23158 23159\end_layout 23160 23161\begin_layout Description 23162 23163\family typewriter 23164HXproc_run_async 23165\family default 23166 Start a subprocess according to the parameters in 23167\family typewriter 23168proc 23169\family default 23170. 23171 Returns a negative errno code if something went wrong, or positive non-zero 23172 on success. 23173\end_layout 23174 23175\begin_layout Description 23176 23177\family typewriter 23178HXproc_run_sync 23179\family default 23180 Start a subprocess synchronously, similar to calling 23181\family typewriter 23182system 23183\family default 23184(3) 23185\begin_inset Index idx 23186status open 23187 23188\begin_layout Plain Layout 23189 23190\family typewriter 23191system 23192\end_layout 23193 23194\end_inset 23195 23196, but with the luxury of being able to specify arguments as separate strings 23197 (via argv) rather than one big command line that is run through the shell. 23198 23199\family typewriter 23200flags 23201\family default 23202 is a value composed of the HXproc flags mentioned above in section 23203\begin_inset space ~ 23204\end_inset 23205 23206 23207\begin_inset CommandInset ref 23208LatexCommand ref 23209reference "subsec:proc-pflags" 23210 23211\end_inset 23212 23213. 23214 23215\family typewriter 23216HXPROC_STDIN 23217\family default 23218, 23219\family typewriter 23220HXPROC_STDOUT 23221\family default 23222 and 23223\family typewriter 23224HXPROC_STDERR 23225\family default 23226 are ignored because there would be no one in a synchronous execution that 23227 could supply data to these file descriptors or read from them 23228\begin_inset Foot 23229status open 23230 23231\begin_layout Plain Layout 23232Even for threads, please just use the async model. 23233\end_layout 23234 23235\end_inset 23236 23237. 23238\end_layout 23239 23240\begin_layout Description 23241 23242\family typewriter 23243HXproc_wait 23244\family default 23245 Wait for a subprocess to terminate, if it has not already. 23246 It will also retrieve the exit status of the process and store it in the 23247 23248\family typewriter 23249struct HXproc 23250\family default 23251. 23252\end_layout 23253 23254\begin_layout Standard 23255Return value will be positive non-zero on success, or negative on error. 23256 Underlying system function's errors are returned, plus: 23257\end_layout 23258 23259\begin_layout Description 23260 23261\family sans 23262EINVAL 23263\family default 23264 Flags were not accepted. 23265\end_layout 23266 23267\begin_layout Section 23268Helper headers 23269\end_layout 23270 23271\begin_layout Subsection 23272ctype helpers 23273\end_layout 23274 23275\begin_layout Standard 23276Functions from the 23277\family typewriter 23278<ctype.h> 23279\family default 23280 header, including, but not limited to, 23281\family typewriter 23282isalpha 23283\family default 23284, 23285\family typewriter 23286tolower 23287\family default 23288, and so forth, are defined to take an 23289\begin_inset Quotes eld 23290\end_inset 23291 23292 23293\family typewriter 23294int 23295\family default 23296 23297\begin_inset Quotes erd 23298\end_inset 23299 23300 as first argument. 23301 Strings used in C programs are usually 23302\begin_inset Quotes eld 23303\end_inset 23304 23305 23306\family typewriter 23307char 23308\begin_inset space ~ 23309\end_inset 23310 23311* 23312\family default 23313 23314\begin_inset Quotes erd 23315\end_inset 23316 23317, without any 23318\begin_inset Quotes eld 23319\end_inset 23320 23321 23322\family typewriter 23323signed 23324\family default 23325 23326\begin_inset Quotes erd 23327\end_inset 23328 23329 or 23330\begin_inset Quotes eld 23331\end_inset 23332 23333 23334\family typewriter 23335unsigned 23336\family default 23337 23338\begin_inset Quotes erd 23339\end_inset 23340 23341 qualifier. 23342 By a high-level view, which also matches daily common sense, characters 23343 (a. 23344\begin_inset space \thinspace{} 23345\end_inset 23346 23347k. 23348\begin_inset space \thinspace{} 23349\end_inset 23350 23351a. 23352\begin_inset space \space{} 23353\end_inset 23354 23355letters) have no notion of signedness 23356\begin_inset space ~ 23357\end_inset 23358 23359— there is no 23360\begin_inset Quotes eld 23361\end_inset 23362 23363positive 23364\begin_inset Quotes erd 23365\end_inset 23366 23367 or 23368\begin_inset Quotes eld 23369\end_inset 23370 23371negative 23372\begin_inset Quotes erd 23373\end_inset 23374 23375 23376\begin_inset Quotes eld 23377\end_inset 23378 23379A 23380\begin_inset Quotes erd 23381\end_inset 23382 23383 in at least the Latin alphabet that is mapped into the ASCII set. 23384 In fact, 23385\family typewriter 23386char 23387\begin_inset space ~ 23388\end_inset 23389 23390* 23391\family default 23392 could either be 23393\family typewriter 23394signed char 23395\begin_inset space ~ 23396\end_inset 23397 23398* 23399\family default 23400 or 23401\family typewriter 23402unsigned char 23403\begin_inset space ~ 23404\end_inset 23405 23406* 23407\family default 23408, depending on the compiler settings. 23409 Only when you start interpreting and using characters as a number does 23410 such become important. 23411 23412\end_layout 23413 23414\begin_layout Standard 23415There come the problems. 23416 Characters are in the same class as numbers in C, that is, can be implicitly 23417 converted from or to a 23418\begin_inset Quotes eld 23419\end_inset 23420 23421number 23422\begin_inset Quotes erd 23423\end_inset 23424 23425 (in this case, their ASCII code point) without causing a compiler warning. 23426 That may be practical in some cases, but is also a bit 23427\begin_inset Quotes eld 23428\end_inset 23429 23430unfortunate 23431\begin_inset Quotes erd 23432\end_inset 23433 23434. 23435 Characters, when interpreted as the 8-bit signed numeric quantity they 23436 are implicitly convertable to, run from 0 to 127 and \SpecialChar nobreakdash 23437128 to \SpecialChar nobreakdash 234381. 23439 Since the 23440\family typewriter 23441isalpha 23442\family default 23443 function and others from 23444\family typewriter 23445ctype.h 23446\family default 23447 take a (signed) 23448\family typewriter 23449int 23450\family default 23451 as argument means that values fed to 23452\family typewriter 23453isalpha 23454\family default 23455 are sign-extended, preserving negative values. 23456\end_layout 23457 23458\begin_layout LyX-Code 23459 23460\series bold 23461/* 23462\family roman 23463\series default 23464\shape italic 23465 23466\begin_inset Quotes eld 23467\end_inset 23468 23469hyvää yötä 23470\begin_inset Quotes erd 23471\end_inset 23472 23473, UTF-8 encoded 23474\family default 23475\series bold 23476\shape default 23477 */ 23478\end_layout 23479 23480\begin_layout LyX-Code 23481 23482\series bold 23483const char 23484\series default 23485h 23486\series bold 23487[] 23488\series default 23489 = {'h', 'y', 'v', 0xc3, 0xa4, 0xc3, 0xa4, ' ', 23490\begin_inset Newline newline 23491\end_inset 23492 23493 'y', 0xc3, 0xb6, 't', 0xc3, 0xa4}; 23494\end_layout 23495 23496\begin_layout Standard 23497When you now pass 23498\family typewriter 23499h[3] 23500\family default 23501 to 23502\family typewriter 23503isalpha 23504\family default 23505 for example (regardless of whether doing so actually produces a meaningful 23506 result), the CPU is instructed to copy 23507\begin_inset Quotes eld 23508\end_inset 23509 235100xc3 23511\begin_inset Quotes erd 23512\end_inset 23513 23514 into a register and sign-extend it (because 23515\begin_inset Quotes eld 23516\end_inset 23517 23518char 23519\begin_inset Quotes erd 23520\end_inset 23521 23522 is often 23523\begin_inset Quotes eld 23524\end_inset 23525 23526signed char 23527\begin_inset Quotes erd 23528\end_inset 23529 23530, see above), producing 0xffffffc3 (\SpecialChar nobreakdash 2353161). 23532 But passing \SpecialChar nobreakdash 2353361 is not what was intended. 23534\end_layout 23535 23536\begin_layout Standard 23537libHX's 23538\family typewriter 23539ctype_helper.h 23540\family default 23541 therefore provides wrappers with a different function signature that uses 23542 zero extension (not sign extension) by means of using an 23543\family typewriter 23544unsigned 23545\family default 23546 quantity. 23547 Currently this is 23548\family typewriter 23549 unsigned char 23550\family default 23551, because 23552\family typewriter 23553isalpha 23554\family default 23555's domain only goes from 0–255. 23556 The implication is that you cannot pass 23557\family typewriter 23558EOF 23559\family default 23560 to 23561\family typewriter 23562HX_isalpha 23563\family default 23564. 23565\end_layout 23566 23567\begin_layout LyX-Code 23568 23569\series bold 23570#include 23571\series default 23572 <libHX/ctype_helper.h> 23573\begin_inset Index idx 23574status open 23575 23576\begin_layout Plain Layout 23577 23578\family typewriter 23579libHX/ctype_helper.h 23580\end_layout 23581 23582\end_inset 23583 23584 23585\begin_inset Newline newline 23586\end_inset 23587 23588 23589\begin_inset Newline newline 23590\end_inset 23591 23592 23593\series bold 23594bool 23595\series default 23596 HX_isalnum( 23597\series bold 23598unsigned char 23599\series default 23600 c); 23601\begin_inset Index idx 23602status open 23603 23604\begin_layout Plain Layout 23605 23606\family typewriter 23607\size normal 23608\color none 23609HX_isalnum 23610\end_layout 23611 23612\end_inset 23613 23614 23615\begin_inset Newline newline 23616\end_inset 23617 23618 23619\series bold 23620bool 23621\series default 23622 HX_isalpha( 23623\series bold 23624unsigned char 23625\series default 23626 c); 23627\begin_inset Index idx 23628status open 23629 23630\begin_layout Plain Layout 23631 23632\family typewriter 23633\size normal 23634\color none 23635HX_isalpha 23636\end_layout 23637 23638\end_inset 23639 23640 23641\begin_inset Newline newline 23642\end_inset 23643 23644 23645\series bold 23646bool 23647\series default 23648 HX_isdigit( 23649\series bold 23650unsigned char 23651\series default 23652 c); 23653\begin_inset Index idx 23654status open 23655 23656\begin_layout Plain Layout 23657 23658\family typewriter 23659\size normal 23660\color none 23661HX_isdigit 23662\end_layout 23663 23664\end_inset 23665 23666 23667\begin_inset Newline newline 23668\end_inset 23669 23670 23671\series bold 23672bool 23673\series default 23674 HX_islower( 23675\series bold 23676unsigned char 23677\series default 23678 c); 23679\begin_inset Index idx 23680status open 23681 23682\begin_layout Plain Layout 23683 23684\family typewriter 23685\size normal 23686\color none 23687HX_islower 23688\end_layout 23689 23690\end_inset 23691 23692 23693\begin_inset Newline newline 23694\end_inset 23695 23696 23697\series bold 23698bool 23699\series default 23700 HX_isprint( 23701\series bold 23702unsigned char 23703\series default 23704 c); 23705\begin_inset Index idx 23706status open 23707 23708\begin_layout Plain Layout 23709 23710\family typewriter 23711\size normal 23712\color none 23713HX_isprint 23714\end_layout 23715 23716\end_inset 23717 23718 23719\begin_inset Newline newline 23720\end_inset 23721 23722 23723\series bold 23724bool 23725\series default 23726 HX_isspace( 23727\series bold 23728unsigned char 23729\series default 23730 c); 23731\begin_inset Index idx 23732status open 23733 23734\begin_layout Plain Layout 23735 23736\family typewriter 23737HX_isspace 23738\end_layout 23739 23740\end_inset 23741 23742 23743\begin_inset Newline newline 23744\end_inset 23745 23746 23747\series bold 23748bool 23749\series default 23750 HX_isupper( 23751\series bold 23752unsigned char 23753\series default 23754 c); 23755\begin_inset Index idx 23756status open 23757 23758\begin_layout Plain Layout 23759 23760\family typewriter 23761HX_isupper 23762\end_layout 23763 23764\end_inset 23765 23766 23767\begin_inset Newline newline 23768\end_inset 23769 23770 23771\series bold 23772bool 23773\series default 23774 HX_isxdigit( 23775\series bold 23776unsigned char 23777\series default 23778 c); 23779\begin_inset Index idx 23780status open 23781 23782\begin_layout Plain Layout 23783 23784\family typewriter 23785\size normal 23786\color none 23787HX_isxdigit 23788\end_layout 23789 23790\end_inset 23791 23792 23793\begin_inset Newline newline 23794\end_inset 23795 23796 23797\series bold 23798unsigned char 23799\series default 23800 HX_tolower( 23801\series bold 23802unsigned char 23803\series default 23804 c); 23805\begin_inset Index idx 23806status open 23807 23808\begin_layout Plain Layout 23809 23810\family typewriter 23811\size normal 23812\color none 23813HX_tolower 23814\end_layout 23815 23816\end_inset 23817 23818 23819\begin_inset Newline newline 23820\end_inset 23821 23822 23823\series bold 23824unsigned char 23825\series default 23826 HX_toupper( 23827\series bold 23828unsigned char 23829\series default 23830 c); 23831\begin_inset Index idx 23832status open 23833 23834\begin_layout Plain Layout 23835 23836\family typewriter 23837\size normal 23838\color none 23839HX_toupper 23840\end_layout 23841 23842\end_inset 23843 23844 23845\end_layout 23846 23847\begin_layout Standard 23848The 23849\family typewriter 23850is* 23851\family default 23852 functions also differ from ctype's in that they return 23853\family typewriter 23854bool 23855\family default 23856 instead of 23857\family typewriter 23858int 23859\family default 23860. 23861 Not all functions from 23862\family typewriter 23863ctype.h 23864\family default 23865 are present either; 23866\family typewriter 23867isascii 23868\family default 23869, 23870\family typewriter 23871isblank 23872\family default 23873, 23874\family typewriter 23875iscntrl 23876\family default 23877, 23878\family typewriter 23879isgraph 23880\family default 23881, 23882\family typewriter 23883ispunct 23884\family default 23885 and 23886\family typewriter 23887isxdigit 23888\family default 23889 have been omitted as the author has never needed them so far. 23890\end_layout 23891 23892\begin_layout Subsection 23893libxml2 helpers 23894\end_layout 23895 23896\begin_layout Standard 23897libxml2 uses an 23898\begin_inset Quotes eld 23899\end_inset 23900 23901 23902\family typewriter 23903xmlChar 23904\family default 23905 23906\begin_inset Quotes erd 23907\end_inset 23908 23909 type as an underlying type for the strings that it reads and outputs. 23910 23911\family typewriter 23912xmlChar 23913\family default 23914 is typedef'ed to 23915\family typewriter 23916unsigned char 23917\family default 23918 by libxml2, causing compiler warnings related to differing signedness whenever 23919 interacting with strings from the outside world, which are usually just 23920 a pointer to 23921\family typewriter 23922char 23923\family default 23924. 23925 Because casting would be a real chore, 23926\family typewriter 23927libxml_helper.h 23928\family default 23929 will do it by providing some wrappers with better argument types. 23930\end_layout 23931 23932\begin_layout LyX-Code 23933 23934\series bold 23935#include 23936\series default 23937 <libHX/libxml_helper.h> 23938\begin_inset Index idx 23939status open 23940 23941\begin_layout Plain Layout 23942 23943\family typewriter 23944libHX/libxml_helper.h 23945\end_layout 23946 23947\end_inset 23948 23949 23950\begin_inset Newline newline 23951\end_inset 23952 23953 23954\begin_inset Newline newline 23955\end_inset 23956 23957 23958\series bold 23959int 23960\series default 23961 xml_strcmp( 23962\series bold 23963const 23964\series default 23965 xmlChar 23966\series bold 23967* 23968\series default 23969a, 23970\series bold 23971const char * 23972\series default 23973b); 23974\begin_inset Index idx 23975status open 23976 23977\begin_layout Plain Layout 23978 23979\family typewriter 23980xml_strcmp 23981\end_layout 23982 23983\end_inset 23984 23985 23986\begin_inset Newline newline 23987\end_inset 23988 23989 23990\series bold 23991int 23992\series default 23993 xml_strcasecmp( 23994\series bold 23995const 23996\series default 23997 xmlChar 23998\series bold 23999* 24000\series default 24001a, 24002\series bold 24003const char * 24004\series default 24005b); 24006\begin_inset Index idx 24007status open 24008 24009\begin_layout Plain Layout 24010 24011\family typewriter 24012xml_strcasecmp 24013\end_layout 24014 24015\end_inset 24016 24017 24018\begin_inset Newline newline 24019\end_inset 24020 24021 24022\series bold 24023char * 24024\series default 24025xml_getprop(xmlNode 24026\series bold 24027* 24028\series default 24029node, 24030\series bold 24031const char * 24032\series default 24033attr); 24034\begin_inset Index idx 24035status open 24036 24037\begin_layout Plain Layout 24038 24039\family typewriter 24040xml_getprop 24041\end_layout 24042 24043\end_inset 24044 24045 24046\begin_inset Newline newline 24047\end_inset 24048 24049char *xml_getnsprop( 24050\series bold 24051xmlNode * 24052\series default 24053node, 24054\series bold 24055const char * 24056\series default 24057nsprefix, 24058\series bold 24059const char * 24060\series default 24061attr); 24062\begin_inset Index idx 24063status open 24064 24065\begin_layout Plain Layout 24066xml_getnsprop 24067\end_layout 24068 24069\end_inset 24070 24071 24072\begin_inset Newline newline 24073\end_inset 24074 24075xmlAttr 24076\series bold 24077* 24078\series default 24079xml_newprop(xmlNode 24080\series bold 24081* 24082\series default 24083node, 24084\series bold 24085const char * 24086\series default 24087attr); 24088\begin_inset Index idx 24089status open 24090 24091\begin_layout Plain Layout 24092 24093\family typewriter 24094xml_newprop 24095\end_layout 24096 24097\end_inset 24098 24099 24100\begin_inset Newline newline 24101\end_inset 24102 24103xmlNode 24104\series bold 24105* 24106\series default 24107xml_newnode(xmlNode 24108\series bold 24109* 24110\series default 24111parent, 24112\series bold 24113const char * 24114\series default 24115name, 24116\series bold 24117const char * 24118\series default 24119value); 24120\begin_inset Index idx 24121status open 24122 24123\begin_layout Plain Layout 24124 24125\family typewriter 24126\size normal 24127\color none 24128xml_newnode 24129\end_layout 24130 24131\end_inset 24132 24133 24134\begin_inset Newline newline 24135\end_inset 24136 24137xmlAttr 24138\series bold 24139* 24140\series default 24141xml_setprop(xmlNode 24142\series bold 24143* 24144\series default 24145node, 24146\series bold 24147const char * 24148\series default 24149name, 24150\series bold 24151const char * 24152\series default 24153value); 24154\begin_inset Index idx 24155status open 24156 24157\begin_layout Plain Layout 24158 24159\family typewriter 24160\size normal 24161\color none 24162xml_setprop 24163\end_layout 24164 24165\end_inset 24166 24167 24168\end_layout 24169 24170\begin_layout Standard 24171The functions map to 24172\family typewriter 24173strcmp 24174\family default 24175(3) 24176\begin_inset Index idx 24177status open 24178 24179\begin_layout Plain Layout 24180 24181\family typewriter 24182strcmp 24183\end_layout 24184 24185\end_inset 24186 24187, 24188\family typewriter 24189strcasecmp 24190\family default 24191(3) 24192\begin_inset Index idx 24193status open 24194 24195\begin_layout Plain Layout 24196 24197\family typewriter 24198strcasecmp 24199\end_layout 24200 24201\end_inset 24202 24203, 24204\begin_inset Index idx 24205status open 24206 24207\begin_layout Plain Layout 24208 24209\family typewriter 24210xmlGetProp 24211\end_layout 24212 24213\end_inset 24214 24215 24216\family typewriter 24217xmlGetProp 24218\family default 24219, 24220\begin_inset Index idx 24221status open 24222 24223\begin_layout Plain Layout 24224 24225\family typewriter 24226xmlNewProp 24227\end_layout 24228 24229\end_inset 24230 24231 24232\family typewriter 24233xmlNewProp 24234\family default 24235, 24236\begin_inset Index idx 24237status open 24238 24239\begin_layout Plain Layout 24240 24241\family typewriter 24242xmlNewTextNode 24243\end_layout 24244 24245\end_inset 24246 24247 24248\family typewriter 24249xml\SpecialChar softhyphen 24250New\SpecialChar softhyphen 24251Text\SpecialChar softhyphen 24252Node 24253\family default 24254 and 24255\begin_inset Index idx 24256status open 24257 24258\begin_layout Plain Layout 24259 24260\family typewriter 24261xmlSetProp 24262\end_layout 24263 24264\end_inset 24265 24266 24267\family typewriter 24268xml\SpecialChar softhyphen 24269Set\SpecialChar softhyphen 24270Prop 24271\family default 24272, respectively. 24273\end_layout 24274 24275\begin_layout Standard 24276 24277\family typewriter 24278xml_getnsprop 24279\family default 24280 works similar to 24281\family typewriter 24282xmlGetNsProp 24283\family default 24284, but instead of taking a namespace URI, it does a lookup by namespace prefix. 24285 The argument order is also different compared to 24286\family typewriter 24287xmlGetNsProp 24288\family default 24289. 24290\end_layout 24291 24292\begin_layout Subsection 24293wxWidgets 24294\end_layout 24295 24296\begin_layout LyX-Code 24297 24298\series bold 24299#include 24300\series default 24301 <libHX/wx_helper.hpp> 24302\begin_inset Index idx 24303status open 24304 24305\begin_layout Plain Layout 24306 24307\family typewriter 24308libHX/wx_helper.hpp 24309\end_layout 24310 24311\end_inset 24312 24313 24314\end_layout 24315 24316\begin_layout Subsubsection 24317Shortcut macros 24318\end_layout 24319 24320\begin_layout Description 24321\begin_inset Index idx 24322status open 24323 24324\begin_layout Plain Layout 24325 24326\family typewriter 24327wxACV 24328\end_layout 24329 24330\end_inset 24331 24332 24333\family typewriter 24334wxACV 24335\family default 24336 Expands to 24337\family typewriter 24338 24339\begin_inset Index idx 24340status open 24341 24342\begin_layout Plain Layout 24343 24344\family typewriter 24345wxALIGN_CENTER_VERTICAL 24346\end_layout 24347 24348\end_inset 24349 24350wxALIGN_CENTER_VERTICAL 24351\end_layout 24352 24353\begin_layout Description 24354\begin_inset Index idx 24355status open 24356 24357\begin_layout Plain Layout 24358 24359\family typewriter 24360wxCDF 24361\end_layout 24362 24363\end_inset 24364 24365 24366\family typewriter 24367wxCDF 24368\family default 24369 Expands to a set of common dialog flags for 24370\family typewriter 24371wxDialog 24372\family default 24373s, which includes 24374\family typewriter 24375wxDEFAULT_\SpecialChar softhyphen 24376FRAME_\SpecialChar softhyphen 24377STYLE 24378\family default 24379 and a flag such that the dialog does not create a new window in the task 24380 bar ( 24381\family typewriter 24382wxFRAME_\SpecialChar softhyphen 24383NO_\SpecialChar softhyphen 24384TASKBAR 24385\family default 24386). 24387\end_layout 24388 24389\begin_layout Description 24390\begin_inset Index idx 24391status open 24392 24393\begin_layout Plain Layout 24394 24395\family typewriter 24396wxDPOS 24397\end_layout 24398 24399\end_inset 24400 24401 24402\family typewriter 24403wxDPOS 24404\family default 24405 Expands to 24406\begin_inset Index idx 24407status open 24408 24409\begin_layout Plain Layout 24410 24411\family typewriter 24412wxDefaultPosition 24413\end_layout 24414 24415\end_inset 24416 24417 24418\family typewriter 24419wxDefaultPosition 24420\family default 24421. 24422\end_layout 24423 24424\begin_layout Description 24425\begin_inset Index idx 24426status open 24427 24428\begin_layout Plain Layout 24429 24430\family typewriter 24431wxDSIZE 24432\end_layout 24433 24434\end_inset 24435 24436 24437\family typewriter 24438wxDSIZE 24439\family default 24440 Expands to 24441\begin_inset Index idx 24442status open 24443 24444\begin_layout Plain Layout 24445 24446\family typewriter 24447wxDefaultSize 24448\end_layout 24449 24450\end_inset 24451 24452 24453\family typewriter 24454wxDefaultSize 24455\family default 24456. 24457\end_layout 24458 24459\begin_layout Description 24460\begin_inset Index idx 24461status open 24462 24463\begin_layout Plain Layout 24464 24465\family typewriter 24466wxDSPAN 24467\end_layout 24468 24469\end_inset 24470 24471 24472\family typewriter 24473wxDSPAN 24474\family default 24475 Expands to 24476\begin_inset Index idx 24477status open 24478 24479\begin_layout Plain Layout 24480 24481\family typewriter 24482wxDefaultSpan 24483\end_layout 24484 24485\end_inset 24486 24487 24488\family typewriter 24489wxDefaultSpan 24490\family default 24491. 24492\end_layout 24493 24494\begin_layout Subsubsection 24495String conversion 24496\end_layout 24497 24498\begin_layout LyX-Code 24499wxString wxfu8( 24500\series bold 24501const char * 24502\series default 24503); 24504\begin_inset Index idx 24505status open 24506 24507\begin_layout Plain Layout 24508 24509\family typewriter 24510wxfu8 24511\end_layout 24512 24513\end_inset 24514 24515 24516\begin_inset Newline newline 24517\end_inset 24518 24519wxString wxfv8( 24520\series bold 24521const char * 24522\series default 24523); 24524\begin_inset Index idx 24525status open 24526 24527\begin_layout Plain Layout 24528 24529\family typewriter 24530wxfv8 24531\end_layout 24532 24533\end_inset 24534 24535 24536\begin_inset Newline newline 24537\end_inset 24538 24539 24540\series bold 24541const char * 24542\series default 24543wxtu8( 24544\series bold 24545const 24546\series default 24547 wxString 24548\series bold 24549& 24550\series default 24551); 24552\begin_inset Index idx 24553status open 24554 24555\begin_layout Plain Layout 24556 24557\family typewriter 24558wxtu8 24559\end_layout 24560 24561\end_inset 24562 24563 24564\end_layout 24565 24566\begin_layout Description 24567 24568\family typewriter 24569wxfu8 24570\family default 24571 Converts an UTF-8 string to a 24572\begin_inset Index idx 24573status open 24574 24575\begin_layout Plain Layout 24576 24577\family typewriter 24578wxString 24579\end_layout 24580 24581\end_inset 24582 24583 24584\family typewriter 24585wxString 24586\family default 24587 object. 24588\end_layout 24589 24590\begin_layout Description 24591 24592\family typewriter 24593wxfv8 24594\family default 24595 Converts an UTF-8 string to an entity usable by 24596\begin_inset Index idx 24597status open 24598 24599\begin_layout Plain Layout 24600 24601\family typewriter 24602wxPrintf 24603\end_layout 24604 24605\end_inset 24606 24607 24608\family typewriter 24609wxPrintf 24610\family default 24611. 24612\end_layout 24613 24614\begin_layout Description 24615 24616\family typewriter 24617wxtu8 24618\family default 24619 Converts a wxString to a pointer to char usable by 24620\family typewriter 24621printf 24622\family default 24623. 24624 Note that the validity of the pointer is very limited and usually does 24625 not extend the statement in which it is used. 24626 Hence storing the pointer in a variable ( 24627\begin_inset Quotes eld 24628\end_inset 24629 24630 24631\family typewriter 24632const char *p = wxtu8(s); 24633\family default 24634 24635\begin_inset Quotes erd 24636\end_inset 24637 24638) will make 24639\family typewriter 24640p 24641\family default 24642 pointing to an invalid region as soon as the assignment is done. 24643\end_layout 24644 24645\begin_layout Part 24646\start_of_appendix 24647Appendix 24648\end_layout 24649 24650\begin_layout Standard 24651\begin_inset CommandInset index_print 24652LatexCommand printindex 24653type "idx" 24654name "Index" 24655literal "true" 24656 24657\end_inset 24658 24659 24660\end_layout 24661 24662\end_body 24663\end_document 24664