The branch, master has been updated via 585e4cdd6c9 docs-xml: remove completely outdated Samba-Developers-Guide from cac38aa3870 vfs: Remove vfs telldir/seekdir functions
https://git.samba.org/?p=samba.git;a=shortlog;h=master - Log ----------------------------------------------------------------- commit 585e4cdd6c98c91ea629f767e95e6c02ab5ed1af Author: Björn Jacke <b...@sernet.de> Date: Wed Jun 7 02:49:49 2023 +0200 docs-xml: remove completely outdated Samba-Developers-Guide Signed-off-by: Bjoern Jacke <bja...@samba.org> Reviewed-by: Andrew Bartlett <abart...@samba.org> Reviewed-by: Volker Lendecke <v...@samba.org> Autobuild-User(master): Volker Lendecke <v...@samba.org> Autobuild-Date(master): Wed Jun 14 12:21:50 UTC 2023 on atb-devel-224 ----------------------------------------------------------------------- Summary of changes: .../Samba-Developers-Guide/CodingSuggestions.xml | 239 -- docs-xml/Samba-Developers-Guide/Tracing.xml | 131 - docs-xml/Samba-Developers-Guide/architecture.xml | 186 -- docs-xml/Samba-Developers-Guide/cifsntdomain.xml | 2934 -------------------- docs-xml/Samba-Developers-Guide/contributing.xml | 112 - docs-xml/Samba-Developers-Guide/debug.xml | 323 --- docs-xml/Samba-Developers-Guide/encryption.xml | 199 -- docs-xml/Samba-Developers-Guide/gencache.xml | 119 - docs-xml/Samba-Developers-Guide/index.xml | 99 - docs-xml/Samba-Developers-Guide/internals.xml | 442 --- docs-xml/Samba-Developers-Guide/modules.xml | 176 -- docs-xml/Samba-Developers-Guide/packagers.xml | 54 - docs-xml/Samba-Developers-Guide/parsing.xml | 241 -- docs-xml/Samba-Developers-Guide/printing.xml | 395 --- docs-xml/Samba-Developers-Guide/rpc_plugin.xml | 90 - docs-xml/Samba-Developers-Guide/unix-smb.xml | 316 --- docs-xml/Samba-Developers-Guide/vfs.xml | 921 ------ docs-xml/Samba-Developers-Guide/wins.xml | 81 - 18 files changed, 7058 deletions(-) delete mode 100644 docs-xml/Samba-Developers-Guide/CodingSuggestions.xml delete mode 100644 docs-xml/Samba-Developers-Guide/Tracing.xml delete mode 100644 docs-xml/Samba-Developers-Guide/architecture.xml delete mode 100644 docs-xml/Samba-Developers-Guide/cifsntdomain.xml delete mode 100644 docs-xml/Samba-Developers-Guide/contributing.xml delete mode 100644 docs-xml/Samba-Developers-Guide/debug.xml delete mode 100644 docs-xml/Samba-Developers-Guide/encryption.xml delete mode 100644 docs-xml/Samba-Developers-Guide/gencache.xml delete mode 100644 docs-xml/Samba-Developers-Guide/index.xml delete mode 100644 docs-xml/Samba-Developers-Guide/internals.xml delete mode 100644 docs-xml/Samba-Developers-Guide/modules.xml delete mode 100644 docs-xml/Samba-Developers-Guide/packagers.xml delete mode 100644 docs-xml/Samba-Developers-Guide/parsing.xml delete mode 100644 docs-xml/Samba-Developers-Guide/printing.xml delete mode 100644 docs-xml/Samba-Developers-Guide/rpc_plugin.xml delete mode 100644 docs-xml/Samba-Developers-Guide/unix-smb.xml delete mode 100644 docs-xml/Samba-Developers-Guide/vfs.xml delete mode 100644 docs-xml/Samba-Developers-Guide/wins.xml Changeset truncated at 500 lines: diff --git a/docs-xml/Samba-Developers-Guide/CodingSuggestions.xml b/docs-xml/Samba-Developers-Guide/CodingSuggestions.xml deleted file mode 100644 index 4adb8cb09b7..00000000000 --- a/docs-xml/Samba-Developers-Guide/CodingSuggestions.xml +++ /dev/null @@ -1,239 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> -<chapter id="CodingSuggestions"> -<chapterinfo> - <author> - <firstname>Steve</firstname><surname>French</surname> - </author> - <author> - <firstname>Simo</firstname><surname>Sorce</surname> - </author> - <author> - <firstname>Andrew</firstname><surname>Bartlett</surname> - </author> - <author> - <firstname>Tim</firstname><surname>Potter</surname> - </author> - <author> - <firstname>Martin</firstname><surname>Pool</surname> - </author> -</chapterinfo> - -<title>Coding Suggestions</title> - -<para> -So you want to add code to Samba ... -</para> - -<para> -One of the daunting tasks facing a programmer attempting to write code for -Samba is understanding the various coding conventions used by those most -active in the project. These conventions were mostly unwritten and helped -improve either the portability, stability or consistency of the code. This -document will attempt to document a few of the more important coding -practices used at this time on the Samba project. The coding practices are -expected to change slightly over time, and even to grow as more is learned -about obscure portability considerations. Two existing documents -<filename>samba/source/internals.doc</filename> and -<filename>samba/source/architecture.doc</filename> provide -additional information. -</para> - -<para> -The loosely related question of coding style is very personal and this -document does not attempt to address that subject, except to say that I -have observed that eight character tabs seem to be preferred in Samba -source. If you are interested in the topic of coding style, two oft-quoted -documents are: -</para> - -<para> -<ulink url="http://lxr.linux.no/source/Documentation/CodingStyle">http://lxr.linux.no/source/Documentation/CodingStyle</ulink> -</para> - -<para> -<ulink url="http://www.fsf.org/prep/standards_toc.html">http://www.fsf.org/prep/standards_toc.html</ulink> -</para> - -<para> -But note that coding style in Samba varies due to the many different -programmers who have contributed. -</para> - -<para> -Following are some considerations you should use when adding new code to -Samba. First and foremost remember that: -</para> - -<para> -Portability is a primary consideration in adding function, as is network -compatibility with de facto, existing, real world CIFS/SMB implementations. -There are lots of platforms that Samba builds on so use caution when adding -a call to a library function that is not invoked in existing Samba code. -Also note that there are many quite different SMB/CIFS clients that Samba -tries to support, not all of which follow the SNIA CIFS Technical Reference -(or the earlier Microsoft reference documents or the X/Open book on the SMB -Standard) perfectly. -</para> - -<para> -Here are some other suggestions: -</para> - -<orderedlist> - -<listitem><para> - use d_printf instead of printf for display text - reason: enable auto-substitution of translated language text -</para></listitem> - -<listitem><para> - use SAFE_FREE instead of free - reason: reduce traps due to null pointers -</para></listitem> - -<listitem><para> - don't use bzero use memset, or ZERO_STRUCT and ZERO_STRUCTP macros - reason: not POSIX -</para></listitem> - -<listitem><para> - don't use strcpy and strlen (use safe_* equivalents) - reason: to avoid traps due to buffer overruns -</para></listitem> - -<listitem><para> - don't use getopt_long, use popt functions instead - reason: portability -</para></listitem> - -<listitem><para> - explicitly add const qualifiers on parm passing in functions where parm - is input only (somewhat controversial but const can be #defined away) -</para></listitem> - -<listitem><para> - when passing a va_list as an arg, or assigning one to another - please use the VA_COPY() macro - reason: on some platforms, va_list is a struct that must be - initialized in each function...can SEGV if you don't. -</para></listitem> - -<listitem><para> - discourage use of threads - reason: portability (also see architecture.doc) -</para></listitem> - -<listitem><para> - don't explicitly include new header files in C files - new h files - should be included by adding them once to includes.h - reason: consistency -</para></listitem> - -<listitem><para> - don't explicitly extern functions (they are autogenerated by - "make proto" into proto.h) - reason: consistency -</para></listitem> - -<listitem><para> - use endian safe macros when unpacking SMBs (see byteorder.h and - internals.doc) - reason: not everyone uses Intel -</para></listitem> - -<listitem><para> - Note Unicode implications of charset handling (see internals.doc). See - pull_* and push_* and convert_string functions. - reason: Internationalization -</para></listitem> - -<listitem><para> - Don't assume English only - reason: See above -</para></listitem> - -<listitem><para> - Try to avoid using in/out parameters (functions that return data which - overwrites input parameters) - reason: Can cause stability problems -</para></listitem> - -<listitem><para> - Ensure copyright notices are correct, don't append Tridge's name to code - that he didn't write. If you did not write the code, make sure that it - can coexist with the rest of the Samba GPLed code. -</para></listitem> - -<listitem><para> - Consider usage of DATA_BLOBs for length specified byte-data. - reason: stability -</para></listitem> - -<listitem><para> - Take advantage of tdbs for database like function - reason: consistency -</para></listitem> - -<listitem><para> - Don't access the SAM_ACCOUNT structure directly, they should be accessed - via pdb_get...() and pdb_set...() functions. - reason: stability, consistency -</para></listitem> - -<listitem><para> - Don't check a password directly against the passdb, always use the - check_password() interface. - reason: long term pluggability -</para></listitem> - -<listitem><para> - Try to use asprintf rather than pstrings and fstrings where possible -</para></listitem> - -<listitem><para> - Use normal C comments / * instead of C++ comments // like - this. Although the C++ comment format is part of the C99 - standard, some older vendor C compilers do not accept it. -</para></listitem> - -<listitem><para> - Try to write documentation for API functions and structures - explaining the point of the code, the way it should be used, and - any special conditions or results. Mark these with a double-star - comment start / ** so that they can be picked up by Doxygen, as in - this file. -</para></listitem> - -<listitem><para> - Keep the scope narrow. This means making functions/variables - static whenever possible. We don't want our namespace - polluted. Each module should have a minimal number of externally - visible functions or variables. -</para></listitem> - -<listitem><para> - Use function pointers to keep knowledge about particular pieces of - code isolated in one place. We don't want a particular piece of - functionality to be spread out across lots of places - that makes - for fragile, hand to maintain code. Instead, design an interface - and use tables containing function pointers to implement specific - functionality. This is particularly important for command - interpreters. -</para></listitem> - -<listitem><para> - Think carefully about what it will be like for someone else to add - to and maintain your code. If it would be hard for someone else to - maintain then do it another way. -</para></listitem> - -</orderedlist> - -<para> -The suggestions above are simply that, suggestions, but the information may -help in reducing the routine rework done on new code. The preceding list -is expected to change routinely as new support routines and macros are -added. -</para> -</chapter> diff --git a/docs-xml/Samba-Developers-Guide/Tracing.xml b/docs-xml/Samba-Developers-Guide/Tracing.xml deleted file mode 100644 index 50ad2eeb37b..00000000000 --- a/docs-xml/Samba-Developers-Guide/Tracing.xml +++ /dev/null @@ -1,131 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> -<chapter id="tracing"> -<chapterinfo> - <author> - <firstname>Andrew</firstname><surname>Tridgell</surname> - <affiliation> - <orgname>Samba Team</orgname> - </affiliation> - </author> -</chapterinfo> - -<title>Tracing samba system calls</title> - -<para> -This file describes how to do a system call trace on Samba to work out -what its doing wrong. This is not for the faint of heart, but if you -are reading this then you are probably desperate. -</para> - -<para> -Actually its not as bad as the the above makes it sound, just don't -expect the output to be very pretty :-) -</para> - -<para> -Ok, down to business. One of the big advantages of unix systems is -that they nearly all come with a system trace utility that allows you -to monitor all system calls that a program is making. This is -extremely using for debugging and also helps when trying to work out -why something is slower than you expect. You can use system tracing -without any special compilation options. -</para> - -<para> -The system trace utility is called different things on different -systems. On Linux systems its called strace. Under SunOS 4 its called -trace. Under SVR4 style systems (including solaris) its called -truss. Under many BSD systems its called ktrace. -</para> - -<para> -The first thing you should do is read the man page for your native -system call tracer. In the discussion below I'll assume its called -strace as strace is the only portable system tracer (its available for -free for many unix types) and its also got some of the nicest -features. -</para> - -<para> -Next, try using strace on some simple commands. For example, <command>strace -ls</command> or <command>strace echo hello</command>. -</para> - -<para> -You'll notice that it produces a LOT of output. It is showing you the -arguments to every system call that the program makes and the -result. Very little happens in a program without a system call so you -get lots of output. You'll also find that it produces a lot of -"preamble" stuff showing the loading of shared libraries etc. Ignore -this (unless its going wrong!) -</para> - -<para> -For example, the only line that really matters in the <command>strace echo -hello</command> output is: -</para> - -<para><programlisting> -write(1, "hello\n", 6) = 6 -</programlisting></para> - -<para>all the rest is just setting up to run the program.</para> - -<para> -Ok, now you're familiar with strace. To use it on Samba you need to -strace the running smbd daemon. The way I tend to use it is to first -login from my Windows PC to the Samba server, then use smbstatus to -find which process ID that client is attached to, then as root I do -<command>strace -p PID</command> to attach to that process. I normally redirect the -stderr output from this command to a file for later perusal. For -example, if I'm using a csh style shell: -</para> - -<para><command>strace -f -p 3872 >& strace.out</command></para> - -<para>or with a sh style shell:</para> - -<para><command>strace -f -p 3872 > strace.out 2>&1</command></para> - -<para> -Note the "-f" option. This is only available on some systems, and -allows you to trace not just the current process, but any children it -forks. This is great for finding printing problems caused by the -"print command" being wrong. -</para> - -<para> -Once you are attached you then can do whatever it is on the client -that is causing problems and you will capture all the system calls -that smbd makes. -</para> - -<para> -So how do you interpret the results? Generally I search through the -output for strings that I know will appear when the problem -happens. For example, if I am having trouble with permissions on a file -I would search for that files name in the strace output and look at -the surrounding lines. Another trick is to match up file descriptor -numbers and "follow" what happens to an open file until it is closed. -</para> - -<para> -Beyond this you will have to use your initiative. To give you an idea -of what you are looking for here is a piece of strace output that -shows that <filename>/dev/null</filename> is not world writeable, which -causes printing to fail with Samba: -</para> - -<para><programlisting> -[pid 28268] open("/dev/null", O_RDWR) = -1 EACCES (Permission denied) -[pid 28268] open("/dev/null", O_WRONLY) = -1 EACCES (Permission denied) -</programlisting></para> - -<para> -The process is trying to first open <filename>/dev/null</filename> read-write -then read-only. Both fail. This means <filename>/dev/null</filename> has -incorrect permissions. -</para> - -</chapter> diff --git a/docs-xml/Samba-Developers-Guide/architecture.xml b/docs-xml/Samba-Developers-Guide/architecture.xml deleted file mode 100644 index f1ec70c99be..00000000000 --- a/docs-xml/Samba-Developers-Guide/architecture.xml +++ /dev/null @@ -1,186 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> -<chapter id="architecture"> -<chapterinfo> - <author> - <firstname>Dan</firstname><surname>Shearer</surname> - </author> - <pubdate> November 1997</pubdate> -</chapterinfo> - -<title>Samba Architecture</title> - -<sect1> -<title>Introduction</title> - -<para> -This document gives a general overview of how Samba works -internally. The Samba Team has tried to come up with a model which is -the best possible compromise between elegance, portability, security -and the constraints imposed by the very messy SMB and CIFS -protocol. -</para> - -<para> -It also tries to answer some of the frequently asked questions such as: -</para> - -<orderedlist> -<listitem><para> - Is Samba secure when running on Unix? The xyz platform? - What about the root privileges issue? -</para></listitem> - -<listitem><para>Pros and cons of multithreading in various parts of Samba</para></listitem> - -<listitem><para>Why not have a separate process for name resolution, WINS, and browsing?</para></listitem> - -</orderedlist> - -</sect1> - -<sect1> -<title>Multithreading and Samba</title> - -<para> -People sometimes tout threads as a uniformly good thing. They are very -nice in their place but are quite inappropriate for smbd. nmbd is -another matter, and multi-threading it would be very nice. -</para> - -<para> -The short version is that smbd is not multithreaded, and alternative -servers that take this approach under Unix (such as Syntax, at the -time of writing) suffer tremendous performance penalties and are less -robust. nmbd is not threaded either, but this is because it is not -possible to do it while keeping code consistent and portable across 35 -or more platforms. (This drawback also applies to threading smbd.) -</para> - -<para> -The longer versions is that there are very good reasons for not making -smbd multi-threaded. Multi-threading would actually make Samba much -slower, less scalable, less portable and much less robust. The fact -that we use a separate process for each connection is one of Samba's -biggest advantages. -</para> - -</sect1> - -<sect1> -<title>Threading smbd</title> - -<para> -A few problems that would arise from a threaded smbd are: -</para> - -<orderedlist> -<listitem><para> - It's not only to create threads instead of processes, but you - must care about all variables if they have to be thread specific - (currently they would be global). -</para></listitem> - -<listitem><para> - if one thread dies (eg. a seg fault) then all threads die. We can - immediately throw robustness out the window. -</para></listitem> - -<listitem><para> - many of the system calls we make are blocking. Non-blocking - equivalents of many calls are either not available or are awkward (and - slow) to use. So while we block in one thread all clients are - waiting. Imagine if one share is a slow NFS filesystem and the others - are fast, we will end up slowing all clients to the speed of NFS. -</para></listitem> - -<listitem><para> - you can't run as a different uid in different threads. This means - we would have to switch uid/gid on _every_ SMB packet. It would be - horrendously slow. -</para></listitem> - -<listitem><para> - the per process file descriptor limit would mean that we could only - support a limited number of clients. -</para></listitem> - -<listitem><para> - we couldn't use the system locking calls as the locking context of - fcntl() is a process, not a thread. -</para></listitem> - -- Samba Shared Repository