glib2 3.0.7-x86-mingw32 → 3.0.8-x86-mingw32

Sign up to get free protection for your applications and to get access to all the features.
Files changed (1058) hide show
  1. checksums.yaml +4 -4
  2. data/Rakefile +24 -12
  3. data/ext/glib2/extconf.rb +1 -0
  4. data/ext/glib2/glib2.def +4 -0
  5. data/ext/glib2/rbglib-variant.c +163 -12
  6. data/ext/glib2/rbglib.c +31 -8
  7. data/ext/glib2/rbglib.h +15 -1
  8. data/ext/glib2/rbglib2conversions.h +3 -0
  9. data/ext/glib2/rbglib_iochannel.c +0 -3
  10. data/ext/glib2/rbglib_iochannel_win32_socket.c +0 -1
  11. data/ext/glib2/rbglib_matchinfo.c +179 -0
  12. data/ext/glib2/rbglib_regex.c +484 -0
  13. data/ext/glib2/rbgobj_value.c +7 -1
  14. data/ext/glib2/rbgprivate.h +2 -0
  15. data/ext/glib2/rbgutil.c +7 -0
  16. data/ext/glib2/rbgutil.h +2 -0
  17. data/lib/2.2/glib2.so +0 -0
  18. data/lib/2.3/glib2.so +0 -0
  19. data/lib/glib2/regex.rb +29 -0
  20. data/lib/glib2.rb +2 -1
  21. data/lib/gnome2/rake/external-package.rb +6 -1
  22. data/lib/gnome2/rake/package-task.rb +1 -1
  23. data/lib/gnome2/rake/package.rb +9 -0
  24. data/lib/gnome2/rake/windows-binary-build-task.rb +35 -11
  25. data/lib/mkmf-gnome2.rb +3 -1
  26. data/test/test-match-info.rb +113 -0
  27. data/test/test-regex.rb +320 -0
  28. data/vendor/local/bin/asn1Coding.exe +0 -0
  29. data/vendor/local/bin/asn1Decoding.exe +0 -0
  30. data/vendor/local/bin/asn1Parser.exe +0 -0
  31. data/vendor/local/bin/envsubst.exe +0 -0
  32. data/vendor/local/bin/gdbus.exe +0 -0
  33. data/vendor/local/bin/gettext.exe +0 -0
  34. data/vendor/local/bin/gettext.sh +1 -1
  35. data/vendor/local/bin/gio-querymodules.exe +0 -0
  36. data/vendor/local/bin/glib-compile-resources.exe +0 -0
  37. data/vendor/local/bin/glib-compile-schemas.exe +0 -0
  38. data/vendor/local/bin/glib-genmarshal.exe +0 -0
  39. data/vendor/local/bin/glib-gettextize +1 -1
  40. data/vendor/local/bin/glib-mkenums +2 -2
  41. data/vendor/local/bin/gobject-query.exe +0 -0
  42. data/vendor/local/bin/gresource.exe +0 -0
  43. data/vendor/local/bin/gsettings.exe +0 -0
  44. data/vendor/local/bin/gspawn-win32-helper-console.exe +0 -0
  45. data/vendor/local/bin/gspawn-win32-helper.exe +0 -0
  46. data/vendor/local/bin/iconv.exe +0 -0
  47. data/vendor/local/bin/idn.exe +0 -0
  48. data/vendor/local/bin/libasprintf-0.dll +0 -0
  49. data/vendor/local/bin/libcharset-1.dll +0 -0
  50. data/vendor/local/bin/libffi-6.dll +0 -0
  51. data/vendor/local/bin/libgio-2.0-0.dll +0 -0
  52. data/vendor/local/bin/libglib-2.0-0.dll +0 -0
  53. data/vendor/local/bin/libgmodule-2.0-0.dll +0 -0
  54. data/vendor/local/bin/libgmp-10.dll +0 -0
  55. data/vendor/local/bin/libgnutls-30.def +993 -984
  56. data/vendor/local/bin/libgnutls-30.dll +0 -0
  57. data/vendor/local/bin/libgobject-2.0-0.dll +0 -0
  58. data/vendor/local/bin/libgthread-2.0-0.dll +0 -0
  59. data/vendor/local/bin/libhogweed-4-2.dll +0 -0
  60. data/vendor/local/bin/libiconv-2.dll +0 -0
  61. data/vendor/local/bin/libidn-11.dll +0 -0
  62. data/vendor/local/bin/libintl-8.dll +0 -0
  63. data/vendor/local/bin/{libnettle-6-1.dll → libnettle-6-2.dll} +0 -0
  64. data/vendor/local/bin/libp11-kit-0.dll +0 -0
  65. data/vendor/local/bin/libpcre-1.dll +0 -0
  66. data/vendor/local/bin/libpcrecpp-0.dll +0 -0
  67. data/vendor/local/bin/libpcreposix-0.dll +0 -0
  68. data/vendor/local/bin/libtasn1-6.dll +0 -0
  69. data/vendor/local/bin/nettle-hash.exe +0 -0
  70. data/vendor/local/bin/nettle-lfib-stream.exe +0 -0
  71. data/vendor/local/bin/nettle-pbkdf2.exe +0 -0
  72. data/vendor/local/bin/ngettext.exe +0 -0
  73. data/vendor/local/bin/p11-kit.exe +0 -0
  74. data/vendor/local/bin/pcre-config +133 -0
  75. data/vendor/local/bin/pcregrep.exe +0 -0
  76. data/vendor/local/bin/pcretest.exe +0 -0
  77. data/vendor/local/bin/pkcs1-conv.exe +0 -0
  78. data/vendor/local/bin/sexp-conv.exe +0 -0
  79. data/vendor/local/bin/trust.exe +0 -0
  80. data/vendor/local/include/glib-2.0/gio/gdatagrambased.h +144 -0
  81. data/vendor/local/include/glib-2.0/gio/gdbusconnection.h +9 -1
  82. data/vendor/local/include/glib-2.0/gio/gdtlsclientconnection.h +75 -0
  83. data/vendor/local/include/glib-2.0/gio/gdtlsconnection.h +191 -0
  84. data/vendor/local/include/glib-2.0/gio/gdtlsserverconnection.h +69 -0
  85. data/vendor/local/include/glib-2.0/gio/gfileinfo.h +14 -0
  86. data/vendor/local/include/glib-2.0/gio/gio-autocleanups.h +1 -0
  87. data/vendor/local/include/glib-2.0/gio/gio.h +4 -0
  88. data/vendor/local/include/glib-2.0/gio/gioenums.h +69 -13
  89. data/vendor/local/include/glib-2.0/gio/gioenumtypes.h +2 -0
  90. data/vendor/local/include/glib-2.0/gio/giotypes.h +77 -0
  91. data/vendor/local/include/glib-2.0/gio/gliststore.h +5 -0
  92. data/vendor/local/include/glib-2.0/gio/gnetworkmonitor.h +3 -0
  93. data/vendor/local/include/glib-2.0/gio/gsettings.h +1 -1
  94. data/vendor/local/include/glib-2.0/gio/gsettingsschema.h +3 -0
  95. data/vendor/local/include/glib-2.0/gio/gsimpleasyncresult.h +25 -25
  96. data/vendor/local/include/glib-2.0/gio/gsocket.h +7 -0
  97. data/vendor/local/include/glib-2.0/gio/gsocketconnectable.h +6 -0
  98. data/vendor/local/include/glib-2.0/gio/gsocketlistener.h +4 -1
  99. data/vendor/local/include/glib-2.0/gio/gtlsbackend.h +14 -0
  100. data/vendor/local/include/glib-2.0/gio/gtlsclientconnection.h +7 -0
  101. data/vendor/local/include/glib-2.0/glib/gasyncqueue.h +13 -0
  102. data/vendor/local/include/glib-2.0/glib/gbacktrace.h +2 -0
  103. data/vendor/local/include/glib-2.0/glib/glib-autocleanups.h +12 -4
  104. data/vendor/local/include/glib-2.0/glib/gmacros.h +46 -10
  105. data/vendor/local/include/glib-2.0/glib/gmain.h +3 -1
  106. data/vendor/local/include/glib-2.0/glib/gmem.h +7 -5
  107. data/vendor/local/include/glib-2.0/glib/gmessages.h +8 -8
  108. data/vendor/local/include/glib-2.0/glib/gnode.h +2 -2
  109. data/vendor/local/include/glib-2.0/glib/gpoll.h +2 -9
  110. data/vendor/local/include/glib-2.0/glib/gsequence.h +2 -0
  111. data/vendor/local/include/glib-2.0/glib/gstdio.h +1 -1
  112. data/vendor/local/include/glib-2.0/glib/gstrfuncs.h +1 -0
  113. data/vendor/local/include/glib-2.0/glib/gtestutils.h +15 -2
  114. data/vendor/local/include/glib-2.0/glib/gthreadpool.h +4 -0
  115. data/vendor/local/include/glib-2.0/glib/gtrashstack.h +10 -57
  116. data/vendor/local/include/glib-2.0/glib/gtypes.h +61 -6
  117. data/vendor/local/include/glib-2.0/glib/gunicode.h +15 -1
  118. data/vendor/local/include/glib-2.0/glib/gutils.h +36 -57
  119. data/vendor/local/include/glib-2.0/glib/gversionmacros.h +59 -10
  120. data/vendor/local/include/glib-2.0/gobject/gboxed.h +3 -3
  121. data/vendor/local/include/glib-2.0/gobject/gclosure.h +2 -1
  122. data/vendor/local/include/glib-2.0/gobject/glib-types.h +0 -7
  123. data/vendor/local/include/glib-2.0/gobject/gobject-autocleanups.h +0 -1
  124. data/vendor/local/include/glib-2.0/gobject/gobject.h +8 -4
  125. data/vendor/local/include/glib-2.0/gobject/gparam.h +5 -2
  126. data/vendor/local/include/glib-2.0/gobject/gsignal.h +3 -0
  127. data/vendor/local/include/glib-2.0/gobject/gtype.h +47 -26
  128. data/vendor/local/include/glib-2.0/gobject/gtypemodule.h +1 -0
  129. data/vendor/local/include/gmp.h +56 -24
  130. data/vendor/local/include/gnutls/gnutls.h +79 -39
  131. data/vendor/local/include/gnutls/pkcs11.h +6 -0
  132. data/vendor/local/include/gnutls/pkcs7.h +17 -4
  133. data/vendor/local/include/gnutls/x509.h +8 -0
  134. data/vendor/local/include/libintl.h +1 -1
  135. data/vendor/local/include/libtasn1.h +1 -1
  136. data/vendor/local/include/nettle/rsa.h +72 -0
  137. data/vendor/local/include/nettle/sha3.h +4 -0
  138. data/vendor/local/include/nettle/version.h +8 -1
  139. data/vendor/local/include/p11-kit-1/p11-kit/p11-kit.h +1 -0
  140. data/vendor/local/include/pcre.h +677 -0
  141. data/vendor/local/include/pcre_scanner.h +172 -0
  142. data/vendor/local/include/pcre_stringpiece.h +180 -0
  143. data/vendor/local/include/pcrecpp.h +710 -0
  144. data/vendor/local/include/pcrecpparg.h +174 -0
  145. data/vendor/local/include/pcreposix.h +146 -0
  146. data/vendor/local/lib/gio/modules/libgiognutls.a +0 -0
  147. data/vendor/local/lib/gio/modules/libgiognutls.dll +0 -0
  148. data/vendor/local/lib/gio/modules/libgiognutls.dll.a +0 -0
  149. data/vendor/local/lib/gio/modules/libgiognutls.la +3 -3
  150. data/vendor/local/lib/glib-2.0/include/glibconfig.h +4 -16
  151. data/vendor/local/lib/libasprintf.a +0 -0
  152. data/vendor/local/lib/libasprintf.dll.a +0 -0
  153. data/vendor/local/lib/libcharset.a +0 -0
  154. data/vendor/local/lib/libcharset.dll.a +0 -0
  155. data/vendor/local/lib/libffi.a +0 -0
  156. data/vendor/local/lib/libffi.dll.a +0 -0
  157. data/vendor/local/lib/libgio-2.0.dll.a +0 -0
  158. data/vendor/local/lib/libgio-2.0.la +5 -5
  159. data/vendor/local/lib/libglib-2.0.dll.a +0 -0
  160. data/vendor/local/lib/libglib-2.0.la +5 -5
  161. data/vendor/local/lib/libgmodule-2.0.dll.a +0 -0
  162. data/vendor/local/lib/libgmodule-2.0.la +5 -5
  163. data/vendor/local/lib/libgmp.dll.a +0 -0
  164. data/vendor/local/lib/libgmp.la +4 -4
  165. data/vendor/local/lib/libgnutls.dll.a +0 -0
  166. data/vendor/local/lib/libgnutls.la +3 -3
  167. data/vendor/local/lib/libgobject-2.0.dll.a +0 -0
  168. data/vendor/local/lib/libgobject-2.0.la +5 -5
  169. data/vendor/local/lib/libgthread-2.0.dll.a +0 -0
  170. data/vendor/local/lib/libgthread-2.0.la +5 -5
  171. data/vendor/local/lib/libhogweed.a +0 -0
  172. data/vendor/local/lib/libhogweed.dll.a +0 -0
  173. data/vendor/local/lib/libiconv.dll.a +0 -0
  174. data/vendor/local/lib/libidn.a +0 -0
  175. data/vendor/local/lib/libidn.dll.a +0 -0
  176. data/vendor/local/lib/libintl.a +0 -0
  177. data/vendor/local/lib/libintl.dll.a +0 -0
  178. data/vendor/local/lib/libintl.la +1 -1
  179. data/vendor/local/lib/libnettle.a +0 -0
  180. data/vendor/local/lib/libnettle.dll.a +0 -0
  181. data/vendor/local/lib/libp11-kit.dll.a +0 -0
  182. data/vendor/local/lib/libpcre.a +0 -0
  183. data/vendor/local/lib/libpcre.dll.a +0 -0
  184. data/vendor/local/lib/libpcre.la +41 -0
  185. data/vendor/local/lib/libpcrecpp.a +0 -0
  186. data/vendor/local/lib/libpcrecpp.dll.a +0 -0
  187. data/vendor/local/lib/libpcrecpp.la +41 -0
  188. data/vendor/local/lib/libpcreposix.a +0 -0
  189. data/vendor/local/lib/libpcreposix.dll.a +0 -0
  190. data/vendor/local/lib/libpcreposix.la +41 -0
  191. data/vendor/local/lib/libtasn1.a +0 -0
  192. data/vendor/local/lib/libtasn1.dll.a +0 -0
  193. data/vendor/local/lib/libtasn1.la +1 -1
  194. data/vendor/local/lib/p11-kit/p11-kit-remote.exe +0 -0
  195. data/vendor/local/lib/pkcs11/p11-kit-trust.dll +0 -0
  196. data/vendor/local/lib/pkcs11/p11-kit-trust.dll.a +0 -0
  197. data/vendor/local/lib/pkgconfig/gio-2.0.pc +1 -1
  198. data/vendor/local/lib/pkgconfig/gio-windows-2.0.pc +1 -1
  199. data/vendor/local/lib/pkgconfig/glib-2.0.pc +3 -3
  200. data/vendor/local/lib/pkgconfig/gmodule-2.0.pc +1 -1
  201. data/vendor/local/lib/pkgconfig/gmodule-export-2.0.pc +1 -1
  202. data/vendor/local/lib/pkgconfig/gmodule-no-export-2.0.pc +1 -1
  203. data/vendor/local/lib/pkgconfig/gnutls.pc +2 -2
  204. data/vendor/local/lib/pkgconfig/gobject-2.0.pc +1 -1
  205. data/vendor/local/lib/pkgconfig/gthread-2.0.pc +1 -1
  206. data/vendor/local/lib/pkgconfig/hogweed.pc +1 -1
  207. data/vendor/local/lib/pkgconfig/libpcre.pc +13 -0
  208. data/vendor/local/lib/pkgconfig/libpcrecpp.pc +12 -0
  209. data/vendor/local/lib/pkgconfig/libpcreposix.pc +13 -0
  210. data/vendor/local/lib/pkgconfig/libtasn1.pc +1 -1
  211. data/vendor/local/lib/pkgconfig/nettle.pc +1 -1
  212. data/vendor/local/lib/pkgconfig/p11-kit-1.pc +1 -1
  213. data/vendor/local/share/aclocal/glib-gettext.m4 +3 -2
  214. data/vendor/local/share/doc/pcre/AUTHORS +45 -0
  215. data/vendor/local/share/doc/pcre/COPYING +5 -0
  216. data/vendor/local/share/doc/pcre/ChangeLog +5918 -0
  217. data/vendor/local/share/doc/pcre/LICENCE +93 -0
  218. data/vendor/local/share/doc/pcre/NEWS +716 -0
  219. data/vendor/local/share/doc/pcre/README +1002 -0
  220. data/vendor/local/share/doc/pcre/html/NON-AUTOTOOLS-BUILD.txt +772 -0
  221. data/vendor/local/share/doc/pcre/html/README.txt +1002 -0
  222. data/vendor/local/share/doc/pcre/html/index.html +185 -0
  223. data/vendor/local/share/doc/pcre/html/pcre-config.html +109 -0
  224. data/vendor/local/share/doc/pcre/html/pcre.html +224 -0
  225. data/vendor/local/share/doc/pcre/html/pcre16.html +384 -0
  226. data/vendor/local/share/doc/pcre/html/pcre32.html +382 -0
  227. data/vendor/local/share/doc/pcre/html/pcre_assign_jit_stack.html +76 -0
  228. data/vendor/local/share/doc/pcre/html/pcre_compile.html +111 -0
  229. data/vendor/local/share/doc/pcre/html/pcre_compile2.html +115 -0
  230. data/vendor/local/share/doc/pcre/html/pcre_config.html +94 -0
  231. data/vendor/local/share/doc/pcre/html/pcre_copy_named_substring.html +65 -0
  232. data/vendor/local/share/doc/pcre/html/pcre_copy_substring.html +61 -0
  233. data/vendor/local/share/doc/pcre/html/pcre_dfa_exec.html +129 -0
  234. data/vendor/local/share/doc/pcre/html/pcre_exec.html +111 -0
  235. data/vendor/local/share/doc/pcre/html/pcre_free_study.html +46 -0
  236. data/vendor/local/share/doc/pcre/html/pcre_free_substring.html +46 -0
  237. data/vendor/local/share/doc/pcre/html/pcre_free_substring_list.html +46 -0
  238. data/vendor/local/share/doc/pcre/html/pcre_fullinfo.html +118 -0
  239. data/vendor/local/share/doc/pcre/html/pcre_get_named_substring.html +68 -0
  240. data/vendor/local/share/doc/pcre/html/pcre_get_stringnumber.html +57 -0
  241. data/vendor/local/share/doc/pcre/html/pcre_get_stringtable_entries.html +60 -0
  242. data/vendor/local/share/doc/pcre/html/pcre_get_substring.html +64 -0
  243. data/vendor/local/share/doc/pcre/html/pcre_get_substring_list.html +61 -0
  244. data/vendor/local/share/doc/pcre/html/pcre_jit_exec.html +108 -0
  245. data/vendor/local/share/doc/pcre/html/pcre_jit_stack_alloc.html +55 -0
  246. data/vendor/local/share/doc/pcre/html/pcre_jit_stack_free.html +48 -0
  247. data/vendor/local/share/doc/pcre/html/pcre_maketables.html +48 -0
  248. data/vendor/local/share/doc/pcre/html/pcre_pattern_to_host_byte_order.html +58 -0
  249. data/vendor/local/share/doc/pcre/html/pcre_refcount.html +51 -0
  250. data/vendor/local/share/doc/pcre/html/pcre_study.html +68 -0
  251. data/vendor/local/share/doc/pcre/html/pcre_utf16_to_host_byte_order.html +57 -0
  252. data/vendor/local/share/doc/pcre/html/pcre_utf32_to_host_byte_order.html +57 -0
  253. data/vendor/local/share/doc/pcre/html/pcre_version.html +46 -0
  254. data/vendor/local/share/doc/pcre/html/pcreapi.html +2922 -0
  255. data/vendor/local/share/doc/pcre/html/pcrebuild.html +534 -0
  256. data/vendor/local/share/doc/pcre/html/pcrecallout.html +286 -0
  257. data/vendor/local/share/doc/pcre/html/pcrecompat.html +235 -0
  258. data/vendor/local/share/doc/pcre/html/pcrecpp.html +368 -0
  259. data/vendor/local/share/doc/pcre/html/pcredemo.html +426 -0
  260. data/vendor/local/share/doc/pcre/html/pcregrep.html +759 -0
  261. data/vendor/local/share/doc/pcre/html/pcrejit.html +452 -0
  262. data/vendor/local/share/doc/pcre/html/pcrelimits.html +90 -0
  263. data/vendor/local/share/doc/pcre/html/pcrematching.html +242 -0
  264. data/vendor/local/share/doc/pcre/html/pcrepartial.html +509 -0
  265. data/vendor/local/share/doc/pcre/html/pcrepattern.html +3273 -0
  266. data/vendor/local/share/doc/pcre/html/pcreperform.html +195 -0
  267. data/vendor/local/share/doc/pcre/html/pcreposix.html +290 -0
  268. data/vendor/local/share/doc/pcre/html/pcreprecompile.html +163 -0
  269. data/vendor/local/share/doc/pcre/html/pcresample.html +110 -0
  270. data/vendor/local/share/doc/pcre/html/pcrestack.html +225 -0
  271. data/vendor/local/share/doc/pcre/html/pcresyntax.html +561 -0
  272. data/vendor/local/share/doc/pcre/html/pcretest.html +1158 -0
  273. data/vendor/local/share/doc/pcre/html/pcreunicode.html +262 -0
  274. data/vendor/local/share/doc/pcre/pcre-config.txt +86 -0
  275. data/vendor/local/share/doc/pcre/pcre.txt +10455 -0
  276. data/vendor/local/share/doc/pcre/pcregrep.txt +741 -0
  277. data/vendor/local/share/doc/pcre/pcretest.txt +1087 -0
  278. data/vendor/local/share/gdb/auto-load/{libglib-2.0.so.0.4400.1-gdb.py → home/vagrant/ruby-gnome2.win32/glib2/vendor/local/lib/libglib-2.0.so.0.4800.0-gdb.py} +0 -0
  279. data/vendor/local/share/gdb/auto-load/{libgobject-2.0.so.0.4400.1-gdb.py → home/vagrant/ruby-gnome2.win32/glib2/vendor/local/lib/libgobject-2.0.so.0.4800.0-gdb.py} +0 -0
  280. data/vendor/local/share/gettext/ABOUT-NLS +382 -413
  281. data/vendor/local/share/gettext/its/gschema.its +25 -0
  282. data/vendor/local/share/gettext/its/gschema.loc +10 -0
  283. data/vendor/local/share/glib-2.0/codegen/__init__.pyc +0 -0
  284. data/vendor/local/share/glib-2.0/codegen/__init__.pyo +0 -0
  285. data/vendor/local/share/glib-2.0/codegen/codegen.py +22 -0
  286. data/vendor/local/share/glib-2.0/codegen/codegen.pyc +0 -0
  287. data/vendor/local/share/glib-2.0/codegen/codegen.pyo +0 -0
  288. data/vendor/local/share/glib-2.0/codegen/codegen_docbook.pyc +0 -0
  289. data/vendor/local/share/glib-2.0/codegen/codegen_docbook.pyo +0 -0
  290. data/vendor/local/share/glib-2.0/codegen/codegen_main.pyc +0 -0
  291. data/vendor/local/share/glib-2.0/codegen/codegen_main.pyo +0 -0
  292. data/vendor/local/share/glib-2.0/codegen/config.py +1 -1
  293. data/vendor/local/share/glib-2.0/codegen/config.pyc +0 -0
  294. data/vendor/local/share/glib-2.0/codegen/config.pyo +0 -0
  295. data/vendor/local/share/glib-2.0/codegen/dbustypes.pyc +0 -0
  296. data/vendor/local/share/glib-2.0/codegen/dbustypes.pyo +0 -0
  297. data/vendor/local/share/glib-2.0/codegen/parser.pyc +0 -0
  298. data/vendor/local/share/glib-2.0/codegen/parser.pyo +0 -0
  299. data/vendor/local/share/glib-2.0/codegen/utils.pyc +0 -0
  300. data/vendor/local/share/glib-2.0/codegen/utils.pyo +0 -0
  301. data/vendor/local/share/glib-2.0/gdb/glib.py +4 -0
  302. data/vendor/local/share/glib-2.0/schemas/gschemas.compiled +0 -0
  303. data/vendor/local/share/gtk-doc/html/gio/GAction.html +58 -64
  304. data/vendor/local/share/gtk-doc/html/gio/GActionGroup.html +75 -80
  305. data/vendor/local/share/gtk-doc/html/gio/GActionMap.html +50 -51
  306. data/vendor/local/share/gtk-doc/html/gio/GAppInfo.html +72 -97
  307. data/vendor/local/share/gtk-doc/html/gio/GAppInfoMonitor.html +7 -8
  308. data/vendor/local/share/gtk-doc/html/gio/GApplication.html +174 -160
  309. data/vendor/local/share/gtk-doc/html/gio/GApplicationCommandLine.html +127 -132
  310. data/vendor/local/share/gtk-doc/html/gio/GAsyncInitable.html +90 -92
  311. data/vendor/local/share/gtk-doc/html/gio/GAsyncResult.html +43 -46
  312. data/vendor/local/share/gtk-doc/html/gio/GBufferedInputStream.html +17 -26
  313. data/vendor/local/share/gtk-doc/html/gio/GBufferedOutputStream.html +12 -17
  314. data/vendor/local/share/gtk-doc/html/gio/GBytesIcon.html +10 -11
  315. data/vendor/local/share/gtk-doc/html/gio/GCancellable.html +45 -52
  316. data/vendor/local/share/gtk-doc/html/gio/GCharsetConverter.html +14 -18
  317. data/vendor/local/share/gtk-doc/html/gio/GConverter.html +20 -21
  318. data/vendor/local/share/gtk-doc/html/gio/GCredentials.html +41 -48
  319. data/vendor/local/share/gtk-doc/html/gio/GDBusActionGroup.html +9 -10
  320. data/vendor/local/share/gtk-doc/html/gio/GDBusAuthObserver.html +34 -40
  321. data/vendor/local/share/gtk-doc/html/gio/GDBusConnection.html +337 -258
  322. data/vendor/local/share/gtk-doc/html/gio/GDBusInterface.html +23 -22
  323. data/vendor/local/share/gtk-doc/html/gio/GDBusInterfaceSkeleton.html +44 -50
  324. data/vendor/local/share/gtk-doc/html/gio/GDBusMenuModel.html +9 -10
  325. data/vendor/local/share/gtk-doc/html/gio/GDBusMessage.html +143 -158
  326. data/vendor/local/share/gtk-doc/html/gio/GDBusMethodInvocation.html +59 -54
  327. data/vendor/local/share/gtk-doc/html/gio/GDBusObject.html +19 -22
  328. data/vendor/local/share/gtk-doc/html/gio/GDBusObjectManager.html +25 -27
  329. data/vendor/local/share/gtk-doc/html/gio/GDBusObjectManagerClient.html +48 -52
  330. data/vendor/local/share/gtk-doc/html/gio/GDBusObjectManagerServer.html +34 -31
  331. data/vendor/local/share/gtk-doc/html/gio/GDBusObjectProxy.html +15 -17
  332. data/vendor/local/share/gtk-doc/html/gio/GDBusObjectSkeleton.html +25 -28
  333. data/vendor/local/share/gtk-doc/html/gio/GDBusProxy.html +105 -122
  334. data/vendor/local/share/gtk-doc/html/gio/GDBusServer.html +32 -39
  335. data/vendor/local/share/gtk-doc/html/gio/GDataInputStream.html +40 -51
  336. data/vendor/local/share/gtk-doc/html/gio/GDataOutputStream.html +17 -28
  337. data/vendor/local/share/gtk-doc/html/gio/GDatagramBased.html +766 -0
  338. data/vendor/local/share/gtk-doc/html/gio/GDrive.html +56 -75
  339. data/vendor/local/share/gtk-doc/html/gio/GDtlsClientConnection.html +468 -0
  340. data/vendor/local/share/gtk-doc/html/gio/GDtlsConnection.html +1521 -0
  341. data/vendor/local/share/gtk-doc/html/gio/GDtlsServerConnection.html +208 -0
  342. data/vendor/local/share/gtk-doc/html/gio/GEmblem.html +16 -19
  343. data/vendor/local/share/gtk-doc/html/gio/GEmblemedIcon.html +16 -17
  344. data/vendor/local/share/gtk-doc/html/gio/GFile.html +204 -240
  345. data/vendor/local/share/gtk-doc/html/gio/GFileDescriptorBased.html +9 -11
  346. data/vendor/local/share/gtk-doc/html/gio/GFileEnumerator.html +36 -41
  347. data/vendor/local/share/gtk-doc/html/gio/GFileIOStream.html +13 -15
  348. data/vendor/local/share/gtk-doc/html/gio/GFileIcon.html +8 -9
  349. data/vendor/local/share/gtk-doc/html/gio/GFileInfo.html +128 -145
  350. data/vendor/local/share/gtk-doc/html/gio/GFileInputStream.html +8 -9
  351. data/vendor/local/share/gtk-doc/html/gio/GFileMonitor.html +75 -36
  352. data/vendor/local/share/gtk-doc/html/gio/GFileOutputStream.html +9 -11
  353. data/vendor/local/share/gtk-doc/html/gio/GFilenameCompleter.html +10 -13
  354. data/vendor/local/share/gtk-doc/html/gio/GFilterInputStream.html +9 -11
  355. data/vendor/local/share/gtk-doc/html/gio/GFilterOutputStream.html +9 -11
  356. data/vendor/local/share/gtk-doc/html/gio/GIOModule.html +41 -43
  357. data/vendor/local/share/gtk-doc/html/gio/GIOStream.html +56 -44
  358. data/vendor/local/share/gtk-doc/html/gio/GIcon.html +20 -23
  359. data/vendor/local/share/gtk-doc/html/gio/GInetAddress.html +103 -118
  360. data/vendor/local/share/gtk-doc/html/gio/GInetAddressMask.html +39 -47
  361. data/vendor/local/share/gtk-doc/html/gio/GInetSocketAddress.html +31 -37
  362. data/vendor/local/share/gtk-doc/html/gio/GInitable.html +17 -19
  363. data/vendor/local/share/gtk-doc/html/gio/GInputStream.html +32 -44
  364. data/vendor/local/share/gtk-doc/html/gio/GListModel.html +28 -29
  365. data/vendor/local/share/gtk-doc/html/gio/GListStore.html +80 -35
  366. data/vendor/local/share/gtk-doc/html/gio/GLoadableIcon.html +10 -11
  367. data/vendor/local/share/gtk-doc/html/gio/GMemoryInputStream.html +11 -15
  368. data/vendor/local/share/gtk-doc/html/gio/GMemoryOutputStream.html +38 -38
  369. data/vendor/local/share/gtk-doc/html/gio/GMenu.html +138 -145
  370. data/vendor/local/share/gtk-doc/html/gio/GMenuModel.html +84 -94
  371. data/vendor/local/share/gtk-doc/html/gio/GMount.html +54 -66
  372. data/vendor/local/share/gtk-doc/html/gio/GMountOperation.html +34 -42
  373. data/vendor/local/share/gtk-doc/html/gio/GNetworkAddress.html +26 -28
  374. data/vendor/local/share/gtk-doc/html/gio/GNetworkMonitor.html +97 -39
  375. data/vendor/local/share/gtk-doc/html/gio/GNetworkService.html +18 -23
  376. data/vendor/local/share/gtk-doc/html/gio/GNotification.html +49 -47
  377. data/vendor/local/share/gtk-doc/html/gio/GOutputStream.html +39 -56
  378. data/vendor/local/share/gtk-doc/html/gio/GPermission.html +26 -34
  379. data/vendor/local/share/gtk-doc/html/gio/GPollableInputStream.html +16 -20
  380. data/vendor/local/share/gtk-doc/html/gio/GPollableOutputStream.html +16 -20
  381. data/vendor/local/share/gtk-doc/html/gio/GPropertyAction.html +33 -20
  382. data/vendor/local/share/gtk-doc/html/gio/GProxy.html +30 -32
  383. data/vendor/local/share/gtk-doc/html/gio/GProxyAddress.html +42 -51
  384. data/vendor/local/share/gtk-doc/html/gio/GProxyResolver.html +17 -19
  385. data/vendor/local/share/gtk-doc/html/gio/GRemoteActionGroup.html +15 -16
  386. data/vendor/local/share/gtk-doc/html/gio/GResolver.html +46 -47
  387. data/vendor/local/share/gtk-doc/html/gio/GResource.html +79 -74
  388. data/vendor/local/share/gtk-doc/html/gio/GSeekable.html +12 -18
  389. data/vendor/local/share/gtk-doc/html/gio/GSettings.html +325 -200
  390. data/vendor/local/share/gtk-doc/html/gio/GSettingsBackend.html +28 -29
  391. data/vendor/local/share/gtk-doc/html/gio/GSimpleAction.html +46 -49
  392. data/vendor/local/share/gtk-doc/html/gio/GSimpleActionGroup.html +21 -23
  393. data/vendor/local/share/gtk-doc/html/gio/GSimpleAsyncResult.html +258 -162
  394. data/vendor/local/share/gtk-doc/html/gio/GSimpleIOStream.html +11 -13
  395. data/vendor/local/share/gtk-doc/html/gio/GSimplePermission.html +7 -9
  396. data/vendor/local/share/gtk-doc/html/gio/GSimpleProxyResolver.html +16 -18
  397. data/vendor/local/share/gtk-doc/html/gio/GSocket.html +470 -281
  398. data/vendor/local/share/gtk-doc/html/gio/GSocketAddress.html +27 -32
  399. data/vendor/local/share/gtk-doc/html/gio/GSocketClient.html +76 -85
  400. data/vendor/local/share/gtk-doc/html/gio/GSocketConnectable.html +118 -72
  401. data/vendor/local/share/gtk-doc/html/gio/GSocketConnection.html +28 -33
  402. data/vendor/local/share/gtk-doc/html/gio/GSocketControlMessage.html +26 -30
  403. data/vendor/local/share/gtk-doc/html/gio/GSocketListener.html +180 -62
  404. data/vendor/local/share/gtk-doc/html/gio/GSocketService.html +51 -28
  405. data/vendor/local/share/gtk-doc/html/gio/GSrvTarget.html +25 -31
  406. data/vendor/local/share/gtk-doc/html/gio/GSubprocess.html +63 -75
  407. data/vendor/local/share/gtk-doc/html/gio/GSubprocessLauncher.html +49 -54
  408. data/vendor/local/share/gtk-doc/html/gio/GTask.html +406 -404
  409. data/vendor/local/share/gtk-doc/html/gio/GTcpConnection.html +11 -13
  410. data/vendor/local/share/gtk-doc/html/gio/GTcpWrapperConnection.html +9 -11
  411. data/vendor/local/share/gtk-doc/html/gio/GTestDBus.html +36 -38
  412. data/vendor/local/share/gtk-doc/html/gio/GThemedIcon.html +30 -31
  413. data/vendor/local/share/gtk-doc/html/gio/GThreadedSocketService.html +11 -14
  414. data/vendor/local/share/gtk-doc/html/gio/GTlsBackend.html +172 -46
  415. data/vendor/local/share/gtk-doc/html/gio/GTlsCertificate.html +26 -32
  416. data/vendor/local/share/gtk-doc/html/gio/GTlsClientConnection.html +96 -37
  417. data/vendor/local/share/gtk-doc/html/gio/GTlsConnection.html +64 -66
  418. data/vendor/local/share/gtk-doc/html/gio/GTlsDatabase.html +256 -63
  419. data/vendor/local/share/gtk-doc/html/gio/GTlsFileDatabase.html +15 -16
  420. data/vendor/local/share/gtk-doc/html/gio/GTlsInteraction.html +150 -49
  421. data/vendor/local/share/gtk-doc/html/gio/GTlsPassword.html +46 -51
  422. data/vendor/local/share/gtk-doc/html/gio/GTlsServerConnection.html +21 -18
  423. data/vendor/local/share/gtk-doc/html/gio/GUnixConnection.html +21 -26
  424. data/vendor/local/share/gtk-doc/html/gio/GUnixCredentialsMessage.html +21 -25
  425. data/vendor/local/share/gtk-doc/html/gio/GUnixFDList.html +31 -37
  426. data/vendor/local/share/gtk-doc/html/gio/GUnixFDMessage.html +24 -28
  427. data/vendor/local/share/gtk-doc/html/gio/GUnixInputStream.html +15 -19
  428. data/vendor/local/share/gtk-doc/html/gio/GUnixOutputStream.html +15 -19
  429. data/vendor/local/share/gtk-doc/html/gio/GUnixSocketAddress.html +43 -47
  430. data/vendor/local/share/gtk-doc/html/gio/GVfs.html +22 -24
  431. data/vendor/local/share/gtk-doc/html/gio/GVolume.html +43 -54
  432. data/vendor/local/share/gtk-doc/html/gio/GVolumeMonitor.html +26 -27
  433. data/vendor/local/share/gtk-doc/html/gio/GZlibCompressor.html +15 -17
  434. data/vendor/local/share/gtk-doc/html/gio/GZlibDecompressor.html +11 -13
  435. data/vendor/local/share/gtk-doc/html/gio/annotation-glossary.html +21 -6
  436. data/vendor/local/share/gtk-doc/html/gio/api-index-2-18.html +3 -4
  437. data/vendor/local/share/gtk-doc/html/gio/api-index-2-20.html +3 -4
  438. data/vendor/local/share/gtk-doc/html/gio/api-index-2-22.html +3 -4
  439. data/vendor/local/share/gtk-doc/html/gio/api-index-2-24.html +3 -4
  440. data/vendor/local/share/gtk-doc/html/gio/api-index-2-26.html +3 -4
  441. data/vendor/local/share/gtk-doc/html/gio/api-index-2-28.html +3 -4
  442. data/vendor/local/share/gtk-doc/html/gio/api-index-2-30.html +11 -4
  443. data/vendor/local/share/gtk-doc/html/gio/api-index-2-32.html +3 -4
  444. data/vendor/local/share/gtk-doc/html/gio/api-index-2-34.html +3 -4
  445. data/vendor/local/share/gtk-doc/html/gio/api-index-2-36.html +3 -4
  446. data/vendor/local/share/gtk-doc/html/gio/api-index-2-38.html +3 -4
  447. data/vendor/local/share/gtk-doc/html/gio/api-index-2-40.html +3 -4
  448. data/vendor/local/share/gtk-doc/html/gio/api-index-2-42.html +11 -5
  449. data/vendor/local/share/gtk-doc/html/gio/api-index-2-44.html +5 -6
  450. data/vendor/local/share/gtk-doc/html/gio/api-index-2-46.html +211 -0
  451. data/vendor/local/share/gtk-doc/html/gio/api-index-2-48.html +283 -0
  452. data/vendor/local/share/gtk-doc/html/gio/api-index-deprecated.html +107 -4
  453. data/vendor/local/share/gtk-doc/html/gio/api-index-full.html +459 -8
  454. data/vendor/local/share/gtk-doc/html/gio/application.html +5 -6
  455. data/vendor/local/share/gtk-doc/html/gio/async.html +3 -4
  456. data/vendor/local/share/gtk-doc/html/gio/ch01.html +3 -4
  457. data/vendor/local/share/gtk-doc/html/gio/ch02.html +3 -4
  458. data/vendor/local/share/gtk-doc/html/gio/ch03.html +3 -4
  459. data/vendor/local/share/gtk-doc/html/gio/ch32.html +29 -172
  460. data/vendor/local/share/gtk-doc/html/gio/ch33.html +187 -27
  461. data/vendor/local/share/gtk-doc/html/gio/ch33s02.html +15 -34
  462. data/vendor/local/share/gtk-doc/html/gio/ch33s03.html +16 -137
  463. data/vendor/local/share/gtk-doc/html/gio/ch34.html +26 -87
  464. data/vendor/local/share/gtk-doc/html/gio/ch34s02.html +37 -121
  465. data/vendor/local/share/gtk-doc/html/gio/ch34s03.html +132 -176
  466. data/vendor/local/share/gtk-doc/html/gio/ch34s04.html +19 -71
  467. data/vendor/local/share/gtk-doc/html/gio/ch34s05.html +24 -908
  468. data/vendor/local/share/gtk-doc/html/gio/{ch33s06.html → ch34s06.html} +9 -10
  469. data/vendor/local/share/gtk-doc/html/gio/{ch33s07.html → ch34s07.html} +9 -10
  470. data/vendor/local/share/gtk-doc/html/gio/ch35.html +94 -0
  471. data/vendor/local/share/gtk-doc/html/gio/ch35s02.html +141 -0
  472. data/vendor/local/share/gtk-doc/html/gio/ch35s03.html +201 -0
  473. data/vendor/local/share/gtk-doc/html/gio/ch35s04.html +96 -0
  474. data/vendor/local/share/gtk-doc/html/gio/conversion.html +3 -4
  475. data/vendor/local/share/gtk-doc/html/gio/data-models.html +4 -5
  476. data/vendor/local/share/gtk-doc/html/gio/extending-gio.html +3 -4
  477. data/vendor/local/share/gtk-doc/html/gio/extending.html +3 -4
  478. data/vendor/local/share/gtk-doc/html/gio/failable_initialization.html +3 -4
  479. data/vendor/local/share/gtk-doc/html/gio/file_mon.html +3 -4
  480. data/vendor/local/share/gtk-doc/html/gio/file_ops.html +3 -4
  481. data/vendor/local/share/gtk-doc/html/gio/gapplication-tool.html +11 -12
  482. data/vendor/local/share/gtk-doc/html/gio/gdbus-codegen.html +199 -200
  483. data/vendor/local/share/gtk-doc/html/gio/gdbus-convenience.html +3 -4
  484. data/vendor/local/share/gtk-doc/html/gio/gdbus-example-gdbus-codegen.html +89 -0
  485. data/vendor/local/share/gtk-doc/html/gio/gdbus-lowlevel.html +3 -4
  486. data/vendor/local/share/gtk-doc/html/gio/gdbus.html +9 -10
  487. data/vendor/local/share/gtk-doc/html/gio/gio-D-Bus-Addresses.html +24 -28
  488. data/vendor/local/share/gtk-doc/html/gio/gio-D-Bus-Introspection-Data.html +77 -87
  489. data/vendor/local/share/gtk-doc/html/gio/gio-D-Bus-Utilities.html +19 -27
  490. data/vendor/local/share/gtk-doc/html/gio/gio-Desktop-file-based-GAppInfo.html +43 -57
  491. data/vendor/local/share/gtk-doc/html/gio/gio-Extension-Points.html +47 -52
  492. data/vendor/local/share/gtk-doc/html/gio/gio-GActionGroup-exporter.html +11 -13
  493. data/vendor/local/share/gtk-doc/html/gio/gio-GContentType.html +20 -27
  494. data/vendor/local/share/gtk-doc/html/gio/gio-GConverterInputstream.html +9 -11
  495. data/vendor/local/share/gtk-doc/html/gio/gio-GConverterOutputstream.html +9 -11
  496. data/vendor/local/share/gtk-doc/html/gio/gio-GDBusError.html +59 -67
  497. data/vendor/local/share/gtk-doc/html/gio/gio-GFileAttribute.html +16 -21
  498. data/vendor/local/share/gtk-doc/html/gio/gio-GIOError.html +21 -17
  499. data/vendor/local/share/gtk-doc/html/gio/gio-GIOScheduler.html +9 -12
  500. data/vendor/local/share/gtk-doc/html/gio/gio-GMenuModel-exporter.html +11 -13
  501. data/vendor/local/share/gtk-doc/html/gio/gio-GSettingsSchema-GSettingsSchemaSource.html +147 -114
  502. data/vendor/local/share/gtk-doc/html/gio/gio-GWin32InputStream.html +12 -16
  503. data/vendor/local/share/gtk-doc/html/gio/gio-GWin32OutputStream.html +13 -17
  504. data/vendor/local/share/gtk-doc/html/gio/gio-GWin32RegistryKey.html +2066 -0
  505. data/vendor/local/share/gtk-doc/html/gio/gio-Owning-Bus-Names.html +29 -32
  506. data/vendor/local/share/gtk-doc/html/gio/gio-TLS-Overview.html +16 -13
  507. data/vendor/local/share/gtk-doc/html/gio/gio-Unix-Mounts.html +54 -75
  508. data/vendor/local/share/gtk-doc/html/gio/gio-Watching-Bus-Names.html +27 -30
  509. data/vendor/local/share/gtk-doc/html/gio/gio-gnetworking.h.html +5 -6
  510. data/vendor/local/share/gtk-doc/html/gio/gio-gpollableutils.html +16 -21
  511. data/vendor/local/share/gtk-doc/html/gio/gio-hierarchy.html +11 -8
  512. data/vendor/local/share/gtk-doc/html/gio/gio-querymodules.html +4 -5
  513. data/vendor/local/share/gtk-doc/html/gio/gio.devhelp2 +194 -140
  514. data/vendor/local/share/gtk-doc/html/gio/glib-compile-resources.html +6 -7
  515. data/vendor/local/share/gtk-doc/html/gio/glib-compile-schemas.html +12 -6
  516. data/vendor/local/share/gtk-doc/html/gio/gresource-tool.html +5 -6
  517. data/vendor/local/share/gtk-doc/html/gio/gsettings-tool.html +5 -6
  518. data/vendor/local/share/gtk-doc/html/gio/highlevel-socket.html +3 -4
  519. data/vendor/local/share/gtk-doc/html/gio/icons.html +3 -4
  520. data/vendor/local/share/gtk-doc/html/gio/index.html +41 -45
  521. data/vendor/local/share/gtk-doc/html/gio/index.sgml +204 -137
  522. data/vendor/local/share/gtk-doc/html/gio/migrating.html +22 -44
  523. data/vendor/local/share/gtk-doc/html/gio/networking.html +6 -4
  524. data/vendor/local/share/gtk-doc/html/gio/permissions.html +3 -4
  525. data/vendor/local/share/gtk-doc/html/gio/pt01.html +3 -4
  526. data/vendor/local/share/gtk-doc/html/gio/pt02.html +20 -5
  527. data/vendor/local/share/gtk-doc/html/gio/registry.html +32 -0
  528. data/vendor/local/share/gtk-doc/html/gio/resolver.html +3 -4
  529. data/vendor/local/share/gtk-doc/html/gio/resources.html +3 -4
  530. data/vendor/local/share/gtk-doc/html/gio/running-gio-apps.html +3 -4
  531. data/vendor/local/share/gtk-doc/html/gio/settings.html +3 -4
  532. data/vendor/local/share/gtk-doc/html/gio/streaming.html +3 -4
  533. data/vendor/local/share/gtk-doc/html/gio/style.css +9 -6
  534. data/vendor/local/share/gtk-doc/html/gio/subprocesses.html +3 -4
  535. data/vendor/local/share/gtk-doc/html/gio/testing.html +3 -4
  536. data/vendor/local/share/gtk-doc/html/gio/tls.html +12 -4
  537. data/vendor/local/share/gtk-doc/html/gio/tools.html +3 -4
  538. data/vendor/local/share/gtk-doc/html/gio/types.html +3 -4
  539. data/vendor/local/share/gtk-doc/html/gio/utils.html +3 -4
  540. data/vendor/local/share/gtk-doc/html/gio/volume_mon.html +3 -4
  541. data/vendor/local/share/gtk-doc/html/glib/annotation-glossary.html +16 -6
  542. data/vendor/local/share/gtk-doc/html/glib/api-index-2-10.html +3 -4
  543. data/vendor/local/share/gtk-doc/html/glib/api-index-2-12.html +3 -4
  544. data/vendor/local/share/gtk-doc/html/glib/api-index-2-14.html +3 -4
  545. data/vendor/local/share/gtk-doc/html/glib/api-index-2-16.html +3 -4
  546. data/vendor/local/share/gtk-doc/html/glib/api-index-2-18.html +3 -4
  547. data/vendor/local/share/gtk-doc/html/glib/api-index-2-2.html +3 -4
  548. data/vendor/local/share/gtk-doc/html/glib/api-index-2-20.html +3 -4
  549. data/vendor/local/share/gtk-doc/html/glib/api-index-2-22.html +3 -4
  550. data/vendor/local/share/gtk-doc/html/glib/api-index-2-24.html +3 -4
  551. data/vendor/local/share/gtk-doc/html/glib/api-index-2-26.html +3 -4
  552. data/vendor/local/share/gtk-doc/html/glib/api-index-2-28.html +3 -4
  553. data/vendor/local/share/gtk-doc/html/glib/api-index-2-30.html +3 -4
  554. data/vendor/local/share/gtk-doc/html/glib/api-index-2-32.html +3 -4
  555. data/vendor/local/share/gtk-doc/html/glib/api-index-2-34.html +3 -4
  556. data/vendor/local/share/gtk-doc/html/glib/api-index-2-36.html +3 -4
  557. data/vendor/local/share/gtk-doc/html/glib/api-index-2-38.html +3 -4
  558. data/vendor/local/share/gtk-doc/html/glib/api-index-2-4.html +3 -4
  559. data/vendor/local/share/gtk-doc/html/glib/api-index-2-40.html +7 -4
  560. data/vendor/local/share/gtk-doc/html/glib/api-index-2-42.html +12 -6
  561. data/vendor/local/share/gtk-doc/html/glib/api-index-2-44.html +5 -6
  562. data/vendor/local/share/gtk-doc/html/glib/api-index-2-46.html +68 -0
  563. data/vendor/local/share/gtk-doc/html/glib/api-index-2-48.html +68 -0
  564. data/vendor/local/share/gtk-doc/html/glib/api-index-2-6.html +3 -4
  565. data/vendor/local/share/gtk-doc/html/glib/api-index-2-8.html +3 -4
  566. data/vendor/local/share/gtk-doc/html/glib/api-index-deprecated.html +46 -8
  567. data/vendor/local/share/gtk-doc/html/glib/api-index-full.html +80 -9
  568. data/vendor/local/share/gtk-doc/html/glib/deprecated.html +3 -4
  569. data/vendor/local/share/gtk-doc/html/glib/glib-Arrays.html +68 -85
  570. data/vendor/local/share/gtk-doc/html/glib/glib-Asynchronous-Queues.html +254 -84
  571. data/vendor/local/share/gtk-doc/html/glib/glib-Atomic-Operations.html +130 -144
  572. data/vendor/local/share/gtk-doc/html/glib/glib-Automatic-String-Completion.html +19 -23
  573. data/vendor/local/share/gtk-doc/html/glib/glib-Balanced-Binary-Trees.html +33 -46
  574. data/vendor/local/share/gtk-doc/html/glib/glib-Base64-Encoding.html +22 -26
  575. data/vendor/local/share/gtk-doc/html/glib/glib-Basic-Types.html +89 -82
  576. data/vendor/local/share/gtk-doc/html/glib/glib-Bookmark-file-parser.html +87 -112
  577. data/vendor/local/share/gtk-doc/html/glib/glib-Bounds-checked-integer-arithmetic.html +384 -0
  578. data/vendor/local/share/gtk-doc/html/glib/glib-Byte-Arrays.html +100 -114
  579. data/vendor/local/share/gtk-doc/html/glib/glib-Byte-Order-Macros.html +83 -143
  580. data/vendor/local/share/gtk-doc/html/glib/glib-Caches.html +14 -19
  581. data/vendor/local/share/gtk-doc/html/glib/glib-Character-Set-Conversion.html +49 -64
  582. data/vendor/local/share/gtk-doc/html/glib/glib-Commandline-option-parser.html +141 -156
  583. data/vendor/local/share/gtk-doc/html/glib/glib-Data-Checksums.html +32 -38
  584. data/vendor/local/share/gtk-doc/html/glib/glib-Data-HMACs.html +24 -31
  585. data/vendor/local/share/gtk-doc/html/glib/glib-Datasets.html +28 -32
  586. data/vendor/local/share/gtk-doc/html/glib/glib-Date-and-Time-Functions.html +108 -141
  587. data/vendor/local/share/gtk-doc/html/glib/glib-Deprecated-Thread-APIs.html +98 -113
  588. data/vendor/local/share/gtk-doc/html/glib/glib-Double-ended-Queues.html +89 -112
  589. data/vendor/local/share/gtk-doc/html/glib/glib-Doubly-Linked-Lists.html +93 -125
  590. data/vendor/local/share/gtk-doc/html/glib/glib-Dynamic-Loading-of-Modules.html +50 -58
  591. data/vendor/local/share/gtk-doc/html/glib/glib-Error-Reporting.html +189 -171
  592. data/vendor/local/share/gtk-doc/html/glib/glib-File-Utilities.html +99 -134
  593. data/vendor/local/share/gtk-doc/html/glib/glib-GDateTime.html +172 -217
  594. data/vendor/local/share/gtk-doc/html/glib/glib-GTimeZone.html +32 -42
  595. data/vendor/local/share/gtk-doc/html/glib/glib-GVariant.html +430 -451
  596. data/vendor/local/share/gtk-doc/html/glib/glib-GVariantType.html +53 -66
  597. data/vendor/local/share/gtk-doc/html/glib/glib-Glob-style-pattern-matching.html +12 -18
  598. data/vendor/local/share/gtk-doc/html/glib/glib-Hash-Tables.html +167 -192
  599. data/vendor/local/share/gtk-doc/html/glib/glib-Hook-Functions.html +58 -78
  600. data/vendor/local/share/gtk-doc/html/glib/glib-Hostname-Utilities.html +14 -20
  601. data/vendor/local/share/gtk-doc/html/glib/glib-I18N.html +70 -79
  602. data/vendor/local/share/gtk-doc/html/glib/glib-IO-Channels.html +68 -102
  603. data/vendor/local/share/gtk-doc/html/glib/glib-Key-value-file-parser.html +166 -183
  604. data/vendor/local/share/gtk-doc/html/glib/glib-Keyed-Data-Lists.html +33 -41
  605. data/vendor/local/share/gtk-doc/html/glib/glib-Lexical-Scanner.html +80 -92
  606. data/vendor/local/share/gtk-doc/html/glib/glib-Memory-Allocation.html +101 -119
  607. data/vendor/local/share/gtk-doc/html/glib/glib-Memory-Slices.html +102 -75
  608. data/vendor/local/share/gtk-doc/html/glib/glib-Message-Logging.html +133 -60
  609. data/vendor/local/share/gtk-doc/html/glib/glib-Miscellaneous-Macros.html +192 -162
  610. data/vendor/local/share/gtk-doc/html/glib/glib-Miscellaneous-Utility-Functions.html +107 -155
  611. data/vendor/local/share/gtk-doc/html/glib/glib-N-ary-Trees.html +69 -103
  612. data/vendor/local/share/gtk-doc/html/glib/glib-Numerical-Definitions.html +12 -16
  613. data/vendor/local/share/gtk-doc/html/glib/glib-Perl-compatible-regular-expressions.html +199 -230
  614. data/vendor/local/share/gtk-doc/html/glib/glib-Pointer-Arrays.html +54 -67
  615. data/vendor/local/share/gtk-doc/html/glib/glib-Quarks.html +15 -22
  616. data/vendor/local/share/gtk-doc/html/glib/glib-Random-Numbers.html +24 -39
  617. data/vendor/local/share/gtk-doc/html/glib/glib-Relations-and-Tuples.html +29 -36
  618. data/vendor/local/share/gtk-doc/html/glib/glib-Sequences.html +187 -173
  619. data/vendor/local/share/gtk-doc/html/glib/glib-Shell-related-Utilities.html +13 -17
  620. data/vendor/local/share/gtk-doc/html/glib/glib-Simple-XML-Subset-Parser.html +104 -117
  621. data/vendor/local/share/gtk-doc/html/glib/glib-Singly-Linked-Lists.html +62 -89
  622. data/vendor/local/share/gtk-doc/html/glib/glib-Spawning-Processes.html +26 -38
  623. data/vendor/local/share/gtk-doc/html/glib/glib-Standard-Macros.html +15 -23
  624. data/vendor/local/share/gtk-doc/html/glib/glib-String-Chunks.html +13 -18
  625. data/vendor/local/share/gtk-doc/html/glib/glib-String-Utility-Functions.html +210 -261
  626. data/vendor/local/share/gtk-doc/html/glib/glib-Strings.html +95 -101
  627. data/vendor/local/share/gtk-doc/html/glib/glib-Testing.html +306 -268
  628. data/vendor/local/share/gtk-doc/html/glib/glib-The-Main-Event-Loop.html +373 -369
  629. data/vendor/local/share/gtk-doc/html/glib/glib-Thread-Pools.html +79 -45
  630. data/vendor/local/share/gtk-doc/html/glib/glib-Threads.html +316 -319
  631. data/vendor/local/share/gtk-doc/html/glib/glib-Timers.html +12 -15
  632. data/vendor/local/share/gtk-doc/html/glib/glib-Trash-Stacks.html +44 -26
  633. data/vendor/local/share/gtk-doc/html/glib/glib-Type-Conversion-Macros.html +20 -21
  634. data/vendor/local/share/gtk-doc/html/glib/glib-UNIX-specific-utilities-and-integration.html +44 -53
  635. data/vendor/local/share/gtk-doc/html/glib/glib-URI-Functions.html +21 -26
  636. data/vendor/local/share/gtk-doc/html/glib/glib-Unicode-Manipulation.html +200 -220
  637. data/vendor/local/share/gtk-doc/html/glib/glib-Version-Information.html +51 -28
  638. data/vendor/local/share/gtk-doc/html/glib/glib-Warnings-and-Assertions.html +38 -41
  639. data/vendor/local/share/gtk-doc/html/glib/glib-Windows-Compatibility-Functions.html +25 -34
  640. data/vendor/local/share/gtk-doc/html/glib/glib-building.html +3 -4
  641. data/vendor/local/share/gtk-doc/html/glib/glib-changes.html +3 -4
  642. data/vendor/local/share/gtk-doc/html/glib/glib-compiling.html +3 -4
  643. data/vendor/local/share/gtk-doc/html/glib/glib-core.html +3 -4
  644. data/vendor/local/share/gtk-doc/html/glib/glib-cross-compiling.html +3 -4
  645. data/vendor/local/share/gtk-doc/html/glib/glib-data-types.html +3 -4
  646. data/vendor/local/share/gtk-doc/html/glib/glib-fundamentals.html +6 -4
  647. data/vendor/local/share/gtk-doc/html/glib/glib-gettextize.html +3 -4
  648. data/vendor/local/share/gtk-doc/html/glib/glib-programming.html +4 -5
  649. data/vendor/local/share/gtk-doc/html/glib/glib-regex-syntax.html +14 -15
  650. data/vendor/local/share/gtk-doc/html/glib/glib-resources.html +3 -4
  651. data/vendor/local/share/gtk-doc/html/glib/glib-running.html +3 -4
  652. data/vendor/local/share/gtk-doc/html/glib/glib-utilities.html +3 -4
  653. data/vendor/local/share/gtk-doc/html/glib/glib.devhelp2 +44 -59
  654. data/vendor/local/share/gtk-doc/html/glib/glib.html +3 -4
  655. data/vendor/local/share/gtk-doc/html/glib/gtester-report.html +3 -4
  656. data/vendor/local/share/gtk-doc/html/glib/gtester.html +3 -4
  657. data/vendor/local/share/gtk-doc/html/glib/gvariant-format-strings.html +149 -149
  658. data/vendor/local/share/gtk-doc/html/glib/gvariant-text.html +11 -12
  659. data/vendor/local/share/gtk-doc/html/glib/index.html +9 -5
  660. data/vendor/local/share/gtk-doc/html/glib/index.sgml +36 -2
  661. data/vendor/local/share/gtk-doc/html/glib/style.css +9 -6
  662. data/vendor/local/share/gtk-doc/html/glib/tools.html +3 -4
  663. data/vendor/local/share/gtk-doc/html/gobject/GBinding.html +53 -57
  664. data/vendor/local/share/gtk-doc/html/gobject/GTypeModule.html +72 -77
  665. data/vendor/local/share/gtk-doc/html/gobject/GTypePlugin.html +19 -20
  666. data/vendor/local/share/gtk-doc/html/gobject/annotation-glossary.html +14 -6
  667. data/vendor/local/share/gtk-doc/html/gobject/api-index-2-10.html +3 -4
  668. data/vendor/local/share/gtk-doc/html/gobject/api-index-2-12.html +3 -4
  669. data/vendor/local/share/gtk-doc/html/gobject/api-index-2-14.html +3 -4
  670. data/vendor/local/share/gtk-doc/html/gobject/api-index-2-18.html +3 -4
  671. data/vendor/local/share/gtk-doc/html/gobject/api-index-2-2.html +3 -4
  672. data/vendor/local/share/gtk-doc/html/gobject/api-index-2-22.html +3 -4
  673. data/vendor/local/share/gtk-doc/html/gobject/api-index-2-24.html +3 -4
  674. data/vendor/local/share/gtk-doc/html/gobject/api-index-2-26.html +3 -4
  675. data/vendor/local/share/gtk-doc/html/gobject/api-index-2-28.html +3 -4
  676. data/vendor/local/share/gtk-doc/html/gobject/api-index-2-30.html +3 -4
  677. data/vendor/local/share/gtk-doc/html/gobject/api-index-2-32.html +3 -4
  678. data/vendor/local/share/gtk-doc/html/gobject/api-index-2-34.html +3 -4
  679. data/vendor/local/share/gtk-doc/html/gobject/api-index-2-36.html +3 -4
  680. data/vendor/local/share/gtk-doc/html/gobject/api-index-2-38.html +3 -4
  681. data/vendor/local/share/gtk-doc/html/gobject/api-index-2-4.html +3 -4
  682. data/vendor/local/share/gtk-doc/html/gobject/api-index-2-40.html +3 -4
  683. data/vendor/local/share/gtk-doc/html/gobject/api-index-2-42.html +3 -4
  684. data/vendor/local/share/gtk-doc/html/gobject/api-index-2-44.html +5 -6
  685. data/vendor/local/share/gtk-doc/html/gobject/api-index-2-46.html +34 -0
  686. data/vendor/local/share/gtk-doc/html/gobject/api-index-2-6.html +3 -4
  687. data/vendor/local/share/gtk-doc/html/gobject/api-index-2-8.html +3 -4
  688. data/vendor/local/share/gtk-doc/html/gobject/api-index-deprecated.html +3 -4
  689. data/vendor/local/share/gtk-doc/html/gobject/api-index-full.html +7 -8
  690. data/vendor/local/share/gtk-doc/html/gobject/ch01s02.html +22 -17
  691. data/vendor/local/share/gtk-doc/html/gobject/chapter-gobject.html +85 -135
  692. data/vendor/local/share/gtk-doc/html/gobject/chapter-gtype.html +80 -144
  693. data/vendor/local/share/gtk-doc/html/gobject/chapter-intro.html +7 -8
  694. data/vendor/local/share/gtk-doc/html/gobject/chapter-signal.html +59 -75
  695. data/vendor/local/share/gtk-doc/html/gobject/glib-genmarshal.html +20 -21
  696. data/vendor/local/share/gtk-doc/html/gobject/glib-mkenums.html +19 -20
  697. data/vendor/local/share/gtk-doc/html/gobject/gobject-Boxed-Types.html +68 -89
  698. data/vendor/local/share/gtk-doc/html/gobject/gobject-Closures.html +227 -218
  699. data/vendor/local/share/gtk-doc/html/gobject/gobject-Enumeration-and-Flag-Types.html +48 -57
  700. data/vendor/local/share/gtk-doc/html/gobject/gobject-GParamSpec.html +125 -96
  701. data/vendor/local/share/gtk-doc/html/gobject/gobject-Generic-values.html +78 -90
  702. data/vendor/local/share/gtk-doc/html/gobject/gobject-Signals.html +143 -138
  703. data/vendor/local/share/gtk-doc/html/gobject/gobject-Standard-Parameter-and-Value-Types.html +226 -285
  704. data/vendor/local/share/gtk-doc/html/gobject/gobject-The-Base-Object-Type.html +306 -289
  705. data/vendor/local/share/gtk-doc/html/gobject/gobject-Type-Information.html +450 -448
  706. data/vendor/local/share/gtk-doc/html/gobject/gobject-Value-arrays.html +22 -23
  707. data/vendor/local/share/gtk-doc/html/gobject/gobject-Varargs-Value-Collection.html +11 -12
  708. data/vendor/local/share/gtk-doc/html/gobject/gobject-memory.html +32 -91
  709. data/vendor/local/share/gtk-doc/html/gobject/gobject-properties.html +134 -133
  710. data/vendor/local/share/gtk-doc/html/gobject/gobject-query.html +3 -4
  711. data/vendor/local/share/gtk-doc/html/gobject/gobject.devhelp2 +4 -8
  712. data/vendor/local/share/gtk-doc/html/gobject/gtype-conventions.html +89 -98
  713. data/vendor/local/share/gtk-doc/html/gobject/gtype-instantiable-classed.html +119 -112
  714. data/vendor/local/share/gtk-doc/html/gobject/gtype-non-instantiable-classed.html +199 -183
  715. data/vendor/local/share/gtk-doc/html/gobject/gtype-non-instantiable.html +30 -30
  716. data/vendor/local/share/gtk-doc/html/gobject/howto-gobject-chainup.html +32 -33
  717. data/vendor/local/share/gtk-doc/html/gobject/howto-gobject-code.html +80 -32
  718. data/vendor/local/share/gtk-doc/html/gobject/howto-gobject-construction.html +73 -53
  719. data/vendor/local/share/gtk-doc/html/gobject/howto-gobject-destruction.html +52 -50
  720. data/vendor/local/share/gtk-doc/html/gobject/howto-gobject-methods.html +255 -133
  721. data/vendor/local/share/gtk-doc/html/gobject/howto-gobject.html +147 -111
  722. data/vendor/local/share/gtk-doc/html/gobject/howto-interface-implement.html +65 -122
  723. data/vendor/local/share/gtk-doc/html/gobject/howto-interface-override.html +93 -79
  724. data/vendor/local/share/gtk-doc/html/gobject/howto-interface-prerequisite.html +80 -54
  725. data/vendor/local/share/gtk-doc/html/gobject/howto-interface-properties.html +82 -87
  726. data/vendor/local/share/gtk-doc/html/gobject/howto-interface.html +126 -62
  727. data/vendor/local/share/gtk-doc/html/gobject/howto-signals.html +61 -54
  728. data/vendor/local/share/gtk-doc/html/gobject/index.html +10 -10
  729. data/vendor/local/share/gtk-doc/html/gobject/index.sgml +4 -2
  730. data/vendor/local/share/gtk-doc/html/gobject/pr01.html +3 -4
  731. data/vendor/local/share/gtk-doc/html/gobject/pt01.html +3 -4
  732. data/vendor/local/share/gtk-doc/html/gobject/pt02.html +10 -11
  733. data/vendor/local/share/gtk-doc/html/gobject/pt03.html +3 -4
  734. data/vendor/local/share/gtk-doc/html/gobject/rn01.html +3 -4
  735. data/vendor/local/share/gtk-doc/html/gobject/rn02.html +3 -4
  736. data/vendor/local/share/gtk-doc/html/gobject/signal.html +98 -198
  737. data/vendor/local/share/gtk-doc/html/gobject/style.css +9 -6
  738. data/vendor/local/share/gtk-doc/html/gobject/tools-ginspector.html +3 -4
  739. data/vendor/local/share/gtk-doc/html/gobject/tools-gob.html +3 -4
  740. data/vendor/local/share/gtk-doc/html/gobject/tools-gtkdoc.html +10 -11
  741. data/vendor/local/share/gtk-doc/html/gobject/tools-refdb.html +3 -4
  742. data/vendor/local/share/gtk-doc/html/gobject/tools-vala.html +3 -4
  743. data/vendor/local/share/gtk-doc/html/p11-kit/config-example.html +3 -4
  744. data/vendor/local/share/gtk-doc/html/p11-kit/config-files.html +3 -4
  745. data/vendor/local/share/gtk-doc/html/p11-kit/config.html +3 -4
  746. data/vendor/local/share/gtk-doc/html/p11-kit/devel-building-style.html +3 -4
  747. data/vendor/local/share/gtk-doc/html/p11-kit/devel-building.html +3 -4
  748. data/vendor/local/share/gtk-doc/html/p11-kit/devel-commands.html +3 -4
  749. data/vendor/local/share/gtk-doc/html/p11-kit/devel-debugging.html +3 -4
  750. data/vendor/local/share/gtk-doc/html/p11-kit/devel-paths.html +3 -4
  751. data/vendor/local/share/gtk-doc/html/p11-kit/devel-testing.html +3 -4
  752. data/vendor/local/share/gtk-doc/html/p11-kit/devel.html +3 -4
  753. data/vendor/local/share/gtk-doc/html/p11-kit/gtk-doc.css +9 -6
  754. data/vendor/local/share/gtk-doc/html/p11-kit/index.html +2 -3
  755. data/vendor/local/share/gtk-doc/html/p11-kit/index.sgml +22 -0
  756. data/vendor/local/share/gtk-doc/html/p11-kit/p11-kit-Deprecated.html +3 -13
  757. data/vendor/local/share/gtk-doc/html/p11-kit/p11-kit-Future.html +3 -14
  758. data/vendor/local/share/gtk-doc/html/p11-kit/p11-kit-Modules.html +3 -15
  759. data/vendor/local/share/gtk-doc/html/p11-kit/p11-kit-PIN-Callbacks.html +3 -14
  760. data/vendor/local/share/gtk-doc/html/p11-kit/p11-kit-URIs.html +3 -18
  761. data/vendor/local/share/gtk-doc/html/p11-kit/p11-kit-Utilities.html +3 -8
  762. data/vendor/local/share/gtk-doc/html/p11-kit/p11-kit.devhelp2 +22 -1
  763. data/vendor/local/share/gtk-doc/html/p11-kit/p11-kit.html +2 -3
  764. data/vendor/local/share/gtk-doc/html/p11-kit/pkcs11-conf.html +7 -8
  765. data/vendor/local/share/gtk-doc/html/p11-kit/reference.html +3 -4
  766. data/vendor/local/share/gtk-doc/html/p11-kit/sharing-managed.html +3 -4
  767. data/vendor/local/share/gtk-doc/html/p11-kit/sharing.html +3 -4
  768. data/vendor/local/share/gtk-doc/html/p11-kit/tools.html +3 -4
  769. data/vendor/local/share/gtk-doc/html/p11-kit/trust-disable.html +3 -4
  770. data/vendor/local/share/gtk-doc/html/p11-kit/trust-glib-networking.html +3 -4
  771. data/vendor/local/share/gtk-doc/html/p11-kit/trust-module.html +3 -4
  772. data/vendor/local/share/gtk-doc/html/p11-kit/trust-nss.html +3 -4
  773. data/vendor/local/share/gtk-doc/html/p11-kit/trust.html +3 -4
  774. data/vendor/local/share/info/gmp.info +153 -158
  775. data/vendor/local/share/info/gmp.info-1 +131 -178
  776. data/vendor/local/share/info/gmp.info-2 +250 -193
  777. data/vendor/local/share/info/libtasn1.info +2 -2
  778. data/vendor/local/share/license/gmp/AUTHORS +1 -1
  779. data/vendor/local/share/license/pcre/AUTHORS +45 -0
  780. data/vendor/local/share/license/pcre/COPYING +5 -0
  781. data/vendor/local/share/locale/be/LC_MESSAGES/gettext-runtime.mo +0 -0
  782. data/vendor/local/share/locale/bg/LC_MESSAGES/gettext-runtime.mo +0 -0
  783. data/vendor/local/share/locale/bg/LC_MESSAGES/glib20.mo +0 -0
  784. data/vendor/local/share/locale/ca/LC_MESSAGES/gettext-runtime.mo +0 -0
  785. data/vendor/local/share/locale/ca/LC_MESSAGES/glib20.mo +0 -0
  786. data/vendor/local/share/locale/cs/LC_MESSAGES/gettext-runtime.mo +0 -0
  787. data/vendor/local/share/locale/cs/LC_MESSAGES/glib20.mo +0 -0
  788. data/vendor/local/share/locale/cs/LC_MESSAGES/gnutls.mo +0 -0
  789. data/vendor/local/share/locale/da/LC_MESSAGES/gettext-runtime.mo +0 -0
  790. data/vendor/local/share/locale/da/LC_MESSAGES/glib20.mo +0 -0
  791. data/vendor/local/share/locale/de/LC_MESSAGES/gettext-runtime.mo +0 -0
  792. data/vendor/local/share/locale/de/LC_MESSAGES/glib20.mo +0 -0
  793. data/vendor/local/share/locale/de/LC_MESSAGES/gnutls.mo +0 -0
  794. data/vendor/local/share/locale/el/LC_MESSAGES/gettext-runtime.mo +0 -0
  795. data/vendor/local/share/locale/el/LC_MESSAGES/glib20.mo +0 -0
  796. data/vendor/local/share/locale/en@boldquot/LC_MESSAGES/gettext-runtime.mo +0 -0
  797. data/vendor/local/share/locale/en@boldquot/LC_MESSAGES/gnutls.mo +0 -0
  798. data/vendor/local/share/locale/en@quot/LC_MESSAGES/gettext-runtime.mo +0 -0
  799. data/vendor/local/share/locale/en@quot/LC_MESSAGES/gnutls.mo +0 -0
  800. data/vendor/local/share/locale/eo/LC_MESSAGES/gettext-runtime.mo +0 -0
  801. data/vendor/local/share/locale/eo/LC_MESSAGES/gnutls.mo +0 -0
  802. data/vendor/local/share/locale/es/LC_MESSAGES/gettext-runtime.mo +0 -0
  803. data/vendor/local/share/locale/es/LC_MESSAGES/glib20.mo +0 -0
  804. data/vendor/local/share/locale/et/LC_MESSAGES/gettext-runtime.mo +0 -0
  805. data/vendor/local/share/locale/eu/LC_MESSAGES/glib20.mo +0 -0
  806. data/vendor/local/share/locale/fi/LC_MESSAGES/gettext-runtime.mo +0 -0
  807. data/vendor/local/share/locale/fi/LC_MESSAGES/glib20.mo +0 -0
  808. data/vendor/local/share/locale/fi/LC_MESSAGES/gnutls.mo +0 -0
  809. data/vendor/local/share/locale/fr/LC_MESSAGES/gettext-runtime.mo +0 -0
  810. data/vendor/local/share/locale/fr/LC_MESSAGES/glib20.mo +0 -0
  811. data/vendor/local/share/locale/fr/LC_MESSAGES/gnutls.mo +0 -0
  812. data/vendor/local/share/locale/ga/LC_MESSAGES/gettext-runtime.mo +0 -0
  813. data/vendor/local/share/locale/gd/LC_MESSAGES/glib20.mo +0 -0
  814. data/vendor/local/share/locale/gl/LC_MESSAGES/gettext-runtime.mo +0 -0
  815. data/vendor/local/share/locale/gl/LC_MESSAGES/glib20.mo +0 -0
  816. data/vendor/local/share/locale/he/LC_MESSAGES/glib20.mo +0 -0
  817. data/vendor/local/share/locale/hr/LC_MESSAGES/gettext-runtime.mo +0 -0
  818. data/vendor/local/share/locale/hu/LC_MESSAGES/gettext-runtime.mo +0 -0
  819. data/vendor/local/share/locale/hu/LC_MESSAGES/glib20.mo +0 -0
  820. data/vendor/local/share/locale/id/LC_MESSAGES/gettext-runtime.mo +0 -0
  821. data/vendor/local/share/locale/id/LC_MESSAGES/glib20.mo +0 -0
  822. data/vendor/local/share/locale/is/LC_MESSAGES/glib20.mo +0 -0
  823. data/vendor/local/share/locale/it/LC_MESSAGES/gettext-runtime.mo +0 -0
  824. data/vendor/local/share/locale/it/LC_MESSAGES/glib20.mo +0 -0
  825. data/vendor/local/share/locale/it/LC_MESSAGES/gnutls.mo +0 -0
  826. data/vendor/local/share/locale/ja/LC_MESSAGES/gettext-runtime.mo +0 -0
  827. data/vendor/local/share/locale/ja/LC_MESSAGES/glib-networking.mo +0 -0
  828. data/vendor/local/share/locale/kk/LC_MESSAGES/glib20.mo +0 -0
  829. data/vendor/local/share/locale/ko/LC_MESSAGES/gettext-runtime.mo +0 -0
  830. data/vendor/local/share/locale/ko/LC_MESSAGES/glib20.mo +0 -0
  831. data/vendor/local/share/locale/lt/LC_MESSAGES/glib20.mo +0 -0
  832. data/vendor/local/share/locale/lv/LC_MESSAGES/glib20.mo +0 -0
  833. data/vendor/local/share/locale/ms/LC_MESSAGES/gnutls.mo +0 -0
  834. data/vendor/local/share/locale/nb/LC_MESSAGES/gettext-runtime.mo +0 -0
  835. data/vendor/local/share/locale/nb/LC_MESSAGES/glib20.mo +0 -0
  836. data/vendor/local/share/locale/nl/LC_MESSAGES/gettext-runtime.mo +0 -0
  837. data/vendor/local/share/locale/nl/LC_MESSAGES/gnutls.mo +0 -0
  838. data/vendor/local/share/locale/nn/LC_MESSAGES/gettext-runtime.mo +0 -0
  839. data/vendor/local/share/locale/oc/LC_MESSAGES/glib-networking.mo +0 -0
  840. data/vendor/local/share/locale/oc/LC_MESSAGES/glib20.mo +0 -0
  841. data/vendor/local/share/locale/pl/LC_MESSAGES/gettext-runtime.mo +0 -0
  842. data/vendor/local/share/locale/pl/LC_MESSAGES/glib20.mo +0 -0
  843. data/vendor/local/share/locale/pl/LC_MESSAGES/gnutls.mo +0 -0
  844. data/vendor/local/share/locale/pt/LC_MESSAGES/gettext-runtime.mo +0 -0
  845. data/vendor/local/share/locale/pt/LC_MESSAGES/glib-networking.mo +0 -0
  846. data/vendor/local/share/locale/pt/LC_MESSAGES/glib20.mo +0 -0
  847. data/vendor/local/share/locale/pt_BR/LC_MESSAGES/gettext-runtime.mo +0 -0
  848. data/vendor/local/share/locale/pt_BR/LC_MESSAGES/glib20.mo +0 -0
  849. data/vendor/local/share/locale/ro/LC_MESSAGES/gettext-runtime.mo +0 -0
  850. data/vendor/local/share/locale/ru/LC_MESSAGES/gettext-runtime.mo +0 -0
  851. data/vendor/local/share/locale/ru/LC_MESSAGES/glib20.mo +0 -0
  852. data/vendor/local/share/locale/sk/LC_MESSAGES/gettext-runtime.mo +0 -0
  853. data/vendor/local/share/locale/sk/LC_MESSAGES/glib20.mo +0 -0
  854. data/vendor/local/share/locale/sl/LC_MESSAGES/gettext-runtime.mo +0 -0
  855. data/vendor/local/share/locale/sl/LC_MESSAGES/glib20.mo +0 -0
  856. data/vendor/local/share/locale/sr/LC_MESSAGES/gettext-runtime.mo +0 -0
  857. data/vendor/local/share/locale/sr/LC_MESSAGES/glib20.mo +0 -0
  858. data/vendor/local/share/locale/sr@latin/LC_MESSAGES/glib20.mo +0 -0
  859. data/vendor/local/share/locale/sv/LC_MESSAGES/gettext-runtime.mo +0 -0
  860. data/vendor/local/share/locale/sv/LC_MESSAGES/glib20.mo +0 -0
  861. data/vendor/local/share/locale/sv/LC_MESSAGES/gnutls.mo +0 -0
  862. data/vendor/local/share/locale/th/LC_MESSAGES/glib20.mo +0 -0
  863. data/vendor/local/share/locale/tr/LC_MESSAGES/gettext-runtime.mo +0 -0
  864. data/vendor/local/share/locale/tr/LC_MESSAGES/glib20.mo +0 -0
  865. data/vendor/local/share/locale/uk/LC_MESSAGES/gettext-runtime.mo +0 -0
  866. data/vendor/local/share/locale/uk/LC_MESSAGES/gnutls.mo +0 -0
  867. data/vendor/local/share/locale/vi/LC_MESSAGES/gettext-runtime.mo +0 -0
  868. data/vendor/local/share/locale/vi/LC_MESSAGES/glib20.mo +0 -0
  869. data/vendor/local/share/locale/vi/LC_MESSAGES/gnutls.mo +0 -0
  870. data/vendor/local/share/locale/zh_CN/LC_MESSAGES/gettext-runtime.mo +0 -0
  871. data/vendor/local/share/locale/zh_CN/LC_MESSAGES/glib20.mo +0 -0
  872. data/vendor/local/share/locale/zh_CN/LC_MESSAGES/gnutls.mo +0 -0
  873. data/vendor/local/share/locale/zh_HK/LC_MESSAGES/gettext-runtime.mo +0 -0
  874. data/vendor/local/share/locale/zh_TW/LC_MESSAGES/gettext-runtime.mo +0 -0
  875. data/vendor/local/share/locale/zh_TW/LC_MESSAGES/glib20.mo +0 -0
  876. data/vendor/local/share/man/man1/asn1Coding.1 +1 -1
  877. data/vendor/local/share/man/man1/asn1Decoding.1 +1 -1
  878. data/vendor/local/share/man/man1/asn1Parser.1 +1 -1
  879. data/vendor/local/share/man/man1/envsubst.1 +1 -1
  880. data/vendor/local/share/man/man1/gapplication.1 +2 -2
  881. data/vendor/local/share/man/man1/gdbus-codegen.1 +23 -22
  882. data/vendor/local/share/man/man1/gdbus.1 +2 -2
  883. data/vendor/local/share/man/man1/gettext.1 +1 -1
  884. data/vendor/local/share/man/man1/gio-querymodules.1 +2 -2
  885. data/vendor/local/share/man/man1/glib-compile-resources.1 +2 -2
  886. data/vendor/local/share/man/man1/glib-compile-schemas.1 +7 -2
  887. data/vendor/local/share/man/man1/glib-genmarshal.1 +2 -2
  888. data/vendor/local/share/man/man1/glib-gettextize.1 +2 -2
  889. data/vendor/local/share/man/man1/glib-mkenums.1 +2 -2
  890. data/vendor/local/share/man/man1/gobject-query.1 +2 -2
  891. data/vendor/local/share/man/man1/gresource.1 +2 -2
  892. data/vendor/local/share/man/man1/gsettings.1 +2 -2
  893. data/vendor/local/share/man/man1/gtester-report.1 +2 -2
  894. data/vendor/local/share/man/man1/gtester.1 +2 -2
  895. data/vendor/local/share/man/man1/ngettext.1 +1 -1
  896. data/vendor/local/share/man/man1/pcre-config.1 +92 -0
  897. data/vendor/local/share/man/man1/pcregrep.1 +683 -0
  898. data/vendor/local/share/man/man1/pcretest.1 +1156 -0
  899. data/vendor/local/share/man/man3/asn1_array2tree.3 +1 -1
  900. data/vendor/local/share/man/man3/asn1_bit_der.3 +1 -1
  901. data/vendor/local/share/man/man3/asn1_check_version.3 +1 -1
  902. data/vendor/local/share/man/man3/asn1_copy_node.3 +1 -1
  903. data/vendor/local/share/man/man3/asn1_create_element.3 +1 -1
  904. data/vendor/local/share/man/man3/asn1_decode_simple_ber.3 +1 -1
  905. data/vendor/local/share/man/man3/asn1_decode_simple_der.3 +1 -1
  906. data/vendor/local/share/man/man3/asn1_delete_element.3 +1 -1
  907. data/vendor/local/share/man/man3/asn1_delete_structure.3 +1 -1
  908. data/vendor/local/share/man/man3/asn1_delete_structure2.3 +1 -1
  909. data/vendor/local/share/man/man3/asn1_der_coding.3 +1 -1
  910. data/vendor/local/share/man/man3/asn1_der_decoding.3 +1 -1
  911. data/vendor/local/share/man/man3/asn1_der_decoding2.3 +1 -1
  912. data/vendor/local/share/man/man3/asn1_der_decoding_element.3 +1 -1
  913. data/vendor/local/share/man/man3/asn1_der_decoding_startEnd.3 +1 -1
  914. data/vendor/local/share/man/man3/asn1_dup_node.3 +1 -1
  915. data/vendor/local/share/man/man3/asn1_encode_simple_der.3 +1 -1
  916. data/vendor/local/share/man/man3/asn1_expand_any_defined_by.3 +1 -1
  917. data/vendor/local/share/man/man3/asn1_expand_octet_string.3 +1 -1
  918. data/vendor/local/share/man/man3/asn1_find_node.3 +1 -1
  919. data/vendor/local/share/man/man3/asn1_find_structure_from_oid.3 +1 -1
  920. data/vendor/local/share/man/man3/asn1_get_bit_der.3 +1 -1
  921. data/vendor/local/share/man/man3/asn1_get_length_ber.3 +1 -1
  922. data/vendor/local/share/man/man3/asn1_get_length_der.3 +1 -1
  923. data/vendor/local/share/man/man3/asn1_get_object_id_der.3 +1 -1
  924. data/vendor/local/share/man/man3/asn1_get_octet_der.3 +1 -1
  925. data/vendor/local/share/man/man3/asn1_get_tag_der.3 +1 -1
  926. data/vendor/local/share/man/man3/asn1_length_der.3 +1 -1
  927. data/vendor/local/share/man/man3/asn1_number_of_elements.3 +1 -1
  928. data/vendor/local/share/man/man3/asn1_octet_der.3 +1 -1
  929. data/vendor/local/share/man/man3/asn1_parser2array.3 +1 -1
  930. data/vendor/local/share/man/man3/asn1_parser2tree.3 +1 -1
  931. data/vendor/local/share/man/man3/asn1_perror.3 +1 -1
  932. data/vendor/local/share/man/man3/asn1_print_structure.3 +1 -1
  933. data/vendor/local/share/man/man3/asn1_read_node_value.3 +1 -1
  934. data/vendor/local/share/man/man3/asn1_read_tag.3 +1 -1
  935. data/vendor/local/share/man/man3/asn1_read_value.3 +1 -1
  936. data/vendor/local/share/man/man3/asn1_read_value_type.3 +1 -1
  937. data/vendor/local/share/man/man3/asn1_strerror.3 +1 -1
  938. data/vendor/local/share/man/man3/asn1_write_value.3 +1 -1
  939. data/vendor/local/share/man/man3/bind_textdomain_codeset.3 +1 -1
  940. data/vendor/local/share/man/man3/bindtextdomain.3 +1 -1
  941. data/vendor/local/share/man/man3/gettext.3 +1 -1
  942. data/vendor/local/share/man/man3/ngettext.3 +1 -1
  943. data/vendor/local/share/man/man3/pcre.3 +230 -0
  944. data/vendor/local/share/man/man3/pcre16.3 +371 -0
  945. data/vendor/local/share/man/man3/pcre16_assign_jit_stack.3 +59 -0
  946. data/vendor/local/share/man/man3/pcre16_compile.3 +96 -0
  947. data/vendor/local/share/man/man3/pcre16_compile2.3 +101 -0
  948. data/vendor/local/share/man/man3/pcre16_config.3 +79 -0
  949. data/vendor/local/share/man/man3/pcre16_copy_named_substring.3 +51 -0
  950. data/vendor/local/share/man/man3/pcre16_copy_substring.3 +47 -0
  951. data/vendor/local/share/man/man3/pcre16_dfa_exec.3 +118 -0
  952. data/vendor/local/share/man/man3/pcre16_exec.3 +99 -0
  953. data/vendor/local/share/man/man3/pcre16_free_study.3 +31 -0
  954. data/vendor/local/share/man/man3/pcre16_free_substring.3 +31 -0
  955. data/vendor/local/share/man/man3/pcre16_free_substring_list.3 +31 -0
  956. data/vendor/local/share/man/man3/pcre16_fullinfo.3 +103 -0
  957. data/vendor/local/share/man/man3/pcre16_get_named_substring.3 +54 -0
  958. data/vendor/local/share/man/man3/pcre16_get_stringnumber.3 +43 -0
  959. data/vendor/local/share/man/man3/pcre16_get_stringtable_entries.3 +46 -0
  960. data/vendor/local/share/man/man3/pcre16_get_substring.3 +50 -0
  961. data/vendor/local/share/man/man3/pcre16_get_substring_list.3 +47 -0
  962. data/vendor/local/share/man/man3/pcre16_jit_exec.3 +96 -0
  963. data/vendor/local/share/man/man3/pcre16_jit_stack_alloc.3 +43 -0
  964. data/vendor/local/share/man/man3/pcre16_jit_stack_free.3 +35 -0
  965. data/vendor/local/share/man/man3/pcre16_maketables.3 +33 -0
  966. data/vendor/local/share/man/man3/pcre16_pattern_to_host_byte_order.3 +44 -0
  967. data/vendor/local/share/man/man3/pcre16_refcount.3 +36 -0
  968. data/vendor/local/share/man/man3/pcre16_study.3 +54 -0
  969. data/vendor/local/share/man/man3/pcre16_utf16_to_host_byte_order.3 +45 -0
  970. data/vendor/local/share/man/man3/pcre16_version.3 +31 -0
  971. data/vendor/local/share/man/man3/pcre32.3 +369 -0
  972. data/vendor/local/share/man/man3/pcre32_assign_jit_stack.3 +59 -0
  973. data/vendor/local/share/man/man3/pcre32_compile.3 +96 -0
  974. data/vendor/local/share/man/man3/pcre32_compile2.3 +101 -0
  975. data/vendor/local/share/man/man3/pcre32_config.3 +79 -0
  976. data/vendor/local/share/man/man3/pcre32_copy_named_substring.3 +51 -0
  977. data/vendor/local/share/man/man3/pcre32_copy_substring.3 +47 -0
  978. data/vendor/local/share/man/man3/pcre32_dfa_exec.3 +118 -0
  979. data/vendor/local/share/man/man3/pcre32_exec.3 +99 -0
  980. data/vendor/local/share/man/man3/pcre32_free_study.3 +31 -0
  981. data/vendor/local/share/man/man3/pcre32_free_substring.3 +31 -0
  982. data/vendor/local/share/man/man3/pcre32_free_substring_list.3 +31 -0
  983. data/vendor/local/share/man/man3/pcre32_fullinfo.3 +103 -0
  984. data/vendor/local/share/man/man3/pcre32_get_named_substring.3 +54 -0
  985. data/vendor/local/share/man/man3/pcre32_get_stringnumber.3 +43 -0
  986. data/vendor/local/share/man/man3/pcre32_get_stringtable_entries.3 +46 -0
  987. data/vendor/local/share/man/man3/pcre32_get_substring.3 +50 -0
  988. data/vendor/local/share/man/man3/pcre32_get_substring_list.3 +47 -0
  989. data/vendor/local/share/man/man3/pcre32_jit_exec.3 +96 -0
  990. data/vendor/local/share/man/man3/pcre32_jit_stack_alloc.3 +43 -0
  991. data/vendor/local/share/man/man3/pcre32_jit_stack_free.3 +35 -0
  992. data/vendor/local/share/man/man3/pcre32_maketables.3 +33 -0
  993. data/vendor/local/share/man/man3/pcre32_pattern_to_host_byte_order.3 +44 -0
  994. data/vendor/local/share/man/man3/pcre32_refcount.3 +36 -0
  995. data/vendor/local/share/man/man3/pcre32_study.3 +54 -0
  996. data/vendor/local/share/man/man3/pcre32_utf32_to_host_byte_order.3 +45 -0
  997. data/vendor/local/share/man/man3/pcre32_version.3 +31 -0
  998. data/vendor/local/share/man/man3/pcre_assign_jit_stack.3 +59 -0
  999. data/vendor/local/share/man/man3/pcre_compile.3 +96 -0
  1000. data/vendor/local/share/man/man3/pcre_compile2.3 +101 -0
  1001. data/vendor/local/share/man/man3/pcre_config.3 +79 -0
  1002. data/vendor/local/share/man/man3/pcre_copy_named_substring.3 +51 -0
  1003. data/vendor/local/share/man/man3/pcre_copy_substring.3 +47 -0
  1004. data/vendor/local/share/man/man3/pcre_dfa_exec.3 +118 -0
  1005. data/vendor/local/share/man/man3/pcre_exec.3 +99 -0
  1006. data/vendor/local/share/man/man3/pcre_free_study.3 +31 -0
  1007. data/vendor/local/share/man/man3/pcre_free_substring.3 +31 -0
  1008. data/vendor/local/share/man/man3/pcre_free_substring_list.3 +31 -0
  1009. data/vendor/local/share/man/man3/pcre_fullinfo.3 +103 -0
  1010. data/vendor/local/share/man/man3/pcre_get_named_substring.3 +54 -0
  1011. data/vendor/local/share/man/man3/pcre_get_stringnumber.3 +43 -0
  1012. data/vendor/local/share/man/man3/pcre_get_stringtable_entries.3 +46 -0
  1013. data/vendor/local/share/man/man3/pcre_get_substring.3 +50 -0
  1014. data/vendor/local/share/man/man3/pcre_get_substring_list.3 +47 -0
  1015. data/vendor/local/share/man/man3/pcre_jit_exec.3 +96 -0
  1016. data/vendor/local/share/man/man3/pcre_jit_stack_alloc.3 +43 -0
  1017. data/vendor/local/share/man/man3/pcre_jit_stack_free.3 +35 -0
  1018. data/vendor/local/share/man/man3/pcre_maketables.3 +33 -0
  1019. data/vendor/local/share/man/man3/pcre_pattern_to_host_byte_order.3 +44 -0
  1020. data/vendor/local/share/man/man3/pcre_refcount.3 +36 -0
  1021. data/vendor/local/share/man/man3/pcre_study.3 +54 -0
  1022. data/vendor/local/share/man/man3/pcre_utf16_to_host_byte_order.3 +45 -0
  1023. data/vendor/local/share/man/man3/pcre_utf32_to_host_byte_order.3 +45 -0
  1024. data/vendor/local/share/man/man3/pcre_version.3 +31 -0
  1025. data/vendor/local/share/man/man3/pcreapi.3 +2919 -0
  1026. data/vendor/local/share/man/man3/pcrebuild.3 +550 -0
  1027. data/vendor/local/share/man/man3/pcrecallout.3 +255 -0
  1028. data/vendor/local/share/man/man3/pcrecompat.3 +200 -0
  1029. data/vendor/local/share/man/man3/pcrecpp.3 +348 -0
  1030. data/vendor/local/share/man/man3/pcredemo.3 +424 -0
  1031. data/vendor/local/share/man/man3/pcrejit.3 +431 -0
  1032. data/vendor/local/share/man/man3/pcrelimits.3 +71 -0
  1033. data/vendor/local/share/man/man3/pcrematching.3 +214 -0
  1034. data/vendor/local/share/man/man3/pcrepartial.3 +476 -0
  1035. data/vendor/local/share/man/man3/pcrepattern.3 +3301 -0
  1036. data/vendor/local/share/man/man3/pcreperform.3 +177 -0
  1037. data/vendor/local/share/man/man3/pcreposix.3 +267 -0
  1038. data/vendor/local/share/man/man3/pcreprecompile.3 +155 -0
  1039. data/vendor/local/share/man/man3/pcresample.3 +99 -0
  1040. data/vendor/local/share/man/man3/pcrestack.3 +215 -0
  1041. data/vendor/local/share/man/man3/pcresyntax.3 +540 -0
  1042. data/vendor/local/share/man/man3/pcreunicode.3 +249 -0
  1043. data/vendor/local/share/man/man3/textdomain.3 +1 -1
  1044. metadata +233 -22
  1045. data/lib/2.0/glib2.so +0 -0
  1046. data/lib/2.1/glib2.so +0 -0
  1047. data/vendor/local/bin/libhogweed-4-1.dll +0 -0
  1048. data/vendor/local/share/gtk-doc/html/gio/ExampleAnimal.html +0 -1537
  1049. data/vendor/local/share/gtk-doc/html/gio/ExampleCat.html +0 -679
  1050. data/vendor/local/share/gtk-doc/html/gio/ExampleObject.html +0 -572
  1051. data/vendor/local/share/gtk-doc/html/gio/ExampleObjectManagerClient.html +0 -561
  1052. data/vendor/local/share/gtk-doc/html/gio/ch31.html +0 -75
  1053. data/vendor/local/share/gtk-doc/html/gio/ch32s02.html +0 -41
  1054. data/vendor/local/share/gtk-doc/html/gio/ch32s03.html +0 -39
  1055. data/vendor/local/share/gtk-doc/html/gio/ch33s04.html +0 -46
  1056. data/vendor/local/share/gtk-doc/html/gio/ch33s05.html +0 -48
  1057. data/vendor/local/share/gtk-doc/html/gio/gdbus-org.gtk.GDBus.Example.ObjectManager.Animal.html +0 -161
  1058. data/vendor/local/share/gtk-doc/html/gio/gdbus-org.gtk.GDBus.Example.ObjectManager.Cat.html +0 -51
