generator/generator_php.ml

   1 (* libguestfs
   2  * Copyright (C) 2009-2010 Red Hat Inc.
   3  *
   4  * This program is free software; you can redistribute it and/or modify
   5  * it under the terms of the GNU General Public License as published by
   6  * the Free Software Foundation; either version 2 of the License, or
   7  * (at your option) any later version.
   8  *
   9  * This program is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  * GNU General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU General Public License
  15  * along with this program; if not, write to the Free Software
  16  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  17  *)
  18
  19 (* Please read generator/README first. *)
  20
  21 open Printf
  22
  23 open Generator_types
  24 open Generator_utils
  25 open Generator_pr
  26 open Generator_docstrings
  27 open Generator_optgroups
  28 open Generator_actions
  29 open Generator_structs
  30 open Generator_c
  31
  32 let rec generate_php_h () =
  33   generate_header CStyle LGPLv2plus;
  34
  35   pr "\
  36 #ifndef PHP_GUESTFS_PHP_H
  37 #define PHP_GUESTFS_PHP_H 1
  38
  39 #ifdef ZTS
  40 #include \"TSRM.h\"
  41 #endif
  42
  43 #define PHP_GUESTFS_PHP_EXTNAME \"guestfs_php\"
  44 #define PHP_GUESTFS_PHP_VERSION \"1.0\"
  45
  46 PHP_MINIT_FUNCTION (guestfs_php);
  47
  48 #define PHP_GUESTFS_HANDLE_RES_NAME \"guestfs_h\"
  49
  50 PHP_FUNCTION (guestfs_create);
  51 PHP_FUNCTION (guestfs_last_error);
  52 ";
  53
  54   List.iter (
  55     fun (shortname, _, _, _, _, _, _) ->
  56       pr "PHP_FUNCTION (guestfs_%s);\n" shortname
  57   ) all_functions_sorted;
  58
  59   pr "\
  60
  61 extern zend_module_entry guestfs_php_module_entry;
  62 #define phpext_guestfs_php_ptr &guestfs_php_module_entry
  63
  64 #endif /* PHP_GUESTFS_PHP_H */
  65 "
  66
  67 and generate_php_c () =
  68   generate_header CStyle LGPLv2plus;
  69
  70   pr "\
  71 /* NOTE: Be very careful with all macros in PHP header files.  The
  72  * morons who wrote them aren't good at making them safe for inclusion
  73  * in arbitrary places in C code, eg. not using 'do ... while(0)'
  74  * or parenthesizing any of the arguments.
  75  */
  76
  77 /* NOTE (2): Some parts of the API can't be used on 32 bit platforms.
  78  * Any 64 bit numbers will be truncated.  There's no easy way around
  79  * this in PHP.
  80  */
  81
  82 #include <config.h>
  83
  84 #include <stdio.h>
  85 #include <stdlib.h>
  86
  87 #include <php.h>
  88 #include <php_guestfs_php.h>
  89
  90 #include \"guestfs.h\"
  91
  92 static int res_guestfs_h;
  93
  94 static void
  95 guestfs_php_handle_dtor (zend_rsrc_list_entry *rsrc TSRMLS_DC)
  96 {
  97   guestfs_h *g = (guestfs_h *) rsrc->ptr;
  98   if (g != NULL)
  99     guestfs_close (g);
 100 }
 101
 102 PHP_MINIT_FUNCTION (guestfs_php)
 103 {
 104   res_guestfs_h =
 105     zend_register_list_destructors_ex (guestfs_php_handle_dtor,
 106     NULL, PHP_GUESTFS_HANDLE_RES_NAME, module_number);
 107 }
 108
 109 static function_entry guestfs_php_functions[] = {
 110   PHP_FE (guestfs_create, NULL)
 111   PHP_FE (guestfs_last_error, NULL)
 112 ";
 113
 114   List.iter (
 115     fun (shortname, _, _, _, _, _, _) ->
 116       pr "  PHP_FE (guestfs_%s, NULL)\n" shortname
 117   ) all_functions_sorted;
 118
 119   pr "  { NULL, NULL, NULL }
 120 };
 121
 122 zend_module_entry guestfs_php_module_entry = {
 123 #if ZEND_MODULE_API_NO >= 20010901
 124   STANDARD_MODULE_HEADER,
 125 #endif
 126   PHP_GUESTFS_PHP_EXTNAME,
 127   guestfs_php_functions,
 128   PHP_MINIT (guestfs_php),
 129   NULL,
 130   NULL,
 131   NULL,
 132   NULL,
 133 #if ZEND_MODULE_API_NO >= 20010901
 134   PHP_GUESTFS_PHP_VERSION,
 135 #endif
 136   STANDARD_MODULE_PROPERTIES
 137 };
 138
 139 #ifdef COMPILE_DL_GUESTFS_PHP
 140 ZEND_GET_MODULE (guestfs_php)
 141 #endif
 142
 143 PHP_FUNCTION (guestfs_create)
 144 {
 145   guestfs_h *g = guestfs_create ();
 146   if (g == NULL) {
 147     RETURN_FALSE;
 148   }
 149
 150   guestfs_set_error_handler (g, NULL, NULL);
 151
 152   ZEND_REGISTER_RESOURCE (return_value, g, res_guestfs_h);
 153 }
 154
 155 PHP_FUNCTION (guestfs_last_error)
 156 {
 157   zval *z_g;
 158   guestfs_h *g;
 159
 160   if (zend_parse_parameters (ZEND_NUM_ARGS() TSRMLS_CC, \"r\",
 161                              &z_g) == FAILURE) {
 162     RETURN_FALSE;
 163   }
 164
 165   ZEND_FETCH_RESOURCE (g, guestfs_h *, &z_g, -1, PHP_GUESTFS_HANDLE_RES_NAME,
 166                        res_guestfs_h);
 167   if (g == NULL) {
 168     RETURN_FALSE;
 169   }
 170
 171   const char *err = guestfs_last_error (g);
 172   if (err) {
 173     RETURN_STRING (err, 1);
 174   } else {
 175     RETURN_NULL ();
 176   }
 177 }
 178
 179 ";
 180
 181   (* Now generate the PHP bindings for each action. *)
 182   List.iter (
 183     fun (shortname, (ret, args, optargs as style), _, _, _, _, _) ->
 184       pr "PHP_FUNCTION (guestfs_%s)\n" shortname;
 185       pr "{\n";
 186       pr "  zval *z_g;\n";
 187       pr "  guestfs_h *g;\n";
 188
 189       List.iter (
 190         function
 191         | String n | Device n | Pathname n | Dev_or_Path n
 192         | FileIn n | FileOut n | Key n
 193         | OptString n
 194         | BufferIn n ->
 195             pr "  char *%s;\n" n;
 196             pr "  int %s_size;\n" n
 197         | StringList n
 198         | DeviceList n ->
 199             pr "  zval *z_%s;\n" n;
 200             pr "  char **%s;\n" n;
 201         | Bool n ->
 202             pr "  zend_bool %s;\n" n
 203         | Int n | Int64 n | Pointer (_, n) ->
 204             pr "  long %s;\n" n
 205         ) args;
 206
 207       if optargs <> [] then (
 208         pr "  struct guestfs_%s_argv optargs_s = { .bitmask = 0 };\n" shortname;
 209         pr "  struct guestfs_%s_argv *optargs = &optargs_s;\n" shortname;
 210
 211         (* XXX Ugh PHP doesn't have proper optional arguments, so we
 212          * have to use sentinel values.
 213          *)
 214         (* Since we don't know if PHP types will exactly match structure
 215          * types, declare some local variables here.
 216          *)
 217         List.iter (
 218           function
 219           | OBool n -> pr "  zend_bool optargs_t_%s = -1;\n" n
 220           | OInt n | OInt64 n -> pr "  long optargs_t_%s = -1;\n" n
 221           | OString n ->
 222               pr "  char *optargs_t_%s = NULL;\n" n;
 223               pr "  int optargs_t_%s_size = -1;\n" n
 224         ) optargs
 225       );
 226
 227       pr "\n";
 228
 229       (* Parse the parameters. *)
 230       let param_string = String.concat "" (
 231         List.map (
 232           function
 233           | String n | Device n | Pathname n | Dev_or_Path n
 234           | FileIn n | FileOut n | BufferIn n | Key n -> "s"
 235           | OptString n -> "s!"
 236           | StringList n | DeviceList n -> "a"
 237           | Bool n -> "b"
 238           | Int n | Int64 n | Pointer (_, n) -> "l"
 239         ) args
 240       ) in
 241
 242       let param_string =
 243         if optargs <> [] then
 244           param_string ^ "|" ^
 245             String.concat "" (
 246               List.map (
 247                 function
 248                 | OBool _ -> "b"
 249                 | OInt _ | OInt64 _ -> "l"
 250                 | OString _ -> "s"
 251               ) optargs
 252             )
 253         else param_string in
 254
 255       pr "  if (zend_parse_parameters (ZEND_NUM_ARGS() TSRMLS_CC, \"r%s\",\n"
 256         param_string;
 257       pr "        &z_g";
 258       List.iter (
 259         function
 260         | String n | Device n | Pathname n | Dev_or_Path n
 261         | FileIn n | FileOut n | BufferIn n | Key n
 262         | OptString n ->
 263             pr ", &%s, &%s_size" n n
 264         | StringList n | DeviceList n ->
 265             pr ", &z_%s" n
 266         | Bool n ->
 267             pr ", &%s" n
 268         | Int n | Int64 n | Pointer (_, n) ->
 269             pr ", &%s" n
 270       ) args;
 271       List.iter (
 272         function
 273         | OBool n | OInt n | OInt64 n ->
 274             pr ", &optargs_t_%s" n
 275         | OString n ->
 276             pr ", &optargs_t_%s, &optargs_t_%s_size" n n
 277       ) optargs;
 278       pr ") == FAILURE) {\n";
 279       pr "    RETURN_FALSE;\n";
 280       pr "  }\n";
 281       pr "\n";
 282       pr "  ZEND_FETCH_RESOURCE (g, guestfs_h *, &z_g, -1, PHP_GUESTFS_HANDLE_RES_NAME,\n";
 283       pr "                       res_guestfs_h);\n";
 284       pr "  if (g == NULL) {\n";
 285       pr "    RETURN_FALSE;\n";
 286       pr "  }\n";
 287       pr "\n";
 288
 289       List.iter (
 290         function
 291         | String n | Device n | Pathname n | Dev_or_Path n
 292         | FileIn n | FileOut n | Key n
 293         | OptString n ->
 294             (* Just need to check the string doesn't contain any ASCII
 295              * NUL characters, which won't be supported by the C API.
 296              *)
 297             pr "  if (strlen (%s) != %s_size) {\n" n n;
 298             pr "    fprintf (stderr, \"libguestfs: %s: parameter '%s' contains embedded ASCII NUL.\\n\");\n" shortname n;
 299             pr "    RETURN_FALSE;\n";
 300             pr "  }\n";
 301             pr "\n"
 302         | BufferIn n -> ()
 303         | StringList n
 304         | DeviceList n ->
 305             (* Convert array to list of strings.
 306              * http://marc.info/?l=pecl-dev&m=112205192100631&w=2
 307              *)
 308             pr "  {\n";
 309             pr "    HashTable *a;\n";
 310             pr "    int n;\n";
 311             pr "    HashPosition p;\n";
 312             pr "    zval **d;\n";
 313             pr "    size_t c = 0;\n";
 314             pr "\n";
 315             pr "    a = Z_ARRVAL_P (z_%s);\n" n;
 316             pr "    n = zend_hash_num_elements (a);\n";
 317             pr "    %s = safe_emalloc (n + 1, sizeof (char *), 0);\n" n;
 318             pr "    for (zend_hash_internal_pointer_reset_ex (a, &p);\n";
 319             pr "         zend_hash_get_current_data_ex (a, (void **) &d, &p) == SUCCESS;\n";
 320             pr "         zend_hash_move_forward_ex (a, &p)) {\n";
 321             pr "      zval t = **d;\n";
 322             pr "      zval_copy_ctor (&t);\n";
 323             pr "      convert_to_string (&t);\n";
 324             pr "      %s[c] = Z_STRVAL (t);\n" n;
 325             pr "      c++;\n";
 326             pr "    }\n";
 327             pr "    %s[c] = NULL;\n" n;
 328             pr "  }\n";
 329             pr "\n"
 330         | Bool _ | Int _ | Int64 _ | Pointer _ -> ()
 331         ) args;
 332
 333       (* Optional arguments. *)
 334       if optargs <> [] then (
 335         let uc_shortname = String.uppercase shortname in
 336         List.iter (
 337           fun argt ->
 338             let n = name_of_optargt argt in
 339             let uc_n = String.uppercase n in
 340             pr "  if (optargs_t_%s != " n;
 341             (match argt with
 342              | OBool _ -> pr "((zend_bool)-1)"
 343              | OInt _ | OInt64 _ -> pr "-1"
 344              | OString _ -> pr "NULL"
 345             );
 346             pr ") {\n";
 347             pr "    optargs_s.%s = optargs_t_%s;\n" n n;
 348             pr "    optargs_s.bitmask |= GUESTFS_%s_%s_BITMASK;\n"
 349               uc_shortname uc_n;
 350             pr "  }\n"
 351         ) optargs;
 352         pr "\n"
 353       );
 354
 355       (* Return value. *)
 356       (match ret with
 357        | RErr -> pr "  int r;\n"
 358        | RBool _
 359        | RInt _ -> pr "  int r;\n"
 360        | RInt64 _ -> pr "  int64_t r;\n"
 361        | RConstString _ -> pr "  const char *r;\n"
 362        | RConstOptString _ -> pr "  const char *r;\n"
 363        | RString _ ->
 364            pr "  char *r;\n"
 365        | RStringList _ ->
 366            pr "  char **r;\n"
 367        | RStruct (_, typ) ->
 368            pr "  struct guestfs_%s *r;\n" typ
 369        | RStructList (_, typ) ->
 370            pr "  struct guestfs_%s_list *r;\n" typ
 371        | RHashtable _ ->
 372            pr "  char **r;\n"
 373        | RBufferOut _ ->
 374            pr "  char *r;\n";
 375            pr "  size_t size;\n"
 376       );
 377
 378       (* Call the function. *)
 379       if optargs = [] then
 380         pr "  r = guestfs_%s " shortname
 381       else
 382         pr "  r = guestfs_%s_argv " shortname;
 383       generate_c_call_args ~handle:"g" style;
 384       pr ";\n";
 385       pr "\n";
 386
 387       (* Free up parameters. *)
 388       List.iter (
 389         function
 390         | String n | Device n | Pathname n | Dev_or_Path n
 391         | FileIn n | FileOut n | Key n
 392         | OptString n -> ()
 393         | BufferIn n -> ()
 394         | StringList n
 395         | DeviceList n ->
 396             pr "  {\n";
 397             pr "    size_t c = 0;\n";
 398             pr "\n";
 399             pr "    for (c = 0; %s[c] != NULL; ++c)\n" n;
 400             pr "      efree (%s[c]);\n" n;
 401             pr "    efree (%s);\n" n;
 402             pr "  }\n";
 403             pr "\n"
 404         | Bool _ | Int _ | Int64 _ | Pointer _ -> ()
 405         ) args;
 406
 407       (* Check for errors. *)
 408       (match errcode_of_ret ret with
 409        | `CannotReturnError -> ()
 410        | `ErrorIsMinusOne ->
 411            pr "  if (r == -1) {\n";
 412            pr "    RETURN_FALSE;\n";
 413            pr "  }\n"
 414        | `ErrorIsNULL ->
 415            pr "  if (r == NULL) {\n";
 416            pr "    RETURN_FALSE;\n";
 417            pr "  }\n"
 418       );
 419       pr "\n";
 420
 421       (* Convert the return value. *)
 422       (match ret with
 423        | RErr ->
 424            pr "  RETURN_TRUE;\n"
 425        | RBool _ ->
 426            pr "  RETURN_BOOL (r);\n"
 427        | RInt _ ->
 428            pr "  RETURN_LONG (r);\n"
 429        | RInt64 _ ->
 430            pr "  RETURN_LONG (r);\n"
 431        | RConstString _ ->
 432            pr "  RETURN_STRING (r, 1);\n"
 433        | RConstOptString _ ->
 434            pr "  if (r) { RETURN_STRING (r, 1); }\n";
 435            pr "  else { RETURN_NULL (); }\n"
 436        | RString _ ->
 437            pr "  char *r_copy = estrdup (r);\n";
 438            pr "  free (r);\n";
 439            pr "  RETURN_STRING (r_copy, 0);\n"
 440        | RBufferOut _ ->
 441            pr "  char *r_copy = estrndup (r, size);\n";
 442            pr "  free (r);\n";
 443            pr "  RETURN_STRING (r_copy, 0);\n"
 444        | RStringList _ ->
 445            pr "  size_t c = 0;\n";
 446            pr "  array_init (return_value);\n";
 447            pr "  for (c = 0; r[c] != NULL; ++c) {\n";
 448            pr "    add_next_index_string (return_value, r[c], 1);\n";
 449            pr "    free (r[c]);\n";
 450            pr "  }\n";
 451            pr "  free (r);\n";
 452        | RHashtable _ ->
 453            pr "  size_t c = 0;\n";
 454            pr "  array_init (return_value);\n";
 455            pr "  for (c = 0; r[c] != NULL; c += 2) {\n";
 456            pr "    add_assoc_string (return_value, r[c], r[c+1], 1);\n";
 457            pr "    free (r[c]);\n";
 458            pr "    free (r[c+1]);\n";
 459            pr "  }\n";
 460            pr "  free (r);\n";
 461        | RStruct (_, typ) ->
 462            let cols = cols_of_struct typ in
 463            generate_php_struct_code typ cols
 464        | RStructList (_, typ) ->
 465            let cols = cols_of_struct typ in
 466            generate_php_struct_list_code typ cols
 467       );
 468
 469       pr "}\n";
 470       pr "\n"
 471   ) all_functions_sorted
 472
 473 and generate_php_struct_code typ cols =
 474   pr "  array_init (return_value);\n";
 475   List.iter (
 476     function
 477     | name, FString ->
 478         pr "  add_assoc_string (return_value, \"%s\", r->%s, 1);\n" name name
 479     | name, FBuffer ->
 480         pr "  add_assoc_stringl (return_value, \"%s\", r->%s, r->%s_len, 1);\n"
 481           name name name
 482     | name, FUUID ->
 483         pr "  add_assoc_stringl (return_value, \"%s\", r->%s, 32, 1);\n"
 484           name name
 485     | name, (FBytes|FUInt64|FInt64|FInt32|FUInt32) ->
 486         pr "  add_assoc_long (return_value, \"%s\", r->%s);\n"
 487           name name
 488     | name, FChar ->
 489         pr "  add_assoc_stringl (return_value, \"%s\", &r->%s, 1, 1);\n"
 490           name name
 491     | name, FOptPercent ->
 492         pr "  add_assoc_double (return_value, \"%s\", r->%s);\n"
 493           name name
 494   ) cols;
 495   pr "  guestfs_free_%s (r);\n" typ
 496
 497 and generate_php_struct_list_code typ cols =
 498   pr "  array_init (return_value);\n";
 499   pr "  size_t c = 0;\n";
 500   pr "  for (c = 0; c < r->len; ++c) {\n";
 501   pr "    zval *z_elem;\n";
 502   pr "    ALLOC_INIT_ZVAL (z_elem);\n";
 503   pr "    array_init (z_elem);\n";
 504   List.iter (
 505     function
 506     | name, FString ->
 507         pr "    add_assoc_string (z_elem, \"%s\", r->val[c].%s, 1);\n"
 508           name name
 509     | name, FBuffer ->
 510         pr "    add_assoc_stringl (z_elem, \"%s\", r->val[c].%s, r->val[c].%s_len, 1);\n"
 511           name name name
 512     | name, FUUID ->
 513         pr "    add_assoc_stringl (z_elem, \"%s\", r->val[c].%s, 32, 1);\n"
 514           name name
 515     | name, (FBytes|FUInt64|FInt64|FInt32|FUInt32) ->
 516         pr "    add_assoc_long (z_elem, \"%s\", r->val[c].%s);\n"
 517           name name
 518     | name, FChar ->
 519         pr "    add_assoc_stringl (z_elem, \"%s\", &r->val[c].%s, 1, 1);\n"
 520           name name
 521     | name, FOptPercent ->
 522         pr "    add_assoc_double (z_elem, \"%s\", r->val[c].%s);\n"
 523           name name
 524   ) cols;
 525   pr "    add_next_index_zval (return_value, z_elem);\n";
 526   pr "  }\n";
 527   pr "  guestfs_free_%s_list (r);\n" typ