lights FAQ Forum



URL transfers

local curl = require'libcurl'

libcurl is a client-side URL transfer library, supporting DICT, FILE, FTP, FTPS, Gopher, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, POP3, POP3S, RTMP, RTSP, SCP, SFTP, SMTP, SMTPS, Telnet and TFTP. libcurl supports SSL certificates, HTTP POST, HTTP PUT, FTP uploading, HTTP form based upload, proxies, cookies, user+password authentication (Basic, Digest, NTLM, Negotiate, Kerberos), file transfer resume, http proxy tunneling and more!


easy interface
curl.easy(url | {opt=val}) -> etr create an easy transfer
etr:set(opt,val | {opt=val}) -> etr set option(s)
etr:perform() -> etr | nil,err,ecode perform the transfer
etr:close() close the transfer
etr:clone([url | {opt=val}]) -> etr clone a transfer
etr:reset([{opt=val}]) -> etr reset all options to their default values
etr:info(opt) -> val get info about the transfer
etr:recv(buf, bufsize) -> n | nil,err,errcode receive raw data
etr:send(buf, bufsize) -> n | nil,err,errcode send raw data
etr:escape(s) -> s|nil escape URL
etr:unescape(s) -> s|nil unescape URL
etr:pause([flags]) pause transfer
multi interface
curl.multi([{opt=val}]) -> mtr create a multi transfer
mtr:set(opt,val | {opt=val}) -> mtr set option(s)
mtr:add(etr) -> mtr add an easy transfer to the queue
mtr:remove(etr) -> mtr remove an easy transfer to the queue
mtr:perform() -> transfers_left | nil,err,ecode start/keep transfering
mtr:close() close the transfer
mtr:wait([timeout_seconds], [extra_fds, extra_nfds]) -> numfds | nil,err,errcode poll on all handles
mtr:fdset(read_fd_set, write_fd_set, exc_fd_set) -> max_fd | nil,err,errcode get file descriptors
mtr:timeout() -> seconds | nil how long to wait for socket actions
mtr:info_read() -> CURLMsg*|nil, msgs_in_queue read multi stack info
mtr:socket_action() read/write available data given an action
mtr:assign(sockfd, p) -> mtr set data to associate with an internal socket
share interface
curl.share([{opt=val}]) -> shr create a share object
shr:set(opt,val | {opt=val}) -> shr set option(s)
shr:free() free the share object
multipart forms
curl.form() -> frm create a multipart form
frm:add(opt1, val1, ...) -> frm add a section to a multipart form
frm:get() -> s get a multipart form as string
frm:get(out_t) -> out_t get a multipart form as an array of strings
frm:get(function(buf, len) end) get a multipart form to a callback
curl.C the libcurl ffi clib object/namespace
curl.init(flags) -> curl global init
curl.init{opt=val} -> curl global init with custom allocators global cleanup
curl.version() -> s get version info as a string
curl.version_info([ver]) -> t get detailed version info as a table
curl.checkver(maj[, min[, patch]]) -> true|false check if CURL version is >= maj.min.patch
curl.getdate(s) -> timestamp parse a date/time to a Unix timestamp
curl.easy.strerror(errcode) -> errmsg look-up an easy interface error code
curl.multi.strerror(errcode) -> errmsg look-up a multi interface error code
curl.share.strerror(errcode) -> errmsg look-up a share interface error code
curl.type(x) -> 'easy'|'multi'|'share'|nil get curl object type

Easy vs multi interface

The easy interface is synchronous while the multi interface can do multiple transfers asynchronously. A multi transfer is set up as a list of easy transfers.

Easy interface

curl.easy(url | {opt=val}) -> etr

Create a transfer using the easy interface. Options are below (they also go for etr:set()). All options are assumed immutable and the option values are anchored internally for the lifetime of the transfer object.

How option values are converted:

  • long options can be given as Lua numbers.
  • char* options can be given as Lua strings (anchored).
  • off_t options can be given as Lua numbers (no need for the _long suffix).
  • Enum options can be given as strings (case-insensitive, no prefix).
  • Bitmask options can be given as tables of form {mask_name = true|false} (again, the mask name follows the C name but case-insensitive and without the prefix).
  • curl_slist options can be given as lists of strings (anchored).
  • Callbacks can be given as Lua functions (anchored). The ffi callback objects are freed on etr:free() (*).