@@ -0,0 +1,2922 @@
1
+ <html>
2
+ <head>
3
+ <title>pcreapi specification</title>
4
+ </head>
5
+ <body bgcolor="#FFFFFF" text="#00005A" link="#0066FF" alink="#3399FF" vlink="#2222BB">
6
+ <h1>pcreapi man page</h1>
7
+ <p>
8
+ Return to the <a href="index.html">PCRE index page</a>.
9
+ </p>
10
+ <p>
11
+ This page is part of the PCRE HTML documentation. It was generated automatically
12
+ from the original man page. If there is any nonsense in it, please consult the
13
+ man page, in case the conversion went wrong.
14
+ <br>
15
+ <ul>
16
+ <li><a name="TOC1" href="#SEC1">PCRE NATIVE API BASIC FUNCTIONS</a>
17
+ <li><a name="TOC2" href="#SEC2">PCRE NATIVE API STRING EXTRACTION FUNCTIONS</a>
18
+ <li><a name="TOC3" href="#SEC3">PCRE NATIVE API AUXILIARY FUNCTIONS</a>
19
+ <li><a name="TOC4" href="#SEC4">PCRE NATIVE API INDIRECTED FUNCTIONS</a>
20
+ <li><a name="TOC5" href="#SEC5">PCRE 8-BIT, 16-BIT, AND 32-BIT LIBRARIES</a>
21
+ <li><a name="TOC6" href="#SEC6">PCRE API OVERVIEW</a>
22
+ <li><a name="TOC7" href="#SEC7">NEWLINES</a>
23
+ <li><a name="TOC8" href="#SEC8">MULTITHREADING</a>
24
+ <li><a name="TOC9" href="#SEC9">SAVING PRECOMPILED PATTERNS FOR LATER USE</a>
25
+ <li><a name="TOC10" href="#SEC10">CHECKING BUILD-TIME OPTIONS</a>
26
+ <li><a name="TOC11" href="#SEC11">COMPILING A PATTERN</a>
27
+ <li><a name="TOC12" href="#SEC12">COMPILATION ERROR CODES</a>
28
+ <li><a name="TOC13" href="#SEC13">STUDYING A PATTERN</a>
29
+ <li><a name="TOC14" href="#SEC14">LOCALE SUPPORT</a>
30
+ <li><a name="TOC15" href="#SEC15">INFORMATION ABOUT A PATTERN</a>
31
+ <li><a name="TOC16" href="#SEC16">REFERENCE COUNTS</a>
32
+ <li><a name="TOC17" href="#SEC17">MATCHING A PATTERN: THE TRADITIONAL FUNCTION</a>
33
+ <li><a name="TOC18" href="#SEC18">EXTRACTING CAPTURED SUBSTRINGS BY NUMBER</a>
34
+ <li><a name="TOC19" href="#SEC19">EXTRACTING CAPTURED SUBSTRINGS BY NAME</a>
35
+ <li><a name="TOC20" href="#SEC20">DUPLICATE SUBPATTERN NAMES</a>
36
+ <li><a name="TOC21" href="#SEC21">FINDING ALL POSSIBLE MATCHES</a>
37
+ <li><a name="TOC22" href="#SEC22">OBTAINING AN ESTIMATE OF STACK USAGE</a>
38
+ <li><a name="TOC23" href="#SEC23">MATCHING A PATTERN: THE ALTERNATIVE FUNCTION</a>
39
+ <li><a name="TOC24" href="#SEC24">SEE ALSO</a>
40
+ <li><a name="TOC25" href="#SEC25">AUTHOR</a>
41
+ <li><a name="TOC26" href="#SEC26">REVISION</a>
42
+ </ul>
43
+ <P>
44
+ <b>#include &#60;pcre.h&#62;</b>
45
+ </P>
46
+ <br><a name="SEC1" href="#TOC1">PCRE NATIVE API BASIC FUNCTIONS</a><br>
47
+ <P>
48
+ <b>pcre *pcre_compile(const char *<i>pattern</i>, int <i>options</i>,</b>
49
+ <b> const char **<i>errptr</i>, int *<i>erroffset</i>,</b>
50
+ <b> const unsigned char *<i>tableptr</i>);</b>
51
+ <br>
52
+ <br>
53
+ <b>pcre *pcre_compile2(const char *<i>pattern</i>, int <i>options</i>,</b>
54
+ <b> int *<i>errorcodeptr</i>,</b>
55
+ <b> const char **<i>errptr</i>, int *<i>erroffset</i>,</b>
56
+ <b> const unsigned char *<i>tableptr</i>);</b>
57
+ <br>
58
+ <br>
59
+ <b>pcre_extra *pcre_study(const pcre *<i>code</i>, int <i>options</i>,</b>
60
+ <b> const char **<i>errptr</i>);</b>
61
+ <br>
62
+ <br>
63
+ <b>void pcre_free_study(pcre_extra *<i>extra</i>);</b>
64
+ <br>
65
+ <br>
66
+ <b>int pcre_exec(const pcre *<i>code</i>, const pcre_extra *<i>extra</i>,</b>
67
+ <b> const char *<i>subject</i>, int <i>length</i>, int <i>startoffset</i>,</b>
68
+ <b> int <i>options</i>, int *<i>ovector</i>, int <i>ovecsize</i>);</b>
69
+ <br>
70
+ <br>
71
+ <b>int pcre_dfa_exec(const pcre *<i>code</i>, const pcre_extra *<i>extra</i>,</b>
72
+ <b> const char *<i>subject</i>, int <i>length</i>, int <i>startoffset</i>,</b>
73
+ <b> int <i>options</i>, int *<i>ovector</i>, int <i>ovecsize</i>,</b>
74
+ <b> int *<i>workspace</i>, int <i>wscount</i>);</b>
75
+ </P>
76
+ <br><a name="SEC2" href="#TOC1">PCRE NATIVE API STRING EXTRACTION FUNCTIONS</a><br>
77
+ <P>
78
+ <b>int pcre_copy_named_substring(const pcre *<i>code</i>,</b>
79
+ <b> const char *<i>subject</i>, int *<i>ovector</i>,</b>
80
+ <b> int <i>stringcount</i>, const char *<i>stringname</i>,</b>
81
+ <b> char *<i>buffer</i>, int <i>buffersize</i>);</b>
82
+ <br>
83
+ <br>
84
+ <b>int pcre_copy_substring(const char *<i>subject</i>, int *<i>ovector</i>,</b>
85
+ <b> int <i>stringcount</i>, int <i>stringnumber</i>, char *<i>buffer</i>,</b>
86
+ <b> int <i>buffersize</i>);</b>
87
+ <br>
88
+ <br>
89
+ <b>int pcre_get_named_substring(const pcre *<i>code</i>,</b>
90
+ <b> const char *<i>subject</i>, int *<i>ovector</i>,</b>
91
+ <b> int <i>stringcount</i>, const char *<i>stringname</i>,</b>
92
+ <b> const char **<i>stringptr</i>);</b>
93
+ <br>
94
+ <br>
95
+ <b>int pcre_get_stringnumber(const pcre *<i>code</i>,</b>
96
+ <b> const char *<i>name</i>);</b>
97
+ <br>
98
+ <br>
99
+ <b>int pcre_get_stringtable_entries(const pcre *<i>code</i>,</b>
100
+ <b> const char *<i>name</i>, char **<i>first</i>, char **<i>last</i>);</b>
101
+ <br>
102
+ <br>
103
+ <b>int pcre_get_substring(const char *<i>subject</i>, int *<i>ovector</i>,</b>
104
+ <b> int <i>stringcount</i>, int <i>stringnumber</i>,</b>
105
+ <b> const char **<i>stringptr</i>);</b>
106
+ <br>
107
+ <br>
108
+ <b>int pcre_get_substring_list(const char *<i>subject</i>,</b>
109
+ <b> int *<i>ovector</i>, int <i>stringcount</i>, const char ***<i>listptr</i>);</b>
110
+ <br>
111
+ <br>
112
+ <b>void pcre_free_substring(const char *<i>stringptr</i>);</b>
113
+ <br>
114
+ <br>
115
+ <b>void pcre_free_substring_list(const char **<i>stringptr</i>);</b>
116
+ </P>
117
+ <br><a name="SEC3" href="#TOC1">PCRE NATIVE API AUXILIARY FUNCTIONS</a><br>
118
+ <P>
119
+ <b>int pcre_jit_exec(const pcre *<i>code</i>, const pcre_extra *<i>extra</i>,</b>
120
+ <b> const char *<i>subject</i>, int <i>length</i>, int <i>startoffset</i>,</b>
121
+ <b> int <i>options</i>, int *<i>ovector</i>, int <i>ovecsize</i>,</b>
122
+ <b> pcre_jit_stack *<i>jstack</i>);</b>
123
+ <br>
124
+ <br>
125
+ <b>pcre_jit_stack *pcre_jit_stack_alloc(int <i>startsize</i>, int <i>maxsize</i>);</b>
126
+ <br>
127
+ <br>
128
+ <b>void pcre_jit_stack_free(pcre_jit_stack *<i>stack</i>);</b>
129
+ <br>
130
+ <br>
131
+ <b>void pcre_assign_jit_stack(pcre_extra *<i>extra</i>,</b>
132
+ <b> pcre_jit_callback <i>callback</i>, void *<i>data</i>);</b>
133
+ <br>
134
+ <br>
135
+ <b>const unsigned char *pcre_maketables(void);</b>
136
+ <br>
137
+ <br>
138
+ <b>int pcre_fullinfo(const pcre *<i>code</i>, const pcre_extra *<i>extra</i>,</b>
139
+ <b> int <i>what</i>, void *<i>where</i>);</b>
140
+ <br>
141
+ <br>
142
+ <b>int pcre_refcount(pcre *<i>code</i>, int <i>adjust</i>);</b>
143
+ <br>
144
+ <br>
145
+ <b>int pcre_config(int <i>what</i>, void *<i>where</i>);</b>
146
+ <br>
147
+ <br>
148
+ <b>const char *pcre_version(void);</b>
149
+ <br>
150
+ <br>
151
+ <b>int pcre_pattern_to_host_byte_order(pcre *<i>code</i>,</b>
152
+ <b> pcre_extra *<i>extra</i>, const unsigned char *<i>tables</i>);</b>
153
+ </P>
154
+ <br><a name="SEC4" href="#TOC1">PCRE NATIVE API INDIRECTED FUNCTIONS</a><br>
155
+ <P>
156
+ <b>void *(*pcre_malloc)(size_t);</b>
157
+ <br>
158
+ <br>
159
+ <b>void (*pcre_free)(void *);</b>
160
+ <br>
161
+ <br>
162
+ <b>void *(*pcre_stack_malloc)(size_t);</b>
163
+ <br>
164
+ <br>
165
+ <b>void (*pcre_stack_free)(void *);</b>
166
+ <br>
167
+ <br>
168
+ <b>int (*pcre_callout)(pcre_callout_block *);</b>
169
+ <br>
170
+ <br>
171
+ <b>int (*pcre_stack_guard)(void);</b>
172
+ </P>
173
+ <br><a name="SEC5" href="#TOC1">PCRE 8-BIT, 16-BIT, AND 32-BIT LIBRARIES</a><br>
174
+ <P>
175
+ As well as support for 8-bit character strings, PCRE also supports 16-bit
176
+ strings (from release 8.30) and 32-bit strings (from release 8.32), by means of
177
+ two additional libraries. They can be built as well as, or instead of, the
178
+ 8-bit library. To avoid too much complication, this document describes the
179
+ 8-bit versions of the functions, with only occasional references to the 16-bit
180
+ and 32-bit libraries.
181
+ </P>
182
+ <P>
183
+ The 16-bit and 32-bit functions operate in the same way as their 8-bit
184
+ counterparts; they just use different data types for their arguments and
185
+ results, and their names start with <b>pcre16_</b> or <b>pcre32_</b> instead of
186
+ <b>pcre_</b>. For every option that has UTF8 in its name (for example,
187
+ PCRE_UTF8), there are corresponding 16-bit and 32-bit names with UTF8 replaced
188
+ by UTF16 or UTF32, respectively. This facility is in fact just cosmetic; the
189
+ 16-bit and 32-bit option names define the same bit values.
190
+ </P>
191
+ <P>
192
+ References to bytes and UTF-8 in this document should be read as references to
193
+ 16-bit data units and UTF-16 when using the 16-bit library, or 32-bit data
194
+ units and UTF-32 when using the 32-bit library, unless specified otherwise.
195
+ More details of the specific differences for the 16-bit and 32-bit libraries
196
+ are given in the
197
+ <a href="pcre16.html"><b>pcre16</b></a>
198
+ and
199
+ <a href="pcre32.html"><b>pcre32</b></a>
200
+ pages.
201
+ </P>
202
+ <br><a name="SEC6" href="#TOC1">PCRE API OVERVIEW</a><br>
203
+ <P>
204
+ PCRE has its own native API, which is described in this document. There are
205
+ also some wrapper functions (for the 8-bit library only) that correspond to the
206
+ POSIX regular expression API, but they do not give access to all the
207
+ functionality. They are described in the
208
+ <a href="pcreposix.html"><b>pcreposix</b></a>
209
+ documentation. Both of these APIs define a set of C function calls. A C++
210
+ wrapper (again for the 8-bit library only) is also distributed with PCRE. It is
211
+ documented in the
212
+ <a href="pcrecpp.html"><b>pcrecpp</b></a>
213
+ page.
214
+ </P>
215
+ <P>
216
+ The native API C function prototypes are defined in the header file
217
+ <b>pcre.h</b>, and on Unix-like systems the (8-bit) library itself is called
218
+ <b>libpcre</b>. It can normally be accessed by adding <b>-lpcre</b> to the
219
+ command for linking an application that uses PCRE. The header file defines the
220
+ macros PCRE_MAJOR and PCRE_MINOR to contain the major and minor release numbers
221
+ for the library. Applications can use these to include support for different
222
+ releases of PCRE.
223
+ </P>
224
+ <P>
225
+ In a Windows environment, if you want to statically link an application program
226
+ against a non-dll <b>pcre.a</b> file, you must define PCRE_STATIC before
227
+ including <b>pcre.h</b> or <b>pcrecpp.h</b>, because otherwise the
228
+ <b>pcre_malloc()</b> and <b>pcre_free()</b> exported functions will be declared
229
+ <b>__declspec(dllimport)</b>, with unwanted results.
230
+ </P>
231
+ <P>
232
+ The functions <b>pcre_compile()</b>, <b>pcre_compile2()</b>, <b>pcre_study()</b>,
233
+ and <b>pcre_exec()</b> are used for compiling and matching regular expressions
234
+ in a Perl-compatible manner. A sample program that demonstrates the simplest
235
+ way of using them is provided in the file called <i>pcredemo.c</i> in the PCRE
236
+ source distribution. A listing of this program is given in the
237
+ <a href="pcredemo.html"><b>pcredemo</b></a>
238
+ documentation, and the
239
+ <a href="pcresample.html"><b>pcresample</b></a>
240
+ documentation describes how to compile and run it.
241
+ </P>
242
+ <P>
243
+ Just-in-time compiler support is an optional feature of PCRE that can be built
244
+ in appropriate hardware environments. It greatly speeds up the matching
245
+ performance of many patterns. Simple programs can easily request that it be
246
+ used if available, by setting an option that is ignored when it is not
247
+ relevant. More complicated programs might need to make use of the functions
248
+ <b>pcre_jit_stack_alloc()</b>, <b>pcre_jit_stack_free()</b>, and
249
+ <b>pcre_assign_jit_stack()</b> in order to control the JIT code's memory usage.
250
+ </P>
251
+ <P>
252
+ From release 8.32 there is also a direct interface for JIT execution, which
253
+ gives improved performance. The JIT-specific functions are discussed in the
254
+ <a href="pcrejit.html"><b>pcrejit</b></a>
255
+ documentation.
256
+ </P>
257
+ <P>
258
+ A second matching function, <b>pcre_dfa_exec()</b>, which is not
259
+ Perl-compatible, is also provided. This uses a different algorithm for the
260
+ matching. The alternative algorithm finds all possible matches (at a given
261
+ point in the subject), and scans the subject just once (unless there are
262
+ lookbehind assertions). However, this algorithm does not return captured
263
+ substrings. A description of the two matching algorithms and their advantages
264
+ and disadvantages is given in the
265
+ <a href="pcrematching.html"><b>pcrematching</b></a>
266
+ documentation.
267
+ </P>
268
+ <P>
269
+ In addition to the main compiling and matching functions, there are convenience
270
+ functions for extracting captured substrings from a subject string that is
271
+ matched by <b>pcre_exec()</b>. They are:
272
+ <pre>
273
+ <b>pcre_copy_substring()</b>
274
+ <b>pcre_copy_named_substring()</b>
275
+ <b>pcre_get_substring()</b>
276
+ <b>pcre_get_named_substring()</b>
277
+ <b>pcre_get_substring_list()</b>
278
+ <b>pcre_get_stringnumber()</b>
279
+ <b>pcre_get_stringtable_entries()</b>
280
+ </pre>
281
+ <b>pcre_free_substring()</b> and <b>pcre_free_substring_list()</b> are also
282
+ provided, to free the memory used for extracted strings.
283
+ </P>
284
+ <P>
285
+ The function <b>pcre_maketables()</b> is used to build a set of character tables
286
+ in the current locale for passing to <b>pcre_compile()</b>, <b>pcre_exec()</b>,
287
+ or <b>pcre_dfa_exec()</b>. This is an optional facility that is provided for
288
+ specialist use. Most commonly, no special tables are passed, in which case
289
+ internal tables that are generated when PCRE is built are used.
290
+ </P>
291
+ <P>
292
+ The function <b>pcre_fullinfo()</b> is used to find out information about a
293
+ compiled pattern. The function <b>pcre_version()</b> returns a pointer to a
294
+ string containing the version of PCRE and its date of release.
295
+ </P>
296
+ <P>
297
+ The function <b>pcre_refcount()</b> maintains a reference count in a data block
298
+ containing a compiled pattern. This is provided for the benefit of
299
+ object-oriented applications.
300
+ </P>
301
+ <P>
302
+ The global variables <b>pcre_malloc</b> and <b>pcre_free</b> initially contain
303
+ the entry points of the standard <b>malloc()</b> and <b>free()</b> functions,
304
+ respectively. PCRE calls the memory management functions via these variables,
305
+ so a calling program can replace them if it wishes to intercept the calls. This
306
+ should be done before calling any PCRE functions.
307
+ </P>
308
+ <P>
309
+ The global variables <b>pcre_stack_malloc</b> and <b>pcre_stack_free</b> are also
310
+ indirections to memory management functions. These special functions are used
311
+ only when PCRE is compiled to use the heap for remembering data, instead of
312
+ recursive function calls, when running the <b>pcre_exec()</b> function. See the
313
+ <a href="pcrebuild.html"><b>pcrebuild</b></a>
314
+ documentation for details of how to do this. It is a non-standard way of
315
+ building PCRE, for use in environments that have limited stacks. Because of the
316
+ greater use of memory management, it runs more slowly. Separate functions are
317
+ provided so that special-purpose external code can be used for this case. When
318
+ used, these functions are always called in a stack-like manner (last obtained,
319
+ first freed), and always for memory blocks of the same size. There is a
320
+ discussion about PCRE's stack usage in the
321
+ <a href="pcrestack.html"><b>pcrestack</b></a>
322
+ documentation.
323
+ </P>
324
+ <P>
325
+ The global variable <b>pcre_callout</b> initially contains NULL. It can be set
326
+ by the caller to a "callout" function, which PCRE will then call at specified
327
+ points during a matching operation. Details are given in the
328
+ <a href="pcrecallout.html"><b>pcrecallout</b></a>
329
+ documentation.
330
+ </P>
331
+ <P>
332
+ The global variable <b>pcre_stack_guard</b> initially contains NULL. It can be
333
+ set by the caller to a function that is called by PCRE whenever it starts
334
+ to compile a parenthesized part of a pattern. When parentheses are nested, PCRE
335
+ uses recursive function calls, which use up the system stack. This function is
336
+ provided so that applications with restricted stacks can force a compilation
337
+ error if the stack runs out. The function should return zero if all is well, or
338
+ non-zero to force an error.
339
+ <a name="newlines"></a></P>
340
+ <br><a name="SEC7" href="#TOC1">NEWLINES</a><br>
341
+ <P>
342
+ PCRE supports five different conventions for indicating line breaks in
343
+ strings: a single CR (carriage return) character, a single LF (linefeed)
344
+ character, the two-character sequence CRLF, any of the three preceding, or any
345
+ Unicode newline sequence. The Unicode newline sequences are the three just
346
+ mentioned, plus the single characters VT (vertical tab, U+000B), FF (form feed,
347
+ U+000C), NEL (next line, U+0085), LS (line separator, U+2028), and PS
348
+ (paragraph separator, U+2029).
349
+ </P>
350
+ <P>
351
+ Each of the first three conventions is used by at least one operating system as
352
+ its standard newline sequence. When PCRE is built, a default can be specified.
353
+ The default default is LF, which is the Unix standard. When PCRE is run, the
354
+ default can be overridden, either when a pattern is compiled, or when it is
355
+ matched.
356
+ </P>
357
+ <P>
358
+ At compile time, the newline convention can be specified by the <i>options</i>
359
+ argument of <b>pcre_compile()</b>, or it can be specified by special text at the
360
+ start of the pattern itself; this overrides any other settings. See the
361
+ <a href="pcrepattern.html"><b>pcrepattern</b></a>
362
+ page for details of the special character sequences.
363
+ </P>
364
+ <P>
365
+ In the PCRE documentation the word "newline" is used to mean "the character or
366
+ pair of characters that indicate a line break". The choice of newline
367
+ convention affects the handling of the dot, circumflex, and dollar
368
+ metacharacters, the handling of #-comments in /x mode, and, when CRLF is a
369
+ recognized line ending sequence, the match position advancement for a
370
+ non-anchored pattern. There is more detail about this in the
371
+ <a href="#execoptions">section on <b>pcre_exec()</b> options</a>
372
+ below.
373
+ </P>
374
+ <P>
375
+ The choice of newline convention does not affect the interpretation of
376
+ the \n or \r escape sequences, nor does it affect what \R matches, which is
377
+ controlled in a similar way, but by separate options.
378
+ </P>
379
+ <br><a name="SEC8" href="#TOC1">MULTITHREADING</a><br>
380
+ <P>
381
+ The PCRE functions can be used in multi-threading applications, with the
382
+ proviso that the memory management functions pointed to by <b>pcre_malloc</b>,
383
+ <b>pcre_free</b>, <b>pcre_stack_malloc</b>, and <b>pcre_stack_free</b>, and the
384
+ callout and stack-checking functions pointed to by <b>pcre_callout</b> and
385
+ <b>pcre_stack_guard</b>, are shared by all threads.
386
+ </P>
387
+ <P>
388
+ The compiled form of a regular expression is not altered during matching, so
389
+ the same compiled pattern can safely be used by several threads at once.
390
+ </P>
391
+ <P>
392
+ If the just-in-time optimization feature is being used, it needs separate
393
+ memory stack areas for each thread. See the
394
+ <a href="pcrejit.html"><b>pcrejit</b></a>
395
+ documentation for more details.
396
+ </P>
397
+ <br><a name="SEC9" href="#TOC1">SAVING PRECOMPILED PATTERNS FOR LATER USE</a><br>
398
+ <P>
399
+ The compiled form of a regular expression can be saved and re-used at a later
400
+ time, possibly by a different program, and even on a host other than the one on
401
+ which it was compiled. Details are given in the
402
+ <a href="pcreprecompile.html"><b>pcreprecompile</b></a>
403
+ documentation, which includes a description of the
404
+ <b>pcre_pattern_to_host_byte_order()</b> function. However, compiling a regular
405
+ expression with one version of PCRE for use with a different version is not
406
+ guaranteed to work and may cause crashes.
407
+ </P>
408
+ <br><a name="SEC10" href="#TOC1">CHECKING BUILD-TIME OPTIONS</a><br>
409
+ <P>
410
+ <b>int pcre_config(int <i>what</i>, void *<i>where</i>);</b>
411
+ </P>
412
+ <P>
413
+ The function <b>pcre_config()</b> makes it possible for a PCRE client to
414
+ discover which optional features have been compiled into the PCRE library. The
415
+ <a href="pcrebuild.html"><b>pcrebuild</b></a>
416
+ documentation has more details about these optional features.
417
+ </P>
418
+ <P>
419
+ The first argument for <b>pcre_config()</b> is an integer, specifying which
420
+ information is required; the second argument is a pointer to a variable into
421
+ which the information is placed. The returned value is zero on success, or the
422
+ negative error code PCRE_ERROR_BADOPTION if the value in the first argument is
423
+ not recognized. The following information is available:
424
+ <pre>
425
+ PCRE_CONFIG_UTF8
426
+ </pre>
427
+ The output is an integer that is set to one if UTF-8 support is available;
428
+ otherwise it is set to zero. This value should normally be given to the 8-bit
429
+ version of this function, <b>pcre_config()</b>. If it is given to the 16-bit
430
+ or 32-bit version of this function, the result is PCRE_ERROR_BADOPTION.
431
+ <pre>
432
+ PCRE_CONFIG_UTF16
433
+ </pre>
434
+ The output is an integer that is set to one if UTF-16 support is available;
435
+ otherwise it is set to zero. This value should normally be given to the 16-bit
436
+ version of this function, <b>pcre16_config()</b>. If it is given to the 8-bit
437
+ or 32-bit version of this function, the result is PCRE_ERROR_BADOPTION.
438
+ <pre>
439
+ PCRE_CONFIG_UTF32
440
+ </pre>
441
+ The output is an integer that is set to one if UTF-32 support is available;
442
+ otherwise it is set to zero. This value should normally be given to the 32-bit
443
+ version of this function, <b>pcre32_config()</b>. If it is given to the 8-bit
444
+ or 16-bit version of this function, the result is PCRE_ERROR_BADOPTION.
445
+ <pre>
446
+ PCRE_CONFIG_UNICODE_PROPERTIES
447
+ </pre>
448
+ The output is an integer that is set to one if support for Unicode character
449
+ properties is available; otherwise it is set to zero.
450
+ <pre>
451
+ PCRE_CONFIG_JIT
452
+ </pre>
453
+ The output is an integer that is set to one if support for just-in-time
454
+ compiling is available; otherwise it is set to zero.
455
+ <pre>
456
+ PCRE_CONFIG_JITTARGET
457
+ </pre>
458
+ The output is a pointer to a zero-terminated "const char *" string. If JIT
459
+ support is available, the string contains the name of the architecture for
460
+ which the JIT compiler is configured, for example "x86 32bit (little endian +
461
+ unaligned)". If JIT support is not available, the result is NULL.
462
+ <pre>
463
+ PCRE_CONFIG_NEWLINE
464
+ </pre>
465
+ The output is an integer whose value specifies the default character sequence
466
+ that is recognized as meaning "newline". The values that are supported in
467
+ ASCII/Unicode environments are: 10 for LF, 13 for CR, 3338 for CRLF, -2 for
468
+ ANYCRLF, and -1 for ANY. In EBCDIC environments, CR, ANYCRLF, and ANY yield the
469
+ same values. However, the value for LF is normally 21, though some EBCDIC
470
+ environments use 37. The corresponding values for CRLF are 3349 and 3365. The
471
+ default should normally correspond to the standard sequence for your operating
472
+ system.
473
+ <pre>
474
+ PCRE_CONFIG_BSR
475
+ </pre>
476
+ The output is an integer whose value indicates what character sequences the \R
477
+ escape sequence matches by default. A value of 0 means that \R matches any
478
+ Unicode line ending sequence; a value of 1 means that \R matches only CR, LF,
479
+ or CRLF. The default can be overridden when a pattern is compiled or matched.
480
+ <pre>
481
+ PCRE_CONFIG_LINK_SIZE
482
+ </pre>
483
+ The output is an integer that contains the number of bytes used for internal
484
+ linkage in compiled regular expressions. For the 8-bit library, the value can
485
+ be 2, 3, or 4. For the 16-bit library, the value is either 2 or 4 and is still
486
+ a number of bytes. For the 32-bit library, the value is either 2 or 4 and is
487
+ still a number of bytes. The default value of 2 is sufficient for all but the
488
+ most massive patterns, since it allows the compiled pattern to be up to 64K in
489
+ size. Larger values allow larger regular expressions to be compiled, at the
490
+ expense of slower matching.
491
+ <pre>
492
+ PCRE_CONFIG_POSIX_MALLOC_THRESHOLD
493
+ </pre>
494
+ The output is an integer that contains the threshold above which the POSIX
495
+ interface uses <b>malloc()</b> for output vectors. Further details are given in
496
+ the
497
+ <a href="pcreposix.html"><b>pcreposix</b></a>
498
+ documentation.
499
+ <pre>
500
+ PCRE_CONFIG_PARENS_LIMIT
501
+ </pre>
502
+ The output is a long integer that gives the maximum depth of nesting of
503
+ parentheses (of any kind) in a pattern. This limit is imposed to cap the amount
504
+ of system stack used when a pattern is compiled. It is specified when PCRE is
505
+ built; the default is 250. This limit does not take into account the stack that
506
+ may already be used by the calling application. For finer control over
507
+ compilation stack usage, you can set a pointer to an external checking function
508
+ in <b>pcre_stack_guard</b>.
509
+ <pre>
510
+ PCRE_CONFIG_MATCH_LIMIT
511
+ </pre>
512
+ The output is a long integer that gives the default limit for the number of
513
+ internal matching function calls in a <b>pcre_exec()</b> execution. Further
514
+ details are given with <b>pcre_exec()</b> below.
515
+ <pre>
516
+ PCRE_CONFIG_MATCH_LIMIT_RECURSION
517
+ </pre>
518
+ The output is a long integer that gives the default limit for the depth of
519
+ recursion when calling the internal matching function in a <b>pcre_exec()</b>
520
+ execution. Further details are given with <b>pcre_exec()</b> below.
521
+ <pre>
522
+ PCRE_CONFIG_STACKRECURSE
523
+ </pre>
524
+ The output is an integer that is set to one if internal recursion when running
525
+ <b>pcre_exec()</b> is implemented by recursive function calls that use the stack
526
+ to remember their state. This is the usual way that PCRE is compiled. The
527
+ output is zero if PCRE was compiled to use blocks of data on the heap instead
528
+ of recursive function calls. In this case, <b>pcre_stack_malloc</b> and
529
+ <b>pcre_stack_free</b> are called to manage memory blocks on the heap, thus
530
+ avoiding the use of the stack.
531
+ </P>
532
+ <br><a name="SEC11" href="#TOC1">COMPILING A PATTERN</a><br>
533
+ <P>
534
+ <b>pcre *pcre_compile(const char *<i>pattern</i>, int <i>options</i>,</b>
535
+ <b> const char **<i>errptr</i>, int *<i>erroffset</i>,</b>
536
+ <b> const unsigned char *<i>tableptr</i>);</b>
537
+ <br>
538
+ <br>
539
+ <b>pcre *pcre_compile2(const char *<i>pattern</i>, int <i>options</i>,</b>
540
+ <b> int *<i>errorcodeptr</i>,</b>
541
+ <b> const char **<i>errptr</i>, int *<i>erroffset</i>,</b>
542
+ <b> const unsigned char *<i>tableptr</i>);</b>
543
+ </P>
544
+ <P>
545
+ Either of the functions <b>pcre_compile()</b> or <b>pcre_compile2()</b> can be
546
+ called to compile a pattern into an internal form. The only difference between
547
+ the two interfaces is that <b>pcre_compile2()</b> has an additional argument,
548
+ <i>errorcodeptr</i>, via which a numerical error code can be returned. To avoid
549
+ too much repetition, we refer just to <b>pcre_compile()</b> below, but the
550
+ information applies equally to <b>pcre_compile2()</b>.
551
+ </P>
552
+ <P>
553
+ The pattern is a C string terminated by a binary zero, and is passed in the
554
+ <i>pattern</i> argument. A pointer to a single block of memory that is obtained
555
+ via <b>pcre_malloc</b> is returned. This contains the compiled code and related
556
+ data. The <b>pcre</b> type is defined for the returned block; this is a typedef
557
+ for a structure whose contents are not externally defined. It is up to the
558
+ caller to free the memory (via <b>pcre_free</b>) when it is no longer required.
559
+ </P>
560
+ <P>
561
+ Although the compiled code of a PCRE regex is relocatable, that is, it does not
562
+ depend on memory location, the complete <b>pcre</b> data block is not
563
+ fully relocatable, because it may contain a copy of the <i>tableptr</i>
564
+ argument, which is an address (see below).
565
+ </P>
566
+ <P>
567
+ The <i>options</i> argument contains various bit settings that affect the
568
+ compilation. It should be zero if no options are required. The available
569
+ options are described below. Some of them (in particular, those that are
570
+ compatible with Perl, but some others as well) can also be set and unset from
571
+ within the pattern (see the detailed description in the
572
+ <a href="pcrepattern.html"><b>pcrepattern</b></a>
573
+ documentation). For those options that can be different in different parts of
574
+ the pattern, the contents of the <i>options</i> argument specifies their
575
+ settings at the start of compilation and execution. The PCRE_ANCHORED,
576
+ PCRE_BSR_<i>xxx</i>, PCRE_NEWLINE_<i>xxx</i>, PCRE_NO_UTF8_CHECK, and
577
+ PCRE_NO_START_OPTIMIZE options can be set at the time of matching as well as at
578
+ compile time.
579
+ </P>
580
+ <P>
581
+ If <i>errptr</i> is NULL, <b>pcre_compile()</b> returns NULL immediately.
582
+ Otherwise, if compilation of a pattern fails, <b>pcre_compile()</b> returns
583
+ NULL, and sets the variable pointed to by <i>errptr</i> to point to a textual
584
+ error message. This is a static string that is part of the library. You must
585
+ not try to free it. Normally, the offset from the start of the pattern to the
586
+ data unit that was being processed when the error was discovered is placed in
587
+ the variable pointed to by <i>erroffset</i>, which must not be NULL (if it is,
588
+ an immediate error is given). However, for an invalid UTF-8 or UTF-16 string,
589
+ the offset is that of the first data unit of the failing character.
590
+ </P>
591
+ <P>
592
+ Some errors are not detected until the whole pattern has been scanned; in these
593
+ cases, the offset passed back is the length of the pattern. Note that the
594
+ offset is in data units, not characters, even in a UTF mode. It may sometimes
595
+ point into the middle of a UTF-8 or UTF-16 character.
596
+ </P>
597
+ <P>
598
+ If <b>pcre_compile2()</b> is used instead of <b>pcre_compile()</b>, and the
599
+ <i>errorcodeptr</i> argument is not NULL, a non-zero error code number is
600
+ returned via this argument in the event of an error. This is in addition to the
601
+ textual error message. Error codes and messages are listed below.
602
+ </P>
603
+ <P>
604
+ If the final argument, <i>tableptr</i>, is NULL, PCRE uses a default set of
605
+ character tables that are built when PCRE is compiled, using the default C
606
+ locale. Otherwise, <i>tableptr</i> must be an address that is the result of a
607
+ call to <b>pcre_maketables()</b>. This value is stored with the compiled
608
+ pattern, and used again by <b>pcre_exec()</b> and <b>pcre_dfa_exec()</b> when the
609
+ pattern is matched. For more discussion, see the section on locale support
610
+ below.
611
+ </P>
612
+ <P>
613
+ This code fragment shows a typical straightforward call to <b>pcre_compile()</b>:
614
+ <pre>
615
+ pcre *re;
616
+ const char *error;
617
+ int erroffset;
618
+ re = pcre_compile(
619
+ "^A.*Z", /* the pattern */
620
+ 0, /* default options */
621
+ &error, /* for error message */
622
+ &erroffset, /* for error offset */
623
+ NULL); /* use default character tables */
624
+ </pre>
625
+ The following names for option bits are defined in the <b>pcre.h</b> header
626
+ file:
627
+ <pre>
628
+ PCRE_ANCHORED
629
+ </pre>
630
+ If this bit is set, the pattern is forced to be "anchored", that is, it is
631
+ constrained to match only at the first matching point in the string that is
632
+ being searched (the "subject string"). This effect can also be achieved by
633
+ appropriate constructs in the pattern itself, which is the only way to do it in
634
+ Perl.
635
+ <pre>
636
+ PCRE_AUTO_CALLOUT
637
+ </pre>
638
+ If this bit is set, <b>pcre_compile()</b> automatically inserts callout items,
639
+ all with number 255, before each pattern item. For discussion of the callout
640
+ facility, see the
641
+ <a href="pcrecallout.html"><b>pcrecallout</b></a>
642
+ documentation.
643
+ <pre>
644
+ PCRE_BSR_ANYCRLF
645
+ PCRE_BSR_UNICODE
646
+ </pre>
647
+ These options (which are mutually exclusive) control what the \R escape
648
+ sequence matches. The choice is either to match only CR, LF, or CRLF, or to
649
+ match any Unicode newline sequence. The default is specified when PCRE is
650
+ built. It can be overridden from within the pattern, or by setting an option
651
+ when a compiled pattern is matched.
652
+ <pre>
653
+ PCRE_CASELESS
654
+ </pre>
655
+ If this bit is set, letters in the pattern match both upper and lower case
656
+ letters. It is equivalent to Perl's /i option, and it can be changed within a
657
+ pattern by a (?i) option setting. In UTF-8 mode, PCRE always understands the
658
+ concept of case for characters whose values are less than 128, so caseless
659
+ matching is always possible. For characters with higher values, the concept of
660
+ case is supported if PCRE is compiled with Unicode property support, but not
661
+ otherwise. If you want to use caseless matching for characters 128 and above,
662
+ you must ensure that PCRE is compiled with Unicode property support as well as
663
+ with UTF-8 support.
664
+ <pre>
665
+ PCRE_DOLLAR_ENDONLY
666
+ </pre>
667
+ If this bit is set, a dollar metacharacter in the pattern matches only at the
668
+ end of the subject string. Without this option, a dollar also matches
669
+ immediately before a newline at the end of the string (but not before any other
670
+ newlines). The PCRE_DOLLAR_ENDONLY option is ignored if PCRE_MULTILINE is set.
671
+ There is no equivalent to this option in Perl, and no way to set it within a
672
+ pattern.
673
+ <pre>
674
+ PCRE_DOTALL
675
+ </pre>
676
+ If this bit is set, a dot metacharacter in the pattern matches a character of
677
+ any value, including one that indicates a newline. However, it only ever
678
+ matches one character, even if newlines are coded as CRLF. Without this option,
679
+ a dot does not match when the current position is at a newline. This option is
680
+ equivalent to Perl's /s option, and it can be changed within a pattern by a
681
+ (?s) option setting. A negative class such as [^a] always matches newline
682
+ characters, independent of the setting of this option.
683
+ <pre>
684
+ PCRE_DUPNAMES
685
+ </pre>
686
+ If this bit is set, names used to identify capturing subpatterns need not be
687
+ unique. This can be helpful for certain types of pattern when it is known that
688
+ only one instance of the named subpattern can ever be matched. There are more
689
+ details of named subpatterns below; see also the
690
+ <a href="pcrepattern.html"><b>pcrepattern</b></a>
691
+ documentation.
692
+ <pre>
693
+ PCRE_EXTENDED
694
+ </pre>
695
+ If this bit is set, most white space characters in the pattern are totally
696
+ ignored except when escaped or inside a character class. However, white space
697
+ is not allowed within sequences such as (?&#62; that introduce various
698
+ parenthesized subpatterns, nor within a numerical quantifier such as {1,3}.
699
+ However, ignorable white space is permitted between an item and a following
700
+ quantifier and between a quantifier and a following + that indicates
701
+ possessiveness.
702
+ </P>
703
+ <P>
704
+ White space did not used to include the VT character (code 11), because Perl
705
+ did not treat this character as white space. However, Perl changed at release
706
+ 5.18, so PCRE followed at release 8.34, and VT is now treated as white space.
707
+ </P>
708
+ <P>
709
+ PCRE_EXTENDED also causes characters between an unescaped # outside a character
710
+ class and the next newline, inclusive, to be ignored. PCRE_EXTENDED is
711
+ equivalent to Perl's /x option, and it can be changed within a pattern by a
712
+ (?x) option setting.
713
+ </P>
714
+ <P>
715
+ Which characters are interpreted as newlines is controlled by the options
716
+ passed to <b>pcre_compile()</b> or by a special sequence at the start of the
717
+ pattern, as described in the section entitled
718
+ <a href="pcrepattern.html#newlines">"Newline conventions"</a>
719
+ in the <b>pcrepattern</b> documentation. Note that the end of this type of
720
+ comment is a literal newline sequence in the pattern; escape sequences that
721
+ happen to represent a newline do not count.
722
+ </P>
723
+ <P>
724
+ This option makes it possible to include comments inside complicated patterns.
725
+ Note, however, that this applies only to data characters. White space characters
726
+ may never appear within special character sequences in a pattern, for example
727
+ within the sequence (?( that introduces a conditional subpattern.
728
+ <pre>
729
+ PCRE_EXTRA
730
+ </pre>
731
+ This option was invented in order to turn on additional functionality of PCRE
732
+ that is incompatible with Perl, but it is currently of very little use. When
733
+ set, any backslash in a pattern that is followed by a letter that has no
734
+ special meaning causes an error, thus reserving these combinations for future
735
+ expansion. By default, as in Perl, a backslash followed by a letter with no
736
+ special meaning is treated as a literal. (Perl can, however, be persuaded to
737
+ give an error for this, by running it with the -w option.) There are at present
738
+ no other features controlled by this option. It can also be set by a (?X)
739
+ option setting within a pattern.
740
+ <pre>
741
+ PCRE_FIRSTLINE
742
+ </pre>
743
+ If this option is set, an unanchored pattern is required to match before or at
744
+ the first newline in the subject string, though the matched text may continue
745
+ over the newline.
746
+ <pre>
747
+ PCRE_JAVASCRIPT_COMPAT
748
+ </pre>
749
+ If this option is set, PCRE's behaviour is changed in some ways so that it is
750
+ compatible with JavaScript rather than Perl. The changes are as follows:
751
+ </P>
752
+ <P>
753
+ (1) A lone closing square bracket in a pattern causes a compile-time error,
754
+ because this is illegal in JavaScript (by default it is treated as a data
755
+ character). Thus, the pattern AB]CD becomes illegal when this option is set.
756
+ </P>
757
+ <P>
758
+ (2) At run time, a back reference to an unset subpattern group matches an empty
759
+ string (by default this causes the current matching alternative to fail). A
760
+ pattern such as (\1)(a) succeeds when this option is set (assuming it can find
761
+ an "a" in the subject), whereas it fails by default, for Perl compatibility.
762
+ </P>
763
+ <P>
764
+ (3) \U matches an upper case "U" character; by default \U causes a compile
765
+ time error (Perl uses \U to upper case subsequent characters).
766
+ </P>
767
+ <P>
768
+ (4) \u matches a lower case "u" character unless it is followed by four
769
+ hexadecimal digits, in which case the hexadecimal number defines the code point
770
+ to match. By default, \u causes a compile time error (Perl uses it to upper
771
+ case the following character).
772
+ </P>
773
+ <P>
774
+ (5) \x matches a lower case "x" character unless it is followed by two
775
+ hexadecimal digits, in which case the hexadecimal number defines the code point
776
+ to match. By default, as in Perl, a hexadecimal number is always expected after
777
+ \x, but it may have zero, one, or two digits (so, for example, \xz matches a
778
+ binary zero character followed by z).
779
+ <pre>
780
+ PCRE_MULTILINE
781
+ </pre>
782
+ By default, for the purposes of matching "start of line" and "end of line",
783
+ PCRE treats the subject string as consisting of a single line of characters,
784
+ even if it actually contains newlines. The "start of line" metacharacter (^)
785
+ matches only at the start of the string, and the "end of line" metacharacter
786
+ ($) matches only at the end of the string, or before a terminating newline
787
+ (except when PCRE_DOLLAR_ENDONLY is set). Note, however, that unless
788
+ PCRE_DOTALL is set, the "any character" metacharacter (.) does not match at a
789
+ newline. This behaviour (for ^, $, and dot) is the same as Perl.
790
+ </P>
791
+ <P>
792
+ When PCRE_MULTILINE it is set, the "start of line" and "end of line" constructs
793
+ match immediately following or immediately before internal newlines in the
794
+ subject string, respectively, as well as at the very start and end. This is
795
+ equivalent to Perl's /m option, and it can be changed within a pattern by a
796
+ (?m) option setting. If there are no newlines in a subject string, or no
797
+ occurrences of ^ or $ in a pattern, setting PCRE_MULTILINE has no effect.
798
+ <pre>
799
+ PCRE_NEVER_UTF
800
+ </pre>
801
+ This option locks out interpretation of the pattern as UTF-8 (or UTF-16 or
802
+ UTF-32 in the 16-bit and 32-bit libraries). In particular, it prevents the
803
+ creator of the pattern from switching to UTF interpretation by starting the
804
+ pattern with (*UTF). This may be useful in applications that process patterns
805
+ from external sources. The combination of PCRE_UTF8 and PCRE_NEVER_UTF also
806
+ causes an error.
807
+ <pre>
808
+ PCRE_NEWLINE_CR
809
+ PCRE_NEWLINE_LF
810
+ PCRE_NEWLINE_CRLF
811
+ PCRE_NEWLINE_ANYCRLF
812
+ PCRE_NEWLINE_ANY
813
+ </pre>
814
+ These options override the default newline definition that was chosen when PCRE
815
+ was built. Setting the first or the second specifies that a newline is
816
+ indicated by a single character (CR or LF, respectively). Setting
817
+ PCRE_NEWLINE_CRLF specifies that a newline is indicated by the two-character
818
+ CRLF sequence. Setting PCRE_NEWLINE_ANYCRLF specifies that any of the three
819
+ preceding sequences should be recognized. Setting PCRE_NEWLINE_ANY specifies
820
+ that any Unicode newline sequence should be recognized.
821
+ </P>
822
+ <P>
823
+ In an ASCII/Unicode environment, the Unicode newline sequences are the three
824
+ just mentioned, plus the single characters VT (vertical tab, U+000B), FF (form
825
+ feed, U+000C), NEL (next line, U+0085), LS (line separator, U+2028), and PS
826
+ (paragraph separator, U+2029). For the 8-bit library, the last two are
827
+ recognized only in UTF-8 mode.
828
+ </P>
829
+ <P>
830
+ When PCRE is compiled to run in an EBCDIC (mainframe) environment, the code for
831
+ CR is 0x0d, the same as ASCII. However, the character code for LF is normally
832
+ 0x15, though in some EBCDIC environments 0x25 is used. Whichever of these is
833
+ not LF is made to correspond to Unicode's NEL character. EBCDIC codes are all
834
+ less than 256. For more details, see the
835
+ <a href="pcrebuild.html"><b>pcrebuild</b></a>
836
+ documentation.
837
+ </P>
838
+ <P>
839
+ The newline setting in the options word uses three bits that are treated
840
+ as a number, giving eight possibilities. Currently only six are used (default
841
+ plus the five values above). This means that if you set more than one newline
842
+ option, the combination may or may not be sensible. For example,
843
+ PCRE_NEWLINE_CR with PCRE_NEWLINE_LF is equivalent to PCRE_NEWLINE_CRLF, but
844
+ other combinations may yield unused numbers and cause an error.
845
+ </P>
846
+ <P>
847
+ The only time that a line break in a pattern is specially recognized when
848
+ compiling is when PCRE_EXTENDED is set. CR and LF are white space characters,
849
+ and so are ignored in this mode. Also, an unescaped # outside a character class
850
+ indicates a comment that lasts until after the next line break sequence. In
851
+ other circumstances, line break sequences in patterns are treated as literal
852
+ data.
853
+ </P>
854
+ <P>
855
+ The newline option that is set at compile time becomes the default that is used
856
+ for <b>pcre_exec()</b> and <b>pcre_dfa_exec()</b>, but it can be overridden.
857
+ <pre>
858
+ PCRE_NO_AUTO_CAPTURE
859
+ </pre>
860
+ If this option is set, it disables the use of numbered capturing parentheses in
861
+ the pattern. Any opening parenthesis that is not followed by ? behaves as if it
862
+ were followed by ?: but named parentheses can still be used for capturing (and
863
+ they acquire numbers in the usual way). There is no equivalent of this option
864
+ in Perl.
865
+ <pre>
866
+ PCRE_NO_AUTO_POSSESS
867
+ </pre>
868
+ If this option is set, it disables "auto-possessification". This is an
869
+ optimization that, for example, turns a+b into a++b in order to avoid
870
+ backtracks into a+ that can never be successful. However, if callouts are in
871
+ use, auto-possessification means that some of them are never taken. You can set
872
+ this option if you want the matching functions to do a full unoptimized search
873
+ and run all the callouts, but it is mainly provided for testing purposes.
874
+ <pre>
875
+ PCRE_NO_START_OPTIMIZE
876
+ </pre>
877
+ This is an option that acts at matching time; that is, it is really an option
878
+ for <b>pcre_exec()</b> or <b>pcre_dfa_exec()</b>. If it is set at compile time,
879
+ it is remembered with the compiled pattern and assumed at matching time. This
880
+ is necessary if you want to use JIT execution, because the JIT compiler needs
881
+ to know whether or not this option is set. For details see the discussion of
882
+ PCRE_NO_START_OPTIMIZE
883
+ <a href="#execoptions">below.</a>
884
+ <pre>
885
+ PCRE_UCP
886
+ </pre>
887
+ This option changes the way PCRE processes \B, \b, \D, \d, \S, \s, \W,
888
+ \w, and some of the POSIX character classes. By default, only ASCII characters
889
+ are recognized, but if PCRE_UCP is set, Unicode properties are used instead to
890
+ classify characters. More details are given in the section on
891
+ <a href="pcre.html#genericchartypes">generic character types</a>
892
+ in the
893
+ <a href="pcrepattern.html"><b>pcrepattern</b></a>
894
+ page. If you set PCRE_UCP, matching one of the items it affects takes much
895
+ longer. The option is available only if PCRE has been compiled with Unicode
896
+ property support.
897
+ <pre>
898
+ PCRE_UNGREEDY
899
+ </pre>
900
+ This option inverts the "greediness" of the quantifiers so that they are not
901
+ greedy by default, but become greedy if followed by "?". It is not compatible
902
+ with Perl. It can also be set by a (?U) option setting within the pattern.
903
+ <pre>
904
+ PCRE_UTF8
905
+ </pre>
906
+ This option causes PCRE to regard both the pattern and the subject as strings
907
+ of UTF-8 characters instead of single-byte strings. However, it is available
908
+ only when PCRE is built to include UTF support. If not, the use of this option
909
+ provokes an error. Details of how this option changes the behaviour of PCRE are
910
+ given in the
911
+ <a href="pcreunicode.html"><b>pcreunicode</b></a>
912
+ page.
913
+ <pre>
914
+ PCRE_NO_UTF8_CHECK
915
+ </pre>
916
+ When PCRE_UTF8 is set, the validity of the pattern as a UTF-8 string is
917
+ automatically checked. There is a discussion about the
918
+ <a href="pcreunicode.html#utf8strings">validity of UTF-8 strings</a>
919
+ in the
920
+ <a href="pcreunicode.html"><b>pcreunicode</b></a>
921
+ page. If an invalid UTF-8 sequence is found, <b>pcre_compile()</b> returns an
922
+ error. If you already know that your pattern is valid, and you want to skip
923
+ this check for performance reasons, you can set the PCRE_NO_UTF8_CHECK option.
924
+ When it is set, the effect of passing an invalid UTF-8 string as a pattern is
925
+ undefined. It may cause your program to crash or loop. Note that this option
926
+ can also be passed to <b>pcre_exec()</b> and <b>pcre_dfa_exec()</b>, to suppress
927
+ the validity checking of subject strings only. If the same string is being
928
+ matched many times, the option can be safely set for the second and subsequent
929
+ matchings to improve performance.
930
+ </P>
931
+ <br><a name="SEC12" href="#TOC1">COMPILATION ERROR CODES</a><br>
932
+ <P>
933
+ The following table lists the error codes than may be returned by
934
+ <b>pcre_compile2()</b>, along with the error messages that may be returned by
935
+ both compiling functions. Note that error messages are always 8-bit ASCII
936
+ strings, even in 16-bit or 32-bit mode. As PCRE has developed, some error codes
937
+ have fallen out of use. To avoid confusion, they have not been re-used.
938
+ <pre>
939
+ 0 no error
940
+ 1 \ at end of pattern
941
+ 2 \c at end of pattern
942
+ 3 unrecognized character follows \
943
+ 4 numbers out of order in {} quantifier
944
+ 5 number too big in {} quantifier
945
+ 6 missing terminating ] for character class
946
+ 7 invalid escape sequence in character class
947
+ 8 range out of order in character class
948
+ 9 nothing to repeat
949
+ 10 [this code is not in use]
950
+ 11 internal error: unexpected repeat
951
+ 12 unrecognized character after (? or (?-
952
+ 13 POSIX named classes are supported only within a class
953
+ 14 missing )
954
+ 15 reference to non-existent subpattern
955
+ 16 erroffset passed as NULL
956
+ 17 unknown option bit(s) set
957
+ 18 missing ) after comment
958
+ 19 [this code is not in use]
959
+ 20 regular expression is too large
960
+ 21 failed to get memory
961
+ 22 unmatched parentheses
962
+ 23 internal error: code overflow
963
+ 24 unrecognized character after (?&#60;
964
+ 25 lookbehind assertion is not fixed length
965
+ 26 malformed number or name after (?(
966
+ 27 conditional group contains more than two branches
967
+ 28 assertion expected after (?(
968
+ 29 (?R or (?[+-]digits must be followed by )
969
+ 30 unknown POSIX class name
970
+ 31 POSIX collating elements are not supported
971
+ 32 this version of PCRE is compiled without UTF support
972
+ 33 [this code is not in use]
973
+ 34 character value in \x{} or \o{} is too large
974
+ 35 invalid condition (?(0)
975
+ 36 \C not allowed in lookbehind assertion
976
+ 37 PCRE does not support \L, \l, \N{name}, \U, or \u
977
+ 38 number after (?C is &#62; 255
978
+ 39 closing ) for (?C expected
979
+ 40 recursive call could loop indefinitely
980
+ 41 unrecognized character after (?P
981
+ 42 syntax error in subpattern name (missing terminator)
982
+ 43 two named subpatterns have the same name
983
+ 44 invalid UTF-8 string (specifically UTF-8)
984
+ 45 support for \P, \p, and \X has not been compiled
985
+ 46 malformed \P or \p sequence
986
+ 47 unknown property name after \P or \p
987
+ 48 subpattern name is too long (maximum 32 characters)
988
+ 49 too many named subpatterns (maximum 10000)
989
+ 50 [this code is not in use]
990
+ 51 octal value is greater than \377 in 8-bit non-UTF-8 mode
991
+ 52 internal error: overran compiling workspace
992
+ 53 internal error: previously-checked referenced subpattern
993
+ not found
994
+ 54 DEFINE group contains more than one branch
995
+ 55 repeating a DEFINE group is not allowed
996
+ 56 inconsistent NEWLINE options
997
+ 57 \g is not followed by a braced, angle-bracketed, or quoted
998
+ name/number or by a plain number
999
+ 58 a numbered reference must not be zero
1000
+ 59 an argument is not allowed for (*ACCEPT), (*FAIL), or (*COMMIT)
1001
+ 60 (*VERB) not recognized or malformed
1002
+ 61 number is too big
1003
+ 62 subpattern name expected
1004
+ 63 digit expected after (?+
1005
+ 64 ] is an invalid data character in JavaScript compatibility mode
1006
+ 65 different names for subpatterns of the same number are
1007
+ not allowed
1008
+ 66 (*MARK) must have an argument
1009
+ 67 this version of PCRE is not compiled with Unicode property
1010
+ support
1011
+ 68 \c must be followed by an ASCII character
1012
+ 69 \k is not followed by a braced, angle-bracketed, or quoted name
1013
+ 70 internal error: unknown opcode in find_fixedlength()
1014
+ 71 \N is not supported in a class
1015
+ 72 too many forward references
1016
+ 73 disallowed Unicode code point (&#62;= 0xd800 && &#60;= 0xdfff)
1017
+ 74 invalid UTF-16 string (specifically UTF-16)
1018
+ 75 name is too long in (*MARK), (*PRUNE), (*SKIP), or (*THEN)
1019
+ 76 character value in \u.... sequence is too large
1020
+ 77 invalid UTF-32 string (specifically UTF-32)
1021
+ 78 setting UTF is disabled by the application
1022
+ 79 non-hex character in \x{} (closing brace missing?)
1023
+ 80 non-octal character in \o{} (closing brace missing?)
1024
+ 81 missing opening brace after \o
1025
+ 82 parentheses are too deeply nested
1026
+ 83 invalid range in character class
1027
+ 84 group name must start with a non-digit
1028
+ 85 parentheses are too deeply nested (stack check)
1029
+ </pre>
1030
+ The numbers 32 and 10000 in errors 48 and 49 are defaults; different values may
1031
+ be used if the limits were changed when PCRE was built.
1032
+ <a name="studyingapattern"></a></P>
1033
+ <br><a name="SEC13" href="#TOC1">STUDYING A PATTERN</a><br>
1034
+ <P>
1035
+ <b>pcre_extra *pcre_study(const pcre *<i>code</i>, int <i>options</i>,</b>
1036
+ <b> const char **<i>errptr</i>);</b>
1037
+ </P>
1038
+ <P>
1039
+ If a compiled pattern is going to be used several times, it is worth spending
1040
+ more time analyzing it in order to speed up the time taken for matching. The
1041
+ function <b>pcre_study()</b> takes a pointer to a compiled pattern as its first
1042
+ argument. If studying the pattern produces additional information that will
1043
+ help speed up matching, <b>pcre_study()</b> returns a pointer to a
1044
+ <b>pcre_extra</b> block, in which the <i>study_data</i> field points to the
1045
+ results of the study.
1046
+ </P>
1047
+ <P>
1048
+ The returned value from <b>pcre_study()</b> can be passed directly to
1049
+ <b>pcre_exec()</b> or <b>pcre_dfa_exec()</b>. However, a <b>pcre_extra</b> block
1050
+ also contains other fields that can be set by the caller before the block is
1051
+ passed; these are described
1052
+ <a href="#extradata">below</a>
1053
+ in the section on matching a pattern.
1054
+ </P>
1055
+ <P>
1056
+ If studying the pattern does not produce any useful information,
1057
+ <b>pcre_study()</b> returns NULL by default. In that circumstance, if the
1058
+ calling program wants to pass any of the other fields to <b>pcre_exec()</b> or
1059
+ <b>pcre_dfa_exec()</b>, it must set up its own <b>pcre_extra</b> block. However,
1060
+ if <b>pcre_study()</b> is called with the PCRE_STUDY_EXTRA_NEEDED option, it
1061
+ returns a <b>pcre_extra</b> block even if studying did not find any additional
1062
+ information. It may still return NULL, however, if an error occurs in
1063
+ <b>pcre_study()</b>.
1064
+ </P>
1065
+ <P>
1066
+ The second argument of <b>pcre_study()</b> contains option bits. There are three
1067
+ further options in addition to PCRE_STUDY_EXTRA_NEEDED:
1068
+ <pre>
1069
+ PCRE_STUDY_JIT_COMPILE
1070
+ PCRE_STUDY_JIT_PARTIAL_HARD_COMPILE
1071
+ PCRE_STUDY_JIT_PARTIAL_SOFT_COMPILE
1072
+ </pre>
1073
+ If any of these are set, and the just-in-time compiler is available, the
1074
+ pattern is further compiled into machine code that executes much faster than
1075
+ the <b>pcre_exec()</b> interpretive matching function. If the just-in-time
1076
+ compiler is not available, these options are ignored. All undefined bits in the
1077
+ <i>options</i> argument must be zero.
1078
+ </P>
1079
+ <P>
1080
+ JIT compilation is a heavyweight optimization. It can take some time for
1081
+ patterns to be analyzed, and for one-off matches and simple patterns the
1082
+ benefit of faster execution might be offset by a much slower study time.
1083
+ Not all patterns can be optimized by the JIT compiler. For those that cannot be
1084
+ handled, matching automatically falls back to the <b>pcre_exec()</b>
1085
+ interpreter. For more details, see the
1086
+ <a href="pcrejit.html"><b>pcrejit</b></a>
1087
+ documentation.
1088
+ </P>
1089
+ <P>
1090
+ The third argument for <b>pcre_study()</b> is a pointer for an error message. If
1091
+ studying succeeds (even if no data is returned), the variable it points to is
1092
+ set to NULL. Otherwise it is set to point to a textual error message. This is a
1093
+ static string that is part of the library. You must not try to free it. You
1094
+ should test the error pointer for NULL after calling <b>pcre_study()</b>, to be
1095
+ sure that it has run successfully.
1096
+ </P>
1097
+ <P>
1098
+ When you are finished with a pattern, you can free the memory used for the
1099
+ study data by calling <b>pcre_free_study()</b>. This function was added to the
1100
+ API for release 8.20. For earlier versions, the memory could be freed with
1101
+ <b>pcre_free()</b>, just like the pattern itself. This will still work in cases
1102
+ where JIT optimization is not used, but it is advisable to change to the new
1103
+ function when convenient.
1104
+ </P>
1105
+ <P>
1106
+ This is a typical way in which <b>pcre_study</b>() is used (except that in a
1107
+ real application there should be tests for errors):
1108
+ <pre>
1109
+ int rc;
1110
+ pcre *re;
1111
+ pcre_extra *sd;
1112
+ re = pcre_compile("pattern", 0, &error, &erroroffset, NULL);
1113
+ sd = pcre_study(
1114
+ re, /* result of pcre_compile() */
1115
+ 0, /* no options */
1116
+ &error); /* set to NULL or points to a message */
1117
+ rc = pcre_exec( /* see below for details of pcre_exec() options */
1118
+ re, sd, "subject", 7, 0, 0, ovector, 30);
1119
+ ...
1120
+ pcre_free_study(sd);
1121
+ pcre_free(re);
1122
+ </pre>
1123
+ Studying a pattern does two things: first, a lower bound for the length of
1124
+ subject string that is needed to match the pattern is computed. This does not
1125
+ mean that there are any strings of that length that match, but it does
1126
+ guarantee that no shorter strings match. The value is used to avoid wasting
1127
+ time by trying to match strings that are shorter than the lower bound. You can
1128
+ find out the value in a calling program via the <b>pcre_fullinfo()</b> function.
1129
+ </P>
1130
+ <P>
1131
+ Studying a pattern is also useful for non-anchored patterns that do not have a
1132
+ single fixed starting character. A bitmap of possible starting bytes is
1133
+ created. This speeds up finding a position in the subject at which to start
1134
+ matching. (In 16-bit mode, the bitmap is used for 16-bit values less than 256.
1135
+ In 32-bit mode, the bitmap is used for 32-bit values less than 256.)
1136
+ </P>
1137
+ <P>
1138
+ These two optimizations apply to both <b>pcre_exec()</b> and
1139
+ <b>pcre_dfa_exec()</b>, and the information is also used by the JIT compiler.
1140
+ The optimizations can be disabled by setting the PCRE_NO_START_OPTIMIZE option.
1141
+ You might want to do this if your pattern contains callouts or (*MARK) and you
1142
+ want to make use of these facilities in cases where matching fails.
1143
+ </P>
1144
+ <P>
1145
+ PCRE_NO_START_OPTIMIZE can be specified at either compile time or execution
1146
+ time. However, if PCRE_NO_START_OPTIMIZE is passed to <b>pcre_exec()</b>, (that
1147
+ is, after any JIT compilation has happened) JIT execution is disabled. For JIT
1148
+ execution to work with PCRE_NO_START_OPTIMIZE, the option must be set at
1149
+ compile time.
1150
+ </P>
1151
+ <P>
1152
+ There is a longer discussion of PCRE_NO_START_OPTIMIZE
1153
+ <a href="#execoptions">below.</a>
1154
+ <a name="localesupport"></a></P>
1155
+ <br><a name="SEC14" href="#TOC1">LOCALE SUPPORT</a><br>
1156
+ <P>
1157
+ PCRE handles caseless matching, and determines whether characters are letters,
1158
+ digits, or whatever, by reference to a set of tables, indexed by character
1159
+ code point. When running in UTF-8 mode, or in the 16- or 32-bit libraries, this
1160
+ applies only to characters with code points less than 256. By default,
1161
+ higher-valued code points never match escapes such as \w or \d. However, if
1162
+ PCRE is built with Unicode property support, all characters can be tested with
1163
+ \p and \P, or, alternatively, the PCRE_UCP option can be set when a pattern
1164
+ is compiled; this causes \w and friends to use Unicode property support
1165
+ instead of the built-in tables.
1166
+ </P>
1167
+ <P>
1168
+ The use of locales with Unicode is discouraged. If you are handling characters
1169
+ with code points greater than 128, you should either use Unicode support, or
1170
+ use locales, but not try to mix the two.
1171
+ </P>
1172
+ <P>
1173
+ PCRE contains an internal set of tables that are used when the final argument
1174
+ of <b>pcre_compile()</b> is NULL. These are sufficient for many applications.
1175
+ Normally, the internal tables recognize only ASCII characters. However, when
1176
+ PCRE is built, it is possible to cause the internal tables to be rebuilt in the
1177
+ default "C" locale of the local system, which may cause them to be different.
1178
+ </P>
1179
+ <P>
1180
+ The internal tables can always be overridden by tables supplied by the
1181
+ application that calls PCRE. These may be created in a different locale from
1182
+ the default. As more and more applications change to using Unicode, the need
1183
+ for this locale support is expected to die away.
1184
+ </P>
1185
+ <P>
1186
+ External tables are built by calling the <b>pcre_maketables()</b> function,
1187
+ which has no arguments, in the relevant locale. The result can then be passed
1188
+ to <b>pcre_compile()</b> as often as necessary. For example, to build and use
1189
+ tables that are appropriate for the French locale (where accented characters
1190
+ with values greater than 128 are treated as letters), the following code could
1191
+ be used:
1192
+ <pre>
1193
+ setlocale(LC_CTYPE, "fr_FR");
1194
+ tables = pcre_maketables();
1195
+ re = pcre_compile(..., tables);
1196
+ </pre>
1197
+ The locale name "fr_FR" is used on Linux and other Unix-like systems; if you
1198
+ are using Windows, the name for the French locale is "french".
1199
+ </P>
1200
+ <P>
1201
+ When <b>pcre_maketables()</b> runs, the tables are built in memory that is
1202
+ obtained via <b>pcre_malloc</b>. It is the caller's responsibility to ensure
1203
+ that the memory containing the tables remains available for as long as it is
1204
+ needed.
1205
+ </P>
1206
+ <P>
1207
+ The pointer that is passed to <b>pcre_compile()</b> is saved with the compiled
1208
+ pattern, and the same tables are used via this pointer by <b>pcre_study()</b>
1209
+ and also by <b>pcre_exec()</b> and <b>pcre_dfa_exec()</b>. Thus, for any single
1210
+ pattern, compilation, studying and matching all happen in the same locale, but
1211
+ different patterns can be processed in different locales.
1212
+ </P>
1213
+ <P>
1214
+ It is possible to pass a table pointer or NULL (indicating the use of the
1215
+ internal tables) to <b>pcre_exec()</b> or <b>pcre_dfa_exec()</b> (see the
1216
+ discussion below in the section on matching a pattern). This facility is
1217
+ provided for use with pre-compiled patterns that have been saved and reloaded.
1218
+ Character tables are not saved with patterns, so if a non-standard table was
1219
+ used at compile time, it must be provided again when the reloaded pattern is
1220
+ matched. Attempting to use this facility to match a pattern in a different
1221
+ locale from the one in which it was compiled is likely to lead to anomalous
1222
+ (usually incorrect) results.
1223
+ <a name="infoaboutpattern"></a></P>
1224
+ <br><a name="SEC15" href="#TOC1">INFORMATION ABOUT A PATTERN</a><br>
1225
+ <P>
1226
+ <b>int pcre_fullinfo(const pcre *<i>code</i>, const pcre_extra *<i>extra</i>,</b>
1227
+ <b> int <i>what</i>, void *<i>where</i>);</b>
1228
+ </P>
1229
+ <P>
1230
+ The <b>pcre_fullinfo()</b> function returns information about a compiled
1231
+ pattern. It replaces the <b>pcre_info()</b> function, which was removed from the
1232
+ library at version 8.30, after more than 10 years of obsolescence.
1233
+ </P>
1234
+ <P>
1235
+ The first argument for <b>pcre_fullinfo()</b> is a pointer to the compiled
1236
+ pattern. The second argument is the result of <b>pcre_study()</b>, or NULL if
1237
+ the pattern was not studied. The third argument specifies which piece of
1238
+ information is required, and the fourth argument is a pointer to a variable
1239
+ to receive the data. The yield of the function is zero for success, or one of
1240
+ the following negative numbers:
1241
+ <pre>
1242
+ PCRE_ERROR_NULL the argument <i>code</i> was NULL
1243
+ the argument <i>where</i> was NULL
1244
+ PCRE_ERROR_BADMAGIC the "magic number" was not found
1245
+ PCRE_ERROR_BADENDIANNESS the pattern was compiled with different
1246
+ endianness
1247
+ PCRE_ERROR_BADOPTION the value of <i>what</i> was invalid
1248
+ PCRE_ERROR_UNSET the requested field is not set
1249
+ </pre>
1250
+ The "magic number" is placed at the start of each compiled pattern as an simple
1251
+ check against passing an arbitrary memory pointer. The endianness error can
1252
+ occur if a compiled pattern is saved and reloaded on a different host. Here is
1253
+ a typical call of <b>pcre_fullinfo()</b>, to obtain the length of the compiled
1254
+ pattern:
1255
+ <pre>
1256
+ int rc;
1257
+ size_t length;
1258
+ rc = pcre_fullinfo(
1259
+ re, /* result of pcre_compile() */
1260
+ sd, /* result of pcre_study(), or NULL */
1261
+ PCRE_INFO_SIZE, /* what is required */
1262
+ &length); /* where to put the data */
1263
+ </pre>
1264
+ The possible values for the third argument are defined in <b>pcre.h</b>, and are
1265
+ as follows:
1266
+ <pre>
1267
+ PCRE_INFO_BACKREFMAX
1268
+ </pre>
1269
+ Return the number of the highest back reference in the pattern. The fourth
1270
+ argument should point to an <b>int</b> variable. Zero is returned if there are
1271
+ no back references.
1272
+ <pre>
1273
+ PCRE_INFO_CAPTURECOUNT
1274
+ </pre>
1275
+ Return the number of capturing subpatterns in the pattern. The fourth argument
1276
+ should point to an <b>int</b> variable.
1277
+ <pre>
1278
+ PCRE_INFO_DEFAULT_TABLES
1279
+ </pre>
1280
+ Return a pointer to the internal default character tables within PCRE. The
1281
+ fourth argument should point to an <b>unsigned char *</b> variable. This
1282
+ information call is provided for internal use by the <b>pcre_study()</b>
1283
+ function. External callers can cause PCRE to use its internal tables by passing
1284
+ a NULL table pointer.
1285
+ <pre>
1286
+ PCRE_INFO_FIRSTBYTE (deprecated)
1287
+ </pre>
1288
+ Return information about the first data unit of any matched string, for a
1289
+ non-anchored pattern. The name of this option refers to the 8-bit library,
1290
+ where data units are bytes. The fourth argument should point to an <b>int</b>
1291
+ variable. Negative values are used for special cases. However, this means that
1292
+ when the 32-bit library is in non-UTF-32 mode, the full 32-bit range of
1293
+ characters cannot be returned. For this reason, this value is deprecated; use
1294
+ PCRE_INFO_FIRSTCHARACTERFLAGS and PCRE_INFO_FIRSTCHARACTER instead.
1295
+ </P>
1296
+ <P>
1297
+ If there is a fixed first value, for example, the letter "c" from a pattern
1298
+ such as (cat|cow|coyote), its value is returned. In the 8-bit library, the
1299
+ value is always less than 256. In the 16-bit library the value can be up to
1300
+ 0xffff. In the 32-bit library the value can be up to 0x10ffff.
1301
+ </P>
1302
+ <P>
1303
+ If there is no fixed first value, and if either
1304
+ <br>
1305
+ <br>
1306
+ (a) the pattern was compiled with the PCRE_MULTILINE option, and every branch
1307
+ starts with "^", or
1308
+ <br>
1309
+ <br>
1310
+ (b) every branch of the pattern starts with ".*" and PCRE_DOTALL is not set
1311
+ (if it were set, the pattern would be anchored),
1312
+ <br>
1313
+ <br>
1314
+ -1 is returned, indicating that the pattern matches only at the start of a
1315
+ subject string or after any newline within the string. Otherwise -2 is
1316
+ returned. For anchored patterns, -2 is returned.
1317
+ <pre>
1318
+ PCRE_INFO_FIRSTCHARACTER
1319
+ </pre>
1320
+ Return the value of the first data unit (non-UTF character) of any matched
1321
+ string in the situation where PCRE_INFO_FIRSTCHARACTERFLAGS returns 1;
1322
+ otherwise return 0. The fourth argument should point to an <b>uint_t</b>
1323
+ variable.
1324
+ </P>
1325
+ <P>
1326
+ In the 8-bit library, the value is always less than 256. In the 16-bit library
1327
+ the value can be up to 0xffff. In the 32-bit library in UTF-32 mode the value
1328
+ can be up to 0x10ffff, and up to 0xffffffff when not using UTF-32 mode.
1329
+ <pre>
1330
+ PCRE_INFO_FIRSTCHARACTERFLAGS
1331
+ </pre>
1332
+ Return information about the first data unit of any matched string, for a
1333
+ non-anchored pattern. The fourth argument should point to an <b>int</b>
1334
+ variable.
1335
+ </P>
1336
+ <P>
1337
+ If there is a fixed first value, for example, the letter "c" from a pattern
1338
+ such as (cat|cow|coyote), 1 is returned, and the character value can be
1339
+ retrieved using PCRE_INFO_FIRSTCHARACTER. If there is no fixed first value, and
1340
+ if either
1341
+ <br>
1342
+ <br>
1343
+ (a) the pattern was compiled with the PCRE_MULTILINE option, and every branch
1344
+ starts with "^", or
1345
+ <br>
1346
+ <br>
1347
+ (b) every branch of the pattern starts with ".*" and PCRE_DOTALL is not set
1348
+ (if it were set, the pattern would be anchored),
1349
+ <br>
1350
+ <br>
1351
+ 2 is returned, indicating that the pattern matches only at the start of a
1352
+ subject string or after any newline within the string. Otherwise 0 is
1353
+ returned. For anchored patterns, 0 is returned.
1354
+ <pre>
1355
+ PCRE_INFO_FIRSTTABLE
1356
+ </pre>
1357
+ If the pattern was studied, and this resulted in the construction of a 256-bit
1358
+ table indicating a fixed set of values for the first data unit in any matching
1359
+ string, a pointer to the table is returned. Otherwise NULL is returned. The
1360
+ fourth argument should point to an <b>unsigned char *</b> variable.
1361
+ <pre>
1362
+ PCRE_INFO_HASCRORLF
1363
+ </pre>
1364
+ Return 1 if the pattern contains any explicit matches for CR or LF characters,
1365
+ otherwise 0. The fourth argument should point to an <b>int</b> variable. An
1366
+ explicit match is either a literal CR or LF character, or \r or \n.
1367
+ <pre>
1368
+ PCRE_INFO_JCHANGED
1369
+ </pre>
1370
+ Return 1 if the (?J) or (?-J) option setting is used in the pattern, otherwise
1371
+ 0. The fourth argument should point to an <b>int</b> variable. (?J) and
1372
+ (?-J) set and unset the local PCRE_DUPNAMES option, respectively.
1373
+ <pre>
1374
+ PCRE_INFO_JIT
1375
+ </pre>
1376
+ Return 1 if the pattern was studied with one of the JIT options, and
1377
+ just-in-time compiling was successful. The fourth argument should point to an
1378
+ <b>int</b> variable. A return value of 0 means that JIT support is not available
1379
+ in this version of PCRE, or that the pattern was not studied with a JIT option,
1380
+ or that the JIT compiler could not handle this particular pattern. See the
1381
+ <a href="pcrejit.html"><b>pcrejit</b></a>
1382
+ documentation for details of what can and cannot be handled.
1383
+ <pre>
1384
+ PCRE_INFO_JITSIZE
1385
+ </pre>
1386
+ If the pattern was successfully studied with a JIT option, return the size of
1387
+ the JIT compiled code, otherwise return zero. The fourth argument should point
1388
+ to a <b>size_t</b> variable.
1389
+ <pre>
1390
+ PCRE_INFO_LASTLITERAL
1391
+ </pre>
1392
+ Return the value of the rightmost literal data unit that must exist in any
1393
+ matched string, other than at its start, if such a value has been recorded. The
1394
+ fourth argument should point to an <b>int</b> variable. If there is no such
1395
+ value, -1 is returned. For anchored patterns, a last literal value is recorded
1396
+ only if it follows something of variable length. For example, for the pattern
1397
+ /^a\d+z\d+/ the returned value is "z", but for /^a\dz\d/ the returned value
1398
+ is -1.
1399
+ </P>
1400
+ <P>
1401
+ Since for the 32-bit library using the non-UTF-32 mode, this function is unable
1402
+ to return the full 32-bit range of characters, this value is deprecated;
1403
+ instead the PCRE_INFO_REQUIREDCHARFLAGS and PCRE_INFO_REQUIREDCHAR values should
1404
+ be used.
1405
+ <pre>
1406
+ PCRE_INFO_MATCH_EMPTY
1407
+ </pre>
1408
+ Return 1 if the pattern can match an empty string, otherwise 0. The fourth
1409
+ argument should point to an <b>int</b> variable.
1410
+ <pre>
1411
+ PCRE_INFO_MATCHLIMIT
1412
+ </pre>
1413
+ If the pattern set a match limit by including an item of the form
1414
+ (*LIMIT_MATCH=nnnn) at the start, the value is returned. The fourth argument
1415
+ should point to an unsigned 32-bit integer. If no such value has been set, the
1416
+ call to <b>pcre_fullinfo()</b> returns the error PCRE_ERROR_UNSET.
1417
+ <pre>
1418
+ PCRE_INFO_MAXLOOKBEHIND
1419
+ </pre>
1420
+ Return the number of characters (NB not data units) in the longest lookbehind
1421
+ assertion in the pattern. This information is useful when doing multi-segment
1422
+ matching using the partial matching facilities. Note that the simple assertions
1423
+ \b and \B require a one-character lookbehind. \A also registers a
1424
+ one-character lookbehind, though it does not actually inspect the previous
1425
+ character. This is to ensure that at least one character from the old segment
1426
+ is retained when a new segment is processed. Otherwise, if there are no
1427
+ lookbehinds in the pattern, \A might match incorrectly at the start of a new
1428
+ segment.
1429
+ <pre>
1430
+ PCRE_INFO_MINLENGTH
1431
+ </pre>
1432
+ If the pattern was studied and a minimum length for matching subject strings
1433
+ was computed, its value is returned. Otherwise the returned value is -1. The
1434
+ value is a number of characters, which in UTF mode may be different from the
1435
+ number of data units. The fourth argument should point to an <b>int</b>
1436
+ variable. A non-negative value is a lower bound to the length of any matching
1437
+ string. There may not be any strings of that length that do actually match, but
1438
+ every string that does match is at least that long.
1439
+ <pre>
1440
+ PCRE_INFO_NAMECOUNT
1441
+ PCRE_INFO_NAMEENTRYSIZE
1442
+ PCRE_INFO_NAMETABLE
1443
+ </pre>
1444
+ PCRE supports the use of named as well as numbered capturing parentheses. The
1445
+ names are just an additional way of identifying the parentheses, which still
1446
+ acquire numbers. Several convenience functions such as
1447
+ <b>pcre_get_named_substring()</b> are provided for extracting captured
1448
+ substrings by name. It is also possible to extract the data directly, by first
1449
+ converting the name to a number in order to access the correct pointers in the
1450
+ output vector (described with <b>pcre_exec()</b> below). To do the conversion,
1451
+ you need to use the name-to-number map, which is described by these three
1452
+ values.
1453
+ </P>
1454
+ <P>
1455
+ The map consists of a number of fixed-size entries. PCRE_INFO_NAMECOUNT gives
1456
+ the number of entries, and PCRE_INFO_NAMEENTRYSIZE gives the size of each
1457
+ entry; both of these return an <b>int</b> value. The entry size depends on the
1458
+ length of the longest name. PCRE_INFO_NAMETABLE returns a pointer to the first
1459
+ entry of the table. This is a pointer to <b>char</b> in the 8-bit library, where
1460
+ the first two bytes of each entry are the number of the capturing parenthesis,
1461
+ most significant byte first. In the 16-bit library, the pointer points to
1462
+ 16-bit data units, the first of which contains the parenthesis number. In the
1463
+ 32-bit library, the pointer points to 32-bit data units, the first of which
1464
+ contains the parenthesis number. The rest of the entry is the corresponding
1465
+ name, zero terminated.
1466
+ </P>
1467
+ <P>
1468
+ The names are in alphabetical order. If (?| is used to create multiple groups
1469
+ with the same number, as described in the
1470
+ <a href="pcrepattern.html#dupsubpatternnumber">section on duplicate subpattern numbers</a>
1471
+ in the
1472
+ <a href="pcrepattern.html"><b>pcrepattern</b></a>
1473
+ page, the groups may be given the same name, but there is only one entry in the
1474
+ table. Different names for groups of the same number are not permitted.
1475
+ Duplicate names for subpatterns with different numbers are permitted,
1476
+ but only if PCRE_DUPNAMES is set. They appear in the table in the order in
1477
+ which they were found in the pattern. In the absence of (?| this is the order
1478
+ of increasing number; when (?| is used this is not necessarily the case because
1479
+ later subpatterns may have lower numbers.
1480
+ </P>
1481
+ <P>
1482
+ As a simple example of the name/number table, consider the following pattern
1483
+ after compilation by the 8-bit library (assume PCRE_EXTENDED is set, so white
1484
+ space - including newlines - is ignored):
1485
+ <pre>
1486
+ (?&#60;date&#62; (?&#60;year&#62;(\d\d)?\d\d) - (?&#60;month&#62;\d\d) - (?&#60;day&#62;\d\d) )
1487
+ </pre>
1488
+ There are four named subpatterns, so the table has four entries, and each entry
1489
+ in the table is eight bytes long. The table is as follows, with non-printing
1490
+ bytes shows in hexadecimal, and undefined bytes shown as ??:
1491
+ <pre>
1492
+ 00 01 d a t e 00 ??
1493
+ 00 05 d a y 00 ?? ??
1494
+ 00 04 m o n t h 00
1495
+ 00 02 y e a r 00 ??
1496
+ </pre>
1497
+ When writing code to extract data from named subpatterns using the
1498
+ name-to-number map, remember that the length of the entries is likely to be
1499
+ different for each compiled pattern.
1500
+ <pre>
1501
+ PCRE_INFO_OKPARTIAL
1502
+ </pre>
1503
+ Return 1 if the pattern can be used for partial matching with
1504
+ <b>pcre_exec()</b>, otherwise 0. The fourth argument should point to an
1505
+ <b>int</b> variable. From release 8.00, this always returns 1, because the
1506
+ restrictions that previously applied to partial matching have been lifted. The
1507
+ <a href="pcrepartial.html"><b>pcrepartial</b></a>
1508
+ documentation gives details of partial matching.
1509
+ <pre>
1510
+ PCRE_INFO_OPTIONS
1511
+ </pre>
1512
+ Return a copy of the options with which the pattern was compiled. The fourth
1513
+ argument should point to an <b>unsigned long int</b> variable. These option bits
1514
+ are those specified in the call to <b>pcre_compile()</b>, modified by any
1515
+ top-level option settings at the start of the pattern itself. In other words,
1516
+ they are the options that will be in force when matching starts. For example,
1517
+ if the pattern /(?im)abc(?-i)d/ is compiled with the PCRE_EXTENDED option, the
1518
+ result is PCRE_CASELESS, PCRE_MULTILINE, and PCRE_EXTENDED.
1519
+ </P>
1520
+ <P>
1521
+ A pattern is automatically anchored by PCRE if all of its top-level
1522
+ alternatives begin with one of the following:
1523
+ <pre>
1524
+ ^ unless PCRE_MULTILINE is set
1525
+ \A always
1526
+ \G always
1527
+ .* if PCRE_DOTALL is set and there are no back references to the subpattern in which .* appears
1528
+ </pre>
1529
+ For such patterns, the PCRE_ANCHORED bit is set in the options returned by
1530
+ <b>pcre_fullinfo()</b>.
1531
+ <pre>
1532
+ PCRE_INFO_RECURSIONLIMIT
1533
+ </pre>
1534
+ If the pattern set a recursion limit by including an item of the form
1535
+ (*LIMIT_RECURSION=nnnn) at the start, the value is returned. The fourth
1536
+ argument should point to an unsigned 32-bit integer. If no such value has been
1537
+ set, the call to <b>pcre_fullinfo()</b> returns the error PCRE_ERROR_UNSET.
1538
+ <pre>
1539
+ PCRE_INFO_SIZE
1540
+ </pre>
1541
+ Return the size of the compiled pattern in bytes (for all three libraries). The
1542
+ fourth argument should point to a <b>size_t</b> variable. This value does not
1543
+ include the size of the <b>pcre</b> structure that is returned by
1544
+ <b>pcre_compile()</b>. The value that is passed as the argument to
1545
+ <b>pcre_malloc()</b> when <b>pcre_compile()</b> is getting memory in which to
1546
+ place the compiled data is the value returned by this option plus the size of
1547
+ the <b>pcre</b> structure. Studying a compiled pattern, with or without JIT,
1548
+ does not alter the value returned by this option.
1549
+ <pre>
1550
+ PCRE_INFO_STUDYSIZE
1551
+ </pre>
1552
+ Return the size in bytes (for all three libraries) of the data block pointed to
1553
+ by the <i>study_data</i> field in a <b>pcre_extra</b> block. If <b>pcre_extra</b>
1554
+ is NULL, or there is no study data, zero is returned. The fourth argument
1555
+ should point to a <b>size_t</b> variable. The <i>study_data</i> field is set by
1556
+ <b>pcre_study()</b> to record information that will speed up matching (see the
1557
+ section entitled
1558
+ <a href="#studyingapattern">"Studying a pattern"</a>
1559
+ above). The format of the <i>study_data</i> block is private, but its length
1560
+ is made available via this option so that it can be saved and restored (see the
1561
+ <a href="pcreprecompile.html"><b>pcreprecompile</b></a>
1562
+ documentation for details).
1563
+ <pre>
1564
+ PCRE_INFO_REQUIREDCHARFLAGS
1565
+ </pre>
1566
+ Returns 1 if there is a rightmost literal data unit that must exist in any
1567
+ matched string, other than at its start. The fourth argument should point to
1568
+ an <b>int</b> variable. If there is no such value, 0 is returned. If returning
1569
+ 1, the character value itself can be retrieved using PCRE_INFO_REQUIREDCHAR.
1570
+ </P>
1571
+ <P>
1572
+ For anchored patterns, a last literal value is recorded only if it follows
1573
+ something of variable length. For example, for the pattern /^a\d+z\d+/ the
1574
+ returned value 1 (with "z" returned from PCRE_INFO_REQUIREDCHAR), but for
1575
+ /^a\dz\d/ the returned value is 0.
1576
+ <pre>
1577
+ PCRE_INFO_REQUIREDCHAR
1578
+ </pre>
1579
+ Return the value of the rightmost literal data unit that must exist in any
1580
+ matched string, other than at its start, if such a value has been recorded. The
1581
+ fourth argument should point to an <b>uint32_t</b> variable. If there is no such
1582
+ value, 0 is returned.
1583
+ </P>
1584
+ <br><a name="SEC16" href="#TOC1">REFERENCE COUNTS</a><br>
1585
+ <P>
1586
+ <b>int pcre_refcount(pcre *<i>code</i>, int <i>adjust</i>);</b>
1587
+ </P>
1588
+ <P>
1589
+ The <b>pcre_refcount()</b> function is used to maintain a reference count in the
1590
+ data block that contains a compiled pattern. It is provided for the benefit of
1591
+ applications that operate in an object-oriented manner, where different parts
1592
+ of the application may be using the same compiled pattern, but you want to free
1593
+ the block when they are all done.
1594
+ </P>
1595
+ <P>
1596
+ When a pattern is compiled, the reference count field is initialized to zero.
1597
+ It is changed only by calling this function, whose action is to add the
1598
+ <i>adjust</i> value (which may be positive or negative) to it. The yield of the
1599
+ function is the new value. However, the value of the count is constrained to
1600
+ lie between 0 and 65535, inclusive. If the new value is outside these limits,
1601
+ it is forced to the appropriate limit value.
1602
+ </P>
1603
+ <P>
1604
+ Except when it is zero, the reference count is not correctly preserved if a
1605
+ pattern is compiled on one host and then transferred to a host whose byte-order
1606
+ is different. (This seems a highly unlikely scenario.)
1607
+ </P>
1608
+ <br><a name="SEC17" href="#TOC1">MATCHING A PATTERN: THE TRADITIONAL FUNCTION</a><br>
1609
+ <P>
1610
+ <b>int pcre_exec(const pcre *<i>code</i>, const pcre_extra *<i>extra</i>,</b>
1611
+ <b> const char *<i>subject</i>, int <i>length</i>, int <i>startoffset</i>,</b>
1612
+ <b> int <i>options</i>, int *<i>ovector</i>, int <i>ovecsize</i>);</b>
1613
+ </P>
1614
+ <P>
1615
+ The function <b>pcre_exec()</b> is called to match a subject string against a
1616
+ compiled pattern, which is passed in the <i>code</i> argument. If the
1617
+ pattern was studied, the result of the study should be passed in the
1618
+ <i>extra</i> argument. You can call <b>pcre_exec()</b> with the same <i>code</i>
1619
+ and <i>extra</i> arguments as many times as you like, in order to match
1620
+ different subject strings with the same pattern.
1621
+ </P>
1622
+ <P>
1623
+ This function is the main matching facility of the library, and it operates in
1624
+ a Perl-like manner. For specialist use there is also an alternative matching
1625
+ function, which is described
1626
+ <a href="#dfamatch">below</a>
1627
+ in the section about the <b>pcre_dfa_exec()</b> function.
1628
+ </P>
1629
+ <P>
1630
+ In most applications, the pattern will have been compiled (and optionally
1631
+ studied) in the same process that calls <b>pcre_exec()</b>. However, it is
1632
+ possible to save compiled patterns and study data, and then use them later
1633
+ in different processes, possibly even on different hosts. For a discussion
1634
+ about this, see the
1635
+ <a href="pcreprecompile.html"><b>pcreprecompile</b></a>
1636
+ documentation.
1637
+ </P>
1638
+ <P>
1639
+ Here is an example of a simple call to <b>pcre_exec()</b>:
1640
+ <pre>
1641
+ int rc;
1642
+ int ovector[30];
1643
+ rc = pcre_exec(
1644
+ re, /* result of pcre_compile() */
1645
+ NULL, /* we didn't study the pattern */
1646
+ "some string", /* the subject string */
1647
+ 11, /* the length of the subject string */
1648
+ 0, /* start at offset 0 in the subject */
1649
+ 0, /* default options */
1650
+ ovector, /* vector of integers for substring information */
1651
+ 30); /* number of elements (NOT size in bytes) */
1652
+ <a name="extradata"></a></PRE>
1653
+ </P>
1654
+ <br><b>
1655
+ Extra data for <b>pcre_exec()</b>
1656
+ </b><br>
1657
+ <P>
1658
+ If the <i>extra</i> argument is not NULL, it must point to a <b>pcre_extra</b>
1659
+ data block. The <b>pcre_study()</b> function returns such a block (when it
1660
+ doesn't return NULL), but you can also create one for yourself, and pass
1661
+ additional information in it. The <b>pcre_extra</b> block contains the following
1662
+ fields (not necessarily in this order):
1663
+ <pre>
1664
+ unsigned long int <i>flags</i>;
1665
+ void *<i>study_data</i>;
1666
+ void *<i>executable_jit</i>;
1667
+ unsigned long int <i>match_limit</i>;
1668
+ unsigned long int <i>match_limit_recursion</i>;
1669
+ void *<i>callout_data</i>;
1670
+ const unsigned char *<i>tables</i>;
1671
+ unsigned char **<i>mark</i>;
1672
+ </pre>
1673
+ In the 16-bit version of this structure, the <i>mark</i> field has type
1674
+ "PCRE_UCHAR16 **".
1675
+ <br>
1676
+ <br>
1677
+ In the 32-bit version of this structure, the <i>mark</i> field has type
1678
+ "PCRE_UCHAR32 **".
1679
+ </P>
1680
+ <P>
1681
+ The <i>flags</i> field is used to specify which of the other fields are set. The
1682
+ flag bits are:
1683
+ <pre>
1684
+ PCRE_EXTRA_CALLOUT_DATA
1685
+ PCRE_EXTRA_EXECUTABLE_JIT
1686
+ PCRE_EXTRA_MARK
1687
+ PCRE_EXTRA_MATCH_LIMIT
1688
+ PCRE_EXTRA_MATCH_LIMIT_RECURSION
1689
+ PCRE_EXTRA_STUDY_DATA
1690
+ PCRE_EXTRA_TABLES
1691
+ </pre>
1692
+ Other flag bits should be set to zero. The <i>study_data</i> field and sometimes
1693
+ the <i>executable_jit</i> field are set in the <b>pcre_extra</b> block that is
1694
+ returned by <b>pcre_study()</b>, together with the appropriate flag bits. You
1695
+ should not set these yourself, but you may add to the block by setting other
1696
+ fields and their corresponding flag bits.
1697
+ </P>
1698
+ <P>
1699
+ The <i>match_limit</i> field provides a means of preventing PCRE from using up a
1700
+ vast amount of resources when running patterns that are not going to match,
1701
+ but which have a very large number of possibilities in their search trees. The
1702
+ classic example is a pattern that uses nested unlimited repeats.
1703
+ </P>
1704
+ <P>
1705
+ Internally, <b>pcre_exec()</b> uses a function called <b>match()</b>, which it
1706
+ calls repeatedly (sometimes recursively). The limit set by <i>match_limit</i> is
1707
+ imposed on the number of times this function is called during a match, which
1708
+ has the effect of limiting the amount of backtracking that can take place. For
1709
+ patterns that are not anchored, the count restarts from zero for each position
1710
+ in the subject string.
1711
+ </P>
1712
+ <P>
1713
+ When <b>pcre_exec()</b> is called with a pattern that was successfully studied
1714
+ with a JIT option, the way that the matching is executed is entirely different.
1715
+ However, there is still the possibility of runaway matching that goes on for a
1716
+ very long time, and so the <i>match_limit</i> value is also used in this case
1717
+ (but in a different way) to limit how long the matching can continue.
1718
+ </P>
1719
+ <P>
1720
+ The default value for the limit can be set when PCRE is built; the default
1721
+ default is 10 million, which handles all but the most extreme cases. You can
1722
+ override the default by suppling <b>pcre_exec()</b> with a <b>pcre_extra</b>
1723
+ block in which <i>match_limit</i> is set, and PCRE_EXTRA_MATCH_LIMIT is set in
1724
+ the <i>flags</i> field. If the limit is exceeded, <b>pcre_exec()</b> returns
1725
+ PCRE_ERROR_MATCHLIMIT.
1726
+ </P>
1727
+ <P>
1728
+ A value for the match limit may also be supplied by an item at the start of a
1729
+ pattern of the form
1730
+ <pre>
1731
+ (*LIMIT_MATCH=d)
1732
+ </pre>
1733
+ where d is a decimal number. However, such a setting is ignored unless d is
1734
+ less than the limit set by the caller of <b>pcre_exec()</b> or, if no such limit
1735
+ is set, less than the default.
1736
+ </P>
1737
+ <P>
1738
+ The <i>match_limit_recursion</i> field is similar to <i>match_limit</i>, but
1739
+ instead of limiting the total number of times that <b>match()</b> is called, it
1740
+ limits the depth of recursion. The recursion depth is a smaller number than the
1741
+ total number of calls, because not all calls to <b>match()</b> are recursive.
1742
+ This limit is of use only if it is set smaller than <i>match_limit</i>.
1743
+ </P>
1744
+ <P>
1745
+ Limiting the recursion depth limits the amount of machine stack that can be
1746
+ used, or, when PCRE has been compiled to use memory on the heap instead of the
1747
+ stack, the amount of heap memory that can be used. This limit is not relevant,
1748
+ and is ignored, when matching is done using JIT compiled code.
1749
+ </P>
1750
+ <P>
1751
+ The default value for <i>match_limit_recursion</i> can be set when PCRE is
1752
+ built; the default default is the same value as the default for
1753
+ <i>match_limit</i>. You can override the default by suppling <b>pcre_exec()</b>
1754
+ with a <b>pcre_extra</b> block in which <i>match_limit_recursion</i> is set, and
1755
+ PCRE_EXTRA_MATCH_LIMIT_RECURSION is set in the <i>flags</i> field. If the limit
1756
+ is exceeded, <b>pcre_exec()</b> returns PCRE_ERROR_RECURSIONLIMIT.
1757
+ </P>
1758
+ <P>
1759
+ A value for the recursion limit may also be supplied by an item at the start of
1760
+ a pattern of the form
1761
+ <pre>
1762
+ (*LIMIT_RECURSION=d)
1763
+ </pre>
1764
+ where d is a decimal number. However, such a setting is ignored unless d is
1765
+ less than the limit set by the caller of <b>pcre_exec()</b> or, if no such limit
1766
+ is set, less than the default.
1767
+ </P>
1768
+ <P>
1769
+ The <i>callout_data</i> field is used in conjunction with the "callout" feature,
1770
+ and is described in the
1771
+ <a href="pcrecallout.html"><b>pcrecallout</b></a>
1772
+ documentation.
1773
+ </P>
1774
+ <P>
1775
+ The <i>tables</i> field is provided for use with patterns that have been
1776
+ pre-compiled using custom character tables, saved to disc or elsewhere, and
1777
+ then reloaded, because the tables that were used to compile a pattern are not
1778
+ saved with it. See the
1779
+ <a href="pcreprecompile.html"><b>pcreprecompile</b></a>
1780
+ documentation for a discussion of saving compiled patterns for later use. If
1781
+ NULL is passed using this mechanism, it forces PCRE's internal tables to be
1782
+ used.
1783
+ </P>
1784
+ <P>
1785
+ <b>Warning:</b> The tables that <b>pcre_exec()</b> uses must be the same as those
1786
+ that were used when the pattern was compiled. If this is not the case, the
1787
+ behaviour of <b>pcre_exec()</b> is undefined. Therefore, when a pattern is
1788
+ compiled and matched in the same process, this field should never be set. In
1789
+ this (the most common) case, the correct table pointer is automatically passed
1790
+ with the compiled pattern from <b>pcre_compile()</b> to <b>pcre_exec()</b>.
1791
+ </P>
1792
+ <P>
1793
+ If PCRE_EXTRA_MARK is set in the <i>flags</i> field, the <i>mark</i> field must
1794
+ be set to point to a suitable variable. If the pattern contains any
1795
+ backtracking control verbs such as (*MARK:NAME), and the execution ends up with
1796
+ a name to pass back, a pointer to the name string (zero terminated) is placed
1797
+ in the variable pointed to by the <i>mark</i> field. The names are within the
1798
+ compiled pattern; if you wish to retain such a name you must copy it before
1799
+ freeing the memory of a compiled pattern. If there is no name to pass back, the
1800
+ variable pointed to by the <i>mark</i> field is set to NULL. For details of the
1801
+ backtracking control verbs, see the section entitled
1802
+ <a href="pcrepattern#backtrackcontrol">"Backtracking control"</a>
1803
+ in the
1804
+ <a href="pcrepattern.html"><b>pcrepattern</b></a>
1805
+ documentation.
1806
+ <a name="execoptions"></a></P>
1807
+ <br><b>
1808
+ Option bits for <b>pcre_exec()</b>
1809
+ </b><br>
1810
+ <P>
1811
+ The unused bits of the <i>options</i> argument for <b>pcre_exec()</b> must be
1812
+ zero. The only bits that may be set are PCRE_ANCHORED, PCRE_NEWLINE_<i>xxx</i>,
1813
+ PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY, PCRE_NOTEMPTY_ATSTART,
1814
+ PCRE_NO_START_OPTIMIZE, PCRE_NO_UTF8_CHECK, PCRE_PARTIAL_HARD, and
1815
+ PCRE_PARTIAL_SOFT.
1816
+ </P>
1817
+ <P>
1818
+ If the pattern was successfully studied with one of the just-in-time (JIT)
1819
+ compile options, the only supported options for JIT execution are
1820
+ PCRE_NO_UTF8_CHECK, PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY,
1821
+ PCRE_NOTEMPTY_ATSTART, PCRE_PARTIAL_HARD, and PCRE_PARTIAL_SOFT. If an
1822
+ unsupported option is used, JIT execution is disabled and the normal
1823
+ interpretive code in <b>pcre_exec()</b> is run.
1824
+ <pre>
1825
+ PCRE_ANCHORED
1826
+ </pre>
1827
+ The PCRE_ANCHORED option limits <b>pcre_exec()</b> to matching at the first
1828
+ matching position. If a pattern was compiled with PCRE_ANCHORED, or turned out
1829
+ to be anchored by virtue of its contents, it cannot be made unachored at
1830
+ matching time.
1831
+ <pre>
1832
+ PCRE_BSR_ANYCRLF
1833
+ PCRE_BSR_UNICODE
1834
+ </pre>
1835
+ These options (which are mutually exclusive) control what the \R escape
1836
+ sequence matches. The choice is either to match only CR, LF, or CRLF, or to
1837
+ match any Unicode newline sequence. These options override the choice that was
1838
+ made or defaulted when the pattern was compiled.
1839
+ <pre>
1840
+ PCRE_NEWLINE_CR
1841
+ PCRE_NEWLINE_LF
1842
+ PCRE_NEWLINE_CRLF
1843
+ PCRE_NEWLINE_ANYCRLF
1844
+ PCRE_NEWLINE_ANY
1845
+ </pre>
1846
+ These options override the newline definition that was chosen or defaulted when
1847
+ the pattern was compiled. For details, see the description of
1848
+ <b>pcre_compile()</b> above. During matching, the newline choice affects the
1849
+ behaviour of the dot, circumflex, and dollar metacharacters. It may also alter
1850
+ the way the match position is advanced after a match failure for an unanchored
1851
+ pattern.
1852
+ </P>
1853
+ <P>
1854
+ When PCRE_NEWLINE_CRLF, PCRE_NEWLINE_ANYCRLF, or PCRE_NEWLINE_ANY is set, and a
1855
+ match attempt for an unanchored pattern fails when the current position is at a
1856
+ CRLF sequence, and the pattern contains no explicit matches for CR or LF
1857
+ characters, the match position is advanced by two characters instead of one, in
1858
+ other words, to after the CRLF.
1859
+ </P>
1860
+ <P>
1861
+ The above rule is a compromise that makes the most common cases work as
1862
+ expected. For example, if the pattern is .+A (and the PCRE_DOTALL option is not
1863
+ set), it does not match the string "\r\nA" because, after failing at the
1864
+ start, it skips both the CR and the LF before retrying. However, the pattern
1865
+ [\r\n]A does match that string, because it contains an explicit CR or LF
1866
+ reference, and so advances only by one character after the first failure.
1867
+ </P>
1868
+ <P>
1869
+ An explicit match for CR of LF is either a literal appearance of one of those
1870
+ characters, or one of the \r or \n escape sequences. Implicit matches such as
1871
+ [^X] do not count, nor does \s (which includes CR and LF in the characters
1872
+ that it matches).
1873
+ </P>
1874
+ <P>
1875
+ Notwithstanding the above, anomalous effects may still occur when CRLF is a
1876
+ valid newline sequence and explicit \r or \n escapes appear in the pattern.
1877
+ <pre>
1878
+ PCRE_NOTBOL
1879
+ </pre>
1880
+ This option specifies that first character of the subject string is not the
1881
+ beginning of a line, so the circumflex metacharacter should not match before
1882
+ it. Setting this without PCRE_MULTILINE (at compile time) causes circumflex
1883
+ never to match. This option affects only the behaviour of the circumflex
1884
+ metacharacter. It does not affect \A.
1885
+ <pre>
1886
+ PCRE_NOTEOL
1887
+ </pre>
1888
+ This option specifies that the end of the subject string is not the end of a
1889
+ line, so the dollar metacharacter should not match it nor (except in multiline
1890
+ mode) a newline immediately before it. Setting this without PCRE_MULTILINE (at
1891
+ compile time) causes dollar never to match. This option affects only the
1892
+ behaviour of the dollar metacharacter. It does not affect \Z or \z.
1893
+ <pre>
1894
+ PCRE_NOTEMPTY
1895
+ </pre>
1896
+ An empty string is not considered to be a valid match if this option is set. If
1897
+ there are alternatives in the pattern, they are tried. If all the alternatives
1898
+ match the empty string, the entire match fails. For example, if the pattern
1899
+ <pre>
1900
+ a?b?
1901
+ </pre>
1902
+ is applied to a string not beginning with "a" or "b", it matches an empty
1903
+ string at the start of the subject. With PCRE_NOTEMPTY set, this match is not
1904
+ valid, so PCRE searches further into the string for occurrences of "a" or "b".
1905
+ <pre>
1906
+ PCRE_NOTEMPTY_ATSTART
1907
+ </pre>
1908
+ This is like PCRE_NOTEMPTY, except that an empty string match that is not at
1909
+ the start of the subject is permitted. If the pattern is anchored, such a match
1910
+ can occur only if the pattern contains \K.
1911
+ </P>
1912
+ <P>
1913
+ Perl has no direct equivalent of PCRE_NOTEMPTY or PCRE_NOTEMPTY_ATSTART, but it
1914
+ does make a special case of a pattern match of the empty string within its
1915
+ <b>split()</b> function, and when using the /g modifier. It is possible to
1916
+ emulate Perl's behaviour after matching a null string by first trying the match
1917
+ again at the same offset with PCRE_NOTEMPTY_ATSTART and PCRE_ANCHORED, and then
1918
+ if that fails, by advancing the starting offset (see below) and trying an
1919
+ ordinary match again. There is some code that demonstrates how to do this in
1920
+ the
1921
+ <a href="pcredemo.html"><b>pcredemo</b></a>
1922
+ sample program. In the most general case, you have to check to see if the
1923
+ newline convention recognizes CRLF as a newline, and if so, and the current
1924
+ character is CR followed by LF, advance the starting offset by two characters
1925
+ instead of one.
1926
+ <pre>
1927
+ PCRE_NO_START_OPTIMIZE
1928
+ </pre>
1929
+ There are a number of optimizations that <b>pcre_exec()</b> uses at the start of
1930
+ a match, in order to speed up the process. For example, if it is known that an
1931
+ unanchored match must start with a specific character, it searches the subject
1932
+ for that character, and fails immediately if it cannot find it, without
1933
+ actually running the main matching function. This means that a special item
1934
+ such as (*COMMIT) at the start of a pattern is not considered until after a
1935
+ suitable starting point for the match has been found. Also, when callouts or
1936
+ (*MARK) items are in use, these "start-up" optimizations can cause them to be
1937
+ skipped if the pattern is never actually used. The start-up optimizations are
1938
+ in effect a pre-scan of the subject that takes place before the pattern is run.
1939
+ </P>
1940
+ <P>
1941
+ The PCRE_NO_START_OPTIMIZE option disables the start-up optimizations, possibly
1942
+ causing performance to suffer, but ensuring that in cases where the result is
1943
+ "no match", the callouts do occur, and that items such as (*COMMIT) and (*MARK)
1944
+ are considered at every possible starting position in the subject string. If
1945
+ PCRE_NO_START_OPTIMIZE is set at compile time, it cannot be unset at matching
1946
+ time. The use of PCRE_NO_START_OPTIMIZE at matching time (that is, passing it
1947
+ to <b>pcre_exec()</b>) disables JIT execution; in this situation, matching is
1948
+ always done using interpretively.
1949
+ </P>
1950
+ <P>
1951
+ Setting PCRE_NO_START_OPTIMIZE can change the outcome of a matching operation.
1952
+ Consider the pattern
1953
+ <pre>
1954
+ (*COMMIT)ABC
1955
+ </pre>
1956
+ When this is compiled, PCRE records the fact that a match must start with the
1957
+ character "A". Suppose the subject string is "DEFABC". The start-up
1958
+ optimization scans along the subject, finds "A" and runs the first match
1959
+ attempt from there. The (*COMMIT) item means that the pattern must match the
1960
+ current starting position, which in this case, it does. However, if the same
1961
+ match is run with PCRE_NO_START_OPTIMIZE set, the initial scan along the
1962
+ subject string does not happen. The first match attempt is run starting from
1963
+ "D" and when this fails, (*COMMIT) prevents any further matches being tried, so
1964
+ the overall result is "no match". If the pattern is studied, more start-up
1965
+ optimizations may be used. For example, a minimum length for the subject may be
1966
+ recorded. Consider the pattern
1967
+ <pre>
1968
+ (*MARK:A)(X|Y)
1969
+ </pre>
1970
+ The minimum length for a match is one character. If the subject is "ABC", there
1971
+ will be attempts to match "ABC", "BC", "C", and then finally an empty string.
1972
+ If the pattern is studied, the final attempt does not take place, because PCRE
1973
+ knows that the subject is too short, and so the (*MARK) is never encountered.
1974
+ In this case, studying the pattern does not affect the overall match result,
1975
+ which is still "no match", but it does affect the auxiliary information that is
1976
+ returned.
1977
+ <pre>
1978
+ PCRE_NO_UTF8_CHECK
1979
+ </pre>
1980
+ When PCRE_UTF8 is set at compile time, the validity of the subject as a UTF-8
1981
+ string is automatically checked when <b>pcre_exec()</b> is subsequently called.
1982
+ The entire string is checked before any other processing takes place. The value
1983
+ of <i>startoffset</i> is also checked to ensure that it points to the start of a
1984
+ UTF-8 character. There is a discussion about the
1985
+ <a href="pcreunicode.html#utf8strings">validity of UTF-8 strings</a>
1986
+ in the
1987
+ <a href="pcreunicode.html"><b>pcreunicode</b></a>
1988
+ page. If an invalid sequence of bytes is found, <b>pcre_exec()</b> returns the
1989
+ error PCRE_ERROR_BADUTF8 or, if PCRE_PARTIAL_HARD is set and the problem is a
1990
+ truncated character at the end of the subject, PCRE_ERROR_SHORTUTF8. In both
1991
+ cases, information about the precise nature of the error may also be returned
1992
+ (see the descriptions of these errors in the section entitled \fIError return
1993
+ values from\fP <b>pcre_exec()</b>
1994
+ <a href="#errorlist">below).</a>
1995
+ If <i>startoffset</i> contains a value that does not point to the start of a
1996
+ UTF-8 character (or to the end of the subject), PCRE_ERROR_BADUTF8_OFFSET is
1997
+ returned.
1998
+ </P>
1999
+ <P>
2000
+ If you already know that your subject is valid, and you want to skip these
2001
+ checks for performance reasons, you can set the PCRE_NO_UTF8_CHECK option when
2002
+ calling <b>pcre_exec()</b>. You might want to do this for the second and
2003
+ subsequent calls to <b>pcre_exec()</b> if you are making repeated calls to find
2004
+ all the matches in a single subject string. However, you should be sure that
2005
+ the value of <i>startoffset</i> points to the start of a character (or the end
2006
+ of the subject). When PCRE_NO_UTF8_CHECK is set, the effect of passing an
2007
+ invalid string as a subject or an invalid value of <i>startoffset</i> is
2008
+ undefined. Your program may crash or loop.
2009
+ <pre>
2010
+ PCRE_PARTIAL_HARD
2011
+ PCRE_PARTIAL_SOFT
2012
+ </pre>
2013
+ These options turn on the partial matching feature. For backwards
2014
+ compatibility, PCRE_PARTIAL is a synonym for PCRE_PARTIAL_SOFT. A partial match
2015
+ occurs if the end of the subject string is reached successfully, but there are
2016
+ not enough subject characters to complete the match. If this happens when
2017
+ PCRE_PARTIAL_SOFT (but not PCRE_PARTIAL_HARD) is set, matching continues by
2018
+ testing any remaining alternatives. Only if no complete match can be found is
2019
+ PCRE_ERROR_PARTIAL returned instead of PCRE_ERROR_NOMATCH. In other words,
2020
+ PCRE_PARTIAL_SOFT says that the caller is prepared to handle a partial match,
2021
+ but only if no complete match can be found.
2022
+ </P>
2023
+ <P>
2024
+ If PCRE_PARTIAL_HARD is set, it overrides PCRE_PARTIAL_SOFT. In this case, if a
2025
+ partial match is found, <b>pcre_exec()</b> immediately returns
2026
+ PCRE_ERROR_PARTIAL, without considering any other alternatives. In other words,
2027
+ when PCRE_PARTIAL_HARD is set, a partial match is considered to be more
2028
+ important that an alternative complete match.
2029
+ </P>
2030
+ <P>
2031
+ In both cases, the portion of the string that was inspected when the partial
2032
+ match was found is set as the first matching string. There is a more detailed
2033
+ discussion of partial and multi-segment matching, with examples, in the
2034
+ <a href="pcrepartial.html"><b>pcrepartial</b></a>
2035
+ documentation.
2036
+ </P>
2037
+ <br><b>
2038
+ The string to be matched by <b>pcre_exec()</b>
2039
+ </b><br>
2040
+ <P>
2041
+ The subject string is passed to <b>pcre_exec()</b> as a pointer in
2042
+ <i>subject</i>, a length in <i>length</i>, and a starting offset in
2043
+ <i>startoffset</i>. The units for <i>length</i> and <i>startoffset</i> are bytes
2044
+ for the 8-bit library, 16-bit data items for the 16-bit library, and 32-bit
2045
+ data items for the 32-bit library.
2046
+ </P>
2047
+ <P>
2048
+ If <i>startoffset</i> is negative or greater than the length of the subject,
2049
+ <b>pcre_exec()</b> returns PCRE_ERROR_BADOFFSET. When the starting offset is
2050
+ zero, the search for a match starts at the beginning of the subject, and this
2051
+ is by far the most common case. In UTF-8 or UTF-16 mode, the offset must point
2052
+ to the start of a character, or the end of the subject (in UTF-32 mode, one
2053
+ data unit equals one character, so all offsets are valid). Unlike the pattern
2054
+ string, the subject may contain binary zeroes.
2055
+ </P>
2056
+ <P>
2057
+ A non-zero starting offset is useful when searching for another match in the
2058
+ same subject by calling <b>pcre_exec()</b> again after a previous success.
2059
+ Setting <i>startoffset</i> differs from just passing over a shortened string and
2060
+ setting PCRE_NOTBOL in the case of a pattern that begins with any kind of
2061
+ lookbehind. For example, consider the pattern
2062
+ <pre>
2063
+ \Biss\B
2064
+ </pre>
2065
+ which finds occurrences of "iss" in the middle of words. (\B matches only if
2066
+ the current position in the subject is not a word boundary.) When applied to
2067
+ the string "Mississipi" the first call to <b>pcre_exec()</b> finds the first
2068
+ occurrence. If <b>pcre_exec()</b> is called again with just the remainder of the
2069
+ subject, namely "issipi", it does not match, because \B is always false at the
2070
+ start of the subject, which is deemed to be a word boundary. However, if
2071
+ <b>pcre_exec()</b> is passed the entire string again, but with <i>startoffset</i>
2072
+ set to 4, it finds the second occurrence of "iss" because it is able to look
2073
+ behind the starting point to discover that it is preceded by a letter.
2074
+ </P>
2075
+ <P>
2076
+ Finding all the matches in a subject is tricky when the pattern can match an
2077
+ empty string. It is possible to emulate Perl's /g behaviour by first trying the
2078
+ match again at the same offset, with the PCRE_NOTEMPTY_ATSTART and
2079
+ PCRE_ANCHORED options, and then if that fails, advancing the starting offset
2080
+ and trying an ordinary match again. There is some code that demonstrates how to
2081
+ do this in the
2082
+ <a href="pcredemo.html"><b>pcredemo</b></a>
2083
+ sample program. In the most general case, you have to check to see if the
2084
+ newline convention recognizes CRLF as a newline, and if so, and the current
2085
+ character is CR followed by LF, advance the starting offset by two characters
2086
+ instead of one.
2087
+ </P>
2088
+ <P>
2089
+ If a non-zero starting offset is passed when the pattern is anchored, one
2090
+ attempt to match at the given offset is made. This can only succeed if the
2091
+ pattern does not require the match to be at the start of the subject.
2092
+ </P>
2093
+ <br><b>
2094
+ How <b>pcre_exec()</b> returns captured substrings
2095
+ </b><br>
2096
+ <P>
2097
+ In general, a pattern matches a certain portion of the subject, and in
2098
+ addition, further substrings from the subject may be picked out by parts of the
2099
+ pattern. Following the usage in Jeffrey Friedl's book, this is called
2100
+ "capturing" in what follows, and the phrase "capturing subpattern" is used for
2101
+ a fragment of a pattern that picks out a substring. PCRE supports several other
2102
+ kinds of parenthesized subpattern that do not cause substrings to be captured.
2103
+ </P>
2104
+ <P>
2105
+ Captured substrings are returned to the caller via a vector of integers whose
2106
+ address is passed in <i>ovector</i>. The number of elements in the vector is
2107
+ passed in <i>ovecsize</i>, which must be a non-negative number. <b>Note</b>: this
2108
+ argument is NOT the size of <i>ovector</i> in bytes.
2109
+ </P>
2110
+ <P>
2111
+ The first two-thirds of the vector is used to pass back captured substrings,
2112
+ each substring using a pair of integers. The remaining third of the vector is
2113
+ used as workspace by <b>pcre_exec()</b> while matching capturing subpatterns,
2114
+ and is not available for passing back information. The number passed in
2115
+ <i>ovecsize</i> should always be a multiple of three. If it is not, it is
2116
+ rounded down.
2117
+ </P>
2118
+ <P>
2119
+ When a match is successful, information about captured substrings is returned
2120
+ in pairs of integers, starting at the beginning of <i>ovector</i>, and
2121
+ continuing up to two-thirds of its length at the most. The first element of
2122
+ each pair is set to the offset of the first character in a substring, and the
2123
+ second is set to the offset of the first character after the end of a
2124
+ substring. These values are always data unit offsets, even in UTF mode. They
2125
+ are byte offsets in the 8-bit library, 16-bit data item offsets in the 16-bit
2126
+ library, and 32-bit data item offsets in the 32-bit library. <b>Note</b>: they
2127
+ are not character counts.
2128
+ </P>
2129
+ <P>
2130
+ The first pair of integers, <i>ovector[0]</i> and <i>ovector[1]</i>, identify the
2131
+ portion of the subject string matched by the entire pattern. The next pair is
2132
+ used for the first capturing subpattern, and so on. The value returned by
2133
+ <b>pcre_exec()</b> is one more than the highest numbered pair that has been set.
2134
+ For example, if two substrings have been captured, the returned value is 3. If
2135
+ there are no capturing subpatterns, the return value from a successful match is
2136
+ 1, indicating that just the first pair of offsets has been set.
2137
+ </P>
2138
+ <P>
2139
+ If a capturing subpattern is matched repeatedly, it is the last portion of the
2140
+ string that it matched that is returned.
2141
+ </P>
2142
+ <P>
2143
+ If the vector is too small to hold all the captured substring offsets, it is
2144
+ used as far as possible (up to two-thirds of its length), and the function
2145
+ returns a value of zero. If neither the actual string matched nor any captured
2146
+ substrings are of interest, <b>pcre_exec()</b> may be called with <i>ovector</i>
2147
+ passed as NULL and <i>ovecsize</i> as zero. However, if the pattern contains
2148
+ back references and the <i>ovector</i> is not big enough to remember the related
2149
+ substrings, PCRE has to get additional memory for use during matching. Thus it
2150
+ is usually advisable to supply an <i>ovector</i> of reasonable size.
2151
+ </P>
2152
+ <P>
2153
+ There are some cases where zero is returned (indicating vector overflow) when
2154
+ in fact the vector is exactly the right size for the final match. For example,
2155
+ consider the pattern
2156
+ <pre>
2157
+ (a)(?:(b)c|bd)
2158
+ </pre>
2159
+ If a vector of 6 elements (allowing for only 1 captured substring) is given
2160
+ with subject string "abd", <b>pcre_exec()</b> will try to set the second
2161
+ captured string, thereby recording a vector overflow, before failing to match
2162
+ "c" and backing up to try the second alternative. The zero return, however,
2163
+ does correctly indicate that the maximum number of slots (namely 2) have been
2164
+ filled. In similar cases where there is temporary overflow, but the final
2165
+ number of used slots is actually less than the maximum, a non-zero value is
2166
+ returned.
2167
+ </P>
2168
+ <P>
2169
+ The <b>pcre_fullinfo()</b> function can be used to find out how many capturing
2170
+ subpatterns there are in a compiled pattern. The smallest size for
2171
+ <i>ovector</i> that will allow for <i>n</i> captured substrings, in addition to
2172
+ the offsets of the substring matched by the whole pattern, is (<i>n</i>+1)*3.
2173
+ </P>
2174
+ <P>
2175
+ It is possible for capturing subpattern number <i>n+1</i> to match some part of
2176
+ the subject when subpattern <i>n</i> has not been used at all. For example, if
2177
+ the string "abc" is matched against the pattern (a|(z))(bc) the return from the
2178
+ function is 4, and subpatterns 1 and 3 are matched, but 2 is not. When this
2179
+ happens, both values in the offset pairs corresponding to unused subpatterns
2180
+ are set to -1.
2181
+ </P>
2182
+ <P>
2183
+ Offset values that correspond to unused subpatterns at the end of the
2184
+ expression are also set to -1. For example, if the string "abc" is matched
2185
+ against the pattern (abc)(x(yz)?)? subpatterns 2 and 3 are not matched. The
2186
+ return from the function is 2, because the highest used capturing subpattern
2187
+ number is 1, and the offsets for for the second and third capturing subpatterns
2188
+ (assuming the vector is large enough, of course) are set to -1.
2189
+ </P>
2190
+ <P>
2191
+ <b>Note</b>: Elements in the first two-thirds of <i>ovector</i> that do not
2192
+ correspond to capturing parentheses in the pattern are never changed. That is,
2193
+ if a pattern contains <i>n</i> capturing parentheses, no more than
2194
+ <i>ovector[0]</i> to <i>ovector[2n+1]</i> are set by <b>pcre_exec()</b>. The other
2195
+ elements (in the first two-thirds) retain whatever values they previously had.
2196
+ </P>
2197
+ <P>
2198
+ Some convenience functions are provided for extracting the captured substrings
2199
+ as separate strings. These are described below.
2200
+ <a name="errorlist"></a></P>
2201
+ <br><b>
2202
+ Error return values from <b>pcre_exec()</b>
2203
+ </b><br>
2204
+ <P>
2205
+ If <b>pcre_exec()</b> fails, it returns a negative number. The following are
2206
+ defined in the header file:
2207
+ <pre>
2208
+ PCRE_ERROR_NOMATCH (-1)
2209
+ </pre>
2210
+ The subject string did not match the pattern.
2211
+ <pre>
2212
+ PCRE_ERROR_NULL (-2)
2213
+ </pre>
2214
+ Either <i>code</i> or <i>subject</i> was passed as NULL, or <i>ovector</i> was
2215
+ NULL and <i>ovecsize</i> was not zero.
2216
+ <pre>
2217
+ PCRE_ERROR_BADOPTION (-3)
2218
+ </pre>
2219
+ An unrecognized bit was set in the <i>options</i> argument.
2220
+ <pre>
2221
+ PCRE_ERROR_BADMAGIC (-4)
2222
+ </pre>
2223
+ PCRE stores a 4-byte "magic number" at the start of the compiled code, to catch
2224
+ the case when it is passed a junk pointer and to detect when a pattern that was
2225
+ compiled in an environment of one endianness is run in an environment with the
2226
+ other endianness. This is the error that PCRE gives when the magic number is
2227
+ not present.
2228
+ <pre>
2229
+ PCRE_ERROR_UNKNOWN_OPCODE (-5)
2230
+ </pre>
2231
+ While running the pattern match, an unknown item was encountered in the
2232
+ compiled pattern. This error could be caused by a bug in PCRE or by overwriting
2233
+ of the compiled pattern.
2234
+ <pre>
2235
+ PCRE_ERROR_NOMEMORY (-6)
2236
+ </pre>
2237
+ If a pattern contains back references, but the <i>ovector</i> that is passed to
2238
+ <b>pcre_exec()</b> is not big enough to remember the referenced substrings, PCRE
2239
+ gets a block of memory at the start of matching to use for this purpose. If the
2240
+ call via <b>pcre_malloc()</b> fails, this error is given. The memory is
2241
+ automatically freed at the end of matching.
2242
+ </P>
2243
+ <P>
2244
+ This error is also given if <b>pcre_stack_malloc()</b> fails in
2245
+ <b>pcre_exec()</b>. This can happen only when PCRE has been compiled with
2246
+ <b>--disable-stack-for-recursion</b>.
2247
+ <pre>
2248
+ PCRE_ERROR_NOSUBSTRING (-7)
2249
+ </pre>
2250
+ This error is used by the <b>pcre_copy_substring()</b>,
2251
+ <b>pcre_get_substring()</b>, and <b>pcre_get_substring_list()</b> functions (see
2252
+ below). It is never returned by <b>pcre_exec()</b>.
2253
+ <pre>
2254
+ PCRE_ERROR_MATCHLIMIT (-8)
2255
+ </pre>
2256
+ The backtracking limit, as specified by the <i>match_limit</i> field in a
2257
+ <b>pcre_extra</b> structure (or defaulted) was reached. See the description
2258
+ above.
2259
+ <pre>
2260
+ PCRE_ERROR_CALLOUT (-9)
2261
+ </pre>
2262
+ This error is never generated by <b>pcre_exec()</b> itself. It is provided for
2263
+ use by callout functions that want to yield a distinctive error code. See the
2264
+ <a href="pcrecallout.html"><b>pcrecallout</b></a>
2265
+ documentation for details.
2266
+ <pre>
2267
+ PCRE_ERROR_BADUTF8 (-10)
2268
+ </pre>
2269
+ A string that contains an invalid UTF-8 byte sequence was passed as a subject,
2270
+ and the PCRE_NO_UTF8_CHECK option was not set. If the size of the output vector
2271
+ (<i>ovecsize</i>) is at least 2, the byte offset to the start of the the invalid
2272
+ UTF-8 character is placed in the first element, and a reason code is placed in
2273
+ the second element. The reason codes are listed in the
2274
+ <a href="#badutf8reasons">following section.</a>
2275
+ For backward compatibility, if PCRE_PARTIAL_HARD is set and the problem is a
2276
+ truncated UTF-8 character at the end of the subject (reason codes 1 to 5),
2277
+ PCRE_ERROR_SHORTUTF8 is returned instead of PCRE_ERROR_BADUTF8.
2278
+ <pre>
2279
+ PCRE_ERROR_BADUTF8_OFFSET (-11)
2280
+ </pre>
2281
+ The UTF-8 byte sequence that was passed as a subject was checked and found to
2282
+ be valid (the PCRE_NO_UTF8_CHECK option was not set), but the value of
2283
+ <i>startoffset</i> did not point to the beginning of a UTF-8 character or the
2284
+ end of the subject.
2285
+ <pre>
2286
+ PCRE_ERROR_PARTIAL (-12)
2287
+ </pre>
2288
+ The subject string did not match, but it did match partially. See the
2289
+ <a href="pcrepartial.html"><b>pcrepartial</b></a>
2290
+ documentation for details of partial matching.
2291
+ <pre>
2292
+ PCRE_ERROR_BADPARTIAL (-13)
2293
+ </pre>
2294
+ This code is no longer in use. It was formerly returned when the PCRE_PARTIAL
2295
+ option was used with a compiled pattern containing items that were not
2296
+ supported for partial matching. From release 8.00 onwards, there are no
2297
+ restrictions on partial matching.
2298
+ <pre>
2299
+ PCRE_ERROR_INTERNAL (-14)
2300
+ </pre>
2301
+ An unexpected internal error has occurred. This error could be caused by a bug
2302
+ in PCRE or by overwriting of the compiled pattern.
2303
+ <pre>
2304
+ PCRE_ERROR_BADCOUNT (-15)
2305
+ </pre>
2306
+ This error is given if the value of the <i>ovecsize</i> argument is negative.
2307
+ <pre>
2308
+ PCRE_ERROR_RECURSIONLIMIT (-21)
2309
+ </pre>
2310
+ The internal recursion limit, as specified by the <i>match_limit_recursion</i>
2311
+ field in a <b>pcre_extra</b> structure (or defaulted) was reached. See the
2312
+ description above.
2313
+ <pre>
2314
+ PCRE_ERROR_BADNEWLINE (-23)
2315
+ </pre>
2316
+ An invalid combination of PCRE_NEWLINE_<i>xxx</i> options was given.
2317
+ <pre>
2318
+ PCRE_ERROR_BADOFFSET (-24)
2319
+ </pre>
2320
+ The value of <i>startoffset</i> was negative or greater than the length of the
2321
+ subject, that is, the value in <i>length</i>.
2322
+ <pre>
2323
+ PCRE_ERROR_SHORTUTF8 (-25)
2324
+ </pre>
2325
+ This error is returned instead of PCRE_ERROR_BADUTF8 when the subject string
2326
+ ends with a truncated UTF-8 character and the PCRE_PARTIAL_HARD option is set.
2327
+ Information about the failure is returned as for PCRE_ERROR_BADUTF8. It is in
2328
+ fact sufficient to detect this case, but this special error code for
2329
+ PCRE_PARTIAL_HARD precedes the implementation of returned information; it is
2330
+ retained for backwards compatibility.
2331
+ <pre>
2332
+ PCRE_ERROR_RECURSELOOP (-26)
2333
+ </pre>
2334
+ This error is returned when <b>pcre_exec()</b> detects a recursion loop within
2335
+ the pattern. Specifically, it means that either the whole pattern or a
2336
+ subpattern has been called recursively for the second time at the same position
2337
+ in the subject string. Some simple patterns that might do this are detected and
2338
+ faulted at compile time, but more complicated cases, in particular mutual
2339
+ recursions between two different subpatterns, cannot be detected until run
2340
+ time.
2341
+ <pre>
2342
+ PCRE_ERROR_JIT_STACKLIMIT (-27)
2343
+ </pre>
2344
+ This error is returned when a pattern that was successfully studied using a
2345
+ JIT compile option is being matched, but the memory available for the
2346
+ just-in-time processing stack is not large enough. See the
2347
+ <a href="pcrejit.html"><b>pcrejit</b></a>
2348
+ documentation for more details.
2349
+ <pre>
2350
+ PCRE_ERROR_BADMODE (-28)
2351
+ </pre>
2352
+ This error is given if a pattern that was compiled by the 8-bit library is
2353
+ passed to a 16-bit or 32-bit library function, or vice versa.
2354
+ <pre>
2355
+ PCRE_ERROR_BADENDIANNESS (-29)
2356
+ </pre>
2357
+ This error is given if a pattern that was compiled and saved is reloaded on a
2358
+ host with different endianness. The utility function
2359
+ <b>pcre_pattern_to_host_byte_order()</b> can be used to convert such a pattern
2360
+ so that it runs on the new host.
2361
+ <pre>
2362
+ PCRE_ERROR_JIT_BADOPTION
2363
+ </pre>
2364
+ This error is returned when a pattern that was successfully studied using a JIT
2365
+ compile option is being matched, but the matching mode (partial or complete
2366
+ match) does not correspond to any JIT compilation mode. When the JIT fast path
2367
+ function is used, this error may be also given for invalid options. See the
2368
+ <a href="pcrejit.html"><b>pcrejit</b></a>
2369
+ documentation for more details.
2370
+ <pre>
2371
+ PCRE_ERROR_BADLENGTH (-32)
2372
+ </pre>
2373
+ This error is given if <b>pcre_exec()</b> is called with a negative value for
2374
+ the <i>length</i> argument.
2375
+ </P>
2376
+ <P>
2377
+ Error numbers -16 to -20, -22, and 30 are not used by <b>pcre_exec()</b>.
2378
+ <a name="badutf8reasons"></a></P>
2379
+ <br><b>
2380
+ Reason codes for invalid UTF-8 strings
2381
+ </b><br>
2382
+ <P>
2383
+ This section applies only to the 8-bit library. The corresponding information
2384
+ for the 16-bit and 32-bit libraries is given in the
2385
+ <a href="pcre16.html"><b>pcre16</b></a>
2386
+ and
2387
+ <a href="pcre32.html"><b>pcre32</b></a>
2388
+ pages.
2389
+ </P>
2390
+ <P>
2391
+ When <b>pcre_exec()</b> returns either PCRE_ERROR_BADUTF8 or
2392
+ PCRE_ERROR_SHORTUTF8, and the size of the output vector (<i>ovecsize</i>) is at
2393
+ least 2, the offset of the start of the invalid UTF-8 character is placed in
2394
+ the first output vector element (<i>ovector[0]</i>) and a reason code is placed
2395
+ in the second element (<i>ovector[1]</i>). The reason codes are given names in
2396
+ the <b>pcre.h</b> header file:
2397
+ <pre>
2398
+ PCRE_UTF8_ERR1
2399
+ PCRE_UTF8_ERR2
2400
+ PCRE_UTF8_ERR3
2401
+ PCRE_UTF8_ERR4
2402
+ PCRE_UTF8_ERR5
2403
+ </pre>
2404
+ The string ends with a truncated UTF-8 character; the code specifies how many
2405
+ bytes are missing (1 to 5). Although RFC 3629 restricts UTF-8 characters to be
2406
+ no longer than 4 bytes, the encoding scheme (originally defined by RFC 2279)
2407
+ allows for up to 6 bytes, and this is checked first; hence the possibility of
2408
+ 4 or 5 missing bytes.
2409
+ <pre>
2410
+ PCRE_UTF8_ERR6
2411
+ PCRE_UTF8_ERR7
2412
+ PCRE_UTF8_ERR8
2413
+ PCRE_UTF8_ERR9
2414
+ PCRE_UTF8_ERR10
2415
+ </pre>
2416
+ The two most significant bits of the 2nd, 3rd, 4th, 5th, or 6th byte of the
2417
+ character do not have the binary value 0b10 (that is, either the most
2418
+ significant bit is 0, or the next bit is 1).
2419
+ <pre>
2420
+ PCRE_UTF8_ERR11
2421
+ PCRE_UTF8_ERR12
2422
+ </pre>
2423
+ A character that is valid by the RFC 2279 rules is either 5 or 6 bytes long;
2424
+ these code points are excluded by RFC 3629.
2425
+ <pre>
2426
+ PCRE_UTF8_ERR13
2427
+ </pre>
2428
+ A 4-byte character has a value greater than 0x10fff; these code points are
2429
+ excluded by RFC 3629.
2430
+ <pre>
2431
+ PCRE_UTF8_ERR14
2432
+ </pre>
2433
+ A 3-byte character has a value in the range 0xd800 to 0xdfff; this range of
2434
+ code points are reserved by RFC 3629 for use with UTF-16, and so are excluded
2435
+ from UTF-8.
2436
+ <pre>
2437
+ PCRE_UTF8_ERR15
2438
+ PCRE_UTF8_ERR16
2439
+ PCRE_UTF8_ERR17
2440
+ PCRE_UTF8_ERR18
2441
+ PCRE_UTF8_ERR19
2442
+ </pre>
2443
+ A 2-, 3-, 4-, 5-, or 6-byte character is "overlong", that is, it codes for a
2444
+ value that can be represented by fewer bytes, which is invalid. For example,
2445
+ the two bytes 0xc0, 0xae give the value 0x2e, whose correct coding uses just
2446
+ one byte.
2447
+ <pre>
2448
+ PCRE_UTF8_ERR20
2449
+ </pre>
2450
+ The two most significant bits of the first byte of a character have the binary
2451
+ value 0b10 (that is, the most significant bit is 1 and the second is 0). Such a
2452
+ byte can only validly occur as the second or subsequent byte of a multi-byte
2453
+ character.
2454
+ <pre>
2455
+ PCRE_UTF8_ERR21
2456
+ </pre>
2457
+ The first byte of a character has the value 0xfe or 0xff. These values can
2458
+ never occur in a valid UTF-8 string.
2459
+ <pre>
2460
+ PCRE_UTF8_ERR22
2461
+ </pre>
2462
+ This error code was formerly used when the presence of a so-called
2463
+ "non-character" caused an error. Unicode corrigendum #9 makes it clear that
2464
+ such characters should not cause a string to be rejected, and so this code is
2465
+ no longer in use and is never returned.
2466
+ </P>
2467
+ <br><a name="SEC18" href="#TOC1">EXTRACTING CAPTURED SUBSTRINGS BY NUMBER</a><br>
2468
+ <P>
2469
+ <b>int pcre_copy_substring(const char *<i>subject</i>, int *<i>ovector</i>,</b>
2470
+ <b> int <i>stringcount</i>, int <i>stringnumber</i>, char *<i>buffer</i>,</b>
2471
+ <b> int <i>buffersize</i>);</b>
2472
+ <br>
2473
+ <br>
2474
+ <b>int pcre_get_substring(const char *<i>subject</i>, int *<i>ovector</i>,</b>
2475
+ <b> int <i>stringcount</i>, int <i>stringnumber</i>,</b>
2476
+ <b> const char **<i>stringptr</i>);</b>
2477
+ <br>
2478
+ <br>
2479
+ <b>int pcre_get_substring_list(const char *<i>subject</i>,</b>
2480
+ <b> int *<i>ovector</i>, int <i>stringcount</i>, const char ***<i>listptr</i>);</b>
2481
+ </P>
2482
+ <P>
2483
+ Captured substrings can be accessed directly by using the offsets returned by
2484
+ <b>pcre_exec()</b> in <i>ovector</i>. For convenience, the functions
2485
+ <b>pcre_copy_substring()</b>, <b>pcre_get_substring()</b>, and
2486
+ <b>pcre_get_substring_list()</b> are provided for extracting captured substrings
2487
+ as new, separate, zero-terminated strings. These functions identify substrings
2488
+ by number. The next section describes functions for extracting named
2489
+ substrings.
2490
+ </P>
2491
+ <P>
2492
+ A substring that contains a binary zero is correctly extracted and has a
2493
+ further zero added on the end, but the result is not, of course, a C string.
2494
+ However, you can process such a string by referring to the length that is
2495
+ returned by <b>pcre_copy_substring()</b> and <b>pcre_get_substring()</b>.
2496
+ Unfortunately, the interface to <b>pcre_get_substring_list()</b> is not adequate
2497
+ for handling strings containing binary zeros, because the end of the final
2498
+ string is not independently indicated.
2499
+ </P>
2500
+ <P>
2501
+ The first three arguments are the same for all three of these functions:
2502
+ <i>subject</i> is the subject string that has just been successfully matched,
2503
+ <i>ovector</i> is a pointer to the vector of integer offsets that was passed to
2504
+ <b>pcre_exec()</b>, and <i>stringcount</i> is the number of substrings that were
2505
+ captured by the match, including the substring that matched the entire regular
2506
+ expression. This is the value returned by <b>pcre_exec()</b> if it is greater
2507
+ than zero. If <b>pcre_exec()</b> returned zero, indicating that it ran out of
2508
+ space in <i>ovector</i>, the value passed as <i>stringcount</i> should be the
2509
+ number of elements in the vector divided by three.
2510
+ </P>
2511
+ <P>
2512
+ The functions <b>pcre_copy_substring()</b> and <b>pcre_get_substring()</b>
2513
+ extract a single substring, whose number is given as <i>stringnumber</i>. A
2514
+ value of zero extracts the substring that matched the entire pattern, whereas
2515
+ higher values extract the captured substrings. For <b>pcre_copy_substring()</b>,
2516
+ the string is placed in <i>buffer</i>, whose length is given by
2517
+ <i>buffersize</i>, while for <b>pcre_get_substring()</b> a new block of memory is
2518
+ obtained via <b>pcre_malloc</b>, and its address is returned via
2519
+ <i>stringptr</i>. The yield of the function is the length of the string, not
2520
+ including the terminating zero, or one of these error codes:
2521
+ <pre>
2522
+ PCRE_ERROR_NOMEMORY (-6)
2523
+ </pre>
2524
+ The buffer was too small for <b>pcre_copy_substring()</b>, or the attempt to get
2525
+ memory failed for <b>pcre_get_substring()</b>.
2526
+ <pre>
2527
+ PCRE_ERROR_NOSUBSTRING (-7)
2528
+ </pre>
2529
+ There is no substring whose number is <i>stringnumber</i>.
2530
+ </P>
2531
+ <P>
2532
+ The <b>pcre_get_substring_list()</b> function extracts all available substrings
2533
+ and builds a list of pointers to them. All this is done in a single block of
2534
+ memory that is obtained via <b>pcre_malloc</b>. The address of the memory block
2535
+ is returned via <i>listptr</i>, which is also the start of the list of string
2536
+ pointers. The end of the list is marked by a NULL pointer. The yield of the
2537
+ function is zero if all went well, or the error code
2538
+ <pre>
2539
+ PCRE_ERROR_NOMEMORY (-6)
2540
+ </pre>
2541
+ if the attempt to get the memory block failed.
2542
+ </P>
2543
+ <P>
2544
+ When any of these functions encounter a substring that is unset, which can
2545
+ happen when capturing subpattern number <i>n+1</i> matches some part of the
2546
+ subject, but subpattern <i>n</i> has not been used at all, they return an empty
2547
+ string. This can be distinguished from a genuine zero-length substring by
2548
+ inspecting the appropriate offset in <i>ovector</i>, which is negative for unset
2549
+ substrings.
2550
+ </P>
2551
+ <P>
2552
+ The two convenience functions <b>pcre_free_substring()</b> and
2553
+ <b>pcre_free_substring_list()</b> can be used to free the memory returned by
2554
+ a previous call of <b>pcre_get_substring()</b> or
2555
+ <b>pcre_get_substring_list()</b>, respectively. They do nothing more than call
2556
+ the function pointed to by <b>pcre_free</b>, which of course could be called
2557
+ directly from a C program. However, PCRE is used in some situations where it is
2558
+ linked via a special interface to another programming language that cannot use
2559
+ <b>pcre_free</b> directly; it is for these cases that the functions are
2560
+ provided.
2561
+ </P>
2562
+ <br><a name="SEC19" href="#TOC1">EXTRACTING CAPTURED SUBSTRINGS BY NAME</a><br>
2563
+ <P>
2564
+ <b>int pcre_get_stringnumber(const pcre *<i>code</i>,</b>
2565
+ <b> const char *<i>name</i>);</b>
2566
+ <br>
2567
+ <br>
2568
+ <b>int pcre_copy_named_substring(const pcre *<i>code</i>,</b>
2569
+ <b> const char *<i>subject</i>, int *<i>ovector</i>,</b>
2570
+ <b> int <i>stringcount</i>, const char *<i>stringname</i>,</b>
2571
+ <b> char *<i>buffer</i>, int <i>buffersize</i>);</b>
2572
+ <br>
2573
+ <br>
2574
+ <b>int pcre_get_named_substring(const pcre *<i>code</i>,</b>
2575
+ <b> const char *<i>subject</i>, int *<i>ovector</i>,</b>
2576
+ <b> int <i>stringcount</i>, const char *<i>stringname</i>,</b>
2577
+ <b> const char **<i>stringptr</i>);</b>
2578
+ </P>
2579
+ <P>
2580
+ To extract a substring by name, you first have to find associated number.
2581
+ For example, for this pattern
2582
+ <pre>
2583
+ (a+)b(?&#60;xxx&#62;\d+)...
2584
+ </pre>
2585
+ the number of the subpattern called "xxx" is 2. If the name is known to be
2586
+ unique (PCRE_DUPNAMES was not set), you can find the number from the name by
2587
+ calling <b>pcre_get_stringnumber()</b>. The first argument is the compiled
2588
+ pattern, and the second is the name. The yield of the function is the
2589
+ subpattern number, or PCRE_ERROR_NOSUBSTRING (-7) if there is no subpattern of
2590
+ that name.
2591
+ </P>
2592
+ <P>
2593
+ Given the number, you can extract the substring directly, or use one of the
2594
+ functions described in the previous section. For convenience, there are also
2595
+ two functions that do the whole job.
2596
+ </P>
2597
+ <P>
2598
+ Most of the arguments of <b>pcre_copy_named_substring()</b> and
2599
+ <b>pcre_get_named_substring()</b> are the same as those for the similarly named
2600
+ functions that extract by number. As these are described in the previous
2601
+ section, they are not re-described here. There are just two differences:
2602
+ </P>
2603
+ <P>
2604
+ First, instead of a substring number, a substring name is given. Second, there
2605
+ is an extra argument, given at the start, which is a pointer to the compiled
2606
+ pattern. This is needed in order to gain access to the name-to-number
2607
+ translation table.
2608
+ </P>
2609
+ <P>
2610
+ These functions call <b>pcre_get_stringnumber()</b>, and if it succeeds, they
2611
+ then call <b>pcre_copy_substring()</b> or <b>pcre_get_substring()</b>, as
2612
+ appropriate. <b>NOTE:</b> If PCRE_DUPNAMES is set and there are duplicate names,
2613
+ the behaviour may not be what you want (see the next section).
2614
+ </P>
2615
+ <P>
2616
+ <b>Warning:</b> If the pattern uses the (?| feature to set up multiple
2617
+ subpatterns with the same number, as described in the
2618
+ <a href="pcrepattern.html#dupsubpatternnumber">section on duplicate subpattern numbers</a>
2619
+ in the
2620
+ <a href="pcrepattern.html"><b>pcrepattern</b></a>
2621
+ page, you cannot use names to distinguish the different subpatterns, because
2622
+ names are not included in the compiled code. The matching process uses only
2623
+ numbers. For this reason, the use of different names for subpatterns of the
2624
+ same number causes an error at compile time.
2625
+ </P>
2626
+ <br><a name="SEC20" href="#TOC1">DUPLICATE SUBPATTERN NAMES</a><br>
2627
+ <P>
2628
+ <b>int pcre_get_stringtable_entries(const pcre *<i>code</i>,</b>
2629
+ <b> const char *<i>name</i>, char **<i>first</i>, char **<i>last</i>);</b>
2630
+ </P>
2631
+ <P>
2632
+ When a pattern is compiled with the PCRE_DUPNAMES option, names for subpatterns
2633
+ are not required to be unique. (Duplicate names are always allowed for
2634
+ subpatterns with the same number, created by using the (?| feature. Indeed, if
2635
+ such subpatterns are named, they are required to use the same names.)
2636
+ </P>
2637
+ <P>
2638
+ Normally, patterns with duplicate names are such that in any one match, only
2639
+ one of the named subpatterns participates. An example is shown in the
2640
+ <a href="pcrepattern.html"><b>pcrepattern</b></a>
2641
+ documentation.
2642
+ </P>
2643
+ <P>
2644
+ When duplicates are present, <b>pcre_copy_named_substring()</b> and
2645
+ <b>pcre_get_named_substring()</b> return the first substring corresponding to
2646
+ the given name that is set. If none are set, PCRE_ERROR_NOSUBSTRING (-7) is
2647
+ returned; no data is returned. The <b>pcre_get_stringnumber()</b> function
2648
+ returns one of the numbers that are associated with the name, but it is not
2649
+ defined which it is.
2650
+ </P>
2651
+ <P>
2652
+ If you want to get full details of all captured substrings for a given name,
2653
+ you must use the <b>pcre_get_stringtable_entries()</b> function. The first
2654
+ argument is the compiled pattern, and the second is the name. The third and
2655
+ fourth are pointers to variables which are updated by the function. After it
2656
+ has run, they point to the first and last entries in the name-to-number table
2657
+ for the given name. The function itself returns the length of each entry, or
2658
+ PCRE_ERROR_NOSUBSTRING (-7) if there are none. The format of the table is
2659
+ described above in the section entitled <i>Information about a pattern</i>
2660
+ <a href="#infoaboutpattern">above.</a>
2661
+ Given all the relevant entries for the name, you can extract each of their
2662
+ numbers, and hence the captured data, if any.
2663
+ </P>
2664
+ <br><a name="SEC21" href="#TOC1">FINDING ALL POSSIBLE MATCHES</a><br>
2665
+ <P>
2666
+ The traditional matching function uses a similar algorithm to Perl, which stops
2667
+ when it finds the first match, starting at a given point in the subject. If you
2668
+ want to find all possible matches, or the longest possible match, consider
2669
+ using the alternative matching function (see below) instead. If you cannot use
2670
+ the alternative function, but still need to find all possible matches, you
2671
+ can kludge it up by making use of the callout facility, which is described in
2672
+ the
2673
+ <a href="pcrecallout.html"><b>pcrecallout</b></a>
2674
+ documentation.
2675
+ </P>
2676
+ <P>
2677
+ What you have to do is to insert a callout right at the end of the pattern.
2678
+ When your callout function is called, extract and save the current matched
2679
+ substring. Then return 1, which forces <b>pcre_exec()</b> to backtrack and try
2680
+ other alternatives. Ultimately, when it runs out of matches, <b>pcre_exec()</b>
2681
+ will yield PCRE_ERROR_NOMATCH.
2682
+ </P>
2683
+ <br><a name="SEC22" href="#TOC1">OBTAINING AN ESTIMATE OF STACK USAGE</a><br>
2684
+ <P>
2685
+ Matching certain patterns using <b>pcre_exec()</b> can use a lot of process
2686
+ stack, which in certain environments can be rather limited in size. Some users
2687
+ find it helpful to have an estimate of the amount of stack that is used by
2688
+ <b>pcre_exec()</b>, to help them set recursion limits, as described in the
2689
+ <a href="pcrestack.html"><b>pcrestack</b></a>
2690
+ documentation. The estimate that is output by <b>pcretest</b> when called with
2691
+ the <b>-m</b> and <b>-C</b> options is obtained by calling <b>pcre_exec</b> with
2692
+ the values NULL, NULL, NULL, -999, and -999 for its first five arguments.
2693
+ </P>
2694
+ <P>
2695
+ Normally, if its first argument is NULL, <b>pcre_exec()</b> immediately returns
2696
+ the negative error code PCRE_ERROR_NULL, but with this special combination of
2697
+ arguments, it returns instead a negative number whose absolute value is the
2698
+ approximate stack frame size in bytes. (A negative number is used so that it is
2699
+ clear that no match has happened.) The value is approximate because in some
2700
+ cases, recursive calls to <b>pcre_exec()</b> occur when there are one or two
2701
+ additional variables on the stack.
2702
+ </P>
2703
+ <P>
2704
+ If PCRE has been compiled to use the heap instead of the stack for recursion,
2705
+ the value returned is the size of each block that is obtained from the heap.
2706
+ <a name="dfamatch"></a></P>
2707
+ <br><a name="SEC23" href="#TOC1">MATCHING A PATTERN: THE ALTERNATIVE FUNCTION</a><br>
2708
+ <P>
2709
+ <b>int pcre_dfa_exec(const pcre *<i>code</i>, const pcre_extra *<i>extra</i>,</b>
2710
+ <b> const char *<i>subject</i>, int <i>length</i>, int <i>startoffset</i>,</b>
2711
+ <b> int <i>options</i>, int *<i>ovector</i>, int <i>ovecsize</i>,</b>
2712
+ <b> int *<i>workspace</i>, int <i>wscount</i>);</b>
2713
+ </P>
2714
+ <P>
2715
+ The function <b>pcre_dfa_exec()</b> is called to match a subject string against
2716
+ a compiled pattern, using a matching algorithm that scans the subject string
2717
+ just once, and does not backtrack. This has different characteristics to the
2718
+ normal algorithm, and is not compatible with Perl. Some of the features of PCRE
2719
+ patterns are not supported. Nevertheless, there are times when this kind of
2720
+ matching can be useful. For a discussion of the two matching algorithms, and a
2721
+ list of features that <b>pcre_dfa_exec()</b> does not support, see the
2722
+ <a href="pcrematching.html"><b>pcrematching</b></a>
2723
+ documentation.
2724
+ </P>
2725
+ <P>
2726
+ The arguments for the <b>pcre_dfa_exec()</b> function are the same as for
2727
+ <b>pcre_exec()</b>, plus two extras. The <i>ovector</i> argument is used in a
2728
+ different way, and this is described below. The other common arguments are used
2729
+ in the same way as for <b>pcre_exec()</b>, so their description is not repeated
2730
+ here.
2731
+ </P>
2732
+ <P>
2733
+ The two additional arguments provide workspace for the function. The workspace
2734
+ vector should contain at least 20 elements. It is used for keeping track of
2735
+ multiple paths through the pattern tree. More workspace will be needed for
2736
+ patterns and subjects where there are a lot of potential matches.
2737
+ </P>
2738
+ <P>
2739
+ Here is an example of a simple call to <b>pcre_dfa_exec()</b>:
2740
+ <pre>
2741
+ int rc;
2742
+ int ovector[10];
2743
+ int wspace[20];
2744
+ rc = pcre_dfa_exec(
2745
+ re, /* result of pcre_compile() */
2746
+ NULL, /* we didn't study the pattern */
2747
+ "some string", /* the subject string */
2748
+ 11, /* the length of the subject string */
2749
+ 0, /* start at offset 0 in the subject */
2750
+ 0, /* default options */
2751
+ ovector, /* vector of integers for substring information */
2752
+ 10, /* number of elements (NOT size in bytes) */
2753
+ wspace, /* working space vector */
2754
+ 20); /* number of elements (NOT size in bytes) */
2755
+ </PRE>
2756
+ </P>
2757
+ <br><b>
2758
+ Option bits for <b>pcre_dfa_exec()</b>
2759
+ </b><br>
2760
+ <P>
2761
+ The unused bits of the <i>options</i> argument for <b>pcre_dfa_exec()</b> must be
2762
+ zero. The only bits that may be set are PCRE_ANCHORED, PCRE_NEWLINE_<i>xxx</i>,
2763
+ PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY, PCRE_NOTEMPTY_ATSTART,
2764
+ PCRE_NO_UTF8_CHECK, PCRE_BSR_ANYCRLF, PCRE_BSR_UNICODE, PCRE_NO_START_OPTIMIZE,
2765
+ PCRE_PARTIAL_HARD, PCRE_PARTIAL_SOFT, PCRE_DFA_SHORTEST, and PCRE_DFA_RESTART.
2766
+ All but the last four of these are exactly the same as for <b>pcre_exec()</b>,
2767
+ so their description is not repeated here.
2768
+ <pre>
2769
+ PCRE_PARTIAL_HARD
2770
+ PCRE_PARTIAL_SOFT
2771
+ </pre>
2772
+ These have the same general effect as they do for <b>pcre_exec()</b>, but the
2773
+ details are slightly different. When PCRE_PARTIAL_HARD is set for
2774
+ <b>pcre_dfa_exec()</b>, it returns PCRE_ERROR_PARTIAL if the end of the subject
2775
+ is reached and there is still at least one matching possibility that requires
2776
+ additional characters. This happens even if some complete matches have also
2777
+ been found. When PCRE_PARTIAL_SOFT is set, the return code PCRE_ERROR_NOMATCH
2778
+ is converted into PCRE_ERROR_PARTIAL if the end of the subject is reached,
2779
+ there have been no complete matches, but there is still at least one matching
2780
+ possibility. The portion of the string that was inspected when the longest
2781
+ partial match was found is set as the first matching string in both cases.
2782
+ There is a more detailed discussion of partial and multi-segment matching, with
2783
+ examples, in the
2784
+ <a href="pcrepartial.html"><b>pcrepartial</b></a>
2785
+ documentation.
2786
+ <pre>
2787
+ PCRE_DFA_SHORTEST
2788
+ </pre>
2789
+ Setting the PCRE_DFA_SHORTEST option causes the matching algorithm to stop as
2790
+ soon as it has found one match. Because of the way the alternative algorithm
2791
+ works, this is necessarily the shortest possible match at the first possible
2792
+ matching point in the subject string.
2793
+ <pre>
2794
+ PCRE_DFA_RESTART
2795
+ </pre>
2796
+ When <b>pcre_dfa_exec()</b> returns a partial match, it is possible to call it
2797
+ again, with additional subject characters, and have it continue with the same
2798
+ match. The PCRE_DFA_RESTART option requests this action; when it is set, the
2799
+ <i>workspace</i> and <i>wscount</i> options must reference the same vector as
2800
+ before because data about the match so far is left in them after a partial
2801
+ match. There is more discussion of this facility in the
2802
+ <a href="pcrepartial.html"><b>pcrepartial</b></a>
2803
+ documentation.
2804
+ </P>
2805
+ <br><b>
2806
+ Successful returns from <b>pcre_dfa_exec()</b>
2807
+ </b><br>
2808
+ <P>
2809
+ When <b>pcre_dfa_exec()</b> succeeds, it may have matched more than one
2810
+ substring in the subject. Note, however, that all the matches from one run of
2811
+ the function start at the same point in the subject. The shorter matches are
2812
+ all initial substrings of the longer matches. For example, if the pattern
2813
+ <pre>
2814
+ &#60;.*&#62;
2815
+ </pre>
2816
+ is matched against the string
2817
+ <pre>
2818
+ This is &#60;something&#62; &#60;something else&#62; &#60;something further&#62; no more
2819
+ </pre>
2820
+ the three matched strings are
2821
+ <pre>
2822
+ &#60;something&#62;
2823
+ &#60;something&#62; &#60;something else&#62;
2824
+ &#60;something&#62; &#60;something else&#62; &#60;something further&#62;
2825
+ </pre>
2826
+ On success, the yield of the function is a number greater than zero, which is
2827
+ the number of matched substrings. The substrings themselves are returned in
2828
+ <i>ovector</i>. Each string uses two elements; the first is the offset to the
2829
+ start, and the second is the offset to the end. In fact, all the strings have
2830
+ the same start offset. (Space could have been saved by giving this only once,
2831
+ but it was decided to retain some compatibility with the way <b>pcre_exec()</b>
2832
+ returns data, even though the meaning of the strings is different.)
2833
+ </P>
2834
+ <P>
2835
+ The strings are returned in reverse order of length; that is, the longest
2836
+ matching string is given first. If there were too many matches to fit into
2837
+ <i>ovector</i>, the yield of the function is zero, and the vector is filled with
2838
+ the longest matches. Unlike <b>pcre_exec()</b>, <b>pcre_dfa_exec()</b> can use
2839
+ the entire <i>ovector</i> for returning matched strings.
2840
+ </P>
2841
+ <P>
2842
+ NOTE: PCRE's "auto-possessification" optimization usually applies to character
2843
+ repeats at the end of a pattern (as well as internally). For example, the
2844
+ pattern "a\d+" is compiled as if it were "a\d++" because there is no point
2845
+ even considering the possibility of backtracking into the repeated digits. For
2846
+ DFA matching, this means that only one possible match is found. If you really
2847
+ do want multiple matches in such cases, either use an ungreedy repeat
2848
+ ("a\d+?") or set the PCRE_NO_AUTO_POSSESS option when compiling.
2849
+ </P>
2850
+ <br><b>
2851
+ Error returns from <b>pcre_dfa_exec()</b>
2852
+ </b><br>
2853
+ <P>
2854
+ The <b>pcre_dfa_exec()</b> function returns a negative number when it fails.
2855
+ Many of the errors are the same as for <b>pcre_exec()</b>, and these are
2856
+ described
2857
+ <a href="#errorlist">above.</a>
2858
+ There are in addition the following errors that are specific to
2859
+ <b>pcre_dfa_exec()</b>:
2860
+ <pre>
2861
+ PCRE_ERROR_DFA_UITEM (-16)
2862
+ </pre>
2863
+ This return is given if <b>pcre_dfa_exec()</b> encounters an item in the pattern
2864
+ that it does not support, for instance, the use of \C or a back reference.
2865
+ <pre>
2866
+ PCRE_ERROR_DFA_UCOND (-17)
2867
+ </pre>
2868
+ This return is given if <b>pcre_dfa_exec()</b> encounters a condition item that
2869
+ uses a back reference for the condition, or a test for recursion in a specific
2870
+ group. These are not supported.
2871
+ <pre>
2872
+ PCRE_ERROR_DFA_UMLIMIT (-18)
2873
+ </pre>
2874
+ This return is given if <b>pcre_dfa_exec()</b> is called with an <i>extra</i>
2875
+ block that contains a setting of the <i>match_limit</i> or
2876
+ <i>match_limit_recursion</i> fields. This is not supported (these fields are
2877
+ meaningless for DFA matching).
2878
+ <pre>
2879
+ PCRE_ERROR_DFA_WSSIZE (-19)
2880
+ </pre>
2881
+ This return is given if <b>pcre_dfa_exec()</b> runs out of space in the
2882
+ <i>workspace</i> vector.
2883
+ <pre>
2884
+ PCRE_ERROR_DFA_RECURSE (-20)
2885
+ </pre>
2886
+ When a recursive subpattern is processed, the matching function calls itself
2887
+ recursively, using private vectors for <i>ovector</i> and <i>workspace</i>. This
2888
+ error is given if the output vector is not large enough. This should be
2889
+ extremely rare, as a vector of size 1000 is used.
2890
+ <pre>
2891
+ PCRE_ERROR_DFA_BADRESTART (-30)
2892
+ </pre>
2893
+ When <b>pcre_dfa_exec()</b> is called with the <b>PCRE_DFA_RESTART</b> option,
2894
+ some plausibility checks are made on the contents of the workspace, which
2895
+ should contain data about the previous partial match. If any of these checks
2896
+ fail, this error is given.
2897
+ </P>
2898
+ <br><a name="SEC24" href="#TOC1">SEE ALSO</a><br>
2899
+ <P>
2900
+ <b>pcre16</b>(3), <b>pcre32</b>(3), <b>pcrebuild</b>(3), <b>pcrecallout</b>(3),
2901
+ <b>pcrecpp(3)</b>(3), <b>pcrematching</b>(3), <b>pcrepartial</b>(3),
2902
+ <b>pcreposix</b>(3), <b>pcreprecompile</b>(3), <b>pcresample</b>(3),
2903
+ <b>pcrestack</b>(3).
2904
+ </P>
2905
+ <br><a name="SEC25" href="#TOC1">AUTHOR</a><br>
2906
+ <P>
2907
+ Philip Hazel
2908
+ <br>
2909
+ University Computing Service
2910
+ <br>
2911
+ Cambridge CB2 3QH, England.
2912
+ <br>
2913
+ </P>
2914
+ <br><a name="SEC26" href="#TOC1">REVISION</a><br>
2915
+ <P>
2916
+ Last updated: 09 February 2014
2917
+ <br>
2918
+ Copyright &copy; 1997-2014 University of Cambridge.
2919
+ <br>
2920
+ <p>
2921
+ Return to the <a href="index.html">PCRE index page</a>.
2922
+ </p>