.Dd March 22, 2013
.Os SQLite\ UDF
.Dt READDIR \&3s "SQLite User-defined Functions"
.Sh NAME
.Nm readdir
.Nd virtual table representing a directory listing
.Sh LIBRARY
SQLite User-defined function Library (readdir.so)
.Sh SYNOPSIS
.Li create virtual table 
.Ar tablename
using
.Nm Pf ( Pa dirname Ns )
.Sh DESCRIPTION
The 
.Nm
virtual table renders
.Pa dirname
in the filesystem as a table with the following columns:
.Bl -tag -width inode
.It fileno
.Li inode
number for the file
.It type
.Li type
of the file, as displayed by 
.Ic ls(1)
.It name
filename in 
.Pa dirname
.It fullname
full file name, formed by combining
.Pa dirname
with the  
.Pa name
column
.El
.Pp
If 
.Ar dirname
begins with 
.Ql $
e.g. 
.Li $HOME
and no directory is found with that name, it is interpreted as 
an environment variable.  If one is found using 
.Xr getenv 3 ,
the value of the variable is used instead.
.Pp
The contents of the virtual table are 
.Em not
cached.  That is, every query initiates a call to 
.Xr opendir 3
and each row is returned by
.Xr readdir 3 .
.Sh EXAMPLES
To compare two directories (or to look for changes over time) consider:
.Bd -literal
sqlite> create virtual table t using readdir (/tmp/eg);
sqlite> select name from t;
name      
----------
.         
..        
atf       
dhcpd     
doc       
games     
groff_font
info      
legal     
man       
misc      
ms        
nvi       
tmac      
xml       
zoneinfo  
sqlite> create table olddir as select * from t;
sqlite> ^Z
$ touch /tmp/eg/newfile
$ fg
./sqlite3
sqlite> select * from t where name not in (select name from olddir);
fileno      type        name        fullname       
----------  ----------  ----------  ---------------
13630394    r           newfile     /tmp/eg/newfile
.Ed
.Sh IMPLEMENTATION NOTES
To use 
.Nm
in the SQLite shell
.Ic sqlite3 ,
add the following to your 
.Pa ${HOME}/.sqliterc 
file:
.Bd -literal
\&.load /usr/local/lib/sqlite3/readdir.so
.Ed
.Sh SEE ALSO
.Xr stat 3s
.Xr strmode 3s
.Pp
The above SQLite user-defined functions are intended for use with 
.Nm .
.Sh AUTHORS
.Nm
was contributed by James K. Lowden
.\" .Sh BUGS