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

Last change on this file since 25875 was 25875, checked in by felix winkelmann, 9 years ago

merged some manual changes from master into wiki

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