hclose, hcount, hdel, hopen, hsym

File and process handles


File size

Syntax: hcount x, hcount[x]

Returns as a long integer the size in bytes of file x.


On a compressed file returns the size of the original uncompressed file.

Basics: File system,


Delete a file or folder

Syntax: hdel x, hdel[x]

Where x is a file or folder symbol, deletes it.

q)hdel`:test.txt   / delete test.txt in current working directory
q)hdel`:test.txt   / should generate an error
'test.txt: No such file or directory

hdel can delete folders only if empty

'​mydir​. OS reports: Directory not empty
  [0]  hdel`:​mydir​

Delete a folder and its contents

To delete a folder and its contents, recursively

​/diR gets recursive dir listing​
q)diR:{$[11h=type d:key x;raze x,.z.s each` sv/:x,/:d;d]}
​/hide power behind nuke​
q)​nuke:hdel​ ​each​ ​​desc diR​@​ / desc sort!​

For a general visitor pattern with hdel

​q)visitNode:{if[11h=type d:key y;.z.s[x]each` sv/:y,/:d;];x y}

Basics: File system,


Open a file or process handle

Syntax: hopen x, hopen[x]

Where x is one of

  • a process handle
  • a 2-item list of a process handle and a timeout in milliseconds
  • a filename: symbol or (since V3.6 2017.09.26) string

opens a file or a process handle, and returns a positive integer handle.

A process handle has the form:

host can be a hostname or IP address; omitted, it denotes the localhost
Unix domain socket
(Since V3.4.) Unix domain sockets can have significantly lower latency and higher throughput than a localhost TCP connection
Knowledge Base: SSL/TLS

User and password are required if the server session has been started with the -u or -U command line options, and are passed to .z.pw for (optional) additional processing.

The optional timeout applies to the initial connection, not subsequent use of it.

q)h:hopen `:                    / IP address
q)h:hopen `:mydb.us.com:5010                     / hostname
q)h:hopen `::5010                                / localhost
q)h:hopen 5010                                   / localhost
q)h:hopen `:unix://5010                          / localhost, Unix domain socket
q)h:hopen `:tcps://mydb.us.com:5010              / SSL/TLS with hostname
q)h:hopen (`:mydb.us.com:5010:elmo:sesame;10000) / full arg list, 10s timeout

To send messages to the remote process:

q)h"2+2"          / synchronous (GET)   
q)(neg h)"a:2"    / asynchronous (SET)

If only one synchronous query/request is to be run, then the single-shot synchronous request can be used to open a connection, send the query, get the results, then close the connection. It is more efficient to keep a connection open if there is an opportunity to re-use it for other queries.

q)`:mydb.us.com:5010:elmo:sesame "1+1"

.Q: .Q.Xf (create file)
Knowledge Base: Client-server

File handles

A file handle is used for writing to a file. The hopen argument is a symbol or (since V3.6 2017.09.26) string filename:

q)hdat:hopen `:f.dat             / data file (bytes)
q)htxt:hopen `:c:/q/test.txt     / text file

Passing char vectors instead of symbols avoids interning of such symbols. This is useful if embedding frequently-changing tokens in the username or password fields.

For IPC compatibility, it serializes to {hopen x}. e.g.

q)hopen each(`:mysymbol;":mycharvector";`:localhost:5000;":localhost:5000";(`:localhost:5000;1000);(":localhost:5000";1000))

To append to these files, the syntax is the same as for IPC:

q)r:hdat 0x2324
q)r:htxt "some text\n"
q)r:htxt ` sv("asdf";"qwer")

Fifo/named pipes

V3.4 Unix builds have support for reading from a Fifo/named pipe, where the hopen argument has the form `:fifo://filename.

Basics: File system, Client-server, Named pipes
Knowledge Base: SSL/TLS


Close a file or process handle

Syntax: hclose x, hclose[x]

Close file or process handle x.

q)h:hopen `::5001
q)h"til 5"
0 1 2 3 4
q)hclose h
q)h"til 5"
': Bad file descriptor

Pending data on the handle is not sent prior to closing. If flushing is required prior to close, this must be done explicitly. (Since V3.6 2019.09.19)

q)neg[h][];hclose h; 

Before V3.6 2019.09.19

If the handle refers to a websocket, hclose blocks until any pending data on the handle has been sent.

Basics: File system, IPC


Convert symbol to file handle

Syntax: hsym x,hsym[x]

Converts symbol x into a file name, or valid hostname, or IP address. Since V3.1, x can be a symbol list.


Basics: File system