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

Last change on this file since 29811 was 29811, checked in by svnwiki, 7 years ago

Anonymous wiki edit for IP [98.14.171.153]: Corrected definition of seconds->string

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