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

Last change on this file since 25773 was 25773, checked in by Jim Ursetto, 9 years ago

wiki/man/Unit posix: Try to clear up file-stat vector contents

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