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

Last change on this file since 22081 was 22081, checked in by Moritz Heidkamp, 10 years ago

manual: update posix' terminal-size signature and document it accordingly

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