Home

erl_interface-3.2.3

1. On success conp is filled in with the address and node name of the connecting client and a file descriptor is returned On failure ERL_ERROR is returned and erl_errno is set to EIO erl_thiscookie erl_thisnodename erl_thishostname erl_thisalivename erl_thiscreation These functions can be used to retrieve information about the C Node These values are initially set with erl_connect_init or erl_connect_xinit erl_unpublish alive Types e char alive This function can be called by a process to unregister a specified node name from epmd on the localhost This may be useful for example when epmd has not detected the failure of anode and will not allow the name to be reused If you use this function to unregister your own process be sure to also close the descriptor that was returned by erl_publish Note Careless use of this function may have unpredictable results if the registered node is in fact still running alive is the name of the node to unregister i e the first component of the nodename without the hostname If the node was successfully unregistered from epmd the function returns 0 Otherwise it returns 1 and sets erl_errno is to EIO Debug Information If aconnection attempt fails the following can be checked e erl errno e that the right cookie was used e that epmd is running e the remote Erlang node on the other side is running the same version of Erlang as
2. ETERM erl_hd list Types e ETERM list Extracts the first element from a list list isan Erlang term containing a list The function returns an Erlang term corresponding to the head element in the list or a NULL pointer if List was not a list ETERM erl iolist to binary term Types e ETERM list This function converts an IO list to a binary term list isan Erlang term containing a list This function an Erlang binary term or NULL if list was not an IO list Informally an IO list is a deep list of characters and binaries which can be sent to an Erlang port In BNF an IO list is formally defined as follows iolist Binary iohead iolist iohead Binary Byte integer in the range 0 255 iolist Erlang Interface 41 erl_eterm C Module Erl Interface Library Reference char erliolist to string list Types e ETERM list This function converts an IO list to a N0 terminated C string list isan Erlang term containing an IO list The lO list must not contain the integer 0 since C strings may not contain this value except as a terminating marker This function returns a pointer to a dynamically allocated buffer containing a string If list isnot an IO list or if List contains the integer 0 NULL is returned It is the caller s responsibility free the allocated buffer with erl free Refer to erl_iolist_to_binary for the definition of an IO list int erliolist length li
3. Types e char node alive e struct in_addr addr These functions set up a connection to an Erlang node erl xconnect requires the IP address of the remote host and the alive name of the remote node to be specified er1 connect provides an alternative interface and determines the information from the node name provided addr is the 32 bit IP address of the remote host alive is the alivename of the remote node node is the name of the remote node These functions return an open file descriptor on success or a negative value indicating that an error occurred in which case they will set erl_errno to one of EHOSTUNREACH The remote host node is unreachable ENOMEM No more memory available EIO I O error Additionally errno values from socket 2 and connect 2 system calls may be propagated into erl errno 30 Erlang Interface Erl Interface Library Reference erl connect C Module define NODE madonna chivas du etx ericsson se define ALIVE madonna define IP ADDR 150 236 14 75 Variant 1 erl_connect NODE Variant 2 struct in_addr addr addr inet_addr IP_ADDR erl_xconnect amp addr ALIVE int erl_close_connection fd Types e int fd This function closes an open connection to an Erlang node Fd isa file descriptor obtained from erl_connect Or erl xconnect On success 0 is returned If the call fails a non zero value is returned and the reason for the er
4. ei reg close 1 C function 21 ei reg delete 2 C function 21 ei reg dump 4 C function 21 60 ei reg getfval 2 C function 22 ei reg getival 2 C function 22 ei reg getpval 3 C function 23 ei reg getsval 2 C function 23 ei_reg_getval 5 C function 23 ei reg markdirty 2 C function 2 ei reg open 1 C function 24 ei reg purge 1 C function 24 ei reg resize 2 C function a ei reg restore 3 C function 2 ei reg setfval 3 C function pa ei reg setival 3 C function 25 ei reg setpval 4 C function 26 ei reg setsval 3 C function 26 ei reg setval 5 C function 26 ei reg stat 3 C function 27 ei reg tabstat 2 C function 27 Erlang Interface
5. i lt count i printf s n names i free names erl global names allocates and returns a buffer containing all the names known to global count will be initialized to indicate how many names are in the array The array of strings in names is terminated by aNULL pointer so it is not necessary to use count to determine when the last name is reached It is the caller s responsibility to free the array erl global names allocates the array and all of the strings using a single call to malloc SO free names is all that is necessary To look up one of the names ETERM pid char node 256 pid erl global whereis fd schedule node If schedule is known to global an Erlang pid is returned that can be used to send messages to the schedule service Additionally node will be initialized to contain the name of the node where the service is registered so that you can make a connection to it by simply passing the variable to erl connect Before registering a name you should already have registered your port number with epmd Thisis not strictly necessary but if you neglect to do so then other nodes wishing to communicate with your service will be unable to find or connect to your process Create a pid that Erlang processes can use to communicate with your service ETERM pid pid erl mk pid thisnode 14 0 0 erl global register fd servicename pid Erlang Interface 9 Chapter 1 Erle Interface User
6. contain table statistics On failure the function returns 1 Erlang Interface Erl Interface Library Reference erl connect C Module erl connect C M odule This module provides support for communication between distributed Erlang nodes and C nodes in a manner that is transparent to Erlang processes A C node appears to Erlang as a hidden node That is Erlang processes that know the name of the C node are able to communicate with it in a normal manner but the node name will not appear in the listing provided by the Erlang function nodes 0 Exports int erl connect init number cookie creation int erl connect xinit host alive node addr cookie creation Types e int number e char cookie e short creation e char host talive node e struct in_addr addr These functions initialize the er1 connect module In particular they are used to identify the name of the C node from which they are called O ne of these functions must be called before any of the other functions in the erl_connect module are used erl connect xinit stores for later use information about the node s host name host alive name alive node name node IP address addr cookie cookie and creation number creation erl connect init provides an alternative interface which does not require as much information from the caller Instead er1 connect init uses gethostbyname to obtain default values If you use erl_connect_in
7. e const char node e unsigned int number e unsigned int creation Erlang Interface Erl Interface Library Reference erl eterm C Module This function creates an old Erlang reference with only 18 bits use er1 mk long ref instead node is the name of the C node number should be chosen uniquely for each reference created for a given C node creation isan arbitrary number Note that number and creation are limited in precision so only the low 18 and 2 bits of these numbers are actually used The function returns an Erlang reference object ERL REF NODE ref ERL REF NUMBER ref and ERL_REF_CREATION ref to retrieve the three values used to create the reference ETERM erl mk long ref node ni n2 n3 creation Types e const char node e unsigned int n1 n2 n3 e unsigned int creation This function creates an Erlang reference with 82 bits node is the name of the C node ni n2 and n3 can be seen as one big number n1 2764 n2 2732 n3 which should be chosen uniquely for each reference created for a given C node creation isan arbitrary number Note that n3 and creation are limited in precision so only the low 18 and 2 bits of these numbers are actually used The function returns an Erlang reference object ERL REF NODE ref ERL REF NUMBERS ref ERL REF LEN ref and ERL_REF_CREATION ref to retrieve the values used to create the reference ETERM erl mk string string Types e char stri
8. flags to ei_reg_dump 12 Erlang Interface Er Interface Command Reference Short Summaries e Command erl_call page 14 Call Start a Distributed Erlang N ode eri call The following functions are exported e erl call lt options gt Start Call Erlang Erlang Interface 13 erl call Command Erl Interface Command Reference erl call Command erl call makesit possible to start and or communicate with a distributed Erlang node It is built upon the erl_interface library as an example application Its purpose is to use an Unix shell script to interact with a distributed Erlang node It performs all communication with the Erlang rex server using the standard Erlang RPC facility It does not require any special software to be run at the Erlang target node Themain use is to either start a distributed Erlang node or to make an ordinary function call However it is also possible to pipe an Erlang module to erl call and have it compiled or to pipe a sequence of Erlang expressions to be evaluated similar to the Erlang shell Options which cause stdin to be read can be used with advantage as scripts from within Unix shell scripts Another nice use of erl ca11 could be from http CG I bin scripts Exports erl call lt options gt Each option flag is described below with its name type and meaning a Mod Fun Args optional Applies the specified function and returns the result Mod must be specified howeve
9. getval instead int ei reg getval reg key flags v Types e ei reg reg e const char key e int flags e void v see below This is a general function for retrieving any kind of object from the registry reg is the registry where the object will be looked up key is the name of the object to look up flags indicates the type of object that you are looking for If flags is 0 then any kind of object will be returned If flags is one of ELINT El_FLT El_STR or EI BIN then only values of that kind will be returned The buffer pointed to by v must be large enough to hold the return data i e it must be a pointer to one of int double chart or void respectively Also if flags is EI BIN then a fifth argument int size is required so that the size of the object can be returned If the function succeeds v and size if the object is binary will be initialized with the value associated with key and the function will return one of ELINT EI FLT EI STR Erlang Interface 23 registry C Module Erl Interface Library Reference or EI_BIN indicating the type of object On failure the function will return 1 and the arguments will not be updated int ei reg markdirty reg key Types e ei reg reg e const char key Mark a registry object as dirty This will ensure that it is included in the next backup to M nesia Normally this operation will not be necessary since all of the normal registry set func
10. int port e struct in_addr addr These functions are used by a server process to register with the local name server epmd thereby allowing other processes to send messages by using the registered name Before calling either of these functions the process should have called bind and listen on an open socket N ote The use of erl_xpublish is deprecated Use erl publish instead port isthe local name to register and should be the same as the port number that was previously bound to the socket addr is the 32 bit IP address of the local host To unregister with epmd simply close the returned descriptor See also erl unpublish On success the functions return a descriptor connecting the calling process to epmd On failure they return 1 and set erl_errno to EIO I O error Additionally errno values from socket 2 and connect 2 system calls may be propagated into erl_errno int erl_accept listensock conp Types e int listensock e ErlConnect conp This function is used by a server process to accept a connection from a client process listensock is an open socket descriptor on which listen has previously been called conp is a pointer to an ErlConnect struct described as follows typedef struct char ipadr 4 char nodename MAXNODELEN ErlConnect Erlang Interface 35 erl_connect C Module Erl_Interface Library Reference const const const const short int 36 char char char char
11. map math sqrt 1 4 9 16 25 n madonna Evaluates a couple of expressions The input ends with EOF Control D erl call s e n madonna statistics runtime X 1 Y 2 _ T statistics runtime X Y T D ok 3 0 Compiles a module and runs it Again the input ends with EOF Control D In the example shown the output has been formatted afterwards Erlang Interface 15 erl call Command Erl Interface Command Reference 16 erl call s m a lolita n madonna module lolita compile export all start gt P processes F fun X gt X process_info X registered_name end lists map F P D lt madonna chivas du etx ericsson se 0 0 gt registered_name init lt madonna chivas du etx ericsson se 2 0 gt registered_name erl_prim_loader lt madonna chivas du etx ericsson se 4 0 gt registered_name error_logger lt madonna chivas du etx ericsson se 5 0 gt registered_name application_controller lt madonna chivas du etx ericsson se 6 0 gt registered_name kernel lt madonna chivas du etx ericsson se 7 0 gt O lt madonna chivas du etx ericsson se 8 0 gt registered_name kernel_sup lt madonna chivas du etx ericsson se 9 0 gt registered_name net_sup lt madonna chivas du etx ericsson se 10 0 gt registered_name net_kernel lt madonna chivas du etx ericsson se 11 0 gt C1 lt madonna chivas du etx ericsson se 12 0 gt register
12. number of elementsin array The function creates an Erlang list object whose length arrsize and whose elements are taken from the termsin array ETERM erl mk pid node number serial creation Types e const char node e unsigned int number e unsigned int serial e unsigned int creation This function creates an Erlang process identifier The resulting pid can be used by Erlang processes wishing to communicate with the C node node is the name of the C node number serial and creation are arbitrary numbers N ote though that these are limited in precision so only the low 15 3 and 2 bits of these numbers are actually used The function returns an Erlang pid object ERL PID NODE pid ERL PID NUMBER pid ERL PID SERIAL pid and ERL PID CREATION pid can be used to retrieve the four values used to create the pid ETERM erl mk port node number creation Types e const char node e unsigned int number e unsigned int creation This function creates an Erlang port identifier node is the name of the C node number and creation are arbitrary numbers N ote though that these are limited in precision so only the low 18 and 2 bits of these numbers are actually used The function returns an Erlang port object ERL PORT NODE port ERL PORT NUMBER port and ERL_PORT_CREATION can be used to retrieve the three values used to create the port ETERM erl mk ref node number creation 44 Types
13. objects will be overwritten with the new values If the registry contains objects that were not in the table they will be unchanged by this operation After the restore operation the entire contents of the registry is marked as unmodified Note that this includes any objects that were modified before the restore and not overwritten by the restore The function returns 0 on success or 1 on failure int ei reg setfval reg key f Types e ei reg reg e const char key e double f Create a key value pair with the specified key and floating point value f If an object already existed with the same key the new value replaces the old one If the previous value was a binary or string it is freed with free reg is the registry where the object should be placed key is the name of the object f is the floating point value to assign The function returns 0 on success or 1 on failure int ei_reg_setival reg key i Types e ei reg reg e const char key Erlang Interface 25 registry C Module Erl Interface Library Reference e int i Create a key value pair with the specified key and integer value i If an object already existed with the same key the new value replaces the old one If the previous value was a binary or string it is freed with free reg is the registry where the object should be placed key is the name of the object i is the integer value to assign The function returns 0 on success
14. or 1 on failure int ei_reg_setpval reg key p size Types e ei reg reg e const char key e const void p e int size Create a key value pair with the specified key whose value is the binary object pointed to by p If an object already existed with the same key the new value replaces the old one If the previous value was a binary or string it is freed with free reg is the registry where the object should be placed key is the name of the object pisa pointer to the binary object The object itself must have been created through a single call to malloc or similar function so that the registry can later delete it if necessary by calling free size isthe length in bytes of the binary object The function returns 0 on success or 1 on failure int ei reg setsval reg key s Types e ei reg reg e const char key e const char 5 Create a key value pair with the specified key whose value is the specified string s If an object already existed with the same key the new value replaces the old one If the previous value was a binary or string it is freed with free reg is the registry where the object should be placed key is the name of the object s isthe string to assign The string itself must have been created through a single call to malloc or similar function so that the registry can later delete it if necessary by calling free The function returns 0 on success or 1 on f
15. the buffer In this Case you should call erl receive msgO again On success the function returns ERL MSG and the Emsg struct will be initialized as described above or ERL_TICK in which case no message is returned On failure the function returns ERL ERROR and will set erl_errno to one of 32 Erlang Interface Erl Interface Library Reference erl connect C Module EMSGSIZE Buffer too small ENOMEM No more memory available EIO O error int erl xreceivemsg fd bufpp bufsizep emsg Types e int fd e unsigned char bufpp e int bufsizep e ErlM essage emsg This function is similar to erl_receive_msg The difference is that er1 xreceive msg expects the buffer to have been allocated by malloc and reallocates it if the received message does not fit into the original buffer For that reason both buffer and buffer length are given as pointers their values may change by the call On success the function returns ERL_MSG and the Emsg struct will be initialized as described above or ERL_TICK in which case no message is returned On failure the function returns ERL_ERROR and will set erl_errno to one of EMSGSIZE Buffer too small ENOMEM No more memory available EIO I O error int erl_send fd to msg Types e int fd e ETERM to msg This function sends an Erlang term to a process fd is an open descriptor to an Erlang connection to isan Erlang term containing the Pid of the intended recipient of the messa
16. the erl interface library Erlang Interface Erl Interface Library Reference erl_error C Module void void void void erl error C M odule This module contains some error printing routines taken from A dvanced Programming in theUNIX Environment by W Richard Stevens These functions are all called in the same manner as printf i e with a string containing format specifiers followed by a list of corresponding arguments All output from these functions is to stderr Exports erl err msg FormatStr Types e const char FormatStr The message provided by the caller is printed This function is simply a wrapper for fprintf 0 erl err quit FormatStr Types e const char FormatStr Use this function when a fatal error has occurred that is not due to a system call The message provided by the caller is printed and the process terminates with an exit value of 1 The function does not return erl err ret FormatStr Types e const char FormatStr Use this function after a failed system call The message provided by the caller is printed followed by a string describing the reason for failure erl err sys FormatStr Types e const char FormatStr Use this function after a failed system call The message provided by the caller is printed followed by a string describing the reason for failure and the process terminates with an exit value of 1 The function does not return E
17. the system ei reg close reg Backing up the registry to Mnesia The contents of a registry can be backed up to M nesia on a nearby Erlang node Y ou need to provide an open connection to the Erlang node see er1 connect Also M nesia 3 0 or later must be running on the Erlang node before the backup is initiated ei reg dump fd reg mtab dumpflags The example above will backup the contents of the registry to the specified M nesia table mtab O nce a registry has been backed up to M nesia in this manner additional backups will only affect objects that have been modified since the most recent backup i e objects that have been created changed or deleted The backup operation is done as a single atomic transaction so that the entire backup will be performed or none of it will In the same manner a registry can be restored from a M nesia table ei reg restore fd reg mtab This will read the entire contents of mtab into the specified registry After the restore all of the objects in the registry will be marked as unmodified so a subsequent backup will only affect objects that you have modified since the restore Note that if you restore to a non empty registry objects in the table will overwrite objects in the registry with the same keys A Iso the entire contents of the registry is marked as unmodified after the restore including any modified obects that were not overwritten by the restore operation This m
18. 2 answer int sockfd rc char buf BUFSIZE ErlMessage emsg if rc erl_receive_msg sockfd buf BUFSIZE amp emsg ERL MSG arr 0 erl_mk_atom goodbye arr 1 erl_element 1 emsg msg answer erl_mk_tuple arr 2 erl send sockfd arr 1 answer Erlang Interface 7 Chapter 1 Ere Interface User s Guide erl free term answer erl free term emsg msg erl free termlemsg to In order to provide robustness a distributed Erlang node occasionally polls all its connected neighbours in an attempt to detect failed nodes or communication links node which receives such a message is expected to respond immediately with an ERL_TICK message This is done automatically by erl receive however when this has occurred erl receive returns ERL TICK to the caller without storing a message into the Er1Message structure W hen a message has been received it is the caller s responsibility to free the received message ensg msg as well as emsg to Or emsg from depending on the type of message received Refer to the Reference M anual for additional information about the following modules e erl connect e erl_eterm Remote Procedure Calls An Erlang node acting as a client to another Erlang node typically sends a request and waits for a reply Such a request is included in a function call at a remote node and is called a remote procedure call The following example shows how the erl_interface library sup
19. 2 C function 37 erl_errno C function 38 erl_eterm erl_cons 2 C function 40 58 42 erl_length 1 C function 42 erl mk atom 1 C function 42 erl mk binary 2 C function 42 erl mk empty list 0 C function 43 erl mk estring 2 C function 43 erl mk float 1 C function 43 erl mk int 1 C function 43 erl mk list 2 C function 43 erl mk long ref 5 C function 45 erl mk pid 4 C function 44 erl mk port 3 C function 44 erl mk ref 3 C function 44 erl mk string 1 C function 45 erl mk tuple 2 C function 45 erl mk uint 1 C function 46 erl mk var 1 C function 46 erl print term 2 C function 46 erl size 1 C function 46 erl t1 1 C function 47 erl var content 2 C function 47 erl eterm release 1 C function erl malloc 52 erl eterm statistics 2 C function erl malloc 52 erl ext size 1 C function erl marshal 55 erl ext type 1 C function erl marshal 55 erl format erl format 2 C function 48 erl match 2 C function 48 erl format 2 C function erl format 48 erl free 1 C function erl malloc 53 erl free array 2 C function erl malloc 53 erl free compound 1 C function erl malloc 53 Erlang Interface erl free term 1 C function erl malloc 53 erl global erl global names 2 C function 50 erl global register 3 C function 50 erl global unregister 2 C function 51 erl global whereis 3 C function 51 erl global names 2 C function erl globa
20. Erlang Interface version 3 2 Typeset in LATEX from SGML source using the DO CBUILDER 3 0 Document System Contents 1 Erl Interface U ser s G uide 1 1 TheErl InterfaceLibrary Compilingand Linkingyour code Initializing the erl interface Library Encoding D ecoding and Sending Erlang T erms Building Terms and Patterns Pattern Matching Connecting to a Distributed Erlang Node Using EPMD Sending and Receiving Erlang M essages Remote Procedure Calls Using Global Names The Registry 2 Erl Interface Command Reference 21 erl_call Command 3 Erl Interface Library Reference 3 1 3 2 3 3 3 4 3 5 3 6 3 7 3 8 registry C Module erl connect C Module erlerror C Module erl_eterm C Module erl format C Module erl global C Module erl malloc C Module erl marshal C Module Erlang Interface O ON OA UN W WU N N e 10 Erlang Interface Chapter 1 Eri Interface User s Guide Erlang Interface 1 1 The En Interface Library The erl_interface library contains functions which help you integrate programs written in C and Erlang The functions in erl interface support the following e manipulation of data represented as Erlang data types e c
21. Erlang Interface 49 erl global C Module Erl Interface Library Reference erl global C M odule This module provides support for registering looking up and unregistering names in the Erlang Global module For more information see the description of Global in the reference manual Exports char erl global names fd count int 50 Types e int fd e int count Retrieve a list of all known global names fd isan open descriptor to an Erlang connection count is the address of an integer or NULL If count is not NULL it will be set by the function to the number of names found On success the function returns an array of strings each containing a single registered name and sets count to the number of names found The array is terminated by a single NULL pointer On failure the function returns NULL and count is not modified Note It is the caller s responsibility to free the array afterwards It has been allocated by the function with a single call to malloc so a single free is all that is necessary erl global register fd name pid Types e int fd e const char name e ETERM pid Erlang Interface Erl Interface Library Reference erl global C Module This function registers a name in Global fd is an open descriptor to an Erlang connection name is the name to register in Global pid is the pid that should be associated with name This is the value that Global will return when proc
22. However since many of the functions that build new Erlang terms in fact share objects with other existing terms it may be difficult for the programmer to maintain pointers to all such terms in order to free them individually erl free compound will recursively free all of the sub terms associated with a given Erlang term regardless of whether we are still holding pointers to the sub terms There is an example in the User M anual under Building Terms and Patterns void erl malloc size Types e long size This function calls the standard malloc function void erl_free ptr Types e void ptr This function calls the standard free O function Erlang Interface 53 erl marshal C Module Erl Interface Library Reference erl marshal C M odule This module contains functions for encoding Erlang terms into a sequence of bytes and for decoding Erlang terms from a sequence of bytes Exports int erl compare ext bufpl bufp2 Types e unsigned char bufp1 bufp2 This function compares two encoded terms bufp1 is a buffer containing an encoded Erlang term term1 bufp2 is a buffer containing an encoded Erlang term term2 The function returns 0 if the terms are equal 1 if term1 is less than term2 or 1 if term2 is less than term1 ETERM erl_decode bufp ETERM erl_decode_buf bufpp Types e unsigned char bufp e unsigned char bufpp erl_decode and erl_decode_buf decode the contents of a buffer and re
23. M erl_mk_uint n Creates an unsigned integer ETERM erl_mk_var name Creates an Erlang variable int erl_print_term stream term Prints an Erlang term int erl_size term Returns the arity of a tuple or binary ETERM x erl tl list Extracts the tail from a list ETERM erl var content term name Extracts the content of a variable Erlang Interface 19 Erl Interface Library Reference eri format The following functions are exported e ETERM erl format FormatStr Creates an Erlang term e int erl_match Pattern Term Performs pattern matching eri global The following functions are exported e char erl global names fd count O btain list of Global names e int erl global register fd name pid Register a name in Global e int erl global unregister fd name Unregister a name in Global e ETERM erl global whereis fd name node Look up a name in global er malloc T he following functions are exported e ETERM erl_alloc_eterm etype Allocates an ETERM structure e void erl_eterm release void Clears the ETERM freelist e void erl_eterm_statistics allocated freed Reports term allocation statistics e void erl free array array size Frees an array of ETERM structures e void erl free term t Frees an ETERM structure e void erl_free_compound t Frees an array of ETERM structures e void erl malloc size Allocates some memory e void erl_free ptr Frees some memory eri marshal The following fu
24. a the objects can also be removed from the M nesia table If you are not backing up to M nesia then you may wish to remove the objects manually with this function reg is a registry containing objects marked for deletion The function returns 0 on success or 1 on failure int ei_reg_resize reg newsize Types e ei reg reg e int newsize 24 Erlang Interface Erl Interface Library Reference registry C Module Change the size of a registry newsize is the new size to make the registry The number will be increased to the nearest larger prime number On success the registry will be resized all contents rehashed and the function will return 0 On failure the registry will be left unchanged and the function will return 1 int ei reg restore fd reg mntab Types e int fd e ei reg reg e const char mntab The contents of a M nesia table are read into the registry fd isan open connection to Erlang M nesia 3 0 or later must be running on the Erlang node reg is the registry where the data should be placed mntab is the name of the M nesia table to read data from Note that only tables of a certain format can be restored i e those that have been created and backed up to with ei reg dump 0 If the registry was not empty before the operation then the contents of the table are added to the contents of the registry If the table contains objects with the same keys as those already in the registry the registry
25. ailure int eireg setval reg key flags v Types e ei reg reg 26 Erlang Interface Erl Interface Library Reference registry C Module e const char key e int flags e V see below Create a key value pair with the specified key whose value is specified by v If an object already existed with the same key the new value replaces the old one If the previous value was a binary or string it is freed with free reg is the registry where the object should be placed key is the name of the object flags indicates the type of the object specified by v Flags must be one of EI INT EI FLT El_STR and EI_BIN indicating whether v is int double char or voidx If flags isEI BIN then a fifth argument size is required indicating the size in bytes of the object pointed to by v If you wish to store an arbitrary pointer in the registry specify a size of 0 In this case the object itself will not be transferred by an ei reg dump operation just the pointer value The function returns 0 on success or 1 on failure int ei reg stat reg key obuf Types e ei reg reg e const char key e struct ei reg stat obuf Return information about an object reg is the registry containing the object key is the name of the object obuf isa pointer to an ei reg stat structure defined below struct ei reg stat int attr int size In attr the object s attributes are stored as the logical OR of its type one
26. ay not be your intention Erlang Interface 11 Storing strings and binaries When string or binary objects are stored in the registry it is important that a number of simple guidelines are followed Most importantly the object must have been created with a single call to malloc or similar so that it can later be removed by a single call to free Objects will be freed by the registry when it is closed or when you assign a new value to an object that previously contained a string or binary You should also be aware that if you store binary objects that are context dependent e g containing pointers or open file descriptors they will lose their meaning if they are backed up to a Mnesia table and subsequently restored in a different context When you retrieve a stored string or binary value from the registry the registry maintains a pointer to the object and you are passed a copy of that pointer You should never free an object retrieved in this manner because when the registry later attempts to free it a runtime error will occur that will likely cause the C node to crash You are free to modify the contents of an object retrieved this way However when you do so the registry will not be aware of the changes you make possibily causing it to be missed the next time you make a M nesia backup of the registry contents This can be avoided if you mark the object as dirty after any such changes with ei_reg_markdirty or pass appropriate
27. be removed from the M nesia table as well If another object is later created with the same key the object will be reused The object will be removed from the registry after a call to ei reg dump or ei reg purge reg is the registry containing key key is the object to remove If the object was found the function returns 0 indicating success O therwise the function returns 1 int ei reg dump fd reg mntab flags Types e int fd e ei reg reg e const char mntab Erlang Interface 21 registry C Module Erl Interface Library Reference e int flags Dump the contents of a registry to a Mnesia table in an atomic manner i e either all data will be updated or none of it will If any errors are encountered while backing up the data the entire operation is aborted fd isan open connection to Erlang M nesia 3 0 or later must be running on the Erlang node reg is the registry to back up mntab is the name of the M nesia table where the backed up data should be placed If the table does not exist it will be created automatically using configurable defaults See your Mnesia documentation for information about configuring this behaviour If flags is 0 the backup will include only those objects which have been created modified or deleted since the last backup or restore i e an incremental backup After the backup any objects that were marked dirty are now clean and any objects that had been marked for deletion ar
28. ch is successful any unbound variables in the pattern will be bound as a side effect The content of a bound variable can then be retrieved ETERM pattern pattern erl_format madonna Age _ erl_match is used to perform pattern matching It takes a pattern and a term and tries to match them Asa side effect any unbound variables in the pattern will be bound In the following example we create a pattern with a variable A ge which appears at two positions in the tuple The pattern match is performed as follows 1 erl match 0 will bind the contents of A geto 21 the first time it reaches the variable 2 the second occurrence of A ge will cause a test for equality between the terms since A ge is already bound to 21 Since A geis bound to 21 the equality test will succeed and the match continues until the end of the pattern 3 if the end of the pattern is reached the match succeeds and you can retrieve the contents of the variable ETERM pattern term pattern erl_format madonna Age Age term erl_format madonna 21 21 if erl match pattern term fprintf stderr Yes they matched Age ep erl var content pattern Age erl print term stderr ep fprintf stderr n erl_free_term ep erl_free_term pattern erl_free_term term Refer to the Reference M anual the er1 match function for more information Also refer to your Erlang manual for information about pattern matc
29. e ERL_LIST ERL_TUPLE ERL_BINARY ERL_FLOAT ERL_VARIABLE ERL SMALL BIG bignum ERL_U SMALL BIG bignum ERL_SMALL_BIG and ERL_U_SMALL_BIG are for creating Erlang bignums which can contain integers of arbitrary size The size of an integer in Erlang is machine dependent but in general any integer larger than 2728 requires a bignum void erl_eterm_release void Clears the freelist where blocks are placed when they are released by erl_free_term and erl_free_compound void erl_eterm_statistics allocated freed 52 Erlang Interface Erl Interface Library Reference erl malloc C Module Types e long allocated e long reed allocated and freed are initialized to contain information about the fix allocator used to allocate ETERM components allocated is the number of blocks currently allocated to ETERM objects freed is the length of the freelist where blocks are placed when they are released by erl_free_term and erl free compound void erl_free_array array size Types e ETERM array e int size This function frees an array of Erlang terms array isan array of ETERM objects size is the number of terms in the array void erl_free_term t Types e ETERM t Use this function to free an Erlang term void erl_free_compound t Types e ETERM t Normally it isthe programmer s responsibility to free each Erlang term that has been returned from any of the erl_interface functions
30. e decoded ErlMessage is defined as follows typedef struct int type ETERM msg ETERM to ETERM from char to name MAXREGLEN ErlMessage Note The definition of Er1Message has changed since earlier versions of Erl Interface type identifies the type of message one of ERL SEND ERL REG SEND ERL LINK ERL UNLINK and ERL_EXIT If type contains ERL SEND this indicates that an ordinary send operation has taken place and emsg to contains the Pid of the recipient If type contains ERL_REG_SEND then a registered send operation took place and emsg 5 from contains the Pid of the sender In both cases the actual message will be in emsg gt msg If type contains one of ERL_LINK or ERL_UNLINK then emsg gt to and emsg gt from contain the pids of the sender and receipient of the link or unlink emsg gt msg is not used in these cases If type contains ERL_EXIT then this indicates that a link has been broken In this case emsg gt to and emsg gt from contain the pids of the linked processes and emsg gt msg contains the reason for the exit N ote It is the caller s responsibility to release the memory pointed to by emsg gt msg emsg gt to and emsg gt from If atick occurs i e the Erlang node on the other end of the connection has polled this node to see if it is still alive the function will return ERL TICK indicating that the tick has been received and responded to but no message will be placed in
31. e deleted Alternatively setting flags to EI_FORCE will cause a full backup to be done and EILNO PURGE will cause the deleted objects to be left in the registry afterwards These can be bitwise O Red together if both behaviours are desired If El NOPURGE was specified you can use ei_reg_purge to explicitly remove the deleted items from the registry later The function returns 0 on success or 1 on failure double ei_reg_getfval reg key Types e ei reg reg e const char key Get the value associated with key in the registry The value must be a floating point type reg is the registry where the object will be looked up key is the name of the object to look up On success the function returns the value associated with key If the object was not found or it was not a floating point object 1 0 is returned To avoid problems with in band error reporting i e if you cannot distinguish between 1 0 and a valid result use the more general function ei reg getval instead int ei reg getival reg key Types e ei reg reg e const char key Get the value associated with key in the registry The value must be an integer reg is the registry where the object will be looked up key is the name of the object to look up On success the function returns the value associated with key If the object was not found or it was not an integer object 1 is returned To avoid problems with in band error reporting i e if you can
32. e variable can later be bound through pattern matching or assignment name specifies a name for the variable The function returns an Erlang variable object with the name name erl_print_term stream term Types e FILE stream e ETERM term This function prints the specified Erlang term to the given output stream stream indicates where the function should send its output term is the Erlang term to print The function returns the number of characters written or a negative value if there was an error erl_size term Types e ETERM term Erlang Interface Erl Interface Library Reference erl eterm C Module Returns the arity of an Erlang tuple or the number of bytes in an Erlang binary object term isan Erlang tuple or an Erlang binary object The function returns the size of term as described above or 1 if term isnot one of the two supported types ETERM erl tl list Types e ETERM ist Extracts the tail from a list list isan Erlang term containing a list The function returns an Erlang list corresponding to the original list minus the first element or NULL pointer if 1ist was not a list ETERM erl var content term name Types e ETERM term e char name This function returns the contents of the specified variable in an Erlang term term is an Erlang term In order for this function to succeed term must be an Erlang variable with the specified name or it must be an Erlang list or tup
33. ect const void ei reg getpval reg key size Get a binary object const char ei reg getsval reg key Get a string object int int ei reg getval reg key flags v Get any object ei reg markdirty reg key Mark an object as dirty ei_reg ei regopen size Create and open a registry int int int int int int ei reg purge reg Remove deleted objects ei reg resize reg newsize Resize a registry ei reg restore fd reg mntab Restore a registry from M nesia ei reg setfval reg key f Assign a floating point object ei reg setival reg key i Assign an integer object ei reg setpval reg key p size Assign a binary object Erlang Interface 17 int int int int Erl Interface Library Reference ei reg setsval reg key s Assign a string object ei reg setval reg key flags v Assign a value to any object type ei reg stat reg key obuf Get object information ei reg tabstat reg obuf Get registry information er connect The following functions are exported int int erl connect init number cookie creation Initializes communication erl connect xinit host alive node addr cookie creation Initializes communication int int int int int erl connect node Establishes a connection to an Erlang node erl xconnect addr alive Establishes a connection to an Erlang node erl close connection fd Closes a connection to an Erlang node erlreceive fd bufp bufsize Receives a messa
34. ed_name global_name_server lt madonna chivas du etx ericsson se 13 0 gt registered_name auth lt madonna chivas du etx ericsson se 14 0 gt registered_name rex lt madonna chivas du etx ericsson se 15 0 gt O lt madonna chivas du etx ericsson se 16 0 gt registered_name file_server lt madonna chivas du etx ericsson se 17 0 gt registered_name code_server lt madonna chivas du etx ericsson se 20 0 gt registered_name user lt madonna chivas du etx ericsson se 38 0 gt bd Erlang Interface Eri Interface Library Reference Short Summaries e C Library Registry page 21 Store and backup key value pairs C Library erl connect page 29 Communicate with Distributed Erlang C Library erl error page 37 Error Print Routines C Library erl_eterm page 39 Functions for Erlang Term Construction C Library erl format page 48 Create and M atch Erlang Terms C Library erl global page 50 Access globally registered names C Library erl malloc page 52 Memory Allocation Functions C Library erl marshal page 54 Encoding and Decoding of Erlang terms Registry The following functions are exported int int int ei_reg_close reg Close a registry ei reg delete reg key Delete an object from the registry ei_reg_dump fd reg mntab flags Back up a registry to M nesia double ei reg getfval reg key Get a floating point object int ei reg getival reg key Get an integer obj
35. eg dump 4 C function registry 21 ei reg getfval 2 C function registry 22 ei reg getival 2 C function registry 22 ei_reg_getpval 3 C function registry 23 ei_reg_getsval 2 C function registry 23 ei_reg_getval 5 C function registry 23 ei reg markdirty 2 C function registry 24 ei reg open 1 C function registry 24 ei reg purge 1 C function registry 24 ei reg resize 2 C function registry 24 ei reg restore 3 C function registry 25 ei reg setfval 3 C function registry 25 ei reg setival 3 C function registry 25 ei reg setpval 4 C function registry 26 ei reg setsval 3 C function registry 26 ei reg setval 5 C function registry 26 ei reg stat 3 C function registry 27 ei reg tabstat 2 C function registry 27 erl accept 2 C function erl connect 35 erl alloc eterm 1 C function erl malloc 52 erl_call erl_call lt options gt Command 14 erl_call lt options gt Command erl_call 14 erl close connection 1 C function erl connect 31 erl compare ext 2 C function erl marshal 54 erl connect erl accept 2 C function 35 erl close connection 1 C function 31 erl connect 1 C function 30 erl connect init 3 C function 29 erl connect xinit 6 C function 29 erl_publish 1 C function 35 erl receive 3 C function 31 erl receive msg 4 C function 31 erl reg send 3 C function 33 erl rpc 4 C function 34 erl rpc fro
36. encode buf bufpp will be updated so that it points to the position for the next encoded term These functions return 0 in success or 1 if term was not a valid Erlang term Note that no bounds checking is done on the buffer It is the caller s responsibility to make sure that the buffer is large enough to hold the encoded terms Y ou can either use a static buffer that is large enough to hold the terms you expect to need in your program or use erl_term_len to determine the exact requirements for a given term The following can help you estimate the buffer requirements for a term Note that this information is implementation specific and may change in future versions If you are unsure Use erl term len Erlang terms are encoded with a 1 byte tag that identifies the type of object a 2 or 4 byte length field and then the data itself Specifically Tuples need 5 bytes plus the space for each element Lists need 5 bytes plus the space for each element and 1 additonal byte for the empty list at the end Strings and atoms need 3 bytes plus 1 byte for each character the terminating 0 is not encoded Really long strings more than 64k characters are encoded as lists Atoms cannot contain more than 256 characters Integers need 5 bytes Characters integers lt 256 need 2 bytes Floating point numbers need 32 bytes Pids need 10 bytes plus the space for the node name which is an atom Ports and Refs need 6 bytes plus
37. erl_free_compound ep Asin previous examples it is your responsibility to free the memory allocated for Erlang terms In this example erl_free_compound ensures that the complete term pointed to by ep is released This is necessary because the pointer from the second call to er1 format is lost The following example shows a slightly different solution ETERM ep ep2 ep2 erl_format adr s i E street 42 ep erl_format name a age i data w madonna 21 ep2 erl_free_term ep erl_free_term ep2 In this case you free the two terms independently The order in which you free the terms ep and ep2 is not important because the erl_interface library uses reference counting to determine when it is safe to actually remove objects If you are not sure whether you have freed the terms properly you can use the following function to see the status of the fixed term allocator long allocated freed erl_eterm_statistics amp allocated amp freed printf currently allocated blocks 1d n allocated printf length of freelist 41d n freed really free the freelist erl_eterm_release Refer to the Reference M anual the erl_malloc module for more information 4 Erlang Interface 1 1 The Erim Interface Library Pattem Matching An Erlang pattern is a term that may contain unbound variables or do not care symbols Such a pattern can be matched against a term and if the mat
38. erm The following functions are exported ETERM erl cons head tail Prepends a term to the head of a list ETERM x erl_copy_term term Creates a copy of an Erlang term ETERM erl element position tuple Extracts an element from an Erlang tuple void erl init NULL 0 Initialization routine ETERM erl hd list Extracts the first element from a list ETERM erl iolist to binary term Converts an IO list to a binary char erLiolist to string list Convertsan IO list to a zero terminated string int erl iolist length list Returns the length of an IO list int erl length list Determines the length of a list ETERM erl mk atom string Creates an atom ETERM erl_mk_binary bptr size Creates a binary object ETERM erl mk empty list Creates an empty Erlang list ETERM erl mk estring string len Creates an Erlang string ETERM erl mk float f Creates an Erlang float ETERM erl mk int n Creates an Erlang integer ETERM erl_mk_list array arrsize Creates a list from an array ETERM erl mk pid node number serial creation Creates a process identifier ETERM erl mk port node number creation Creates a port identifier ETERM erl mk ref node number creation Creates an old Erlang reference ETERM erl mk long ref node ni n2 n3 creation Creates an Erlang reference ETERM erl mk string string Creates a string ETERM erl_mk_tuple array arrsize Creates an Erlang tuple from an array ETER
39. esses request the location of name The function returns 0 on success or 1 on failure int erl global unregister fd name Types e int fd e const char name This function unregisters a name from Global fd is an open descriptor to an Erlang connection name is the name to unregister from Global The function returns 0 on success or 1 on failure ETERM erl global whereis fd name node Types e int fd e const char name e char node fd is an open descriptor to an Erlang connection name is the name that is to be looked up in Global If node is not NULL it isa pointer to a buffer where the function can fill in the name of the node where name is found node can be passed directly to er1 connect if necessary On success the function returns an Erlang Pid containing the address of the given name and node will be initialized to the nodename where name is found On failure NULL will be returned and node will not be modified Erlang Interface 51 erl_malloc C Module Erl_Interface Library Reference erl malloc C Module This module provides functions for allocating and deallocating memory Exports ETERM erl alloc eterm etype Types e unsigned char etype This function allocates an ETERM structure Specify etype as one of the following constants ERL STRING ERL_INTEGER ERL U INTEGER unsigned integer ERLATOM ERL_PID Erlang process identifier ERL_PORT ERL_REF Erlang referenc
40. eterm 45 erl mk pid 4 C function erl eterm 44 erl mk port 3 C function erl_eterm 44 erl mk ref 3 C function erl eterm 44 erl mk string 1 C function erl eterm 45 erl mk tuple 2 C function erl eterm 45 erl mk uint 1 C function erl eterm 46 erl mk var 1 C function erl eterm 46 erl peek ext 2 C function erl marshal 56 erl print term 2 C function erl eterm 46 erl_publish 1 C function erl connect 35 erl receive 3 C function Erlang Interface 59 Index erl connect 31 erl receive msg 4 C function erl_connect 31 erl reg send 3 C function erl connect 33 erl rpc 4 C function erl connect 34 erl_rpc_from 3 C function erl connect 34 erl rpc to 4 C function erl connect 34 erl send 3 C function erl_connect 33 erl size 1 C function erl_eterm 46 erl term len 1 C function erl marshal 56 erl thisalivename 0 C function erl connect 36 erl_thiscookie 0 C function erl connect 36 erl_thiscreation 0 C function erl connect 36 erl thishostname 0 C function erl connect 36 erl thisnodename 0 C function erl connect 36 erl t1 1 C function erl eterm 47 erl unpublish 1 C function erl connect 36 erl var content 2 C function erl eterm 47 erl xconnect 2 C function erl connect 30 erl xpublish 2 C function erl connect 35 erl xreceive msg 4 C function erl connect 33 registry
41. find out the correct port number to connect to When you use er1 connect to connect to an Erlang node a connection is first made to epmd and if the node is known a connection is then made to the Erlang node C nodes can also register themselves with epmd if they want other nodes in the system to be able to find and connect to them Before registering with epmd you need to first create a listen socket and bind it to a port Then int pub pub erl_publish port pub isa file descriptor now connected to epmd Epmd monitors the other end of the connection and if it detects that the connection has been closed the node will be unregistered So if you explicitly close the descriptor or if your node fails it will be unregistered from epmd Be aware that on some systems such as V xW orks a failed node will not be detected by this mechanism since the operating system does not automatically close descriptors that were left open when the node failed If a node has failed in this way epmd will prevent you from registering a new node with the old name since it thinks that the old name is still in use In this case you must unregister the name explicitly erl_unpublish node This will cause epmd to close the connection from the far end Note that if the name was in fact still in use by a node the results of this operation are unpredictable Also doing this does not cause the local end of the connection to close so resources may be c
42. g c When linking you will need to specify the path to liberl interface a and libei a with L OTPROOT lib ei 3 1 lib and you will need to specify the name of the libraries with lerl interface lei You can do this on the command line or by adding the flags to the LDFLAGS definition in your Makefile ld L usr local otp lib ei 3 1 1ib myprog o lerl interface lei o myprog Also on some systems it may be necessary to link with some additional libraries e g 1ibns1 a and libsocket a 0n Solaris Or wsock32 1ib on Windows in order to use the communication facilities of erl interface If you are using erl interface functions in a threaded application based on PO SIX threads or Solaris threads then erl_interface needs access to some of the synchronization facilities in your threads package and you will need to specify additional compiler flags in order to indicate which of the packages you are using Define REENTRANT and either STHREADS or PTHREADS The default is to use POSIX threads if REENTRANT is specified Initializing the er interface Library Before calling any of the other erl interface functions you must call erl init exactly once to initialize the library er1 init takes two arguments however the arguments are no longer used by erl_interface and should therefore be specified as erl init NULL 0 Encoding Decoding and Sending Erlang Terms D ata sent between distributed Erlang nodes is encoded in the Erlang external f
43. ge msg is the Erlang term to be sent The function returns 1 if successful otherwise 0 in which case it will set erl_errno to one of EINVAL Invalid argument to is not a valid Erlang pid ENOMEM No more memory available EIO I O error int erl reg send fd to msg Types e int fd e char to e ETERM msg Erlang Interface 33 erl_connect C Module Erl_Interface Library Reference This function sends an Erlang term to a registered process fd is an open descriptor to an Erlang connection to is a string containing the registered name of the intended recipient of the message msg is the Erlang term to be sent The function returns 1 if successful otherwise 0 in which case it will set er1_errno to one of ENOMEM No more memory available EIO I O error ETERM erlrpc fd mod fun args int int 34 erlrpcto fd mod fun args erlrpc from fd timeout emsg Types e int fd timeout e char mod fun e ETERM args e ErlM essage emsg These functions support calling Erlang functions on remote nodes erl_rpc_to sends an rpc request to a remote node and erl rpc from receives the results of such a call erl_rpc combines the functionality of these two functions by sending an rpc request and waiting for the results See also rpc ca11 4 fd is an open descriptor to an Erlang connection timeout is the maximum time in ms to wait for results Specify ERL_NO_TIMEOUT to wait fore
44. ge erl_receivemsg fd bufp bufsize emsg Receives and decodes a message int erl_xreceivemsg fd bufpp bufsizep emsg Receives and decodes a message int int erl_send fd to msg Sends a message erl reg send fd to msg Sends a message to a registered name ETERM erlrpc fd mod fun args Remote Procedure Call int int int int int erl_rpc_to fd mod fun args Remote Procedure Call erl_rpc_from fd timeout emsg Remote Procedure Call erl_publish port Publishes anode name erl_xpublish port addr Publishes a node name erl accept listensock conp Accepts a connection const char erl thiscookie Retrieves some values const char erl thisnodename Retrieves some values const char erl thishostname Retrieves some values const char erl_thisalivename Retrieves some values short erl_thiscreation Retrieves some values int erl unpublish alive Unpublishes a node name erl error The following functions are exported e void erl err msg FormatStr Non fatal error and not system call error e void erl_err_quit FormatStr Fatal error but not system call error 18 Erlang Interface Erl Interface Library Reference void erl err ret FormatStr Non fatal system call error void erl_err_sys FormatStr Fatal system call error volatile int erl errno The variable erl errno contains the erl interface error number You can change the value if you wish eri et
45. hat fully qualified long node names are used If the s option is given an Erlang node will if necessary be started with erl name q optional Halts the Erlang node specified with the n switch This switch overrides the s switch r optional G enerates a random name of the hidden node that er1_cal1 represents s optional Starts a distributed Erlang node if necessary This means that in a sequence of calls where the s and n Node are constant only the first call will start the Erlang node This makes the rest of the communication very fast This flag is currently only available on the Unix platform sname Node one of n name sname is required Node is the name of the node to be started or communicated with It is assumed that Node is started with er1 sname which means that short node names are used If s option is given an Erlang node will be started if necessary with erl sname v optional Prints a lot of verbose information This is only useful for the developer and maintainer of erl call X ErlScript optional Specifies another name of the Erlang start up script to be used If not specified the standard er1 start up script is used Examples Starts an Erlang node and calls erlang time 0 erl call s a erlang time n madonna 18 27 34 Terminates an Erlang node by calling erlang halt 0 erl call s a erlang halt n madonna An apply with several arguments erl call s a lists
46. hing Connecting to a Distributed Erlang Node In order to connect to a distributed Erlang node you need to first initialize the connection routine with erl connect init which stores information such as the host name node name and IP address for later use int identification_number 99 int creation 1 char cookie a secret cookie string An example erl connect init identification number cookie creation Erlang Interface 5 Chapter 1 Erlm Interface User s Guide Refer to the Reference M anual the er1 connect module for more information After initialization you set up the connection to the Erlang node Use erl1 connect to specify the Erlang node you want to connect to The following example sets up the connection and should result in a valid socket file descriptor int sockfd char nodename xyz chivas du etx ericsson se An example if sockfd erl connect nodename lt 0 erl err quit ERROR erl connect failed erl err quit prints the specified string and terminates the program Refer to the Reference M anual the erl error function for more information Using EPMD Epmd is the Erlang Port M apper D aemon D istributed Erlang nodes register with epmd on the localhost to indicate to other nodes that they exist and can accept connections Epmd maintains a register of node and port number information and when a node wishes to connect to another node it first contacts epmd in order to
47. inary data ERL BIN SIZE bin retrieves the size ETERM erl mk empty list This function creates and returns an empty Erlang list N ote that NULL is not used to represent an empty list U se this function instead ETERM erl mk estring string len Types e char string e int len This function creates a list from a sequence of bytes string isa buffer containing a sequence of bytes The buffer does not need to be zero terminated lenisthe length of string The function returns an Erlang list object corresponding to the character sequence in string ETERM erl mk float f Types e double f Creates an Erlang float f isa value to be converted to an Erlang float The function returns an Erlang float object with the value specified in ERL FLOAT VALUE t can be used to retrieve the value from an Erlang float ETERM erl mk int n Types e intn Creates an Erlang integer nisavalueto be converted to an Erlang integer Thefunction returns an Erlang integer object with the value specified in n ERL INT VALUE t can be used to retrieve the value value from an Erlang integer ETERM erl mklist array arrsize Types e ETERM array Erlang Interface 43 erl eterm C Module Erl Interface Library Reference e int arrsize Creates an Erlang list from an array of Erlang terms such that each element in the list corresponds to one element in the array array isan array of Erlang terms arrsize is the
48. inary objects struct bonk tb malloc sizeof xb char name malloc 7 ei_reg_setival reg age 29 ei_reg_setfval reg height 1 85 strcpy name Martin ei reg setsval reg name name b gt 1 42 b gt m 12 ei reg setpval reg jox b sizeof b If you attempt to store an object in the registry and there is an existing object with the same key the new value will replace the old one This is done regardless of whether the new object and the old one have the same type so you can for example replace a string with an integer If the existing value is a string or binary it will be freed before the new value is assigned Stored values are retrieved from the registry as follows 10 Erlang Interface 1 1 The Erlm Interface Library long i double f char s struct bonk bj int size ei reg getival reg age ei reg getfval reg height ei reg getsval reg name ei reg getpval reg jox ksize om FP Il In all of the above examples the object must exist and it must be of the right type for the specified operation If you do not know the type of a given object you can ask struct ei reg stat buf ei reg stat reg name amp buf Buf will be initialized to contain object attributes O bjects can be removed from the registry ei reg delete reg name When you are finished with a registry close it to remove all the objects and free the memory back to
49. it your node will have a short name i e it will not be fully qualified If you need to use fully qualified a k a long names use erl connect xinit instead host is the name of the host on which the node is running alive is the alivename of the node node is the name of the node T he nodename should be of the form alivename hostname addr is the 32 bit IP address of host cookie is the authorization string required for access to the remote node Refer to the auth module for more details Erlang Interface 29 erl connect C Module Erl Interface Library Reference creation helps identify a particular instance of aC node In particular it can help prevent us from receiving messages sent to an earlier process with the same registered name A C node acting as a server will be assigned a creation number when it calls erl publish Or erl_xpublish number is used by erl connect init to construct the actual node name In the second example shown below c17 a DN S name will be the resulting node name Example 1 struct in addr addr addr inet addr 150 236 14 75 if lerl connect xinit chivas madonna madonna chivas du etx ericsson se amp addr samplecookiestring 0 erl err quit ERROR when initializing Example 2 if lerl connect init 17 samplecookiestring 0 erl err quit ERROR when initializing int erl connect node int erl xconnect addr alive
50. l 50 erl global register 3 C function erl global 50 erl global unregister 2 C function erl global 51 erl global whereis 3 C function erl global 51 erl hd 1 C function erl eterm 41 erl init 2 C function erl eterm 41 erl iolist length 1 C function erl eterm 42 erl iolist to binary 1 C function erl eterm 41 erl_iolist_to_string 1 C function erl_eterm 42 erl length 1 C function erl eterm 42 erl malloc erl alloc eterm 1 C function 52 erl eterm release 1 C function 52 erl eterm statistics 2 C function 52 erl free 1 C function 53 erl free array 2 C function 53 erl free compound 1 C function 53 erl free term 1 C function 53 erl malloc 1 C function 53 erl malloc 1 C function erl malloc 53 erl marshal erl compare ext 2 C function 54 erl decode 1 C function 54 erl decode buf 1 C function 54 erl_encode 2 C function 54 erl encode buf 2 C function 54 Index erl ext size 1 C function 5 erl ext type 1 C function 5 erl peek ext 2 C function 5 5 erl match 2 C function erl format 48 erl mk atom 1 C function erl eterm 42 erl mk binary 2 C function erl_eterm 42 erl mk empty list 0 C function erl eterm 43 erl mk estring 2 C function erl eterm 43 erl mk float 1 C function erl eterm 43 erl mk int 1 C function erl eterm 43 erl mk list 2 C function erl_eterm 43 erl mk long ref 5 C function erl
51. le containing a variable with the specified name O ther Erlang types cannot contain variables name is the name of an Erlang variable Returns the Erlang object corresponding to the value of name in term If no variable with the name name was found in term or if term is not a valid Erlang term NULL is returned Erlang Interface 47 erl format C Module Erl Interface Library Reference erl format C Module This module contains two routines one general function for creating Erlang terms and one for pattern matching Erlang terms Exports ETERM erlformat FormatStr Types e char FormatStr Thisis a general function for creating Erlang terms using a format specifier and a corresponding set of arguments much in the way printf works FormatStr isa format specification string T he set of valid format specifiers is as follows e i Integer e f Floating point e a Atom e s String e w Arbitrary Erlang term For each format specifier that appears in FormatStr there must be a corresponding argument following FormatStr An Erlang term is built according to the FormatStr with values and Erlang terms substituted from the corresponding arguments and according to the individual format specifiers For example erl_format name a age i data w madonna 21 erl_format fadr s i E street 42 This will create an ETERM structure corresponding to the Erlang term name mad
52. m 3 C function 34 erl rpc to 4 C function 34 erl send 3 C function 33 erl thisalivename 0 C function 36 erl thiscookie 0 C function 36 Erlang Interface 57 Index erl thiscreation 0 C function 36 erl thishostname 0 C function 36 erl thisnodename 0 C function 36 erl unpublish 1 C function 36 erl xconnect 2 C function 30 erl xpublish 2 C function 35 erl xreceive msg 4 C function 33 erl copy term 1 C function 40 erl element 2 C function 41 erl hd 1 C function 41 erl init 2 C function 41 erl iolist length 1 C function 42 erl iolist to binary 1 C function 41 erl iolist to string 1 C function erl connect 1 C function erl connect 30 erl connect init 3 C function erl_connect 29 erl connect xinit 6 C function erl connect 29 erl cons 2 C function erl eterm 40 erl copy term 1 C function erl eterm 40 erl decode 1 C function erl marshal 54 erl decode buf 1 C function erl marshal 54 erl element 2 C function erl eterm 41 erl encode 2 C function erl marshal 54 erl encode buf 2 C function erl marshal 54 erl err msg 2 C function erl error 37 erl err quit 2 C function erl error 37 erl err ret 2 C function erl error 37 erl err sys 2 C function erl error 37 erl errno C function erl error 38 erl_error erl_err_msg 2 C function 37 erl_err_quit 2 C function 37 erl_err_ret 2 C function 37 erl_err_sys
53. nctions are exported e int erl compare ext bufp1 bufp2 Compares encoded byte sequences e ETERM erl decode bufp Converts a term from Erlang external format e ETERM erl decode buf bufpp Converts a term from Erlang external format e int erl_encode term bufp Converts a term into Erlang external format e int erl encode buf term bufpp Converts a term into Erlang external format e int erl_ext_size bufp Counts elements in encoded term e char erl ext type bufp Determines type of an encoded byte sequence e unsigned char erl peek ext bufp pos Steps over encoded term e int erl term len t Determines encoded size of term Erlang Interface Erl Interface Library Reference registry C Module registry C M odule This module provides support for storing key value pairs in a table known as a registry backing up registries to M nesia in an atomic manner and later restoring the contents of a registry from M nesia Exports int ei reg close reg Types e ei reg reg A registry that has previously been created with ei reg open is closed and all the objects it contains are freed reg is the registry to close The function returns 0 int ei reg delete reg key Types e ei reg reg e const char key D elete an object from the registry The object is not actually removed from the registry it is only marked for later removal so that on subsequent backups to M nesia the corresponding object can
54. ng This function creates a list from a zero terminated string string is the zero terminated sequence of characters i e aC string from which the list will be created The function returns an Erlang list ETERM erl mk tuple array arrsize Types e ETERM array e int arrsize Erlang Interface 45 erl_eterm C Module Erl Interface Library Reference Creates an Erlang tuple from an array of Erlang terms array isan array of Erlang terms arrsize is the number of elementsin array The function creates an Erlang tuple whose arity is size and whose elements are taken from the terms in array To retrieve the size of a tuple either use the er1 size function which checks the type of the checked term and works for a binary as well as for a tuple or the ERL TUPLE SIZE tuple returns the arity of a tuple erl size will do the same thing but it checks that the argument really is a tuple erl1 element index tuple returns the element corresponding to a given position in the tuple ETERM erl mk_uint n Types e unsigned int n Creates an Erlang unsigned integer n isa value to be converted to an Erlang unsigned integer The function returns an Erlang unsigned integer object with the value specified in n ERL_INT_UVALUE t can be used to retrieve the value from an Erlang unsigned integer ETERM erl_mk_var name int int 46 Types e char name This function creates an unbound Erlang variable Th
55. not distinguish between 1 and a valid result use the more general function ei reg getval instead 22 Erlang Interface Erl Interface Library Reference registry C Module const void const char ei reg getpval reg key size Types e ei reg reg e const char key e int size Get the value associated with key in the registry The value must be a binary pointer type reg is the registry where the object will be looked up key is the name of the object to look up size will be initialized to contain the length in bytes of the object if it is found On success the function returns the value associated with key and indicates its length in size If the object was not found or it was not a binary object NULL isreturned To avoid problems with in band error reporting i e if you cannot distinguish between NULL and a valid result use the more general function ei reg getval instead ei reg getsval reg key Types e ei reg reg e const char key Get the value associated with key in the registry The value must be a string reg is the registry where the object will be looked up key is the name of the object to look up On success the function returns the value associated with key If the object was not found or it was not a string NULL is returned To avoid problems with in band error reporting i e if you cannot distinguish between NULL and a valid result use the more general function ei reg
56. ntains functions for creating and manipulating Erlang terms An Erlang term is represented by a C structure of type ETERM Applications should not reference any fields in this structure directly because it may be changed in future releases to provide faster and more compact term storage Instead applications should us the macros and functions provided The following macros each take a single ET ERM pointer as an argument They return a non zero value if the test is true and 0 otherwise ERL_IS_INTEGER t True if t is an integer ERL_IS_UNSIGNED_INTEGER t True if t isan integer ERL_IS_FLOAT t Trueif t isa floating point number ERL_IS_ATOM t Trueif t isan atom ERL_IS_PID t True if t is a Pid process identifier ERL IS PORT t Trueif t isa port ERL IS REF t Trueif t isa reference ERL IS TUPLE t Trueif t isa tuple ERL IS BINARY t Trueif t isa binary ERL_IS_LIST t Trueif t isa list with zero or more elements ERL IS EMPTY LIST t True if t isan empty list ERL_IS_CONS t Trueif t isa list with at least one element The following macros can be used for retrieving parts of Erlang terms None of these do any type checking results are undefined if you pass an ETERM containing the wrong type For example passing a tuple to ERL ATOM PTR will likely result in garbage char ERL ATOM PTR t A string representing atom t int ERL_ATOM_SIZE t Thelength in characters of atom t void ERL_BIN_PTR t A pointer to the conte
57. nts of t int ERL BIN SIZE t The length in bytes of binary object t int ERL_INT_VALUE t The integer of t unsigned int ERL INT UVALUE t The unsigned integer value of t double ERL FLOAT VALUE t The floating point value of t ETERM ERL PID NODE t TheNodein pid t int ERL_PID_NUMBER t The sequence number in pid t int ERL PID SERIAL t The serial number in pid t int ERL_PID_CREATION t The creation number in pid t int ERL PORT NUMBER t The sequence number in port t Erlang Interface 39 erl eterm C Module Erl Interface Library Reference int ERL PORT CREATION t The creation number in port t ETERM ERL PORT NODE t The node in port t int ERL_REF_NUMBER t The first part of the reference number in ref t Use only for compatibility int ERL_REF_NUMBERS t Pointer to the array of reference numbers in ref t int ERL_REF_LEN t The number of used reference numbers in ref t int ERL_REF_CREATION t The creation number in ref t int ERL TUPLE SIZE t The number of elements in tuple t ETERM ERL CONS HEAD t The head element of list t ETERM ERL_CONS_TAIL t A List representing the tail elements of list t Exports ETERM erl cons head tail Types e ETERM head e ETERM tail This function concatenates two Erlang terms prepending head onto tail and thereby creating a cons cell To make a proper list tail should always be a list or an empty list Note that NULL is not a valid list head is the ne
58. of El_INT EI FLT EI BIN and EI STR whether it is marked for deletion EI D ELET and whether it has been modified since the last backup to M nesia EI DIRTY The size field indicates the size in bytes required to store EI_STR including the terminating 0 and EI BIN objects or O for ELINT and EI FLT The function returns O and initializes obuf on success or returns 1 on failure int ei_reg_tabstat reg obuf Types e ei reg reg e struct ei reg tabstat obuf Erlang Interface 27 registry C Module Erl Interface Library Reference 28 Return information about a registry U sing information returned by this function you can see whether the size of the registry is suitable for the amount of data it contains reg is the registry to return information about obuf isa pointer to an ei_reg_tabstat structure defined below struct ei reg tabstat int size int nelem int npos int collisions F5 The size field indicates the number of hash positions in the registry This is the number you provided when you created or last resized the registry rounded up to the nearest prime nelem indicates the number of elements stored in the registry It includes objects that are deleted but not purged npos indicates the number of unique positions that are occupied in the registry collisions indicates how many elements are sharing positions in the registry On success the function returns O and obuf isinitialized to
59. onna age 21 data adr E street 42 The function returns an Erlang term or NULL if FormatStr does not describe a valid Erlang term int erl_match Pattern Term Types e ETERM Pattern T erm 48 Erlang Interface Erl Interface Library Reference erl format C Module This function is used to perform pattern matching similar to that done in Erlang Refer to an Erlang manual for matching rules and more examples Pattern is an Erlang term possibly containing unbound variables Term is an Erlang term that we wish to match against Pattern Term and Pattern are compared and any unbound variables in Pattern are bound to corresponding values in Term If Term and Pattern can be matched the function returns a non zero value and binds any unbound variables in Pattern If Term Pattern do not match the function returns 0 For example ETERM term pattern pattern2 termi erl_format 14 21 term2 erl_format 19 19 patterni erl_format A B pattern2 erl_format F F if erl match patternl termi match succeeds A gets bound to 14 B gets bound to 21 if erl match pattern2 termi match fails because F cannot be bound to two separate values 14 and 21 if erl match pattern2 term2 match succeeds and F gets bound to 19 erl var content can be used to retrieve the content of any variables bound as a result of a call to erl match
60. onsumed 6 Erlang Interface 1 1 The Erlm Interface Library Sending and Receiving Erlang Messages Use one of the following two functions to send messages e erl_send e erl reg send Asin Erlang it is possible to send messages to a Pid or to a registered name It is easier to send a message to a registered name because it avoids the problem of finding a suitable Pid Use one of the following two functions to receive messages e erl receive e erl receive msg erl receive receives the message into a buffer while erl receive msg decodes the message into an Erlang term Example of Sending Messages In the following example Pid hello world is sent to a registered process my server The message is encoded by erl send extern const char erl_thisnodename void extern short erl_thiscreation void define SELF fd erl_mk_pid erl_thisnodename fd 0 erl_thiscreation ETERM arr 2 emsg int sockfd creation 1 arr 0 SELF sockfd arr 1 erl mk atom Hello world emsg erl mk tuplelarr 2 erl reg send sockfd my server emsg erl_free_term emsg The first element of the tuple that is sent is your own Pid This enables my_server to reply Refer to the Reference M anual the erl_connect module for more information about send primitives Example of Receiving Messages In this example Pid Something is received The received Pid is then used to return goodbye Pid ETERM xarr
61. onversion of data between C and Erlang formats e encoding and decoding of Erlang data types for transmission or storage e communication between C nodes and Erlang processes e backup and restore of C node state to and from M nesia In the following sections these topics are described compiling your code for use with erl interface initializing er1 interface encoding decoding and sending Erlang terms building terms and patterns pattern matching connecting to a distributed Erlang node using EPMD sending and receiving Erlang messages remote procedure calls global names the registry Compiling and Linking your code In order to use any of the erl interface functions include the following lines in your code include erl interface h include ei h D etermine where the top directory of your OTP installation is You can find this out by starting Erlang and entering the following command at the Eshell prompt Eshell V4 7 4 abort with G 15 code root dir usr local otp To compile your code make sure that your C compiler knows where to find erl_interface h by specifying an appropriate I argument on the command line or by adding it to the CFLAGS definition in your Makefile The correct value for this path is OTPROOT 1ib ei 3 1 include Where SOTPROOT is the path reported by code root dir 0 in the above example 2 Erlang Interface 1 1 The Erim Interface Library cc c I usr local otp lib ei 3 1 include mypro
62. ormat Conseguently you have to encode and decode Erlang terms into byte streams if you want to use the distribution protocol to communicate between a C program and Erlang The erl interface library supports this activity It has a number of C functions which create and manipulate Erlang data structures The library also contains an encode and a decode function The example below shows how to create and encode an Erlang tuple tobbe 3928 ETERM arr 2 tuple char buf BUFSIZ int i arr 0 erl_mk_atom tobbe arr 1 erl_mk_integer 3928 tuple erl_mk_tuple arr 2 i erl_encode tuple buf Alternatively you can use erl_send and erl receive msg which handle the encoding and decoding of messages transparently Refer to the Reference M anual for a complete description of the following modules e the erl_eterm module for creating Erlang terms e the erl_marshal module for encoding and decoding routines Erlang Interface 3 Chapter 1 Erlm Interface User s Guide Building Terms and Patterns The previous example can be simplified by using er1_format to create an Erlang term ETERM tep ep erl_format a i tobbe 3928 Refer to the Reference M anual the er1 format module for a full description of the different format directives The following example is more complex ETERM tep ep erl_format name a age i data w madonna 21 erl_format fadr s i E street 42
63. ports remote procedure calls char modname THE MODNAME ETERM reply tep ep erl_format a modname if reply erl_rpc fd c c ep erl_err_msg lt ERROR gt when compiling file s erl n modname erl_free_term ep ep erl_format ok _ if lerl_match ep reply erl_err_msg lt ERROR gt compiler errors n erl_free_term ep erl_free_term reply c c 1 is called to compile the specified module on the remote node erl_match checks that the compilation was successful by testing for the expected ok Refer to the Reference M anual the erl_connect module for more information about erl_rpc and its companions erl_rpc_to and erl_rpc_from 8 Erlang Interface 1 1 The Erlm Interface Library Using Global Names A C node has access to names registered through the Erlang Global module Names can be looked up allowing the C node to send messages to named Erlang services C nodes can also register global names allowing them to provide named services to Erlang processes or other C nodes Erl Interface does not provide a native implementation of the global service Instead it uses the global services provides by a nearby Erlang node In order to use the services described in this section it is necessary to first open a connection to an Erlang node To see what names there are char names int count int i names erl global names fd count if names for i 0
64. r is assumed for unspecified Fun and Args Args should be in the same format as for erlang apply 3 Note that this flag takes exactly one argument so quoting may be necessary in order to group Mod Fun and Args in a manner dependent on the behaviour of your command shell c Cookie optional Use this option to specify a certain cookie If no cookie is specified the erlang cookie file is read and its content are used as cookie The Erlang node we want to communicate with must have the same cookie d optional Debug mode This causes all IO to be output to the file erl_call out Nodename where Nodename is the node name of the Erlang node in question e optional Reads a sequence of Erlang expressions separated by and ended with a from stdin until EOF Control D Evaluates the expressions and returns the result from the last expression Returns ok Result if successful h HiddenN ame optional Specifies the name of the hidden node that erl_call represents m optional Reads an Erlang module from stdin and compiles it n Node one of n name sname is required H as the same meaning as name and can still be used for backwards compatibility reasons 14 Erlang Interface Erl Interface Command Reference erl call Command name Node one of n name sname is required Node is the name of the node to be started or communicated with It is assumed that Node is started with er1 name which means t
65. rlang Interface 37 erl error C Module Erl Interface Library Reference volatile int 38 Error Reporting M ost functions in erl interface report failures to the caller by returning some otherwise meaningless value typically NULL or a negative number As this only tells you that things did not go well you will have to examine the error code in erl_errno if you want to find out more about the failure Exports erl errno erl errno is initially at program startup zero and is then set by many erl_interface functions on failure to a non zero error code to indicate what kind of error it encountered A successful function call might change er1_errno by calling some other function that fails but no function will ever set it to zero T his means that you cannot use erl_errno to seeif a function call failed Instead each function reports failure in its own way usually by returning a negative number or NULL in which case you can examine erl errno for details erl_errno uses the error codes defined in your system s lt errno h gt N ote Actually erl errno is a modifiable Ivalue just like ISO C defines errno to be rather than a variable This means it might be implemented as a macro expanding to e g x erl errno For reasons of thread or task safety this is exactly what we do on most platforms Erlang Interface Erl Interface Library Reference erl eterm C Module erl eterm C M odule This module co
66. ror can be obtained with the appropriate platform dependent call int erlreceive fd bufp bufsize Types e int fd e char bufp e int bufsize This function receives a message consisting of a sequence of bytes in the Erlang external format fd is an open descriptor to an Erlang connection bufp is a buffer large enough to hold the expected message buf size indicates the size of bufp If atick occurs i e the Erlang node on the other end of the connection has polled this node to see if it is still alive the function will return ERL_TICK and no message will be placed in the buffer Also erl_errno will be set to EAGAIN On success the message is placed in the specified buffer and the function returns the number of bytes actually read On failure the function returns a negative value and will set erl_errno to one of EAGAIN Temporary error Try again EMSGSIZE Buffer too small EIO O error int erl_receive msg fd bufp bufsize emsg Types e int fd e unsigned char bufp Erlang Interface 31 erl_connect C Module Erl_Interface Library Reference e int bufsize e ErlM essage emsg This function receives the message into the specified buffer and decodes into the ErlMessage emsg fa is an open descriptor to an Erlang connection bufp is a buffer large enough to hold the expected message bufsize indicates the size of bufp emsg is a pointer to an ErlMessage structure into which the message will b
67. s Guide After registering the name you should use erl accept to wait for incoming connections Do not forget to free pid later with erl free term To unregister a name erl global unregister fd servicename The Registry This section describes the use of the registry a simple mechanism for storing key value pairsin a C node as well as backing them up or restoring them from a M nesia table on an Erlang node M ore detailed information about the individual API functions can be found in the reference manual Keys are strings i e O terminated arrays of characters and values are arbitrary objects Although integers and floating point numbers are treated specially by the registry you can store strings or binary objects of any type as pointers To start you need to open a registry ei reg reg reg ei reg open 45 The number 45 in the example indicates the approximate number of objects that you expect to store in the registry Internally the registry uses hash tables with collision chaining so there is no absolute upper limit on the number of objects that the registry can contain but if performance or memory usage are important then you should choose a number accordingly T he registry can be resized later You can open as many registries as you like if memory permits Objects are stored and retrieved through set and get functions In the following examples you see how to store integers floats strings and arbitrary b
68. st Types e ETERM list Returns the length of an IO list list isan Erlang term containing an IO list The function returns the length of list or 1 if list is not an IO list Refer to erl iolist to binary for the definition of an IO list int erl_length list Types e ETERM list D etermines the length of a proper list list isan Erlang term containing proper list In a proper list all tails except the last point to another list cell and the last tail points to an empty list Returns 1 if list is not a proper list ETERM erl mk atom string Types e char string Creates an atom string is the sequence of characters that will be used to create the atom Returns an Erlang term containing an atom N ote that it is the callers responsibility to make sure that string contains a valid name for an atom ERL ATOM PTR atom can be used to retrieve the atom name as a string Note that the string is not O terminated in the atom ERL_ATOM SIZE atom returns the length of the atom name ETERM erl mk binary bptr size Types e char bptr e int size 42 Erlang Interface Erl Interface Library Reference erl eterm C Module This function produces an Erlang binary object from a buffer containing a sequence of bytes bptr isa pointer to a buffer containg data to be converted size indicates the length of bptr The function returns an Erlang binary object ERL BIN PTR bin retrieves a pointer to the b
69. the space for the node name which is an atom Thetotal space required will be the result calculated from the information above plus 1 additional byte for a version identifier int erl_ext_size bufp Types e unsigned char bufp This function returns the number of elements in an encoded term char erl ext type bufp Types e unsigned char bufp Erlang Interface 55 This function identifies and returns the type of Erlang term encoded in a buffer unsigned char erl peek ext bufp pos int 56 Types e unsigned char bufp e int pos This function is used for stepping over one or more encoded terms in a buffer in order to directly access a later term bufp isa pointer to a buffer containing one or more encoded Erlang terms pos indicates how many terms to step over in the buffer The function returns a pointer to a sub term that can be used in a subsequent call to erl decode in order to retrieve the term at that position If there is no term or pos would exceed the size of the terms in the buffer NULL is returned erl term len t Types e ETERM t This function determines the buffer space that would be needed by t if it were encoded into Erlang external format by erl_encode The size in bytes is returned Erlang Interface Index M odules are typed in this way Functions are typed in this way ei reg close 1 C function registry 21 ei reg delete 2 C function registry 21 ei r
70. tions do this automatically H owever if you have retrieved the value of a string or binary object from the registry and modified the contents then the change will be invisible to the registry and the object will be assumed to be unmodified This function allows you to make such modifications and then let the registry know about them reg is the registry containing the object key is the name of the object to mark The function returns 0 on success or 1 on failure ei reg ei reg open size Types e int size Open create a registry The registry will be initially empty Use ei reg close to close the registry later size is the approximate number of objects you intend to store in the registry Since the registry uses a hash table with collision chaining there is no absolute upper limit on the number of objects that can be stored in it H owever for reasons of efficiency it is a good idea to choose a number that is appropriate for your needs It is possible to use ei_reg_resize to change the size later Note that the number you provide will be increased to the nearest larger prime number On success an empty registry will be returned On failure NULL will be returned int ei reg purge reg Types e ei reg reg Remove all objects marked for deletion W hen objects are deleted with ei reg delete they are not actually removed from the registry only marked for later removal This is so that on a subsequent backup to M nesi
71. turn the corresponding Erlang term erl_decode_buf provides a simple mechanism for dealing with several encoded terms stored consecutively in the buffer bufp is a pointer to a buffer containing one or more encoded Erlang terms buf pp is the address of a buffer pointer The buffer contains one or more consecutively encoded Erlang terms Following a successful call to erl_decode_buf bufpp will be updated so that it points to the next encoded term erl_decode returns an Erlang term corresponding to the contents of bufp on success or NULL on failure er1 decode buf returns an Erlang term corresponding to the first of the consecutive terms in bufpp and moves buf pp forward to point to the next term in the buffer On failure each of the functions returns NULL int erl_encode term bufp int erl_encode_buf term bufpp Types 54 Erlang Interface Erl Interface Library Reference erl marshal C Module e ETERM term e unsigned char bufp e unsigned char bufpp erl_encode and erl encode buf encode Erlang terms into external format for storage or transmission erl encode buf provides a simple mechanism for encoding several terms consecutively in the same buffer term isan Erlang term to be encoded bufp isa pointer to a buffer containing one or more encoded Erlang terms bufpp isa pointer to a pointer to a buffer containing one or more consecutively encoded Erlang terms Following a successful call to er1
72. ver When erl_rpc calls erl_rpc_from the call will never timeout mod is the name of the module containing the function to be run on the remote node fun is the name of the function to run args is an Erlang list containing the arguments to be passed to the function emsg is a message containing the result of the function call The actual message returned by the rpc server is a 2 tuple rex Reply If you are using erl_rpc_from in your code then this is the message you will need to parse If you are using erl_rpc then the tuple itself is parsed for you and the message returned to your program is the erlang term containing Reply only Replies to rpc requests are always ERL_SEN D messages N ote It is the caller s responsibility to free the returned ETERM structure as well as the memory pointed to by emsg gt msg and emsg gt to erl_rpc returns the remote function s return value or NULL if it failed erl_rpc_to returns 0 on success and a negative number on failure erl_rcp_from returns ERL MSG when successful with Emsg now containing the reply tuple and one of ERL_TICK ERL TIMEOUT and ERL_ERROR otherwise W hen failing all three functions set erl_errno to one of Erlang Interface Erl Interface Library Reference erl connect C Module ENOMEM No more memory available EIO I O error ETIMEDOUT Timeout expired EAGAIN Temporary error Try again int erl_publish port int erlxpublish port addr Types e
73. w term to be added tail isthe existing list to which head will be concatenated The function returns a new list ERL CONS HEAD list and ERL CONS TAIL list can be used to retrieve the head and tail components from the list erl_hd list and erl t1 list will do the same thing but check that the argument really is a list For example ETERM list xanAtom xanInt anAtom erl mk atom madonna anInt erl mk int 21 list erl mk empty list O list erl cons anAtom list list erl cons anInt list do some work erl free compound list ETERM erl_copy_term term Types e ETERM term This function creates and returns a copy of the Erlang term term 40 Erlang Interface Erl Interface Library Reference erl eterm C Module ETERM erl_element position tuple Types e int position e ETERM tuple This function extracts a specified element from an Erlang tuple position specifies which element to retrieve from tuple The elements are numbered starting from 1 tuple is an Erlang term containing at least position elements The function returns a new Erlang term corresponding to the requested element or NULL if position was greater than the arity of tuple void erl_init NULL 0 Types e void NULL e int 0 This function must be called before any of the others in the erl_interface library in order to initialize the library functions The arguments must be specified as erl init NULL 0

Download Pdf Manuals

Related Search

erl_interface 3.2.3

erl_interface-3.2.3

Contents

Download Pdf Manuals

Related Search

Related Contents