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

Last change on this file since 33130 was 33130, checked in by sjamaan, 5 years ago

Sync wiki manual with core 4.10.0 changes (which was apparently forgotten when we made the release...)

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