1Unix(3) OCaml library Unix(3)
2
6 Unix - Interface to the Unix system.
7
9 Module Unix
10
12 Module Unix
13 : sig end
14 Interface to the Unix system.
17 To use the labeled version of this module, add module Unix = UnixLabels
19 in your implementation.
20 Note: all the functions of this module (except Unix.error_message and
22 Unix.handle_unix_error ) are liable to raise the Unix.Unix_error excep‐
23 tion whenever the underlying system call signals an error.
24 Error report
32 type error =
33 | E2BIG (* Argument list too long
34 *)
35 | EACCES (* Permission denied
36 *)
37 | EAGAIN (* Resource temporarily unavailable; try again
38 *)
39 | EBADF (* Bad file descriptor
40 *)
41 | EBUSY (* Resource unavailable
42 *)
43 | ECHILD (* No child process
44 *)
45 | EDEADLK (* Resource deadlock would occur
46 *)
47 | EDOM (* Domain error for math functions, etc.
48 *)
49 | EEXIST (* File exists
50 *)
51 | EFAULT (* Bad address
52 *)
53 | EFBIG (* File too large
54 *)
55 | EINTR (* Function interrupted by signal
56 *)
57 | EINVAL (* Invalid argument
58 *)
59 | EIO (* Hardware I/O error
60 *)
61 | EISDIR (* Is a directory
62 *)
63 | EMFILE (* Too many open files by the process
64 *)
65 | EMLINK (* Too many links
66 *)
67 | ENAMETOOLONG (* Filename too long
68 *)
69 | ENFILE (* Too many open files in the system
70 *)
71 | ENODEV (* No such device
72 *)
73 | ENOENT (* No such file or directory
74 *)
75 | ENOEXEC (* Not an executable file
76 *)
77 | ENOLCK (* No locks available
78 *)
79 | ENOMEM (* Not enough memory
80 *)
81 | ENOSPC (* No space left on device
82 *)
83 | ENOSYS (* Function not supported
84 *)
85 | ENOTDIR (* Not a directory
86 *)
87 | ENOTEMPTY (* Directory not empty
88 *)
89 | ENOTTY (* Inappropriate I/O control operation
90 *)
91 | ENXIO (* No such device or address
92 *)
93 | EPERM (* Operation not permitted
94 *)
95 | EPIPE (* Broken pipe
96 *)
97 | ERANGE (* Result too large
98 *)
99 | EROFS (* Read-only file system
100 *)
101 | ESPIPE (* Invalid seek e.g. on a pipe
102 *)
103 | ESRCH (* No such process
104 *)
105 | EXDEV (* Invalid link
106 *)
107 | EWOULDBLOCK (* Operation would block
108 *)
109 | EINPROGRESS (* Operation now in progress
110 *)
111 | EALREADY (* Operation already in progress
112 *)
113 | ENOTSOCK (* Socket operation on non-socket
114 *)
115 | EDESTADDRREQ (* Destination address required
116 *)
117 | EMSGSIZE (* Message too long
118 *)
119 | EPROTOTYPE (* Protocol wrong type for socket
120 *)
121 | ENOPROTOOPT (* Protocol not available
122 *)
123 | EPROTONOSUPPORT (* Protocol not supported
124 *)
125 | ESOCKTNOSUPPORT (* Socket type not supported
126 *)
127 | EOPNOTSUPP (* Operation not supported on socket
128 *)
129 | EPFNOSUPPORT (* Protocol family not supported
130 *)
131 | EAFNOSUPPORT (* Address family not supported by protocol family
132 *)
133 | EADDRINUSE (* Address already in use
134 *)
135 | EADDRNOTAVAIL (* Can't assign requested address
136 *)
137 | ENETDOWN (* Network is down
138 *)
139 | ENETUNREACH (* Network is unreachable
140 *)
141 | ENETRESET (* Network dropped connection on reset
142 *)
143 | ECONNABORTED (* Software caused connection abort
144 *)
145 | ECONNRESET (* Connection reset by peer
146 *)
147 | ENOBUFS (* No buffer space available
148 *)
149 | EISCONN (* Socket is already connected
150 *)
151 | ENOTCONN (* Socket is not connected
152 *)
153 | ESHUTDOWN (* Can't send after socket shutdown
154 *)
155 | ETOOMANYREFS (* Too many references: can't splice
156 *)
157 | ETIMEDOUT (* Connection timed out
158 *)
159 | ECONNREFUSED (* Connection refused
160 *)
161 | EHOSTDOWN (* Host is down
162 *)
163 | EHOSTUNREACH (* No route to host
164 *)
165 | ELOOP (* Too many levels of symbolic links
166 *)
167 | EOVERFLOW (* File size or position not representable
168 *)
169 | EUNKNOWNERR of int
170 (* Unknown error
171 *)
172 The type of error codes. Errors defined in the POSIX standard and ad‐
175 ditional errors from UNIX98 and BSD. All other errors are mapped to
176 EUNKNOWNERR.
177 exception Unix_error of error * string * string
181 Raised by the system calls below when an error is encountered. The
184 first component is the error code; the second component is the function
185 name; the third component is the string parameter to the function, if
186 it has one, or the empty string otherwise.
187 UnixLabels.Unix_error and Unix.Unix_error are the same, and catching
190 one will catch the other.
191 val error_message : error -> string
195 Return a string describing the given error code.
197 val handle_unix_error : ('a -> 'b) -> 'a -> 'b
201 handle_unix_error f x applies f to x and returns the result. If the
204 exception Unix.Unix_error is raised, it prints a message describing the
205 error and exits with code 2.
206 Access to the process environment
211 val environment : unit -> string array
212 Return the process environment, as an array of strings with the format
214 ``variable=value''. The returned array is empty if the process has
215 special privileges.
216 val unsafe_environment : unit -> string array
220 Return the process environment, as an array of strings with the format
222 ``variable=value''. Unlike Unix.environment , this function returns a
223 populated array even if the process has special privileges. See the
224 documentation for Unix.unsafe_getenv for more details.
225 Since 4.06.0 (4.12.0 in UnixLabels)
228 val getenv : string -> string
232 Return the value associated to a variable in the process environment,
234 unless the process has special privileges.
235 Raises Not_found if the variable is unbound or the process has special
238 privileges.
239 This function is identical to Sys.getenv .
241 val unsafe_getenv : string -> string
245 Return the value associated to a variable in the process environment.
247 Unlike Unix.getenv , this function returns the value even if the
249 process has special privileges. It is considered unsafe because the
250 programmer of a setuid or setgid program must be careful to avoid using
251 maliciously crafted environment variables in the search path for exe‐
252 cutables, the locations for temporary files or logs, and the like.
253 Since 4.06.0
256 Raises Not_found if the variable is unbound.
259 val putenv : string -> string -> unit
263 putenv name value sets the value associated to a variable in the
266 process environment. name is the name of the environment variable, and
267 value its new associated value.
268 Process handling
273 type process_status =
274 | WEXITED of int
275 (* The process terminated normally by exit ; the argument is the re‐
276 turn code.
277 *)
278 | WSIGNALED of int
279 (* The process was killed by a signal; the argument is the signal
280 number.
281 *)
282 | WSTOPPED of int
283 (* The process was stopped by a signal; the argument is the signal
284 number.
285 *)
286 The termination status of a process. See module Sys for the defini‐
289 tions of the standard signal numbers. Note that they are not the num‐
290 bers used by the OS.
291 type wait_flag =
294 | WNOHANG (* Do not block if no child has died yet, but immediately
295 return with a pid equal to 0.
296 *)
297 | WUNTRACED (* Report also the children that receive stop signals.
298 *)
299 Flags for Unix.waitpid .
302 val execv : string -> string array -> 'a
306 execv prog args execute the program in file prog , with the arguments
309 args , and the current process environment. These execv* functions
310 never return: on success, the current program is replaced by the new
311 one.
312 Raises Unix_error on failure
315 val execve : string -> string array -> string array -> 'a
319 Same as Unix.execv , except that the third argument provides the envi‐
321 ronment to the program executed.
322 val execvp : string -> string array -> 'a
326 Same as Unix.execv , except that the program is searched in the path.
328 val execvpe : string -> string array -> string array -> 'a
332 Same as Unix.execve , except that the program is searched in the path.
334 val fork : unit -> int
338 Fork a new process. The returned integer is 0 for the child process,
340 the pid of the child process for the parent process.
341 Raises Invalid_argument on Windows. Use Unix.create_process or threads
344 instead.
345 val wait : unit -> int * process_status
349 Wait until one of the children processes die, and return its pid and
351 termination status.
352 Raises Invalid_argument on Windows. Use Unix.waitpid instead.
355 val waitpid : wait_flag list -> int -> int * process_status
359 Same as Unix.wait , but waits for the child process whose pid is given.
361 A pid of -1 means wait for any child. A pid of 0 means wait for any
362 child in the same process group as the current process. Negative pid
363 arguments represent process groups. The list of options indicates
364 whether waitpid should return immediately without waiting, and whether
365 it should report stopped children.
366 On Windows: can only wait for a given PID, not any child process.
368 val system : string -> process_status
372 Execute the given command, wait until it terminates, and return its
374 termination status. The string is interpreted by the shell /bin/sh (or
375 the command interpreter cmd.exe on Windows) and therefore can contain
376 redirections, quotes, variables, etc. To properly quote whitespace and
377 shell special characters occurring in file names or command arguments,
378 the use of Filename.quote_command is recommended. The result WEXITED
379 127 indicates that the shell couldn't be executed.
380 val _exit : int -> 'a
384 Terminate the calling process immediately, returning the given status
386 code to the operating system: usually 0 to indicate no errors, and a
387 small positive integer to indicate failure. Unlike exit , Unix._exit
388 performs no finalization whatsoever: functions registered with at_exit
389 are not called, input/output channels are not flushed, and the C
390 run-time system is not finalized either.
391 The typical use of Unix._exit is after a Unix.fork operation, when the
393 child process runs into a fatal error and must exit. In this case, it
394 is preferable to not perform any finalization action in the child
395 process, as these actions could interfere with similar actions per‐
396 formed by the parent process. For example, output channels should not
397 be flushed by the child process, as the parent process may flush them
398 again later, resulting in duplicate output.
399 Since 4.12.0
402 val getpid : unit -> int
406 Return the pid of the process.
408 val getppid : unit -> int
412 Return the pid of the parent process.
414 Raises Invalid_argument on Windows (because it is meaningless)
417 val nice : int -> int
421 Change the process priority. The integer argument is added to the
423 ``nice'' value. (Higher values of the ``nice'' value mean lower priori‐
424 ties.) Return the new nice value.
425 Raises Invalid_argument on Windows
428 Basic file input/output
433 type file_descr
434 The abstract type of file descriptors.
437 val stdin : file_descr
441 File descriptor for standard input.
443 val stdout : file_descr
447 File descriptor for standard output.
449 val stderr : file_descr
453 File descriptor for standard error.
455 type open_flag =
458 | O_RDONLY (* Open for reading
459 *)
460 | O_WRONLY (* Open for writing
461 *)
462 | O_RDWR (* Open for reading and writing
463 *)
464 | O_NONBLOCK (* Open in non-blocking mode
465 *)
466 | O_APPEND (* Open for append
467 *)
468 | O_CREAT (* Create if nonexistent
469 *)
470 | O_TRUNC (* Truncate to 0 length if existing
471 *)
472 | O_EXCL (* Fail if existing
473 *)
474 | O_NOCTTY (* Don't make this dev a controlling tty
475 *)
476 | O_DSYNC (* Writes complete as `Synchronised I/O data integrity com‐
477 pletion'
478 *)
479 | O_SYNC (* Writes complete as `Synchronised I/O file integrity com‐
480 pletion'
481 *)
482 | O_RSYNC (* Reads complete as writes (depending on O_SYNC/O_DSYNC)
483 *)
484 | O_SHARE_DELETE (* Windows only: allow the file to be deleted while
485 still open
486 *)
487 | O_CLOEXEC (* Set the close-on-exec flag on the descriptor returned
488 by Unix.openfile . See Unix.set_close_on_exec for more information.
489 *)
490 | O_KEEPEXEC (* Clear the close-on-exec flag. This is currently the
491 default.
492 *)
493 The flags to Unix.openfile .
496 type file_perm = int
499 The type of file access rights, e.g. 0o640 is read and write for user,
502 read for group, none for others
503 val openfile : string -> open_flag list -> file_perm -> file_descr
507 Open the named file with the given flags. Third argument is the permis‐
509 sions to give to the file if it is created (see Unix.umask ). Return a
510 file descriptor on the named file.
511 val close : file_descr -> unit
515 Close a file descriptor.
517 val fsync : file_descr -> unit
521 Flush file buffers to disk.
523 Since 4.08.0 (4.12.0 in UnixLabels)
526 val read : file_descr -> bytes -> int -> int -> int
530 read fd buf pos len reads len bytes from descriptor fd , storing them
533 in byte sequence buf , starting at position pos in buf . Return the
534 number of bytes actually read.
535 val write : file_descr -> bytes -> int -> int -> int
539 write fd buf pos len writes len bytes to descriptor fd , taking them
542 from byte sequence buf , starting at position pos in buff . Return the
543 number of bytes actually written. write repeats the writing operation
544 until all bytes have been written or an error occurs.
545 val single_write : file_descr -> bytes -> int -> int -> int
549 Same as Unix.write , but attempts to write only once. Thus, if an er‐
551 ror occurs, single_write guarantees that no data has been written.
552 val write_substring : file_descr -> string -> int -> int -> int
556 Same as Unix.write , but take the data from a string instead of a byte
558 sequence.
559 Since 4.02.0
562 val single_write_substring : file_descr -> string -> int -> int -> int
566 Same as Unix.single_write , but take the data from a string instead of
568 a byte sequence.
569 Since 4.02.0
572 Interfacing with the standard input/output library
577 val in_channel_of_descr : file_descr -> in_channel
578 Create an input channel reading from the given descriptor. The channel
580 is initially in binary mode; use set_binary_mode_in ic false if text
581 mode is desired. Text mode is supported only if the descriptor refers
582 to a file or pipe, but is not supported if it refers to a socket.
583 On Windows: set_binary_mode_in always fails on channels created with
585 this function.
586 Beware that input channels are buffered, so more characters may have
588 been read from the descriptor than those accessed using channel func‐
589 tions. Channels also keep a copy of the current position in the file.
590 Closing the channel ic returned by in_channel_of_descr fd using
592 close_in ic also closes the underlying descriptor fd . It is incorrect
593 to close both the channel ic and the descriptor fd .
594 If several channels are created on the same descriptor, one of the
596 channels must be closed, but not the others. Consider for example a
597 descriptor s connected to a socket and two channels ic = in_chan‐
598 nel_of_descr s and oc = out_channel_of_descr s . The recommended clos‐
599 ing protocol is to perform close_out oc , which flushes buffered output
600 to the socket then closes the socket. The ic channel must not be
601 closed and will be collected by the GC eventually.
602 val out_channel_of_descr : file_descr -> out_channel
606 Create an output channel writing on the given descriptor. The channel
608 is initially in binary mode; use set_binary_mode_out oc false if text
609 mode is desired. Text mode is supported only if the descriptor refers
610 to a file or pipe, but is not supported if it refers to a socket.
611 On Windows: set_binary_mode_out always fails on channels created with
613 this function.
614 Beware that output channels are buffered, so you may have to call flush
616 to ensure that all data has been sent to the descriptor. Channels also
617 keep a copy of the current position in the file.
618 Closing the channel oc returned by out_channel_of_descr fd using
620 close_out oc also closes the underlying descriptor fd . It is incor‐
621 rect to close both the channel ic and the descriptor fd .
622 See Unix.in_channel_of_descr for a discussion of the closing protocol
624 when several channels are created on the same descriptor.
625 val descr_of_in_channel : in_channel -> file_descr
629 Return the descriptor corresponding to an input channel.
631 val descr_of_out_channel : out_channel -> file_descr
635 Return the descriptor corresponding to an output channel.
637 Seeking and truncating
642 type seek_command =
643 | SEEK_SET (* indicates positions relative to the beginning of the
644 file
645 *)
646 | SEEK_CUR (* indicates positions relative to the current position
647 *)
648 | SEEK_END (* indicates positions relative to the end of the file
649 *)
650 Positioning modes for Unix.lseek .
653 val lseek : file_descr -> int -> seek_command -> int
657 Set the current position for a file descriptor, and return the result‐
659 ing offset (from the beginning of the file).
660 val truncate : string -> int -> unit
664 Truncates the named file to the given size.
666 val ftruncate : file_descr -> int -> unit
670 Truncates the file corresponding to the given descriptor to the given
672 size.
673 File status
678 type file_kind =
679 | S_REG (* Regular file
680 *)
681 | S_DIR (* Directory
682 *)
683 | S_CHR (* Character device
684 *)
685 | S_BLK (* Block device
686 *)
687 | S_LNK (* Symbolic link
688 *)
689 | S_FIFO (* Named pipe
690 *)
691 | S_SOCK (* Socket
692 *)
693 type stats = {
698 st_dev : int ; (* Device number
699 *)
700 st_ino : int ; (* Inode number
701 *)
702 st_kind : file_kind ; (* Kind of the file
703 *)
704 st_perm : file_perm ; (* Access rights
705 *)
706 st_nlink : int ; (* Number of links
707 *)
708 st_uid : int ; (* User id of the owner
709 *)
710 st_gid : int ; (* Group ID of the file's group
711 *)
712 st_rdev : int ; (* Device ID (if special file)
713 *)
714 st_size : int ; (* Size in bytes
715 *)
716 st_atime : float ; (* Last access time
717 *)
718 st_mtime : float ; (* Last modification time
719 *)
720 st_ctime : float ; (* Last status change time
721 *)
722 }
723 The information returned by the Unix.stat calls.
726 val stat : string -> stats
730 Return the information for the named file.
732 val lstat : string -> stats
736 Same as Unix.stat , but in case the file is a symbolic link, return the
738 information for the link itself.
739 val fstat : file_descr -> stats
743 Return the information for the file associated with the given descrip‐
745 tor.
746 val isatty : file_descr -> bool
750 Return true if the given file descriptor refers to a terminal or con‐
752 sole window, false otherwise.
753 File operations on large files
758 module LargeFile : sig end
759 File operations on large files. This sub-module provides 64-bit vari‐
762 ants of the functions Unix.LargeFile.lseek (for positioning a file de‐
763 scriptor), Unix.LargeFile.truncate and Unix.LargeFile.ftruncate (for
764 changing the size of a file), and Unix.LargeFile.stat , Unix.Large‐
765 File.lstat and Unix.LargeFile.fstat (for obtaining information on
766 files). These alternate functions represent positions and sizes by
767 64-bit integers (type int64 ) instead of regular integers (type int ),
768 thus allowing operating on files whose sizes are greater than max_int .
769 Mapping files into memory
774 val map_file : file_descr -> ?pos:int64 -> ('a, 'b) Bigarray.kind -> 'c
775 Bigarray.layout -> bool -> int array -> ('a, 'b, 'c) Bigarray.Genar‐
776 ray.t
777 Memory mapping of a file as a Bigarray. map_file fd kind layout shared
779 dims returns a Bigarray of kind kind , layout layout , and dimensions
780 as specified in dims . The data contained in this Bigarray are the
781 contents of the file referred to by the file descriptor fd (as opened
782 previously with Unix.openfile , for example). The optional pos parame‐
783 ter is the byte offset in the file of the data being mapped; it de‐
784 faults to 0 (map from the beginning of the file).
785 If shared is true , all modifications performed on the array are re‐
787 flected in the file. This requires that fd be opened with write per‐
788 missions. If shared is false , modifications performed on the array
789 are done in memory only, using copy-on-write of the modified pages; the
790 underlying file is not affected.
791 Unix.map_file is much more efficient than reading the whole file in a
794 Bigarray, modifying that Bigarray, and writing it afterwards.
795 To adjust automatically the dimensions of the Bigarray to the actual
797 size of the file, the major dimension (that is, the first dimension for
798 an array with C layout, and the last dimension for an array with For‐
799 tran layout) can be given as -1 . Unix.map_file then determines the
800 major dimension from the size of the file. The file must contain an
801 integral number of sub-arrays as determined by the non-major dimen‐
802 sions, otherwise Failure is raised.
803 If all dimensions of the Bigarray are given, the file size is matched
805 against the size of the Bigarray. If the file is larger than the Bi‐
806 garray, only the initial portion of the file is mapped to the Bigarray.
807 If the file is smaller than the big array, the file is automatically
808 grown to the size of the Bigarray. This requires write permissions on
809 fd .
810 Array accesses are bounds-checked, but the bounds are determined by the
812 initial call to map_file . Therefore, you should make sure no other
813 process modifies the mapped file while you're accessing it, or a SIGBUS
814 signal may be raised. This happens, for instance, if the file is
815 shrunk.
816 Invalid_argument or Failure may be raised in cases where argument vali‐
819 dation fails.
820 Since 4.06.0
823 Operations on file names
828 val unlink : string -> unit
829 Removes the named file.
831 If the named file is a directory, raises:
833 - EPERM on POSIX compliant system
835 - EISDIR on Linux >= 2.1.132
837 - EACCESS on Windows
839 val rename : string -> string -> unit
844 rename src dst changes the name of a file from src to dst , moving it
847 between directories if needed. If dst already exists, its contents
848 will be replaced with those of src . Depending on the operating sys‐
849 tem, the metadata (permissions, owner, etc) of dst can either be pre‐
850 served or be replaced by those of src .
851 val link : ?follow:bool -> string -> string -> unit
855 link ?follow src dst creates a hard link named dst to the file named
858 src .
859 Raises ENOSYS On Unix if ~follow:_ is requested, but linkat is unavail‐
862 able.
863 Raises ENOSYS On Windows if ~follow:false is requested.
866 val realpath : string -> string
870 realpath p is an absolute pathname for p obtained by resolving all ex‐
873 tra / characters, relative path segments and symbolic links.
874 Since 4.13.0
877 File permissions and ownership
882 type access_permission =
883 | R_OK (* Read permission
884 *)
885 | W_OK (* Write permission
886 *)
887 | X_OK (* Execution permission
888 *)
889 | F_OK (* File exists
890 *)
891 Flags for the Unix.access call.
894 val chmod : string -> file_perm -> unit
898 Change the permissions of the named file.
900 val fchmod : file_descr -> file_perm -> unit
904 Change the permissions of an opened file.
906 Raises Invalid_argument on Windows
909 val chown : string -> int -> int -> unit
913 Change the owner uid and owner gid of the named file.
915 Raises Invalid_argument on Windows
918 val fchown : file_descr -> int -> int -> unit
922 Change the owner uid and owner gid of an opened file.
924 Raises Invalid_argument on Windows
927 val umask : int -> int
931 Set the process's file mode creation mask, and return the previous
933 mask.
934 Raises Invalid_argument on Windows
937 val access : string -> access_permission list -> unit
941 Check that the process has the given permissions over the named file.
943 On Windows: execute permission X_OK cannot be tested, just tests for
945 read permission instead.
946 Raises Unix_error otherwise.
949 Operations on file descriptors
954 val dup : ?cloexec:bool -> file_descr -> file_descr
955 Return a new file descriptor referencing the same file as the given de‐
957 scriptor. See Unix.set_close_on_exec for documentation on the cloexec
958 optional argument.
959 val dup2 : ?cloexec:bool -> file_descr -> file_descr -> unit
963 dup2 src dst duplicates src to dst , closing dst if already opened.
966 See Unix.set_close_on_exec for documentation on the cloexec optional
967 argument.
968 val set_nonblock : file_descr -> unit
972 Set the ``non-blocking'' flag on the given descriptor. When the
974 non-blocking flag is set, reading on a descriptor on which there is
975 temporarily no data available raises the EAGAIN or EWOULDBLOCK error
976 instead of blocking; writing on a descriptor on which there is tempo‐
977 rarily no room for writing also raises EAGAIN or EWOULDBLOCK .
978 val clear_nonblock : file_descr -> unit
982 Clear the ``non-blocking'' flag on the given descriptor. See
984 Unix.set_nonblock .
985 val set_close_on_exec : file_descr -> unit
989 Set the ``close-on-exec'' flag on the given descriptor. A descriptor
991 with the close-on-exec flag is automatically closed when the current
992 process starts another program with one of the exec , create_process
993 and open_process functions.
994 It is often a security hole to leak file descriptors opened on, say, a
996 private file to an external program: the program, then, gets access to
997 the private file and can do bad things with it. Hence, it is highly
998 recommended to set all file descriptors ``close-on-exec'', except in
999 the very few cases where a file descriptor actually needs to be trans‐
1000 mitted to another program.
1001 The best way to set a file descriptor ``close-on-exec'' is to create it
1003 in this state. To this end, the openfile function has O_CLOEXEC and
1004 O_KEEPEXEC flags to enforce ``close-on-exec'' mode or ``keep-on-exec''
1005 mode, respectively. All other operations in the Unix module that cre‐
1006 ate file descriptors have an optional argument ?cloexec:bool to indi‐
1007 cate whether the file descriptor should be created in ``close-on-exec''
1008 mode (by writing ~cloexec:true ) or in ``keep-on-exec'' mode (by writ‐
1009 ing ~cloexec:false ). For historical reasons, the default file de‐
1010 scriptor creation mode is ``keep-on-exec'', if no cloexec optional ar‐
1011 gument is given. This is not a safe default, hence it is highly recom‐
1012 mended to pass explicit cloexec arguments to operations that create
1013 file descriptors.
1014 The cloexec optional arguments and the O_KEEPEXEC flag were introduced
1016 in OCaml 4.05. Earlier, the common practice was to create file de‐
1017 scriptors in the default, ``keep-on-exec'' mode, then call
1018 set_close_on_exec on those freshly-created file descriptors. This is
1019 not as safe as creating the file descriptor in ``close-on-exec'' mode
1020 because, in multithreaded programs, a window of vulnerability exists
1021 between the time when the file descriptor is created and the time
1022 set_close_on_exec completes. If another thread spawns another program
1023 during this window, the descriptor will leak, as it is still in the
1024 ``keep-on-exec'' mode.
1025 Regarding the atomicity guarantees given by ~cloexec:true or by the use
1027 of the O_CLOEXEC flag: on all platforms it is guaranteed that a concur‐
1028 rently-executing Caml thread cannot leak the descriptor by starting a
1029 new process. On Linux, this guarantee extends to concurrently-execut‐
1030 ing C threads. As of Feb 2017, other operating systems lack the neces‐
1031 sary system calls and still expose a window of vulnerability during
1032 which a C thread can see the newly-created file descriptor in
1033 ``keep-on-exec'' mode.
1034 val clear_close_on_exec : file_descr -> unit
1038 Clear the ``close-on-exec'' flag on the given descriptor. See
1040 Unix.set_close_on_exec .
1041 Directories
1046 val mkdir : string -> file_perm -> unit
1047 Create a directory with the given permissions (see Unix.umask ).
1049 val rmdir : string -> unit
1053 Remove an empty directory.
1055 val chdir : string -> unit
1059 Change the process working directory.
1061 val getcwd : unit -> string
1065 Return the name of the current working directory.
1067 val chroot : string -> unit
1071 Change the process root directory.
1073 Raises Invalid_argument on Windows
1076 type dir_handle
1079 The type of descriptors over opened directories.
1082 val opendir : string -> dir_handle
1086 Open a descriptor on a directory
1088 val readdir : dir_handle -> string
1092 Return the next entry in a directory.
1094 Raises End_of_file when the end of the directory has been reached.
1097 val rewinddir : dir_handle -> unit
1101 Reposition the descriptor to the beginning of the directory
1103 val closedir : dir_handle -> unit
1107 Close a directory descriptor.
1109 Pipes and redirections
1114 val pipe : ?cloexec:bool -> unit -> file_descr * file_descr
1115 Create a pipe. The first component of the result is opened for reading,
1117 that's the exit to the pipe. The second component is opened for writ‐
1118 ing, that's the entrance to the pipe. See Unix.set_close_on_exec for
1119 documentation on the cloexec optional argument.
1120 val mkfifo : string -> file_perm -> unit
1124 Create a named pipe with the given permissions (see Unix.umask ).
1126 Raises Invalid_argument on Windows
1129 High-level process and redirection management
1134 val create_process : string -> string array -> file_descr -> file_descr
1135 -> file_descr -> int
1136 create_process prog args stdin stdout stderr forks a new process that
1139 executes the program in file prog , with arguments args . The pid of
1140 the new process is returned immediately; the new process executes con‐
1141 currently with the current process. The standard input and outputs of
1142 the new process are connected to the descriptors stdin , stdout and
1143 stderr . Passing e.g. Unix.stdout for stdout prevents the redirection
1144 and causes the new process to have the same standard output as the cur‐
1145 rent process. The executable file prog is searched in the path. The
1146 new process has the same environment as the current process.
1147 val create_process_env : string -> string array -> string array ->
1151 file_descr -> file_descr -> file_descr -> int
1152 create_process_env prog args env stdin stdout stderr works as Unix.cre‐
1155 ate_process , except that the extra argument env specifies the environ‐
1156 ment passed to the program.
1157 val open_process_in : string -> in_channel
1161 High-level pipe and process management. This function runs the given
1163 command in parallel with the program. The standard output of the com‐
1164 mand is redirected to a pipe, which can be read via the returned input
1165 channel. The command is interpreted by the shell /bin/sh (or cmd.exe
1166 on Windows), cf. Unix.system . The Filename.quote_command function
1167 can be used to quote the command and its arguments as appropriate for
1168 the shell being used. If the command does not need to be run through
1169 the shell, Unix.open_process_args_in can be used as a more robust and
1170 more efficient alternative to Unix.open_process_in .
1171 val open_process_out : string -> out_channel
1175 Same as Unix.open_process_in , but redirect the standard input of the
1177 command to a pipe. Data written to the returned output channel is sent
1178 to the standard input of the command. Warning: writes on output chan‐
1179 nels are buffered, hence be careful to call flush at the right times to
1180 ensure correct synchronization. If the command does not need to be run
1181 through the shell, Unix.open_process_args_out can be used instead of
1182 Unix.open_process_out .
1183 val open_process : string -> in_channel * out_channel
1187 Same as Unix.open_process_out , but redirects both the standard input
1189 and standard output of the command to pipes connected to the two re‐
1190 turned channels. The input channel is connected to the output of the
1191 command, and the output channel to the input of the command. If the
1192 command does not need to be run through the shell,
1193 Unix.open_process_args can be used instead of Unix.open_process .
1194 val open_process_full : string -> string array -> in_channel *
1198 out_channel * in_channel
1199 Similar to Unix.open_process , but the second argument specifies the
1201 environment passed to the command. The result is a triple of channels
1202 connected respectively to the standard output, standard input, and
1203 standard error of the command. If the command does not need to be run
1204 through the shell, Unix.open_process_args_full can be used instead of
1205 Unix.open_process_full .
1206 val open_process_args_in : string -> string array -> in_channel
1210 open_process_args_in prog args runs the program prog with arguments
1213 args . The new process executes concurrently with the current process.
1214 The standard output of the new process is redirected to a pipe, which
1215 can be read via the returned input channel.
1216 The executable file prog is searched in the path. This behaviour
1218 changed in 4.12; previously prog was looked up only in the current di‐
1219 rectory.
1220 The new process has the same environment as the current process.
1222 Since 4.08.0
1225 val open_process_args_out : string -> string array -> out_channel
1229 Same as Unix.open_process_args_in , but redirect the standard input of
1231 the new process to a pipe. Data written to the returned output channel
1232 is sent to the standard input of the program. Warning: writes on out‐
1233 put channels are buffered, hence be careful to call flush at the right
1234 times to ensure correct synchronization.
1235 Since 4.08.0
1238 val open_process_args : string -> string array -> in_channel *
1242 out_channel
1243 Same as Unix.open_process_args_out , but redirects both the standard
1245 input and standard output of the new process to pipes connected to the
1246 two returned channels. The input channel is connected to the output of
1247 the program, and the output channel to the input of the program.
1248 Since 4.08.0
1251 val open_process_args_full : string -> string array -> string array ->
1255 in_channel * out_channel * in_channel
1256 Similar to Unix.open_process_args , but the third argument specifies
1258 the environment passed to the new process. The result is a triple of
1259 channels connected respectively to the standard output, standard input,
1260 and standard error of the program.
1261 Since 4.08.0
1264 val process_in_pid : in_channel -> int
1268 Return the pid of a process opened via Unix.open_process_in or
1270 Unix.open_process_args_in .
1271 Since 4.08.0 (4.12.0 in UnixLabels)
1274 val process_out_pid : out_channel -> int
1278 Return the pid of a process opened via Unix.open_process_out or
1280 Unix.open_process_args_out .
1281 Since 4.08.0 (4.12.0 in UnixLabels)
1284 val process_pid : in_channel * out_channel -> int
1288 Return the pid of a process opened via Unix.open_process or
1290 Unix.open_process_args .
1291 Since 4.08.0 (4.12.0 in UnixLabels)
1294 val process_full_pid : in_channel * out_channel * in_channel -> int
1298 Return the pid of a process opened via Unix.open_process_full or
1300 Unix.open_process_args_full .
1301 Since 4.08.0 (4.12.0 in UnixLabels)
1304 val close_process_in : in_channel -> process_status
1308 Close channels opened by Unix.open_process_in , wait for the associated
1310 command to terminate, and return its termination status.
1311 val close_process_out : out_channel -> process_status
1315 Close channels opened by Unix.open_process_out , wait for the associ‐
1317 ated command to terminate, and return its termination status.
1318 val close_process : in_channel * out_channel -> process_status
1322 Close channels opened by Unix.open_process , wait for the associated
1324 command to terminate, and return its termination status.
1325 val close_process_full : in_channel * out_channel * in_channel ->
1329 process_status
1330 Close channels opened by Unix.open_process_full , wait for the associ‐
1332 ated command to terminate, and return its termination status.
1333 Symbolic links
1338 val symlink : ?to_dir:bool -> string -> string -> unit
1339 symlink ?to_dir src dst creates the file dst as a symbolic link to the
1342 file src . On Windows, ~to_dir indicates if the symbolic link points to
1343 a directory or a file; if omitted, symlink examines src using stat and
1344 picks appropriately, if src does not exist then false is assumed (for
1345 this reason, it is recommended that the ~to_dir parameter be specified
1346 in new code). On Unix, ~to_dir is ignored.
1347 Windows symbolic links are available in Windows Vista onwards. There
1349 are some important differences between Windows symlinks and their POSIX
1350 counterparts.
1351 Windows symbolic links come in two flavours: directory and regular,
1353 which designate whether the symbolic link points to a directory or a
1354 file. The type must be correct - a directory symlink which actually
1355 points to a file cannot be selected with chdir and a file symlink which
1356 actually points to a directory cannot be read or written (note that
1357 Cygwin's emulation layer ignores this distinction).
1358 When symbolic links are created to existing targets, this distinction
1360 doesn't matter and symlink will automatically create the correct kind
1361 of symbolic link. The distinction matters when a symbolic link is cre‐
1362 ated to a non-existent target.
1363 The other caveat is that by default symbolic links are a privileged op‐
1365 eration. Administrators will always need to be running elevated (or
1366 with UAC disabled) and by default normal user accounts need to be
1367 granted the SeCreateSymbolicLinkPrivilege via Local Security Policy
1368 (secpol.msc) or via Active Directory.
1369 Unix.has_symlink can be used to check that a process is able to create
1372 symbolic links.
1373 val has_symlink : unit -> bool
1377 Returns true if the user is able to create symbolic links. On Windows,
1379 this indicates that the user not only has the SeCreateSymbolicLinkPriv‐
1380 ilege but is also running elevated, if necessary. On other platforms,
1381 this is simply indicates that the symlink system call is available.
1382 Since 4.03.0
1385 val readlink : string -> string
1389 Read the contents of a symbolic link.
1391 Polling
1396 val select : file_descr list -> file_descr list -> file_descr list ->
1397 float -> file_descr list * file_descr list * file_descr list
1398 Wait until some input/output operations become possible on some chan‐
1400 nels. The three list arguments are, respectively, a set of descriptors
1401 to check for reading (first argument), for writing (second argument),
1402 or for exceptional conditions (third argument). The fourth argument is
1403 the maximal timeout, in seconds; a negative fourth argument means no
1404 timeout (unbounded wait). The result is composed of three sets of de‐
1405 scriptors: those ready for reading (first component), ready for writing
1406 (second component), and over which an exceptional condition is pending
1407 (third component).
1408 Locking
1413 type lock_command =
1414 | F_ULOCK (* Unlock a region
1415 *)
1416 | F_LOCK (* Lock a region for writing, and block if already locked
1417 *)
1418 | F_TLOCK (* Lock a region for writing, or fail if already locked
1419 *)
1420 | F_TEST (* Test a region for other process locks
1421 *)
1422 | F_RLOCK (* Lock a region for reading, and block if already locked
1423 *)
1424 | F_TRLOCK (* Lock a region for reading, or fail if already locked
1425 *)
1426 Commands for Unix.lockf .
1429 val lockf : file_descr -> lock_command -> int -> unit
1433 lockf fd mode len puts a lock on a region of the file opened as fd .
1436 The region starts at the current read/write position for fd (as set by
1437 Unix.lseek ), and extends len bytes forward if len is positive, len
1438 bytes backwards if len is negative, or to the end of the file if len is
1439 zero. A write lock prevents any other process from acquiring a read or
1440 write lock on the region. A read lock prevents any other process from
1441 acquiring a write lock on the region, but lets other processes acquire
1442 read locks on it.
1443 The F_LOCK and F_TLOCK commands attempts to put a write lock on the
1445 specified region. The F_RLOCK and F_TRLOCK commands attempts to put a
1446 read lock on the specified region. If one or several locks put by an‐
1447 other process prevent the current process from acquiring the lock,
1448 F_LOCK and F_RLOCK block until these locks are removed, while F_TLOCK
1449 and F_TRLOCK fail immediately with an exception. The F_ULOCK removes
1450 whatever locks the current process has on the specified region. Fi‐
1451 nally, the F_TEST command tests whether a write lock can be acquired on
1452 the specified region, without actually putting a lock. It returns im‐
1453 mediately if successful, or fails otherwise.
1454 What happens when a process tries to lock a region of a file that is
1456 already locked by the same process depends on the OS. On POSIX-compli‐
1457 ant systems, the second lock operation succeeds and may "promote" the
1458 older lock from read lock to write lock. On Windows, the second lock
1459 operation will block or fail.
1460 Signals
1465 Note: installation of signal handlers is performed via the functions
1466 Sys.signal and Sys.set_signal .
1467 val kill : int -> int -> unit
1469 kill pid signal sends signal number signal to the process with id pid .
1472 On Windows: only the Sys.sigkill signal is emulated.
1474 type sigprocmask_command =
1477 | SIG_SETMASK
1478 | SIG_BLOCK
1479 | SIG_UNBLOCK
1480 val sigprocmask : sigprocmask_command -> int list -> int list
1486 sigprocmask mode sigs changes the set of blocked signals. If mode is
1489 SIG_SETMASK , blocked signals are set to those in the list sigs . If
1490 mode is SIG_BLOCK , the signals in sigs are added to the set of blocked
1491 signals. If mode is SIG_UNBLOCK , the signals in sigs are removed from
1492 the set of blocked signals. sigprocmask returns the set of previously
1493 blocked signals.
1494 When the systhreads version of the Thread module is loaded, this func‐
1496 tion redirects to Thread.sigmask . I.e., sigprocmask only changes the
1497 mask of the current thread.
1498 Raises Invalid_argument on Windows (no inter-process signals on Win‐
1501 dows)
1502 val sigpending : unit -> int list
1506 Return the set of blocked signals that are currently pending.
1508 Raises Invalid_argument on Windows (no inter-process signals on Win‐
1511 dows)
1512 val sigsuspend : int list -> unit
1516 sigsuspend sigs atomically sets the blocked signals to sigs and waits
1519 for a non-ignored, non-blocked signal to be delivered. On return, the
1520 blocked signals are reset to their initial value.
1521 Raises Invalid_argument on Windows (no inter-process signals on Win‐
1524 dows)
1525 val pause : unit -> unit
1529 Wait until a non-ignored, non-blocked signal is delivered.
1531 Raises Invalid_argument on Windows (no inter-process signals on Win‐
1534 dows)
1535 Time functions
1540 type process_times = {
1541 tms_utime : float ; (* User time for the process
1542 *)
1543 tms_stime : float ; (* System time for the process
1544 *)
1545 tms_cutime : float ; (* User time for the children processes
1546 *)
1547 tms_cstime : float ; (* System time for the children processes
1548 *)
1549 }
1550 The execution times (CPU times) of a process.
1553 type tm = {
1556 tm_sec : int ; (* Seconds 0..60
1557 *)
1558 tm_min : int ; (* Minutes 0..59
1559 *)
1560 tm_hour : int ; (* Hours 0..23
1561 *)
1562 tm_mday : int ; (* Day of month 1..31
1563 *)
1564 tm_mon : int ; (* Month of year 0..11
1565 *)
1566 tm_year : int ; (* Year - 1900
1567 *)
1568 tm_wday : int ; (* Day of week (Sunday is 0)
1569 *)
1570 tm_yday : int ; (* Day of year 0..365
1571 *)
1572 tm_isdst : bool ; (* Daylight time savings in effect
1573 *)
1574 }
1575 The type representing wallclock time and calendar date.
1578 val time : unit -> float
1582 Return the current time since 00:00:00 GMT, Jan. 1, 1970, in seconds.
1584 val gettimeofday : unit -> float
1588 Same as Unix.time , but with resolution better than 1 second.
1590 val gmtime : float -> tm
1594 Convert a time in seconds, as returned by Unix.time , into a date and a
1596 time. Assumes UTC (Coordinated Universal Time), also known as GMT. To
1597 perform the inverse conversion, set the TZ environment variable to
1598 "UTC", use Unix.mktime , and then restore the original value of TZ.
1599 val localtime : float -> tm
1603 Convert a time in seconds, as returned by Unix.time , into a date and a
1605 time. Assumes the local time zone. The function performing the inverse
1606 conversion is Unix.mktime .
1607 val mktime : tm -> float * tm
1611 Convert a date and time, specified by the tm argument, into a time in
1613 seconds, as returned by Unix.time . The tm_isdst , tm_wday and tm_yday
1614 fields of tm are ignored. Also return a normalized copy of the given
1615 tm record, with the tm_wday , tm_yday , and tm_isdst fields recomputed
1616 from the other fields, and the other fields normalized (so that, e.g.,
1617 40 October is changed into 9 November). The tm argument is interpreted
1618 in the local time zone.
1619 val alarm : int -> int
1623 Schedule a SIGALRM signal after the given number of seconds.
1625 Raises Invalid_argument on Windows
1628 val sleep : int -> unit
1632 Stop execution for the given number of seconds.
1634 val sleepf : float -> unit
1638 Stop execution for the given number of seconds. Like sleep , but frac‐
1640 tions of seconds are supported.
1641 Since 4.03.0 (4.12.0 in UnixLabels)
1644 val times : unit -> process_times
1648 Return the execution times of the process.
1650 On Windows: partially implemented, will not report timings for child
1652 processes.
1653 val utimes : string -> float -> float -> unit
1657 Set the last access time (second arg) and last modification time (third
1659 arg) for a file. Times are expressed in seconds from 00:00:00 GMT, Jan.
1660 1, 1970. If both times are 0.0 , the access and last modification
1661 times are both set to the current time.
1662 type interval_timer =
1665 | ITIMER_REAL (* decrements in real time, and sends the signal
1666 SIGALRM when expired.
1667 *)
1668 | ITIMER_VIRTUAL (* decrements in process virtual time, and sends
1669 SIGVTALRM when expired.
1670 *)
1671 | ITIMER_PROF (* (for profiling) decrements both when the process is
1672 running and when the system is running on behalf of the process; it
1673 sends SIGPROF when expired.
1674 *)
1675 The three kinds of interval timers.
1678 type interval_timer_status = {
1681 it_interval : float ; (* Period
1682 *)
1683 it_value : float ; (* Current value of the timer
1684 *)
1685 }
1686 The type describing the status of an interval timer
1689 val getitimer : interval_timer -> interval_timer_status
1693 Return the current status of the given interval timer.
1695 Raises Invalid_argument on Windows
1698 val setitimer : interval_timer -> interval_timer_status -> inter‐
1702 val_timer_status
1703 setitimer t s sets the interval timer t and returns its previous sta‐
1706 tus. The s argument is interpreted as follows: s.it_value , if nonzero,
1707 is the time to the next timer expiration; s.it_interval , if nonzero,
1708 specifies a value to be used in reloading it_value when the timer ex‐
1709 pires. Setting s.it_value to zero disables the timer. Setting
1710 s.it_interval to zero causes the timer to be disabled after its next
1711 expiration.
1712 Raises Invalid_argument on Windows
1715 User id, group id
1720 val getuid : unit -> int
1721 Return the user id of the user executing the process.
1723 On Windows: always returns 1 .
1725 val geteuid : unit -> int
1729 Return the effective user id under which the process runs.
1731 On Windows: always returns 1 .
1733 val setuid : int -> unit
1737 Set the real user id and effective user id for the process.
1739 Raises Invalid_argument on Windows
1742 val getgid : unit -> int
1746 Return the group id of the user executing the process.
1748 On Windows: always returns 1 .
1750 val getegid : unit -> int
1754 Return the effective group id under which the process runs.
1756 On Windows: always returns 1 .
1758 val setgid : int -> unit
1762 Set the real group id and effective group id for the process.
1764 Raises Invalid_argument on Windows
1767 val getgroups : unit -> int array
1771 Return the list of groups to which the user executing the process be‐
1773 longs.
1774 On Windows: always returns [|1|] .
1776 val setgroups : int array -> unit
1780 setgroups groups sets the supplementary group IDs for the calling
1783 process. Appropriate privileges are required.
1784 Raises Invalid_argument on Windows
1787 val initgroups : string -> int -> unit
1791 initgroups user group initializes the group access list by reading the
1794 group database /etc/group and using all groups of which user is a mem‐
1795 ber. The additional group group is also added to the list.
1796 Raises Invalid_argument on Windows
1799 type passwd_entry = {
1802 pw_name : string ;
1803 pw_passwd : string ;
1804 pw_uid : int ;
1805 pw_gid : int ;
1806 pw_gecos : string ;
1807 pw_dir : string ;
1808 pw_shell : string ;
1809 }
1810 Structure of entries in the passwd database.
1813 type group_entry = {
1816 gr_name : string ;
1817 gr_passwd : string ;
1818 gr_gid : int ;
1819 gr_mem : string array ;
1820 }
1821 Structure of entries in the groups database.
1824 val getlogin : unit -> string
1828 Return the login name of the user executing the process.
1830 val getpwnam : string -> passwd_entry
1834 Find an entry in passwd with the given name.
1836 Raises Not_found if no such entry exists, or always on Windows.
1839 val getgrnam : string -> group_entry
1843 Find an entry in group with the given name.
1845 Raises Not_found if no such entry exists, or always on Windows.
1848 val getpwuid : int -> passwd_entry
1852 Find an entry in passwd with the given user id.
1854 Raises Not_found if no such entry exists, or always on Windows.
1857 val getgrgid : int -> group_entry
1861 Find an entry in group with the given group id.
1863 Raises Not_found if no such entry exists, or always on Windows.
1866 Internet addresses
1871 type inet_addr
1872 The abstract type of Internet addresses.
1875 val inet_addr_of_string : string -> inet_addr
1879 Conversion from the printable representation of an Internet address to
1881 its internal representation. The argument string consists of 4 numbers
1882 separated by periods ( XXX.YYY.ZZZ.TTT ) for IPv4 addresses, and up to
1883 8 numbers separated by colons for IPv6 addresses.
1884 Raises Failure when given a string that does not match these formats.
1887 val string_of_inet_addr : inet_addr -> string
1891 Return the printable representation of the given Internet address. See
1893 Unix.inet_addr_of_string for a description of the printable representa‐
1894 tion.
1895 val inet_addr_any : inet_addr
1899 A special IPv4 address, for use only with bind , representing all the
1901 Internet addresses that the host machine possesses.
1902 val inet_addr_loopback : inet_addr
1906 A special IPv4 address representing the host machine ( 127.0.0.1 ).
1908 val inet6_addr_any : inet_addr
1912 A special IPv6 address, for use only with bind , representing all the
1914 Internet addresses that the host machine possesses.
1915 val inet6_addr_loopback : inet_addr
1919 A special IPv6 address representing the host machine ( ::1 ).
1921 val is_inet6_addr : inet_addr -> bool
1925 Whether the given inet_addr is an IPv6 address.
1927 Since 4.12.0
1930 Sockets
1935 type socket_domain =
1936 | PF_UNIX (* Unix domain
1937 *)
1938 | PF_INET (* Internet domain (IPv4)
1939 *)
1940 | PF_INET6 (* Internet domain (IPv6)
1941 *)
1942 The type of socket domains. Not all platforms support IPv6 sockets
1945 (type PF_INET6 ).
1946 On Windows: PF_UNIX supported since 4.14.0 on Windows 10 1803 and
1948 later.
1949 type socket_type =
1952 | SOCK_STREAM (* Stream socket
1953 *)
1954 | SOCK_DGRAM (* Datagram socket
1955 *)
1956 | SOCK_RAW (* Raw socket
1957 *)
1958 | SOCK_SEQPACKET (* Sequenced packets socket
1959 *)
1960 The type of socket kinds, specifying the semantics of communications.
1963 SOCK_SEQPACKET is included for completeness, but is rarely supported by
1964 the OS, and needs system calls that are not available in this library.
1965 type sockaddr =
1968 | ADDR_UNIX of string
1969 | ADDR_INET of inet_addr * int
1970 The type of socket addresses. ADDR_UNIX name is a socket address in
1973 the Unix domain; name is a file name in the file system.
1974 ADDR_INET(addr,port) is a socket address in the Internet domain; addr
1975 is the Internet address of the machine, and port is the port number.
1976 val socket : ?cloexec:bool -> socket_domain -> socket_type -> int ->
1980 file_descr
1981 Create a new socket in the given domain, and with the given kind. The
1983 third argument is the protocol type; 0 selects the default protocol for
1984 that kind of sockets. See Unix.set_close_on_exec for documentation on
1985 the cloexec optional argument.
1986 val domain_of_sockaddr : sockaddr -> socket_domain
1990 Return the socket domain adequate for the given socket address.
1992 val socketpair : ?cloexec:bool -> socket_domain -> socket_type -> int
1996 -> file_descr * file_descr
1997 Create a pair of unnamed sockets, connected together. See
1999 Unix.set_close_on_exec for documentation on the cloexec optional argu‐
2000 ment.
2001 val accept : ?cloexec:bool -> file_descr -> file_descr * sockaddr
2005 Accept connections on the given socket. The returned descriptor is a
2007 socket connected to the client; the returned address is the address of
2008 the connecting client. See Unix.set_close_on_exec for documentation on
2009 the cloexec optional argument.
2010 val bind : file_descr -> sockaddr -> unit
2014 Bind a socket to an address.
2016 val connect : file_descr -> sockaddr -> unit
2020 Connect a socket to an address.
2022 val listen : file_descr -> int -> unit
2026 Set up a socket for receiving connection requests. The integer argument
2028 is the maximal number of pending requests.
2029 type shutdown_command =
2032 | SHUTDOWN_RECEIVE (* Close for receiving
2033 *)
2034 | SHUTDOWN_SEND (* Close for sending
2035 *)
2036 | SHUTDOWN_ALL (* Close both
2037 *)
2038 The type of commands for shutdown .
2041 val shutdown : file_descr -> shutdown_command -> unit
2045 Shutdown a socket connection. SHUTDOWN_SEND as second argument causes
2047 reads on the other end of the connection to return an end-of-file con‐
2048 dition. SHUTDOWN_RECEIVE causes writes on the other end of the connec‐
2049 tion to return a closed pipe condition ( SIGPIPE signal).
2050 val getsockname : file_descr -> sockaddr
2054 Return the address of the given socket.
2056 val getpeername : file_descr -> sockaddr
2060 Return the address of the host connected to the given socket.
2062 type msg_flag =
2065 | MSG_OOB
2066 | MSG_DONTROUTE
2067 | MSG_PEEK
2068 The flags for Unix.recv , Unix.recvfrom , Unix.send and Unix.sendto .
2071 val recv : file_descr -> bytes -> int -> int -> msg_flag list -> int
2075 Receive data from a connected socket.
2077 val recvfrom : file_descr -> bytes -> int -> int -> msg_flag list ->
2081 int * sockaddr
2082 Receive data from an unconnected socket.
2084 val send : file_descr -> bytes -> int -> int -> msg_flag list -> int
2088 Send data over a connected socket.
2090 val send_substring : file_descr -> string -> int -> int -> msg_flag
2094 list -> int
2095 Same as send , but take the data from a string instead of a byte se‐
2097 quence.
2098 Since 4.02.0
2101 val sendto : file_descr -> bytes -> int -> int -> msg_flag list ->
2105 sockaddr -> int
2106 Send data over an unconnected socket.
2108 val sendto_substring : file_descr -> string -> int -> int -> msg_flag
2112 list -> sockaddr -> int
2113 Same as sendto , but take the data from a string instead of a byte se‐
2115 quence.
2116 Since 4.02.0
2119 Socket options
2124 type socket_bool_option =
2125 | SO_DEBUG (* Record debugging information
2126 *)
2127 | SO_BROADCAST (* Permit sending of broadcast messages
2128 *)
2129 | SO_REUSEADDR (* Allow reuse of local addresses for bind
2130 *)
2131 | SO_KEEPALIVE (* Keep connection active
2132 *)
2133 | SO_DONTROUTE (* Bypass the standard routing algorithms
2134 *)
2135 | SO_OOBINLINE (* Leave out-of-band data in line
2136 *)
2137 | SO_ACCEPTCONN (* Report whether socket listening is enabled
2138 *)
2139 | TCP_NODELAY (* Control the Nagle algorithm for TCP sockets
2140 *)
2141 | IPV6_ONLY (* Forbid binding an IPv6 socket to an IPv4 address
2142 *)
2143 | SO_REUSEPORT (* Allow reuse of address and port bindings
2144 *)
2145 The socket options that can be consulted with Unix.getsockopt and modi‐
2148 fied with Unix.setsockopt . These options have a boolean ( true /
2149 false ) value.
2150 type socket_int_option =
2153 | SO_SNDBUF (* Size of send buffer
2154 *)
2155 | SO_RCVBUF (* Size of received buffer
2156 *)
2157 | SO_ERROR (* .B "Deprecated." Use Unix.getsockopt_error instead.
2158 Deprecated. Use Unix.getsockopt_error instead.
2161 *)
2162 | SO_TYPE (* Report the socket type
2163 *)
2164 | SO_RCVLOWAT (* Minimum number of bytes to process for input opera‐
2165 tions
2166 *)
2167 | SO_SNDLOWAT (* Minimum number of bytes to process for output opera‐
2168 tions
2169 *)
2170 The socket options that can be consulted with Unix.getsockopt_int and
2173 modified with Unix.setsockopt_int . These options have an integer
2174 value.
2175 type socket_optint_option =
2178 | SO_LINGER (* Whether to linger on closed connections that have data
2179 present, and for how long (in seconds)
2180 *)
2181 The socket options that can be consulted with Unix.getsockopt_optint
2184 and modified with Unix.setsockopt_optint . These options have a value
2185 of type int option , with None meaning ``disabled''.
2186 type socket_float_option =
2189 | SO_RCVTIMEO (* Timeout for input operations
2190 *)
2191 | SO_SNDTIMEO (* Timeout for output operations
2192 *)
2193 The socket options that can be consulted with Unix.getsockopt_float and
2196 modified with Unix.setsockopt_float . These options have a float‐
2197 ing-point value representing a time in seconds. The value 0 means in‐
2198 finite timeout.
2199 val getsockopt : file_descr -> socket_bool_option -> bool
2203 Return the current status of a boolean-valued option in the given
2205 socket.
2206 val setsockopt : file_descr -> socket_bool_option -> bool -> unit
2210 Set or clear a boolean-valued option in the given socket.
2212 val getsockopt_int : file_descr -> socket_int_option -> int
2216 Same as Unix.getsockopt for an integer-valued socket option.
2218 val setsockopt_int : file_descr -> socket_int_option -> int -> unit
2222 Same as Unix.setsockopt for an integer-valued socket option.
2224 val getsockopt_optint : file_descr -> socket_optint_option -> int op‐
2228 tion
2229 Same as Unix.getsockopt for a socket option whose value is an int op‐
2231 tion .
2232 val setsockopt_optint : file_descr -> socket_optint_option -> int op‐
2236 tion -> unit
2237 Same as Unix.setsockopt for a socket option whose value is an int op‐
2239 tion .
2240 val getsockopt_float : file_descr -> socket_float_option -> float
2244 Same as Unix.getsockopt for a socket option whose value is a float‐
2246 ing-point number.
2247 val setsockopt_float : file_descr -> socket_float_option -> float ->
2251 unit
2252 Same as Unix.setsockopt for a socket option whose value is a float‐
2254 ing-point number.
2255 val getsockopt_error : file_descr -> error option
2259 Return the error condition associated with the given socket, and clear
2261 it.
2262 High-level network connection functions
2267 val open_connection : sockaddr -> in_channel * out_channel
2268 Connect to a server at the given address. Return a pair of buffered
2270 channels connected to the server. Remember to call flush on the output
2271 channel at the right times to ensure correct synchronization.
2272 The two channels returned by open_connection share a descriptor to a
2274 socket. Therefore, when the connection is over, you should call
2275 close_out on the output channel, which will also close the underlying
2276 socket. Do not call close_in on the input channel; it will be col‐
2277 lected by the GC eventually.
2278 val shutdown_connection : in_channel -> unit
2282 ``Shut down'' a connection established with Unix.open_connection ; that
2284 is, transmit an end-of-file condition to the server reading on the
2285 other side of the connection. This does not close the socket and the
2286 channels used by the connection. See Unix.open_connection for how to
2287 close them once the connection is over.
2288 val establish_server : (in_channel -> out_channel -> unit) -> sockaddr
2292 -> unit
2293 Establish a server on the given address. The function given as first
2295 argument is called for each connection with two buffered channels con‐
2296 nected to the client. A new process is created for each connection. The
2297 function Unix.establish_server never returns normally.
2298 The two channels given to the function share a descriptor to a socket.
2300 The function does not need to close the channels, since this occurs au‐
2301 tomatically when the function returns. If the function prefers ex‐
2302 plicit closing, it should close the output channel using close_out and
2303 leave the input channel unclosed, for reasons explained in
2304 Unix.in_channel_of_descr .
2305 Raises Invalid_argument on Windows. Use threads instead.
2308 Host and protocol databases
2313 type host_entry = {
2314 h_name : string ;
2315 h_aliases : string array ;
2316 h_addrtype : socket_domain ;
2317 h_addr_list : inet_addr array ;
2318 }
2319 Structure of entries in the hosts database.
2322 type protocol_entry = {
2325 p_name : string ;
2326 p_aliases : string array ;
2327 p_proto : int ;
2328 }
2329 Structure of entries in the protocols database.
2332 type service_entry = {
2335 s_name : string ;
2336 s_aliases : string array ;
2337 s_port : int ;
2338 s_proto : string ;
2339 }
2340 Structure of entries in the services database.
2343 val gethostname : unit -> string
2347 Return the name of the local host.
2349 val gethostbyname : string -> host_entry
2353 Find an entry in hosts with the given name.
2355 Raises Not_found if no such entry exists.
2358 val gethostbyaddr : inet_addr -> host_entry
2362 Find an entry in hosts with the given address.
2364 Raises Not_found if no such entry exists.
2367 val getprotobyname : string -> protocol_entry
2371 Find an entry in protocols with the given name.
2373 Raises Not_found if no such entry exists.
2376 val getprotobynumber : int -> protocol_entry
2380 Find an entry in protocols with the given protocol number.
2382 Raises Not_found if no such entry exists.
2385 val getservbyname : string -> string -> service_entry
2389 Find an entry in services with the given name.
2391 Raises Not_found if no such entry exists.
2394 val getservbyport : int -> string -> service_entry
2398 Find an entry in services with the given service number.
2400 Raises Not_found if no such entry exists.
2403 type addr_info = {
2406 ai_family : socket_domain ; (* Socket domain
2407 *)
2408 ai_socktype : socket_type ; (* Socket type
2409 *)
2410 ai_protocol : int ; (* Socket protocol number
2411 *)
2412 ai_addr : sockaddr ; (* Address
2413 *)
2414 ai_canonname : string ; (* Canonical host name
2415 *)
2416 }
2417 Address information returned by Unix.getaddrinfo .
2420 type getaddrinfo_option =
2423 | AI_FAMILY of socket_domain
2424 (* Impose the given socket domain
2425 *)
2426 | AI_SOCKTYPE of socket_type
2427 (* Impose the given socket type
2428 *)
2429 | AI_PROTOCOL of int
2430 (* Impose the given protocol
2431 *)
2432 | AI_NUMERICHOST (* Do not call name resolver, expect numeric IP ad‐
2433 dress
2434 *)
2435 | AI_CANONNAME (* Fill the ai_canonname field of the result
2436 *)
2437 | AI_PASSIVE (* Set address to ``any'' address for use with Unix.bind
2438 *)
2440 Options to Unix.getaddrinfo .
2443 val getaddrinfo : string -> string -> getaddrinfo_option list ->
2447 addr_info list
2448 getaddrinfo host service opts returns a list of Unix.addr_info records
2451 describing socket parameters and addresses suitable for communicating
2452 with the given host and service. The empty list is returned if the
2453 host or service names are unknown, or the constraints expressed in opts
2454 cannot be satisfied.
2455 host is either a host name or the string representation of an IP ad‐
2458 dress. host can be given as the empty string; in this case, the
2459 ``any'' address or the ``loopback'' address are used, depending whether
2460 opts contains AI_PASSIVE . service is either a service name or the
2461 string representation of a port number. service can be given as the
2462 empty string; in this case, the port field of the returned addresses is
2463 set to 0. opts is a possibly empty list of options that allows the
2464 caller to force a particular socket domain (e.g. IPv6 only or IPv4
2465 only) or a particular socket type (e.g. TCP only or UDP only).
2466 type name_info = {
2469 ni_hostname : string ; (* Name or IP address of host
2470 *)
2471 ni_service : string ; (* Name of service or port number
2472 *)
2473 }
2474 Host and service information returned by Unix.getnameinfo .
2477 type getnameinfo_option =
2480 | NI_NOFQDN (* Do not qualify local host names
2481 *)
2482 | NI_NUMERICHOST (* Always return host as IP address
2483 *)
2484 | NI_NAMEREQD (* Fail if host name cannot be determined
2485 *)
2486 | NI_NUMERICSERV (* Always return service as port number
2487 *)
2488 | NI_DGRAM (* Consider the service as UDP-based instead of the de‐
2489 fault TCP
2490 *)
2491 Options to Unix.getnameinfo .
2494 val getnameinfo : sockaddr -> getnameinfo_option list -> name_info
2498 getnameinfo addr opts returns the host name and service name corre‐
2501 sponding to the socket address addr . opts is a possibly empty list of
2502 options that governs how these names are obtained.
2503 Raises Not_found if an error occurs.
2506 Terminal interface
2511 The following functions implement the POSIX standard terminal inter‐
2512 face. They provide control over asynchronous communication ports and
2513 pseudo-terminals. Refer to the termios man page for a complete descrip‐
2514 tion.
2515 type terminal_io = {
2517 mutable c_ignbrk : bool ; (* Ignore the break condition.
2519 *)
2520 mutable c_brkint : bool ; (* Signal interrupt on break condition.
2522 *)
2523 mutable c_ignpar : bool ; (* Ignore characters with parity errors.
2525 *)
2526 mutable c_parmrk : bool ; (* Mark parity errors.
2528 *)
2529 mutable c_inpck : bool ; (* Enable parity check on input.
2531 *)
2532 mutable c_istrip : bool ; (* Strip 8th bit on input characters.
2534 *)
2535 mutable c_inlcr : bool ; (* Map NL to CR on input.
2537 *)
2538 mutable c_igncr : bool ; (* Ignore CR on input.
2540 *)
2541 mutable c_icrnl : bool ; (* Map CR to NL on input.
2543 *)
2544 mutable c_ixon : bool ; (* Recognize XON/XOFF characters on input.
2546 *)
2547 mutable c_ixoff : bool ; (* Emit XON/XOFF chars to control input flow.
2549 *)
2550 mutable c_opost : bool ; (* Enable output processing.
2552 *)
2553 mutable c_obaud : int ; (* Output baud rate (0 means close connec‐
2555 tion).
2556 *)
2557 mutable c_ibaud : int ; (* Input baud rate.
2559 *)
2560 mutable c_csize : int ; (* Number of bits per character (5-8).
2562 *)
2563 mutable c_cstopb : int ; (* Number of stop bits (1-2).
2565 *)
2566 mutable c_cread : bool ; (* Reception is enabled.
2568 *)
2569 mutable c_parenb : bool ; (* Enable parity generation and detection.
2571 *)
2572 mutable c_parodd : bool ; (* Specify odd parity instead of even.
2574 *)
2575 mutable c_hupcl : bool ; (* Hang up on last close.
2577 *)
2578 mutable c_clocal : bool ; (* Ignore modem status lines.
2580 *)
2581 mutable c_isig : bool ; (* Generate signal on INTR, QUIT, SUSP.
2583 *)
2584 mutable c_icanon : bool ; (* Enable canonical processing (line buffer‐
2586 ing and editing)
2587 *)
2588 mutable c_noflsh : bool ; (* Disable flush after INTR, QUIT, SUSP.
2590 *)
2591 mutable c_echo : bool ; (* Echo input characters.
2593 *)
2594 mutable c_echoe : bool ; (* Echo ERASE (to erase previous character).
2596 *)
2597 mutable c_echok : bool ; (* Echo KILL (to erase the current line).
2599 *)
2600 mutable c_echonl : bool ; (* Echo NL even if c_echo is not set.
2602 *)
2603 mutable c_vintr : char ; (* Interrupt character (usually ctrl-C).
2605 *)
2606 mutable c_vquit : char ; (* Quit character (usually ctrl-\).
2608 *)
2609 mutable c_verase : char ; (* Erase character (usually DEL or ctrl-H).
2611 *)
2612 mutable c_vkill : char ; (* Kill line character (usually ctrl-U).
2614 *)
2615 mutable c_veof : char ; (* End-of-file character (usually ctrl-D).
2617 *)
2618 mutable c_veol : char ; (* Alternate end-of-line char. (usually none).
2620 *)
2621 mutable c_vmin : int ; (* Minimum number of characters to read before
2623 the read request is satisfied.
2624 *)
2625 mutable c_vtime : int ; (* Maximum read wait (in 0.1s units).
2627 *)
2628 mutable c_vstart : char ; (* Start character (usually ctrl-Q).
2630 *)
2631 mutable c_vstop : char ; (* Stop character (usually ctrl-S).
2633 *)
2634 }
2635 val tcgetattr : file_descr -> terminal_io
2641 Return the status of the terminal referred to by the given file de‐
2643 scriptor.
2644 Raises Invalid_argument on Windows
2647 type setattr_when =
2650 | TCSANOW
2651 | TCSADRAIN
2652 | TCSAFLUSH
2653 val tcsetattr : file_descr -> setattr_when -> terminal_io -> unit
2659 Set the status of the terminal referred to by the given file descrip‐
2661 tor. The second argument indicates when the status change takes place:
2662 immediately ( TCSANOW ), when all pending output has been transmitted (
2663 TCSADRAIN ), or after flushing all input that has been received but not
2664 read ( TCSAFLUSH ). TCSADRAIN is recommended when changing the output
2665 parameters; TCSAFLUSH , when changing the input parameters.
2666 Raises Invalid_argument on Windows
2669 val tcsendbreak : file_descr -> int -> unit
2673 Send a break condition on the given file descriptor. The second argu‐
2675 ment is the duration of the break, in 0.1s units; 0 means standard du‐
2676 ration (0.25s).
2677 Raises Invalid_argument on Windows
2680 val tcdrain : file_descr -> unit
2684 Waits until all output written on the given file descriptor has been
2686 transmitted.
2687 Raises Invalid_argument on Windows
2690 type flush_queue =
2693 | TCIFLUSH
2694 | TCOFLUSH
2695 | TCIOFLUSH
2696 val tcflush : file_descr -> flush_queue -> unit
2702 Discard data written on the given file descriptor but not yet transmit‐
2704 ted, or data received but not yet read, depending on the second argu‐
2705 ment: TCIFLUSH flushes data received but not read, TCOFLUSH flushes
2706 data written but not transmitted, and TCIOFLUSH flushes both.
2707 Raises Invalid_argument on Windows
2710 type flow_action =
2713 | TCOOFF
2714 | TCOON
2715 | TCIOFF
2716 | TCION
2717 val tcflow : file_descr -> flow_action -> unit
2723 Suspend or restart reception or transmission of data on the given file
2725 descriptor, depending on the second argument: TCOOFF suspends output,
2726 TCOON restarts output, TCIOFF transmits a STOP character to suspend in‐
2727 put, and TCION transmits a START character to restart input.
2728 Raises Invalid_argument on Windows
2731 val setsid : unit -> int
2735 Put the calling process in a new session and detach it from its con‐
2737 trolling terminal.
2738 Raises Invalid_argument on Windows
2741OCamldoc 2023-07-20 Unix(3)