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

Last change on this file since 15321 was 15321, checked in by felix winkelmann, 11 years ago

documentation fixes, read-symbolic-link enhancement by mario; rational? fixed (thanks to John Cowan)

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