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 On Windows: not implemented, use Unix.create_process or threads.
343 val wait : unit -> int * process_status
347 Wait until one of the children processes die, and return its pid and
349 termination status.
350 On Windows: not implemented, use Unix.waitpid .
352 val waitpid : wait_flag list -> int -> int * process_status
356 Same as Unix.wait , but waits for the child process whose pid is given.
358 A pid of -1 means wait for any child. A pid of 0 means wait for any
359 child in the same process group as the current process. Negative pid
360 arguments represent process groups. The list of options indicates
361 whether waitpid should return immediately without waiting, and whether
362 it should report stopped children.
363 On Windows: can only wait for a given PID, not any child process.
365 val system : string -> process_status
369 Execute the given command, wait until it terminates, and return its
371 termination status. The string is interpreted by the shell /bin/sh (or
372 the command interpreter cmd.exe on Windows) and therefore can contain
373 redirections, quotes, variables, etc. To properly quote whitespace and
374 shell special characters occurring in file names or command arguments,
375 the use of Filename.quote_command is recommended. The result WEXITED
376 127 indicates that the shell couldn't be executed.
377 val _exit : int -> 'a
381 Terminate the calling process immediately, returning the given status
383 code to the operating system: usually 0 to indicate no errors, and a
384 small positive integer to indicate failure. Unlike exit , Unix._exit
385 performs no finalization whatsoever: functions registered with at_exit
386 are not called, input/output channels are not flushed, and the C
387 run-time system is not finalized either.
388 The typical use of Unix._exit is after a Unix.fork operation, when the
390 child process runs into a fatal error and must exit. In this case, it
391 is preferable to not perform any finalization action in the child
392 process, as these actions could interfere with similar actions per‐
393 formed by the parent process. For example, output channels should not
394 be flushed by the child process, as the parent process may flush them
395 again later, resulting in duplicate output.
396 Since 4.12.0
399 val getpid : unit -> int
403 Return the pid of the process.
405 val getppid : unit -> int
409 Return the pid of the parent process.
411 On Windows: not implemented (because it is meaningless).
413 val nice : int -> int
417 Change the process priority. The integer argument is added to the
419 ``nice'' value. (Higher values of the ``nice'' value mean lower priori‐
420 ties.) Return the new nice value.
421 On Windows: not implemented.
423 Basic file input/output
428 type file_descr
429 The abstract type of file descriptors.
432 val stdin : file_descr
436 File descriptor for standard input.
438 val stdout : file_descr
442 File descriptor for standard output.
444 val stderr : file_descr
448 File descriptor for standard error.
450 type open_flag =
453 | O_RDONLY (* Open for reading
454 *)
455 | O_WRONLY (* Open for writing
456 *)
457 | O_RDWR (* Open for reading and writing
458 *)
459 | O_NONBLOCK (* Open in non-blocking mode
460 *)
461 | O_APPEND (* Open for append
462 *)
463 | O_CREAT (* Create if nonexistent
464 *)
465 | O_TRUNC (* Truncate to 0 length if existing
466 *)
467 | O_EXCL (* Fail if existing
468 *)
469 | O_NOCTTY (* Don't make this dev a controlling tty
470 *)
471 | O_DSYNC (* Writes complete as `Synchronised I/O data integrity com‐
472 pletion'
473 *)
474 | O_SYNC (* Writes complete as `Synchronised I/O file integrity com‐
475 pletion'
476 *)
477 | O_RSYNC (* Reads complete as writes (depending on O_SYNC/O_DSYNC)
478 *)
479 | O_SHARE_DELETE (* Windows only: allow the file to be deleted while
480 still open
481 *)
482 | O_CLOEXEC (* Set the close-on-exec flag on the descriptor returned
483 by Unix.openfile . See Unix.set_close_on_exec for more information.
484 *)
485 | O_KEEPEXEC (* Clear the close-on-exec flag. This is currently the
486 default.
487 *)
488 The flags to Unix.openfile .
491 type file_perm = int
494 The type of file access rights, e.g. 0o640 is read and write for user,
497 read for group, none for others
498 val openfile : string -> open_flag list -> file_perm -> file_descr
502 Open the named file with the given flags. Third argument is the permis‐
504 sions to give to the file if it is created (see Unix.umask ). Return a
505 file descriptor on the named file.
506 val close : file_descr -> unit
510 Close a file descriptor.
512 val fsync : file_descr -> unit
516 Flush file buffers to disk.
518 Since 4.08.0 (4.12.0 in UnixLabels)
521 val read : file_descr -> bytes -> int -> int -> int
525 read fd buf pos len reads len bytes from descriptor fd , storing them
528 in byte sequence buf , starting at position pos in buf . Return the
529 number of bytes actually read.
530 val write : file_descr -> bytes -> int -> int -> int
534 write fd buf pos len writes len bytes to descriptor fd , taking them
537 from byte sequence buf , starting at position pos in buff . Return the
538 number of bytes actually written. write repeats the writing operation
539 until all bytes have been written or an error occurs.
540 val single_write : file_descr -> bytes -> int -> int -> int
544 Same as Unix.write , but attempts to write only once. Thus, if an er‐
546 ror occurs, single_write guarantees that no data has been written.
547 val write_substring : file_descr -> string -> int -> int -> int
551 Same as Unix.write , but take the data from a string instead of a byte
553 sequence.
554 Since 4.02.0
557 val single_write_substring : file_descr -> string -> int -> int -> int
561 Same as Unix.single_write , but take the data from a string instead of
563 a byte sequence.
564 Since 4.02.0
567 Interfacing with the standard input/output library
572 val in_channel_of_descr : file_descr -> in_channel
573 Create an input channel reading from the given descriptor. The channel
575 is initially in binary mode; use set_binary_mode_in ic false if text
576 mode is desired. Text mode is supported only if the descriptor refers
577 to a file or pipe, but is not supported if it refers to a socket.
578 On Windows: set_binary_mode_in always fails on channels created with
580 this function.
581 Beware that channels are buffered so more characters may have been read
583 from the file descriptor than those accessed using channel functions.
584 Channels also keep a copy of the current position in the file.
585 You need to explicitly close all channels created with this function.
587 Closing the channel also closes the underlying file descriptor (unless
588 it was already closed).
589 val out_channel_of_descr : file_descr -> out_channel
593 Create an output channel writing on the given descriptor. The channel
595 is initially in binary mode; use set_binary_mode_out oc false if text
596 mode is desired. Text mode is supported only if the descriptor refers
597 to a file or pipe, but is not supported if it refers to a socket.
598 On Windows: set_binary_mode_out always fails on channels created with
600 this function.
601 Beware that channels are buffered so you may have to flush them to en‐
603 sure that all data has been sent to the file descriptor. Channels also
604 keep a copy of the current position in the file.
605 You need to explicitly close all channels created with this function.
607 Closing the channel flushes the data and closes the underlying file de‐
608 scriptor (unless it has already been closed, in which case the buffered
609 data is lost).
610 val descr_of_in_channel : in_channel -> file_descr
614 Return the descriptor corresponding to an input channel.
616 val descr_of_out_channel : out_channel -> file_descr
620 Return the descriptor corresponding to an output channel.
622 Seeking and truncating
627 type seek_command =
628 | SEEK_SET (* indicates positions relative to the beginning of the
629 file
630 *)
631 | SEEK_CUR (* indicates positions relative to the current position
632 *)
633 | SEEK_END (* indicates positions relative to the end of the file
634 *)
635 Positioning modes for Unix.lseek .
638 val lseek : file_descr -> int -> seek_command -> int
642 Set the current position for a file descriptor, and return the result‐
644 ing offset (from the beginning of the file).
645 val truncate : string -> int -> unit
649 Truncates the named file to the given size.
651 val ftruncate : file_descr -> int -> unit
655 Truncates the file corresponding to the given descriptor to the given
657 size.
658 File status
663 type file_kind =
664 | S_REG (* Regular file
665 *)
666 | S_DIR (* Directory
667 *)
668 | S_CHR (* Character device
669 *)
670 | S_BLK (* Block device
671 *)
672 | S_LNK (* Symbolic link
673 *)
674 | S_FIFO (* Named pipe
675 *)
676 | S_SOCK (* Socket
677 *)
678 type stats = {
683 st_dev : int ; (* Device number
684 *)
685 st_ino : int ; (* Inode number
686 *)
687 st_kind : file_kind ; (* Kind of the file
688 *)
689 st_perm : file_perm ; (* Access rights
690 *)
691 st_nlink : int ; (* Number of links
692 *)
693 st_uid : int ; (* User id of the owner
694 *)
695 st_gid : int ; (* Group ID of the file's group
696 *)
697 st_rdev : int ; (* Device ID (if special file)
698 *)
699 st_size : int ; (* Size in bytes
700 *)
701 st_atime : float ; (* Last access time
702 *)
703 st_mtime : float ; (* Last modification time
704 *)
705 st_ctime : float ; (* Last status change time
706 *)
707 }
708 The information returned by the Unix.stat calls.
711 val stat : string -> stats
715 Return the information for the named file.
717 val lstat : string -> stats
721 Same as Unix.stat , but in case the file is a symbolic link, return the
723 information for the link itself.
724 val fstat : file_descr -> stats
728 Return the information for the file associated with the given descrip‐
730 tor.
731 val isatty : file_descr -> bool
735 Return true if the given file descriptor refers to a terminal or con‐
737 sole window, false otherwise.
738 File operations on large files
743 module LargeFile : sig end
744 File operations on large files. This sub-module provides 64-bit vari‐
747 ants of the functions Unix.LargeFile.lseek (for positioning a file de‐
748 scriptor), Unix.LargeFile.truncate and Unix.LargeFile.ftruncate (for
749 changing the size of a file), and Unix.LargeFile.stat , Unix.Large‐
750 File.lstat and Unix.LargeFile.fstat (for obtaining information on
751 files). These alternate functions represent positions and sizes by
752 64-bit integers (type int64 ) instead of regular integers (type int ),
753 thus allowing operating on files whose sizes are greater than max_int .
754 Mapping files into memory
759 val map_file : file_descr -> ?pos:int64 -> ('a, 'b) Bigarray.kind -> 'c
760 Bigarray.layout -> bool -> int array -> ('a, 'b, 'c) Bigarray.Genar‐
761 ray.t
762 Memory mapping of a file as a Bigarray. map_file fd kind layout shared
764 dims returns a Bigarray of kind kind , layout layout , and dimensions
765 as specified in dims . The data contained in this Bigarray are the
766 contents of the file referred to by the file descriptor fd (as opened
767 previously with Unix.openfile , for example). The optional pos parame‐
768 ter is the byte offset in the file of the data being mapped; it de‐
769 faults to 0 (map from the beginning of the file).
770 If shared is true , all modifications performed on the array are re‐
772 flected in the file. This requires that fd be opened with write per‐
773 missions. If shared is false , modifications performed on the array
774 are done in memory only, using copy-on-write of the modified pages; the
775 underlying file is not affected.
776 Genarray.map_file is much more efficient than reading the whole file in
779 a Bigarray, modifying that Bigarray, and writing it afterwards.
780 To adjust automatically the dimensions of the Bigarray to the actual
782 size of the file, the major dimension (that is, the first dimension for
783 an array with C layout, and the last dimension for an array with For‐
784 tran layout) can be given as -1 . Genarray.map_file then determines
785 the major dimension from the size of the file. The file must contain
786 an integral number of sub-arrays as determined by the non-major dimen‐
787 sions, otherwise Failure is raised.
788 If all dimensions of the Bigarray are given, the file size is matched
790 against the size of the Bigarray. If the file is larger than the Bi‐
791 garray, only the initial portion of the file is mapped to the Bigarray.
792 If the file is smaller than the big array, the file is automatically
793 grown to the size of the Bigarray. This requires write permissions on
794 fd .
795 Array accesses are bounds-checked, but the bounds are determined by the
797 initial call to map_file . Therefore, you should make sure no other
798 process modifies the mapped file while you're accessing it, or a SIGBUS
799 signal may be raised. This happens, for instance, if the file is
800 shrunk.
801 Invalid_argument or Failure may be raised in cases where argument vali‐
804 dation fails.
805 Since 4.06.0
808 Operations on file names
813 val unlink : string -> unit
814 Removes the named file.
816 If the named file is a directory, raises:
818 - EPERM on POSIX compliant system
820 - EISDIR on Linux >= 2.1.132
822 - EACCESS on Windows
824 val rename : string -> string -> unit
829 rename src dst changes the name of a file from src to dst , moving it
832 between directories if needed. If dst already exists, its contents
833 will be replaced with those of src . Depending on the operating sys‐
834 tem, the metadata (permissions, owner, etc) of dst can either be pre‐
835 served or be replaced by those of src .
836 val link : ?follow:bool -> string -> string -> unit
840 link ?follow src dst creates a hard link named dst to the file named
843 src .
844 Raises ENOSYS On Unix if ~follow:_ is requested, but linkat is unavail‐
847 able.
848 Raises ENOSYS On Windows if ~follow:false is requested.
851 File permissions and ownership
856 type access_permission =
857 | R_OK (* Read permission
858 *)
859 | W_OK (* Write permission
860 *)
861 | X_OK (* Execution permission
862 *)
863 | F_OK (* File exists
864 *)
865 Flags for the Unix.access call.
868 val chmod : string -> file_perm -> unit
872 Change the permissions of the named file.
874 val fchmod : file_descr -> file_perm -> unit
878 Change the permissions of an opened file.
880 On Windows: not implemented.
882 val chown : string -> int -> int -> unit
886 Change the owner uid and owner gid of the named file.
888 On Windows: not implemented.
890 val fchown : file_descr -> int -> int -> unit
894 Change the owner uid and owner gid of an opened file.
896 On Windows: not implemented.
898 val umask : int -> int
902 Set the process's file mode creation mask, and return the previous
904 mask.
905 On Windows: not implemented.
907 val access : string -> access_permission list -> unit
911 Check that the process has the given permissions over the named file.
913 On Windows: execute permission X_OK cannot be tested, just tests for
915 read permission instead.
916 Raises Unix_error otherwise.
919 Operations on file descriptors
924 val dup : ?cloexec:bool -> file_descr -> file_descr
925 Return a new file descriptor referencing the same file as the given de‐
927 scriptor. See Unix.set_close_on_exec for documentation on the cloexec
928 optional argument.
929 val dup2 : ?cloexec:bool -> file_descr -> file_descr -> unit
933 dup2 src dst duplicates src to dst , closing dst if already opened.
936 See Unix.set_close_on_exec for documentation on the cloexec optional
937 argument.
938 val set_nonblock : file_descr -> unit
942 Set the ``non-blocking'' flag on the given descriptor. When the
944 non-blocking flag is set, reading on a descriptor on which there is
945 temporarily no data available raises the EAGAIN or EWOULDBLOCK error
946 instead of blocking; writing on a descriptor on which there is tempo‐
947 rarily no room for writing also raises EAGAIN or EWOULDBLOCK .
948 val clear_nonblock : file_descr -> unit
952 Clear the ``non-blocking'' flag on the given descriptor. See
954 Unix.set_nonblock .
955 val set_close_on_exec : file_descr -> unit
959 Set the ``close-on-exec'' flag on the given descriptor. A descriptor
961 with the close-on-exec flag is automatically closed when the current
962 process starts another program with one of the exec , create_process
963 and open_process functions.
964 It is often a security hole to leak file descriptors opened on, say, a
966 private file to an external program: the program, then, gets access to
967 the private file and can do bad things with it. Hence, it is highly
968 recommended to set all file descriptors ``close-on-exec'', except in
969 the very few cases where a file descriptor actually needs to be trans‐
970 mitted to another program.
971 The best way to set a file descriptor ``close-on-exec'' is to create it
973 in this state. To this end, the openfile function has O_CLOEXEC and
974 O_KEEPEXEC flags to enforce ``close-on-exec'' mode or ``keep-on-exec''
975 mode, respectively. All other operations in the Unix module that cre‐
976 ate file descriptors have an optional argument ?cloexec:bool to indi‐
977 cate whether the file descriptor should be created in ``close-on-exec''
978 mode (by writing ~cloexec:true ) or in ``keep-on-exec'' mode (by writ‐
979 ing ~cloexec:false ). For historical reasons, the default file de‐
980 scriptor creation mode is ``keep-on-exec'', if no cloexec optional ar‐
981 gument is given. This is not a safe default, hence it is highly recom‐
982 mended to pass explicit cloexec arguments to operations that create
983 file descriptors.
984 The cloexec optional arguments and the O_KEEPEXEC flag were introduced
986 in OCaml 4.05. Earlier, the common practice was to create file de‐
987 scriptors in the default, ``keep-on-exec'' mode, then call
988 set_close_on_exec on those freshly-created file descriptors. This is
989 not as safe as creating the file descriptor in ``close-on-exec'' mode
990 because, in multithreaded programs, a window of vulnerability exists
991 between the time when the file descriptor is created and the time
992 set_close_on_exec completes. If another thread spawns another program
993 during this window, the descriptor will leak, as it is still in the
994 ``keep-on-exec'' mode.
995 Regarding the atomicity guarantees given by ~cloexec:true or by the use
997 of the O_CLOEXEC flag: on all platforms it is guaranteed that a concur‐
998 rently-executing Caml thread cannot leak the descriptor by starting a
999 new process. On Linux, this guarantee extends to concurrently-execut‐
1000 ing C threads. As of Feb 2017, other operating systems lack the neces‐
1001 sary system calls and still expose a window of vulnerability during
1002 which a C thread can see the newly-created file descriptor in
1003 ``keep-on-exec'' mode.
1004 val clear_close_on_exec : file_descr -> unit
1008 Clear the ``close-on-exec'' flag on the given descriptor. See
1010 Unix.set_close_on_exec .
1011 Directories
1016 val mkdir : string -> file_perm -> unit
1017 Create a directory with the given permissions (see Unix.umask ).
1019 val rmdir : string -> unit
1023 Remove an empty directory.
1025 val chdir : string -> unit
1029 Change the process working directory.
1031 val getcwd : unit -> string
1035 Return the name of the current working directory.
1037 val chroot : string -> unit
1041 Change the process root directory.
1043 On Windows: not implemented.
1045 type dir_handle
1048 The type of descriptors over opened directories.
1051 val opendir : string -> dir_handle
1055 Open a descriptor on a directory
1057 val readdir : dir_handle -> string
1061 Return the next entry in a directory.
1063 Raises End_of_file when the end of the directory has been reached.
1066 val rewinddir : dir_handle -> unit
1070 Reposition the descriptor to the beginning of the directory
1072 val closedir : dir_handle -> unit
1076 Close a directory descriptor.
1078 Pipes and redirections
1083 val pipe : ?cloexec:bool -> unit -> file_descr * file_descr
1084 Create a pipe. The first component of the result is opened for reading,
1086 that's the exit to the pipe. The second component is opened for writ‐
1087 ing, that's the entrance to the pipe. See Unix.set_close_on_exec for
1088 documentation on the cloexec optional argument.
1089 val mkfifo : string -> file_perm -> unit
1093 Create a named pipe with the given permissions (see Unix.umask ).
1095 On Windows: not implemented.
1097 High-level process and redirection management
1102 val create_process : string -> string array -> file_descr -> file_descr
1103 -> file_descr -> int
1104 create_process prog args stdin stdout stderr forks a new process that
1107 executes the program in file prog , with arguments args . The pid of
1108 the new process is returned immediately; the new process executes con‐
1109 currently with the current process. The standard input and outputs of
1110 the new process are connected to the descriptors stdin , stdout and
1111 stderr . Passing e.g. Stdlib.stdout for stdout prevents the redirect‐
1112 ion and causes the new process to have the same standard output as the
1113 current process. The executable file prog is searched in the path.
1114 The new process has the same environment as the current process.
1115 val create_process_env : string -> string array -> string array ->
1119 file_descr -> file_descr -> file_descr -> int
1120 create_process_env prog args env stdin stdout stderr works as Unix.cre‐
1123 ate_process , except that the extra argument env specifies the environ‐
1124 ment passed to the program.
1125 val open_process_in : string -> in_channel
1129 High-level pipe and process management. This function runs the given
1131 command in parallel with the program. The standard output of the com‐
1132 mand is redirected to a pipe, which can be read via the returned input
1133 channel. The command is interpreted by the shell /bin/sh (or cmd.exe
1134 on Windows), cf. Unix.system . The Filename.quote_command function
1135 can be used to quote the command and its arguments as appropriate for
1136 the shell being used. If the command does not need to be run through
1137 the shell, Unix.open_process_args_in can be used as a more robust and
1138 more efficient alternative to Unix.open_process_in .
1139 val open_process_out : string -> out_channel
1143 Same as Unix.open_process_in , but redirect the standard input of the
1145 command to a pipe. Data written to the returned output channel is sent
1146 to the standard input of the command. Warning: writes on output chan‐
1147 nels are buffered, hence be careful to call flush at the right times to
1148 ensure correct synchronization. If the command does not need to be run
1149 through the shell, Unix.open_process_args_out can be used instead of
1150 Unix.open_process_out .
1151 val open_process : string -> in_channel * out_channel
1155 Same as Unix.open_process_out , but redirects both the standard input
1157 and standard output of the command to pipes connected to the two re‐
1158 turned channels. The input channel is connected to the output of the
1159 command, and the output channel to the input of the command. If the
1160 command does not need to be run through the shell,
1161 Unix.open_process_args can be used instead of Unix.open_process .
1162 val open_process_full : string -> string array -> in_channel *
1166 out_channel * in_channel
1167 Similar to Unix.open_process , but the second argument specifies the
1169 environment passed to the command. The result is a triple of channels
1170 connected respectively to the standard output, standard input, and
1171 standard error of the command. If the command does not need to be run
1172 through the shell, Unix.open_process_args_full can be used instead of
1173 Unix.open_process_full .
1174 val open_process_args_in : string -> string array -> in_channel
1178 High-level pipe and process management. The first argument specifies
1180 the command to run, and the second argument specifies the argument ar‐
1181 ray passed to the command. This function runs the command in parallel
1182 with the program. The standard output of the command is redirected to
1183 a pipe, which can be read via the returned input channel.
1184 Since 4.08.0
1187 val open_process_args_out : string -> string array -> out_channel
1191 Same as Unix.open_process_args_in , but redirect the standard input of
1193 the command to a pipe. Data written to the returned output channel is
1194 sent to the standard input of the command. Warning: writes on output
1195 channels are buffered, hence be careful to call flush at the right
1196 times to ensure correct synchronization.
1197 Since 4.08.0
1200 val open_process_args : string -> string array -> in_channel *
1204 out_channel
1205 Same as Unix.open_process_args_out , but redirects both the standard
1207 input and standard output of the command to pipes connected to the two
1208 returned channels. The input channel is connected to the output of the
1209 command, and the output channel to the input of the command.
1210 Since 4.08.0
1213 val open_process_args_full : string -> string array -> string array ->
1217 in_channel * out_channel * in_channel
1218 Similar to Unix.open_process_args , but the third argument specifies
1220 the environment passed to the command. The result is a triple of chan‐
1221 nels connected respectively to the standard output, standard input, and
1222 standard error of the command.
1223 Since 4.08.0
1226 val process_in_pid : in_channel -> int
1230 Return the pid of a process opened via Unix.open_process_in or
1232 Unix.open_process_args_in .
1233 Since 4.08.0 (4.12.0 in UnixLabels)
1236 val process_out_pid : out_channel -> int
1240 Return the pid of a process opened via Unix.open_process_out or
1242 Unix.open_process_args_out .
1243 Since 4.08.0 (4.12.0 in UnixLabels)
1246 val process_pid : in_channel * out_channel -> int
1250 Return the pid of a process opened via Unix.open_process or
1252 Unix.open_process_args .
1253 Since 4.08.0 (4.12.0 in UnixLabels)
1256 val process_full_pid : in_channel * out_channel * in_channel -> int
1260 Return the pid of a process opened via Unix.open_process_full or
1262 Unix.open_process_args_full .
1263 Since 4.08.0 (4.12.0 in UnixLabels)
1266 val close_process_in : in_channel -> process_status
1270 Close channels opened by Unix.open_process_in , wait for the associated
1272 command to terminate, and return its termination status.
1273 val close_process_out : out_channel -> process_status
1277 Close channels opened by Unix.open_process_out , wait for the associ‐
1279 ated command to terminate, and return its termination status.
1280 val close_process : in_channel * out_channel -> process_status
1284 Close channels opened by Unix.open_process , wait for the associated
1286 command to terminate, and return its termination status.
1287 val close_process_full : in_channel * out_channel * in_channel ->
1291 process_status
1292 Close channels opened by Unix.open_process_full , wait for the associ‐
1294 ated command to terminate, and return its termination status.
1295 Symbolic links
1300 val symlink : ?to_dir:bool -> string -> string -> unit
1301 symlink ?to_dir src dst creates the file dst as a symbolic link to the
1304 file src . On Windows, to_dir indicates if the symbolic link points to
1305 a directory or a file; if omitted, symlink examines src using stat and
1306 picks appropriately, if src does not exist then false is assumed (for
1307 this reason, it is recommended that the to_dir parameter be specified
1308 in new code). On Unix, to_dir is ignored.
1309 Windows symbolic links are available in Windows Vista onwards. There
1311 are some important differences between Windows symlinks and their POSIX
1312 counterparts.
1313 Windows symbolic links come in two flavours: directory and regular,
1315 which designate whether the symbolic link points to a directory or a
1316 file. The type must be correct - a directory symlink which actually
1317 points to a file cannot be selected with chdir and a file symlink which
1318 actually points to a directory cannot be read or written (note that
1319 Cygwin's emulation layer ignores this distinction).
1320 When symbolic links are created to existing targets, this distinction
1322 doesn't matter and symlink will automatically create the correct kind
1323 of symbolic link. The distinction matters when a symbolic link is cre‐
1324 ated to a non-existent target.
1325 The other caveat is that by default symbolic links are a privileged op‐
1327 eration. Administrators will always need to be running elevated (or
1328 with UAC disabled) and by default normal user accounts need to be
1329 granted the SeCreateSymbolicLinkPrivilege via Local Security Policy
1330 (secpol.msc) or via Active Directory.
1331 Unix.has_symlink can be used to check that a process is able to create
1334 symbolic links.
1335 val has_symlink : unit -> bool
1339 Returns true if the user is able to create symbolic links. On Windows,
1341 this indicates that the user not only has the SeCreateSymbolicLinkPriv‐
1342 ilege but is also running elevated, if necessary. On other platforms,
1343 this is simply indicates that the symlink system call is available.
1344 Since 4.03.0
1347 val readlink : string -> string
1351 Read the contents of a symbolic link.
1353 Polling
1358 val select : file_descr list -> file_descr list -> file_descr list ->
1359 float -> file_descr list * file_descr list * file_descr list
1360 Wait until some input/output operations become possible on some chan‐
1362 nels. The three list arguments are, respectively, a set of descriptors
1363 to check for reading (first argument), for writing (second argument),
1364 or for exceptional conditions (third argument). The fourth argument is
1365 the maximal timeout, in seconds; a negative fourth argument means no
1366 timeout (unbounded wait). The result is composed of three sets of de‐
1367 scriptors: those ready for reading (first component), ready for writing
1368 (second component), and over which an exceptional condition is pending
1369 (third component).
1370 Locking
1375 type lock_command =
1376 | F_ULOCK (* Unlock a region
1377 *)
1378 | F_LOCK (* Lock a region for writing, and block if already locked
1379 *)
1380 | F_TLOCK (* Lock a region for writing, or fail if already locked
1381 *)
1382 | F_TEST (* Test a region for other process locks
1383 *)
1384 | F_RLOCK (* Lock a region for reading, and block if already locked
1385 *)
1386 | F_TRLOCK (* Lock a region for reading, or fail if already locked
1387 *)
1388 Commands for Unix.lockf .
1391 val lockf : file_descr -> lock_command -> int -> unit
1395 lockf fd mode len puts a lock on a region of the file opened as fd .
1398 The region starts at the current read/write position for fd (as set by
1399 Unix.lseek ), and extends len bytes forward if len is positive, len
1400 bytes backwards if len is negative, or to the end of the file if len is
1401 zero. A write lock prevents any other process from acquiring a read or
1402 write lock on the region. A read lock prevents any other process from
1403 acquiring a write lock on the region, but lets other processes acquire
1404 read locks on it.
1405 The F_LOCK and F_TLOCK commands attempts to put a write lock on the
1407 specified region. The F_RLOCK and F_TRLOCK commands attempts to put a
1408 read lock on the specified region. If one or several locks put by an‐
1409 other process prevent the current process from acquiring the lock,
1410 F_LOCK and F_RLOCK block until these locks are removed, while F_TLOCK
1411 and F_TRLOCK fail immediately with an exception. The F_ULOCK removes
1412 whatever locks the current process has on the specified region. Fi‐
1413 nally, the F_TEST command tests whether a write lock can be acquired on
1414 the specified region, without actually putting a lock. It returns im‐
1415 mediately if successful, or fails otherwise.
1416 What happens when a process tries to lock a region of a file that is
1418 already locked by the same process depends on the OS. On POSIX-compli‐
1419 ant systems, the second lock operation succeeds and may "promote" the
1420 older lock from read lock to write lock. On Windows, the second lock
1421 operation will block or fail.
1422 Signals
1427 Note: installation of signal handlers is performed via the functions
1428 Sys.signal and Sys.set_signal .
1429 val kill : int -> int -> unit
1431 kill pid signal sends signal number signal to the process with id pid .
1434 On Windows: only the Sys.sigkill signal is emulated.
1436 type sigprocmask_command =
1439 | SIG_SETMASK
1440 | SIG_BLOCK
1441 | SIG_UNBLOCK
1442 val sigprocmask : sigprocmask_command -> int list -> int list
1448 sigprocmask mode sigs changes the set of blocked signals. If mode is
1451 SIG_SETMASK , blocked signals are set to those in the list sigs . If
1452 mode is SIG_BLOCK , the signals in sigs are added to the set of blocked
1453 signals. If mode is SIG_UNBLOCK , the signals in sigs are removed from
1454 the set of blocked signals. sigprocmask returns the set of previously
1455 blocked signals.
1456 When the systhreads version of the Thread module is loaded, this func‐
1458 tion redirects to Thread.sigmask . I.e., sigprocmask only changes the
1459 mask of the current thread.
1460 On Windows: not implemented (no inter-process signals on Windows).
1462 val sigpending : unit -> int list
1466 Return the set of blocked signals that are currently pending.
1468 On Windows: not implemented (no inter-process signals on Windows).
1470 val sigsuspend : int list -> unit
1474 sigsuspend sigs atomically sets the blocked signals to sigs and waits
1477 for a non-ignored, non-blocked signal to be delivered. On return, the
1478 blocked signals are reset to their initial value.
1479 On Windows: not implemented (no inter-process signals on Windows).
1481 val pause : unit -> unit
1485 Wait until a non-ignored, non-blocked signal is delivered.
1487 On Windows: not implemented (no inter-process signals on Windows).
1489 Time functions
1494 type process_times = {
1495 tms_utime : float ; (* User time for the process
1496 *)
1497 tms_stime : float ; (* System time for the process
1498 *)
1499 tms_cutime : float ; (* User time for the children processes
1500 *)
1501 tms_cstime : float ; (* System time for the children processes
1502 *)
1503 }
1504 The execution times (CPU times) of a process.
1507 type tm = {
1510 tm_sec : int ; (* Seconds 0..60
1511 *)
1512 tm_min : int ; (* Minutes 0..59
1513 *)
1514 tm_hour : int ; (* Hours 0..23
1515 *)
1516 tm_mday : int ; (* Day of month 1..31
1517 *)
1518 tm_mon : int ; (* Month of year 0..11
1519 *)
1520 tm_year : int ; (* Year - 1900
1521 *)
1522 tm_wday : int ; (* Day of week (Sunday is 0)
1523 *)
1524 tm_yday : int ; (* Day of year 0..365
1525 *)
1526 tm_isdst : bool ; (* Daylight time savings in effect
1527 *)
1528 }
1529 The type representing wallclock time and calendar date.
1532 val time : unit -> float
1536 Return the current time since 00:00:00 GMT, Jan. 1, 1970, in seconds.
1538 val gettimeofday : unit -> float
1542 Same as Unix.time , but with resolution better than 1 second.
1544 val gmtime : float -> tm
1548 Convert a time in seconds, as returned by Unix.time , into a date and a
1550 time. Assumes UTC (Coordinated Universal Time), also known as GMT. To
1551 perform the inverse conversion, set the TZ environment variable to
1552 "UTC", use Unix.mktime , and then restore the original value of TZ.
1553 val localtime : float -> tm
1557 Convert a time in seconds, as returned by Unix.time , into a date and a
1559 time. Assumes the local time zone. The function performing the inverse
1560 conversion is Unix.mktime .
1561 val mktime : tm -> float * tm
1565 Convert a date and time, specified by the tm argument, into a time in
1567 seconds, as returned by Unix.time . The tm_isdst , tm_wday and tm_yday
1568 fields of tm are ignored. Also return a normalized copy of the given
1569 tm record, with the tm_wday , tm_yday , and tm_isdst fields recomputed
1570 from the other fields, and the other fields normalized (so that, e.g.,
1571 40 October is changed into 9 November). The tm argument is interpreted
1572 in the local time zone.
1573 val alarm : int -> int
1577 Schedule a SIGALRM signal after the given number of seconds.
1579 On Windows: not implemented.
1581 val sleep : int -> unit
1585 Stop execution for the given number of seconds.
1587 val sleepf : float -> unit
1591 Stop execution for the given number of seconds. Like sleep , but frac‐
1593 tions of seconds are supported.
1594 Since 4.03.0 (4.12.0 in UnixLabels)
1597 val times : unit -> process_times
1601 Return the execution times of the process.
1603 On Windows: partially implemented, will not report timings for child
1605 processes.
1606 val utimes : string -> float -> float -> unit
1610 Set the last access time (second arg) and last modification time (third
1612 arg) for a file. Times are expressed in seconds from 00:00:00 GMT, Jan.
1613 1, 1970. If both times are 0.0 , the access and last modification
1614 times are both set to the current time.
1615 type interval_timer =
1618 | ITIMER_REAL (* decrements in real time, and sends the signal
1619 SIGALRM when expired.
1620 *)
1621 | ITIMER_VIRTUAL (* decrements in process virtual time, and sends
1622 SIGVTALRM when expired.
1623 *)
1624 | ITIMER_PROF (* (for profiling) decrements both when the process is
1625 running and when the system is running on behalf of the process; it
1626 sends SIGPROF when expired.
1627 *)
1628 The three kinds of interval timers.
1631 type interval_timer_status = {
1634 it_interval : float ; (* Period
1635 *)
1636 it_value : float ; (* Current value of the timer
1637 *)
1638 }
1639 The type describing the status of an interval timer
1642 val getitimer : interval_timer -> interval_timer_status
1646 Return the current status of the given interval timer.
1648 On Windows: not implemented.
1650 val setitimer : interval_timer -> interval_timer_status -> inter‐
1654 val_timer_status
1655 setitimer t s sets the interval timer t and returns its previous sta‐
1658 tus. The s argument is interpreted as follows: s.it_value , if nonzero,
1659 is the time to the next timer expiration; s.it_interval , if nonzero,
1660 specifies a value to be used in reloading it_value when the timer ex‐
1661 pires. Setting s.it_value to zero disables the timer. Setting
1662 s.it_interval to zero causes the timer to be disabled after its next
1663 expiration.
1664 On Windows: not implemented.
1666 User id, group id
1671 val getuid : unit -> int
1672 Return the user id of the user executing the process.
1674 On Windows: always returns 1 .
1676 val geteuid : unit -> int
1680 Return the effective user id under which the process runs.
1682 On Windows: always returns 1 .
1684 val setuid : int -> unit
1688 Set the real user id and effective user id for the process.
1690 On Windows: not implemented.
1692 val getgid : unit -> int
1696 Return the group id of the user executing the process.
1698 On Windows: always returns 1 .
1700 val getegid : unit -> int
1704 Return the effective group id under which the process runs.
1706 On Windows: always returns 1 .
1708 val setgid : int -> unit
1712 Set the real group id and effective group id for the process.
1714 On Windows: not implemented.
1716 val getgroups : unit -> int array
1720 Return the list of groups to which the user executing the process be‐
1722 longs.
1723 On Windows: always returns [|1|] .
1725 val setgroups : int array -> unit
1729 setgroups groups sets the supplementary group IDs for the calling
1732 process. Appropriate privileges are required.
1733 On Windows: not implemented.
1735 val initgroups : string -> int -> unit
1739 initgroups user group initializes the group access list by reading the
1742 group database /etc/group and using all groups of which user is a mem‐
1743 ber. The additional group group is also added to the list.
1744 On Windows: not implemented.
1746 type passwd_entry = {
1749 pw_name : string ;
1750 pw_passwd : string ;
1751 pw_uid : int ;
1752 pw_gid : int ;
1753 pw_gecos : string ;
1754 pw_dir : string ;
1755 pw_shell : string ;
1756 }
1757 Structure of entries in the passwd database.
1760 type group_entry = {
1763 gr_name : string ;
1764 gr_passwd : string ;
1765 gr_gid : int ;
1766 gr_mem : string array ;
1767 }
1768 Structure of entries in the groups database.
1771 val getlogin : unit -> string
1775 Return the login name of the user executing the process.
1777 val getpwnam : string -> passwd_entry
1781 Find an entry in passwd with the given name.
1783 Raises Not_found if no such entry exists, or always on Windows.
1786 val getgrnam : string -> group_entry
1790 Find an entry in group with the given name.
1792 Raises Not_found if no such entry exists, or always on Windows.
1795 val getpwuid : int -> passwd_entry
1799 Find an entry in passwd with the given user id.
1801 Raises Not_found if no such entry exists, or always on Windows.
1804 val getgrgid : int -> group_entry
1808 Find an entry in group with the given group id.
1810 Raises Not_found if no such entry exists, or always on Windows.
1813 Internet addresses
1818 type inet_addr
1819 The abstract type of Internet addresses.
1822 val inet_addr_of_string : string -> inet_addr
1826 Conversion from the printable representation of an Internet address to
1828 its internal representation. The argument string consists of 4 numbers
1829 separated by periods ( XXX.YYY.ZZZ.TTT ) for IPv4 addresses, and up to
1830 8 numbers separated by colons for IPv6 addresses.
1831 Raises Failure when given a string that does not match these formats.
1834 val string_of_inet_addr : inet_addr -> string
1838 Return the printable representation of the given Internet address. See
1840 Unix.inet_addr_of_string for a description of the printable representa‐
1841 tion.
1842 val inet_addr_any : inet_addr
1846 A special IPv4 address, for use only with bind , representing all the
1848 Internet addresses that the host machine possesses.
1849 val inet_addr_loopback : inet_addr
1853 A special IPv4 address representing the host machine ( 127.0.0.1 ).
1855 val inet6_addr_any : inet_addr
1859 A special IPv6 address, for use only with bind , representing all the
1861 Internet addresses that the host machine possesses.
1862 val inet6_addr_loopback : inet_addr
1866 A special IPv6 address representing the host machine ( ::1 ).
1868 val is_inet6_addr : inet_addr -> bool
1872 Whether the given inet_addr is an IPv6 address.
1874 Since 4.12.0
1877 Sockets
1882 type socket_domain =
1883 | PF_UNIX (* Unix domain
1884 *)
1885 | PF_INET (* Internet domain (IPv4)
1886 *)
1887 | PF_INET6 (* Internet domain (IPv6)
1888 *)
1889 The type of socket domains. Not all platforms support IPv6 sockets
1892 (type PF_INET6 ).
1893 On Windows: PF_UNIX not implemented.
1895 type socket_type =
1898 | SOCK_STREAM (* Stream socket
1899 *)
1900 | SOCK_DGRAM (* Datagram socket
1901 *)
1902 | SOCK_RAW (* Raw socket
1903 *)
1904 | SOCK_SEQPACKET (* Sequenced packets socket
1905 *)
1906 The type of socket kinds, specifying the semantics of communications.
1909 SOCK_SEQPACKET is included for completeness, but is rarely supported by
1910 the OS, and needs system calls that are not available in this library.
1911 type sockaddr =
1914 | ADDR_UNIX of string
1915 | ADDR_INET of inet_addr * int
1916 The type of socket addresses. ADDR_UNIX name is a socket address in
1919 the Unix domain; name is a file name in the file system.
1920 ADDR_INET(addr,port) is a socket address in the Internet domain; addr
1921 is the Internet address of the machine, and port is the port number.
1922 val socket : ?cloexec:bool -> socket_domain -> socket_type -> int ->
1926 file_descr
1927 Create a new socket in the given domain, and with the given kind. The
1929 third argument is the protocol type; 0 selects the default protocol for
1930 that kind of sockets. See Unix.set_close_on_exec for documentation on
1931 the cloexec optional argument.
1932 val domain_of_sockaddr : sockaddr -> socket_domain
1936 Return the socket domain adequate for the given socket address.
1938 val socketpair : ?cloexec:bool -> socket_domain -> socket_type -> int
1942 -> file_descr * file_descr
1943 Create a pair of unnamed sockets, connected together. See
1945 Unix.set_close_on_exec for documentation on the cloexec optional argu‐
1946 ment.
1947 val accept : ?cloexec:bool -> file_descr -> file_descr * sockaddr
1951 Accept connections on the given socket. The returned descriptor is a
1953 socket connected to the client; the returned address is the address of
1954 the connecting client. See Unix.set_close_on_exec for documentation on
1955 the cloexec optional argument.
1956 val bind : file_descr -> sockaddr -> unit
1960 Bind a socket to an address.
1962 val connect : file_descr -> sockaddr -> unit
1966 Connect a socket to an address.
1968 val listen : file_descr -> int -> unit
1972 Set up a socket for receiving connection requests. The integer argument
1974 is the maximal number of pending requests.
1975 type shutdown_command =
1978 | SHUTDOWN_RECEIVE (* Close for receiving
1979 *)
1980 | SHUTDOWN_SEND (* Close for sending
1981 *)
1982 | SHUTDOWN_ALL (* Close both
1983 *)
1984 The type of commands for shutdown .
1987 val shutdown : file_descr -> shutdown_command -> unit
1991 Shutdown a socket connection. SHUTDOWN_SEND as second argument causes
1993 reads on the other end of the connection to return an end-of-file con‐
1994 dition. SHUTDOWN_RECEIVE causes writes on the other end of the connec‐
1995 tion to return a closed pipe condition ( SIGPIPE signal).
1996 val getsockname : file_descr -> sockaddr
2000 Return the address of the given socket.
2002 val getpeername : file_descr -> sockaddr
2006 Return the address of the host connected to the given socket.
2008 type msg_flag =
2011 | MSG_OOB
2012 | MSG_DONTROUTE
2013 | MSG_PEEK
2014 The flags for Unix.recv , Unix.recvfrom , Unix.send and Unix.sendto .
2017 val recv : file_descr -> bytes -> int -> int -> msg_flag list -> int
2021 Receive data from a connected socket.
2023 val recvfrom : file_descr -> bytes -> int -> int -> msg_flag list ->
2027 int * sockaddr
2028 Receive data from an unconnected socket.
2030 val send : file_descr -> bytes -> int -> int -> msg_flag list -> int
2034 Send data over a connected socket.
2036 val send_substring : file_descr -> string -> int -> int -> msg_flag
2040 list -> int
2041 Same as send , but take the data from a string instead of a byte se‐
2043 quence.
2044 Since 4.02.0
2047 val sendto : file_descr -> bytes -> int -> int -> msg_flag list ->
2051 sockaddr -> int
2052 Send data over an unconnected socket.
2054 val sendto_substring : file_descr -> string -> int -> int -> msg_flag
2058 list -> sockaddr -> int
2059 Same as sendto , but take the data from a string instead of a byte se‐
2061 quence.
2062 Since 4.02.0
2065 Socket options
2070 type socket_bool_option =
2071 | SO_DEBUG (* Record debugging information
2072 *)
2073 | SO_BROADCAST (* Permit sending of broadcast messages
2074 *)
2075 | SO_REUSEADDR (* Allow reuse of local addresses for bind
2076 *)
2077 | SO_KEEPALIVE (* Keep connection active
2078 *)
2079 | SO_DONTROUTE (* Bypass the standard routing algorithms
2080 *)
2081 | SO_OOBINLINE (* Leave out-of-band data in line
2082 *)
2083 | SO_ACCEPTCONN (* Report whether socket listening is enabled
2084 *)
2085 | TCP_NODELAY (* Control the Nagle algorithm for TCP sockets
2086 *)
2087 | IPV6_ONLY (* Forbid binding an IPv6 socket to an IPv4 address
2088 *)
2089 | SO_REUSEPORT (* Allow reuse of address and port bindings
2090 *)
2091 The socket options that can be consulted with Unix.getsockopt and modi‐
2094 fied with Unix.setsockopt . These options have a boolean ( true /
2095 false ) value.
2096 type socket_int_option =
2099 | SO_SNDBUF (* Size of send buffer
2100 *)
2101 | SO_RCVBUF (* Size of received buffer
2102 *)
2103 | SO_ERROR (* Deprecated. Use Unix.getsockopt_error instead.
2104 *)
2105 | SO_TYPE (* Report the socket type
2106 *)
2107 | SO_RCVLOWAT (* Minimum number of bytes to process for input opera‐
2108 tions
2109 *)
2110 | SO_SNDLOWAT (* Minimum number of bytes to process for output opera‐
2111 tions
2112 *)
2113 The socket options that can be consulted with Unix.getsockopt_int and
2116 modified with Unix.setsockopt_int . These options have an integer
2117 value.
2118 type socket_optint_option =
2121 | SO_LINGER (* Whether to linger on closed connections that have data
2122 present, and for how long (in seconds)
2123 *)
2124 The socket options that can be consulted with Unix.getsockopt_optint
2127 and modified with Unix.setsockopt_optint . These options have a value
2128 of type int option , with None meaning ``disabled''.
2129 type socket_float_option =
2132 | SO_RCVTIMEO (* Timeout for input operations
2133 *)
2134 | SO_SNDTIMEO (* Timeout for output operations
2135 *)
2136 The socket options that can be consulted with Unix.getsockopt_float and
2139 modified with Unix.setsockopt_float . These options have a float‐
2140 ing-point value representing a time in seconds. The value 0 means in‐
2141 finite timeout.
2142 val getsockopt : file_descr -> socket_bool_option -> bool
2146 Return the current status of a boolean-valued option in the given
2148 socket.
2149 val setsockopt : file_descr -> socket_bool_option -> bool -> unit
2153 Set or clear a boolean-valued option in the given socket.
2155 val getsockopt_int : file_descr -> socket_int_option -> int
2159 Same as Unix.getsockopt for an integer-valued socket option.
2161 val setsockopt_int : file_descr -> socket_int_option -> int -> unit
2165 Same as Unix.setsockopt for an integer-valued socket option.
2167 val getsockopt_optint : file_descr -> socket_optint_option -> int op‐
2171 tion
2172 Same as Unix.getsockopt for a socket option whose value is an int op‐
2174 tion .
2175 val setsockopt_optint : file_descr -> socket_optint_option -> int op‐
2179 tion -> unit
2180 Same as Unix.setsockopt for a socket option whose value is an int op‐
2182 tion .
2183 val getsockopt_float : file_descr -> socket_float_option -> float
2187 Same as Unix.getsockopt for a socket option whose value is a float‐
2189 ing-point number.
2190 val setsockopt_float : file_descr -> socket_float_option -> float ->
2194 unit
2195 Same as Unix.setsockopt for a socket option whose value is a float‐
2197 ing-point number.
2198 val getsockopt_error : file_descr -> error option
2202 Return the error condition associated with the given socket, and clear
2204 it.
2205 High-level network connection functions
2210 val open_connection : sockaddr -> in_channel * out_channel
2211 Connect to a server at the given address. Return a pair of buffered
2213 channels connected to the server. Remember to call flush on the output
2214 channel at the right times to ensure correct synchronization.
2215 val shutdown_connection : in_channel -> unit
2219 ``Shut down'' a connection established with Unix.open_connection ; that
2221 is, transmit an end-of-file condition to the server reading on the
2222 other side of the connection. This does not fully close the file de‐
2223 scriptor associated with the channel, which you must remember to free
2224 via close_in .
2225 val establish_server : (in_channel -> out_channel -> unit) -> sockaddr
2229 -> unit
2230 Establish a server on the given address. The function given as first
2232 argument is called for each connection with two buffered channels con‐
2233 nected to the client. A new process is created for each connection. The
2234 function Unix.establish_server never returns normally.
2235 On Windows: not implemented (use threads).
2237 Host and protocol databases
2242 type host_entry = {
2243 h_name : string ;
2244 h_aliases : string array ;
2245 h_addrtype : socket_domain ;
2246 h_addr_list : inet_addr array ;
2247 }
2248 Structure of entries in the hosts database.
2251 type protocol_entry = {
2254 p_name : string ;
2255 p_aliases : string array ;
2256 p_proto : int ;
2257 }
2258 Structure of entries in the protocols database.
2261 type service_entry = {
2264 s_name : string ;
2265 s_aliases : string array ;
2266 s_port : int ;
2267 s_proto : string ;
2268 }
2269 Structure of entries in the services database.
2272 val gethostname : unit -> string
2276 Return the name of the local host.
2278 val gethostbyname : string -> host_entry
2282 Find an entry in hosts with the given name.
2284 Raises Not_found if no such entry exists.
2287 val gethostbyaddr : inet_addr -> host_entry
2291 Find an entry in hosts with the given address.
2293 Raises Not_found if no such entry exists.
2296 val getprotobyname : string -> protocol_entry
2300 Find an entry in protocols with the given name.
2302 Raises Not_found if no such entry exists.
2305 val getprotobynumber : int -> protocol_entry
2309 Find an entry in protocols with the given protocol number.
2311 Raises Not_found if no such entry exists.
2314 val getservbyname : string -> string -> service_entry
2318 Find an entry in services with the given name.
2320 Raises Not_found if no such entry exists.
2323 val getservbyport : int -> string -> service_entry
2327 Find an entry in services with the given service number.
2329 Raises Not_found if no such entry exists.
2332 type addr_info = {
2335 ai_family : socket_domain ; (* Socket domain
2336 *)
2337 ai_socktype : socket_type ; (* Socket type
2338 *)
2339 ai_protocol : int ; (* Socket protocol number
2340 *)
2341 ai_addr : sockaddr ; (* Address
2342 *)
2343 ai_canonname : string ; (* Canonical host name
2344 *)
2345 }
2346 Address information returned by Unix.getaddrinfo .
2349 type getaddrinfo_option =
2352 | AI_FAMILY of socket_domain
2353 (* Impose the given socket domain
2354 *)
2355 | AI_SOCKTYPE of socket_type
2356 (* Impose the given socket type
2357 *)
2358 | AI_PROTOCOL of int
2359 (* Impose the given protocol
2360 *)
2361 | AI_NUMERICHOST (* Do not call name resolver, expect numeric IP ad‐
2362 dress
2363 *)
2364 | AI_CANONNAME (* Fill the ai_canonname field of the result
2365 *)
2366 | AI_PASSIVE (* Set address to ``any'' address for use with Unix.bind
2367 *)
2369 Options to Unix.getaddrinfo .
2372 val getaddrinfo : string -> string -> getaddrinfo_option list ->
2376 addr_info list
2377 getaddrinfo host service opts returns a list of Unix.addr_info records
2380 describing socket parameters and addresses suitable for communicating
2381 with the given host and service. The empty list is returned if the
2382 host or service names are unknown, or the constraints expressed in opts
2383 cannot be satisfied.
2384 host is either a host name or the string representation of an IP ad‐
2387 dress. host can be given as the empty string; in this case, the
2388 ``any'' address or the ``loopback'' address are used, depending whether
2389 opts contains AI_PASSIVE . service is either a service name or the
2390 string representation of a port number. service can be given as the
2391 empty string; in this case, the port field of the returned addresses is
2392 set to 0. opts is a possibly empty list of options that allows the
2393 caller to force a particular socket domain (e.g. IPv6 only or IPv4
2394 only) or a particular socket type (e.g. TCP only or UDP only).
2395 type name_info = {
2398 ni_hostname : string ; (* Name or IP address of host
2399 *)
2400 ni_service : string ; (* Name of service or port number
2401 *)
2402 }
2403 Host and service information returned by Unix.getnameinfo .
2406 type getnameinfo_option =
2409 | NI_NOFQDN (* Do not qualify local host names
2410 *)
2411 | NI_NUMERICHOST (* Always return host as IP address
2412 *)
2413 | NI_NAMEREQD (* Fail if host name cannot be determined
2414 *)
2415 | NI_NUMERICSERV (* Always return service as port number
2416 *)
2417 | NI_DGRAM (* Consider the service as UDP-based instead of the de‐
2418 fault TCP
2419 *)
2420 Options to Unix.getnameinfo .
2423 val getnameinfo : sockaddr -> getnameinfo_option list -> name_info
2427 getnameinfo addr opts returns the host name and service name corre‐
2430 sponding to the socket address addr . opts is a possibly empty list of
2431 options that governs how these names are obtained.
2432 Raises Not_found if an error occurs.
2435 Terminal interface
2440 The following functions implement the POSIX standard terminal inter‐
2441 face. They provide control over asynchronous communication ports and
2442 pseudo-terminals. Refer to the termios man page for a complete descrip‐
2443 tion.
2444 type terminal_io = {
2446 mutable c_ignbrk : bool ; (* Ignore the break condition.
2448 *)
2449 mutable c_brkint : bool ; (* Signal interrupt on break condition.
2451 *)
2452 mutable c_ignpar : bool ; (* Ignore characters with parity errors.
2454 *)
2455 mutable c_parmrk : bool ; (* Mark parity errors.
2457 *)
2458 mutable c_inpck : bool ; (* Enable parity check on input.
2460 *)
2461 mutable c_istrip : bool ; (* Strip 8th bit on input characters.
2463 *)
2464 mutable c_inlcr : bool ; (* Map NL to CR on input.
2466 *)
2467 mutable c_igncr : bool ; (* Ignore CR on input.
2469 *)
2470 mutable c_icrnl : bool ; (* Map CR to NL on input.
2472 *)
2473 mutable c_ixon : bool ; (* Recognize XON/XOFF characters on input.
2475 *)
2476 mutable c_ixoff : bool ; (* Emit XON/XOFF chars to control input flow.
2478 *)
2479 mutable c_opost : bool ; (* Enable output processing.
2481 *)
2482 mutable c_obaud : int ; (* Output baud rate (0 means close connec‐
2484 tion).
2485 *)
2486 mutable c_ibaud : int ; (* Input baud rate.
2488 *)
2489 mutable c_csize : int ; (* Number of bits per character (5-8).
2491 *)
2492 mutable c_cstopb : int ; (* Number of stop bits (1-2).
2494 *)
2495 mutable c_cread : bool ; (* Reception is enabled.
2497 *)
2498 mutable c_parenb : bool ; (* Enable parity generation and detection.
2500 *)
2501 mutable c_parodd : bool ; (* Specify odd parity instead of even.
2503 *)
2504 mutable c_hupcl : bool ; (* Hang up on last close.
2506 *)
2507 mutable c_clocal : bool ; (* Ignore modem status lines.
2509 *)
2510 mutable c_isig : bool ; (* Generate signal on INTR, QUIT, SUSP.
2512 *)
2513 mutable c_icanon : bool ; (* Enable canonical processing (line buffer‐
2515 ing and editing)
2516 *)
2517 mutable c_noflsh : bool ; (* Disable flush after INTR, QUIT, SUSP.
2519 *)
2520 mutable c_echo : bool ; (* Echo input characters.
2522 *)
2523 mutable c_echoe : bool ; (* Echo ERASE (to erase previous character).
2525 *)
2526 mutable c_echok : bool ; (* Echo KILL (to erase the current line).
2528 *)
2529 mutable c_echonl : bool ; (* Echo NL even if c_echo is not set.
2531 *)
2532 mutable c_vintr : char ; (* Interrupt character (usually ctrl-C).
2534 *)
2535 mutable c_vquit : char ; (* Quit character (usually ctrl-\).
2537 *)
2538 mutable c_verase : char ; (* Erase character (usually DEL or ctrl-H).
2540 *)
2541 mutable c_vkill : char ; (* Kill line character (usually ctrl-U).
2543 *)
2544 mutable c_veof : char ; (* End-of-file character (usually ctrl-D).
2546 *)
2547 mutable c_veol : char ; (* Alternate end-of-line char. (usually none).
2549 *)
2550 mutable c_vmin : int ; (* Minimum number of characters to read before
2552 the read request is satisfied.
2553 *)
2554 mutable c_vtime : int ; (* Maximum read wait (in 0.1s units).
2556 *)
2557 mutable c_vstart : char ; (* Start character (usually ctrl-Q).
2559 *)
2560 mutable c_vstop : char ; (* Stop character (usually ctrl-S).
2562 *)
2563 }
2564 val tcgetattr : file_descr -> terminal_io
2570 Return the status of the terminal referred to by the given file de‐
2572 scriptor.
2573 On Windows: not implemented.
2575 type setattr_when =
2578 | TCSANOW
2579 | TCSADRAIN
2580 | TCSAFLUSH
2581 val tcsetattr : file_descr -> setattr_when -> terminal_io -> unit
2587 Set the status of the terminal referred to by the given file descrip‐
2589 tor. The second argument indicates when the status change takes place:
2590 immediately ( TCSANOW ), when all pending output has been transmitted (
2591 TCSADRAIN ), or after flushing all input that has been received but not
2592 read ( TCSAFLUSH ). TCSADRAIN is recommended when changing the output
2593 parameters; TCSAFLUSH , when changing the input parameters.
2594 On Windows: not implemented.
2596 val tcsendbreak : file_descr -> int -> unit
2600 Send a break condition on the given file descriptor. The second argu‐
2602 ment is the duration of the break, in 0.1s units; 0 means standard du‐
2603 ration (0.25s).
2604 On Windows: not implemented.
2606 val tcdrain : file_descr -> unit
2610 Waits until all output written on the given file descriptor has been
2612 transmitted.
2613 On Windows: not implemented.
2615 type flush_queue =
2618 | TCIFLUSH
2619 | TCOFLUSH
2620 | TCIOFLUSH
2621 val tcflush : file_descr -> flush_queue -> unit
2627 Discard data written on the given file descriptor but not yet transmit‐
2629 ted, or data received but not yet read, depending on the second argu‐
2630 ment: TCIFLUSH flushes data received but not read, TCOFLUSH flushes
2631 data written but not transmitted, and TCIOFLUSH flushes both.
2632 On Windows: not implemented.
2634 type flow_action =
2637 | TCOOFF
2638 | TCOON
2639 | TCIOFF
2640 | TCION
2641 val tcflow : file_descr -> flow_action -> unit
2647 Suspend or restart reception or transmission of data on the given file
2649 descriptor, depending on the second argument: TCOOFF suspends output,
2650 TCOON restarts output, TCIOFF transmits a STOP character to suspend in‐
2651 put, and TCION transmits a START character to restart input.
2652 On Windows: not implemented.
2654 val setsid : unit -> int
2658 Put the calling process in a new session and detach it from its con‐
2660 trolling terminal.
2661 On Windows: not implemented.
2663OCamldoc 2021-07-22 Unix(3)