source: project/chicken/trunk/manual/Unit posix @ 5945

Last change on this file since 5945 was 5945, checked in by felix winkelmann, 12 years ago

renamed some tools in misc/; apply hack fix on x86-64 (again); re-added manual

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