git.m6w6.name Git - m6w6/ext-psi/blob - README.md

   1 # ext-psi
   2
   3 [![Join the chat at https://gitter.im/m6w6/ext-psi](https://badges.gitter.im/m6w6/ext-psi.svg)](https://gitter.im/m6w6/ext-psi?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
   4 [![Build Status](https://travis-ci.org/m6w6/ext-psi.svg?branch=master)](https://travis-ci.org/m6w6/ext-psi)
   5
   6 PSI is a PHP extension, which provides a foreign function interface through
   7 `libffi` and/or `libjit`.
   8
   9 The acronym PSI may be read as:
  10 * PHP System Interface
  11 * POSIX Standard Interface
  12
  13 The latter because PSI can be configured to include declarations for most of the
  14 [base definitions and system interfaces of POSIX.1-2008](http://pubs.opengroup.org/onlinepubs/9699919799/).
  15
  16 > **WARNING:**
  17 > This is heavy WIP. Only a small part of configuration and implementation has been completed yet.
  18
  19 ## Features
  20
  21 * standard scalar types mapped to stdint types
  22 * structs, unions, enums and typedefs
  23 * simple numeric expressions
  24 * string and int constants
  25 * vararg calls
  26
  27 ## Installing
  28
  29 > **WARNING:**
  30 > This is heavy WIP. Installation only works from a source checkout yet.
  31
  32 ### PECL
  33
  34 This extension is distributed through [PECL](http://pecl.php.net) and can be
  35 installed with [PEAR](http://pear.php.net)'s pecl command:
  36
  37         pecl install psi
  38
  39 ### PHARext
  40
  41 Watch out for [PECL replicates](https://replicator.pharext.org?psi)
  42 and [pharext](https://github.com/pharext) packages attached to
  43 [releases](https://github.com/m6w6/ext-psi/releases).
  44
  45 ### Checkout
  46
  47 This extension is hosted at [Github](https://github.com/m6w6/ext-psi) with a
  48 personal [mirror](https://git.m6w6.name/?p=m6w6/ext-psi) available.
  49
  50         git clone github.com:m6w6/ext-psi
  51
  52         cd ext-psi
  53
  54         /path/to/phpize
  55         ./configure --with-php-config=/path/to/php-config
  56         make
  57         sudo make install
  58
  59 ## Configuring PSI at build time
  60
  61 PSI supports the following configure switches:
  62
  63 ### --enable-psi
  64 **Enable PHP System Interface support.**
  65
  66 This is only relevant for an in-tree build. Use `--enable-psi` to include
  67 the PSI extension in the build.
  68
  69 ### --enable-psi-posix
  70 **Pre-define POSIX decls.**
  71
  72 Use `--enable-psi-posix=all` to enable all available POSIX checks.
  73
  74 Use `--enable-psi-posix=section,another,onemore` to enable specific modules only.
  75
  76 The following modules are included by default:
  77
  78 [stdint](http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/stdint.h.html),
  79 [stddef](http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/stddef.h.html),
  80 [stdlib](http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/stdlib.h.html),
  81 [sys/types](http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/sys_types.h.html)
  82
  83 The following modules are available to select:
  84
  85 [errno](http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/errno.h.html),
  86 [fcntl](http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/fcntl.h.html),
  87 [glob](http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/glob.h.html),
  88 [locale](http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/locale.h.html),
  89 [ndbm](http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/ndbm.h.html),
  90 [netdb](http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/netdb.h.html),
  91 [netinet/in](http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/netinet_in.h.html),
  92 [netinet/tcp](http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/netinet_tcp.h.html),
  93 [poll](http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/poll.h.html),
  94 [signal](http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html),
  95 [stdio](http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/stdio.h.html),
  96 [sys/select](http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/sys_select.h.html),
  97 [sys/socket](http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/sys_socket.h.html),
  98 [sys/stat](http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/sys_stat.h.html),
  99 [sys/time](http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/sys_time.h.html),
 100 [sys/times](http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/sys_times.h.html),
 101 [sys/uio](http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/sys_uio.h.html),
 102 [sys/utsname](http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/sys_utsname.h.html),
 103 [syslog](http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/syslog.h.html),
 104 [time](http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/time.h.html),
 105 [unistd](http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/unistd.h.html),
 106 [wchar](http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/wchar.h.html),
 107 [wctype](http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/wctype.h.html),
 108
 109 ### --with-psi-libjit
 110 **Path to libjit.**
 111
 112 > **WARNING:**
 113 > We currently rely on a patched libjit, because of an apparent bug in how
 114 > libjit creates closures, which still needs to be verified, though.
 115 > See https://github.com/m6w6/libjit for the preliminary patch.
 116
 117 ### --with-psi-libffi
 118 **Path to libffi.**
 119
 120 ## Configuring PSI at runtime
 121
 122 ### psi.engine
 123
 124 The backend that PSI should use as FFI, either _jit_ for `libjit` or _ffi_ for `libffi`. Defaults to "ffi".
 125
 126 ### psi.directory
 127
 128 A colon separated list of directories to scan for `*.psi` files. Defaults to "psi.d".
 129
 130 ## PSI files
 131
 132 ### Comments
 133
 134 * C style multi line comments
 135 * C++ style single line comments
 136
 137 ```c
 138 // this is a one line comment
 139 /* followed
 140    by a multi
 141    line comment
 142 */
 143 ```
 144
 145 ### Typedefs
 146
 147 ```c
 148 typedef unsigned char xmlChar;
 149 ```
 150
 151 They follow the basic C-style `typedef` syntax.
 152
 153 ```c
 154 typedef struct str {
 155     char *p;
 156     size_t l;
 157 } str_t;
 158 ```
 159 You can also `typedef` unions and enums that way.
 160
 161 ### Structs
 162
 163 The following example results in exactly the same interpretation as the previous:
 164
 165 ```c
 166 typedef struct str str_t;
 167 struct str {
 168     char *p;
 169     size_t l;
 170 }
 171 ```
 172
 173 A struct will have the size of all its elements plus padding combined and an
 174 alignment equal to that of the largest element's alignment.
 175
 176 ### Enums
 177
 178 Enums are considered to be of type `int`.
 179
 180 ```c
 181 enum STATUS {
 182  FAILURE = -1,
 183  SUCCESS
 184 }
 185 ```
 186
 187 Enums will be registered as userland constants with the following pattern:
 188
 189 * `psi\STATUS\FAILURE` with value -1
 190 * `psi\STATUS\SUCCESS` with value 0
 191
 192 ### Unions
 193
 194 ```c
 195 union anyval {
 196     char c;
 197     short s;
 198     int i;
 199     long l;
 200     float f;
 201     double d;
 202     str_t str;
 203 }
 204 ```
 205
 206 Unions will have the size and alignment of the largest element they contain.
 207
 208 ### Lib
 209
 210 ```c
 211 lib "awesome";
 212 ```
 213
 214 These statements define what library should be `dlopen()`-ed to look up symbols from declarations.
 215 They must only occur once in a file. When a `lib` statement is omitted, stdlib is assumed.
 216
 217 ### Declarations
 218
 219 Declarations provide all information needed to make a foreign function call.
 220
 221 ```c
 222 extern char *strerror(int errnum);
 223 ```
 224
 225 You may specify a non-standard calling convention in place of `extern`, where `default` and `cdecl` have the same meaning as `extern`.
 226
 227 Additionally recognized calling conventions include: `stdcall` and `fastcall`.
 228
 229 ### Constants
 230
 231 ```c
 232 const int num\ZERO = 0;
 233 const string pwd\TOKEN = "4WlOjXGL";
 234 ```
 235
 236 Constants must have a namespaced identifiers and are registered as userland constants.
 237
 238 ### Implementations
 239
 240 Implementations are the userland visible interfaces to the foreign function interface.
 241
 242 ```php
 243 function str\error(int $num) : string {
 244     let errnum = intval($num);
 245     return to_string(strerror);
 246 }
 247 ```
 248
 249 Each implementation refers to exactly one declared foreign function referenced in its `return` statement. Each declaration, on the other hand, may have any number of implementations.
 250
 251 ## Complete example
 252
 253 ```c
 254 // all declarations in this file should be looked up in libidn
 255 lib "idn";
 256
 257 // IDNA errors
 258 const int \IDNA_SUCCESS = 0;
 259 const int \IDNA_STRINGPREP_ERROR = 1;
 260 const int \IDNA_PUNYCODE_ERROR = 2;
 261 const int \IDNA_CONTAINS_NON_LDH = 3;
 262 const int \IDNA_CONTAINS_LDH = 3;
 263 const int \IDNA_CONTAINS_MINUS = 4;
 264 const int \IDNA_INVALID_LENGTH = 5;
 265 const int \IDNA_NO_ACE_PREFIX = 6;
 266 const int \IDNA_ROUNDTRIP_VERIFY_ERROR = 7;
 267 const int \IDNA_CONTAINS_ACE_PREFIX = 8;
 268 const int \IDNA_ICONV_ERROR = 9;
 269 const int \IDNA_MALLOC_ERROR = 201;
 270 const int \IDNA_DLOPEN_ERROR = 202;
 271 // IDNA flags
 272 const int \IDNA_ALLOW_UNASSIGNED = 1;
 273 const int \IDNA_USE_STD3_ASCII_RULES = 2;
 274
 275 // nothing special about the declaration here
 276 default int idna_to_ascii_8z(char *host, char **buffer, int flags);
 277
 278 function idn\utf8_to_ascii(string $host, string &$result, int $flags = 0) : int {
 279     // there must be a `let` statement for each
 280     // declared argument of the called function
 281
 282     // setup a pointer to NULL
 283         let buffer = &NULL;
 284
 285         // setup a string pointer to $host
 286         let host = strval($host);
 287
 288         // assing the integer value of $flags
 289         let flags = intval($flags);
 290
 291         // the function to call is referenced in
 292         // the return statement, along with the
 293         // neccessary cast how to interpred the
 294         // returned native value
 295         return to_int(idna_to_ascii_8z);
 296
 297         // by-ref vars might receive output values
 298         // through `set` statments, which also
 299         // require a cast how to marshal the
 300         // native data as PHP value
 301         set $result = to_string(*buffer);
 302
 303         // after the buffer has been marshaled
 304         // for the PHP engine, we have to free
 305         // the buffer to avoid a memory leak
 306         free free(*buffer);
 307         // note that in this example we omit the
 308         // declaration of the free() function called
 309         // in our `free` statement for brevity
 310 }
 311
 312 default char *idna_strerror(int rc);
 313 function idn\strerror(int $rc) : string {
 314         return to_string(idna_strerror);
 315         let rc = intval($rc);
 316 }
 317 ```
 318
 319 ### Userland
 320
 321 ```php
 322 $rc = idn\utf8_to_ascii("flöte.de", $result);
 323 printf("<%s>\n", $result);
 324 printf("%s\n", idn\strerror($rc));
 325
 326 $rc = idn\utf8_to_ascii("…asdf….de", $result, IDNA_USE_STD3_ASCII_RULES);
 327 printf("<%s>\n", $result);
 328 printf("%s\n", idn\strerror($rc));
 329 ```
 330
 331 #### Output
 332 ```
 333 <xn--flte-6qa.de>
 334 Success
 335 <>
 336 Non-digit/letter/hyphen in input
 337 ```
 338
 339 ## ChangeLog
 340
 341 A comprehensive list of changes can be obtained from the
 342 [PECL website](https://pecl.php.net/package-changelog.php?package=psi).
 343
 344 Known issues are listed in [BUGS](./BUGS) and future ideas can be found in [TODO](./TODO).
 345
 346 ## License
 347
 348 ext-psi is licensed under the 2-Clause-BSD license, which can be found in
 349 the accompanying [LICENSE](./LICENSE) file.
 350
 351 ## Contributing
 352
 353 All forms of contribution are welcome! Please see the bundled
 354 [CONTRIBUTING](./CONTRIBUTING.md) note for the general principles followed.
 355
 356 The list of past and current contributors is maintained in [THANKS](./THANKS).