(*) Callback objects are ref-counted which means that replacing them on cloned transfers does not result in double-frees, and freeing them is deterministic, which is important since their number is hard-limited.

Main options
url URL to work on.
protocols Allowed protocols.
redir_protocols Protocols to allow redirects to.
default_protocol Default protocol.
port Port number to connect to.
range Request range: "X-Y,N-M,...".
resume_from Resume transfer from offset.
header Include the header in the body output.
maxfilesize Max. file size to get.
upload Enable data upload.
infilesize Size of file to send.
timecondition Make a time-conditional request.
timevalue Timestamp for conditional request.
Progress Tracking
noprogress Shut off the progress meter.
progressfunction OBSOLETE callback for progress meter.
progressdata Data pointer to pass to the progress meter callback.
xferinfofunction Callback for progress meter.
xferinfodata Data pointer to pass to the progress meter callback.
Error Handling
verbose Display verbose information.
stderr stderr replacement stream.
errorbuffer Error message buffer.
failonerror Fail on HTTP 4xx errors.
proxy Proxy to use.
proxyport Proxy port to use.
proxytype Proxy type.
noproxy Filter out hosts from proxy use.
httpproxytunnel Tunnel through the HTTP proxy.
socks5_gssapi_service Socks5 GSSAPI service name.
socks5_gssapi_nec Socks5 GSSAPI NEC mode.
proxy_service_name Proxy service name.
I/O Callbacks
writefunction Callback for writing data.
writedata Data pointer to pass to the write callback.
readfunction Callback for reading data.
readdata Data pointer to pass to the read callback.
seekfunction Callback for seek operations.
seekdata Data pointer to pass to the seek callback.
Speed Limits
low_speed_limit Low speed limit to abort transfer.
low_speed_time Time to be below the speed to trigger low speed abort.
max_send_speed Cap the upload speed.
max_recv_speed Cap the download speed.
netrc Enable .netrc parsing.
netrc_file .netrc file name.
userpwd User name and password.
proxyuserpwd Proxy user name and password.
username User name.
password Password.
login_options Login options.
proxyusername Proxy user name.
proxypassword Proxy password.
httpauth HTTP server authentication methods.
tlsauth_username TLS authentication user name.
tlsauth_password TLS authentication password.
tlsauth_type TLS authentication methods.
proxyauth HTTP proxy authentication methods.
sasl_ir Enable SASL initial response.
xoauth2_bearer OAuth2 bearer token.
HTTP Protocol
autoreferer Automatically set Referer: header.
accept_encoding Accept-Encoding and automatic decompressing data.
transfer_encoding Request Transfer-Encoding.
followlocation Follow HTTP redirects.
unrestricted_auth Do not restrict authentication to original host.
maxredirs Maximum number of redirects to follow.
postredir How to act on redirects after POST.
put Issue a HTTP PUT request.
post Issue a HTTP POST request.
httpget Do a HTTP GET request.
postfields Send a POST with this data.
postfieldsize The POST data is this big.
copypostfields Send a POST with this data - and copy it.
httppost Multipart formpost HTTP POST.
referer Referer: header.
useragent User-Agent: header.
httpheader Custom HTTP headers.
headeropt Control custom headers.
proxyheader Custom HTTP headers sent to proxy.
http200aliases Alternative versions of 200 OK.
cookie Cookie(s) to send.
cookiefile File to read cookies from.
cookiejar File to write cookies to.
cookiesession Start a new cookie session.
cookielist Add or control cookies.
http_version HTTP version to use.
ignore_content_length Ignore Content-Length.
http_content_decoding Disable Content decoding.
http_transfer_decoding Disable Transfer decoding.
expect_100_timeout_ms 100-continue timeout in ms.
pipewait Wait on connection to pipeline on it.
interface Bind connection locally to this.
localport Bind connection locally to this port.
localportrange Bind connection locally to port range.
tcp_nodelay Disable the Nagle algorithm.
tcp_keepalive Enable TCP keep-alive.
tcp_keepidle Idle time before sending keep-alive.
tcp_keepintvl Interval between keep-alive probes.
address_scope IPv6 scope for local addresses.
unix_socket_path Path to a Unix domain socket.
dns_interface Bind name resolves to an interface.
dns_cache_timeout Timeout for DNS cache.
dns_local_ip4 Bind name resolves to an IP4 address.
dns_local_ip6 Bind name resolves to an IP6 address.
dns_servers Preferred DNS servers.
dns_use_global_cache OBSOLETE Enable global DNS cache.
timeout Timeout for the entire request in seconds.
timeout_ms Timeout for the entire request in ms.
connecttimeout Timeout for the connection phase in seconds.
connecttimeout_ms Timeout for the connection phase in ms.
accepttimeout_ms Timeout for a connection be accepted.
fresh_connect Use a new connection.
forbid_reuse Prevent subsequent connections from re-using this connection.
connect_only Only connect, nothing else.
resolve Provide fixed/fake name resolves.
conv_from_network_function Callback for code base conversion.
conv_to_network_function Callback for code base conversion.
conv_from_utf8_function Callback for code base conversion.
sockoptfunction Callback for sockopt operations.
sockoptdata Data pointer to pass to the sockopt callback.
SSH Protocol
ssh_auth_types SSH authentication types.
ssh_public_keyfile File name of public key.
ssh_private_keyfile File name of private key.
ssh_knownhosts File name with known hosts.
ssh_keyfunction Callback for known hosts handling.
ssh_keydata Custom pointer to pass to ssh key callback.
ssh_host_public_key_md5 MD5 of host's public key.
SMTP Protocol
mail_from Address of the sender.
mail_rcpt Address of the recipients.
mail_auth Authentication address.
TFTP Protocol
tftp_blksize TFTP block size.
use_ssl Use TLS/SSL.
sslcert Client cert.
sslversion SSL version to use.
sslcerttype Client cert type.
sslkey Client key.
sslkeytype Client key type.
keypasswd Client key password.
sslengine Use identifier with SSL engine.
sslengine_default Default SSL engine.
ssl_options Control SSL behavior.
ssl_falsestart Enable TLS False Start.
ssl_cipher_list Ciphers to use.
ssl_verifyhost Verify the host name in the SSL certificate.
ssl_verifypeer Verify the SSL certificate.
ssl_verifystatus Verify the SSL certificate's status.
ssl_ctx_function Callback for SSL context logic.
ssl_ctx_data Data pointer to pass to the SSL context callback.
ssl_sessionid_cache Disable SSL session-id cache.
cainfo CA cert bundle.
capath Path to CA cert bundle.
crlfile Certificate Revocation List.
issuercert Issuer certificate.
certinfo Extract certificate info.
pinnedpublickey Set pinned SSL public key.
krblevel Kerberos security level.
random_file Provide source for entropy random data.
egdsocket Identify EGD socket for entropy.
gssapi_delegation Disable GSS-API delegation.
FTP Protocol
ftpport Use active FTP.
quote Commands to run before transfer.
postquote Commands to run after transfer.
prequote Commands to run just before transfer.
append Append to remote file.
ftp_use_eprt Use EPTR.
ftp_use_epsv Use EPSV.
ftp_use_pret Use PRET.
ftp_create_missing_dirs Create missing directories on the remote server.
ftp_response_timeout Timeout for FTP responses.
ftp_alternative_to_user Alternative to USER.
ftp_skip_pasv_ip Ignore the IP address in the PASV response.
ftpsslauth Control how to do TLS.
ftp_ssl_ccc Back to non-TLS again after authentication.
ftp_account Send ACCT command.
ftp_filemethod Specify how to reach files.
transfertext Use text transfer.
proxy_transfer_mode Add transfer mode to URL over proxy.
RTSP Protocol
rtsp_request RTSP request.
rtsp_session_id RTSP session-id.
rtsp_stream_uri RTSP stream URI.
rtsp_transport RTSP Transport:
rtsp_client_cseq Client CSEQ number.
rtsp_server_cseq CSEQ number for RTSP Server->Client request.
interleavefunction Callback for RTSP interleaved data.
interleavedata Data pointer to pass to the RTSP interleave callback.
Misc. Options
path_as_is Disable squashing /../ and /./ sequences in the path.
buffersize Ask for smaller buffer size.
nosignal Do not install signal handlers.
share Share object to use.
private Private pointer to store.
ipresolve IP version to resolve to.
ioctlfunction Callback for I/O operations.
ioctldata Data pointer to pass to the I/O callback.
service_name SPNEGO service name.
crlf Convert newlines.
customrequest Custom request/method.
filetime Request file modification date and time.
dirlistonly List only.
nobody Do not get the body contents.
new_file_perms Mode for creating new remote files.
new_directory_perms Mode for creating new remote directories.
chunk_bgn_function Callback for wildcard download start of chunk.
chunk_end_function Callback for wildcard download end of chunk.
chunk_data Data pointer to pass to the chunk callbacks.
fnmatch_function Callback for wildcard matching.
fnmatch_data Data pointer to pass to the wildcard matching callback.
wildcardmatch Transfer multiple files according to a file name pattern.
telnetoptions TELNET options.
maxconnects Maximum number of connections in the connection pool.
headerfunction Callback for writing received headers.
headerdata Data pointer to pass to the header callback.
debugfunction Callback for debug information.
debugdata Data pointer to pass to the debug callback.

