README

This is skeleton documentation for a small but usable driver for POSIX
system calls and C library functions that the Erlang runtime doesn't
support out-of-the-box.  It supports the following:

    getegid geteuid getgid getgrgid getgrnam getgroups getlogin getpgrp
    getppid getpwnam getpwuid getsid getuid kill lstat mkfifo mknod
    umask

This driver was automatically generated by the Erlang Driver Toolkit,
http://www.snookles.com/erlang/edtk/.  See the file "priv/posix.xml"
for the config file used to create the driver.  If you find bugs or
portability problems with this driver, please contact me via email at
slfritchie /at\ snookles {dot} com so I can fix both this driver and
the EDTK code generator!

See the file "LICENSE" in this directory for the licensing terms for
this software.

A demo of all supported functions can be found in the cut-and-paste of
an interactive shell session at the end of this README.  In almost all
cases, the driver will return a tuple of {ok, Stuff} or {error,
Stuff}.  In the error case, Stuff is typically the systems "errno"
value.

The "test" directory contains a regression test program.  It contains
additional hints and examples of using the driver.

NOTE: The posix_drv:start/0 function is expecting to find the
      posix_drv.so shared library somewhere in the BEAM virtual
      machine's code path.  Therefore, you need to use the "-pa
      /path/to/dir" or "-pz /path/to/dir" on the "erl" command line,
      otherwise you'll get an error like the following:

      Erlang (BEAM) emulator version 5.2.3.3 [source] [threads:0]
      
      Eshell V5.2.3.3  (abort with ^G)
      1> posix_drv:start().
      Error: posix_drv.so not found in code path
      
      =ERROR REPORT==== 22-Apr-2003::02:31:21 ===
      Error in process <0.26.0> with exit value: {{badmatch,{error,enoent}},[{posix_drv,start,0},{erl_eval,expr,3},{erl_eval,exprs,4},{shell,eval_loop,2}]}
      ** exited: {{badmatch,{error,enoent}},
                  [{posix_drv,start,0},
                   {erl_eval,expr,3},
                   {erl_eval,exprs,4},
                   {shell,eval_loop,2}]} **

--- usage demo --- usage demo --- usage demo --- usage demo --- usage demo ---

% ./bin/jerl
Erlang (BEAM) emulator version 5.2.3.3 [source] [threads:0]

Eshell V5.2.3.3  (abort with ^G)
1> {ok, P} = posix_drv:start().
{ok,#Port<0.29>}
2> posix_drv:getg
getgid/1     getgrgid/2   getgrnam/2   getgroups/1  
2> posix_drv:getgid(P).
{ok,20}
3> posix_drv:getegid(P).
{ok,20}
4> posix_drv:getgrnam(P, "wheel").
{ok,{group,<<119,104,101,101,108>>,
           <<42>>,
           0,
           <<10,160,68,8,15,160,68,8>>}}
5> posix_drv:getgrgid(P, 0).      
{ok,{group,<<119,104,101,101,108>>,
           <<42>>,
           0,
           <<10,160,68,8,15,160,68,8>>}}
6> posix_drv:getgroups(P).  
{ok,{3,[20,20,0]}}
7> ^Z
   Suspended
% id
uid=100(fritchie) gid=20(staff) groups=20(staff), 0(wheel)
% grep wheel /etc/group 
wheel:*:0:root,fritchie
% fg
./bin/jerl

7> posix_drv:getpwnam(P, "fritchie").
{ok,{passwd,<<102,114,105,116,99,104,105,101>>,
            <<42>>,
            100,
            20,
            <<83,99,111,116,116,32,76,121,115,116,105,103,32,70,114,105,116,99,104,105,...>>,
            <<47,117,115,101,114,47,102,114,105,116,99,104,105,101>>,
            <<47,98,105,110,47,99,115,104>>}}
8> posix_drv:getpwuid(P, 0).         
{ok,{passwd,<<114,111,111,116>>,
            <<42>>,
            0,
            0,
            <<67,104,97,114,108,105,101,32,38>>,
            <<47,114,111,111,116>>,
            <<47,98,105,110,47,99,115,104>>}}
9> ^Z
   Suspended
% grep fritchie /etc/passwd 
fritchie:*:100:20:Scott Lystig Fritchie:/user/fritchie:/bin/csh
% grep root /etc/passwd
root:*:0:0:Charlie &:/root:/bin/csh
% fg
./bin/jerl

9> posix_drv:getuid(P).     
{ok,100}
10> posix_drv:geteuid(P).
{ok,100}
11> posix_drv:getlogin(P).
{ok,<<102,114,105,116,99,104,105,101>>}
12> posix_drv:getpgrp(P). 
{ok,24844}
13> posix_drv:getppid(P).
{ok,24844}
14> posix_drv:getsid(P). 
{ok,22532}
15> posix_drv:kill(P, 88888, 15).
{error,3}
16> os:getpid().
"24845"
17> posix_drv:kill(P, 24845, 0). 
{ok,0}
18> posix_drv:lstat(P, "/").     
{ok,{stat,1030,
          2,
          16877,
          18,
          0,
          0,
          1504,
          {1050963494,0},
          {1050600129,0},
          {1050600129,0},
          512,
          4,
          4096}}
19> posix_drv:mkfifo(P, "/tmp/fifo0", 8#644).
{ok,0}
20> posix_drv:mknod(P, "/tmp/i-am-not-root", 8#644, 0). 
{error,1}
21> posix_drv:umask(P, 8#022).                          
{ok,18}
22> q().
ok
23>
% ls -lLd /
drwxr-xr-x  18 root  wheel  512 Apr 17 12:22 /
% ls -l /tmp/fifo0 
prw-r--r--  1 fritchie  wheel  0 Apr 22 02:16 /tmp/fifo0