Home
Client APIs and tools
You can use the HCL Informix® implementation of client APIs to develop applications for Informix database servers.
ESQL/C Guide
The Informix® ESQL/C Programmer's Manual explains how to use Informix ESQL/C, the Informix implementation of Embedded Structured Query Language (SQL) for C (ESQL/C), to create client applications with database-management capabilities.
Appendixes
This section contains additional reference information.
The ESQL/C function library
These topics describe the syntax and behavior of all the library functions provided with Informix® ESQL/C.
The ifx_lo_spec_free() function
The ifx_lo_spec_free() function frees the resources of an LO-specification structure.

Client APIs and tools
You can use the HCL Informix® implementation of client APIs to develop applications for Informix database servers.
- Change Data Capture API Programmer's Guide
  The Informix® Change Data Capture API Programmer's Guide describes how to program applications to process changed data from HCL Informix databases using the Informix Change Data Capture API.
- Embedded SQLJ for HCL Informix®
  The Informix® Embedded SQLJ User's Guide contains information about using Informix Embedded SQLJ.
- ESQL/C Guide
  The Informix® ESQL/C Programmer's Manual explains how to use Informix ESQL/C, the Informix implementation of Embedded Structured Query Language (SQL) for C (ESQL/C), to create client applications with database-management capabilities.
  - What is Informix® ESQL/C?
  - Database server communication
  - Dynamic SQL
  - Appendixes
    This section contains additional reference information.
    - The ESQL/C example programs
    - The ESQL/C function library
      These topics describe the syntax and behavior of all the library functions provided with Informix® ESQL/C.
      - Informix® ESQL/C library functions
      - The bigintcvasc() function
        The bigintcvasc() function converts a C char type value to a BIGINT type number.
      - The bigintcvdbl() function
        The bigintcvdbl() function converts a double type number to a BIGINT type number.
      - The bigintcvdec() function
        The bigintcvdec() function converts a decimal type number to a BIGINT type number.
      - The bigintcvflt() function
        The bigintcvflt() function converts a float type number to a BIGINT type number.
      - The bigintcvifx_int8() function
        The bigintcvifx_int8() function converts and int8 type number to a BIGINT type number.
      - The bigintcvint2() function
        The bigintcvint2() function converts an int2 type number to a BIGINT type number.
      - The bigintcvint4() function
        The bigintcvint4() function converts an int4 type number to a BIGINT type number.
      - The biginttoasc() function
        The biginttoasc() function converts a BIGINT type value to a C char type value.
      - The biginttodbl() function
        The biginttodbl() function converts a BIGINT type number to a double type number.
      - The biginttodec() function
        The biginttodec() function converts a BIGINT type number to a decimal type number.
      - The biginttoflt() function
        The biginttoflt() function converts a BIGINT type number to a float type number.
      - The biginttoifx_int8() function
        The biginttoifx_int8() function converts a BIGINT type number to an int8 type number.
      - The biginttoint2() function
        The biginttoint2() function converts a BIGINT type number to an int2 type number.
      - The biginttoint4() function
        The biginttoint4() function converts a BIGINT type number to an int4 type number.
      - The bycmpr() function
        The bycmpr() function compares two groups of contiguous bytes for a given length. It returns the result of the comparison as its value.
      - The bycopy() function
        The bycopy() function copies a given number of bytes from one location to another.
      - The byfill() function
        The byfill() function fills a specified area with one character.
      - The byleng() function
        The byleng() function returns the number of significant characters in a string, not counting trailing blanks.
      - The decadd() function
        The decadd() function adds two decimal type values.
      - The deccmp() function
        The deccmp() function compares two decimal type numbers.
      - The deccopy() function
        The deccopy() function copies one decimal structure to another.
      - The deccvasc() function
      - The deccvdbl() function
        The deccvdbl() function converts a C double type number into a decimal type number.
      - The deccvflt() function
      - The deccvint() function
        The deccvint() function converts a C int type number into a decimal type number.
      - The deccvlong() function
        The deccvlong() function converts a C long type value into a decimal type value.
      - The decdiv() function
        The decdiv() function divides two decimal type values.
      - The dececvt() and decfcvt() functions
        The dececvt() and decfcvt() functions are analogous to the subroutines under ECVT(3) in section three of the UNIX™ Programmer's Manual. The dececvt() function works in the same fashion as the ecvt(3) function, and the decfcvt() function works in the same fashion as the fcvt(3) function. They both convert a decimal type number to a C char type value.
      - The decmul() function
        The decmul() function multiplies two decimal type values.
      - The decround() function
        The decround() function rounds a decimal type number to fractional digits.
      - The decsub() function
        The decsub() function subtracts two decimal type values.
      - The dectoasc() function
        The dectoasc() function converts a decimal type number to a C char type value.
      - The dectodbl() function
        The dectodbl() function converts a decimal type number into a C double type number.
      - The dectoint() function
        The dectoint() function converts a decimal type number into a C int type number.
      - The dectolong() function
        The dectolong() function converts a decimal type number into an int4 type number.
      - The dectrunc() function
        The dectrunc() function truncates a rounded decimal type number to fractional digits.
      - The dtaddinv() function
        The dtaddinv() function adds an interval value to a datetime value. The result is a datetime value.
      - The dtcurrent() function
        The dtcurrent() function assigns the current date and time to a datetime variable.
      - The dtcvasc() function
        The dtcvasc() function converts a string that conforms to ANSI SQL standard for a DATETIME value to a datetime value.
      - The dtcvfmtasc() function
        The dtcvfmtasc() function uses a formatting mask to convert a character string to a datetime value.
      - The dtextend() function
        The dtextend() function extends a datetime value to a different qualifier. Extending is the operation of adding or dropping fields of a DATETIME value to make it match a given qualifier.
      - The dtsub() function
        The dtsub() function subtracts one datetime value from another. The result is an interval value.
      - The dtsubinv() function
        The dtsubinv() function subtracts an interval value from a datetime value. The result is a datetime value.
      - The dttoasc() function
        The dttoasc() function converts the field values of a datetime variable to an ASCII string that conforms to ANSI SQL standards.
      - The dttofmtasc() function
        The dttofmtasc() function uses a formatting mask to convert a datetime variable to a character string.
      - The GetConnect() function (Windows™)
        The GetConnect() function is available only in Windows™ environments and establishes a new explicit connection to a database server.
      - The ifx_cl_card() function
        The ifx_cl_card() function returns the cardinality of the specified collection type host variable.
      - The ifx_dececvt() and ifx_decfcvt() function
        The ifx_dececvt() and ifx_decfcvt() functions are the thread-safe versions of the dececvt() and decfcvt() Informix® ESQL/C library functions.
      - The ifx_defmtdate() function
        The ifx_defmtdate() function uses a formatting mask to convert a character string to an internal DATE format.
      - The ifx_dtcvasc() function
        The ifx_dtcvasc() function converts a string that conforms to ANSI SQL standard for a DATETIME value to a datetime value.
      - The ifx_dtcvfmtasc() function
        The ifx_dtcvfmtasc() function uses a formatting mask to convert a character string to a datetime value.
      - The ifx_dttofmtasc() function
        The ifx_dttofmtasc() function uses a formatting mask to convert a datetime variable to a character string.
      - The ifx_getenv() function
        The ifx_getenv() function retrieves the value of a current environment variable.
      - The ifx_getcur_conn_name() function
        The ifx_getcur_conn_name() function returns the name of the current connection.
      - The ifx_getserial8() function
        The ifx_getserial8() function returns the SERIAL8 value of the last inserted row into an int8 host variable.
      - The ifx_int8add() function
        The ifx_int8add() function adds two int8 type values.
      - The ifx_int8cmp() function
        The ifx_int8cmp() function compares two int8 type numbers.
      - The ifx_int8copy() function
        The ifx_int8copy() function copies one int8 structure to another.
      - The ifx_int8cvasc() function
        The ifx_int8cvasc() function converts a value held as printable characters in a C char type into an int8 type number.
      - The ifx_int8cvdbl() function
        The ifx_int8cvdbl() function converts a C double type number into an int8 type number.
      - The ifx_int8cvdec() function
        The ifx_int8cvdec() function converts a decimal type value into an int8 type value.
      - The ifx_int8cvflt() function
        The ifx_int8cvflt() function converts a C float type number into an int8 type number.
      - The ifx_int8cvint() function
        The ifx_int8cvint() function converts a C int type number into an int8 type number.
      - The ifx_int8cvlong() function
        The ifx_int8cvlong() function converts a C long type value into an int8 type value.
      - The ifx_int8div() function
        The ifx_int8div() function divides two int8 type values.
      - The ifx_int8mul() function
        The ifx_int8mul() function multiplies two int8 type values.
      - The ifx_int8sub() function
        The ifx_int8sub() function subtracts two int8 type values.
      - The ifx_int8toasc() function
        The ifx_int8toasc() function converts an int8 type number to a C char type value.
      - The ifx_int8todbl() function
        The ifx_int8todbl() function converts an int8 type number into a C double type number.
      - The ifx_int8todec() function
        The ifx_int8todec() function converts an int8 type number into a decimal type number.
      - The ifx_int8toflt() function
        The ifx_int8toflt() function converts an int8 type number into a C float type number.
      - The ifx_int8toint() function
        The ifx_int8toint() function converts an int8 type number into a C int type number.
      - The ifx_int8tolong() function
        The ifx_int8tolong() function converts an int8 type number into a C long type number.
      - The ifx_lo_alter() function
        The ifx_lo_alter() function alters the storage characteristics of an existing smart large object.
      - The ifx_lo_close() function
        The ifx_lo_close() function closes an open smart large object.
      - The ifx_lo_col_info() function
        The ifx_lo_col_info() function sets the fields of an LO-specification structure to the column-level storage characteristics for a specified database column.
      - The ifx_lo_copy_to_file() function
        The ifx_lo_copy_to_file() function copies the contents of a smart large object into an operating-system file.
      - The ifx_lo_copy_to_lo() function
        The ifx_lo_copy_to_lo() function copies the contents of a file into an open smart large object.
      - The ifx_lo_create() function
        The ifx_lo_create() function creates a new smart large object and opens it for access within the Informix® ESQL/C program.
      - The ifx_lo_def_create_spec() function
        The ifx_lo_def_create_spec() function allocates and initializes an LO-specification structure.
      - The ifx_lo_filename() function
        The ifx_lo_filename() function returns the path name that the database server would use if you copied a smart large object to a file.
      - The ifx_lo_from_buffer() function
        The ifx_lo_from_buffer() function copies a specified number of bytes from a user-defined buffer into a smart large object.
      - The ifx_lo_lock() function
        The ifx_lo_lock() function allows you to lock an explicit range of bytes in a smart large object.
      - The ifx_lo_open() function
        The ifx_lo_open() function opens an existing smart large object for access.
      - The ifx_lo_read() function
        The ifx_lo_read() function reads a specified number of bytes of data from an open smart large object.
      - The ifx_lo_readwithseek() function
        The ifx_lo_readwithseek() function performs a seek operation and then reads a specified number of bytes of data from an open smart large object.
      - The ifx_lo_release() function
        The ifx_lo_release() function tells the database server to release the resources associated with a temporary smart large object.
      - The ifx_lo_seek() function
        The ifx_lo_seek() function sets the file position for the next read or write operation on the open smart large object.
      - The ifx_lo_spec_free() function
        The ifx_lo_spec_free() function frees the resources of an LO-specification structure.
      - The ifx_lo_specget_def_open_flags() function
        The ifx_lo_specget_def_open_flags() function obtains the default open flags of a smart large object from an LO-specification structure.
      - The ifx_lo_specget_estbytes() function
        The ifx_lo_specget_estbytes() function obtains from an LO-specification structure the estimated size of a smart large object.
      - The ifx_lo_specget_extsz() function
        The ifx_lo_specget_extsz() function obtains from an LO-specification structure the allocation extent size of a smart large object.
      - The ifx_lo_specget_flags() function
        The ifx_lo_specget_flags() function obtains from an LO-specification structure the create-time flags of a smart large object.
      - The ifx_lo_specget_maxbytes() function
        The ifx_lo_specget_maxbytes() function obtains from an LO-specification structure the maximum size of a smart large object.
      - The ifx_lo_specget_sbspace() function
        The ifx_lo_specget_sbspace() function obtains from an LO-specification structure the name of an sbspace where a smart large object is stored.
      - The ifx_lo_specset_def_open_flags() function
        The ifx_lo_specset_def_open_flags() function sets the default open flags for a smart large object.
      - The ifx_lo_specset_estbytes() function
        The ifx_lo_specset_estbytes() function sets the estimated size of a smart large object.
      - The ifx_lo_specset_extsz() function
        The ifx_lo_specset_extsz() function sets the allocation extent size for a smart large object.
      - The ifx_lo_specset_flags() function
        The ifx_lo_specset_flags() function sets the create-time flags of a smart large object.
      - The ifx_lo_specset_maxbytes() function
        The ifx_lo_specset_maxbytes() function sets the maximum size for a smart large object.
      - The ifx_lo_specset_sbspace() function
        The ifx_lo_specset_sbspace() function sets the name of the sbspace for a smart large object.
      - The ifx_lo_stat() function
        The ifx_lo_stat() function returns information about the status of an open smart large object.
      - The ifx_lo_stat_atime() function
        The ifx_lo_stat_atime() function returns the time of last access for a smart large object.
      - The ifx_lo_stat_cspec() function
        The ifx_lo_stat_cspec() function returns the LO-specification structure for a smart large object.
      - The ifx_lo_stat_ctime() function
        The ifx_lo_stat_ctime() function returns the time of last change in status for a smart large object.
      - The ifx_lo_stat_free() function
        The ifx_lo_stat_free() function frees an LO-status structure.
      - The ifx_lo_stat_mtime_sec() function
        The ifx_lo_stat_mtime_sec() function returns the time of last modification for a smart large object.
      - The ifx_lo_stat_refcnt() function
        The ifx_lo_stat_refcnt() function returns the number of references to a smart large object.
      - The ifx_lo_stat_size() function
        The ifx_lo_stat_size() function returns the size, in bytes, of a smart large object.
      - The ifx_lo_tell() function
        The ifx_lo_tell() function returns the current file or seek position for an open smart large object.
      - The ifx_lo_to_buffer() function
        The ifx_lo_to_buffer() function copies a specified number of bytes from a smart large object into a user-defined buffer.
      - The ifx_lo_truncate() function
        The ifx_lo_truncate() function truncates a smart large object at a specified byte position.
      - The ifx_lo_unlock() function
        The ifx_lo_unlock() function allows you to unlock a range of bytes in a smart large object that was locked by the ifx_lo_lock() function.
      - The ifx_lo_write() function
        The ifx_lo_write() function writes a specified number of bytes of data to an open smart large object.
      - The ifx_lo_writewithseek() function
        The ifx_lo_writewithseek() function performs a seek operation and then writes a specified number of bytes of data to an open smart large object.
      - The ifx_lvar_alloc() function
        The ifx_lvar_alloc() function specifies whether to allocate memory when fetching lvarchar data.
      - The ifx_putenv() function
        The ifx_putenv() function changes the value of an existing environment variable, creates an environment variable, or removes a variable from the runtime environment.
      - The ifx_strdate() function
        The ifx_strdate() function converts a character string to an internal DATE.
      - The ifx_var_alloc() function
        The ifx_var_alloc() function allocates memory for the data buffer of an lvarchar or var binary host variable.
      - The ifx_var_dealloc() function
        The ifx_var_dealloc() function deallocates the memory that was allocated for the data buffer of a var binary host variable.
      - The ifx_var_flag() function
        The ifx_var_flag() function determines how memory is allocated for the data buffer of an lvarchar or var binary host variable.
      - The ifx_var_freevar() function
        The ifx_var_freevar() function frees memory that has been allocated for the var binary and lvarchar pointer host variables.
      - The ifx_var_getdata() function
        The ifx_var_getdata() function returns the data from an lvarchar or var binary host variable.
      - The ifx_var_getlen() function
        The ifx_var_getlen() function returns the length of the data in an lvarchar pointer or var binary host variable.
      - The ifx_var_isnull() function
        The ifx_var_isnull() function checks whether an lvarchar or var binary host variable contains a null value.
      - The ifx_var_setdata() function
        The ifx_var_setdata() function stores data in an lvarchar or var binary host variable.
      - The ifx_var_setlen() function
        The ifx_var_setlen() function stores the length of the data buffer for an lvarchar or var binary host variable.
      - The ifx_var_setnull() function
        The ifx_var_setnull() function sets an lvarchar or var binary host variable to a null value.
      - The incvasc() function
        The incvasc() function converts a string that conforms to the ANSI SQL standard for an INTERVAL value to an interval value.
      - The incvfmtasc() function
        The incvfmtasc() function uses a formatting mask to convert a character string to an interval value.
      - The intoasc() function
        The intoasc() function converts the field values of an interval variable to an ASCII string that conforms to the ANSI SQL standard.
      - The intofmtasc() function
        The intofmtasc() function uses a formatting mask to convert an interval variable to a character string.
      - The invdivdbl() function
        The invdivdbl() function divides an interval value by a numeric value.
      - The invdivinv() function
        The invdivinv() function divides an interval value by another interval value.
      - The invextend() function
        The invextend() function copies an interval value under a different qualifier.
      - The invmuldbl() function
        The invmuldbl() function multiplies an interval value by a numeric value.
      - The ldchar() function
        The ldchar() function copies a fixed-length string into a null-terminated string and removes any trailing blanks.
      - The rdatestr() function
        The rdatestr() function converts an internal DATE to a character string.
      - The rdayofweek() function
        The rdayofweek() function returns the day of the week as an integer value for an internal DATE.
      - The rdefmtdate() function
        The rdefmtdate() function uses a formatting mask to convert a character string to an internal DATE format.
      - The rdownshift() function
        The rdownshift() function changes all the uppercase characters within a null-terminated string to lowercase characters.
      - The ReleaseConnect() function (Windows™)
        The ReleaseConnect() function is available only in Windows™ environments. It releases, or terminates, the explicit connection and clears all allocated memory.
      - The rfmtdate() function
        The rfmtdate() function uses a formatting mask to convert an internal DATE format to a character string.
      - The rfmtdec() function
      - The rfmtdouble() function
      - The rfmtlong() function
      - The rgetlmsg() function
        The rgetlmsg() function retrieves the corresponding error message for a given error number that is specific to HCL Informix®. The rgetlmsg() function allows for error numbers in the range of a long integer.
      - The rgetmsg() function
        The rgetmsg() function retrieves the error message text for a given error number that is specific to HCL Informix®. The rgetmsg() function can handle a short error number and, therefore, can only handle error numbers in the range of -32768 - +32767. For this reason, use the rgetlmsg() function in all new Informix ESQL/C code.
      - The risnull() function
        The risnull() function checks whether the C or the Informix® ESQL/C variable contains a null value.
      - The rjulmdy() function
        The rjulmdy() function creates an array of three short integer values that represent the month, day, and year from an internal DATE value.
      - The rleapyear() function
        The rleapyear() function returns 1 (TRUE) when the argument that is passed to it is a leap year and 0 (FALSE) when it is not.
      - The rmdyjul() function
        The rmdyjul() function creates an internal DATE from an array of three short integer values that represent month, day, and year.
      - The rsetnull() function
        The rsetnull() function sets a C variable to a value that corresponds to a database null value.
      - The rstod() function
        The rstod() function converts a null-terminated string into a double value.
      - The rstoi() function
        The rstoi() function converts a null-terminated string into a short integer value.
      - The rstol() function
        The rstol() function converts a null-terminated string into a long integer value.
      - The rstrdate() function
        The rstrdate() function converts a character string to an internal DATE.
      - The rtoday() function
        The rtoday() function returns the system date as a long integer value.
      - The rtypalign() function
        The rtypalign() function returns the position of the next proper boundary for a variable of the specified data type.
      - The rtypmsize() function
        The rtypmsize() function returns the number of bytes you must allocate in memory for the specified Informix® ESQL/C or SQL data type.
      - The rtypname() function
        The rtypname() function returns a null-terminated string that contains the name of the specified SQL data type.
      - The rtypsize() function
        The rtypsize() function returns the internal storage sizes of data for clients that use the Change Data Capture API.
      - The rtypwidth() function
        The rtypwidth() function returns the minimum number of characters that a character data type needs to avoid truncation when you convert a value with an SQL data type to a character data type.
      - The rupshift() function
        The rupshift() function changes all the characters within a null-terminated string to uppercase characters.
      - The SetConnect() function (Windows™)
        The SetConnect() function is available only in Windows™ environments. It switches the connection to a specified explicit connection.
      - The sqgetdbs() function
        The sqgetdbs() function returns the names of databases that a database server can access.
      - The sqlbreak() function
        The sqlbreak() function sends the database server a request to interrupt processing of the current SQL request. You generally call this function to interrupt long queries.
      - The sqlbreakcallback() function
        The sqlbreakcallback() function allows you to specify a timeout interval and to register a callback function. The callback function provides a method for the application to regain control when the database server is processing an SQL request.
      - The sqldetach() function
        The sqldetach() function detaches a process from the database server. You generally call this function when an application forks a new process to begin a new stream of execution.
      - The sqldone() function
        The sqldone() function determines whether the database server is currently processing an SQL request.
      - The sqlexit() function
        The sqlexit() function terminates all database server connections and frees resources. You can use sqlexit() to reduce database overhead in programs that refer to a database only briefly and after long intervals, or that access a database only during initialization.
      - The sqlsignal() function
        The sqlsignal() function enables or disables signal handling of the signals that the Informix® ESQL/C library handles.
      - The sqlstart() function
        The sqlstart() function starts an implicit default connection. An implicit default connection can support one connection to the default database server (that the INFORMIXSERVER environment variable specifies).
      - The stcat() function
        The stcat() function concatenates one null-terminated string to the end of another.
      - The stchar() function
        The stchar() function stores a null-terminated string in a fixed-length string, padding the end with blanks, if necessary.
      - The stcmpr() function
        The stcmpr() function compares two null-terminated strings.
      - The stcopy() function
        The stcopy() function copies a null-terminated string from one location in memory to another location.
      - The stleng() function
        The stleng() function returns the length, in bytes, of a null-terminated string that you specify.
    - Examples for smart-large-object functions
      These examples illustrate how to use the Informix® ESQL/C library functions to access smart large objects. These examples apply only if you are using HCL Informix as your database server.
