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

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

Synch wiki manual with 4.11.0 release manual (some small updates, plus a new Debugging chapter)

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