source: project/wiki/man/4/Unit posix @ 30079

Last change on this file since 30079 was 30079, checked in by sjamaan, 7 years ago

Clarify process/process* distinction a bit

File size: 49.0 KB
Line 
1[[tags: manual]]
2[[toc:]]
3
4== Unit posix
5
6This unit provides services as used on many UNIX-like systems.  Note that
7the following definitions are not all available on non-UNIX systems like
8Windows. See below for Windows specific notes.
9
10This unit uses the {{regex}}, {{scheduler}}, {{extras}} and {{utils}} units.
11
12All errors related to failing file-operations will signal a condition
13of kind {{(exn i/o file)}}.
14
15
16=== Constants
17
18==== File-control Commands
19
20<constant>fcntl/dupfd</constant><br>
21<constant>fcntl/getfd</constant><br>
22<constant>fcntl/setfd</constant><br>
23<constant>fcntl/getfl</constant><br>
24<constant>fcntl/setfl</constant>
25
26Operations used with {{file-control}}.
27
28==== Standard I/O file-descriptors
29
30<constant>fileno/stdin</constant><br>
31<constant>fileno/stdout</constant><br>
32<constant>fileno/stderr</constant>
33
34Standard I/O file descriptor numbers, used with procedures
35such as {{open-input-file*}} which take file descriptors.
36
37==== Open flags
38
39<constant>open/rdonly</constant><br>
40<constant>open/wronly</constant><br>
41<constant>open/rdwr</constant><br>
42<constant>open/read</constant><br>
43<constant>open/write</constant><br>
44<constant>open/creat</constant><br>
45<constant>open/append</constant><br>
46<constant>open/excl</constant><br>
47<constant>open/noctty</constant><br>
48<constant>open/nonblock</constant><br>
49<constant>open/trunc</constant><br>
50<constant>open/sync</constant><br>
51<constant>open/fsync</constant><br>
52<constant>open/binary</constant><br>
53<constant>open/text</constant>
54
55Open flags used with the {{file-open}} procedure.  {{open/read}} is a
56convenience synonym for {{open/rdonly}}, as is {{open/write}}
57for {{open/wronly}}.
58
59==== Permission bits
60
61<constant>perm/irusr</constant><br>
62<constant>perm/iwusr</constant><br>
63<constant>perm/ixusr</constant><br>
64<constant>perm/irgrp</constant><br>
65<constant>perm/iwgrp</constant><br>
66<constant>perm/ixgrp</constant><br>
67<constant>perm/iroth</constant><br>
68<constant>perm/iwoth</constant><br>
69<constant>perm/ixoth</constant><br>
70<constant>perm/irwxu</constant><br>
71<constant>perm/irwxg</constant><br>
72<constant>perm/irwxo</constant><br>
73<constant>perm/isvtx</constant><br>
74<constant>perm/isuid</constant><br>
75<constant>perm/isgid</constant>
76
77Permission bits used with, for example, {{file-open}}.
78
79=== Directories
80
81==== change-directory
82
83<procedure>(change-directory NAME)</procedure>
84
85Changes the current working directory to {{NAME}}.
86
87==== change-directory*
88
89<procedure>(change-directory* FD)</procedure>
90
91Changes the current working directory to the one represented by the
92file-descriptor {{FD}}, which should be an exact integer.
93
94
95==== current-directory
96
97<procedure>(current-directory [DIR])</procedure>
98
99Returns the name of the current working directory. If the optional argument {{DIR}} is given,
100then {{(current-directory DIR)}} is equivalent to {{(change-directory DIR)}}.
101
102==== create-directory
103
104<procedure>(create-directory NAME #!optional PARENTS?)</procedure>
105
106Creates a directory with the pathname {{NAME}}.  If the {{PARENTS?}} argument
107is given and not false, any nonexistent parent directories are also created.
108
109Notice that if {{NAME}} exists, {{create-directory}} won't try to create it
110and will return {{NAME}} (i.e., it won't raise an error when given a {{NAME}}
111that already exists).
112
113
114==== delete-directory
115
116<procedure>(delete-directory NAME [RECURSIVE])</procedure>
117
118Deletes the directory with the pathname {{NAME}}. If {{RECURSIVE}} is
119not given or false, then the directory has to be empty.
120
121==== directory
122
123<procedure>(directory [PATHNAME [SHOW-DOTFILES?]])</procedure>
124
125Returns a list with all files that are contained in the directory with the name {{PATHNAME}}
126(which defaults to the value of {{(current-directory)}}).
127Files beginning with {{.}} are included only if {{SHOW-DOTFILES?}} is given and not {{#f}}.
128
129==== directory?
130
131<procedure>(directory? FILE)</procedure>
132
133Returns {{#t}} if {{FILE}} designates directory. Otherwise, it returns {{#f}}.
134{{FILE}} may be a pathname or a file-descriptor.
135
136==== glob
137
138<procedure>(glob PATTERN1 ...)</procedure>
139
140Returns a list of the pathnames of all existing files matching
141{{PATTERN1 ...}}, which should be strings containing the usual
142file-patterns (with {{*}} matching zero or more characters and
143{{?}} matching zero or one character).
144
145==== set-root-directory!
146
147<procedure>(set-root-directory! STRING)</procedure>
148
149Sets the root directory for the current process to the path given in {{STRING}}
150(using the {{chroot}} function).
151If the current process has no root permissions, the operation will fail.
152
153
154=== Pipes
155
156==== call-with-input-pipe
157==== call-with-output-pipe
158
159<procedure>(call-with-input-pipe CMDLINE PROC [MODE])</procedure><br>
160<procedure>(call-with-output-pipe CMDLINE PROC [MODE])</procedure>
161
162Call {{PROC}} with a single argument: a input- or output port
163for a pipe connected to the subprocess named in {{CMDLINE}}. If
164{{PROC}} returns normally, the pipe is closed and any result values
165are returned.
166
167==== close-input-pipe
168==== close-output-pipe
169
170<procedure>(close-input-pipe PORT)</procedure><br>
171<procedure>(close-output-pipe PORT)</procedure>
172
173Closes the pipe given in {{PORT}} and waits until the connected
174subprocess finishes. The exit-status code of the invoked process
175is returned.
176
177==== create-pipe
178
179<procedure>(create-pipe)</procedure>
180
181The fundamental pipe-creation operator. Calls the C function
182{{pipe()}} and returns 2 values: the file-descriptors of the input-
183and output-ends of the pipe.
184
185==== open-input-pipe
186
187<procedure>(open-input-pipe CMDLINE [MODE])</procedure>
188
189Spawns a subprocess with the command-line string {{CMDLINE}} and
190returns a port, from which the output of the process can be read. If
191{{MODE}} is specified, it should be the keyword {{#:text}}
192(the default) or {{#:binary}}.
193
194==== open-output-pipe
195
196<procedure>(open-output-pipe CMDLINE [MODE])</procedure>
197
198Spawns a subprocess with the command-line string {{CMDLINE}} and
199returns a port. Anything written to that port is treated as the input
200for the process.  If {{MODE}} is specified, it should be the keyword
201{{#:text}} (the default) or {{#:binary}}.
202
203==== pipe/buf
204This variable contains the maximal number of bytes that can be written
205atomically into a pipe or FIFO.
206
207==== with-input-from-pipe
208==== with-output-to-pipe
209
210<procedure>(with-input-from-pipe CMDLINE THUNK [MODE])</procedure><br>
211<procedure>(with-output-to-pipe CMDLINE THUNK [MODE])</procedure>
212
213Temporarily set the value of
214{{current-input-port/current-output-port}} to a port for a
215pipe connected to the subprocess named in {{CMDLINE}} and call
216the procedure {{THUNK}} with no arguments. After {{THUNK}}
217returns normally the pipe is closed and the standard input-/output port
218is restored to its previous value and any result values are returned.
219
220<enscript highlight=scheme>
221(with-output-to-pipe
222  "gs -dNOPAUSE -sDEVICE=jpeg -dBATCH -sOutputFile=signballs.jpg -g600x600 -q -"
223  (lambda ()
224    (print #<<EOF
225 %!IOPSC-1993 %%Creator: HAYAKAWA Takashi<xxxxxxxx@xx.xxxxxx.xx.xx>
226 /C/neg/d/mul/R/rlineto/E/exp/H{{cvx def}repeat}def/T/dup/g/gt/r/roll/J/ifelse 8
227 H/A/copy(z&v4QX&93r9AxYQOZomQalxS2w!!O&vMYa43d6r93rMYvx2dca!D&cjSnjSnjjS3o!v&6A
228 X&55SAxM1CD7AjYxTTd62rmxCnTdSST0g&12wECST!&!J0g&D1!&xM0!J0g!l&544dC2Ac96ra!m&3A
229 F&&vGoGSnCT0g&wDmlvGoS8wpn6wpS2wTCpS1Sd7ov7Uk7o4Qkdw!&Mvlx1S7oZES3w!J!J!Q&7185d
230 Z&lx1CS9d9nE4!k&X&MY7!&1!J!x&jdnjdS3odS!N&mmx1C2wEc!G&150Nx4!n&2o!j&43r!U&0777d
231 ]&2AY2A776ddT4oS3oSnMVC00VV0RRR45E42063rNz&v7UX&UOzF!F!J![&44ETCnVn!a&1CDN!Y&0M
232 V1c&j2AYdjmMdjjd!o&1r!M){( )T 0 4 3 r put T(/)g{T(9)g{cvn}{cvi}J}{($)g[]J}J
233 cvx}forall/moveto/p/floor/w/div/S/add 29 H[{[{]setgray fill}for Y}for showpage
234 EOF
235 ) ) )
236</enscript>
237
238
239=== Fifos
240
241==== create-fifo
242
243<procedure>(create-fifo FILENAME [MODE])</procedure>
244
245Creates a FIFO with the name {{FILENAME}} and the permission bits
246{{MODE}}, which defaults to
247
248<enscript highlight=scheme>
249 (+ perm/irwxu perm/irwxg perm/irwxo)
250</enscript>
251
252==== fifo?
253
254<procedure>(fifo? FILE)</procedure>
255
256Returns {{#t}} if {{FILE}} names a FIFO. {{FILE}} may be a filename
257or a file-descriptor.
258
259
260=== File descriptors and low-level I/O
261
262==== duplicate-fileno
263
264<procedure>(duplicate-fileno OLD [NEW])</procedure>
265
266If {{NEW}} is given, then the file-descriptor {{NEW}} is opened
267to access the file with the file-descriptor {{OLD}}. Otherwise a
268fresh file-descriptor accessing the same file as {{OLD}} is returned.
269
270==== file-close
271
272<procedure>(file-close FILENO)</procedure>
273
274Closes the input/output file with the file-descriptor {{FILENO}}.
275
276==== file-open
277
278<procedure>(file-open FILENAME FLAGS [MODE])</procedure>
279
280Opens the file specified with the string {{FILENAME}} and open-flags
281{{FLAGS}} using the C function {{open(2)}}. On success a
282file-descriptor for the opened file is returned.
283
284{{FLAGS}} is a bitmask of {{open/...}}
285values '''or'''ed together using {{bitwise-ior}} (or simply added
286together).  You must provide exactly one of the access flags {{open/rdonly}}, {{open/wronly}}, or {{open/rdwr}}.  Additionally, you may provide zero or more creation flags ({{open/creat}}, {{open/excl}}, {{open/trunc}}, and {{open/noctty}}) and status flags (the remaining {{open/...}} values).  For example, to open a possibly new output file for appending:
287
288 (file-open "/tmp/hen.txt" (+ open/wronly open/append open/creat))
289
290The optional {{MODE}} should be a bitmask composed of one
291or more permission values like {{perm/irusr}} and is only relevant
292when a new file is created. The default mode is
293{{perm/irwxu | perm/irgrp | perm/iroth}}.
294
295==== file-mkstemp
296
297<procedure>(file-mkstemp TEMPLATE-FILENAME)</procedure>
298
299Create a file based on the given {{TEMPLATE-FILENAME}}, in which
300the six last characters must be ''XXXXXX''.  These will be replaced
301with a string that makes the filename unique.  The file descriptor of
302the created file and the generated filename is returned.  See the
303{{mkstemp(3)}} manual page for details on how this function
304works.  The template string given is not modified.
305
306Example usage:
307
308<enscript highlight=scheme>
309 (let-values (((fd temp-path) (file-mkstemp "/tmp/mytemporary.XXXXXX")))
310  (let ((temp-port (open-output-file* fd)))
311    (format temp-port "This file is ~A.~%" temp-path)
312    (close-output-port temp-port)))
313</enscript>
314
315==== file-read
316
317<procedure>(file-read FILENO SIZE [BUFFER])</procedure>
318
319Reads {{SIZE}} bytes from the file with the file-descriptor
320{{FILENO}}.  If a string or bytevector is passed in the optional
321argument {{BUFFER}}, then this string will be destructively modified
322to contain the read data. This procedure returns a list with two values:
323the buffer containing the data and the number of bytes read.
324
325==== file-select
326
327<procedure>(file-select READFDLIST WRITEFDLIST [TIMEOUT])</procedure>
328
329Waits until any of the file-descriptors given in the lists
330{{READFDLIST}} and {{WRITEFDLIST}} is ready for input or
331output, respectively. If the optional argument {{TIMEOUT}} is
332given and not false, then it should specify the number of seconds after
333which the wait is to be aborted (the value may be a floating point
334number). This procedure returns two values:
335the lists of file-descriptors ready for input and output, respectively.
336{{READFDLIST}} and '''WRITEFDLIST''' may also by file-descriptors
337instead of lists.  In this case the returned values are booleans
338indicating whether input/output is ready by {{#t}} or {{#f}}
339otherwise.  You can also pass {{#f}} as {{READFDLIST}} or
340{{WRITEFDLIST}} argument, which is equivalent to {{()}}.
341
342==== file-write
343
344<procedure>(file-write FILENO BUFFER [SIZE])</procedure>
345
346Writes the contents of the string or bytevector {{BUFFER}} into
347the file with the file-descriptor {{FILENO}}. If the optional
348argument {{SIZE}} is given, then only the specified number of bytes
349are written.
350
351==== file-control
352
353<procedure>(file-control FILENO COMMAND [ARGUMENT])</procedure>
354
355Performs the fcntl operation {{COMMAND}} with the given
356{{FILENO}} and optional {{ARGUMENT}}. The return value is
357meaningful depending on the {{COMMAND}}.
358
359==== open-input-file*
360==== open-output-file*
361
362<procedure>(open-input-file* FILENO [OPENMODE])</procedure><br>
363<procedure>(open-output-file* FILENO [OPENMODE])</procedure>
364
365Opens file for the file-descriptor {{FILENO}} for input or output
366and returns a port.  {{FILENO}} should be a positive exact integer.
367{{OPENMODE}} specifies an additional mode for opening the file
368(currently only the keyword {{#:append}} is supported, which opens
369an output-file for appending).
370
371==== port->fileno
372
373<procedure>(port->fileno PORT)</procedure>
374
375If {{PORT}} is a file- or tcp-port, then a file-descriptor is returned for
376this port. Otherwise an error is signaled.
377
378
379=== Retrieving file attributes
380
381==== file-access-time
382==== file-change-time
383==== file-modification-time
384
385<procedure>(file-access-time FILE)</procedure><br>
386<procedure>(file-change-time FILE)</procedure><br>
387<procedure>(file-modification-time FILE)</procedure>
388<procedure>(set! (file-modification-time FILE) SECONDS)</procedure>
389
390Returns time (in seconds) of the last access, modification or change of {{FILE}}. {{FILE}}
391may be a filename or a file-descriptor. If the file does not exist,
392an error is signaled.
393
394{{(set! (file-modification-time FILE) SECONDS)}} sets the access- and modification
395time of {{FILE}} to {{SECONDS}}.
396
397==== file-stat
398
399<procedure>(file-stat FILE [LINK])</procedure>
400
401Returns a 13-element vector with the following contents:
402
403<table>
404<tr><th>index</th>
405    <th>value</th>
406    <th>field</th>
407    <th>notes</th></tr>
408<tr><td>0</td>
409    <td>inode number</td>
410    <td>{{st_ino}}</td>
411    <td></td></tr>
412<tr><td>1</td>
413    <td>mode</td>
414    <td>{{st_mode}}</td>
415    <td>bitfield combining file permissions and file type</td></tr>
416<tr><td>2</td>
417    <td>number of hard links</td>
418    <td>{{st_nlink}}</td>
419    <td></td></tr>
420<tr><td>3</td>
421    <td>UID of owner</td>
422    <td>{{st_uid}}</td>
423    <td>as with {{file-owner}}</td></tr>
424<tr><td>4</td>
425    <td>GID of owner</td>
426    <td>{{st_gid}}</td>
427    <td></td></tr>
428<tr><td>5</td>
429    <td>size</td>
430    <td>{{st_size}}</td>
431    <td>as with {{file-size}}</td></tr>
432<tr><td>6</td>
433    <td>access time</td>
434    <td>{{st_atime}}</td>
435    <td>as with {{file-access-time}}</td></tr>
436<tr><td>7</td>
437    <td>change time</td>
438    <td>{{st_ctime}}</td>
439    <td>as with {{file-change-time}}</td></tr>
440<tr><td>8</td>
441    <td>modification time</td>
442    <td>{{st_mtime}}</td>
443    <td>as with {{file-modification-time}}</td></tr>
444<tr><td>9</td>
445    <td>parent device ID </td>
446    <td>{{st_dev}}</td>
447    <td>ID of device on which this file resides</td></tr>
448<tr><td>10</td>
449    <td>device ID</td>
450    <td>{{st_rdev}}</td>
451    <td>device ID for special files (i.e. the raw major/minor number)</td></tr>
452<tr><td>11</td>
453    <td>block size</td>
454    <td>{{st_blksize}}</td>
455    <td></td></tr>
456<tr><td>12</td>
457    <td>number of blocks allocated</td>
458    <td>{{st_blocks}}</td>
459    <td></td></tr>
460</table>
461
462On Windows systems, the last 4 values are undefined.
463
464By default, symbolic links are followed and
465the status of the referenced file is returned;
466however, if the optional argument {{LINK}} is given and
467not {{#f}}, the status of the link itself is returned.
468
469Note that for very large files, the {{file-size}} value may be an
470inexact integer.
471
472==== file-position
473
474<procedure>(file-position FILE)</procedure>
475
476Returns the current file position of {{FILE}}, which should be a
477port or a file-descriptor.
478
479==== file-size
480
481<procedure>(file-size FILE)</procedure>
482
483Returns the size of the file designated by {{FILE}}.  {{FILE}}
484may be a filename or a file-descriptor.  If the file does not exist,
485an error is signaled. Note that for very large files, {{file-size}} may
486return an inexact integer.
487
488==== regular-file?
489
490<procedure>(regular-file? FILENAME)</procedure>
491
492Returns true, if {{FILENAME}} names a regular file (not a directory, socket, etc.)  This operation follows symbolic links; use either {{symbolic-link?}} or {{file-type}} if you need to test for symlinks.
493
494==== file-owner
495
496<procedure>(file-owner FILE)</procedure>
497
498Returns the user-id of {{FILE}}.  {{FILE}} may be a filename
499or a file-descriptor.
500
501==== file-permissions
502
503<procedure>(file-permissions FILE)</procedure>
504
505Returns the permission bits for {{FILE}}. You can test this value
506by performing bitwise operations on the result and the {{perm/...}}
507values.  {{FILE}} may be a filename or a file-descriptor.
508
509==== file-read-access?
510==== file-write-access?
511==== file-execute-access?
512
513<procedure>(file-read-access? FILENAME)</procedure><br>
514<procedure>(file-write-access? FILENAME)</procedure><br>
515<procedure>(file-execute-access? FILENAME)</procedure>
516
517These procedures return {{#t}} if the current user has read,
518write or execute permissions on the file named {{FILENAME}}.
519
520
521==== file-type
522
523<procedure>(file-type FILE [LINK [ERROR]])</procedure>
524
525Returns the file-type for {{FILE}}, which should be a filename or
526file-descriptor. If {{LINK}} is given and true, symbolic-links are
527not followed:
528
529  regular-file
530  directory
531  fifo
532  socket
533  symbolic-link
534  character-device
535  block-device
536
537Note that not all types are supported on every platform.
538If {{ERROR}} is given and true, {{file-type}} signals an
539error if the file does not exist.
540
541
542==== character-device?
543==== block-device?
544==== socket?
545
546<procedure>(character-device? FILE)</procedure><br>
547<procedure>(block-device? FILE)</procedure><br>
548<procedure>(socket? FILE)</procedure>
549
550These procedures return {{#t}} if {{FILE}} given is of the
551appropriate type. {{FILE}} may be a filename or a file-descriptor.
552Note that these operations follow symbolic links. If the file does
553not exist, {{#f}} is returned.
554
555
556=== Changing file attributes
557
558==== file-truncate
559
560<procedure>(file-truncate FILE OFFSET)</procedure>
561
562Truncates the file {{FILE}} to the length {{OFFSET}},
563which should be an integer. If the file-size is smaller or equal to
564{{OFFSET}} then nothing is done.  {{FILE}} should be a filename
565or a file-descriptor.
566
567==== set-file-position!
568
569<procedure>(set-file-position! FILE POSITION [WHENCE])</procedure><br>
570<procedure>(set! (file-position FILE) POSITION)</procedure>
571
572Sets the current read/write position of {{FILE}} to
573{{POSITION}}, which should be an exact integer. {{FILE}}
574should be a port or a file-descriptor.  {{WHENCE}} specifies
575how the position is to interpreted and should be one of the values
576{{seek/set, seek/cur}} and {{seek/end}}. It defaults to
577{{seek/set}}.
578
579Exceptions: {{(exn bounds)}}, {{(exn i/o file)}}
580
581==== change-file-mode
582
583<procedure>(change-file-mode FILENAME MODE)</procedure>
584
585Changes the current file mode of the file named {{FILENAME}}
586to {{MODE}} using the {{chmod()}} system call.  The
587{{perm/...}} variables contain the various permission bits and can
588be combinded with the {{bitwise-ior}} procedure.
589
590==== change-file-owner
591
592<procedure>(change-file-owner FILENAME UID GID)</procedure>
593
594Changes the owner information of the file named {{FILENAME}} to
595the user- and group-ids {{UID}} and {{GID}} (which should be
596exact integers) using the {{chown()}} system call.
597
598
599==== file-creation-mode
600
601<procedure>(file-creation-mode MODE)</procedure>
602
603Returns the initial file permissions used for newly created files
604(as with {{umask(2)}}. You can set the mode by executing
605
606  (set! (file-creation-mode) MODE)
607
608or
609
610  (file-creation-mode MODE)
611
612where {{MODE}} is a bitwise combination of one or more of
613the {{perm/...}} flags.
614
615
616=== Processes
617
618==== current-process-id
619
620<procedure>(current-process-id)</procedure>
621
622Returns the process ID of the current process.
623
624==== parent-process-id
625
626<procedure>(parent-process-id)</procedure>
627
628Returns the process ID of the parent of the current process.
629
630==== process-group-id
631
632<procedure>(process-group-id PID)</procedure>
633
634Returns the process group ID of the process specified by {{PID}}.
635
636==== process-execute
637
638<procedure>(process-execute PATHNAME [ARGUMENT-LIST [ENVIRONMENT-LIST]])</procedure>
639
640Replaces the running process with a new process image from the program
641stored at {{PATHNAME}}, using the C library function {{execvp(3)}}.
642If the optional argument {{ARGUMENT-LIST}} is given, then it should
643contain a list of strings which are passed as arguments to the subprocess.
644If the optional argument {{ENVIRONMENT-LIST}} is supplied, then the library
645function {{execve(2)}} is used, and the environment passed in
646{{ENVIRONMENT-LIST}} (which should be of the form {{("<NAME>=<VALUE>" ...)}}
647is given to the invoked process. Note that {{execvp(3)}} respects the
648current setting of the {{PATH}} environment variable while {{execve(3)}} does not.
649
650This procedure never returns; it either replaces the process with a new one
651or it raises an exception in case something went wrong executing the program.
652
653==== process-fork
654
655<procedure>(process-fork [THUNK])</procedure>
656
657Creates a new child process with the UNIX system call
658{{fork()}}. Returns either the PID of the child process or 0. If
659{{THUNK}} is given, then the child process calls it as a procedure
660with no arguments and terminates.
661
662==== process-run
663
664<procedure>(process-run COMMANDLINE)</procedure><br>
665<procedure>(process-run COMMAND ARGUMENT-LIST)</procedure>
666
667Creates a new child process. The PID of the new process is returned.
668
669* The single parameter version passes the {{COMMANDLINE}} to the system shell, so usual
670argument expansion can take place.
671* The multiple parameter version directly invokes the {{COMMAND}} with the {{ARGUMENT-LIST}}.
672
673==== process-signal
674
675<procedure>(process-signal PID [SIGNAL])</procedure>
676
677Sends {{SIGNAL}} to the process with the id {{PID}} using the
678UNIX system call {{kill()}}. {{SIGNAL}} defaults to the value
679of the variable {{signal/term}}.
680
681==== process-wait
682
683<procedure>(process-wait [PID [NOHANG]])</procedure>
684
685Suspends the current process until the child process with
686the id {{PID}} has terminated using the UNIX system call
687{{waitpid()}}. If {{PID}} is not given, then this procedure
688waits for any child process. If {{NOHANG}} is given and not
689{{#f}} then the current process is not suspended.  This procedure
690returns three values:
691
692* {{PID}} or 0, if {{NOHANG}} is true and the child process has not terminated yet.
693* {{#t}} if the process exited normally or {{#f}} otherwise.
694* either the exit status, if the process terminated normally or the signal number that terminated/stopped the process.
695
696Note that suspending the current process implies that all threads
697are suspended as well.
698
699==== process
700
701<procedure>(process COMMANDLINE)</procedure><br>
702<procedure>(process COMMAND ARGUMENT-LIST [ENVIRONMENT-LIST])</procedure>
703
704Creates a subprocess and returns three values: an input port from
705which data written by the sub-process can be read, an output port from
706which any data written to will be received as input in the sub-process
707and the process-id of the started sub-process. Blocking reads and writes
708to or from the ports returned by {{process}} only block the current
709thread, not other threads executing concurrently.
710
711Standard error for the subprocess is linked up to the current
712process's standard error (see {{process*}} if you want to reify
713its standard error into a separate port).
714
715* The single parameter version passes the string {{COMMANDLINE}} to the host-system's shell that
716is invoked as a subprocess.
717* The multiple parameter version directly invokes the {{COMMAND}} as a subprocess. The {{ARGUMENT-LIST}}
718is directly passed, as is {{ENVIRONMENT-LIST}}.
719
720Not using the shell may be preferrable for security reasons.
721
722Once both the input- and output ports are closed, an implicit
723{{waitpid(3)}} is done to wait for the subprocess to finish or to reap
724a subprocess that has terminated. If the subprocess has not finished,
725waiting for it will necessarily block all executing threads.
726
727==== process*
728
729<procedure>(process* COMMANDLINE)</procedure><br>
730<procedure>(process* COMMAND ARGUMENT-LIST [ENVIRONMENT-LIST])</procedure>
731
732Like {{process}} but does not cause the subprocess to share standard
733error with the current process.  It returns 4 values: an input port
734from which data written by the sub-process can be read, an output port
735from which any data written to will be received as input in the
736sub-process, the process-id of the started sub-process, and an input
737port from which data written by the sub-process to {{stderr}} can be
738read.
739
740==== sleep
741
742<procedure>(sleep SECONDS)</procedure>
743
744Puts the process to sleep for {{SECONDS}}. Returns either 0 if
745the time has completely elapsed, or the number of remaining seconds,
746if a signal occurred.
747
748==== create-session
749
750<procedure>(create-session)</procedure>
751
752Creates a new session if the calling process is not a process group leader and returns
753the session ID.
754
755
756=== Hard and symbolic links
757
758==== symbolic-link?
759
760<procedure>(symbolic-link? FILENAME)</procedure>
761
762Returns true, if {{FILENAME}} names a symbolic link. If no such file exists, {{#f}}
763is returned.  This operation does not follow symbolic links itself.
764
765==== create-symbolic-link
766
767<procedure>(create-symbolic-link OLDNAME NEWNAME)</procedure>
768
769Creates a symbolic link with the filename {{NEWNAME}} that points
770to the file named {{OLDNAME}}.
771
772==== read-symbolic-link
773
774<procedure>(read-symbolic-link FILENAME [CANONICALIZE])</procedure>
775
776Returns the filename to which the symbolic link {{FILENAME}} points.
777If {{CANONICALIZE}} is given and true, then symbolic links are
778resolved repeatedly until the result is not a link.
779
780==== file-link
781
782<procedure>(file-link OLDNAME NEWNAME)</procedure>
783
784Creates a hard link from {{OLDNAME}} to {{NEWNAME}} (both strings).
785
786
787=== Retrieving user & group information
788
789==== current-user-id
790
791<procedure>(current-user-id)</procedure>
792 [setter] (set! (current-user-id) UID)
793
794Get or set the real user-id of the current process. The procedure corresponds to the getuid and setuid C functions.
795
796==== current-effective-user-id
797
798<procedure>(current-effective-user-id)</procedure>
799 [setter] (set! (current-effective-user-id) UID)
800
801Get or set the effective user-id of the current process.
802
803==== user-information
804
805<procedure>(user-information USER [AS-VECTOR])</procedure>
806
807If {{USER}} specifes a valid username (as a string) or user ID, then the user
808database is consulted and a list of 7 values are returned: the user-name, the
809encrypted password, the user ID, the group ID, a user-specific string, the home
810directory and the default shell. When {{AS-VECTOR}} is {{#t}} a vector of 7
811elements is returned instead of a list. If no user with this name or id then
812{{#f}} is returned.
813
814==== current-group-id
815
816<procedure>(current-group-id)</procedure>
817 [setter] (set! (current-group-id) GID)
818
819Get or set the real group-id of the current process.
820
821==== current-effective-group-id
822
823<procedure>(current-effective-group-id)</procedure>
824 [setter] (set! (current-effective-group-id) GID)
825
826Get or set the effective group-id of the current process.
827ID can be found, then {{#f}} is returned.
828
829==== group-information
830
831<procedure>(group-information GROUP)</procedure>
832
833If {{GROUP}} specifies a valid group-name or group-id, then this
834procedure returns a list of four values: the group-name, the encrypted group password,
835the group ID and a list of the names of all group members. If no group with the
836given name or ID exists, then {{#f}} is returned.
837
838==== get-groups
839
840<procedure>(get-groups)</procedure>
841
842Returns a list with the supplementary group IDs of the current user.
843
844
845=== Changing user & group information
846
847==== set-groups!
848
849<procedure>(set-groups! GIDLIST)</procedure>
850
851Sets the supplementrary group IDs of the current user to the IDs given in the list {{GIDLIST}}.
852
853Only the superuser may invoke this procedure.
854
855==== initialize-groups
856
857<procedure>(initialize-groups USERNAME BASEGID)</procedure>
858
859Sets the supplementrary group IDs of the current user to the IDs from the user with name {{USERNAME}}
860(a string), including {{BASEGID}}.
861
862Only the superuser may invoke this procedure.
863
864==== set-process-group-id!
865
866<procedure>(set-process-group-id! PID PGID)</procedure>
867 [setter] (set! (process-group-id PID) PGID)
868
869Sets the process group ID of the process specifed by {{PID}} to {{PGID}}.
870
871
872=== Record locking
873
874==== file-lock
875
876<procedure>(file-lock PORT [START [LEN]])</procedure>
877
878Locks the file associated with {{PORT}} for reading or
879writing (according to whether {{PORT}} is an input- or
880output-port). {{START}} specifies the starting position in the
881file to be locked and defaults to 0. {{LEN}} specifies the length
882of the portion to be locked and defaults to {{#t}}, which means
883the complete file. {{file-lock}} returns a ''lock''-object.
884
885==== file-lock/blocking
886
887<procedure>(file-lock/blocking PORT [START [LEN]])</procedure>
888
889Similar to {{file-lock}}, but if a lock is held on the file,
890the current process blocks (including all threads) until the lock is released.
891
892==== file-test-lock
893
894<procedure>(file-test-lock PORT [START [LEN]])</procedure>
895
896Tests whether the file associated with {{PORT}} is locked for reading
897or writing (according to whether {{PORT}} is an input- or output-port)
898and returns either {{#f}} or the process-id of the locking process.
899
900==== file-unlock
901
902<procedure>(file-unlock LOCK)</procedure>
903
904Unlocks the previously locked portion of a file given in {{LOCK}}.
905
906
907=== Signal handling
908
909==== set-alarm!
910
911<procedure>(set-alarm! SECONDS)</procedure>
912
913Sets an internal timer to raise the {{signal/alrm}}
914after {{SECONDS}} are elapsed.  You can use the
915{{set-signal-handler!}} procedure to write a handler for this signal.
916
917==== set-signal-handler!
918
919==== signal-handler
920
921<procedure>(signal-handler SIGNUM)</procedure>
922
923Returns the signal handler for the code {{SIGNUM}} or {{#f}}.
924
925<procedure>(set-signal-handler! SIGNUM PROC)</procedure>
926
927Establishes the procedure of one argument {{PROC}} as the handler
928for the signal with the code {{SIGNUM}}. {{PROC}} is called
929with the signal number as its sole argument. If the argument {{PROC}} is {{#f}}
930then any signal handler will be removed, and the corresponding signal set to {{SIG_IGN}}.
931
932Notes
933
934* it is unspecified in which thread of execution the signal handler will be invoked.
935
936* when signals arrive in quick succession (specifically, before the handler for a signal has been started), then signals will be queued (up to a certain limit); the order in which the queued signals will be handled is not specified
937
938* {{(set! (signal-handler SIG) PROC)}} can be used as an alternative to {{(set-signal-handler! SIG PROC)}}
939
940==== set-signal-mask!
941
942<procedure>(set-signal-mask! SIGLIST)</procedure>
943
944Sets the signal mask of the current process to block all signals given
945in the list {{SIGLIST}}.  Signals masked in that way will not be
946delivered to the current process.
947
948==== signal-mask
949
950<procedure>(signal-mask)</procedure>
951
952Returns the signal mask of the current process.
953
954==== signal-masked?
955
956<procedure>(signal-masked? SIGNUM)</procedure>
957
958Returns whether the signal for the code {{SIGNUM}} is currently masked.
959
960==== signal-mask!
961
962<procedure>(signal-mask! SIGNUM)</procedure>
963
964Masks (blocks) the signal for the code {{SIGNUM}}.
965
966==== signal-unmask!
967
968<procedure>(signal-unmask! SIGNUM)</procedure>
969
970Unmasks (unblocks) the signal for the code {{SIGNUM}}.
971
972==== Signal codes
973
974<constant>signal/term</constant><br>
975<constant>signal/kill</constant><br>
976<constant>signal/int</constant><br>
977<constant>signal/hup</constant><br>
978<constant>signal/fpe</constant><br>
979<constant>signal/ill</constant><br>
980<constant>signal/segv</constant><br>
981<constant>signal/abrt</constant><br>
982<constant>signal/trap</constant><br>
983<constant>signal/quit</constant><br>
984<constant>signal/alrm</constant><br>
985<constant>signal/vtalrm</constant><br>
986<constant>signal/prof</constant><br>
987<constant>signal/io</constant><br>
988<constant>signal/urg</constant><br>
989<constant>signal/chld</constant><br>
990<constant>signal/cont</constant><br>
991<constant>signal/stop</constant><br>
992<constant>signal/tstp</constant><br>
993<constant>signal/pipe</constant><br>
994<constant>signal/xcpu</constant><br>
995<constant>signal/xfsz</constant><br>
996<constant>signal/usr1</constant><br>
997<constant>signal/usr2</constant><br>
998<constant>signal/winch</constant>
999
1000These variables contain signal codes for use with {{process-signal}},  {{set-signal-handler!}},  {{signal-handler}},  {{signal-masked?}},  {{signal-mask!}},  or {{signal-unmask!}}.
1001
1002
1003=== Environment access
1004
1005==== get-environment-variables
1006
1007<procedure>(get-environment-variables)</procedure>
1008
1009Returns a association list of the environment variables and their
1010current values (see also [[http://srfi.schemers.org/srfi-98/|SRFI-98]]).
1011
1012==== setenv
1013
1014<procedure>(setenv VARIABLE VALUE)</procedure>
1015
1016Sets the environment variable named {{VARIABLE}} to
1017{{VALUE}}. Both arguments should be strings. If the variable is
1018not defined in the environment, a new definition is created.
1019
1020==== unsetenv
1021
1022<procedure>(unsetenv VARIABLE)</procedure>
1023
1024Removes the definition of the environment variable {{VARIABLE}} from
1025the environment of the current process. If the variable is not defined,
1026nothing happens.
1027
1028
1029=== Memory mapped I/O
1030
1031Memory mapped I/O takes the contents of a file descriptor and places them in memory.
1032 
1033==== memory-mapped-file?
1034
1035<procedure>(memory-mapped-file? X)</procedure>
1036
1037Returns {{#t}}, if {{X}} is an object representing a memory
1038mapped file, or {{#f}} otherwise.
1039
1040==== map-file-to-memory
1041
1042<procedure>(map-file-to-memory ADDRESS LEN PROTECTION FLAG FILENO [OFFSET])</procedure>
1043
1044Maps a section of a file to memory using the C function
1045{{mmap()}}.  {{ADDRESS}} should be a foreign pointer object
1046or {{#f}}; {{LEN}} specifies the size of the section to
1047be mapped; {{PROTECTION}} should be one or more of the flags
1048{{prot/read, prot/write, prot/exec}} or {{prot/none}}
1049'''bitwise-ior'''ed together; {{FLAG}} should be one or more of
1050the flags {{map/fixed, map/shared, map/private, map/anonymous}} or
1051{{map/file}}; {{FILENO}} should be the file-descriptor of the
1052mapped file. The optional argument {{OFFSET}} gives the offset of
1053the section of the file to be mapped and defaults to 0. This procedure
1054returns an object representing the mapped file section.  The procedure
1055{{move-memory!}} can be used to access the mapped memory.
1056
1057==== memory-mapped-file-pointer
1058
1059<procedure>(memory-mapped-file-pointer MMAP)</procedure>
1060
1061Returns a machine pointer to the start of the memory region to which
1062the file is mapped.
1063
1064==== unmap-file-from-memory
1065
1066<procedure>(unmap-file-from-memory MMAP [LEN])</procedure>
1067
1068Unmaps the section of a file mapped to memory using the C function
1069{{munmap()}}.  {{MMAP}} should be a mapped file as returned
1070by the procedure {{map-file-to-memory}}.  The optional argument
1071{{LEN}} specifies the length of the section to be unmapped and
1072defaults to the complete length given when the file was mapped.
1073
1074==== Memory Mapped I/O Example
1075
1076<enscript highlight=scheme>
1077;; example-mmap.scm
1078;;
1079;; basic example of memory mapped I/O
1080;;
1081;; This example does no error checking or cleanup, and serves
1082;; only to demonstrate how the mmap functions work together.
1083;;
1084(use posix)
1085(use lolevel)
1086
1087       ; open a file using the posix module, so we have the file descriptor.
1088(let* ((fd   (file-open "example-mmap.scm" (+ open/rdonly open/nonblock)))
1089       ; fstat(2) the file descriptor fd to determine its size
1090       (size (file-size fd))
1091       ; mmap(2) the file for reading.
1092       (mmap (map-file-to-memory #f
1093                                 size
1094                                 prot/read
1095                                 (+ map/file map/shared)
1096                                 fd))
1097       ; return a pointer object to the beginning of the memory map.
1098       (buf  (memory-mapped-file-pointer mmap))
1099       ; allocate a string the same size as the file.
1100       (str  (make-string size)))
1101  ; copy the mapped memory into a string
1102  (move-memory! buf str size)
1103  (display str)
1104  ; alternately, print the string byte-by-byte without copying.
1105  (let loop ((p buf)
1106             (i 0))
1107    (unless (= i size)
1108      (display (integer->char (pointer-s8-ref p)))
1109      (loop (pointer+ p 1) (+ i 1)))))
1110</enscript>
1111
1112
1113=== Date and time routines
1114
1115==== seconds->local-time
1116
1117<procedure>(seconds->local-time [SECONDS])</procedure>
1118
1119Breaks down the time value represented in {{SECONDS}} into a 10
1120element vector of the form {{#(seconds minutes hours mday month
1121year wday yday dstflag timezone)}}, in the following format:
1122
1123; seconds (0) : the number of seconds after the minute (0 - 59)
1124; minutes (1) : the number of minutes after the hour (0 - 59)
1125; hours (2) : the number of hours past midnight (0 - 23)
1126; mday (3) : the day of the month (1 - 31)
1127; month (4) : the number of months since january (0 - 11)
1128; year (5) : the number of years since 1900
1129; wday (6) : the number of days since Sunday (0 - 6)
1130; yday (7) : the number of days since January 1 (0 - 365)
1131; dstflag (8) : a flag that is true if Daylight Saving Time is in effect at the time described.
1132; timezone (9) : the difference between UTC and the latest local standard time, in seconds west of UTC.
1133
1134{{SECONDS}} defaults to
1135the value of {{(current-seconds)}}.
1136
1137==== local-time->seconds
1138
1139<procedure>(local-time->seconds VECTOR)</procedure>
1140
1141Converts the ten-element vector {{VECTOR}} representing the time value relative to
1142the current timezone into
1143the number of seconds since the first of January, 1970 UTC.
1144
1145==== local-timezone-abbreviation
1146
1147<procedure>(local-timezone-abbreviation)</procedure>
1148
1149Returns the abbreviation for the local timezone as a string.
1150
1151==== seconds->string
1152
1153<procedure>(seconds->string [SECONDS])</procedure>
1154
1155Converts the time represented in {{SECONDS}} into a local-time string
1156of the form {{"Tue May 21 13:46:22 1991"}}. {{SECONDS}} defaults to
1157the value of {{(current-seconds)}}.
1158
1159==== seconds->utc-time
1160
1161<procedure>(seconds->utc-time [SECONDS])</procedure>
1162
1163Similar to {{seconds->local-time}}, but interpretes {{SECONDS}}
1164as UTC time. {{SECONDS}} defaults to
1165the value of {{(current-seconds)}}.
1166
1167==== utc-time->seconds
1168
1169<procedure>(utc-time->seconds VECTOR)</procedure>
1170
1171Converts the ten-element vector {{VECTOR}} representing the UTC time value into
1172the number of seconds since the first of January, 1970 UTC.
1173
1174==== time->string
1175
1176<procedure>(time->string VECTOR [FORMAT])</procedure>
1177
1178Converts the broken down time represented in the 10 element vector
1179{{VECTOR}} into a string of the form represented by the {{FORMAT}}
1180string. The default time form produces something like {{"Tue May 21 13:46:22 1991"}}.
1181
1182The {{FORMAT}} string follows the rules for the C library procedure {{strftime}}. The default {{FORMAT}} string is "%a %b %e %H:%M:%S %Z %Y".
1183
1184==== string->time
1185
1186<procedure>(string->time TIME [FORMAT])</procedure>
1187
1188Converts a string of the form represented by the {{FORMAT}} string
1189into the broken down time represented in a 10 element vector. The
1190default time form understands something like {{"Tue May 21 13:46:22 1991"}}.
1191
1192The {{FORMAT}} string follows the rules for the C library procedure {{strptime}}. The default {{FORMAT}} string is "%a %b %e %H:%M:%S %Z %Y".
1193
1194
1195=== Raw exit
1196
1197==== _exit
1198
1199<procedure>(_exit [CODE])</procedure>
1200
1201Exits the current process without flushing any buffered output (using
1202the C function {{_exit}}).  Note that the {{exit-handler}}
1203is not called when this procedure is invoked. The optional return-code
1204{{CODE}} defaults to {{0}}.
1205
1206
1207=== ERRNO values
1208
1209<constant>errno/perm</constant><br>
1210<constant>errno/noent</constant><br>
1211<constant>errno/srch</constant><br>
1212<constant>errno/intr</constant><br>
1213<constant>errno/io</constant><br>
1214<constant>errno/noexec</constant><br>
1215<constant>errno/badf</constant><br>
1216<constant>errno/child</constant><br>
1217<constant>errno/nomem</constant><br>
1218<constant>errno/acces</constant><br>
1219<constant>errno/fault</constant><br>
1220<constant>errno/busy</constant><br>
1221<constant>errno/notdir</constant><br>
1222<constant>errno/isdir</constant><br>
1223<constant>errno/inval</constant><br>
1224<constant>errno/mfile</constant><br>
1225<constant>errno/nospc</constant><br>
1226<constant>errno/spipe</constant><br>
1227<constant>errno/pipe</constant><br>
1228<constant>errno/again</constant><br>
1229<constant>errno/rofs</constant><br>
1230<constant>errno/exist</constant><br>
1231<constant>errno/wouldblock</constant>
1232
1233These variables contain error codes as returned by {{errno}}.
1234
1235
1236=== Finding files
1237
1238==== find-files
1239
1240<procedure>(find-files DIRECTORY #!key test action seed limit dotfiles follow-symlinks)</procedure>
1241
1242Recursively traverses the contents of {{DIRECTORY}} (which should be a
1243string) and invokes the procedure {{action}} for all files in which
1244the procedure {{test}} is true.  {{test}} may be a procedure of one
1245argument or a regular-expression string that will be matched with a
1246full pathname using {{irregex-match}}.  {{action}} should be a
1247procedure of two arguments: the currently encountered file and the
1248result of the previous invocation of {{action}}, or, if this is the
1249first invocation, the value of {{seed}}. {{test}} defaults to
1250{{(constantly #t)}}, {{action}} defaults to {{cons}}, {{seed}}
1251defaults to {{()}}.  {{limit}} should be a procedure of one argument
1252that is called for each nested directory and which should return true,
1253if that directory is to be traversed recursively. {{limit}} may also
1254be an exact integer that gives the maximum recursion depth. For
1255example, a depth of {{0}} means that only files in the top-level,
1256specified directory are to be traversed. In this case, all nested
1257directories are ignored.  {{limit}} may also be {{#f}} (the default),
1258which is equivalent to {{(constantly #t)}}.
1259
1260If {{dotfiles}} is given and true, then files starting with a "{{.}}"
1261character will not be ignored (but note that "{{.}}" and "{{..}}"  are
1262always ignored). if {{follow-symlinks}} is given and true, then the
1263traversal of a symbolic link that points to a directory will
1264recursively traverse the latter. By default, symbolic links are not
1265followed.
1266
1267Note that {{action}} is called with the full pathname of each file,
1268including the directory prefix.
1269
1270This procedure's signature was changed in CHICKEN 4.6.   In older versions, {{find-files}}
1271has a different signature:
1272
1273  (find-files DIRECTORY [TEST [ACTION [SEED [LIMIT]]]])
1274
1275The old signature was supported until CHICKEN 4.7.3 for compatibility reasons,
1276at which point it became invalid.  The optional arguments are ignored
1277and use their default values, and no warning is issued.  One symptom is
1278that your {{TEST}} does not work, returning every file.
1279
1280=== Getting the hostname and system information
1281
1282==== get-host-name
1283
1284<procedure>(get-host-name)</procedure>
1285
1286Returns the hostname of the machine that this process is running on.
1287
1288==== system-information
1289
1290<procedure>(system-information)</procedure>
1291
1292Invokes the UNIX system call {{uname()}} and returns a list of 5 values:
1293system-name, node-name, OS release, OS version and machine.
1294
1295=== Setting the file buffering mode
1296
1297==== set-buffering-mode!
1298
1299<procedure>(set-buffering-mode! PORT MODE [BUFSIZE])</procedure>
1300
1301Sets the buffering-mode for the file associated with {{PORT}} to
1302{{MODE}}, which should be one of the keywords {{#:full}},
1303{{#:line}} or {{#:none}}. If {{BUFSIZE}} is specified it
1304determines the size of the buffer to be used (if any).
1305
1306
1307=== Terminal ports
1308
1309==== terminal-name
1310
1311<procedure>(terminal-name PORT)</procedure>
1312
1313Returns the name of the terminal that is connected to {{PORT}}.
1314
1315==== terminal-port?
1316
1317<procedure>(terminal-port? PORT)</procedure>
1318
1319Returns {{#t}} if {{PORT}} is connected to a terminal and
1320{{#f}} otherwise.
1321
1322
1323==== terminal-size
1324
1325<procedure>(terminal-size PORT)</procedure>
1326
1327Returns two values, the number of columns and rows of the terminal
1328that is connected to {{PORT}} or {{0}}, {{0}} if the terminal size can
1329not be obtained. On Windows, this procedure always returns {{0}},
1330{{0}}.
1331
1332
1333=== How Scheme procedures relate to UNIX C functions
1334
1335; {{change-directory}} : {{chdir}}
1336; {{change-directory*}} : {{fchdir}}
1337; {{change-file-mode}} : {{chmod}}
1338; {{change-file-owner}} : {{chown}}
1339; {{create-directory}} : {{mkdir}}
1340; {{create-fifo}} : {{mkfifo}}
1341; {{create-pipe}} : {{pipe}}
1342; {{create-session}} : {{setsid}}
1343; {{create-symbolic-link}} : {{link}}
1344; {{current-directory}} : {{curdir}}
1345; {{current-effective-groupd-id}} : {{getegid}}
1346; {{current-effective-user-id}} : {{geteuid}}
1347; {{current-group-id}} : {{getgid}}
1348; {{current-parent-id}} : {{getppid}}
1349; {{current-process-id}} : {{getpid}}
1350; {{current-user-id}} : {{getuid}}
1351; {{delete-directory}} : {{rmdir}}
1352; {{duplicate-fileno}} : {{dup/dup2}}
1353; {{_exit}} : {{_exit}}
1354; {{file-close}} : {{close}}
1355; {{file-access-time}} : {{stat}}
1356; {{file-change-time}} : {{stat}}
1357; {{file-creation-mode}} : {{umask}}
1358; {{file-modification-time}} : {{stat}}
1359; {{file-execute-access?}} : {{access}}
1360; {{file-open}} : {{open}}
1361; {{file-lock}} : {{fcntl}}
1362; {{file-position}} : {{ftell/lseek}}
1363; {{file-read}} : {{read}}
1364; {{file-read-access?}} : {{access}}
1365; {{file-select}} : {{select}}
1366; {{file-control}} : {{fcntl}}
1367; {{file-stat}} : {{stat}}
1368; {{file-test-lock}} : {{fcntl}}
1369; {{file-truncate}} : {{truncate/ftruncate}}
1370; {{file-unlock}} : {{fcntl}}
1371; {{file-write}} : {{write}}
1372; {{file-write-access?}} : {{access}}
1373; {{get-groups}} : {{getgroups}}
1374; {{get-host-name}} : {{gethostname}}
1375; {{initialize-groups}} : {{initgroups}}
1376; {{local-time->seconds}} : {{mktime}}
1377; {{local-timezone-abbreviation}} : {{localtime}}
1378; {{map-file-to-memory}} : {{mmap}}
1379; {{open-input-file*}} : {{fdopen}}
1380; {{open-output-file*}} : {{fdopen}}
1381; {{open-input-pipe}} : {{popen}}
1382; {{open-output-pipe}} : {{popen}}
1383; {{port->fileno}} : {{fileno}}
1384; {{process-execute}} : {{execvp}}
1385; {{process-fork}} : {{fork}}
1386; {{process-group-id}} : {{getpgid}}
1387; {{process-signal}} : {{kill}}
1388; {{process-wait}} : {{waitpid}}
1389; {{close-input-pipe}} : {{pclose}}
1390; {{close-output-pipe}} : {{pclose}}
1391; {{read-symbolic-link}} : {{readlink}}
1392; {{seconds->local-time}} : {{localtime}}
1393; {{seconds->string}} : {{ctime}}
1394; {{seconds->utc-time}} : {{gmtime}}
1395; {{set-alarm!}} : {{alarm}}
1396; {{set-buffering-mode!}} : {{setvbuf}}
1397; {{set-file-position!}} : {{fseek/seek}}
1398; {{set-groups!}} : {{setgroups}}
1399; {{set-signal-mask!}} : {{sigprocmask}}
1400; {{set-group-id!}} : {{setgid}}
1401; {{set-process-group-id!}} : {{setpgid}}
1402; {{set-user-id!}} : {{setuid}}
1403; {{set-root-directory!}} : {{chroot}}
1404; {{setenv}} : {{setenv/putenv}}
1405; {{sleep}} : {{sleep}}
1406; {{system-information}} : {{uname}}
1407; {{terminal-name}} : {{ttyname}}
1408; {{terminal-port?}} : {{isatty}}
1409; {{time->string}} : {{asctime}}
1410; {{unsetenv}} : {{putenv}}
1411; {{unmap-file-from-memory}} : {{munmap}}
1412; {{user-information}} : {{getpwnam/getpwuid}}
1413; {{utc-time->seconds}} : {{timegm}}
1414
1415
1416=== Windows specific notes
1417
1418Use of UTF8 encoded strings is for pathnames is not supported. Windows uses a
141916-bit UNICODE encoding with special system calls for wide-character support.
1420Only single-byte string encoding can be used.
1421
1422==== Procedure Changes
1423
1424Exceptions to the above procedure definitions.
1425
1426<procedure>(create-pipe [MODE])</procedure>
1427
1428The optional parameter {{MODE}}, default {{open/binary | open/noinherit}}. This can be {{open/binary}} or
1429{{open/text}}, optionally or'ed with {{open/noinherit}}.
1430
1431<procedure>(process-wait [PID [NOHANG]])</procedure>
1432
1433{{process-wait}} always returns {{#t}} for a terminated process and only the exit
1434status is available. (Windows does not provide signals as an interprocess
1435communication method.)
1436
1437<procedure>(process-execute PATHNAME [ARGUMENT-LIST [ENVIRONMENT-LIST [EXACT-FLAG]]])</procedure><br>
1438<procedure>(process COMMAND ARGUMENT-LIST [ENVIRONMENT-LIST [EXACT-FLAG]])</procedure><br>
1439<procedure>(process* COMMAND ARGUMENT-LIST [ENVIRONMENT-LIST [EXACT-FLAG]])</procedure><br>
1440
1441The optional parameter {{EXACT-FLAG}}, default {{#f}}. When {{#f}} any argument string with
1442embedded whitespace will be wrapped in quotes. When {{#t}} no such wrapping occurs.
1443
1444==== Unsupported Definitions
1445
1446The following definitions are not supported for native Windows builds (compiled with the
1447Microsoft tools or with MinGW):
1448
1449 open/noctty  open/nonblock  open/fsync  open/sync
1450 perm/isvtx  perm/isuid  perm/isgid
1451 file-select file-control
1452 signal/... (except signal/term, signal/int, signal/fpe, signal/ill, signal/segv, signal/abrt, signal/break)
1453 set-signal-mask!  signal-mask  signal-masked?  signal-mask!  signal-unmask!
1454 user-information  group-information  get-groups  set-groups!  initialize-groups
1455 errno/wouldblock
1456 change-directory*
1457 change-file-owner
1458 current-user-id  current-group-id  current-effective-user-id  current-effective-groupd-id
1459 set-user-id!  set-group-id!
1460 create-session
1461 process-group-id  set-process-group-id!
1462 create-symbolic-link  read-symbolic-link
1463 file-truncate
1464 file-lock  file-lock/blocking  file-unlock  file-test-lock
1465 create-fifo  fifo?
1466 prot/...
1467 map/...
1468 map-file-to-memory  unmap-file-from-memory  memory-mapped-file-pointer  memory-mapped-file?
1469 set-alarm!
1470 terminal-port?  terminal-name
1471 process-fork  process-signal
1472 parent-process-id
1473 set-root-directory!
1474 utc-time->seconds
1475
1476==== Additional Definitions
1477
1478Only available for Windows
1479
1480* open/noinherit
1481
1482This variable is a mode value for {{create-pipe}}. Useful when spawning a child process.
1483
1484* spawn/overlay
1485* spawn/wait
1486* spawn/nowait
1487* spawn/nowaito
1488* spawn/detach
1489
1490These variables contains special flags that specify the exact semantics of {{process-spawn}}:
1491{{spawn/overlay}} replaces the current process with the new one.
1492{{spawn/wait}} suspends execution of the current process until the spawned process returns.
1493{{spawn/nowait}} does the opposite ({{spawn/nowaito}} is identical, according to the Microsoft
1494documentation) and runs the process asynchronously.
1495{{spawn/detach}} runs the new process in the background, without being attached to a console.
1496
1497==== process-spawn
1498
1499<procedure>(process-spawn MODE COMMAND [ARGUMENT-LIST [ENVIRONMENT-LIST [EXACT-FLAG]]])</procedure>
1500
1501Creates and runs a new process with the given {{COMMAND}} filename and the optional
1502{{ARGUMENT-LIST}} and {{ENVIRONMENT-LIST}}. {{MODE}} specifies how exactly the process
1503should be executed and must be one or more of the {{spawn/...}} flags defined above.
1504
1505The {{EXACT-FLAG}}, default {{#f}}, controls quote-wrapping of argument strings. When {{#t}}
1506quote-wrapping is not performed.
1507
1508Returns:
1509* the exit status when synchronous
1510* the PID when asynchronous
1511* -1 when failure
1512
1513----
1514Previous: [[Unit srfi-69]]
1515
1516Next: [[Unit utils]]
Note: See TracBrowser for help on using the repository browser.