- GLS User's Guide
  The Informix® GLS User's Guide describes the Global Language Support (GLS) feature available in Informix products.
- API
  The Informix® GLS API Programmer's Guide describes the global language support (GLS) application programming interface (API) available in Informix ESQL/C and HCL Informix DataBlade® modules.
- Informix® Object Interface for C++ Guide
  The Informix® Object Interface for C++ Programmer's Guide describes how to develop HCL Informix client applications by using the object-oriented C++ programming language.
- Informix® ODBC Driver Guide
  The Informix® ODBC Driver Programmer's Manual serves as a user guide and reference for Informix ODBC Driver, which is the Informix implementation of the Microsoft™ Open Database Connectivity (ODBC) interface, Version 3.0.
- .NET provider options
  The Data Server Provider for .NET DB2® provider option is the preferred Informix® provider for developing new applications.
- Informix® JDBC Driver Guide
  The Informix® JDBC Driver Programmer's Guide describes how to install, load, and use Informix JDBC Driver to connect to the Informix database from within a Java™ application or applet.
- Informix International Language Supplement (ILS) User Guide
  These topics include information about the translated user interface files for Informix® UNIX™ products, locales, and code set conversion tables
- Informix® OLE DB Provider Guide
  The Informix® OLE DB Provider Programmer's Guide describes the software requirements for using Informix OLE DB Provider, show how to install and configure the provider for your use, and explain how to use Informix OLE DB Provider to enable client applications, such as ActiveX Data Object (ADO) applications and web pages, to access data on the Informix server.

The ifx_lo_spec_free() function

The ifx_lo_spec_free() function frees the resources of an LO-specification structure.

Syntax

mint ifx_lo_spec_free(LO_spec)
   ifx_lo_create_spec_t *LO_spec;

LO_spec: A pointer to the LO-specification structure to free.

Usage

The ifx_lo_spec_free() function frees a LO-specification structure that was allocated by a call to ifx_lo_spec_free(). The LO_spec pointer points to the ifx_lo_create_spec_t structure which is to be freed.

Informix® ESQL/C does not perform memory management for a LO-specification structure. You must call ifx_lo_spec_free() for each LO-specification structure that you allocate with a call to the ifx_lo_def_create_spec() function.

Important: Do not use ifx_lo_spec_free() to free an ifx_lo_create_spec_t structure that you accessed through a call to the ifx_lo_stat_cspec() function. When you call ifx_lo_stat_free() to free the ifx_lo_stat_t structure, it also automatically frees the ifx_lo_create_spec_t structure. Use ifx_lo_spec_free() only to free an ifx_lo_create_spec_t structure that you created through a call to ifx_lo_def_create_spec().

Return codes

0: The function was successful.
<0: The function was not successful and the return value indicates the cause of the failure.