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

Last change on this file since 30951 was 30951, checked in by sjamaan, 6 years ago

Update the online User's Manual for CHICKEN 4.9.0

File size: 49.6 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)}}).  If {{MODE}} is supplied, the mode is
605changed to this value.  You can set the mode by executing
606
607  (set! (file-creation-mode) MODE)
608
609or
610
611  (file-creation-mode MODE)
612
613where {{MODE}} is a bitwise combination of one or more of
614the {{perm/...}} flags.
615
616
617=== Processes
618
619==== current-process-id
620
621<procedure>(current-process-id)</procedure>
622
623Returns the process ID of the current process.
624
625==== parent-process-id
626
627<procedure>(parent-process-id)</procedure>
628
629Returns the process ID of the parent of the current process.
630
631==== process-group-id
632
633<procedure>(process-group-id PID)</procedure>
634
635Returns the process group ID of the process specified by {{PID}}.
636
637==== process-execute
638
639<procedure>(process-execute PATHNAME [ARGUMENT-LIST [ENVIRONMENT-LIST]])</procedure>
640
641Replaces the running process with a new process image from the program
642stored at {{PATHNAME}}, using the C library function {{execvp(3)}}.
643If the optional argument {{ARGUMENT-LIST}} is given, then it should
644contain a list of strings which are passed as arguments to the subprocess.
645If the optional argument {{ENVIRONMENT-LIST}} is supplied, then the library
646function {{execve(2)}} is used, and the environment passed in
647{{ENVIRONMENT-LIST}} (which should be of the form {{("<NAME>=<VALUE>" ...)}}
648is given to the invoked process. Note that {{execvp(3)}} respects the
649current setting of the {{PATH}} environment variable while {{execve(3)}} does not.
650 
651This procedure never returns; it either replaces the process with a new one
652or it raises an exception in case something went wrong executing the program.
653
654==== process-fork
655
656<procedure>(process-fork [THUNK [KILLOTHERS?]])</procedure>
657
658Creates a new child process with the UNIX system call
659{{fork()}}. Returns either the PID of the child process or 0. If
660{{THUNK}} is given, then the child process calls it as a procedure
661with no arguments and terminates. If {{THUNK}} is given and the
662optional argument {{KILLOTHERS?}} is true, then kill all other
663existing threads in the child process, leaving only the current thread
664to run {{THUNK}} and terminate.
665
666==== process-run
667
668<procedure>(process-run COMMANDLINE)</procedure><br>
669<procedure>(process-run COMMAND ARGUMENT-LIST)</procedure>
670
671Creates a new child process. The PID of the new process is returned.
672
673* The single parameter version passes the {{COMMANDLINE}} to the system shell, so usual
674argument expansion can take place.
675* The multiple parameter version directly invokes the {{COMMAND}} with the {{ARGUMENT-LIST}}.
676
677==== process-signal
678
679<procedure>(process-signal PID [SIGNAL])</procedure>
680
681Sends {{SIGNAL}} to the process with the id {{PID}} using the
682UNIX system call {{kill()}}. {{SIGNAL}} defaults to the value
683of the variable {{signal/term}}.
684
685==== process-wait
686
687<procedure>(process-wait [PID [NOHANG]])</procedure>
688
689Suspends the current process until the child process with
690the id {{PID}} has terminated using the UNIX system call
691{{waitpid()}}. If {{PID}} is not given, then this procedure
692waits for any child process. If {{NOHANG}} is given and not
693{{#f}} then the current process is not suspended.  This procedure
694returns three values:
695
696* {{PID}} or 0, if {{NOHANG}} is true and the child process has not terminated yet.
697* {{#t}} if the process exited normally or {{#f}} otherwise.
698* either the exit status, if the process terminated normally or the signal number that terminated/stopped the process.
699
700Note that suspending the current process implies that all threads
701are suspended as well.
702
703==== process
704
705<procedure>(process COMMANDLINE)</procedure><br>
706<procedure>(process COMMAND ARGUMENT-LIST [ENVIRONMENT-LIST])</procedure>
707
708Creates a subprocess and returns three values: an input port from
709which data written by the sub-process can be read, an output port from
710which any data written to will be received as input in the sub-process
711and the process-id of the started sub-process. Blocking reads and writes
712to or from the ports returned by {{process}} only block the current
713thread, not other threads executing concurrently.
714
715Standard error for the subprocess is linked up to the current
716process's standard error (see {{process*}} if you want to reify
717its standard error into a separate port).
718
719* The single parameter version passes the string {{COMMANDLINE}} to the host-system's shell that
720is invoked as a subprocess.
721* The multiple parameter version directly invokes the {{COMMAND}} as a subprocess. The {{ARGUMENT-LIST}}
722is directly passed, as is {{ENVIRONMENT-LIST}}.
723
724Not using the shell may be preferrable for security reasons.
725
726Once both the input- and output ports are closed, an implicit
727{{waitpid(3)}} is done to wait for the subprocess to finish or to reap
728a subprocess that has terminated. If the subprocess has not finished,
729waiting for it will necessarily block all executing threads.
730
731==== process*
732
733<procedure>(process* COMMANDLINE)</procedure><br>
734<procedure>(process* COMMAND ARGUMENT-LIST [ENVIRONMENT-LIST])</procedure>
735
736Like {{process}} but returns 4 values: an input port from
737which data written by the sub-process can be read, an output port from
738which any data written to will be received as input in the sub-process,
739the process-id of the started sub-process, and an input port from
740which data written by the sub-process to {{stderr}} can be read.
741
742==== sleep
743
744<procedure>(sleep SECONDS)</procedure>
745
746Puts the process to sleep for {{SECONDS}}. Returns either 0 if
747the time has completely elapsed, or the number of remaining seconds,
748if a signal occurred.
749
750==== create-session
751
752<procedure>(create-session)</procedure>
753
754Creates a new session if the calling process is not a process group leader and returns
755the session ID.
756
757
758=== Hard and symbolic links
759
760==== symbolic-link?
761
762<procedure>(symbolic-link? FILENAME)</procedure>
763
764Returns true, if {{FILENAME}} names a symbolic link. If no such file exists, {{#f}}
765is returned.  This operation does not follow symbolic links itself.
766
767==== create-symbolic-link
768
769<procedure>(create-symbolic-link OLDNAME NEWNAME)</procedure>
770
771Creates a symbolic link with the filename {{NEWNAME}} that points
772to the file named {{OLDNAME}}.
773
774==== read-symbolic-link
775
776<procedure>(read-symbolic-link FILENAME [CANONICALIZE])</procedure>
777
778Returns the filename to which the symbolic link {{FILENAME}} points.
779If {{CANONICALIZE}} is given and true, then symbolic links are
780resolved repeatedly until the result is not a link.
781
782==== file-link
783
784<procedure>(file-link OLDNAME NEWNAME)</procedure>
785
786Creates a hard link from {{OLDNAME}} to {{NEWNAME}} (both strings).
787
788
789=== Retrieving user & group information
790
791==== current-user-id
792
793<procedure>(current-user-id)</procedure>
794 [setter] (set! (current-user-id) UID)
795
796Get or set the real user-id of the current process. The procedure corresponds to the getuid and setuid C functions.
797
798==== current-effective-user-id
799
800<procedure>(current-effective-user-id)</procedure>
801 [setter] (set! (current-effective-user-id) UID)
802
803Get or set the effective user-id of the current process.
804
805==== user-information
806
807<procedure>(user-information USER [AS-VECTOR])</procedure>
808
809If {{USER}} specifes a valid username (as a string) or user ID, then the user
810database is consulted and a list of 7 values are returned: the user-name, the
811encrypted password, the user ID, the group ID, a user-specific string, the home
812directory and the default shell. When {{AS-VECTOR}} is {{#t}} a vector of 7
813elements is returned instead of a list. If no user with this name or id then
814{{#f}} is returned.
815
816Note: on Android systems, the user-specific string is always {{""}},
817since {{pw_gecos}} is not available in the C {{passwd}} struct on that
818platform.
819
820==== current-group-id
821
822<procedure>(current-group-id)</procedure>
823 [setter] (set! (current-group-id) GID)
824
825Get or set the real group-id of the current process.
826
827==== current-effective-group-id
828
829<procedure>(current-effective-group-id)</procedure>
830 [setter] (set! (current-effective-group-id) GID)
831
832Get or set the effective group-id of the current process.
833ID can be found, then {{#f}} is returned.
834
835==== group-information
836
837<procedure>(group-information GROUP)</procedure>
838
839If {{GROUP}} specifies a valid group-name or group-id, then this
840procedure returns a list of four values: the group-name, the encrypted group password,
841the group ID and a list of the names of all group members. If no group with the
842given name or ID exists, then {{#f}} is returned.
843
844==== get-groups
845
846<procedure>(get-groups)</procedure>
847
848Returns a list with the supplementary group IDs of the current user.
849
850
851=== Changing user & group information
852
853==== set-groups!
854
855<procedure>(set-groups! GIDLIST)</procedure>
856
857Sets the supplementrary group IDs of the current user to the IDs given in the list {{GIDLIST}}.
858
859Only the superuser may invoke this procedure.
860
861==== initialize-groups
862
863<procedure>(initialize-groups USERNAME BASEGID)</procedure>
864
865Sets the supplementrary group IDs of the current user to the IDs from the user with name {{USERNAME}}
866(a string), including {{BASEGID}}.
867
868Only the superuser may invoke this procedure.
869
870==== set-process-group-id!
871
872<procedure>(set-process-group-id! PID PGID)</procedure>
873 [setter] (set! (process-group-id PID) PGID)
874
875Sets the process group ID of the process specifed by {{PID}} to {{PGID}}.
876
877
878=== Record locking
879
880==== file-lock
881
882<procedure>(file-lock PORT [START [LEN]])</procedure>
883
884Locks the file associated with {{PORT}} for reading or
885writing (according to whether {{PORT}} is an input- or
886output-port). {{START}} specifies the starting position in the
887file to be locked and defaults to 0. {{LEN}} specifies the length
888of the portion to be locked and defaults to {{#t}}, which means
889the complete file. {{file-lock}} returns a ''lock''-object.
890
891==== file-lock/blocking
892
893<procedure>(file-lock/blocking PORT [START [LEN]])</procedure>
894
895Similar to {{file-lock}}, but if a lock is held on the file,
896the current process blocks (including all threads) until the lock is released.
897
898==== file-test-lock
899
900<procedure>(file-test-lock PORT [START [LEN]])</procedure>
901
902Tests whether the file associated with {{PORT}} is locked for reading
903or writing (according to whether {{PORT}} is an input- or output-port)
904and returns either {{#f}} or the process-id of the locking process.
905
906==== file-unlock
907
908<procedure>(file-unlock LOCK)</procedure>
909
910Unlocks the previously locked portion of a file given in {{LOCK}}.
911
912
913=== Signal handling
914
915==== set-alarm!
916
917<procedure>(set-alarm! SECONDS)</procedure>
918
919Sets an internal timer to raise the {{signal/alrm}}
920after {{SECONDS}} are elapsed.  You can use the
921{{set-signal-handler!}} procedure to write a handler for this signal.
922
923==== set-signal-handler!
924
925==== signal-handler
926
927<procedure>(signal-handler SIGNUM)</procedure>
928
929Returns the signal handler for the code {{SIGNUM}} or {{#f}}.
930
931<procedure>(set-signal-handler! SIGNUM PROC)</procedure>
932
933Establishes the procedure of one argument {{PROC}} as the handler
934for the signal with the code {{SIGNUM}}. {{PROC}} is called
935with the signal number as its sole argument. If the argument {{PROC}} is {{#f}}
936then any signal handler will be removed, and the corresponding signal set to {{SIG_IGN}}.
937
938Notes
939
940* it is unspecified in which thread of execution the signal handler will be invoked.
941
942* 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
943
944* {{(set! (signal-handler SIG) PROC)}} can be used as an alternative to {{(set-signal-handler! SIG PROC)}}
945
946* Any signal handlers for the signals {{signal/segv}}, {{signal/bus}}, {{signal/fpe}} and {{signal/ill}} will be ignored and these signals will always trigger an exception, unless the executable was started with the {{-:S}} runtime option. This feature is only available on platforms that support the {{sigprocmask(3)}} POSIX API function.
947
948==== set-signal-mask!
949
950<procedure>(set-signal-mask! SIGLIST)</procedure>
951
952Sets the signal mask of the current process to block all signals given
953in the list {{SIGLIST}}.  Signals masked in that way will not be
954delivered to the current process.
955
956==== signal-mask
957
958<procedure>(signal-mask)</procedure>
959
960Returns the signal mask of the current process.
961
962==== signal-masked?
963
964<procedure>(signal-masked? SIGNUM)</procedure>
965
966Returns whether the signal for the code {{SIGNUM}} is currently masked.
967
968==== signal-mask!
969
970<procedure>(signal-mask! SIGNUM)</procedure>
971
972Masks (blocks) the signal for the code {{SIGNUM}}.
973
974==== signal-unmask!
975
976<procedure>(signal-unmask! SIGNUM)</procedure>
977
978Unmasks (unblocks) the signal for the code {{SIGNUM}}.
979
980==== Signal codes
981
982<constant>signal/term</constant><br>
983<constant>signal/kill</constant><br>
984<constant>signal/int</constant><br>
985<constant>signal/hup</constant><br>
986<constant>signal/fpe</constant><br>
987<constant>signal/ill</constant><br>
988<constant>signal/segv</constant><br>
989<constant>signal/abrt</constant><br>
990<constant>signal/trap</constant><br>
991<constant>signal/quit</constant><br>
992<constant>signal/alrm</constant><br>
993<constant>signal/vtalrm</constant><br>
994<constant>signal/prof</constant><br>
995<constant>signal/io</constant><br>
996<constant>signal/urg</constant><br>
997<constant>signal/chld</constant><br>
998<constant>signal/cont</constant><br>
999<constant>signal/stop</constant><br>
1000<constant>signal/tstp</constant><br>
1001<constant>signal/pipe</constant><br>
1002<constant>signal/xcpu</constant><br>
1003<constant>signal/xfsz</constant><br>
1004<constant>signal/usr1</constant><br>
1005<constant>signal/usr2</constant><br>
1006<constant>signal/bus</constant><br>
1007<constant>signal/winch</constant>
1008<constant>signal/break</constant>
1009
1010These variables contain signal codes for use with {{process-signal}},  {{set-signal-handler!}},  {{signal-handler}},  {{signal-masked?}},  {{signal-mask!}},  or {{signal-unmask!}}.
1011
1012
1013=== Environment access
1014
1015==== get-environment-variables
1016
1017<procedure>(get-environment-variables)</procedure>
1018
1019Returns a association list of the environment variables and their
1020current values (see also [[http://srfi.schemers.org/srfi-98/|SRFI-98]]).
1021
1022==== setenv
1023
1024<procedure>(setenv VARIABLE VALUE)</procedure>
1025
1026Sets the environment variable named {{VARIABLE}} to
1027{{VALUE}}. Both arguments should be strings. If the variable is
1028not defined in the environment, a new definition is created.
1029
1030==== unsetenv
1031
1032<procedure>(unsetenv VARIABLE)</procedure>
1033
1034Removes the definition of the environment variable {{VARIABLE}} from
1035the environment of the current process. If the variable is not defined,
1036nothing happens.
1037
1038
1039=== Memory mapped I/O
1040
1041Memory mapped I/O takes the contents of a file descriptor and places them in memory.
1042 
1043==== memory-mapped-file?
1044
1045<procedure>(memory-mapped-file? X)</procedure>
1046
1047Returns {{#t}}, if {{X}} is an object representing a memory
1048mapped file, or {{#f}} otherwise.
1049
1050==== map-file-to-memory
1051
1052<procedure>(map-file-to-memory ADDRESS LEN PROTECTION FLAG FILENO [OFFSET])</procedure>
1053
1054Maps a section of a file to memory using the C function
1055{{mmap()}}.  {{ADDRESS}} should be a foreign pointer object
1056or {{#f}}; {{LEN}} specifies the size of the section to
1057be mapped; {{PROTECTION}} should be one or more of the flags
1058{{prot/read, prot/write, prot/exec}} or {{prot/none}}
1059'''bitwise-ior'''ed together; {{FLAG}} should be one or more of
1060the flags {{map/fixed, map/shared, map/private, map/anonymous}} or
1061{{map/file}}; {{FILENO}} should be the file-descriptor of the
1062mapped file. The optional argument {{OFFSET}} gives the offset of
1063the section of the file to be mapped and defaults to 0. This procedure
1064returns an object representing the mapped file section.  The procedure
1065{{move-memory!}} can be used to access the mapped memory.
1066
1067==== memory-mapped-file-pointer
1068
1069<procedure>(memory-mapped-file-pointer MMAP)</procedure>
1070
1071Returns a machine pointer to the start of the memory region to which
1072the file is mapped.
1073
1074==== unmap-file-from-memory
1075
1076<procedure>(unmap-file-from-memory MMAP [LEN])</procedure>
1077
1078Unmaps the section of a file mapped to memory using the C function
1079{{munmap()}}.  {{MMAP}} should be a mapped file as returned
1080by the procedure {{map-file-to-memory}}.  The optional argument
1081{{LEN}} specifies the length of the section to be unmapped and
1082defaults to the complete length given when the file was mapped.
1083
1084==== Memory Mapped I/O Example
1085
1086<enscript highlight=scheme>
1087;; example-mmap.scm
1088;;
1089;; basic example of memory mapped I/O
1090;;
1091;; This example does no error checking or cleanup, and serves
1092;; only to demonstrate how the mmap functions work together.
1093;;
1094(use posix)
1095(use lolevel)
1096
1097       ; open a file using the posix module, so we have the file descriptor.
1098(let* ((fd   (file-open "example-mmap.scm" (+ open/rdonly open/nonblock)))
1099       ; fstat(2) the file descriptor fd to determine its size
1100       (size (file-size fd))
1101       ; mmap(2) the file for reading.
1102       (mmap (map-file-to-memory #f
1103                                 size
1104                                 prot/read
1105                                 (+ map/file map/shared)
1106                                 fd))
1107       ; return a pointer object to the beginning of the memory map.
1108       (buf  (memory-mapped-file-pointer mmap))
1109       ; allocate a string the same size as the file.
1110       (str  (make-string size)))
1111  ; copy the mapped memory into a string
1112  (move-memory! buf str size)
1113  (display str)
1114  ; alternately, print the string byte-by-byte without copying.
1115  (let loop ((p buf)
1116             (i 0))
1117    (unless (= i size)
1118      (display (integer->char (pointer-s8-ref p)))
1119      (loop (pointer+ p 1) (+ i 1)))))
1120</enscript>
1121
1122
1123=== Date and time routines
1124
1125==== seconds->local-time
1126
1127<procedure>(seconds->local-time [SECONDS])</procedure>
1128
1129Breaks down the time value represented in {{SECONDS}} into a 10
1130element vector of the form {{#(seconds minutes hours mday month
1131year wday yday dstflag timezone)}}, in the following format:
1132
1133; seconds (0) : the number of seconds after the minute (0 - 59)
1134; minutes (1) : the number of minutes after the hour (0 - 59)
1135; hours (2) : the number of hours past midnight (0 - 23)
1136; mday (3) : the day of the month (1 - 31)
1137; month (4) : the number of months since january (0 - 11)
1138; year (5) : the number of years since 1900
1139; wday (6) : the number of days since Sunday (0 - 6)
1140; yday (7) : the number of days since January 1 (0 - 365)
1141; dstflag (8) : a flag that is true if Daylight Saving Time is in effect at the time described.
1142; timezone (9) : the difference between UTC and the latest local standard time, in seconds west of UTC.
1143
1144{{SECONDS}} defaults to
1145the value of {{(current-seconds)}}.
1146
1147==== local-time->seconds
1148
1149<procedure>(local-time->seconds VECTOR)</procedure>
1150
1151Converts the ten-element vector {{VECTOR}} representing the time value relative to
1152the current timezone into
1153the number of seconds since the first of January, 1970 UTC.
1154
1155==== local-timezone-abbreviation
1156
1157<procedure>(local-timezone-abbreviation)</procedure>
1158
1159Returns the abbreviation for the local timezone as a string.
1160
1161==== seconds->string
1162
1163<procedure>(seconds->string [SECONDS])</procedure>
1164
1165Converts the time represented in {{SECONDS}} into a local-time string
1166of the form {{"Tue May 21 13:46:22 1991"}}. {{SECONDS}} defaults to
1167the value of {{(current-seconds)}}.
1168
1169==== seconds->utc-time
1170
1171<procedure>(seconds->utc-time [SECONDS])</procedure>
1172
1173Similar to {{seconds->local-time}}, but interpretes {{SECONDS}}
1174as UTC time. {{SECONDS}} defaults to
1175the value of {{(current-seconds)}}.
1176
1177==== utc-time->seconds
1178
1179<procedure>(utc-time->seconds VECTOR)</procedure>
1180
1181Converts the ten-element vector {{VECTOR}} representing the UTC time value into
1182the number of seconds since the first of January, 1970 UTC.
1183
1184==== time->string
1185
1186<procedure>(time->string VECTOR [FORMAT])</procedure>
1187
1188Converts the broken down time represented in the 10 element vector
1189{{VECTOR}} into a string of the form represented by the {{FORMAT}}
1190string. The default time form produces something like {{"Tue May 21 13:46:22 1991"}}.
1191
1192The {{FORMAT}} string follows the rules for the C library procedure {{strftime}}. The default {{FORMAT}} string is "%a %b %e %H:%M:%S %Z %Y".
1193
1194==== string->time
1195
1196<procedure>(string->time TIME [FORMAT])</procedure>
1197
1198Converts a string of the form represented by the {{FORMAT}} string
1199into the broken down time represented in a 10 element vector. The
1200default time form understands something like {{"Tue May 21 13:46:22 1991"}}.
1201
1202The {{FORMAT}} string follows the rules for the C library procedure {{strptime}}. The default {{FORMAT}} string is "%a %b %e %H:%M:%S %Z %Y".
1203
1204
1205=== Raw exit
1206
1207==== _exit
1208
1209<procedure>(_exit [CODE])</procedure>
1210
1211Exits the current process without flushing any buffered output (using
1212the C function {{_exit}}).  Note that the {{exit-handler}}
1213is not called when this procedure is invoked. The optional return-code
1214{{CODE}} defaults to {{0}}.
1215
1216
1217=== ERRNO values
1218
1219<constant>errno/perm</constant><br>
1220<constant>errno/noent</constant><br>
1221<constant>errno/srch</constant><br>
1222<constant>errno/intr</constant><br>
1223<constant>errno/io</constant><br>
1224<constant>errno/noexec</constant><br>
1225<constant>errno/badf</constant><br>
1226<constant>errno/child</constant><br>
1227<constant>errno/nomem</constant><br>
1228<constant>errno/acces</constant><br>
1229<constant>errno/fault</constant><br>
1230<constant>errno/busy</constant><br>
1231<constant>errno/notdir</constant><br>
1232<constant>errno/isdir</constant><br>
1233<constant>errno/inval</constant><br>
1234<constant>errno/mfile</constant><br>
1235<constant>errno/nospc</constant><br>
1236<constant>errno/spipe</constant><br>
1237<constant>errno/pipe</constant><br>
1238<constant>errno/again</constant><br>
1239<constant>errno/rofs</constant><br>
1240<constant>errno/exist</constant><br>
1241<constant>errno/wouldblock</constant>
1242
1243These variables contain error codes as returned by {{errno}}.
1244
1245
1246=== Finding files
1247
1248==== find-files
1249
1250<procedure>(find-files DIRECTORY #!key test action seed limit dotfiles follow-symlinks)</procedure>
1251
1252Recursively traverses the contents of {{DIRECTORY}} (which should be a
1253string) and invokes the procedure {{action}} for all files in which
1254the procedure {{test}} is true.  {{test}} may be a procedure of one
1255argument or an irregex object, regex string or SRE expression that
1256will be matched with a full pathname using {{irregex-match}}.
1257{{action}} should be a procedure of two arguments: the currently
1258encountered file and the result of the previous invocation of
1259{{action}}, or, if this is the first invocation, the value of
1260{{seed}}. {{test}} defaults to {{(constantly #t)}}, {{action}}
1261defaults to {{cons}}, {{seed}} defaults to {{()}}.  {{limit}} should
1262be a procedure of one argument that is called for each nested
1263directory and which should return true, if that directory is to be
1264traversed recursively. {{limit}} may also be an exact integer that
1265gives the maximum recursion depth. For example, a depth of {{0}} means
1266that only files in the top-level, specified directory are to be
1267traversed. In this case, all nested directories are ignored.
1268{{limit}} may also be {{#f}} (the default), which is equivalent to
1269{{(constantly #t)}}.
1270
1271If {{dotfiles}} is given and true, then files starting with a "{{.}}"
1272character will not be ignored (but note that "{{.}}" and "{{..}}"  are
1273always ignored). if {{follow-symlinks}} is given and true, then the
1274traversal of a symbolic link that points to a directory will
1275recursively traverse the latter. By default, symbolic links are not
1276followed.
1277
1278Note that {{action}} is called with the full pathname of each file,
1279including the directory prefix.
1280
1281This procedure's signature was changed in CHICKEN 4.6.   In older versions, {{find-files}}
1282has a different signature:
1283
1284  (find-files DIRECTORY [TEST [ACTION [SEED [LIMIT]]]])
1285
1286The old signature was supported until CHICKEN 4.7.3 for compatibility reasons,
1287at which point it became invalid.  The optional arguments are ignored
1288and use their default values, and no warning is issued.  One symptom is
1289that your {{TEST}} does not work, returning every file.
1290
1291=== Getting the hostname and system information
1292
1293==== get-host-name
1294
1295<procedure>(get-host-name)</procedure>
1296
1297Returns the hostname of the machine that this process is running on.
1298
1299==== system-information
1300
1301<procedure>(system-information)</procedure>
1302
1303Invokes the UNIX system call {{uname()}} and returns a list of 5 values:
1304system-name, node-name, OS release, OS version and machine.
1305
1306=== Setting the file buffering mode
1307
1308==== set-buffering-mode!
1309
1310<procedure>(set-buffering-mode! PORT MODE [BUFSIZE])</procedure>
1311
1312Sets the buffering-mode for the file associated with {{PORT}} to
1313{{MODE}}, which should be one of the keywords {{#:full}},
1314{{#:line}} or {{#:none}}. If {{BUFSIZE}} is specified it
1315determines the size of the buffer to be used (if any).
1316
1317
1318=== Terminal ports
1319
1320==== terminal-name
1321
1322<procedure>(terminal-name PORT)</procedure>
1323
1324Returns the name of the terminal that is connected to {{PORT}}.
1325
1326==== terminal-port?
1327
1328<procedure>(terminal-port? PORT)</procedure>
1329
1330Returns {{#t}} if {{PORT}} is connected to a terminal and
1331{{#f}} otherwise.
1332
1333
1334==== terminal-size
1335
1336<procedure>(terminal-size PORT)</procedure>
1337
1338Returns two values, the number of columns and rows of the terminal
1339that is connected to {{PORT}} or {{0}}, {{0}} if the terminal size can
1340not be obtained. On Windows, this procedure always returns {{0}},
1341{{0}}.
1342
1343
1344=== How Scheme procedures relate to UNIX C functions
1345
1346; {{change-directory}} : {{chdir}}
1347; {{change-directory*}} : {{fchdir}}
1348; {{change-file-mode}} : {{chmod}}
1349; {{change-file-owner}} : {{chown}}
1350; {{create-directory}} : {{mkdir}}
1351; {{create-fifo}} : {{mkfifo}}
1352; {{create-pipe}} : {{pipe}}
1353; {{create-session}} : {{setsid}}
1354; {{create-symbolic-link}} : {{link}}
1355; {{current-directory}} : {{curdir}}
1356; {{current-effective-group-id}} : {{getegid}}
1357; {{current-effective-user-id}} : {{geteuid}}
1358; {{current-group-id}} : {{getgid}}
1359; {{current-parent-id}} : {{getppid}}
1360; {{current-process-id}} : {{getpid}}
1361; {{current-user-id}} : {{getuid}}
1362; {{delete-directory}} : {{rmdir}}
1363; {{duplicate-fileno}} : {{dup/dup2}}
1364; {{_exit}} : {{_exit}}
1365; {{file-close}} : {{close}}
1366; {{file-access-time}} : {{stat}}
1367; {{file-change-time}} : {{stat}}
1368; {{file-creation-mode}} : {{umask}}
1369; {{file-modification-time}} : {{stat}}
1370; {{file-execute-access?}} : {{access}}
1371; {{file-open}} : {{open}}
1372; {{file-lock}} : {{fcntl}}
1373; {{file-position}} : {{ftell/lseek}}
1374; {{file-read}} : {{read}}
1375; {{file-read-access?}} : {{access}}
1376; {{file-select}} : {{select}}
1377; {{file-control}} : {{fcntl}}
1378; {{file-stat}} : {{stat}}
1379; {{file-test-lock}} : {{fcntl}}
1380; {{file-truncate}} : {{truncate/ftruncate}}
1381; {{file-unlock}} : {{fcntl}}
1382; {{file-write}} : {{write}}
1383; {{file-write-access?}} : {{access}}
1384; {{get-groups}} : {{getgroups}}
1385; {{get-host-name}} : {{gethostname}}
1386; {{initialize-groups}} : {{initgroups}}
1387; {{local-time->seconds}} : {{mktime}}
1388; {{local-timezone-abbreviation}} : {{localtime}}
1389; {{map-file-to-memory}} : {{mmap}}
1390; {{open-input-file*}} : {{fdopen}}
1391; {{open-output-file*}} : {{fdopen}}
1392; {{open-input-pipe}} : {{popen}}
1393; {{open-output-pipe}} : {{popen}}
1394; {{port->fileno}} : {{fileno}}
1395; {{process-execute}} : {{execvp}}
1396; {{process-fork}} : {{fork}}
1397; {{process-group-id}} : {{getpgid}}
1398; {{process-signal}} : {{kill}}
1399; {{process-wait}} : {{waitpid}}
1400; {{close-input-pipe}} : {{pclose}}
1401; {{close-output-pipe}} : {{pclose}}
1402; {{read-symbolic-link}} : {{readlink}}
1403; {{seconds->local-time}} : {{localtime}}
1404; {{seconds->string}} : {{ctime}}
1405; {{seconds->utc-time}} : {{gmtime}}
1406; {{set-alarm!}} : {{alarm}}
1407; {{set-buffering-mode!}} : {{setvbuf}}
1408; {{set-file-position!}} : {{fseek/seek}}
1409; {{set-groups!}} : {{setgroups}}
1410; {{set-signal-mask!}} : {{sigprocmask}}
1411; {{set-group-id!}} : {{setgid}}
1412; {{set-process-group-id!}} : {{setpgid}}
1413; {{set-user-id!}} : {{setuid}}
1414; {{set-root-directory!}} : {{chroot}}
1415; {{setenv}} : {{setenv/putenv}}
1416; {{sleep}} : {{sleep}}
1417; {{system-information}} : {{uname}}
1418; {{terminal-name}} : {{ttyname}}
1419; {{terminal-port?}} : {{isatty}}
1420; {{time->string}} : {{asctime}}
1421; {{unsetenv}} : {{putenv}}
1422; {{unmap-file-from-memory}} : {{munmap}}
1423; {{user-information}} : {{getpwnam/getpwuid}}
1424; {{utc-time->seconds}} : {{timegm}}
1425
1426
1427=== Windows specific notes
1428
1429Use of UTF8 encoded strings is for pathnames is not supported. Windows uses a
143016-bit UNICODE encoding with special system calls for wide-character support.
1431Only single-byte string encoding can be used.
1432
1433==== Procedure Changes
1434
1435Exceptions to the above procedure definitions.
1436
1437<procedure>(create-pipe [MODE])</procedure>
1438
1439The optional parameter {{MODE}}, default {{open/binary | open/noinherit}}. This can be {{open/binary}} or
1440{{open/text}}, optionally or'ed with {{open/noinherit}}.
1441
1442<procedure>(process-wait [PID [NOHANG]])</procedure>
1443
1444{{process-wait}} always returns {{#t}} for a terminated process and only the exit
1445status is available. (Windows does not provide signals as an interprocess
1446communication method.)
1447
1448<procedure>(process-execute PATHNAME [ARGUMENT-LIST [ENVIRONMENT-LIST [EXACT-FLAG]]])</procedure><br>
1449<procedure>(process COMMAND ARGUMENT-LIST [ENVIRONMENT-LIST [EXACT-FLAG]])</procedure><br>
1450<procedure>(process* COMMAND ARGUMENT-LIST [ENVIRONMENT-LIST [EXACT-FLAG]])</procedure><br>
1451
1452The optional parameter {{EXACT-FLAG}}, default {{#f}}. When {{#f}} any argument string with
1453embedded whitespace will be wrapped in quotes. When {{#t}} no such wrapping occurs.
1454
1455==== Unsupported Definitions
1456
1457The following definitions are not supported for native Windows builds (compiled with the
1458Microsoft tools or with MinGW):
1459
1460 open/noctty  open/nonblock  open/fsync  open/sync
1461 perm/isvtx  perm/isuid  perm/isgid
1462 file-select file-control
1463 signal/... (except signal/term, signal/int, signal/fpe, signal/ill, signal/segv, signal/abrt, signal/break)
1464 set-signal-mask!  signal-mask  signal-masked?  signal-mask!  signal-unmask!
1465 user-information  group-information  get-groups  set-groups!  initialize-groups
1466 errno/wouldblock
1467 change-directory*
1468 change-file-owner
1469 current-user-id  current-group-id  current-effective-user-id  current-effective-group-id
1470 set-user-id!  set-group-id!
1471 create-session
1472 process-group-id  set-process-group-id!
1473 create-symbolic-link  read-symbolic-link
1474 file-truncate
1475 file-lock  file-lock/blocking  file-unlock  file-test-lock
1476 create-fifo  fifo?
1477 set-alarm!
1478 terminal-port?  terminal-name
1479 process-fork  process-signal
1480 parent-process-id
1481 set-root-directory!
1482 utc-time->seconds
1483
1484==== Additional Definitions
1485
1486Only available for Windows
1487
1488* open/noinherit
1489
1490This variable is a mode value for {{create-pipe}}. Useful when spawning a child process.
1491
1492* spawn/overlay
1493* spawn/wait
1494* spawn/nowait
1495* spawn/nowaito
1496* spawn/detach
1497
1498These variables contains special flags that specify the exact semantics of {{process-spawn}}:
1499{{spawn/overlay}} replaces the current process with the new one.
1500{{spawn/wait}} suspends execution of the current process until the spawned process returns.
1501{{spawn/nowait}} does the opposite ({{spawn/nowaito}} is identical, according to the Microsoft
1502documentation) and runs the process asynchronously.
1503{{spawn/detach}} runs the new process in the background, without being attached to a console.
1504
1505==== process-spawn
1506
1507<procedure>(process-spawn MODE COMMAND [ARGUMENT-LIST [ENVIRONMENT-LIST [EXACT-FLAG]]])</procedure>
1508
1509Creates and runs a new process with the given {{COMMAND}} filename and the optional
1510{{ARGUMENT-LIST}} and {{ENVIRONMENT-LIST}}. {{MODE}} specifies how exactly the process
1511should be executed and must be one or more of the {{spawn/...}} flags defined above.
1512
1513The {{EXACT-FLAG}}, default {{#f}}, controls quote-wrapping of argument strings. When {{#t}}
1514quote-wrapping is not performed.
1515
1516Returns:
1517* the exit status when synchronous
1518* the PID when asynchronous
1519* -1 when failure
1520
1521----
1522Previous: [[Unit srfi-69]]
1523
1524Next: [[Unit utils]]
Note: See TracBrowser for help on using the repository browser.