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

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

synced wiki changes into manual and some changes back

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