Multi interface

curl.multi([{etr1,..., opt=val}]) -> mtr

Create a transfer using the multi interface. The details are the same as with the easy interface except that the list of options is different (see below). Also, if the options table has any elements in the array part, mtr:add() is called for/with each element.

There's a section on the libcurl tutorial on how to use the multi interface.

socketfunction Callback about what to wait for
socketdata Custom pointer passed to the socket callback
pipelining enable/disable HTTP pipelining
timerfunction Set callback to receive timeout values
timerdata Custom pointer to pass to timer callback
maxconnects Set size of connection cache
max_host_connections Set max number of connections to a single host
max_pipeline_length Maximum number of requests in a pipeline
content_length_penalty_size Size threshold for pipelining penalty
chunk_length_penalty_size Chunk length threshold for pipelining
pipelining_site_bl Pipelining host blacklist (list of strings)
pipelining_server_bl Pipelining server blacklist (list of strings)
max_total_connections Max simultaneously open connections
pushfunction Callback that approves or denies server pushes
pushdata Pointer to pass to push callback

Share interface

curl.share([{opt=val}]) -> shr

Create a share object. Options below (also for shr:set()):

lockfunc lock data callback
unlockfunc unlock data callback
share what tyoe of data to share
unshare what type of data not to share
userdata pointer to pass to lock and unlock functions

Multipart forms

frm:add(opt1, val1, ...) -> frm

Add a section to a multipart form. Options can be given as strings (case-insensitive, no prefix). The value for the 'array' option is a Lua array of options. The 'end' option is appended automatically to the arg list and to arrays. All values are anchored for the lifetime of the form, so strings and cdata arrays can be passed in freely.


   'ptrname', 'main-section',
   'file', 'file1.txt',
   'file', 'file2.txt'
form:add('array', {
   'ptrname', 'main-section',
   'ptrcontents', 'hello',
   'contentheader', {'Header1: Value1', 'Header2: Value2'},


The included libcurl binaries are compiled to use the SSL/TLS APIs provided by the OS and do not include binaries for OpenSSL or other SSL library, except for Linux, where openssl is used (*).

(*) The decision to ship OpenSSL on Linux is because OpenSSL is not ABI-compatible between versions and distros don't usually ship multiple versions of it (sigh, Linux).

DNS resolving is asynchronous using the multi-threaded resolver.

Features that were not compiled in:

  • SFTP and SCP (requires libssh2).
  • HTTP2 (requires ng-http2).
  • IDN (requires libidn).
  • RTMP (requires librtmp).
  • PSL (requires libpsl).
  • LDAP.

Last updated: 12 months ago | Edit on GitHub

Pkg type:Lua+ffi
Version: r1-3-g96b2fda
Last commit:
License: PD
Import ver: 7.46.0
Requires: luajit  +openssl 
Required by: none